Completado de chat de OpenAI

El Gateway puede ofrecer una pequeña interfaz de Chat Completions compatible con OpenAI. Está deshabilitada de forma predeterminada.

Una vez habilitada, ofrece todo lo siguiente en el mismo puerto que el Gateway (multiplexación de WS + HTTP):

Las solicitudes se ejecutan como una ejecución normal de un agente del Gateway (la misma ruta de código que openclaw agent), por lo que el enrutamiento, los permisos y la configuración coinciden con los del Gateway.

Habilitación del endpoint

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

Establezca enabled: false (u omítalo) para deshabilitarlo.

Límite de seguridad (importante)

Trate este endpoint como acceso completo de operador a la instancia del Gateway:

• Un token o una contraseña válidos del Gateway para este endpoint equivalen a una credencial de propietario u operador, no a un ámbito limitado por usuario.
• Las solicitudes pasan por la misma ruta de agente del plano de control que las acciones de operadores de confianza, por lo que, si la política del agente de destino permite herramientas sensibles, este endpoint puede utilizarlas.
• Manténgalo únicamente en la interfaz de bucle invertido, la tailnet o una entrada privada. No lo exponga a la Internet pública.

Matriz de autenticación:

Consulte Ámbitos de operador, Seguridad y Acceso remoto.

Autenticación

Utiliza la configuración de autenticación del Gateway (consulte Autenticación mediante proxy de confianza para obtener información detallada sobre ese modo):

Notas:

• Los autores de llamadas del mismo host que omitan el proxy en un Gateway trusted-proxy pueden recurrir directamente a gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Cualquier evidencia de encabezado Forwarded, X-Forwarded-* o X-Real-IP mantiene la solicitud en la ruta del proxy de confianza.
• Si gateway.auth.rateLimit está configurado y fallan demasiados intentos de autenticación, el endpoint devuelve 429 con un encabezado Retry-After.

Cuándo utilizar este endpoint

• Prefiera este endpoint en lugar de añadir un nuevo canal integrado cuando la integración sea simplemente otra interfaz de operador o cliente para el mismo Gateway.
• Para clientes móviles nativos que se conecten directamente a un Gateway remoto, prefiera WebChat o el Protocolo del Gateway con el flujo de arranque de dispositivos emparejados y tokens de dispositivo, para que el dispositivo no necesite un token o una contraseña HTTP compartidos.
• En su lugar, cree un plugin de canal cuando integre una red de mensajería externa con sus propios usuarios, salas, entrega mediante Webhook o transporte de salida. Consulte Creación de plugins.

Contrato de modelo centrado en agentes

OpenClaw trata el campo model de OpenAI como un destino de agente, no como un identificador de modelo de proveedor sin procesar.

Encabezados de solicitud opcionales:

/v1/models enumera destinos de agente de nivel superior (openclaw, openclaw/default, openclaw/<agentId>), no modelos de proveedores de backend ni subagentes; los subagentes permanecen como topología interna de ejecución. Si se omite x-openclaw-model, el agente seleccionado se ejecuta con su modelo configurado habitual.

/v1/embeddings utiliza los mismos identificadores model de destino de agente. Envíe x-openclaw-model (desde un autor de llamada con secreto compartido o uno con identidad y operator.admin) para seleccionar un modelo de embeddings específico; de lo contrario, la solicitud utiliza la configuración habitual de embeddings del agente seleccionado.

Comportamiento de las sesiones

De forma predeterminada, el endpoint no conserva estado entre solicitudes (se genera una nueva clave de sesión en cada llamada).

Si la solicitud incluye una cadena user de OpenAI, el Gateway deriva de ella una clave de sesión estable para que las llamadas repetidas puedan compartir una sesión de agente. En aplicaciones personalizadas, reutilice el mismo valor de user en cada hilo de conversación; evite los identificadores de nivel de cuenta, salvo que se desee que varias conversaciones o dispositivos compartan una misma sesión de OpenClaw. Utilice x-openclaw-session-key únicamente cuando necesite controlar explícitamente el enrutamiento entre varios clientes o hilos, con claves administradas por la aplicación que eviten los espacios de nombres reservados anteriores.

Límites de las solicitudes

El endpoint utiliza límites integrados de 20 MB por cuerpo de solicitud, 8 partes de image_url del último mensaje del usuario y 20 MB de datos de imagen decodificados acumulados. La política de fuentes de imágenes sigue siendo configurable en gateway.http.endpoints.chatCompletions.images:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

Valores predeterminados de la configuración de imágenes:

Las fuentes image_url HEIC/HEIF se aceptan y normalizan a JPEG antes de entregarlas al proveedor mediante el procesador de imágenes compartido de OpenClaw (Rastermill), que recurre a un conversor del sistema (sips, ImageMagick, GraphicsMagick o ffmpeg) para los formatos que requieren compatibilidad con códecs externos.

