1. openclaw update 之后版本还是旧的？先分清你装的是哪种
很多人第一次遇到 openclaw update 的问题，场景都差不多：终端里敲完openclaw update，看着它跑完一堆输出，心里以为搞定了，结果openclaw --version一看，还是老版本。或者更糟，更新完 gateway 起不来，doctor 一堆红字，整个人卡在那里不知道从哪下手。
这个问题的根源，往往不是 update 命令本身坏了，而是你没搞清楚自己这套 OpenClaw 到底是 npm 全局包安装，还是 git 源码检出。这两种安装方式，更新路径完全不同，混着用就会出各种版本不一致的怪现象。
我先把结论摆出来：openclaw update 会自动检测安装类型，但检测逻辑依赖~/.openclaw下的状态文件。如果你之前手动npm i -g装过，又用 installer 装过一次，状态就可能打架。这时候最靠谱的做法，是先用openclaw update status --json看清楚它认为你是什么安装类型，再决定走 npm 还是 git 这条路。
这篇内容适合三类人：一是刚接触 OpenClaw、被 update 报错卡住的新手；二是想把 endpoint 和鉴权统一到 TaoToken 通道、避免每个工具各配一套 Key 的开发者；三是长期跑 gateway 服务、需要稳定更新流程的运维向用户。核心检索词就是 openclaw update、npm 全局包、git 拉取、doctor 自检这四件事，我会一条条拆开讲，每条都给能直接复制的命令。
先说清楚 OpenClaw 是什么：它是一个带 CLI 和 gateway 服务的智能体运行框架，你可以把它理解成一个「本地大脑 + 网关」的组合，CLI 负责命令交互，gateway 负责常驻服务。update 要同时照顾这两部分，所以它比单纯npm update复杂。适合谁？适合需要长期跑 Agent、又希望版本可控的人。不适合只想临时试一下、装完就删的人，那种场景直接重装更省事。
下面进入正题，从三条排查路径讲起，最后把配置统一到 TaoToken 通道，并用一次完整 update 验证。
2. TaoToken 前置准备：统一 Key 与 API 通道
在动 update 之前，我建议你先把 API 通道这件事理顺。原因很简单：OpenClaw 更新后，配置文件结构偶尔会变，如果你每个模型、每个工具都单独填 endpoint 和 Key，更新一次就要重配一遍，非常痛苦。把通道统一到 TaoToken，后面无论怎么更新，只要改一处就行。
TaoToken 在这里扮演的角色，是一个统一的 API 接入层。你拿到一个 Key，配一个 Base URL，就能在 OpenClaw 里调用多种模型，不用为每个模型单独申请账号。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 这个地址不带 UTM 参数，配置时直接写这个。
你需要准备三样东西，我称之为「三件套」：Base URL、API Key、Model ID。这三样在 OpenClaw 的配置里会反复出现，尤其是 auth.json 和 openclaw.json 这两个文件。
Base URL 填https://taotoken.net/api。API Key 在控制台创建，入口是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建后复制出来，注意别泄露。Model ID 根据你要用的模型填，比如你想用某个编码模型，就填对应的模型标识，具体可以在模型对话页确认，入口是 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。
这里有个坑要提前说：OpenClaw 的 auth.json 里，Key 的字段名和 openclaw.json 里的 endpoint 字段名，不同版本可能不一样。更新后如果 doctor 报鉴权失败，第一件事就是打开这两个文件对照字段名，别想当然。
为什么强调「前置」？因为 update 过程中，如果 gateway 正在跑，它会用旧配置启动新进程，配置没理顺的话，更新完直接鉴权失败，你会以为是 update 把东西搞坏了，其实是配置没跟上。所以顺序是：先确认三件套，再动 update。
如果你还没创建 Key，现在去控制台建一个，顺手把 Base URL 和 Model ID 记在便签上。接下来所有配置片段，都围绕这三样展开。这一步花五分钟，能省掉后面半小时的排障。
3. 可复制配置：npm 更新命令、git 分支切换与 settings 片段
这一节是全文最实操的部分，我按 npm 路径、git 路径、配置文件三块来讲，每块都给能直接复制的命令和片段。
先说 npm 全局包路径。如果你确认自己是 npm 安装，最稳的更新方式是：
npm i -g openclaw@latest但更推荐用 OpenClaw 自带的 update，因为它能协调 gateway 服务：
openclaw update想预览不实际执行，加--dry-run：
openclaw update --dry-run想要结构化结果，加--json：
openclaw update --json注意，openclaw update不接受--verbose，这是很多人踩的坑。想看诊断信息，用--dry-run或openclaw update status --json。切换通道用--channel：
openclaw update --channel beta openclaw update --channel dev openclaw update --tag main--channel dev会确保走 git 检出，stable和beta走包安装。如果你 npm 装完 update 失败，可以用 installer 恢复：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm想锁定版本：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>再说 git 路径。如果你是源码检出，更新流程是：
git fetch origin git checkout main git pull pnpm install && pnpm build openclaw gateway restart想切到某个历史提交：
git fetch origin git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)" pnpm install && pnpm build openclaw gateway restart回到最新：git checkout main && git pull。如果遇到 pnpm/corepack bootstrap 报错，手动装 pnpm 再重跑。
最后是配置文件。OpenClaw 的配置主要在~/.openclaw/openclaw.json和~/.openclaw/auth.json。把 endpoint 和 Key 统一到 TaoToken，openclaw.json 里大致这样写：
{ "update": { "channel": "stable", "auto": { "enabled": false, "stableDelayHours": 6, "stableJitterHours": 12, "betaCheckIntervalHours": 1 } }, "model": { "baseUrl": "https://taotoken.net/api", "modelId": "your-model-id" } }auth.json 里放 Key：
{ "apiKey": "sk-your-taotoken-key" }如果你用的是 Codex 风格的 auth.json，字段名可能是OPENAI_API_KEY或类似，具体以你版本为准。Cline MCP 或 CC Switch 场景下，同样把 Base URL 填https://taotoken.net/api，Key 填 TaoToken 的 Key，Model ID 填对应模型。这三件套在哪个工具里都是同一套，别每个工具填不一样的。
配置改完，别急着 update，先openclaw doctor看一眼，确认配置能被正确读取。这一步能提前暴露字段名写错的问题。
4. 验证请求：一次完整 update 与成功结果解读
配置理顺后，跑一次完整 update 验证。我建议按这个顺序来，每一步都有明确的成功标志。
第一步，看当前状态：
openclaw update status --json输出里会告诉你当前 channel、安装类型、可用版本。重点看installType字段，是npm还是git，这决定你后面走哪条路。
第二步，预览更新：
openclaw update --dry-run它会列出计划执行的动作，比如「fetch latest」「run doctor」「restart gateway」。如果这里就报错，说明状态文件有问题，先解决再继续。
第三步，正式更新：
openclaw update成功的话，你会看到它依次完成包替换、doctor 自检、gateway 重启。注意 npm 路径下，它会先把目标版本装到临时 prefix，验证 dist 清单，再替换到全局 prefix，避免旧文件残留。如果安装命令失败，它会用--omit=optional重试一次。
第四步，跑 doctor：
openclaw doctordoctor 会迁移配置、审计 DM 策略、检查 gateway 健康。输出里如果有OK或passed，说明没问题。看到WARN要读清楚，看到ERROR必须解决。
第五步，重启 gateway：
openclaw gateway restart第六步，验证健康：
openclaw health返回健康状态就说明整条链路通了。
怎么确认 TaoToken 配置生效？更新后发一个测试请求，比如用 CLI 触发一次模型调用，看返回是否正常。如果返回鉴权错误，回到 auth.json 检查 Key；如果返回 endpoint 错误，检查 openclaw.json 里的 baseUrl 是不是https://taotoken.net/api。成功的话，你会看到模型正常返回内容，这就证明三件套配对了。
我实测下来，npm 路径最容易出问题的是 gateway 没重启，旧进程还在用被替换的包文件，导致行为诡异。所以 update 完一定手动openclaw gateway restart一次，别偷懒。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
这一节对照真实报错讲，每个都给排查方向。
401 Unauthorized：最常见。原因通常是 auth.json 里的 Key 没更新，或者字段名写错。排查步骤：打开~/.openclaw/auth.json，确认 Key 是 TaoToken 控制台创建的那个，字段名和当前版本要求一致。如果用的是 Codex 风格，确认是OPENAI_API_KEY还是apiKey。改完跑openclaw doctor再试。
local proxy failed：这个报错通常和网络配置有关。先确认 Base URL 写的是https://taotoken.net/api，没有多余斜杠或路径。然后检查 gateway 是否正常启动，openclaw gateway restart一次。如果还报，看 doctor 输出里有没有端口冲突。
reading choices 报错：这通常是模型返回格式解析失败，根源可能是 Model ID 填错，或者 endpoint 指向了不兼容的接口。确认 Model ID 和你在模型对话页看到的一致，Base URL 用 TaoToken 的 API 地址。如果换了模型还报，检查 openclaw.json 里 model 段的结构是否符合当前版本。
OAuth 相关报错：如果你之前用 OAuth 方式登录过某个模型，更新后 OAuth token 可能失效。排查方向是清掉旧的 OAuth 缓存，改用 API Key 方式。在 auth.json 里确保用的是 Key 而不是 OAuth token。CC Switch 或 Cline MCP 场景下，同样优先用 Key 方式，避免 OAuth 过期问题。
pnpm/corepack bootstrap error：git 路径常见。手动装 pnpm：npm i -g pnpm，然后重跑 update。或者重新启用 corepack。
版本不一致：update 完openclaw --version还是旧的。原因可能是 PATH 里有多个 openclaw，或者 npm 全局 prefix 和实际执行的不是同一个。用which openclaw看路径，用npm prefix -g看全局 prefix，两者要对上。对不上就调整 PATH 或重装。
排查通用原则：先openclaw doctor，再openclaw update status --json，两个输出对照看，大部分问题能定位。如果卡住，去文档页查，入口是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有接入和排障说明。
6. 把通道固定下来：长期编码与 Agent 场景的配置建议
排障讲完，说点长期的。如果你打算长期跑 OpenClaw 做编码或 Agent 任务，建议把通道固定成一套，别每次更新都重配。
具体做法：openclaw.json 里把update.auto.enabled设为 false，手动控制更新时机，避免自动更新在你跑任务时重启 gateway。然后把 model 段的 baseUrl 固定为https://taotoken.net/api，modelId 固定成你常用的那个。auth.json 里的 Key 单独管理，更新前备份一份。
如果你用 Coding Plan 跑长期编码任务，入口是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，可以把 Key 和通道统一到那里管理。Claude Code 或 Anthropic 风格接入的场景，入口是 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode-anthropic&utm_campaign=rewrite ，同样用 Base URL + Key + Model ID 三件套。
API Keys 管理入口是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，建议定期轮换 Key，更新前先确认新 Key 能用。
最后给个实用技巧：每次 update 前，先cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak，出问题能快速回滚。更新后如果 doctor 报配置迁移，别慌，按提示走，迁移一般不会丢数据。整套流程跑顺之后，openclaw update 就是一条命令的事，版本不一致和鉴权报错基本不会再找上门。
