OpenClaw工具调用失败主因是模型未识别调用指令、不支持原生工具调用或JSON Schema格式错误；需强制tool_choice="required"、选用support_tool_calling模型，并严格校验tools字段小写命名、基础schema及工具返回字典。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw工具调用失败时，常表现为模型返回空响应、报错“Invalid tool call format”、工具函数未触发或执行后无结果，这类问题多由配置格式、模型能力或参数约束不匹配导致。
确认工具调用是否被模型真正识别
第一步：在请求中显式添加 【tool_choice: "required"】 参数，强制模型必须调用工具。若仅靠 prompt 描述“请调用天气插件”，部分模型（如 DeepSeek Reasoner）会忽略或自由生成文本而非结构化调用。
第二步：检查模型是否支持原生工具调用。Gemma4、Qwen2.5VL 等轻量模型默认不支持 function calling；必须选用明确标注 support_tool_calling 的模型（如 ollama run llama3.2:latest + 工具扩展版）。
第三步：用 curl 发送最小可复现请求，绕过 OpenClaw CLI 层，直连 Ollama API 验证：
curl -X POST http://localhost:11434/api/chat -H "Content-Type: application/json" -d '{"model":"your-model","messages":[{"role":"user","content":"查上海天气"}],"tools":[{"type":"function","function":{"name":"get_weather","description":"获取城市天气","parameters":{"type":"object","properties":{"city":{"type":"string"}}}}}]}'
检查工具定义 JSON 格式合规性
方法一：字段名必须全小写且严格匹配 OpenClaw 解析器要求。常见错误是把 "parameters" 写成 "Parameters" 或 "params"，会导致解析中断并静默跳过工具注册。
方法二：嵌套 schema 中禁止使用 $ref 或复杂联合类型（如 {"type": ["string", "null"]}）。OpenClaw 仅支持基础 JSON Schema v7 子集，遇到 anyOf、oneOf 会直接报 invalid tool schema 错误。
方法三：用 openclaw tools validate 命令校验本地工具文件。该命令会输出具体哪一行、哪个 key 不合法，比手动肉眼排查快得多。
定位工具执行阶段失败原因
① 打开调试日志：启动网关时加 --verbose 参数，或设置环境变量 OPENCLAW_LOG_LEVEL=debug，观察日志中是否出现 executing tool: get_weather 字样。没有该日志说明调用未进入执行环节，问题出在模型输出解析层。
② 检查工具函数返回值是否为标准 JSON 对象。若 Python 工具函数返回的是 print("done") 或 None，OpenClaw 会认为执行失败并回退为普通回复。必须显式 return 字典，例如：return {"temperature": 32, "condition": "sunny"}。
③ 验证工具路径权限。Linux/macOS 下，若工具脚本位于 ~/scripts/weather.py 但未赋予可执行权限（chmod +x），OpenClaw 尝试 spawn 进程时会抛出 【EPERM 权限拒绝】，日志仅显示 “failed to launch tool process”。
