OpenClaw Agent 排障清单：会话、子代理、权限与网络问题怎么查

即使是最先进的代理也会遇到麻烦。无论是连接问题还是权限错误，了解如何排查故障对于维护健康的 OpenClaw 环境至关重要。

1. 检查日志

任何调查的第一步都是检查日志。OpenClaw 提供了查看最近活动的命令：

openclaw logs --tail 100

寻找 ERROR 或 WARN 消息。常见的罪魁祸首包括：

• API 速率限制：检查您的提供商仪表板。
• 网络超时：验证您的 Gateway 连接。

2. 常见错误与修复

"web_search needs a Brave Search API key"

如果您的代理无法搜索网络，请确保已配置您的 API 密钥：

openclaw configure --section web
# 输入您的 Brave Search API 密钥

或验证环境变量 BRAVE_API_KEY 是否已在 .env 文件中设置。

exec 上的 "Permission denied"

默认情况下，OpenClaw 以受限权限运行命令。要在 exec 中运行特权命令，请在 openclaw.toml 中调整 security.exec 策略，或者在命令前使用 sudo（如果已授权）。

注意：授予提升的权限时务必小心。

子代理故障

如果子代理没有响应：

1. 检查主代理的会话状态：openclaw session status。
2. 确保子代理进程没有过早终止。
3. 查看代理间通信日志。

3. 高级诊断

监控资源使用情况

代理在长会话期间可能会消耗大量内存。使用 top 或 htop 监控 openclaw-agent 进程。

网络调试

如果代理无法连接到外部服务：

• 验证 DNS 设置。
• 检查防火墙规则是否阻止了 80/443 端口的传出流量。
• 使用 curl -I https://api.openclaw.ai 测试连接性。

谁应该先看这份排障清单

如果你属于下面这些情况，这一页更适合作为入口：

• agent 之前还能工作，但在配置、模型或 gateway 变更后开始报错
• subagent 卡住、提前退出，或者一直不给可用结果
• exec、web、browser 等工具失败了，但你还不确定是权限、凭证还是网络问题
• 你需要判断当前应该先重启、先改配置，还是先验证上游 provider

如果问题很明确就是首次在 Mac 上安装失败，那么完整安装指南或 quick install 指南通常比通用排障清单更适合先看。

如果你是从 /zh 首页或搜索直接点进来的，最省时间的走法通常是先判断自己属于哪一类：首次安装或环境刚搭好但不稳定，先看 OpenClaw 完整安装指南；CLI 在 hooks 后明显卡顿，先去 CLI 回归页；Codex OAuth 登录成功但 provider 还是不对，先去 Codex OAuth 排障页。这样能少走很多‘先怀疑全部，再逐个排除’的弯路。

搜索访客的 90 秒入口分流

如果你只想快速找到下一步，可以先按症状选入口：

• 命令行慢或卡住：先查 CLI 回归页，不要一上来改 agent 配置。
• 工具调用失败：先确认是 exec、browser、web 还是外部 API，再看权限和凭证。
• 子代理没有结果：先看父会话是否还活着，再查子 run 是否退出或卡审批。
• 安装后第一次任务失败：先回安装验收，不要直接进入 provider 深水区。

这层分流的目标，是把“OpenClaw 不工作”拆成能继续行动的四个入口。

常见排障判断问题

什么时候应该先回到迁移页，而不是继续把问题都算到 agent 故障

如果你这次出问题的起点，其实是刚把 Moltbot / Clawdbot 环境切到 OpenClaw，例如 remote、镜像名、CLI 包名、配置目录刚改完，那就要先回到 1 分钟迁移指南 做一次迁移层核对。很多看起来像 agent 异常的问题，实际是旧仓库 URL、旧镜像 tag、旧命令或旧配置路径没有切干净，而不是 agent 本身坏了。

什么时候应该先重启，什么时候应该先看日志

只有在你已经确认之前状态健康，而且这次故障像短暂抖动时，才适合先重启。如果同样症状重复出现，就应该先查日志再动配置，因为一味重启会掩盖真实原因，到底是 rate limit、审批策略还是连通性断掉。

什么时候真实问题在 provider 或网络，而不在本地 agent

如果 session 能正常启动，但卡在模型调用；或者 web 与外部 API 工具一起失败，就应优先怀疑上游 API 健康、DNS、防火墙或 provider 限流，而不是先改本地 agent 逻辑。多个工具同时在出站层失灵时，本地 prompt 调整通常解决不了问题。

