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

# API de Invocação de Ferramentas

# Invocação de Ferramentas (HTTP)

O Gateway do OpenClaw expõe um endpoint HTTP simples para invocar diretamente uma única ferramenta. Ele está sempre habilitado, mas é controlado pela autenticação do Gateway e pela política de ferramentas.

* `POST /tools/invoke`
* Mesma porta do Gateway (multiplexação 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. Envie um token bearer:

* `Authorization: Bearer <token>`

Notas:

* 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`).
* Se `gateway.auth.rateLimit` estiver configurado e ocorrerem muitas falhas de autenticação, o endpoint retorna `429` com `Retry-After`.

## Corpo da requisiçã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 suportar `action` e o payload de `args` o omitir.
* `args` (object, opcional): argumentos específicos da ferramenta.
* `sessionKey` (string, opcional): chave de sessão de destino. Se omitida 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 das 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**.

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

* `sessions_spawn`
* `sessions_send`
* `gateway`
* `whatsapp_login`

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    tools: {
      // Ferramentas adicionais para bloquear via HTTP /tools/invoke
      deny: ["browser"],
      // Remover ferramentas da lista de negação padrão
      allow: ["gateway"],
    },
  },
}
```

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

* `x-openclaw-message-channel: <channel>` (exemplo: `slack`, `telegram`)
* `x-openclaw-account-id: <accountId>` (quando existem múltiplas contas)

## Respostas

* `200` → `{ ok: true, result }`
* `400` → `{ ok: false, error: { type, message } }` (requisição inválida ou erro da ferramenta)
* `401` → não autorizado
* `429` → autenticação limitada por taxa (`Retry-After` definido)
* `404` → ferramenta não disponível (não encontrada ou não permitida pela lista de permissões)
* `405` → método não permitido
* `500` → `{ ok: false, error: { type, message } }` (erro inesperado na 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 YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'
```