这两年做模型应用层，我最大的体会是：工具链里最让人头疼的不是模型效果，而是怎么把不同的模型服务统一管起来。DeepSeek-Harness（后面我统一叫 dsh）就是为解决这件事来的。它本身是一个面向 DeepSeek 系模型的开发与调用工作台，支持 TUI、Web、Desktop 多种形态，但真正让我离不开它的，是它对“第三方兼容 API”的接入方式——只要服务方提供的是 OpenAI 兼容接口，基本上都能在 YAML 配置里搞定。这篇文章就从实际使用出发，完整记录 dsh 配置第三方兼容 API 的过程，包括前置概念、配置写法、多供应商路由、常见报错排查，适合正在折腾 dsh 或者准备把 DeepSeek 模型接入自己私有网关的开发者参考。
1. 配置前先搞懂：dsh 怎么看待“模型提供方”
1.1 为什么官方 API 也要走“供应商”这层抽象
很多刚接触 dsh 的人会有一个疑问：我直接用官方 DeepSeek API 不就行了吗？为什么还要在配置里单独写 provider？我第一次看到 dsh 的配置文件时也有这个反应，觉得多了一层没必要的东西。
实际用下来才明白，这一层抽象是工具链能长期稳定的关键。dsh 的设计思路和很多 Agent 框架不一样，它不会在代码里写死https://api.deepseek.com这样的地址，而是把所有外部调用都抽象成“供应商 + 模型 + 路由”三个层级。供应商负责描述“怎么连”，模型负责描述“连完之后叫什么”，路由负责描述“什么时候用哪个”。
这套设计带来的直接好处是：如果你的主力渠道是官方 API，但想加一个备用的第三方网关，只需要新增一个 provider 块，然后把某个模型的 provider 指过去，业务代码和插件完全不需要动。我在实际项目中切换过一次渠道，整个操作就是改两行 YAML，跑一次验证命令，五分钟内结束。如果没有这一层抽象，排查成本和切换成本会高很多。
1.2 第三方兼容 API 到底兼容的是什么
标题里说的“第三方兼容 API”，实践中通常指两类服务。
一类是模型网关服务：一些平台会在自己的基础设施上部署 DeepSeek 的开源模型，然后对外暴露接口，接口格式完全仿照 OpenAI 的标准。这类服务在高校、企业内部比较常见，因为数据不需要离开内网，而且可以用统一的接口管理多个模型。
另一类是商业 API 聚合平台：它们往往提供一个统一的 key，背后可以路由到多家模型服务商，有的还提供负载均衡、成本统计、缓存等能力。你在这类平台上拿到的 base_url 和 key，本质上和官方 API 相似，都是 HTTP 接口调用。
无论哪种，“兼容”的重点其实落在两处：一是 HTTP 路径和鉴权方式是否遵循/chat/completions + Bearer Token的约定；二是请求体和响应体的字段是否和 OpenAI 的 Chat Completion 格式一致。绝大多数情况下，只要供应商说自己是“OpenAI Compatible”，dsh 就能直接对接。但注意“兼容”不等于“完全一致”，供应商之间的细节差异非常大，后面我会专门讲参数层面的坑。
1.3 dsh 配置文件的整体结构，先建立一个心智模型
dsh 的配置入口是config.yaml，它通常放在三个位置：全局目录~/.dsh/config.yaml、项目目录.dsh/config.yaml、以及 profile 目录。加载优先级是项目配置优先于全局配置。整个文件的核心结构并不复杂，我第一次看文档时总结了四个顶层字段：
providers：定义外部服务的连接方式。每个 provider 至少包含type、base_url、api_key_env。models：定义 dsh 内部使用的模型别名。每个别名指向某个 provider，并可以附带参数覆盖。routes：可选，定义多个模型之间的路由优先级。retry、compat：可选，定义重试策略和兼容性参数。
可以用一种类比来理解：providers相当于“通讯录里的联系人”，models相当于“你的同事”，同事属于某个联系人，但你平时叫同事的名字而不是手机号。这样好处是，同事 A 换了手机号，你只需要更新联系人，不需要改你对他的称呼。
2. 开搞：从空环境到第一个第三方 API 请求跑通
2.1 初始化配置文件，先把 CLI 跑起来
我默认读者已经装好了 dsh，如果还没装，直接看项目 README 里的安装命令就好，这里不多说。装完第一件事不是立即写配置，而是运行dsh init。
这个命令会做几件事：检查本地环境依赖、创建默认目录结构、生成一份带注释的config.yaml模板。很多新手上来就找教程然后直接手写 config，结果因为缩进或字段名出错被反复折磨。dsh init生成的模板能帮你规避掉绝大部分“低级错误”。
dsh init运行后会看到类似输出：
[ok] dsh config initialized at /home/user/.dsh/config.yaml [ok] env file template at /home/user/.dsh/.env.example如果你的环境里有多个 dsh 配置文件（比如同时存在全局和项目级），dsh doctor会帮你检查当前生效的是哪一份、格式是否有问题、模型引用是否完整。
dsh doctor这一步相当于体检。我建议每次改完配置都跑一次，尤其是团队协作时，别人提交的配置未必和你本地环境完全一样，dsh doctor能提前暴露大部分问题。
2.2 三件事确认好再动手：base_url、密钥、可用模型名
在写配置前，我习惯先确认三件事，而且是用一张纸记下来，不丢进脑子里。
第一件事是base_url。这部分最容易出问题的是“带不带/v1”。OpenAI 兼容接口的规范路径一般是https://域名/v1/chat/completions，但很多网关平台提供的接入地址有两种风格：有的是根域名，比如https://api.example.com，dsh 会自动补全/v1；有的直接把/v1给你了，比如https://api.example.com/v1。如果你又把两者叠加，最终请求会变成/v1/v1/chat/completions，返回 404。我在配置供应商时，会先手动 curl 一下确认路径，而不是直接信平台文档。
第二件事是密钥的环境变量名。dsh 官方推荐的姿势是：不把 key 明文写在 config.yaml 里，而是通过环境变量引用。比如你在某个平台申请了一个第三方 key，建议导出为环境变量：
export THIRD_GATEWAY_API_KEY="sk-xxxxxxxx"这样在 config.yaml 里通过api_key_env: THIRD_GATEWAY_API_KEY引用。好处很明显：config.yaml 可以提交到 Git 仓库，但密钥不会泄露。我见过有人直接把 key 写进 config 然后推到公开仓库，结果几分钟之内就被爬虫扫走，血泪教训。
第三件事是“这个第三方供应商实际支持哪些模型名”。一个很容易忽视的细节是：第三方兼容 API 虽然能用 OpenAI 格式调用，但模型名不一定和 DeepSeek 官方命名一致。你可以直接请求供应商的模型列表接口：
curl https://api.example.com/v1/models \ -H "Authorization: Bearer $THIRD_GATEWAY_API_KEY"正常返回里会列出支持的所有模型 id。之前我遇到过一次情况，平台文档写的是deepseek-v4-pro，实际接口只接受deepseek-v4-pro-ctx1m，多了一个后缀，如果按文档配置，请求会直接 400。所以“以服务端返回为准”是铁律。
2.3 写配置：供应商、模型映射与默认参数
三件事确认完后，就可以打开~/.dsh/config.yaml写第一个 provider 了。下面是我实际使用过的一份最小配置，我做了脱敏处理，地址换成演示域名：
# ~/.dsh/config.yaml providers: third_gateway: type: openai_compatible base_url: https://api.example.com/v1 api_key_env: THIRD_GATEWAY_API_KEY timeout: 60 models: main: provider: third_gateway name: deepseek-v4-pro max_context_tokens: 1048576 request_kwargs: temperature: 0.7 max_tokens: 4096 flash: provider: third_gateway name: deepseek-v4-flash max_context_tokens: 1048576这里有几个字段值得逐个说。
type字段，dsh 把它默认设置为openai_compatible。如果你用的模型不是 Chat 格式，而是 Completion 格式或 Embedding 接口，type 可能不同，但绝大多数对话模型场景下用这个值就够了。
base_url字段，我建议写成“最终请求路径的公共前缀”。以 OpenAI 兼容接口来说，如果你确认请求路径是https://api.example.com/v1/chat/completions，那base_url就是https://api.example.com/v1。
models.main是一个内部别名，可以随意命名，比如你也可以叫coder、chat或者default。重要的是下面的name字段，这个才是真正发给第三方 API 的模型标识，必须和供应商服务端返回的模型 id 完全一致。
max_context_tokens这个字段虽然不直接发给供应商，但它相当于 dsh 的“安全阀”。dsh 在组织上下文时，会根据这个上限决定何时截断历史消息。第三方网关经常标注“支持 1M 上下文”，但如果你真的把一万条历史全部塞进去，要么请求超时，要么触发供应商的隐性限制。我会在后面的排障部分详细讲这个。
request_kwargs里的参数会随请求一起发给模型，比如temperature、max_tokens、top_p。注意，不同的第三方供应商对这些参数的处理方式不一样，有的供应商会忽略超出范围的参数，有的会直接报 400。
2.4 验证三条命令，确认链路真的通
配置写完后，不要立刻开始写业务代码。先用 dsh 自带的验证命令把链路打通，确保问题范围被限制在“配置层”，而不是“应用层”。
第一步，查看 dsh 是否认得你的 provider 和模型：
dsh models list正常会列出你在 models 里定义的所有别名，以及对应的 provider 和实际模型名。如果你看到某个模型后面标记了invalid或missing, 大概率是 provider 字段写错了，或者环境变量没生效。
第二步，发一条最简请求，确认能拿到正常响应：
dsh run -m main "你好，请用一句话回复。"这里-m main用的是模型别名。如果网络和鉴权都正常，你会看到模型的回复。如果返回 401 或 403，检查THIRD_GATEWAY_API_KEY是否真的导出到了当前 shell；如果返回 404，基本可以确定是base_url路径问题。
第三步，如果第二步返回了异常，用 debug 模式看原始请求响应：
dsh debug request -m main "ping" --raw这个命令会把完整的 HTTP 请求 URL、Headers（密钥会自动打码）、请求体、以及第三方返回的原始 body 打出来。我排障时几乎必开这个命令，因为它能看到错误信息里被 dsh 包装层隐藏掉的细节。比如之前遇到一个供应商返回 400，dsh 的报错只给了“bad request”，打开--raw才发现是供应商要求temperature必须是 0 到 2 之间的小数，而我的配置传了 2.5。
3. 升级配置：多供应商路由、模型别名与兼容性打磨
3.1 一个 dsh 同时接多家服务：路由优先级
当项目从“能用”进入“敢用”阶段时，单一供应商的风险就暴露出来了。某个第三方网关可能半夜扩容导致 503，也可能因为上游模型调整临时下线某个模型。我的做法是至少配置两个 provider：一个主力，一个备用，然后在 dsh 里设置路由。
下面是一个备用的多供应商配置示例：
providers: primary_gateway: type: openai_compatible base_url: https://api.example.com/v1 api_key_env: PRIMARY_API_KEY timeout: 60 backup_gateway: type: openai_compatible base_url: https://backup.example.com/v1 api_key_env: BACKUP_API_KEY timeout: 90 models: main: provider: primary_gateway name: deepseek-v4-pro max_context_tokens: 1048576 routes: - id: main-primary model: main provider: primary_gateway priority: 10 - id: main-backup model: main provider: backup_gateway priority: 1这个含义是：当 dsh 以别名main发起调用时，优先走main-primary；如果请求因为连接超时、5xx 错误而被判定为失败，dsh 会自动降级到main-backup。这里priority数字越大优先级越高。
我自己测试下来，这套机制对付“单点故障”足够用了。但要注意：dsh 的自动降级不会智能判断“这个错误是不是重试能解决”，比如你传的参数本身非法导致 400，它也会尝试降级到备用渠道，结果备用渠道大概率也返回 400，白白浪费时间。所以我一般建议把retry和routes配合使用，而不是完全依赖路由做容错。
3.2 用模型别名统一命名，避免供应商命名混乱
模型别名是我最推荐 dsh 的功能之一，原因非常现实：第三方平台提供的模型名经常变化。你今天用的是deepseek-v4-pro，明天平台可能改成了deepseek-v4-pro-20250401。如果你在业务代码里直接写模型名，升级时就要全局搜索替换。但如果你在 dsh 里设置别名，升级只改一行配置。
举个例子。我在插件里调用的模型名，统一叫coding-agent。而这个别名在不同环境指向不同的实际模型名：
models: coding-agent: provider: primary_gateway name: deepseek-v4-pro request_kwargs: temperature: 0.3本地调试时可以用便宜的deepseek-v4-flash，只要把name字段换成deepseek-v4-flash即可。插件的调用代码不动。我在多个项目里维护了同一套别名，coding-agent、light-chat、embedding-service各司其职，迁移成本被压到很低。
3.3 供应商参数差异怎么处理：从 thinking_budget 说起
第三方“兼容 API”最大的坑，不是网络，不是鉴权，而是参数层面的细微差别。最近我在群里看到很多人遇到api error: 400 the thinking_budget parameter must be a positive integer这类报错，这里面的原因值得展开讲。
DeepSeek 模型本身有推理能力，dsh 在调用时，会根据任务类型自动决定是否发送推理参数。但不同第三方平台对“推理参数”的暴露程度不一样。有的平台参考官方实现，支持thinking_budget参数，要求值为正整数；有的平台虽然底层模型支持推理，但接口层没有同步升级，你传thinking_budget过去它就不认识，直接 400。
dsh 处理这类问题主要通过两个机制。第一个是把模型声明为“是否支持推理参数”，在 models 里加一行supports_reasoning: false，dsh 就会在拼请求体时主动剔除相关字段。第二个是在compat层配置参数过滤规则，把指定供应商不支持的参数一律剥离。
providers: no_reasoning_gateway: type: openai_compatible base_url: https://api.example.com/v1 api_key_env: NO_REASONING_API_KEY compat: strip_parameters: ["thinking_budget", "reasoning_effort"]配置之后，dsh 发给这家供应商的请求里就完全不会带上这两个字段，从根源上避免了 400。需要说明的是，这并不意味着模型的推理能力被破坏了。对于不支持显式传参的供应商，模型的思考过程依然会发生，只是不能通过接口层控制预算大小而已。
另一个常见参数坑是temperature的范围不一致。官方 DeepSeek API 一般接受 0 到 2，但部分第三方网关会把它收敛到 0 到 1，如果你写了 1.5 就直接报 400。遇到这类问题，优先查看供应商自己的接口文档，而不是默认所有 OpenAI 兼容服务行为一致。
3.4 团队共享配置：profile、.env.example 与 secret 管理
项目从个人使用进入团队协作阶段后，配置管理会从“能跑”变成“可维护”。这种场景下我推荐的方式是用 profile 区分不同环境，比如dev、test、prod各一套 provider。
dsh config set --profile dev providers.primary_gateway.base_url "https://dev-api.example.com/v1" dsh config set --profile prod providers.primary_gateway.base_url "https://api.example.com/v1"实际运行 dsh 时，用环境变量指定 profile：
DSH_PROFILE=prod dsh run -m main "你好"团队协作时，.dsh/config.yaml是可以提交到 Git 的，但.env文件绝对不能提交。dsh init 会生成一份.env.example模板，里面只放变量名不放真实值。新成员拉代码后，复制一份.env.example并填入自己的 key。再配合dsh doctor检查，能大大减少“我本地明明没问题”式的沟通成本。
还有个小细节：如果你在团队里后端服务和其他成员共用同一个第三方网关，最好申请独立的 key，不要共用一个。一方面是因为并发和账号限速的问题，另一方面也是出问题时方便追踪。
4. 现实世界排错：我把最常踩的坑按症状分类整理
4.1 400 model's maximum context length 超限
这个报错信息很常见，完整提示通常类似：this model's maximum context length is 1048576 tokens. however your request used ... tokens。
看到这个错误，第一反应不应该是“模型不够强”，而是查两件事。
第一件事是你的 dsh 配置里max_context_tokens是不是设得太高。它的作用不是告诉供应商你能用多少，而是告诉 dsh“本地最多组织多少 token 的上下文”。但如果你设成了 1048576，dsh 会认为供应商完全能容纳 1M token 的输入，于是肆无忌惮地把聊天历史、工具返回、知识库片段全部塞进请求。结果你的 prompt 累计到了 1M 以上，触发了供应商的实际限制。
第二件事才是真实的请求体确实超了。解决办法不是降低模型的 max_context_tokens，而是在 dsh 里开启上下文管理策略。比如设置更小的窗口，或者让 dsh 在长对话里自动摘要历史：
dsh config set models.main.max_context_tokens 65536 dsh config set models.main.context_policy "compact"这里的context_policy: compact表示当对话历史超过窗口时，把早期消息压缩成摘要而不是直接丢弃。遇到超限报错时，先看自己当前请求实际包含多少 token。可以用 dsh 自带的估算命令：
dsh debug token-count -m main "你的完整历史消息文件"如果实际 token 远小于上限还报 400，那大概率是供应商在网关层面有更严格的最大长度限制，例如它对所有请求设了一个硬上限 128K，即便模型底层是 1M 也不放开。这种时候只能给这个 provider 单独把 max_context_tokens 调低，并在compat里忽略模型自报的 1M 上限。
4.2 503 server overloaded：服务器过载怎么处理
api error: 503 server overloaded. this is a server-side issue, usually temporary这类错误，属于第三方网关的“日常操作”。尤其是晚高峰或平台在做模型调度时，503 出现的概率会明显升高。
dsh 内置了重试机制，建议显式配置而不是用默认值。我项目里的配置如下：
retry: max_attempts: 4 backoff: exponential base_delay: 1.0 max_delay: 30.0 retry_on: [429, 500, 502, 503, 529]这个配置的含义是：最多重试 4 次，第一次等 1 秒，之后按指数退避，最长不超过 30 秒；对 429、503 这类负载类错误做重试。这里有一个经验之谈：不要把max_attempts设得太大，4 到 6 次已经足够。我见过有人设置 10 次重试，结果高峰期不仅没等到成功，反而把第三方网关打得更满，甚至触发对方的限流封禁。
如果单请求重试已经配置好但仍然频繁 503，问题很可能出在“并发”——你的 dsh 或上层 Agent 同时发起了太多请求。dsh 支持在 config 里限制 max concurrency：
execution: max_concurrency: 8把它调低到 4 或 2，再观察 503 频率，往往会明显下降。这个思路和数据库连接池的限流逻辑一样：不是服务端不给你处理，是你的瞬时请求淹没了它。
4.3 thinking_budget 必须是正整数 / 参数非法
前面讲过，典型的报错是the thinking_budget parameter must be a positive integer。除了供应商不支持之外，还有一种情况是你显式或隐式传了不合理的值。比如某个插件在调用模型时，把 thinking_budget 设成了 0，如果供应商要求严格正整数，就会直接拒绝。
这类问题排查时，我建议区分两个层面。
第一是 dsh 自身的参数校验。dsh 一般不要求 thinking_budget 一定大于 0，但某些插件在透传用户输入时，可能把“未设置”错误地转成了 0。遇到这种情况，可以检查插件的配置面板，看有没有把 thinking_budget 显式暴露出来。
第二是供应商的兼容层。如果你确认 dsh 和插件都没有主动传这个值，错误却依然出现，可能是供应商的兼容层在收到底层模型返回时自行构造了 thinking_budget，然后在请求结束校验时误报。这种情况属于供应商的问题，最快的解决办法是换货或者联系服务商，不值得在不稳定的环境上浪费时间。
4.4 插件加载失败 / plugin tree failed to load
dsh 的一个特色玩法是插件系统，社区里有大量实用插件，可以通过 marketplace 一键安装。但插件装多了之后，偶尔会看到这样的报错：
dsh: plugin tree failed to load: failed to apply loader entry include (cordi...这类报错本质上是插件加载器在构建插件树时，某个入口文件格式错误或引用了不存在的本地路径。我排查时按三步走。
第一步，确认插件版本和 dsh 版本兼容。dsh 迭代速度快，插件作者未必每次都跟上，版本不匹配是最常见原因。
dsh plugin list dsh version第二步，重建插件加载缓存。很多“plugin tree failed”是因为之前安装中断导致缓存里的引用信息不完整。
dsh plugin repair如果 repair 没有效果，可以直接手动清理插件缓存目录，再重新安装。注意先备份你自己的插件配置，避免清理时把自定义配置也删掉。
rm -rf ~/.dsh/plugins/cache dsh plugin update --all第三步，定位到具体出错的插件。报错信息里如果带了插件名，比如cordi...这种被截断的插件 id，可以先临时禁用这个插件再启动。
dsh plugin disable <plugin-id>如果禁用后 dsh 正常，说明问题集中在这个插件与当前环境的兼容性上，建议优先联系插件维护者，或者查找社区是否有人提交过类似 issue。
4.5 局域网访问和 Desktop 连接问题
dsh 有 Web 和 Desktop 形态，很多人喜欢在桌面端写 prompt，然后让 dsh 在远程服务器上执行。这里最常见的问题是把 dsh 的 Web 服务启动在本机回环地址上，导致局域网内其他设备访问不了。
如果是想临时在局域网里访问 dsh 的 Web UI，启动时加上主机参数：
dsh web --host 0.0.0.0 --port 8080然后在同一局域网的另一台机器浏览器里输入http://服务器IP:8080即可。但这里必须提醒：把自己本机的服务暴露到局域网，相当于打开了大门，如果你的 dsh 环境里配置了第三方 API 的密钥，别人访问到 Web UI 后是有可能读取到配置信息的。dsh 在--host 0.0.0.0模式下会默认要求 Token 认证，启动时设置一个 token：
dsh web --host 0.0.0.0 --port 8080 --auth-token your-access-token访问时在 Web UI 的登录框里填这个 token。不要嫌麻烦，我见过太多人图省事直接裸奔，结果内网里一个扫描脚本就把配置扫走了。
Desktop 客户端连接远程 dsh 服务时，如果在日志里看到类似permission denied while trying to connect to the docker api at unix:///var/run/docker.sock，这通常不是 dsh 本身的问题，而是当前用户没有权限访问 Docker 的 Unix Socket。把当前用户加入 docker 用户组，或者用 root 运行 dsh，问题就解决了。不过从安全角度，更推荐前者。
4.6 常见错误速查表
| 错误特征 | 可能原因 | 排查顺序 |
|---|---|---|
| 401 Unauthorized | API key 错误或环境变量未生效 | 检查 env 是否导出；检查 key 是否有效 |
| 404 Not Found | base_url 路径错误，可能重复拼了 /v1 | curl 手动请求确认正确路径 |
| 400 maximum context length | 上下文超过供应商实际限制 | 调低 max_context_tokens；开启 compact 策略 |
| 400 thinking_budget | 供应商不支持或参数值非法 | compat 里 strip 该参数；确认参数为正整数 |
| 429 Too Many Requests | 触发限流或并发过高 | 配置重试；调低 max_concurrency |
| 503 server overloaded | 供应商负载高 | 指数退避重试；切备用路由 |
| plugin tree failed | 插件版本不兼容或缓存损坏 | 升级插件；repair；清缓存 |
| permission denied / docker.sock | dsh 无权限访问 Docker | 用户加 docker 用户组或调整权限 |
这个表格可以贴在项目文档里，团队遇到问题先按表格排查，能省掉大量重复沟通时间。
5. 最后分享一点个人经验
在写这篇记录之前，我刚帮团队把一个内部工具从单一官方 API 切换到了双供应商路由架构，过程中又把 dsh 的配置从零到一捋了一遍。这里说几个踩过坑之后沉淀下来的习惯。
第一，每一个新的第三方 provider 接入，我都坚持先 curl 再写配置。curl 命令虽然原始，但它能最快把问题定位在网络层、鉴权层还是参数层，一旦确认 curl 能通，后面 dsh 配置里的问题基本是字段名写错或格式不对，排起来很快。
第二，config.yaml里不要写死任何 magic value，比如把某个模型默认的 temperature 写进业务代码。统一放在models.<alias>.request_kwargs里，团队其他人看配置就能理解当前默认行为，不需要翻代码。时间久了，你会感谢这个习惯。
第三，重视 dsh 的 debug 命令。很多第三方兼容 API 的报错在 SDK 层会被包装得面目全非，只有看原始响应才能知道供应商到底在抱怨什么。我现在遇到任何 API 异常，第一反应永远是打开dsh debug request --raw，而不是去改业务代码。
dsh 这套工具还在快速迭代，插件生态也在变，但“供应商 + 模型别名 + 路由 + 兼容层”这套配置哲学短期内不会过时。搞清楚这些，无论以后第三方平台怎么调整，你都能以不变应万变。
