-
- DeepSeek Harness 官方仓库
- 官方模型配置指南
- 官方 Web UI 说明
- 官方 Safe Use Policy
- 官方 Data Processing Statement
- CSDN 社区教程参考:DeepSeek Harness 快速上手、全局安装与 VS Code 实践、从 0 到 1 安装避坑等相关文章。本文仅参考章节组织,内容已重新核验与改写。
DeepSeek Harness(命令名
dsh)是 DeepSeek AI 开源的 Agent Harness。它不是“下载 DeepSeek 模型权重并在显卡上推理”的模型部署工具,而是给大模型装上文件读写、命令执行、工具调用、会话记录、权限沙箱和 Web 界面的智能体运行环境。本文参考 CSDN 多篇快速上手、全局安装和避坑教程的章节组织,所有版本要求、启动命令与配置路径均再次对照 DeepSeek 官方仓库和官方文档核验。完成后,你将能启动 Web UI、配置模型、选择安全工作区、完成第一个任务,并掌握源码部署、Headless、SSH 远程访问和常见故障排查。
版本提示:截至 2026-09-19,DeepSeek Harness 仍处于 Developer Preview,升级可能包含不兼容变更。长期使用请固定版本,并先在隔离目录、虚拟机或容器中验证。

DeepSeek Harness:模型、工具、技能、存储和界面都由插件组合。图片来源:DeepSeek 官方网站。 一、先分清:Harness 不是模型本体
可以把 Agent 理解为“模型 + Harness”:模型负责思考,Harness 负责连接真实环境。DeepSeek Harness 通过插件组合模型、工具、技能、会话、沙箱、存储、调度与 UI。它默认调用云端模型 API,不要求下载几十 GB 的模型权重,也不要求本机有独立显卡。
如果你要的是 Ollama 或 vLLM 本地推理,这篇不是模型权重部署教程;但可以把兼容 OpenAI 协议的本地模型服务配置成 DSH 的自定义 Provider。
二、部署前检查
项目 要求或建议 操作系统 Windows 10/11、macOS、Linux Node.js ^22.19.0或>=24.0.0,建议 Node.js 24 LTS包管理工具 npm/npx;源码方式额外需要 pnpm Git 仅源码部署必需 端口 默认 127.0.0.1:3080模型凭据 DeepSeek API Key 或其他 Provider 的 Key 工作区 单独创建的测试目录,不要选择整个用户目录 检查版本:
node -v npm -v npx -vNode.js 低于 22.19 时先升级。旧版 Node.js 或 Bun 可能缺少项目依赖的运行时 API。
三、方案 A:npx 一行启动(新手首选)
1. 创建隔离工作区
Windows PowerShell:
New-Item -ItemType Directory -Path "$HOME\dsh-workspace" -Force Set-Location "$HOME\dsh-workspace"macOS / Linux:
mkdir -p ~/dsh-workspace cd ~/dsh-workspace2. 启动 Web UI
npx @deepseek-ai/dsh web首次执行时,npx 可能询问是否下载并运行软件包,确认后等待依赖下载。成功时终端会打印:
dsh web: http://127.0.0.1:3080
npx 一行启动并打印本地 Web UI 地址。截图来源:DeepSeek Harness Plugins 安装教程。 本机通常会自动打开浏览器。只启动服务、不自动打开:
npx @deepseek-ai/dsh web --no-open端口被占用时:
npx @deepseek-ai/dsh web --port 30813. 停止服务
回到启动 DSH 的终端按
Ctrl+C。Web UI 由这个前台进程提供,关闭终端或停止进程后页面会失去连接。四、方案 B:全局安装(经常使用可选)
部分 CSDN 教程采用全局安装,适合希望在任意项目目录直接使用
dsh命令的人:npm install -g @deepseek-ai/dsh dsh web检查命令:
dsh --help官方 README 的最短路径仍是 npx。全局命令找不到时,先执行
npm prefix -g检查全局目录是否在 PATH;也可以退回 npx,避免为一次体验修改系统 PATH。五、可选:把 DSH 数据放到指定磁盘
默认 Harness Home 是
~/.dsh,Windows 一般位于C:\Users\用户名\.dsh。它保存设置、凭据引用、Profile、插件、缓存和会话日志。Windows 当前终端临时指定:
New-Item -ItemType Directory -Path "D:\DeepSeekHarness" -Force $env:DSH_HOME="D:\DeepSeekHarness" npx @deepseek-ai/dsh web永久设置到当前用户:
[Environment]::SetEnvironmentVariable("DSH_HOME", "D:\DeepSeekHarness", "User")设置后重新打开终端,用
$env:DSH_HOME验证。macOS/Linux 可在启动前执行:export DSH_HOME="$HOME/.dsh"已经使用过 DSH 时不要直接删除原目录;先备份会话、设置、凭据和 Profile。
六、首次启动:从欢迎页到可用会话
1. 阅读 Developer Preview 提示
首次进入可能出现测试或预览提示。重点是:项目仍快速迭代,插件与配置可能变化;生产仓库不要直接授予最大权限。

