API de OpenResponses (HTTP)

El Gateway de OpenClaw puede servir un endpoint POST /v1/responses compatible con OpenResponses.

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

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

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, seguridad y enrutamiento

El comportamiento operativo coincide con OpenAI Chat Completions:

usa Authorization: Bearer <token> con la configuración de autenticación normal del Gateway
trata el endpoint como acceso completo de operador para la instancia del gateway
selecciona agentes con model: "openclaw:<agentId>", model: "agent:<agentId>", o x-openclaw-agent-id
usa x-openclaw-session-key para enrutamiento explícito de sesión

Habilita o deshabilita este endpoint con gateway.http.endpoints.responses.enabled.

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 OpenResponses, 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.

Formato de solicitud (soportado)

La solicitud sigue la API de OpenResponses con entrada basada en items. Soporte actual:

input: string o array de objetos item.
instructions: se fusiona con el prompt del sistema.
tools: definiciones de herramientas del cliente (herramientas de función).
tool_choice: filtrar o requerir herramientas del cliente.
stream: habilita streaming SSE.
max_output_tokens: límite de salida en base a mejor esfuerzo (depende del proveedor).
user: enrutamiento estable de sesión.

Aceptados pero actualmente ignorados:

max_tool_calls
reasoning
metadata
store
previous_response_id
truncation

Items (input)

`message`

Roles: system, developer, user, assistant.

system y developer se agregan al prompt del sistema.
El item user o function_call_output más reciente se convierte en el “mensaje actual”.
Los mensajes previos de user/assistant se incluyen como historial para contexto.

`function_call_output` (herramientas por turno)

Envía resultados de herramientas de vuelta al modelo:

{
  "type": "function_call_output",
  "call_id": "call_123",
  "output": "{\"temperature\": \"72F\"}"
}

`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 con tools: [{ type: "function", function: { name, description?, parameters? } }].

Si el agente decide llamar a una herramienta, la respuesta devuelve un item de salida function_call. Luego envías una solicitud de seguimiento con function_call_output para continuar el turno.

Imágenes (`input_image`)

Soporta fuentes en base64 o URL:

{
  "type": "input_image",
  "source": { "type": "url", "url": "https://example.com/image.png" }
}

Tipos MIME permitidos (actual): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Tamaño máximo (actual): 10MB.

Archivos (`input_file`)

Soporta fuentes en base64 o URL:

{
  "type": "input_file",
  "source": {
    "type": "base64",
    "media_type": "text/plain",
    "data": "SGVsbG8gV29ybGQh",
    "filename": "hello.txt"
  }
}

Tipos MIME permitidos (actual): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf.

Tamaño máximo (actual): 5MB.

Comportamiento actual:

El contenido del archivo se decodifica y se agrega al prompt del sistema, no al mensaje del usuario, por lo que permanece efímero (no se persiste en el historial de sesión).
Los PDFs se analizan para extraer texto. Si se encuentra poco texto, las primeras páginas se rasterizan en imágenes y se pasan al modelo.

El análisis de PDF usa la build legacy de pdfjs-dist compatible con Node (sin worker). La build moderna de PDF.js espera workers/globales del DOM del navegador, por lo que no se usa en el Gateway.

Valores por defecto de obtención de URLs:

files.allowUrl: true
images.allowUrl: true
maxUrlParts: 8 (total de partes input_file + input_image basadas en URL por solicitud)
Las solicitudes están protegidas (resolución DNS, bloqueo de IPs privadas, límites de redirecciones, timeouts).
Se soportan listas de hosts permitidos opcionales por tipo de entrada (files.urlAllowlist, images.urlAllowlist).
- Host exacto: "cdn.example.com"
- Subdominios con comodín: "*.assets.example.com" (no coincide con el apex)

Límites de archivos e imágenes (configuración)

Los valores por defecto se pueden ajustar en gateway.http.endpoints.responses:

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          maxUrlParts: 8,
          files: {
            allowUrl: true,
            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
            allowedMimes: [
              "text/plain",
              "text/markdown",
              "text/html",
              "text/csv",
              "application/json",
              "application/pdf",
            ],
            maxBytes: 5242880,
            maxChars: 200000,
            maxRedirects: 3,
            timeoutMs: 10000,
            pdf: {
              maxPages: 4,
              maxPixels: 4000000,
              minTextChars: 200,
            },
          },
          images: {
            allowUrl: true,
            urlAllowlist: ["images.example.com"],
            allowedMimes: [
              "image/jpeg",
              "image/png",
              "image/gif",
              "image/webp",
              "image/heic",
              "image/heif",
            ],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

Valores por defecto cuando se omiten:

maxBodyBytes: 20MB
maxUrlParts: 8
files.maxBytes: 5MB
files.maxChars: 200k
files.maxRedirects: 3
files.timeoutMs: 10s
files.pdf.maxPages: 4
files.pdf.maxPixels: 4,000,000
files.pdf.minTextChars: 200
images.maxBytes: 10MB
images.maxRedirects: 3
images.timeoutMs: 10s
Las fuentes input_image HEIC/HEIF se aceptan y se normalizan a JPEG antes de enviarlas al proveedor.

Nota de seguridad:

Las listas de hosts permitidos se aplican antes de la obtención y en cada salto de redirección.
Poner un hostname en la lista de permitidos no omite el bloqueo de IPs privadas/internas.
Para gateways expuestos a internet, aplica controles de egreso de red además de las protecciones a nivel de aplicación. Consulta Seguridad.

Streaming (SSE)

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

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

Tipos de evento emitidos actualmente:

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 rellena cuando el proveedor subyacente reporta conteos de tokens.

Errores

Los errores usan un objeto JSON como:

{ "error": { "message": "...", "type": "invalid_request_error" } }

Casos comunes:

401 autenticación faltante/inválida
400 cuerpo de solicitud inválido
405 método incorrecto

Ejemplos

Sin streaming:

curl -sS http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "input": "hi"
  }'

Con streaming:

curl -N http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-agent-id: main' \
  -d '{
    "model": "openclaw",
    "stream": true,
    "input": "hi"
  }'