Completados de chat de OpenAI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• POST /v1/chat/completions
• El mismo puerto que el Gateway (multiplexación WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

​

Autenticación

• autenticación con secreto compartido (gateway.auth.mode="token" o "password"): Authorization: Bearer <token-or-password>
• autenticación HTTP confiable con identidad (gateway.auth.mode="trusted-proxy"): enruta a través del proxy configurado con conocimiento de identidad y deja que inyecte los encabezados de identidad requeridos
• autenticación abierta de ingreso privado (gateway.auth.mode="none"): no se requiere encabezado de autenticación

• 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).
• Cuando gateway.auth.mode="trusted-proxy", la solicitud HTTP debe provenir de una fuente de proxy confiable configurada; los proxies de loopback del mismo host requieren gateway.auth.trustedProxy.allowLoopback = true explícito.
• 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)

• 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 se ejecutan a través de la misma ruta de agente de plano de control que las acciones de operador confiables.
• No hay un límite de herramientas separado de no propietario/por usuario en este endpoint; una vez que un llamador supera la autenticación del Gateway aquí, OpenClaw trata a ese llamador como un operador confiable para este gateway.
• Para los modos de autenticación con secreto compartido (token y password), el endpoint restaura los valores predeterminados normales de operador completo incluso si el llamador envía un encabezado x-openclaw-scopes más limitado.
• Los modos HTTP confiables con identidad (por ejemplo, autenticación de proxy confiable o gateway.auth.mode="none") respetan x-openclaw-scopes cuando está presente y, de lo contrario, recurren al conjunto de alcances predeterminado normal del operador.
• Si la política del agente de destino permite herramientas sensibles, este endpoint puede usarlas.
• Mantén este endpoint solo en loopback/tailnet/ingreso privado; no lo expongas directamente a Internet pública.

• gateway.auth.mode="token" o "password" + Authorization: Bearer ...
  • demuestra posesión del secreto compartido de operador del gateway
  • ignora x-openclaw-scopes más limitados
  • restaura el conjunto completo de alcances predeterminados de operador: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • trata los turnos de chat en este endpoint como turnos enviados por el propietario
• modos HTTP confiables con identidad (por ejemplo, autenticación de proxy confiable, o gateway.auth.mode="none" en ingreso privado)
  • autentican alguna identidad externa confiable o límite de despliegue
  • respetan x-openclaw-scopes cuando el encabezado está presente
  • recurren al conjunto de alcances predeterminado normal del operador cuando el encabezado está ausente
  • solo pierden semántica de propietario cuando el llamador limita explícitamente los alcances y omite operator.admin

​

Contrato de modelo centrado en agentes

• model: "openclaw" enruta al agente predeterminado configurado.
• model: "openclaw/default" también enruta al agente predeterminado configurado.
• model: "openclaw/<agentId>" enruta a un agente específico.

• x-openclaw-model: <provider/model-or-bare-id> sobrescribe el modelo de backend para el agente seleccionado.
• x-openclaw-agent-id: <agentId> sigue admitiéndose como sobrescritura de compatibilidad.
• x-openclaw-session-key: <sessionKey> controla completamente el enrutamiento de sesión.
• x-openclaw-message-channel: <channel> establece el contexto sintético de canal de ingreso para prompts y políticas con conocimiento de canal.

• model: "openclaw:<agentId>"
• model: "agent:<agentId>"

​

Habilitar el endpoint

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

​

Deshabilitar el endpoint

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

​

Comportamiento de sesión

​

Por qué importa esta superficie

• La mayoría de las configuraciones de Open WebUI, LobeChat y LibreChat esperan /v1/models.
• Muchos sistemas RAG esperan /v1/embeddings.
• Los clientes de chat existentes de OpenAI normalmente pueden empezar con /v1/chat/completions.
• Cada vez más clientes más nativos de agentes prefieren /v1/responses.

​

Lista de modelos y enrutamiento de agentes

​

Streaming (SSE)

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

​

Contrato de herramientas de chat

​

Campos de solicitud admitidos

• tools: array de { "type": "function", "function": { ... } }
• tool_choice: "auto", "none"
• turnos de seguimiento messages[*].role: "tool"
• messages[*].tool_call_id para vincular resultados de herramientas a una llamada de herramienta anterior
• max_completion_tokens: número; límite por llamada para el total de tokens de finalización (incluidos tokens de razonamiento). Nombre de campo actual de Chat Completions de OpenAI; se prefiere cuando se envían tanto max_completion_tokens como max_tokens.
• max_tokens: número; alias heredado aceptado por compatibilidad hacia atrás. Se ignora cuando max_completion_tokens también está presente.

​

Variantes no admitidas

• tools que no sean arrays
• entradas de herramientas que no sean función
• falta de tool.function.name
• variantes de tool_choice como allowed_tools y custom
• tool_choice: "required" (aún no se aplica en tiempo de ejecución; se admitirá cuando se implemente la aplicación estricta)
• tool_choice: { "type": "function", "function": { "name": "..." } } (misma justificación que required)
• valores de tool_choice.function.name que no coinciden con las tools proporcionadas

​

Forma de respuesta de herramientas sin streaming

• choices[0].finish_reason = "tool_calls"
• entradas choices[0].message.tool_calls[] con:
  • id
  • type: "function"
  • function.name
  • function.arguments (cadena JSON)

​

Forma de respuesta de herramientas con streaming

• delta inicial del rol de asistente
• deltas opcionales de comentario del asistente
• uno o más fragmentos delta.tool_calls que transportan identidad de herramienta y fragmentos de argumentos
• fragmento final con finish_reason: "tool_calls"
• data: [DONE]

​

Bucle de seguimiento de herramientas

• mensaje de llamada de herramienta anterior del asistente
• uno o más mensajes role: "tool" con tool_call_id coincidente

​

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 del Gateway
• Modelo: openclaw/default

• GET /v1/models debe listar openclaw/default
• Open WebUI debe usar openclaw/default como id del modelo de chat
• Si quieres un proveedor/modelo de backend específico para ese agente, establece el modelo predeterminado normal del agente o envía x-openclaw-model

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

• /v1/models devuelve destinos de agentes de OpenClaw, no catálogos de proveedores sin procesar.
• openclaw/default siempre está presente para que un identificador estable funcione en todos los entornos.
• Las sustituciones de proveedor/modelo del backend se definen en x-openclaw-model, no en el campo model de OpenAI.
• /v1/embeddings admite input como cadena o matriz de cadenas.

​

Relacionado

• Referencia de configuración
• OpenAI