Nota de seguridad: incluir un nombre de host en la lista de permitidos no evita el bloqueo de direcciones IP privadas o internas. Para Gateways expuestos a Internet, aplique controles de salida de red además de las protecciones de la aplicación. Consulte Seguridad.

Contrato de herramientas de chat

/v1/chat/completions admite un subconjunto de herramientas de función compatible con clientes comunes de Chat de OpenAI.

Campos de solicitud compatibles

Todos los campos de muestreo y límite de tokens utilizan el mismo canal de parámetros de flujo del agente y se reenvían en la medida de lo posible:

• Límite de tokens: el transporte del proveedor elige el nombre del campo en la transmisión: max_completion_tokens para los endpoints de la familia OpenAI y max_tokens para los proveedores que solo aceptan el nombre heredado (Mistral, Chutes).
• stop se asigna al campo de detención del transporte: stop para backends de Chat Completions y stop_sequences para Anthropic. La API Responses de OpenAI no tiene ningún parámetro de detención, por lo que stop no se aplica a los modelos respaldados por Responses.
• El backend Codex Responses basado en ChatGPT utiliza un muestreo fijo en el servidor y elimina temperature/top_p (junto con max_output_tokens, metadata, prompt_cache_retention y service_tier) antes de que la solicitud llegue a dicho backend.

Variantes no compatibles

Devuelve 400 invalid_request_error para:

• tools que no sean matrices, entradas de herramientas que no sean funciones o ausencia de tool.function.name
• variantes de tool_choice, como allowed_tools y custom
• valores de tool_choice.function.name que no coincidan con una herramienta proporcionada

Para tool_choice: "required" y tool_choice fijado a una función, el endpoint restringe el conjunto de herramientas de función del cliente expuesto, indica al runtime que llame a una herramienta del cliente antes de responder y genera un error si la respuesta del agente no contiene ninguna llamada estructurada coincidente a una herramienta del cliente. Esto se aplica a la lista HTTP tools proporcionada por quien realiza la llamada, no a todas las herramientas internas del agente de OpenClaw.

Estructura de la respuesta de herramienta sin streaming

Cuando el agente llama a herramientas, la respuesta utiliza:

• choices[0].finish_reason = "tool_calls"
• entradas de choices[0].message.tool_calls[] con id, type: "function", function.name y function.arguments (cadena JSON)
• Comentario del asistente anterior a la llamada a la herramienta, en choices[0].message.content (posiblemente vacío)

Estructura de la respuesta de herramienta con streaming

Cuando stream: true, las llamadas a herramientas llegan como fragmentos SSE incrementales: un delta inicial del rol de asistente, deltas opcionales de comentarios del asistente, uno o más fragmentos de delta.tool_calls que contienen la identidad de la herramienta y fragmentos de argumentos y, después, un fragmento final con finish_reason: "tool_calls" y data: [DONE].

Si stream_options.include_usage=true, se emite un fragmento final de uso antes de [DONE].

Bucle de seguimiento de herramientas

Después de recibir tool_calls, ejecute las funciones solicitadas y envíe una solicitud de seguimiento que incluya el mensaje anterior del asistente con la llamada a la herramienta y uno o más mensajes role: "tool" con un tool_call_id coincidente. Esto continúa el mismo bucle de razonamiento del agente para generar la respuesta final.

Streaming (SSE)

Establezca stream: true para recibir eventos enviados por el servidor:

• Content-Type: text/event-stream
• Cada línea de evento es data: <json>
• El flujo termina con data: [DONE]

Configuración rápida de Open WebUI

• URL base: http://127.0.0.1:18789/v1
• URL base de Docker en macOS: http://host.docker.internal:18789/v1
• Clave de API: el token de portador del Gateway
• Modelo: openclaw/default

Comportamiento esperado: GET /v1/models enumera openclaw/default y Open WebUI lo utiliza como id. del modelo de chat. Para un proveedor o modelo de backend específico, establezca el modelo predeterminado habitual del agente o envíe x-openclaw-model (llamante con secreto compartido o llamante con identidad y operator.admin).

Prueba rápida de humo:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Si devuelve openclaw/default, la mayoría de las configuraciones de Open WebUI pueden conectarse con la misma URL base y el mismo token.

Ejemplos

Sesión estable para una conversación de una aplicación:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Resume mis tareas para hoy"}]  }'

Reutilice el mismo valor de user en llamadas posteriores de esa conversación para continuar la misma sesión del agente.

Sin streaming:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"hola"}]  }'

Con streaming:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"hola"}]  }'

Enumerar modelos:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

Obtener un modelo:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

Crear embeddings:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings admite input como cadena o matriz de cadenas.

Contenido relacionado

• Referencia de configuración
• Ámbitos del operador
• OpenAI