最近在使用 OpenClaw 跑 Agent 时，偶尔会遇到一条很笼统的报错：

Agent couldn't generate a response

字面意思是“Agent 无法生成响应”，但它通常不是某一个固定问题，而是 OpenClaw 在调用模型、接收结果或解析输出时失败后的统一提示。换句话说，这条报错只是表象，真正原因还得从 API、上下文、网关和日志里找。

错误现象

常见表现包括：消息发送后长时间没有结果，最后弹出错误；同一个问题反复重试偶尔又能成功；新会话正常、旧会话报错；主模型不可用，但切换其他模型后恢复；或者所有模型同时无法响应。

如果只是偶发一次，大概率是网络抖动或上游 API 超时。如果持续出现，就不能只点重试了，需要按顺序排查。

可能原因

1. API 超时或触发限流。 模型服务响应太慢，超过 OpenClaw 或网关设置的超时时间，就会中断请求。短时间发送太多消息，还可能触发 429 限流。

2. 上下文过长。 长时间在同一会话里聊天，会让历史消息、工具调用结果和系统提示不断累积。一旦超过模型的上下文窗口，请求可能直接失败，或者模型无法生成完整回答。

3. 输出格式解析失败。 某些 Agent 要求模型返回 JSON、工具调用参数或固定结构。如果模型多输出了一段解释、JSON 缺少引号，或者字段不符合 Schema，OpenClaw 就可能把它当成“没有生成有效响应”。

4. 网关连接问题。 自建 API 网关、反向代理或容器网络不稳定时，可能出现连接重置、DNS 解析失败、TLS 错误，以及 502、503、504 等状态码。

5. API Key 失效或额度用完。 Key 被撤销、填写错误、权限不足、账户欠费或余额耗尽，都可能导致调用失败。有些兼容接口不会展示清晰提示，最后只剩统一错误。

6. 模型暂时不可用。 模型名称写错、供应商下线模型、区域限制或上游服务故障，也会让 Agent 无法拿到回复。

解决方案：按顺序排查

第一步，先重试一次。 等十几秒后重新发送，避免连续快速点击。偶发超时和限流通常可以这样恢复。

第二步，新建会话。 如果新会话正常，基本可以判断是旧会话上下文过长或历史工具调用异常。重要内容可以先做摘要，再带到新会话里。

第三步，检查 API Key 和余额。 登录模型供应商后台，确认 Key 未过期、权限正确、账户有余额，同时检查 OpenClaw 中的接口地址和模型名称有没有多余空格或拼写错误。

第四步，查看日志。 重点搜索 401、403、429、502、503、504、timeout、context length 和 parse error。不同部署方式命令会有差异，例如：

docker logs --tail 200 openclaw
docker logs -f openclaw-gateway
journalctl -u openclaw-gateway -n 200 --no-pager

401/403 多半是认证问题，429 是限流或额度问题，5xx 通常指向网关或上游服务，parse error 则要检查模型输出格式。

第五步，切换备用模型。 临时换成另一个供应商或较稳定的模型测试。如果备用模型正常，说明 OpenClaw 主体大概率没坏，问题集中在原模型或对应接口。

第六步，重启网关。 当前面都无效时，再重启 OpenClaw 网关或相关容器，清理卡住的连接。不要一上来就重启，否则容易把关键日志一起丢掉。

docker restart openclaw-gateway
# 或
systemctl restart openclaw-gateway

预防建议

我自己的做法是至少配置一个备用模型，主模型连续失败时可以快速切换；长对话定期总结并开启新会话，避免上下文无限增长；给 API 余额、请求失败率和 429 状态设置监控提醒；网关尽量部署在网络稳定、访问模型接口延迟较低的环境中。

如果 Agent 强依赖 JSON 或工具调用，还应尽量使用结构化输出能力较好的模型，并在解析层加入容错和原始响应日志。超时时间可以适当调大，但不建议无限增加，否则请求卡住时只会等得更久。

总结

“Agent couldn’t generate a response”更像一个结果提示，而不是具体病因。排查时按“重试 → 新会话 → 查 Key 和额度 → 看日志 → 换备用模型 → 重启网关”的顺序走，通常很快就能定位。最关键的还是日志：界面只告诉我失败了，日志才会告诉我到底为什么失败。