Ferramentas invocam a API

• POST /tools/invoke
• Mesma porta que o Gateway (multiplexação de WS + HTTP): http://<gateway-host>:<port>/tools/invoke
• Tamanho máximo padrão do corpo da solicitação: 2 MB

​

Autenticação

• autenticação por segredo compartilhado (gateway.auth.mode="token" ou "password"): Authorization: Bearer <token-or-password>
• autenticação HTTP confiável com identidade (gateway.auth.mode="trusted-proxy"): encaminhe pelo proxy configurado com reconhecimento de identidade e permita que ele injete os cabeçalhos de identidade necessários
• autenticação aberta em entrada privada (gateway.auth.mode="none"): nenhum cabeçalho de autenticação é necessário

• mode="token" usa gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN).
• mode="password" usa gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" exige que a solicitação HTTP venha de uma origem de proxy confiável configurada; proxies local loopback no mesmo host exigem gateway.auth.trustedProxy.allowLoopback = true explicitamente.
• Chamadores internos no mesmo host que contornam o proxy podem usar gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD como alternativa direta local. Qualquer evidência dos cabeçalhos Forwarded, X-Forwarded-* ou X-Real-IP mantém a solicitação no caminho do proxy confiável.
• Se gateway.auth.rateLimit estiver configurado e ocorrerem muitas falhas de autenticação, o endpoint retornará 429 com Retry-After.

​

Limite de segurança (importante)

• A autenticação bearer HTTP aqui não é um modelo de escopo restrito por usuário.
• Um token/senha válido do Gateway para este endpoint deve ser tratado como uma credencial de proprietário/operador.
• Nos modos de autenticação por segredo compartilhado (token e password), o endpoint restaura os padrões normais de operador com acesso total, mesmo que o chamador envie um cabeçalho x-openclaw-scopes mais restrito.
• A autenticação por segredo compartilhado também trata invocações diretas de ferramentas neste endpoint como turnos enviados pelo proprietário.
• Os modos HTTP confiáveis com identidade (autenticação por proxy confiável ou gateway.auth.mode="none" em uma entrada privada) respeitam x-openclaw-scopes quando presente e, caso contrário, recorrem ao conjunto normal de escopos padrão do operador.
• Mantenha este endpoint apenas em local loopback, tailnet ou entrada privada; não o exponha diretamente à internet pública.

​

Corpo da solicitação

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}

• tool / name (string, obrigatório): nome da ferramenta a ser invocada. name tem precedência se ambos forem enviados.
• action (string, opcional): incorporado a args.action se o esquema da ferramenta aceitar uma propriedade action e args ainda não tiver definido uma.
• args (objeto, opcional): argumentos específicos da ferramenta.
• sessionKey (string, opcional): chave da sessão de destino. Se for omitida ou for "main", o Gateway usará a chave configurada da sessão principal (respeita session.mainKey e o agente padrão, ou global no escopo de sessão global).
• agentId (string, opcional): resolve a chave de sessão desse agente. Retorna erro 400 se houver conflito com um sessionKey explícito que já esteja associado a outro agente.
• idempotencyKey (string, opcional): usado para derivar um ID estável de chamada de ferramenta para a invocação.
• dryRun (booleano, opcional): reservado para uso futuro; atualmente ignorado.

​

Comportamento de política e roteamento

• tools.profile / tools.byProvider.profile
• tools.allow / tools.byProvider.allow
• agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
• políticas de grupo (se a chave da sessão estiver associada a um grupo ou canal)
• política de subagente (ao invocar com a chave de sessão de um subagente)

• As aprovações de execução são proteções operacionais, não um limite de autorização separado para este endpoint HTTP. Se uma ferramenta estiver acessível aqui por meio da autenticação do Gateway e da política de ferramentas, /tools/invoke não adicionará uma solicitação extra de aprovação por chamada.
• Se exec estiver acessível aqui, trate-o como uma interface de shell com capacidade de alteração. Negar write, edit, apply_patch ou ferramentas HTTP de gravação no sistema de arquivos não torna a execução do shell somente leitura.
• Não compartilhe credenciais bearer do Gateway com chamadores não confiáveis. Se precisar separar limites de confiança, execute gateways distintos (idealmente sob usuários ou hosts distintos do sistema operacional).

{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list for owner/admin callers
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (exemplo: slack, telegram)
• x-openclaw-account-id: <accountId> (quando existem várias contas)
• x-openclaw-message-to: <target> (destino de entrega para a política da ferramenta de mensagens)
• x-openclaw-thread-id: <threadId> (contexto da thread para a política da ferramenta de mensagens)

​

Respostas

​

Exemplo

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'

​

Relacionados

• Protocolo do Gateway
• Ferramentas e plugins