OpenResponses API (HTTP)

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

Este endpoint está deshabilitado por defecto. Habilítalo en config primero.

- ''POST /v1/responses''

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

Bajo el capó, las solicitudes se ejecutan como una ejecución normal de agente del Gateway (mismo código que ''openclaw agent''), así que enrutamiento/permisos/config coinciden con tu Gateway.

Usa la configuración de auth del Gateway. Envía un bearer token:

- ''Authorization: Bearer <token>''

Notas:

- 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'').

Sin headers personalizados requeridos: codifica el id del agente en el campo ''model'' de OpenResponses:

- ''model: "openclaw:<agentId>"'' (ejemplo: ''"openclaw:main"'', ''"openclaw:beta"'')

- ''model: "agent:<agentId>"''（Aliases）

O apunta a un agente OpenClaw específico por header:

- ''x-openclaw-agent-id: <agentId>''（Por defecto:''main''）

Avanzado:

- ''x-openclaw-session-key: '''' para controlar completamente el enrutamiento de sesión.

Establece ''gateway.http.endpoints.responses.enabled'' a ''true'':

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

Establece ''gateway.http.endpoints.responses.enabled'' a ''false'':

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

Por defecto el endpoint es sin estado por solicitud (se genera una nueva clave de sesión cada llamada).

Si la solicitud incluye un string ''user'' de OpenResponses, el Gateway deriva una clave de sesión estable de él, así que llamadas repetidas pueden compartir una sesión de agente.

Las solicitudes siguen la API de OpenResponses con entrada basada en items. Actualmente soportado:

- ''input'': string o array de objetos item.

- ''instructions'': se fusionará en el prompt del sistema.

- ''tools'': definiciones de herramientas cliente (function tools).

- ''tool_choice'': filtrar o requerir herramientas cliente.

- ''stream'': habilitar streaming SSE.

- ''max_output_tokens'': límite de salida de mejor esfuerzo (depende del proveedor).

- ''user'': enrutamiento de sesión estable.

Aceptados pero actualmente ignorados:

- ''max_tool_calls''

- ''reasoning''

- ''metadata''

- ''store''

- ''previous_response_id''

- ''truncation''

#

role: ''system'', ''developer'', ''user'', ''assistant''.

- ''system'' y ''developer'' se añaden después del prompt del sistema.

- El item ''user'' o ''function_call_output'' más reciente se convierte en el "mensaje actual".

- Los mensajes user/assistant anteriores se incluyen como historial de contexto.

#

Envía resultados de herramientas de vuelta al modelo:

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

#

Aceptados por compatibilidad pero ignorados al construir el prompt.

Proporciona herramientas vía tools: [{ type: "function", function: { name, description?, parameters? } }].

Si el agente decide llamar una herramienta, la respuesta devuelve un item de salida ''function_call''.

Después, envía una solicitud de seguimiento vía ''function_call_output'' para continuar el turno.

Soporta fuentes 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''.

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

Soporta fuentes 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 añade al prompt del sistema, no al mensaje del usuario, así que permanece efímero (no persiste en el historial de sesión).

- Los PDFs se analizan para 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'' amigable con Node (sin worker). La build moderna de PDF.js espera workers del navegador/globales DOM, así que no se usa en el Gateway.

Valores predeterminados de fetch URL:

- ''files.allowUrl''：''true''

- ''images.allowUrl''：''true''

- Las solicitudes están protegidas (resolución DNS, bloqueo de IP privada, límites de redirección, timeouts).

Los valores predeterminados se pueden ajustar bajo ''gateway.http.endpoints.responses'':

{
  gateway: {
    http: {
      endpoints: {
        responses: {
          enabled: true,
          maxBodyBytes: 20000000,
          files: {
            allowUrl: true,
            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,
            allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
            maxBytes: 10485760,
            maxRedirects: 3,
            timeoutMs: 10000,
          },
        },
      },
    },
  },
}

Valores predeterminados cuando se omiten:

- ''maxBodyBytes''：20MB

- ''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

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 eventos actualmente emitidos:

- ''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 error)

''usage'' se popula cuando el proveedor subyacente reporta conteos de tokens.

Los errores usan un objeto JSON. Ejemplo:

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

Casos comunes:

- ''401'' auth faltante/inválida

- ''400'' cuerpo de solicitud inválido

- ''405'' método incorrecto

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:

ReferenceGatewayOpenresponsesHttpApiPage.step18.code2