Conclusões de chat da OpenAI

OpenClaw’s Gateway pode servir um pequeno endpoint de Chat Completions compatível com OpenAI. Este endpoint é desabilitado por padrão. Habilite-o primeiro na configuração.

POST /v1/chat/completions
Mesma porta que o Gateway (multiplex WS + HTTP): http://<gateway-host>:<port>/v1/chat/completions

Quando a superfície HTTP compatível com OpenAI do Gateway está habilitada, ela também serve:

GET /v1/models
GET /v1/models/{id}
POST /v1/embeddings
POST /v1/responses

Por baixo dos panos, as requisições são executadas como uma execução normal de agente do Gateway (mesmo caminho de código que openclaw agent), então roteamento/permissões/configuração correspondem ao seu Gateway.

Autenticação

Usa a configuração de autenticação do Gateway. Caminhos comuns de autenticação HTTP:

autenticação por segredo compartilhado (gateway.auth.mode="token" ou "password"): Authorization: Bearer <token-or-password>
autenticação HTTP confiável com identidade (gateway.auth.mode="trusted-proxy"): roteie pelo proxy configurado com reconhecimento de identidade e deixe-o injetar os cabeçalhos de identidade necessários
autenticação aberta em ingresso privado (gateway.auth.mode="none"): nenhum cabeçalho de autenticação necessário

Observações:

Quando gateway.auth.mode="token", use gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN).
Quando gateway.auth.mode="password", use gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
Quando gateway.auth.mode="trusted-proxy", a requisição HTTP deve vir de uma origem de proxy confiável configurada; proxies local loopback no mesmo host exigem gateway.auth.trustedProxy.allowLoopback = true explícito.
Se gateway.auth.rateLimit estiver configurado e ocorrerem falhas demais de autenticação, o endpoint retorna 429 com Retry-After.

Limite de segurança (importante)

Trate este endpoint como uma superfície de acesso completo de operador para a instância do Gateway.

A autenticação bearer HTTP aqui não é um modelo de escopo restrito por usuário.
Um token/senha válido do Gateway para este endpoint deve ser tratado como uma credencial de proprietário/operador.
As requisições passam pelo mesmo caminho de agente do plano de controle que ações de operador confiáveis.
Não há um limite separado de ferramenta por usuário/não proprietário neste endpoint; depois que um chamador passa pela autenticação do Gateway aqui, o OpenClaw trata esse chamador como um operador confiável para este Gateway.
Para modos de autenticação por segredo compartilhado (token e password), o endpoint restaura os padrões normais completos de operador mesmo que o chamador envie um cabeçalho x-openclaw-scopes mais restrito.
Modos HTTP confiáveis com identidade (por exemplo, autenticação por proxy confiável ou gateway.auth.mode="none") respeitam x-openclaw-scopes quando presente e, caso contrário, recorrem ao conjunto de escopos padrão normal de operador.
Se a política do agente de destino permitir ferramentas sensíveis, este endpoint pode usá-las.
Mantenha este endpoint apenas em loopback/tailnet/ingresso privado; não o exponha diretamente à internet pública.

Matriz de autenticação:

gateway.auth.mode="token" ou "password" + Authorization: Bearer ...
- prova posse do segredo compartilhado de operador do Gateway
- ignora x-openclaw-scopes mais restrito
- restaura o conjunto completo de escopos padrão de operador: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
- trata turnos de chat neste endpoint como turnos de remetente proprietário
modos HTTP confiáveis com identidade (por exemplo, autenticação por proxy confiável ou gateway.auth.mode="none" em ingresso privado)
- autenticam alguma identidade confiável externa ou limite de implantação
- respeitam x-openclaw-scopes quando o cabeçalho está presente
- recorrem ao conjunto de escopos padrão normal de operador quando o cabeçalho está ausente
- só perdem semântica de proprietário quando o chamador restringe escopos explicitamente e omite operator.admin

Consulte Segurança e Acesso remoto.

Contrato de modelo centrado em agente

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

model: "openclaw" roteia para o agente padrão configurado.
model: "openclaw/default" também roteia para o agente padrão configurado.
model: "openclaw/<agentId>" roteia para um agente específico.

Cabeçalhos de requisição opcionais:

x-openclaw-model: <provider/model-or-bare-id> substitui o modelo de backend para o agente selecionado.
x-openclaw-agent-id: <agentId> continua com suporte como substituição de compatibilidade.
x-openclaw-session-key: <sessionKey> controla totalmente o roteamento de sessão.
x-openclaw-message-channel: <channel> define o contexto sintético de canal de ingresso para prompts e políticas com reconhecimento de canal.

