OpenAI Chat Completions (HTTP)

El Gateway de OpenClaw puede servir un pequeño endpoint de Chat Completions compatible con OpenAI.

Este endpoint está deshabilitado por defecto. Habilítalo primero en la configuración.

POST /v1/chat/completions
Mismo puerto que el Gateway (multiplexado WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

Internamente, las solicitudes se ejecutan como una ejecución normal del agente del Gateway (mismo flujo de código que openclaw agent), por lo que el enrutamiento, permisos y configuración coinciden con tu Gateway.

Autenticación

Usa la configuración de autenticación del Gateway. Envía un token bearer:

Authorization: Bearer <token>

Notas:

Cuando gateway.auth.mode="token", usa gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN).
Cuando gateway.auth.mode="password", usa gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
Si gateway.auth.rateLimit está configurado y ocurren demasiados fallos de autenticación, el endpoint devuelve 429 con Retry-After.

Límite de seguridad (importante)

Trata este endpoint como una superficie de acceso completo de operador para la instancia del gateway.

La autenticación bearer HTTP aquí no es un modelo de alcance limitado por usuario.
Un token/contraseña válido del Gateway para este endpoint debe tratarse como una credencial de propietario/operador.
Las solicitudes pasan por el mismo flujo del agente del plano de control que las acciones de operador de confianza.
No existe un límite separado de herramientas por usuario en este endpoint; una vez que un llamador pasa la autenticación del Gateway aquí, OpenClaw lo trata como un operador de confianza para este gateway.
Si la política del agente objetivo permite herramientas sensibles, este endpoint puede usarlas.
Mantén este endpoint solo en loopback/tailnet/ingreso privado; no lo expongas directamente a internet público.

Consulta Seguridad y Acceso remoto.

Elegir un agente

No se requieren headers personalizados: codifica el id del agente en el campo model de OpenAI:

model: "openclaw:<agentId>" (ejemplo: "openclaw:main", "openclaw:beta")
model: "agent:<agentId>" (alias)

O apunta a un agente específico de OpenClaw mediante header:

x-openclaw-agent-id: <agentId> (por defecto: main)

Avanzado:

x-openclaw-session-key: <sessionKey> para controlar completamente el enrutamiento de sesión.

Habilitar el endpoint

Establece gateway.http.endpoints.chatCompletions.enabled a true:

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

Deshabilitar el endpoint

Establece gateway.http.endpoints.chatCompletions.enabled a false:

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

Comportamiento de sesión

Por defecto el endpoint es sin estado por solicitud (se genera una nueva clave de sesión en cada llamada).

Si la solicitud incluye un string user de OpenAI, el Gateway deriva una clave de sesión estable a partir de él, para que las llamadas repetidas puedan compartir una sesión de agente.

Streaming (SSE)

Establece stream: true para recibir Server-Sent Events (SSE):

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

Ejemplos

Sin streaming:

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

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-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'