> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de invocação de ferramentas

O Gateway do OpenClaw expõe um endpoint HTTP simples para invocar uma única ferramenta diretamente. Ele está sempre habilitado e usa a autenticação do Gateway mais a política de ferramentas. Assim como a superfície compatível com OpenAI `/v1/*`, a autenticação bearer com segredo compartilhado é tratada como acesso confiável de operador para todo o gateway.

* `POST /tools/invoke`
* Mesma porta do Gateway (multiplex WS + HTTP): `http://<gateway-host>:<port>/tools/invoke`

O tamanho máximo padrão do payload é 2 MB.

## Autenticação

Usa a configuração de autenticação do Gateway.

Caminhos comuns de autenticação HTTP:

* 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"`):
  roteie pelo proxy configurado com reconhecimento de identidade e deixe-o injetar os
  cabeçalhos de identidade exigidos
* autenticação aberta em ingresso privado (`gateway.auth.mode="none"`):
  nenhum cabeçalho de autenticação é necessário

Observações:

* Quando `gateway.auth.mode="token"`, use `gateway.auth.token` (ou `OPENCLAW_GATEWAY_TOKEN`).
* Quando `gateway.auth.mode="password"`, use `gateway.auth.password` (ou `OPENCLAW_GATEWAY_PASSWORD`).
* Quando `gateway.auth.mode="trusted-proxy"`, a solicitação HTTP deve vir de uma
  origem de proxy confiável configurada; proxies de local loopback no mesmo host exigem
  `gateway.auth.trustedProxy.allowLoopback = true` explicitamente.
* Chamadores internos no mesmo host que ignoram o proxy podem usar
  `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` como fallback local direto.
  Qualquer evidência de cabeçalho `Forwarded`, `X-Forwarded-*` ou `X-Real-IP`
  mantém a solicitação no caminho de trusted-proxy.
* Se `gateway.auth.rateLimit` estiver configurado e ocorrerem muitas falhas de autenticação, o endpoint retorna `429` com `Retry-After`.

## Limite de segurança (importante)

Trate este endpoint como uma superfície de **acesso total de operador** para a instância do gateway.

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

Matriz de autenticação:

* `gateway.auth.mode="token"` ou `"password"` + `Authorization: Bearer ...`
  * comprova a posse do segredo compartilhado de operador do gateway
  * ignora `x-openclaw-scopes` mais estreitos
  * restaura o conjunto completo de escopos padrão do operador:
    `operator.admin`, `operator.approvals`, `operator.pairing`,
    `operator.read`, `operator.talk.secrets`, `operator.write`
  * trata invocações diretas de ferramenta neste endpoint como turnos de remetente proprietário
* modos HTTP confiáveis com identidade (por exemplo, autenticação por proxy confiável ou `gateway.auth.mode="none"` em ingresso privado)
  * autenticam alguma identidade confiável externa ou limite de implantação
  * respeitam `x-openclaw-scopes` quando o cabeçalho está presente
  * retornam ao conjunto normal de escopos padrão do operador quando o cabeçalho está ausente
  * só perdem a semântica de proprietário quando o chamador estreita explicitamente os escopos e omite `operator.admin`

## Corpo da solicitação

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
```

Campos:

* `tool` (string, obrigatório): nome da ferramenta a invocar.
* `action` (string, opcional): mapeado para args se o esquema da ferramenta oferecer suporte a `action` e o payload de args o omitir.
* `args` (object, opcional): argumentos específicos da ferramenta.
* `sessionKey` (string, opcional): chave da sessão de destino. Se omitido ou `"main"`, o Gateway usa a chave de sessão principal configurada (respeita `session.mainKey` e o agente padrão, ou `global` no escopo global).
* `dryRun` (boolean, opcional): reservado para uso futuro; atualmente ignorado.

## Política + comportamento de roteamento

A disponibilidade de ferramentas é filtrada pela mesma cadeia de políticas usada pelos agentes do Gateway:

* `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 de sessão mapear para um grupo ou canal)
* política de subagente (ao invocar com uma chave de sessão de subagente)

Se uma ferramenta não for permitida pela política, o endpoint retorna **404**.

Observações importantes de limite:

* Aprovações de exec são proteções de operador, não um limite de autorização separado para este endpoint HTTP. Se uma ferramenta estiver acessível aqui por autenticação do Gateway + política de ferramentas, `/tools/invoke` não adiciona um prompt extra de aprovação por chamada.
* Se `exec` estiver acessível aqui, trate-o como uma superfície mutável de shell. Negar `write`, `edit`, `apply_patch` ou ferramentas HTTP de escrita no sistema de arquivos não torna a execução de shell somente leitura.
* Não compartilhe credenciais bearer do Gateway com chamadores não confiáveis. Se você precisar de separação entre limites de confiança, execute gateways separados (e idealmente usuários/hosts de SO separados).

O HTTP do Gateway também aplica uma lista de negação rígida por padrão (mesmo que a política de sessão permita a ferramenta):

* `exec` - execução direta de comandos (superfície de RCE)
* `spawn` - criação arbitrária de processo filho (superfície de RCE)
* `shell` - execução de comando de shell (superfície de RCE)
* `fs_write` - mutação arbitrária de arquivos no host
* `fs_delete` - exclusão arbitrária de arquivos no host
* `fs_move` - movimentação/renomeação arbitrária de arquivos no host
* `apply_patch` - aplicação de patch pode reescrever arquivos arbitrários
* `sessions_spawn` - orquestração de sessões; gerar agentes remotamente é RCE
* `sessions_send` - injeção de mensagens entre sessões
* `cron` - plano de controle de automação persistente
* `gateway` - plano de controle do gateway; impede reconfiguração via HTTP
* `nodes` - retransmissão de comandos de nó pode alcançar system.run em hosts pareados
* `whatsapp_login` - configuração interativa que exige leitura de QR no terminal; trava em HTTP

Você pode personalizar esta lista de negação via `gateway.tools`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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"],
    },
  },
}
```

`gateway.tools.allow` é uma substituição de exposição, não uma elevação de escopo. Em
modos HTTP com identidade, `cron`, `gateway` e `nodes` permanecem indisponíveis
para chamadores que não têm identidade de proprietário/admin (`operator.admin`), mesmo quando
estão listados em `gateway.tools.allow`. A autenticação bearer por segredo compartilhado ainda segue
a regra de operador confiável total acima.

Para ajudar políticas de grupo a resolver contexto, você pode definir opcionalmente:

* `x-openclaw-message-channel: <channel>` (exemplo: `slack`, `telegram`)
* `x-openclaw-account-id: <accountId>` (quando existem várias contas)

## Respostas

* `200` → `{ ok: true, result }`
* `400` → `{ ok: false, error: { type, message } }` (solicitação inválida ou erro de entrada da ferramenta)
* `401` → não autorizado
* `429` → autenticação limitada por taxa (`Retry-After` definido)
* `404` → ferramenta indisponível (não encontrada ou não incluída na allowlist)
* `405` → método não permitido
* `500` → `{ ok: false, error: { type, message } }` (erro inesperado de execução da ferramenta; mensagem sanitizada)

## Exemplo

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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": {}
  }'
```

## Relacionado

* [Protocolo do Gateway](/pt-BR/gateway/protocol)
* [Ferramentas e plugins](/pt-BR/tools)