Aliases de compatibilidade ainda aceitos:

model: "openclaw:<agentId>"
model: "agent:<agentId>"

Habilitando o endpoint

Defina gateway.http.endpoints.chatCompletions.enabled como true:

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}

Desabilitando o endpoint

Defina gateway.http.endpoints.chatCompletions.enabled como false:

{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: false },
      },
    },
  },
}

Comportamento de sessão

Por padrão, o endpoint é sem estado por requisição (uma nova chave de sessão é gerada em cada chamada). Se a requisição incluir uma string user da OpenAI, o Gateway deriva uma chave de sessão estável a partir dela, então chamadas repetidas podem compartilhar uma sessão de agente.

Por que esta superfície importa

Este é o conjunto de compatibilidade de maior impacto para frontends e ferramentas auto-hospedados:

A maioria das configurações do Open WebUI, LobeChat e LibreChat espera /v1/models.
Muitos sistemas RAG esperam /v1/embeddings.
Clientes de chat existentes da OpenAI geralmente podem começar com /v1/chat/completions.
Clientes mais nativos de agente preferem cada vez mais /v1/responses.

Lista de modelos e roteamento de agente

What does `/v1/models` return?

Uma lista de destinos de agente do OpenClaw.Os ids retornados são entradas openclaw, openclaw/default e openclaw/<agentId>. Use-os diretamente como valores de model da OpenAI.

Does `/v1/models` list agents or sub-agents?

Ele lista destinos de agente de nível superior, não modelos de provedor de backend e nem subagentes.Subagentes permanecem como topologia interna de execução. Eles não aparecem como pseudo-modelos.

Why is `openclaw/default` included?

openclaw/default é o alias estável para o agente padrão configurado.Isso significa que clientes podem continuar usando um id previsível mesmo que o id real do agente padrão mude entre ambientes.

How do I override the backend model?

Use x-openclaw-model.Exemplos: x-openclaw-model: openai/gpt-5.4 x-openclaw-model: gpt-5.5Se você o omitir, o agente selecionado será executado com sua escolha normal de modelo configurada.

How do embeddings fit this contract?

/v1/embeddings usa os mesmos ids de model de destino de agente.Use model: "openclaw/default" ou model: "openclaw/<agentId>". Quando precisar de um modelo específico de embeddings, envie-o em x-openclaw-model. Sem esse cabeçalho, a requisição passa para a configuração normal de embeddings do agente selecionado.

Streaming (SSE)

Defina stream: true para receber Server-Sent Events (SSE):

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

Contrato de ferramentas de chat

/v1/chat/completions oferece suporte a um subconjunto de ferramentas de função compatível com clientes comuns do OpenAI Chat.

Campos de requisição com suporte

tools: array de { "type": "function", "function": { ... } }
tool_choice: "auto", "none"
messages[*].role: "tool" turnos de acompanhamento
messages[*].tool_call_id para vincular resultados de ferramenta a uma chamada de ferramenta anterior
max_completion_tokens: número; limite por chamada para o total de tokens de conclusão (incluindo tokens de raciocínio). Nome atual do campo de Chat Completions da OpenAI; preferido quando max_completion_tokens e max_tokens são enviados.
max_tokens: número; alias legado aceito para compatibilidade retroativa. Ignorado quando max_completion_tokens também está presente.

Quando qualquer um dos campos é definido, o valor é encaminhado ao provedor upstream pelo canal de parâmetros de stream do agente. O nome real do campo no fio enviado ao provedor upstream é escolhido pelo transporte do provedor: max_completion_tokens para endpoints da família OpenAI, e max_tokens para provedores que aceitam apenas o nome legado (como Mistral e Chutes).

Variantes sem suporte

O endpoint retorna 400 invalid_request_error para variantes de ferramentas sem suporte, incluindo:

tools que não seja array
entradas de ferramenta que não sejam função
tool.function.name ausente
variantes de tool_choice como allowed_tools e custom
tool_choice: "required" (ainda não imposto em tempo de execução; terá suporte quando a imposição rígida for implementada)
tool_choice: { "type": "function", "function": { "name": "..." } } (mesma justificativa que required)
valores de tool_choice.function.name que não correspondem aos tools fornecidos

Formato de resposta de ferramenta sem streaming

Quando o agente decide chamar ferramentas, a resposta usa:

choices[0].finish_reason = "tool_calls"
entradas choices[0].message.tool_calls[] com:
- id
- type: "function"
- function.name
- function.arguments (string JSON)

