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

Com serve, o OpenClaw atua como um servidor MCP. Com os outros subcomandos, o OpenClaw atua como um registro MCP do lado do cliente para servidores que seus próprios runtimes poderão consumir posteriormente.

Use openclaw acp quando o próprio OpenClaw precisar hospedar uma sessão de ambiente de programação e rotear esse runtime pelo ACP.

Escolha o caminho MCP correto

OpenClaw como servidor MCP

Este é o caminho openclaw mcp serve.

Quando usar serve

Use openclaw mcp serve quando:

• o Codex, Claude Code ou outro cliente MCP precisar se comunicar diretamente com conversas de canais apoiadas pelo OpenClaw
• você já tiver um Gateway local ou remoto do OpenClaw com sessões roteadas
• você quiser um único servidor MCP que funcione com todos os backends de canais do OpenClaw, em vez de executar pontes separadas por canal

Use openclaw acp quando o próprio OpenClaw precisar hospedar o runtime de programação e manter a sessão do agente dentro do OpenClaw.

Como funciona

openclaw mcp serve inicia um servidor MCP stdio. O cliente MCP é responsável por esse processo. Enquanto o cliente mantiver a sessão stdio aberta, a ponte se conectará a um Gateway local ou remoto do OpenClaw por WebSocket e exporá conversas de canais roteadas via MCP.

Escolha um modo de cliente

O que serve expõe

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

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

Isso oferece aos clientes MCP um único lugar para:

• listar conversas roteadas recentes
• ler o histórico recente de transcrições
• aguardar novos eventos de entrada
• enviar uma resposta pela mesma rota
• ver solicitações de aprovação recebidas 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

Modelo de eventos

A ponte mantém uma fila de eventos na 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 do Claude

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

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

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

Comportamento atual da ponte:

• mensagens user de entrada da transcrição são encaminhadas como notifications/claude/channel
• as solicitações de permissão do Claude recebidas via MCP são monitoradas na memória
• se o responsável pelo comando na conversa vinculada enviar posteriormente yes <id> ou no <id> (<id> é o ID da solicitação com 5 letras, excluindo l), a ponte converterá isso em notifications/claude/channel/permission
• essas notificações existem apenas durante a sessão ativa; se o cliente MCP se desconectar, não haverá destino para o push

Isso é intencionalmente específico do cliente. Clientes MCP genéricos devem usar as ferramentas de consulta padrão.

Configuração do 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 em clientes que realmente entendam os métodos de notificação específicos do Claude.

Opções

openclaw mcp serve oferece suporte a:

Limite de segurança e confiança

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

Isso significa que:

• listas de remetentes permitidos, pareamento e confiança no nível do canal ainda pertencem à configuração subjacente do canal do OpenClaw
• messages_send só pode responder por meio de uma rota armazenada existente
• o estado de aprovação permanece ativo/somente na memória apenas durante a sessão atual da ponte
• a autenticação da ponte deve usar os mesmos controles de token ou senha do Gateway nos quais você confiaria para qualquer outro cliente remoto do Gateway

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

Testes

O OpenClaw inclui um teste de fumaça determinístico em Docker para essa ponte:

pnpm test:docker:mcp-channels

Esse teste de fumaça executa um único contêiner: ele inicializa o estado das conversas, inicia o Gateway, depois cria openclaw mcp serve como um processo filho stdio e o controla como um cliente MCP. Ele verifica a descoberta de conversas, a leitura de transcrições, a leitura de metadados de anexos, o comportamento da fila de eventos em tempo real e as notificações de canal e permissão no estilo do Claude por meio da ponte MCP stdio real. O roteamento de envios de saída (messages_send reutilizando a rota armazenada da conversa) é coberto separadamente por testes unitários em src/mcp/channel-server.test.ts.

Essa é a maneira mais rápida de comprovar que a ponte funciona sem vincular uma conta real do Telegram, Discord ou iMessage à execução do teste.

Para um contexto mais amplo sobre testes, consulte Testes.

Solução de problemas

OpenClaw como registro de clientes MCP

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

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

Essas definições salvas são destinadas a runtimes que o OpenClaw inicia ou configura posteriormente, como o OpenClaw 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.

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

