DeepSeek Harness（dsh）上手指南

它到底是什么

先澄清一个最容易混的点：DeepSeek Harness（命令行叫 dsh）不是新模型，也不是一个 API 客户端。它是 harness——把模型接到文件系统、Shell、代码编辑器、网页和其他 Agent 上的那一层，同时记录它做过什么，限制它能做什么。

仓库把自己的架构总结成四个字：一切皆插件。这话是字面意思，连 Agent Loop 本身也是插件。底座是 Cordis 微内核，配套发了论文《A Programming Paradigm for Spatiotemporal Composability》。跑起来的 harness 本质上是一个 Cordis Context，各个包往里注册服务、事件和能力，最后由配置文件决定这个 Agent 拿到哪些。

所以文件系统、终端、子进程、PTY、语言服务器、网页访问、技能、子智能体、工作流、计划模式、会话持久化、设置、凭据、遥测，几乎每一项都有自己的包和自己的接口。官方那个编程 Agent，更像这套 SDK 的第一个客户，而不是项目的目的。

装上跑起来

装好 Node.js，然后一条命令：

npx @deepseek-ai/dsh web

Web UI 默认服务在 http://127.0.0.1:3080。运行命令的目录会成为默认工作区根目录，但新装的 Web UI 并没有选中任何工作区——不点一下「Choose workspace」把目录加进来，下面的输入框一直是灰的。第一次用卡在这一步的人不少。

想从源码跑：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

配模型

打开「Settings → Models」，填 DeepSeek API Key，保存即生效，不用重启。Key 对前端是只写的：存完之后页面只拿得到一个脱敏描述符，密钥落在 $DSH_HOME/.credentials.yaml，设置里只留一个引用。

凭据的解析顺序是固定的：先读继承来的环境变量，然后 $DSH_HOME/.credentials.yaml，然后运行目录下的 .env，最后 $DSH_HOME/.env。托管的那份凭据文件不会被塞进 process.env。

别的服务商走「Add provider」（Anthropic、OpenAI 等自带目录），公司网关或自建端点走「Add a custom provider」，填 Provider ID、Base URL、协议、凭据和至少一个模型。有两个坑值得先知道：

• Provider ID 定了就改不了。请求、已保存的会话、模型默认值、凭据引用全都用它做键。想改名只能新建一个再删旧的。
• 手填的模型默认按纯文本处理。没有任何办法去问一个端点支持哪些模态，所以给这类模型发图片会在发出去之前就被拒掉。要开图片，得在 $DSH_HOME/settings.yaml 里给这个模型加一行 input: [text, image]，表单里没有这个字段。

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

顺带一提，DeepSeek 自家的 chat-completions 路由本身是纯文本的，配也配不出图片能力。

四种 Agent 预设

Web UI 里有四个预设。它们不是四套独立的 Agent，也不只是换提示词风格—— 底层的模型路由、会话持久化、沙箱和审批是同一套宿主，预设只决定往这个 Agent 里装哪些工具和提示词。

界面名称是跟着语言设置走的。preset.yml 里写的确实是中文名，但 Web UI 会做本地化：设置页有一个语言选项，切到 English 之后这四个预设就显示成 Standard mode、PTC mode、Minimal mode 和 Creator mode。这里有个容易看错的地方——cordis 在界面上叫 Creator mode，不是 Cordis mode。不管界面显示成什么语言，代码真正引用的始终是目录名 standard、code、minimal、cordis。

极简模式最能说明这套架构。它的整个系统提示词就是一句You are a helpful software engineer assistant.，运行时上下文快照被关掉，上下文压缩也不存在，模型手里只有常驻 bash 和 str_replace_editor 两个工具。而 harness 的其余部分照常在跑，只是没有装进这个 Agent 而已。

配置分层：profile 才是入口

不少报道只提了一个 cordis.yml。实际发布的 CLI 比这个说法具体：dsh 是 profile 的启动器，一个 profile 就是一摞按顺序叠起来的插件包补丁层，最上面盖着你自己的配置。

最终生效的配置树从空根开始，按这个顺序叠：

1. profile 清单里 dsh.profile.bundles 列出的每个 bundle 补丁
2. profile 自己的 cordis.patch.yml
3. 用户级的 $DSH_HOME/cordis.patch.yml，它压过 profile 那一层
4. 命令行上每个 --patch <path>，按参数顺序