Comentário do assistente antes da chamada de ferramenta é retornado em choices[0].message.content (possivelmente vazio).

Formato de resposta de ferramenta com streaming

Quando stream: true, chamadas de ferramenta são emitidas como chunks SSE incrementais:

delta inicial de função do assistente
deltas opcionais de comentário do assistente
um ou mais chunks delta.tool_calls carregando identidade da ferramenta e fragmentos de argumentos
chunk final com finish_reason: "tool_calls"
data: [DONE]

Se stream_options.include_usage=true, um chunk final de uso é emitido antes de [DONE].

Loop de acompanhamento de ferramenta

Após receber tool_calls, o cliente deve executar as funções solicitadas e enviar uma requisição de acompanhamento que inclua:

mensagem anterior de chamada de ferramenta do assistente
uma ou mais mensagens role: "tool" com tool_call_id correspondente

Isso permite que a execução do agente do Gateway continue o mesmo loop de raciocínio e produza a resposta final do assistente.

Configuração rápida do Open WebUI

Para uma conexão básica do Open WebUI:

URL base: http://127.0.0.1:18789/v1
URL base do Docker no macOS: http://host.docker.internal:18789/v1
Chave de API: seu token bearer do Gateway
Modelo: openclaw/default

Comportamento esperado:

GET /v1/models deve listar openclaw/default
O Open WebUI deve usar openclaw/default como o id de modelo de chat
Se quiser um provedor/modelo de backend específico para esse agente, defina o modelo padrão normal do agente ou envie x-openclaw-model

Smoke rápido:

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

Se isso retornar openclaw/default, a maioria das configurações do Open WebUI pode se conectar com a mesma URL base e token.

Exemplos

Sem streaming:

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "messages": [{"role":"user","content":"hi"}]
  }'

Com streaming:

curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/gpt-5.4' \
  -d '{
    "model": "openclaw/research",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'

Listar modelos:

curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

Buscar um modelo:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \
  -H 'Authorization: Bearer YOUR_TOKEN'

Criar embeddings:

curl -sS http://127.0.0.1:18789/v1/embeddings \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/text-embedding-3-small' \
  -d '{
    "model": "openclaw/default",
    "input": ["alpha", "beta"]
  }'

Observações:

/v1/models retorna destinos de agentes do OpenClaw, não catálogos brutos de provedores.
openclaw/default está sempre presente para que um ID estável funcione em todos os ambientes.
Substituições de provedor/modelo de back-end pertencem a x-openclaw-model, não ao campo model da OpenAI.
/v1/embeddings aceita input como uma cadeia de caracteres ou uma matriz de cadeias de caracteres.

Gateway

Remote access

Security

Nodes and media

Web interfaces

Conclusões de chat da OpenAI

Autenticação

Limite de segurança (importante)

Contrato de modelo centrado em agente

Habilitando o endpoint

Desabilitando o endpoint

Comportamento de sessão

Por que esta superfície importa

Lista de modelos e roteamento de agente

Streaming (SSE)

Contrato de ferramentas de chat

Campos de requisição com suporte

Variantes sem suporte

Formato de resposta de ferramenta sem streaming

Formato de resposta de ferramenta com streaming

Loop de acompanhamento de ferramenta

Configuração rápida do Open WebUI

Exemplos

Relacionado

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​Autenticação

​Limite de segurança (importante)

​Contrato de modelo centrado em agente

​Habilitando o endpoint

​Desabilitando o endpoint

​Comportamento de sessão

​Por que esta superfície importa

​Lista de modelos e roteamento de agente

​Streaming (SSE)

​Contrato de ferramentas de chat

​Campos de requisição com suporte

​Variantes sem suporte

​Formato de resposta de ferramenta sem streaming

​Formato de resposta de ferramenta com streaming

​Loop de acompanhamento de ferramenta

​Configuração rápida do Open WebUI

​Exemplos

​Relacionado

Autenticação

Limite de segurança (importante)

Contrato de modelo centrado em agente

Habilitando o endpoint

Desabilitando o endpoint

Comportamento de sessão

Por que esta superfície importa

Lista de modelos e roteamento de agente

Streaming (SSE)

Contrato de ferramentas de chat

Campos de requisição com suporte

Variantes sem suporte

Formato de resposta de ferramenta sem streaming

Formato de resposta de ferramenta com streaming

Loop de acompanhamento de ferramenta

Configuração rápida do Open WebUI

Exemplos

Relacionado