# DeepSeek Harness 接入 OfoxAI 配置指南

Source: https://ofox.io/zh/docs/integrations/deepseek-harness

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness?utm=ofox_ai)（命令名 `dsh`）是 DeepSeek 官方开源的 agent harness，采用「一切皆插件」架构 —— 模型、工具、技能、会话、沙箱、界面全部是可替换的插件。它默认调用 DeepSeek 官方 API，把其中的模型插件指向 OfoxAI 之后，同一套 harness 就能使用 100+ 模型。

> **此工具目前仍需手动配置。** Ofox Desktop 暂不自动配置 DSH。如果你还在 Apple 芯片 Mac 上使用 Codex、Claude Code、Gemini CLI、OpenCode、OpenClaw 或 Hermes，[Ofox Desktop 可以检测并配置这些已支持的工具](https://ofox.io/zh/desktop)。

dsh 处于开发者预览阶段，官方明确说明会有破坏性变更。本文基于 `@deepseek-ai/dsh` 0.1.2-rc.1 编写。

## 配置步骤

### 1. 安装 dsh

先安装 Node.js。dsh 通过 npm 分发，包名 `@deepseek-ai/dsh`，安装后提供 `dsh` 命令。

**macOS**

```bash
npm install -g pnpm          # 已安装可跳过
pnpm add -g @deepseek-ai/dsh
dsh --version
```

pnpm 的全局 bin 目录需要在 `PATH` 上，用 `pnpm bin -g` 可以查到具体路径。

**Linux**

```bash
npm install -g pnpm          # 已安装可跳过
pnpm add -g @deepseek-ai/dsh
dsh --version
```

pnpm 的全局 bin 目录默认在 `~/.local/share/pnpm`，需要加入 `PATH`。

**Windows**

```powershell
npm install -g pnpm
pnpm add -g @deepseek-ai/dsh
dsh --version
```

pnpm 的全局 bin 目录默认在 `%LOCALAPPDATA%\pnpm`，需要加入 `PATH`。使用 WSL 的话按 Linux 步骤操作。

安装过程中 pnpm 可能提示 `Ignored build scripts: node-pty, koffi …`，可以忽略 —— 这两个依赖自带各平台预编译二进制，不需要本地编译。

不想全局安装也可以直接试跑：

```bash
npx @deepseek-ai/dsh web
```

### 2. 配置 OfoxAI 供应商

dsh 的配置根目录是 `$DSH_HOME`，macOS / Linux 默认 `~/.dsh`，Windows 默认 `%USERPROFILE%\.dsh`。以下两种方式任选其一。

**Base URL 按网络环境选择**：国际网络用 `api.ofox.io`，中国大陆网络用 `api.ofox.io`。两者是同一套服务的镜像，API Key 通用，路径都是 `/v1`。

**Web UI 配置（推荐）**

```bash
dsh web
```

终端会打印一个带 token 的地址（默认 `http://127.0.0.1:3080`）并自动打开浏览器。点左下角的 **设置**：

![打开 dsh 设置](https://ofox.io/screenshots/deepseek-harness/01-settings.png)

在左侧切到 **模型**：

![切到模型设置](https://ofox.io/screenshots/deepseek-harness/02-models.png)

内置的 `deepseek-official` 是 DeepSeek 官方直连，走 OfoxAI 要新建一个自定义提供方 —— 点 **添加自定义提供方**：

![添加自定义提供方](https://ofox.io/screenshots/deepseek-harness/03-add-custom-provider.png)

按下表填写，然后点 **获取可用模型**：

| 字段 | 填入 |
|---|---|
| Provider ID | `ofox` |
| 显示名称 | `ofox` |
| API 地址 | `https://api.ofox.io/v1` |
| API 协议 | `openai-completions` |
| API 密钥 | 你的 OfoxAI API Key |

![填写自定义提供方](https://ofox.io/screenshots/deepseek-harness/04-provider-form.png)

截图里的 **API 协议** 是 `openai-responses`，那是表单的默认值，只有 DeepSeek 系模型能用；选 `openai-completions` 才对整个模型目录通用。

勾选要用的模型，点 **添加所选**，回到表单后点 **创建提供方**：

![勾选要添加的模型](https://ofox.io/screenshots/deepseek-harness/05-select-models.png)

回到会话界面。首次使用需要先选一个工作区（就是 dsh 可以读写的项目目录），之后在输入框右下角的模型选择器里，就能看到 `ofox` 分组下的全部模型：

![在会话里选择 ofox 的模型](https://ofox.io/screenshots/deepseek-harness/06-model-picker.png)

API Key 会写入 `$DSH_HOME/.credentials.yaml`（仅当前用户可读），供应商配置写入 `$DSH_HOME/settings.yaml`，保存后立即生效，无需重启。

**直接编辑配置文件**

```yaml filename="~/.dsh/settings.yaml"
llm-pi-ai:
  providers:
    ofox:
      apiKeyEnv: OFOX_API_KEY
      api: openai-completions
      baseURL: https://api.ofox.io/v1
      models:
        - id: deepseek/deepseek-v4-pro-0813
          name: DeepSeek V4 Pro
        - id: google/gemini-3.8-flash
          name: Gemini 3.8 Flash
    ofox-anthropic:
      apiKeyEnv: OFOX_API_KEY
      api: anthropic-messages
      baseURL: https://api.ofox.io/anthropic
      models:
        - id: anthropic/claude-sonnet-5
          name: Claude Sonnet 5
          contextWindow: 1000000
agent-default-model:
  provider: ofox
  model: deepseek/deepseek-v4-pro-0813
```

`llm-pi-ai` 是 dsh 的多供应商模型插件，`providers` 下的每个键就是一个可被请求选中的路由名。上面配了两条：OpenAI 兼容协议走 `ofox`，Anthropic 原生协议走 `ofox-anthropic`，两条共用同一个 API Key。

协议和端点要配套：

| `api` | `baseURL` | 适用模型 |
|---|---|---|
| `openai-completions` | `https://api.ofox.io/v1` | 通用，整个模型目录都能走 |
| `openai-responses` | `https://api.ofox.io/v1` | 仅部分模型，DeepSeek 系可用 |
| `anthropic-messages` | `https://api.ofox.io/anthropic` | Anthropic 系模型 |

Anthropic 的模型两条路都行：`openai-completions` 或本节这样的 `anthropic-messages` 原生路由。但**不要**把它们放进 `openai-responses` 路由，那样会静默返回空回复。

模型 ID 必须带供应商前缀，例如 `anthropic/claude-sonnet-5.5`，只写 `claude-sonnet-5.5` 会被拒绝。完整目录见[模型广场](https://ofox.io/zh/models)。

### 3. 设置 API Key

`apiKeyEnv` 填的是凭据名而不是明文 Key。dsh 按「启动时的环境变量 → `$DSH_HOME/.credentials.yaml` → 项目目录 `.env` → 家目录 `.env`」的顺序解析。用 Web UI 配过的话 Key 已经在凭据文件里，可以跳过这一步。

**macOS**

```bash filename="~/.zshrc"
export OFOX_API_KEY=<你的 OFOXAI_API_KEY>
```

**Linux**

```bash filename="~/.bashrc"
export OFOX_API_KEY=<你的 OFOXAI_API_KEY>
```

**Windows**

```powershell
# 仅当前会话生效
$env:OFOX_API_KEY = "<你的 OFOXAI_API_KEY>"

# 永久生效（重开终端后可用）
setx OFOX_API_KEY "<你的 OFOXAI_API_KEY>"
```

### 4. 验证

```bash
dsh --profile headless "只回复两个字：可用。不要调用任何工具。"
```

输出 `可用` 就说明模型层已经走通 OfoxAI。日常使用可以启动 Web 界面（`dsh web`），或者用 `dsh --profile headless "run the tests"` 跑完单次任务后退出。

## 三平台差异

配置文件的内容三平台完全一致，只有路径和环境变量写法不同。

| | macOS | Linux | Windows |
|---|---|---|---|
| 配置根目录 `$DSH_HOME` | `~/.dsh` | `~/.dsh` | `%USERPROFILE%\.dsh` |
| API Key 持久化 | `~/.zshrc` | `~/.bashrc` | `setx` |
| Shell 工具沙箱 | Bash | Bash | PowerShell（Bash 沙箱自动禁用） |

## 常见问题

**`TIMEOUT: Request timed out.`** — dsh 是 Node 应用，不读取 `http_proxy` / `all_proxy` 环境变量，系统代理能连通不代表 dsh 能连通。如果 `baseURL` 指向的域名在你的网络下不可达，中国大陆用户请改用镜像 `https://api.ofox.io/v1`。

**`MISSING_CREDENTIAL`** — `apiKeyEnv` 写的凭据名没解析到值。确认环境变量在**启动 dsh 的那个终端**里已经生效，或者 Key 已经存进 `$DSH_HOME/.credentials.yaml`。另一种情形是选错了模型：内置的 `deepseek-official` 即使没配 Key，它的模型也照样列在模型选择器里，名字和自定义路由的很像，注意别选到它。

**回复是空的，也不报错** — 这个组合最容易踩：`api: openai-responses` 配 Anthropic 系模型时，请求会正常结束（`finish reason: stop`）但内容为空。把该模型挪到 `openai-completions` 路由，或挪到指向 `https://api.ofox.io/anthropic` 的 `anthropic-messages` 路由。

**`INVALID_REQUEST` / 400 `endpoint_not_supported`** — 报文里会写 `Model '…' does not support the /v1/responses endpoint on this platform. Please use /v1/chat/completions instead.`，Google、Qwen 等模型走 `openai-responses` 时就是这样。同样把 `api` 改成 `openai-completions`。

**插件加载失败、提示路由重复** — 同一个路由名被注册了两次，检查 `$DSH_HOME/cordis.patch.yml` 和 `settings.yaml` 里是否都定义了 `ofox`。

## 进阶：用 patch 层配置

`settings.yaml` 改的是运行时用户设置，改完下一个请求就生效。如果要改插件装配本身（替换或禁用某个插件），用 patch 层 `$DSH_HOME/cordis.patch.yml`：

```yaml filename="~/.dsh/cordis.patch.yml"
- id: llm-pi-ai
  config:
    providers:
      ofox:
        apiKeyEnv: OFOX_API_KEY
        api: openai-completions
        baseURL: https://api.ofox.io/v1
- id: agent-default-model
  config:
    provider: ofox
    model: deepseek/deepseek-v4-pro-0813
```

用 `dsh web --dump-config` 可以打印合成后的完整插件树，确认配置有没有生效。

## 推荐模型

推荐模型请参考 [模型广场](https://ofox.io/zh/models)。

dsh 处于快速迭代阶段，配置字段可能随版本变化，请同时参考 [DeepSeek Harness 官方仓库](https://github.com/deepseek-ai/deepseek-harness?utm=ofox_ai)。