跳转到内容
OpenClaw Docs

更新

保持 OpenClaw 为最新状态。

推荐：openclaw update

Section titled “推荐：openclaw update”

最快的更新方式。它会检测您的安装类型（npm 或 git），获取最新版本，运行 openclaw doctor，并重启网关。

Terminal window
openclaw update

要切换渠道或指定特定版本：

Terminal window
openclaw update --channel beta
openclaw update --channel dev
openclaw update --dry-run   # preview without applying

openclaw update 不接受 --verbose。如需更新诊断，请使用 --dry-run 预览计划操作，使用 --json 获取结构化结果，或 使用 openclaw update status --json 检查渠道和可用性状态。 安装程序有自己的 --verbose 标志，但该标志不是 openclaw update 的一部分。

--channel beta 优先选择 beta，但当 beta 标签缺失或比最新的稳定版本旧时，运行时会回退到 stable/latest。如果您希望针对一次性包更新获取原始的 npm beta dist-tag，请使用 --tag beta。

使用 --channel devGitHub 进行持动的 GitHub main 检出。对于包更新，--tag main 在一次运行中映射到 github:openclaw/openclaw#mainGitHubnpm，并且 GitHub/git 源规范在暂存的 npm 安装之前被打包到一个临时 tarball 中。

对于受管插件，beta 渠道回退是一个警告：核心更新仍然可以成功，即使插件使用其记录的默认/最新版本，因为没有可用的插件 beta 版本。

有关渠道语义，请参阅 开发渠道。

在 npm 和 git 安装之间切换

Section titled “在 npm 和 git 安装之间切换”

当您想要更改安装类型时，请使用渠道。更新程序将您的状态、配置、凭据和工作区保留在 ~/.openclawOpenClawCLI 中；它仅更改 CLI 和 gateway 使用的 OpenClaw 代码安装。

Terminal window
# npm package install -> editable git checkout
openclaw update --channel dev


# git checkout -> npm package install
openclaw update --channel stable

首先使用 --dry-run 运行以预览确切的安装模式切换：

Terminal window
openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run

devCLI 渠道确保 git 检出，构建它，并从该检出安装全局 CLI。stable 和 beta 渠道使用包安装。如果 gateway 已安装，openclaw update 将刷新服务元数据并重新启动它，除非您传递 --no-restart。

对于具有受管 Gateway 服务的包安装，Gateway(网关)openclaw update 以该服务使用的包根目录为目标。如果 shell openclaw 命令来自不同的安装，更新程序将打印两个根目录和受管服务 Node 路径。包更新使用拥有服务根目录的包管理器，并在替换包之前根据目标发布引擎检查受管服务 Node。

替代方案：重新运行安装程序

Section titled “替代方案：重新运行安装程序”
Terminal window
curl -fsSL https://openclaw.ai/install.sh | bash

添加 --no-onboard 以跳过新手引导。要通过安装程序强制特定的安装类型，请传递 --install-method git --no-onboard 或 --install-method npm --no-onboard。

如果 openclaw updatenpm 在 npm 包安装阶段失败，请重新运行 安装程序。安装程序不会调用旧的更新程序；它直接运行全局 包安装，可以恢复部分更新的 npm 安装。

Terminal window
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

要将恢复操作固定到特定版本或分发标签，请添加 --version：

Terminal window
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>

备选方案：手动 npm、pnpm 或 bun

Section titled “备选方案：手动 npm、pnpm 或 bun”
Terminal window
npm i -g openclaw@latest

对于受管安装，首选 openclaw update，因为它可以协调 包交换与正在运行的 Gateway(网关) 服务。如果您在受管安装上 手动更新，请在包管理器启动之前停止受管的 Gateway(网关)。 包管理器会就地替换文件，否则正在运行的 Gateway(网关) 可能会尝试 在包树临时半交换的情况下加载核心或插件文件。 包管理器完成后，请重启 Gateway(网关)，以便服务获取 新安装。

对于 root 拥有的 Linux 系统全局安装，如果 openclaw update 失败并显示 EACCES，并且您使用系统 npm 进行恢复，请保持 Gateway(网关) 在手动包替换期间 处于停止状态。使用您通常为该 Gateway(网关) 使用的相同 openclaw 配置文件标志或环境 变量。将 /usr/bin/npm 替换为您主机上拥有 root 拥有的全局前缀的系统 npm：

Terminal window
openclaw gateway stop
sudo /usr/bin/npm i -g openclaw@latest
openclaw gateway install --force
openclaw gateway restart

