OpenClaw MCP 高级配置：固定端口、超时与重试

问题一：MCP server 端口随机，如何固定？

OpenClaw 启动 MCP server 时，stdio 模式不涉及端口；HTTP / SSE 模式则会监听一个端口。如果你不指定端口，默认会随机选一个未被占用的端口。这在以下场景会出问题：

• 你想用反向代理（Nginx / Caddy）转发到 MCP server
• 你想用防火墙规则只放行特定端口
• 你的 MCP 客户端写死了端口号
• 容器之间通过端口互访

固定端口的两种方式

方式 A：在 MCP server 启动命令里指定

大部分 MCP server 实现都接受 --port 或 PORT 环境变量。在 OpenClaw 的 MCP 配置里：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "--port", "3845", "/path/to/dir"],
      "env": { "PORT": "3845" }
    }
  }
}

方式 B：使用 stdio 模式（推荐）

如果你不需要外部访问 MCP server（绝大多数本地 MCP 用例都不需要），直接用 stdio 模式就好 — OpenClaw 通过标准输入输出和 server 进程通信，根本不需要端口：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

stdio 模式更简单、更安全、不占端口、不会被外部攻击。除非你明确需要 HTTP / SSE，否则都用 stdio。

问题二：MCP 调用超时怎么设？

OpenClaw 调用 MCP 工具时，每个 MCP server 有独立的超时配置。默认值通常是 30 秒。对于慢工具（爬虫、大文件处理、跨网络 API）需要调高。

在 MCP 配置里设置 timeout

{
  "mcpServers": {
    "slow-scraper": {
      "command": "node",
      "args": ["scraper-server.js"],
      "timeout": 120000
    }
  }
}

单位是毫秒。120000 表示 120 秒。

分场景的 timeout 推荐值

问题三：MCP 调用失败怎么重试？

OpenClaw 默认不会自动重试失败的 MCP 调用 — 因为很多 MCP 工具有副作用（写文件、发请求），重试可能造成重复操作。你需要显式开启：

{
  "mcpServers": {
    "github-api": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "retry": {
        "maxAttempts": 3,
        "backoffMs": 1000
      }
    }
  }
}

建议只对读操作开启重试。写操作改用幂等设计（带 idempotency key）或在 agent 端处理失败。

问题四：MCP server 启动失败怎么排查？

OpenClaw 启动 MCP server 失败时，错误信息通常被吞掉。打开详细日志的方法：

# 容器内执行
DEBUG=mcp:* openclaw start

# 或在配置里
{
  "logging": {
    "mcp": "debug"
  }
}

常见错误及解决方案：

• spawn ENOENT — MCP server 命令找不到。检查 command 是否在 PATH 里，或用绝对路径。
• EADDRINUSE — 端口被占用。换一个端口或改用 stdio 模式。
• Permission denied — MCP server 没执行权限。chmod +x 或在容器里以 root 运行。
• npm ERR! could not determine executable — npx 包名拼错。确认 @modelcontextprotocol/server-X 包真实存在。
• 启动后立即退出 — MCP server 自己崩了。把 command 单独在终端跑一次，看真正的错误。

问题五：怎么验证 MCP 接入成功？

改完配置后让 OpenClaw reload，然后给 agent 发："列出你目前能用的所有工具"。正常情况下 MCP 提供的工具会出现在列表里，工具名格式通常是 <mcp-server-name>_<tool>。

如果列表里没有 — 一定是 MCP server 启动失败了，按上一节的方法看 debug 日志。

问题六：MCP 调用很慢怎么优化？

• 本地优先 — 把 MCP server 跑在和 OpenClaw 同一台机器（同一个容器或 host network），避免跨网络调用的 RTT。
• 持久连接 — stdio 模式保持长连接，比 HTTP 短连接快得多。
• 缓存层 — 对幂等的 MCP 调用（查询类）在 agent 这一侧加 5-60s 缓存。
• 少用 MCP，多用 Skills — OpenClaw 原生 Skill 走进程内调用，比跨进程的 MCP 快一个数量级。只有真的需要外部能力时才用 MCP。

常见问题

OpenClaw 支持 MCP 1.0 还是 0.x？

当前 OpenClaw 主线支持 MCP 1.0 标准（streamable HTTP + stdio）。0.x 时代的 SSE-only server 仍然兼容，但建议升级到 1.0 server 以获得更好的连接稳定性。

能不能同时挂多个 MCP server？

可以。在 mcpServers 字段里加多条就行。OpenClaw 会启动每个 server 并把它们的工具合并到 agent 的工具列表。

MCP server 的安全性怎么保证？

MCP server 是和 OpenClaw 跑在同一权限下的子进程。如果你装第三方 MCP server，等于给它了 OpenClaw 容器的所有权限。建议：只装可信来源的 server；用 stdio 模式（不暴露端口）；在 OpenClaw 配置里限制 MCP 工具的 allowList。

OpenClaw Launch 托管能用 MCP 吗？

可以。在 仪表盘 的 MCP 配置里粘贴你的 MCP server 配置，托管平台会在你的实例里启动这些 server。本地 MCP server（需要访问你电脑文件）则需要走 stdio + 反向连接的方式，更复杂；建议把"读本地文件"这类需求用 OpenClaw 自带的 fs Skill 实现。