La API HTTP compatible con OpenAI de OpenClaw

Cualquier cosa que hable el protocolo OpenAI Chat Completions puede comunicarse con un agente de OpenClaw, porque el gateway sirve una pequeña superficie compatible en el mismo puerto que su WebSocket. Está desactivada por defecto, equivale a acceso de operador completo cuando está activada, y su campo model significa algo distinto de lo que cree tu cliente. Este es el contrato tal como lo describe la documentación.

Qué sirve y en quién confía

• Una vez activado gateway.http.endpoints.chatCompletions, el gateway sirve POST /v1/chat/completions, GET /v1/models, GET sobre un id de modelo individual y POST /v1/embeddings en el puerto del gateway; el endpoint responses se activa por separado, y cada solicitud se ejecuta como una ejecución normal de agente del gateway por la misma ruta de código que el comando agent, así que el enrutamiento, los permisos y la configuración coinciden con los de tu gateway.
• Un token o una contraseña de gateway válidos para este endpoint equivalen a una credencial de propietario u operador, no a un scope por usuario: la autenticación bearer con secreto compartido ignora cualquier encabezado x-openclaw-scopes, restaura el conjunto completo de scopes de operador por defecto y trata los turnos de chat como turnos de un remitente propietario; un trusted-proxy o un ingress privado sin autenticación respeta x-openclaw-scopes cuando está presente y necesita operator.admin para los controles de nivel propietario.
• La autenticación sigue el modo del gateway: token bearer o contraseña desde la configuración o la variable de entorno, un proxy con reconocimiento de identidad en modo trusted-proxy (los proxies loopback en el mismo host necesitan allowLoopback), o ningún encabezado en un ingress privado; los clientes del mismo host que eluden un proxy de confianza pueden recurrir a la contraseña, salvo que la evidencia de los encabezados reenviados los mantenga en la ruta del proxy, y demasiados intentos fallidos devuelven 429 con Retry-After cuando hay un límite de frecuencia configurado.
• La documentación prefiere este endpoint a un nuevo canal integrado cuando la integración es solo otra superficie de operador, prefiere WebChat o el protocolo del gateway con el flujo de dispositivo emparejado para los clientes móviles nativos, de modo que ningún token compartido viaje en el dispositivo, y un plugin de canal cuando se integra una red de mensajería externa con sus propios usuarios, salas y transporte.

OpenClaw trata el campo model de OpenAI como un destino de agente, no como un id bruto de modelo de proveedor.

Los modelos son agentes, las sesiones salen de user

openclaw y openclaw/default enrutan al agente predeterminado configurado, openclaw/ seguido del id del agente o agent: seguido de él enrutan a un agente concreto, y /v1/models enumera esos destinos de agente, no modelos de proveedor ni subagentes. El encabezado x-openclaw-model sobrescribe el modelo de backend del agente seleccionado, directamente para los clientes con secreto compartido y solo con operator.admin para los que llevan identidad; x-openclaw-session-key enruta de forma explícita y se rechaza con un 400 cuando usa un espacio de nombres reservado como subagent, cron o acp; x-openclaw-message-channel define un canal de entrada sintético para los prompts que tienen en cuenta el canal. Por defecto, cada solicitud es sin estado y lleva una clave de sesión nueva; una cadena user de OpenAI deriva una clave estable para que las llamadas repetidas compartan una sesión, así que reutiliza un valor por hilo de conversación y evita los identificadores a nivel de cuenta, salvo que varios dispositivos deban compartir una sesión. Continuar explícitamente una sesión de incógnito requiere operator.admin efectivo, y la respuesta respaldada por el perfil oculta el destino tras un error forbidden de tipo no encontrado.

Herramientas, límites y streaming

• Se admiten las herramientas de función y tool_choice (auto, none, required o una función fijada), con mensajes de seguimiento con rol tool vinculados por tool_call_id; max_completion_tokens es el límite actual, con max_tokens como alias heredado, y temperature, top_p, las penalizaciones, seed y hasta cuatro secuencias stop se validan y luego se reenvían en la medida de lo posible, con los nombres que viajan por la red elegidos por el transporte del proveedor.
• Las solicitudes están limitadas a 20 MB de cuerpo, 8 partes image_url del último mensaje del usuario y 20 MB de datos de imagen decodificados; las imágenes procedentes de una URL se rechazan salvo que images.allowUrl esté activado, con una lista de hosts permitidos, tipos MIME permitidos, 10 MB por imagen, 3 redirecciones y un tiempo de espera de 10 s por defecto, HEIC y HEIF normalizados a JPEG, y un nombre de host de la lista de permitidos nunca elude el bloqueo de IP privadas.
• Con stream en true, los eventos llegan como líneas data que terminan en DONE, las llamadas a herramientas como fragmentos delta incrementales seguidos de un motivo de finalización tool_calls, y un fragmento de uso cuando include_usage está definido; una ejecución fallida devuelve un error en lugar de una completion, un fallo durante el streaming emite un objeto error y luego DONE, y un cliente que se desconecta cancela las descargas de origen y la ejecución del agente.

La API de OpenClaw es el artículo más amplio sobre la API del gateway, y los scopes de operador de OpenClaw explica el conjunto de scopes de operador que este endpoint restaura o restringe.

La receta de Open WebUI

La configuración rápida consiste en una URL base con el host y el puerto del gateway más /v1 (host.docker.internal desde Docker en macOS), el token bearer del gateway como clave de API y openclaw/default como modelo; si un curl a /v1/models con el bearer devuelve openclaw/default, la mayoría de las instalaciones de Open WebUI se conectan con la misma URL base y el mismo token. Después, los ejemplos muestran una sesión estable con un valor user con el prefijo conv, una llamada en streaming con x-openclaw-model fijando un modelo de proveedor, la obtención de un solo modelo con la barra codificada en la URL, y embeddings con un modelo de embeddings en el encabezado y un entero dimensions opcional que sobrescribe la dimensionalidad de salida de la memoria del agente. El acceso remoto a OpenClaw cubre cómo llegar al puerto de forma segura y los controles de seguridad del gateway de OpenClaw, los controles que lo protegen.

En Diali

En Diali, el gateway está detrás del ingress de la plataforma, con la configuración de ejecución generada desde el panel, así que exponer esta superficie es una decisión de configuración y no un puerto que abrir. OpenClaw alojado en Diali describe el asistente alojado y la página de precios de Diali, los planes en los que se incluye.

• Desactivada por defecto; activada, un token es acceso de propietario.
• El campo model nombra un agente; user nombra la sesión.
• Loopback, tailnet o ingress privado, nunca la internet pública.