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

serve é o OpenClaw atuando como um servidor MCP. Os outros subcomandos correspondem ao OpenClaw atuando como um registro de servidores no lado do cliente MCP, que seus próprios runtimes poderão consumir posteriormente.

Use openclaw acp quando o OpenClaw precisar hospedar uma sessão de harness de programação e encaminhar esse runtime por meio do ACP.

Escolha o caminho MCP correto

OpenClaw como um servidor MCP

Este é o caminho de openclaw mcp serve.

Quando usar serve

Use openclaw mcp serve quando:

• Codex, Claude Code ou outro cliente MCP precisar se comunicar diretamente com conversas de canais apoiadas pelo OpenClaw
• já houver um Gateway local ou remoto do OpenClaw com sessões encaminhadas
• for necessário um único servidor MCP que funcione nos backends de canais do OpenClaw, em vez de executar pontes separadas para cada canal

Use openclaw acp quando o OpenClaw precisar hospedar o próprio 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 é o proprietário desse processo. Enquanto o cliente mantiver a sessão stdio aberta, a ponte se conectará a um Gateway local ou remoto do OpenClaw via WebSocket e exporá conversas de canais encaminhadas por meio do MCP.

Escolha um modo de cliente

O que serve expõe

A ponte usa os metadados existentes de rota 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 encaminhadas recentes
• ler o 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 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 do canal do Claude

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

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

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

Comportamento atual da ponte:

• as mensagens de entrada user da transcrição são encaminhadas como notifications/claude/channel
• as solicitações de permissão do Claude recebidas por MCP são acompanhadas na memória
• se o proprietário do comando na conversa vinculada enviar posteriormente yes <id> ou no <id> (<id> é o ID da solicitação de 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á um destino para o envio

Isso é intencionalmente específico do cliente. Clientes MCP genéricos devem usar as ferramentas de sondagem 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 somente para clientes que realmente compreendam 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:

• as listas de remetentes permitidos, o pareamento e a 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 existe apenas ao vivo/em memória 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 aparecer em conversations_list, normalmente a causa 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 rápido determinístico em Docker para essa ponte:

pnpm test:docker:mcp-channels

Esse teste rápido executa um único contêiner: ele inicializa o estado das conversas, inicia o Gateway e, em seguida, gera 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 ao vivo e as notificações de canal e permissão no estilo Claude pela 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 conectar uma conta real do Telegram, Discord ou iMessage à execução do teste.

Para obter um contexto mais amplo sobre testes, consulte Testes.

Solução de problemas

OpenClaw como um 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 por MCP. Eles gerenciam as 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 destinam-se 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 transport do OpenClaw, 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. 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 harness do Codex nem outros adaptadores de runtime. Use codex.agents não vazio para projetar um servidor apenas em IDs de agentes específicos 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 mcp_servers nativa ao Codex.

Definições de servidores MCP salvas

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 do servidor MCP configurado.
• 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 conseguem se conectar.
• probe conecta-se e relata as contagens de ferramentas, o suporte a recursos/prompts, o suporte a alterações na lista e os diagnósticos.
• add aceita flags de stdio, como --command, --arg, --env e --cwd, ou flags de HTTP, como --url, --transport, --header, --auth oauth, TLS, tempo limite e flags 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 dicas 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 *.
• 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. Os processos do Gateway ou de agentes em outro processo ainda precisam de seu próprio caminho de recarga ou reinicialização.
• Use transport: "streamable-http" para servidores MCP HTTP Streamable. openclaw mcp set também normaliza o type: "http" nativo da CLI para o mesmo formato de configuração canônico por 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 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. Os conjuntos de campos podem aumentar ao longo do 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 meio de 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 headers ou env que aparentam ser 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 app-server local do Codex.

Até que as credenciais estejam disponíveis, o OpenClaw omite apenas esse servidor MCP do runtime do agente, em vez de fazer a interação do agente falhar. O operador, ou um agente com acesso ao shell, pode então executar openclaw mcp login <name> e usar o servidor em uma interação posterior.

Quando um serviço MCP remoto já utiliza um perfil de autenticação separado do OpenClaw com capacidade de renovação, é possível definir opcionalmente oauth.authProfileId. O OpenClaw renova qualquer uma das fontes de credenciais antes da projeção no runtime e transmite apenas 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 de 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 no armazenamento de credenciais.

Transporte HTTP com streaming

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 grafia canônica. Os valores type: "http" nativos da CLI do MCP são aceitos quando salvos por meio de openclaw mcp set e corrigidos por openclaw doctor --fix em configurações existentes, 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 as contagens de servidores configurados, resumos de servidores habilitados, OAuth e 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 inventário rápido. Use openclaw mcp doctor --probe ou openclaw mcp probe quando precisar de comprovação ativa do servidor.

Fluxo de trabalho do operador:

1. Abra a interface de controle e escolha MCP.
2. Revise os cartões de resumo do total de servidores, servidores habilitados, OAuth e servidores filtrados.
3. Use cada linha de servidor para obter informações sobre 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 com escopo definido mcp para realizar alterações estruturais, como novos servidores, cabeçalhos, TLS, metadados OAuth ou filtros de ferramentas.
6. Escolha Salvar para apenas persistir a configuração ou Salvar e publicar para aplicá-la por meio do caminho de configuração do Gateway.
7. Execute openclaw mcp doctor --probe quando precisar de comprovação ativa de que o servidor editado inicia e lista ferramentas.

Observações:

• os trechos de comandos colocam os nomes dos servidores entre aspas para que nomes incomuns ainda possam ser copiados para um shell
• os 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
• os ambientes de execução ativos podem precisar de 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 MCP Apps estável. Os aplicativos exigem ativação 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 esta 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 nem 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 para o 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 outros conteúdos autenticados ou confidenciais.

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"],      },    },  },}

Comportamento e limites de 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 têm limite de 2 MiB, são colocados atrás de um proxy com 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.
• As ferramentas exclusivas de aplicativos (_meta.ui.visibility: ["app"]) permanecem fora das listas de ferramentas do modelo. Os aplicativos só podem chamar ferramentas visíveis a aplicativos em seu servidor proprietário que também atendam à política efetiva de ferramentas do OpenClaw para a execução que criou a visualização.
• As permissões de aplicativos vinculadas à origem, como câmera, microfone e geolocalização, não são concedidas enquanto os documentos internos dos aplicativos 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 na memória, limitada a dez minutos, e não são gravados em disco nem copiados para os metadados de pré-visualização da transcrição. A transcrição armazena somente um descritor limitado de servidor, ferramenta e recurso vinculado ao ID original da chamada de ferramenta. Após uma reinicialização do Gateway, a interface de controle pode verificar esse descritor em relação à transcrição da sessão autenticada e buscar novamente o recurso ui://; as visualizações reconstruídas permanecem somente leitura até que uma nova execução estabeleça as permissões atuais das ferramentas.
• openclaw security audit exibe 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 push genérico 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 se conecta a um único servidor remoto; ainda não há upstream multiplexado
• permissions_list_open inclui somente aprovações observadas enquanto a ponte está conectada

Relacionados

• Referência da CLI
• Plugins