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 gerenciadas pelo OpenClaw com list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload e unset

Em outras palavras:

• serve é o OpenClaw atuando como um servidor MCP
• os outros subcomandos são o OpenClaw atuando como um registro do lado cliente MCP para servidores MCP que seus ambientes de execução poderão consumir depois

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

Escolha o caminho MCP correto

O OpenClaw tem várias superfícies MCP. Escolha a que corresponde a quem possui o ambiente de execução do agente e quem possui as ferramentas.

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 canais apoiadas pelo OpenClaw
• você já tem um Gateway OpenClaw 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 próprio ambiente de execução de codificação e manter a sessão do agente dentro do OpenClaw.

Como funciona

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

Escolha um modo de cliente

Use a mesma ponte de duas maneiras diferentes:

O que serve expõe

A ponte usa metadados existentes de rota de sessão do Gateway para expor conversas baseadas em canais. 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 lugar para:

• listar conversas roteadas recentes
• ler histórico de transcrição recente
• 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 --verboseopenclaw 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 evento atuais:

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

Notificações de canal do Claude

A ponte também pode expor notificações de canal específicas do Claude. Este é o equivalente no OpenClaw a um adaptador de canal Claude Code: as ferramentas MCP padrão continuam disponíveis, mas mensagens de entrada ativas 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 do Claude recebidas por MCP são rastreadas em memória
• se o proprietário do comando na conversa vinculada depois enviar yes abcde ou no abcde, a ponte converte isso em notifications/claude/channel/permission
• essas notificações são apenas de sessão ativa; se o cliente MCP se 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 com a 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 oferece suporte a:

Segurança e limite de confiança

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

Isso significa que:

• listas de permissão de remetentes, pareamento e confiança no nível do canal ainda pertencem à configuração subjacente do canal do OpenClaw
• messages_send só pode responder por uma rota armazenada existente
• o estado de aprovação é live/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 de 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 do Gateway com dados semeados
• 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 live 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 um contexto de testes mais amplo, consulte Testes.

Solução de problemas

OpenClaw como registro de clientes MCP

Este é o caminho openclaw mcp list, show, status, doctor, probe, add, set, configure, tools, login, logout, reload e unset.

Esses comandos não expõem o OpenClaw por MCP. Eles gerenciam definições de servidores MCP gerenciadas pelo OpenClaw em mcp.servers na configuração do OpenClaw. Eles não leem servidores mcporter de config/mcporter.json.

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

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

O app-server do Codex também respeita um bloco opcional codex em cada servidor. Estes são metadados de projeção do OpenClaw apenas para threads do app-server do Codex; eles não alteram sessões ACP, configuração genérica do harness do Codex nem outros adaptadores de runtime. Use codex.agents não vazio para projetar um servidor apenas para ids de agentes específicos do OpenClaw. Listas de agentes vazias, em branco ou inválidas são rejeitadas pela validação de configuração e omitidas pelo caminho de projeção de runtime em vez de se tornarem globais. Use codex.defaultToolsApprovalMode (auto, prompt ou approve) para emitir o default_tools_approval_mode nativo do Codex para um servidor confiável. O OpenClaw remove os metadados codex antes de entregar a configuração nativa mcp_servers ao Codex.

Definições salvas de servidores 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 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 nomes de servidores.
• show sem um nome imprime o objeto completo de servidores MCP configurado.
• status classifica transportes configurados sem se conectar. --verbose inclui detalhes resolvidos de inicialização, timeout, OAuth, filtro e chamadas paralelas.
• doctor executa verificações estáticas sem se conectar. Adicione --probe quando o comando também deve verificar se servidores habilitados se conectam.
• probe conecta e relata contagens de ferramentas, suporte a recursos/prompts, suporte a alteração de lista e diagnósticos.
• add aceita flags stdio como --command, --arg, --env e --cwd, ou flags HTTP como --url, --transport, --header, --auth oauth, TLS, timeout e flags de seleção de ferramentas.
• set espera um valor de objeto JSON na linha de comando.
• configure atualiza habilitação, filtros de ferramentas, timeouts, OAuth, TLS e dicas de chamadas paralelas de ferramentas sem substituir toda a definição do servidor.
• tools atualiza filtros de ferramentas por servidor. Entradas include/exclude são nomes de ferramentas MCP e globs * simples.
• login executa o fluxo OAuth para servidores HTTP configurados com auth: "oauth". A primeira execução imprime uma URL de autorização; execute novamente com --code após a aprovação.
• logout limpa credenciais OAuth armazenadas para o servidor nomeado sem remover a definição de servidor salva.
• reload descarta runtimes MCP em processo armazenados em cache. Processos de Gateway ou agente em outro processo ainda precisam de seu próprio caminho de reload ou restart.
• Use transport: "streamable-http" para servidores MCP Streamable HTTP. openclaw mcp set também normaliza type: "http" nativo da CLI para o mesmo formato de configuração canônico por compatibilidade.
• unset falha se o servidor nomeado não existir.

