--- read_when: - Conectando Codex, Claude Code ou outro cliente MCP a canais baseados no OpenClaw - Executando `openclaw mcp serve` - Gerenciando definições de servidor MCP salvas pelo OpenClaw sidebarTitle: MCP summary: Exponha conversas de canais do OpenClaw via MCP e gerencie definições salvas de servidores MCP title: MCP x-i18n: generated_at: "2026-06-30T22:09:34Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: e979654cb17f5cb25b936039f9e4690ecfda41bc58ae073426a9e42978fa85dc source_path: cli/mcp.md workflow: 16 --- `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 `list`, `show`, `set` e `unset` apenas leem e gravam entradas `mcp.servers` gerenciadas pelo OpenClaw na configuração do OpenClaw. Elas não incluem servidores mcporter de `config/mcporter.json`; use `mcporter list` para esse registro. Use [`openclaw acp`](/pt-BR/cli/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. | Objetivo | Use | Por quê | | ------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Permitir que um cliente MCP externo leia/envie conversas de canais do OpenClaw | `openclaw mcp serve` | O OpenClaw é o servidor MCP e expõe conversas baseadas no Gateway por stdio. | | Salvar servidores MCP de terceiros para execuções de agentes gerenciadas pelo OpenClaw | `openclaw mcp add`, `set`, `configure`, `tools`, `login` | O OpenClaw é o registro do lado cliente MCP e depois projeta esses servidores em ambientes de execução elegíveis. | | Verificar um servidor salvo sem executar uma rodada de agente | `openclaw mcp status`, `doctor`, `probe` | `status` e `doctor` inspecionam a configuração; `probe` abre uma conexão MCP ativa e lista capacidades. | | Editar configuração MCP de um navegador | Control UI `/mcp` | A página mostra inventário, ativação, resumos de OAuth/filtros, dicas de comando e um editor `mcp` com escopo. | | Dar ao servidor de aplicativo Codex um servidor MCP nativo com escopo | `mcp.servers..codex` | O bloco `codex` afeta apenas a projeção de threads do servidor de aplicativo Codex e é removido antes da entrega da configuração nativa. | | Executar sessões de harness hospedadas por ACP | [`openclaw acp`](/pt-BR/cli/acp) e [Agentes ACP](/pt-BR/tools/acp-agents-setup) | O modo de ponte ACP não aceita injeção de servidor MCP por sessão; configure pontes de gateway/plugin em vez disso. | Se você não tem certeza de qual caminho precisa, comece com `openclaw mcp status --verbose`. Ele mostra o que o OpenClaw salvou sem iniciar nenhum servidor MCP. ## 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`](/pt-BR/cli/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. O cliente MCP inicia `openclaw mcp serve`. A ponte se conecta ao Gateway OpenClaw por WebSocket. Sessões roteadas viram conversas MCP e ferramentas de transcrição/histórico. Eventos ativos são enfileirados em memória enquanto a ponte está conectada. Se o modo de canal Claude estiver ativado, a mesma sessão também poderá receber notificações push específicas do Claude. - o estado da fila ativa começa quando a ponte se conecta - o histórico de transcrição mais antigo é lido com `messages_read` - notificações push do Claude só existem enquanto a sessão MCP está ativa - quando o cliente se desconecta, a ponte encerra e a fila ativa desaparece - pontos de entrada de agente de execução única, como `openclaw agent` e `openclaw infer model run`, encerram quaisquer ambientes de execução MCP incluídos que eles abrem quando a resposta é concluída, então execuções roteirizadas repetidas não acumulam processos filhos MCP stdio - servidores MCP stdio iniciados pelo OpenClaw (incluídos ou configurados pelo usuário) são encerrados como uma árvore de processos no desligamento, então subprocessos filhos iniciados pelo servidor não sobrevivem depois que o cliente stdio pai sai - excluir ou redefinir uma sessão descarta os clientes MCP dessa sessão pelo caminho compartilhado de limpeza de runtime, então não há conexões stdio remanescentes vinculadas a uma sessão removida ### Escolha um modo de cliente Use a mesma ponte de duas maneiras diferentes: Apenas ferramentas MCP padrão. Use `conversations_list`, `messages_read`, `events_poll`, `events_wait`, `messages_send` e as ferramentas de aprovação. Ferramentas MCP padrão mais o adaptador de canal específico do Claude. Ative `--claude-channel-mode on` ou deixe o padrão `auto`. Hoje, `auto` se comporta igual a `on`. Ainda não há detecção de capacidade do cliente. ### 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 ```bash openclaw mcp serve ``` ```bash openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token ``` ```bash openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password ``` ```bash openclaw mcp serve --verbose openclaw mcp serve --claude-channel-mode off ``` ### Ferramentas da ponte A ponte atual expõe estas ferramentas MCP: Lista conversas recentes baseadas em sessões que já têm metadados de rota no estado de sessão do Gateway. Filtros úteis: - `limit` - `search` - `channel` - `includeDerivedTitles` - `includeLastMessage` Retorna uma conversa por `session_key` usando uma consulta direta de sessão do Gateway. Lê mensagens de transcrição recentes para uma conversa baseada em sessão. Extrai blocos de conteúdo de mensagem que não são texto de uma mensagem de transcrição. Esta é uma visualização de metadados sobre o conteúdo da transcrição, não um armazenamento autônomo e durável de blobs de anexo. Lê eventos ativos enfileirados desde um cursor numérico. Faz long-polling até que o próximo evento enfileirado correspondente chegue ou um tempo limite expire. Use isto quando um cliente MCP genérico precisa de entrega quase em tempo real sem um protocolo push específico do Claude. Envia texto de volta pela mesma rota já registrada na sessão. Comportamento atual: - exige uma rota de conversa existente - usa o canal, destinatário, id da conta e id da thread da sessão - envia apenas texto Lista solicitações pendentes de aprovação de exec/plugin que a ponte observou desde que se conectou ao Gateway. Resolve uma solicitação pendente de aprovação de exec/plugin com: - `allow-once` - `allow-always` - `deny` ### 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` - a fila é apenas ativa; ela começa quando a ponte MCP inicia - `events_poll` e `events_wait` não reproduzem histórico antigo do Gateway por conta própria - o backlog durável deve ser lido com `messages_read` ### 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. `--claude-channel-mode off`: apenas ferramentas MCP padrão. `--claude-channel-mode on`: ativa notificações de canal do Claude. `--claude-channel-mode auto`: padrão atual; mesmo comportamento de ponte que `on`. 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: ```json { "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: URL WebSocket do Gateway. Token do Gateway. Ler token do arquivo. Senha do Gateway. Ler senha do arquivo. Modo de notificação do Claude. Logs detalhados em stderr. Prefira `--token-file` ou `--password-file` em vez de segredos inline quando possível. ### 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: ```bash 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](/pt-BR/help/testing). ### Solução de problemas Geralmente significa que a sessão do Gateway ainda não é roteável. Confirme que a sessão subjacente tem metadados de rota armazenados de canal/provedor, destinatário e conta/thread opcional. Esperado. A fila live começa quando a ponte se conecta. Leia o histórico de transcrições mais antigo com `messages_read`. Verifique todos estes pontos: - o cliente manteve a sessão MCP stdio aberta - `--claude-channel-mode` é `on` ou `auto` - o cliente realmente entende os métodos de notificação específicos do Claude - a mensagem de entrada aconteceu depois que a ponte se conectou `permissions_list_open` mostra apenas solicitações de aprovação observadas enquanto a ponte estava conectada. Não é uma API durável de histórico de aprovações. ## 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. - estes comandos apenas leem ou gravam a configuração do OpenClaw - `status`, `list`, `show`, `doctor` sem `--probe`, `set`, `configure`, `tools`, `logout`, `reload` e `unset` não se conectam ao servidor MCP de destino - `login` executa o fluxo de rede OAuth do MCP para o servidor HTTP configurado e salva as credenciais locais resultantes - `status --verbose` imprime dicas resolvidas de transporte, autenticação, timeout, filtro e chamadas paralelas de ferramentas sem se conectar - `doctor` verifica definições salvas em busca de problemas de configuração local, como comandos stdio ausentes, diretórios de trabalho inválidos, arquivos TLS ausentes, servidores desabilitados, valores literais sensíveis em cabeçalhos/env e autorização OAuth incompleta - `doctor --probe` adiciona a mesma prova de conexão live que `probe` depois que as verificações estáticas passam - `probe` conecta ao servidor selecionado ou a todos os servidores configurados, lista ferramentas e relata capacidades/diagnósticos - `add` cria uma definição a partir de flags e faz probe antes de salvar, a menos que `--no-probe` esteja definido ou a autorização OAuth seja necessária primeiro - os adaptadores de runtime decidem quais formatos de transporte eles realmente suportam no momento da execução - `enabled: false` mantém um servidor salvo, mas o exclui da descoberta de runtime incorporado - `timeout` e `connectTimeout` definem timeouts de solicitação e conexão por servidor em segundos - `supportsParallelToolCalls: true` marca servidores que os adaptadores podem chamar simultaneamente - servidores HTTP podem usar cabeçalhos estáticos, login OAuth, controle de verificação TLS e caminhos de certificado/chave mTLS - o OpenClaw incorporado expõe ferramentas MCP configuradas nos perfis de ferramenta normais `coding` e `messaging`; `minimal` ainda as oculta, e `tools.deny: ["bundle-mcp"]` as desabilita explicitamente - `toolFilter.include` e `toolFilter.exclude` por servidor filtram ferramentas MCP descobertas antes que elas se tornem ferramentas do OpenClaw - servidores que anunciam recursos ou prompts também expõem ferramentas utilitárias para listar/ler recursos e listar/buscar prompts; esses nomes utilitários gerados (`resources_list`, `resources_read`, `prompts_list`, `prompts_get`) usam o mesmo filtro include/exclude - alterações dinâmicas na lista de ferramentas MCP invalidam o catálogo em cache dessa sessão; a próxima descoberta/uso atualiza a partir do servidor - falhas repetidas de solicitação/protocolo de ferramentas MCP pausam esse servidor brevemente para que um servidor quebrado não consuma todo o turno - runtimes MCP empacotados com escopo de sessão são recolhidos depois de `mcp.sessionIdleTtlMs` milissegundos de ociosidade (padrão de 10 minutos; defina `0` para desabilitar), e execuções incorporadas one-shot os limpam ao final da execução 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 [flags]` - `openclaw mcp set ` - `openclaw mcp configure [flags]` - `openclaw mcp tools [--include csv] [--exclude csv] [--clear]` - `openclaw mcp login [--code code]` - `openclaw mcp logout ` - `openclaw mcp reload` - `openclaw mcp unset ` 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: ```bash openclaw mcp list openclaw mcp show context7 --json openclaw mcp status --verbose openclaw mcp doctor --probe openclaw mcp probe context7 --json openclaw mcp add memory --command npx --arg -y --arg @modelcontextprotocol/server-memory openclaw 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 docs openclaw mcp logout docs openclaw 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. ```bash 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 ``` Restrinja servidores de sistema de arquivos à menor árvore de diretórios que o agente deve ler ou editar. ```bash openclaw mcp add memory \ --command npx \ --arg -y \ --arg @modelcontextprotocol/server-memory openclaw mcp probe memory --json ``` Use um filtro de ferramentas se o servidor expuser ferramentas de escrita que não devem ficar disponíveis para agentes normais. ```bash openclaw mcp add local-tools \ --command node \ --arg ./dist/mcp-server.js \ --cwd /srv/openclaw-tools \ --env API_BASE=https://internal.example openclaw mcp status --verbose ``` `doctor` verifica se `cwd` existe e se o comando resolve a partir do ambiente configurado. ```bash 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 ``` Use OAuth quando o servidor remoto oferecer suporte a ele. Se o servidor exigir cabeçalhos estáticos, evite fazer commit de tokens bearer literais. ```bash 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 ``` Servidores de controle direto do desktop herdam as permissões do processo que eles iniciam. Use filtros de ferramenta restritos e prompts de permissão em nível de SO. ### 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. ```json { "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 } ] } ``` ```json { "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" } ] } ] } ``` `doctor --json` sai com código diferente de zero quando qualquer servidor habilitado verificado tem um erro. Avisos são relatados, mas não fazem o comando falhar por si só. ```json { "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": [] } ``` `probe` abre uma sessão ativa de cliente MCP. Use-o para prova de acessibilidade e capacidade, não para auditorias de configuração estática. Exemplo de formato de configuração: ```json { "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. | Campo | Descrição | | -------------------------- | -------------------------------------- | | `command` | Executável a iniciar (obrigatório) | | `args` | Array de argumentos de linha de comando | | `env` | Variáveis de ambiente extras | | `cwd` / `workingDirectory` | Diretório de trabalho para o processo | **Filtro de segurança de env do stdio** OpenClaw rejeita chaves de env de inicialização de interpretador que podem alterar como um servidor MCP stdio é iniciado antes do primeiro RPC, mesmo que elas apareçam no bloco `env` de um servidor. Chaves bloqueadas incluem `BASHOPTS`, `FPATH`, `KSH_ENV`, `NODE_OPTIONS`, `NODE_REDIRECT_WARNINGS`, `NODE_REPL_EXTERNAL_MODULE`, `NODE_REPL_HISTORY`, `NODE_V8_COVERAGE`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4`, `TCLLIBPATH` e variáveis semelhantes de controle de runtime. A inicialização rejeita essas chaves com um erro de configuração para que elas não possam injetar um prelúdio implícito, trocar o interpretador, habilitar um depurador ou redirecionar a saída de runtime contra o processo stdio. Variáveis de credenciais, proxy e específicas do servidor comuns (`GITHUB_TOKEN`, `HTTP_PROXY`, `*_API_KEY` personalizadas etc.) não são afetadas. Se o seu servidor MCP realmente precisar de uma das variáveis bloqueadas, defina-a no processo host do Gateway em vez de sob o `env` do servidor stdio. ### Transporte SSE / HTTP Conecta-se a um servidor MCP remoto por HTTP Server-Sent Events. | Campo | Descrição | | ------------------------------ | ---------------------------------------------------------------- | | `url` | URL HTTP ou HTTPS do servidor remoto (obrigatório) | | `headers` | Mapa chave-valor opcional de cabeçalhos HTTP (por exemplo, tokens de autenticação) | | `connectionTimeoutMs` | Tempo limite de conexão por servidor em ms (opcional) | | `connectTimeout` | Tempo limite de conexão por servidor em segundos (opcional) | | `timeout` / `requestTimeoutMs` | Tempo limite de solicitação MCP por servidor em segundos ou ms | | `auth: "oauth"` | Usa armazenamento de token OAuth do MCP e `openclaw mcp login` | | `sslVerify` | Defina como false apenas para endpoints HTTPS privados explicitamente confiáveis | | `clientCert` / `clientKey` | Caminhos do certificado e da chave de cliente mTLS | | `supportsParallelToolCalls` | Indica que chamadas simultâneas são seguras para este servidor | Exemplo: ```json { "mcp": { "servers": { "remote-tools": { "url": "https://mcp.example.com", "auth": "oauth", "timeout": 20, "headers": { "Authorization": "Bearer " } } } } } ``` 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. Adicione ou atualize o servidor com `auth: "oauth"` e quaisquer metadados opcionais de OAuth. ```bash openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}' ``` Execute o login para criar a solicitação de autorização. ```bash openclaw mcp login docs ``` OpenClaw imprime a URL de autorização e armazena o estado temporário do verificador OAuth no diretório de estado do OpenClaw. Depois de aprovar no navegador, passe o código retornado de volta para o OpenClaw. ```bash openclaw mcp login docs --code abc123 ``` Use status ou doctor para confirmar que os tokens estão presentes. ```bash openclaw mcp status --verbose openclaw mcp doctor docs --probe ``` Logout remove credenciais OAuth armazenadas, mas mantém a definição de servidor salva. ```bash openclaw mcp logout docs ``` Se o provedor rotacionar tokens ou o estado de autorização ficar travado, execute `openclaw mcp logout ` 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. | Campo | Descrição | | ------------------------------ | ------------------------------------------------------------------------------------ | | `url` | URL HTTP ou HTTPS do servidor remoto (obrigatório) | | `transport` | Defina como `"streamable-http"` para selecionar este transporte; quando omitido, OpenClaw usa `sse` | | `headers` | Mapa chave-valor opcional de cabeçalhos HTTP (por exemplo, tokens de autenticação) | | `connectionTimeoutMs` | Tempo limite de conexão por servidor em ms (opcional) | | `connectTimeout` | Tempo limite de conexão por servidor em segundos (opcional) | | `timeout` / `requestTimeoutMs` | Tempo limite de solicitação MCP por servidor em segundos ou ms | | `auth: "oauth"` | Usa armazenamento de token OAuth do MCP e `openclaw mcp login` | | `sslVerify` | Defina como false apenas para endpoints HTTPS privados explicitamente confiáveis | | `clientCert` / `clientKey` | Caminhos do certificado e da chave de cliente mTLS | | `supportsParallelToolCalls` | Indica que chamadas simultâneas são seguras para este servidor | 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: ```json { "mcp": { "servers": { "streaming-tools": { "url": "https://mcp.example.com/stream", "transport": "streamable-http", "connectTimeout": 10, "timeout": 30, "headers": { "Authorization": "Bearer " } } } } } ``` Comandos de registro não iniciam a ponte de canal. Apenas `probe` e `doctor --probe` abrem uma sessão ativa de cliente MCP para provar que o servidor de destino está acessível. ## 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](/pt-BR/cli) - [Plugins](/pt-BR/cli/plugins)