MCP

openclaw mcp tiene dos tareas:

• ejecutar OpenClaw como un servidor MCP con openclaw mcp serve
• administrar definiciones de servidores MCP salientes gestionadas por OpenClaw con list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload y unset

En otras palabras:

• serve es OpenClaw actuando como servidor MCP
• los otros subcomandos son OpenClaw actuando como un registro del lado del cliente MCP para servidores MCP que sus runtimes pueden consumir más adelante

Usa openclaw acp cuando OpenClaw deba alojar por sí mismo una sesión de arnés de codificación y enrutar ese runtime a través de ACP.

Elige la ruta MCP correcta

OpenClaw tiene varias superficies MCP. Elige la que coincida con quién es propietario del runtime del agente y quién es propietario de las herramientas.

OpenClaw como servidor MCP

Esta es la ruta openclaw mcp serve.

Cuándo usar serve

Usa openclaw mcp serve cuando:

• Codex, Claude Code u otro cliente MCP deba comunicarse directamente con conversaciones de canales respaldadas por OpenClaw
• ya tengas un Gateway de OpenClaw local o remoto con sesiones enrutadas
• quieras un servidor MCP que funcione en todos los backends de canal de OpenClaw en lugar de ejecutar puentes separados por canal

Usa openclaw acp en su lugar cuando OpenClaw deba alojar el runtime de codificación por sí mismo y mantener la sesión del agente dentro de OpenClaw.

Cómo funciona

openclaw mcp serve inicia un servidor MCP stdio. El cliente MCP es propietario de ese proceso. Mientras el cliente mantiene abierta la sesión stdio, el puente se conecta a un Gateway de OpenClaw local o remoto mediante WebSocket y expone conversaciones de canales enrutadas mediante MCP.

Elige un modo de cliente

Usa el mismo puente de dos formas diferentes:

Qué expone serve

El puente usa metadatos de ruta de sesión existentes de Gateway para exponer conversaciones respaldadas por canales. Una conversación aparece cuando OpenClaw ya tiene estado de sesión con una ruta conocida, como:

• channel
• metadatos de destinatario o destino
• accountId opcional
• threadId opcional

Esto da a los clientes MCP un único lugar para:

• listar conversaciones enrutadas recientes
• leer historial reciente de transcripciones
• esperar nuevos eventos entrantes
• enviar una respuesta de vuelta por la misma ruta
• ver solicitudes de aprobación que llegan mientras el puente está conectado

Uso

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 --verboseopenclaw mcp serve --claude-channel-mode off

Herramientas del puente

El puente actual expone estas herramientas MCP:

Modelo de eventos

El puente mantiene una cola de eventos en memoria mientras está conectado.

Tipos de eventos actuales:

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

Notificaciones de canal de Claude

El puente también puede exponer notificaciones de canal específicas de Claude. Este es el equivalente de OpenClaw a un adaptador de canal de Claude Code: las herramientas MCP estándar siguen disponibles, pero los mensajes entrantes en vivo también pueden llegar como notificaciones MCP específicas de Claude.

Cuando el modo de canal de Claude está habilitado, el servidor anuncia capacidades experimentales de Claude y puede emitir:

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

Comportamiento actual del puente:

• los mensajes de transcripción entrantes de user se reenvían como notifications/claude/channel
• las solicitudes de permiso de Claude recibidas mediante MCP se registran en memoria
• si el propietario del comando en la conversación vinculada envía más tarde yes abcde o no abcde, el puente lo convierte en notifications/claude/channel/permission
• estas notificaciones son solo de sesión en vivo; si el cliente MCP se desconecta, no hay destino push

Esto es intencionalmente específico del cliente. Los clientes MCP genéricos deben depender de las herramientas de sondeo estándar.

Configuración de cliente MCP

Ejemplo de configuración de cliente stdio:

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

