15.6 发布说明

参考与模板参考与模板

发布检查清单（npm + macOS）

从仓库根目录使用 pnpm（Node 22+）。在标记/发布之前保持工作树干净。

操作员触发

当操作员说"发布"时，立即执行此预检（除非被阻止，否则不要问额外的问题）：

  • 阅读本文档和 docs/platforms/mac/release.md
  • 从 ~/.profile 加载环境变量，确认已设置 SPARKLE_PRIVATE_KEY_FILE + App Store Connect 变量
  • 如果需要，使用来自 ~/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
  • [ ] 如果依赖项发生变化，运行 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/** 用于无头 node + ACP CLI）
  • [ ] 确认 dist/build-info.json 存在并包含预期的 commit 哈希
  • [ ] 可选：构建后运行 npm pack --pack-destination /tmp；检查 tarball 内容并保留它用于 GitHub 发布（不要提交它）

3. 更新日志和文档

  • [ ] 用面向用户的亮点更新 CHANGELOG.md（如果缺少则创建文件）；严格按版本降序保持条目
  • [ ] 确保 README 示例/标志与当前 CLI 行为匹配（特别是新命令或选项）

4. 验证

  • [ ] pnpm lint
  • [ ] pnpm test（或如果需要覆盖率输出则使用 pnpm test:coverage）
  • [ ] pnpm run build（测试后的最后完整性检查）
  • [ ] pnpm release:check（验证 npm pack 内容）
  • [ ] OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke（Docker 安装冒烟测试，快速路径；发布前必需）
  • [ ] （可选）完整安装冒烟：pnpm test:install:smoke
  • [ ] （可选）安装器 E2E：pnpm test:install:e2e:openai、pnpm test:install:e2e:anthropic 或 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 钥匙串配置文件

6. 发布（npm）

  • [ ] 确认 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

故障排除（来自 2.0.0-beta2 发布的注释）

  • npm pack/publish 挂起或生成巨大的 tarball：通过 package.json files 将发布内容列入白名单
  • npm auth web 循环用于 dist-tags：使用旧版身份验证获取 OTP 提示：NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add openclaw@X.Y.Z latest
  • npx 验证失败并显示 ECOMPROMISED：使用新鲜缓存重试
  • 延迟修复后需要重新指向标签：强制更新并推送标签

7. GitHub 发布 + appcast

  • [ ] 标记并推送：git tag vX.Y.Z && git push origin vX.Y.Z
  • [ ] 为 vX.Y.Z 创建/刷新 GitHub 发布，标题为 openclaw X.Y.Z；正文应包含该版本的完整更新日志部分
  • [ ] 附加制品：npm pack tarball、OpenClaw-X.Y.Z.zip 和 OpenClaw-X.Y.Z.dSYM.zip
  • [ ] 提交更新的 appcast.xml 并推送它
  • [ ] 从干净的临时目录运行 npx -y openclaw@X.Y.Z send --help 以确认安装/CLI 入口点正常工作
  • [ ] 宣布/分享发布说明

插件发布范围（npm）

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

当前 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）。