还有个连带的坑：官方有些行的配置是靠表达式读运行时服务的，比如 port: !!js ctx.webStartup.port ?? 3080。你把整个 config 换成字面量，这个运行时读取就悄悄没了，命令行参数也就压不过文件了。想看清楚合成出来的树，用 --dump-default-config 和 --dump-config，不用真启动。

TUI 不在包里

报道里常把「Web、TUI、Headless、SDK」并列成四个官方入口。实际盒子里有三个。终端界面是个外部插件，得自己建 profile 再装：

dsh plugin --profile tui add github:deepseek-harness/turtle-ui
dsh --profile tui

只有 web 和 headless 会在首次使用时按内置模板自动初始化，别的 profile 名字直接报错，并提示你先装一个包进去。

沙箱与审批

编程 Agent 一旦拿到 Shell 和文件系统权限，就能改代码、装依赖、起进程。这个项目把它当架构问题处理，而不是在界面上加个确认弹窗。文件写入受沙箱模式管：

落地的后端分平台：Linux 用 bwrap 和 Landlock，macOS 用 Seatbelt，Windows 用 ACL 受限令牌。隔离强度不是靠假设，而是后端自己上报的事实——full 表示模式承诺的文件效果全都管住了，partial 表示只管住一部分，目前老版本 Landlock ABI 和 Windows ACL 就是 partial。整个接缝是失败即关闭的：runner 要么返回真正带约束的命令行，要么直接失败，悄悄降级成无保护执行是被明令禁止的。

界面上那个权限选择器，其实是把沙箱模式和审批策略两个独立开关打包成了命名预设。默认只有两个：workspace-write（workspace-write + ask）和 danger-full-access（danger-full-access + never）。

还有一个和行业惯例反着来的决定值得单独说：默认一个 MCP Server 都不开。MCP 客户端是作为依赖发出来的，供补丁层使用，但每个 server 命令都是跑在 Agent 沙箱之外的可执行代码，所以开哪个得你自己明确写进去。对比一下别家怎么默认装 MCP，这个取舍挺清楚。

会话日志是唯一权威

项目给自己定的规矩是：凡是模型看见过的东西，都必须能从日志里重建出来。用户消息、运行环境上下文、模型请求信息、流式输出、工具调用和结果、压缩事件、权限切换、取消原因，全部以事件形式追加进同一条会话流。界面、持久化、恢复、Fork、遥测和回放都从这一个事件源派生，而不是各自维护一份「差不多对」的状态。

这解决的是智能体系统里一个很难缠的问题：出错的时候，模型当时到底看到了什么？只存最终聊天文本的话，请求前刚注入的工作区状态、被裁剪过的工具结果、系统自动切换的模型路由、用户在流式输出中途插进来的转向指令，全都查不到了。持久化本身也是插件，提供 JSONL 和 SQLite 两种后端；Resume 沿用原会话，Fork 从一个确定的历史边界派生新会话。

自动化：Headless、ACP、JSON-RPC、Python

接 CI 用 dsh --profile headless "跑一下测试"：接一个任务，等 Agent 完全停稳，把最后一条非空回复打到 stdout，然后退出。headless profile 不挂 HTTP 服务、不挂 Web 运行时、不挂浏览器客户端，跑干净了一个监听端口都不开。

需要结构化事件和持续控制的，走 ACP 服务或 JSON-RPC 入口。Python SDK 驱动的就是随附的 JSON-RPC 运行时，Python 程序可以开会话、发任务、收通知，不必把 Node 内核嵌进去：

python -m pip install deepseek-harness-sdk
export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1   # OpenAI 兼容代理
# export DSH_MODEL=deepseek-v4-flash

SDK 要 Python 3.10 以上，自带同版本运行时，不需要系统装 Node。目前支持 Linux x64、Linux arm64，以及 macOS 14 以上的 arm64。

它不做什么

dsh 是跑在你面前这台机器上的编程 harness。这个定位本身就解释了它的边界：

• 没有消息平台。没有 Telegram、Discord、WhatsApp、微信这些入口，只能通过本地 Web UI、终端或代码去用。
• 不是常驻的。合上电脑它就停了，凌晨三点没人替你接消息，也没有定时任务在跑。这一条取决于你把它放在哪，而不是框架本身的毛病：同一个 dsh 丢进托管的编程工作区，盒子就不会跟着你的笔记本一起睡。
• 是开发者预览版。官方明说会有破坏性变更，迭代速度也确实快，配置格式还会变。
• 默认围绕工作区。整套设计都假定有一个 clone 下来的项目目录，供它读、改、跑命令。

这些不算缺点，是它本来的形状。只不过和「一个常驻的私人助手」是两件事。

