DeepSeek Harness（命令行里叫 dsh）是 DeepSeek 官方开源的 agent harness，MIT 协议，架构上是「一切皆插件」。它不像普通软件只有一个入口——你可以只跑命令行，可以开个 Web UI 当界面用，也可以当成 Python 库嵌进自己的程序。

这篇只解决一件事：把它在你的 Windows 或 macOS 上跑起来。

三个前提先说清楚：

  • 项目还在开发者预览阶段，官方自己写了「未来将出现破坏兼容性的变更」，别直接装在要长期稳定的生产机上。
  • Web UI 需要一个 DeepSeek API Key，去 platform.deepseek.com 注册就能拿。
  • 完全不想碰命令行的，看「方法四」，装个桌面客户端就行。

一、先选一条路

方式 适合谁 需要先装什么
npx 免安装 只想先试试 Node.js
npm 全局安装 打算长期用命令行 Node.js
源码构建 要跟最新代码、要改代码 Node.js + pnpm + Git
DSH Desktop 桌面客户端 完全不想碰命令行 无，安装包自带运行时
Python SDK 要把 agent 嵌进 Python 程序 Python 3.10+

Node.js 版本要求：22.19 以上，22 LTS 或 24 都行，别用太老的版本。

二、Windows

2.1 装 Node.js

走 npx / npm / 源码这三条路才需要，桌面客户端跳过。

方法一：官网安装包（推荐）

  1. 打开 nodejs.org，下载 LTS 版
  2. 双击 .msi，一路默认下一步

方法二：包管理器

1
2
3
4
5
6
7
8
# winget（Win10 1809+ / Win11 自带）
winget install OpenJS.NodeJS.LTS

# 或者 Chocolatey
choco install nodejs-lts

# 或者 Scoop
scoop install nodejs-lts

装完重开一个 PowerShell，验证：

1
2
node -v
npm -v

能打印版本号就算好了。后面所有命令都建议在 PowerShell 里跑，别用老 CMD。

2.2 方法一：npx，一行启动

不装任何东西，直接拉最新的包跑：

1
npx @deepseek-ai/dsh web

跑完会在 http://127.0.0.1:3080 起服务，并自动用默认浏览器打开。两个常用参数：

1
2
npx @deepseek-ai/dsh web --no-open      # 只起服务，不弹浏览器
npx @deepseek-ai/dsh web --port 8080    # 换端口

国内下载慢的话，先切镜像：

1
npm config set registry https://registry.npmmirror.com

2.3 方法二：全局安装

想在任意目录敲 dsh 就能用，就装到全局：

1
2
3
npm i -g @deepseek-ai/dsh --registry=https://registry.npmmirror.com
dsh --version
dsh web

以后升级也是重跑一遍这条命令。

2.4 方法三：从源码跑

要跟最新代码，或者想自己改点什么：

1
2
3
4
5
6
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install
pnpm run build
pnpm dsh web

pnpm run build 不能省，它负责生成前端产物；pnpm dsh web 直接吃这些产物，不会再构建一遍。corepack enable 失败的话，直接 npm i -g pnpm 也一样。

2.5 方法四：DSH Desktop 桌面客户端

官方目前只发 npm 包，没有官方桌面版。zhu1090093659/dsh-web 这个社区项目（Apache-2.0）把 Web GUI 打包成了双击即用的桌面应用：

  1. 打开它的 Releases，下 Windows 的 dsh-desktop-<版本>-win-x64.exe
  2. 双击安装，启动就能用

不想走安装器的话，同页面还有 win-x64.zip 免安装包。有几点跟命令行版不一样，值得先知道：

  • 安装包自带 Node.js 运行时（含 npm、pnpm）、dsh 宿主和预装好的 web profile（官方 web bundle + dsh-web 插件全家桶），所以不用先装 Node，也不用装 dsh CLI；
  • 它在 3082–3181 端口段起自己的宿主，不占 dsh web 的 3080/3081，两边可以同时开、会话各自独立；
  • 和命令行版共用 ~/.dsh，配置、会话、密钥都是同一份；
  • 安装包没有做代码签名，Windows 首次运行会弹 SmartScreen，点「更多信息 → 仍要运行」；
  • 插件在应用内的插件管理器里装，不需要外部工具链。

