帮助与生态

故障排查

安装依赖、模型网络、端口、工作区、权限审批与构建错误的排查指南

按「症状 → 原因 → 修复」排查 DeepSeek Harness 的常见问题。每节先给现象，再给最可能的原因与可操作的处理。若本节未覆盖，请到社区反馈。

开始之前：三项快速检查

遇到问题时，先按顺序确认这三点，能排除大部分情况：

Node 版本：node --version 应满足 ^22.19 或 >=24。
密钥有效：确认模型 API 密钥可用，且网络能访问 API 端点。
网络可用：首次启动与模型调用都需要网络。

安装与依赖

症状	原因	修复
`pnpm install` 失败、报依赖缺失或校验错误	pnpm store 缓存损坏或陈旧	运行 `pnpm store prune` 清理陈旧缓存后重新 `pnpm install`；必要时删除 `node_modules` 再重装
依赖下载缓慢或超时	网络或 npm 源不可达	检查网络，必要时换用可达的 npm 源后重试
安装报错指向 pnpm 自身	pnpm 版本过旧	升级 pnpm 到较新版本后重试
安装插件时被拒绝，提示 `prepare` 脚本未运行	pnpm ≥10 在得到显式允许前拒绝运行 git 依赖的 `prepare` 脚本	把 pnpm 打印的确切包键复制进该 profile 的 `pnpm-workspace.yaml`（`onlyBuiltDependencies`）；详见插件
构建产物缺失或命令找不到	Node 版本不符	确认 `node --version` 满足 `^22.19` 或 `>=24`，详见安装与启动
提示「`npx`/`node` 不是内部或外部命令」	Node 未安装，或安装后没有重开终端	重新安装 Node.js 并重开终端；Windows 注意安装器是否勾选了加入 PATH，详见安装与启动
首次 `npx` 卡住	正在下载依赖，或网络不通	确认网络可用，等待首次下载完成

模型与网络

症状	原因	修复
模型不响应或超时	密钥无效、网络无法访问 API 端点、Base URL 填错	检查密钥是否有效、网络能否访问端点、Base URL 是否正确，见配置模型
请求被代理拦截或超时	代理环境变量配置有误	检查 `HTTP_PROXY` / `HTTPS_PROXY`，确认代理不拦截模型端点
提示 `MISSING_CREDENTIAL`	缺少提供方凭据	通过模型页保存密钥，或提供被引用的环境变量
提示 `UNKNOWN_MODEL`	请求的模型未配置	选择已配置的模型，或向自定义提供方添加缺失模型
「获取可用模型」返回 401	密钥错误或服务不提供 `GET /models`	检查密钥；对不提供该端点的服务手动输入模型
新会话仍使用旧模型	已发送过请求的会话会保留日志中记录的模型	在模型选择器切换；该选择只会成为新会话的默认值
输入框显示「选择模型」并阻止输入	已保存的默认值指向已删除的提供方	重新选择一个模型
图片在发送前被拒绝	模型未声明图片模态	给自定义提供方的模型加 `input: [text, image]`；DeepSeek 自身的 chat-completions 路由为纯文本，无法通过配置改变
提供方拒绝了带图片的请求	模型声明了端点实际不支持的图片能力	从授予图片能力的列表中移除 `image`（模型的 `input` 或路由的 `defaultInput`），然后开启新会话

端口冲突

症状	原因	修复
启动即失败，报告 `EADDRINUSE`	默认端口 `3080` 已被占用	换端口：`dsh --profile web --port 8080`（`--port` 属于 web 应用）；或先释放占用进程
不清楚实际监听的端口	端口配置为 `0` 时由操作系统分配	以命令打印的地址为准

工作区

症状	原因	修复
会话输入框不可用	尚未选中工作区	点击选择工作区，添加并选中启动 `dsh` 时所在的目录
读写文件被拒绝	操作超出当前沙箱授权的工作区范围	把目标文件放进工作区，或调整权限预设；不要追求过宽的访问范围
找不到预期的文件	工作区指向了错误的目录	重新选择正确的项目目录作为工作区

权限与审批

症状	原因	修复
操作反复要求审批	当前权限预设要求对敏感操作逐一确认	检查权限预设；日常使用保留带询问的档位（如 `workspace-write`）
操作被沙箱拒绝、无法升权	主体不得获得超出既有授权的权限（非升权）	在权限预设允许的范围内重试；确需更宽权限时，由你切换预设或明确批准该次调用
受限沙箱报 `SANDBOX_UNAVAILABLE`	当前环境未提供所需的沙箱后端	改用当前环境可用的沙箱模式或预设

构建错误

症状	原因	修复
`pnpm run build` 失败	Node 版本不符、依赖未完整安装、或仓库未同步	确认 Node `^22.19` 或 `>=24`，重新 `pnpm install` 后重试 `pnpm run build`
从源码启动报模块解析错误	未先执行 `pnpm run build`	先完成构建再运行 `pnpm dsh <args...>`，见安装与启动

还不行？

以上都没有命中时，带上复现步骤、Node 版本与报错信息，到社区反馈。

常见问题

安装、模型配置、工作区、审批、headless 与插件安装的常见问题解答

安全与合规

数据路径、部署风险三档、企业安全基线、供应链与许可证边界

本页目录

开始之前：三项快速检查安装与依赖模型与网络端口冲突工作区权限与审批构建错误还不行？