Configura OpenClaw como servidor MCP: Guía rápida

OpenClaw como servidor MCP

Este es el camino de openclaw mcp serve.

Cuándo usar serve

Usa openclaw mcp serve cuando:

• Codex, Claude Code u otro cliente MCP deba hablar directamente con conversaciones de canales de OpenClaw y ya tengas un Gateway local o remoto con sesiones enrutadas.
• Quieras un único servidor MCP que funcione a través de los backends de canales 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 y mantener la sesión del agente dentro de OpenClaw.

Cómo funciona

openclaw mcp serve inicia un servidor MCP por stdio. El cliente MCP controla ese proceso. Mientras el cliente mantiene abierta la sesión de stdio, el bridge se conecta a un Gateway de OpenClaw local o remoto a través de WebSocket y expone las conversaciones de canales enrutadas mediante MCP.

Ciclo de vida:

1. El cliente MCP lanza openclaw mcp serve.
2. El bridge se conecta al Gateway.
3. Las sesiones enrutadas se convierten en conversaciones MCP y herramientas de transcript/history.
4. Los eventos en vivo se encolan en memoria mientras el bridge está conectado.
5. Si el modo de canal de Claude está activado, la misma sesión también puede recibir notificaciones push específicas de Claude.

Comportamiento importante:

• El estado de la cola en vivo comienza cuando el bridge se conecta.
• El historial de transcript antiguo se lee con messages_read.
• Las notificaciones push de Claude solo existen mientras la sesión MCP está activa.
• Cuando el cliente se desconecta, el bridge termina y la cola en vivo desaparece.

Elige un modo de cliente

Usa el mismo bridge de dos maneras diferentes:

• Clientes MCP genéricos: solo herramientas MCP estándar. Usa conversations_list, messages_read, events_poll, events_wait, messages_send y las herramientas de aprobación.
• Claude Code: herramientas MCP estándar más el adaptador de canal específico de Claude. Activa --claude-channel-mode on o deja el valor por defecto auto.

Hoy en día, auto se comporta igual que on. Todavía no hay detección de capacidades del cliente.

Qué expone serve

El bridge utiliza los metadatos de ruta de sesión existentes del Gateway para exponer conversaciones respaldadas por canales. Una conversación aparece cuando OpenClaw ya tiene un estado de sesión con una ruta conocida como:

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

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

• listar conversaciones enrutadas recientes
• leer el historial de transcripciones recientes
• esperar nuevos eventos entrantes
• enviar una respuesta a través de la misma ruta
• ver solicitudes de aprobación que lleguen mientras el bridge está conectado

Uso

# Local Gateway
openclaw mcp serve

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

# Remote Gateway with password auth
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# Enable verbose bridge logs
openclaw mcp serve --verbose

# Disable Claude-specific push notifications
openclaw mcp serve --claude-channel-mode off

Herramientas del bridge

El bridge actual expone estas herramientas MCP:

• conversations_list
• conversation_get
• messages_read
• attachments_fetch
• events_poll
• events_wait
• messages_send
• permissions_list_open
• permissions_respond

conversations_list

Lista conversaciones recientes respaldadas por sesiones que ya tienen metadatos de ruta en el estado de sesión del Gateway.

Filtros útiles:

• limit
• search
• channel
• includeDerivedTitles
• includeLastMessage

conversation_get

Devuelve una conversación por session_key.

messages_read

Lee mensajes de transcripción recientes para una conversación respaldada por sesión.

attachments_fetch

Extrae bloques de contenido de mensajes que no sean texto de un mensaje de transcripción. Esta es una vista de metadatos sobre el contenido de la transcripción, no un almacén de archivos adjuntos duradero e independiente.

events_poll

Lee eventos en vivo en cola desde un cursor numérico.

events_wait

Realiza un long-polling hasta que llegue el próximo evento en cola que coincida o expire el tiempo de espera.

Úsalo cuando un cliente MCP genérico necesite una entrega casi en tiempo real sin un protocolo push específico de Claude.

messages_send

Envía texto de vuelta a través de la misma ruta ya registrada en la sesión.

Comportamiento actual:

• requiere una ruta de conversación existente
• usa el canal, destinatario, ID de cuenta e ID de hilo de la sesión
• envía solo texto

permissions_list_open

Lista las solicitudes de aprobación de exec/plugin pendientes que el bridge ha detectado desde que se conectó al Gateway.

permissions_respond

Resuelve una solicitud de aprobación de exec/plugin pendiente con:

• allow-once
• allow-always
• deny

Modelo de eventos

El bridge 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

Límites importantes:

• la cola es solo en vivo; comienza cuando se inicia el bridge MCP
• events_poll y events_wait no reproducen el historial antiguo del Gateway por sí mismos
• el historial duradero debe leerse con messages_read

Notificaciones de canal de Claude

El bridge también puede exponer notificaciones de canal específicas de Claude. Esta es la equivalencia en OpenClaw del adaptador de canal de Claude Code: las herramientas MCP estándar siguen disponibles y los mensajes entrantes en vivo también pueden llegar como notificaciones MCP específicas de Claude.

Flags:

