OpenClaw调用工具失败时，需依次检查插件文件名与ID规范、技能路径挂载与权限、执行环境依赖缺失，并重启网关生效；文件名必须为openclaw.plugin.json，ID须为纯ASCII字符串，路径须严格匹配~/openclaw-data/skills//，依赖须逐个验证安装，最后执行openclaw gateway restart。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw调用工具失败时，命令无响应、返回空结果或报错“Skill not found”“Execution timeout”，说明技能注册路径异常、配置不匹配或执行上下文缺失，必须逐层验证才能恢复功能。
检查插件文件名与注册规范
OpenClaw严格依据固定命名规则加载插件，文件名或ID不合规会导致技能被完全忽略，调用静默失败，没有任何错误提示。
第一步：进入插件所在目录，运行ls -la，确认存在且仅存在一个名为【openclaw.plugin.json】的配置文件——不能是clawdbot.plugin.json、plugin.json或带大小写混写的变体。
第二步：用cat openclaw.plugin.json查看内容，检查"id"字段值是否为纯ASCII字符串，不含空格、中文、emoji或特殊符号（如web_search_v2合法，网页搜索或search@v2非法）。
第三步：执行openclaw skills list，观察输出中是否包含你刚检查的id。若未出现，说明注册根本未生效，必须修正前两步再重试。
验证技能路径挂载与权限设置
OpenClaw默认只扫描~/openclaw-data/skills/下的子目录，路径错一位、权限缺读取、Docker没挂载，都会让技能“存在却不可见”。
方法一（本地部署）：确认插件完整路径为~/openclaw-data/skills/<skill-id>/</skill-id>，其中<skill-id></skill-id>必须与openclaw.plugin.json中"id"字段【完全一致、大小写敏感】。
方法二（Docker部署）：检查启动命令是否包含显式挂载参数，例如-v $(pwd)/openclaw-data/skills:/root/openclaw-data/skills；若漏掉/root/前缀，容器内路径将失效。
OpenClaw 基础设施心跳监控与自动恢复：部署/卸载心跳守护进程，配置主机监控（Gateway、磁盘、内存、CPU、进程），设置飞书告警，自动重启故障Gateway。适用关键词：心跳监控、heartbeat daemon、服务器告警、自动重启、健康检查、auto recovery。
方法三（权限修复）：运行chmod -R u+rx ~/openclaw-data/skills/，确保当前用户对整个目录有读和执行权限——缺少x权限会导致子目录无法进入，插件加载中断且无报错。
排查执行环境依赖缺失
部分Skills在运行时需调用外部命令（如curl、jq）或Python模块（如requests），依赖未就绪会直接导致子进程崩溃，日志里只显示“exit code 1”。
打开openclaw.plugin.json，查找"requires"字段。若存在，例如"requires": ["curl", "jq"]，则需在系统中逐个验证：which curl && which jq；任一缺失，立即安装（Ubuntu执行sudo apt-get install curl jq）。
若"requires"中列出Python包（如"requires": ["python3-pip", "beautifulsoup4"]），先运行python3 -m pip list | grep beautifulsoup4，未找到则执行python3 -m pip install beautifulsoup4。
注意：不要跳过which或pip list验证，直接重装可能掩盖真实缺失项。
重启网关使变更生效
所有路径、权限、依赖修改完成后，必须重启网关服务，否则新配置不会加载。
执行openclaw gateway restart，等待终端输出Runtime: running后再测试工具调用。
如果使用Docker，需额外执行docker restart <container-name></container-name>，仅openclaw gateway restart对容器内服务无效。
