1. 为什么一周之后我决定重配 QClaw 的 APIQClaw 是 OpenClaw 生态里的桌面端封装版本中文社区习惯把这一整套东西叫「龙虾」。它能做什么简单说它把本地 AI 代理框架的安装、启动、平台绑定都包好了你下载完打开就能对话还能把微信、飞书、钉钉这些聊天工具变成控制本地 AI 的入口。适合谁适合想把 AI 深度嵌进日常工作流、又不想每次从零解释背景的开发者尤其是需要统一管理多个模型 Key 的人。我一开始用得很随意。装完 QClaw默认模型能跑就懒得动配置。后来陆续接了几个第三方模型——有公司内网部署的有自己买的 API 额度还有几个用来对比效果的——问题就来了Key 散落在不同地方有的写在对话里让 QClaw 自动写入有的我手动改了openclaw.json时间一长自己都记不清哪个 provider 对应哪个 Key。更麻烦的是每次换模型都要重新确认 baseUrl 和模型 ID 有没有写对错一个字符就是 401。真正让我下决心重配的是一次定时任务翻车。我设了个每天早上抓 AI 热点的任务结果某天开始一直报错排查半天发现是某个 provider 的 Key 过期了而那个 provider 恰好是定时任务默认调用的。Key 管理不统一故障点就藏得很深。所以这一周我做的事本质上是把 QClaw 的 API 配置重新梳理了一遍哪些配置写在config.toml哪些写在settings.json怎么用一套统一的 Key 和 API 通道把多个模型管起来怎么验证配置真的生效。这篇就把整个过程拆开讲给你一份能直接抄的骨架。先说清楚 QClaw 和 OpenClaw 的关系不然后面配置容易懵。OpenClaw 是底层的本地 AI 代理框架负责连接聊天平台、加载 Skills、调度模型。QClaw 是在它上面做的桌面应用把命令行那套藏起来了。但底层配置文件还是 OpenClaw 那一套所以你会看到~/.qclaw/目录下既有 QClaw 自己的设置也有 OpenClaw 的 provider 配置。理解这一点后面找文件就不会找错地方。我踩过的坑里最常见的就是把配置写到了错误的文件。QClaw 的界面设置和 OpenClaw 的模型 provider 配置是分开的前者管界面行为后者管模型接入。你要是把 baseUrl 写进界面设置里它不会报错但也不会生效然后你就开始怀疑人生。所以下面我会明确标出每个片段该放哪个文件。2. TaoToken 前置把 Key 和 API 通道统一起来在讲具体配置之前先解决一个前置问题为什么建议用 TaoToken 来统一 Key 和 API 通道。QClaw 支持任何兼容 OpenAI 格式的第三方模型这意味着你可以接很多家。但每接一家你就要管一个 baseUrl、一个 apiKey、一套模型 ID。接三家就是三套接五家就是五套。而且不同家的 Key 格式、额度、过期时间都不一样散着管迟早出问题。TaoToken 在这里的角色是一个统一的 API 通道。你把 Key 配一次模型 ID 用统一的命名QClaw 这边只需要认一个 baseUrl 和一个 apiKey就能调用背后多个模型。对 QClaw 这种需要频繁切换模型做对比、又要跑定时任务的场景来说配置复杂度直接降一个量级。具体怎么接TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 格式所以 QClaw 里配置 provider 的时候baseUrl 填这个就行。Key 在控制台生成模型 ID 用文档里列出的名称。这样 QClaw 的 provider 配置里只有一套凭证换模型只改模型 ID 字段不用动 baseUrl 和 Key。这里要提醒一句TaoToken 是正规的 API 聚合通道不是那种来路不明的中转。它的作用是帮你把多个模型的调用统一到一个入口省去你分别管理多家 Key 的麻烦。对于 QClaw 这种本地跑、需要长期稳定调用的场景统一通道的好处是故障排查简单——出问题先看这一个通道不用在五个 provider 之间来回猜。配之前你需要准备三样东西TaoToken 的 API Key、你要用的模型 ID、以及确认 QClaw 的配置文件路径。Key 在控制台的 API Keys 页面生成模型 ID 在文档里查。配置文件路径后面会具体说。还有一点QClaw 的模型配置支持 reasoning 开关之类的参数这些在统一通道下也能透传。也就是说你用 TaoToken 统一了 Key不代表失去对单个模型参数的细粒度控制该调的还能调。如果你还没生成 Key可以去控制台建一个。生成之后先别急着往 QClaw 里塞下面会讲怎么组织配置文件让这套 Key 在config.toml和settings.json里各就各位。3. 可复制配置config.toml 与 settings.json 骨架这一节是重点直接给可复制的配置骨架。先明确两个文件的职责别搞混。config.toml一般放在 QClaw 的工作目录下管的是 QClaw 应用层的行为比如界面、默认会话、定时任务的时区这些。settings.json或者 OpenClaw 那套openclaw.json管的是模型 provider 的接入baseUrl、apiKey、模型列表都在这里。不同版本的 QClaw 文件名可能略有差异但结构是一致的你按自己目录里的实际文件名来。先看config.toml的骨架。这个文件用 TOML 格式注意字符串要加引号布尔值是小写 true/false。# QClaw 应用层配置骨架 [app] # 默认会话模式isolated 表示定时任务隔离运行不污染主对话 default_session_mode isolated # 时区定时任务的 cron 按这个时区解释 timezone Asia/Shanghai # 界面语言 language zh-CN [model] # 默认使用的 provider 名称要和 settings.json 里的 provider key 对应 default_provider taotoken # 默认模型 ID default_model gpt-4.5 [gateway] # 本地 gateway 监听端口 port 18789 # 是否随应用启动自动拉起 gateway auto_start true [memory] # 记忆文件目录相对工作空间 memory_dir memory # 长期记忆文件名 long_term_file MEMORY.md这个骨架里default_provider填taotoken对应下面settings.json里的 provider 名。default_model填你实际要用的模型 ID。时区设成Asia/Shanghai定时任务的 cron 表达式才会按北京时间触发不然你设的早上 8 点可能变成别的点。再看settings.json的骨架。这是模型 provider 的配置OpenAI 兼容格式。{ providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, api: openai-completions, models: [ { id: gpt-4.5, name: GPT-4.5, reasoning: false, contextWindow: 128000 }, { id: claude-sonnet-4-5, name: Claude Sonnet 4.5, reasoning: true, contextWindow: 200000 } ] } }, defaultProvider: taotoken, defaultModel: gpt-4.5 }这个片段里baseUrl是https://taotoken.net/apiapiKey换成你自己的。api字段标成openai-completions表示走 OpenAI 兼容的 completions 接口。models数组里每个模型有 id、name、reasoning 开关、contextWindow。你要加模型就往数组里加一项换模型只改defaultModel。三件套对照一下Base URL 是https://taotoken.net/apiKey 是你在控制台生成的sk-开头那串Model ID 是models数组里的id字段。这三个在 QClaw、Cline、Codex 这类工具里都是通用的配一次到处能用。如果你用的是 Cline 或者带 MCP 的场景配置逻辑一样只是文件位置不同。Cline 的 MCP 配置里同样填 Base URL、Key、Model ID 三件套。Codex 的auth.json也是这个结构把 baseUrl 和 apiKey 填进去模型 ID 在请求时指定。CC Switch 这类切换工具本质也是帮你在这三件套之间快速换。改完配置记得重启 QClaw 的 gateway不然不生效。QClaw 每次改配置前会自动备份一份.bak改坏了直接还原。这个备份机制很实用我改配置翻车过两次都是靠备份救回来的。4. 验证请求发一条消息确认配置真的生效配置写完不代表生效必须验证。这一步很多人跳过然后遇到问题就开始瞎猜。验证方法很简单分两步先看 gateway 有没有正常加载 provider再发一条真实请求看返回。第一步重启 QClaw 后打开它的日志或者 gateway 状态页确认taotoken这个 provider 被加载了默认模型是你设的那个。如果日志里报 provider 解析失败多半是 JSON 格式错了比如多了个逗号或者少了引号。JSON 对格式很敏感建议用编辑器自带的校验。第二步直接在 QClaw 对话界面发一条消息比如「你现在用的是哪个模型」。如果配置正确它会正常回复并且你能在日志里看到请求打到了https://taotoken.net/api。这一步能过说明 Base URL、Key、Model ID 三件套都对上了。如果你想更严谨一点可以用 curl 直接测 TaoToken 通道排除 QClaw 本身的干扰。curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: gpt-4.5, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }这条命令如果返回一个包含choices的 JSON说明通道和 Key 都没问题。返回里choices[0].message.content就是模型回复。如果返回 401是 Key 的问题返回 404是模型 ID 或路径的问题返回超时是网络或 baseUrl 的问题。这样一层层排除比在 QClaw 里瞎试快得多。验证通过之后再回到 QClaw 跑一次定时任务确认隔离会话模式下也能正常调用。定时任务用的是isolated会话和主对话的上下文是分开的但 provider 配置是共用的。如果主对话能跑、定时任务报错那问题多半在定时任务自己的配置不在模型通道。我实测下来验证这一步花五分钟能省掉后面半小时的排查。尤其是你接了好几个模型的时候先确认通道通再逐个确认模型 ID顺序不能反。5. 常见报错排查401、local proxy failed、reading choices这一节列几个我实际遇到过的报错以及对应的排查方向。这些报错在 QClaw、Cline、Codex 里都可能出现排查逻辑是通用的。401 Unauthorized。最常见基本就是 Key 的问题。三种可能Key 写错了、Key 过期了、Key 前面的Bearer或者sk-前缀漏了。先检查settings.json里apiKey字段是不是完整的sk-开头字符串有没有多余空格。如果 Key 是对的去 TaoToken 控制台确认这个 Key 还有效、额度没用完。还有一种隐蔽情况你把 Key 写进了config.toml而不是settings.jsonQClaw 读不到也会报 401。记住 Key 只放 provider 配置里。local proxy failed。这个报错通常出现在 QClaw 启动 gateway 的时候意思是本地代理没起来。原因可能是端口被占用或者 gateway 进程没启动。先看config.toml里gateway.port设的端口有没有被别的程序占了换个端口试试。再确认auto_start是 true。如果还不行手动重启 QClaw看日志里 gateway 的启动信息。这个报错和模型 Key 无关别往 Key 上查。reading choices 相关报错。比如cannot read property choices of undefined或者reading choices。这个说明请求发出去了但返回的结构不是预期的 OpenAI 格式。两种可能一是 baseUrl 写错了请求打到了非 API 地址返回了 HTML 或者别的 JSON二是模型 ID 不存在服务端返回了错误结构。先确认 baseUrl 是https://taotoken.net/api没有多余路径。再确认模型 ID 在 TaoToken 文档里存在。如果都对用上面那条 curl 单独测一下看返回结构到底是什么。OAuth 相关报错。如果你在 QClaw 里绑定了微信、飞书这些平台可能会遇到 OAuth 授权失败。这个和模型 API 配置是两回事排查方向是平台侧的 App ID、Secret、回调地址。别把它和模型 401 混在一起查会绕远路。模型切换后不生效。改完defaultModel重启了但对话还是用旧模型。先确认config.toml和settings.json里的默认模型字段是不是都改了两个文件可能各有一份。再确认 gateway 真的重启了有时候界面重启了但 gateway 进程还在跑旧的。最后看日志里实际请求的模型 ID 是哪个。排查的核心思路是分层先确认通道通不通curl 测再确认 QClaw 读没读到配置看日志最后确认模型 ID 对不对看返回。一层层来别跳步。6. 把 Key 管起来之后QClaw 才真正好用配置梳理完最大的感受是QClaw 的能力上限很大程度上取决于你的 API 配置管得好不好。默认模型能跑但只有把多个模型、多个场景的 Key 统一起来它才从「一个能聊天的工具」变成「一个能长期干活的工作台」。用 TaoToken 统一 Key 和 API 通道之后我这边的好处很具体换模型只改一个字段加模型只往数组里加一项定时任务和主对话共用一套凭证出问题只查一个通道。以前接三家模型要维护三套配置现在一套搞定。如果你刚开始用 QClaw建议别急着接一堆模型。先把一套通道配通、验证通过再逐步加模型。配置这东西一次只改一个变量出问题才知道是哪个变量引起的。一次改五个地方报错了你只能全推倒重来。Key 生成和通道配置可以去控制台和文档里对照着做模型对话页面可以拿来快速验证某个模型 ID 是否可用。如果你打算长期用 QClaw 跑编码任务或者 Agent 类的自动化Coding Plan 那条线也值得看一下它和按量调用的场景不太一样适合高频长期使用的开发者。最后留一个实用习惯每次改完配置把settings.json和config.toml各备份一份命名带上日期。QClaw 自己会备份.bak但那是覆盖式的你自己留一份带日期的回滚的时候更从容。我现在的做法是改配置前先复制一份到backup/目录文件名加日期后缀一周下来攒了七八个版本哪次改坏了直接翻出来对比比在脑子里回忆改了什么靠谱得多。