1. 为什么你的 Agent 实验总在 Token 账单前止步
如果你最近在折腾 Agent 项目，大概率遇到过这种场景：本地把 DeepSeek Harness 跑起来了，工具链、沙箱、会话管理都通了，结果一接上付费模型，跑几个多步任务，后台的 Token 消耗曲线就开始陡峭上升。尤其是做多模型对比、循环调度、长上下文研究这类实验，一次完整的 Agent 编排动辄几十万 Token，钱包压力比调试压力还大。
DeepSeek Harness（命令行dsh）是 DeepSeek 开源的一个 Agent 智能体框架，基于「一切皆插件」的架构，由 Cordis 插件内核驱动。模型、工具、技能、会话、沙箱、存储、循环、调度乃至 UI 全部由插件组合而成，可以自由替换。它本身只是模型之外的「控制中心」，负责环境交互、工具契约、上下文流转与沙箱隔离，模型可以来自任意提供方。这个设计天然适合接入聚合网关。
OpenRouter 是一个 LLM 聚合路由平台，把多家提供方的 API 统一成一套 OpenAI 兼容接口。它上面标注:free的模型，prompt 与 completion 定价都是 $0，覆盖编程、推理、多模态、金融、医疗等场景。把 DeepSeek Harness 和 OpenRouter 接起来，等于给 Agent 实验装了一个「免费弹药库」：你可以用同一套 Harness 工作流，在不同免费模型之间切换，做路由对比、成本验证、能力评测，而不用为每次试错付费。
这篇文章面向个人开发者和 Agent 实验场景，给出三条可复制的接入路径：Web UI 图形化配置、settings.yaml配置文件、以及让 Harness 自己帮你写配置的对话式接入。同时会演示一次多模型切换与 Token 用量对比，帮你把「Token 焦虑」变成「路由策略」。适合谁：正在用 DeepSeek Harness 做 Agent 原型、想低成本试多模型、或者单纯想搭一个私人 AI 工作站的人。
2. 接入前的准备：OpenRouter Key 与 DeepSeek Harness 环境
在动手之前，先把两样东西准备好：一个能用的 OpenRouter API Key，以及一个能启动的 DeepSeek Harness 环境。这一步不复杂，但顺序别搞反，否则后面配置会反复报错。
先说 Harness。项目目前处于开发者预览阶段，采用 MIT 协议开源，一条命令即可启动：
npx @deepseek-ai/dsh web该命令默认在http://127.0.0.1:3080启动 Web UI，本机启动时还会自动用默认浏览器打开页面。如果你习惯命令行，也可以直接用dsh子命令操作。首次运行会拉取依赖，耐心等一会儿。启动成功后，你会看到一个带设置、模型、会话管理的界面，这就是后面配置的主战场。
再说 OpenRouter Key。你需要到 OpenRouter 的 Keys 页面创建一个 API Key，格式通常是sk-or-v1-开头的一长串。创建时注意两点：一是给它起个能认出来的名字，比如dsh-free-test；二是如果平台提供额度限制选项，可以先设一个保守值，避免实验跑飞。拿到 Key 后先别急着填进 Harness，建议先用一条 curl 验证它本身是通的：
curl https://openrouter.ai/api/v1/models \ -H "Authorization: Bearer sk-or-v1-你的Key"如果返回一大段 JSON 模型列表，说明 Key 有效、网络可达。这一步能帮你把「Key 问题」和「Harness 配置问题」提前分开，后面排障会省很多时间。
关于免费模型，OpenRouter 上标注:free的模型 prompt 与 completion 定价均为 $0，适合原型开发和学习实验。常见的包括 NVIDIA 的 Nemotron 系列、DeepSeek 的 Flash 系列、inclusionAI 的 Ling 系列、Thinking Machines 的 Inkling 系列、Cohere 的 North Mini Code 等，上下文从 256K 到 1M 不等，参数规模覆盖 3B 到 975B MoE。如果你不想逐个挑，OpenRouter 还提供了一个特殊路由openrouter/free，会自动为每个请求匹配一个合适的免费模型。
这里有个容易忽略的点：Harness 的凭据存储和配置文件是分开的。settings.yaml里只保留凭据的「引用名」，真正的密钥存在~/.dsh/.credentials.yaml。所以你在配置文件里写的是apiKeyEnv: OPENROUTER_API_KEY，而实际值通过环境变量或凭据文件注入。理解这一点，后面看到「Key 填了却报 401」就不会慌。
最后提醒一句：免费层通常有每日请求次数上限，高并发或长任务可能触发限流，不适合生产环境。部分免费模型的提供方可能会使用你的输入输出来训练和改进模型，敏感数据不要走免费模型。这些限制不影响实验，但心里要有数。
3. 三条可复制配置路径：Web UI、settings.yaml 与对话式接入
DeepSeek Harness 接入 OpenRouter 有三种方式，从图形界面到配置文件再到对话式接入，难度递减、灵活度不同。下面每条都给出可复制的片段，你可以按自己的习惯选一条。
3.1 Web UI 配置（推荐给大多数用户）
全程图形化，不用手写 YAML。启动npx @deepseek-ai/dsh web后，在 Web UI 里打开「设置 > 模型」，点击「添加提供方」，选择「添加自定义提供方」，然后填四个字段：
| 字段 | 填写值 |
|---|---|
| Provider ID | openrouter（小写，一经设定不可更改） |
| 基础 URL | https://openrouter.ai/api/v1 |
| API 协议 | openai-completions |
| 凭据 | sk-or-v1-你的Key |
保存后，在模型列表里填入模型 ID，例如nvidia/nemotron-3-ultra-550b-a55b:free。也可以点「获取可用模型」让 Harness 自动探测端点提供的模型，搜索后勾选。最后在模型选择器中选中刚添加的模型，即设为新会话默认值。
注意：Provider ID 是永久的，请求、已保存会话和凭据引用都会使用它。若需重命名，请新建提供方再删除旧的。模型变更在下一次请求时生效，无需重启服务器。
3.2 settings.yaml 配置文件（进阶用户）
适合需要批量管理模型、精细控制请求兼容性的场景。配置文件位于~/.dsh/settings.yaml，与模型页写入的是同一份文档，可直接编辑，适配器会在下次请求时重新读取。可复制片段如下：
llm-pi-ai: providers: openrouter: apiKeyEnv: OPENROUTER_API_KEY api: openai-completions baseURL: https://openrouter.ai/api/v1 models: - id: nvidia/nemotron-3-ultra-550b-a55b:free displayName: Nemotron 3 Ultra (Free) - id: deepseek/deepseek-v4-flash-0731:free displayName: DeepSeek V4 Flash (Free) - id: inclusionai/ling-3.0-flash-vl:free displayName: Ling 3.0 Flash VL (Free) input: [text, image]然后设置环境变量：
export OPENROUTER_API_KEY="sk-or-v1-你的Key"把这条export写进~/.bashrc或~/.zshrc可实现持久化。apiKeyEnv只命名凭据引用，密钥本身存储在~/.dsh/.credentials.yaml中。
两个进阶提示值得记一下。视觉模型（如 Ling 3.0 Flash VL、Inkling 系列）需补充模态声明，否则附图会被拦截，写法是input: [text, image]。若推理模型请求被拒，可能是网关不接受developer角色，需在路由上设compat.supportsDeveloperRole: false及compat.maxTokensField: max_tokens。
3.3 对话式无脑接入（零基础用户）
如果你连表单都懒得填，Harness 的 Agent 本身就能帮你完成配置。它是个能读写文件、运行命令的智能体，直接在会话里用自然语言说：
帮我接入 OpenRouter，API Key 是 sk-or-v1-xxxx，基础 URL 是 https://openrouter.ai/api/v1，协议用 openai-completions，把所有免费模型都加上。
Agent 会读取并编辑~/.dsh/settings.yaml、写入凭据、添加模型，全程你可能只需点击几次审批确认。完成后即可直接开始对话，零配置文件知识门槛。
三种方式对比一下：Web UI 难度低、适合大多数用户、批量管理一般；settings.yaml难度中、适合进阶用户、精细控制全部字段；对话式难度极低、适合零基础用户、依赖 Agent 代写。推荐指数上，Web UI 和对话式对新手更友好，配置文件适合要长期维护多模型路由的人。
4. 验证请求与多模型切换：一次 Token 用量对比实测
配置写完，最关键的一步是验证它真的通了，并且能切换模型。很多人卡在「配置看起来对，但请求没反应」，所以这里给一套可复现的验证流程。
先做最小验证。在 Harness 会话里发一句简单指令，比如「用一句话解释什么是 MoE 架构」。如果模型正常返回，说明 Base URL、Key、Model ID 三件套都对。如果报错，先看错误类型，下一节会专门排障。
接着做多模型切换。在 Web UI 的模型选择器里，依次选中你配置的几个免费模型，发同一个问题，观察返回风格和速度差异。比如：
问题：写一个 Python 函数，判断一个字符串是否是回文，要求忽略大小写和空格。用deepseek/deepseek-v4-flash-0731:free跑一次，再用nvidia/nemotron-3-ultra-550b-a55b:free跑一次，最后用cohere/north-mini-code:free跑一次。你会明显感觉到：代码类模型在函数补全上更利落，大参数 MoE 模型在解释性文字上更啰嗦但更全面，小模型响应更快但偶尔漏边界条件。
然后是 Token 用量对比。Harness 的会话面板通常会显示每次请求的 Token 统计。你可以设计一个固定任务，比如「读取当前目录下的 README.md，总结成三点」，在三个模型上各跑一次，记录 prompt tokens、completion tokens 和总耗时。因为都是:free模型，费用一栏都是 $0，但 Token 消耗量能反映模型的「话痨程度」和上下文处理效率。实测下来，同一个任务在不同模型上的 completion tokens 可能相差两三倍，这对你后续做路由策略很有参考价值。
如果你想让 Harness 自动在免费模型间路由，可以把模型 ID 设为openrouter/free，OpenRouter 会为每个请求匹配一个合适的免费模型。这适合「不想挑、先跑起来」的阶段，但做对比实验时还是建议显式指定模型，否则变量不可控。
验证通过后，你可以把常用模型固化到settings.yaml的 models 列表里，配合displayName起个短名字，切换时更顺手。整个流程跑下来，从零到多模型可用，熟练后大概十分钟。
5. 常见报错排查：401、local proxy failed 与 choices 读取失败
接入过程中最容易遇到的几类报错，这里按真实错误信息对照排查。先记住一个原则：先分清是「Key 问题」「网络问题」还是「配置格式问题」，再动手改。
401 Unauthorized / invalid api key。这是最常见的。原因通常有三个：Key 复制时带了空格或换行；apiKeyEnv引用的环境变量没生效；凭据文件~/.dsh/.credentials.yaml里存的值和settings.yaml的引用名对不上。排查顺序：先用第 2 节的 curl 命令单独验证 Key；再确认echo $OPENROUTER_API_KEY有输出；最后检查settings.yaml里apiKeyEnv的名字和环境变量名是否完全一致（大小写敏感）。
local proxy failed / connection refused。这类错误多半是 Base URL 写错或网络不通。确认baseURL是https://openrouter.ai/api/v1，注意结尾的/v1不能少，也不能多斜杠。如果你在 Harness 里配了本地代理相关设置，先关掉再试，避免多层转发互相干扰。
reading choices / unexpected response shape。这通常出现在非 OpenAI 原生网关的兼容性问题上。OpenRouter 虽然兼容 OpenAI 协议，但某些模型返回结构略有差异。解决办法是在提供方配置里补兼容开关，比如compat.supportsDeveloperRole: false和compat.maxTokensField: max_tokens。另外，视觉模型没声明input: [text, image]时，附图请求会被拦截，也可能表现为响应结构异常。
OAuth / 授权相关报错。如果你在配置里误开了某些需要 OAuth 的提供方，或者凭据类型选错，会看到授权失败。OpenRouter 用的是 API Key，不需要 OAuth 流程，检查提供方类型是否选成了需要授权的选项。
模型不可用 / model not found。免费模型可能因提供方调整、容量不足而临时不可用或下线。先在 OpenRouter 的模型页确认该模型 ID 当前是否还在免费列表里，再检查settings.yaml里的id是否拼写正确，包括:free后缀。
速率限制 429。免费层通常有每日请求次数上限，高并发或长任务会触发限流。降低并发、错峰跑任务，或者临时切到另一个免费模型，都能缓解。
排查时建议开一个终端专门看 Harness 的日志输出，错误信息比 UI 上显示的更详细。改完配置后，模型变更在下一次请求时生效，不用重启服务器，这点很方便。
6. 从免费模型到稳定工作流：把 Token 焦虑变成路由策略
免费模型能解决「起步成本」，但要做长期稳定的 Agent 工作流，还需要一点策略。我的经验是：把免费模型当成「实验层」，把稳定模型当成「生产层」，中间用 Harness 的插件化路由做切换。
具体做法是，在settings.yaml里把模型按用途分组：编程类任务优先用cohere/north-mini-code:free或deepseek/deepseek-v4-flash-0731:free；长上下文研究用nvidia/nemotron-3-ultra-550b-a55b:free或thinkingmachines/inkling:free；多模态任务用inclusionai/ling-3.0-flash-vl:free。每组配一个displayName，切换时一目了然。
对于需要长期跑、对稳定性要求高的编码或 Agent 任务，可以考虑用 TaoToken 的 Coding Plan 做补充，它面向长期编码和 Agent 场景，和免费模型形成互补。如果你只是想先验证模型能力，可以直接在模型对话里试；要接入自己的项目，则参考接入文档把 Base URL、Key、Model ID 三件套配好。API Key 在控制台的 API Keys 页面管理，建议按项目分 Key，方便追踪用量。
最后回到 Token 焦虑这件事。焦虑的根源不是「Token 贵」，而是「试错成本不可控」。当你有一套能随时切换、免费模型兜底的 Harness 工作流，试错就变成了低成本的路由实验。先跑npx @deepseek-ai/dsh web，再选一种方式填上 OpenRouter Key，把免费模型加进去，你会发现 Agent 实验的门槛比想象中低很多。
)
)
)
