MCP

• 使用 openclaw mcp serve 将 OpenClaw 作为 MCP 服务器运行
• 使用 list、show、status、doctor、probe、add、set、configure、tools、login、logout、reload 和 unset 管理 OpenClaw 托管的出站 MCP 服务器定义

​

选择合适的 MCP 路径

​

作为 MCP 服务器的 OpenClaw

​

何时使用 serve

• Codex、Claude Code 或其他 MCP 客户端应直接与由 OpenClaw 支持的通道通信
• 你已经有一个带有已路由对话的本地或远程 OpenClaw Gateway
• 你希望有一个可跨 OpenClaw 通道后端工作的 MCP 服务器，而不是为每个通道运行一个桥接器

​

工作原理

​

选择客户端模式

​

serve 暴露的内容

• channel
• 收件人或目标元数据
• 可选的 accountId
• 可选的 threadId

• 列出最近的已路由对话
• 读取最近的会话记录历史
• 等待新的入站事件
• 通过相同路由发送回复
• 查看桥接连接期间到达的审批请求

​

用法

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
openclaw mcp serve --claude-channel-mode off

​

桥接工具

​

事件模型

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

​

Claude 通道通知

• notifications/claude/channel
• notifications/claude/channel/permission

• 传入的 user 转录消息会作为 notifications/claude/channel 转发
• 通过 MCP 接收到的 Claude 权限请求会在内存中跟踪
• 如果关联对话中的命令所有者随后发送 yes <id> 或 no <id>（<id> 是 5 位请求 ID，不包含 l），桥接器会将其转换为 notifications/claude/channel/permission
• 这些通知仅限于当前在线会话；如果 MCP 客户端断开连接，就没有推送目标

​

MCP 客户端配置

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

​

选项

​

安全与信任边界

• 发送方允许列表、配对以及通道级信任仍然属于底层的 OpenClaw 通道配置
• messages_send 只能通过已有的已存储路由进行回复
• 允许状态仅在当前桥接器会话期间处于实时内存中
• 桥接器认证应与其他远程 Gateway 客户端一样使用相同的 Gateway token 或密码控制

​

测试

pnpm test:docker:mcp-channels

​

故障排查

​

作为 MCP 客户端注册表的 OpenClaw

​

已保存的 MCP 服务器定义

• openclaw mcp list [--json]
• openclaw mcp show [name] [--json]
• openclaw mcp status [--verbose] [--json]
• openclaw mcp doctor [name] [--probe] [--json]
• openclaw mcp probe [name] [--json]
• openclaw mcp add <name> [flags]
• openclaw mcp set <name> <json>
• openclaw mcp configure <name> [flags]
• openclaw mcp tools <name> [--include csv] [--exclude csv] [--clear]
• openclaw mcp login <name> [--code code]
• openclaw mcp logout <name>
• openclaw mcp reload
• openclaw mcp unset <name>

• list 会对服务器名称进行排序。
• 不带名称的 show 会打印完整的已配置 MCP 服务器对象。
• status 会在不建立连接的情况下对已配置的传输方式进行分类。--verbose 会包含解析后的启动、超时、OAuth、筛选器和并行调用详细信息，包括已存储的 OAuth 令牌需要额外授权的情况。在文本和 JSON 输出中，包含凭据的 stdio 参数都会被隐藏。
• doctor 会在不建立连接的情况下执行静态检查。当命令还应验证已启用服务器是否能够连接时，请添加 --probe。
• probe 会建立连接，并报告工具数量、资源/提示支持情况、列表变更支持情况以及诊断信息。
• add 接受 stdio 标志，例如 --command、--arg、--env 和 --cwd；也接受 HTTP 标志，例如 --url、--transport、--header、--auth oauth、TLS、超时和工具选择标志。
• set 要求在命令行中提供一个 JSON 对象值。
• configure 会更新启用状态、工具筛选器、超时、OAuth、TLS 以及并行工具调用提示，而不会替换整个服务器定义。添加 --probe 可在保存之前验证更新后的服务器。
• tools 会更新每个服务器的工具筛选器。包含/排除条目是 MCP 工具名称和简单的 * 通配符。
• login 会为配置了 auth: "oauth" 的 HTTP 服务器运行 OAuth 流程。对于环回重定向，OpenClaw 会监听浏览器回调并自动完成登录。打印出的 --code 命令仍可作为远程、无头或无法访问回调时的备用方案。
• logout 会清除指定服务器的已存储 OAuth 凭据，但不会移除已保存的服务器定义。
• reload 仅会释放当前 CLI 进程中缓存的进程内 MCP 运行时。其他进程中的网关或代理进程仍需要各自执行重新加载或重启。
• 对于 Streamable HTTP MCP 服务器，请使用 transport: "streamable-http"。为兼容性起见，openclaw mcp set 还会将 CLI 原生的 type: "http" 规范化为相同的标准配置形式。
• 如果指定名称的服务器不存在，unset 会执行失败。

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp status --verbose
openclaw mcp doctor --probe
openclaw mcp probe context7 --json
openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp tools context7 --include 'resolve-library-id,get-library-docs'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp configure docs --timeout 20 --connect-timeout 5 --include 'search,read_*'
openclaw mcp configure docs --auth oauth --oauth-scope 'docs.read'
openclaw mcp login docs
openclaw mcp logout docs
openclaw mcp unset context7

