OpenAI

OpenClaw utilise un seul identifiant de fournisseur, openai, pour l’authentification directe par clé d’API et l’authentification par abonnement ChatGPT/Codex. openai/* est la route de modèle canonique. Pour les tours d’agent intégrés dont la politique d’exécution n’est pas définie ou vaut auto, les caractéristiques de route d’OpenAI déterminent si OpenClaw peut sélectionner implicitement l’environnement d’exécution app-server Codex inclus. Le préfixe openai/* seul ne sélectionne aucun environnement d’exécution.

• Modèles d’agent - openai/* via l’environnement d’exécution sélectionné par une configuration agentRuntime explicite ou par la politique de route implicite d’OpenAI. Connectez-vous avec l’authentification Codex pour utiliser un abonnement ChatGPT/Codex, ou configurez un profil d’authentification par clé d’API si vous souhaitez une facturation basée sur une clé.
• API OpenAI hors agent - accès direct à OpenAI Platform, facturé à l’utilisation, via OPENAI_API_KEY ou un profil d’authentification par clé d’API openai.
• Configuration héritée - les références codex/* et openai-codex/* sont corrigées en openai/*, avec agentRuntime.id: "codex" limité au modèle, par openclaw doctor --fix.

OpenAI prend explicitement en charge l’utilisation d’OAuth avec un abonnement dans des outils externes et des workflows comme OpenClaw.

Suivi de l’utilisation et des coûts

OpenClaw distingue le quota de l’abonnement de la facturation de l’API Platform :

• L’OAuth ChatGPT/Codex affiche le forfait d’abonnement, les fenêtres de quota et le solde de crédits.
• OPENAI_ADMIN_KEY affiche 30 jours de coûts d’organisation et d’utilisation des complétions communiqués par le fournisseur dans Utilisation de l’interface de contrôle, notamment les dépenses quotidiennes, les totaux de requêtes et de jetons, les principaux modèles et les catégories de coûts.
• OPENAI_PROJECT_ID limite facultativement l’historique de l’API d’administration à un seul projet.
• OpenClaw n’envoie jamais OPENAI_API_KEY ni un profil d’inférence openai aux API de l’organisation ; ces identifiants peuvent appartenir à des points de terminaison personnalisés, Azure ou locaux à l’agent.

Une clé d’administration explicite est prioritaire sur OAuth. L’historique communiqué par le fournisseur n’est pas fusionné avec le coût estimé par OpenClaw à partir des sessions ; il peut inclure l’activité d’API d’autres clients et des ajustements de facturation effectués côté fournisseur.

La documentation du tableau de bord d’utilisation de l’API d’OpenAI décrit les exigences relatives au rôle de propriétaire de l’organisation et à l’autorisation explicite Usage Dashboard pour accéder aux données d’utilisation.

Le fournisseur, le modèle, l’environnement d’exécution et le canal constituent des couches distinctes. Si ces libellés sont confondus, consultez Environnements d’exécution des agents avant de modifier la configuration.

Choix rapide

Correspondance des noms

Environnement d’exécution implicite de l’agent

Lorsque la politique agentRuntime du fournisseur/modèle n’est pas définie ou vaut auto, la politique de route détenue par le fournisseur OpenAI choisit l’environnement d’exécution implicite à partir du point de terminaison et de l’adaptateur effectifs :

Une configuration agentRuntime.id explicite et non par défaut du fournisseur/modèle reste prioritaire. Par exemple, agentRuntime.id: "openclaw" maintient sur OpenClaw une route qui serait autrement admissible à Codex, tandis que agentRuntime.id: "codex" exige Codex et échoue de manière fermée lorsque la route effective n’est pas déclarée compatible avec Codex. La sélection de l’environnement d’exécution ne modifie ni le type d’identifiants ni la facturation : l’authentification par clé d’API Platform et l’authentification par abonnement ChatGPT/Codex restent distinctes.

openclaw doctor --fix migre les références de modèle héritées codex/* et openai-codex/*, les identifiants de profils d’authentification Codex hérités et les entrées héritées d’ordre d’authentification Codex vers la route canonique openai. Les références de modèle migrées reçoivent agentRuntime.id: "codex" limité au modèle ; utilisez auth.order.openai pour toute nouvelle configuration de l’ordre d’authentification.

Aperçu limité de GPT-5.6

OpenClaw reconnaît les identifiants de modèle exacts openai/gpt-5.6-sol, openai/gpt-5.6-terra et openai/gpt-5.6-luna. Tous trois proposent le raisonnement xhigh et max dans le catalogue actuel. OpenAI décrit Sol comme le niveau phare, Terra comme le niveau équilibré et Luna comme le niveau rapide et moins coûteux. Consultez l’annonce de lancement de GPT-5.6 et le guide d’accès.

Avec l’authentification directe par clé d’API OpenAI, l’identifiant openai/gpt-5.6 sans qualification est un alias de Sol et constitue la valeur par défaut d’une nouvelle configuration. Le catalogue Codex natif n’applique pas cet alias d’API directe côté client ; selon l’accès de l’espace de travail, il peut afficher les identifiants exacts de Sol, Terra et Luna. Une nouvelle configuration OAuth ChatGPT/Codex utilise donc openai/gpt-5.6-sol. Vérifiez le compte actuel avec :

openclaw models list --provider openai

L’accès de l’organisation de l’API et celui de l’espace de travail Codex peuvent différer. Si GPT-5.6 n’est pas disponible, sélectionnez explicitement GPT-5.5 :

openclaw models set openai/gpt-5.5

OpenClaw affiche l’erreur d’accès en amont et ne remplace pas silencieusement une sélection GPT-5.6 par GPT-5.5.

Couverture fonctionnelle d’OpenClaw

Plongements de mémoire

OpenClaw peut utiliser OpenAI, ou un point de terminaison de plongements compatible avec OpenAI, pour les plongements d’indexation et de requête memory_search :

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

Pour les points de terminaison compatibles avec OpenAI qui nécessitent des libellés de plongement asymétriques, définissez queryInputType et documentInputType sous memorySearch. OpenClaw les transmet en tant que champs de requête input_type propres au fournisseur : les plongements 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.

Prise en main

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

Authentification du serveur d’application Codex natif

Le harnais de serveur d’application Codex natif utilise les références de modèle openai/* lorsqu’une route HTTPS officielle exacte et admissible le sélectionne implicitement, ou lorsque le agentRuntime.id: "codex" du fournisseur/modèle le sélectionne explicitement. Son authentification reste liée au 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. Exécutez openclaw doctor --fix pour migrer les anciens identifiants de profil d’authentification Codex et l’ordre d’authentification hérités.
2. Compte existant du serveur d’application, par exemple une connexion ChatGPT locale dans la CLI Codex. Pour le répertoire personnel isolé par défaut de l’agent, OpenClaw transmet ce compte CLI natif au serveur d’application via son RPC de connexion ; il ne partage pas la configuration, les plugins ni le magasin de fils de discussion de la CLI.
3. Pour les lancements locaux du serveur d’application via stdio uniquement, et seulement lorsque celui-ci ne signale aucun compte : CODEX_API_KEY, puis OPENAI_API_KEY.

Une connexion locale à un abonnement ChatGPT/Codex n’est pas remplacée simplement parce que le processus Gateway dispose également de OPENAI_API_KEY pour les modèles OpenAI directs ou les embeddings. Le recours à la clé d’API d’environnement s’applique uniquement au chemin local stdio sans compte ; elle n’est jamais envoyée sur les connexions WebSocket du serveur d’application. Lorsqu’un profil Codex de type abonnement est sélectionné, OpenClaw empêche également CODEX_API_KEY et OPENAI_API_KEY d’atteindre le processus enfant du serveur d’application stdio et envoie plutôt 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 marque le profil comme bloqué jusqu’à l’heure de réinitialisation annoncée par Codex et permet à l’ordre d’authentification de passer au profil openai:* suivant, sans changer le modèle sélectionné ni quitter le harnais Codex. Une fois l’heure de réinitialisation passée, le profil d’abonnement redevient admissible.

Génération d’images

Le plugin openai inclus enregistre la génération d’images au moyen de l’outil image_generate. Il prend en charge la génération d’images avec une clé d’API OpenAI et avec 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 d’images à partir de texte et la retouche d’images avec OpenAI. gpt-image-1.5, gpt-image-1 et gpt-image-1-mini restent utilisables comme remplacements explicites du modèle. 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, appelez image_generate avec model: "openai/gpt-image-1.5", outputFormat: "png" ou "webp", ainsi que background: "transparent" ; l’ancienne option de fournisseur openai.background est toujours acceptée. OpenClaw protège également les routes publiques OpenAI et OAuth OpenAI Codex en réécrivant les requêtes transparentes openai/gpt-image-2 par défaut en gpt-image-1.5 ; Azure et les points de terminaison personnalisés compatibles avec OpenAI conservent leurs noms de déploiement/modèle configurés.

Le même réglage est disponible pour les exécutions sans interface de la CLI :

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "Un autocollant représentant un simple cercle rouge sur un arrière-plan transparent" \  --json

Utilisez les mêmes options --output-format et --background avec openclaw infer image edit lorsque vous partez d’un fichier d’entrée. --openai-background reste disponible comme alias propre à OpenAI. Utilisez --quality low|medium|high|auto pour contrôler la qualité et le coût d’OpenAI Images. Utilisez --openai-moderation low|auto pour transmettre l’indication de modération d’OpenAI depuis image generate ou image edit.

Pour les installations OAuth ChatGPT/Codex, conservez la même référence openai/gpt-image-2. Lorsqu’un profil OAuth openai est configuré, OpenClaw résout le 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. Configurez explicitement models.providers.openai avec une clé d’API, une URL de base personnalisée ou un point de terminaison Azure lorsque vous souhaitez utiliser directement la route de l’API OpenAI Images. Si ce point de terminaison d’image personnalisé se trouve sur une adresse de réseau local/privée de confiance, définissez également browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ; OpenClaw maintient les points de terminaison d’image privés/internes compatibles avec OpenAI bloqués en l’absence de cette activation explicite.

Générer :

/tool image_generate model=openai/gpt-image-2 prompt="Une affiche de lancement soignée pour OpenClaw sur macOS" size=3840x2160 count=1

Générer un PNG transparent :

/tool image_generate model=openai/gpt-image-1.5 prompt="Un autocollant représentant un simple cercle rouge sur un arrière-plan transparent" outputFormat=png background=transparent

Modifier :

/tool image_generate model=openai/gpt-image-2 prompt="Conserver la forme de l’objet et remplacer le matériau par du verre translucide" image=/path/to/reference.png size=1024x1536

Génération de vidéos

Le plugin openai inclus enregistre la génération de vidéos au moyen de l’outil video_generate.

Les requêtes image-vers-vidéo OpenAI utilisent POST /v1/videos avec une image input_reference. Les modifications d’une seule vidéo utilisent POST /v1/videos/edits avec la vidéo téléversée dans le champ video.

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

Contribution à l’invite GPT-5

OpenClaw ajoute une contribution partagée à l’invite GPT-5 pour les modèles de la famille GPT-5 sur le fournisseur openai (y compris les anciennes références Codex antérieures à la réparation, qui sont normalisées en openai/*). Les autres fournisseurs qui proposent également des identifiants de modèles de la famille GPT-5, tels qu’OpenRouter ou les routes opencode, ne reçoivent pas cette surcouche ; son activation dépend de l’identifiant de fournisseur openai, et non du seul identifiant de modèle. Les anciens modèles GPT-4.x ne la reçoivent jamais.

Le harnais natif du serveur d’application Codex ne reçoit pas le contrat de comportement relatif à la personnalité et à la discipline d’utilisation des outils, ni la surcouche de style d’interaction convivial, par l’intermédiaire des instructions du développeur ; le Codex natif conserve les comportements de base, de modèle et de documentation du projet propres à Codex, et OpenClaw désactive la personnalité intégrée de Codex pour les fils natifs afin que les fichiers de personnalité de l’espace de travail de l’agent restent la référence. OpenClaw apporte uniquement le contexte d’exécution aux fils Codex natifs : distribution par canal, outils dynamiques OpenClaw, délégation ACP, contexte de l’espace de travail et Skills OpenClaw. Le texte d’orientation du Heartbeat issu de cette même contribution constitue l’unique exception : les tours de Heartbeat Codex natifs le reçoivent bien, injecté sous forme d’instructions de collaboration dédiées plutôt que par l’intermédiaire du point d’extension partagé de contribution à l’invite.

La contribution GPT-5 ajoute un contrat de comportement balisé pour la persistance de la personnalité, la sécurité d’exécution, la discipline d’utilisation des outils, la forme de la sortie, les vérifications d’achèvement et la validation dans les invites correspondantes assemblées par OpenClaw. Le comportement des réponses propres aux canaux et des messages silencieux reste défini dans l’invite système partagée d’OpenClaw et dans la politique de distribution sortante. La couche de style d’interaction convivial 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", speakerVoice: "coral" },      },    },  },}

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

Points de terminaison Azure OpenAI

Le fournisseur openai intégré 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 dans models.providers.openai.baseUrl et adopte automatiquement le format de requête d’Azure.

Utilisez Azure OpenAI dans les cas suivants :

• Vous disposez déjà d’un abonnement Azure OpenAI, d’un quota ou d’un contrat 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 au sein d’un locataire Azure existant

Configuration

Pour la génération d’images Azure via le fournisseur openai intégré, faites pointer 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 les suffixes d’hôte Azure suivants 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 propres 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 600s pour les appels de génération d’images Azure. Les valeurs timeoutMs propres à chaque appel remplacent toujours cette valeur par défaut.

Les autres URL de base (OpenAI public, proxys compatibles avec OpenAI) conservent le format standard des requêtes d’images OpenAI.

Version de l’API

Définissez AZURE_OPENAI_API_VERSION pour fixer une version préliminaire ou GA spécifique d’Azure 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 routées via le fournisseur openai intégré, le champ model dans OpenClaw doit correspondre au nom du 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 nommé gpt-image-2-prod qui fournit gpt-image-2 :

/tool image_generate model=openai/gpt-image-2-prod prompt="Une affiche épurée" size=1024x1024 count=1

La même règle concernant le nom du déploiement s’applique à tout appel de génération d’images routé 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 vérifiez que le modèle concerné est proposé dans votre région.

Différences entre les paramètres

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

Configuration avancée

Les exemples params propres à chaque modèle ci-dessous définissent la requête du fournisseur intégré d’OpenClaw. Leur configuration constitue un comportement de requête explicite ; une route auto par ailleurs admissible reste donc sur OpenClaw au lieu de sélectionner implicitement Codex. Le harnachement natif du serveur d’application Codex gère son propre transport et ses propres paramètres de requête ; une valeur agentRuntime.id: "codex" explicite échoue de manière fermée lorsque la route effective n’est pas déclarée compatible avec 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" },    },  },}

Voir aussi