O app-server do Codex também respeita um bloco opcional codex em cada servidor. Esses são metadados de projeção do OpenClaw somente para threads do app-server do Codex; eles não alteram sessões ACP, a configuração genérica do executor do Codex nem outros adaptadores de runtime. Use codex.agents não vazio para projetar um servidor somente em IDs específicos de agentes do OpenClaw. Listas de agentes vazias, em branco ou inválidas são rejeitadas pela validação da configuração e omitidas pelo caminho de projeção do 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

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>

Observações:

• list ordena os nomes dos servidores.
• show sem um nome exibe o objeto completo de servidores MCP configurados.
• status classifica os transportes configurados sem se conectar. --verbose inclui detalhes resolvidos de inicialização, tempo limite, OAuth, filtro e chamadas paralelas.
• doctor executa verificações estáticas sem se conectar. Adicione --probe quando o comando também precisar verificar se os servidores ativados se conectam.
• probe conecta-se e relata a contagem de ferramentas, o suporte a recursos/prompts, o suporte a alterações de lista e os diagnósticos.
• add aceita opções de stdio, como --command, --arg, --env e --cwd, ou opções HTTP, como --url, --transport, --header, --auth oauth, TLS, tempo limite e opções de seleção de ferramentas.
• set espera um valor de objeto JSON na linha de comando.
• configure atualiza a ativação, os filtros de ferramentas, os tempos limite, o OAuth, o TLS e as indicações de chamadas paralelas de ferramentas sem substituir toda a definição do servidor. Adicione --probe para verificar o servidor atualizado antes de salvar.
• tools atualiza os filtros de ferramentas por servidor. As entradas de inclusão/exclusão são nomes de ferramentas MCP e globs simples com *.
• login executa o fluxo OAuth para servidores HTTP configurados com auth: "oauth". A primeira execução exibe uma URL de autorização; execute novamente com --code após a aprovação.
• logout limpa as credenciais OAuth armazenadas do servidor especificado sem remover a definição salva do servidor.
• reload descarta os runtimes MCP em processo armazenados em cache apenas para o processo atual da CLI. Processos do Gateway ou de agentes em outro processo ainda precisam de seu próprio caminho de recarregamento ou reinicialização.
• Use transport: "streamable-http" para servidores MCP de HTTP com streaming. openclaw mcp set também normaliza o type: "http" nativo da CLI para o mesmo formato canônico de configuração para fins de compatibilidade.
• unset falha se o servidor especificado 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 as definições dos servidores. Execute openclaw mcp doctor --probe depois para comprovar que o servidor é iniciado 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. Os conjuntos de campos podem aumentar com o tempo, portanto, os 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": true,  "path": "/home/user/.openclaw/openclaw.json",  "servers": [    {      "name": "docs",      "ok": true,      "issues": [        {          "level": "warning",          "message": "As credenciais OAuth não estão autorizadas; execute 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": []}

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 confidenciais em url (informações do usuário) e headers são ocultados nos logs e na saída de status. openclaw mcp doctor avisa quando entradas de headers ou env que parecem confidenciais contêm valores literais, para que os operadores possam remover esses valores da configuração versionada.

Fluxo de trabalho OAuth

OAuth destina-se a 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. As credenciais salvas por openclaw mcp login funcionam com o MCP incorporado, executores da CLI e o servidor de aplicativo local do Codex.

Até que as credenciais estejam disponíveis, o OpenClaw omite somente esse servidor MCP do runtime do agente, em vez de causar falha no turno do agente. O operador, ou um agente com acesso ao shell, pode então executar openclaw mcp login <name> e usar o servidor em um turno posterior.

Quando um serviço MCP remoto já é respaldado por um perfil de autenticação separado do OpenClaw com capacidade de renovação, você pode definir opcionalmente oauth.authProfileId. O OpenClaw renova qualquer uma das fontes de credenciais antes da projeção no runtime e passa somente o token de acesso atual ao cliente MCP subsequente.

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 --verboseopenclaw mcp doctor docs --probe

openclaw mcp logout docs

Se o provedor rotacionar os tokens ou o estado da autorização ficar travado, execute openclaw mcp logout <name> e repita login. logout pode limpar as 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 com streaming

