DeepSeek Harness 安装与启动教程

如果你第一次安装 DeepSeek Harness（下文简称 DSH），先走官方最简单的 npm 路线。当前官方快速启动命令是：

$ npx @deepseek-ai/dsh web

正常情况下，它会在本机启动 Web UI（浏览器图形界面），默认地址是 http://127.0.0.1:3080。

这篇只解决一个问题：让 DeepSeek Harness 真正启动起来，并确认 Web UI 可以访问。模型、工作区和第一个智能体任务放在下一篇。

最终至少满足：

• node -v 返回官方支持的 Node.js 版本；
• npx @deepseek-ai/dsh web 没有因为环境错误直接退出；
• 终端显示 Web UI 地址；
• 浏览器可以访问 DSH Web UI。

只有做到这一步，才进入《DeepSeek Harness 第一次使用》。

DeepSeek Harness 当前仓库要求 Node.js 版本在 ^22.19.0 || >=24.0.0 范围内。先在终端运行：

$ node -v

例如返回 v24.7.0，表示 Node.js 已经安装。

哪些版本符合当前要求？

当前可接受 Node 22 的 22.19.0 及以上版本，或者 Node 24 及以上版本。例如 v22.19.0、v22.20.0、v24.0.0、v24.7.0 都符合当前版本范围。

如果看到的是 v18.x、v20.x、v22.10.x 这类版本，则不符合当前官方要求。

如果 node 命令不存在怎么办？

macOS / Linux 可能看到 command not found: node；Windows 可能看到 'node' 不是内部或外部命令。这说明问题还没有进入 DSH，先处理 Node.js 安装或 PATH 环境（PATH 是系统查找可执行程序的环境变量）。

直到下面三条命令都能正常返回版本，再继续安装 DSH：

$ node -v
$ npm -v
$ npx -v

macOS

可以直接打开「终端（Terminal）」。

Windows

推荐 PowerShell 或 Windows Terminal。当前官方 Web profile 在 Windows 上使用 PowerShell 相关工具栈。

第一次安装 DSH，不需要 WSL（Windows 下的 Linux 子系统），也不需要为了教程专门切换 Git Bash。

dsh 进程会把启动时所在目录作为默认文件系统位置。因此执行启动命令之前，建议先进入一个你准备拿来测试 DSH 的目录，例如：

$ cd ~/Desktop/dsh-test

Windows PowerShell 示例：

$ cd C:\Users\你的用户名\Desktop\dsh-test

后续 Web UI 仍然需要正式选择工作区。这里的启动目录只是 DSH 进程启动时的默认文件系统位置。

运行：

$ npx @deepseek-ai/dsh web

这是当前官方 README 给出的 npm 快速启动方式。这条命令分别是什么意思：

• npx：获取并运行 npm 包中的命令；
• @deepseek-ai/dsh：DeepSeek Harness 官方 npm 包；
• web：启动 Web UI 运行模式。

安全提示

第一次运行可能发生什么？

第一次运行 npx @deepseek-ai/dsh web 时，npm / npx 可能需要先下载包及依赖。因此，命令执行后没有立刻弹出网页，不等于 DSH 启动失败，先观察终端。

真正需要关注的是：

• 是否出现明确错误；
• 进程是否直接退出；
• 最后是否进入 Web Server 运行状态；
• 是否打印访问地址。

当前官方默认地址是 http://127.0.0.1:3080。如果启动成功，终端会给出 Web UI 地址；正常本机启动时，官方当前行为还会尝试打开默认浏览器。你也可以手动访问该地址。

127.0.0.1 是什么？

它指向你当前这台电脑本机。也就是说，http://127.0.0.1:3080 不是一个公开互联网网站；默认情况下，你是在浏览器里访问本机正在运行的 DSH 服务。

点击放大010203

• 01内测声明标题
• 02声明正文
• 03继续按钮

浏览器没有自动弹出，不等于启动失败。判断重点不是浏览器有没有自动弹出来，而是 DSH Web Server 是否已经启动。

如果终端已经显示 http://127.0.0.1:3080，直接把地址复制到浏览器即可。

不想自动打开浏览器怎么办？

可以使用 --no-open 参数，这样只启动服务器，不主动打开浏览器：

$ npx @deepseek-ai/dsh web --no-open

然后手动访问 http://127.0.0.1:3080。

3080 端口被占用怎么办？

默认 Web UI 使用端口 3080。如果出现类似 EADDRINUSE 的错误，通常表示当前地址 / 端口已经被其他程序占用。最直接的第一步是换端口：

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

然后访问 http://127.0.0.1:3081。如果新端口正常，说明 DSH 本身并不一定有问题，故障更可能集中在原来的 3080 端口。

Windows 出现 EACCES 怎么办？

