CH 07 · 排障速查
本章目标
跑起来之后遇到问题，不用慌，按这张地图对号入座。把最常见的启动、配置、运行三类问题一次讲清。
启动起不来
dsh web 启动相关的坑就三个：
| 现象 | 原因 | 处理 |
|---|---|---|
| 启动报端口被占用 | 3080 被别的程序占了 | 启动时换端口：dsh web --port 8080（这是启动命令的一部分，不是运行中能改的） |
| 浏览器没自动打开 | 某些环境不会自动拉起浏览器 | 手动访问 http://127.0.0.1:3080（换了端口就访问对应的） |
| 服务用着用着自己退了 | dsh 服务有时候会自退 | 不是坏了，需要用的时候重新跑一次就行 |
配置相关报错
模型配置阶段，报错就那几类，对号入座：
| 报错 | 意思 | 处理 |
|---|---|---|
MISSING_CREDENTIAL | 没配密钥 | 去 设置 → 模型 存密钥，或提供它引用的环境变量 |
INVALID_CREDENTIAL | 密钥格式不对 | 检查你填的 Key 有没有多空格、少字符 |
UNKNOWN_MODEL | 模型不存在或没配置 | 检查模型 ID 是否已配置；再检查这个提供商是否支持这个模型 |
UNSUPPORTED_REASONING_EFFORT | 推理档位不支持 | 用 off / low / high / max 之一 |
| 获取可用模型返回 401 | 密钥不对 | 检查密钥；模型发现会调 OpenAI 兼容的 GET /models 接口，不提供该接口的服务就手动输入模型 |
运行时的请求报错
请求发出后报 HTTP 错误码，多数是 DeepSeek 服务端状态，跟你的配置无关。官方错误码速查：
| 错误码 | 意思 | 处理 |
|---|---|---|
| 401 | 认证失败 | 检查 API Key 是否有效、有没有过期 |
| 402 | 余额不足 | 去 DeepSeek 开放平台充值 |
| 422 | 参数错误 | 按错误信息修改请求参数 |
| 429 | 请求太频繁 | 降低请求频率，稍等重试（别连续猛发） |
| 500 | 服务器内部故障 | 等一会儿重试；一直报就找官方 |
| 502 | 网关错误 | 上游模型服务不可用，稍等重试 |
| 503 | 服务器繁忙 | 服务端负载高，稍后重试 |
另外 dsh 内部还会把错误归成几个稳定代号（AUTH 认证失败、QUOTA 额度、RATE_LIMIT 限流、CONTEXT_WINDOW_EXCEEDED 上下文超限、TRANSPORT 网络传输失败等）。看到这些代号，先按字面意思猜，多半就是它。
界面上的两个小坑
- 模型选择器显示"选择模型"、输入框输不进：你之前设的默认模型，指向的提供方被删了。重新选一个模型即可恢复。
- 找不到 headless 跑过的任务：去会话列表的未分组里找（CH 05 讲过：文件按工作区存，界面显示归未分组，两回事）。
先试的三板斧
遇到说不清的问题，按这个顺序来，能解决一大半：
- 看日志：启动时的终端输出，或重定向的启动日志（比如
dsh web > .dsh-startup.log 2>&1），报错码就在里面。 - 让 AI 自己查配置树：直接在会话里问它用
--dump-config检查配置，把"为什么默认模型不是我想用的"这类问题丢给它定位（CH 05 讲过这招）。 - 重启服务：dsh 服务本来就会自退，重跑一次经常就好了。
三板斧都救不回来，按你的底子分两种情况：
- 纯新手（dsh 是你用的第一个 Agent）：去官方仓库的 Issues 搜同样的报错关键词，大概率有人踩过。
- 已经用过 Claude Code、Codex 这类工具：直接让他们帮你排查问题。
这一章你学到了什么
- [ ] 知道启动三坑（端口占用 / 浏览器没开 / 服务自退）分别怎么处理
- [ ] 能对照配置报错表处理
MISSING_CREDENTIAL、UNKNOWN_MODEL、UNSUPPORTED_REASONING_EFFORT - [ ] 认识运行时常见 HTTP 错误码（401 / 402 / 429 / 500 / 502 / 503）的含义和基本处理
- [ ] 知道"选择模型"锁输入框是默认模型指向已删提供方
- [ ] 遇到新问题会用三板斧（看日志 / dump-config / 重启）先排查