[OpenClaw 文档]安装--维护

本文档汇总了 OpenClaw 官方文档站 安装 > 维护 子模块下的全部 3 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 更新

原文：https://docs.openclaw.ai/zh-CN/install/updating

让 OpenClaw 保持最新。

推荐：openclaw update

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

openclaw update

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

openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag main
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。

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

请参阅 Development channels 了解频道语义。

在 npm 和 git 安装之间切换

当你想更改安装类型时，请使用频道。更新器会保留你的状态、配置、凭证和
~/.openclaw 中的工作区；它只会更改 CLI 和 Gateway 网关使用的 OpenClaw 代码安装。

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

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

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

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

dev 频道会确保存在 git checkout，构建它，并从该 checkout 安装全局 CLI。
stable 和 beta 频道使用包安装。如果 Gateway 网关已安装，openclaw update
会刷新服务元数据并重启它，除非你传入 --no-restart。

替代方案：重新运行安装器

curl -fsSL https://openclaw.ai/install.sh | bash

添加 --no-onboard 可跳过新手引导。要通过安装器强制使用特定安装类型，
请传入 --install-method git --no-onboard 或
--install-method npm --no-onboard。

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

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

要将恢复固定到特定版本或 dist-tag，请添加 --version：

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

替代方案：手动使用 npm、pnpm 或 bun

npm i -g openclaw@latest

对于受监督的安装，优先使用 openclaw update，因为它可以将包替换与正在运行的
Gateway 网关服务协调起来。如果你在托管 Gateway 网关运行时手动更新，请在包管理器完成后立即重启
Gateway 网关，这样旧进程就不会继续从已替换的包文件提供服务。

当 openclaw update 管理全局 npm 安装时，它会先将目标安装到临时 npm 前缀，
验证打包后的 dist 清单，然后将干净的包树切换到真实的全局前缀。这样可以避免 npm
将新包覆盖到旧包残留文件之上。如果安装命令失败，OpenClaw 会使用 --omit=optional
重试一次。该重试有助于原生可选依赖无法编译的主机，同时如果回退也失败，仍会保留原始失败信息。

pnpm add -g openclaw@latest

bun add -g openclaw@latest

高级 npm 安装主题

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

一些 Linux npm 设置会把全局包安装到 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 支持这种布局，因为插件安装/更新命令会写入该全局包目录之外的位置。

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

```ini
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
```

在包更新和显式插件安装之前，OpenClaw 会尽力对目标卷执行磁盘空间检查。空间不足会产生一条带有已检查路径的警告，但不会阻止更新，因为文件系统配额、快照和网络卷可能会在检查后发生变化。实际的包管理器安装和安装后验证仍然具有权威性。

自动更新器

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

