十分钟教你如何升级OpenClaw：npm与Docker两种方式配TaoToken

1. 升级前先想清楚：OpenClaw 版本升级到底在升什么

OpenClaw 是一个把本地网关、模型调用、工具链串起来的开发侧服务，很多人第一次装完就跑起来了，等到要升级时才发现：npm 全局包和 Docker 镜像两条路径的升级逻辑完全不一样，配置目录、守护进程、端口映射、环境变量注入点都不同。如果你正在搜「openclaw 升级 npm docker 区别」或者「openclaw 升级后 API 调用中断怎么办」，这篇就是按我实际踩过的流程写的。

先说结论：升级本身不复杂，复杂的是升级后调用链不能断。OpenClaw 的调用链大致是「客户端 → 本地网关(18789) → 模型 API endpoint」。升级会替换二进制或镜像，但不会自动帮你把 endpoint 迁移到新的统一 Key 通道。所以真正要做的三件事是：备份配置目录、选对升级路径、升级后把 API endpoint 指向 TaoToken 的统一入口并验证。

适合谁看：已经用 npm 全局装过 OpenClaw 的开发者；用 Docker 跑 OpenClaw 容器、挂载了~/.openclaw的人；以及升级后遇到 401、local proxy failed、reading choices 这类报错、想快速定位的人。下面按「备份 → 选路径 → 改 endpoint → 验证 → 排障」走，命令都可以直接复制。

先确认你当前版本和安装方式，这决定了后面走哪条路：

openclaw --version which openclaw npm list -g --depth=0 | grep openclaw docker ps | grep openclaw

如果which openclaw指向 npm 全局目录（比如/usr/local/bin或 nvm 目录），走 npm 路径；如果docker ps里有 openclaw 容器，走 Docker 路径。两条路都装过的人，建议只保留一条，否则升级后openclaw命令指向哪个二进制会混乱。

备份是通用动作，别省。配置目录默认在用户目录下的.openclaw：

# Linux / macOS cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d) # Windows PowerShell Copy-Item -Recurse "$env:USERPROFILE\.openclaw" "$env:USERPROFILE\.openclaw.backup-$(Get-Date -Format 'yyyyMMdd')"

备份完停服务，避免升级时文件被占用：

openclaw gateway stop

到这里准备工作结束，接下来分两条路径。

2. npm 全局升级 OpenClaw 的完整命令与回滚策略

npm 路径适合用npm install -g openclaw装的人。它的升级本质是替换全局包，配置目录不动，所以升级后配置还在，但二进制版本变了。

先看可用版本，别盲目上 latest：

npm view openclaw versions --json | python3 -c "import sys,json;v=json.load(sys.stdin);print('\n'.join(v[-20:]))"

输出会列出最近 20 个版本。选一个稳定版，比如2026.3.13-1，然后升级：

npm install -g openclaw@2026.3.13-1

想直接上最新稳定版：

npm install -g openclaw@latest

升级完重启网关并验证：

openclaw gateway restart openclaw --version openclaw doctor

doctor会检查配置、服务状态、端口占用，并尝试提示修复项。如果它报配置不兼容，先别急着--fix，把输出贴出来对照下一节的排障。

npm 路径的回滚很直接，装回上一个版本即可：

openclaw gateway stop npm install -g openclaw@2026.3.11 openclaw gateway start openclaw --version

如果问题出在配置而不是二进制，恢复备份目录：

openclaw gateway stop rm -rf ~/.openclaw cp -r ~/.openclaw.backup-20260315 ~/.openclaw openclaw gateway start

Windows 下把rm -rf换成Remove-Item -Recurse -Force，路径换成$env:USERPROFILE\.openclaw。

npm 路径的坑主要有两个：一是 nvm 切换 Node 版本后全局包丢失，openclaw命令找不到，这时要重新npm install -g；二是权限问题，Linux 下全局安装可能需要sudo，但用sudo装会导致配置目录归属 root，后续普通用户跑不起来。建议用 nvm 或配置 npm 全局目录到用户空间，别用 sudo。

