Cómo usar el endpoint de Chat Completions en OpenClaw

Integrar diferentes agentes en tus aplicaciones suele obligarte a aprender nuevas estructuras de datos o SDKs específicos. Es molesto tener que cambiar todo tu código cuando ya tienes una implementación que funciona con el estándar de OpenAI y solo quieres conectar tus herramientas actuales.

Si buscas una forma directa de comunicarte con tus agentes usando peticiones HTTP estándar sin añadir complejidad innecesaria, habilitar este endpoint es la mejor opción.

Requisitos previos

• Gateway de OpenClaw instalado.
• Token o password de autenticación configurado.

Inicio rápido

El Gateway de OpenClaw puede servir un endpoint de Chat Completions compatible con OpenAI, pero está desactivado por defecto.

1. Habilita el endpoint

Modifica tu archivo de configuración y establece gateway.http.endpoints.chatCompletions.enabled en true:

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

2. Autenticación

El endpoint usa la misma configuración de autenticación que tu Gateway. Debes enviar un bearer token en el header:

• Si usas gateway.auth.mode="token", envía el gateway.auth.token.
• Si usas gateway.auth.mode="password", envía el gateway.auth.password.

3. Elige un agente

Puedes definir a qué agente enviar la petición de dos formas:

• En el JSON: Usa el campo model con el formato openclaw:<agentId> o agent:<agentId>.
• En el Header: Usa x-openclaw-agent-id: <agentId>.

4. Ejecuta una petición

Aquí tienes un ejemplo usando curl para una respuesta estándar:

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

Si prefieres recibir la respuesta en tiempo real (Streaming), usa stream: true:

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

Security boundary

Es fundamental que entiendas que este endpoint ofrece acceso total de operador a la instancia del Gateway.

• La autenticación por bearer token no limita el alcance por usuario.
• Un token válido debe tratarse como una credencial de propietario.
• Las peticiones se ejecutan con el mismo nivel de confianza que las acciones del operador.
• No existe una separación de permisos para herramientas sensibles en este endpoint.
• Mantén este acceso solo en redes privadas, loopback o tailnet.
• No expongas este endpoint directamente a internet.

Session behavior

Por defecto, cada petición al endpoint es stateless y genera una session key nueva. Si necesitas que varias llamadas compartan la misma sesión del agente, incluye un string en el campo user de la petición de OpenAI. El Gateway derivará una session key estable a partir de ese valor.

Solución de problemas

• Error 429: Este error aparece si tienes configurado gateway.auth.rateLimit y se detectan demasiados fallos de autenticación. Incluirá un header Retry-After.

¿Necesitas ayuda con la configuración? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Security
• Remote access