Invoca herramientas OpenClaw vía HTTP: Guía de integración

¿Alguna vez has necesitado ejecutar una herramienta específica de tu Gateway sin tener que pasar por todo el flujo de un agente? A veces, lo único que quieres es una respuesta rápida a través de una petición HTTP directa, sin complicaciones innecesarias ni esperas.

El Gateway de OpenClaw expone un endpoint HTTP sencillo para invocar una sola herramienta directamente. Siempre está habilitado y utiliza la autenticación del Gateway junto con la política de herramientas. Al igual que la superficie /v1/* compatible con OpenAI, la autenticación bearer de secreto compartido se trata como acceso de operador confiable para todo el Gateway.

• 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 por defecto es de 2 MB.

Autenticación

Usa la configuración de autenticación del Gateway. Envía un bearer token:

• Authorization: Bearer <token>

Notas:

• Cuando gateway.auth.mode="token", usa gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN).
• Cuando gateway.auth.mode="password", usa gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
• Si gateway.auth.rateLimit está configurado y ocurren demasiados fallos de autenticación, el endpoint devuelve 429 con Retry-After.

Límite de seguridad (importante)

Trata este endpoint como una superficie de acceso total de operador para la instancia del Gateway.

• La autenticación bearer HTTP aquí no es un modelo de alcance limitado por usuario.
• Un token o contraseña de Gateway válido para este endpoint debe tratarse como una credencial de propietario u operador.
• Para los modos de autenticación de secreto compartido (token y password), el endpoint restaura los valores predeterminados de operador completo, incluso si quien llama envía una cabecera x-openclaw-scopes más restringida.
• La autenticación de secreto compartido también trata las invocaciones directas de herramientas en este endpoint como turnos del propietario-emisor.
• Los modos HTTP confiables que portan identidad (por ejemplo, autenticación por proxy confiable o gateway.auth.mode="none" en un ingress privado) siguen respetando los alcances de operador declarados en la solicitud.
• Mantén este endpoint solo en loopback/tailnet/ingress privado; no lo expongas directamente a la internet pública.

Matriz de autenticación:

• gateway.auth.mode="token" o "password" + Authorization: Bearer ...
  • demuestra la posesión del secreto compartido del operador del Gateway
  • ignora cabeceras x-openclaw-scopes más restringidas
  • restaura el conjunto de alcances de operador predeterminado completo
  • trata las invocaciones directas de herramientas en este endpoint como turnos del propietario-emisor
• modos HTTP confiables que portan identidad (por ejemplo, autenticación por proxy confiable, o gateway.auth.mode="none" en ingress privado)
  • autentican alguna identidad externa confiable o límite de despliegue
  • respetan la cabecera x-openclaw-scopes declarada
  • solo obtienen semántica de propietario cuando operator.admin está presente en esos alcances declarados

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 mapea en args si el esquema de la herramienta admite action y la carga útil de args lo omitió.
• args (objeto, 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 por defecto, o global en el alcance global).
• dryRun (boolean, opcional): reservado para uso futuro; actualmente se ignora.

Comportamiento de políticas y enrutamiento

La disponibilidad de las herramientas se filtra a través de la misma cadena de políticas que usan 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 mapea a un grupo o canal)
• política de subagente (cuando se invoca con una clave de sesión de subagente)

Si una política no permite una herramienta, el endpoint devuelve 404.

Notas importantes sobre los límites:

• Las aprobaciones de ejecución son protecciones para el operador, no un límite de autorización separado para este endpoint HTTP. Si una herramienta es accesible aquí mediante la autenticación del Gateway y la política de herramientas, /tools/invoke no añade una solicitud de aprobación extra por llamada.
• No compartas las credenciales bearer del Gateway con usuarios no confiables. Si necesitas separación entre límites de confianza, ejecuta Gateways separados (e idealmente usuarios de SO o hosts separados).

El HTTP del Gateway también aplica una lista de denegación estricta por defecto (incluso si la política de sesión permite la herramienta):

• exec — ejecución directa de comandos (superficie de RCE)
• spawn — creación arbitraria de procesos hijos (superficie de RCE)
• shell — ejecución de comandos de shell (superficie de RCE)
• fs_write — mutación arbitraria de archivos en el host
• fs_delete — eliminación arbitraria de archivos en el host
• fs_move — mover o renombrar archivos arbitrarios en el host
• apply_patch — la aplicación de parches puede sobrescribir archivos arbitrarios
• sessions_spawn — orquestación de sesiones; generar agentes de forma remota es RCE
• sessions_send — inyección de mensajes entre sesiones
• cron — plano de control de automatización persistente
• gateway — plano de control del Gateway; evita la reconfiguración vía HTTP
• nodes — el relé de comandos de nodo puede alcanzar system.run en hosts vinculados
• whatsapp_login — configuración interactiva que requiere escaneo de QR en terminal; se bloquea en HTTP

Puedes personalizar esta lista de denegación mediante gateway.tools:

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

Para ayudar a que las políticas de grupo resuelvan el contexto, puedes configurar 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 entrada de la herramienta)
• 401 → no autorizado
• 429 → límite de tasa de autenticación alcanzado (se establece Retry-After)
• 404 → herramienta no disponible (no encontrada o no permitida en la lista)
• 405 → método no permitido
• 500 → { ok: false, error: { type, message } } (error inesperado en la ejecución de la herramienta; mensaje sanitizado)

Ejemplo

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

Siguientes pasos

• Configura tus políticas de herramientas para controlar el acceso.
• Revisa la documentación de autenticación del Gateway para asegurar tu instancia.

AI Setup Assistant