DeepSeek Harness 部署指南：一条命令本地跑起来，5 分钟上手 AI Agent 工作台

上一篇聊了 DeepSeek Harness 是什么、为什么不是又一个 Codex。这篇直接动手：把它跑起来。你不需要先读完 230 多个包的源码，也不需要懂 Cordis 的微内核原理。按照下面步骤，一条命令就能在本地启动 Web 工作台，再花 5 分钟配置 API Key、工作区和运行模式，就能让 Agent 开始读文件、跑命令、规划任务。

本地启动后看到的 DeepSeek Harness Web 工作台

一、前置条件：Node.js 版本

DeepSeek Harness 是一个基于 Node.js 的 Agent 运行时。官方要求的 Node 版本是 22.19.0 或更高（22.x 线），以及 24.x 及以上。开始前先检查本地版本：

node -v

如果输出类似 v22.23.1 或 v24.x.x，说明环境 OK。如果版本过低，请先去 nodejs.org 安装 LTS 版本，或者用 nvm 切换。

小提示：DeepSeek Harness 目前处在开发者预览阶段，兼容性和界面都可能继续调整。建议先用本地目录或虚拟机试水，不要直接挂载生产代码库。

二、最快上手：npx 一条命令启动

官方最推荐的尝鲜方式是 npx。它会临时下载并运行最新版本的 DSH CLI，无需提前 clone 仓库，也无需全局安装。

npx @deepseek-ai/dsh web

执行后，终端会显示服务已启动，默认监听：

http://127.0.0.1:3080

把地址复制到浏览器打开。首次运行会显示开发者预览声明，点击「继续」即可进入主界面。整个过程通常在 30 秒到 1 分钟内完成，取决于网络下载速度。

如果命令卡住，大概率是网络下载慢。可以尝试换 npm 镜像，或者直接跳到下一节的源码编译方式，clone 后用 pnpm 安装。

三、首次配置：API Key + 工作区

1）填入 API Key

进入首页后，第一步会被提示添加 API Key。点击左下角「设置 → 模型」，填入 DeepSeek 官方 API Key。如果没有 Key，可以去 https://platform.deepseek.com/ 申请并充值。

首次启动后的 API Key 配置弹窗

也可以在启动前把 Key 放到环境变量里：

export DEEPSEEK_API_KEY="sk-xxxxxxxx"
npx @deepseek-ai/dsh web

Web UI 会把密钥写入 $DSH_HOME/.credentials.yaml，不会直接写进会话日志。如果你更放心环境变量，可以不填弹窗里的输入框，留空即可回退读取环境变量或 .env 文件。

2）选择工作区

工作区就是 Agent 可以读写的项目目录。建议先建一个空目录做测试，避免它误动你的生产代码：

mkdir DeepSeekProjects

然后回到 Harness 首页，点击顶部的工作区名称，选择「添加工作区」，把刚才创建的目录加进去。之后 Agent 的文件操作、Shell 执行都会以这个目录为边界。

在工作区下拉菜单中添加本地项目目录

四、选模型、选模式

1）模型选择：Flash vs Pro

在输入框右下角可以快速切换模型。目前官方默认提供 DeepSeek-V4-Flash 和 DeepSeek-V4-Pro 两档：

右下角下拉可切换 Flash / Pro，以及思考强度

• Flash：速度快、单价低，适合简单任务、批量脚本、初步探索；
• Pro：能力更强，适合复杂规划、长上下文、需要多步工具调用的任务。

注意：8 月 17 日起 DeepSeek-V4 Pro API 涨价，高峰期输出价达到 27 元/百万 token。初次体验建议先用 Flash，熟悉流程后再根据任务复杂度切换。

2）四种运行模式怎么选

点击顶部「标准模式」下拉，可以看到四种预设。它们不是四套独立 Agent，而是同一套 Harness 宿主装入不同插件后的「运行时形态」。

标准、PTC、极简、创造四种模式

