OpenClaw 工作流里的“工具失败”，不能只记录成一个状态。超时、空结果、权限拒绝、参数错误、写入失败和外部限流，背后的处理方式完全不同。如果日志里都写失败，后续排查就只能靠猜。
工具失败分类可以接上 审计日志字段、运行看板字段、异常分级。日志负责还原事实，看板负责暴露趋势，异常分级负责决定谁来处理。
超时和空结果不是一回事
工具超时说明外部接口、网络或执行时间有问题；空结果则可能是查询条件不对、数据源没有记录，或者权限范围太窄。两者都可能让 Agent 无法完成任务，但修复方向完全不同。
超时可以考虑重试、降级或排查服务稳定性；空结果应该回到输入字段、检索条件和数据范围。不要用同一套重试策略处理所有失败。
权限拒绝要单独标记
权限拒绝不是普通技术错误。它可能说明 Agent 试图访问不该访问的系统，也可能说明当前用户没有完成这一步的授权。无论是哪种，都应该进入人工确认或权限复核。
这类失败要和 权限复核 连起来。记录当前用户、目标系统、动作类型和拒绝原因，后续才能判断是权限配置问题，还是流程边界本来就应该禁止。
写入失败要保留幂等信息
读失败和写失败的风险不同。写入失败最怕重复执行：第一次其实写入成功但返回失败，第二次重试又写了一遍，最终造成重复通知、重复工单或重复修改。
因此写入类工具要保留请求编号、目标对象、幂等键、返回状态和是否可重试。可以参考 失败重试与幂等设计，把可重试和不可重试分开。
外部限流要进入成本和容量复盘
外部限流不是偶发小问题。如果某个工作流经常触发限流，说明调用频率、批处理策略或任务排队方式需要调整。盲目重试只会放大成本，还可能让服务更不稳定。
这类问题适合放进 成本预算复盘 和运行看板。工具失败分类越细，月度复核时越容易找到真正的瓶颈。
总结
OpenClaw 工具失败分类的目标，是让每一次失败都有处理方向。超时、空结果、权限拒绝、参数错误、写入失败和外部限流分开记录，团队才能更快定位问题，也能避免错误重试带来新的风险。
