# DeepSeek Harness：开源编程 Agent 安装指南

> DeepSeek Harness 是 DeepSeek 开源的编程 Agent。本文先讲清它是什么，再逐步完成安装，并通过 OpenAI 兼容 Provider 接入 OmniaKey。

- Canonical HTML: https://omniakey.com/zh/blog/deepseek-harness-omniakey-setup
- Markdown: https://omniakey.com/zh/blog/deepseek-harness-omniakey-setup.md
- Published: 2026-08-14 (updated 2026-09-18)
- Author: Kiki, COO at OmniaKey
- Language: zh
- Category: API setup
- Reading time: 10 min
- All posts: https://omniakey.com/blog/llms.txt

---

DeepSeek Harness 是 DeepSeek AI 开源的编程 Agent 和 Agent 运行时。它负责模型外围的循环、工具、工作区访问、会话、权限和界面；真正提供智能的模型仍来自 API Provider。本文先介绍 DeepSeek code harness 能做什么，再通过官方自定义 Provider 流程把它接入 OmniaKey。

> **事实核验日期：2026 年 9 月 18 日。** 安装命令、默认端口、Provider 字段、模型发现方式、密钥存储和 developer preview 风险，已交叉核对 DeepSeek 官网、官方文档、GitHub README 与当前源码。OmniaKey Base URL 和模型 ID 已对照当前 API 文档及模型目录。我们实际启动了 `dsh`，并检查了配置页面；没有运行付费模型 benchmark。

## DeepSeek Harness 是什么？

DeepSeek Harness 简称 `dsh`，它不是一个新大模型，而是把模型变成 Agent 的软件层。它让模型能够理解工作区、调用工具、编辑文件、执行命令、保存会话，并在敏感操作前申请授权。

它最核心的设计是 **everything is a plugin（万物皆插件）**。该项目把 Harness 建在 Cordis 插件系统上，因此模型、工具、Skills、会话、沙箱、存储、循环、调度乃至 UI，都可以通过配置替换或重新组合。

|能力|对实际使用意味着什么|
|-|-|
|插件优先的运行时|可以替换或扩展模型、工具、存储、会话等 Agent 能力|
|可追踪会话|在一份 append-only 日志里检查提示词、推理、工具调用与结果、上下文注入和 Subagent 调度|
|多种运行模式|Standard、Code、Minimal 和 Creator 模式提供不同的工具与编排能力|
|本地 Web UI|npm 命令默认在 `http://127.0.0.1:3080` 提供界面|
|自定义 Provider|不修改 Harness 源码即可接入公司网关或自建的 OpenAI 兼容端点|

这条可追踪事件流不只是聊天记录。官方文档说明，resume、fork、search 和 replay 都建立在同一份会话日志上。当 Agent 在回答前做了多轮工具调用时，这种设计很适合排查过程。

### 它不是什么

- 它不是 DeepSeek V4 Pro，也不是任何模型。Harness 与模型是两个独立层。
- 它目前不是稳定生产版。官方资料明确标为 **developer preview**，并警告后续会有破坏兼容性的改动。
- 通过 npm 快速启动时，它不是云端托管的编程服务；Web UI 默认只绑定本机 loopback。
- 开源不等于模型推理免费。代码使用 MIT License，API 调用仍由你配置的 Provider 计费。

## DeepSeek Harness 接入 OmniaKey 的配置

先给出完整配置，后面再逐步操作：

|字段|填写值|
|-|-|
|Provider ID|`omniakey`|
|Display name|`OmniaKey`|
|Base URL|`https://api.omniakey.com/v1`|
|API protocol|`openai-completions`|
|API key|在 OmniaKey Dashboard 单独创建的 key|
|起步模型|`deepseek-v4-pro` 或 `deepseek-v4-flash`|

Base URL 必须包含 `/v1`。不要只填裸域名，不要重复成 `/v1/v1`，也不要填完整的 `/chat/completions` 请求路径；该工具会自己拼接操作路径。

## 第 1 步：安装并启动 DeepSeek Harness

安装 Node.js，在你希望 Agent 看到的项目目录打开终端，然后运行官方 npm 快速启动命令：

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

当前版本默认把 Web UI 启动在：

```text
http://127.0.0.1:3080
```

如果 `3080` 端口已被占用，Web profile 支持改用其它端口：

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

启动 `dsh` 时所在的目录会成为默认文件系统位置，但你仍需在界面里新增并选中 workspace，输入框才可用。请明确选择仓库；在当前权限策略允许时，Agent 会获得文件和 shell 工具。

## 第 2 步：创建一把独立的 OmniaKey API Key

