1. 从 2.7.5 升到 2.7.9为什么私有化部署总在配置迁移这一步翻车OpenClaw 是一个可以在本地离线运行的私有化 AI 智能体所有文件读写、键鼠模拟、浏览器控制都在你自己的机器上完成适合对数据外传比较敏感、又想让 AI 帮忙处理办公自动化的场景。2.7.5 到 2.7.9 这次升级核心变化集中在 Gateway 网关的启动顺序、依赖版本校验以及 settings 配置文件的字段结构上。很多人卡住不是因为不会装而是因为旧版本的 settings 直接覆盖过去字段对不上服务起不来。我实测下来升级失败基本集中在三类一是依赖冲突旧版 Node.js 或 Git 版本不满足 2.7.9 的最低要求二是配置迁移2.7.5 的 settings 里模型通道写的是本地直连2.7.9 要求走统一的 Key/API 通道字段名和层级都变了三是服务启动失败Gateway 一直显示离线日志里报local proxy failed或者reading choices相关错误。这篇手册按「先排环境、再迁配置、后验连通」的顺序走每一步都给可复制的命令和配置片段。如果你只是想让 OpenClaw 的模型调用稳定下来不想每次升级都重新折腾一遍 Key那 settings 改到 TaoToken 这一步是重点后面会给出完整的 JSON 片段。适合谁看已经在用 OpenClaw 2.7.5、准备升 2.7.9 的人刚接触私有化 AI 智能体、想一次装对的人以及升级后 Gateway 掉线、模型请求报错、想快速定位的人。全文不需要你懂编程配置片段复制粘贴改路径就行。2. 升级前的环境准备与 TaoToken 通道前置配置2.1 先确认 2.7.9 的依赖底线2.7.9 对运行环境的要求比 2.7.5 严。升级前先在终端里跑一遍版本检查缺什么补什么。Windows 用 PowerShellmacOS/Linux 用自带终端。node -v git --version2.7.9 要求 Node.js 不低于 18.17Git 不低于 2.30。如果 Node 版本太低去官网下 LTS 包覆盖安装装完重启终端再查一次。Git 版本低的话Windows 用winget install Git.GitmacOS 用brew install git。这里有个坑2.7.5 时代很多人用的是内置整合包里的 Node升级时如果直接覆盖安装目录旧 Node 会被保留导致 2.7.9 启动时校验失败。正确做法是先把旧安装目录整体备份一份再装新版本让新包自己带依赖。2.2 为什么要把 settings 改到 TaoTokenOpenClaw 本身是个智能体框架它自己不产出模型能力模型调用要靠外部通道。2.7.5 的 settings 里模型配置是分散的每个技能可能各写各的 endpoint。2.7.9 把这块统一成一套 Key/API 通道好处是升级时只改一处所有技能共用。TaoToken 提供的就是这样一个统一入口一个 Key 对应多个模型Base URL 固定Model ID 按需切换。对私有化部署来说这意味着你本地环境不用为每个模型单独配代理和鉴权settings 里只维护一份通道配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加任何参数。你需要提前准备三样东西后面配置里会反复用到项目说明获取位置Base URL固定为https://taotoken.net/api接入文档API Key以sk-开头的字符串API Keys 页面Model ID例如claude-sonnet-4-5等模型对话页面可查Key 的获取路径是控制台里的 API Keys 模块进去新建一个复制出来存好。Model ID 不确定的话先去模型对话页面发一条消息页面上会显示当前使用的模型标识直接抄进 settings 就行。2.3 升级前必须做的两件备份第一件备份旧安装目录。把整个 OpenClaw 文件夹复制一份命名带日期比如OpenClaw-2.7.5-backup。第二件备份旧 settings 文件。2.7.5 的 settings 通常在安装目录下的config/settings.json也可能在用户目录的.openclaw/settings.json两个位置都找一下复制到桌面。备份完再动升级出问题可以随时回退。这一步别省我见过太多人直接覆盖结果旧配置丢了新配置又不对只能重装。3. 可复制的 settings 配置片段与依赖冲突处理3.1 2.7.9 的 settings 结构长什么样2.7.9 的 settings 是标准 JSON顶层分三块gateway、model、skills。模型通道全部收在model下面provider字段指向 TaoTokenbaseUrl和apiKey是必填。下面这段可以直接复制改掉apiKey和modelId两个值就能用。{ gateway: { host: 127.0.0.1, port: 18789, autoStart: true, logLevel: info }, model: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的Key粘贴在这里, modelId: claude-sonnet-4-5, timeout: 60000, maxRetries: 2 }, skills: { fileOrganize: { enabled: true }, browserExtract: { enabled: true }, mailSend: { enabled: false } } }保存路径Windows 放在D:\OpenClaw\config\settings.jsonmacOS/Linux 放在~/OpenClaw/config/settings.json。路径里不要有中文和空格这是 2.7.9 的硬性要求和 2.7.5 一样。如果你之前用的是 TOML 格式的配置2.7.9 也兼容但字段名要对应上。TOML 版本长这样[gateway] host 127.0.0.1 port 18789 autoStart true [model] provider taotoken baseUrl https://taotoken.net/api apiKey sk-你的Key粘贴在这里 modelId claude-sonnet-4-5 timeout 60000两种格式选一种就行不要同时存在否则 2.7.9 启动时会报配置冲突。3.2 依赖冲突的典型表现与处理升级后如果启动脚本一闪而过或者日志里出现Cannot find module基本是依赖没对齐。2.7.9 内置的依赖整合包和 2.7.5 不通用正确做法是删掉旧安装目录里的node_modules和package-lock.json让新版本重新拉。cd D:\OpenClaw rmdir /s /q node_modules del package-lock.json npm installmacOS/Linux 把rmdir /s /q换成rm -rf。npm install跑完看到added xxx packages且没有ERR字样说明依赖装好了。如果卡在某个包下载不动换国内镜像再跑一次npm config set registry https://registry.npmmirror.com npm install还有一种冲突是端口占用。2.7.9 的 Gateway 默认端口还是 18789如果 2.7.5 的进程没退干净新服务起不来。查端口占用netstat -ano | findstr 18789有输出就记下 PID用taskkill /PID 那个数字 /F杀掉再重启 OpenClaw。3.3 配置迁移时最容易漏的字段从 2.7.5 迁到 2.7.9旧 settings 里的endpoint、token、modelName这三个字段名已经废弃新版本认的是baseUrl、apiKey、modelId。如果你直接把旧文件改名覆盖启动时会报unknown field或者干脆静默失败。迁移的正确姿势是打开旧 settings把里面的值抄到新结构里而不是整体替换。旧endpoint的值如果指向的是本地模型服务现在要改成 TaoToken 的https://taotoken.net/api旧token的值如果是本地生成的现在换成 TaoToken 的sk-Key旧modelName换成对应的 Model ID。改完保存先别急着启动用编辑器自带的 JSON 校验看一眼有没有语法错误比如少逗号、多逗号、引号不配对。JSON 对格式很敏感一个逗号就能让整个服务起不来。4. 启动服务并验证模型通道连通4.1 启动 Gateway 并观察日志配置改好后双击一键启动程序或者命令行进安装目录跑cd D:\OpenClaw npm run start首次启动会初始化 Gateway界面右上角会从「离线」变成「在线」这个过程 1 到 3 分钟。期间不要关窗口。日志里正常会看到这几行[gateway] loading settings from config/settings.json [gateway] model provider: taotoken [gateway] listening on 127.0.0.1:18789 [gateway] ready看到ready就说明网关起来了。如果卡在loading settings不动回去检查 settings 路径和 JSON 格式。如果卡在model provider这行报错说明 Key 或 Base URL 有问题下一节专门讲。4.2 用一条真实请求验证模型通道网关在线不代表模型通道通。最直接的验证方式是打开主界面的聊天对话输入一句简单指令比如「你好请回复当前模型名称」。如果返回正常文本说明 TaoToken 通道打通了。命令行验证也可以用 curl 直接打 TaoToken 的接口确认 Key 本身有效curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: ping}] }返回 JSON 里如果有choices字段和正常内容说明 Key 和 Model ID 都对。如果返回 401是 Key 问题返回 404是 Model ID 写错返回超时检查本机网络能不能访问taotoken.net。4.3 验证各技能组件是否连通模型通道通了之后再逐个验证技能。文件整理类技能直接在对话框输入「整理桌面图片按日期分类」看它能不能调起本地文件操作。浏览器提取类技能输入「打开浏览器搜索今天的天气」看浏览器进程能不能被拉起。每个技能第一次调用时Gateway 日志里会多一行[skill] xxx invoked。如果某个技能一直没反应去skills配置里确认它的enabled是true。2.7.9 默认只开文件整理和浏览器提取邮件发送是关的需要手动打开。全部验证通过后右上角状态、模型对话、技能调用三处都正常这次升级就算完成了。后续再启动Gateway 几秒就能就绪不用再等初始化。5. 升级后高频报错对照排查5.1 401 UnauthorizedKey 没生效报错原文通常是401 Unauthorized或者invalid api key。原因有三个Key 复制时带了空格、Key 已经失效、settings 里apiKey字段名写错。处理打开 settings确认apiKey的值是完整的sk-开头字符串前后没有引号外的空格。然后去 TaoToken 控制台的 API Keys 页面看这个 Key 是否还在、有没有被删。如果 Key 没问题用上一节的 curl 命令单独测一次curl 能通说明是 settings 写法问题curl 也不通就是 Key 本身的问题重新建一个。5.2 local proxy failed本地代理层没起来这个报错在 2.7.9 里出现频率很高原文类似local proxy failed to start或proxy connect error。它指的是 OpenClaw 内部的本地转发层没起来不是外部网络问题。处理先确认 18789 端口没被占用用netstat -ano | findstr 18789查。有占用就杀掉旧进程。然后检查 settings 里gateway.host是不是127.0.0.1如果写成了0.0.0.0或者本机实际 IP某些系统上会起不来。改回127.0.0.1再启动。如果端口没占用、host 也对还是报这个错把logLevel从info改成debug重启后看详细日志里面会指出具体是哪一步失败。5.3 reading choices 相关报错返回结构对不上报错原文可能是error reading choices或cannot read property choices of undefined。这是模型返回的 JSON 结构和 OpenClaw 预期的不一致通常发生在 Model ID 写错、或者 Base URL 指向了一个不兼容的接口。处理确认baseUrl是https://taotoken.net/api结尾没有多余的斜杠也没有加/v1之外的后缀。确认modelId是 TaoToken 支持的模型标识去模型对话页面核对。改完重启 Gateway再发一条测试消息。5.4 OAuth 或鉴权跳转类报错如果日志里出现OAuth、authorize、redirect这类词说明某个技能或通道还在走旧的鉴权流程。2.7.9 统一走 Key 鉴权不应该再出现 OAuth 跳转。处理检查 settings 里有没有残留的oauth字段有就删掉。检查skills下面每个技能的配置如果有单独的auth子字段也删掉让它们继承顶层model的通道。改完保存重启。5.5 启动后界面空白或一直转圈这种情况多半是前端资源没加载出来或者 Gateway 虽然在线但 WebSocket 没连上。处理先看 Gateway 日志有没有ready没有就是网关没起来回到 5.2 排查。有ready但界面空白清一下浏览器缓存或者换个浏览器打开http://127.0.0.1:18789。如果换浏览器还是空白把安装目录下的web文件夹删掉重新跑一次npm install让前端资源重新生成。6. 把 settings 固定到 TaoToken 后的长期用法升级完成后settings 里模型通道这一块就固定下来了。以后 OpenClaw 再出小版本你只需要替换程序文件config/settings.json不用动Key 和 Base URL 一直有效。这是把配置统一到 TaoToken 之后最省心的地方。如果你后面要加新技能比如定时任务、批量文档处理技能本身不需要单独配模型它们会自动读顶层model的通道。你只要在skills里把对应项设成enabled: true就行。需要换模型的时候只改modelId一个字段保存后重启 Gateway其他都不用碰。Model ID 的可用列表在模型对话页面能查到发一条消息看返回里用的哪个标识抄过来即可。Key 的管理在控制台 API Keys 页面建议一个环境用一个 Key方便区分和吊销。如果 Key 泄露或者要轮换新建一个把 settings 里的apiKey换掉重启服务旧 Key 在控制台删掉。接入文档里有完整的字段说明和示例遇到 settings 里某个字段不确定含义去文档里搜字段名比猜要快。模型对话页面适合快速验证某个 Model ID 能不能用不用改配置就能测。如果你打算长期跑编码类或 Agent 类任务Coding Plan 那边有更细的通道说明按需看就行。整套流程走下来升级本身不复杂复杂的是旧配置和新结构的对齐。把 settings 改到 TaoToken 统一通道之后模型这块基本不用再操心了剩下的就是按需开技能、按需换 Model ID。