如果 Windows 启动监听端口时出现 EACCES，不要直接理解成「DSH 安装失败」。它可能和当前端口权限、系统网络组件、保留端口、本机其他配置有关。

第一检查点仍然是换端口：

$ npx @deepseek-ai/dsh web --port 3180

如果换端口后能正常启动，优先排查原端口，而不是重新安装整个 DSH。如果换多个普通端口仍然失败，再进入《DeepSeek Harness 常见问题与报错排查》。

为什么官方不建议直接监听 0.0.0.0？

当前 CLI 对 Web 启动有明确安全边界：不支持直接通过 --host 0.0.0.0 把 Web UI 暴露到所有网络接口。对于第一次使用，保持默认本机访问方式即可。

如果未来需要远程访问，不要通过随意放开监听地址来解决，应该单独考虑网络边界、身份验证、反向代理（Reverse Proxy）、隧道和可信网络。这些不属于新手安装页。

通过 SSH 启动时为什么不自动打开本地浏览器？

当前官方 CLI 会识别继承的 SSH 环境。通过 SSH 启动时，通常只打印宿主机 Web 地址，而不会像本地桌面环境一样主动打开浏览器，因为真正的本地转发地址由 SSH 客户端或编辑器负责。这属于正常行为，不应直接判断为浏览器启动故障。

怎样停止 DeepSeek Harness？

在运行 DSH 的终端中按 Ctrl + C。当前官方 CLI 的第一次 SIGINT / SIGTERM（进程终止信号）会进入正常释放流程，对普通用户可以理解成让 DSH 正常关闭。不要为了停止服务直接关闭大量系统进程。

如果第一次中断无法正常结束，官方当前 CLI 允许第二次信号强制退出。

npx 是不是把 DSH 全局安装到了电脑？

不应该这样理解。当你运行 npx @deepseek-ai/dsh web 时，npx 的核心作用是获取并执行这个包提供的 CLI。所以后续 DSHOPC Learn 普通用户命令都会继续明确写 npx @deepseek-ai/dsh ...，而不是默认你的系统已经可以直接运行 dsh，这样可以避免后续教程突然出现 dsh: command not found。

如果我想从源码运行呢？

如果你是开发者，或者准备研究 DSH 源码，官方还提供源码运行方式：

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

这里需要注意：pnpm run build 会准备仓库构建产物，pnpm dsh web 使用这些已经构建好的内容。源码路线更适合阅读实现、修改 Harness、开发插件、调试内部机制。

如果你只是第一次学习怎么使用 DSH，不需要为了「更专业」而先从源码安装，先把 npx 路线跑通即可。

安装阶段不要急着做什么？

Web UI 还没稳定启动之前，不建议同时做以下操作：

• 安装第三方插件；
• 手改 cordis.patch.yml；
• 配 MCP；
• 创建自定义 profile；
• 删除 ~/.dsh；
• 大量清 npm 缓存；
• 同时切换多个 Node.js 版本。

原因很简单：一次同时改变太多变量，会让后续故障几乎无法定位。先只完成 Node.js → npx → Web UI 这条主线。

• node 不存在——问题层在 Node.js 环境，先修 Node；
• Node.js 版本不符合——问题层在运行环境，先升级 Node；
• npx 执行后直接报 npm 网络错误——问题层在 npm 获取包 / 网络，还没有进入 DSH Web UI 层；
• 终端显示 URL，但浏览器没自动打开——手动访问 URL 即可，不等于 DSH 失败；
• EADDRINUSE——优先换端口；
• 页面能打开——说明 Web 服务已经能够访问，但还不能证明模型已配置、工作区已选择、智能体能正常调用工具，这些属于下一篇。

不要只看命令有没有报错。这篇的「验证成功」至少包括以下四项：

1. Node.js 符合当前要求：node -v 返回 ^22.19.0 || >=24.0.0 范围内的版本；
2. DSH 进程持续运行：运行 npx @deepseek-ai/dsh web 以后，进程没有因为启动错误立即退出；
3. 出现 Web UI 地址：例如终端打印 http://127.0.0.1:3080；
4. 浏览器真实可访问：打开地址后，能够看到 DeepSeek Harness Web UI。

此时不要急着判断「智能体已经能工作了」，下一篇才验证完整智能体链路。

继续《DeepSeek Harness 第一次使用：从启动到完成第一个智能体任务》。下一篇会完成：

1. 配置一个可用模型；
2. 选择安全测试工作区；
3. 使用标准模式；
4. 让智能体真实读取文件；
5. 观察工具调用；
6. 用不可猜的唯一值确认智能体真的完成了任务。

如果本篇没有成功，先进入《DeepSeek Harness 常见问题与报错排查》，不要带着启动问题继续往下学。