发布检查清单 (npm + macOS)

从仓库根目录使用 pnpm(Node 22+)。在打标签/发布之前保持工作树干净。

操作员触发

当操作员说"发布"时,立即执行此预检(除非被阻止,否则不要提出额外问题):

阅读本文档和 docs/platforms/mac/release.md。
从 ~/.profile 加载环境变量并确认 SPARKLE_PRIVATE_KEY_FILE + App Store Connect 变量已设置(SPARKLE_PRIVATE_KEY_FILE 应位于 ~/.profile)。
如需要,从 ~/Library/CloudStorage/Dropbox/Backup/Sparkle 使用 Sparkle 密钥。

[ ] 更新 package.json 版本(例如 2026.1.29)。
[ ] 运行 pnpm plugins:sync 以对齐扩展包版本 + 变更日志。
[ ] 更新 CLI/版本字符串:src/cli/program.ts 和 src/provider-web.ts 中的 Baileys 用户代理。
[ ] 确认包元数据(name、description、repository、keywords、license)以及 bin 映射指向 openclaw.mjs 中的 openclaw。
[ ] 如果依赖项有变化,运行 pnpm install 以使 pnpm-lock.yaml 保持最新。

[ ] 如果 A2UI 输入有变化,运行 pnpm canvas:a2ui:bundle 并提交任何更新的 src/canvas-host/a2ui/a2ui.bundle.js。
[ ] pnpm run build(重新生成 dist/)。
[ ] 验证 npm 包 files 包含所有必需的 dist/* 文件夹(特别是用于无头节点 + ACP CLI 的 dist/node-host/** 和 dist/acp/**)。
[ ] 确认 dist/build-info.json 存在并包含预期的 commit 哈希(CLI 横幅在 npm 安装时使用此项)。
[ ] 可选:构建后执行 npm pack --pack-destination /tmp;检查 tarball 内容并保留它以用于 GitHub 发布(不要提交它)。

[ ] pnpm build
[ ] pnpm check
[ ] pnpm test(或如果需要覆盖率输出则使用 pnpm test:coverage)
[ ] pnpm release:check(验证 npm pack 内容)
[ ] OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke(Docker 安装冒烟测试,快速路径;发布前必需)
- 如果已知前一个 npm 版本已损坏,在预安装步骤设置 OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version> 或 OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1。
[ ] (可选)完整安装程序冒烟测试(添加非 root + CLI 覆盖率):pnpm test:install:smoke
[ ] (可选)安装程序 E2E(Docker,运行 curl -fsSL https://openclaw.ai/install.sh | bash、入门引导,然后运行实际工具调用):
- pnpm test:install:e2e:openai(需要 OPENAI_API_KEY)
- pnpm test:install:e2e:anthropic(需要 ANTHROPIC_API_KEY)
- pnpm test:install:e2e(需要两个密钥;运行两个提供商)
[ ] (可选)如果您的更改影响发送/接收路径,抽查 web 网关。

[ ] 构建 + 签名 macOS 应用,然后将其打包为 zip 以供分发。
[ ] 生成 Sparkle appcast(通过 scripts/make_appcast.sh 生成 HTML 说明)并更新 appcast.xml。
[ ] 保留应用 zip(和可选的 dSYM zip)以附加到 GitHub 发布。
[ ] 遵循 macOS 发布以获取确切的命令和所需的环境变量。
- APP_BUILD 必须是数字 + 单调递增(不能有 -beta),以便 Sparkle 正确比较版本。
- 如果进行公证,使用从 App Store Connect API 环境变量创建的 openclaw-notary 钥匙串配置文件(参见 macOS 发布)。

[ ] 确认 git 状态干净;根据需要提交并推送。
[ ] 如需要,执行 npm login(验证 2FA)。
[ ] npm publish --access public(预发布版本使用 --tag beta)。
[ ] 验证注册表:npm view openclaw version、npm view openclaw dist-tags 和 npx -y openclaw@X.Y.Z --version(或 --help)。

npm pack/publish 挂起或生成巨大的 tarball:dist/OpenClaw.app 中的 macOS 应用包(和发布 zip)被打包进去。通过 package.json files 将发布内容加入白名单来修复(包含 dist 子目录、docs、skills;排除应用包)。使用 npm pack --dry-run 确认 dist/OpenClaw.app 未被列出。
npm auth 对 dist-tags 进行 Web 循环:使用旧版身份验证获取 OTP 提示:
- NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add openclaw@X.Y.Z latest
npx 验证失败,显示 ECOMPROMISED: Lock compromised:使用新缓存重试:
- NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y openclaw@X.Y.Z --version
在后期修复后需要重新指向标签:强制更新并推送标签,然后确保 GitHub 发布资产仍然匹配:
- git tag -f vX.Y.Z && git push -f origin vX.Y.Z

[ ] 打标签并推送:git tag vX.Y.Z && git push origin vX.Y.Z(或 git push --tags)。
[ ] 为 vX.Y.Z 创建/刷新 GitHub 发布,标题为 openclaw X.Y.Z(不仅仅是标签);正文应包含该版本的完整变更日志部分(重点 + 变更 + 修复),内联(无裸链接),并且不得在正文内重复标题。
[ ] 附加制品:npm pack tarball(可选)、OpenClaw-X.Y.Z.zip 和 OpenClaw-X.Y.Z.dSYM.zip(如果已生成)。
[ ] 提交更新的 appcast.xml 并推送(Sparkle 从 main 分支获取)。
[ ] 从干净的临时目录(无 package.json)运行 npx -y openclaw@X.Y.Z send --help 以确认安装/CLI 入口点工作正常。
[ ] 公告/分享发布说明。

我们仅在 @openclaw/* 范围下发布现有的 npm 插件。未在 npm 上的捆绑插件保持仅磁盘树(仍在 extensions/** 中发布)。

派生列表的过程:

当前 npm 插件列表(根据需要更新):

发布说明还必须指出默认情况下未启用的新的可选捆绑插件(示例:tlon)。