openclaw reset 命令完全指南安全清理本地配置、凭据与会话状态【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawopenclaw reset是 OpenClaw CLI 提供的本地状态清理命令用于在保留 CLI 安装本身的前提下按需移除配置文件、OAuth/凭据目录、各 Agent 会话目录乃至整个状态目录与工作区。本指南基于 docs/cli/reset.md 整理并结合 src/commands/reset.ts、src/commands/cleanup-plan.ts 与 src/commands/cleanup-utils.ts 等源码展开实现细节。读完本文你将掌握三种 reset 作用域的区别与适用场景、交互式与非交互式两种执行方式、--dry-run预演技巧以及 reset 背后的 Gateway 停机、状态所有权锁定与安全路径保护机制。命令概览openclaw reset的核心定位是「重置本地配置/状态但保留 CLI 安装」。它与卸载是两条不同的路径reset 清空的是运行时产生的数据而openclaw uninstall移除的是安装本身。基本用法# 交互式提示选择要清理的作用域 openclaw reset # 只打印将要执行的操作不真正删除任何文件 openclaw reset --dry-run # 仅清理配置文件跳过所有确认 openclaw reset --scope config --yes --non-interactive # 清理配置 凭据 会话适合脚本化执行 openclaw reset --scope configcredssessions --yes --non-interactive # 完整重置状态目录 工作区 openclaw reset --scope full --yes --non-interactive从源码看命令入口resetCommand(runtime, opts)接收四个可选参数src/commands/reset.ts选项说明--scope scopeconfig、configcredssessions或full--yes跳过确认提示--non-interactive禁用所有交互提示必须与--scope和--yes同时使用--dry-run只打印将要执行的动作不实际删除任何文件非交互模式的强制约束源码在命令开头即校验参数组合src/commands/reset.ts若启用了--non-interactive但未传--yes命令直接报错Non-interactive mode requires --yes.并以退出码 1 结束若未传--scope且处于非交互模式报错Non-interactive mode requires --scope.传入的--scope不在三个合法值内报错Invalid --scope. Expected config, configcredssessions, or full.这些校验确保了无人值守环境下 reset 不会因为缺少参数而挂起等待输入也不会因非法作用域产生不确定行为。交互模式的选择菜单未传--scope时交互模式会通过selectStyled弹出作用域选择器src/commands/reset.ts默认选中configcredssessions三个选项附带提示文本Config only—— 对应openclaw.jsonConfig credentials sessions—— 保留工作区与 auth profilesFull reset—— 状态目录 工作区选择后再弹一次确认Proceed with scope reset?取消则打印Reset cancelled.并以退出码 0 结束。三种作用域Scope详解文档用一张表概括了三种作用域的清理范围Scope移除内容是否先停止 Gatewayconfig仅配置文件否configcredssessions配置文件、OAuth/凭据目录、各 Agent 会话目录是full状态目录含共享 SQLite 数据库以及工作区目录是configcredssessions和full都会在删除状态前停止正在运行的受管 Gateway 服务managed gateway service。config只动配置文件这是最轻量的一档。源码中该分支直接解析配置文件路径并调用removePath删除src/commands/reset.ts不涉及 Gateway 停机也不打印备份建议。适用于你想从零重新开始配置、但保留所有会话与凭据的场景。configcredssessions清理配置、凭据与全部会话在删除前会先记录备份建议Recommended first: openclaw backup create对应文档中的「先执行openclaw backup create获取可恢复快照」。随后依次移除src/commands/reset.ts配置文件configPathOAuth/凭据目录oauthDir每个 Agent 的会话目录。会话目录的枚举很关键listAgentSessionDirs会读取状态目录下的agents/子目录为每个 Agent 拼出stateDir/agents/agentId/sessions路径src/commands/cleanup-utils.ts。也就是说即使某个 Agent 已不在当前配置中其残留会话也会被一并清理——这是从磁盘实际枚举而非依赖配置避免遗留孤儿数据。完成后打印Next: openclaw onboard --install-daemon引导用户重新初始化安装对应文档中的说明。full完整重置这是最彻底的一档会调用removeStateAndLinkedPaths删除整个状态目录包括共享 SQLite 数据库并调用removeWorkspaceDirs删除配置中所有 Agent 的工作区目录src/commands/reset.ts。从源码实现看工作区目录的收集逻辑collectWorkspaceDirs会遍历配置中所有 Agent ID逐一解析其工作区路径若配置不可用则回退到默认 Agent 工作区目录src/commands/cleanup-utils.ts。执行前的安全机制备份建议对configcredssessions与full两种状态破坏性作用域命令都会在真正删除前打印Recommended first: openclaw backup create对应文档中的第一条注意事项「先执行openclaw backup create获取可恢复快照再删除本地状态」。测试用例也专门验证了这一行为——在 dry-run 下执行configcredssessions日志中必然包含openclaw backup createsrc/commands/reset.test.ts。备份命令的完整用法见openclaw backup。Gateway 停机检查configcredssessions与full会先停止受管的 Gateway 服务。源码中的stopGatewayIfRunningsrc/commands/reset.ts逻辑如下处于 Nix 模式时不干预——该模式下服务生命周期由 Nix 侧管理reset 不应停止并非由 OpenClaw 的 launchd/systemd 安装创建的服务通过resolveGatewayService()检查服务是否已加载isLoaded未加载直接放行已加载则调用service.stop()停止。若检查或停止过程失败命令报错并以退出码 1 结束且不会继续执行删除。测试用例明确验证了这一点当isLoaded或stop抛错时removeStateAndLinkedPaths与removeWorkspaceDirs都不会被调用用户数据得以保全src/commands/reset.test.ts。状态所有权锁防止并发删除full删除状态目录前要求独占状态所有权。即使服务管理器检查是建议性的状态锁state lock也会覆盖外部监督的 Gateway。源码中acquireStateCleanupOwnershipsrc/commands/cleanup-utils.ts通过acquireGatewayLock获取锁带 250ms 超时、25ms 轮询间隔拿不到锁或锁获取失败时会抛出明确错误Cannot remove OpenClaw state while the Gateway or another state maintenance command owns this state directory. Stop the Gateway and retry.这正是文档所述「若仍有未受管或外部监督的 Gateway 在运行reset 会拒绝执行并要求你先停止它」的底层实现。删除期间还会对共享 SQLite 数据库文件加文件排他acquireOpenClawStateDatabaseFileExclusion防止其他进程写入。删除完成后还有一道并发安全校验如果检测到锁目录重新出现或状态目录未成功移除说明清理期间有新的状态操作启动命令会报错要求停止其他 OpenClaw 命令后重试src/commands/cleanup-utils.ts。路径安全护栏removePath在删除任何路径前都会经过isUnsafeRemovalTarget校验src/commands/cleanup-utils.ts拒绝删除以下目标空路径或根路径/用户主目录本身当前工作目录或其祖先。同时trashAllowedRoots定义了允许移入废纸篓的根目录集合每个声明路径的父目录以及符号链接解析后的父目录都会被纳入src/commands/cleanup-utils.ts。删除操作优先尝试移入系统废纸篓movePathToTrash失败时回退为直接删除并记录日志最大限度降低误删风险。--dry-run删除前预演--dry-run模式下不会真正删除任何文件只打印计划执行的动作。以[dry-run]前缀标注例如[dry-run] stop gateway service [dry-run] remove ~/.openclaw/openclaw.json [dry-run] remove ~/.openclaw/oauth源码中 dry-run 走的是resolveCleanupPlanForDryRunsrc/commands/cleanup-plan.ts它通过readSourceConfigBestEffort以尽力而为的方式读取配置来构建清理计划且不会记录配置健康状态——即预演本身不产生副作用。文档建议用它在正式清理前确认将要移除的内容是养成安全习惯的关键一步。清理计划解析配置与定位目标路径无论 dry-run 还是真正删除都会先构建一份 cleanup plan确定以下路径src/commands/cleanup-plan.tsstateDir状态目录通过resolveStateDir()解析configPath配置文件路径通过resolveConfigPath()解析oauthDirOAuth/凭据目录通过resolveOAuthDir()解析configInsideState/oauthInsideState配置与凭据目录是否位于状态目录内部——这决定full清理时是否需要单独删除外部链接路径workspaceDirs全部 Agent 的工作区目录列表。值得注意的区别dry-run 使用readSourceConfigBestEffort尽力读取而真正删除前使用resolveCleanupPlanForRemovalsrc/commands/cleanup-plan.ts它会做严格校验——若配置无效或存在影响工作区发现agents.defaults.workspace、agents.entries.*.workspace的警告命令会拒绝继续并输出配置问题摘要提示修复配置后重试。这保证了删除操作永远不会在一个「看不清工作区在哪」的状态下盲目进行。与 Workspace 状态、SQLite 数据库的关系文档特别指出工作区设置状态workspace setup state与证明记录attestations是共享 SQLite 数据库中的行数据。full随状态目录一起删除它们目前不存在需要单独清理的 attestation sidecar 文件。源码印证了这一点removeWorkspaceDirs在处理每个工作区时会先prepareLegacyWorkspaceStateReset旧版工作区状态并可选prepareWorkspaceStateDeletion当前版本工作区状态行删除目录后调用deleteWorkspaceState清理对应数据库行src/commands/cleanup-utils.ts。只有removeStateRows为真即状态目录未被成功整体删除时才会执行数据库行清理——若状态目录连同 SQLite 数据库一起被移除了则无需也无法再单独删行。常见问题与最佳实践Q1如何在不删除凭据的情况下只清空配置openclaw reset --scope config --yes --non-interactiveQ2如何在脚本里全自动重置openclaw reset --scope full --yes --non-interactive--non-interactive仅当--scope与--yes同时给出时才有效三者缺一不可。Q3担心删错东西先用--dry-run预演openclaw reset --scope full --yes --non-interactive --dry-run看到完整动作清单后再真正执行。Q4reset 被拒绝执行「Gateway 仍在运行」先停止 Gateway或受管服务再重试。若为 Nix 模式reset 不会尝试停止服务需自行管理服务生命周期。Q5reset 之后怎么恢复三种作用域完成后提示的路径不同configcredssessions与full会打印Next: openclaw onboard --install-daemon引导你重新初始化安装详见openclaw onboard。若已提前用openclaw backup创建快照则可以从备份恢复。相关命令CLI 参考总览openclaw backup—— 重置前归档状态openclaw onboard—— 重置后重新配置安装openclaw uninstall—— 移除整个安装而非重置一句话总结使用时机日常想「回到出厂状态」用full只想重配不想丢会话凭据用config介于两者之间清空凭据与历史会话但保留工作区与 auth profiles 用configcredssessions任何破坏性操作前先--dry-run预演、再openclaw backup create兜底。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 19:45:51 · 阅读 1.2k openclaw reset 命令完全指南：安全清理本地配置、凭据与会话状态
openclaw reset 命令完全指南安全清理本地配置、凭据与会话状态【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawopenclaw reset是 OpenClaw CLI 提供的本地状态清理命令用于在保留 CLI 安装本身的前提下按需移除配置文件、OAuth/凭据目录、各 Agent 会话目录乃至整个状态目录与工作区。本指南基于 docs/cli/reset.md 整理并结合 src/commands/reset.ts、src/commands/cleanup-plan.ts 与 src/commands/cleanup-utils.ts 等源码展开实现细节。读完本文你将掌握三种 reset 作用域的区别与适用场景、交互式与非交互式两种执行方式、--dry-run预演技巧以及 reset 背后的 Gateway 停机、状态所有权锁定与安全路径保护机制。命令概览openclaw reset的核心定位是「重置本地配置/状态但保留 CLI 安装」。它与卸载是两条不同的路径reset 清空的是运行时产生的数据而openclaw uninstall移除的是安装本身。基本用法# 交互式提示选择要清理的作用域 openclaw reset # 只打印将要执行的操作不真正删除任何文件 openclaw reset --dry-run # 仅清理配置文件跳过所有确认 openclaw reset --scope config --yes --non-interactive # 清理配置 凭据 会话适合脚本化执行 openclaw reset --scope configcredssessions --yes --non-interactive # 完整重置状态目录 工作区 openclaw reset --scope full --yes --non-interactive从源码看命令入口resetCommand(runtime, opts)接收四个可选参数src/commands/reset.ts选项说明--scope scopeconfig、configcredssessions或full--yes跳过确认提示--non-interactive禁用所有交互提示必须与--scope和--yes同时使用--dry-run只打印将要执行的动作不实际删除任何文件非交互模式的强制约束源码在命令开头即校验参数组合src/commands/reset.ts若启用了--non-interactive但未传--yes命令直接报错Non-interactive mode requires --yes.并以退出码 1 结束若未传--scope且处于非交互模式报错Non-interactive mode requires --scope.传入的--scope不在三个合法值内报错Invalid --scope. Expected config, configcredssessions, or full.这些校验确保了无人值守环境下 reset 不会因为缺少参数而挂起等待输入也不会因非法作用域产生不确定行为。交互模式的选择菜单未传--scope时交互模式会通过selectStyled弹出作用域选择器src/commands/reset.ts默认选中configcredssessions三个选项附带提示文本Config only—— 对应openclaw.jsonConfig credentials sessions—— 保留工作区与 auth profilesFull reset—— 状态目录 工作区选择后再弹一次确认Proceed with scope reset?取消则打印Reset cancelled.并以退出码 0 结束。三种作用域Scope详解文档用一张表概括了三种作用域的清理范围Scope移除内容是否先停止 Gatewayconfig仅配置文件否configcredssessions配置文件、OAuth/凭据目录、各 Agent 会话目录是full状态目录含共享 SQLite 数据库以及工作区目录是configcredssessions和full都会在删除状态前停止正在运行的受管 Gateway 服务managed gateway service。config只动配置文件这是最轻量的一档。源码中该分支直接解析配置文件路径并调用removePath删除src/commands/reset.ts不涉及 Gateway 停机也不打印备份建议。适用于你想从零重新开始配置、但保留所有会话与凭据的场景。configcredssessions清理配置、凭据与全部会话在删除前会先记录备份建议Recommended first: openclaw backup create对应文档中的「先执行openclaw backup create获取可恢复快照」。随后依次移除src/commands/reset.ts配置文件configPathOAuth/凭据目录oauthDir每个 Agent 的会话目录。会话目录的枚举很关键listAgentSessionDirs会读取状态目录下的agents/子目录为每个 Agent 拼出stateDir/agents/agentId/sessions路径src/commands/cleanup-utils.ts。也就是说即使某个 Agent 已不在当前配置中其残留会话也会被一并清理——这是从磁盘实际枚举而非依赖配置避免遗留孤儿数据。完成后打印Next: openclaw onboard --install-daemon引导用户重新初始化安装对应文档中的说明。full完整重置这是最彻底的一档会调用removeStateAndLinkedPaths删除整个状态目录包括共享 SQLite 数据库并调用removeWorkspaceDirs删除配置中所有 Agent 的工作区目录src/commands/reset.ts。从源码实现看工作区目录的收集逻辑collectWorkspaceDirs会遍历配置中所有 Agent ID逐一解析其工作区路径若配置不可用则回退到默认 Agent 工作区目录src/commands/cleanup-utils.ts。执行前的安全机制备份建议对configcredssessions与full两种状态破坏性作用域命令都会在真正删除前打印Recommended first: openclaw backup create对应文档中的第一条注意事项「先执行openclaw backup create获取可恢复快照再删除本地状态」。测试用例也专门验证了这一行为——在 dry-run 下执行configcredssessions日志中必然包含openclaw backup createsrc/commands/reset.test.ts。备份命令的完整用法见openclaw backup。Gateway 停机检查configcredssessions与full会先停止受管的 Gateway 服务。源码中的stopGatewayIfRunningsrc/commands/reset.ts逻辑如下处于 Nix 模式时不干预——该模式下服务生命周期由 Nix 侧管理reset 不应停止并非由 OpenClaw 的 launchd/systemd 安装创建的服务通过resolveGatewayService()检查服务是否已加载isLoaded未加载直接放行已加载则调用service.stop()停止。若检查或停止过程失败命令报错并以退出码 1 结束且不会继续执行删除。测试用例明确验证了这一点当isLoaded或stop抛错时removeStateAndLinkedPaths与removeWorkspaceDirs都不会被调用用户数据得以保全src/commands/reset.test.ts。状态所有权锁防止并发删除full删除状态目录前要求独占状态所有权。即使服务管理器检查是建议性的状态锁state lock也会覆盖外部监督的 Gateway。源码中acquireStateCleanupOwnershipsrc/commands/cleanup-utils.ts通过acquireGatewayLock获取锁带 250ms 超时、25ms 轮询间隔拿不到锁或锁获取失败时会抛出明确错误Cannot remove OpenClaw state while the Gateway or another state maintenance command owns this state directory. Stop the Gateway and retry.这正是文档所述「若仍有未受管或外部监督的 Gateway 在运行reset 会拒绝执行并要求你先停止它」的底层实现。删除期间还会对共享 SQLite 数据库文件加文件排他acquireOpenClawStateDatabaseFileExclusion防止其他进程写入。删除完成后还有一道并发安全校验如果检测到锁目录重新出现或状态目录未成功移除说明清理期间有新的状态操作启动命令会报错要求停止其他 OpenClaw 命令后重试src/commands/cleanup-utils.ts。路径安全护栏removePath在删除任何路径前都会经过isUnsafeRemovalTarget校验src/commands/cleanup-utils.ts拒绝删除以下目标空路径或根路径/用户主目录本身当前工作目录或其祖先。同时trashAllowedRoots定义了允许移入废纸篓的根目录集合每个声明路径的父目录以及符号链接解析后的父目录都会被纳入src/commands/cleanup-utils.ts。删除操作优先尝试移入系统废纸篓movePathToTrash失败时回退为直接删除并记录日志最大限度降低误删风险。--dry-run删除前预演--dry-run模式下不会真正删除任何文件只打印计划执行的动作。以[dry-run]前缀标注例如[dry-run] stop gateway service [dry-run] remove ~/.openclaw/openclaw.json [dry-run] remove ~/.openclaw/oauth源码中 dry-run 走的是resolveCleanupPlanForDryRunsrc/commands/cleanup-plan.ts它通过readSourceConfigBestEffort以尽力而为的方式读取配置来构建清理计划且不会记录配置健康状态——即预演本身不产生副作用。文档建议用它在正式清理前确认将要移除的内容是养成安全习惯的关键一步。清理计划解析配置与定位目标路径无论 dry-run 还是真正删除都会先构建一份 cleanup plan确定以下路径src/commands/cleanup-plan.tsstateDir状态目录通过resolveStateDir()解析configPath配置文件路径通过resolveConfigPath()解析oauthDirOAuth/凭据目录通过resolveOAuthDir()解析configInsideState/oauthInsideState配置与凭据目录是否位于状态目录内部——这决定full清理时是否需要单独删除外部链接路径workspaceDirs全部 Agent 的工作区目录列表。值得注意的区别dry-run 使用readSourceConfigBestEffort尽力读取而真正删除前使用resolveCleanupPlanForRemovalsrc/commands/cleanup-plan.ts它会做严格校验——若配置无效或存在影响工作区发现agents.defaults.workspace、agents.entries.*.workspace的警告命令会拒绝继续并输出配置问题摘要提示修复配置后重试。这保证了删除操作永远不会在一个「看不清工作区在哪」的状态下盲目进行。与 Workspace 状态、SQLite 数据库的关系文档特别指出工作区设置状态workspace setup state与证明记录attestations是共享 SQLite 数据库中的行数据。full随状态目录一起删除它们目前不存在需要单独清理的 attestation sidecar 文件。源码印证了这一点removeWorkspaceDirs在处理每个工作区时会先prepareLegacyWorkspaceStateReset旧版工作区状态并可选prepareWorkspaceStateDeletion当前版本工作区状态行删除目录后调用deleteWorkspaceState清理对应数据库行src/commands/cleanup-utils.ts。只有removeStateRows为真即状态目录未被成功整体删除时才会执行数据库行清理——若状态目录连同 SQLite 数据库一起被移除了则无需也无法再单独删行。常见问题与最佳实践Q1如何在不删除凭据的情况下只清空配置openclaw reset --scope config --yes --non-interactiveQ2如何在脚本里全自动重置openclaw reset --scope full --yes --non-interactive--non-interactive仅当--scope与--yes同时给出时才有效三者缺一不可。Q3担心删错东西先用--dry-run预演openclaw reset --scope full --yes --non-interactive --dry-run看到完整动作清单后再真正执行。Q4reset 被拒绝执行「Gateway 仍在运行」先停止 Gateway或受管服务再重试。若为 Nix 模式reset 不会尝试停止服务需自行管理服务生命周期。Q5reset 之后怎么恢复三种作用域完成后提示的路径不同configcredssessions与full会打印Next: openclaw onboard --install-daemon引导你重新初始化安装详见openclaw onboard。若已提前用openclaw backup创建快照则可以从备份恢复。相关命令CLI 参考总览openclaw backup—— 重置前归档状态openclaw onboard—— 重置后重新配置安装openclaw uninstall—— 移除整个安装而非重置一句话总结使用时机日常想「回到出厂状态」用full只想重配不想丢会话凭据用config介于两者之间清空凭据与历史会话但保留工作区与 auth profiles 用configcredssessions任何破坏性操作前先--dry-run预演、再openclaw backup create兜底。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考