本篇导读

预计阅读时间：7 分钟。收录新手最常踩的坑：装不上、连不通、答非所问、莫名断掉。遇到问题时来这里对照排查，也适合在入坑前通读一遍预防。

这本附录是一本「急救手册」：按症状分类，对照排查。

症状一：模型不回话 / 报连接错误

十有八九是模型接入的问题，按顺序查：

1. Key 对不对：复制时是否带了多余空格？是否过期或被删除？
2. Base URL 对不对：地址要和服务商文档一字不差（注意有没有 /v1 这类后缀）。
3. 账户还有没有额度：到控制台看余额或用量，欠费是最常见的「静默断供」。
4. 网络通不通：部分服务商需要代理才能访问；如果你开着代理，试试「开着连一次、关着连一次」，定位问题在哪边。

症状二：答非所问 / 越聊越笨

先别怪模型，多数是「喂料」出了问题：

1. 上下文太满了：一个会话塞了太多任务，早期的重要信息可能已被挤出窗口。新开一个会话，重新简洁交代，常常立竿见影。
2. 需求太模糊：「帮我搞一下这个文件」不如「把这个 CSV 的电话列格式统一成 11 位数字」。回到 4.1 节的提问三技巧。
3. 它没读到关键文件：明确让它先读哪个文件再干活，别指望它在文件夹里自己「悟」。

症状三：执行到一半停了 / 反复失败

1. 看它的现场汇报：它失败时通常会说明卡在哪一步，先读原因再决定怎么办，别盲目重试。
2. 命令执行失败：常见于系统差异（比如命令在 Windows 上语法不同）。直接说「这个命令在我的系统上失败了，报错如下：……」，把报错原文给它。
3. 任务确实太大：让它「把任务拆成几步，先做第一步」。大任务切小，是万能解法。

症状四：文件好像被改坏了

预防大于抢救，三道保险按顺序上：

1. 事前：批量操作前确认它会先出方案（5.2 节）；重要目录让它在副本上先试。
2. 事中：逐条审批权限弹窗，看不懂的操作先问「这一步会做什么」。
3. 事后：真出问题了，第一时间停止操作让它汇报「刚才改了哪些文件、怎么改的」，然后从备份恢复。所以——现在就去给你的重要文件夹做一次备份，别等。

症状五：MCP 工具 / 技能装了没反应

1. 配置保存后重启会话了吗？工具列表在会话启动时加载。
2. 在工具列表里能看到它吗？看不到是配置问题，看得到是调用问题——直接说「列出你当前可用的工具」验证。
3. 检查描述写没写清楚（技能的 description 决定它会不会被想起，见 3.5 节）。

一条万能心法

所有排错的底层逻辑就一句：把 Agent 当成一个能力很强、但需要清晰沟通的新同事——它出错时，你给它现场信息（报错原文、页面截图、复述确认），它给你解决方案。甩锅和干等都解决不了问题，沟通可以。