> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DeepSeek Harness

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

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

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

[YouTube video player](https://www.youtube.com/embed/JnsoAykX2Ks?si=jT98wdBZMfjwWL73)

## 快速结论

接入需要以下四项配置：

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

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

![DeepSeek Harness Models 页面显示 AIHubMix 已配置](https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/01-models-aihubmix-configured.png?fit=max\&auto=format\&n=pPBGbuf_Qo9bMEMd\&q=85\&s=9a11531222d056d05d6ee6030eddb595)

## 需要准备什么？

开始前需要：

* 一个可用的 [AIHubMix API Key](https://console.aihubmix.com/workspaces/default/keys)
* Node.js 22（22.19.0 或更高版本）或 Node.js 24 及以上
* 能访问 npm Registry 和 `https://aihubmix.com` 的网络环境

检查 Node.js 和 npm：

```bash theme={null}
node --version
npm --version
```

## 如何安装 DeepSeek Harness？

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

```bash theme={null}
npm install -g @deepseek-ai/dsh
```

确认安装结果：

```bash theme={null}
dsh --version
```

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

## 如何启动 Web UI？

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

```bash theme={null}
npx @deepseek-ai/dsh web --port 3080
```

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

```bash theme={null}
dsh web --port 3080
```

浏览器打开：

```text theme={null}
http://127.0.0.1:3080
```

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

## 如何配置 AIHubMix 提供方？

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

![DeepSeek Harness 自定义提供方配置表单](https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/03-add-custom-provider.png?fit=max\&auto=format\&n=pPBGbuf_Qo9bMEMd\&q=85\&s=e5f609447d3c979a65235ecc1b0382d0)

| 字段 | 推荐值 | 说明 |
| - | - | - |
| 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`，最终请求地址为：

```text theme={null}
https://aihubmix.com/v1/chat/completions
```

> [!WARNING]
>
> Base URL 中不要填写完整的 `/chat/completions` 路径。

## 添加 auto 或其他模型

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

![DeepSeek Harness 从 AIHubMix 获取可用模型列表](https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/07-discover-models.png?fit=max\&auto=format\&n=pPBGbuf_Qo9bMEMd\&q=85\&s=7fdeeb8c4ba8400910bcabe1e7b50a78)

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

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

![DeepSeek Harness 手动添加 AIHubMix auto 模型](https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/04-add-auto-model.png?fit=max\&auto=format\&n=pPBGbuf_Qo9bMEMd\&q=85\&s=0c1e93d53cf9840d5c5885dc192b0d80)

## 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`

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

```yaml theme={null}
- 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
```

> [!WARNING]
>
> 两个条目缺一不可。只写 `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 前设置密钥：

```bash theme={null}
export AIHUBMIX_API_KEY='sk-***'
dsh web --port 3080
```

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

![DeepSeek Harness AIHubMix 提供方详细配置](https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/02-aihubmix-provider-details.png?fit=max\&auto=format\&n=pPBGbuf_Qo9bMEMd\&q=85\&s=a18af7f6409268331dcb4ddfa7d78568)

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

## 选择模型并验证对话

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

![DeepSeek Harness 模型选择器中的 Auto 模型](https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/05-select-auto-model.png?fit=max\&auto=format\&n=pPBGbuf_Qo9bMEMd\&q=85\&s=82577ac5295eebc0ef6e4945f75f5ffe)

发送一条最小测试消息：

```text theme={null}
Reply with exactly: AIHubMix connection successful
```

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

![DeepSeek Harness 通过 AIHubMix 返回测试响应](https://mintcdn.com/aihubmix/pPBGbuf_Qo9bMEMd/public/en/deepseek-harness/06-live-chat-success.png?fit=max\&auto=format\&n=pPBGbuf_Qo9bMEMd\&q=85\&s=f5fe3902c1c2f57b84b34b739b258394)

## 运行 headless 测试

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

```bash theme={null}
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：

```bash theme={null}
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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.