MCP

• 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

​

Escolha o caminho MCP correto

​

OpenClaw como um servidor MCP

​

Quando usar serve

• 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

​

Como funciona

​

Escolha um modo de cliente

​

O que serve expõe

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

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

​

Ferramentas da ponte

​

Modelo de eventos

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

​

Notificações do canal do Claude

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

• 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

​

Configuração do cliente MCP

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

​

Opções

​

Limite de segurança e confiança

• 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

​

Testes

pnpm test:docker:mcp-channels

​

Solução de problemas

​

OpenClaw como um registro de clientes MCP

​

Definições de servidores MCP salvas

• 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>

• 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.

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

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-memory
openclaw 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.example
openclaw 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

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

{
  "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

​

Transporte SSE/HTTP

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

​

Fluxo de trabalho OAuth

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

openclaw mcp logout docs

​

Transporte HTTP com streaming

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

​

Interface de controle

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.

• 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

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

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

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

• 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

• 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