POST /v1/responses compatible con OpenResponses. Está deshabilitado de forma predeterminada y comparte su puerto con el Gateway (multiplexación WS + HTTP): http://<gateway-host>:<port>/v1/responses.
Las solicitudes se ejecutan como una ejecución normal de agente del Gateway (la misma ruta de código que openclaw agent), por lo que el enrutamiento, los permisos y la configuración coinciden con tu Gateway.
Habilítalo o deshabilítalo con gateway.http.endpoints.responses.enabled. Cuando está habilitado, la misma superficie de compatibilidad también sirve GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings y POST /v1/chat/completions.
Autenticación, seguridad y enrutamiento
El comportamiento operativo coincide con OpenAI Chat Completions:- La ruta de autenticación coincide con
gateway.auth.mode: shared-secret (token/password) usaAuthorization: Bearer <token-or-password>; trusted-proxy usa encabezados de proxy conscientes de identidad (los proxies loopback del mismo host necesitangateway.auth.trustedProxy.allowLoopback = true, con una alternativa directa del mismo host mediantegateway.auth.password/OPENCLAW_GATEWAY_PASSWORDcuando no hay encabezadoForwarded/X-Forwarded-*/X-Real-IPpresente);noneen una entrada privada no necesita encabezado de autenticación. Consulta Autenticación de proxy de confianza. - Trata el endpoint como acceso completo de operador a la instancia del gateway.
- Los modos de autenticación shared-secret ignoran un
x-openclaw-scopesdeclarado por bearer más restringido y restauran el conjunto completo de ámbitos de operador predeterminado:operator.admin,operator.approvals,operator.pairing,operator.read,operator.talk.secrets,operator.write. Los turnos de chat en este endpoint se tratan como turnos de remitente propietario. - Los modos HTTP con identidad de confianza (trusted-proxy, o
gateway.auth.mode="none") respetanx-openclaw-scopescuando está presente; de lo contrario, recurren al conjunto predeterminado de ámbitos de operador. La semántica de propietario solo se pierde cuando el llamador restringe explícitamente los ámbitos y omiteoperator.admin. - Selecciona agentes con
model: "openclaw","openclaw/default","openclaw/<agentId>"o el encabezadox-openclaw-agent-id. - Usa
x-openclaw-modelpara anular el modelo backend del agente seleccionado (requiereoperator.adminen rutas de autenticación con identidad). - Usa
x-openclaw-session-keypara el enrutamiento explícito de sesión (se rechaza con400 invalid_request_errorsi usa un espacio de nombres reservado:subagent:,cron:,acp:). - Usa
x-openclaw-message-channelpara un contexto de canal de entrada sintético no predeterminado.
openclaw/default, el paso directo de embeddings y las anulaciones de modelo backend, consulta OpenAI Chat Completions.
Consulta Ámbitos de operador y Seguridad.
Comportamiento de sesión
De forma predeterminada, el endpoint es sin estado por solicitud (se genera una nueva clave de sesión en cada llamada). Si la solicitud incluye una cadena OpenResponsesuser, el Gateway deriva de ella una clave de sesión estable para que las llamadas repetidas puedan compartir una sesión de agente.
previous_response_id reutiliza la sesión de la respuesta anterior cuando la solicitud permanece dentro del mismo ámbito de agente/usuario/sesión solicitada (coincidencia por sujeto de autenticación, id de agente y x-openclaw-session-key).
Forma de la solicitud
| Campo | Compatibilidad |
|---|---|
input | Cadena o matriz de objetos de elemento. |
instructions | Se fusiona en el prompt del sistema. |
tools | Definiciones de herramientas del cliente (herramientas de función). |
tool_choice | "auto", "none", "required" o { "type": "function", "name": "..." } para filtrar o requerir herramientas del cliente. |
stream | Habilita streaming SSE. |
max_output_tokens | Límite de salida de mejor esfuerzo (dependiente del proveedor). |
temperature | Temperatura de muestreo de mejor esfuerzo. Ignorada por el backend Codex Responses basado en ChatGPT, que usa muestreo fijo del lado del servidor. |
top_p | Muestreo por núcleo de mejor esfuerzo. Misma salvedad de Codex Responses que temperature. |
user | Enrutamiento de sesión estable. |
previous_response_id | Continuidad de sesión (consulta arriba). |
max_tool_calls, reasoning, metadata, store, truncation | Aceptados, pero actualmente ignorados. |
Elementos (input)
message
Roles: system, developer, user, assistant.
systemydeveloperse anexan al prompt del sistema.- El elemento
userofunction_call_outputmás reciente se convierte en el “mensaje actual”. - Los mensajes anteriores de usuario/asistente se incluyen como historial para contexto.
function_call_output (herramientas basadas en turnos)
Envía los resultados de herramientas de vuelta al modelo:
reasoning e item_reference
Aceptados por compatibilidad de esquema, pero ignorados al construir el prompt.
Herramientas (herramientas de función del lado del cliente)
Proporciona herramientas contools: [{ type: "function", name, description?, parameters? }].
Si el agente llama a una herramienta, la respuesta devuelve un elemento de salida function_call. Envía una solicitud de seguimiento con function_call_output para continuar el turno.
Para tool_choice: "required" y tool_choice fijado a una función, el endpoint restringe el conjunto expuesto de herramientas de función del cliente, instruye al runtime para que llame a una herramienta del cliente antes de responder y rechaza el turno si no incluye una llamada estructurada coincidente a una herramienta del cliente, de acuerdo con el contrato de /v1/chat/completions. Las solicitudes sin streaming devuelven 502 con un api_error; las solicitudes con streaming emiten un evento response.failed.
Imágenes (input_image)
Admite fuentes base64 o URL:
image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Tamaño máximo (predeterminado): 10 MB.
Archivos (input_file)
Admite fuentes base64 o URL:
text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. Tamaño máximo (predeterminado): 5 MB.
Comportamiento actual:
- El contenido del archivo se decodifica y se agrega al prompt del sistema, no al mensaje de usuario, por lo que permanece efímero (no se persiste en el historial de sesión).
- El texto de archivo decodificado se envuelve como contenido externo no confiable antes de agregarse, por lo que los bytes del archivo se tratan como datos, no como instrucciones de confianza. El bloque inyectado usa marcadores de límite explícitos (
<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>/<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>) y una línea de metadatosSource: External. Omite intencionalmente el banner largoSECURITY NOTICE:para preservar el presupuesto del prompt; los marcadores de límite y los metadatos siguen aplicándose. - Los PDF se analizan primero para extraer texto. Si se encuentra poco texto, las primeras páginas se rasterizan como imágenes y se pasan al modelo, y el bloque de archivo inyectado usa el marcador de posición
[PDF content rendered to images].
document-extract, que usa clawpdf y su runtime PDFium WebAssembly empaquetado para la extracción de texto y el renderizado de páginas.
Valores predeterminados de recuperación de URL:
files.allowUrl:trueimages.allowUrl:truemaxUrlParts:8(total de partesinput_file+input_imagebasadas en URL por solicitud)- Las solicitudes están protegidas (resolución DNS, bloqueo de IP privadas, límites de redirección, tiempos de espera).
- Se admiten listas de permitidos de nombres de host opcionales por tipo de entrada (
files.urlAllowlist,images.urlAllowlist): host exacto ("cdn.example.com") o subdominios comodín ("*.assets.example.com", no coincide con el apex). Las listas de permitidos vacías u omitidas significan que no hay restricción de lista de permitidos de nombres de host. - Para deshabilitar por completo las recuperaciones basadas en URL, establece
files.allowUrl: falsey/oimages.allowUrl: false.
Límites de archivos e imágenes (configuración)
Los valores predeterminados se pueden ajustar engateway.http.endpoints.responses:
| Clave | Predeterminado |
|---|---|
maxBodyBytes | 20 MB |
maxUrlParts | 8 |
files.maxBytes | 5 MB |
files.maxChars | 60k |
files.maxRedirects | 3 |
files.timeoutMs | 10s |
files.pdf.maxPages | 4 |
files.pdf.maxPixels | 4,000,000 |
files.pdf.minTextChars | 200 |
images.maxBytes | 10 MB |
images.maxRedirects | 3 |
images.timeoutMs | 10s |
input_image se normalizan a JPEG antes de entregarse al proveedor mediante el procesador de imágenes compartido de OpenClaw (Rastermill), que recurre a un conversor del sistema (sips, ImageMagick, GraphicsMagick o ffmpeg) para formatos que necesitan compatibilidad con códecs externos.
Nota de seguridad: las listas de permitidos de URL se aplican antes de la recuperación y en los saltos de redirección. Permitir un nombre de host no omite el bloqueo de IP privadas/internas. Para gateways expuestos a internet, aplica controles de salida de red además de las protecciones a nivel de aplicación. Consulta Seguridad.
Streaming (SSE)
Establecestream: true para recibir Server-Sent Events:
Content-Type: text/event-stream- Cada línea de evento es
event: <type>ydata: <json> - El flujo termina con
data: [DONE]
response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta, response.output_text.done, response.content_part.done, response.output_item.done, response.completed, response.failed (en caso de error).
Uso
usage se completa cuando el proveedor subyacente informa recuentos de tokens. OpenClaw normaliza alias comunes de estilo OpenAI antes de que esos contadores lleguen a las superficies de estado/sesión posteriores, incluidos input_tokens / output_tokens y prompt_tokens / completion_tokens.
Errores
Los errores usan un objeto JSON como:400, autenticación faltante/no válida 401, alcance de operador faltante 403, método incorrecto 405, demasiados intentos de autenticación fallidos 429 (con Retry-After).