API OpenResponses

O Gateway pode disponibilizar um endpoint POST /v1/responses compatível com OpenResponses. Ele fica desativado por padrão e compartilha a porta com o Gateway (multiplexação de WS + HTTP): http://<gateway-host>:<port>/v1/responses.

As solicitações são executadas como uma execução normal do agente do Gateway (o mesmo fluxo de código de openclaw agent), portanto o roteamento, as permissões e a configuração correspondem aos do seu Gateway.

Ative ou desative com gateway.http.endpoints.responses.enabled. Quando ativada, a mesma superfície de compatibilidade também disponibiliza GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings e POST /v1/chat/completions.

Autenticação, segurança e roteamento

O comportamento operacional corresponde ao de OpenAI Chat Completions:

• O caminho de autenticação corresponde a gateway.auth.mode: segredo compartilhado (token/password) usa Authorization: Bearer <token-or-password>; proxy confiável usa cabeçalhos de proxy com reconhecimento de identidade (proxies de loopback no mesmo host precisam de gateway.auth.trustedProxy.allowLoopback = true, com um fallback direto no mesmo host por meio de gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD quando nenhum cabeçalho Forwarded/X-Forwarded-*/X-Real-IP está presente); none em uma entrada privada não precisa de cabeçalho de autenticação. Consulte Autenticação por proxy confiável.
• Trate o endpoint como acesso completo de operador à instância do Gateway.
• Os modos de autenticação por segredo compartilhado ignoram um x-openclaw-scopes mais restrito declarado no bearer e restauram o conjunto completo de escopos padrão do operador: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write. As interações de chat nesse endpoint são tratadas como interações enviadas pelo proprietário.
• Os modos HTTP confiáveis que incluem identidade (proxy confiável ou gateway.auth.mode="none") respeitam x-openclaw-scopes quando presente; caso contrário, recorrem ao conjunto padrão de escopos do operador. A semântica de proprietário só é perdida quando o chamador restringe explicitamente os escopos e omite operator.admin.
• Selecione agentes com model: "openclaw", "openclaw/default", "openclaw/<agentId>" ou com o cabeçalho x-openclaw-agent-id.
• Use x-openclaw-model para substituir o modelo de backend do agente selecionado (requer operator.admin em caminhos de autenticação que incluem identidade).
• Use x-openclaw-session-key para o roteamento explícito de sessão (será rejeitado com 400 invalid_request_error se usar um namespace reservado: subagent:, cron:, acp:).
• Use x-openclaw-message-channel para um contexto de canal de entrada sintético que não seja o padrão.

Para obter a explicação canônica sobre modelos direcionados a agentes, openclaw/default, repasse de embeddings e substituições do modelo de backend, consulte OpenAI Chat Completions.

Consulte Escopos do operador e Segurança.

Comportamento da sessão

Por padrão, o endpoint é sem estado por solicitação (uma nova chave de sessão é gerada a cada chamada).

Se a solicitação incluir uma string user do OpenResponses, o Gateway derivará dela uma chave de sessão estável, permitindo que chamadas repetidas compartilhem uma sessão do agente.

previous_response_id reutiliza a sessão da resposta anterior quando a solicitação permanece no mesmo escopo de agente/usuário/sessão solicitada (correspondente ao sujeito da autenticação, ao ID do agente e a x-openclaw-session-key).

Formato da solicitação

Itens (input)

message

Funções: system, developer, user, assistant.

• system e developer são acrescentados ao prompt do sistema.
• O item user ou function_call_output mais recente se torna a "mensagem atual".
• As mensagens anteriores do usuário/assistente são incluídas como histórico para fornecer contexto.

function_call_output (ferramentas baseadas em turnos)

Envie os resultados das ferramentas de volta ao modelo:

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

reasoning e item_reference

Aceitos para compatibilidade de esquema, mas ignorados durante a criação do prompt.

Ferramentas (ferramentas de função do lado do cliente)

Forneça ferramentas com tools: [{ type: "function", name, description?, parameters? }].

Se o agente chamar uma ferramenta, a resposta retornará um item de saída function_call. Envie uma solicitação subsequente com function_call_output para continuar o turno.