升级完成后，先别急着接业务，把 endpoint 改到 TaoToken 统一 Key 通道，这一步在下一节。

3. 把 API endpoint 切到 TaoToken 统一 Key 通道的可复制配置

升级后调用中断，十有八九是 endpoint 或 Key 没跟着迁移。OpenClaw 的模型调用配置一般写在~/.openclaw/config.json或环境变量里。你要做的是把 Base URL 指向 TaoToken 的 API 入口，Key 换成统一 Key，Model ID 填你实际要用的模型。

先拿 Key：打开 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制出来。注意这个 Key 只在创建时完整显示一次，存好。

然后改配置。OpenClaw 的配置文件通常是 JSON，路径~/.openclaw/config.json。找到模型或 provider 段，改成下面这样（字段名以你实际版本为准，核心是 baseUrl、apiKey、model 三件套）：

{ "providers": { "default": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken统一Key", "model": "claude-sonnet-4-20250514", "timeout": 60000 } } }

如果你用的是环境变量注入，改成：

export OPENCLAW_BASE_URL="https://taotoken.net/api" export OPENCLAW_API_KEY="sk-你的TaoToken统一Key" export OPENCLAW_MODEL="claude-sonnet-4-20250514"

Docker 路径的人注意：环境变量要在docker run时用-e传进去，或者写进 compose 文件。挂载卷-v ~/.openclaw:/root/.openclaw保持不变，配置才会持久化。

services: openclaw: image: openclaw/openclaw:2026.3.13-1 container_name: openclaw ports: - "18789:18789" volumes: - ~/.openclaw:/root/.openclaw environment: - OPENCLAW_BASE_URL=https://taotoken.net/api - OPENCLAW_API_KEY=sk-你的TaoToken统一Key - OPENCLAW_MODEL=claude-sonnet-4-20250514 restart: unless-stopped

改完配置重启：

openclaw gateway restart

Docker 路径：

docker restart openclaw

这里有个容易忽略的点：Base URL 末尾不要多加/v1或斜杠，TaoToken 的 API 入口就是https://taotoken.net/api，路径拼接由客户端处理。多写一层会导致 404 或 reading choices 报错。

配置改完，进入验证环节。

4. 验证升级后调用不中断：从 doctor 到真实请求

验证分三层：服务层、配置层、调用层。

服务层先看网关是否起来：

openclaw gateway status curl -s http://127.0.0.1:18789/health

health返回 ok 或类似状态，说明网关活着。

配置层跑 doctor：

openclaw doctor

它会检查 endpoint 可达性、Key 格式、模型 ID 是否存在。如果 doctor 报 endpoint 不可达，先curl一下 TaoToken 的 API 入口确认网络通：

curl -s -o /dev/null -w "%{http_code}" https://taotoken.net/api

返回 200、401、404 都说明网络通，401 是没带 Key 的正常响应。返回 000 才是网络问题。

调用层发一个真实请求。OpenClaw 一般有内置的测试命令，或者你直接用 curl 打网关：

curl -s http://127.0.0.1:18789/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}] }'

如果返回带choices的 JSON，说明整条链路通了。如果返回 401，是 Key 问题；返回local proxy failed，是网关到 endpoint 的连接问题；返回reading choices相关错误，多半是响应格式不对或 endpoint 路径写错。

Docker 路径验证版本：

docker exec openclaw openclaw --version

确认容器内版本和你拉取的镜像 tag 一致。

三层都过，升级就算完成。接下来是排障。

5. 升级 OpenClaw 常见报错排查：401、local proxy failed、reading choices

这一节按真实报错对照，遇到哪个查哪个。

401 Unauthorized：Key 没生效。检查三处：配置文件里的apiKey是否被环境变量覆盖；Docker 是否用-e传了旧 Key；Key 是否复制完整（前后无空格）。用 curl 直接打 TaoToken 验证 Key：

curl -s https://taotoken.net/api/v1/models \ -H "Authorization: Bearer sk-你的Key"

返回模型列表说明 Key 有效，问题在 OpenClaw 配置读取。

local proxy failed：网关到 endpoint 的连接失败。常见原因是 Base URL 写错、端口被占、或容器内 DNS 解析不了。Docker 路径先在容器内测：

docker exec openclaw curl -s -o /dev/null -w "%{http_code}" https://taotoken.net/api

容器内返回 000，是容器网络问题；返回 200/401，是配置路径问题。另外检查18789端口有没有被别的进程占：

lsof -i :18789

reading choices 报错：客户端拿到了响应但解析不出choices字段。多半是 endpoint 返回了错误页或非 JSON。先看原始响应：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"hi"}]}'