首次启动的 Developer Preview 提示。截图来源:DeepSeek Harness Plugins 安装教程。 2. 选择 Workspace
Workspace 是 Agent 读取和修改文件的主要边界。第一次建议选择空的
dsh-workspace,不要选择桌面根目录、用户主目录或包含密钥的生产仓库。
首次启动选择 Workspace 和模式。截图来源:DeepSeek Harness Plugins 安装教程。 3. 配置 DeepSeek API Key
进入“Settings/设置 → Models/模型”,打开 DeepSeek 卡片,填入 Key 并保存。Key 是只写的:保存后页面只拿到脱敏描述,明文保存在
$DSH_HOME/.credentials.yaml,设置文件只保存凭据引用。模型设置修改后下一次请求直接生效,一般不需要重启。
官方 Models 页面:配置 DeepSeek 或添加其他 Provider。图片来源:DeepSeek Harness 官方文档。 4. 添加其他模型或自定义网关
“Add provider”可选择内置提供方;“Add a custom provider”适合企业网关、第三方 API 或本地模型服务。至少填写小写 Provider ID、Base URL、API 协议、凭据和一个模型 ID。
openai-completions:OpenAI Chat Completions;openai-responses:OpenAI Responses API;anthropic-messages:Anthropic Messages API。
协议必须与端点一致。“Fetch available models”失败不等于端点不能用;部分网关不提供兼容模型列表,可手工添加模型 ID。

自定义 Provider:填写 ID、Base URL、协议、Key 和模型。图片来源:DeepSeek Harness 官方文档。 5. 选择权限
- Read Only:只读检查,适合第一次验证;
- Workspace Write:允许修改工作区,适合日常编码;
- Full Access:范围最大,只对完全可信任务使用。
权限策略决定“该不该做”,沙箱决定“能不能做到”。即使模型很强,也不要跳过权限边界。

Read Only、Workspace Write 与 Full Access。截图来源:DeepSeek Harness Plugins 安装教程。 6. 选择 Preset
版本不同,UI 可能显示 Standard、PTC/Code、Minimal、Creator:
- Standard:完整编码 Agent,日常首选;
- PTC/Code:模型用代码编排多轮工具调用,适合批量任务;
- Minimal:精简工具集,适合基准测试;
- Creator:检查运行时、实验插件和创建自定义 Preset。

四种 Agent Preset。截图来源:DeepSeek Harness Plugins 安装教程。 7. 查看插件
打开 Settings → Plugins 可以看到 Shell、Agent Loop、Web Search 等组件。Everything is a Plugin 不是口号,而是实际可查看、配置和替换的运行树。