​

常见服务器配方

openclaw mcp add files \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg "$HOME/Documents" \
  --include 'read_file,list_directory,search_files'
openclaw mcp doctor files --probe

openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory
openclaw mcp probe memory --json

openclaw mcp add local-tools \
  --command node \
  --arg ./dist/mcp-server.js \
  --cwd /srv/openclaw-tools \
  --env API_BASE=https://internal.example
openclaw mcp status --verbose

openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope docs.read \
  --timeout 20 \
  --connect-timeout 5 \
  --include 'search,read_*'
openclaw mcp doctor docs --probe

openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'
openclaw mcp tools cua-driver --include 'list_apps,get_window_state,click,type_text'
openclaw mcp doctor cua-driver --probe

​

JSON 输出形状

{
  "path": "/home/user/.openclaw/openclaw.json",
  "servers": [
    {
      "name": "docs",
      "configured": true,
      "enabled": true,
      "ok": true,
      "transport": "streamable-http",
      "launch": "streamable-http https://mcp.example.com/mcp",
      "auth": "oauth",
      "authStatus": {
        "hasTokens": true,
        "requiresAuthorization": false,
        "hasClientInformation": true,
        "hasCodeVerifier": false,
        "hasDiscoveryState": true,
        "hasLastAuthorizationUrl": false,
        "state": "authorized"
      },
      "requestTimeoutMs": 20000,
      "connectionTimeoutMs": 5000,
      "toolFilter": {
        "include": ["search", "read_*"],
        "exclude": []
      },
      "supportsParallelToolCalls": true
    }
  ]
}

{
  "ok": true,
  "path": "/home/user/.openclaw/openclaw.json",
  "servers": [
    {
      "name": "docs",
      "ok": true,
      "issues": [
        {
          "level": "warning",
          "message": "OAuth 凭据尚未授权；请运行 openclaw mcp login docs"
        }
      ]
    }
  ]
}

{
  "generatedAt": "2026-05-31T09:00:00.000Z",
  "servers": {
    "docs": {
      "launch": "streamable-http https://mcp.example.com/mcp",
      "tools": 2,
      "resources": true,
      "listChanged": {
        "tools": true,
        "resources": false,
        "prompts": false
      }
    }
  },
  "tools": ["docs__read_page", "docs__search"],
  "diagnostics": []
}

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http",
        "requestTimeoutMs": 20000,
        "connectionTimeoutMs": 5000,
        "supportsParallelToolCalls": true,
        "auth": "oauth",
        "oauth": {
          "scope": "docs.read"
        },
        "sslVerify": true,
        "clientCert": "/path/to/client.crt",
        "clientKey": "/path/to/client.key",
        "toolFilter": {
          "include": ["search_*"],
          "exclude": ["admin_*"]
        }
      }
    }
  }
}

​

Stdio 传输

​

SSE / HTTP 传输

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "auth": "oauth",
        "requestTimeoutMs": 20000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

​

OAuth 工作流

{
  gateway: {
    publicOrigin: "https://gateway.example.com",
  },
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        auth: "oauth",
        oauth: {
          identity: "per-requester",
          scope: "docs.read",
        },
      },
    },
  },
}

1. 发送者在连接账户之前调用服务器中的工具。
2. OpenClaw 为该发送者返回登录链接，而不是暴露其他发送者的凭据。
3. 提供方通过 Gateway 回调进行重定向。回调成功后，发送者使用其已连接的账户重试工具调用。

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"authProfileId":"docs:mcp"}}'

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verbose
openclaw mcp doctor docs --probe

openclaw mcp logout docs

​

Streamable HTTP 传输

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "requestTimeoutMs": 30000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

​

控制界面

