导语：在企业 AI Agent 运维中，一个容易被忽视的误区是——模型能正常回复，就被当成“系统正常”。真正决定 Agent 能干多少活的，是它背后的工具：执行命令、读写文件、操作浏览器、调用插件与 MCP。工具一旦消失，Agent 看上去还在聊天，其实已经失去了大部分执行能力。

本文记录我们生产环境的一次真实故障：OpenClaw 由 v2026.9.5 升级到 v2026.9.6 后，Agent 的核心工具大量不可用。排查中还有一个有意思的两难——出问题的正好是 Agent 自己的工具，所以后段的部分检查只能直接在生产主机上通过 SSH 完成。

一、故障现象

升级后，Agent 可以正常对话，但 exec、read、write、browser、memory_*、sessions_* 等工具不可用；可用的工具面里只剩结构化工具检索相关的元工具和部分 MCP 工具。与此同时，Gateway、模型、消息通道与日志服务表面全部正常。

日志中出现三条关键提示：

• no write tool survived this agent's tool policy
• No callable tools remain after resolving explicit tool allowlist
• no registered tools matched

二、为什么这个问题不好判断

在 OpenClaw 中，一个工具从“存在”到“可用”，要依次穿过：

创建 → 策略过滤（Tool Policy / Model Policy）→ 授权（Invocation Policy / Session Authority）→ 挂载有效工具面 → 暴露（Structured Tool Search 或 Direct Tool Schema）。

任何一环出问题，对外表现都是同一句话——“工具搜不到”。所以，不能仅凭“exec 不在了”，就直接去改工具白名单。

三、排查过程

• 工具权限：生产配置为 tools.profile=full、tools.allow=[]。一度怀疑 [] 被解释成“拒绝全部”，但没有找到支持这一解释的直接证据，本次也未做受控的会话对比，故不把它当作根因。
• 模型与 Provider：此时模型对话本身正常，Provider 与接口层未见异常，问题不在模型可用性。
• 版本风险其实已被预判：本次升级的变更记录在升级前就把“Tool Search 默认开启”列为风险项，缓解办法正是按需显式设置 tools.toolSearch:false——这也为后面的定位提供了方向。
• 关键线索：日志中出现 tool-search: cataloged 32 tools behind compact prompt surface，即工具被编入检索目录，却没有进入可用工具面。问题由此收敛到“有效工具面 → 结构化工具检索 → 会话运行时”这条链路。

四、处理：只改一个变量

为不引入干扰，处理时严格控制为单变量：其他配置一律不动。

{ "tools": { "toolSearch": false } }

配置修改后，系统先检测到 tools.toolSearch 变化并做了一次热重载；随后我们又执行了一次完整重启，以确保工具面干净生效。

重启后 Gateway 正常监听服务端口、进入 ready，各消息通道正常——说明该配置本身不影响 Gateway 与消息通道的运行。由于出问题的正是 Agent 自身的工具，这两步都是在生产主机上通过 SSH 直接完成的。

五、验证：四项工具实际调用

修复后新建会话，分别对 exec、read、write、browser 做了实际调用验证，而不只是看工具名是否出现：

四项全部通过，工具调用能力恢复正常。

六、结论与边界

关闭结构化工具检索后，工具全面恢复，故障在生产上已经闭环。但本次并未做受控对比，因此只能说：问题与 v2026.9.6 的结构化工具检索路径相关，关闭该功能可以绕过并恢复；具体触发环节尚未定位到函数级缺陷，如需继续，可在实验环境中推进源码级根因分析。

七、当前策略与四条经验

生产环境保留 tools.toolSearch=false，没有做版本回滚、模型切换、批量修改 tools.allow、禁用插件或打补丁——业务已经恢复，没有明确收益就不应扩大变更范围。

1. 模型能聊天，不代表 Agent 正常。 Agent 的能力是「LLM + Tools」；工具全部不可用，等于失去了执行能力。

2. 插件已加载，不等于工具可用。 必须做真实的工具调用验证，而不是只看日志里的 loaded。

3. 工具搜不到，要向上游继续查。 构造、策略、授权、有效工具面、检索，任何一环都可能吞掉工具。

4. 升级前先把已知风险落到配置上。 本次升级记录早已列出 Tool Search 风险项，若升级前就显式设置，多半能省掉这次故障。

八、补充：Tool Search 的官方定位与后续安排

OpenClaw 官方把 Tool Search 定义为实验性功能，用于在工具数量较多时压缩 Tool Schema、降低上下文占用。官方也明确：tools.toolSearch 未配置时默认启用 Structured Tool Search（tools 模式）；设为 false 则恢复 Direct Tool Schema。

结合本次故障：

• 升级后出现了 exec、read、write、browser 等工具无法正常调用的情况。
• 在保持其他工具配置不变的前提下，仅设置 "tools.toolSearch": false 并重启 Gateway，新建会话四项工具实测全部恢复正常。
• 因此生产环境当前继续采用 Direct Tool Schema（toolSearch=false），以稳定性优先，Tool Search 暂不重新启用。
• 后续计划在测试环境评估 directory 等 Tool Search 模式，验证稳定性与 Token 优化效果之后，再决定是否进入生产。

官方文档：OpenClaw — Tool Search，https://docs.openclaw.ai/tools/tool-search

结语

随着企业逐步引入 AI Agent，“应用启动正常、接口返回正常”已经不足以判断系统是否健康。Agent 还需要关注一整套新的运行层：模型能力、Tool Calling、Tool Policy、Tool Authority、Tool Surface、插件注册与会话运行时。其中任意一环异常，都可能产生一种非常特殊的故障——

AI 看起来还在正常回答问题，但实际上已经失去了执行能力。

这类问题，正在成为 AI Agent 基础设施运维中一种新的故障类型。