DeepSeek Harness（dsh）配置指南：怎么接任意模型（2026）

DeepSeek 在 2026-08-13 放出了自家的 agent harness，第一个意外是它在浏览器里打开，而不是终端。

你会得到：    一个每项能力都可替换成插件的 agent harness
耗时：        冷装约 2 分钟，热缓存下每次 headless 运行约 25 秒
需要准备：    Node.js、一把 API key、一个临时目录
安装：        npx @deepseek-ai/dsh web  →  http://127.0.0.1:3080
实测版本：    0.1.0-rc.6，macOS，Node 24.14.1，2026-08-14
许可：        MIT，TypeScript，基于 Cordis 插件内核
状态：        developer preview；README 明说会有破坏性变更
接别的模型：  可以，走自定义 provider 或两个环境变量

这个名字最早出现在 DeepSeek 2026-07-31 的更新日志里：按那条脚注的说法，V4-Flash 的 Code Agent 跑分是「用 DeepSeek Harness minimal mode（即将发布）作为框架」跑出来的。目前没有任何公开材料说你今天装到的这个 rc 就是那一版构建，但这个项目本身确实公开了。下面的内容都是 2026-08-14 在一台干净机器上实跑出来的，不是照着 README 抄的。

装完之后能做什么，不能做什么？

你会得到一个能用的本地 agent，带浏览器界面、可脚本化的 headless 模式，以及任何你能通过 HTTP 访问到的模型。 你不会得到终端界面、稳定的 API，也不会得到一个这周就能指向生产代码的东西。

今天可用：

• 一个跑在 127.0.0.1:3080 的本地网页应用，带会话、工作区，以及特权操作前的授权提示。
• dsh --profile headless "你的任务"，一次性脚本化运行，打印最终答案后退出。
• 任意 OpenAI 兼容、OpenAI-Responses 或 Anthropic-Messages 端点作为模型来源。
• PyPI 上的 Python SDK，自带运行时，所以调用方机器不需要 Node.js。
• 一套插件体系，模型、工具、技能、会话、沙箱、存储、调度乃至界面本身都可替换。

今天不可用：

• 没有交互式 TUI。 启动器是 CLI，但交互界面在浏览器里。
• 接口不稳定。 README 用大写警告会有破坏兼容的变更。
• 仓库上没有 release 和 tag（截至 2026-08-14），所以「最新版」就是 npx 当时解析到的那个。
• 没有 GitHub issues。 issue 跟踪是关的，缺陷反馈走 Discussions 或 Discord。

现在该装 DeepSeek Harness 吗？

如果你想基于这套插件架构做东西，装。如果你想要一个今天就能干活的 agent，跳过。

适合的情况：

• 你在写 agent 插件或评估 harness 架构，Cordis 的组合方式正是你来的理由。
• 你想要 DeepSeek 自己的参考框架，用来复现它的 Code Agent 跑分环境。
• 你在浏览器优先或共享服务器的环境里跑 agent，网页界面在这里是优势而不是妥协。

不适合的情况：

• 你通过 SSH 在远程机器上干活。这是项目自己 discussions 里最响的抱怨，没有 TUI 能回应它；而且把界面开在 0.0.0.0 上还必须声明 trustedHosts，否则 API 层会拒绝一切非 loopback 抵达的请求。
• 你需要一个不会在脚下变形的 harness。没有 tag、rc 快速迭代的 developer preview 正好相反。
• 你只是想在已经信任的 agent 里用 DeepSeek 模型。那就把现有工具指向 DeepSeek API，本文的任何内容都不必要。

停止规则： 如果你想要的只是在编码 agent 里用上 DeepSeek 模型，读完下面环境变量那一节就可以停，回去用你原来那套。

安装前需要准备什么？

Node.js、一把 key，以及一个你不介意它往里写东西的目录。

开始之前有一件事要先定：你从哪个目录启动，哪个目录就成为默认工作区根目录。从一份临时 checkout 起步，别在你在乎的仓库里。

怎么安装 DeepSeek Harness？

一条命令，然后大约两分钟的沉默。

第 1 步：跑 web profile

mkdir ~/dsh-scratch && cd ~/dsh-scratch
npx @deepseek-ai/dsh web

预期结果（要等一会）：

dsh web: http://127.0.0.1:3080

