1. 为什么要在 QClaw 里接本地 Ollama又为什么还要留一条统一通道QClaw 是腾讯推出的桌面 AI 客户端支持通过openclaw.json挂载多家模型提供商。Ollama 则是本地跑大模型最省心的方案一条ollama run就能把模型拉起来。把这两者接在一起你就能在 QClaw 的界面里直接调用本机显卡跑模型数据不出局域网断网也能用。但纯本地方案有个现实问题本地模型受限于显存和量化精度遇到长上下文、复杂推理、代码生成这类任务时效果和响应速度会明显掉档。这时候如果能在同一个 QClaw 里再挂一条云端统一通道本地模型当主力、云端模型当兜底体验会稳很多。TaoToken 提供的统一 Key/API 通道正好适合这个角色——它兼容 OpenAI 协议QClaw 的openai-completions适配器可以直接对接不需要额外写适配层。这篇教程面向三类人一是已经在用 QClaw、想加本地模型的二是本地 Ollama 跑起来了、但不知道怎么让 QClaw 认出来的三是想同时保留本地和云端两条通道、做 fallback 的。下面从 Ollama 服务启动讲起逐项拆openclaw.json的关键字段最后给出可复制的配置片段和 curl 验证命令确保本地模型和统一通道都能正常返回。先明确一个概念QClaw 里的“提供商provider”本质就是一组baseUrl apiKey api 协议 模型列表。本地 Ollama 暴露的是 OpenAI 兼容接口所以它和云端通道在配置结构上是一模一样的区别只在baseUrl指向哪里、apiKey填什么。理解这一点后面所有字段都不会觉得陌生。2. 前置准备Ollama 服务启动、模型拉取与 QClaw 配置目录定位这一章把动手前的环境全部铺好。很多人卡在“配置写了但连不上”八成是这一步没做扎实。2.1 安装并启动 Ollama 服务去 Ollama 官网下载对应系统的安装包Windows 装完后任务栏会出现一个羊驼图标macOS 和 Linux 用命令行启动。安装完成后先在终端确认服务在跑ollama --version ollama listollama list有输出哪怕是空的表头就说明服务进程正常。如果提示连接被拒绝说明后台服务没起来Windows 下重新点一下托盘图标Linux 下执行systemctl start ollama或手动ollama serve。注意Ollama 默认监听127.0.0.1:11434。如果你打算让 QClaw 通过局域网 IP 访问后面会解释为什么建议这么做需要让它监听所有网卡。Linux 下设置环境变量OLLAMA_HOST0.0.0.0:11434再启动Windows 下在系统环境变量里加同名的OLLAMA_HOST值填0.0.0.0:11434然后重启 Ollama。2.2 拉取你要用的模型模型选择直接决定后面openclaw.json里models数组填什么。先拉一个体积适中的做验证ollama pull qwen2.5:7b ollama pull llama3.1:8b拉完后用ollama list确认输出里的 NAME 列就是模型 ID比如qwen2.5:7b。这个 ID 必须和配置文件里的id字段完全一致大小写、冒号、标签都不能错。如果你用的是量化版本ID 可能长这样glm-4.7-flash:q4_K_M照抄即可。想快速验证模型本身能跑ollama run qwen2.5:7b 用一句话解释什么是量化能正常回复就 CtrlC 退出。这一步很关键它把“模型问题”和“配置问题”隔离开了——如果这里就不通后面怎么改配置都没用。2.3 定位 QClaw 的 openclaw.jsonQClaw 首次启动后会在用户目录生成配置文件夹。各平台路径平台配置文件路径WindowsC:\Users\用户名\.qclaw\openclaw.jsonmacOS/Users/用户名/.qclaw/openclaw.jsonLinux/home/用户名/.qclaw/openclaw.json改之前务必完全退出 QClaw包括右下角托盘图标否则保存后可能被进程回写覆盖。用 VS Code 打开这个文件如果它是空的或只有默认的qclaw提供商就按下一章的结构补全。2.4 查本机局域网 IP为什么不建议用localhost因为 QClaw 的模型请求可能由独立进程或容器发起localhost在那种上下文里指向的不是你的宿主机。用实际局域网 IP 最稳。Windows 下ipconfig找 IPv4 地址形如192.168.1.23。macOS/Linux 下ifconfig | grep inet 记下这个 IP后面baseUrl要用。同时确认防火墙放行了 11434 端口Windows 下在“高级安全 Windows Defender 防火墙”里给 Ollama 加一条入站规则或者临时关闭防火墙测试。3. 可复制配置openclaw.json 关键字段逐项说明与统一通道接入这一章是核心。先给完整可复制的配置再逐字段拆解最后讲怎么把云端统一通道加进来。3.1 完整 openclaw.json 配置片段把下面内容覆盖到你的openclaw.json。注意把192.168.1.23换成你自己的 IP模型 ID 换成你实际拉取的{ models: { mode: merge, providers: { qclaw: { baseUrl: ${QCLAW_LLM_BASE_URL}, apiKey: ${QCLAW_LLM_API_KEY}, api: openai-completions, models: [ { id: modelroute, name: modelroute, input: [text, image] } ] }, ollama-local: { baseUrl: http://192.168.1.23:11434/v1, apiKey: ollama, api: openai-completions, models: [ { id: qwen2.5:7b, name: qwen2.5:7b }, { id: llama3.1:8b, name: llama3.1:8b } ] }, taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, api: openai-completions, models: [ { id: claude-sonnet-4-5, name: claude-sonnet-4-5 }, { id: gpt-4.1, name: gpt-4.1 } ] } } }, agents: { defaults: { model: { primary: ollama-local/qwen2.5:7b, fallbacks: [taotoken/claude-sonnet-4-5, qclaw/modelroute] }, models: { ollama-local/qwen2.5:7b: { alias: 本地 Qwen2.5 }, ollama-local/llama3.1:8b: { alias: 本地 Llama3.1 }, taotoken/claude-sonnet-4-5: { alias: 统一通道 Claude } } } } }3.2 关键字段逐项说明models.mode设为merge表示新配置和内置默认合并而不是整体替换。这样即使你漏写了某个内置提供商QClaw 也不会直接报错。providers下每个键就是一个提供商。ollama-local和taotoken是我们新增的qclaw是原有的云端备用。baseUrl是请求地址。Ollama 的 OpenAI 兼容接口必须带/v1后缀写成http://192.168.1.23:11434/v1。TaoToken 统一通道的地址是https://taotoken.net/api同样走 OpenAI 兼容协议不要画蛇添足加/v1按官方文档给的地址填。apiKey对 Ollama 来说其实不校验但字段不能为空随便填ollama即可。TaoToken 这边必须填真实密钥格式通常是sk-开头。密钥在控制台的 API Keys 页面创建地址是https://taotoken.net/console/api-keys。api字段固定写openai-completions表示用 OpenAI 的 chat completions 协议。QClaw 目前对本地和云端统一走这个适配器不要改成别的值。models数组里每个对象的id必须和ollama list输出的模型名完全一致name是显示名可以自定义。input字段声明该模型支持的输入类型纯文本模型写[text]就行多模态才加image。agents.defaults.model.primary是默认模型格式必须是提供商名/模型ID中间用斜杠。fallbacks是兜底列表按顺序尝试。这里我把本地 Qwen 设为主力统一通道的 Claude 做第一兜底原有云端做第二兜底。agents.defaults.models里的alias决定 QClaw 界面下拉框显示的名字。没有 alias 的模型可能不会出现在 UI 里这是很多人“看不到本地模型”的直接原因。3.3 把 endpoint 与鉴权改到 TaoToken 统一通道如果你想让 QClaw 默认走统一通道而不是本地只改一行primary: taotoken/claude-sonnet-4-5这样所有请求都从 TaoToken 的https://taotoken.net/api发出鉴权用你创建的 Key。本地 Ollama 依然保留在 providers 里随时可以切回来。这种“本地 统一通道”双挂的配置适合白天用云端跑复杂任务、晚上断网用本地跑简单任务的场景。密钥管理上有个小技巧不要把 Key 硬编码在 JSON 里提交到任何仓库。QClaw 支持${ENV_VAR}形式引用环境变量你可以把apiKey写成${TAOTOKEN_API_KEY}然后在系统环境变量里设置真实值。这样配置文件可以安全备份和分享。4. 验证请求curl 命令确认本地模型与统一通道均正常返回配置写完先别急着开 QClaw用 curl 分别打两条通道把问题定位在配置层还是客户端层。4.1 验证本地 Ollama 的 OpenAI 兼容接口curl http://192.168.1.23:11434/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer ollama \ -d { model: qwen2.5:7b, messages: [{role: user, content: 你好用一句话介绍你自己}], stream: false }正常返回是一个 JSONchoices[0].message.content里有模型回复。如果返回Connection refused说明 IP 或端口不对或者 Ollama 没监听0.0.0.0。如果返回model not found说明model字段和ollama list里的名字不一致。4.2 验证 TaoToken 统一通道curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字收到}], stream: false }返回 200 且choices里有内容说明 Key 和地址都对。如果返回 401检查 Key 是否复制完整、有没有多余空格。如果返回 404检查地址是不是写成了https://taotoken.net/api/v1/...多加了路径。4.3 在 QClaw 界面里做端到端验证两条 curl 都通之后完全退出 QClaw 再重新启动。打开后看输入框上方的模型选择栏应该能看到“本地 Qwen2.5”“统一通道 Claude”这些 alias。选中本地模型发一条“你好”观察任务管理器里 Ollama 进程的 CPU/GPU 占用是否飙升同时 QClaw 正常回复就说明整条链路通了。再切到统一通道的模型发一条确认云端也能返回。如果本地模型长时间无响应fallbacks会自动切到统一通道你会在回复里看到模型名变化——这本身就是 fallback 生效的证明。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth 对照这一章按真实报错逐条给解法。这些错误我在配置过程中基本都踩过一遍。5.1 401 Unauthorized出现在统一通道请求时九成是 Key 问题。检查三点Key 是否完整复制sk-后面不能断、Authorization头是不是Bearer加空格再加 Key、Key 有没有被禁用或额度耗尽。在控制台重新生成一个 Key 替换测试最快。如果 401 出现在本地 Ollama 上那基本是apiKey字段留空了。Ollama 不校验但字段必须有值填ollama即可。5.2 local proxy failed / connection refused这个报错说明 QClaw 发请求时连不上baseUrl。按顺序排查Ollama 服务是否在跑ollama list有输出、baseUrl里的 IP 是不是本机实际局域网 IP、端口 11434 是否被防火墙拦截、Ollama 是否监听了0.0.0.0而非仅127.0.0.1。Windows 下临时关闭防火墙测试一下能通就说明是防火墙规则问题。5.3 reading choices / unexpected end of JSON这个报错通常出现在流式响应解析时。原因可能是stream参数和客户端预期不一致或者模型返回了非标准 JSON。先在 curl 里加stream: false确认非流式能通。如果非流式正常、流式报错检查 QClaw 版本是否过旧升级到最新版。另外某些量化模型在极端参数下会输出截断的 JSON换一个模型 ID 测试可以排除。5.4 OAuth / authentication failed如果 QClaw 提示 OAuth 相关错误说明它尝试走账号登录鉴权而不是 API Key。检查api字段是否被误改成了非openai-completions的值或者baseUrl指向了需要 OAuth 的端点。统一通道和本地 Ollama 都走 API Key 鉴权不需要 OAuth 流程。把apiKey填对、api字段确认无误即可。5.5 配置改了不生效QClaw 的热重载不稳定改完openclaw.json必须完全退出进程托盘图标也要退再重新启动。如果还不生效检查 JSON 是否有语法错误——用 VS Code 的 JSON 校验或者python -m json.tool openclaw.json验证格式。一个多余的逗号就能让整个配置被忽略。5.6 模型列表里看不到本地模型回到agents.defaults.models检查 alias 是否配置。没有 alias 的模型可能不显示在下拉框。另外确认primary或fallbacks里引用的模型 ID 和providers里定义的完全一致拼写错误会导致该模型被静默忽略。6. 长期编码与 Agent 场景把统一通道用成主力本地做补充配置跑通只是起点。如果你打算把 QClaw 当日常编码和 Agent 工具用模型调度策略值得再调一调。本地 Ollama 的优势是零延迟、零成本、数据不出本机适合代码补全、简单重构、日志分析这类高频轻量任务。统一通道的优势是模型能力强、上下文长、支持复杂推理适合架构设计、跨文件重构、长文档理解。我的做法是把primary设成本地模型处理日常问答把fallbacks第一顺位设成统一通道的强模型遇到本地搞不定的自动升级。如果你要跑长时间的 Agent 任务比如让模型自主规划多步操作、调用工具、迭代修改代码建议直接走 Coding Plan 这类长期编码方案地址是https://taotoken.net/coding-plan。它针对 Agent 场景做了会话保持和额度优化比按次调用更划算。模型对话的调试入口在https://taotoken.net/models接入文档在https://taotoken.net/docAPI Keys 管理在https://taotoken.net/console/api-keys。最后留一个实用习惯每次改完openclaw.json先用python -m json.tool校验格式再用两条 curl 分别打本地和统一通道最后才重启 QClaw。这个顺序能把 90% 的问题挡在客户端之外省下大量“到底是配置错还是客户端抽风”的排查时间。本地模型和统一通道各司其职QClaw 才算真正用起来。
腾讯QClaw 调用本地 Ollama 大模型完整教程：openclaw.json 配置到 TaoToken 统一通道
1. 为什么要在 QClaw 里接本地 Ollama又为什么还要留一条统一通道QClaw 是腾讯推出的桌面 AI 客户端支持通过openclaw.json挂载多家模型提供商。Ollama 则是本地跑大模型最省心的方案一条ollama run就能把模型拉起来。把这两者接在一起你就能在 QClaw 的界面里直接调用本机显卡跑模型数据不出局域网断网也能用。但纯本地方案有个现实问题本地模型受限于显存和量化精度遇到长上下文、复杂推理、代码生成这类任务时效果和响应速度会明显掉档。这时候如果能在同一个 QClaw 里再挂一条云端统一通道本地模型当主力、云端模型当兜底体验会稳很多。TaoToken 提供的统一 Key/API 通道正好适合这个角色——它兼容 OpenAI 协议QClaw 的openai-completions适配器可以直接对接不需要额外写适配层。这篇教程面向三类人一是已经在用 QClaw、想加本地模型的二是本地 Ollama 跑起来了、但不知道怎么让 QClaw 认出来的三是想同时保留本地和云端两条通道、做 fallback 的。下面从 Ollama 服务启动讲起逐项拆openclaw.json的关键字段最后给出可复制的配置片段和 curl 验证命令确保本地模型和统一通道都能正常返回。先明确一个概念QClaw 里的“提供商provider”本质就是一组baseUrl apiKey api 协议 模型列表。本地 Ollama 暴露的是 OpenAI 兼容接口所以它和云端通道在配置结构上是一模一样的区别只在baseUrl指向哪里、apiKey填什么。理解这一点后面所有字段都不会觉得陌生。2. 前置准备Ollama 服务启动、模型拉取与 QClaw 配置目录定位这一章把动手前的环境全部铺好。很多人卡在“配置写了但连不上”八成是这一步没做扎实。2.1 安装并启动 Ollama 服务去 Ollama 官网下载对应系统的安装包Windows 装完后任务栏会出现一个羊驼图标macOS 和 Linux 用命令行启动。安装完成后先在终端确认服务在跑ollama --version ollama listollama list有输出哪怕是空的表头就说明服务进程正常。如果提示连接被拒绝说明后台服务没起来Windows 下重新点一下托盘图标Linux 下执行systemctl start ollama或手动ollama serve。注意Ollama 默认监听127.0.0.1:11434。如果你打算让 QClaw 通过局域网 IP 访问后面会解释为什么建议这么做需要让它监听所有网卡。Linux 下设置环境变量OLLAMA_HOST0.0.0.0:11434再启动Windows 下在系统环境变量里加同名的OLLAMA_HOST值填0.0.0.0:11434然后重启 Ollama。2.2 拉取你要用的模型模型选择直接决定后面openclaw.json里models数组填什么。先拉一个体积适中的做验证ollama pull qwen2.5:7b ollama pull llama3.1:8b拉完后用ollama list确认输出里的 NAME 列就是模型 ID比如qwen2.5:7b。这个 ID 必须和配置文件里的id字段完全一致大小写、冒号、标签都不能错。如果你用的是量化版本ID 可能长这样glm-4.7-flash:q4_K_M照抄即可。想快速验证模型本身能跑ollama run qwen2.5:7b 用一句话解释什么是量化能正常回复就 CtrlC 退出。这一步很关键它把“模型问题”和“配置问题”隔离开了——如果这里就不通后面怎么改配置都没用。2.3 定位 QClaw 的 openclaw.jsonQClaw 首次启动后会在用户目录生成配置文件夹。各平台路径平台配置文件路径WindowsC:\Users\用户名\.qclaw\openclaw.jsonmacOS/Users/用户名/.qclaw/openclaw.jsonLinux/home/用户名/.qclaw/openclaw.json改之前务必完全退出 QClaw包括右下角托盘图标否则保存后可能被进程回写覆盖。用 VS Code 打开这个文件如果它是空的或只有默认的qclaw提供商就按下一章的结构补全。2.4 查本机局域网 IP为什么不建议用localhost因为 QClaw 的模型请求可能由独立进程或容器发起localhost在那种上下文里指向的不是你的宿主机。用实际局域网 IP 最稳。Windows 下ipconfig找 IPv4 地址形如192.168.1.23。macOS/Linux 下ifconfig | grep inet 记下这个 IP后面baseUrl要用。同时确认防火墙放行了 11434 端口Windows 下在“高级安全 Windows Defender 防火墙”里给 Ollama 加一条入站规则或者临时关闭防火墙测试。3. 可复制配置openclaw.json 关键字段逐项说明与统一通道接入这一章是核心。先给完整可复制的配置再逐字段拆解最后讲怎么把云端统一通道加进来。3.1 完整 openclaw.json 配置片段把下面内容覆盖到你的openclaw.json。注意把192.168.1.23换成你自己的 IP模型 ID 换成你实际拉取的{ models: { mode: merge, providers: { qclaw: { baseUrl: ${QCLAW_LLM_BASE_URL}, apiKey: ${QCLAW_LLM_API_KEY}, api: openai-completions, models: [ { id: modelroute, name: modelroute, input: [text, image] } ] }, ollama-local: { baseUrl: http://192.168.1.23:11434/v1, apiKey: ollama, api: openai-completions, models: [ { id: qwen2.5:7b, name: qwen2.5:7b }, { id: llama3.1:8b, name: llama3.1:8b } ] }, taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, api: openai-completions, models: [ { id: claude-sonnet-4-5, name: claude-sonnet-4-5 }, { id: gpt-4.1, name: gpt-4.1 } ] } } }, agents: { defaults: { model: { primary: ollama-local/qwen2.5:7b, fallbacks: [taotoken/claude-sonnet-4-5, qclaw/modelroute] }, models: { ollama-local/qwen2.5:7b: { alias: 本地 Qwen2.5 }, ollama-local/llama3.1:8b: { alias: 本地 Llama3.1 }, taotoken/claude-sonnet-4-5: { alias: 统一通道 Claude } } } } }3.2 关键字段逐项说明models.mode设为merge表示新配置和内置默认合并而不是整体替换。这样即使你漏写了某个内置提供商QClaw 也不会直接报错。providers下每个键就是一个提供商。ollama-local和taotoken是我们新增的qclaw是原有的云端备用。baseUrl是请求地址。Ollama 的 OpenAI 兼容接口必须带/v1后缀写成http://192.168.1.23:11434/v1。TaoToken 统一通道的地址是https://taotoken.net/api同样走 OpenAI 兼容协议不要画蛇添足加/v1按官方文档给的地址填。apiKey对 Ollama 来说其实不校验但字段不能为空随便填ollama即可。TaoToken 这边必须填真实密钥格式通常是sk-开头。密钥在控制台的 API Keys 页面创建地址是https://taotoken.net/console/api-keys。api字段固定写openai-completions表示用 OpenAI 的 chat completions 协议。QClaw 目前对本地和云端统一走这个适配器不要改成别的值。models数组里每个对象的id必须和ollama list输出的模型名完全一致name是显示名可以自定义。input字段声明该模型支持的输入类型纯文本模型写[text]就行多模态才加image。agents.defaults.model.primary是默认模型格式必须是提供商名/模型ID中间用斜杠。fallbacks是兜底列表按顺序尝试。这里我把本地 Qwen 设为主力统一通道的 Claude 做第一兜底原有云端做第二兜底。agents.defaults.models里的alias决定 QClaw 界面下拉框显示的名字。没有 alias 的模型可能不会出现在 UI 里这是很多人“看不到本地模型”的直接原因。3.3 把 endpoint 与鉴权改到 TaoToken 统一通道如果你想让 QClaw 默认走统一通道而不是本地只改一行primary: taotoken/claude-sonnet-4-5这样所有请求都从 TaoToken 的https://taotoken.net/api发出鉴权用你创建的 Key。本地 Ollama 依然保留在 providers 里随时可以切回来。这种“本地 统一通道”双挂的配置适合白天用云端跑复杂任务、晚上断网用本地跑简单任务的场景。密钥管理上有个小技巧不要把 Key 硬编码在 JSON 里提交到任何仓库。QClaw 支持${ENV_VAR}形式引用环境变量你可以把apiKey写成${TAOTOKEN_API_KEY}然后在系统环境变量里设置真实值。这样配置文件可以安全备份和分享。4. 验证请求curl 命令确认本地模型与统一通道均正常返回配置写完先别急着开 QClaw用 curl 分别打两条通道把问题定位在配置层还是客户端层。4.1 验证本地 Ollama 的 OpenAI 兼容接口curl http://192.168.1.23:11434/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer ollama \ -d { model: qwen2.5:7b, messages: [{role: user, content: 你好用一句话介绍你自己}], stream: false }正常返回是一个 JSONchoices[0].message.content里有模型回复。如果返回Connection refused说明 IP 或端口不对或者 Ollama 没监听0.0.0.0。如果返回model not found说明model字段和ollama list里的名字不一致。4.2 验证 TaoToken 统一通道curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复两个字收到}], stream: false }返回 200 且choices里有内容说明 Key 和地址都对。如果返回 401检查 Key 是否复制完整、有没有多余空格。如果返回 404检查地址是不是写成了https://taotoken.net/api/v1/...多加了路径。4.3 在 QClaw 界面里做端到端验证两条 curl 都通之后完全退出 QClaw 再重新启动。打开后看输入框上方的模型选择栏应该能看到“本地 Qwen2.5”“统一通道 Claude”这些 alias。选中本地模型发一条“你好”观察任务管理器里 Ollama 进程的 CPU/GPU 占用是否飙升同时 QClaw 正常回复就说明整条链路通了。再切到统一通道的模型发一条确认云端也能返回。如果本地模型长时间无响应fallbacks会自动切到统一通道你会在回复里看到模型名变化——这本身就是 fallback 生效的证明。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth 对照这一章按真实报错逐条给解法。这些错误我在配置过程中基本都踩过一遍。5.1 401 Unauthorized出现在统一通道请求时九成是 Key 问题。检查三点Key 是否完整复制sk-后面不能断、Authorization头是不是Bearer加空格再加 Key、Key 有没有被禁用或额度耗尽。在控制台重新生成一个 Key 替换测试最快。如果 401 出现在本地 Ollama 上那基本是apiKey字段留空了。Ollama 不校验但字段必须有值填ollama即可。5.2 local proxy failed / connection refused这个报错说明 QClaw 发请求时连不上baseUrl。按顺序排查Ollama 服务是否在跑ollama list有输出、baseUrl里的 IP 是不是本机实际局域网 IP、端口 11434 是否被防火墙拦截、Ollama 是否监听了0.0.0.0而非仅127.0.0.1。Windows 下临时关闭防火墙测试一下能通就说明是防火墙规则问题。5.3 reading choices / unexpected end of JSON这个报错通常出现在流式响应解析时。原因可能是stream参数和客户端预期不一致或者模型返回了非标准 JSON。先在 curl 里加stream: false确认非流式能通。如果非流式正常、流式报错检查 QClaw 版本是否过旧升级到最新版。另外某些量化模型在极端参数下会输出截断的 JSON换一个模型 ID 测试可以排除。5.4 OAuth / authentication failed如果 QClaw 提示 OAuth 相关错误说明它尝试走账号登录鉴权而不是 API Key。检查api字段是否被误改成了非openai-completions的值或者baseUrl指向了需要 OAuth 的端点。统一通道和本地 Ollama 都走 API Key 鉴权不需要 OAuth 流程。把apiKey填对、api字段确认无误即可。5.5 配置改了不生效QClaw 的热重载不稳定改完openclaw.json必须完全退出进程托盘图标也要退再重新启动。如果还不生效检查 JSON 是否有语法错误——用 VS Code 的 JSON 校验或者python -m json.tool openclaw.json验证格式。一个多余的逗号就能让整个配置被忽略。5.6 模型列表里看不到本地模型回到agents.defaults.models检查 alias 是否配置。没有 alias 的模型可能不显示在下拉框。另外确认primary或fallbacks里引用的模型 ID 和providers里定义的完全一致拼写错误会导致该模型被静默忽略。6. 长期编码与 Agent 场景把统一通道用成主力本地做补充配置跑通只是起点。如果你打算把 QClaw 当日常编码和 Agent 工具用模型调度策略值得再调一调。本地 Ollama 的优势是零延迟、零成本、数据不出本机适合代码补全、简单重构、日志分析这类高频轻量任务。统一通道的优势是模型能力强、上下文长、支持复杂推理适合架构设计、跨文件重构、长文档理解。我的做法是把primary设成本地模型处理日常问答把fallbacks第一顺位设成统一通道的强模型遇到本地搞不定的自动升级。如果你要跑长时间的 Agent 任务比如让模型自主规划多步操作、调用工具、迭代修改代码建议直接走 Coding Plan 这类长期编码方案地址是https://taotoken.net/coding-plan。它针对 Agent 场景做了会话保持和额度优化比按次调用更划算。模型对话的调试入口在https://taotoken.net/models接入文档在https://taotoken.net/docAPI Keys 管理在https://taotoken.net/console/api-keys。最后留一个实用习惯每次改完openclaw.json先用python -m json.tool校验格式再用两条 curl 分别打本地和统一通道最后才重启 QClaw。这个顺序能把 90% 的问题挡在客户端之外省下大量“到底是配置错还是客户端抽风”的排查时间。本地模型和统一通道各司其职QClaw 才算真正用起来。