Completaciones de chat de OpenAI

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

Una vez habilitada, ofrece todos estos endpoints 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.

Habilitar el 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 se ejecutan mediante 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 local loopback, tailnet o una entrada privada. No lo exponga a Internet público.

Matriz de autenticación:

Consulte Ámbitos del 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 llamadores del mismo host que omitan el proxy en un gateway trusted-proxy pueden recurrir directamente a gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD. Cualquier indicio en los encabezados Forwarded, X-Forwarded-* o X-Real-IP hace que la solicitud permanezca 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 usar este endpoint

• Prefiera esta opción en lugar de añadir un nuevo canal integrado cuando su integración sea simplemente otra interfaz de operador o cliente para el mismo gateway.
• Para clientes móviles nativos que se conectan directamente a un gateway remoto, prefiera WebChat o el protocolo del Gateway con el flujo de arranque del dispositivo emparejado y token del 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 el agente

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

Encabezados opcionales de la solicitud:

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

/v1/embeddings utiliza los mismos identificadores de model de destino de agente. Envíe x-openclaw-model (desde un llamador con secreto compartido o uno con identidad y operator.admin) para elegir 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 para cada hilo de conversación; evite identificadores de nivel de cuenta, salvo que quiera que varias conversaciones o dispositivos compartan una misma sesión de OpenClaw. Utilice x-openclaw-session-key solo cuando necesite un control explícito del enrutamiento entre varios clientes o hilos, con claves propiedad de la aplicación que eviten los espacios de nombres reservados indicados anteriormente.

Límites de las solicitudes (configuración)

Los valores predeterminados pueden ajustarse en gateway.http.endpoints.chatCompletions:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          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 cuando se omiten:

Las fuentes HEIC/HEIF de image_url se aceptan y normalizan a JPEG antes de enviarse 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 necesitan compatibilidad con códecs externos.

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

Contrato de herramientas de chat

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

Campos de solicitud admitidos

Todos los campos de muestreo y límite de tokens utilizan el mismo canal de parámetros de transmisión 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 del protocolo: 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 los 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 del lado del 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 admitidas

Devuelve 400 invalid_request_error en los siguientes casos:

• tools no es una matriz, hay entradas de herramientas que no son funciones o falta tool.function.name
• variantes de tool_choice como allowed_tools y custom
• valores de tool_choice.function.name que no coinciden con una herramienta proporcionada

Para tool_choice: "required" y tool_choice fijado a una función, el endpoint restringe el conjunto expuesto de herramientas de función del cliente, indica al entorno de ejecución que llame a una herramienta del cliente antes de responder y genera un error si la respuesta del agente no contiene una 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.

Formato de respuesta de herramientas sin transmisión

Cuando el agente llama a herramientas, la respuesta utiliza:

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

Formato de respuesta de herramientas con transmisión

Cuando stream: true, las llamadas a herramientas llegan como fragmentos SSE incrementales: un delta inicial del rol del asistente, deltas opcionales de comentarios del asistente, uno o más fragmentos 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 de llamada a herramientas del asistente, además de uno o más mensajes con role: "tool" y un tool_call_id coincidente. Esto continúa el mismo bucle de razonamiento del agente para generar la respuesta final.

Transmisión (SSE)

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

• Content-Type: text/event-stream
• Cada línea de evento tiene el formato data: <json>
• La transmisión 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: su token de portador del Gateway
• Modelo: openclaw/default

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

Prueba rápida de funcionamiento:

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":"Summarize my tasks for today"}]  }'

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

Sin transmisió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",    "messages": [{"role":"user","content":"hi"}]  }'

Con transmisión:

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

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 incrustaciones:

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 una cadena o una matriz de cadenas.

Contenido relacionado

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