Ir al contenido
OpenClaw

OpenResponses API: Conecta tu Gateway mediante HTTP

¿Alguna vez has sentido que configurar un Gateway para que se comunique con diferentes modelos es un dolor de cabeza constante? A veces solo quieres un endpoint estándar que funcione sin tener que reinventar la rueda cada vez que cambias de proveedor o de agente.

Si buscas una forma directa de estandarizar tus comunicaciones, el Gateway de OpenClaw puede exponer un endpoint POST /v1/responses compatible con OpenResponses. Ten en cuenta que esta opción está desactivada por defecto, así que lo primero que debes hacer es habilitarla en tu configuración.

API de OpenResponses (HTTP)

Sección titulada «API de OpenResponses (HTTP)»
  • POST /v1/responses
  • Mismo puerto que el Gateway (multiplexación WS + HTTP): http://<gateway-host>:<port>/v1/responses

Internamente, las solicitudes se ejecutan como una ejecución normal de un agente del Gateway (el mismo camino de código que openclaw agent), por lo que el enrutamiento, los permisos y la configuración coinciden con tu Gateway.

Autenticación, seguridad y enrutamiento

Sección titulada «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 total de operador para la instancia del Gateway.
  • Para modos de autenticación de secreto compartido (token y password), ignora los valores de x-openclaw-scopes declarados en el bearer y restaura los valores predeterminados de operador total.
  • Para modos HTTP con identidad de confianza (por ejemplo, autenticación por proxy de confianza o gateway.auth.mode="none"), respeta los scopes de operador declarados en la solicitud.
  • Selecciona agentes con model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>" o x-openclaw-agent-id.
  • Usa x-openclaw-model cuando quieras sobrescribir el modelo de backend del agente seleccionado.
  • Usa x-openclaw-session-key para un enrutamiento de sesión explícito.
  • Usa x-openclaw-message-channel cuando quieras un contexto de canal de ingreso sintético que no sea el predeterminado.

Matriz de autenticación:

  • gateway.auth.mode="token" o "password" + Authorization: Bearer ...
    • Demuestra la posesión del secreto compartido del operador del Gateway.
    • Ignora los x-openclaw-scopes más restrictivos.
    • Restaura el conjunto completo de scopes de operador por defecto.
    • Trata los turnos de chat en este endpoint como turnos de propietario-remitente.
  • Modos HTTP con identidad de confianza (por ejemplo, proxy de confianza o gateway.auth.mode="none" en ingreso privado).
    • Respeta la cabecera x-openclaw-scopes declarada.
    • Solo obtiene semántica de propietario cuando operator.admin está presente en esos scopes declarados.

Activa o desactiva este endpoint con gateway.http.endpoints.responses.enabled.

La misma superficie de compatibilidad también incluye:

  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions

Para la explicación canónica de cómo encajan los modelos de destino del agente, openclaw/default, el paso de embeddings y las sobrescrituras de modelos de backend, consulta OpenAI Chat Completions y Model list and agent routing.

Comportamiento de la sesión

Sección titulada «Comportamiento de la 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.

Estructura de la solicitud (soportada)

Sección titulada «Estructura de la solicitud (soportada)»

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

  • input: string o array de objetos de ítem.
  • instructions: se fusionan en el prompt del sistema.
  • tools: definiciones de herramientas del cliente (herramientas de función).
  • tool_choice: filtra o requiere herramientas del cliente.
  • stream: habilita el streaming SSE.
  • max_output_tokens: límite de salida de mejor esfuerzo (depende del proveedor).
  • user: enrutamiento de sesión estable.

Aceptado pero ignorado actualmente:

  • max_tool_calls
  • reasoning
  • metadata
  • store
  • truncation

Soportado:

  • previous_response_id: OpenClaw reutiliza la sesión de respuesta anterior cuando la solicitud se mantiene dentro del mismo alcance de agente/usuario/sesión solicitada.

Items (entrada)

Sección titulada «Items (entrada)»

message

Sección titulada «message»

Roles: system, developer, user, assistant.

  • system y developer se añaden al prompt del sistema.
  • El ítem user o function_call_output más reciente se convierte en el “mensaje actual”.
  • Los mensajes anteriores de usuario/asistente se incluyen como historial para el contexto.

function_call_output (herramientas basadas en turnos)

Sección titulada «function_call_output (herramientas basadas en turnos)»

Envía los resultados de las herramientas de vuelta al modelo:

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

reasoning e item_reference

Sección titulada «reasoning e item_reference»

Se aceptan por compatibilidad de esquema, pero se ignoran al construir el prompt.

Tools (herramientas de función del lado del cliente)

Sección titulada «Tools (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 ítem de salida function_call. Luego envías una solicitud de seguimiento con function_call_output para continuar el turno.

Imágenes (input_image)

Sección titulada «Imágenes (input_image)»

Soporta fuentes base64 o URL:

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

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

Archivos (input_file)

Sección titulada «Archivos (input_file)»

Soporta fuentes base64 o URL:

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

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

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

Comportamiento actual:

  • El contenido del archivo se decodifica y se añade al prompt del sistema, no al mensaje del usuario, por lo que permanece efímero (no se persiste en el historial de la 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 utiliza la compilación legacy de pdfjs-dist compatible con Node.js (sin worker). La compilación moderna de PDF.js espera workers de navegador o globales de DOM, por lo que no se usa en el Gateway.

Valores por defecto para la 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 redirección, timeouts).
  • Se admiten listas de permitidos de hostnames 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 dominio raíz)
    • Las listas vacías o emitidas significan que no hay restricción de lista de permitidos de hostname.
  • Para desactivar completamente las obtenciones basadas en URL, establece files.allowUrl: false y/o images.allowUrl: false.

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

Sección titulada «Límites de archivos e imágenes (configuración)»

Los valores por defecto se pueden ajustar bajo 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 la entrega al proveedor.

Nota de seguridad:

  • Las listas de permitidos de URL se aplican antes de la obtención y en los saltos de redirección.
  • Incluir un hostname en la lista de permitidos no evita el bloqueo de IPs privadas o internas.
  • Para gateways expuestos a internet, aplica controles de egreso de red además de las protecciones a nivel de aplicación. Consulta Security.

Streaming (SSE)

Sección titulada «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 eventos 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

Sección titulada «Uso»

usage se rellena cuando el proveedor subyacente informa el conteo de tokens.

Errores

Sección titulada «Errores»

Los errores utilizan un objeto JSON como este:

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

Casos comunes:

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

Ejemplos

Sección titulada «Ejemplos»

Sin streaming:

Ventana de terminal
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:

Ventana de terminal
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"
  }'

Próximos pasos

Sección titulada «Próximos pasos»

AI Setup Assistant

OpenClaw

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.