工具失败时，很多人第一反应会去怀疑模型，其实这往往不是根因。对 OpenClaw 来说，工具执行是单独的一层，它会受到审批、权限、宿主机环境、节点能力和外部依赖的共同影响。所以真正有效的排查方式，是先确认“这件事允不允许做”，再确认“允许之后，执行环境有没有准备好”。
先分清两类失败
工具失败大致可以分成两类：
第一类：被拦住
例如：
- 审批没通过
- 当前策略不允许执行
- 沙箱边界挡住了
第二类：允许执行，但执行不了
例如：
- 依赖缺失
- 工具路径不存在
- 节点没连接
- 宿主机根本没有这个能力
这两类问题的排查方向完全不同，所以一定要先分清。
常见根因
最常见的几类原因包括：
- 审批没通过
- 权限边界不允许
- 节点没准备好
- 外部依赖没装
- 工具路径或命令范围不正确
- 当前任务被路由到了不具备该能力的执行主机
为什么这一层最容易被忽视
因为用户通常只能看到“最后失败了”，但看不到中间具体停在：
- 审批层
- 权限层
- 执行层
这就很容易把所有问题都误判成“模型不行”或“Gateway 坏了”。
先按报错现象来分类
这几个现象特别有代表性：
- 明确提示需要批准：优先看审批
- 明确提示权限不足：优先看允许列表和沙箱
- 命令找不到或文件不存在：优先看执行环境
- 某节点工具一直不可用：优先看节点连接和能力暴露
只要先按现象归类，很多工具问题其实不复杂。
推荐排查顺序
我建议先按下面顺序判断：
- 这件事当前策略允不允许做
- 如果需要审批，审批是否已完成
- 即使允许执行，当前主机是否真的具备该能力
- 工具依赖和路径是否存在
- 当前任务有没有被路由到正确的节点或主机
这样能最快把“被安全层拦住”和“环境没准备好”区分开。
三个典型场景
场景一：网页相关动作失败
先不要立刻怀疑浏览器坏了，先看：
- 当前任务是不是其实只该用
Web - Browser 能力是否真的开启
- 执行主机是否提供浏览器代理
很多所谓“浏览器失败”，本质上是任务选错层或者执行主机没暴露对应能力。
场景二：命令执行失败
优先确认：
- 审批是否通过
- 命令是否在允许范围
- 当前主机是否真有这个命令
- 目标目录是否可访问
如果这几项里任何一项不满足，问题都不在模型层。
场景三：文件修改失败
优先确认：
- 当前工作区是否允许写入
- 路径是否存在
- 沙箱是否限制了目标目录
- 当前任务是否在正确主机上执行
如果是节点相关问题
先确认：
- 节点是否已连接
- 节点是否暴露了你要用的能力
- 当前任务是否真的路由到了那个节点
很多节点型问题，本质上不是工具坏了，而是工具并不在当前执行主机上。
如果是本地工具问题
优先确认：
- 路径是否存在
- 命令是否在允许范围内
- 当前宿主机是否真的装了相关依赖
例如你让 OpenClaw 调一个本地二进制，但当前主机根本没装这个二进制，那就不是提示词问题，而是环境问题。
一个很重要的判断
工具失败不等于系统坏。很多时候它恰恰说明：
- 审批系统在正常工作
- 权限边界在正常工作
- OpenClaw 已经把任务推进到了真实执行层
从排障角度看，这其实是好事，因为它说明模型和任务分解大概率已经走到了后面几层。
工具排障的关键是先问一句：这是没被允许，还是被允许了但执行不了。只要先把这两个层次分开，再去看节点、依赖、路径和环境，定位速度会快很多。