跳转至

发布渠道

OpenClaw 提供四个更新通道:

  • stable:npm dist-tag latest。推荐大多数用户使用。
  • extended-stable:npm dist-tag extended-stable。这是一个全新的、尾随受支持月份的包通道。它仅支持包安装,且安装仅限前台。当启用 update.checkOnStart 时,它会收到只读更新提示,包括直接安装最终 extended-stable 包的提示,但绝不会自动应用。
  • beta:按语义化版本顺序,来自 npm beta 和 latest dist-tag 的最新版本。较旧的 beta 标签永远不会取代较新的稳定版。
  • dev:main(git)分支的移动头,包括从包安装切换过来时。main 用于实验和活跃开发;它可能包含不完整的功能或破坏性变更。不要在生产环境 Gateway 上运行它。

稳定版通常先发布到 beta,在那里经过验证,然后在不提升版本号的情况下晋升到 latest。维护者也可以直接发布到 latest。dist-tag 是 npm 安装的权威来源。

切换通道

openclaw update --channel stable
openclaw update --channel extended-stable
openclaw update --channel beta
openclaw update --channel dev

--channel 驱动更新,并在核心更新成功后将该选择持久化到配置中的 update.channel。如果核心更新被拒绝或失败,则会保留之前的通道。所选通道决定以下两种安装路径:

通道 npm/包安装 git 安装
stable dist-tag latest 切换到 npm 包的 latest 版本
extended-stable 解析公共 npm extended-stable 选择器,验证确切选定的包,并安装该确切版本。验证失败即关闭(fail closed),不回退到 latest、beta 或 dev。 不支持:OpenClaw 保持检出不变,并要求你使用包安装方式
beta dist-tag beta,当 beta 缺失或更旧时回退到 latest 切换到 npm 包的 beta 版本,当 beta 缺失或更旧时回退到 latest
dev 切换到 Git 检出,构建它,并重新安装全局 CLI 获取(fetch),将检出变基(rebase)到上游 main 分支,然后构建并重新安装全局 CLI

显式的 --channel stable 或 --channel beta 会将 Git 安装切换为包安装。在 Git 检出中直接运行不带参数的 openclaw update,如果此前存储的是 stable 或 beta 通道,则会选择相应的 Git 标签。对于这些 Git 标签更新,OpenClaw 会刷新分支,但不会向其配置的 refspec 添加强制(force),然后仅从发布远程(release remote)强制刷新标签。保留的 branch.main.remote 设置优先,其次是 origin 或唯一配置的远程。如果有多个远程且以上两者都不适用,请在重试前将 branch.main.remote 设置为发布版本的远程。重新创建的发布标签会替换其旧副本;仅存在于本地的标签会被保留。即使 Git 的 fetch.pruneTags 设置已启用,标签修剪(pruning)也会被禁用。这些保证假定使用标准的分支获取映射;显式包含标签的自定义 remote.*.fetch 映射仍遵循 Git 的配置行为。常规 CLI 在允许更新之前会在一个私有仓库中检查这些引用,因此被拒绝的更新会保持已安装检出的引用不变。

对于受管理的 Gateway,成功的切换会在检查就绪状态之前将服务刷新为已验证的安装。被拒绝的切换或已验证的回滚会恢复之前的服务;未经验证的恢复会使其保持停止状态以供检查。

对于 dev git 安装,默认检出路径是 ~/openclaw(当设置了 OPENCLAW_HOME 时为 $OPENCLAW_HOME/openclaw);可使用 OPENCLAW_GIT_DIR 覆盖。自动更新活动会固定其所宣布的上游提交,因此即使 main 在倒计时期间前进了,显示的列表也会预览确切安装目标中的最多五个提交。手动运行 openclaw update --channel dev 仍以当前上游 main 为目标。

Tip

若要并行保留 stable 和 dev,请使用两个独立的检出,并让每个 gateway 指向各自的检出。

一次性版本或标签定位

使用 --tag 可在单次更新中定位特定的 dist-tag、版本或包规范(package spec),不改变已持久化的通道:

# Install a specific version
openclaw update --tag 2026.4.1-beta.1

# Install from the beta dist-tag (one-off, does not persist)
openclaw update --tag beta

# Switch to the moving GitHub main checkout (persistent)
openclaw update --channel dev

# Install a specific npm package spec
openclaw update --tag openclaw@2026.4.1-beta.1