首次成功运行时，除了一条 npm 弃用警告之外，控制台输出就只有这一行。我们这次从命令到端口打开花了大约两分钟，期间进程占满一个核心，什么都不打印。没有进度指示。如果你在 60 秒时以为它挂了把它杀掉，那你早了 60 秒。

第 2 步：关掉首次运行提示

应用打开时会有一条内部测试提示，写着 DeepSeek Harness 0.1「仍在面向 Harness 开发者测试中」。点掉它。

第 3 步：填或跳过 DeepSeek key

引导流程会要一把 DeepSeek API key，并提供 Configure later。如果你打算用别的 provider，选稍后配置，那正是下一节的内容。

第 4 步：确认它把东西放在哪

ls ~/.dsh
# profiles  storages

$DSH_HOME 默认是 ~/.dsh：

动手改任何东西之前，组合顺序值得先知道：先是各 bundle 按 dsh.profile.bundles 顺序的补丁，然后是 profile 的 cordis.patch.yml，再然后是 $DSH_HOME/cordis.patch.yml，最后是 --patch 叠加层。用 --dump-config 看合成结果，别猜。

怎么添加自定义 provider？

Settings → Models → Add a custom provider；如果只需要把 DeepSeek 那条线路改个指向，两个环境变量就够。

表单要填五项：

之后点 Fetch available models，它会用表单里当前填的 base URL 和 key 去查，让你从返回结果里勾选。探测走的是 OpenAI 兼容的 GET /models；如果你的端点不提供这个接口，就手动把 ID 敲进去。

不管用哪种方式填，这个列表就是这条线路的全部。models 列表是替换线路目录而不是追加，线路没配的模型会在请求离开本机之前就以 UNKNOWN_MODEL 失败。自定义 provider 上不存在「先发出去再说」这条路。

Provider ID 永久不可改是最咬人的一条。请求、已保存的会话、模型默认值和凭据引用全都以它为键，所以改名意味着新建一个再删掉旧的，而任何已经记在旧 ID 名下的会话仍然指着旧的。

如果你不想点界面，$DSH_HOME/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
        - id: anthropic/claude-opus-5

为什么手填的模型会拒绝图片？

因为手动录入的模型在你另行声明之前一律按纯文本处理，而表单里没有这个字段。

没有任何办法去问一个端点它接受哪些模态，所以 dsh 取窄的那种假设，在发送之前就拒掉附件并点名是哪个模型。修法只在 settings.yaml 里：

llm-pi-ai:
  providers:
    ofox:
      models:
        - id: deepseek/deepseek-v4-pro
        - id: anthropic/claude-opus-5
          input: [text, image]

如果你加的每个模型都吃图片，就在线路上设 defaultInput: [text, image]。它是回退值而不是覆盖值：在目录型 provider 上，它只对目录未描述的模型生效，所以不会把本来支持图片的模型的图片能力剥掉。

手填的模型还会默默假设什么？

还有三个默认值，而图片只是其中报错报得最响的那个。 你手动录入的模型不带任何元数据，于是线路只能猜，而这些猜测写在文档里，界面上看不出来。

最后一条对用网关的人最微妙。thinking 请求的线上格式各家不同，底层库是从 URL 推断的。私有网关的 URL 什么都不透露，于是一个挂在你自己域名后面的 DeepSeek 方言端点，会被按 OpenAI 方言说话，除非你明说。两个 compat 开关都只在 openai-completions 上存在；另外两种协议的推理形态由协议本身承载。

上下文窗口那个默认值是后期才咬人的：262,144 比你会指向它的多数模型都大，于是长会话攒出一个请求，端点要么拒收要么截断，而 harness 事先没有理由提醒你。

不改配置文件怎么把 dsh 指向网关？

导出两个变量，内置的 DeepSeek 线路就会跟着走。 那条线路的 apiKeyEnv 默认是 DEEPSEEK_API_KEY，base URL 会先回退到 $DEEPSEEK_BASE_URL，再回退到公网 API。

export DEEPSEEK_API_KEY="your-gateway-key"
export DEEPSEEK_BASE_URL="https://api.ofox.io/v1"
npx @deepseek-ai/dsh --profile headless "Reply with exactly this and nothing else: dsh-ofox-ok"

