​

Ferramentas (OpenClaw)

​

Desabilitando ferramentas

{
  tools: { deny: ["browser"] },
}

• Correspondência é insensível a maiúsculas e minúsculas.
• Curingas * são suportados ("*" significa todas as ferramentas).
• Se tools.allow referenciar apenas nomes de ferramentas de plugin desconhecidos ou não carregados, o OpenClaw registra um aviso e ignora a allowlist para que as ferramentas principais continuem disponíveis.

​

Perfis de ferramentas (allowlist base)

• minimal: apenas session_status
• coding: group:fs, group:runtime, group:sessions, group:memory, image
• messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
• full: sem restrição (igual a não definido)

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

​

Política de ferramentas específica por provedor

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

​

Grupos de ferramentas (atalhos)

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:openclaw: todas as ferramentas integradas do OpenClaw (exclui plugins de provedores)

{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

​

Plugins + ferramentas

• Lobster: runtime de workflow tipado com aprovações retomáveis (requer a CLI do Lobster no host do Gateway).
• LLM Task: etapa de LLM somente em JSON para saída estruturada de workflow (validação de esquema opcional).

​

Inventário de ferramentas

​

apply_patch

​

exec

• command (obrigatório)
• yieldMs (vai para background automaticamente após timeout, padrão 10000)
• background (background imediato)
• timeout (segundos; encerra o processo se excedido, padrão 1800)
• elevated (bool; executa no host se o modo elevado estiver habilitado/permitido; só altera o comportamento quando o agente está em sandbox)
• host (sandbox | gateway | node)
• security (deny | allowlist | full)
• ask (off | on-miss | always)
• node (id/nome do node para host=node)
• Precisa de um TTY real? Defina pty: true.

• Retorna status: "running" com um sessionId quando em background.
• Use process para consultar/logar/escrever/encerrar/limpar sessões em background.
• Se process não for permitido, exec executa de forma síncrona e ignora yieldMs/background.
• elevated é controlado por tools.elevated mais qualquer substituição agents.list[].tools.elevated (ambos devem permitir) e é um alias para host=gateway + security=full.
• elevated só altera o comportamento quando o agente está em sandbox (caso contrário, não tem efeito).
• host=node pode direcionar para um aplicativo complementar do macOS ou um host de node headless (openclaw node run).
• aprovações e allowlists de gateway/node: Exec approvals.

​

process

• list, poll, log, write, kill, clear, remove

• poll retorna nova saída e status de saída quando concluído.
• log suporta offset/limit baseados em linhas (omita offset para pegar as últimas N linhas).
• process é por agente; sessões de outros agentes não são visíveis.

​

web_search

• query (obrigatório)
• count (1–10; padrão de tools.web.search.maxResults)

• Requer uma chave de API do Brave (recomendado: openclaw configure --section web, ou defina BRAVE_API_KEY).
• Habilite via tools.web.search.enabled.
• As respostas são armazenadas em cache (padrão 15 min).
• Veja Web tools para configuração.

​

web_fetch

• url (obrigatório)
• extractMode (markdown | text)
• maxChars (truncar páginas longas)

• Habilite via tools.web.fetch.enabled.
• maxChars é limitado por tools.web.fetch.maxCharsCap (padrão 50000).
• As respostas são armazenadas em cache (padrão 15 min).
• Para sites com muito JS, prefira a ferramenta de browser.
• Veja Web tools para configuração.
• Veja Firecrawl para o fallback anti-bot opcional.

​

browser

• status, start, stop, tabs, open, focus, close
• snapshot (aria/ai)
• screenshot (retorna bloco de imagem + MEDIA:<path>)
• act (ações de UI: click/type/press/hover/drag/select/fill/resize/wait/evaluate)
• navigate, console, pdf, upload, dialog

• profiles — listar todos os perfis de browser com status
• create-profile — criar novo perfil com porta alocada automaticamente (ou cdpUrl)
• delete-profile — parar o browser, excluir dados do usuário, remover da configuração (apenas local)
• reset-profile — encerrar processo órfão na porta do perfil (apenas local)

• profile (opcional; padrão browser.defaultProfile)
• target (sandbox | host | node)
• node (opcional; seleciona um id/nome de node específico) Notas:
• Requer browser.enabled=true (padrão é true; defina false para desabilitar).
• Todas as ações aceitam o parâmetro opcional profile para suporte a múltiplas instâncias.
• Quando profile é omitido, usa browser.defaultProfile (padrão “chrome”).
• Nomes de perfil: apenas alfanuméricos em minúsculas + hífens (máx. 64 caracteres).
• Faixa de portas: 18800–18899 (~100 perfis no máximo).
• Perfis remotos são apenas para anexar (sem start/stop/reset).
• Se um node com capacidade de browser estiver conectado, a ferramenta pode rotear automaticamente para ele (a menos que você fixe target).
• snapshot usa por padrão ai quando o Playwright está instalado; use aria para a árvore de acessibilidade.
• snapshot também suporta opções de snapshot por função (interactive, compact, depth, selector) que retornam refs como e12.
• act requer ref de snapshot (numérico 12 de snapshots de IA, ou e12 de snapshots por função); use evaluate para casos raros que exigem seletor CSS.
• Evite act → wait por padrão; use apenas em casos excepcionais (sem estado confiável de UI para aguardar).
• upload pode opcionalmente passar um ref para auto-clique após armar.
• upload também suporta inputRef (ref aria) ou element (seletor CSS) para definir <input type="file"> diretamente.

​

canvas

• present, hide, navigate, eval
• snapshot (retorna bloco de imagem + MEDIA:<path>)
• a2ui_push, a2ui_reset

• Usa node.invoke do gateway por baixo dos panos.
• Se nenhum node for fornecido, a ferramenta escolhe um padrão (um único node conectado ou node local do mac).
• A2UI é apenas v0.8 (sem createSurface); a CLI rejeita JSONL v0.9 com erros de linha.
• Teste rápido: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI".

​

nodes

• status, describe
• pending, approve, reject (pareamento)
• notify (macOS system.notify)
• run (macOS system.run)
• camera_snap, camera_clip, screen_record
• location_get

• Comandos de câmera/tela exigem que o app do node esteja em primeiro plano.
• Imagens retornam blocos de imagem + MEDIA:<path>.
• Vídeos retornam FILE:<path> (mp4).
• Localização retorna um payload JSON (lat/lon/precisão/timestamp).
• Parâmetros de run: array argv command; opcionais cwd, env (KEY=VAL), commandTimeoutMs, invokeTimeoutMs, needsScreenRecording.

{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

​

image

• image (caminho ou URL obrigatório)
• prompt (opcional; padrão “Describe the image.”)
• model (substituição opcional)
• maxBytesMb (limite opcional de tamanho)

• Disponível apenas quando agents.defaults.imageModel está configurado (primário ou fallbacks), ou quando um modelo de imagem implícito pode ser inferido a partir do seu modelo padrão + autenticação configurada (emparelhamento best-effort).
• Usa o modelo de imagem diretamente (independente do modelo principal de chat).

​

message

• send (texto + mídia opcional; MS Teams também suporta card para Adaptive Cards)
• poll (enquetes do WhatsApp/Discord/MS Teams)
• react / reactions / read / edit / delete
• pin / unpin / list-pins
• permissions
• thread-create / thread-list / thread-reply
• search
• sticker
• member-info / role-info
• emoji-list / emoji-upload / sticker-upload
• role-add / role-remove
• channel-info / channel-list
• voice-status
• event-list / event-create
• timeout / kick / ban

• send roteia o WhatsApp via o Gateway; outros canais vão direto.
• poll usa o Gateway para WhatsApp e MS Teams; enquetes do Discord vão direto.
• Quando uma chamada de ferramenta de mensagem está vinculada a uma sessão de chat ativa, os envios ficam restritos ao alvo dessa sessão para evitar vazamentos entre contextos.

​

cron

• status, list
• add, update, remove, run, runs
• wake (enfileirar evento do sistema + heartbeat imediato opcional)

• add espera um objeto completo de job de cron (mesmo esquema do RPC cron.add).
• update usa { jobId, patch } (id aceito por compatibilidade).

​

gateway

• restart (autoriza + envia SIGUSR1 para reinício em processo; reinício in-place openclaw gateway)
• config.get / config.schema
• config.apply (validar + gravar configuração + reiniciar + acordar)
• config.patch (mesclar atualização parcial + reiniciar + acordar)
• update.run (executar atualização + reiniciar + acordar)

• Use delayMs (padrão 2000) para evitar interromper uma resposta em andamento.
• restart é desabilitado por padrão; habilite com commands.restart: true.

​

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

• sessions_list: kinds?, limit?, activeMinutes?, messageLimit? (0 = nenhum)
• sessions_history: sessionKey (ou sessionId), limit?, includeTools?
• sessions_send: sessionKey (ou sessionId), message, timeoutSeconds? (0 = fire-and-forget)
• sessions_spawn: task, label?, agentId?, model?, runTimeoutSeconds?, cleanup?
• session_status: sessionKey? (padrão atual; aceita sessionId), model? (default limpa a substituição)

• main é a chave canônica de chat direto; global/desconhecido ficam ocultos.
• messageLimit > 0 busca as últimas N mensagens por sessão (mensagens de ferramenta filtradas).
• sessions_send aguarda a conclusão final quando timeoutSeconds > 0.
• A entrega/anúncio ocorre após a conclusão e é best-effort; status: "ok" confirma que a execução do agente terminou, não que o anúncio foi entregue.
• sessions_spawn inicia uma execução de subagente e publica uma resposta de anúncio de volta ao chat solicitante.
• sessions_spawn não bloqueia e retorna status: "accepted" imediatamente.
• sessions_send executa um ping‑pong de resposta (responda REPLY_SKIP para parar; máximo de turnos via session.agentToAgent.maxPingPongTurns, 0–5).
• Após o ping‑pong, o agente alvo executa uma etapa de anúncio; responda ANNOUNCE_SKIP para suprimir o anúncio.

​

agents_list

• O resultado é restrito às allowlists por agente (agents.list[].subagents.allowAgents).
• Quando ["*"] está configurado, a ferramenta inclui todos os agentes configurados e marca allowAny: true.

​

Parâmetros (comum)

• gatewayUrl (padrão ws://127.0.0.1:18789)
• gatewayToken (se a autenticação estiver habilitada)
• timeoutMs

• profile (opcional; padrão browser.defaultProfile)
• target (sandbox | host | node)
• node (opcional; fixar um id/nome de node específico)

​

Fluxos recomendados do agente

1. browser → status / start
2. snapshot (ai ou aria)
3. act (click/type/press)
4. screenshot se precisar de confirmação visual

1. canvas → present
2. a2ui_push (opcional)
3. snapshot

1. nodes → status
2. describe no node escolhido
3. notify / run / camera_snap / screen_record

​

Segurança

• Evite system.run direto; use nodes → run apenas com consentimento explícito do usuário.
• Respeite o consentimento do usuário para captura de câmera/tela.
• Use status/describe para garantir permissões antes de invocar comandos de mídia.

​

Como as ferramentas são apresentadas ao agente

1. Texto do prompt do sistema: uma lista legível por humanos + orientação.
2. Esquema da ferramenta: as definições estruturadas de função enviadas à API do modelo.