DeepSeek Harness 排错指南：常见错误与修复

按症状找原因，而不是按模块翻文档。这一篇按"先看什么、常见症状、诊断命令"组织，遇到问题时从上往下走一遍。

出问题时先做三件事

1. 看配置树：dsh --dump-config——多数"不生效"问题的答案都在这（机制见 配置层与 patch）
2. 看日志：会话日志记录每一步动作与工具调用（位置见 会话与记忆）
3. 看错误码：DSH 的错误信息是结构化的，报错文本本身往往就是排查提示

症状 → 原因 → 处理

启动类

症状	可能原因	处理
启动即失败、退出码非零	profile 配置错误 / 缺插件依赖	用 dump 看配置；检查cordis.patch.yml 语法
"等不到服务提供方"	某行 inject 的服务无人提供	找到该行，确认其依赖行也在组合里
端口被占	3080 冲突	换端口：dsh --profile web --port 8080
Windows 上 b​ash 相关报错	Windows 用 pwsh 执行栈，不支持 b​ash 行	保持默认配置；如需 b​ash 要完整重配执行栈（进阶）

配置类

症状	可能原因	处理
改了 patch 不生效	写错文件/层级，或行 id 不对	--dump-config 看该行最终值
改一个字段、别的字段回默认	patch 替换整行而非合并	重述该行全部字段
两个文件都改同一行	层越高越优先，低层被覆盖	确认你改的是想要的那层

模型类

症状	可能原因	处理
MISSING_CREDENTIAL	密钥没存/环境变量缺失	模型页保存密钥，或补环境变量
UNKNOWN_MODEL	选了不存在的模型	重选已配置模型，或给自定义提供方补模型
获取模型列表 401	密钥错误	换密钥重试

运行时类

症状	可能原因	处理
agent 说"文件访问被拒"	权限模式不够 / 路径超出工作区	确认模式与路径；必要时提权（见沙箱与安全）
工具调用超时	单次调用超预算	检查该工具的超时配置；任务本身耗时过长则拆解
agent 不用某个工具/技能	未挂载 / description 触发条件不清	dump 确认挂载；改 description
MCP 工具不出现	服务器启动失败 / 配置行未加载	看配置树；检查 MCP 服务器本身能否运行

最后手段：重置

排查陷入死胡同时的阶梯式重置（从轻到重）：

1. 备份 ~/.dsh，删掉 settings.yaml 里的可疑块 → 重启看是否恢复
2. 重建某个 profile（删 profile 目录，首次启动自动重新初始化）
3. 彻底重置：备份后删除 ~/.dsh（会话历史、凭据、配置全清，谨慎）

接下来读什么

• 高频问题 → 常见问题 FAQ
• 去哪求助 → 资源与社区入口

---

← 上一篇：7.1 常见问题 FAQ | 下一篇：7.3 资源与社区入口 →

↑ 返回 教程总目录