★ FEATURED ARTICLE 1. Docker 里升级 OpenClaw为什么配置总是「看起来没生效」先说清楚这篇要解决什么。OpenClaw 是一个跑在容器里的 AI 网关/工具链服务很多人用 Docker 部署它然后通过 Web UI 或 API 通道对外提供模型能力。问题出在升级环节你在容器里执行npm install -g openclawlatestopenclaw --version明明显示新版本号但 Web UI 打开还是旧界面API 通道报Missing config工具链配置全部失效。这不是升级失败而是升级只换了 npm 全局包没有把新版本的dist和node_modules映射到容器的工作目录/app同时旧版模型缓存和用户目录下的配置文件还在干扰。适合谁看已经用 Docker 跑着 OpenClaw、准备升级到新版本、并且需要继续用 API 通道对接外部模型服务的人。你需要对 Docker 基本命令docker run、docker exec、-v挂载有概念不需要懂 Node.js 源码。整篇围绕三个交付物展开可复制的config.toml与settings.json骨架、CC Switch 切换步骤、升级前后的连通性验证动作。我试过在 8G 内存的容器里反复重建踩过的坑基本都写在第五节了。核心检索词先摆出来Docker 升级 OpenClaw 版本、OpenClaw 配置迁移、CC Switch 切换、API 通道对接。下面从原问题拆解开始。2. 原问题与场景升级后 API 通道和工具链为什么失效2.1 升级动作只改了全局包没改工作目录OpenClaw 官方镜像的启动方式通常是node /app/dist/index.js gateway也就是说容器真正运行的是/app/dist这个目录。而npm install -g openclawlatest把新版本装到了/usr/local/lib/node_modules/openclaw/。这两个路径之间没有自动软链接所以版本号变了实际跑的代码还是旧的。这就是「Web UI 显示旧版本」的根因。2.2 配置文件按用户目录查找切用户就丢OpenClaw 启动时会在当前用户的家目录下找.openclaw目录里的配置。你用-u root进去配置在/root/.openclaw但容器默认可能以node用户启动它去找/home/node/.openclaw自然读不到于是报Missing config. Run openclaw setup or set gateway.modelocal。这个报错不是配置写错了是找错了地方。2.3 旧模型缓存会锁住旧规格/root/.openclaw/models.json里缓存了模型规格。升级后如果不清掉新版本可能仍然按旧的上下文长度比如 32k去加载而不是你期望的 128k。这个文件不删升级等于白做一半。2.4 工具链配置的依赖关系tools段里的profile、exec.host、exec.security决定了工具调用走哪条通道。升级后如果gateway.mode没设成local工具链会尝试走远程模式直接失败。所以配置迁移不是复制粘贴而是要保证gateway、tools、auth三段语义一致。3. TaoToken 前置API 通道与密钥准备OpenClaw 本身是网关它需要对接一个模型服务来提供实际推理能力。这里用 TaoToken 作为 API 通道原因是它的接口兼容主流协议配置进 OpenClaw 的config.toml后可以直接被工具链调用。你需要先拿到 API Key。进入控制台创建密钥控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite密钥管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建后复制那串sk-开头的 Key后面写进配置文件。API 基础地址用https://taotoken.net/api注意这个地址不带任何查询参数直接填进base_url字段即可。如果你只是先验证模型通不通不想动 OpenClaw 配置可以先用模型对话页面测一下模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite长期跑编码类 Agent 任务的话Coding Plan 更合适额度模型和按次调用不一样Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档在这里配置字段有疑问可以对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite前置准备就这些一个 API Key、一个基础地址、确认你要用的模型名。下面进入可复制配置。4. 可复制配置config.toml 与 settings.json 骨架4.1 config.toml 骨架OpenClaw 的模型通道配置放在config.toml。下面这份骨架可以直接改 Key 和模型名使用。注意base_url用 TaoToken 的 API 地址api_key填你刚创建的密钥。# /root/.openclaw/config.toml [provider] name taotoken base_url https://taotoken.net/api api_key sk-你的密钥替换这里 timeout 120 [model] default claude-sonnet-4-20250514 max_tokens 8192 temperature 0.7 [gateway] port 18789 mode local bind lan关键点mode必须是local否则启动时会报Missing config。bind如果只想本机访问改成loopback要让局域网其他机器访问保持lan。4.2 settings.json 骨架gateway 与 tools 部分settings.json管的是网关行为、鉴权和工具链策略。下面这份是升级后需要保证语义一致的核心段。{ gateway: { port: 18789, mode: local, bind: lan, controlUi: { enabled: true, allowedOrigins: [ http://127.0.0.1:18789, http://localhost:18789 ], dangerouslyAllowHostHeaderOriginFallback: true, allowInsecureAuth: true, dangerouslyDisableDeviceAuth: true }, auth: { mode: token, token: 替换成你自己的gateway授权token }, trustedProxies: [ 192.168.65.0/24, 172.18.0.0/16 ], tailscale: { mode: off, resetOnExit: false }, nodes: { denyCommands: [ camera.snap, camera.clip, screen.record, contacts.add, calendar.add, reminders.add, sms.send ] } }, tools: { profile: coding, exec: { host: gateway, security: full, ask: on-miss } } }allowedOrigins里把物理机 IP 加进去比如http://192.168.1.100:18789否则浏览器访问会被拦。auth.token和config.toml里的 Key 是两回事前者是网关自身的访问令牌后者是模型服务的密钥别混。4.3 容器内升级与软链接命令进入容器用 root否则权限不够docker exec -u root -it openclaw-prod /bin/sh然后在容器内执行升级四步# 1. 强制安装最新版覆盖旧二进制 npm install -g openclawlatest --force --registryhttps://registry.npmmirror.com # 2. 把新版本目录映射到工作目录 rm -rf /app/dist /app/node_modules ln -sf /usr/local/lib/node_modules/openclaw/dist /app/dist ln -sf /usr/local/lib/node_modules/openclaw/node_modules /app/node_modules # 3. 清理旧模型缓存激活新规格 rm -f /root/.openclaw/models.json # 4. 修正权限并启动 chown -R node:node /root/.openclaw exec node /app/dist/index.js gateway第 2 步是整篇最关键的动作。不做软链接openclaw --version再新也没用因为运行入口还是旧目录。4.4 一键重建容器命令如果容器已经起不来直接用下面这条重建。它把升级、软链接、启动串在一条命令里适合官方docker-setup.sh拉起的openclaw:local镜像。docker run -d \ --name openclaw-prod \ --restart unless-stopped \ -u root \ --memory8g \ -p 18789:18789 \ -p 18790:18790 \ -v /root/.openclaw:/root/.openclaw \ -v /root/.openclaw/workspace:/root/.openclaw/workspace \ -e NODE_ENVproduction \ -e NODE_OPTIONS--max-old-space-size4096 \ --entrypoint /bin/sh \ openclaw:local \ -c npm install -g openclawlatest --force --registryhttps://registry.npmmirror.com \ rm -rf /app/dist /app/node_modules \ ln -sf /usr/local/lib/node_modules/openclaw/dist /app/dist \ ln -sf /usr/local/lib/node_modules/openclaw/node_modules /app/node_modules \ exec node /app/dist/index.js gateway--memory8g和NODE_OPTIONS的 4096 是配套的内存给小了 Node 会 OOM。挂载/root/.openclaw保证配置和 workspace 不丢。5. CC Switch 切换步骤与连通性验证5.1 CC Switch 是什么、切什么CC Switch 用来在多个配置档之间切换比如你有「本地模型档」和「TaoToken 通道档」切换时不用手改文件。它的核心是替换config.toml里的provider段和settings.json里的tools段。切换步骤# 1. 查看当前档位 cc-switch list # 2. 切到 TaoToken 通道档 cc-switch use taotoken # 3. 确认写入结果 cat /root/.openclaw/config.toml | grep -A3 provider切换后必须重启 gateway 进程配置才会重新加载。在容器内执行pkill -f node /app/dist/index.js || true exec node /app/dist/index.js gateway5.2 升级前验证记录基线升级前先确认旧版本能通这样升级后出问题才知道是哪一步坏的。# 查版本 openclaw --version # 查网关健康 curl -s http://127.0.0.1:18789/health # 查模型通道 curl -s http://127.0.0.1:18789/v1/models \ -H Authorization: Bearer 你的gateway授权token把这三个输出记下来。/health返回ok、/v1/models返回模型列表说明基线正常。5.3 升级后验证三步确认第一步确认版本和运行目录一致openclaw --version ls -l /app/dist/app/dist应该是指向/usr/local/lib/node_modules/openclaw/dist的软链接不是实体目录。第二步确认配置被读到curl -s http://127.0.0.1:18789/health如果这里报Missing config回到第 2.2 节检查当前用户和.openclaw路径。第三步确认模型通道真的通curl -s http://127.0.0.1:18789/v1/chat/completions \ -H Authorization: Bearer 你的gateway授权token \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }返回里有choices字段且内容非空说明 API 通道对接成功。这一步过了升级才算真正完成。5.4 参数对照表配置项位置作用常见值base_urlconfig.toml模型服务地址https://taotoken.net/apiapi_keyconfig.toml模型服务密钥sk- 开头gateway.modesettings.json网关运行模式localgateway.bindsettings.json监听范围lan / loopbackauth.tokensettings.json网关访问令牌自定义长串tools.profilesettings.json工具链档位codingexec.securitysettings.json执行安全级别full6. 本篇常见错排查6.1 Missing config. Run openclaw setup这个报错九成是用户目录不对。容器以node用户启动时它找/home/node/.openclaw而你的配置在/root/.openclaw。解决办法有两个要么启动时加-u root要么把配置复制到 node 用户目录并改权限。mkdir -p /home/node/.openclaw cp -r /root/.openclaw/* /home/node/.openclaw/ chown -R node:node /home/node/.openclaw6.2 npm error code EEXIST/usr/local/bin/openclaw已存在npm 不敢直接覆盖。加--force即可npm install -g openclawlatest --force --registryhttps://registry.npmmirror.com6.3 Web UI 还是旧版本版本号新、界面旧就是软链接没做。回到第 4.3 节第 2 步删掉/app/dist和/app/node_modules再重建软链接。注意rm -rf删的是工作目录里的副本不是全局包删错了重装一次全局包就行。6.4 只想本机访问却暴露到局域网把settings.json里gateway.bind从lan改成loopback然后重启 gateway。改完用curl http://127.0.0.1:18789/health确认再用物理机 IP 访问应该失败说明生效。6.5 工具链调用报权限错误检查tools.exec.security和tools.exec.host。host设成gateway表示工具在网关进程内执行security设成full表示不额外限制。如果升级后这两项被重置成默认值工具调用会走远程模式然后失败。对照第 4.2 节补回去。6.6 模型上下文长度没变/root/.openclaw/models.json没删。这个文件缓存了旧规格删掉后重启新版本会重新探测并写入 128k 规格。rm -f /root/.openclaw/models.json6.7 容器内存不足被 OOM Killdocker logs openclaw-prod里看到Killed或JavaScript heap out of memory就是内存不够。把--memory提到 8gNODE_OPTIONS的--max-old-space-size设成 4096两者要匹配。7. 通道对接与后续动作升级完成后日常维护主要盯两件事一是config.toml里的base_url和api_key是否还有效二是settings.json里gateway和tools两段有没有被意外重置。建议把这两份配置纳入版本管理每次升级前先备份。如果你在排障阶段需要重新生成或核对密钥直接去 API Keys 页面API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite配置字段拿不准时对照接入文档里面有完整的字段说明和示例接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite只想快速验证模型通道是否正常用模型对话页面发一条消息最快模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你打算让 OpenClaw 长期跑编码类 Agent 任务按次调用的 Coding Plan 比通用额度更划算切换档位时记得同步更新config.toml里的模型名Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后给一个实用习惯每次升级前先跑一遍第 5.2 节的三条基线命令并把输出存成文件升级后再跑一遍对比。这样出问题时你能立刻定位是版本、配置还是通道哪一层坏了不用从头猜。
阅读完成 · 觉得有帮助？
