OpenAI

OpenClaw usa um único id de provedor, openai, tanto para autenticação direta por chave de API quanto para autenticação de assinatura do ChatGPT/Codex. openai/* é a rota de modelo canônica. Para turnos de agentes incorporados com a política de runtime não definida ou definida como auto, os dados da rota da OpenAI determinam se o OpenClaw pode selecionar implicitamente o runtime incluído do servidor de aplicativo Codex. O prefixo openai/*, por si só, não seleciona um runtime.

• Modelos de agente - openai/* por meio do runtime selecionado pela configuração explícita agentRuntime ou pela política de rota implícita da OpenAI. Entre com a autenticação do Codex para usar uma assinatura do ChatGPT/Codex ou configure um perfil de autenticação por chave de API quando quiser cobrança baseada em chave.
• APIs da OpenAI não relacionadas a agentes - acesso direto à OpenAI Platform, com cobrança por uso, por meio de OPENAI_API_KEY ou de um perfil de autenticação por chave de API openai.
• Configuração legada - as referências codex/* e openai-codex/* são corrigidas para openai/*, com agentRuntime.id: "codex" com escopo de modelo, por openclaw doctor --fix.

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

Acompanhamento de uso e custos

O OpenClaw mantém separadas a cota da assinatura e a cobrança da API da Platform:

• O OAuth do ChatGPT/Codex mostra o plano de assinatura, as janelas de cota e o saldo de créditos.
• OPENAI_ADMIN_KEY mostra 30 dias de custos da organização e uso de conclusões informados pelo provedor na seção Uso da Control UI, incluindo gastos diários, totais de solicitações/tokens, principais modelos e categorias de custos.
• OPENAI_PROJECT_ID restringe opcionalmente o histórico da Admin API a um único projeto.
• O OpenClaw nunca envia OPENAI_API_KEY nem um perfil de inferência openai às APIs da organização; essas credenciais podem pertencer a endpoints personalizados, do Azure ou locais do agente.

Uma chave de administrador explícita tem precedência sobre o OAuth. O histórico informado pelo provedor não é mesclado ao custo estimado pelo OpenClaw com base nas sessões; ele pode incluir atividades da API de outros clientes e ajustes de cobrança feitos pelo provedor.

A documentação do Painel de uso da API da OpenAI descreve os requisitos de proprietário da organização e de permissão explícita no Painel de uso para acessar dados de uso.

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

Escolha rápida

Mapa de nomes

Runtime implícito do agente

Quando a política agentRuntime do provedor/modelo não está definida ou é auto, a política de rota pertencente ao provedor da OpenAI escolhe o runtime implícito com base no endpoint e no adaptador efetivos:

Uma configuração explícita e não padrão de agentRuntime.id do provedor/modelo continua sendo autoritativa. Por exemplo, agentRuntime.id: "openclaw" mantém no OpenClaw uma rota que, de outro modo, seria elegível para o Codex, enquanto agentRuntime.id: "codex" exige o Codex e falha de forma fechada quando a rota efetiva não é declarada compatível com o Codex. A seleção do runtime não altera o tipo de credencial nem a cobrança: a autenticação por chave de API da Platform e a autenticação por assinatura do ChatGPT/Codex permanecem distintas.

openclaw doctor --fix migra referências de modelo legadas codex/* e openai-codex/*, ids legados de perfis de autenticação do Codex e entradas legadas de ordem de autenticação do Codex para a rota canônica openai. As referências de modelo migradas recebem agentRuntime.id: "codex" com escopo de modelo; use auth.order.openai para novas configurações de ordem de autenticação.

Prévia limitada do GPT-5.6

O OpenClaw reconhece os ids de modelo exatos openai/gpt-5.6-sol, openai/gpt-5.6-terra e openai/gpt-5.6-luna. Os três oferecem raciocínio xhigh e max no catálogo atual. A OpenAI descreve o Sol como a categoria principal, o Terra como a categoria equilibrada e o Luna como a categoria rápida e de menor custo. Consulte o anúncio de lançamento do GPT-5.6 e o guia de acesso.

Com autenticação direta por chave de API da OpenAI, o id openai/gpt-5.6 sem qualificador é um alias do Sol e o padrão para novas configurações. O catálogo nativo do Codex não aplica esse alias da API direta no lado do cliente; dependendo do acesso ao workspace, ele pode mostrar os ids exatos de Sol, Terra e Luna. Portanto, uma nova configuração de OAuth do ChatGPT/Codex usa openai/gpt-5.6-sol. Verifique a conta atual com:

openclaw models list --provider openai

O acesso da organização da API e do workspace do Codex pode ser diferente. Se o GPT-5.6 não estiver disponível, selecione explicitamente o GPT-5.5:

openclaw models set openai/gpt-5.5

O OpenClaw exibe o erro de acesso do serviço upstream e não substitui silenciosamente uma seleção do GPT-5.6 pelo GPT-5.5.

Cobertura de recursos do OpenClaw

Embeddings de memória

O OpenClaw pode usar a OpenAI, ou um endpoint de embeddings compatível com a 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 a OpenAI que exigem rótulos de embeddings assimétricos, defina queryInputType e documentInputType em memorySearch. O OpenClaw os encaminha como campos de solicitação input_type específicos do provedor: os embeddings de consulta usam queryInputType; os fragmentos de memória indexados e a indexação em lote usam documentInputType. Consulte a referência de configuração de memória para ver o exemplo completo.

Introduçã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.6" } } },}

{  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.6-sol

openclaw models list --provider openai

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  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 do Codex

O harness nativo do app-server do Codex usa referências de modelo openai/* quando uma rota HTTPS oficial exata e qualificada o seleciona implicitamente ou quando agentRuntime.id: "codex" do provedor/modelo o seleciona explicitamente. 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. Execute openclaw doctor --fix para migrar IDs de perfil de autenticação legados do Codex e a ordem de autenticação.
2. A conta existente do app-server, como um login local do ChatGPT na CLI do Codex. Para o diretório inicial isolado padrão do agente, o OpenClaw conecta essa conta nativa da CLI ao app-server por meio do RPC de login; ele não compartilha a configuração, os plugins nem o armazenamento de threads da CLI.
3. Somente para inicializações locais do app-server por stdio e apenas quando o app-server não informar nenhuma conta: CODEX_API_KEY e depois OPENAI_API_KEY.

Um login local de assinatura do ChatGPT/Codex não é substituído apenas porque o processo do Gateway também tem OPENAI_API_KEY para modelos diretos da OpenAI ou embeddings. O fallback de chave de API do ambiente se aplica somente ao caminho local por stdio sem conta; ele nunca é enviado por conexões WebSocket do app-server. Quando um perfil do Codex baseado em assinatura é selecionado, o OpenClaw também mantém CODEX_API_KEY e OPENAI_API_KEY fora do processo filho do app-server por stdio e envia as credenciais selecionadas por meio do RPC de login do app-server.

Quando esse perfil de assinatura é bloqueado por um limite de uso do Codex, o OpenClaw marca o perfil como bloqueado até o horário de redefinição anunciado pelo Codex e permite que a ordem de autenticação alterne para o próximo perfil openai:*, sem mudar o modelo selecionado nem sair do harness do Codex. Depois que o horário de redefinição passa, o perfil de assinatura volta a ser elegível.

Geração de imagens

O plugin integrado openai registra a geração de imagens por meio da ferramenta image_generate. Ele oferece geração de imagens tanto por chave de API da OpenAI quanto por OAuth do Codex usando a mesma referência de modelo openai/gpt-image-2.

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

gpt-image-2 é o padrão para geração de texto para imagem e edição de imagens da OpenAI. gpt-image-1.5, gpt-image-1 e gpt-image-1-mini permanecem 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 gpt-image-2 atual rejeita background: "transparent".

Para uma solicitação de fundo transparente, chame image_generate com model: "openai/gpt-image-1.5", outputFormat: "png" ou "webp" e background: "transparent"; a opção mais antiga do provedor openai.background 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 como gpt-image-1.5; o Azure e endpoints personalizados compatíveis com a OpenAI mantêm os nomes de implantação/modelo configurados.

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

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "Um adesivo simples de círculo vermelho sobre um fundo transparente" \  --json

Use as mesmas flags --output-format e --background com openclaw infer image edit ao começar com um arquivo de entrada. --openai-background permanece disponível como um alias específico da OpenAI. Use --quality low|medium|high|auto para controlar a qualidade e o custo das imagens da OpenAI. Use --openai-moderation low|auto para passar a indicação de moderação da OpenAI a partir de image generate ou image edit.

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

Gerar:

/tool image_generate model=openai/gpt-image-2 prompt="Um pôster de lançamento refinado do OpenClaw no macOS" size=3840x2160 count=1

Gerar um PNG transparente:

/tool image_generate model=openai/gpt-image-1.5 prompt="Um adesivo simples de círculo vermelho sobre um fundo transparente" outputFormat=png background=transparent

Editar:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve o formato do objeto e altere o material para vidro translúcido" image=/path/to/reference.png size=1024x1536

Geração de vídeos

O plugin integrado openai registra a geração de vídeos por meio da ferramenta video_generate.

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

{  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 modelos da família GPT-5 no provedor openai (incluindo referências legadas do Codex anteriores ao reparo que são normalizadas para openai/*). Outros provedores que também oferecem IDs de modelos da família GPT-5, como rotas do OpenRouter ou opencode, não recebem essa sobreposição; ela é condicionada ao ID de provedor openai, e não apenas ao ID do modelo. Modelos GPT-4.x mais antigos nunca a recebem.

O harness nativo do app-server do Codex não recebe o contrato de comportamento de persona e disciplina de ferramentas nem a sobreposição de estilo de interação amigável por meio de instruções do desenvolvedor; o Codex nativo mantém os comportamentos de base, de modelo e de documentação do projeto controlados pelo Codex, e o OpenClaw desativa a personalidade integrada do Codex em threads nativas para que os arquivos de personalidade do workspace do agente permaneçam autoritativos. O OpenClaw fornece apenas contexto de runtime às threads nativas do Codex: entrega por canal, ferramentas dinâmicas do OpenClaw, delegação ACP, contexto do workspace e Skills do OpenClaw. O texto de orientação de Heartbeat dessa mesma contribuição é a única exceção: turnos de Heartbeat do Codex nativo o recebem, injetado como instruções de colaboração dedicadas, e não por meio do hook compartilhado de contribuição de prompt.

A contribuição do GPT-5 adiciona um contrato de comportamento com tags para persistência de persona, segurança de execução, disciplina de ferramentas, formato de saída, verificações de conclusão e validação em prompts correspondentes montados pelo OpenClaw. O comportamento de resposta específico do canal e de mensagens silenciosas 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 incluído pode direcionar a geração de imagens para um recurso do Azure OpenAI 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 automaticamente para o formato de solicitação do Azure.

Use o Azure OpenAI quando:

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

Configuração

Para gerar imagens no Azure por meio do provedor openai incluído, direcione 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 do Azure reconhecido, o OpenClaw:

• Envia o cabeçalho api-key em vez de Authorization: Bearer
• Usa caminhos específicos da 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. Os valores de 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 imagens da OpenAI.

Versão da API

Defina AZURE_OPENAI_API_VERSION para fixar uma versão específica de prévia 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.

Os nomes dos modelos são nomes de implantação

O Azure OpenAI associa 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 configurado 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 disponibiliza gpt-image-2:

/tool image_generate model=openai/gpt-image-2-prod prompt="Um pôster limpo" size=1024x1024 count=1

A mesma regra de nome de implantação se aplica a qualquer chamada de geração de imagens roteada pelo provedor openai incluído.

Disponibilidade regional

Atualmente, a geração de imagens do Azure está disponível apenas em um subconjunto de regiões (por exemplo, eastus2, swedencentral, polandcentral, westus3, uaenorth). Consulte a lista atual de regiões da Microsoft antes de criar uma implantação e confirme se o modelo específico é oferecido em 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 permitidas pela OpenAI pública (por exemplo, determinados valores de background em gpt-image-2) ou disponibilizá-las apenas em versões específicas do modelo. Essas diferenças são provenientes do Azure e do modelo subjacente, não do OpenClaw. Se uma solicitação do Azure falhar com um erro de validação, consulte no portal do Azure o conjunto de parâmetros compatível com sua implantação e versão da API específicas.

Configuração avançada

Os exemplos de params por modelo abaixo definem o formato da solicitação do provedor incorporado do OpenClaw. Configurá-los constitui um comportamento de solicitação definido pelo autor, portanto, uma rota auto que seria elegível permanece no OpenClaw, em vez de selecionar implicitamente o Codex. O harness nativo do servidor de aplicativo Codex controla seu próprio transporte e suas configurações de solicitação; agentRuntime.id: "codex" explícito falha de forma fechada quando a rota efetiva não está declarada como compatível com Codex.

{  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: "default" },    },  },}

Relacionados