`openclaw uninstall` 完全卸载指南:移除 Gateway 网关服务与本地数据(CLI 保留)

原创2026-10-14 21:03:361,698 阅读
文章标签:人工智能大模型AI 应用后端LLM 网关即时通讯AI Agent插件系统本地部署MCP Clients

openclaw uninstall 完全卸载指南:移除 Gateway 网关服务与本地数据(CLI 保留)

openclaw uninstall 是 OpenClaw CLI 提供的维护类命令,用于从当前机器上移除 Gateway 网关服务与本地状态数据,同时保留 CLI 本身以便后续重新安装或彻底删除。本指南以 docs/zh-CN/cli/uninstall.md 为核心,结合仓库源码与测试,系统讲解该命令的四种卸载范围、全部参数、交互与非交互流程、底层服务卸载原理,以及与其他维护命令(reset、doctor)的边界,帮助你安全、可预测地完成卸载。

快速上手

卸载命令的基本形态如下:

# 先创建可恢复的快照(推荐,涉及状态或工作区删除时)
openclaw backup create

# 交互式卸载(默认:选择卸载范围并确认)
openclaw uninstall

# 一键卸载所有组件,跳过所有确认提示
openclaw uninstall --all --yes

# 只查看将要执行的操作,不真正删除任何文件
openclaw uninstall --dry-run

命令的定位是「卸载 Gateway 网关服务 + 本地数据(CLI 保留)」:执行完毕后,openclaw 命令行工具本身仍然安装在系统中,若想连同 CLI 一起移除,需另行通过 npm/pnpm 卸载(见文末)。

卸载范围:四个可独立选择的组件

openclaw uninstall 把卸载内容划分为四个互不干扰的「范围(scope)」,可以单独卸载,也可以组合卸载。从 commands/uninstall.ts 的 UninstallScope 类型可以看到这四个范围的定义:

范围 说明 典型路径
service Gateway 网关系统服务 launchd / systemd / schtasks 注册的服务
state 本地状态与配置 ~/.openclaw(状态目录、配置、OAuth 凭据)
workspace Agent 工作区目录 配置文件中的 agents.defaults.workspace 及每个 agent 的 workspace 指向的目录
app macOS 桌面应用 /Applications/OpenClaw.app(仅 macOS 平台)

在交互模式下直接运行 openclaw uninstall,CLI 会通过多选列表(multiselect)让你勾选要卸载的组件,默认预选 service、state、workspace 三项(见 commands/uninstall.ts),app 仅当平台为 macOS 时参与选择。

参数详解

命令的参数在 cli/program/register.maintenance.ts 中注册,完整清单如下:

参数 默认值 作用
--service false 移除 Gateway 网关系统服务
--state false 移除本地状态与配置
--workspace false 移除工作区目录
--app false 移除 macOS 应用(/Applications/OpenClaw.app)
--all false 同时移除 service + state + workspace + app 四项
--yes false 跳过所有确认提示
--non-interactive false 禁用交互提示(要求同时提供 --yes)
--dry-run false 只打印将要执行的操作,不删除任何文件

几个关键组合的实际效果:

# 只卸载系统服务,保留全部数据(以后可随时 openclaw gateway install 重新装回)
openclaw uninstall --service --yes

# 卸载服务 + 状态 + 工作区,保留 macOS 应用
openclaw uninstall --service --state --workspace --yes

# 非交互脚本场景:全量卸载,全程无提示(缺 --yes 会直接报错退出码 1)
openclaw uninstall --all --yes --non-interactive

# 安全检查:先预览所有将被移除的路径
openclaw uninstall --all --dry-run

参数之间的约束关系

从 commands/uninstall.ts 的实现可以看出两处硬性约束,自动化脚本中尤其需要注意:

  • 非交互模式必须显式指定范围:--non-interactive 且未传任何范围参数(--all/--service/--state/--workspace/--app)时,命令会报错 Non-interactive mode requires explicit scopes (use --all). 并以退出码 1 结束;
  • 非交互模式必须搭配 --yes:--non-interactive 不带 --yes 时,报错 Non-interactive mode requires --yes. 并退出。这是为了防止无人值守环境中命令被中途挂起等待输入。

交互式卸载流程

不带任何范围参数运行时,交互流程分为三步(参见 commands/uninstall.ts):

  1. 多选范围:提示 Uninstall which components?,可选 Gateway service(launchd / systemd / schtasks)、State + config(~/.openclaw)、Workspace(agent files)、macOS app;
  2. 二次确认:显示 Proceed with uninstall? 确认提示,选择取消则打印 Uninstall cancelled. 并正常退出(退出码 0);
  3. 依次执行:按 service → state → workspace → app 的顺序执行清理,最后输出 CLI still installed. Remove via npm/pnpm if desired.

交互模式的每一步都可在中途安全取消,取消不会删除任何文件。

先备份:openclaw backup create

原文档(英文版 docs/cli/uninstall.md)和源码都强调一个关键建议:在移除状态或工作区之前,先创建可恢复的备份快照。

openclaw backup create
openclaw uninstall --state --workspace

这一建议并非口头提醒,而是写进了实现逻辑:当卸载范围包含 state 或 workspace 时,commands/uninstall.ts 会调用 logBackupRecommendation 打印 Recommended first: openclaw backup create;而仅卸载服务(--service)时不会出现该提示,因为服务注册信息可通过重新安装恢复。commands/uninstall.test.ts 中有两条对应的测试用例,分别验证「含 state/workspace 时推荐备份」与「仅 service 时不推荐备份」。

源码级原理:卸载到底做了什么

1. 命令注册