这是 2026-08-14 的真实运行，它打印了 dsh-ofox-ok 并以 0 退出，热缓存下耗时 24 秒。没有配置文件，没有界面，没有 provider 条目。它能成，是因为网关接受 DeepSeek 线路发出的那些模型 ID：我们确认了 deepseek-v4-flash 和带命名空间的 deepseek/deepseek-v4-flash 在同一个端点上都能解析。

在正经配置它之前，这是回答「我的端点能不能配合这东西用」最快的办法。

有 CLI 或 TUI 吗？

有 CLI 启动器和 headless 运行模式。没有交互式 TUI。

启动器自己的入口模式：

启动器的参数必须在前，它遇到的第一个不认识的 token 就开始算应用自己的参数，所以 dsh --profile web --port 8080 会把 --port 交给网页应用而不是启动器。

headless 是值得知道的那个模式，因为关于「没有 TUI」的大部分噪音都默认它压根没有终端路径。终端路径是有的，只是不交互。对 CI、cron 和脚本化评估来说，这个形态本来就更合适。

「给个不是浏览器的东西」是项目 discussions 里最响的诉求，到 2026-08-14 那里已经有 622 个帖子。票数最高的一条拿了 74 票，要的是独立客户端加 CLI 加 VS Code 插件；专门要 TUI 的那条排第二，24 票。关于 agent 本身的任何话题，票数都没超过「它跑在什么里面」这个问题。

这在 DeepSeek 那边也不是盲区：仓库里有一份 2026-07-22 的内部架构笔记，讲的是终端交互扩展服务，也就是说底子比公开发布早了三周。

有编程接口吗？

有，而且很容易漏掉，因为它不是 Node 包。pip install deepseek-harness-sdk（0.1.0rc6，Python 3.10 及以上）自带 harness 运行时，所以跑它的机器完全不需要系统 Node.js；仓库里还有一个可直接运行的 JSON-RPC 示例，接收工作区、会话目录和一段提示词。它读 DEEPSEEK_API_KEY 和 DEEPSEEK_BASE_URL 的方式和启动器一样，所以上面那个两变量接网关的招在这里也管用。支持平台比 CLI 窄：Linux x64、Linux arm64，或 macOS 14 及以上的 arm64。

到底能换掉哪些部件？

你 profile 的 package.json 里那份 bundle 列表，「一切皆插件」在这里才不再只是口号。

一个 profile 会指定一份有序的 bundle 列表，随包发布的三个在 npm 上是分开发布的：

第四列不是趣闻，是陷阱。启动器对这三个依赖写的都是 ^0.1.0-rc.6，所以走 npx 装出来的是版本一致的树。但在 npm 上，这三个 bundle 的 latest 标签仍然指着 0.0.1-rc.1，那是 2026-08-10 发布的，比仓库公开早三天；当前构建挂在 next 标签下。手动 npm i @deepseek-ai/dsh-base 装到的是发布前那一版，而且不会有任何提示。

装第三方插件走启动器，而不是你自己跑包管理器。按启动器文档，dsh plugin --profile <name> 会把后面的一切原样转发给 profile 目录里的 pnpm，所以你熟悉的 pnpm 语法照用：

dsh plugin --profile web add <package-name>

插件会落在该 profile 自己的 node_modules 里，解析顺序排在随包 bundle 之后。

生态起来的速度比软件稳定的速度快。GitHub 上 dsh-plugin 话题在 2026-08-14 有 775 个仓库，距离仓库公开大约十四小时，而在我们写这篇的这几个小时里，它从 337 个翻了一倍还多。质量参差不齐，里面没有官方出品，还有不少是为了 star 蹭话题的，所以把这个话题当目录看，不要当推荐看。

大家最先做什么依然很能说明问题。星数最高的真插件是给纯文本模型用的视觉桥，760 星，第二个视觉工具箱 569 星，而这正好是「手填模型默认纯文本」给用自定义 provider 接文本模型的人留下的坑。排行另一头还是界面这件事：一个 Web UI 插件与皮肤合集 650 星，社区做的 TUI 从 292 星起步。

安装过程中会坏在哪，怎么修？

六种值得知道的失败，四种是我们自己碰到的，两种是别人在发布首日报告的。

先想清楚一把 key 属于哪个 provider，再往密钥框里填。密钥会写进 $DSH_HOME/.credentials.yaml，页面只拿得到一个脱敏描述符，这是好习惯，但也意味着你没法从界面把它读回来核对。