打开 [OmniaKey API Keys Dashboard](https://omniakey.com/zh/dashboard/tokens)，为该工具单独创建一把 key。相比多个工具共用一把凭据，独立 key 更容易设置额度、轮换、撤销和审计。

不要把明文 key 放进代码仓库、shell 历史、截图、Issue 或聊天记录。Web UI 会把保存后的 key 当作 write-only 数据：官方文档说明，密钥保存在 `$DSH_HOME/.credentials.yaml`，settings 只保存凭据引用，页面只能拿到脱敏描述。

## 第 3 步：把 OmniaKey 添加为自定义 Provider

全新安装时，先在 **Internal Testing Notice** 点击 **Continue**。下一张 onboarding 对话框只要求填写官方 DeepSeek API key；OmniaKey 应放在自定义 Provider，不是这条内置官方路由，因此请点击 **Configure later**。

在 Harness 中打开 **Settings → Models**，点击 **Add a custom provider**，填写：

1. **Provider ID** 填 `omniakey`。Provider ID 必须以小写字母开头。
2. **Display name** 填 `OmniaKey`。
3. **Base URL** 填 `https://api.omniakey.com/v1`。
4. **API protocol** 选择 `openai-completions`。
5. 在 **API key** 粘贴刚才创建的 OmniaKey key。

在当前 Harness 设计里，Provider ID 一经创建就不能改名，因为已保存的会话、默认设置、请求和凭据引用都会使用它。Display name、Base URL、协议、凭据和模型列表仍可以编辑。

## 第 4 步：自动获取并选择模型

在 **Model catalog** 下点击 **Fetch available models**。对于自定义 OpenAI 兼容 Provider，该工具会用 Bearer 鉴权，请求表单里当前 Base URL 的 `GET /models`。按上面的配置，最终请求的是 OmniaKey 的 `GET /v1/models`。

只选择准备实际使用的模型。这类工作流可以从下面两个 ID 开始：

|模型 ID|适合先用在哪些任务|
|-|-|
|`deepseek-v4-pro`|优先使用旗舰路由的长上下文编程和 Agent 任务|
|`deepseek-v4-flash`|更在意较低输入、输出价格和快速高频回合的任务|

同一个 Provider 还可以访问 OmniaKey 当前支持的 Claude、GPT、Gemini、Grok 和 GLM 模型。请从[实时模型目录](https://omniakey.com/zh/models)复制 ID；模型名是精确标识符，不是模糊别名。

如果模型发现暂时不可用，也可以手工添加准确的 Model ID。`dsh` 至少需要一个模型，才能创建自定义 Provider。

## 第 5 步：保存、选择工作区并安全验证

保存 Provider，用 **Choose workspace** 选中项目，然后新建会话，在模型选择器里选 `OmniaKey / deepseek-v4-pro` 或 `OmniaKey / deepseek-v4-flash`。

先执行一条范围很窄的只读任务：

```text
检查 package.json，并总结其中的 scripts。不要编辑文件，也不要运行命令。
```

这一步能在授权文件修改或 shell 命令前，确认 workspace、Provider、API key、准确 Model ID 和基础响应链路都能工作。文字回复成功不代表所有工具调用形式都已验证，因此在交给它大型重构前，再测试一个可逆的工具任务。

模型配置会在下一次请求生效，不用重启服务。但官方指南说明，一个已经发送过请求的会话会保留日志中记录的模型。更换 Provider 或模型后，最好新建会话，避免测试结果含糊。

## 可选：通过 settings.yaml 配置 OmniaKey

首次配置用 Web UI 更直观。如果需要可控的本地配置，也可以在 `$DSH_HOME/settings.yaml` 里写 Provider profile，并引用环境变量，不把 key 写进配置：

```bash
export OMNIAKEY_API_KEY="your-omniakey-api-key"
```

```yaml
llm-pi-ai:
  providers:
    omniakey:
      displayName: OmniaKey
      apiKeyEnv: OMNIAKEY_API_KEY
      api: openai-completions
      baseURL: https://api.omniakey.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash
```

启动 `dsh` 的进程环境必须能读到这把 key。不要在 `settings.yaml` 里用明文 secret 替换 `apiKeyEnv`。官方 `dsh-llm-pi-ai` 文档明确建议使用凭据引用，避免 secret 进入 settings 文档。

## 为什么 DeepSeek Harness 适合接入 OmniaKey？

Harness 原生支持自定义网关；OmniaKey 可以把这个扩展点变成一条可复用的 Provider 配置。

- **一份配置覆盖多个模型家族。** 在 Harness 模型选择器里切换精确 Model ID，不必为每家厂商再建一份网关配置。
- **可以直接发现模型。** Harness 能读取 OmniaKey 的 OpenAI 兼容模型列表，不必凭记忆手输每个 ID。
- **独立的运维控制。** 给 Harness 单独设置 API key、额度、轮换周期和用量记录。
- **模型身份明确。** OmniaKey 不做静默模型替换：请求的 Provider 和模型就是实际运行者；上游不可用时会返回可见错误。
- **为 API 用量付费，不再增加一层 Agent 订阅。** OmniaKey 采用预付余额和按 Token 计费；当前模型和价格以实时目录为准，不在这篇文章里写死。

这不代表 OmniaKey 在所有情况下都优于官方直连。如果你只需要原厂账号和端点，直连很合理。当同一套 Harness 需要通过一把 key、一个 Base URL 使用精选的 DeepSeek 及其它模型家族时，OmniaKey 的价值更明显。

## 常见问题排查

### Fetch available models 返回 401

Base URL 或 API key 没通过鉴权。确认 key 来自 OmniaKey、前后没有空格、仍处于启用状态，并且与准确的 `https://api.omniakey.com/v1` 配对。模型发现使用 Bearer 鉴权。

### Provider 返回 404

先检查 Base URL，再换模型。常见错误包括漏掉 `/v1`、重复 `/v1`，或把 `https://api.omniakey.com/v1/chat/completions` 误当作 Base URL。

### `UNKNOWN_MODEL`

所选模型不在自定义 Provider 已保存的列表里。重新获取模型，或添加 OmniaKey 目录里的准确 ID，再在新会话中选择它。

### `MISSING_CREDENTIAL`

通过 **Settings → Models** 保存 key，或确认启动 `dsh` 的 shell 里存在 `OMNIAKEY_API_KEY`。在另一个终端设置环境变量，不会更新已经运行的进程。

### 换了模型却像是没有生效

新建会话。现有会话在发出第一条请求后，会保留 append-only 日志中记录的 Provider 和模型。

### 文字能回复，但 Agent 工具失败

基础文本生成和结构化工具调用是两项不同的验证。先做只读工具任务，到 Trajectory 视图查看准确失败位置，再决定是否调整限制或权限。格式错误的工具调用，不能靠轮换一把有效 API key 解决。

## FAQ

### 这个 Agent 免费吗？

源码使用 MIT License。模型推理是另一层，使用官方 API、OmniaKey 或其它 Provider 都可能产生费用。

### DeepSeek Harness 能通过 OmniaKey 使用 DeepSeek V4 Pro 吗？

可以。把 OmniaKey 添加为 `openai-completions` 自定义 Provider，再选择当前准确 ID `deepseek-v4-pro`。`deepseek-v4-flash` 也是价格更低的 DeepSeek V4 路由。

如果要了解 0813 新版、官方峰谷费率和 token 成本算例，请阅读[DeepSeek V4 Pro API 价格指南](https://omniakey.com/zh/blog/deepseek-v4-pro-api-pricing)。
如果要了解更新的 Flash 路由、原生视觉、跑分证据和 V4 Pro 当前状态，请阅读 [DeepSeek V4.1 Flash 评测](https://omniakey.com/zh/blog/deepseek-v4-1-flash-review)。

### 可以把 OmniaKey key 直接填进内置 DeepSeek 卡片吗？

建议使用 **Add a custom provider**。内置卡片配置的是官方 DeepSeek 路由；自定义 Provider 才是官方文档给公司网关准备的入口，并且会提供 OmniaKey 所需的 Base URL、协议和模型列表字段。

### 同一个 Provider 能使用 Claude、GPT 或 Gemini 吗？

可以，前提是该模型当前在 OmniaKey 的 OpenAI 兼容接口上受支持。获取实时列表并添加所需的准确 ID。不同模型的协议特性可能有差异，应实际验证工具行为，不要假设所有模型完全一致。Claude Opus 5.5、Claude Sonnet 5.5 和 GPT-6.1 的具体设置见[Claude 和 GPT 接入教程](https://omniakey.com/zh/blog/deepseek-harness-claude-gpt-setup)：每个模型都要打开推理等级，并把输出上限设为 128K。

### API key 保存在哪里？

通过 Models 页面保存的 key 是 write-only，存放在 `$DSH_HOME/.credentials.yaml`；settings 只保留凭据引用。直接写 YAML 时应使用 `apiKeyEnv`，并通过进程环境提供 key。

### 适合稳定生产工作流了吗？

现阶段应把它当作评估对象。官方资料明确称当前版本为 developer preview，并警告会有破坏兼容性的变更。建议固定版本、备份不含 secret 的配置，并在升级后重新核对官方指南。

## 已核对来源

- [DeepSeek Harness 产品页](https://deepseek.com/harness/)
- [DeepSeek Harness GitHub README](https://github.com/deepseek-ai/deepseek-harness)
- [官方 Web UI 快速开始](https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart)
- [官方模型与自定义 Provider 指南](https://deepseek-harness.github.io/deepseek-harness/en/guide/providers)
- [官方 dsh-llm-pi-ai Provider 参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/README.md)
- [OmniaKey OpenAI 兼容 API 文档](https://docs.omniakey.com/cn/api/openai-compatible)
- [OmniaKey 实时模型目录](https://omniakey.com/zh/models)
