​

API OpenResponses (HTTP)

• POST /v1/responses
• Stessa porta del Gateway (multiplex WS + HTTP): http://<gateway-host>:<port>/v1/responses

​

Autenticazione, sicurezza e instradamento

• usa il percorso di autenticazione HTTP del Gateway corrispondente:
  • autenticazione con segreto condiviso (gateway.auth.mode="token" o "password"): Authorization: Bearer <token-or-password>
  • autenticazione con proxy fidato (gateway.auth.mode="trusted-proxy"): header del proxy consapevoli dell’identità da una sorgente proxy fidata non-loopback configurata
  • autenticazione aperta su ingresso privato (gateway.auth.mode="none"): nessun header di autenticazione
• tratta l’endpoint come accesso completo da operatore per l’istanza gateway
• per le modalità di autenticazione con segreto condiviso (token e password), ignora i valori x-openclaw-scopes più restrittivi dichiarati nel bearer e ripristina i normali valori predefiniti completi da operatore
• per le modalità HTTP fidate con identità (ad esempio autenticazione con proxy fidato o gateway.auth.mode="none"), rispetta x-openclaw-scopes quando presente e altrimenti usa come fallback il normale insieme di scope predefiniti dell’operatore
• seleziona gli agenti con model: "openclaw", model: "openclaw/default", model: "openclaw/<agentId>" oppure x-openclaw-agent-id
• usa x-openclaw-model quando vuoi sovrascrivere il modello backend dell’agente selezionato
• usa x-openclaw-session-key per l’instradamento esplicito della sessione
• usa x-openclaw-message-channel quando vuoi un contesto di canale di ingresso sintetico non predefinito

• gateway.auth.mode="token" o "password" + Authorization: Bearer ...
  • dimostra il possesso del segreto operatore condiviso del gateway
  • ignora x-openclaw-scopes più restrittivi
  • ripristina l’insieme completo di scope predefiniti dell’operatore: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • tratta i turni di chat su questo endpoint come turni del mittente proprietario
• modalità HTTP fidate con identità (ad esempio autenticazione con proxy fidato, oppure gateway.auth.mode="none" su ingresso privato)
  • rispettano x-openclaw-scopes quando l’header è presente
  • usano come fallback il normale insieme di scope predefiniti dell’operatore quando l’header è assente
  • perdono la semantica di proprietario solo quando il chiamante restringe esplicitamente gli scope e omette operator.admin

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

​

Comportamento della sessione

​

Forma della richiesta (supportata)

• input: stringa o array di oggetti item.
• instructions: unito nel prompt di sistema.
• tools: definizioni di strumenti lato client (strumenti function).
• tool_choice: filtra o richiede strumenti lato client.
• stream: abilita lo streaming SSE.
• max_output_tokens: limite di output best effort (dipende dal provider).
• user: instradamento stabile della sessione.

• max_tool_calls
• reasoning
• metadata
• store
• truncation

• previous_response_id: OpenClaw riutilizza la sessione della risposta precedente quando la richiesta resta nello stesso ambito di agente/utente/sessione richiesta.

​

Item (input)

​

message

• system e developer vengono aggiunti al prompt di sistema.
• L’item user o function_call_output più recente diventa il “messaggio corrente”.
• I messaggi utente/assistant precedenti vengono inclusi come cronologia per il contesto.

​

function_call_output (strumenti per turno)

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

​

reasoning e item_reference

​

Strumenti (strumenti function lato client)

​

Immagini (input_image)

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

​

File (input_file)

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

• Il contenuto del file viene decodificato e aggiunto al prompt di sistema, non al messaggio utente, così resta effimero (non persistito nella cronologia della sessione).
• Il testo del file decodificato viene racchiuso come contenuto esterno non fidato prima di essere aggiunto, quindi i byte del file vengono trattati come dati, non come istruzioni fidate.
• Il blocco iniettato usa marcatori di confine espliciti come <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> e include una riga di metadati Source: External.
• Questo percorso di input file omette intenzionalmente il lungo banner SECURITY NOTICE: per preservare il budget del prompt; i marcatori di confine e i metadati restano comunque presenti.
• I PDF vengono prima analizzati per estrarre testo. Se viene trovato poco testo, le prime pagine vengono rasterizzate in immagini e passate al modello, e il blocco file iniettato usa il placeholder [PDF content rendered to images].

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (numero totale di parti input_file + input_image basate su URL per richiesta)
• Le richieste sono protette (risoluzione DNS, blocco di IP privati, limiti di redirect, timeout).
• Sono supportate allowlist facoltative di hostname per tipo di input (files.urlAllowlist, images.urlAllowlist).
  • Host esatto: "cdn.example.com"
  • Sottodomini wildcard: "*.assets.example.com" (non corrisponde all’apex)
  • Allowlist vuote o omesse significano nessuna restrizione di allowlist per hostname.
• Per disabilitare completamente i recuperi basati su URL, imposta files.allowUrl: false e/o images.allowUrl: false.

​

Limiti di file + immagini (config)

{
  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,
          },
        },
      },
    },
  },
}

• 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
• Le sorgenti input_image HEIC/HEIF sono accettate e normalizzate a JPEG prima della consegna al provider.

• Le allowlist URL vengono applicate prima del recupero e a ogni passaggio di redirect.
• Mettere un hostname in allowlist non aggira il blocco degli IP privati/interni.
• Per gateway esposti a Internet, applica controlli di uscita di rete oltre alle protezioni a livello applicativo. Vedi Sicurezza.

​

Streaming (SSE)

• Content-Type: text/event-stream
• Ogni riga evento è event: <type> e data: <json>
• Lo stream 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 (in caso di errore)

​

Utilizzo

​

Errori

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

• 401 autenticazione mancante/non valida
• 400 corpo della richiesta non valido
• 405 metodo errato

​

Esempi

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

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