1. 为什么升级 OpenClaw 后总有人卡在 gateway 起不来OpenClaw 是一个本地优先的 AI Agent 运行框架你可以把它理解成一个「常驻在后台的智能体管家」它通过 gateway 服务对外提供 HTTP/WebSocket 接口通过 CLI 提供openclaw系列命令再配合各种模型通道完成对话、编码、工具调用。适合谁适合已经在本地跑 Agent、想用统一 Key 通道管理多家模型、又不想每次手动改配置的开发者。它的版本迭代节奏很快尤其是跨大版本时插件 API、gateway 绑定策略、控制台鉴权方式都可能变。我见过太多人执行完npm install -g openclawlatest就以为完事了结果浏览器打开控制台一片空白或者 CLI 能跑但 gateway 端口不通。问题基本都出在三个环节更新前没停 gateway 导致文件占用、更新后没跑openclaw doctor自检、以及 gateway 的 bind 与鉴权配置沿用了旧版默认值。这篇就按「npm 升级 → gateway 重启 → doctor 自检 → 用 TaoToken 统一通道验证模型调用」这条完整链路走一遍。每一步都给可复制的命令和预期输出你照着敲就行。核心检索词先摆出来OpenClaw 版本升级、openclaw update 命令、npm 全局更新、gateway 服务重启、openclaw doctor 自检这几个词贯穿全文。先说清楚一个前提升级不是目的升级后模型还能正常调用才是目的。所以最后我会用 TaoToken 的 API 通道做一次端到端验证——它的 Base URL 是https://taotoken.net/api一个 Key 就能覆盖多家模型正好用来确认升级后 gateway 的模型转发链路没断。2. 升级前的准备备份配置与确认安装方式动手之前先做两件事能省掉后面 80% 的麻烦。第一件是备份配置目录。OpenClaw 的所有配置、会话、插件状态默认都在~/.openclaw下升级出问题直接回滚这个目录就行cp -r ~/.openclaw ~/.openclaw.backup-$(date %Y%m%d)执行完你会看到类似.openclaw.backup-20250512的文件夹。别嫌这一步啰嗦跨大版本时插件 API 重构是常事回滚比重装快得多。第二件是确认你的安装方式因为不同方式的更新命令不一样。用下面这条查which openclaw npm ls -g --depth0 | grep openclaw如果输出里有openclawx.y.z说明是 npm 全局安装走本文的 npm 升级路线。如果which openclaw指向的是某个源码目录下的bin那你是源码安装得用git pull那套。国内还有汉化增强版包名是qingchencloud/openclaw-zh更新命令是npm update -g qingchencloud/openclaw-zh别和官方包混用。确认完安装方式先停掉 gateway。这一步很多人跳过结果 npm 覆盖文件时被占用装完版本号还是旧的openclaw gateway stop预期输出是Gateway stopped或类似提示。如果提示服务本来就没运行也正常继续往下走。注意如果你在用 systemd 或 pm2 托管 gateway先停托管服务再执行 npm 更新否则进程会被自动拉起同样造成文件占用。3. 可复制的升级命令序列openclaw update 与 npm 两条路升级有两条路选一条即可不要混着来。路线 A内置 update 命令推荐OpenClaw 自带更新器会自动处理依赖和迁移openclaw update --channel stable想尝鲜可以换--channel beta或--channel dev追 GitHub main 分支用openclaw update --tag main。稳定环境就用 stable别折腾。路线 Bnpm 手动更新如果你习惯自己控制版本或者内置更新器报错直接走 npmnpm install -g openclawlatest要装指定版本就替换成openclaw2026.3.13-1这种格式。装完确认版本openclaw --version两条路走完都要重启 gatewayopenclaw gateway start接下来是本文最关键的一步——gateway 配置检查。新版安全策略收紧后旧配置经常导致控制台打不开。先看当前绑定模式openclaw config get gateway.bind如果返回localhost而你需要局域网访问改成 lanopenclaw config set gateway.bind lan如果控制台提示鉴权失败或 HTTP 被拒补上这条openclaw config set gateway.controlUi.allowInsecureAuth true改完重启生效openclaw gateway restart这里给你一份 gateway 相关的配置片段参考路径是~/.openclaw/config.json部分版本是config.toml以openclaw config path输出为准。JSON 格式如下{ gateway: { bind: lan, port: 18789, controlUi: { allowInsecureAuth: true } }, models: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: claude-sonnet-4-5 } }三件套对齐Base URL 填https://taotoken.net/apiKey 填你在 TaoToken 控制台生成的密钥Model ID 填你要用的模型标识。这三项缺一不可后面验证环节就靠它。4. 验证升级结果openclaw doctor 自检与模型调用连通性升级完别急着用先跑自检openclaw doctordoctor 会检查配置兼容性、端口占用、插件版本、模型通道可达性。典型输出会分几块Config段告诉你配置文件是否可解析Gateway段报告服务状态和端口Plugins段列出不兼容的插件Models段测试模型端点连通性。看到All checks passed就稳了。如果有WARN多数是插件版本落后按提示升级对应插件即可如果是ERROR且指向模型通道八成是 Key 或 Base URL 写错了回到上一节核对三件套。doctor 通过后做一次真实的模型调用验证。最直接的方式是用 CLI 发一条测试请求openclaw chat --message 回复 ok 两个字母即可如果 gateway 的模型通道配置正确你会看到模型返回的内容。这一步能跑通说明升级没有破坏模型转发链路。想更直观地确认通道状态可以打开 TaoToken 的模型对话页面手动测一条https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat在页面里选同一个 Model ID发一条消息对比 CLI 和网页的返回是否一致。两边都通说明你的 gateway 配置和 TaoToken 通道完全对齐。如果你还没生成 Key去控制台建一个https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleKey 管理页在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys生成后复制填回上面 config 的apiKey字段重启 gateway 再跑一次 doctor。5. 升级后常见报错排查401、local proxy failed 与 OAuth 失效这一节按真实报错对照着排。报错一401 Unauthorizeddoctor 的 Models 段报 401或者openclaw chat返回鉴权失败。原因通常是 Key 失效、Key 前后有空格、或者 Base URL 写成了带路径的完整地址。检查 config 里baseUrl必须是https://taotoken.net/api不要多加/v1之类的后缀。Key 重新从控制台复制一次注意别把换行符带进去。报错二local proxy failed / connection refusedgateway 起来了但 CLI 连不上多半是 bind 和 port 不匹配。先确认服务在跑openclaw gateway status再看端口监听lsof -i :18789如果端口没监听说明 gateway 启动失败去看日志openclaw gateway logs --tail 50日志里如果有bind address already in use换个端口或杀掉占用进程。报错三reading choices 相关解析错误模型返回体解析失败报reading choices之类的字段错误。这通常是 Model ID 填错或者通道返回了非 OpenAI 兼容格式。核对 config 里的modelId是否和 TaoToken 支持的模型标识一致别用别名。报错四OAuth 登录态失效升级后控制台要求重新登录或者旧 token 不认。这是新版鉴权策略变更导致的清掉本地凭据重新走一遍openclaw auth logout openclaw auth login如果你在用 Claude Code 或 Cline 这类工具接 OpenClaw 的 gateway升级后它们的 MCP 配置也要同步更新。以 Cline 的 MCP 配置为例三件套同样要对齐{ mcpServers: { openclaw: { command: openclaw, args: [mcp, serve], env: { OPENCLAW_BASE_URL: https://taotoken.net/api, OPENCLAW_API_KEY: sk-你的TaoToken密钥, OPENCLAW_MODEL_ID: claude-sonnet-4-5 } } } }Codex 用户如果走auth.json同样把 Base URL、Key、Model ID 三项写全缺一项就会在调用时报通道不可达。6. 升级完成后如何用 TaoToken 统一通道长期跑模型版本升级只是起点真正省心的是把模型通道固定下来。OpenClaw 支持 OpenAI 兼容协议TaoToken 的 API 端点正好是这个协议所以配置一次就能长期用。长期编码或跑 Agent 任务的话建议用 Coding Plan 把额度固定下来避免每次调用都手动确认https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan接入文档在这里遇到协议细节可以对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用 Claude Code 做主力开发Anthropic 兼容通道的说明在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code最后给一个我自己的习惯每次升级完把openclaw doctor的输出存一份到备份目录旁边命名带上版本号。下次升级出问题时两份 doctor 输出一对比哪个环节变了立刻就能定位。升级这件事命令本身不难难的是升级后确认每一环都还通——doctor 加一次真实模型调用两分钟就能确认别省。