团队之间怎么共享 dsh 配置？

共享 profile，不共享凭据。 一个 profile 就是一个目录，里面有指定 bundle 的 package.json 和放覆盖项的 cordis.patch.yml，两者都不含密钥。

在一个 preview 级别的工具上，可行的分工是：

• 提交 profile 目录：bundle 列表、插件依赖，以及带模型线路和权限默认值的补丁层。
• 绝不提交 $DSH_HOME/.credentials.yaml。在 settings.yaml 里用 apiKeyEnv，让每个开发者通过环境变量提供自己的 key。
• 不要 pin，做好频繁变动的准备。 没有 tag 可以 pin，所以把你验证过的 rc 版本记在自己的 README 里，每次更新后重新验一遍。
• 让所有人指向同一个端点，这样模型列表、花费和速率限制是共享的，而不是每个开发者一套。

最后这条是多数团队在任何 harness 上都会做错的地方，不只是这一个。

怎么让 dsh 和你其他的 agent 共用一把 key？

每个 agent harness 都要你单独配一遍模型访问。Claude Code 要它自己的环境变量，Codex CLI 要 config.toml 里的 provider 块，Cline 要它自己的设置面板，dsh 要么要自定义 provider，要么要 DEEPSEEK_BASE_URL。四个工具，四个地方轮换密钥，四份要各自维护的模型目录。

因为这四个都是通过 HTTP 对着 OpenAI 兼容或 Anthropic 兼容端点说话，解法在每一个上都一样：给它们同一个 base URL 和同一把 key，只让模型字符串不同。聚合网关就是干这个的，也正因如此 dsh 的自定义 provider 表单恰好是那几个字段。

在 ofox 上端点是 https://api.ofox.io/v1，协议 openai-completions，截至 2026-08-14 同一把 key 能触达 129 个模型，包括 DeepSeek V4 Pro、DeepSeek V4 Flash、Claude Opus 5 和 Kimi K3。另外三个工具的等价配置，见我们的 Codex CLI 自定义 provider 指南和 Cursor、Claude Code、Cline 配置详解。

指向真实仓库之前该知道什么？

它是 preview，而且社区在发布首日就发现了权限边界相关的缺陷。

项目的 discussions 在发布后二十四小时内出现了多份互相独立的报告，涉及文件沙箱和权限模型，覆盖 workspace-write 边界、路径处理竞态和审批流程。我们不在这里复现其中任何一项；对于作者自己明确标注为 developer preview、并预告会有破坏性变更的软件，这些也不算意外。

务实的读法不是「这个工具不安全」，而是「这个工具的权限模型还没被摇匀」。由此有两个习惯：

• 从临时目录启动，因为调用目录会成为工作区根目录。
• 权限模式保持默认，并且真的去读审批提示，而不是一路点过去。

这两件事成本都很低。另一种选择是在你需要的那个仓库上发现边界在哪。

它和你已经在用的 harness 比怎么样？

形态不同，活是同一份，里程数差得远。 Claude Code 和 Codex CLI 是终端优先、经过了几个月打磨；dsh 是浏览器优先、上线一天，而且设计上让你不喜欢的部分是可替换的而不是只能 fork。

插件架构是真正的差异点，而且是实打实的：模型层、工具层、沙箱、存储和界面全都是由加载器组合起来的 bundle，所以把网关换进去是填个表单而不是打补丁。这种可组合性能不能扛住稳定 API 的考验是个开放问题，现在谁也答不了。

要在成熟选项里做选择，我们在 AI 编码 agent harness 横评里跑过那个对比，终端类 agent 的具体比较在 Claude Code、Codex CLI 与 Cursor 对比。如果你来这里主要是想给最终选定的 harness 挑一个 DeepSeek 模型，V4 Pro 与 V4 Flash 对比直接讲的就是这笔取舍。

参考信息来源

• DeepSeek Harness 仓库
• dsh 启动器文档
• 模型 provider 指南
• dsh-llm-pi-ai 适配器文档
• 插件配置目录
• Python SDK 指南
• PyPI 上的 deepseek-harness-sdk
• DeepSeek Harness 官方站点
• Cordis 插件内核
• @deepseek-ai/dsh 的 registry 元数据
• DeepSeek API 更新日志
• 项目 discussions