Exemplos:

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

Receitas comuns de servidores

Estes exemplos salvam apenas definições de servidores. Execute openclaw mcp doctor --probe depois para provar que o servidor inicia e expõe ferramentas.

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

Formatos de saída JSON

Use --json para scripts e painéis. Conjuntos de campos podem crescer com o tempo, portanto consumidores devem ignorar chaves desconhecidas.

{  "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": []}

Exemplo de formato de configuração:

{  "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 um processo filho local e se comunica por stdin/stdout.

Transporte SSE / HTTP

Conecta-se a um servidor MCP remoto por HTTP Server-Sent Events.

Exemplo:

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

Valores sensíveis em url (userinfo) e headers são redigidos nos logs e na saída de status. openclaw mcp doctor avisa quando entradas de headers ou env com aparência sensível contêm valores literais, para que operadores possam mover esses valores para fora da configuração comitada.

Fluxo de trabalho OAuth

OAuth é para servidores MCP HTTP que anunciam o fluxo OAuth do MCP. Cabeçalhos Authorization estáticos são ignorados para um servidor enquanto auth: "oauth" estiver 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

Se o provedor rotacionar tokens ou o estado de autorização ficar travado, execute openclaw mcp logout <name> e depois repita login. logout pode limpar credenciais de um servidor HTTP salvo mesmo depois que auth: "oauth" tiver sido removido da configuração, desde que o nome e a URL do servidor ainda identifiquem a entrada do armazenamento de credenciais.

Transporte HTTP transmitível

streamable-http é uma opção de transporte adicional ao lado de 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 grafia canônica. Valores MCP nativos da CLI type: "http" são aceitos quando salvos por meio de openclaw mcp set e reparados por openclaw doctor --fix na configuração existente, mas transport é o que o OpenClaw embutido consome diretamente.

Exemplo:

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

Interface de Controle

A Interface de Controle no navegador inclui uma página dedicada de configurações de MCP em /mcp. Ela mostra contagens de servidores configurados, resumos de habilitação/OAuth/filtro, linhas de transporte por servidor, controles de habilitar/desabilitar, comandos CLI comuns e um editor com escopo para a seção de configuração mcp.

Use a página para edições de operador e inventário rápido. Use openclaw mcp doctor --probe ou openclaw mcp probe quando precisar de prova ativa do servidor.

Fluxo de trabalho do operador:

1. Abra a Control UI e escolha MCP.
2. Revise os cartões de resumo de servidores totais, habilitados, OAuth e filtrados.
3. Use cada linha de servidor para conferir transporte, autenticação, filtro, tempo limite e dicas de comando.
4. Alterne a habilitação quando quiser manter uma definição, mas excluí-la da descoberta em tempo de execução.
5. Edite a seção de configuração mcp com escopo para mudanças estruturais, como novos servidores, cabeçalhos, TLS, metadados OAuth ou filtros de ferramentas.
6. Escolha Salvar para persistir apenas a configuração, ou Salvar e Publicar para aplicar pelo caminho de configuração do Gateway.
7. Execute openclaw mcp doctor --probe quando precisar de comprovação ao vivo de que o servidor editado inicia e lista ferramentas.

Observações:

• trechos de comando colocam nomes de servidor entre aspas para que nomes incomuns continuem copiáveis em um shell
• valores exibidos semelhantes a URLs são redigidos antes da renderização quando contêm credenciais incorporadas
• a página não inicia transportes MCP por conta própria
• runtimes ativos podem precisar de openclaw mcp reload, publicação da configuração do Gateway ou reinicialização do processo, dependendo de qual processo possui os clientes MCP

Limites atuais

Esta página documenta a ponte conforme distribuída hoje.

Limites atuais:

• a descoberta de conversas depende dos metadados de rota de sessão existentes do Gateway
• não há protocolo push genérico além do adaptador específico do Claude
• ainda não há ferramentas de edição de mensagens nem de reação
• 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