DeepSeek Harness 安装与使用教程：从启动 Web UI 到配置 API 和完成首个任务

DeepSeek Harness（dsh）是 DeepSeek AI 推出的插件化开源智能体框架。本文从 npx 快速启动、源码运行、DeepSeek API 配置、工作区选择、首个任务、headless 模式到常见问题，完整讲清上手流程。

更新时间：2026-08-19
原文出处：DeepSeek Harness 官方仓库与 Web UI 使用指南。本文按官方文档重新整理和改写，示例命令经过筛选；配图来自官方文档，项目采用 MIT 许可证。

DeepSeek Harness，命令行简称 dsh，是 DeepSeek AI 推出的开源智能体框架。它的思路不是做一个固定功能的聊天客户端，而是把模型、工具、权限、工作区、插件和界面拆成可组合的模块。对想在本地让 DeepSeek 读代码、改文件、跑命令、处理任务的人来说，它比单纯打开一个对话网页更接近开发工具。

不过先说结论：它目前还是 Developer Preview（开发者预览）。接口、插件和配置方式仍可能有不兼容改动，因此适合愿意尝试新工具的开发者，不适合一上来就放进关键生产流程。下面的教程以最稳妥的 Web UI 路线为主，先跑起来、完成一个真实任务，再决定是否研究源码、插件或无界面运行。

DeepSeek Harness 能做什么

启动后，DSH 会在本机运行一个 Web 界面。选择项目目录并配置模型后，Agent 可以在受当前权限策略约束的情况下读取、编辑工作区文件、执行终端命令、维护计划，也可以在需要时发起工具调用或继续处理较长任务。

它和一般聊天窗口最大的区别在于“工作区”。模型不是只看你粘贴的一段代码，而是可以围绕你选中的项目目录工作。因此它适合这些场景：

让 Agent 先梳理一个陌生仓库的模块、启动方式和风险点。
根据明确需求修改局部代码，再让它补充测试或解释变更。
对一组文件做归纳、迁移、格式化或文档整理。
以无界面模式把一次任务交给脚本或自动化流程。

不要把它理解成“给 DeepSeek 套壳”。DSH 的核心是插件化运行时：不同 profile 可以组合不同插件和权限配置，所以同一个 dsh 命令可以运行 Web、headless 等不同模式。

安装前准备

最轻量的使用方式只需要安装 Node.js。完成后在终端确认：

node --version
npx --version

如果你只是想体验 Web UI，不需要先克隆仓库，也不需要手动安装 pnpm。准备好 DeepSeek API Key 即可，密钥可在 DeepSeek 开放平台创建。不要把 API Key 写进项目代码、截图或提交到 Git 仓库。

如果你准备从源码开发插件或修改 DSH 本身，官方开发文档要求 Node.js 22.19+ 或 24+、Corepack 管理的 pnpm，以及 Git 2.26+。这是一条开发路线，不是普通使用的前置条件。

方式一：一条命令启动 Web UI

进入你希望作为默认工作区的项目目录，再运行：

npx @deepseek-ai/dsh web

首次执行时，npx 会下载并运行 DSH。成功后，终端会打印本地访问地址；官方默认端口是 3080，通常直接在浏览器打开：

http://127.0.0.1:3080

这里有两个容易忽略的细节。第一，dsh 在哪个目录启动，哪个目录就会成为它默认关联的文件系统位置，所以不要随手在下载目录里启动后再让它处理其他项目。第二，服务启动并不代表已经授权 Agent 操作文件，首次进入 Web UI 仍需要选择工作区，并且需要按权限策略批准敏感操作。

如果 3080 已被其他程序占用，可以用应用参数指定端口：

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

第一次配置：填 API Key，选择模型

打开 Web UI 后，进入 设置 → 模型。找到 DeepSeek 卡片，粘贴 API Key 并保存；保存后不必重启服务，模型路由会在下一次请求时生效。

DeepSeek Harness 模型设置页面

图片来源：DeepSeek Harness 官方文档。

官方文档强调，页面不会把已保存的明文密钥再返回给浏览器，而是保存凭据引用并用脱敏信息展示。即便如此，实际使用时仍建议把本地用户目录、浏览器配置文件和终端历史当作敏感环境来管理，不要在演示视频或聊天截图中暴露密钥。

保存后，在模型选择器中选一个已配置的 DeepSeek 模型。新建会话会使用这个默认模型；已经产生请求的旧会话会保留其会话记录里的模型信息。如果删除了某个提供方但默认模型还指向它，输入框会被阻止，重新选择可用模型即可恢复。

选择工作区，再做第一个真实任务

回到主界面，点击 选择工作区，添加并选中你的项目根目录。没有选中工作区时，输入框保持不可用，这是为了避免 Agent 在你没有明确指定目录时操作文件。

