在 DeepSeek Harness 中把 Router One 添加为 自定义模型 API
DeepSeek Harness(dsh)是 DeepSeek 开源的 Agent 框架(agent harness):工具在你的机器上执行,每一轮模型调用发给你配置的提供商。它的「设置 → 模型」页支持「自定义模型 API」提供商,由 API 地址、一种 API 协议、Key 和模型 ID 组成。把 Router One 加进去,一把 Key 就能用上目录中的 Claude、GPT、Gemini、Grok 和 DeepSeek 对话模型,网关发往模型的每个请求都记录在控制台 → 日志中(在输出任何内容之前就失败的流式请求可能没有记录)。本指南依据 dsh 0.2.2-rc.1(2026-11-05 时 npm 的 latest 标签)的提供商配置文档与源码核对(2026-11-05)。DeepSeek Harness 也提供桌面版(按 deepseek.com,2026-11-05 核对);本指南讲的是 Web UI 路径(dsh web)。dsh 仍是预览版:README 提示会有破坏兼容性的变更;按 deepseek.com(2026-11-05 核对),DeepSeek Harness 处于公开预览阶段,并提供 macOS 与 Windows 桌面版下载,请按你实际运行的版本对照下面的步骤。
启动 dsh Web UI,并创建 专用 Key
dsh 的 README 给出的运行方式是 npm:安装 Node.js(按其发布说明,0.2.2-rc.1 需要 Node.js 24.9 及以上版本)后运行 npx @deepseek-ai/dsh web,它默认在 http://127.0.0.1:3080 启动 Web UI,本机启动时还会用默认浏览器打开(加 --no-open 则不打开浏览器)。2026-11-05 时 npm 的 latest 标签是 0.2.2-rc.1(2026 年 11 月 4 日发布);想运行同一版本,可在包名后加 @0.2.2-rc.1。按 dsh 0.2.2-rc.1 源码,首次运行且还没有可用的提供商时,会弹出「开始使用」对话框,提供「登录」(DeepSeek 账号)和「添加 API Key」(官方 DeepSeek 提供商的 Key)两个选项;直接关闭它,或点「添加 API Key」后再选「稍后配置」即可,因为 Router One 提供商使用自己的 Key。然后在控制台 → API 密钥点「创建密钥」,为 dsh 单独建一把 Key,并设置 maxSpend 上限。一次 Agent 任务的每一轮模型调用都是一个请求,只把工具结果交回模型的那几轮也算,所以长任务可能在你不再输入的情况下产生大量计费请求。maxSpend 是钱包扣费的硬上限,专用 Key 也方便在控制台 → 日志里只筛出 dsh 的请求。
npx @deepseek-ai/dsh web # Web UI 地址 http://127.0.0.1:3080 npx @deepseek-ai/dsh@0.2.2-rc.1 web # 本指南核对时的版本
在 DeepSeek Harness 中添加 Router One 自定义模型 API
打开「设置 → 模型」,点「添加模型提供商」。卡片默认打开在「第三方模型提供商」,那是 dsh 内置的各家官方 API 列表;把它切换到「自定义模型 API」。Provider ID 填 router-one 之类的名称:必须以小写字母开头,只能使用小写字母、数字和短横线;dsh 文档说明 Provider ID 是永久的,因为请求、已保存的会话、模型默认值和凭据引用都会用到它。「显示名称」填 Router One,「API 地址」填 https://api.router.one/v1,「API 协议」选 OpenAI Chat Completions,「API 密钥」粘贴专用 Key;按 dsh 文档,密钥只写不读,保存在 $DSH_HOME/.credentials.yaml 中。至少按精确的目录 ID 添加一个模型,例如 anthropic/claude-sonnet-5(「获取可用模型」见后文添加模型一节),然后点「创建提供商」。添加的模型会出现在模型选择器中。选中模型也会把它设为新会话的默认模型;按 dsh 文档,已经发过请求的会话保留自己的模型,要换就在该会话里用输入框的模型选择或 /model 切换,从该会话的下一次请求起生效。填好的表单如下:
- Base URL (OpenAI Chat Completions, OpenAI Responses)
- https://api.router.one/v1
- Base URL (Anthropic Messages)
- https://api.router.one
# DeepSeek Harness:设置 → 模型 → 添加模型提供商 → 自定义模型 API # DeepSeek Harness: Settings → Models → Add model provider → Custom model API Provider ID: router-one 显示名称 / Display name: Router One API 地址 / Base URL: https://api.router.one/v1 API 协议 / API protocol: OpenAI Chat Completions API 密钥 / API key: sk-your-router-one-key 模型 ID / Model ID: anthropic/claude-sonnet-5 # GPT 的 ID:第二个提供商 / GPT IDs: a second provider router-one-responses OpenAI Responses https://api.router.one/v1 # 可选:Claude 原生格式 / Optional: Claude in its native format router-one-anthropic Anthropic Messages https://api.router.one
每种 协议 一个 提供商:API 地址与 模型 ID
dsh 文档写得很明确:一个提供商只使用一种协议,网关同时提供两种协议时需要建两个提供商。Router One 在 Chat Completions 上提供全部对话模型,在 Responses 上原生提供 GPT 系列、DeepSeek V4 与 Grok 对话模型,在 Anthropic Messages 上提供 Claude 系列与 DeepSeek V4 的 ID,所以选哪种协议,决定了这个提供商能列哪些 ID。API 地址不要带最后的 /chat/completions、/responses 或 /messages;dsh 表单里两种 OpenAI 协议的占位地址是 https://gateway.example/v1,Anthropic Messages 的占位地址是 https://gateway.example。Anthropic Messages 请保持主机根地址:按 dsh 的架构笔记,「获取可用模型」对这种协议两种写法都接受,但对话请求原样使用你填的地址,Anthropic 客户端还会自己补上 /v1。Claude ID 发到 Responses 提供商,会在调用任何模型之前被 HTTP 400 拒绝(model '<id>' must be called via /v1/messages or /v1/chat/completions);Claude 与 DeepSeek 系列以外的对话 ID 发到 Anthropic Messages 提供商,会收到提示 must be called via /v1/chat/completions 的 400。
| dsh 的 API 协议(存储值) | 本指南使用的 Provider ID | API 地址 | Router One 请求路径与模型 ID |
|---|---|---|---|
| OpenAI Chat Completions(openai-completions) | router-one | https://api.router.one/v1 | POST /v1/chat/completions;全部对话模型:Claude、GPT、Gemini、Grok 与 DeepSeek 的 ID |
| OpenAI Responses(openai-responses) | router-one-responses | https://api.router.one/v1 | POST /v1/responses;GPT 系列、DeepSeek V4 与 Grok 对话模型 ID |
| Anthropic Messages(anthropic-messages) | router-one-anthropic | https://api.router.one | POST /v1/messages;Claude 系列与 DeepSeek V4 的 ID |
添加模型:获取 可用 模型,或手动填 精确 ID
在表单的「模型目录」里,「获取可用模型」会用表单当前的 API 地址、协议和 Key 询问端点。按 dsh 0.2.2-rc.1 源码,两种 OpenAI 协议发送 GET {API 地址}/models 并带 Bearer Key,Anthropic Messages 发送 GET /v1/models 并带 x-api-key 请求头;这两种请求头 Router One 都接受。Router One 只在 Key 有效时回应这个请求,返回的是整个目录,包括生图模型,无论哪种协议来问都一样,所以只勾选该提供商协议支持的对话 ID,再点「更新列表」;按 dsh 文档,提供商列表里已有的模型默认勾选,取消勾选就会把它移除。dsh 文档把探测称为便利手段而非保证:探测失败或列表为空时,用「添加模型」逐个手动添加从 /models 精确复制的 ID,效果完全一样。保存前请逐行检查:按同一份源码,「获取可用模型」添加的行可能带着列表里的容量值。「上下文窗口」按 /models 上该模型详情页的窗口填写;详情页显示的是取整后的缩写(1.05M、500K),请换算成整数并往小取:anthropic/claude-sonnet-5 与 deepseek-v4.1-flash 填 1000000,grok-4.7 填 500000。每个模型都要填:按 dsh 0.2.2-rc.1 的发布说明,没有设置容量的自定义模型按 1,000,000 token 上下文和 128,000 token 输出计,窗口更小的模型会因此推迟压缩。「最大输出 token 数」填你想要的上限,或清空以沿用 dsh 为该提供商设定的默认值;推理模型的思考 token 也计入这个上限,请留出余量。图片输入按 dsh 文档的做法设置:编辑提供商,打开「自定义设置」并展开该模型的「模型选项」;只有 /models 上该模型的详情页标明支持图片输入时,才在「输入类型」中勾选「图片」(例如 deepseek-v4-flash 只支持文本)。
跑 Agent:工具 调用、GPT 的 ID 与 Responses 提供商
dsh 在它所在的机器上执行工具,每一轮模型调用发给所选模型所属的提供商;Router One 只承载这些模型请求。请选择 /models 详情页标明支持工具调用的 ID。GPT 的 ID 放在 OpenAI Responses 提供商下:按 OpenAI 的 GPT-6 指南(2026-11-05 核对),GPT-6 Astra、GPT-6.1 Sol 与 GPT-6.1 Terra 的工具调用只走 Responses API,其中 GPT-6 Astra 与 GPT-6.1 Sol 不接受推理强度 none;GPT-6 Sol 与 GPT-6 Luna 在 Chat Completions 上只有推理强度为 none 时才能调用函数。Router One 在 /v1/responses 上提供 GPT 系列模型,所以请把 openai/gpt-6.1-sol 或 openai/gpt-5.6-sol 加到 router-one-responses,而不是 Chat Completions 提供商。Claude 的 ID 走 Chat Completions 或 Anthropic Messages 提供商都可以,Gemini 的 ID 走 Chat Completions,Grok 的 ID 走 Chat Completions 或 Responses,DeepSeek V4 的 ID 三种都行。网关发往模型的每一轮调用(包括只交回工具结果的那一轮)都是一个单独的请求,记录在控制台 → 日志中(在输出任何内容之前就失败的流式请求可能没有记录)。
设置 推理 等级与 请求 选项
按 dsh 的提供商配置文档,「自定义模型 API」提供商下的模型可以在模型页设置推理等级:编辑提供商,打开「自定义设置」,展开该模型的「模型选项」,再打开「推理等级」。默认带有 off、low、medium、high 四行,每个档位的「API 参数值」默认与档位名相同,off 档不发送任何值。请求兼容开关在模型页上没有对应字段。dsh 把这两类设置都放在 $DSH_HOME/profiles/<profile>/cordis.patch.yml,也就是模型页写入的同一份文件;按 dsh 文档,用 dsh web 常规启动 Web UI 时 <profile> 就是 web,浏览器与 dsh 在同一台机器上时,可以点设置页顶部的「打开配置文件」打开它。只修改模型页已经写好的提供商条目,并保留其中的其他字段和模型,因为 Cordis 的覆盖会替换整个条目;dsh 会在下一次请求时重新读取这个文件。手动添加的模型默认不声明推理等级,所以在你添加等级之前不会出现推理等级菜单,由端点自身的默认值决定模型是否思考。为它打开「推理等级」,或在文件里给模型加上 reasoningEfforts,写法见下方 openai/gpt-5.6-sol 的例子。按 dsh 文档,声明了推理等级的模型(无论在模型页还是在文件里声明)会用 developer 角色发送系统提示词;Router One 的 Chat Completions 参考文档列出的消息角色是 system、user、assistant 和 tool,所以在 Chat Completions 提供商上同时设置 compat.supportsDeveloperRole: false。对 GPT-6 Astra 与 GPT-6.1 Sol,不要在 reasoningEfforts 里把 off 设为 none:按 OpenAI 的 GPT-6 指南(2026-11-05 核对),这两个模型都不接受 none。输出上限不需要额外开关:dsh 文档说,遇到无法识别的地址时,pi-ai 会把输出上限写成 max_completion_tokens,而 Router One 的 Chat Completions 同时接受 max_tokens 和 max_completion_tokens 作为输出上限(两者都传时以 max_completion_tokens 为准);Responses API 的输出上限字段是 max_output_tokens。
# $DSH_HOME/profiles/<profile>/cordis.patch.yml(dsh web 的 <profile> 是 web)
# 只修改模型页已写好的条目,保留其中的其他字段和模型。
- id: llm-pi-ai
config:
providers:
router-one:
compat:
supportsDeveloperRole: false
router-one-responses:
models:
- id: openai/gpt-5.6-sol
reasoningEfforts:
low: low
medium: medium
high: highDeepSeek Harness 该填 哪个 模型 ID?
从 /models 页复制精确的模型 ID,保留大小写、连字符和版本后缀,不要用展示名称代替。打开该模型的详情页,核对支持的 API 端点、上下文窗口和工具调用等能力,再与 DeepSeek Harness 当前选择的 provider 和功能对应。模型出现在目录里,不等于当前客户端能调用它的所有功能。建议为每个客户端或应用单独建 API Key,并设置 maxSpend 消费上限。每把 Key 的消费上限(maxSpend)限的是这把 Key 能从钱包扣的钱:累计扣费到上限后,这把 Key 上需要钱包付费的请求返回 HTTP 402。套餐额度覆盖的请求从账户共用的套餐额度里扣,不计入任何 Key 的上限。
DeepSeek Harness 用的是哪种 API 协议?
OpenAI 兼容描述的是接口格式,不能据此推断 Chat Completions(/v1/chat/completions)、Responses(/v1/responses)和 Anthropic Messages(/v1/messages)可以互换。先核对工具当前版本、provider 配置和实际请求路径,再查模型详情与 API 兼容性事实页。一次普通对话成功,也不能证明服务端工具、历史状态或文件编辑功能都受支持。
在请求日志里 核对 DeepSeek Harness 的调用
先在 DeepSeek Harness 发出一次简单文本请求,再到控制台 → 日志按时间、模型和 request_id 找到这条记录,核对 Token、钱包扣费或套餐扣减次数、总耗时和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id;没有对应日志时,要么请求没到达网关(客户端配置或网络问题),要么网关在调用模型之前就拒绝了它——Key 问题的 401、余额不足或 Key 达到 maxSpend 上限的 402、Key 或账户自身限额触发的 429,或模型 ID、端点不对的 400 / 404;在输出任何内容之前就失败的流式请求也可能没有日志。看客户端收到的状态码和错误消息就能区分是哪一种;先确认这一点,再判断是不是网关或上游故障。
常见 问题
在 DeepSeek Harness 的哪里 添加 Router One?
在「设置 → 模型」点「添加模型提供商」,把卡片从「第三方模型提供商」切换到「自定义模型 API」;第三方列表对应各家官方 API,要用它们自己的 Key。Provider ID 填 router-one,「API 地址」填 https://api.router.one/v1,「API 协议」选 OpenAI Chat Completions,填入 Router One Key,并从 /models 至少添加一个精确的模型 ID,然后点「创建提供商」。GPT 的 ID 再建一个 OpenAI Responses 提供商;如需 Claude 原生消息格式,可以再建一个 Anthropic Messages 提供商,API 地址填主机根地址 https://api.router.one。
DeepSeek Harness 提示 API Key 无效,该查 什么?
先看 Key 填在了哪个提供商:Router One Key 应填在你的「自定义模型 API」提供商的「API 密钥」里,「设置 → 模型」上的 DeepSeek 卡片放的是 DeepSeek 官方 API 的 Key。只粘贴 Key 本身:按 dsh 0.2.2-rc.1 源码,Key 里含有 HTTP 请求头无法携带的字符时,表单会提示「该 API 密钥格式错误,请检查」,「获取可用模型」也无法点击;端点返回 401 时,「获取可用模型」会报告「answered 401; check the API key」。再到控制台 → API 密钥确认这把 Key 仍然可用。dsh 的密钥只写不读,要替换已保存的 Key,在表单里输入新值即可。
「获取 可用 模型」失败或 列表为空,还能用 这个 提供商吗?
能。dsh 文档说明,探测失败或列表为空时手动添加模型 ID 即可,效果完全一样。这里报 401,说明表单里的 Key 缺失或错误,因为 Router One 只在 Key 有效时回应 GET /v1/models。列表能加载时,返回的是整个目录(含生图模型),只勾选该提供商协议支持的对话 ID。
能在 DeepSeek Harness 里用 Claude 吗?
能。把 anthropic/claude-sonnet-5 这类 Claude 系列 ID 加到 Chat Completions 提供商;想用 Claude 原生消息格式,就再建一个 Anthropic Messages 提供商,API 地址填主机根地址 https://api.router.one,DeepSeek V4 的 ID 也能放在这个提供商下。不要把 Claude ID 放到 Responses 提供商,那里会返回 HTTP 400。这些请求从你的 Router One 账户扣费:按 token 从钱包扣,或者对 /pricing 上各档套餐列出的模型扣套餐额度。
还需要 DeepSeek 的 API Key 吗?
Router One 提供商不需要,它只用你的 Router One Key;目录里的 deepseek-v4.1-flash 和 deepseek-v4-flash 与其他 ID 一样跑在这把 Key 上。DeepSeek 卡片放的是 DeepSeek 官方 API 的 Key,通过那张卡片使用的模型需要它;按 dsh 文档,dsh 自带的网页搜索工具 web_search 默认也用这把 Key,没有它时,即使对话用的是 Router One 提供商的模型,dsh 也不会把 web_search 提供给模型。本指南按 dsh web 启动的 Web UI 编写,不涉及桌面版首次启动的界面;按 dsh 的架构笔记,桌面版使用自己的 profile,所以它的 cordis.patch.yml 不是 web 那一份。
能不能 直接把 内置的 DeepSeek 卡片 指向 Router One?
不建议这样做。按 dsh 文档,DeepSeek 卡片的 API 地址不是 DeepSeek 官方 API 时,卡片沿用自己的模型列表(没有改动时就是 dsh 自带的 DeepSeek 目录),也不会向该地址请求模型列表,所以其中的模型 ID 不一定与 Router One 的一致。按同一文档,dsh 自带的网页搜索工具 web_search 默认还会把这张卡片保存的 Key 发给 DeepSeek 自己的搜索接口,改卡片的 API 地址也不会改变这一点,所以不要把 Router One 的 Key 填在这张卡片里。请添加「自定义模型 API」提供商,并使用 /models 上的 ID。
为什么我 添加的 模型 没有 推理 等级 菜单?
按 dsh 文档,手动添加的模型默认不声明推理等级,所以在你添加等级之前,选择器里不出现推理等级菜单,由端点自身的默认值决定模型是否思考。如果是「自定义模型 API」提供商,可以在该模型的「模型选项」里打开「推理等级」,也可以在 cordis.patch.yml 中给这个模型加上 reasoningEfforts(写法见上一节);在 Chat Completions 提供商上还要设置 compat.supportsDeveloperRole: false。
DeepSeek Harness 能通过 网关用 哪些 模型?
选用当前目录中同时支持 DeepSeek Harness 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准;不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型,只说明它从自身配置或 GET /v1/models 读到了这个 ID,仍需验证实际调用。
能列出 模型,但调用报 400 或 404,怎么办?
先记录实际请求路径和错误消息,再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配;404 可能是请求路径或资源不存在,不能直接判定模型下线。若错误提示 must be called via,按它指明的端点调整客户端 provider,或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。
中国 大陆能 直连吗?
能。Router One 在大陆可直连、无需 VPN,dsh 从它所在的机器直接把模型请求发到 api.router.one,所以提供商配置与其他地区完全一致。dsh 本身的安装(用 npx 从 npm 仓库运行,或从 deepseek.com 下载桌面版)另行处理,与 Router One 无关。
报 401/402/403/429 怎么 排查?
先看客户端收到的响应:状态码、错误消息和 X-Request-ID 响应头。401(Key 缺失、不存在、已吊销或已过期)、402(钱包余额不足,或这把 Key 达到 maxSpend 上限)以及 Key 或账户自身限额触发的 429,都在调用任何模型之前被拒绝,不会出现在控制台 → 日志里;模型 ID 或端点写错导致的 400 / 404 也一样。401 查 Key 是否完整传入、在控制台 → API 密钥里是否仍有效;402 充值或调高这把 Key 的 maxSpend;403 请保留完整错误消息。429 请退避后重试;日志里能查到的 429 是网关重试之后上游仍返回的。保留 request_id,再按错误码速查页逐项排查。