`openclaw uninstall` 完全卸载指南:移除 Gateway 网关服务与本地数据(CLI 保留)
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):
- 多选范围:提示
Uninstall which components?,可选 Gateway service(launchd / systemd / schtasks)、State + config(~/.openclaw)、Workspace(agent files)、macOS app; - 二次确认:显示
Proceed with uninstall?确认提示,选择取消则打印Uninstall cancelled.并正常退出(退出码 0); - 依次执行:按 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)遵循「先停服务、再注销、最后校验」的流程:
- 检查 Nix 模式:若检测到 Nix 模式(
isNixMode),服务卸载会被直接禁用并报错; - 通过
service.isLoaded()判断服务当前是否已加载/注册; - 已加载则先
service.stop()停止服务; - 再调用
service.uninstall()移除服务注册; - 返回成功标志。
更深层的保障在 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 网关服务与本地数据。