{
  update: {
    channel: "stable",
    auto: {
      enabled: true,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

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

通过实时 Gateway 网关控制平面处理程序请求的包管理器更新，会在包替换后强制执行非延迟、无冷却时间的更新重启。
这样可以避免旧的内存中进程长时间存在，以至于从已经被替换的包树中延迟加载块。
Shell openclaw update 仍然是受监督安装的首选路径，因为它可以围绕更新停止并重启服务。

更新后

运行 Doctor

openclaw doctor

迁移配置、审计私信策略，并检查 Gateway 网关健康状态。详情：Doctor

重启 Gateway 网关

openclaw gateway restart

验证

openclaw health

回滚

固定版本（npm）

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

npm view openclaw version 显示当前已发布版本。

固定提交（源码）

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。

如果你卡住了

• 再次运行 openclaw doctor，并仔细阅读输出。
• 对于源码 checkout 上的 openclaw update --channel dev，更新器会在需要时自动引导 pnpm。如果你看到 pnpm/corepack 引导错误，请手动安装 pnpm（或重新启用 corepack），然后重新运行更新。
• 查看：Troubleshooting
• 在 Discord 中提问：https://discord.gg/clawd

相关内容

• 安装概览：所有安装方法。
• Doctor：更新后的健康检查。
• 迁移：主版本迁移指南。

📄 迁移指南

原文：https://docs.openclaw.ai/zh-CN/install/migrating

OpenClaw 支持三种迁移路径：从另一个智能体系统导入、将现有安装移到新机器，以及就地升级插件。

从另一个智能体系统导入

使用内置迁移提供商将指令、MCP 服务器、Skills、模型配置和（可选）API 密钥导入 OpenClaw。任何更改前都会先预览计划，报告中会遮蔽密钥，应用更改时会有经过验证的备份作为支撑。

导入 Claude Code 和 Claude Desktop 状态，包括 CLAUDE.md、MCP 服务器、Skills 和项目命令。


导入 Hermes 配置、提供商、MCP 服务器、记忆、Skills 和受支持的 .env 键。

CLI 入口点是 openclaw migrate。当新手引导检测到已知来源时，也可以提供迁移（openclaw onboard --flow import）。

将 OpenClaw 移到新机器

复制状态目录（默认是 ~/.openclaw/）和你的工作区，以保留：

• 配置 — openclaw.json 和所有 Gateway 网关设置。
• 凭证 — 每个智能体的 auth-profiles.json（API 密钥和 OAuth），以及 credentials/ 下的任何渠道或提供商状态。
• 会话 — 对话历史和智能体状态。
• 渠道状态 — WhatsApp 登录、Telegram 会话，以及类似内容。
• 工作区文件 — MEMORY.md、USER.md、Skills 和提示词。

在旧机器上运行 openclaw status，确认你的状态目录路径。自定义配置使用 ~/.openclaw-<profile>/，或使用通过 OPENCLAW_STATE_DIR 设置的路径。

迁移步骤

在旧机器上停止 Gateway 网关，避免文件在复制过程中发生变化，然后归档：

```bash
openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw
```

如果你使用多个配置（例如 `~/.openclaw-work`），请分别归档每一个。

在新机器上安装 CLI（如有需要也安装 Node）。如果新手引导创建了新的 ~/.openclaw/，也没有问题。下一步会覆盖它。

通过 scp、rsync -a 或外部硬盘传输归档，然后解压：

```bash
cd ~
tar -xzf openclaw-state.tgz
```

确保隐藏目录已包含在内，并且文件所有权与将运行 Gateway 网关的用户一致。

在新机器上运行 Doctor，应用配置迁移并修复服务：

```bash
openclaw doctor
openclaw gateway restart
openclaw status
```

如果 Telegram 或 Discord 使用默认环境变量回退（TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN），请验证迁移后的状态目录 .env 是否包含这些键，同时不要打印密钥值：

awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

当已启用的默认 Telegram 或 Discord 账号没有配置令牌，并且 Doctor 进程无法使用匹配的环境变量时，openclaw doctor 也会发出警告。

常见陷阱

如果旧 Gateway 网关使用了 --profile 或 OPENCLAW_STATE_DIR，而新的没有使用，渠道会显示为已登出，会话也会为空。用你迁移的同一个配置或状态目录启动 Gateway 网关，然后重新运行 openclaw doctor。

仅配置文件还不够。模型凭证配置文件位于 agents/<agentId>/agent/auth-profiles.json 下，渠道和提供商状态位于 credentials/ 下。请始终迁移整个状态目录。

如果你以 root 身份复制，或切换了用户，Gateway 网关可能无法读取凭证。确保状态目录和工作区归运行 Gateway 网关的用户所有。

如果你的 UI 指向远程 Gateway 网关，会话和工作区归远程主机所有。迁移 Gateway 网关主机本身，而不是你的本地笔记本电脑。参见常见问题。

状态目录包含凭证配置文件、渠道凭证和其他提供商状态。请加密存储备份，避免使用不安全的传输渠道；如果你怀疑发生暴露，请轮换密钥。

验证清单

在新机器上确认：

• [ ] openclaw status 显示 Gateway 网关正在运行。
• [ ] 渠道仍保持连接（无需重新配对）。
• [ ] 仪表盘可以打开，并显示现有会话。
• [ ] 工作区文件（记忆、配置）存在。

就地升级插件

就地插件升级会保留相同的插件 ID 和配置键，但可能会把磁盘上的状态移入当前布局。插件专属升级指南与其渠道放在一起：

• Matrix 迁移：加密状态恢复限制、自动快照行为和手动恢复命令。

相关内容

• openclaw migrate：跨系统导入的 CLI 参考。
• 安装概览：所有安装方法。
• Doctor：迁移后的健康检查。
• 卸载：干净地移除 OpenClaw。

📄 卸载

原文：https://docs.openclaw.ai/zh-CN/install/uninstall

两种路径：

• 如果 openclaw 仍已安装，使用简易路径。
• 如果 CLI 已不存在但服务仍在运行，使用手动移除服务。

简易路径（CLI 仍已安装）

推荐：使用内置卸载程序：

openclaw uninstall

非交互式（自动化 / npx）：

openclaw uninstall --all --yes --non-interactive
npx -y openclaw uninstall --all --yes --non-interactive

手动步骤（结果相同）：

1. 停止 Gateway 网关服务：

openclaw gateway stop

2. 卸载 Gateway 网关服务（launchd/systemd/schtasks）：

openclaw gateway uninstall

3. 删除状态 + 配置：

rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"

如果你将 OPENCLAW_CONFIG_PATH 设置为状态目录之外的自定义位置，也请删除该文件。

4. 删除你的工作区（可选，会移除智能体文件）：

rm -rf ~/.openclaw/workspace

5. 移除 CLI 安装（选择你使用的方式）：

npm rm -g openclaw
pnpm remove -g openclaw
bun remove -g openclaw

6. 如果你安装了 macOS 应用：

rm -rf /Applications/OpenClaw.app

说明：

• 如果你使用了配置文件（--profile / OPENCLAW_PROFILE），请对每个状态目录重复步骤 3（默认值为 ~/.openclaw-<profile>）。
• 在远程模式下，状态目录位于Gateway 网关主机上，因此也要在那里运行步骤 1-4。

手动移除服务（CLI 未安装）

如果 Gateway 网关服务持续运行但 openclaw 缺失，请使用此方法。

macOS（launchd）

默认标签为 ai.openclaw.gateway（或 ai.openclaw.<profile>；旧版 com.openclaw.* 可能仍然存在）：

launchctl bootout gui/$UID/ai.openclaw.gateway
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist

如果你使用了配置文件，请将标签和 plist 名称替换为 ai.openclaw.<profile>。如果存在任何旧版 com.openclaw.* plist，也请将其删除。

Linux（systemd 用户单元）

默认单元名称为 openclaw-gateway.service（或 openclaw-gateway-<profile>.service）：

systemctl --user disable --now openclaw-gateway.service
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload

Windows（计划任务）

默认任务名称为 OpenClaw Gateway（或 OpenClaw Gateway (<profile>)）。
任务脚本位于你的状态目录下。

schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"

如果你使用了配置文件，请删除匹配的任务名称和 ~\.openclaw-<profile>\gateway.cmd。

正常安装 vs 源码检出

正常安装（install.sh / npm / pnpm / bun）

如果你使用了 https://openclaw.ai/install.sh 或 install.ps1，CLI 是通过 npm install -g openclaw@latest 安装的。
请使用 npm rm -g openclaw 将其移除（如果你是通过 pnpm / bun 安装的，则使用 pnpm remove -g / bun remove -g）。

源码检出（git clone）

如果你是从仓库检出运行（git clone + openclaw ... / bun run openclaw ...）：

1. 在删除仓库之前先卸载 Gateway 网关服务（使用上面的简易路径或手动移除服务）。
2. 删除仓库目录。
3. 按上文所示移除状态 + 工作区。

相关

• 安装概览
• 迁移指南