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 开源在 GitHub（sichenai/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_KEY="sk-or-v1-你的Key"Windows PowerShell：
$env:OPENROUTER_API_KEY="sk-or-v1-你的Key"如果你后面要切到统一通道做连通性核对，再加一个变量区分：
export TAOTOKEN_API_KEY="你的统一通道Key" export TAOTOKEN_BASE_URL="https://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,576（1M） |
| 最大输出 | 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-21，WorkBuddy 5.3.14 + macOS 15.7.1，OpenRouter 免费模型 stealth/ox-alpha，接入全程 0 元。免费定价有时效，Ox Alpha 截至实测日定价为 0，之后可能变化，以 OpenRouter 实时定价为准。其他智能体的字段名可能不同，但「探针验证 + 宿主层验证」的思路通用。
