Las herramientas invocan la API

• POST /tools/invoke
• Mismo puerto que el Gateway (multiplexación de WS + HTTP): http://<gateway-host>:<port>/tools/invoke
• Tamaño máximo predeterminado del cuerpo de la solicitud: 2 MB

​

Autenticación

• autenticación mediante secreto compartido (gateway.auth.mode="token" o "password"): Authorization: Bearer <token-or-password>
• autenticación HTTP de confianza con identidad (gateway.auth.mode="trusted-proxy"): enrute mediante el proxy configurado con reconocimiento de identidad y permita que este inyecte los encabezados de identidad necesarios
• autenticación abierta de entrada privada (gateway.auth.mode="none"): no se requiere ningún encabezado de autenticación

• mode="token" utiliza gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN).
• mode="password" utiliza gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
• mode="trusted-proxy" requiere que la solicitud HTTP proceda de un origen de proxy de confianza configurado; los proxies de bucle invertido del mismo host requieren gateway.auth.trustedProxy.allowLoopback = true explícito.
• Los llamadores internos del mismo host que omiten el proxy pueden utilizar gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD como alternativa directa local. Cualquier evidencia de los encabezados Forwarded, X-Forwarded-* o X-Real-IP mantiene la solicitud en la ruta del proxy de confianza.
• Si se configura gateway.auth.rateLimit y se producen demasiados fallos de autenticación, el endpoint devuelve 429 con Retry-After.

​

Límite de seguridad (importante)

• Aquí, la autenticación de portador HTTP no es un modelo de ámbitos restringidos por usuario.
• Un token o una contraseña válidos del Gateway para este endpoint deben tratarse como una credencial de propietario u operador.
• En los modos de autenticación mediante secreto compartido (token y password), el endpoint restablece los valores predeterminados normales de operador completo incluso si el llamador envía un encabezado x-openclaw-scopes más restringido.
• La autenticación mediante secreto compartido también trata las invocaciones directas de herramientas en este endpoint como turnos enviados por el propietario.
• Los modos HTTP de confianza con identidad (autenticación mediante proxy de confianza o gateway.auth.mode="none" en una entrada privada) respetan x-openclaw-scopes cuando está presente y, de lo contrario, recurren al conjunto normal de ámbitos predeterminados del operador.
• Mantenga este endpoint únicamente en el bucle invertido, la red de Tailscale o una entrada privada; no lo exponga directamente a la Internet pública.

​

Cuerpo de la solicitud

{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}

• tool / name (cadena, obligatorio): nombre de la herramienta que se invocará. name tiene prioridad si se envían ambos.
• action (cadena, opcional): se combina con args.action si el esquema de la herramienta admite una propiedad action y args todavía no ha establecido ninguna.
• args (objeto, opcional): argumentos específicos de la herramienta.
• sessionKey (cadena, opcional): clave de la sesión de destino. Si se omite o es "main", el Gateway utiliza la clave de sesión principal configurada (respeta session.mainKey y el agente predeterminado, o global en el ámbito de sesión global).
• agentId (cadena, opcional): resuelve la clave de sesión de ese agente. Produce un error con 400 si entra en conflicto con un sessionKey explícito que ya está asignado a otro agente.
• idempotencyKey (cadena, opcional): se utiliza para derivar un identificador estable de llamada a herramienta para la invocación.
• dryRun (booleano, opcional): reservado para uso futuro; actualmente se ignora.

​

Comportamiento de políticas y enrutamiento

• 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 corresponde a un grupo o canal)
• política de subagentes (cuando se invoca con una clave de sesión de subagente)

• Las aprobaciones de ejecución son mecanismos de protección para el operador, no un límite de autorización independiente para este endpoint HTTP. Si se puede acceder a una herramienta desde aquí mediante la autenticación del Gateway y la política de herramientas, /tools/invoke no añade una solicitud adicional de aprobación por llamada.
• Si se puede acceder a exec desde aquí, trátelo como una superficie de shell con capacidad de modificación. Denegar write, edit, apply_patch o las herramientas HTTP de escritura en el sistema de archivos no hace que la ejecución del shell sea de solo lectura.
• No comparta las credenciales de portador del Gateway con llamadores que no sean de confianza. Si necesita separar distintos límites de confianza, ejecute gateways independientes (preferiblemente con distintos usuarios o hosts del sistema operativo).

{
  gateway: {
    tools: {
      // Herramientas adicionales que se bloquearán mediante HTTP /tools/invoke
      deny: ["browser"],
      // Eliminar herramientas de la lista de denegación predeterminada para llamadores propietarios o administradores
      allow: ["gateway"],
    },
  },
}

• x-openclaw-message-channel: <channel> (ejemplo: slack, telegram)
• x-openclaw-account-id: <accountId> (cuando existen varias cuentas)
• x-openclaw-message-to: <target> (destino de entrega para la política de herramientas de mensajería)
• x-openclaw-thread-id: <threadId> (contexto del hilo para la política de herramientas de mensajería)

​

Respuestas

​

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

​

Contenido relacionado

• Protocolo del Gateway
• Herramientas y plugins