Settings → Plugins 中的插件列表。截图来源:DeepSeek Harness Plugins 安装教程。 七、跑通第一个任务
新建会话后先用只读提示验证环境:
读取当前工作区,列出文件并说明用途。不要修改任何内容。确认读取正常后,再测试写入:
在当前工作区创建 hello-dsh.md,写入标题“Hello DeepSeek Harness”,完成后重新读取文件并报告结果。建议检查三件事:文件是否真实生成、内容是否正确、Trajectory 是否记录了工具调用与结果。不要只相信模型口头说“完成”。

Trajectory 会记录初始提示、步骤和工具调用。截图来源:DeepSeek Harness Plugins 安装教程。 
任务跟踪器展示创建文件、写代码和运行测试等进度。截图来源:DeepSeek Harness Plugins 安装教程。 八、从源码部署
适合开发插件、修改 Harness 或参与贡献:
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,否则 Web 前端产物缺失。项目固定 pnpm 版本;pnpm不可用时先确认 Node.js,再执行corepack enable。九、远程服务器与 SSH 端口转发
服务器端:
npx @deepseek-ai/dsh web --no-open本地电脑:
ssh -L 3080:127.0.0.1:3080 your-user@your-server本地浏览器打开
http://127.0.0.1:3080。不要把 Agent 管理界面直接裸露到公网;优先保持回环监听并使用 SSH、可信反向代理或专用内网。十、Headless:脚本与 CI 的一次性任务
npx @deepseek-ai/dsh --profile headless "检查当前项目并总结测试失败原因,不要修改文件"Headless 不打开浏览器、不监听 HTTP 端口,任务结束后退出。完成时退出码为 0,中止或报错时为 1。
十一、更新与版本固定
Developer Preview 可能出现破坏性更新。稳定使用建议固定验证过的版本:
npx @deepseek-ai/dsh@<已验证版本> web全局安装升级:
npm update -g @deepseek-ai/dsh升级前备份
$DSH_HOME并查看 GitHub Releases。十二、常见报错与解决方法
1. Node.js 版本不支持
升级到 Node.js 22.19+ 或 24+,重新开终端后检查
node -v。2. PowerShell 提示脚本被禁用
这是 PowerShell 执行策略阻止 npm 生成的脚本入口,不代表 DSH 包损坏。可先改用命令提示符或执行
npx.cmd @deepseek-ai/dsh web;是否修改系统执行策略应根据公司安全要求决定。3. 3080 端口被占用
npx @deepseek-ai/dsh web --port 30814. 页面没有自动打开
查看终端打印的地址并手动打开;SSH 场景使用端口转发。
5. 模型请求报 401/403
检查 Key、账户额度、Base URL 与协议。自定义网关还要检查模型 ID 是否与服务端配置一致。
6. 获取模型列表失败
端点可能不提供兼容列表。只要推理接口正常,可在自定义 Provider 中手工填写模型 ID。
7. 源码启动提示前端未构建
pnpm install pnpm run build pnpm dsh web8. Agent 读取了错误目录
停止服务,切换到正确目录再启动,或在 UI 中重新选择 Workspace。检查当前权限,不要用 Full Access 掩盖路径配置错误。
十三、安全清单
- 用隔离工作区、虚拟机或容器试运行;
- 不把用户主目录或密钥目录设为 Workspace;
- API Key 只放设置页、环境变量或
.env,不要提交到 Git; - 不可信仓库、网页和文档可能包含提示注入;
- 外部模型、MCP、插件和网络工具可能上传数据,启用前确认目的地;
- 高权限操作保留人工审批;
- 升级前备份
$DSH_HOME并阅读 Release Notes。
总结
新手先用:
npx @deepseek-ai/dsh web随后依次完成模型配置、隔离 Workspace、Read Only 验证和 Workspace Write 写入测试。经常使用可以全局安装;要改源码或开发插件再走 pnpm 构建;CI 和自动化使用 Headless。
© 版权声明
文章版权归作者所有,未经允许请勿转载。
THE END




暂无评论内容