OpenAI

OpenAI fournit des API développeur pour les modèles GPT, et Codex est également disponible comme agent de codage avec formule ChatGPT via les clients Codex d'OpenAI. OpenClaw garde ces surfaces séparées afin que la configuration reste prévisible.

OpenClaw utilise openai/* comme route canonique des modèles OpenAI. Les tours d'agent intégrés sur les modèles OpenAI passent par le runtime natif du serveur d'application Codex par défaut ; l'authentification directe par clé d'API OpenAI reste disponible pour les surfaces OpenAI hors agent, comme les images, les embeddings, la parole et le temps réel.

• Modèles d'agent - modèles openai/* via le runtime Codex ; connectez-vous avec l'authentification Codex pour l'utilisation d'un abonnement ChatGPT/Codex, ou configurez une sauvegarde par clé d'API OpenAI compatible Codex lorsque vous voulez intentionnellement une authentification par clé d'API.
• API OpenAI hors agent - accès direct à la plateforme OpenAI avec facturation à l'usage via OPENAI_API_KEY ou l'onboarding par clé d'API OpenAI.
• Configuration héritée - les références de modèle openai-codex/* sont réparées par openclaw doctor --fix en openai/* plus le runtime Codex.

OpenAI prend explicitement en charge l'utilisation OAuth par abonnement dans des outils et workflows externes comme OpenClaw.

Le fournisseur, le modèle, le runtime et le canal sont des couches distinctes. Si ces libellés sont mélangés, lisez Runtimes d'agent avant de modifier la configuration.

Choix rapide

Carte de nommage

Les noms sont similaires, mais ne sont pas interchangeables :

Cela signifie qu'une configuration peut contenir intentionnellement des références de modèle openai/* tandis que les profils d'authentification pointent encore vers des identifiants compatibles Codex. Préférez auth.order.openai pour les nouvelles configurations ; les profils openai-codex:* existants et auth.order.openai-codex restent pris en charge. openclaw doctor --fix réécrit les références de modèle héritées openai-codex/* vers la route canonique des modèles OpenAI.

Couverture des fonctionnalités OpenClaw

Embeddings mémoire

OpenClaw peut utiliser OpenAI, ou un endpoint d'embeddings compatible OpenAI, pour l'indexation memory_search et les embeddings de requête :

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

Pour les endpoints compatibles OpenAI qui nécessitent des libellés d'embedding asymétriques, définissez queryInputType et documentInputType sous memorySearch. OpenClaw les transmet comme champs de requête input_type propres au fournisseur : les embeddings de requête utilisent queryInputType ; les fragments de mémoire indexés et l'indexation par lots utilisent documentInputType. Consultez la référence de configuration de la mémoire pour l'exemple complet.

Démarrage

Choisissez votre méthode d'authentification préférée et suivez les étapes de configuration.

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 }],      },    },  },}

Authentification native du serveur d’application Codex

Le harnais natif de serveur d’application Codex utilise des références de modèle openai/* avec une configuration d’exécution omise ou agentRuntime.id: "codex" au niveau fournisseur/modèle, mais son authentification reste basée sur le compte. OpenClaw sélectionne l’authentification dans cet ordre :

1. Profils d’authentification OpenAI ordonnés pour l’agent, de préférence sous auth.order.openai. Les profils openai-codex:* existants et auth.order.openai-codex restent valides pour les installations plus anciennes.
2. Le compte existant du serveur d’application, comme une connexion ChatGPT locale de la CLI Codex.
3. Pour les lancements locaux du serveur d’application stdio uniquement, CODEX_API_KEY, puis OPENAI_API_KEY, lorsque le serveur d’application ne signale aucun compte et nécessite encore une authentification OpenAI.

Cela signifie qu’une connexion locale avec abonnement ChatGPT/Codex n’est pas remplacée simplement parce que le processus Gateway dispose aussi de OPENAI_API_KEY pour les modèles OpenAI directs ou les embeddings. Le recours à une clé d’API d’environnement est uniquement le chemin local stdio sans compte ; il n’est pas envoyé aux connexions WebSocket du serveur d’application. Lorsqu’un profil Codex de type abonnement est sélectionné, OpenClaw garde également CODEX_API_KEY et OPENAI_API_KEY hors du processus enfant stdio du serveur d’application lancé, et envoie les identifiants sélectionnés via le RPC de connexion du serveur d’application. Lorsque ce profil d’abonnement est bloqué par une limite d’utilisation Codex, OpenClaw peut basculer vers le prochain profil de clé d’API openai:* ordonné sans changer le modèle sélectionné ni quitter le harnais Codex. Une fois l’heure de réinitialisation de l’abonnement passée, le profil d’abonnement redevient éligible.

Génération d’images

Le Plugin openai inclus enregistre la génération d’images via l’outil image_generate. Il prend en charge à la fois la génération d’images avec clé d’API OpenAI et la génération d’images OAuth Codex via la même référence de modèle openai/gpt-image-2.

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

gpt-image-2 est la valeur par défaut pour la génération texte-vers-image OpenAI et l’édition d’images. gpt-image-1.5, gpt-image-1 et gpt-image-1-mini restent utilisables comme remplacements de modèle explicites. Utilisez openai/gpt-image-1.5 pour une sortie PNG/WebP à arrière-plan transparent ; l’API gpt-image-2 actuelle rejette background: "transparent".

Pour une requête avec arrière-plan transparent, les agents doivent appeler image_generate avec model: "openai/gpt-image-1.5", outputFormat: "png" ou "webp", et background: "transparent" ; l’ancienne option de fournisseur openai.background est toujours acceptée. OpenClaw protège aussi les routes publiques OpenAI et OpenAI Codex OAuth en réécrivant les requêtes transparentes openai/gpt-image-2 par défaut vers gpt-image-1.5 ; Azure et les points de terminaison personnalisés compatibles OpenAI conservent leurs noms de déploiement/modèle configurés.

Le même réglage est exposé pour les exécutions CLI sans 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

Utilisez les mêmes indicateurs --output-format et --background avec openclaw infer image edit lorsque vous partez d’un fichier d’entrée. --openai-background reste disponible comme alias spécifique à OpenAI.

Pour les installations OAuth Codex, conservez la même référence openai/gpt-image-2. Lorsqu’un profil OAuth openai-codex est configuré, OpenClaw résout ce jeton d’accès OAuth stocké et envoie les requêtes d’image via le backend Codex Responses. Il n’essaie pas d’abord OPENAI_API_KEY et ne bascule pas silencieusement vers une clé d’API pour cette requête. Configurez explicitement models.providers.openai avec une clé d’API, une URL de base personnalisée ou un point de terminaison Azure lorsque vous voulez utiliser la route directe de l’API OpenAI Images. Si ce point de terminaison d’image personnalisé se trouve sur un réseau local/adresse privée de confiance, définissez également browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ; OpenClaw garde les points de terminaison d’image privés/internes compatibles OpenAI bloqués sauf si cette option d’adhésion est présente.

Générer :

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

Générer un PNG transparent :

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

Modifier :

/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

Génération de vidéos

Le Plugin openai intégré enregistre la génération vidéo via l’outil video_generate.

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

Contribution de prompt GPT-5

OpenClaw ajoute une contribution de prompt GPT-5 partagée pour les exécutions de la famille GPT-5 entre fournisseurs. Elle s’applique par id de modèle, donc openai/gpt-5.5, les références héritées antérieures à la réparation telles que openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 et les autres références GPT-5 compatibles reçoivent la même surcouche. Les anciens modèles GPT-4.x ne la reçoivent pas.

Le harnais Codex natif intégré utilise le même comportement GPT-5 et la même surcouche Heartbeat via les instructions développeur du serveur d’application Codex, donc les sessions openai/gpt-5.x acheminées via Codex conservent les mêmes consignes de suivi et de Heartbeat proactif, même si Codex possède le reste du prompt du harnais.

La contribution GPT-5 ajoute un contrat de comportement balisé pour la persistance de persona, la sécurité d’exécution, la discipline d’outils, la forme de sortie, les vérifications d’achèvement et la vérification. Le comportement de réponse propre au canal et de message silencieux reste dans le prompt système OpenClaw partagé et la politique de livraison sortante. Le guidage GPT-5 est toujours activé pour les modèles correspondants. La couche de style d’interaction conviviale est distincte et configurable.

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

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

Voix et parole

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

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

Points de terminaison Azure OpenAI

Le fournisseur openai inclus peut cibler une ressource Azure OpenAI pour la génération d’images en remplaçant l’URL de base. Sur le chemin de génération d’images, OpenClaw détecte les noms d’hôte Azure sur models.providers.openai.baseUrl et bascule automatiquement vers la forme de requête d’Azure.

Utilisez Azure OpenAI lorsque :

• Vous disposez déjà d’un abonnement Azure OpenAI, d’un quota ou d’un accord d’entreprise
• Vous avez besoin de la résidence régionale des données ou des contrôles de conformité fournis par Azure
• Vous souhaitez conserver le trafic à l’intérieur d’un tenant Azure existant

Configuration

Pour la génération d’images Azure via le fournisseur openai inclus, pointez models.providers.openai.baseUrl vers votre ressource Azure et définissez apiKey sur la clé Azure OpenAI (et non une clé OpenAI Platform) :

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

OpenClaw reconnaît ces suffixes d’hôte Azure pour la route de génération d’images Azure :

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

Pour les requêtes de génération d’images sur un hôte Azure reconnu, OpenClaw :

• Envoie l’en-tête api-key au lieu de Authorization: Bearer
• Utilise des chemins limités au déploiement (/openai/deployments/{deployment}/...)
• Ajoute ?api-version=... à chaque requête
• Utilise un délai d’expiration de requête par défaut de 600 s pour les appels de génération d’images Azure. Les valeurs timeoutMs par appel remplacent toujours cette valeur par défaut.

Les autres URL de base (OpenAI public, proxys compatibles OpenAI) conservent la forme standard des requêtes d’image OpenAI.

Version de l’API

Définissez AZURE_OPENAI_API_VERSION pour figer une version Azure spécifique en préversion ou GA pour le chemin de génération d’images Azure :

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

La valeur par défaut est 2024-12-01-preview lorsque la variable n’est pas définie.

Les noms de modèles sont des noms de déploiements

Azure OpenAI associe les modèles à des déploiements. Pour les requêtes de génération d’images Azure acheminées via le fournisseur openai intégré, le champ model dans OpenClaw doit être le nom de déploiement Azure que vous avez configuré dans le portail Azure, et non l’identifiant public du modèle OpenAI.

Si vous créez un déploiement appelé gpt-image-2-prod qui sert gpt-image-2 :

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

La même règle de nom de déploiement s’applique aux appels de génération d’images acheminés via le fournisseur openai intégré.

Disponibilité régionale

La génération d’images Azure n’est actuellement disponible que dans un sous-ensemble de régions (par exemple eastus2, swedencentral, polandcentral, westus3, uaenorth). Consultez la liste actuelle des régions de Microsoft avant de créer un déploiement, et confirmez que le modèle spécifique est proposé dans votre région.

Différences de paramètres

Azure OpenAI et OpenAI public n’acceptent pas toujours les mêmes paramètres d’image. Azure peut rejeter des options qu’OpenAI public autorise (par exemple certaines valeurs background sur gpt-image-2) ou ne les exposer que sur des versions de modèle spécifiques. Ces différences viennent d’Azure et du modèle sous-jacent, pas d’OpenClaw. Si une requête Azure échoue avec une erreur de validation, consultez l’ensemble de paramètres pris en charge par votre déploiement spécifique et votre version d’API dans le portail Azure.

Configuration avancée

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

Associé