1. 打开控制界面并选择 MCP。
2. 查看摘要卡片中的总数、已启用、OAuth 和已过滤服务器。
3. 使用每个服务器行查看传输、认证、过滤、超时和命令提示。
4. 当你想保留定义但将其排除在运行时发现之外时，切换启用状态。
5. 编辑作用域内的 mcp 配置段，以进行结构性更改，例如新增服务器、头部、TLS、OAuth 元数据或工具过滤器。
6. 选择 保存 仅持久化配置，或选择 保存并发布 通过 Gateway 配置路径应用。
7. 当你需要该已编辑服务器已启动并列出工具的实时证明时，运行 openclaw mcp doctor --probe。

• 命令片段会给服务器名称加引号，因此即使是不常见的名称，在 shell 中也很方便复制
• 当显示的类 URL 值包含嵌入式凭据时，会在渲染前进行脱敏
• 该页面不会自行启动 MCP 传输
• 活动运行时可能需要 openclaw mcp reload、Gateway 配置发布或进程重启，具体取决于哪个进程持有 MCP 客户端

​

MCP Apps

openclaw config set mcp.apps.enabled true --strict-json

{
  mcp: {
    apps: {
      enabled: true,
      sandboxOrigin: "https://mcp-apps.example.com",
      sandboxPort: 18790,
    },
  },
}

{
  mcp: {
    apps: { enabled: true },
    servers: {
      "basic-react": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-basic-react", "--stdio"],
      },
    },
  },
}

• 只有在启用 Apps 时，OpenClaw 才会声明 io.modelcontextprotocol/ui 扩展。
• 只有 ui:// 资源且 MIME 类型精确为 text/html;profile=mcp-app 时才会渲染。
• UI 资源大小上限为 2 MiB，放置在专用外层源上的双 iframe 代理后面，加载到不透明的内层 App 源中，并受由资源元数据派生的 CSP 约束。
• 仅限 App 的工具（_meta.ui.visibility: ["app"]）不会出现在模型工具列表中。Apps 只能调用其所属服务器上对 app 可见的工具，并且这些工具还必须通过创建该视图的运行所对应的有效 OpenClaw 工具策略。
• 基于源绑定的 App 权限（如摄像头、麦克风和地理位置）不会授予，因为内层 App 文档使用不透明源以实现跨 App 隔离。
• App HTML、完整工具参数和原始结果保存在一个有界的十分钟内存视图租约中，不会写入磁盘，也不会复制到对话预览元数据中。转录仅存储一个有界的服务器/工具/资源描述符，并与原始工具调用 ID 绑定。Gateway 重启后，Control UI 可以根据经过认证的会话转录验证该描述符，并重新获取 ui:// 资源；重建的视图在新的运行建立当前工具权限之前均为只读。
• 在频道对话中，某一轮中最新成功的 App 视图会在最终的助手回复中增加一个 打开应用 风格的动作。Telegram 私信使用原生 Mini App 按钮；Slack 和 Discord 将相同的可移植动作渲染为链接。其他频道则保留原始回复文本，并附加一个可理解的 HTTPS 链接。
• 只有在 Gateway Tailscale 暴露已准备好一个已发布的 HTTPS 源时，才可获得频道启动链接。gateway.tailscale.mode: "serve" 只能从 tailnet 访问；"funnel" 可从公共互联网访问。由 gateway.tailscale.preserveFunnel 保留的外部管理 Funnel 也视为可从互联网访问。参见 Tailscale。
• 启动票据是不透明的，仅在生成最终频道回复时铸造，并在最多两分钟后或底层视图租约到期时失效，以先发生者为准。URL 不包含 Gateway bearer 凭证、会话密钥、视图元数据、App HTML、工具输入或工具结果。
• 如果没有可用的已发布源或票据容量，或者视图/票据已过期，或者传输无法渲染原生控件，则保留原始助手文本。Control UI 会保留其现有的内联 App 画布，并且不会收到重复的启动动作。
• 在桥接启用时，openclaw security audit 会发出警告。若不需要，请使用 openclaw config set mcp.apps.enabled false --strict-json 将其禁用。

​

当前限制

• 会话发现依赖于现有的 Gateway 会话路由元数据
• 除了 Claude 特定适配器之外，没有通用的推送协议
• 目前还没有消息编辑或反应工具
• HTTP/SSE/streamable-http 传输连接到单个远程服务器；尚未支持多路复用上游
• permissions_list_open 只包含桥接连接期间观察到的审批。

​

相关

• 连接 MCP 服务器
• CLI 参考
• 插件