发布检查清单（npm + macOS）

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

操作员触发

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

  • 阅读本文档和 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/* 文件夹（特别是用于无头 node + ACP CLI 的 dist/node-host/** 和 dist/acp/**）
  • 确认 dist/build-info.json 存在并包含预期的提交哈希（CLI 横幅为 npm 安装使用此信息）
  • 可选：构建后使用 npm pack --pack-destination /tmp；检查 tarball 内容并保留它以便 GitHub 发布（不要提交）

变更日志和文档

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

验证

  • 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= 或 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 应用（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 发布）

发布（npm）

  • 确认 git status 是干净的；根据需要提交并推送
  • 如果需要，npm login（验证 2FA）
  • npm publish --access public（对于预发布使用 --tag beta）
  • 验证注册表：npm view openclaw version、npm view openclaw dist-tags 和 npx -y openclaw@latest --version（或 --help）

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

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

  • dist-tags 的 npm auth web 循环： 使用旧版 auth 获取 OTP 提示：

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

  • npx 验证失败并显示 ECOMPROMISED： 锁已损坏：使用新缓存重试：

    NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y openclaw@latest --version

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

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

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 openclaw@latest send --help 以确认安装/CLI 入口点工作
  • 宣布/分享发布说明

插件发布范围（npm）

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

派生列表的过程：

  • npm search @openclaw --json 并捕获包名称
  • 与 extensions/*/package.json 名称比较
  • 仅发布交集（已在 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）。

← 返回文档首页