DeepSeek Harness（DSH）安装与常见报错排查指南：含 exited with code 1、npx 无法识别与 MCP 配置

一、DSH 是什么

DeepSeek Harness（简称 DSH）是围绕 DeepSeek 大模型构建的智能体（Agent）运行环境：它把模型调用、工具执行、终端操作和 MCP（Model Context Protocol）工具接入整合到一个本地运行时里，开发者可以在自己的工程目录中启动一个“能动手干活”的 AI 编程助手。本文记录一次完整的安装过程，以及最容易踩的三个坑的修复方法。更系统的图文版安装手册也可以在 https://deepseekdsh.com/ 查到。

二、安装前准备

• 操作系统：Windows 10/11、macOS 或主流 Linux 发行版
• Node.js 18 及以上版本（使用 npx 安装的前提）
• 一个可用的 DeepSeek API Key

先验证 Node 环境：node -v / npm -v / npx -v，三条命令都能正常输出版本号再继续。

三、方式一：npx 一行命令启动 Web 版

运行：npx @deepseek-ai/dsh web。npx 会自动拉取 @deepseek-ai/dsh 包并启动本地 Web 服务，终端中会打印访问地址（通常是 localhost 的某个端口），用浏览器打开后填入 API Key 即可使用。长期使用可全局安装：npm install -g @deepseek-ai/dsh，然后运行 dsh web。

四、方式二：DSH Desktop 桌面端

到发布页下载对应平台的安装包，Windows 双击安装，macOS 将应用拖入“应用程序”文件夹。桌面端首次启动会引导填写 API Key 与默认工作目录，配置完成后的功能与 Web 版基本一致。

五、报错 1：dsh web exited with code 1

含义是 Web 服务进程异常退出，按顺序排查：

1. 端口被占用：换端口启动，如 dsh web --port 8080，或关掉占用端口的程序
2. Node 版本过低：node -v 低于 18 时升级到 LTS
3. 缓存或安装损坏：npm cache clean --force 后重装
4. 权限问题：Windows 以管理员身份运行终端，macOS/Linux 检查工作目录读写权限

六、报错 2：npx is not recognized

Windows 的 CMD/PowerShell 出现“'npx' 不是内部或外部命令”，说明 Node.js 未安装或未加入 PATH：

1. 官网下载 LTS 安装包并勾选添加到 PATH
2. 安装后必须重新打开终端
3. 检查安装目录下是否有 npx.cmd 且该目录在系统 Path 中
4. 用 nvm 时确认已 nvm use 到附带 npm 的版本

七、加载与配置 MCP 工具

在项目根目录新建配置文件（或在设置界面打开 MCP 配置），写入 mcpServers，例如 filesystem：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/projects"]
    }
  }
}

保存后重启 DSH，工具列表里能看到 filesystem 即加载成功；若某个 server 启动失败，先单独在终端运行其 command 验证，再检查 JSON 格式错误（如尾随逗号）。

八、小结

DSH 安装本身不复杂，多数失败集中在 Node 环境、端口占用和配置格式三类问题。遇到本文未覆盖的报错，可到 https://deepseekdsh.com/ 的故障修复中心按错误信息检索，那里有更全的错误对照与修复步骤。