OpenAI

O OpenClaw usa um único id de provedor, openai, tanto para autenticação direta por chave de API quanto para autenticação por assinatura do ChatGPT/Codex. openai/* é a rota de modelo canônica. Para turnos de agentes integrados 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 do servidor de aplicativo Codex incluído. 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 de 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 faturamento baseado em chave.
• APIs da OpenAI não relacionadas a agentes - acesso direto à Plataforma OpenAI, 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 - referências antigas de modelos Codex e ids de perfil são corrigidos para openai/* por openclaw doctor --fix.

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

Acompanhamento de uso e custos

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

• O OAuth do ChatGPT/Codex mostra o plano da 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 Usage da Control UI, incluindo gastos diários, totais de solicitações/tokens, principais modelos e categorias de custo.
• OPENAI_PROJECT_ID limita opcionalmente o histórico da Admin API a um 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 é combinado com o custo estimado derivado das sessões do OpenClaw; ele pode incluir atividade de API de outros clientes e ajustes de cobrança feitos pelo provedor.

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

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

Escolha rápida

Mapa de nomes

Runtime de agente implícito

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

Um agentRuntime.id explícito e não padrão do provedor/modelo continua sendo determinante. Por exemplo, agentRuntime.id: "openclaw" mantém no OpenClaw uma rota que, de outra forma, seria elegível para o Codex, enquanto agentRuntime.id: "codex" exige o Codex e falha de forma segura quando a rota efetiva não está declarada como 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 Plataforma e a autenticação por assinatura do ChatGPT/Codex permanecem distintas.

openclaw doctor --fix migra referências legadas de modelos 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. 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 exatos de modelo 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 o nível principal, o Terra como o nível equilibrado e o 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.

Com autenticação direta por chave de API da OpenAI, o id simples openai/gpt-5.6 é um alias para Sol e é o padrão da configuração inicial. O catálogo nativo do Codex não aplica esse alias de API direta no lado do cliente; dependendo do acesso do 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 apresenta o erro de acesso do serviço subjacente 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 do memory_search e embeddings de consultas:

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

Para endpoints compatíveis com a OpenAI que exigem rótulos assimétricos de embedding, defina queryInputType e documentInputType em memorySearch. O OpenClaw os encaminha como campos de solicitação input_type específicos do provedor: embeddings de consultas 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.

Primeiros passos

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 do app-server nativo do Codex

O harness app-server nativo do Codex usa referências de modelo openai/* quando uma rota HTTPS oficial exata e elegível o seleciona implicitamente ou quando agentRuntime.id: "codex" do provedor/modelo o seleciona explicitamente. A autenticação dele continua baseada em conta. O OpenClaw seleciona a autenticação nesta ordem:

1. Perfis ordenados de autenticação da OpenAI para o agente, preferencialmente em auth.order.openai. Execute openclaw doctor --fix para migrar IDs antigos legados de perfis de autenticação do Codex e a ordem de autenticação.
2. A conta existente do app-server, como um login do ChatGPT na CLI local 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 para a chave de API do ambiente aplica-se somente ao caminho local por stdio sem conta; ela nunca é enviada por conexões WebSocket do app-server. Quando um perfil do Codex no estilo de assinatura é selecionado, o OpenClaw também impede que CODEX_API_KEY e OPENAI_API_KEY sejam passadas ao processo filho do app-server por stdio e, em vez disso, 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 ordenação 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 openai incluído registra a geração de imagens por meio da ferramenta image_generate. Ele aceita tanto a geração de imagens com chave de API da OpenAI quanto com 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 imagens a partir de texto e edição de imagens da OpenAI. gpt-image-1.5, gpt-image-1 e gpt-image-1-mini continuam disponíveis como substituições explícitas de modelo. Use openai/gpt-image-1.5 para saídas PNG/WebP com fundo transparente; a API atual de gpt-image-2 rejeita background: "transparent".

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

A mesma configuração está disponível para execuções de 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 continua 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 OAuth do ChatGPT/Codex, mantenha a mesma referência openai/gpt-image-2. Quando um perfil OAuth openai estiver configurado, o OpenClaw resolve o token de acesso OAuth armazenado e envia as solicitações de imagem pelo backend de 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 uma LAN confiável/endereço privado, também defina 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 sofisticado 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 openai incluído 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. As 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 disponibilizam 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, 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/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 o comportamento básico, de modelo e de documentação do projeto controlado pelo Codex, e o OpenClaw desativa 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 com contexto de runtime para 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, em vez de pelo 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 específico de canal para respostas e 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
• Precisar de residência regional de dados ou controles de conformidade fornecidos pelo Azure
• Quiser manter o tráfego dentro de uma locação existente do Azure

Configuração

Para geração de imagens no Azure por meio do provedor openai incluído, 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 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}/...)
• 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 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 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 configurado no portal do Azure, e 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 vêm do Azure e do modelo subjacente, não do OpenClaw. Se uma solicitação ao Azure falhar com um erro de validação, verifique 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 ao OpenClaw. Configurá-los constitui um comportamento de solicitação definido, portanto uma rota auto que seria elegível permanece no OpenClaw em vez de selecionar implicitamente o Codex. O harness nativo do app-server do Codex controla seu próprio transporte e suas próprias configurações de solicitação; agentRuntime.id: "codex" explícito falha de forma fechada quando a rota efetiva não é declarada compatível com o 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