五、源码编译方式（适合开发者）

如果你想改源码、写插件，或者需要固定一个版本，建议直接 clone 仓库本地构建：

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

源码仓库的 packages/ 目录，每个能力都是一个可替换的插件包

源码方式的优势是：版本可控、可以改配置文件 cordis.yml、可以加载自己写的本地插件。缺点也很明显：仓库体积大、依赖多、构建时间长，普通用户用 npx 就够了。

六、Headless 与自动化

如果要把 Harness 塞进脚本、CI 或批处理任务，可以使用 Headless 模式。它接受一个任务，等 Agent 完全停稳后，把最后一条有效回复输出到终端：

dsh --profile headless "run the tests and summarize failures"

需要更结构化的事件和持续控制时，官方还提供 ACP 服务、JSON-RPC 入口以及 Python SDK。这些场景更偏自动化开发，等你在 Web UI 里跑顺了再深入不迟。

七、接入其他模型

DeepSeek Harness 没有把你锁死在自家模型上。在设置 → 模型里，你可以选择「添加提供方」，支持 Anthropic、OpenAI、Azure、Bedrock、Vertex 等目录模型，也可以自定义 OpenAI 兼容端点。

设置页支持自定义提供方、Base URL 和模型列表

配置项包括：提供方名称、Base URL、协议类型、可用模型列表。填好保存后，回到输入框右下角就能切换过去。这意味着你可以把 GLM、Qwen 或其他 OpenAI 兼容服务接进来，用 Harness 的插件能力跑它们的模型。

八、安全与权限

Agent 一旦能运行 Shell、修改文件，就天然有破坏力。DeepSeek Harness 默认采用 workspace-write 模式：命令和文件修改被限制在当前工作区及允许的临时目录内。如果需要扩大权限，会弹窗询问，也就是 ask 审批策略。

默认的 workspace-write + ask 审批策略

更宽松的 danger-full-access 模式也存在，但必须在设置里明确选择。官方推荐的态度是：权限扩大必须被显式决策，而不是藏在一个不起眼的复选框里。

建议新手保持默认策略。如果某条命令确实需要越界，Harness 会说明原因并弹窗请求批准。所有权限切换和审批记录也会进入 Session Log，方便事后审计。

九、装社区插件

DeepSeek Harness 刚发布就同步上线了社区插件入口。在设置 → 插件里可以浏览和安装。几个被频繁提到的插件包括：

设置页中的社区插件入口

• dsh-at-file：输入框里 @ 文件即可调用；
• dsh-genui：让模型在回复里渲染图表、表格、Mermaid、Diff 等；
• dsh-automation：补充自动化/后台任务能力；
• DSH-better-sidebar：给侧边栏增加文件树、终端、Git、Diff 预览；
• ModLens：给纯文本模型补上视觉读图能力。

更多插件可以关注 GitHub 话题 github.com/topics/dsh-plugin。

十、结语与常见坑

DeepSeek Harness 现在还处在「能跑，但不够丝滑」的阶段。它的真正价值不是让你明天就卸载 Claude Code，而是把 Agent 的每个零件都拆开给你看，并允许你替换它们。

部署三步走再复习一遍：

1. 确认 Node.js ≥ 22.19；
2. 执行 npx @deepseek-ai/dsh web，打开 http://127.0.0.1:3080；
3. 设置 API Key、添加工作区、选择标准模式，开始对话。

几个常见坑：

• 工作区不选，Agent 就不知道该操作哪个目录；
• API Key 没填或余额不足，对话会报错，先到 platform.deepseek.com 检查余额；
• 第一次运行别用「创造模式」，那是给插件开发者的高级入口；
• 想换模型不要只改输入框，必要时去设置 → 模型里添加自定义提供方。

如果你只是把 Harness 当成一个本地 coding agent 用，上面的步骤已经足够。如果你想让它成为你的 Agent 基础设施，接下来要研究的就是 cordis.yml、自定义插件和 Session Log 了。