1. 为什么本地 vLLM 跑通了OpenClaw 还是报 Unknown model如果你已经按前两章把 vLLM 推理服务在服务器上拉起来也用中间跳转把本地和虚拟机打通了那大概率会遇到一个很典型的卡点网页界面能打开但模型下拉框里显示的是「未知模型」或者一发消息就抛Unknown model: qwen-portal/Qwen3.5-27B-FP8。这不是 vLLM 挂了也不是网络断了而是 OpenClaw 侧的 LLM 工具链没有和 vLLM 的模型标识对齐。OpenClaw 这类 Agent 框架在启动时会读一份本地 settings 文件通常是~/.openclaw/openclaw.json里面定义了「去哪里请求模型、用哪个 Key、模型 ID 叫什么、上下文窗口多大」。而 vLLM 启动时也有自己的model_name参数这个值才是它对外暴露的唯一模型 ID。两边对不上OpenClaw 就会认为你要的模型不存在。这一章要解决的就是这个适配问题。适合已经在本地跑通 vLLM 推理、需要统一管理多模型 Key 与 API 通道的开发者。我会先给出 OpenClaw 侧可直接复制的 settings 配置片段再讲怎么把请求通道收敛到 TaoToken 统一管理最后用一次真实对话请求验证整条链路是否稳定可复现。整个过程不需要你重装任何东西改配置文件、重启、发一条消息就能确认。需要先明确一个概念OpenClaw 里的models模块和agents模块是两套东西。models负责「怎么连到模型」agents负责「默认用哪个模型」。很多人只改了models没改agents结果就是配置看着对、请求还是报错。下面会一步步把这两块对齐。2. TaoToken 前置把多模型 Key 与 API 通道统一收口在讲具体配置之前先说清楚为什么要在本地 vLLM 之外再引入 TaoToken。本地 vLLM 适合跑你自己的私有模型但实际做 Agent 开发时你往往还需要调用云端能力更强的模型做对比、做兜底、做工具调用。如果每个模型都单独配一套 Base URL 和 Keysettings 文件会迅速膨胀换环境时极易出错。TaoToken 在这里扮演的是「统一 API 通道 统一 Key 管理」的角色。它兼容 OpenAI 风格的接口协议也就是说 OpenClaw 里原本写给 OpenAI 的api: openai-completions配置只要把baseUrl和apiKey换成 TaoToken 的就能直接复用。这样你的 settings 里可以同时存在两个 provider一个是本地vllm_local一个是走 TaoToken 的云端通道Agent 按需切换。接入前你需要准备两样东西一个 TaoToken 的 API Key以及确认要用的模型 ID。Key 在控制台的 API Keys 页面创建模型 ID 在文档里能查到。这两个值后面会填进 settings 的apiKey和models[].id字段。注意本地 vLLM 自己部署的模型不需要真实 Key填EMPTY即可但走 TaoToken 的通道必须填真实 Key否则会返回 401。TaoToken 的 Base URL 统一是https://taotoken.net/api注意结尾不要多加/v1OpenClaw 的 provider 配置里api字段已经声明了协议类型路径拼接由框架处理。如果你在别的工具里看到有人写https://taotoken.net/api/v1那是另一套拼接逻辑在 OpenClaw 里按本文的写法来。把 Key 和通道准备好之后你的 settings 里就会形成「本地 云端」双 provider 的结构。这样做的好处是本地模型负责隐私数据和离线场景云端通道负责需要更强推理或工具调用的任务两者共用同一份 Agent 配置切换只改agents.defaults.model.primary一行。3. 可复制配置openclaw.json 的 models 与 agents 对齐这一节是全文的核心直接给你能复制进~/.openclaw/openclaw.json的片段。先讲本地 vLLM 的 provider 配置再讲 TaoToken 通道的配置最后讲 agents 怎么引用。先看本地 vLLM 的 provider。关键字段有五个baseUrl指向你中间跳转的地址加端口apiKey填EMPTYapi声明协议类型models[].id必须和 vLLM 启动时的model_name完全一致contextWindow和maxTokens要和 vLLM 的max-model-len对齐。models: { mode: merge, providers: { vllm_local: { baseUrl: http://172.23.20.15:8000/v1, apiKey: EMPTY, api: openai-completions, models: [ { id: qwen, name: Qwen3.5-27B-FP8, contextWindow: 32768, maxTokens: 4096, input: [text, image] } ] } } }这里id填的是qwen对应 vLLM 里的model_name。contextWindow填 32768maxTokens填 4096意思是模型总窗口 32768其中最多留 4096 给回答剩下的给提问和上下文。这个分配对大多数对话场景够用如果你要喂长文档可以把contextWindow调大但不要超过 vLLM 的max-model-len。接着加 TaoToken 的 provider。它和本地 provider 并列放在providers下面baseUrl换成 TaoToken 的地址apiKey换成你创建的真实 Keymodels[].id换成你要用的云端模型 ID。taotoken_cloud: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, api: openai-completions, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5, contextWindow: 200000, maxTokens: 8192, input: [text, image] } ] }两个 provider 都配好后agents模块要引用它们。primary决定默认用哪个格式是provider名/模型id。如果你想让本地模型做默认就写vllm_local/qwen想用云端就写taotoken_cloud/claude-sonnet-4-5。agents: { defaults: { model: { primary: vllm_local/qwen }, models: { vllm_local/qwen: { alias: Qwen3.5 }, taotoken_cloud/claude-sonnet-4-5: { alias: Sonnet } }, workspace: /home/ubuntu/.openclaw/workspace, compaction: { mode: safeguard } } }还有一个容易漏的点tools.profile。默认 onboard 生成的配置里tools.profile是coding它的 allowlist 里可能包含一些当前模型不支持的条目日志会一直刷allowlist contains unknown entries。把 profile 改成full可以消除这个警告前提是你的模型确实支持工具调用。Qwen3.5 这类多模态模型在 vLLM 启动日志里能看到/v1/chat/completions接口说明它支持多轮对话和工具调用改成full是安全的。tools: { profile: full }把上面几段合并进你的openclaw.json保存后 OpenClaw 会自动检测文件变化并重启。重启完成后网页界面的模型下拉框里应该能看到Qwen3.5和Sonnet两个别名不再是「未知模型」。4. 验证请求一次对话确认整条链路连通配置改完不算完必须发一次真实请求确认链路通。验证分两步先确认 OpenClaw 读到了新配置再确认请求真的打到了模型并返回了内容。第一步看 OpenClaw 的启动日志。重启后终端会打印加载的 provider 和模型列表你应该能看到vllm_local和taotoken_cloud两个 provider以及各自的模型 ID。如果只看到一个说明 JSON 结构有问题多半是括号没闭合或者 provider 名写错了。第二步在网页界面选Qwen3.5发一条最简单的文本消息比如「用一句话说明你是什么模型」。正常情况你会看到流式返回的内容。如果返回的是空或者报错先看终端日志里的具体错误码。第三步验证多模态。选一张本地图片上传问「这张图里有什么」。Qwen3.5 的input字段配了[text, image]vLLM 也支持视觉接口所以应该能正常识别。如果这一步报错检查 vLLM 启动时是否加载了视觉模块以及input字段是否漏了image。第四步切到Sonnet别名发一条消息确认 TaoToken 通道也通。这一步能验证你的 Key 是否有效、Base URL 是否正确。如果返回 401说明 Key 填错了或者没生效如果返回连接超时检查baseUrl是不是写成了https://taotoken.net/api/v1多写的/v1会导致路径拼接错误。验证通过后你可以在终端里看到类似这样的日志请求先到 OpenClaw 的 gatewaygateway 根据agents.defaults.model.primary找到 providerprovider 用baseUrl和apiKey发起请求模型返回内容后原路返回。整条链路清晰可追踪出问题时按这个顺序逐段排查即可。提示如果你在对话时看到黄色日志[compaction-safeguard] Compaction safeguard: cancelling compaction with no real conversation messages to summarize这不是报错。它是 OpenClaw 的对话压缩机制在对话太短时主动取消压缩不影响使用。5. 本篇常见错排查401、local proxy failed、reading choices配置过程中最容易撞上的几个报错这里逐个对照给排查方向。401 Unauthorized出现在走 TaoToken 通道时。原因通常是apiKey填错、Key 被删除、或者 Key 没有对应模型的权限。排查方法是把apiKey复制到 curl 里单独测一次确认 Key 本身有效。如果 curl 通但 OpenClaw 报 401检查 JSON 里 Key 有没有被引号截断或者有没有多余空格。local proxy failed / connection refused出现在走本地 vLLM 时。原因是baseUrl指向的地址端口不通。排查顺序是先在本地机器curl http://172.23.20.15:8000/v1/models看能不能返回模型列表如果不通检查中间跳转是否启动、防火墙是否放行、vLLM 是否还在运行。这一步能排除掉大部分网络问题。reading choices / unexpected end of JSON出现在模型返回内容解析阶段。原因通常是 vLLM 返回的响应格式和 OpenClaw 期望的不一致或者流式返回被中途截断。检查api字段是否和 vLLM 实际暴露的接口匹配——vLLM 的 OpenAI 兼容接口用openai-completions如果你写成了openai-responses就会解析失败。另外确认maxTokens没有设得比 vLLM 的max-model-len还大。Unknown model出现在agents和models没对齐时。agents.defaults.model.primary里的provider名/模型id必须在models.providers里存在。比如你写了vllm_local/qwen但models里 provider 叫vllm、模型 id 叫qwen3就会报这个错。逐字符核对两边。OAuth / auth profile 相关报错如果你在配置里保留了auth.profiles且指向了openai:default但实际没走 OpenAI 官方通道可能会触发 OAuth 流程报错。本地 vLLM 和 TaoToken 都不需要 OAuth把auth.profiles里无关的条目删掉或者改成api_key模式。排查时记住一个原则先确认单点通再确认链路通。curl 能通说明网络和 Key 没问题问题在 OpenClaw 配置curl 不通说明问题在服务端或网络先解决那一层。6. 语义一致 CTA把通道固定下来后续组件才好加到这里OpenClaw 与 LLM 工具链的适配就完成了。你手上现在有一份能同时驱动本地 vLLM 和云端通道的 settingsAgent 默认模型、别名、上下文窗口、工具 profile 都对齐了发一条消息就能验证整条链路。下一步如果你要加网页搜索组件、记忆组件或者工具调用都会依赖这份配置的稳定性。建议把openclaw.json纳入版本管理每次改完先跑一次第 4 节的验证动作确认没回归再继续。需要创建或管理 Key 的话去控制台的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys接入细节和模型 ID 查询看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc想先在网页里试一下模型对话效果可以直接用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat如果你打算长期跑编码类 Agent 任务Coding Plan 的通道更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan配置改完后如果遇到报错先回到第 5 节对照错误码排查大部分问题都能在那几个方向里找到答案。