Pular para o conteúdo principal

​
OpenAI

A OpenAI fornece APIs para desenvolvedores para modelos GPT. O OpenClaw oferece suporte a duas rotas de auth:
  • Chave de API — acesso direto à OpenAI Platform com cobrança baseada em uso (modelos openai/*)
  • Assinatura do Codex — login no ChatGPT/Codex com acesso por assinatura (modelos openai-codex/*)
A OpenAI oferece suporte explicitamente ao uso de OAuth de assinatura em ferramentas e fluxos de trabalho externos como o OpenClaw.

​
Primeiros passos

Escolha seu método de auth preferido e siga as etapas de configuração.
Ideal para: acesso direto à API e cobrança baseada em uso.
1

Obtenha sua chave de API

Crie ou copie uma chave de API no painel da OpenAI Platform.
2

Execute o onboarding

openclaw onboard --auth-choice openai-api-key
Ou passe a chave diretamente:
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
3

Verifique se o modelo está disponível

openclaw models list --provider openai

​
Resumo da rota

Model refRotaAuth
openai/gpt-5.4API direta da OpenAI PlatformOPENAI_API_KEY
openai/gpt-5.4-proAPI direta da OpenAI PlatformOPENAI_API_KEY
O login do ChatGPT/Codex é roteado por openai-codex/*, não por openai/*.

​
Exemplo de configuração

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}
O OpenClaw não expõe openai/gpt-5.3-codex-spark no caminho direto da API. Solicitações ao vivo para a API da OpenAI rejeitam esse modelo. Spark é exclusivo do Codex.

​
Geração de imagem

O plugin openai integrado registra a geração de imagem por meio da ferramenta image_generate.
CapacidadeValor
Modelo padrãoopenai/gpt-image-1
Máximo de imagens por solicitação4
Modo de ediçãoAtivado (até 5 imagens de referência)
Substituições de tamanhoCompatíveis
Proporção / resoluçãoNão encaminhadas para a OpenAI Images API
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-1" },
    },
  },
}
Consulte Geração de imagem para ver parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.

​
Geração de vídeo

O plugin openai integrado registra a geração de vídeo por meio da ferramenta video_generate.
CapacidadeValor
Modelo padrãoopenai/sora-2
ModosTexto para vídeo, imagem para vídeo, edição de um único vídeo
Entradas de referência1 imagem ou 1 vídeo
Substituições de tamanhoCompatíveis
Outras substituiçõesaspectRatio, resolution, audio, watermark são ignorados com um aviso da ferramenta
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
Consulte Geração de vídeo para ver parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.

​
Overlay de personalidade

O OpenClaw adiciona um pequeno overlay de prompt específico da OpenAI para execuções openai/* e openai-codex/*. O overlay mantém o assistente caloroso, colaborativo, conciso e um pouco mais expressivo emocionalmente, sem substituir o prompt base do sistema.
ValorEfeito
"friendly" (padrão)Ativa o overlay específico da OpenAI
"on"Alias para "friendly"
"off"Usa apenas o prompt base do OpenClaw
{
  plugins: {
    entries: {
      openai: { config: { personality: "friendly" } },
    },
  },
}
Os valores não diferenciam maiúsculas de minúsculas em tempo de execução, então "Off" e "off" desativam o overlay.

​
Voz e fala

O plugin openai integrado registra síntese de fala para a superfície messages.tts.
SettingCaminho de configuraçãoPadrão
Modelomessages.tts.providers.openai.modelgpt-4o-mini-tts
Vozmessages.tts.providers.openai.voicecoral
Velocidademessages.tts.providers.openai.speed(não definido)
Instruçõesmessages.tts.providers.openai.instructions(não definido, apenas gpt-4o-mini-tts)
Formatomessages.tts.providers.openai.responseFormatopus para notas de voz, mp3 para arquivos
Chave de APImessages.tts.providers.openai.apiKeyUsa fallback para OPENAI_API_KEY
Base URLmessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
Modelos disponíveis: gpt-4o-mini-tts, tts-1, tts-1-hd. Vozes disponíveis: alloy, ash, ballad, cedar, coral, echo, fable, juniper, marin, onyx, nova, sage, shimmer, verse.
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}
Defina OPENAI_TTS_BASE_URL para substituir a base URL de TTS sem afetar o endpoint da API de chat.
O plugin openai integrado registra transcrição em tempo real para o Plugin Voice Call.
SettingCaminho de configuraçãoPadrão
Modeloplugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
Duração do silêncio...openai.silenceDurationMs800
Limiar de VAD...openai.vadThreshold0.5
Chave de API...openai.apiKeyUsa fallback para OPENAI_API_KEY
Usa uma conexão WebSocket com wss://api.openai.com/v1/realtime com áudio G.711 u-law.
O plugin openai integrado registra voz em tempo real para o Plugin Voice Call.
SettingCaminho de configuraçãoPadrão
Modeloplugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime
Voz...openai.voicealloy
Temperatura...openai.temperature0.8
Limiar de VAD...openai.vadThreshold0.5
Duração do silêncio...openai.silenceDurationMs500
Chave de API...openai.apiKeyUsa fallback para OPENAI_API_KEY
Compatível com Azure OpenAI por meio das chaves de configuração azureEndpoint e azureDeployment. Compatível com chamada de ferramentas bidirecional. Usa formato de áudio G.711 u-law.

​
Configuração avançada

O OpenClaw usa WebSocket primeiro com fallback para SSE ("auto") tanto para openai/* quanto para openai-codex/*.No modo "auto", o OpenClaw:
  • Tenta novamente uma falha inicial de WebSocket antes de usar fallback para SSE
  • Após uma falha, marca o WebSocket como degradado por ~60 segundos e usa SSE durante o período de resfriamento
  • Anexa cabeçalhos estáveis de identidade de sessão e turno para novas tentativas e reconexões
  • Normaliza contadores de uso (input_tokens / prompt_tokens) entre variantes de transporte
ValorComportamento
"auto" (padrão)WebSocket primeiro, fallback para SSE
"sse"Força apenas SSE
"websocket"Força apenas WebSocket
{
  agents: {
    defaults: {
      models: {
        "openai-codex/gpt-5.4": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
Documentação relacionada da OpenAI:
O OpenClaw ativa o aquecimento de WebSocket por padrão para openai/* para reduzir a latência do primeiro turno.
// Desativar aquecimento
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}
O OpenClaw expõe uma alternância compartilhada de modo rápido para openai/* e openai-codex/*:
  • Chat/UI: /fast status|on|off
  • Config: agents.defaults.models["<provider>/<model>"].params.fastMode
Quando ativado, o OpenClaw mapeia o modo rápido para processamento prioritário da OpenAI (service_tier = "priority"). Valores existentes de service_tier são preservados, e o modo rápido não reescreve reasoning nem text.verbosity.
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { fastMode: true } },
        "openai-codex/gpt-5.4": { params: { fastMode: true } },
      },
    },
  },
}
Substituições no nível da sessão têm prioridade sobre a configuração. Limpar a substituição da sessão na UI de Sessions faz a sessão voltar ao padrão configurado.
A API da OpenAI expõe processamento prioritário por meio de service_tier. Defina isso por modelo no OpenClaw:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { serviceTier: "priority" } },
        "openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
      },
    },
  },
}
Valores compatíveis: auto, default, flex, priority.
serviceTier só é encaminhado para endpoints nativos da OpenAI (api.openai.com) e endpoints nativos do Codex (chatgpt.com/backend-api). Se você rotear qualquer um dos provedores por um proxy, o OpenClaw deixará service_tier intacto.
Para modelos Responses diretos da OpenAI (openai/* em api.openai.com), o OpenClaw ativa automaticamente Compaction no lado do servidor:
  • Força store: true (a menos que a compatibilidade do modelo defina supportsStore: false)
  • Injeta context_management: [{ type: "compaction", compact_threshold: ... }]
  • compact_threshold padrão: 70% de contextWindow (ou 80000 quando indisponível)
Útil para endpoints compatíveis como Azure OpenAI Responses:
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
responsesServerCompaction controla apenas a injeção de context_management. Modelos Responses diretos da OpenAI ainda forçam store: true, a menos que a compatibilidade defina supportsStore: false.
Para execuções da família GPT-5 em openai/* e openai-codex/*, o OpenClaw pode usar um contrato de execução embutido mais estrito:
{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}
Com strict-agentic, o OpenClaw:
  • Não trata mais um turno apenas com plano como progresso bem-sucedido quando há uma ação de ferramenta disponível
  • Tenta novamente o turno com uma orientação para agir agora
  • Ativa automaticamente update_plan para trabalho substancial
  • Expõe um estado explícito de bloqueio se o modelo continuar planejando sem agir
Escopo apenas para execuções da família GPT-5 da OpenAI e do Codex. Outros provedores e famílias de modelos mais antigas mantêm o comportamento padrão.
O OpenClaw trata endpoints diretos da OpenAI, Codex e Azure OpenAI de forma diferente de proxies genéricos compatíveis com OpenAI em /v1:Rotas nativas (openai/*, openai-codex/*, Azure OpenAI):
  • Mantêm reasoning: { effort: "none" } intacto quando o raciocínio está explicitamente desativado
  • Usam por padrão esquemas de ferramentas em modo estrito
  • Anexam cabeçalhos ocultos de atribuição apenas em hosts nativos verificados
  • Mantêm a formatação de solicitação exclusiva da OpenAI (service_tier, store, compatibilidade de reasoning, dicas de cache de prompt)
Rotas de proxy/compatíveis:
  • Usam comportamento de compatibilidade mais flexível
  • Não forçam esquemas de ferramentas estritos nem cabeçalhos exclusivos nativos
O Azure OpenAI usa transporte nativo e comportamento de compatibilidade nativa, mas não recebe os cabeçalhos ocultos de atribuição.

​
Relacionado

Seleção de modelo

Escolha de provedores, refs de modelo e comportamento de failover.

Geração de imagem

Parâmetros compartilhados da ferramenta de imagem e seleção de provedor.

Geração de vídeo

Parâmetros compartilhados da ferramenta de vídeo e seleção de provedor.

OAuth e auth

Detalhes de auth e regras de reutilização de credenciais.