DeepSeek Harness 怎么用？安装、模型配置与常见问题

DeepSeek Harness，简称 dsh，是 DeepSeek 开源的 Agent 框架。模型负责理解任务、决定下一步；Harness 负责把文件、命令、工具和会话接起来，让任务能够在具体的工作环境中继续执行。

例如，你可以让它阅读一个代码仓库、整理项目资料、查找需要修改的文件，再根据你的要求继续处理。能完成到什么程度，取决于接入的模型、可用工具和任务本身。

它采用插件架构，可以按需要配置模型、工具与运行方式。DeepSeek 模型、DeepSeek Harness 和 Hermes Agent 是不同的名称；Hermes Agent 是另一款 Agent 工具，不能直接照搬它的安装命令。

截至 2026 年 9 月 11 日，Harness 仍处于开发预览阶段。本文采用当天 npm 的 latest 发布版 0.1.5-rc.1；后续版本的界面和配置可能变化。下文两张模型设置截图来自 DeepSeek 官方文档，任务资料和操作示例由 AONIR 编写。

先安装 Node.js。建议直接选择官方提供的 Node.js 24 LTS 安装包，安装后重新打开终端。macOS 使用“终端”，Windows 使用 PowerShell，Linux 使用自己的终端程序。

运行下面两条命令，确认 node 和 npm 都能显示版本。官方当前源码声明的 Node.js 范围为 ^22.19.0 或 >=24.0.0；旧教程里只写“Node 20 以上”的要求不适合直接沿用。

接着在 DeepSeek 开放平台准备 API 密钥，并确认账号有可用额度。普通聊天网页的登录状态不会自动完成 Harness 的 API 配置。工具安装、模型调用和人工部署服务是不同的事项，使用前分别确认即可。

node --version
npm --version

先进入你准备存放练习资料的位置，再执行下面的命令。它会创建 dsh-demo 文件夹，并从这个目录启动 Harness。如果已经有同名文件夹，直接进入它即可。

首次运行时，npm 可能询问是否下载软件包。核对名称为 @deepseek-ai/dsh、版本为 0.1.5-rc.1 后继续。下载依赖需要一些时间，等终端打印访问地址再打开网页。

默认端口是 3080，本机启动通常会自动打开浏览器。本文核对的版本会在终端打印带 ?token= 参数的完整访问地址；没有自动打开时，请复制整条地址，不要只输入 http://127.0.0.1:3080。这个地址指向自己的电脑，其中的登录参数也不要公开分享。

使用期间保留启动它的终端。关掉进程后，网页就无法继续连接；需要结束时，在原终端按 Ctrl+C。

mkdir dsh-demo
cd dsh-demo
npx @deepseek-ai/dsh@0.1.5-rc.1 web

首次进入时，会先显示测试说明和 API 密钥配置引导。你可以在那里配置；如果选择了稍后配置，再打开“设置 → 模型”（Settings → Models），在 DeepSeek 卡片中填写开放平台生成的 API 密钥，点击 Apply 应用。官方中文文档中的对应按钮标为“保存”。

配置会在下一次请求中生效，不需要为了更换密钥反复重启程序。如果页面显示英文，可以在“设置 → 通用”（Settings → General）的 Language 项中选择中文。

回到会话页面，确认模型选择器中选择的是已经配置好的提供方和模型。保存了密钥、但仍选着另一家尚未配置的模型，也会导致请求失败。

API 密钥保存在本机的 Harness 数据目录中。截图或向别人求助时，隐藏密钥；不要把整个配置目录随项目一起上传。

点击“选择工作区”，添加前面创建的 dsh-demo 文件夹，并选中它。全新的 Web UI 不会自动选好工作区；如果输入框不能使用，先检查这里。

为了方便练习，我们准备了三份简短的 Markdown 资料，内容是一个虚构的活动页项目。下载后把 ZIP 中的三个 .md 文件解压到 dsh-demo，再新建会话，发送下面的任务。资料不含真实客户信息，也没有需要执行的脚本。

这一步要检查的是：模型能否读到文件，能否按要求区分已确认事项和待定事项，以及生成的文件是否出现在正确目录。示例用于练习，不是一次模型能力评测。

请阅读当前工作区的 brief.md、meeting-notes.md 和 ideas.md，整理一份 TASKS.md。

按“已确认的需求”“待确认的问题”“下一步任务”分组。每一项注明依据来自哪个文件；资料里没有确定的日期、预算或负责人，请保留为待确认。