如果这里就报错，是模型 ID 或 Key 的问题；如果这里正常但 OpenClaw 报错，是 OpenClaw 的响应解析配置问题，检查是否开了流式但客户端不支持。

OAuth 相关报错：如果你之前用 OAuth 方式登录过某个 provider，升级后 token 过期会报 OAuth 错误。切到 TaoToken 统一 Key 通道后这类问题自然消失，因为不再依赖 OAuth 刷新。确认配置里没有残留的 OAuth 字段。

版本回滚后仍报错：说明问题在配置不在版本。恢复备份目录，或把config.json里 provider 段重置为上面的三件套。

排障时记住一个顺序：先 curl endpoint，再 curl 网关，最后看 OpenClaw 日志。日志路径一般在~/.openclaw/logs/，Docker 路径用docker logs openclaw。

6. 长期跑 OpenClaw 的版本管理与 Coding Plan 接入建议

升级不是一次性动作。OpenClaw 迭代快，稳定版和测试版交替，长期跑的人需要一套版本管理习惯。

我的做法是：生产环境锁版本，不追 latest。npm 路径在package.json或安装命令里写死版本号，Docker 路径用具体 tag 而不是latest。这样回滚时不用猜上一个版本是什么。

# 锁版本安装 npm install -g openclaw@2026.3.13-1 # Docker 锁 tag docker pull openclaw/openclaw:2026.3.13-1

升级前跑一次openclaw doctor存个基线，升级后再跑一次对比。配置目录纳入版本管理（比如 git），每次改 endpoint 或 Key 都有记录。

如果你把 OpenClaw 当长期编码助手或 Agent 底座用，调用量会上去，按量计费不如包月划算。TaoToken 的 Coding Plan 适合这种场景，接入方式和上面一样，只是 Key 换成 Coding Plan 的 Key，Base URL 不变。具体入口在 https://taotoken.net/coding-plan ，配置三件套还是 Base URL + Key + Model ID。

模型选择上，日常编码用 claude-sonnet 系列够用，复杂推理再切更强的模型。切换模型只改model字段，不用动 endpoint。

最后给一个升级检查清单，照着走不会漏：

# 1. 备份 cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d) # 2. 停服务 openclaw gateway stop # 3. 升级（npm 或 docker 二选一） npm install -g openclaw@2026.3.13-1 # 4. 改 endpoint 到 TaoToken # 编辑 ~/.openclaw/config.json 的 baseUrl/apiKey/model # 5. 重启 openclaw gateway restart # 6. 验证 openclaw doctor curl -s http://127.0.0.1:18789/health

Docker 路径把第 3 步换成docker pull+docker rm+docker run，第 5 步换成docker restart openclaw。

升级这件事，真正花时间的不是敲命令，是升级后调用链的重新对齐。把 endpoint 统一到 TaoToken 之后，以后换模型、换版本都不用再动 Key，只改 Model ID 就行。这套流程我跑过几次，十分钟够用，前提是备份别省、验证别跳。