三、macOS

3.1 装 Node.js

方法一：Homebrew（推荐）

1
2
brew update
brew install node

方法二：官网安装包

去 nodejs.org 下 .pkg，双击按向导装，官网会自动判断 Intel 还是 Apple Silicon。

验证：

1
2
node -v
npm -v

3.2 三种命令行装法

命令和 Windows 完全一样，照抄：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# npx
npx @deepseek-ai/dsh web

# 全局安装
npm i -g @deepseek-ai/dsh
dsh web

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

唯一的区别：从源码装依赖时如果报编译错误，先补上命令行工具：

1
xcode-select --install

3.3 桌面客户端

还是上面那个 DSH Desktop，按芯片下对应的包：

  • M 系列芯片：dsh-desktop-<版本>-mac-arm64.dmg
  • Intel 芯片：dsh-desktop-<版本>-mac-x64.dmg

安装包同样没签名，第一次打开会被 Gatekeeper 拦下来，右键点应用图标选「打开」，再确认一次即可。自带运行时、独立端口段、共用 ~/.dsh 这些特性跟 Windows 版一样。

四、还有一种玩法：Python SDK

如果你不是要给自己用界面，而是想把 agent 嵌进 Python 程序，那装 SDK 更合适。需要 Python 3.10 以上。

macOS：

1
2
3
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

Windows PowerShell：

1
2
3
py -3.10 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install deepseek-harness-sdk

SDK 自带配套的 dsh 运行时，不用系统再装一遍 Node。装完就能在代码里 from deepseek_harness import DeepSeekHarness。

五、填 API Key

服务起来了也还不能直接聊天，得先配模型密钥。

DSH 设置里的模型页

打开 设置 → 模型，把 platform.deepseek.com 拿到的 API Key 填进 DeepSeek 那一栏，点保存。保存即生效，不用重启服务。

要用第三方中转或者别的 OpenAI 兼容端点，点下面的「添加自定义提供方」：

添加自定义提供方

  • Provider ID：小写标识，随便起，比如 my-gateway
  • API 地址：填到 /v1 为止
  • API 协议：OpenAI 兼容的选 openai-completions
  • API 密钥：中转站给你的 key

如果你只用 headless 这类纯命令行模式，不想开界面配置，直接给环境变量也行：

1
2
# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-你的key"
1
2
# macOS
export DEEPSEEK_API_KEY=sk-你的key

六、装完之后

  • 先选工作区。Web UI 刚打开时没有工作区，不选的话输入框是灰的。点「选择工作区」，把它加到启动 dsh 时所在的目录。
  • 一次性问题。dsh --profile headless "帮我总结这个仓库"，答完就退出，适合写进脚本。
  • 想换端口、想让局域网访问。dsh web --port 8080、dsh web --host 0.0.0.0。
  • 数据在哪。默认在 ~/.dsh，profile、插件、会话日志都在里面；换位置就设环境变量 DSH_HOME。

七、几个容易踩的坑

端口被占

报 EADDRINUSE 就是端口冲突，换个：dsh web --port 8081。

命令找不到

全局装完敲 dsh 提示「不是内部或外部命令」，先重开一个终端窗口；还不行就看看 npm 全局目录进没进 PATH（npm config get prefix）。

代理的问题

DSH 会读标准的代理环境变量：

1
2
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY  = "http://127.0.0.1:7890"

反过来，如果你在用国内中转、不想走代理，记得把 NO_PROXY 加上对应域名。

升级

npx 每次自动拉最新；全局装的 npm i -g @deepseek-ai/dsh；源码装的 git pull && pnpm install && pnpm run build；DSH Desktop 在 Releases 里下新版装上就行。

DSH 现在迭代很快，文档和 CLI 参数都可能变。遇到对不上的地方，以 官方仓库 和在线文档 为准。