DeepSeek Harness

在 DeepSeek Harness 中接入 AIHubMix：安装 npm 发布版、配置 OpenAI 兼容提供方、添加 auto 或指定模型并验证 Agent 请求。

DeepSeek Harness（命令名 dsh）是 DeepSeek 开源的编码 Agent Harness，支持工作区、终端、文件编辑、Skills、计划和 Web UI。它可以通过 OpenAI Chat Completions 兼容接口连接 AIHubMix。

本文基于 DeepSeek Harness 0.2.0-rc.2 编写，该版本为截至 2026 年 10 月 18 日的最新版本。与 0.1.0-rc.6 相比，版本变化较大，配置位置和界面均已更新。Harness 仍处于开发者预览阶段，后续版本的界面和字段可能变化。

​

快速结论

接入需要以下四项配置：

配置项	值
Provider ID	aihubmix
Base URL	https://aihubmix.com/v1
API protocol	openai-completions
API key environment variable	AIHUBMIX_API_KEY

完成后，Models 页面会显示已配置的 AIHubMix 提供方。

​

需要准备什么？

开始前需要：

• 一个可用的 AIHubMix API Key
• Node.js 22（22.19.0 或更高版本）或 Node.js 24 及以上
• 能访问 npm Registry 和 https://aihubmix.com 的网络环境

检查 Node.js 和 npm：

node --version
npm --version

​

如何安装 DeepSeek Harness？

直接安装 npm 发布版，无需克隆源码：

npm install -g @deepseek-ai/dsh

确认安装结果：

dsh --version

若终端提示 dsh: command not found，运行 npm config get prefix，并确认该目录下的 bin 已加入 PATH。

​

如何启动 Web UI？

在准备作为工作区的项目目录中运行。官方推荐使用 npx 启动：

npx @deepseek-ai/dsh web --port 3080

已全局安装时，也可以运行：

dsh web --port 3080

浏览器打开：

http://127.0.0.1:3080

首次进入时选择或添加工作区，Harness 才能在该目录中运行 Agent 请求。

​

如何配置 AIHubMix 提供方？

打开 Settings → Models → Add model provider，将卡片切换到 Custom model API，然后填写以下内容：

字段	推荐值	说明
Provider ID	aihubmix	小写标识；若已占用，可使用 aihubmix-gateway
Display name	AIHubMix	模型选择器中显示的名称
Base URL	https://aihubmix.com/v1	必须包含 /v1
API protocol	openai-completions	使用 OpenAI Chat Completions 兼容协议
API key	你的 AIHubMix API Key	Harness 将其保存为凭据，不会在设置页回显明文

Harness 会在 Base URL 后请求 /chat/completions，最终请求地址为：

https://aihubmix.com/v1/chat/completions

Base URL 中不要填写完整的 /chat/completions 路径。

​

添加 auto 或其他模型

填写 Base URL 和 API Key 后，在 Model catalog 中点击 Fetch available models。Harness 会请求 GET https://aihubmix.com/v1/models 并显示当前可用的模型 ID。

首次验证可只添加 auto，显示名称填写 Auto。auto 是 AIHubMix 的自动模型选择入口，适合先验证连接。

需要使用指定模型时，在获取到的列表中勾选对应模型，然后点击 Add selected。只有已经加入当前 Provider 模型目录的条目会出现在图形界面的模型选择器中。

​

auto 与指定模型对比

选择	适用情况
auto	首次连通性验证，或希望由 AIHubMix 自动选择模型
指定模型 ID	需要固定模型能力、版本或可复现结果

两种方式使用相同的 Provider、Base URL 和 API Key。切换模型不需要重新创建提供方。

​

使用环境变量保存 API Key

开发机和 CI 环境可以让 Harness 通过环境变量读取 API Key，配置写在 profile 文件中。Web UI 使用 web profile，headless 测试使用 headless profile，两者的文件路径分别为：

• $DSH_HOME/profiles/web/cordis.patch.yml
• $DSH_HOME/profiles/headless/cordis.patch.yml

两个文件的内容相同，文件内容如下：

- id: llm-pi-ai
  config:
    providers:
      aihubmix:
        apiKeyEnv: AIHUBMIX_API_KEY
        api: openai-completions
        baseURL: https://aihubmix.com/v1
        models:
          - id: auto
- id: agent-default-model
  config:
    provider: aihubmix
    model: auto

两个条目缺一不可。只写 llm-pi-ai 而不写 agent-default-model 时，headless 仍会使用默认的 deepseek-official，并报 MISSING_CREDENTIAL。

旧版本使用 $HOME/.dsh/settings.yaml 保存配置，0.2.0 起不再使用该文件。DSH 0.2.0 首次启动时会把旧文件迁移为 profile 配置，并将原文件改名为 settings.yaml.imported。迁移当次运行可能报 MISSING_CREDENTIAL，再运行一次即可。

启动 Harness 前设置密钥：

export AIHUBMIX_API_KEY='sk-***'
dsh web --port 3080

密钥来自启动环境时，设置页会显示只读提示，不会展示真实值。

修改环境变量后需要重启 Harness。

​

选择模型并验证对话

关闭设置窗口，点击输入框右下角的模型选择器，然后选择 Auto 或已添加的指定模型。

发送一条最小测试消息：

Reply with exactly: AIHubMix connection successful

收到预期响应后，说明 Harness、OpenAI Chat Completions 兼容接口和 AIHubMix 的连接正常。

​

运行 headless 测试

无需 Web UI 时，可运行以下命令。该命令使用 headless profile，需要 $DSH_HOME/profiles/headless/cordis.patch.yml 中已写入上面的两个条目。

export AIHUBMIX_API_KEY='sk-***'
dsh --profile headless \
  'Reply with exactly DSH_AIHUBMIX_OK and do not use tools.'

成功时会输出 DSH_AIHUBMIX_OK。

​

常见问题

​

为什么显示 MISSING_CREDENTIAL？

Harness 没有读取到可用的配置。请确认 profile 中两个条目都已写入，并确认环境变量 AIHUBMIX_API_KEY 已设置，然后从同一个终端启动 Harness：

test -n "$AIHUBMIX_API_KEY" && echo configured

​

为什么获取模型返回 401？

检查 API Key 是否有效，以及复制时是否包含空格或换行。模型发现请求使用 Bearer 认证。

​

为什么模型选择器只有 Auto？

模型选择器只显示当前 Provider 模型目录中已经注册的模型。进入 Settings → Models → AIHubMix → Edit，在 Model catalog 中点击 Fetch available models，勾选需要的模型后点击 Add selected。

​

为什么出现 UNKNOWN_MODEL？

当前 Provider 的模型目录中没有该模型 ID。模型 ID 区分大小写，应使用模型发现接口返回的准确值。

​

为什么请求连接超时？

检查 DNS、公司网络和本地代理。DSH 会自动读取 HTTP_PROXY 和 HTTPS_PROXY 环境变量，如需让特定地址不经过代理，可设置 NO_PROXY。若浏览器使用系统代理而终端没有使用，请为启动 dsh 的终端配置 HTTP_PROXY 和 HTTPS_PROXY。

​

安全建议

• 不要把 API Key 写入 Git 仓库、教程截图或共享脚本
• 优先使用 Harness 凭据存储或 AIHUBMIX_API_KEY 环境变量
• 排错时不要打印完整 API Key
• CI 中使用平台的 Secret 管理功能注入环境变量

---

更新时间：2026-10-18