然后验证服务：

Terminal window
openclaw --version
curl -fsS http://127.0.0.1:18789/readyz
openclaw plugins list --json
openclaw gateway status --deep --json
openclaw doctor --lint --json

当 openclaw update 管理全局 npm 安装时，它会先将目标安装到临时的 npm 前缀中，验证打包的 dist 清单，然后将干净的包树交换到真正的全局前缀中。这避免了 npm 将新包覆盖到旧包的过时文件上。如果安装命令失败，OpenClaw 会使用 --omit=optional 重试一次。这种重试有助于原生可选依赖无法编译的主机，同时如果后备方案也失败，保持原始失败信息可见。

由 OpenClaw 管理的 npm 更新和插件更新命令也会为子 npm 进程清除 npm min-release-age 隔离。npm 可能会将该策略报告为派生的 before 截止；两者对一般供应链隔离策略都有用，但显式的 OpenClaw 更新意味着“现在安装选定的 OpenClaw 版本”。

Terminal window
pnpm add -g openclaw@latest
Terminal window
bun add -g openclaw@latest

高级 npm 安装主题

Section titled “高级 npm 安装主题”
Read-only package tree

OpenClaw 在运行时将打包的全局安装视为只读，即使当前用户对全局包目录具有写权限也是如此。插件包安装位于用户配置目录下 OpenClaw 拥有的 npm/git 根目录中，且 Gateway(网关) 启动不会改变 OpenClaw 包树。

一些 Linux npm 设置将全局包安装在根用户拥有的目录（如 /usr/lib/node_modules/openclaw）下。OpenClaw 支持这种布局，因为插件安装/更新命令是在该全局包目录之外进行写入的。

Hardened systemd units

授予 OpenClaw 对其配置/状态根目录的写入权限，以便显式插件安装、插件更新和 doctor 清理能够持久化其更改：

ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
Disk-space preflight

在包更新和显式插件安装之前，OpenClaw 会尝试对目标卷进行尽力而为的磁盘空间检查。空间不足会生成包含已检查路径的警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的包管理器安装和安装后验证仍然是决定性的依据。

自动更新程序

Section titled “自动更新程序”

自动更新程序默认关闭。在 ~/.openclaw/openclaw.json 中启用它：

{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}
通道行为
stable等待 stableDelayHours，然后在 stableJitterHours 内应用确定性抖动（分批推出）。
beta每隔 betaCheckIntervalHours 检查一次（默认：每小时）并立即应用。
dev不自动应用。请手动使用 openclaw update。

网关还会在启动时记录更新提示（使用 update.checkOnStart: false 禁用）。 对于降级或事件恢复，请在网关环境中设置 OPENCLAW_NO_AUTO_UPDATE=1 以阻止自动应用，即使配置了 update.auto.enabled。除非同时也禁用了 update.checkOnStart，否则启动更新提示仍可运行。

通过实时 Gateway(网关) 控制平面处理程序请求的包管理器更新 不会替换正在运行的 Gateway(网关) 进程内部的包树。在托管 服务安装中，Gateway(网关) 启动分离的移交，退出，并让 正常的 openclaw update --yes --json CLI 路径停止服务，替换 包，刷新服务元数据，重启，验证 Gateway(网关) 版本 和可达性，并在可能时恢复已安装但未加载的 macOS LaunchAgent。 如果 Gateway(网关) 无法安全地进行该移交，update.run 将报告 一条安全的 shell 命令，而不是在进程内运行包管理器。

更新后

Section titled “更新后”

    回滚

    Section titled “回滚”

    固定版本 (npm)

    Section titled “固定版本 (npm)”
    Terminal window
    npm i -g openclaw@<version>
    openclaw doctor
    openclaw gateway restart

    固定提交 (source)

    Section titled “固定提交 (source)”
    Terminal window
    git fetch origin
    git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
    pnpm install && pnpm build
    openclaw gateway restart

    要返回最新版本：git checkout main && git pull。

    如果遇到问题

    Section titled “如果遇到问题”
    • 再次运行 openclaw doctor 并仔细阅读输出。
    • 对于源代码检出上的 openclaw update --channel dev，更新程序会在需要时自动引导 pnpm。如果您看到 pnpm/corepack 引导错误，请手动安装 pnpm（或重新启用 corepack）并重新运行更新。
    • 检查：故障排除
    • 在 Discord 中询问：https://discord.gg/clawd

    相关

    Section titled “相关”