“Tool provider unavailable”或“MCP server connection failed”表明MCP服务未就绪或网关未正确加载：需先确认MCP Server进程存活（如ps aux | grep mcp）、再验证config/mcp.yaml配置合法且URL使用127.0.0.1而非localhost、最后检查MCP协议版本是否为2.2并确保/server/initialize接口支持该版本。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw调用MCP工具时提示“Tool provider unavailable”或“MCP server connection failed”，说明智能体已生成工具调用指令，但底层MCP服务未响应、未就绪或协议不通——这通常不是模型问题，而是服务链路断在了网关与MCP Server之间。
确认MCP Server是否真实运行
第一步必须验证MCP Server进程是否存活，而非仅看OpenClaw日志里有没有报错。很多用户误以为“OpenClaw启动成功”就等于MCP可用，其实两者完全独立。
在终端执行：ps aux | grep mcp 或 lsof -i :3001（默认MCP端口），若无任何输出，说明服务根本没起来。
若你使用的是mcporter启动的MCP Server，需明确进入其项目根目录再运行：npm start 或 python main.py，不能只在任意路径下敲mcporter命令——该命令本身不启动服务，只是配置生成器。
【关键前提】MCP Server必须先于OpenClaw网关启动，且保持后台常驻。一旦OpenClaw发起首次调用时Server未就绪，后续即使Server启动，OpenClaw也不会自动重连，必须重启网关。
检查OpenClaw网关是否识别到MCP Provider
运行命令：openclaw gateway status --verbose，观察输出中mcp_providers字段是否列出你的MCP服务名（如dida365、notion-mcp）。
若为空或显示0 providers loaded，说明网关根本没加载MCP配置。此时要检查：~/.openclaw/config/mcp.yaml是否存在且语法合法——YAML缩进错误、冒号后漏空格、引号不闭合，都会导致整个文件被跳过解析。
打开该文件，确认包含类似结构：
providers: - id: "dida365" name: "滴答清单" url: "http://127.0.0.1:3001" capabilities: ["task", "calendar"]
注意：url值必须是HTTP协议，不能写成localhost——Mac或Docker环境下localhost会解析失败，必须用127.0.0.1；端口必须与MCP Server实际监听端口一致。
验证MCP Server端点可被网关直连
不要依赖浏览器访问来判断连通性。OpenClaw网关是命令行进程，它走的是系统级网络栈，可能受代理、防火墙、容器网络隔离影响。
在终端执行：curl -v http://127.0.0.1:3001/health（多数MCP Server提供该健康检查接口）。如果返回HTTP/1.1 200 OK和JSON响应，说明网络层通畅；若卡住、超时或返回Connection refused，问题出在Server未监听、端口错配或被防火墙拦截。
若你在Docker中运行OpenClaw，而MCP Server在宿主机，127.0.0.1对容器而言指向容器内部，必须改用宿主机真实IP（如192.168.1.100）或Docker特殊DNS名host.docker.internal。
Windows用户注意：netsh interface portproxy转发规则若存在，可能劫持本地端口，导致curl能通但OpenClaw不通——此时直接停用端口代理：netsh interface portproxy reset。
排查MCP协议版本兼容性
方法一：查看MCP Server控制台日志，搜索关键词mcp version或protocol mismatch。当前OpenClaw v2026.3+强制要求MCP Server声明mcp-version: "2.2"，低于此版本的Server会被拒绝注册。
方法二：手动请求MCP Server的/server/initialize端点：curl -X POST http://127.0.0.1:3001/server/initialize -H "Content-Type: application/json" -d '{"version":"2.2"}'。若返回400 Bad Request或"unsupported version"，说明Server代码太旧，需升级至支持MCP 2.2的分支或镜像。
方法三：检查MCP Server项目中的manifest.json，确认"mcp_version"字段值为"2.2"。老项目常写死"2.0"或"1.0"，必须手动修改并重新构建。
