OpenAI

OpenClaw utilise un identifiant de fournisseur unique, openai, pour l’authentification directe par clé 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 la route d’OpenAI déterminent si OpenClaw peut sélectionner implicitement l’environnement d’exécution groupé du serveur d’application Codex. 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 la configuration explicite agentRuntime 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é 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 openai par clé API.
• Configuration héritée - les anciennes références de modèles Codex et les anciens identifiants de profils sont convertis en openai/* par openclaw doctor --fix.

OpenAI prend explicitement en charge l’utilisation d’OAuth avec un abonnement dans des outils externes et des flux de travail tels qu’OpenClaw.

Suivi de l’utilisation et des coûts

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

• OAuth ChatGPT/Codex affiche l’offre d’abonnement, les fenêtres de quota et le solde de crédits.
• OPENAI_ADMIN_KEY affiche 30 jours de coûts de l’organisation et d’utilisation des complétions communiqués par le fournisseur dans Usage de l’interface de contrôle, notamment les dépenses quotidiennes, les totaux de requêtes/jetons, les principaux modèles et les catégories de coûts.
• OPENAI_PROJECT_ID permet éventuellement de limiter l’historique de l’API Admin à 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é Admin explicite a priorité sur OAuth. L’historique communiqué par le fournisseur n’est pas fusionné avec l’estimation des coûts dérivée des sessions d’OpenClaw ; il peut inclure l’activité API d’autres clients et des ajustements de facturation effectués par le 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 vous confondez ces libellés, 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 appartenant au fournisseur OpenAI choisit l’environnement d’exécution implicite selon le point de terminaison et l’adaptateur effectifs :

Un agentRuntime.id de fournisseur/modèle explicite et différent de la valeur par défaut reste prioritaire. Par exemple, agentRuntime.id: "openclaw" maintient sur OpenClaw une route qui serait autrement éligible à Codex, tandis que agentRuntime.id: "codex" impose 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’identifiant ni la facturation : l’authentification par clé API Platform et l’authentification par abonnement ChatGPT/Codex restent distinctes.

openclaw doctor --fix migre les références de modèles Codex héritées, les identifiants de profils d’authentification Codex hérités et les anciennes entrées d’ordre d’authentification vers la route canonique openai. 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èles exacts openai/gpt-5.6-sol, openai/gpt-5.6-terra et openai/gpt-5.6-luna. Tous trois proposent les niveaux de 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 du lancement de GPT-5.6 et le guide d’accès.

Avec l’authentification directe par clé API OpenAI, l’identifiant sans suffixe openai/gpt-5.6 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 à 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 provenant du service en amont et ne remplace pas silencieusement une sélection GPT-5.6 par GPT-5.5.

Couverture fonctionnelle d’OpenClaw

Embeddings de mémoire

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

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

Pour les points de terminaison compatibles avec OpenAI qui nécessitent des libellés d’embedding asymétriques, définissez queryInputType et documentInputType sous memorySearch. OpenClaw les transmet sous forme de 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.

Bien démarrer

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 des références de modèle openai/* lorsqu’une route HTTPS officielle exacte admissible le sélectionne implicitement, ou lorsque la valeur 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. Les 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 hérités et l’ordre d’authentification.
2. Le compte existant du serveur d’application, par exemple une connexion ChatGPT à la CLI Codex locale. Pour le répertoire personnel isolé par défaut de l’agent, OpenClaw transmet ce compte CLI natif au serveur d’application au moyen de son RPC de connexion ; il ne partage pas la configuration, les plugins ni le magasin de fils de discussion de la CLI.
3. Uniquement pour les lancements locaux du serveur d’application via stdio, et seulement lorsque le serveur d’application ne signale aucun compte : CODEX_API_KEY, puis OPENAI_API_KEY.

Une connexion locale avec 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 plongements. Le recours à la clé API d’environnement ne s’applique qu’au chemin local stdio sans compte ; elle n’est jamais envoyée via les connexions WebSocket au serveur d’application. Lorsqu’un profil Codex de type abonnement est sélectionné, OpenClaw exclut également CODEX_API_KEY et OPENAI_API_KEY du processus enfant du serveur d’application stdio lancé et envoie à la place les identifiants sélectionnés au moyen du 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 modifier 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 intégré enregistre la génération d’images au moyen de l’outil image_generate. Il prend en charge la génération d’images par clé API OpenAI et OAuth Codex au moyen de 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 le modèle 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 produire des fichiers PNG/WebP à arrière-plan transparent ; l’API gpt-image-2 actuelle rejette background: "transparent".

Pour une demande d’arrière-plan transparent, appelez 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 également les routes publiques OpenAI et OAuth OpenAI Codex en réécrivant les demandes transparentes utilisant par défaut openai/gpt-image-2 vers 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 de CLI sans interface :

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 demandes d’images via le service principal Codex Responses ; il n’essaie pas d’abord OPENAI_API_KEY et ne bascule pas silencieusement vers une clé API. Configurez explicitement models.providers.openai avec une clé API, une URL de base personnalisée ou un point de terminaison Azure lorsque vous souhaitez utiliser à la place la route directe de l’API OpenAI Images. Si ce point de terminaison d’images personnalisé se trouve sur une adresse de réseau local/de réseau privé fiable, définissez également browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ; OpenClaw maintient les points de terminaison d’images privés/internes compatibles avec OpenAI bloqués sans 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, remplacer le matériau par du verre translucide" image=/path/to/reference.png size=1024x1536

Génération de vidéos

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

Les demandes OpenAI d’image vers vidéo 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 au prompt GPT-5

OpenClaw ajoute une contribution partagée au prompt 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, comme OpenRouter ou les routes opencode, ne reçoivent pas cette surcouche ; elle est conditionnée par l’identifiant de fournisseur openai, et non par le 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 persona et à la discipline d’utilisation des outils, ni la surcouche de style d’interaction convivial par l’intermédiaire des instructions du développeur ; Codex natif conserve les comportements de base, du modèle et de la documentation du projet qui lui sont propres, 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 fournit uniquement le contexte d’exécution aux fils Codex natifs : acheminement par canal, outils dynamiques OpenClaw, délégation ACP, contexte de l’espace de travail et Skills OpenClaw. Le texte d’orientation Heartbeat issu de cette même contribution constitue la seule exception : les tours Heartbeat de Codex natif le reçoivent, injecté sous forme d’instructions de collaboration dédiées plutôt que par l’intermédiaire du mécanisme partagé de contribution au prompt.

La contribution GPT-5 ajoute un contrat de comportement balisé pour la persistance de la persona, la sécurité d’exécution, la discipline d’utilisation des outils, la forme de la sortie, les contrôles d’achèvement et la vérification dans les prompts correspondants assemblés par OpenClaw. Les comportements propres aux canaux pour les réponses et les messages silencieux restent dans le prompt système partagé d’OpenClaw et dans la politique d’acheminement sortant. 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 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 dans models.providers.openai.baseUrl et adopte automatiquement le format de requête d’Azure.

Utilisez Azure OpenAI lorsque :

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

Configuration

Pour générer des images avec Azure au moyen du fournisseur openai inclus, définissez models.providers.openai.baseUrl sur votre ressource Azure et 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ôtes 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 imposer une version préliminaire ou GA précise 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 par le fournisseur openai inclus, le champ model dans OpenClaw doit être le 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 relative au nom du déploiement s’applique à tout appel de génération d’images routé par le fournisseur openai inclus.

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 de 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 avec gpt-image-2) ou ne les proposer que pour des versions de modèle précises. 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, vérifiez 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 de 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 normalement admissible reste donc sur OpenClaw au lieu de sélectionner implicitement Codex. Le harnais natif du serveur d’application Codex gère son propre transport et ses propres paramètres de requête ; 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" },    },  },}

Contenu associé