API HTTP compatível com OpenAI do OpenClaw

Qualquer coisa que fale o protocolo OpenAI Chat Completions pode conversar com um agente do OpenClaw, porque o gateway serve uma pequena superfície compatível na mesma porta do seu WebSocket. Ela vem desativada por padrão, é acesso completo de operador quando ativada, e o campo model dela significa algo diferente do que o seu cliente pensa. Aqui está o contrato como a documentação o descreve.

O que ela serve e em quem confia

• Assim que gateway.http.endpoints.chatCompletions é ativado, o gateway serve POST /v1/chat/completions, GET /v1/models, GET em um único id de modelo e POST /v1/embeddings na porta do gateway; o endpoint responses é ativado separadamente, e toda requisição roda como uma execução normal de agente do gateway, no mesmo caminho de código do comando agent, então roteamento, permissões e configuração correspondem aos do seu gateway.
• Um token ou senha válido do gateway para esse endpoint equivale a uma credencial de proprietário ou operador, e não a um escopo por usuário: a autenticação bearer por segredo compartilhado ignora qualquer cabeçalho x-openclaw-scopes, restaura o conjunto completo de escopos padrão de operador e trata os turnos de chat como turnos de remetente proprietário; o ingress por trusted-proxy ou privado sem autenticação respeita x-openclaw-scopes quando presente e exige operator.admin para controles de nível proprietário.
• A autenticação segue o modo do gateway: token bearer ou senha vindos da configuração ou da variável de ambiente, um proxy com reconhecimento de identidade no modo trusted-proxy (proxies de loopback no mesmo host precisam de allowLoopback) ou nenhum cabeçalho em ingress privado; chamadores no mesmo host que contornam um proxy confiável podem recorrer à senha, a menos que evidências de cabeçalhos encaminhados os mantenham no caminho do proxy, e tentativas malsucedidas demais retornam 429 com Retry-After quando há um limite de taxa configurado.
• A documentação prefere esse endpoint a um novo canal integrado quando a integração é só mais uma superfície de operador, prefere o WebChat ou o protocolo do gateway com o fluxo de dispositivo pareado para clientes móveis nativos, para que nenhum token compartilhado vá embarcado no dispositivo, e um plugin de canal ao integrar uma rede de mensagens externa com seus próprios usuários, salas e transporte.

O OpenClaw trata o campo model da OpenAI como um alvo de agente, e não como um id bruto de modelo de provedor.

Modelos são agentes, sessões vêm de user

openclaw e openclaw/default roteiam para o agente padrão configurado, openclaw/ seguido do id do agente, ou agent: seguido dele, para um agente específico, e /v1/models lista esses alvos de agente, não modelos de provedor nem subagentes. O cabeçalho x-openclaw-model substitui o modelo de backend do agente selecionado, diretamente para chamadores com segredo compartilhado e só com operator.admin para os que carregam identidade; x-openclaw-session-key roteia explicitamente e é rejeitado com um 400 quando usa um namespace reservado como subagent, cron ou acp; x-openclaw-message-channel define um canal de entrada sintético para prompts sensíveis ao canal. Por padrão, cada requisição é sem estado, com uma chave de sessão nova; uma string user da OpenAI deriva uma chave estável para que chamadas repetidas compartilhem uma sessão, então reutilize um valor por thread de conversa e evite identificadores de nível de conta, a menos que vários dispositivos devam compartilhar uma sessão. Continuar explicitamente uma sessão incognito exige operator.admin efetivo, e a resposta baseada em perfil esconde o alvo como um erro forbidden do tipo não encontrado.

Ferramentas, limites e streaming

• Ferramentas de função e tool_choice (auto, none, required ou uma função fixada) são suportados, com mensagens de acompanhamento de papel tool vinculadas por tool_call_id; max_completion_tokens é o limite atual, com max_tokens como alias legado, e temperature, top_p, as penalidades, seed e até quatro sequências stop são validados e depois repassados na base do melhor esforço, com os nomes no protocolo escolhidos pelo transporte do provedor.
• As requisições são limitadas a 20 MB de corpo, 8 partes image_url da última mensagem do usuário e 20 MB de dados de imagem decodificados; imagens vindas de URL são rejeitadas, a menos que images.allowUrl esteja ativado, com uma lista de permissões de hosts, tipos MIME permitidos, 10 MB por imagem, 3 redirecionamentos e um tempo limite de 10 s por padrão, HEIC e HEIF normalizados para JPEG, e um nome de host na lista de permissões nunca contorna o bloqueio de IPs privados.
• Com stream em true, os eventos chegam como linhas data terminadas em DONE, as chamadas de ferramenta como fragmentos delta incrementais seguidos de um motivo de término tool_calls, e um fragmento de uso quando include_usage está definido; uma execução com falha retorna um erro em vez de uma completion, uma falha no streaming emite um objeto error seguido de DONE, e um cliente que se desconecta cancela os downloads de origem e a execução do agente.

A API do OpenClaw é o artigo mais amplo sobre a API do gateway, e escopos de operador do OpenClaw explica o conjunto de escopos de operador que esse endpoint restaura ou restringe.

A receita do Open WebUI

A configuração rápida é uma URL base com o host e a porta do gateway mais /v1 (host.docker.internal a partir do Docker no macOS), o token bearer do gateway como chave de API e openclaw/default como modelo; se um curl de /v1/models com o bearer retornar openclaw/default, a maioria das instalações do Open WebUI se conecta com a mesma URL base e o mesmo token. Os exemplos mostram então uma sessão estável com um valor user prefixado com conv, uma chamada de streaming com x-openclaw-model fixando um modelo de provedor, a busca de um único modelo com a barra codificada na URL, e embeddings com um modelo de embedding no cabeçalho e um inteiro dimensions opcional que substitui a dimensionalidade de saída da memória do agente. Acesso remoto ao OpenClaw cobre como alcançar a porta com segurança, e controles de segurança do gateway do OpenClaw, os controles que a protegem.

Na Diali

Na Diali, o gateway fica atrás do ingress da plataforma, com a configuração de execução gerada a partir do painel, então expor essa superfície é uma decisão de configuração, e não uma porta a abrir. OpenClaw hospedado na Diali descreve o assistente hospedado, e a página de preços da Diali, os planos em que ele vem incluído.

• Desativada por padrão; ativada, um token é acesso de proprietário.
• O campo model nomeia um agente; user nomeia a sessão.
• Loopback, tailnet ou ingress privado, nunca a internet pública.