MCP

openclaw mcp tem duas funções:

• executar o OpenClaw como um servidor MCP com openclaw mcp serve
• gerenciar definições de servidores MCP de saída pertencentes ao OpenClaw com list, show, set e unset

Em outras palavras:

• serve é o OpenClaw atuando como um servidor MCP
• list / show / set / unset é o OpenClaw atuando como um registro do lado do cliente MCP para outros servidores MCP que seus runtimes podem consumir depois

Use openclaw acp quando o OpenClaw deve hospedar por conta própria uma sessão de harness de codificação e rotear esse runtime por meio de ACP.

# OpenClaw como um servidor MCP

Este é o caminho openclaw mcp serve.

# Quando usar serve

Use openclaw mcp serve quando:

• Codex, Claude Code ou outro cliente MCP deve falar diretamente com conversas de canal apoiadas pelo OpenClaw
• você já tem um OpenClaw Gateway local ou remoto com sessões roteadas
• você quer um servidor MCP que funcione nos backends de canal do OpenClaw em vez de executar pontes separadas por canal

Use openclaw acp em vez disso quando o OpenClaw deve hospedar o runtime de codificação por conta própria e manter a sessão do agente dentro do OpenClaw.

# Como funciona

openclaw mcp serve inicia um servidor MCP stdio. O cliente MCP é dono desse processo. Enquanto o cliente mantém a sessão stdio aberta, a ponte se conecta a um OpenClaw Gateway local ou remoto por WebSocket e expõe conversas de canal roteadas por MCP.

# Escolha um modo de cliente

Use a mesma ponte de duas formas diferentes:

# O que serve expõe

A ponte usa metadados existentes de rota de sessão do Gateway para expor conversas apoiadas por canal. Uma conversa aparece quando o OpenClaw já tem estado de sessão com uma rota conhecida, como:

• channel
• metadados de destinatário ou destino
• accountId opcional
• threadId opcional

Isso dá aos clientes MCP um único lugar para:

• listar conversas roteadas recentes
• ler histórico recente de transcrições
• aguardar novos eventos de entrada
• enviar uma resposta de volta pela mesma rota
• ver solicitações de aprovação que chegam enquanto a ponte está conectada

# 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 --verbose
openclaw mcp serve --claude-channel-mode off

# Ferramentas da ponte

A ponte atual expõe estas ferramentas MCP:

# Modelo de eventos

A ponte mantém uma fila de eventos em memória enquanto está conectada.

Tipos de eventos atuais:

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

# Notificações de canal Claude

A ponte também pode expor notificações de canal específicas do Claude. Este é o equivalente do OpenClaw a um adaptador de canal Claude Code: ferramentas MCP padrão continuam disponíveis, mas mensagens de entrada ao vivo também podem chegar como notificações MCP específicas do Claude.

Quando o modo de canal Claude está ativado, o servidor anuncia capacidades experimentais do Claude e pode emitir:

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

Comportamento atual da ponte:

• mensagens de transcrição user de entrada são encaminhadas como notifications/claude/channel
• solicitações de permissão Claude recebidas por MCP são rastreadas em memória
• se a conversa vinculada enviar depois yes abcde ou no abcde, a ponte converte isso para notifications/claude/channel/permission
• essas notificações são apenas da sessão ao vivo; se o cliente MCP desconectar, não há alvo de push

Isso é intencionalmente específico do cliente. Clientes MCP genéricos devem depender das ferramentas padrão de polling.

# Configuração de cliente MCP

Exemplo de configuração de cliente stdio:

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

Para a maioria dos clientes MCP genéricos, comece pela superfície de ferramentas padrão e ignore o modo Claude. Ative o modo Claude apenas para clientes que realmente entendem os métodos de notificação específicos do Claude.

# Opções

openclaw mcp serve é compatível com:

# Segurança e limite de confiança

A ponte não inventa roteamento. Ela apenas expõe conversas que o Gateway já sabe como rotear.

Isso significa:

• allowlists de remetentes, pareamento e confiança no nível do canal ainda pertencem à configuração do canal OpenClaw subjacente
• messages_send só pode responder por uma rota armazenada existente
• o estado de aprovação é ao vivo/em memória apenas para a sessão atual da ponte
• a autenticação da ponte deve usar os mesmos controles de token ou senha do Gateway em que você confiaria para qualquer outro cliente remoto do Gateway

Se uma conversa estiver ausente de conversations_list, a causa usual não é a configuração MCP. São metadados de rota ausentes ou incompletos na sessão subjacente do Gateway.

# Testes

O OpenClaw inclui um smoke Docker determinístico para esta ponte:

pnpm test:docker:mcp-channels

Esse smoke:

• inicia um contêiner Gateway semeado
• inicia um segundo contêiner que executa openclaw mcp serve
• verifica descoberta de conversas, leituras de transcrição, leituras de metadados de anexos, comportamento da fila de eventos ao vivo e roteamento de envio de saída
• valida notificações de canal e permissão no estilo Claude pela ponte MCP stdio real

Esta é a forma mais rápida de provar que a ponte funciona sem conectar uma conta real do Telegram, Discord ou iMessage à execução de teste.

Para contexto mais amplo de testes, consulte Testes.

# Solução de problemas

# OpenClaw como um registro de cliente MCP

Este é o caminho de openclaw mcp list, show, set e unset.

Esses comandos não expõem o OpenClaw via MCP. Eles gerenciam definições de servidor MCP pertencentes ao OpenClaw em mcp.servers na configuração do OpenClaw.

Essas definições salvas são para runtimes que o OpenClaw inicia ou configura depois, como Pi incorporado e outros adaptadores de runtime. O OpenClaw armazena as definições de forma centralizada para que esses runtimes não precisem manter suas próprias listas duplicadas de servidores MCP.

Adaptadores de runtime podem normalizar esse registro compartilhado para o formato esperado pelo cliente downstream. Por exemplo, o Pi incorporado consome valores transport do OpenClaw diretamente, enquanto Claude Code e Gemini recebem valores type nativos da CLI, como http, sse ou stdio.

# Definições salvas de servidor MCP

O OpenClaw também armazena um registro leve de servidores MCP na configuração para superfícies que querem definições MCP gerenciadas pelo OpenClaw.

Comandos:

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

Observações:

• list ordena nomes de servidores.
• show sem um nome imprime o objeto completo de servidores MCP configurados.
• set espera um valor de objeto JSON na linha de comando.
• Use transport: "streamable-http" para servidores MCP Streamable HTTP. openclaw mcp set também normaliza type: "http" nativo da CLI para o mesmo formato canônico de configuração por compatibilidade.
• unset falha se o servidor nomeado não existir.

Exemplos:

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","transport":"streamable-http"}'
openclaw mcp unset context7

Exemplo de formato de configuração:

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

# Transporte stdio

Inicia um processo filho local e se comunica por stdin/stdout.

# Transporte SSE / HTTP

Conecta-se a um servidor MCP remoto por Eventos Enviados pelo Servidor via HTTP.

Exemplo:

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

Valores sensíveis em url (userinfo) e headers são redigidos nos logs e na saída de status.

# Transporte Streamable HTTP

streamable-http é uma opção de transporte adicional junto com sse e stdio. Ele usa streaming HTTP para comunicação bidirecional com servidores MCP remotos.

A configuração do OpenClaw usa transport: "streamable-http" como a grafia canônica. Valores MCP type: "http" nativos da CLI são aceitos quando salvos por meio de openclaw mcp set e reparados por openclaw doctor --fix em configurações existentes, mas transport é o que o Pi incorporado consome diretamente.

Exemplo:

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

# Limites atuais

Esta página documenta a ponte conforme enviada hoje.

Limites atuais:

• a descoberta de conversas depende dos metadados de rota de sessão existentes do Gateway
• nenhum protocolo push genérico além do adaptador específico do Claude
• ainda não há ferramentas para editar mensagem ou reagir
• o transporte HTTP/SSE/streamable-http conecta-se a um único servidor remoto; ainda não há upstream multiplexado
• permissions_list_open inclui apenas aprovações observadas enquanto a ponte está conectada

# Relacionado

• Referência da CLI
• Plugins