【Bug已解决】openclaw: MCP server connection failed / Tool provider unavailable — OpenClaw MCP 服务器连接失败解决方案1. 问题描述OpenClaw 无法连接 MCPModel Context Protocol服务器或工具提供者不可用# MCP 服务器连接失败 $ openclaw 使用文件系统工具 Error: MCP server connection failed Cannot connect to filesystem MCP server. # 或工具提供者不可用 $ openclaw 搜索代码 Error: Tool provider unavailable MCP server code-search is not running. # 或 MCP 配置错误 $ openclaw Error: Failed to load MCP config Invalid MCP configuration at line 15. # 或 MCP 超时 $ openclaw task Error: MCP timeout Server did not respond within 30000ms.这个问题在以下场景中特别常见MCP 服务器未启动MCP 配置错误端口冲突MCP 服务器崩溃超时设置过小依赖缺失2. 原因分析原因分类表原因分类具体表现占比服务器未启动not running约 35%配置错误JSON约 25%端口冲突port in use约 15%服务器崩溃crash约 10%超时30s约 10%依赖缺失module约 5%3. 解决方案方案一启动 MCP 服务器最推荐# 步骤 1检查 MCP 服务器状态 openclaw --mcp-status # 步骤 2启动 MCP 服务器 openclaw --mcp-start filesystem openclaw --mcp-start code-search # 步骤 3或启动所有 openclaw --mcp-start-all # 步骤 4验证 openclaw --mcp-status openclaw 使用文件系统工具方案二检查 MCP 配置# 步骤 1检查配置 cat .openclaw/mcp_config.json # 步骤 2验证 JSON python3 -m json.tool .openclaw/mcp_config.json # 步骤 3修复配置 cat .openclaw/mcp_config.json EOF { servers: { filesystem: { command: npx, args: [-y, anthropic/mcp-filesystem], timeout: 30000 } } } EOF # 步骤 4验证 python3 -m json.tool .openclaw/mcp_config.json openclaw --mcp-status方案三检查端口# 步骤 1检查端口占用 lsof -i :3000 # MCP 常用端口 # 步骤 2如果端口被占用 kill -9 $(lsof -t -i :3000) # 步骤 3或更换端口 cat .openclaw/mcp_config.json EOF { servers: { filesystem: { port: 3001 } } } EOF # 步骤 4验证 openclaw --mcp-status方案四增加超时# 步骤 1增加 MCP 超时 cat .openclaw/mcp_config.json EOF { servers: { filesystem: { timeout: 60000 } } } EOF # 步骤 2或环境变量 export OPENCLAW_MCP_TIMEOUT60000 # 步骤 3永久设置 echo export OPENCLAW_MCP_TIMEOUT60000 ~/.bashrc source ~/.bashrc # 步骤 4验证 openclaw --mcp-status方案五重启 MCP 服务器# 步骤 1停止所有 MCP openclaw --mcp-stop-all # 步骤 2清除缓存 rm -rf ~/.openclaw/mcp_cache/ # 步骤 3重新启动 openclaw --mcp-start-all # 步骤 4验证 openclaw --mcp-status openclaw task方案六安装 MCP 依赖# 步骤 1检查依赖 npm list -g anthropic/mcp-filesystem # 步骤 2安装缺失依赖 npm install -g anthropic/mcp-filesystem npm install -g anthropic/mcp-code-search # 步骤 3或使用 npx不需要全局安装 cat .openclaw/mcp_config.json EOF { servers: { filesystem: { command: npx, args: [-y, anthropic/mcp-filesystem] } } } EOF # 步骤 4验证 openclaw --mcp-status4. 各方案对比总结方案适用场景推荐指数难度方案一启动未运行⭐⭐⭐⭐⭐低方案二配置JSON⭐⭐⭐⭐⭐低方案三端口冲突⭐⭐⭐⭐低方案四超时30s⭐⭐⭐⭐低方案五重启崩溃⭐⭐⭐⭐⭐低方案六依赖缺失⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 MCP 是什么Model Context Protocol。允许 OpenClaw 连接外部工具服务器。5.2 如何检查 MCP 状态openclaw --mcp-status5.3 如何启动 MCP 服务器openclaw --mcp-start filesystem # 或 openclaw --mcp-start-all5.4 MCP 配置在哪里.openclaw/mcp_config.json。5.5 端口冲突怎么办lsof -i :port检查kill终止或更换端口。5.6 MCP 超时多少默认 30 秒。通过配置中的timeout或OPENCLAW_MCP_TIMEOUT调整。5.7 如何重启 MCPopenclaw --mcp-stop-all openclaw --mcp-start-all5.8 MCP 依赖缺失使用npm install -g安装或使用npx -y自动安装。5.9 npx 是什么Node.js 包执行器不需要全局安装即可运行包。5.10 排查清单速查表□ 1. openclaw --mcp-status 检查 □ 2. openclaw --mcp-start-all 启动 □ 3. python3 -m json.tool 验证配置 □ 4. cat .openclaw/mcp_config.json 检查 □ 5. lsof -i :port 检查端口 □ 6. kill 端口占用进程 □ 7. timeout: 60000 增加超时 □ 8. OPENCLAW_MCP_TIMEOUT60000 □ 9. openclaw --mcp-stop-all start 重启 □ 10. npm install -g 安装依赖6. 总结根本原因MCP 连接失败最常见原因是服务器未启动35%和配置错误25%最佳实践使用openclaw --mcp-start-all启动所有 MCP 服务器配置验证python3 -m json.tool验证 MCP 配置 JSON端口检查lsof -i :port检查冲突更换端口或 kill 进程最佳实践建议使用npx -y自动安装依赖设置timeout: 60000增加超时故障排查流程图flowchart TD A[MCP 连接失败] -- B[openclaw --mcp-status] B -- C{服务器运行?} C --|否| D[启动服务器] C --|是| E[检查配置] D -- F[openclaw --mcp-start-all] F -- G[openclaw task 验证] E -- H[cat mcp_config.json] H -- I[python3 -m json.tool] I -- J{JSON 有效?} J --|否| K[修复配置] J --|是| L[检查端口] K -- G L -- M[lsof -i :port] M -- N{端口冲突?} N --|是| O[kill 进程或换端口] N --|否| P[检查超时] O -- G P -- Q{超时?} Q --|是| R[timeout: 60000] Q --|否| S[重启 MCP] R -- G S -- T[openclaw --mcp-stop-all] T -- U[rm -rf mcp_cache] U -- V[openclaw --mcp-start-all] V -- G G -- W{成功?} W --|是| X[✅ 问题解决] W --|否| Y[安装依赖] Y -- Z[npm install -g mcp-filesystem] Z -- G G -- AA{成功?} AA --|是| X AA --|否| AB[使用 npx -y] AB -- AC[config: command npx args -y] AC -- G X -- AD[长期: mcp-start 配置 超时] AD -- AE[✅ 长期方案]