API OpenResponses de OpenClaw

La superficie OpenResponses es la segunda puerta HTTP a un gateway de OpenClaw. Comparte su puerto, sus reglas de autenticación y su contrato de modelo centrado en el agente con el endpoint de chat completions, pero acepta entrada basada en elementos, devuelve las llamadas a funciones como elementos de salida y admite archivos. Esto es lo que dice la documentación que hace, con los límites que se aplican.

Activarlo y confiar en él

• El ajuste del endpoint responses activa la ruta responses en el puerto del gateway y, con ella, la lista de modelos, la consulta de un solo modelo y los embeddings; chat completions se activa por separado, y cada solicitud se ejecuta como una ejecución normal de agente del gateway, así que el enrutamiento, los permisos y la configuración coinciden con los del gateway.
• La autenticación sigue el modo del gateway: token bearer o contraseña para los modos de secreto compartido, encabezados de proxy con reconocimiento de identidad para trusted-proxy (los proxies de loopback en el mismo host necesitan la opción de loopback, con un respaldo directo por contraseña cuando no hay ningún encabezado reenviado), ningún encabezado para none en un ingress privado; el endpoint equivale a acceso completo de operador, los modos de secreto compartido ignoran un encabezado de scopes declarado más restringido y restauran el conjunto de scopes de operador predeterminado, y los modos que llevan identidad respetan el encabezado cuando está presente.
• Los agentes se seleccionan con model en openclaw, openclaw/default, openclaw/ más el id del agente, o con el encabezado agent-id; el encabezado de modelo sobrescribe el modelo del backend (admin en las rutas que llevan identidad), el encabezado session-key enruta de forma explícita y se rechaza con un 400 en los espacios de nombres reservados subagent, cron y acp, y el encabezado message-channel define un canal de entrada sintético.
• El endpoint no guarda estado entre solicitudes de forma predeterminada; una cadena user deriva una clave de sesión estable, y previous_response_id reutiliza la sesión de la respuesta anterior cuando la solicitud se mantiene dentro del mismo ámbito de agente, usuario y sesión solicitada, comprobado por sujeto de autenticación, id de agente y encabezado session-key; continuar explícitamente una sesión de incógnito requiere autoridad de administrador efectiva y, si no, devuelve un 403 forbidden que oculta el destino.

El contenido del archivo se decodifica y se añade al prompt del sistema, no al mensaje del usuario, así que sigue siendo efímero (no se conserva en el historial de la sesión).

Elementos, herramientas y archivos

El campo input es una cadena o un array de elementos. Los elementos de mensaje llevan los roles system, developer, user y assistant: system y developer se añaden al prompt del sistema, el elemento user o function_call_output más reciente se convierte en el mensaje actual, y los turnos anteriores son historial. Las instrucciones se fusionan en el prompt del sistema; las herramientas son herramientas de función del cliente, la elección de herramienta admite auto, none, required o una función con nombre, el límite de tokens de salida se aplica en la medida de lo posible, temperature y top_p también se aplican en la medida de lo posible y el backend Codex Responses basado en ChatGPT los ignora, y el límite de llamadas a herramientas, reasoning, metadata, store y truncation se aceptan pero se ignoran. Cuando el agente llama a una herramienta, la respuesta devuelve un elemento de salida function_call y el cliente continúa el turno con un function_call_output que lleva el id de la llamada; una salida vacía también completa la llamada. Los clientes que mantienen su propio historial añaden la salida de la respuesta a la siguiente entrada sin cambios, o envían previous_response_id solo con los elementos nuevos. Una elección de herramienta obligatoria o fijada que no produce ninguna llamada coincidente devuelve un 502 api_error, o un evento de respuesta fallida con streaming.

Archivos, imágenes y límites

• Los elementos de imagen aceptan fuentes base64 o URL, con JPEG, PNG, GIF, WebP, HEIC y HEIF permitidos de forma predeterminada y 10 MB por imagen, y HEIC y HEIF normalizados a JPEG; los elementos de archivo aceptan base64 o URL, con texto plano, markdown, HTML, CSV, JSON y PDF permitidos de forma predeterminada, 5 MB y 60k caracteres, el texto decodificado con su codificación detectada, y los PDF analizados primero en busca de texto, con las primeras páginas rasterizadas como imágenes cuando se encuentra poco texto (4 páginas, 4 millones de píxeles y 200 caracteres como mínimo de forma predeterminada).
• El texto decodificado de los archivos se envuelve como contenido externo no confiable con marcadores de límite explícitos y una línea de fuente antes de entrar en el prompt, así que los bytes del archivo son datos y no instrucciones; las descargas por URL están activadas de forma predeterminada para archivos e imágenes, con 8 partes URL por solicitud, protegidas por la resolución DNS, el bloqueo de direcciones privadas, límites de redirecciones y tiempos de espera, y listas opcionales de hosts permitidos por tipo que aceptan hosts exactos o subdominios comodín y se aplican antes de la descarga y en cada salto de redirección.
• El cuerpo de la solicitud tiene un límite de 20 MB; con el streaming activado, los eventos son tipados (created, in progress, output item added, content part added, output text delta y done, output item done, completed, incomplete cuando se trunca por el presupuesto de salida y failed en caso de error) y terminan con DONE; una respuesta cortada por el presupuesto de tokens de salida devuelve un estado incomplete con el motivo max output tokens, el uso se rellena cuando el proveedor informa de los recuentos, y los errores son 400, 401, 403 por un scope faltante, 405 y 429 con un encabezado de reintento tras demasiados intentos de autenticación fallidos.

La API HTTP compatible con OpenAI de OpenClaw es el endpoint hermano cuyo contrato de modelo reutiliza este, y la guía de scopes de operador de OpenClaw explica el conjunto de scopes que ambos restauran o restringen.

Cuándo usarlo

El modelo de elementos encaja con clientes que ya mantienen su propio historial de conversación y quieren reproducirlo tal cual, o que necesitan pasar archivos e imágenes a un agente sin conservarlos en la sesión. El endpoint de chat completions encaja con herramientas que solo conocen el formato antiguo. Ambos ejecutan por debajo la misma ejecución de agente, así que la elección depende del cliente, no del agente. La API de OpenClaw cubre la API más amplia del gateway y la herramienta web fetch de OpenClaw, lo que hace el propio agente con las URL una vez que le llega una solicitud.

En Diali

En Diali, el gateway está detrás del ingress de la plataforma, con la configuración del motor generada desde el panel y reemplazada en cada versión, así que activar cualquiera de las dos superficies HTTP es una decisión de configuración, no un puerto que abrir. OpenClaw alojado en Diali describe el asistente alojado y los precios de Diali, los planes en los que se incluye.

• Elementos de entrada, llamadas a funciones de salida, resultados de vuelta como function_call_output.
• Los archivos llegan al prompt del sistema como contenido no confiable.
• Mismo puerto, misma autenticación y la misma confianza de nivel propietario que chat completions.