★ FEATURED ARTICLE 1. 卸载不干净的真实场景为什么openclaw uninstall跑完了还有残留很多人第一次接触 OpenClaw 的卸载都是直接敲一句openclaw uninstall看到终端打印几行Removed ...就以为万事大吉。结果过几天重装发现旧的会话记录、通道凭据、甚至 Gateway 服务还在后台偷偷跑着端口被占用、配置被覆盖排查半天才发现是上一轮卸载没清干净。这个问题的根源在于OpenClaw 的卸载不是一个「删文件夹」动作而是一条从 CLI 入口、参数解析、交互确认、清理计划解析到分平台服务卸载、状态目录清理、工作区清理的完整链路。任何一个环节被跳过残留就会留下来。我试过在一台 macOS 上反复装删 OpenClaw最典型的现象是~/Library/LaunchAgents/ai.openclaw.gateway.plist还在系统登录时依然会尝试拉起 Gateway虽然二进制没了但 launchd 会不断报错。Linux 上则是~/.config/systemd/user/openclaw-gateway.service没删systemctl --user status一直显示 failed。Windows 更隐蔽计划任务「OpenClaw Gateway」和启动项.cmd文件分三处存放只删一处等于没删。所以这篇不是教你「怎么点卸载按钮」而是把 OpenClaw Uninstall 的源码链路拆开让你知道每个阶段到底删了什么、路径在哪、什么情况下会漏。适合两类人一是卸载后要确认环境是否干净的开发者二是需要排查「卸载不彻底导致重装异常」的运维同学。核心检索词就是 OpenClaw 卸载、Uninstall 源码分析、残留清理。下面我会按源码执行顺序把入口、范围选择、清理计划、分平台服务卸载、状态与工作区清理逐段讲清楚并给出可复制的目录检查命令和卸载后验证清单。先建立一个整体认知OpenClaw 的卸载分两个独立子系统主程序卸载openclaw uninstall负责 Gateway 服务、本地状态、工作区插件卸载openclaw plugins uninstall只管插件。两者互不覆盖所以如果你装过插件光跑主程序卸载是清不掉插件目录的。本文聚焦主程序卸载的完整链路。卸载范围被抽象成四个 scopeservice服务、state状态、workspace工作区、appmacOS 应用。这四个 scope 不是随便定的它们对应磁盘上四类完全不同的东西服务是系统级的守护进程注册项状态是运行时数据工作区是 Agent 的用户数据app 是 macOS 的应用程序包。理解这个划分后面看源码就不会乱。还有一个容易踩的坑workspace默认路径是~/.openclaw/workspace它是state目录~/.openclaw的子目录。也就是说如果你只选了state没选workspace删state的时候会把workspace一起带走。源码里对这点有明确注释但命令行交互时默认勾选的是 service state workspace 三项很多人没注意就全删了Agent 的 memory、knowledge 全没了。所以卸载前那句Recommended first: openclaw backup create不是客套话是真会丢数据。2. TaoToken 前置卸载后要重装或换模型先把接入信息备好卸载 OpenClaw 往往不是终点而是「重装 换模型后端」的起点。如果你卸载是为了清理环境后重新接入那在动手删之前最好先把接入信息准备好避免删完发现 Key 找不到了。这里说的接入信息指的是 Base URL、API Key、Model ID 这三件套。OpenClaw 这类 Agent 工具在配置模型通道时本质上就是填这三项。TaoToken 在这里的角色是一个模型接入层官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的作用是让你用统一的 Base URL 和 Key 去调用不同模型省得每个模型单独配一套凭证。对于 OpenClaw 这种需要频繁切换模型的 Agent 场景统一接入能少很多配置麻烦。具体到操作层面你需要先拿到 API Key。进入控制台的 API Keys 页面创建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建后复制保存这个 Key 就是后面配置里的api_key字段。注意 Key 只在创建时完整显示一次关掉页面就看不到了所以先存好再继续。拿到 Key 之后Base URL 统一填https://taotoken.net/api注意这个地址不带任何查询参数是纯 API 根路径。Model ID 则根据你要用的模型填比如对话类、编码类各有对应的模型标识。如果你不确定该填哪个可以先去模型对话页面试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在网页里选模型发一条消息确认能通再把这个模型 ID 抄到 OpenClaw 配置里。为什么要在卸载前做这件事因为 OpenClaw 的state目录里存着credentials/里面就是通道凭据。你一旦执行openclaw uninstall --state这些凭据就没了。如果你没提前把 Key 记下来重装后就得重新走一遍创建流程。所以顺序应该是先确认 TaoToken 的 Key 和模型 ID 可用再执行卸载最后重装时直接填回去。对于长期跑 Agent 的场景比如需要持续编码、多轮任务编排可以考虑 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它更适合高频调用、需要稳定配额的情况。如果你只是偶尔用一下按量走 API 就够了。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言的调用示例重装后配置遇到问题可以对照查。这里要强调一点TaoToken 是正规的模型接入服务不是那种来路不明的中转。你在 OpenClaw 里配置它就是把它当成一个标准的 OpenAI 兼容端点来用Base URL 填https://taotoken.net/apiKey 填你创建的Model ID 填对应模型。三件套齐了通道就通了。卸载前把这三样记在安全的地方卸载后重装直接复用能省掉大量重复配置。3. 可复制配置OpenClaw 卸载命令与清理计划解析这一节给你可以直接复制的命令和配置片段。先说卸载命令本身。OpenClaw 的卸载入口注册在src/cli/program/register.maintenance.ts命令名是uninstall支持的选项有这些openclaw uninstall \ --service \ --state \ --workspace \ --app \ --all \ --yes \ --non-interactive \ --dry-run每个选项的含义--service删 Gateway 服务--state删状态和配置--workspace删工作区目录--app删 macOS 应用--all等于四个全选--yes跳过确认--non-interactive禁用交互必须配合--yes--dry-run只打印不实际删。最稳妥的第一次操作是先 dry-run 看一遍openclaw uninstall --all --dry-run它会打印[dry-run] remove ...之类的日志告诉你将要删哪些路径。确认无误后再去掉--dry-run真删。如果你只想清服务不想动数据用openclaw uninstall --service --yes参数解析逻辑在src/commands/uninstall.ts的buildScopeSelection()。它的规则是如果用户显式指定了--all或任一具体 scope就按指定的来如果什么都没指定进入交互式多选菜单默认勾选 service、state、workspace 三项。--non-interactive且没有显式 scope 时会直接报错退出这是防止误操作。清理计划解析在src/commands/cleanup-plan.ts的resolveCleanupPlanFromDisk()它从磁盘解析出这些路径{ stateDir: ~/.openclaw, configPath: ~/.openclaw/config.json, oauthDir: ~/.openclaw/credentials, configInsideState: true, oauthInsideState: true, workspaceDirs: [~/.openclaw/workspace] }注意configInsideState和oauthInsideState这两个布尔值。如果配置和凭证都在 state 目录内删 state 时一并带走如果不在比如你自定义过路径源码会单独再删一次避免漏掉。工作区目录列表workspaceDirs默认是~/.openclaw/workspace如果你用过自定义 profile路径会变成~/.openclaw/workspace-{profile}。如果你要在重装后配置模型通道OpenClaw 的配置文件通常是~/.openclaw/config.json里面关于模型通道的部分大致长这样字段名以实际版本为准这里给的是结构参考{ channels: { default: { base_url: https://taotoken.net/api, api_key: sk-你的Key, model: 你的ModelID } } }三件套对应关系base_url填https://taotoken.net/apiapi_key填你在控制台创建的 Keymodel填模型 ID。这个 JSON 片段在卸载时会被--state删掉所以卸载前先备份一份重装后直接贴回去。对于用 Claude Code 或类似工具的场景配置可能走settings.json或环境变量。如果是环境变量方式大致是export OPENCLAW_BASE_URLhttps://taotoken.net/api export OPENCLAW_API_KEYsk-你的Key export OPENCLAW_MODEL你的ModelID环境变量方式的好处是卸载时不受影响重装后重新 export 即可。但要注意如果你把 Key 写进了 shell 的.zshrc或.bashrc卸载 OpenClaw 不会动这些文件残留的旧 Key 可能造成混淆建议卸载后顺手检查一下。还有一个容易忽略的点--dry-run模式下源码里removePath()会返回{ ok: true, skipped: true }也就是标记为跳过不会真的调fs.rm。所以 dry-run 是安全的可以放心多跑几次确认路径。真删时用的是fs.rm(resolved, { recursive: true, force: true })递归强制删除删之前有isUnsafeRemovalTarget()做安全检查防止删到根目录或用户主目录。4. 验证请求与成功结果卸载后怎么确认真的干净了卸载命令跑完不代表干净必须做验证。这一节给你分平台的检查命令和预期结果。先看 macOS。服务注册项在~/Library/LaunchAgents/ai.openclaw.gateway.plist源码里uninstallLaunchAgent()会先launchctl bootout再launchctl unload最后把 plist 移到废纸篓而不是直接删。所以验证时ls -la ~/Library/LaunchAgents/ | grep openclaw launchctl list | grep openclaw预期结果是第一条没有输出plist 已移走第二条也没有输出服务已卸载。如果launchctl list还有ai.openclaw.gateway说明 bootout 没成功需要手动launchctl bootout gui/$(id -u)/ai.openclaw.gateway。Linux 上服务单元在~/.config/systemd/user/openclaw-gateway.service源码uninstallSystemdService()执行systemctl --user disable --now然后fs.unlink删文件。验证systemctl --user status openclaw-gateway.service ls -la ~/.config/systemd/user/ | grep openclaw预期第一条显示Unit openclaw-gateway.service could not be found第二条无输出。如果 status 还能查到说明 disable 没生效手动systemctl --user disable --now openclaw-gateway.service再删文件。Windows 最复杂涉及三处计划任务、启动项、任务脚本。源码uninstallScheduledTask()依次处理。验证用schtasks /Query /TN OpenClaw Gateway dir %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\OpenClaw Gateway.cmd dir %USERPROFILE%\.openclaw\gateway.cmd预期三条都报「找不到」。如果计划任务还在手动schtasks /Delete /F /TN OpenClaw Gateway。状态目录和工作区的验证是跨平台的检查这几个路径是否还存在ls -la ~/.openclaw ls -la ~/.openclaw/workspace ls -la ~/.openclaw/credentials ls -la ~/.openclaw/config.json如果选了--state~/.openclaw整个目录应该没了如果选了--workspace~/.openclaw/workspace也没了。注意workspace是state的子目录删 state 会连带删 workspace所以如果你只想删 state 保留 workspace得单独处理但源码默认行为是 state 删除会覆盖 workspace。成功结果长这样终端最后打印CLI still installed. Remove via npm/pnpm if desired.意思是 CLI 本体还在需要你自己用包管理器删。这是设计上的选择卸载命令只管服务和数据不管 npm 全局包。所以完整清理还要加一步npm uninstall -g openclaw # 或 pnpm remove -g openclaw验证 CLI 是否还在which openclaw openclaw --version预期which无输出或指向不存在--version报 command not found。如果还在说明全局包没删干净检查 npm 全局目录npm root -g。最后给一个完整的卸载后验证清单你可以照着逐条打勾检查项命令预期macOS 服务launchctl list | grep openclaw无输出Linux 服务systemctl --user status openclaw-gatewaynot foundWindows 计划任务schtasks /Query /TN OpenClaw Gateway找不到状态目录ls ~/.openclaw不存在工作区ls ~/.openclaw/workspace不存在凭证ls ~/.openclaw/credentials不存在CLI 本体which openclaw无输出全部通过才算真正卸载干净。任何一条不通过就回到对应章节看源码逻辑定位是哪一步漏了。5. 本篇常见错排查401、local proxy failed、reading choices 等真实报错卸载和重装过程中报错往往不是卸载本身的问题而是重装后接入配置没弄对。这一节把几个高频报错和排查路径列出来。第一个是401 Unauthorized。这个几乎都是 Key 的问题。可能原因Key 复制时带了空格或换行Key 已过期或被删除Base URL 填错导致请求打到了别的端点。排查步骤先确认base_url是https://taotoken.net/api注意结尾没有多余的斜杠或路径再确认api_key是完整的没有首尾空白最后去控制台 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 看这个 Key 是否还在、是否被禁用。如果 Key 没问题用 curl 直接测一下curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:你的ModelID,messages:[{role:user,content:hi}]}如果 curl 通而 OpenClaw 不通说明是 OpenClaw 配置读取的问题检查配置文件路径和字段名。第二个是local proxy failed。这个报错通常出现在 OpenClaw 尝试通过本地代理转发请求时。可能原因本地代理端口被占用代理进程没起来配置里写了代理但代理已卸载。排查检查配置里是否有proxy相关字段如果有且你不需要删掉确认没有残留的代理进程占着端口lsof -i :端口号看一下。注意这里说的代理是 OpenClaw 自身的转发配置不是网络层面的东西排查时聚焦在 OpenClaw 配置和本地端口即可。第三个是reading choices相关报错完整形态可能是Cannot read properties of undefined (reading choices)。这是典型的响应结构不符合预期。OpenClaw 期望模型返回 OpenAI 兼容的choices数组但实际返回的不是这个结构。可能原因Base URL 填成了网页地址而不是 API 地址Model ID 填错导致端点返回错误页请求被重定向到了非 API 页面。排查确认base_url是https://taotoken.net/api不是官网首页确认 Model ID 是有效的模型标识用上面的 curl 命令看返回的 JSON 里有没有choices字段。如果 curl 返回的是 HTML 或错误 JSON说明端点不对。第四个是 OAuth 相关报错。OpenClaw 的credentials/目录存 OAuth token卸载时如果oauthInsideState为 false源码会单独删oauthDir。如果卸载不彻底旧 token 残留重装后可能报 token 无效或冲突。排查检查~/.openclaw/credentials是否还在如果在就手动删掉检查配置里是否有引用旧 token 的字段。重装后重新走一遍授权流程不要复用旧 token。第五个是服务卸载失败。macOS 上launchctl bootout可能因为权限或域不对失败报错类似Boot-out failed: 3: No such process。这通常是因为服务本来就没加载源码里isLoaded()返回 false 时会直接返回成功所以这个报错不一定影响结果。Linux 上systemctl --user disable失败可能是 D-Bus 会话问题试试systemctl --user daemon-reload再重试。Windows 上schtasks /Delete失败可能是任务名不对用schtasks /Query /FO LIST列出所有任务找准确名称。排查通用思路先看报错发生在哪个阶段。如果是卸载阶段对照第 3 节的 scope 和路径如果是重装后的接入阶段对照三件套配置。把报错原文和对应阶段对上基本能定位。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的请求示例和字段说明配置拿不准时对照看。6. 语义一致 CTA卸载后重装接入的下一步卸载干净之后如果你要重装并接入模型按这个顺序走先去控制台创建或确认 API Key地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 把 Key 存好。然后确认 Base URL 用https://taotoken.net/apiModel ID 根据你的场景选。不确定选哪个模型去模型对话页面实测一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息确认通再抄 Model ID。重装 OpenClaw 后把三件套填进配置Base URL、API Key、Model ID。如果你用的是 Claude Code 这类工具配置方式可能不同接入文档里有对应说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期跑编码或 Agent 任务的话Coding Plan 更适合稳定调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一个实操细节卸载前跑一次openclaw backup create把 state 和 workspace 备份出来。源码里在涉及 state 或 workspace 时会打印这条建议但很多人直接--yes跳过了。备份文件放在安全位置重装后如果发现少了什么还能从备份里捞回来。卸载不是目的干净地重装、稳定地接入才是。把第 4 节的验证清单跑一遍确认没有残留再开始重装能省掉后面一大堆莫名其妙的报错。
阅读完成 · 觉得有帮助？
