DeepSeek Harness（简称dsh）是DeepSeek开源的插件化AI智能体运行框架，核心理念是一切皆插件，可以串联大模型、文件操作、Shell命令、会话日志，把基础大模型变成能够自主执行任务的编程Agent。目前处于开发者预览阶段，很多开发者在Windows部署时，频繁遇到API鉴权失败、权限策略报错、只能本地访问无法内网/公网远程使用等一系列卡点。
我们这篇文章是一份Windows完整落地实战指南，从环境准备、一键部署，到API配置、权限管控、远程访问搭建，同时集中解决部署过程中高频踩坑问题，帮你一次性跑通整套Harness服务。
重要提醒：Harness具备操作本地文件、执行系统命令的能力，有一定安全风险，不建议直接对公网无防护开放。
一、前置环境准备（Windows）
- 依赖要求
-
Node.js：最低v22.19，推荐24 LTS版本，Node版本过低会出现npx执行无输出、依赖解析失败，这是Windows用户最常见的第一个坑。
-
Git for Windows：可选，源码编译部署需要。
-
PowerShell（推荐），避免使用老旧CMD，兼容性更好。
-
DeepSeek API Key：前往DeepSeek开放平台申请，账户预留余额，否则API调用直接返回402。
验证环境，打开PowerShell执行：
powershell
node --version
输出版本号≥22.19才算合格。
国内npm加速（可选，解决下载超时）
powershell
npm config set registry https://registry.npmmirror.com
二、Windows快速本地部署
两种部署方式，推荐新手直接用npx一键启动。
方式1：npx直接运行（最简）
powershell
npx @deepseek-ai/dsh web
首次运行会自动下载依赖包，启动成功后，默认WebUI地址： http://127.0.0.1:3080 。
常见报错： JavaScript heap out of memory 内存溢出
解决方案：改用pnpm，或者全局安装再启动
powershell
npm install -g @deepseek-ai/dsh
dsh web
全局安装后提示 dsh不是内部或外部命令 ：关闭当前终端，重新打开PowerShell，刷新系统PATH环境变量。
方式2：源码部署（进阶，适合二次开发）
powershell
git clone https://github.com/deepseek-ai/deepseek-harness
cd deepseek-harness
npm install
npm run web
启动成功后浏览器访问 http://127.0.0.1:3080 ，进入Harness工作台。
三、API配置：解决401鉴权、402余额、模型调用失败
进入WebUI左下角「设置」→模型，添加模型服务商。
-
服务商ID自定义小写名称；
-
BaseURL填写 https://api.deepseek.com/v1 ；
-
API协议选择OpenAI Completions；
-
API Key填入平台密钥；
-
模型ID填写 deepseek-v4-flash 或 deepseek-v4-pro ，保存。
API高频报错排查
- 401鉴权失败
密钥复制错误、前后带有空格；密钥粘贴时不要带多余换行；确认密钥归属平台一致。
- 402余额不足
开放平台账户充值，余额不足会直接拒绝所有模型请求。
- 429请求限流
短时间Agent循环调用次数过多，降低任务并发，或者在设置中调整请求间隔。
- 连接超时
Windows防火墙、代理/VPN干扰，关闭代理重试；或者切换国内镜像加速。
小技巧：API Key存储在Harness内部，不会明文展示，只做引用存储，相对安全。
四、权限策略配置（Windows重点，防止误操作）
DeepSeek Harness可以调用工具读写本地文件、执行Shell命令，内置三层权限策略，默认推荐Workspace-Write，也是最安全的模式 ：
-
Read Only（只读）：Agent只能读取文件，不能修改、执行命令，适合测试prompt。
-
Workspace-Write（默认）：仅允许Agent在你选定的工作文件夹内读写文件，跨目录修改文件、执行系统命令，会弹出人工审批弹窗。
-
danger-full-access（完全权限）：无限制访问系统文件、执行任意命令，不推荐日常使用，风险极高。
Windows权限常见问题
- 问题：Agent无法保存文件，提示权限拒绝
原因：工作目录放在C盘Windows系统保护目录（C:\Windows、C:\Program Files）。
解决：把工作区选择在D盘新建文件夹，例如 D:\harness-workspace 。
- 问题：弹窗审批不弹出，任务直接失败
解决：确认当前Harness进程不是后台静默运行，WebUI会话保持打开状态。
- 安全建议：
不要给Harness全盘访问权限；重要文档目录不要选为工作区；任何修改系统文件的操作，人工仔细审核。
所有工具调用、命令执行都会记录会话轨迹日志，可回溯查看Agent执行的全部操作。
五、内网+公网远程访问配置
默认启动仅监听 127.0.0.1 ，只能本机访问，局域网其他电脑、手机无法打开页面。
方案1：局域网内网访问（推荐，安全）
启动时指定监听0.0.0.0，允许局域网其他设备访问。
powershell
dsh web --host 0.0.0.0
-
Windows防火墙放行3080端口（入站规则，TCP）；
-
在本机查看内网IP： ipconfig ，例如 192.168.1.100:3080 ；
-
同局域网其他电脑浏览器直接访问该地址。
风险提示：内网开放后，局域网内所有设备都可以访问Harness界面，做好权限管控。
方案2：公网远程访问（cpolar内网穿透，临时测试）
适合外网远程访问，不建议长期裸跑公网。
-
安装cpolar，创建隧道，本地端口填写3080；
-
启动隧道，获取公网访问地址；
-
浏览器访问cpolar生成的公网URL，即可在外网访问Harness工作台。
安全警告：公网暴露Harness存在较大风险，任何人访问WebUI都可以触发Agent执行本地命令，测试完成及时关闭隧道。生产环境建议增加账号密码认证、IP白名单。
六、其他高频踩坑汇总
- 端口占用：3080被其他程序占用，启动失败。
解决： dsh web --port 3081 更换端口启动。
- Agent循环空命令，任务卡住不动
属于已知预览版bug，直接终止当前会话，重新新建任务。
- Windows下插件安装失败
优先使用pnpm替代npm，减少依赖解析异常；关闭杀毒软件实时扫描，部分杀毒会拦截Node子进程。
- 工作区文件夹无法选择
路径不要包含中文、空格、特殊符号，使用纯英文路径。
七、最佳实践总结
-
Windows部署优先Node24 LTS，避开低版本带来的隐性报错；
-
API配置核对BaseURL、密钥、模型名称，优先使用deepseek-v4-flash做日常任务；
-
权限策略保持Workspace-Write，非必要不要开启full access；
-
内网远程需要 --host 0.0.0.0 并放行防火墙端口；公网访问仅临时测试，做好安全防护；
-
项目目前属于开发者预览版，版本迭代快，升级前留意破坏性变更。
DeepSeek Harness给AI Agent开发提供了非常灵活的插件化能力，Windows本地部署门槛不算高，但API鉴权、系统权限、网络访问是最容易卡住的三道关卡。把这几个环节处理好，就能在Windows上搭建一套可以自动写代码、执行脚本、批量处理文件的本地AI智能体工作台。