OC
OpenClaw 中文解释版

给五岁小朋友也能看懂的说明书
查看原始文档 最近生成：2026/03/08 15:37

简要总结

Release Checklist

这页纸是一个“发布清单”，就像你准备去野餐前要检查带没带三明治、水果和毯子一样。它告诉负责发布新版本的大人，在说“好，现在可以发布了！”之后，需要一步一步检查哪些事情。比如，要更新版本号、把软件打包、写清楚这次更新了什么，最后才能把新玩具（软件）放到商店（npm和GitHub）里让大家下载。

如果你想知道一个新版本是怎么从电脑里“生出来”并送到大家手里的，就可以看看这页。

五岁小孩版解释

好啦，现在我们来仔细看看每一步要做什么。这就像搭一个很复杂的乐高，得按顺序来。

首先，当负责人说“可以发布啦”，你要立刻开始准备。就像出门前要检查钥匙一样，你要做几件小事：读一读这份清单和另一份叫docs/platforms/mac/release.md的说明。然后，要确保电脑里一些重要的“秘密钥匙”（环境变量）已经准备好了，它们的名字是SPARKLE_PRIVATE_KEY_FILE和一些关于App Store Connect的变量。如果找不到，可以去~/Library/CloudStorage/Dropbox/Backup/Sparkle这个文件夹里找找看。

第一步：改版本号和信息

  1. 要更新package.json文件里的版本号，比如改成2026.1.29。
  2. 运行pnpm plugins:sync这个命令。这就像把一堆小积木（插件）的版本号都对齐，并且更新它们自己的更新记录。
  3. 去更新两个文件里的版本信息：一个是src/version.ts，另一个是src/web/session.ts里的“Baileys user agent”。
  4. 检查package.json里的其他信息，比如名字、描述对不对。还要确认bin这个设置正确指向了openclaw.mjs文件。
  5. 如果依赖的“零件”（依赖包）有变化，要运行pnpm install，让pnpm-lock.yaml这个“零件清单”保持最新。

第二步：打包软件

  1. 如果叫“A2UI”的东西有改动，要运行pnpm canvas:a2ui:bundle，然后把更新后的src/canvas-host/a2ui/a2ui.bundle.js文件保存起来。
  2. 运行pnpm run build。这就像把乐高模型拼好，会生成一个叫dist/的新文件夹。
  3. 检查package.json里的files设置，确保它包含了所有需要的dist/*文件夹，特别是给“无头节点”和“ACP命令行”用的那些。
  4. 确认dist/build-info.json这个文件存在，并且里面有正确的“提交哈希值”（一串字母数字，像模型的身份证）。
  5. （可选）运行npm pack --pack-destination /tmp，这会把打包好的东西变成一个压缩包。你可以检查一下里面有什么，先留着，等会儿上传到GitHub时用。注意：这个压缩包不要保存到代码仓库里。

第三步：写更新记录和文档

  1. 更新CHANGELOG.md文件，用大家能看懂的话写下这次更新了什么。如果文件不存在就新建一个。记得版本号要从新到旧排列。
  2. 确保README.md文件里的例子和命令选项，和现在软件的实际行为是一致的。

第四步：检查 这一大步里有很多小检查，就像把拼好的乐高模型每个部分都摇一摇，看牢不牢。

  1. 运行pnpm build再构建一次。
  2. 运行pnpm check检查代码。
  3. 运行pnpm test（或者pnpm test:coverage）做测试。
  4. 运行pnpm release:check，检查打包的内容对不对。
  5. 运行OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke。这是一个必须做的“冒烟测试”，用Docker快速检查安装会不会出问题。如果知道上一个版本是坏的，可以设置OPENCLAW_INSTALL_SMOKE_PREVIOUS=<上一个好版本>或者OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1来跳过对上一个版本的检查。
  6. （可选）运行完整的安装冒烟测试：pnpm test:install:smoke。
  7. （可选）运行更复杂的“端到端”安装测试，这需要一些API密钥（像进入游乐场的门票）：
    • pnpm test:install:e2e:openai（需要OPENAI_API_KEY）
    • pnpm test:install:e2e:anthropic（需要ANTHROPIC_API_KEY）
    • pnpm test:install:e2e（需要上面两个密钥）
  8. （可选）如果你的改动影响了网页网关，可以快速检查一下它。

第五步：制作苹果电脑（macOS）的应用程序

  1. 构建并签名macOS应用程序，然后把它压缩成zip文件。
  2. 用scripts/make_appcast.sh这个脚本生成Sparkle更新说明（appcast），并更新appcast.xml文件。
  3. 把应用程序的zip文件（还有可选的dSYM调试文件zip）准备好，等会儿要传到GitHub上。
  4. 一定要按照另一份详细的macOS release说明来操作，那里有具体的命令和需要的环境变量。特别注意：APP_BUILD必须是一个单调递增的数字，不能带-beta这样的字，这样Sparkle才能正确比较版本。

第六步：发布到npm（一个软件商店）

  1. 确认你的代码仓库是干净的，没有未保存的改动。有需要的话，先提交并推送代码。
  2. 如果需要，运行npm login登录你的npm账户（可能需要双重验证）。
  3. 运行npm publish --access public发布软件。如果是测试版，就用--tag beta。
  4. 发布后要检查一下：运行npm view openclaw version看版本，npm view openclaw dist-tags看标签，再用npx -y openclaw@X.Y.Z --version（或--help）试试新版本能不能运行。

第七步：在GitHub上发布并更新appcast

  1. 打标签并推送：运行git tag vX.Y.Z && git push origin vX.Y.Z。
  2. 在GitHub上为vX.Y.Z这个标签创建一个发布版。标题要用openclaw X.Y.Z（不能光写标签）。正文里要完整地贴上CHANGELOG.md里对应版本的内容（亮点、变化、修复），直接写进去，不要只放链接。注意：正文里不要再重复写一遍标题了。
  3. 上传文件：把npm pack生成的压缩包（可选）、OpenClaw-X.Y.Z.zip和OpenClaw-X.Y.Z.dSYM.zip（如果有的话）都附加上去。
  4. 把更新后的appcast.xml文件提交并推送到代码仓库。
  5. 从一个干净的临时文件夹（里面没有package.json）运行npx -y openclaw@X.Y.Z send --help，确认安装和命令行都能正常工作。
  6. 最后，可以宣布和分享发布说明了！

关于插件的发布 我们只发布那些已经在npm上的、名字以@openclaw/开头的插件。那些只放在我们自己文件夹里、没上传到npm的插件，就还是只跟着主软件一起走。

怎么知道要发布哪些插件呢？

  1. 运行npm search @openclaw --json，看看npm上现在有哪些@openclaw的包。
  2. 和我们自己extensions/*/package.json里的插件名字对比一下。
  3. 只发布两边都有的（也就是已经在npm上的）。

当前的插件列表（可能需要更新）有：@openclaw/bluebubbles, @openclaw/diagnostics-otel, @openclaw/discord, @openclaw/feishu, @openclaw/lobster, @openclaw/matrix, @openclaw/msteams, @openclaw/nextcloud-talk, @openclaw/nostr, @openclaw/voice-call, @openclaw/zalo, @openclaw/zalouser。

另外，在发布说明里，一定要特别提到那些新的、默认不开启的捆绑插件（比如tlon）。