OpenClaw-cn `reset` 命令完全指南：安全重置本地配置与状态，保留 CLI 安装

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音

导读

clawdbot reset（中文社区版 OpenClaw-cn 亦提供openclaw-cn reset）是一条用于重置本地配置与运行时状态、但保留 CLI 本体安装的维护命令，适合在网关异常、配置损坏、需要清除凭据与会话，或希望彻底"回到出厂状态"重新引导时使用。读完本文，你将掌握 reset 的三种重置范围（config/config+creds+sessions/full）、交互式与全自动非交互式用法、--dry-run预演机制，以及命令底层对路径安全、网关服务停止和旧版目录兼容的具体实现原理。

何时需要执行 reset

reset面向"想清空本地状态但继续使用 CLI"的场景，与uninstall（卸载网关服务与数据、进一步移除 CLI）形成两级维护手段。典型使用场景包括：

• 配置损坏或想重新开始：openclaw.json中的网关、渠道或模型配置已不可恢复，希望删掉后通过onboard重新初始化；
• 凭据失效或泄漏：OAuth 令牌（oauth.json）需要清除，强制重新授权；
• 会话数据清理：各 Agent 的会话记录占用了本地磁盘，需要删除以获得干净的上下文；
• 迁移前清理：从旧版本（.clawdbot/.moltbot/.moldbot）目录结构向新目录迁移之前，清空遗留数据。

与原文档一致，reset 的核心承诺是只清数据、不动 CLI：重置完成后，CLI 可执行文件、npm 包或安装目录都不会被移除，你仍然可以立即运行onboard重新配置。

基础用法与命令参数

原文档给出的三行命令即覆盖了 reset 的核心用法：

clawdbot reset clawdbot reset --dry-run clawdbot reset --scope config+creds+sessions --yes --non-interactive

第一行以交互式向导运行；第二行只打印将要执行的操作而不真正删除；第三行则跳过一切提示，在脚本/CI 中全自动执行。

在 src/cli/program/register.maintenance.ts 中，reset子命令被注册在维护命令组下，与doctor、dashboard、uninstall并列，完整参数如下：

从 src/commands/reset.ts 可以看到，非交互模式有两条硬性校验：缺少--yes时直接报错Non-interactive mode requires --yes.并以退出码 1 结束；缺少--scope时报错Non-interactive mode requires --scope.。这是为了杜绝脚本环境中的"静默误删"，任何自动化调用都必须显式声明范围并确认。

三种重置范围（scope）的含义

ResetScope在 src/commands/reset.ts 中被定义为"config" | "config+creds+sessions" | "full"三种取值，删除对象逐级扩大：

1.config：仅配置

只删除当前生效的配置文件（默认~/.openclaw/openclaw.json），其余一切保留。执行后立即返回，不再提示后续步骤。适合只想丢弃配置、保留会话与凭据的场景。

2.config+creds+sessions：配置 + 凭据 + 会话（推荐默认）

依次删除：

