OpenAI

OpenAI fornece APIs de desenvolvedor para modelos GPT, e Codex também está disponível como um agente de codificação de plano ChatGPT por meio dos clientes Codex da OpenAI. O OpenClaw mantém essas superfícies separadas para que a configuração permaneça previsível.

O OpenClaw usa openai/* como a rota canônica de modelo da OpenAI. Turnos de agente incorporados em modelos OpenAI são executados pelo runtime nativo do servidor de app do Codex por padrão; a autenticação direta por chave de API da OpenAI permanece disponível para superfícies OpenAI sem agente, como imagens, embeddings, fala e tempo real.

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

A OpenAI oferece suporte explicitamente ao uso de OAuth de assinatura em ferramentas externas e fluxos de trabalho como o OpenClaw.

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

Escolha rápida

Mapa de nomes

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

Isso significa que uma configuração pode conter intencionalmente referências de modelo openai/* enquanto perfis de autenticação ainda apontam para credenciais compatíveis com Codex. Prefira auth.order.openai para novas configurações; perfis openai-codex:* existentes e auth.order.openai-codex continuam compatíveis. openclaw doctor --fix reescreve referências de modelo legadas openai-codex/* para a rota canônica de modelo da OpenAI.

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 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; fragmentos de memória indexados e indexação em lote usam documentInputType. Consulte a referência de configuração de memória para ver 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: "sk-..." },  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },}

{  env: { OPENAI_API_KEY: "sk-..." },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

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

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

openclaw models list --provider openai-codex

{  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-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw 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-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

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

Autenticação nativa do servidor de aplicativo do Codex

O harness nativo do servidor de aplicativo do Codex usa refs de modelo openai/* mais configuração de runtime omitida ou provider/model agentRuntime.id: "codex", mas sua autenticação ainda é baseada em conta. O OpenClaw seleciona a autenticação nesta ordem:

1. Perfis de autenticação OpenAI ordenados para o agente, de preferência em auth.order.openai. Perfis openai-codex:* existentes e auth.order.openai-codex continuam válidos para instalações mais antigas.
2. A conta existente do servidor de aplicativo, como um login local do ChatGPT pela CLI do Codex.
3. Somente para inicializações locais do servidor de aplicativo stdio, CODEX_API_KEY e depois OPENAI_API_KEY, quando o servidor de aplicativo 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 variável de ambiente é apenas o caminho local stdio sem conta; ele não é enviado a conexões WebSocket do servidor de aplicativo. Quando um perfil de Codex no estilo assinatura é selecionado, o OpenClaw também mantém CODEX_API_KEY e OPENAI_API_KEY fora do processo filho stdio do servidor de aplicativo gerado e envia as credenciais selecionadas pela RPC de login do servidor de aplicativo. Quando esse perfil de assinatura é bloqueado por um limite de uso do Codex, o OpenClaw pode alternar para o próximo perfil de chave de API openai:* ordenado sem mudar o modelo selecionado nem sair do harness do Codex. Depois que o tempo de redefinição da assinatura passa, o perfil de assinatura fica elegível novamente.

Geração de imagens

O plugin openai empacotado registra 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 ref. 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 de gpt-image-2 rejeita background: "transparent".

Para uma solicitação de 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 antiga openai.background ainda é aceita. O OpenClaw também protege as rotas públicas OpenAI e OpenAI Codex OAuth reescrevendo solicitações transparentes padrão openai/gpt-image-2 para gpt-image-1.5; endpoints Azure e OpenAI-compatíveis personalizados mantêm seus nomes de implantação/modelo configurados.

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 começar a partir de um arquivo de entrada. --openai-background permanece disponível como um alias específico da OpenAI.

Para instalações com OAuth do Codex, mantenha a mesma ref. openai/gpt-image-2. Quando um perfil OAuth openai-codex estiver configurado, o OpenClaw resolve esse token de acesso OAuth armazenado e envia solicitações de imagem pelo backend Codex Responses. Ele não tenta primeiro OPENAI_API_KEY nem faz fallback silencioso para 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 OpenAI Images. 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 OpenAI-compatíveis privados/internos 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 incluído registra geração de vídeo por meio da ferramenta video_generate.

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

Contribuição de prompt do GPT-5

O OpenClaw adiciona uma contribuição compartilhada de prompt do GPT-5 para execuções da família GPT-5 entre provedores. Ela se aplica pelo id do modelo, portanto openai/gpt-5.5, refs legadas anteriores ao reparo como openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 e outras refs compatíveis com GPT-5 recebem a mesma sobreposição. Modelos GPT-4.x mais antigos não recebem.

O harness Codex nativo incluído usa o mesmo comportamento do GPT-5 e a mesma sobreposição de Heartbeat por meio das instruções de desenvolvedor do servidor de aplicativo Codex, portanto sessões openai/gpt-5.x roteadas pelo Codex mantêm a mesma orientação de acompanhamento e Heartbeat proativo, embora o Codex seja dono do restante do prompt do harness.

A contribuição do 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. 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 orientação do GPT-5 está sempre habilitada para modelos correspondentes. 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", voice: "coral" },      },    },  },}

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

Endpoints do Azure OpenAI

O provedor openai incluído 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 muda para o formato de solicitação do Azure automaticamente.

Use o Azure OpenAI quando:

• Você já tem uma assinatura, cota ou contrato empresarial do Azure OpenAI
• Você precisa de residência regional de dados ou controles de conformidade fornecidos pelo Azure
• Você quer manter o tráfego dentro de uma locação existente do Azure

Configuração

Para geração de imagens do Azure por meio do provedor openai incluído, aponte models.providers.openai.baseUrl para o 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 do Azure reconhecido, o OpenClaw:

• Envia o cabeçalho api-key em vez de Authorization: Bearer
• Usa caminhos com escopo de implantação (/openai/deployments/{deployment}/...)
• Anexa ?api-version=... a cada solicitação
• Usa um tempo limite de solicitação padrã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 específica de preview ou GA 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 modelos 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 incluído, 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 às chamadas de geração de imagens roteadas pelo provedor openai incluído.

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 de 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 específica e versão da API 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: true } },      },    },  },}

{  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: {      embeddedPi: { executionContract: "strict-agentic" },    },  },}

Relacionado