Saltar al contenido principal

​
Invocación de Herramientas (HTTP)

El Gateway de OpenClaw expone un endpoint HTTP sencillo para invocar una sola herramienta directamente. Siempre está habilitado, pero está protegido por la autenticación del Gateway y la política de herramientas.
  • POST /tools/invoke
  • Mismo puerto que el Gateway (multiplexación WS + HTTP): http://<gateway-host>:<port>/tools/invoke
El tamaño máximo de carga útil predeterminado es de 2 MB.

​
Autenticación

Usa la configuración de autenticación del Gateway. Envíe un token bearer:
  • Authorization: Bearer <token>
Notas:
  • Cuando gateway.auth.mode="token", use gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN).
  • Cuando gateway.auth.mode="password", use gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
  • Si gateway.auth.rateLimit está configurado y se producen demasiados fallos de autenticación, el endpoint devuelve 429 con Retry-After.

​
Cuerpo de la solicitud

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
Campos:
  • tool (string, requerido): nombre de la herramienta a invocar.
  • action (string, opcional): se asigna a args si el esquema de la herramienta admite action y la carga útil de args lo omitió.
  • args (object, opcional): argumentos específicos de la herramienta.
  • sessionKey (string, opcional): clave de sesión de destino. Si se omite o es "main", el Gateway usa la clave de sesión principal configurada (respeta session.mainKey y el agente predeterminado, o global en el ámbito global).
  • dryRun (boolean, opcional): reservado para uso futuro; actualmente se ignora.

​
Política + comportamiento de enrutamiento

La disponibilidad de herramientas se filtra mediante la misma cadena de políticas utilizada por los agentes del Gateway:
  • tools.profile / tools.byProvider.profile
  • tools.allow / tools.byProvider.allow
  • agents.<id>.tools.allow / agents.<id>.tools.byProvider.allow
  • políticas de grupo (si la clave de sesión se asigna a un grupo o canal)
  • política de subagente (al invocar con una clave de sesión de subagente)
Si una herramienta no está permitida por la política, el endpoint devuelve 404. Gateway HTTP también aplica una lista de denegación estricta por defecto (incluso si la política de sesión permite la herramienta):
  • sessions_spawn
  • sessions_send
  • gateway
  • whatsapp_login
Puede personalizar esta lista de denegación mediante gateway.tools: 
{
  gateway: {
    tools: {
      // Herramientas adicionales para bloquear a través de HTTP /tools/invoke
      deny: ["browser"],
      // Eliminar herramientas de la lista de denegación predeterminada
      allow: ["gateway"],
    },
  },
}
Para ayudar a que las políticas de grupo resuelvan el contexto, puede establecer opcionalmente:
  • x-openclaw-message-channel: <channel> (ejemplo: slack, telegram)
  • x-openclaw-account-id: <accountId> (cuando existen múltiples cuentas)

​
Respuestas

  • 200 → { ok: true, result }
  • 400 → { ok: false, error: { type, message } } (solicitud inválida o error de la herramienta)
  • 401 → no autorizado
  • 429 → autenticación limitada por tasa (Retry-After establecido)
  • 404 → herramienta no disponible (no encontrada o no en la lista de permitidos)
  • 405 → método no permitido
  • 500 → { ok: false, error: { type, message } } (error inesperado en la ejecución de la herramienta; mensaje saneado)

​
Ejemplo

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