DeepSeek Harness接入大模型网关：配置步骤与常见问题排查

DeepSeek Harness 连上网关后可以聊天，却不能稳定执行工具，是接入时值得重点区分的两种状态。文字回复只证明请求到达了模型；一个编程任务还需要流式输出、工具参数、执行结果回传和后续推理共同配合。

先分清两个“网关”

本文讨论的是模型请求经过的公司网关或兼容 API 服务。Harness 内部的界面通信接口属于另一层，不能把内部 RPC 地址填进模型 Base URL。先画出实际链路：Harness → Provider 配置 → 模型网关 → 上游模型，后续排查都沿这条链路进行。

Harness 当前处于开发者预览阶段，配置应与安装版本对应。不要混用旧教程中的字段与新界面保存的设置。

第一步：启动并建立最小连接

在已准备好 Node.js 与 npm 的环境中，可通过以下官方入口启动 Web 界面。初次运行可能需要下载软件包；团队环境应在验证后记录实际安装版本。

npx @deepseek-ai/dsh web

打开启动输出提供的本机地址，在模型设置中增加自定义 Provider。准备五项信息：自定义标识、Base URL、接口协议、凭据和真实模型 ID。Provider 名称可由你定义，模型 ID 必须与网关端一致。

协议必须与接口匹配

自定义 Provider 提供 Chat Completions、Responses、Anthropic Messages 等协议选择。一个 Provider 对应一种协议；同一网关支持多种协议时，应分别配置，避免用一种协议解析另一种协议的返回。

一份可对照的配置结构

下面为结构示例，地址和模型名都是占位内容，不能原样请求。先在界面完成配置，再对照实际生成的文件检查，更便于适配预览版变化。

llm-pi-ai:
  providers:
    team-gateway:
      apiKeyEnv: TEAM_GATEWAY_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: your-model-id

这里的 apiKeyEnv 是环境变量名称，实际凭据应提供给运行 Harness 的进程。终端、桌面启动器和服务进程可能继承不同环境，排查时检查变量是否存在即可，不要把密钥打印进日志。

第二步：分四层验证功能

1. 普通文本：发送一句短问题，确认状态码和模型选择。
2. 流式响应：要求一段较长回答，观察是否持续返回，还是到结束时一次性出现。
3. 单次工具：在测试目录里要求读取一个已知文件，确认模型真的发出工具调用。
4. 闭环任务：让它依据文件内容做一个小修改，再读取结果核对，确认工具结果被正确送回模型。

常见错误应该先查哪里

• 401 或 403：检查密钥、网关授权与模型访问范围，不要先改提示词。
• 404：核对网关要求的是基础路径还是完整接口路径，以及模型 ID 是否存在。
• 能聊天、不能执行：检查模型与协议的工具调用支持，保留脱敏后的工具请求及返回。
• 输出停顿：检查网关缓冲、流式转发和超时；先用短任务排除任务本身耗时。
• 反复重试：同时观察客户端与网关重试，避免多层重试扩大请求量。

不要用配置声明替代能力验证

把模型标成支持图片，不会让一个文本模型获得视觉能力；把上下文窗口写大，也不会增加上游服务实际允许的输入。只有端到端测试通过，才应把相应能力开放给正式任务。

建议保留一份接入记录

记录 Harness 版本、网关协议、模型 ID、四层测试结果和失败样例，不保存真实密钥。以后任一组件升级，先重跑这组小任务，就能判断变化来自模型、网关还是客户端。