只新建 TASKS.md，不修改这三个原始文件。完成后告诉我文件放在哪里。

任务结束后，打开 dsh-demo，找到 TASKS.md，再和原始资料对照。练习资料里已经确认了首版页面的内容和预约方式，但上线日期、预算及案例授权还没有定。整理结果应当保留这些区别。

如果只收到一段聊天回复，没有生成文件，先看执行记录：是否调用过文件工具、是否出现等待你确认的操作、是否发生写入失败。可以继续告诉它“请把整理结果保存到当前工作区的 TASKS.md”，然后检查文件是否出现。

完成这个小任务后，再换成自己的资料或代码项目。遇到删除文件、安装依赖等操作时，先看清它准备执行的内容。重要文件保留备份，项目目录尽量明确。

如果使用的提供方已经在列表中，优先选择“添加提供方”。官方文档中，Kimi 的提供方 ID 是 moonshotai；选择后填写该平台的 API 密钥并保存。

公司网关、自建接口，或列表里没有的提供方，可以选择“添加自定义提供方”。需要核对提供方标识、API 地址、API 协议、密钥和模型 ID。这几项必须对应同一个服务，不能只替换其中的密钥。

API 协议按接口文档选择：openai-completions、openai-responses 和 anthropic-messages 对应不同请求格式。不要因为页面里出现 OpenAI 字样，就默认所有接口都可以用同一种协议。

“获取可用模型”可以帮助查找模型列表。部分接口不提供兼容的列表响应；查询失败时，可以按照提供方文档手动填写模型 ID，再保存并在新会话中选择它。

点击查看大图↗

IMAGE VIEWER

DeepSeek Harness 自定义提供方表单，包含提供方标识、API 地址、协议和密钥

完整预览原图尺寸

1128 × 864

提示找不到 node 或 npx：重新打开终端，运行前面的版本检查。仍然找不到时，先处理 Node.js 安装或 PATH 配置，Harness 的模型设置还没有到需要检查的阶段。

Windows PowerShell 如果提示 npx.ps1 无法加载，可以改用同一次 Node.js 安装提供的 npx.cmd。下面的命令不需要修改系统执行策略。

页面提示 Unauthorized：先复制当前启动终端打印的完整地址，保留 ?token= 后面的参数再打开。它和模型 API 密钥不是一回事，不要把 API 密钥填到网址里。

浏览器打不开 3080：检查启动终端是否仍在运行、是否打印了错误，以及实际端口是否发生变化。如果提示端口已被占用，可以换一个端口重新启动，例如 3081。

下载长时间没有完成：先看 npm 的具体错误。连接超时、版本不存在和文件权限是不同问题，不能都靠重复安装解决。

npx.cmd @deepseek-ai/dsh@0.1.5-rc.1 web

npx @deepseek-ai/dsh@0.1.5-rc.1 web --port 3081

输入框不能用：先选工作区，再选已经配置好的模型。只看到设置页里有密钥，不等于当前会话已经选中了那条模型配置。

提示密钥无效或没有权限：确认密钥属于当前提供方、复制时没有多出空格，并到对应平台查看额度和接口权限。如果接的是自定义网关，同时核对 API 地址和协议。保留脱敏后的完整错误，便于进一步定位。

提示模型不存在：按提供方文档核对模型 ID，避免把网页显示名称当作接口 ID。修改配置后先开一个新会话验证，以免继续使用旧会话记录的模型。

文字能用、图片不能发：先确认模型和接口支持图片输入。自定义模型的能力声明也需要正确；不要仅靠勾选图片能力，把纯文本接口当成视觉模型。

以上检查仍不能定位时，记录系统版本、Harness 版本、所用提供方，以及从哪一步开始出错。不要直接把 API 密钥或完整配置文件发到公开讨论区。

下次使用时，进入自己的项目目录，再运行前面的启动命令。固定版本号可以让两次使用的版本保持一致；想升级时，先查看官方说明和 npm 当前发布版本，再决定是否切换。

工作文件保存在你选定的项目目录；Harness 的配置等用户数据默认放在 ~/.dsh，设置过 DSH_HOME 时则使用指定目录。它们不是同一个位置。更新或迁移之前，分别备份需要保留的项目文件和配置。

熟悉基础使用后，再按需求添加插件、工具或工作流。每增加一项，先验证原来的任务仍能完成，排查问题时也更容易知道是哪次改动造成的。

npm view @deepseek-ai/dsh version