发布渠道

OpenClaw 提供四个更新通道：

• stable：npm dist-tag latest。推荐大多数用户使用。
• extended-stable：npm dist-tag extended-stable。一个全新的、按支持月份滞后提供的包通道。它仅支持包，且安装仅在前台进行。当启用 update.checkOnStart 时，它会接收只读更新提示，包括直接安装最终 extended-stable 包，但绝不会自动应用。
• beta：按语义化版本顺序，来自 npm beta 和 latest dist-tags 的最新版本。较旧的 beta 标签绝不会替换较新的 stable 发布。
• dev：main（git）的移动头指针，包括从包安装切换时。main 用于实验和活跃开发；它可能包含不完整的功能或破坏性变更。请勿在生产网关中运行它。

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

切换通道¶

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

--channel 控制更新，并在核心更新成功后将选择持久化到配置中的 update.channel。被拒绝或失败的核心更新会保留之前的通道。所选通道同时驱动两种安装路径：

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

对于托管 Gateways，成功切换会在检查就绪状态之前将服务刷新到已验证的安装。被拒绝的切换或已验证的回滚会恢复之前的服务；未验证的恢复会使其保持停止以供检查。

对于 dev git 安装，默认检出为 ~/openclaw（当设置 OPENCLAW_HOME 时为 $OPENCLAW_HOME/openclaw）；可用 OPENCLAW_GIT_DIR 覆盖。自动更新活动会固定其宣布的上游提交，因此即使 main 在倒计时期间前进，显示列表也会预览来自确切安装目标的至多五个提交。手动 openclaw update --channel dev 仍指向当前上游 main。

一次性版本或标签指定¶

使用 --tag 为单次更新指定特定的 dist-tag、版本或包规范，而不会更改持久化的通道：

# 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，解析到精确的已安装核心版本。它不会在运行时查询 插件的 @extended-stable 标签。版本绑定的运行时插件在修正版本中使用 基础发布群组（例如，YYYY.M.P-2 使用插件 YYYY.M.P）。
• 通过 npm 安装的插件会在核心更新完成后更新。
• beta 对受管理的 npm 插件使用相同的 beta/latest 中最新者规则， 包括 @openclaw/codex 等官方插件。精确版本和范围 固定值会保留其选择器。启动修复会保留已经是最新版本的插件， 而不是重新安装它并要求再次重启。

检查当前状态¶

openclaw update status

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

标签最佳实践¶

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

macOS 应用可用性¶

Beta 和 dev 构建可能不包含 macOS 应用发布。这没关系：

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

相关¶

• 更新
• 安装程序内部机制
• 发布策略 - 说明如何切分并发布到这些渠道