DeepSeek Harness 安装教程官方仓库https://github.com/deepseek-ai/deepseek-harness快速命令npx deepseek-ai/dsh web默认访问地址http://127.0.0.1:3080DeepSeek Harness简称 DSH是 DeepSeek AI 开源的 Agent 运行框架。它让大模型能够真正读写本地文件、执行命令、拆分任务是「Model Harness Agent」的一整套可插拔运行时。目前处于开发者预览版需要 Node.js 环境。目录第一步安装 Node.jsWindows 安装macOS 安装更新 Node.js删除 Node.js第二步安装并启动 Harness第三步浏览器访问首次使用三步配置常用维护与卸载常见问题排查第一步安装 Node.jsHarness 需要 Node.jsv22.19 及以上官方package.json中engines声明为^22.19.0 || 24.0.0。安装前先检查本机是否已安装及其版本node--versionnpm--version如果能输出版本号说明已装好直接跳到 第二步。版本管理工具强烈推荐相比手动下载安装包更推荐使用版本管理工具来安装 Node.js。它能让你随时切换、升级、多版本共存也方便彻底卸载。Windows 用nvm-windows或fnmmacOS 用nvm或fnmWindows 安装方式一官网安装包最省事访问 Node.js 官网 https://nodejs.org 下载LTS长期支持版本安装包.msi。双击运行一路「下一步」即可。默认会同时安装npm并写入系统PATH。安装完成后重新打开终端验证node--versionnpm--version方式二用 nvm-windows多版本切换到 nvm-windows 的 GitHub 发布页下载nvm-setup.ziphttps://github.com/coreybutler/nvm-windows/releases解压并运行安装。安装并启用某个 LTS 版本nvminstall22.19.0 nvm use22.19.0node--version方式三用 fnm快速且跨平台# 用 PowerShell管理员执行wingetinstallSchniz.fnm# 或直接下载安装脚本后初始化fnminstall22fnm use22node--version方式四用 winget 直接安装wingetinstallOpenJS.NodeJS.LTSmacOS 安装方式一Homebrew推荐# 安装 Node.js LTSbrewinstallnode22# 让命令可用Homebrew 会把 22 链接到 PATHbrewlink--overwritenode22# 验证node--versionnpm--version方式二官网.pkg安装包访问 https://nodejs.org 下载 macOSLTS的.pkg安装包。双击运行按提示完成安装。打开终端验证node--versionnpm--version方式三用 nvm多版本切换# 安装 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh|bash# 重新加载 shell 配置或新开一个终端source~/.zshrc# 若用 bash 则 source ~/.bashrc# 安装并启用某个 LTS 版本nvminstall22nvm use22node--version方式四用 fnmbrewinstallfnm# 在 .zshrc 里加入 eval $(fnm env --use-on-cd) 后重开终端fnminstall22fnm use22node--version更新 Node.js⚠️ 版本管理工具nvm / fnm会方便得多建议优先使用。Windows# 用 nvm-windowsnvminstall新版本号# 例如 nvm install 24.0.0nvm use新版本号node--version# 或用 winget 升级winget upgrade OpenJS.NodeJS.LTSmacOS# 用 nvm 升级nvminstall24nvm use24node--version# 或用 Homebrew 升级brew upgrade node22删除 Node.jsWindows —— 方式一安装包方式「设置 → 应用 → 已安装的应用」中找到Node.js点击卸载。删除残留目录可选用于彻底清理rd/s/q%APPDATA%\npmrd/s/q%APPDATA%\npm-cacherd/s/qC:\Program Files\nodejsWindows —— 方式二nvm-windowsnvm uninstall22.19.0# 卸载指定版本# 彻底卸载 nvm-windows到「控制面板 → 程序」卸载 NVM for WindowsmacOS —— Homebrewbrew uninstall --ignore-dependencies node22 brew cleanuprm-rf~/.npmrm-rf~/.node-gypmacOS —— nvmnvm uninstall22rm-rf~/.nvm# 再移除 .zshrc / .bashrc 里与 nvm 相关的加载行第二步安装并启动 Harness确认 Node.js 版本满足要求后打开终端Windows 用 CMD 或 PowerShellmacOS 用「终端」执行npx deepseek-ai/dsh web首次运行会发生以下几件事npx会询问是否安装deepseek-ai/dsh包输入y回车确认。自动从 npm 拉取并安装依赖需要联网首次可能稍慢。下载完成后自动在本地启动 Web 服务。快捷方式若已全局安装过npm install -g deepseek-ai/dsh可直接用dsh web启动。想用别的端口当 3080 被占用时npx deepseek-ai/dsh--profileweb--port8080看到终端输出本地地址后说明启动成功。保持这个终端窗口不要关闭服务运行期间关闭终端会停止服务。第三步浏览器访问启动成功后打开浏览器访问http://127.0.0.1:3080这是本地回环地址只在本机生效不会对外暴露不用担心别人访问。首次打开会弹出页面让你填入模型API Key。若该页面未能打开请先确认上面启动命令的终端窗口仍在运行。首次使用三步配置浏览器打开后界面输入框默认是灰色的需要先完成三步才能开始对话配置模型 API Key进入Settings → Models在 DeepSeek 卡片中填入你的 API Key以sk-开头。没有的话到 DeepSeek 开放平台创建一个。也支持接入 OpenAI、Anthropic、Google 等近 40 家厂商或任意 OpenAI 兼容接口。Key 只保存在本地$DSH_HOME/.credentials.yamlWindows 下默认C:\Users\用户名\.dsh界面不回显明文。选择工作区点击Choose workspace添加并选中你想让 Agent 操作的项目目录。未选中前输入框不可用。派发任务新建会话输入一句任务指令例如「总结这个仓库说明主要的包结构」Agent 会开始读取文件、执行命令并给出结果。涉及写操作时会按权限策略弹出确认。常用维护与卸载常用命令# 启动 Web 界面npx deepseek-ai/dsh web# 用 headless 模式运行一次性任务适合脚本 / CInpx deepseek-ai/dsh--profileheadless运行当前项目的测试# 查看组合后的完整配置树npx deepseek-ai/dsh--profileweb --dump-config更新 Harness由于用npx按需拉取每次运行npx deepseek-ai/dsh web时npx会优先使用 npm 缓存若需要强制更新到最新版# 清掉 npx 缓存后重装npx--yesdeepseek-ai/dshlatest web若是全局安装方式则直接升级npminstall-gdeepseek-ai/dshlatest删除 Harness方式一清除 npx 缓存npmcache clean--forcenpx clear-npx-cache# 部分 npm 版本可用方式二若曾全局安装过# 查看是否全局安装npmlist-g--depth0# 卸载npmuninstall-gdeepseek-ai/dsh方式三清理本地配置与数据删除 Harness 保存在本地的配置目录Windows 默认为C:\Users\用户名\.dshmacOS/Linux 在$DSH_HOME对应目录。删除后本地 API Key、会话记录等将一并清除请谨慎操作。常见问题排查现象处理方法node: not found/node 不是内部或外部命令Node.js 未安装或未写入 PATH重新安装或重开终端Node.js version ... is not supportedNode 版本过低升级到 v22.19见更新 Node.js首次npx卡住或下载失败检查网络必要时配置 npm 镜像后重试npm config set registry https://registry.npmmirror.com端口 3080 被占用换端口npx deepseek-ai/dsh --profile web --port 8080页面打不开确认启动命令的终端窗口仍开着且地址确实是http://127.0.0.1:3080输入框灰色无法输入还未选择工作区去Choose workspace选中目录提示需要 API Key进入Settings → Models填入以sk-开头的 Key补充从源码运行可选如果想体验最新开发版本或参与贡献可以克隆源码运行需要pnpm用npm install -g pnpm安装gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web⚠️ 预览版迭代较快接口和插件可能有破坏性变更请留意版本兼容性。