1. 配置文件（openclaw.json及其旧名clawdbot.json/moltbot.json/moldbot.json中的当前生效者）；
2. OAuth 凭据目录（默认~/.openclaw/credentials，内含oauth.json）；
3. 所有 Agent 的会话目录——listAgentSessionDirs 会扫描状态目录下的agents/*/sessions子目录并逐一删除。

该范围保留工作区（workspace）目录与认证档案（auth profiles），删除后命令会提示下一步：openclaw-cn onboard --install-daemon。这是交互式向导的默认选择，也是绝大多数"重新来过"场景的最优解。

3.full：完整重置

删除最彻底，包括：

1. 整个状态目录（默认~/.openclaw，含会话、日志、缓存）；
2. 若配置文件不在状态目录内（例如通过OPENCLAW_CONFIG_PATH指向了别处），则额外删除该配置文件；
3. 若凭据目录不在状态目录内（例如通过OPENCLAW_OAUTH_DIR自定义），则额外删除凭据目录；
4. 所有工作区目录——collectWorkspaceDirs 会收集agents.defaults.workspace、每个agents.list条目的workspace，若两者皆未配置则回退到默认 Agent 工作区目录。

full之后同样提示执行openclaw-cn onboard --install-daemon重新引导。

值得注意的细节是：full范围通过 isPathWithin 判断配置与凭据是否已包含在状态目录内，避免重复删除；而config+creds+sessions范围则不做此判断，始终显式删除这三类对象，因此它比full更精准（不碰工作区），但比config更彻底（清凭据与会话）。

交互式流程与脚本化（非交互式）流程

交互式（默认）

未加--non-interactive时，reset 分两步引导：

1. 范围选择器：若未通过--scope指定，使用 @clack/prompts）；按Esc/Ctrl+C取消时打印Reset cancelled.并以退出码 0 正常结束；
2. 确认提示：删除前再次用确认组件询问Proceed with <scope> reset?，取消同样安全退出（见 src/commands/reset.ts）。

非交互式（脚本/CI）

clawdbot reset --scope full --yes --non-interactive

三个要素缺一不可：显式--scope、--yes、--non-interactive。这种写法确保无人值守环境下不会出现"卡在提示"或"未经确认即删除"两种极端。原文档中的--scope config+creds+sessions --yes --non-interactive即为此类标准形态。

干跑模式（--dry-run）

--dry-run适用于任何范围。删除动作在 removePath 中统一处理：干跑时只打印[dry-run] remove <路径>；真实执行时调用fs.rm(target, { recursive: true, force: true })并打印Removed <路径>。干跑模式下连"停止网关服务"这一前置动作也只会打印[dry-run] stop gateway service（见 src/commands/reset.ts），因此你可以放心先预演一遍完整删除清单，再决定是否真正执行。

底层实现原理：路径解析与安全防护

目标路径如何确定

reset 要删除的路径全部来自 src/config/paths.ts 的解析逻辑，并支持环境变量覆盖：

• 状态目录：默认~/.openclaw（新目录），若不存在则回退探测旧目录~/.clawdbot、~/.moltbot、~/.moldbot；可用OPENCLAW_STATE_DIR（旧名CLAWDBOT_STATE_DIR）覆盖（resolveStateDir）；
• 配置文件：默认$STATE_DIR/openclaw.json，兼容旧名clawdbot.json/moltbot.json/moldbot.json，可用OPENCLAW_CONFIG_PATH覆盖（resolveConfigPath）；
• 凭据目录：默认$STATE_DIR/credentials，可用OPENCLAW_OAUTH_DIR覆盖（resolveOAuthDir）。

这套解析同时照顾了中文社区版与上游旧版的目录命名，是"重置总能找到正确目标"的根基。

拒绝删除危险路径

removePath 内置了 isUnsafeRemovalTarget 防护：当目标路径是文件系统根目录（如/）或用户主目录时，命令会拒绝执行并打印Refusing to remove unsafe path: <路径>。结合环境变量可能把状态目录指向任意位置，这道防线防止了极端误配下"把整个家目录删掉"的灾难。

删除前自动停止网关服务

当范围不是config（即会删除状态/凭据）时，reset 会先停止正在运行的网关服务（stopGatewayIfRunning）：

1. 先通过isLoaded()探测服务是否已加载，避免对未运行的服务做无谓操作；
2. 已加载则调用stop()停止。

网关服务的实现是平台自适应的（见 src/daemon/service.ts）：macOS 使用 LaunchAgent，Linux 使用 systemd，Windows 使用计划任务（Scheduled Task）。另外，当环境变量OPENCLAW_NIX_MODE=1（Nix 模式）时，网关服务由外部管理，reset 会跳过停止网关的步骤（见 src/commands/reset.ts）。先停服务再删文件，是为了避免正在运行的网关进程继续向已被删除的会话/凭据文件写入，防止"边删边写"造成数据残留或进程异常。

重置后的下一步：重新引导

无论是config+creds+sessions还是full，reset 完成后都会提示执行：

openclaw-cn onboard --install-daemon

onboard命令注册于 src/cli/program/register.onboard.ts，其中--install-daemon（以及相反的--no-install-daemon）用于决定是否顺带安装网关系统服务（src/cli/program/register.onboard.ts）。也就是说，reset 清空的是"历史状态"，而 onboard 负责"从零重建"——重新生成配置文件、完成设备配对/认证，并按需把网关安装回系统服务。这条"reset → onboard"的组合拳，正是把一台状态混乱的 OpenClaw-cn 恢复为可用状态的标准恢复路径。

与 uninstall 的边界：reset 与 uninstall 的取舍

reset 常与uninstall混淆，二者在 src/cli/program/register.maintenance.ts 中同组注册，但职责分明：

• reset：只清配置/状态/凭据/会话/工作区，CLI 本体与可执行文件原样保留，重置后可立即onboard重建；
• uninstall：通过--service、--state、--workspace、--app、--all分别卸载网关服务、删除状态与配置、删除工作区目录、删除 macOS 应用，并可组合出"完全移除"，同样支持--yes、--non-interactive、--dry-run。

一句话总结：想继续用 CLI 就选reset，想彻底离开就选uninstall。二者都内置干跑模式与安全路径防护，可在执行前完整预演，适合在生产或长期运行的设备上放心维护本地数据。

小结

clawdbot reset/openclaw-cn reset是 OpenClaw-cn 维护命令组中最常用的"软重置"工具：三种 scope 覆盖从"只清配置"到"连工作区一起清空"的粒度需求；--dry-run、--yes、--non-interactive组合让它在交互终端和无人值守脚本中同样安全；底层路径解析兼容新旧目录与环境变量覆盖，配合"拒绝删除根目录/主目录"的防线与删除前自动停止网关服务的流程，保证了操作的可预测性。掌握reset与onboard --install-daemon的配合，你就能在任何时候把本地实例干净、可控地恢复到初始可用状态。

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音