• --claude-channel-mode off: solo herramientas MCP estándar
• --claude-channel-mode on: activa las notificaciones de canal de Claude
• --claude-channel-mode auto: valor por defecto actual; mismo comportamiento del bridge que on

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

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

Comportamiento actual del bridge:

• Los mensajes de transcripción user entrantes se reenvían como notifications/claude/channel
• Las solicitudes de permiso de Claude recibidas a través de MCP se rastrean en memoria
• Si la conversación vinculada envía después yes abcde o no abcde, el bridge convierte eso a notifications/claude/channel/permission
• Estas notificaciones son solo para la sesión en vivo; si el cliente MCP se desconecta, no hay un destino de push

Esto es intencionalmente específico para el cliente. Los clientes MCP genéricos deberían confiar en las herramientas de polling estándar.

Configuración del 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, te recomiendo empezar con la superficie de herramientas estándar e ignorar 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 soporta:

• --url <url>: Gateway WebSocket URL
• --token <token>: Gateway token
• --token-file <path>: lee el token desde un archivo
• --password <password>: Gateway password
• --password-file <path>: lee el password desde un archivo
• --claude-channel-mode <auto|on|off>: modo de notificación de Claude
• -v, --verbose: logs detallados en stderr

Prefiere --token-file o --password-file en lugar de secretos en línea siempre que sea posible.

Seguridad y límites de confianza

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

Esto significa:

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

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

Pruebas

OpenClaw incluye un smoke test determinista en Docker para este bridge:

pnpm test:docker:mcp-channels

Este test:

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

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

Para más contexto sobre las pruebas, consulta Testing.

Solución de problemas

No se devuelven conversaciones

Normalmente significa que la sesión del Gateway no es enrutable todavía. Confirma que la sesión subyacente tiene almacenados los metadatos de canal/provider, destinatario y la ruta opcional de cuenta/thread.

events_poll o events_wait no muestran mensajes antiguos

Es el comportamiento esperado. La cola en vivo comienza cuando el bridge se conecta. Lee el historial de transcripciones más antiguo con messages_read.

Las notificaciones de Claude no aparecen

Revisa todo esto:

• el cliente mantuvo abierta la sesión MCP de stdio
• --claude-channel-mode está en on o auto
• el cliente realmente entiende los métodos de notificación específicos de Claude
• el mensaje entrante ocurrió después de que el bridge se conectara

Faltan las aprobaciones

permissions_list_open solo muestra las solicitudes de aprobación observadas mientras el bridge estaba conectado. No es una API de historial de aprobaciones persistente.

OpenClaw como registro de clientes MCP

Esta es la ruta para openclaw mcp list, show, set y unset.

Estos comandos no exponen OpenClaw a través de MCP. Su función es gestionar las definiciones de servidores MCP que pertenecen a OpenClaw bajo la clave mcp.servers en la configuración de OpenClaw.

Esas definiciones guardadas sirven para los entornos de ejecución (runtimes) que OpenClaw lanza o configura más adelante, como Pi embebido y otros adaptadores de runtime. OpenClaw almacena las definiciones de forma centralizada para que esos entornos no tengan que mantener sus propias listas de servidores MCP duplicadas.

Comportamiento importante:

• estos comandos solo leen o escriben la configuración de OpenClaw
• no se conectan al servidor MCP de destino
• no validan si el comando, la URL o el transporte remoto están accesibles en este momento
• los adaptadores de runtime deciden qué tipos de transporte soportan realmente al momento de la ejecución

Definiciones de servidores MCP guardadas

OpenClaw también guarda un registro ligero de servidores MCP en la configuración para las interfaces que necesitan definiciones de MCP gestionadas por OpenClaw.

Comandos:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp set <name> <json>
• openclaw mcp unset <name>

Ejemplos:

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7

Ejemplo de estructura de configuración:

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com"
      }
    }
  }
}

Transporte Stdio

Lanza un proceso hijo local y se comunica a través de stdin/stdout.

Campo	Descripción
command	Ejecutable a lanzar (requerido)
args	Array de argumentos de línea de comandos
env	Variables de entorno adicionales
cwd / workingDirectory	Directorio de trabajo para el proceso

Transporte SSE / HTTP

Se conecta a un servidor MCP remoto a través de HTTP Server-Sent Events.

Campo	Descripción
url	URL HTTP o HTTPS del servidor remoto (requerido)
headers	Mapa opcional de clave-valor de cabeceras HTTP (por ejemplo, tokens de autenticación)
connectionTimeout	Tiempo de espera de conexión por servidor en ms (opcional)

Ejemplo:

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

Los valores sensibles en la url (userinfo) y en las headers se ocultan en los logs y en la salida de estado.

Transporte Streamable HTTP

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

Campo	Descripción
url	URL HTTP o HTTPS del servidor remoto (requerido)
transport	Configúralo como "streamable-http" para seleccionar este transporte
headers	Mapa opcional de clave-valor de cabeceras HTTP (por ejemplo, tokens de autenticación)
connectionTimeout	Tiempo de espera de conexión por servidor en ms (opcional)

Ejemplo:

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

Estos comandos solo gestionan la configuración guardada. No inician el puente del canal, ni abren una sesión de cliente MCP activa, ni comprueban que el servidor de destino sea accesible.

Límites actuales

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

Límites actuales:

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