说明:

  • --tag 仅适用于包(npm)安装;git 安装会忽略它。
  • 该标签不会被持久化;下一次 openclaw update 会使用已配置的通道。
  • 存储了 update.channel: "dev" 的包安装仍会遵循一次性 --tag,而不会切换到 Git。显式的 --channel dev 优先于 --tag,并选择 Git 检出流程。
  • --tag main 简写形式在包安装中会被拒绝,因为工作区检出不是自包含的包产物。请使用 openclaw update --channel dev(包安装会切换到 git 检出),或使用安装程序的 git 方法重新安装:curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --version main。
  • 降级保护:如果目标版本旧于当前版本,OpenClaw 会提示确认(可使用 --yes 跳过)。
  • Extended-stable 始终使用其已验证的精确包目标。它不是 --tag extended-stable 的一次性别名,并且 --tag 不能与生效的 extended-stable 通道组合使用。
  • --channel beta 与 --tag beta 不同:通道流程在 beta 缺失或更旧时可以回退到 stable/latest,而 --tag beta 在这一次运行时始终以原始 beta dist-tag 为目标。

试运行

预览 openclaw update 将会执行的操作,而不进行任何更改:

openclaw update --dry-run
openclaw update --channel beta --dry-run
openclaw update --tag 2026.4.1-beta.1 --dry-run
openclaw update --dry-run --json

试运行会报告生效的渠道、目标版本、计划执行的操作,以及是否需要降级确认。

插件与渠道

使用 openclaw update 切换渠道时,也会同步插件源:

  • dev 会将已安装且存在捆绑对应版本的插件切换回其捆绑(git checkout)源。
  • stable 和 beta 会恢复通过 npm 安装或 ClawHub 安装的插件包。
  • extended-stable 会将符合条件的官方 npm 插件,在 bare/default 或 latest 意图下,解析到精确安装的 core 版本。它不会在运行时查询插件的 @extended-stable 标签。版本绑定的运行时插件会使用基础发布队列来修正版本(例如,YYYY.M.P-2 使用插件 YYYY.M.P)。
  • npm 安装的插件会在 core 更新完成后更新。
  • beta 对受管理的 npm 插件使用相同的“beta/latest 中最新”规则,包括 @openclaw/codex 等官方插件。精确版本和范围固定会保留其选择器。启动修复会保留已经最新的插件,而不是重新安装并要求再次重启。

检查当前状态

openclaw update status

显示当前活动渠道(以及决定该渠道的来源:配置、git tag、git branch、已安装版本或默认值)、安装类型(git 或 package)、当前版本以及更新可用性。 它还显示最后一次记录的更新运行,包括失败的 fetch。普通的 openclaw status 使用缓存的 Git refs,而不执行 fetch。如果当前状态目录中最近一次记录的更新 fetch 失败,它会显示 update check stale: last update fetch failed,并附上失败时长和简短原因,而不是 up to date。ahead/behind 计数会标记为 cached。 后续一次完成 fetch 的更新运行会清除该警告,即使更新的其余部分被跳过、失败或回滚。手动执行 git fetch 不会清除已记录的警告。请使用 openclaw update status 进行新的可用性检查,或再次运行 openclaw update。openclaw status --deep 也会为该检查执行 fetch,但不会更改 ledger。

标签最佳实践

  • 为希望 git checkout 落地的发布打标签:常规 stable 使用 vYYYY.M.PATCH,patch 为 1 到 32;beta 使用 vYYYY.M.PATCH-beta.N。诸如 -alpha.N、-rc.N 和 -next.N 等命名预发布后缀不是 stable 或 beta 目标。
  • 旧版数字 stable 标签,例如 vYYYY.M.PATCH-1 和 v1.0.1-1,出于兼容性仍会被识别为 stable git 标签,但每月补丁 33 及更高版本除外。这些补丁保留给 extended-stable;最终标签和数字修正变体永远不会是常规 stable 目标或 beta 的 stable 回退。extended-stable 仍然是仅 package 的更新渠道。
  • vYYYY.M.PATCH.beta.N(点分隔)也出于兼容性被识别;请优先使用 -beta.N。
  • 保持标签不可变:永远不要移动或复用标签。
  • npm dist-tags 仍然是 npm 安装的权威来源:
  • latest -> stable
  • extended-stable -> 尾随受支持月份的 package 发布
  • beta -> 候选构建或 beta 优先的 stable 构建
  • dev -> main 快照(可选)

macOS 应用可用性

Beta 和 dev 构建可能不包含 macOS 应用发布。这没问题:

  • git tag 和 npm dist-tag 仍可单独发布。
  • 在发布说明或 changelog 中注明“此 beta 没有 macOS 构建”。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw