1. 为什么我要把 OpenRouter 免费模型接进智能体先说一个我踩过的坑去年我为了给自建的智能体工具链接一个能用的模型前后注册了四家平台每家都要单独申请 Key、单独看文档、单独调参数光是把模型名写对就耗掉一个下午。后来发现 OpenRouter 这类聚合平台一个 API Key 就能调用几十个厂商的模型其中相当一部分是免费的不需要绑卡。但「拿到 Key」和「智能体里真的能跑」之间还隔着一堆细节模型 slug 怎么写、能力字段填什么、文档标的上下文上限是不是虚标、接完怎么确认链路通了。这篇要讲的 model-connector Skill就是把这套流程固化下来的东西。它是什么一个能自动完成「查配置、核对元数据、发探针、写配置、宿主层验证」的智能体技能。能做什么你只给它一个 API Key它把模型接进你的智能体并实测通过。适合谁想零成本搭智能体工具链、又不想在配置细节上反复试错的开发者。我 2026 年实测下来从拿 Key 到智能体里真正跑通全程 5 分钟左右花费 0 元。需要提前说清楚一件事免费模型不是慈善。厂商愿意给免费额度通常是获客、数据或转化考量。拿它做测试、学习、跑通流程完全没问题但别把生产环境的关键业务押在免费模型上随时可能下架或转收费。理解这个前提后面的操作你心里就有数了。这篇的结构是这样先讲清楚聚合平台和 Skill 的定位再给前置准备然后是可直接复制的配置片段接着是一次端到端验证再把我遇到的报错逐条排查最后说怎么把 endpoint 切到统一通道做连通性核对。全程给命令、给配置、给预期输出你可以跟着做。2. 前置准备OpenRouter Key 与 model-connector Skill 安装2.1 拿 OpenRouter API Key打开 OpenRouter 官网用 Google 或 GitHub 账号登录也支持邮箱注册。登录后右上角头像进 Keys 页面点 Create Key起个名字复制弹出的 Key。注意 Key 只显示一次关掉页面就看不到了先存到安全的地方。拿到的 Key 长这样以sk-or-v1-开头sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx不需要信用卡不需要手机验证免费模型可以直接用。这一步没什么难度真正容易出问题的是下一步——把 Key 交给智能体之后模型名和能力字段怎么填。2.2 安装 model-connector Skill这个 Skill 开源在 GitHubsichenai/sichen-skills两种安装方式任选。方式一是 npx 一键安装npx skills add sichenai/sichen-skills方式二是 clone 后手动复制git clone https://github.com/sichenai/sichen-skills.git # 把 skills/model-connector 整个目录复制到你的智能体 skill 目录不同智能体的 skill 目录不一样。以 WorkBuddy 为例目录是~/.workbuddy/skills/把model-connector整个目录复制进去即可。装完在智能体对话里输入skill:model-connector能唤起就说明装好了。这里有个细节值得说Skill 的本质是一段可被智能体调用的流程脚本它内置了一份模型注册表收录了常见模型的接入参数——官方接口地址、鉴权方式、模型名、能力字段、Token 上限。你给它模型名或平台名它先匹配注册表匹配到了预填配置没匹配到就去读官方文档提取参数。所以它不是一个「魔法按钮」而是一套有明确步骤的自动化流程你要看懂它每步在做什么出问题才知道从哪查。2.3 环境变量写法Key 不要硬编码进配置文件用环境变量管理。macOS 或 Linux 下写入 shell 配置export OPENROUTER_API_KEYsk-or-v1-你的KeyWindows PowerShell$env:OPENROUTER_API_KEYsk-or-v1-你的Key如果你后面要切到统一通道做连通性核对再加一个变量区分export TAOTOKEN_API_KEY你的统一通道Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api环境变量写好后source ~/.zshrc或重开终端让它生效。这一步看着简单但我见过不少人 Key 写错一个字符后面排查半天所以复制完建议echo $OPENROUTER_API_KEY确认一下。3. 可复制配置models.json 与 Skill 调用片段3.1 Skill 调用方式装好之后接入就变成一句话的事。在智能体对话里发skill:model-connector api_key:sk-or-v1-你的KeySkill 会自动往下跑你不用手动改任何配置。它一共走六步查注册表识别模型、拉官方元数据核对、发三个探针实测、写入配置、宿主层验证、收工。下面把关键配置片段给出来方便你对照。3.2 智能体模型配置片段Skill 最终会把探针验证过的值写进智能体的自定义模型配置。以 WorkBuddy 为例文件是~/.workbuddy/models.json写入的结构大致如下{ models: [ { id: stealth/ox-alpha, name: Ox Alpha (OpenRouter Free), provider: openrouter, base_url: https://openrouter.ai/api/v1, api_key_env: OPENROUTER_API_KEY, context_length: 1048576, max_output_tokens: 131072, input_modalities: [text, image, video], output_modalities: [text], pricing: { prompt: 0, completion: 0 } } ] }这里有两个细节 Skill 替你守住了。第一模型名id必须一字不差。这个 id 会被智能体原样当成请求里的model字段发给 API多一个字符、大小写不对、斜杠写错都会返回 404。所以它必须精确等于 OpenRouter 的模型 slug比如stealth/ox-alpha。第二能力字段如实填写。支持什么填什么不支持的不硬填。比如 Ox Alpha 支持图片输入实测返回 200不支持图片输出官方元数据只有文本输出配置就按这个填避免智能体误启用不存在的功能。3.3 切到统一通道的配置片段如果你想把 endpoint 改到统一 Key/API 通道做连通性核对把base_url和api_key_env换掉即可{ id: stealth/ox-alpha, name: Ox Alpha (TaoToken Channel), provider: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, context_length: 1048576, max_output_tokens: 131072, input_modalities: [text, image, video], output_modalities: [text] }注意base_url用https://taotoken.net/api不要带多余路径。切过去之后用同样的探针请求打一次能返回内容就说明统一通道连通正常。这一步的意义是当你有多个模型来源时用统一通道管理 Key 和计费比每个平台单独维护一套配置省心得多。3.4 官方元数据核对结果Skill 第二步会去 OpenRouter 官方接口拉模型元数据核对真实能力。我这次拉到的是项官方值上下文长度1,048,5761M最大输出131,072输入模态文本 图片 视频输出模态仅文本定价0 / 0免费推理强制开启这一步的意义在于注册表是起点假设官方元数据才是权威。模型能力会更新注册表可能过期所以每次接入都重新核对一遍别拿旧配置直接套。4. 端到端验证三个探针与宿主层实测4.1 三个探针实测静态配置写得再对不如实际发一次请求。Skill 会连发三个探针。文本探针发一条最简请求验证模型名和 Key 对不对。返回 200 且带内容就算通。用 curl 手动复现大致是这样curl https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json \ -d { model: stealth/ox-alpha, messages: [{role: user, content: ping}], max_tokens: 16 }上限探针把max_tokens设成标称上限 131072 再发一次验证文档没虚标。这一步很重要文档写的上限经常虚标不实测就写进配置你选这个模型发长文时会直接报错。如果被拒就下调到真实可用值。图片探针带一张图发一次验证是不是真的支持图片输入。能力字段最怕想当然兄弟模型支持不等于这个模型支持必须拿确切模型名实测。三个探针全过才说明这个模型真的能用。4.2 宿主层验证写进配置文件不等于智能体真的能用了。Skill 会回到智能体里做两层验证先看智能体的模型列表里有没有出现新模型出现说明配置被正确加载再实际选这个模型发一句话返回正常才算链路全通。我用命令行实测返回我是 CodeBuddy Code一个在命令行中帮你完成软件工程任务的交互式编程助手底层由 ox-alpha 模型驱动。到这一步你在智能体的模型选择器里就能看到stealth/ox-alpha了选它就能用。全程你没有手改过一行配置。4.3 切到统一通道后的验证把base_url换成https://taotoken.net/api、Key 换成统一通道的 Key 之后重复上面的文本探针把请求地址和鉴权头换掉curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: stealth/ox-alpha, messages: [{role: user, content: ping}], max_tokens: 16 }返回 200 且带内容说明统一通道连通正常。这一步做完你的智能体工具链就有了一个可切换的模型入口后面换模型只改配置不改代码。5. 常见报错排查401、local proxy failed、reading choices、OAuth接入过程里我遇到过的报错逐条对照排查。401 Unauthorized。最常见的原因是 Key 没生效或写错。先echo $OPENROUTER_API_KEY确认环境变量有值再确认请求头是Authorization: Bearer sk-or-v1-...注意 Bearer 后面有一个空格。如果切到统一通道后报 401检查是不是还在用 OpenRouter 的 Key 打统一通道的地址两者要配套。local proxy failed。这个报错通常出现在智能体通过本地代理转发请求时。先确认本地代理进程是否在跑再确认base_url有没有写错路径。如果你把base_url写成https://taotoken.net/api/带尾斜杠有些客户端会拼出双斜杠导致失败去掉尾斜杠再试。reading choices 相关报错。这类报错一般是响应结构不符合预期常见于模型名写错返回了错误对象或者max_tokens超限被拒。先确认model字段精确等于模型 slug再把max_tokens降到标称上限以下重试。如果降下来就通了说明是上限虚标把配置里的max_output_tokens改成实测可用值。OAuth 相关报错。如果你用的是需要 OAuth 授权的客户端比如某些 Claude Code 类工具报 OAuth 失败通常是授权流程没走完或 token 过期。重新走一遍授权或者改用 API Key 方式接入。这里要提醒CC Switch、Cline MCP、Codex 的auth.json这类配置一旦出现就要写全三件套——Base URL、Key、Model ID缺一个都会失败。以 Codex 的auth.json为例{ base_url: https://taotoken.net/api, api_key: 你的统一通道Key, model: stealth/ox-alpha }429 限流。免费模型限流是常态别把它误判成配置错。429 重试即可400 才算真上限。Skill 在探针阶段会区分这两种情况你手动排查时也要分清。配置写了没生效。模型列表里找不到先确认配置文件路径对不对再确认 JSON 语法有没有错少个逗号就会整份失效。改完重启智能体再看列表。6. 把接入流程固化成 Skill 的价值把「接入聚合平台免费模型」从手动流程变成 Skill最大的价值不是省那几分钟而是把踩过的坑固化成流程查注册表、对官方元数据、三连探针、写配置、宿主验证每一步都有明确目的不会再靠猜。新手拿到手就是一套完整方法论。如果你要长期跑编码或 Agent 任务建议把模型入口统一管理用 Coding Plan 把多个模型来源收敛到一个通道换模型只改配置。想先验证模型效果可以直接在模型对话里试。接入和排障过程中需要的 Key 和文档在 API Keys 和接入文档里都能找到。免费模型还有一个现实问题随时可能下架或转收费。厂商调整政策不打招呼所以别把免费模型写死在关键路径上。用之前看一眼模型页的定价用的时候多备一两个替代模型。model-connector 的注册表会随实测持续更新同一模型下次接入更快。最后说一句实测环境2026-08-21WorkBuddy 5.3.14 macOS 15.7.1OpenRouter 免费模型 stealth/ox-alpha接入全程 0 元。免费定价有时效Ox Alpha 截至实测日定价为 0之后可能变化以 OpenRouter 实时定价为准。其他智能体的字段名可能不同但「探针验证 宿主层验证」的思路通用。