API OpenResponses do OpenClaw

A superfície OpenResponses é a segunda porta HTTP de entrada em um gateway do OpenClaw. Ela compartilha a porta, as regras de autenticação e o contrato de modelo centrado no agente com o endpoint chat completions, mas recebe entrada baseada em itens, retorna chamadas de função como itens de saída e aceita arquivos. Aqui está o que a documentação diz que ela faz, com os limites que se aplicam.

Como ativar e quanto confiar

• A configuração do endpoint responses ativa a rota responses na porta do gateway e, com ela, a lista de modelos, a consulta de um único modelo e os embeddings; o chat completions é ativado separadamente, e cada requisição roda como uma execução normal de agente do gateway, então roteamento, permissões e configuração são os mesmos do gateway.
• A autenticação segue o modo do gateway: token bearer ou senha para os modos de segredo compartilhado, cabeçalhos de proxy com reconhecimento de identidade para trusted-proxy (proxies de loopback no mesmo host precisam da opção de loopback, com fallback direto para senha quando não há cabeçalho encaminhado), nenhum cabeçalho para none em um ingress privado; o endpoint dá acesso completo de operador, os modos de segredo compartilhado ignoram um cabeçalho de escopos declarado mais restrito e restauram o conjunto padrão de escopos de operador, e os modos que carregam identidade respeitam o cabeçalho quando ele está presente.
• Os agentes são selecionados com model definido como openclaw, openclaw/default, openclaw/ mais o id do agente, ou com o cabeçalho de id do agente; o cabeçalho de modelo substitui o modelo do backend (admin nos caminhos que carregam identidade), o cabeçalho de chave de sessão roteia explicitamente e é rejeitado com um 400 nos namespaces reservados subagent, cron e acp, e o cabeçalho de canal de mensagem define um canal de entrada sintético.
• Por padrão, o endpoint não mantém estado entre requisições; uma string user deriva uma chave de sessão estável, e previous_response_id reutiliza a sessão da resposta anterior quando a requisição fica dentro do mesmo escopo de agente, usuário e sessão solicitada, com a correspondência feita pelo sujeito da autenticação, pelo id do agente e pelo cabeçalho de chave de sessão; continuar explicitamente uma sessão incognito exige autoridade efetiva de admin e, caso contrário, retorna um 403 forbidden que esconde o destino.

O conteúdo do arquivo é decodificado e adicionado ao prompt de sistema, não à mensagem do usuário, então ele permanece efêmero (não é persistido no histórico da sessão).

Itens, ferramentas e arquivos

O campo input é uma string ou um array de itens. Os itens de mensagem trazem os papéis system, developer, user e assistant: system e developer são anexados ao prompt de sistema, o item user ou function_call_output mais recente se torna a mensagem atual, e os turnos anteriores viram histórico. As instruções são mescladas ao prompt de sistema; as ferramentas são ferramentas de função do cliente, a escolha de ferramenta aceita auto, none, required ou uma função nomeada, o limite de tokens de saída é aplicado na base do melhor esforço, temperature e top_p também são de melhor esforço e ignorados pelo backend Codex Responses baseado no ChatGPT, e o limite de chamadas de ferramentas, reasoning, metadata, store e truncation são aceitos, mas ignorados. Quando o agente chama uma ferramenta, a resposta retorna um item de saída function_call e o cliente continua o turno com um function_call_output que traz o id da chamada; uma saída vazia ainda conclui a chamada. Clientes que mantêm o próprio histórico anexam a saída da resposta à próxima entrada sem alterações, ou enviam previous_response_id apenas com os itens novos. Uma escolha de ferramenta required ou fixada que não gera nenhuma chamada correspondente retorna um 502 api_error, ou um evento de resposta failed quando há streaming.

Arquivos, imagens e limites

• Os itens de imagem aceitam fontes base64 ou URL, com JPEG, PNG, GIF, WebP, HEIC e HEIF permitidos por padrão e 10 MB por imagem, sendo HEIC e HEIF normalizados para JPEG; os itens de arquivo aceitam base64 ou URL, com texto simples, markdown, HTML, CSV, JSON e PDF permitidos por padrão, 5 MB e 60k caracteres, o texto decodificado com a codificação detectada, e os PDFs analisados primeiro em busca de texto, com as primeiras páginas rasterizadas em imagens quando pouco texto é encontrado (4 páginas, 4 milhões de pixels, mínimo de 200 caracteres por padrão).
• O texto decodificado dos arquivos é envolvido como conteúdo externo não confiável, com marcadores de fronteira explícitos e uma linha de origem, antes de entrar no prompt, então os bytes do arquivo são dados, não instruções; a busca por URL vem ativada por padrão para arquivos e imagens, com 8 partes de URL por requisição, protegida por resolução de DNS, bloqueio de endereços privados, limites de redirecionamento e timeouts, e listas de permissões de hostnames opcionais por tipo, que aceitam hosts exatos ou subdomínios com curinga e são aplicadas antes da busca e em cada salto de redirecionamento.
• O corpo da requisição é limitado a 20 MB; com o streaming ativado, os eventos são tipados (created, in progress, output item added, content part added, output text delta e done, output item done, completed, incomplete no truncamento pelo orçamento de saída e failed em caso de erro) e terminam com DONE; uma resposta cortada pelo orçamento de tokens de saída retorna o status incomplete com o motivo max output tokens, o uso é preenchido quando o provedor informa as contagens, e os erros são 400, 401, 403 por escopo ausente, 405 e 429 com um cabeçalho de retry depois de muitas tentativas de autenticação com falha.

A API HTTP compatível com OpenAI do OpenClaw é o endpoint irmão cujo contrato de modelo este reutiliza, e os escopos de operador do OpenClaw explica o conjunto de escopos que os dois restauram ou restringem.

Quando usar

O modelo de itens serve para clientes que já mantêm o próprio histórico de conversa e querem reproduzi-lo literalmente, ou que precisam entregar arquivos e imagens a um agente sem persisti-los na sessão. O endpoint chat completions serve para ferramentas que só conhecem o formato mais antigo. Os dois rodam a mesma execução de agente por baixo, então a escolha depende do cliente, não do agente. A API do OpenClaw cobre a API mais ampla do gateway, e o web fetch do OpenClaw, o que o próprio agente faz com URLs depois que uma requisição chega até ele.

Na Diali

Na Diali, o gateway fica atrás do ingress da plataforma, com a configuração do motor gerada a partir do painel e substituída a cada versão, então ativar qualquer uma das superfícies HTTP é uma decisão de configuração, e não uma porta a abrir. O OpenClaw hospedado na Diali descreve o assistente hospedado, e os preços da Diali, os planos em que ele vem.

• Itens na entrada, chamadas de função na saída, resultados de volta como function_call_output.
• Os arquivos chegam ao prompt de sistema como conteúdo não confiável.
• Mesma porta, mesma autenticação, mesma confiança de nível de proprietário do chat completions.