Para la mayoría de los clientes MCP genéricos, empieza con la superficie de herramientas estándar e ignora el modo Claude. Activa el modo Claude solo para clientes que realmente entiendan los métodos de notificación específicos de Claude.

Opciones

openclaw mcp serve admite:

Seguridad y límite de confianza

El puente no inventa el enrutamiento. Solo expone conversaciones que Gateway ya sabe cómo enrutar.

Eso significa:

• las listas de remitentes permitidos, el emparejamiento y la confianza a nivel de canal siguen perteneciendo a la configuración de canal de OpenClaw subyacente
• messages_send solo puede responder a través de una ruta almacenada existente
• el estado de aprobación está activo/en memoria solo para la sesión actual del puente
• la autenticación del puente debe usar los mismos controles de token o contraseña de Gateway en los que confiarías para cualquier otro cliente remoto de Gateway

Si falta una conversación en conversations_list, la causa habitual no es la configuración de MCP. Son metadatos de ruta ausentes o incompletos en la sesión de Gateway subyacente.

Pruebas

OpenClaw incluye una prueba de humo Docker determinista para este puente:

pnpm test:docker:mcp-channels

Esa prueba de humo:

• inicia un contenedor de Gateway con datos iniciales
• inicia un segundo contenedor que genera openclaw mcp serve
• verifica la detección de conversaciones, las lecturas de transcripciones, las lecturas de metadatos de adjuntos, el comportamiento de la cola de eventos en vivo y el enrutamiento de envíos salientes
• valida notificaciones de permisos y canales al estilo de Claude sobre el puente MCP stdio real

Esta es la forma más rápida de demostrar que el puente funciona sin conectar una cuenta real de Telegram, Discord o iMessage a la ejecución de pruebas.

Para un contexto de pruebas más amplio, consulta Pruebas.

Solución de problemas

OpenClaw como registro de clientes MCP

Esta es la ruta de openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload y unset.

Estos comandos no exponen OpenClaw a través de MCP. Gestionan definiciones de servidores MCP administradas por OpenClaw bajo mcp.servers en la configuración de OpenClaw. No leen servidores de mcporter desde config/mcporter.json.

Esas definiciones guardadas son para runtimes que OpenClaw inicia o configura más adelante, como OpenClaw integrado y otros adaptadores de runtime. OpenClaw almacena las definiciones de forma centralizada para que esos runtimes no necesiten mantener sus propias listas duplicadas de servidores MCP.

Los adaptadores de runtime pueden normalizar este registro compartido a la forma que espera su cliente descendente. Por ejemplo, OpenClaw integrado consume directamente los valores transport de OpenClaw, mientras que Claude Code y Gemini reciben valores type nativos de CLI como http, sse o stdio.

El servidor de aplicación de Codex también respeta un bloque opcional codex en cada servidor. Estos son metadatos de proyección de OpenClaw solo para hilos del servidor de aplicación de Codex; no cambian las sesiones ACP, la configuración genérica del arnés de Codex ni otros adaptadores de runtime. Usa codex.agents no vacío para proyectar un servidor solo en ids de agente de OpenClaw específicos. Las listas de agentes vacías, en blanco o no válidas se rechazan mediante la validación de configuración y se omiten en la ruta de proyección de runtime en lugar de volverse globales. Usa codex.defaultToolsApprovalMode (auto, prompt o approve) para emitir el default_tools_approval_mode nativo de Codex para un servidor de confianza. OpenClaw elimina los metadatos codex antes de entregar la configuración nativa mcp_servers a Codex.

Definiciones guardadas de servidores MCP

OpenClaw también almacena un registro ligero de servidores MCP en la configuración para superficies que quieren definiciones MCP administradas por OpenClaw.

Comandos:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp status [--verbose]
• openclaw mcp doctor [name] [--probe]
• openclaw mcp probe [name]
• 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>

Notas:

• list ordena los nombres de servidores.
• show sin nombre imprime el objeto completo de servidores MCP configurados.
• status clasifica los transportes configurados sin conectarse. --verbose incluye detalles resueltos de inicio, tiempo de espera, OAuth, filtro y llamadas paralelas.
• doctor realiza comprobaciones estáticas sin conectarse. Agrega --probe cuando el comando también deba verificar que los servidores habilitados se conectan.
• probe se conecta e informa recuentos de herramientas, compatibilidad con recursos/prompts, compatibilidad con cambios de lista y diagnósticos.
• add acepta flags de stdio como --command, --arg, --env y --cwd, o flags HTTP como --url, --transport, --header, --auth oauth, TLS, tiempo de espera y flags de selección de herramientas.
• set espera un valor de objeto JSON en la línea de comandos.
• configure actualiza habilitación, filtros de herramientas, tiempos de espera, OAuth, TLS e indicaciones de llamadas paralelas a herramientas sin reemplazar toda la definición del servidor.
• tools actualiza filtros de herramientas por servidor. Las entradas include/exclude son nombres de herramientas MCP y globs * simples.
• login ejecuta el flujo OAuth para servidores HTTP configurados con auth: "oauth". La primera ejecución imprime una URL de autorización; vuelve a ejecutar con --code después de la aprobación.
• logout borra las credenciales OAuth almacenadas para el servidor nombrado sin eliminar la definición de servidor guardada.
• reload descarta runtimes MCP en proceso almacenados en caché. Los procesos de Gateway o de agente en otro proceso aún necesitan su propia ruta de recarga o reinicio.
• Usa transport: "streamable-http" para servidores MCP HTTP transmitibles. openclaw mcp set también normaliza type: "http" nativo de CLI a la misma forma de configuración canónica por compatibilidad.
• unset falla si el servidor nombrado no existe.

Ejemplos:

openclaw mcp listopenclaw mcp show context7 --jsonopenclaw mcp status --verboseopenclaw mcp doctor --probeopenclaw mcp probe context7 --jsonopenclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memoryopenclaw 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 docsopenclaw mcp logout docsopenclaw mcp unset context7

Recetas comunes de servidores

Estos ejemplos solo guardan definiciones de servidores. Ejecuta openclaw mcp doctor --probe después para demostrar que el servidor se inicia y expone herramientas.

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-memoryopenclaw 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.exampleopenclaw 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,observe,click,type'openclaw mcp doctor cua-driver --probe

Formas de salida JSON

Usa --json para scripts y paneles. Los conjuntos de campos pueden crecer con el tiempo, por lo que los consumidores deben ignorar las claves desconocidas.

{  "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,        "hasClientInformation": true,        "hasCodeVerifier": false,        "hasDiscoveryState": true,        "hasLastAuthorizationUrl": false      },      "requestTimeoutMs": 20000,      "connectionTimeoutMs": 5000,      "toolFilter": {        "include": ["search", "read_*"],        "exclude": []      },      "supportsParallelToolCalls": true    }  ]}

{  "ok": false,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": false,      "issues": [        {          "level": "error",          "message": "OAuth credentials are not authorized; run openclaw mcp login docs"        }      ]    }  ]}

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

Forma de configuración de ejemplo:

{  "mcp": {    "servers": {      "context7": {        "command": "uvx",        "args": ["context7-mcp"]      },      "docs": {        "url": "https://mcp.example.com",        "transport": "streamable-http",        "timeout": 20,        "connectTimeout": 5,        "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_*"]        }      }    }  }}

Transporte stdio

Inicia un proceso hijo local y se comunica por stdin/stdout.

Transporte SSE / HTTP

Se conecta a un servidor MCP remoto mediante HTTP Server-Sent Events.

Ejemplo:

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

Los valores confidenciales en url (userinfo) y headers se censuran en los registros y la salida de estado. openclaw mcp doctor advierte cuando las entradas de headers o env con apariencia confidencial contienen valores literales, para que los operadores puedan sacar esos valores de la configuración confirmada.

