DeepSeek Harness（dsh）保姆级下载&使用教程

DeepSeek Harness（简称 dsh）是 DeepSeek 开源的 AI Agent 智能体框架，支持文件读写、命令执行、自主规划；提供 WebUI、命令行、源码部署三种方式。

⚠️ 当前为开发者预览版，接口持续变动。

一、前置准备

1. 环境要求

• Node.js ≥ v22.19 / Node 24 LTS（强烈推荐）
  ❌ Node23、低于22.19版本大概率启动失败
• 系统：Windows / macOS / Linux 全支持
• 浏览器：Chrome / Edge（不推荐IE、老旧浏览器）
• 网络：能够正常访问 npm 仓库

2. 安装 Node.js

官网下载 LTS：https://nodejs.org/

Windows安装务必勾选 Add to PATH
安装完成，关闭所有旧终端，新开窗口验证：

node -v
npm -v

输出版本号即正常。

3. 获取 DeepSeek API Key（必备）

1. 打开 DeepSeek 开放平台：https://platform.deepseek.com/
2. 登录 → API Keys → 创建新密钥
3. 复制保存密钥（只展示一次！切勿泄露）

---

二、三种安装启动方式（任选其一）

方式1：npx 一键启动【新手首选，无需本地安装】

不需要下载源码，一行命令拉起Web界面
打开终端（CMD/PowerShell/终端）执行：

npx @deepseek-ai/dsh web

首次运行询问下载，输入 y 确认。
启动成功后终端输出地址：

dsh web: http://127.0.0.1:3080

浏览器打开链接即可进入界面。

💡 小技巧：先 cd 你的项目文件夹，再执行命令，默认工作目录就是项目目录。

方式2：全局安装【长期使用推荐】

# 全局安装
npm install -g @deepseek-ai/dsh
# 验证
dsh --version
# 启动WebUI
dsh web

方式3：源码编译部署【开发者/二次修改源码】

需要安装 Git + pnpm

# 安装pnpm
npm install -g pnpm
# 拉取源码
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
# 安装依赖
pnpm install
# 编译项目
pnpm run build
# 启动Web
pnpm dsh web

---

三、WebUI 初始化配置步骤

1. 浏览器访问：http://127.0.0.1:3080
2. 填入 DeepSeek API Key，保存
3. 选择 Workspace（工作目录）

   Agent 只能读写这个文件夹内文件，保障安全，建议单独新建项目文件夹

4. 确认权限策略：
   • 推荐默认：危险操作人工确认（命令执行、文件删除需要你点同意）
5. 进入对话界面，即可开始使用Agent。

简单测试指令示例

帮我在当前目录新建一个readme.md，简单介绍项目结构

Agent会自动规划、创建文件，所有操作可实时查看日志。

---

四、常用 dsh 命令汇总

# 启动Web面板
dsh web

# 检查环境诊断
dsh doctor

# 纯命令行对话模式
dsh chat

# 指定端口启动web
dsh web --port 3081

# 查看帮助
dsh -h

五、接入兼容OpenAI接口（可选）

如果你想用本地模型、其他厂商API（通义千问、Ollama等OpenAI兼容接口）
在设置→模型配置：

• API Endpoint：填写对应接口地址
• API Key：填入对应服务商密钥
  模型名称按需填写。

六、常见报错 & 解决方案

1. node版本过低

报错：version not supported
解决：重装 Node24 LTS

2. npx 下载缓慢/超时

切换npm国内镜像

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

3. 浏览器打不开 127.0.0.1:3080

• 检查终端进程是否正常运行，不要关闭终端窗口
• 检查防火墙拦截
• 尝试更换端口启动 dsh web --port 3081

4. API调用报错401

API Key复制错误、密钥已删除、账户无余额，重新在平台创建密钥。

5. Agent无法读写文件

确认工作目录选择正确；不要选择系统根目录。

6. Windows PowerShell 执行策略报错

以管理员打开PowerShell运行：

Set-ExecutionPolicy RemoteSigned

七、停止运行

终端窗口按下 Ctrl + C 即可关闭服务。

八、补充说明

• 配置文件存放目录：~/.dsh（Windows：C:\Users\用户名.dsh）
• 所有会话记录、密钥缓存在本地，不上传第三方；
• 项目仓库：https://github.com/deepseek-ai/deepseek-harness