Para tool_choice: "required" e tool_choice fixado em uma função, o endpoint restringe o conjunto exposto de ferramentas de função do cliente, instrui o runtime a chamar uma ferramenta do cliente antes de responder e rejeita o turno se ele não incluir uma chamada estruturada correspondente a uma ferramenta do cliente, de acordo com o contrato de /v1/chat/completions. Solicitações sem streaming retornam 502 com um api_error; solicitações com streaming emitem um evento response.failed.

Imagens (input_image)

Compatível com fontes em base64 ou URL:

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

Tipos MIME permitidos (padrão): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif. Tamanho máximo (padrão): 10MB.

Arquivos (input_file)

Compatível com fontes em base64 ou URL:

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

Tipos MIME permitidos (padrão): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf. Tamanho máximo (padrão): 5MB.

Comportamento atual:

• O conteúdo do arquivo é decodificado e adicionado ao prompt do sistema, não à mensagem do usuário, de modo que permanece efêmero (não é persistido no histórico da sessão).
• O texto decodificado do arquivo é delimitado como conteúdo externo não confiável antes de ser adicionado; assim, os bytes do arquivo são tratados como dados, não como instruções confiáveis. O bloco injetado usa marcadores de limite explícitos (<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>) e uma linha de metadados Source: External. Ele omite intencionalmente o banner longo SECURITY NOTICE: para preservar o orçamento do prompt; os marcadores de limite e os metadados continuam sendo aplicados.
• Primeiro, os PDFs são analisados para extrair texto. Se pouco texto for encontrado, as primeiras páginas serão rasterizadas em imagens e enviadas ao modelo, e o bloco de arquivo injetado usará o espaço reservado [PDF content rendered to images].

A análise de PDFs é fornecida pelo Plugin document-extract incluído, que usa clawpdf e o runtime PDFium WebAssembly fornecido em seu pacote para extração de texto e renderização de páginas.

Padrões de busca por URL:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (total de partes input_file + input_image baseadas em URL por solicitação)
• As solicitações são protegidas (resolução de DNS, bloqueio de IPs privados, limites de redirecionamento e tempos limite).
• Há suporte a listas opcionais de nomes de host permitidos por tipo de entrada (files.urlAllowlist, images.urlAllowlist): host exato ("cdn.example.com") ou subdomínios com curinga ("*.assets.example.com", não corresponde ao domínio raiz). Listas de permissões vazias ou omitidas significam que não há restrição por lista de nomes de host permitidos.
• Para desativar completamente as buscas baseadas em URL, defina files.allowUrl: false e/ou images.allowUrl: false.

Limites de arquivos e imagens (configuração)

Os valores padrão podem ser ajustados em 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: 60000,            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 padrão quando omitidos:

As fontes HEIC/HEIF de input_image são normalizadas para JPEG antes da entrega ao provedor por meio do processador de imagens compartilhado do OpenClaw (Rastermill), que recorre a um conversor do sistema (sips, ImageMagick, GraphicsMagick ou ffmpeg) para formatos que precisam de suporte externo a codecs.

Observação de segurança: as listas de URLs permitidas são aplicadas antes da busca e em cada etapa de redirecionamento. Permitir um nome de host não contorna o bloqueio de IPs privados/internos. Para gateways expostos à internet, aplique controles de saída de rede além das proteções no nível da aplicação. Consulte Segurança.

Streaming (SSE)

Defina stream: true para receber eventos enviados pelo servidor:

• Content-Type: text/event-stream
• Cada linha de evento é event: <type> e data: <json>
• O fluxo termina com data: [DONE]

Tipos de evento emitidos atualmente: 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 (em caso de erro).

Uso

usage é preenchido quando o provedor subjacente informa as contagens de tokens. O OpenClaw normaliza aliases comuns no estilo da OpenAI antes que esses contadores cheguem às superfícies de status/sessão posteriores, incluindo input_tokens / output_tokens e prompt_tokens / completion_tokens.

Erros

Os erros usam um objeto JSON como:

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

Casos comuns: 400 corpo da solicitação inválido, 401 autenticação ausente/inválida, 403 escopo de operador ausente, 405 método incorreto, 429 excesso de tentativas de autenticação com falha (com Retry-After).

Exemplos

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

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

Relacionado

• Conclusões de chat da OpenAI
• Escopos de operador
• OpenAI