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

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

DeepSeek Harness 是什么？

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

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

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

它不是什么

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

DeepSeek Harness 接入 OmniAKey 的配置

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

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

第 1 步：安装并启动 DeepSeek Harness

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

npx @deepseek-ai/dsh web

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

http://127.0.0.1:3080

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

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

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

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

打开 OmniAKey API Keys Dashboard，为该工具单独创建一把 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 开始：

同一个 Provider 还可以访问 OmniAKey 当前支持的 Claude、GPT、Gemini、Grok 和 GLM 模型。请从实时模型目录复制 ID；模型名是精确标识符，不是模糊别名。

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

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

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

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

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

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

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

可选：通过 settings.yaml 配置 OmniAKey

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

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

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 路由。

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

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

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

可以，前提是该模型当前在 OmniAKey 的 OpenAI 兼容接口上受支持。获取实时列表并添加所需的准确 ID。不同模型的协议特性可能有差异，应实际验证工具行为，不要假设所有模型完全一致。

API key 保存在哪里？

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

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

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

已核对来源

• DeepSeek Harness 产品页
• DeepSeek Harness GitHub README
• 官方 Web UI 快速开始
• 官方模型与自定义 Provider 指南
• 官方 dsh-llm-pi-ai Provider 参考
• OmniAKey OpenAI 兼容 API 文档
• OmniAKey 实时模型目录