发布流程

从仓库根目录使用 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 密钥。

1. 版本和元数据

- [ ] 增加 package.json 版本（例如 2026.1.29）。

- [ ] 运行 pnpm plugins:sync 以对齐扩展包版本 + 更改日志。

- [ ] 更新 CLI/版本字符串：src/cli/program.ts 和 src/provider-web.ts 中的 Baileys 用户代理。

- [ ] 确认包元数据（名称、描述、仓库、关键字、许可证）和 bin 映射指向 openclaw.mjs 以用于 openclaw。

- [ ] 如果依赖项更改，运行 pnpm install 以使 pnpm-lock.yaml 为最新。

2. 构建和产物

- [ ] 如果 A2UI 输入更改，运行 pnpm canvas:a2ui:bundle 并提交任何更新的 src/canvas-host/a2ui/a2ui.bundle.js。

- [ ] pnpm run build（重新生成 dist/）。

- [ ] 验证 npm 包 files 包含所有必需的 dist/* 文件夹（特别是 dist/node-host/** 和 dist/acp/** 用于无头节点 + ACP CLI）。

- [ ] 确认 dist/build-info.json 存在并包含预期的 commit 哈希（CLI 横幅使用此哈希进行 npm 安装）。

- [ ] 可选：构建后运行 npm pack --pack-destination /tmp；检查 tarball 内容并保留它以备 GitHub 发布使用（不要提交它）。

3. 更改日志和文档

- [ ] 更新 CHANGELOG.md 以包含面向用户的亮点（如果文件缺失则创建）；保持条目严格按版本降序排列。

- [ ] 确保 README 示例/标志与当前 CLI 行为匹配（特别是新命令或选项）。

4. 验证

- [ ] 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 安装冒烟测试，快速路径；发布前必需）

- If the immediate previous npm release is known broken, set OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version> or OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1 for the preinstall step.

- [ ] （可选）完整安装程序冒烟测试（添加非 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 网关。

5. macOS 应用程序（Sparkle）

- [ ] 构建 + 签名 macOS 应用程序，然后将其压缩以进行分发。

- [ ] 生成 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 发布）。

6. 发布（npm）

- [ ] 确认 git 状态干净；根据需要提交并推送。

- [ ] npm login（如果需要，验证 2FA）。

- [ ] npm publish --access public（对于预发布使用 --tag beta）。

- [ ] 验证注册表：npm view openclaw version、npm view openclaw dist-tags 和 npx -y [email protected] --version（或 --help）。

#

7. GitHub 发布 + appcast

- [ ] 标记并推送：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 [email protected] send --help 以确认安装/CLI 入口点工作。

- [ ] 公布/共享发布说明。

- npm pack/publish 挂起或产生巨大的 tarball：dist/OpenClaw.app（和发布 zip）中的 macOS 应用程序包被扫入包中。通过 package.json files 白名单发布内容来修复（包含 dist 子目录、文档、技能；排除应用程序包）。使用 npm pack --dry-run 确认 dist/OpenClaw.app 未列出。

- dist-tags 的 npm auth Web 循环：使用传统身份验证获取 OTP 提示：

- NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add [email protected] latest

- npx 验证失败并显示 ECOMPROMISED: Lock compromised：使用新缓存重试：

- NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y [email protected] --version

- 标签在后期修复后需要重新指向：强制更新并推送标签，然后确保 GitHub 发布资产仍然匹配：

- git tag -f vX.Y.Z && git push -f origin vX.Y.Z

我们只发布 @openclaw/* 范围下的现有 npm 插件。捆绑的插件不在 npm 上保持仅磁盘树（仍然在 extensions/** 中提供）。

派生列表的过程：

1. npm search @openclaw --json 并捕获包名称。

2. 与 extensions/*/package.json 名称进行比较。

3. 仅发布交集（已在 npm 上）。

当前 npm 插件列表（根据需要更新）：

- @openclaw/bluebubbles

- @openclaw/diagnostics-otel

- @openclaw/discord

- @openclaw/lobster

- @openclaw/matrix

- @openclaw/msteams

- @openclaw/nextcloud-talk

- @openclaw/nostr

- @openclaw/voice-call

- @openclaw/zalo

- @openclaw/zalouser

发布说明还必须注明新的可选捆绑插件，这些插件**默认不启用**（例如：tlon）。