streamable-http é uma opção de transporte adicional, além de sse e stdio. Ela 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 type: "http" do MCP nativo da CLI são aceitos quando salvos por meio de openclaw mcp set e corrigidos por openclaw doctor --fix na configuração existente, mas transport é o que o OpenClaw incorporado 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 do MCP em /settings/mcp; o caminho anterior /mcp permanece como um alias. A página mostra contagens de servidores configurados, resumos de servidores habilitados/OAuth/filtros, linhas de transporte por servidor, controles para habilitar/desabilitar, comandos comuns da CLI e um editor com escopo definido para a seção de configuração mcp.

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

Fluxo de trabalho do operador:

1. Abra a Interface de controle e escolha MCP.
2. Confira os cartões de resumo para o total de servidores, habilitados, com OAuth e filtrados.
3. Use cada linha de servidor para ver indicações de transporte, autenticação, filtro, tempo limite e comandos.
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 definido para alterações estruturais, como novos servidores, cabeçalhos, TLS, metadados OAuth ou filtros de ferramentas.
6. Escolha Save para apenas persistir a configuração ou Save & Publish para aplicá-la por meio do caminho de configuração do Gateway.
7. Execute openclaw mcp doctor --probe quando precisar de uma comprovação ativa de que o servidor editado inicia e lista as ferramentas.

Observações:

• os trechos de comandos colocam os nomes dos servidores entre aspas para que nomes incomuns continuem podendo ser copiados e usados em um shell
• valores exibidos semelhantes a URLs são ocultados antes da renderização quando contêm credenciais incorporadas
• a página não inicia transportes MCP por conta própria
• tempos de execução ativos podem exigir openclaw mcp reload, publicação da configuração do Gateway ou reinicialização do processo, dependendo de qual processo controla os clientes MCP

Aplicativos MCP

O OpenClaw pode renderizar ferramentas que implementam a extensão estável MCP Apps. Os aplicativos são opcionais porque seu HTML vem do servidor MCP configurado e pode solicitar ferramentas ou recursos visíveis ao aplicativo nesse mesmo servidor.

Habilite a ponte do host:

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

Reinicie o Gateway após alterar essa configuração. Quando habilitado, o OpenClaw inicia um listener HTTP(S) exclusivo do sandbox na porta do Gateway mais um (para o Gateway padrão, 18790). A Interface de controle carrega os aplicativos dessa origem separada; o listener nunca disponibiliza a Interface de controle, rotas autenticadas do Gateway ou dados do usuário.

As conexões diretas com o Gateway precisam de acesso a ambas as portas. Se um proxy reverso ou terminador TLS expuser a Interface de controle, forneça aos aplicativos uma origem pública dedicada e encaminhe somente essa origem ao listener do sandbox:

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

A origem do sandbox deve ser diferente da origem da Interface de controle. Não hospede nela outro conteúdo autenticado ou confidencial.

Por exemplo, a demonstração básica oficial em React pode ser configurada assim:

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

Limites de comportamento e segurança:

• O OpenClaw anuncia a extensão io.modelcontextprotocol/ui somente quando os aplicativos estão habilitados.
• Somente recursos ui:// com o tipo MIME exato text/html;profile=mcp-app são renderizados.
• Os recursos da interface são limitados a 2 MiB, colocados atrás de um proxy de iframe duplo em uma origem externa dedicada, carregados em uma origem interna opaca do aplicativo e restringidos por uma CSP derivada dos metadados do recurso.
• Ferramentas exclusivas de aplicativos (_meta.ui.visibility: ["app"]) não aparecem nas listas de ferramentas do modelo. Os aplicativos podem chamar somente ferramentas visíveis a aplicativos em seu servidor de origem.
• Permissões do aplicativo vinculadas à origem, como câmera, microfone e geolocalização, não são concedidas enquanto os documentos internos do aplicativo usam origens opacas para isolamento entre aplicativos.
• O HTML do aplicativo, os argumentos completos das ferramentas e os resultados brutos permanecem em uma concessão de visualização em memória, limitada a dez minutos. Eles não são gravados em disco nem copiados para os metadados de pré-visualização da transcrição, e uma visualização expirada não reinicia seu tempo de execução MCP.
• openclaw security audit emite um aviso enquanto a ponte está habilitada. Desabilite-a com openclaw config set mcp.apps.enabled false --strict-json quando ela não for necessária.

Limites atuais

Esta página documenta a ponte conforme disponibilizada atualmente.

Limites atuais:

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

Conteúdo relacionado

• Referência da CLI
• Plugins