如果你的现象更像这两类高频故障，下一跳先看哪里

如果你已经知道自己不是通用 agent 故障，而是更接近某一类高频症状，建议直接分流到更具体的页面：

• CLI 在 hooks 后卡 20 到 40 秒，但 Gateway health 还正常：先看 OpenClaw CLI 在 v4.5+ 后可能卡 20 到 40 秒：为什么 Gateway 明明健康，命令行却像死了一样，优先区分是 CLI / RPC 链路回归，还是整机、网络或 gateway 真的变慢。
• Codex OAuth 看起来登录成功，但运行时还是回退默认配置或报 No API key found：先看 OpenClaw 的 Codex OAuth 可能看起来已就绪，实际却永远不走 Codex，优先确认是不是 per-agent auth order 没落盘，或 provider 路由状态没补齐。

这样做的价值是，把“通用排障入口”和“高意图具体故障页”接起来，减少用户在首页、总表页和具体 bug 页之间来回跳但没有明确下一步的流失。

如果你已经落到总表页，下一步最该补哪种判断

总表页最怕的问题，不是信息太少，而是用户知道自己‘有问题’，却还是不知道下一步该点哪篇。

所以如果你已经走到这页，最值得先补的一层判断通常是：

• CLI 在 hooks 后明显卡顿，但 Gateway health 还快：直接转去 CLI 回归卡顿排障页；
• Codex OAuth 看起来成功，但实际请求仍落错 provider 或顺序不生效：直接转去 Codex OAuth 排障页；
• 刚从 Moltbot / Clawdbot 迁过来，怀疑是旧命令、旧路径、旧 remote 没切干净：先回 1 分钟迁移指南。

这层分流越明确，越容易把总表页流量继续送到更高意图的具体问题页。

升级给下一位值班同事前，先补 4 个证据

如果这份总表已经帮你缩小了方向，但问题还没有彻底解决，不要只把一句“还是不行”交给下一位同事。先补齐四类证据：

1. 当前卡在哪一层：安装、gateway、消息入口、工具调用、模型/provider，至少标出一个最可疑层。
2. 最后一次可复现命令或用户输入：保留原始命令、会话输入或最小触发步骤。
3. 一段真实日志：不要只贴截图，保留错误前后 20-50 行，方便继续 grep 和比对。
4. 已经排除过什么：写清楚哪些重启、换模型、换入口或权限检查已经做过，避免下一轮重复消耗。

这能把“泛排障入口”变成真正可交接的事故处理入口，也能减少搜索用户在多个问题页之间来回跳。

从总表分流到具体故障页前，先做哪一步

这篇总表适合快速缩小范围，但不要把所有问题都停在总表里。为了让搜索访客更快进入能解决问题的页面，先用下面三步分流：

1. 先确认症状层级：是 agent 没启动、渠道没初始化、工具调用失败，还是某个 provider / runtime 被错误选择。
2. 再确认是否已有专门故障页：如果错误信息已经指向 Codex OAuth、custom provider key、session reset、Feishu schema、Telegram 初始化这类具体问题，优先跳到对应故障页。
3. 最后再回到总表补全证据：只有当症状跨多个层级、或者无法确定入口时，才在总表里继续补日志、配置差异和复现步骤。

最实用的判断是：如果用户能说出明确报错或明确渠道，就去具体故障页；如果只能说“agent 不工作”，才留在这篇总表继续排查。

从 setup 页面进来时，先确认是不是安装后验证问题

最新流量里，setup 与这篇排障总表会同时出现，说明一部分读者不是在查单个 bug，而是在安装后想确认“现在能不能真正用了”。这类读者不要一上来就改 agent 配置，先按下面顺序走：

1. 先做最小可用性验证：确认 CLI 能启动、Gateway 能返回健康状态、默认模型能完成一次短回复。
2. 再判断失败发生在哪一步：如果 setup 页的命令还没跑通，优先回安装页；如果安装成功但首次任务失败，再进入这篇总表。
3. 最后补具体故障页：只有当失败信息已经指向某个 provider、渠道、schema 或 session 问题时，才跳到对应 bug 页。

这能把“刚装好但不确定是否可用”的访客，和“已经在线上任务里遇到明确故障”的访客分开，避免把 setup 流量直接丢进过宽的排障清单。

5 分钟内先决定：停在总表，还是跳到具体故障页

如果你是从 /zh、setup 或搜索结果进来，先不要把所有检查项从头跑一遍。用 5 分钟做一次入口判断：

