OpenAI

OpenAI fornece APIs de desenvolvedor para modelos GPT, e o Codex também está disponível como um agente de codificação do 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 modelos da OpenAI. Turnos de agente embutidos em modelos OpenAI passam pelo runtime app-server nativo do Codex por padrão; 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/* pelo runtime do Codex; entre com a autenticação openai-codex para uso de assinatura ChatGPT/Codex, ou configure um perfil de chave de API openai-codex quando você intencionalmente quiser 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 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 do 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 agentes antes de alterar a configuração.

# Escolha rápida

# Mapa de nomes

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

Isso significa que uma configuração pode conter intencionalmente tanto referências de modelo openai/* quanto perfis de autenticação openai-codex. openclaw doctor --fix reescreve referências de modelo legadas openai-codex/* para a rota canônica de modelos 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 assimétricos de embedding, defina queryInputType e documentInputType em memorySearch. O OpenClaw encaminha esses valores 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. Veja a referência de configuração de memória para o exemplo completo.

# Primeiros passos

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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

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

openclaw doctor --fix
openclaw config validate

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

{
  models: {
    providers: {
      "openai-codex": {
        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/* mais configuração de ambiente de execução omitida ou agentRuntime.id: "codex", mas sua autenticação ainda é baseada em conta. O OpenClaw seleciona a autenticação nesta ordem:

1. Um perfil de autenticação openai-codex explícito do OpenClaw vinculado ao agente.
2. A conta existente do app-server, como um login local ChatGPT na CLI do Codex.
3. Somente para inicializações locais de app-server stdio, CODEX_API_KEY, depois OPENAI_API_KEY, quando o app-server informa que não há 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 de app-server WebSocket. Quando um perfil Codex do tipo assinatura é selecionado, o OpenClaw também mantém CODEX_API_KEY e OPENAI_API_KEY fora do processo filho app-server stdio iniciado e envia as credenciais selecionadas pela RPC de login do app-server.

# Geração de imagens

O Plugin openai incluído registra geração de imagens pela ferramenta image_generate. Ele oferece suporte tanto à geração de imagens por chave de API OpenAI quanto à geração de imagens por OAuth 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 OpenAI quanto para edição de imagens. gpt-image-1.5, gpt-image-1 e gpt-image-1-mini continuam utilizáveis como sobrescritas 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, os 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 OpenAI e OAuth OpenAI Codex reescrevendo solicitações transparentes padrão openai/gpt-image-2 para gpt-image-1.5; Azure e endpoints personalizados compatíveis com OpenAI mantêm seus nomes de implantação/modelo configurados.

A mesma configuração é exposta para execuções headless pela CLI:

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 de um arquivo de entrada. --openai-background continua disponível como um alias específico da OpenAI.

Para instalações OAuth Codex, mantenha a mesma referência 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 silenciosamente 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, defina também browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; o OpenClaw mantém endpoints de imagem privados/internos compatíveis com OpenAI bloqueados, a menos que essa opçã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 pela ferramenta video_generate.

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

# Contribuição de prompt GPT-5

O OpenClaw adiciona uma contribuição de prompt GPT-5 compartilhada para execuções da família GPT-5 em vários provedores. Ela se aplica por id de modelo, então openai/gpt-5.5, referências legadas antes do reparo como openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 e outras referências GPT-5 compatíveis recebem a mesma sobreposição. Modelos GPT-4.x mais antigos não recebem.

O harness Codex nativo incluído usa o mesmo comportamento GPT-5 e a sobreposição de Heartbeat por meio das instruções de desenvolvedor do app-server do Codex, então sessões openai/gpt-5.x forçadas por agentRuntime.id: "codex" mantêm as mesmas orientações de acompanhamento e Heartbeat proativo, embora o Codex controle o 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 de canal e de mensagens silenciosas permanece no prompt de sistema compartilhado do OpenClaw e na política de entrega de saída. A orientação do GPT-5 fica 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 direcionar 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 automaticamente para o formato de solicitação do Azure.

Use 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 tenancy 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 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}/...)
• Anexa ?api-version=... a cada solicitação
• Usa um tempo limite padrão de solicitação de 600 s 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 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 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 do modelo público 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 por meio do 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). Consulte 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, determinados 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" },
        },
      },
    },
  },
}

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

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

# Relacionados