OpenAI

OpenAI fornece APIs de desenvolvedor para modelos GPT, e o Codex também está disponível como um agente de programação em planos ChatGPT por meio dos clientes Codex da OpenAI. O OpenClaw usa um único id de provedor, openai, para ambos os formatos de autenticação.

O OpenClaw usa openai/* como a rota canônica de modelos OpenAI. Turnos de agente embutidos em modelos OpenAI são executados por padrão pelo runtime nativo do servidor de aplicativo Codex; a autenticação direta por chave de API da OpenAI continua disponível para superfícies OpenAI que não são de agente, como imagens, embeddings, fala e realtime.

• Modelos de agente - modelos openai/* por meio do runtime Codex; entre com autenticação Codex para uso de assinatura ChatGPT/Codex, ou configure um backup de chave de API da OpenAI compatível com Codex quando você quiser intencionalmente autenticação por chave de API.
• APIs OpenAI que não são de agente - acesso direto à OpenAI Platform com cobrança baseada em uso por meio de OPENAI_API_KEY ou onboarding por chave de API da OpenAI.
• Configuração legada - refs de modelo Codex legadas são reparadas por openclaw doctor --fix para openai/* mais o runtime Codex.

A OpenAI oferece suporte explícito ao uso de OAuth de assinatura em ferramentas e fluxos de trabalho externos como o OpenClaw.

Provedor, modelo, runtime e canal são camadas separadas. Se esses rótulos estiverem se misturando, leia Runtimes de agente antes de alterar a configuração.

Escolha rápida

Mapa de nomes

Os nomes são parecidos, mas não são intercambiáveis:

Isso significa que uma configuração pode conter intencionalmente refs de modelo openai/* enquanto os perfis de autenticação apontam para credenciais de chave de API ou OAuth ChatGPT/Codex. Use auth.order.openai para configuração; openclaw doctor --fix reescreve refs de modelo Codex legadas, ids de perfil de autenticação Codex legados e ordem de autenticação Codex legada para a rota canônica da OpenAI.

Preview limitado do GPT-5.6

O OpenClaw reconhece os três ids públicos de modelo GPT-5.6:

• openai/gpt-5.6-sol
• openai/gpt-5.6-terra
• openai/gpt-5.6-luna

Todos os três expõem raciocínio max no catálogo atual do servidor de aplicativo Codex. O anúncio de lançamento da OpenAI descreve Sol como o nível flagship, Terra como o nível balanceado e Luna como o nível rápido e de menor custo. Consulte o anúncio de lançamento do GPT-5.6 e o guia de acesso ao preview.

O acesso é por allowlist durante o preview e pode ser concedido separadamente para a API e o Codex. Um plano pago do ChatGPT sozinho não concede acesso. O OpenClaw mantém openai/gpt-5.5 como padrão; selecionar uma ref GPT-5.6 sem acesso retorna o erro de acesso upstream em vez de fazer fallback silenciosamente.

Cobertura de recursos do OpenClaw

Embeddings de memória

O OpenClaw pode usar a OpenAI, ou um endpoint de embeddings compatível com OpenAI, para indexação de memory_search e embeddings de consulta:

{  agents: {    defaults: {      memorySearch: {        provider: "openai",        model: "text-embedding-3-small",      },    },  },}

Para endpoints compatíveis com OpenAI que exigem rótulos de embedding assimétricos, defina queryInputType e documentInputType em memorySearch. O OpenClaw os encaminha como campos de solicitação input_type específicos do provedor: embeddings de consulta usam queryInputType; blocos de memória indexados e indexação em lote usam documentInputType. Consulte a referência de configuração de memória para o exemplo completo.

Introdução

Escolha seu método de autenticação preferido e siga as etapas de configuração.

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

openclaw models auth login --provider openai --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.5

openclaw models list --provider openai

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

{  models: {    providers: {      openai: {        models: [{ id: "gpt-5.5", contextTokens: 160000 }],      },    },  },}

Autenticação nativa do app-server Codex

O harness app-server Codex nativo usa referências de modelo openai/* mais configuração de runtime omitida ou agentRuntime.id: "codex" de provedor/modelo, mas sua autenticação ainda é baseada em conta. OpenClaw seleciona a autenticação nesta ordem:

1. Perfis ordenados de autenticação OpenAI para o agente, preferencialmente em auth.order.openai. Execute openclaw doctor --fix para migrar ids de perfil de autenticação Codex legados mais antigos e a ordem legada de autenticação Codex.
2. A conta existente do app-server, como um login local ChatGPT do CLI Codex.
3. Somente para inicializações locais do app-server por stdio, CODEX_API_KEY, depois OPENAI_API_KEY, quando o app-server não relata nenhuma conta e ainda exige autenticação OpenAI.

Isso significa que um login local de assinatura ChatGPT/Codex não é substituído apenas porque o processo do Gateway também tem OPENAI_API_KEY para modelos OpenAI diretos ou embeddings. O fallback de chave de API por env é apenas o caminho local stdio sem conta; ele não é enviado para conexões WebSocket do app-server. Quando um perfil Codex no estilo assinatura é selecionado, OpenClaw também mantém CODEX_API_KEY e OPENAI_API_KEY fora do filho app-server stdio iniciado e envia as credenciais selecionadas pela RPC de login do app-server. Quando esse perfil de assinatura é bloqueado por um limite de uso do Codex, OpenClaw pode alternar para o próximo perfil de chave de API openai:* ordenado sem alterar o modelo selecionado nem sair do harness Codex. Depois que o horário de redefinição da assinatura passa, o perfil de assinatura fica elegível novamente.

Geração de imagens

O Plugin openai incluído registra a geração de imagens pela ferramenta image_generate. Ele oferece suporte tanto à geração de imagens com chave de API OpenAI quanto à geração de imagens com OAuth do Codex pela mesma referência de modelo openai/gpt-image-2.

{  agents: {    defaults: {      imageGenerationModel: { primary: "openai/gpt-image-2" },    },  },}

gpt-image-2 é o padrão tanto para geração de texto para imagem da OpenAI quanto para edição de imagens. gpt-image-1.5, gpt-image-1 e gpt-image-1-mini continuam utilizáveis como substituições explícitas de modelo. Use openai/gpt-image-1.5 para saída PNG/WebP com fundo transparente; a API atual gpt-image-2 rejeita background: "transparent".

Para uma solicitação com fundo transparente, agentes devem chamar image_generate com model: "openai/gpt-image-1.5", outputFormat: "png" ou "webp" e background: "transparent"; a opção de provedor openai.background mais antiga ainda é aceita. O OpenClaw também protege as rotas públicas da OpenAI e do OAuth do OpenAI Codex reescrevendo solicitações transparentes padrão de openai/gpt-image-2 para gpt-image-1.5; endpoints Azure e personalizados compatíveis com OpenAI mantêm seus nomes configurados de implantação/modelo.

A mesma configuração é exposta para execuções CLI sem interface:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "A simple red circle sticker on a transparent background" \  --json

Use as mesmas flags --output-format e --background com openclaw infer image edit ao partir de um arquivo de entrada. --openai-background continua disponível como um alias específico da OpenAI. Use --quality low|medium|high|auto quando precisar controlar a qualidade e o custo do OpenAI Images. Use --openai-moderation low|auto para passar a dica de moderação específica do provedor da OpenAI a partir de image generate ou image edit.

Para instalações OAuth do ChatGPT/Codex, mantenha a mesma ref. openai/gpt-image-2. Quando um perfil OAuth openai está configurado, o OpenClaw resolve esse token de acesso OAuth armazenado e envia solicitações de imagem pelo backend Responses do Codex. Ele não tenta primeiro OPENAI_API_KEY nem recorre silenciosamente a uma chave de API para essa solicitação. Configure models.providers.openai explicitamente com uma chave de API, URL base personalizada ou endpoint Azure quando quiser a rota direta da API de Imagens da OpenAI. Se esse endpoint de imagem personalizado estiver em uma LAN/endereço privado confiável, também defina browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; o OpenClaw mantém endpoints de imagem privados/internos compatíveis com OpenAI bloqueados a menos que essa adesão explícita esteja presente.

Gerar:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

Gerar um PNG transparente:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

Editar:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

Geração de vídeo

O Plugin openai integrado registra geração de vídeo por meio da ferramenta video_generate.

Solicitações de imagem para vídeo da OpenAI usam POST /v1/videos com uma imagem input_reference. Edições de vídeo único usam POST /v1/videos/edits com o vídeo enviado no campo video.

{  agents: {    defaults: {      videoGenerationModel: { primary: "openai/sora-2" },    },  },}

Contribuição de prompt GPT-5

O OpenClaw adiciona uma contribuição compartilhada de prompt GPT-5 para execuções da família GPT-5 em superfícies de prompt montadas pelo OpenClaw. Ela se aplica por id de modelo, então rotas OpenClaw/provedor como refs legadas pré-reparo (ref legada GPT-5.5 do Codex), openrouter/openai/gpt-5.5, opencode/gpt-5.5 e outras refs GPT-5 compatíveis recebem a mesma sobreposição. Modelos GPT-4.x mais antigos não recebem.

O harness Codex nativo integrado não recebe essa sobreposição GPT-5 do OpenClaw por meio das instruções de desenvolvedor do servidor de app do Codex. O Codex nativo mantém o comportamento de base, modelo e documentos de projeto pertencente ao Codex, enquanto o OpenClaw desabilita a personalidade integrada do Codex para threads nativas para que os arquivos de personalidade do workspace do agente permaneçam autoritativos. O OpenClaw contribui apenas contexto de runtime, como entrega por canal, ferramentas dinâmicas do OpenClaw, delegação ACP, contexto do workspace e Skills do OpenClaw.

A contribuição GPT-5 adiciona um contrato de comportamento marcado para persistência de persona, segurança de execução, disciplina de ferramentas, formato de saída, verificações de conclusão e verificação em prompts montados pelo OpenClaw correspondentes. O comportamento de resposta específico do canal e de mensagem silenciosa permanece no prompt de sistema compartilhado do OpenClaw e na política de entrega de saída. A camada de estilo de interação amigável é separada e configurável.

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

Voz e fala

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

Endpoints do Azure OpenAI

O provedor openai integrado pode apontar para um recurso do Azure OpenAI para geração de imagens substituindo a URL base. No caminho de geração de imagens, o OpenClaw detecta nomes de host do Azure em models.providers.openai.baseUrl e alterna para o formato de solicitação do Azure automaticamente.

Use o Azure OpenAI quando:

• Você já tiver uma assinatura, cota ou contrato empresarial do Azure OpenAI
• Você precisar de residência regional de dados ou controles de conformidade fornecidos pelo Azure
• Você quiser manter o tráfego dentro de uma tenancy existente do Azure

Configuração

Para geração de imagens no Azure por meio do provedor openai integrado, aponte models.providers.openai.baseUrl para seu recurso do Azure e defina apiKey como a chave do Azure OpenAI (não uma chave da OpenAI Platform):

{  models: {    providers: {      openai: {        baseUrl: "https://<your-resource>.openai.azure.com",        apiKey: "<azure-openai-api-key>",      },    },  },}

O OpenClaw reconhece estes sufixos de host do Azure para a rota de geração de imagens do Azure:

• *.openai.azure.com
• *.services.ai.azure.com
• *.cognitiveservices.azure.com

Para solicitações de geração de imagens em um host reconhecido do Azure, o OpenClaw:

• Envia o cabeçalho api-key em vez de Authorization: Bearer
• Usa caminhos com escopo de implantação (/openai/deployments/{deployment}/...)
• Acrescenta ?api-version=... a cada solicitação
• Usa um tempo limite padrão de solicitação de 600s para chamadas de geração de imagens do Azure. Valores timeoutMs por chamada ainda substituem esse padrão.

Outras URLs base (OpenAI pública, proxies compatíveis com OpenAI) mantêm o formato padrão de solicitação de imagem da OpenAI.

Versão da API

Defina AZURE_OPENAI_API_VERSION para fixar uma versão preview ou GA específica do Azure para o caminho de geração de imagens do Azure:

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

O padrão é 2024-12-01-preview quando a variável não está definida.

Nomes de modelo são nomes de implantação

O Azure OpenAI vincula modelos a implantações. Para solicitações de geração de imagens do Azure roteadas pelo provedor openai integrado, o campo model no OpenClaw deve ser o nome da implantação do Azure que você configurou no portal do Azure, não o ID público do modelo da OpenAI.

Se você criar uma implantação chamada gpt-image-2-prod que serve gpt-image-2:

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

A mesma regra de nome de implantação se aplica a chamadas de geração de imagens roteadas pelo provedor openai integrado.

Disponibilidade regional

A geração de imagens do Azure está disponível atualmente apenas em um subconjunto de regiões (por exemplo, eastus2, swedencentral, polandcentral, westus3, uaenorth). Verifique a lista atual de regiões da Microsoft antes de criar uma implantação e confirme se o modelo específico é oferecido na sua região.

Diferenças de parâmetros

O Azure OpenAI e a OpenAI pública nem sempre aceitam os mesmos parâmetros de imagem. O Azure pode rejeitar opções que a OpenAI pública permite (por exemplo, certos valores de background em gpt-image-2) ou expô-las apenas em versões específicas do modelo. Essas diferenças vêm do Azure e do modelo subjacente, não do OpenClaw. Se uma solicitação do Azure falhar com um erro de validação, verifique o conjunto de parâmetros compatível com sua implantação e versão de API específicas no portal do Azure.

Configuração avançada

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { transport: "auto" },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { serviceTier: "priority" } },      },    },  },}

{  agents: {    defaults: {      models: {        "azure-openai-responses/gpt-5.5": {          params: { responsesServerCompaction: true },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 120000,          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: { responsesServerCompaction: false },        },      },    },  },}

{  agents: {    defaults: {      embeddedAgent: { executionContract: "strict-agentic" },    },  },}

Relacionados