1. 有明确报错文本：直接搜本页和 news 目录里的专门故障页，例如 No API key、/reset、Telegram initialize、schema。
2. 有明确渠道：先按渠道分流，Feishu、Telegram、Discord、Kimi、ACP 的日志边界通常不同。
3. 只有“agent 不工作”这种模糊描述：留在本总表，先确定失败层级，再补最小复现。
4. 刚安装或刚迁移：先回安装或迁移页，确认旧命令、旧路径、旧 remote 和旧 provider 名没有残留。

这一步的目标不是多读一篇文章，而是让高意图流量尽快进入能解决问题的页面：能说出错误和渠道，就去专门页；说不出，才继续用总表缩小范围。

把总表流量变成下一步可衡量动作

当 GA4 把读者送到这份总排障页时，不要让他只停留在泛泛检查。先把访问转成三类可衡量动作之一：

1. 事故交接：如果读者已经有失败命令，先记录命令、channel、model/provider 和第一条错误日志，再跳到具体 bug 页。
2. 安装验收：如果读者是从 /setup 过来的，先确认第一个 agent 任务、浏览器动作、channel 投递是否都至少跑通过一次。没有通过，就回安装验收，不要直接深挖模型配置。
3. 版本回归判断：如果问题出现在升级之后，先把现象和发布说明、CLI 性能回归路径对齐，再决定是否改 provider、model 或 hook 设置。

这样总表页就不只是“排障清单”，而是高意图流量的分流 hub：每次访问都应该进入收集证据、验证安装或跳转到具体事故页其中之一。

交接前先做这张四层证据表

如果你是从搜索进来的值班者，最容易浪费时间的地方是直接重启 agent，却没有留下证据。建议先把问题填进这张四层表：

层级	先记录什么	什么时候升级
运行时	当前 agent、model、provider、最近一次配置变更	同一任务换模型后仍失败
工具	失败 tool 名称、输入摘要、错误时间戳	多个工具同类权限失败
渠道	Discord/Telegram/Feishu/CLI 哪条链路坏	同一 agent 在多个渠道都异常
权限	token、OAuth、文件路径、外部 API 写入范围	只读成功但写入失败

这张表能把“agent 不工作”拆成可交接的排障线索，也能帮助读者更快决定该去 CLI 回归页、Skills 决策页，还是继续留在 Agents 总表。

什么时候停止自查，升级给维护者？

总排障页的价值不是让你无限自查。出现下面任一条件，就应该把证据打包给维护者或内部平台负责人：

1. 跨渠道复现：同一个 agent 在 CLI、Feishu、Discord 或浏览器入口里都失败。
2. 跨模型复现：换 provider / model 后仍然卡在同一层，不再像单一模型问题。
3. 只读成功、写入失败：说明权限、token、路径或外部 API 写入边界可能有问题。
4. 升级后才出现：最近一次版本、gateway、plugin 或 auth 配置变更能和故障时间对上。
5. 已经影响交付：自动化任务、客户交付或生产值班被阻断，不适合继续个人试错。

升级时直接附上四层证据表、最后一次可复现输入和已经排除过的动作。这样维护者拿到的不是一句“agent 不工作”，而是可以继续定位的事故包。

把模糊的 agent 故障导到具体事故页

这篇总表应该作为分流 hub，而不是最终终点。前 5 分钟完成初筛后，把读者导到最具体的事故类型，让下一次点击直接匹配他手里的故障。

1. session 或历史看起来为空：先去 ACP transcript / sessions_history 文章，不要急着换模型。
2. 聊天面板出现巨大警告三角：先去 main-session warning-triangle 恢复指南，不要直接清空全部 session storage。
3. 可复用自动化调用超时：先去 sessions_send timeout 恢复指南，对比旧 session 和新 session 的行为。
4. provider 返回空 assistant message：先走 Vertex Gemini 空回复排障路径，并保留 raw provider response 字段。

这样能把“OpenClaw agent 不工作”的宽泛流量切成更清晰的排障意图。读者要么拿到更窄的恢复路径，要么带回一份更适合维护者继续定位的证据包。

相关阅读

• OpenClaw 完整安装指南
• OpenClaw Mac 快速安装指南
• 安装后怎么确认 OpenClaw 已经真的可用
• 安全与成本

需要更多帮助？

加入我们的 Discord 社区或查阅 官方文档 获取更详细的指南。

编程愉快！