Completions de chat de OpenAI

​

Habilitar el endpoint

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

​

Límite de seguridad (importante)

• Un token/contraseña de Gateway válido para este endpoint equivale a una credencial de propietario/operador, no a un alcance estrecho por usuario.
• Las solicitudes pasan por la misma ruta de agente del plano de control que las acciones de operador de confianza, por lo que, si la política del agente de destino permite herramientas sensibles, este endpoint puede usarlas.
• Mantenlo solo en loopback/tailnet/entrada privada. No lo expongas a la internet pública.

​

Autenticación

• Los llamadores del mismo host que omiten 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 de 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

• Prefiere esto antes que añadir un nuevo canal integrado cuando tu integración sea solo otra superficie de operador/cliente para el mismo gateway.
• Para clientes móviles nativos que se conectan directamente a un gateway remoto, prefiere WebChat o el Protocolo de Gateway con el flujo de arranque de dispositivo emparejado/token de dispositivo, para que el dispositivo no necesite un token/contraseña HTTP compartido.
• En su lugar, crea un plugin de canal cuando integres una red de mensajería externa con sus propios usuarios, salas, entrega por webhook o transporte saliente. Consulta Crear plugins.

​

Contrato de modelo centrado en agentes

​

Comportamiento de sesión

​

Límites de solicitud (configuración)

{
  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,
          },
        },
      },
    },
  },
}

​

Contrato de herramientas de chat

​

Campos de solicitud admitidos

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

​

Variantes no admitidas

• tools que no sea un array, entradas de herramientas que no sean de función, o falta de 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

​

Forma de respuesta de herramienta sin streaming

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

​

Forma de respuesta de herramienta con streaming

​

Bucle de seguimiento de herramientas

​

Streaming (SSE)

• Content-Type: text/event-stream
• Cada línea de evento es data: <json>
• El stream 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: tu token bearer de Gateway
• Modelo: openclaw/default

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

​

Ejemplos

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

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

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

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

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

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

​

Relacionado

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