第一次不要直接让它“把整个项目优化一遍”。先给一个范围清楚、可核验的任务，例如：

请只阅读当前仓库：概括主要目录和启动方式，列出三个最需要注意的风险点；不要修改文件，也不要执行会改变数据的命令。

这个提示词有三个价值：限定了只读范围、明确要什么结果、禁止破坏性动作。确认它理解你的仓库结构后，再逐步让它处理某个页面、一个 bug 或一组测试。对代码智能体来说，先缩小任务范围往往比一开始堆很多规则更有效。

DSH 会按当前的权限策略处理需要批准的操作。读文件、编辑文件、执行命令的风险不同，看到审批提示时要看清命令和目标路径；不要因为“是 AI 自动生成的”就默认允许。

想接入其他模型或公司网关怎么办

除了 DeepSeek，DSH 还支持通过“添加提供方”接入目录内的服务，或通过“添加自定义提供方”填写 OpenAI 兼容端点。后者适合公司网关、自建代理，或目录里没有的服务。

DeepSeek Harness 自定义提供方表单

图片来源：DeepSeek Harness 官方文档。

填写自定义提供方时，最关键的是 Provider ID、基础 URL、API 协议、凭据和模型列表。Provider ID 会被会话、默认模型和凭据引用长期使用，后期想改名时更稳妥的做法是新增一个提供方、迁移选择，再删除旧项，而不是直接猜测配置文件结构。

需要特别注意视觉输入。官方文档说明，DeepSeek 的 chat-completions 路由默认是纯文本；不能仅靠改一个开关就让模型突然接收图片。对自定义端点，只有端点真的支持图片，并且你在配置中为模型声明 input: [text, image] 时，DSH 才会把图片作为模型输入发送出去。声明和实际能力不一致，最终仍会被服务端拒绝。

源码运行：适合想开发插件的人

如果你的目标是看源码、开发插件或参与贡献，使用仓库方式更合适：

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

源码模式的重点不是“比 npx 更高级”，而是你可以固定某个提交版本、查看完整文档、修改 profile 和插件，并在本地验证改动。官方仓库是一个包含 Web、CLI、包和文档的 monorepo，首次 pnpm install 会同时初始化相关的 Git hook 和开发环境配置，所以不要在生产项目目录里盲目混装依赖。

日常只用 DSH 的人仍建议选 npx 路线。它更短、更容易清理，也不会把开发依赖塞进你的业务仓库。

无界面运行：适合单次、可脚本化任务

除了 Web UI，CLI 还提供 headless profile。它会创建一段新的持久会话，完成任务后把最终答案输出到终端：

npx @deepseek-ai/dsh --profile headless "只读取当前项目，列出 package.json 中的脚本及其用途，不修改文件。"

这种模式适合一次性的仓库盘点、生成报告、CI 前检查或外部脚本调用。它并不等于“绕过权限”。真正是否执行文件编辑、命令或其他工具，仍受当前 profile 和权限策略控制。先在非关键目录中验证输出和审批行为，再考虑接入团队自动化。

常见问题与排错

浏览器打不开页面： 先看终端输出的实际地址；如果指定端口被占用，换一个端口重新启动。不要只看到 http://127.0.0.1:3080 就假设服务一定已经启动成功。

输入框不可用： 通常是没有选择工作区，回到主界面选中项目目录即可。

模型报 MISSING_CREDENTIAL： 回到设置页保存对应提供方的密钥，或者检查被引用的环境变量是否存在。

模型报 UNKNOWN_MODEL： 选择已经配置的模型；如果走自定义提供方，确认模型 ID 与服务端实际提供的名称一致。

添加图片后立即被拒绝： 这通常不是界面 bug，而是模型路由没有声明图片输入能力。DeepSeek 的默认 chat-completions 路由是文本路线；请换支持视觉的端点，或按官方配置说明为真正支持图片的自定义模型声明能力。

升级后配置或插件失效： 这是开发者预览项目最现实的风险。升级前备份配置，关注官方 release、仓库 Discussions 和迁移说明；不要把未验证的插件直接放进涉及密钥或生产代码的工作区。

最后给新用户的建议

DeepSeek Harness 最适合的上手顺序是：先用 npx 启动本地 Web UI，在一个非关键项目里配置 DeepSeek API，选择工作区，完成一个只读任务，再逐步开放编辑和命令执行。不要一开始就研究全部插件，也不要让它无边界地“自动优化整个项目”。

等你确认它的任务质量、成本和权限行为都符合预期，再进入自定义提供方、headless 模式和插件开发。这个工具的优势来自可组合性，但可组合也意味着配置和版本需要更谨慎地管理。