用 OpenClaw 的朋友几乎都遇到过这样的时刻：Agent 昨天还好好的，今天突然不干活了——不回消息、报错、或者答非所问。第一反应是重装，重装完问题还在，只好上网搜，搜半天也没个准话。其实九成问题都能从日志里找到答案，只是很多人不知道日志在哪看、该看什么。
这篇把 OpenClaw 排错讲透：先教你怎么看日志、开 debug，再逐个拆解最常见的五类报错（密钥认证失败、工具调用异常、上下文溢出、技能加载失败、模型限流超时）的定位方法和修复方案，最后给一整套排查流程。照着走，Agent 出问题不用再靠猜。
第一步：日志在哪看，先搞清楚三层
OpenClaw 出问题时，信息分三层，从粗到细：
CLI 终端输出。启动 OpenClaw 的终端里会实时打印运行日志，启动报错、配置错误一般在这里一眼可见。终端里出现了红字、ERROR、Traceback，先从这层开始。
日志文件。OpenClaw 会把运行日志写进本地日志目录，按时间滚动。配置文件里能指定日志级别和路径，生产环境建议开到 info 以上，方便事后回溯。
会话记录。OpenClaw 保存了每次会话的完整历史——用户说了什么、模型回了什么、调用了哪些工具、结果如何。很多「答非所问」的怪问题，回看会话就能发现是上一步的工具结果喂错了。回放对照 的思路在这里同样适用：把出问题的会话完整回放一遍，往往比盯着报错猜更有效。
第二步：开 debug，让日志多说几句
默认日志级别下信息有限，排错前先把日志级别调到 debug/verbose：这样 OpenClaw 会打印每次 API 请求的完整参数、每个工具调用的输入输出、模型返回的原始内容。
开了 debug 你就能看到：模型到底收到了什么、工具返回了什么、哪一步开始跑偏。这一步能过滤掉 70% 的「玄学问题」——多数所谓「Agent 疯了」，其实是某个环节的数据喂错了。
常见报错一：密钥认证失败（401 / Invalid API key）
表现：Agent 一调用模型就报认证错误，或者某天突然开始报。原因基本是三类：密钥填错或复制多了空格、密钥过期或被吊销、密钥配置的位置不对（写在配置里但没被读到）。
排查顺序：先在终端确认密钥能被正确读取（避免把密钥直接打印出来，Agent 密钥边界 提醒过，密钥暴露是事故级别的问题）；再确认密钥本身有效（去模型厂商控制台看状态）；最后看是不是轮换过密钥没同步——权限管理 里讲的凭证轮换，换完旧密钥失效，配置没更新就会集体报错。换 DeepSeek、GPT、Claude 等不同厂商的密钥，注意各自的 接入格式差异。
常见报错二：工具调用失败（Tool call error / MCP error）
表现：Agent 说要调用某个工具，然后卡住、报错，或者「假装调用了」但结果明显不对。原因集中在：MCP 服务没启动或连不上、工具参数格式错误、工具返回的数据结构 Agent 解析不了。
排查顺序：先确认 MCP 服务本身活着（单独启动看报错）；再开 debug 看 Agent 实际传的参数和工具实际返回的内容；最后确认工具协议版本和配置对不对。OpenClaw 怎么接 MCP 工具 里有完整的配置和调试方法，工具调用失败排查 则是通用排查清单——报错、重试、降级、转人工，四个层级走一遍。
常见报错三：上下文溢出 / 越聊越傻
表现：Agent 聊到后面开始忘事、答非所问、重复提问，或者直接报上下文超长错误。原因是会话越长，上下文窗口越满，旧信息被冲掉或模型注意力被稀释——上下文管理 说的「窗口不是越大越好，关键是往里面放什么」就是这个道理。
解法：长任务拆短（一次别塞太多内容）；关键信息放结构化记忆里，别全堆在对话里（记忆设计 的思路）；定期清理或归档旧会话，给新会话腾空间。
常见报错四：技能 / 插件加载失败
表现：明明装了技能，Agent 却「不会用」；或者启动时技能加载报错。原因集中在：SKILL.md 格式问题、技能目录结构不对、依赖缺失、技能之间命名冲突。
排查顺序：看启动日志里技能的加载状态；检查 SKILL.md 的 frontmatter 和目录结构是否符合规范——OpenClaw 自定义技能开发 里有标准结构可以对照；确认技能依赖的脚本、命令在当前环境里可用（比如技能要调用某个 CLI，但这个 CLI 没装）。
常见报错五：模型限流 / 超时（429 / timeout）
表现：Agent 频繁报限流、请求超时、重试后仍然失败。原因：单模型并发打满、上下文太长导致单次请求超时、账户余额不足被停。
解法：降低并发、加退避重试；给 Agent 换个 更合适的模型（小任务用小模型，便宜还快）；检查账户余额。这类报错一般是临时的，做好重试策略就能扛过去。
一整套排查流程：复现 → 定位 → 修复 → 验证
遇到搞不定的问题，别东一榔头西一棒子，按四步走：
复现。同一个指令再触发一次，确认是不是稳定复现——偶发问题多半是外部依赖（网络、服务波动），稳定复现才是配置或代码问题。
定位。看 debug 日志，找到第一次出现异常的位置：是模型请求阶段、工具调用阶段、还是结果处理阶段。把问题范围从「整个 Agent」缩小到「某一个环节」。
修复。针对定位到的环节改配置、改提示词、改技能。一次只改一个变量，别同时动三处——改完不知道是哪处起效，等于没排错。
验证。修复后用回放对照跑一遍历史会话，确认问题真的解决、且没有引入新问题。模型或版本升级后更要跑回归——OpenClaw 模型版本管理 讲的回放验证，是防止「修好 A 弄坏 B」的标准做法。
排错习惯，比排错技巧更重要
最后说几个好习惯：日志级别别常年开 error，日常 info、出问题再临时开 debug，省资源也少噪音；改动配置前先备份——OpenClaw 数据备份与迁移 的备份流程要养成习惯；把常见报错和对应解法记下来，团队里共享一份排错手册，下次五分钟解决。
适合：正在用 OpenClaw 跑自动化任务、被报错困扰的个人和团队；想建立 Agent 运维规范的技术负责人。这套方法不挑版本，日志、debug、回放三个武器用好，OpenClaw 的绝大多数问题都能自己解决。
总结
OpenClaw 排错就五步：知道日志在哪看、开 debug 让信息变多、按类型定位常见报错（密钥、工具、上下文、技能、限流）、四步流程走一遍（复现→定位→修复→验证）、养成备份和记录的好习惯。九成问题在日志里就有答案，别一上来就重装——重装解决的是配置损坏，解决不了配置错误。把排错流程跑顺，OpenClaw 才能真正成为「可靠的下属」，而不是「薛定谔的 Agent」。