和常驻托管智能体怎么分工

两者是互补的。手边仓库要重构、要写代码，用 dsh；想要合上电脑之后还能在微信或 Telegram 里回你的，那是另一件事。

模型这一层是通的。在 dsh 里试出来 V4 Pro 或 V4 Flash 好用，同样可以让托管的龙虾 OpenClaw 用同一批模型—— 模型选择器里直接选、用自己的 DeepSeek Key，或者走 OpenRouter。具体见 DeepSeek V4 Pro 部署教程 和 V4 Flash 详解。

还有第三条路：把 dsh 本体托管起来

上面那张表比的是两件不同的事，而这一条两边都不算：你可以直接在托管的编程工作区里跑 dsh——不是找个替代品，就是官方那个 CLI。盒子里已经预装好，和 Claude Code、Codex、OpenCode、Aider、OpenClaude、Zero、Pi 摆在一起。网页终端里的 dsh，和你在本地用 npx 跑起来的是同一个官方 CLI，区别只是这台机器不会因为你合上笔记本就停。

export DEEPSEEK_API_KEY=sk-...
dsh --profile headless "跑一遍测试"

关于上面这两行，有三点要说。--profile 在哪儿都没有默认值，托管与否都一样，单敲一个 dsh 只会得到 error: --profile <name> is required，什么都不会打开——把 profile 的名字写上，或者用 dsh web 这个别名。运行时还得有一份可用的凭证，而新开的工作区里没有：账号里保存的那把 Key 只用于下面的 API 调用，不会进入交互式终端。所以第一次运行前，要么 export DEEPSEEK_API_KEY，要么通过前面提到的凭证服务保存，否则 dsh 会立刻退出并报 MISSING_CREDENTIAL。Web UI 本身能正常启动，但它只监听容器内部，而工作区不映射端口——所以在托管环境下，只能通过终端或 API 使用 dsh。

也可以完全不碰终端。工作区的 API 收一段提示词就能把 harness 跑起来，相当于前面讲的 headless 模式，只是容器、工作目录和轮询都已经给你搭好了：

curl -X POST https://openclawlaunch.com/api/v1/coding-workspaces \
  -H "Authorization: Bearer $OPENCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"harness":"dsh","prompt":"跑一遍测试，把挂掉的修好","use_saved_key":true}'

use_saved_key 决定这次运行花谁的 Key。带上它，用的就是你存在账号里的 DeepSeek Key；不带，用的是盒子里已经登录过的凭证——而新开的工作区里什么都没有，dsh 会当场停下并告诉你没有 Key。这个开关是按次请求给的，不是账号级设置：智能体是在关闭审批的情况下跑的，运行期间能读到这个 Key，提示词是你自己写的时候没问题，来自别人的时候就不行。

另外版本是钉死的。盒子里装的是某个确定的 dsh 版本，不是 npx 今天恰好解析到的那个；对一个官方明说会有破坏性改动的项目来说，这意味着上游更新不会让你的工作区行为在某天早上突然变样。这个 Key 从头到尾都是你自己的，背后没有我们的 Key 替你垫着。

常见问题

DeepSeek Harness 免费吗？

框架本身免费开源，MIT 协议。模型推理不免费——需要自己提供 API Key，用谁的模型就付谁的钱。

它是新模型吗？

不是。它是模型外面那一层运行时。内置 DeepSeek 原生适配器，也能通过服务商目录或自定义 provider 接 Anthropic、OpenAI 以及任何 OpenAI 兼容端点。

怎么安装？

装 Node.js，跑 npx @deepseek-ai/dsh web，Web UI 在 http://127.0.0.1:3080。然后进「Settings → Models」填 Key，再选一个工作区，才能开始对话。

支持 MCP 吗？

支持，但默认一个都不开。MCP 客户端是作为依赖提供给补丁层用的；每个 server 命令都是跑在 Agent 沙箱之外的可执行代码，所以要不要开由你明确决定。

能接微信或 Telegram 吗？

不能。它没有消息平台入口，只能通过本地 Web UI、需要自己安装的终端界面、一次性的 Headless 命令，或者 ACP / JSON-RPC / Python 接口来用。要在聊天软件里用，得换常驻托管的方案。

能上生产吗？

按官方自己的说法，还不行。README 标的是开发者预览版，并且用大写强调会有破坏性变更。

相关阅读

• DeepSeek V4 Pro 部署教程
• DeepSeek V4 Flash 0731 详解
• DeepSeek 机器人搭建教程
• Claude Code 使用指南