Flujo de trabajo OAuth

OAuth es para servidores MCP HTTP que anuncian el flujo OAuth de MCP. Los encabezados Authorization estáticos se ignoran para un servidor mientras auth: "oauth" está habilitado.

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

openclaw mcp login docs

openclaw mcp login docs --code abc123

openclaw mcp status --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

Si el proveedor rota tokens o el estado de autorización queda atascado, ejecuta openclaw mcp logout <name> y luego repite login. logout puede borrar credenciales de un servidor HTTP guardado incluso después de que auth: "oauth" se haya eliminado de la configuración, siempre que el nombre del servidor y la URL sigan identificando la entrada del almacén de credenciales.

Transporte HTTP transmitible

streamable-http es una opción de transporte adicional junto con sse y stdio. Usa streaming HTTP para la comunicación bidireccional con servidores MCP remotos.

La configuración de OpenClaw usa transport: "streamable-http" como la grafía canónica. Los valores type: "http" nativos del MCP de la CLI se aceptan cuando se guardan mediante openclaw mcp set y openclaw doctor --fix los repara en la configuración existente, pero transport es lo que OpenClaw incrustado consume directamente.

Ejemplo:

{  "mcp": {    "servers": {      "streaming-tools": {        "url": "https://mcp.example.com/stream",        "transport": "streamable-http",        "connectTimeout": 10,        "timeout": 30,        "headers": {          "Authorization": "Bearer <token>"        }      }    }  }}

Interfaz de control

La interfaz de control del navegador incluye una página dedicada de configuración de MCP en /mcp. Muestra recuentos de servidores configurados, resúmenes de habilitación/OAuth/filtros, filas de transporte por servidor, controles para habilitar/deshabilitar, comandos comunes de la CLI y un editor delimitado para la sección de configuración mcp.

Usa la página para ediciones de operadores e inventario rápido. Usa openclaw mcp doctor --probe u openclaw mcp probe cuando necesites una prueba de servidor en vivo.

Flujo de trabajo del operador:

1. Abre la interfaz de control y elige MCP.
2. Revisa las tarjetas de resumen para servidores totales, habilitados, OAuth y filtrados.
3. Usa cada fila de servidor para obtener indicaciones de transporte, autenticación, filtro, tiempo de espera y comando.
4. Activa o desactiva la habilitación cuando quieras conservar una definición pero excluirla del descubrimiento en tiempo de ejecución.
5. Edita la sección de configuración mcp con alcance para cambios estructurales como servidores nuevos, encabezados, TLS, metadatos de OAuth o filtros de herramientas.
6. Elige Guardar para persistir solo la configuración, o Guardar y publicar para aplicarla mediante la ruta de configuración del Gateway.
7. Ejecuta openclaw mcp doctor --probe cuando necesites una prueba en vivo de que el servidor editado se inicia y lista herramientas.

Notas:

• los fragmentos de comando entrecomillan los nombres de servidores para que los nombres inusuales sigan siendo copiables en una shell
• los valores mostrados con formato de URL se redactan antes de renderizarse cuando contienen credenciales incrustadas
• la página no inicia transportes MCP por sí misma
• los tiempos de ejecución activos pueden necesitar openclaw mcp reload, publicación de configuración del Gateway o reinicio del proceso, según qué proceso sea propietario de los clientes MCP

Límites actuales

Esta página documenta el puente tal como se distribuye hoy.

Límites actuales:

• el descubrimiento de conversaciones depende de los metadatos de ruta de sesión existentes del Gateway
• no hay ningún protocolo push genérico más allá del adaptador específico de Claude
• todavía no hay herramientas para editar mensajes ni reaccionar
• el transporte HTTP/SSE/streamable-http se conecta a un único servidor remoto; todavía no hay upstream multiplexado
• permissions_list_open solo incluye aprobaciones observadas mientras el puente está conectado

Relacionado

• Referencia de la CLI
• Plugins