工具调用失败的关键在于快速定位“没发出去”“发错了”或“没回好”，需从参数合规性、工具可用性、上下文权限链路、结构化调试输出四环节切入排查。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
工具调用失败不是 Muse 智能体独有的问题，而是智能体运行时与外部服务对接过程中的典型断点。关键不在重试次数，而在快速定位是“没发出去”“发错了”还是“没回好”。下面从四个最常出问题的环节切入，给出可立即验证的调试路径。
检查参数是否合规
图像生成、文件操作、API 请求等工具对输入参数极其敏感。常见陷阱包括：
- 必填字段缺失（如 width/height 未传，或传了字符串 "1024" 而非数字 1024）
- 值超出白名单（例如只支持 [720, 960, 1024, 1280]，却传了 800）
- 文本描述含非法字符（如控制符、未转义的双引号、超长 prompt 触发截断）
- 图片链接返回 404 或跨域拒绝，本地文件路径未加 file:// 前缀（尤其在桌面版中）
确认工具本身可用
Muse 不会自动绕过不可用的工具——它依赖你配置的工具状态是否健康：
- 执行 mise doctor（若使用 mise 管理工具链），查看工具安装状态、权限、shims 是否生效
- 手动调用该工具的原始命令（如 curl -X POST … 或 python gen_image.py --width 1024），验证能否独立运行
- 检查日志中是否有 “tool timeout”、“HTTP 503”、“rate limit exceeded” 等明确错误码
- 注意：Muse Spark 1.3 默认限制每个工具单次会话最多调用一次，重复调用会静默跳过
验证上下文与权限链路
尤其是 Muse for Mac 或私有化部署场景，工具失败往往卡在系统层：
- macOS 上检查是否已授权 Muse 访问“文件和文件夹”“完全磁盘访问”（系统设置 → 隐私与安全性）
- Linux 下确认 pygatt/hcitool 等底层工具是否获得 cap_net_raw 权限（sudo setcap 'cap_net_raw+eip' $(which hcitool)）
- 本地运行时若调用 Python 工具，确保其依赖（如 pylsl、opencv）版本与 Muse 兼容（例如 pylsl==1.10.5 对应 Linux LSL 流创建）
- 检查工具配置中是否误启用了沙箱模式，导致无法访问网络或本地路径
启用结构化调试输出
别只看最终报错，要让 Muse 把中间决策暴露出来：
- 启动时加 --verbose 或设置环境变量 MUSE_LOG_LEVEL=debug
- 观察日志中是否出现 “planning step: call_tool image_gen with {…}” —— 若没这句，说明任务规划阶段就跳过了该工具
- 对比成功与失败请求的完整 payload（可在日志或 network tab 中捕获），逐字段比对差异
- 对关键工具封装一层 wrapper 脚本，在入口处 echo 参数、记录时间戳、捕获 exit code，不依赖 Muse 日志兜底