顶层 openclaw uninstall 在 cli/program/register.maintenance.ts 中注册,与 doctor、dashboard、reset 同属维护类命令,统一通过 runCommandWithRuntime 运行。参数解析完成后,会把布尔参数汇聚为 UninstallOptions 交给 uninstallCommand 执行。

2. 服务卸载的完整生命周期

卸载系统服务时,stopAndUninstallService(commands/uninstall.ts)遵循「先停服务、再注销、最后校验」的流程:

  1. 检查 Nix 模式:若检测到 Nix 模式(isNixMode),服务卸载会被直接禁用并报错;
  2. 通过 service.isLoaded() 判断服务当前是否已加载/注册;
  3. 已加载则先 service.stop() 停止服务;
  4. 再调用 service.uninstall() 移除服务注册;
  5. 返回成功标志。

更深层的保障在 runServiceUninstall(cli/daemon-cli/lifecycle-core.ts)中:它同样执行「先停止(stopBeforeUninstall: true)、卸载后再断言服务已不存在(assertNotLoadedAfterUninstall: true)」。如果卸载后服务仍然处于加载状态,会直接判定失败并输出 Gateway service still loaded after uninstall.,避免留下「半卸载」的脏状态。

3. 各平台的网关服务抽象

Gateway 服务并非平台特定的硬编码,而是通过 daemon/service.ts 中按平台注册的 GatewayService 接口抽象:

平台 服务类型 卸载实现
macOS(darwin) LaunchAgent uninstallLaunchAgent
Linux(linux) systemd(用户级服务) uninstallSystemdService
Windows(win32) Scheduled Task uninstallScheduledTask

resolveGatewayService() 会根据 process.platform 自动选择对应实现;不受支持的平台会抛出 Gateway service install not supported on <platform> 错误。这也是多选提示中服务类型标注为「launchd / systemd / schtasks」的原因——你看到的具体服务名取决于当前操作系统。

4. 路径清理与安全防护

状态与工作区的删除由 commands/cleanup-utils.ts 负责,包含三层关键逻辑:

  • 计划解析:commands/cleanup-plan.ts 通过 resolveCleanupPlanFromDisk() 读取磁盘上的真实路径——状态目录(resolveStateDir)、配置文件(resolveConfigPath)、OAuth 凭据目录(resolveOAuthDir),并计算配置/凭据是否位于状态目录之内,避免重复删除;
  • 工作区收集:collectWorkspaceDirs 汇总 agents.defaults.workspace 与每个 agent 的 workspace 配置;若配置为空则回退到默认工作区目录(commands/cleanup-utils.ts);
  • 危险路径拦截:isUnsafeRemovalTarget 会拒绝删除路径解析后等于文件系统根目录或用户主目录的目标,打印 Refusing to remove unsafe path: ...(commands/cleanup-utils.ts)。removePath 同时支持 dryRun 模式——此时只输出 [dry-run] remove <path>,不会真正调用 fs.rm。

state 范围删除时会联动处理关联路径:状态目录、配置文件、OAuth 目录依次移除;若配置或凭据本身就在状态目录内(configInsideState / oauthInsideState 为真),则自动跳过重复删除(commands/cleanup-utils.ts)。

卸载、重置与修复:三个命令的边界

卸载命令与仓库中另外两个维护命令容易混淆,这里给出清晰的区分:

命令 定位 是否删除状态数据 是否删除系统服务
openclaw uninstall 彻底移除服务与本地数据 是(可选 --state/--workspace) 是(可选 --service/--all)
openclaw reset 重置本地配置/状态,保留 CLI 是(--scope 控制深度) 否
openclaw doctor 健康检查 + 快速修复 否(仅修复) 否(可 --deep 扫描额外服务)

三者均注册于 cli/program/register.maintenance.ts。如果你只是想清空配置重新初始化(比如换一套模型配置),用 openclaw reset 即可;只有当你决定不再运行 Gateway 网关,才需要 openclaw uninstall。reset 的交互选择中同样会提示备份与后续的 openclaw onboard --install-daemon 引导(commands/reset.ts)。

卸载完成之后

无论选择哪种范围,命令末尾都会输出:

CLI still installed. Remove via npm/pnpm if desired.

即 OpenClaw CLI 本体始终保留。需要彻底移除 CLI 时,根据当初的安装方式执行:

# npm 全局安装
npm uninstall -g openclaw

# 或 pnpm 全局安装
pnpm remove -g openclaw

如果卸载了 state 但保留了 workspace,命令还会提示:工作区已保留,可用 --workspace 再次执行以删除(commands/uninstall.ts)。

验证与可观测性

  • 测试覆盖:commands/uninstall.test.ts 通过 mock 验证了「备份推荐」的两条关键行为;服务生命周期逻辑在 cli/daemon-cli/install.test.ts 中亦有覆盖,uninstall 行为被挂载为可注入的 mock 实现。
  • 行为审计:整个卸载过程全程打印每一步的 [dry-run] remove ... 或 Removed ... 日志,配合 --dry-run 可以先完整审计将要删除的路径清单,再决定是否真正执行。

小结

openclaw uninstall 是一个设计保守、可预测的卸载工具:范围可独立选择、默认交互确认、支持 --dry-run 预演、非交互模式强制显式参数,并且在源码层面内置了「先停服务再注销」「卸载后断言」「拒绝删除根目录/主目录」三重安全护栏。只要遵循「先 openclaw backup create、再 --dry-run 预览、最后执行」的顺序,即可在保留 CLI 的前提下干净地移除 Gateway 网关服务与本地数据。

登录后查看全文
openclaw-zero-token