OpenAI

OpenAI fournit des API développeur pour les modèles GPT, et Codex est également disponible comme agent de codage avec abonnement 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 défaut par le runtime natif du serveur d’application Codex ; 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 openai-codex pour utiliser un abonnement ChatGPT/Codex, ou configurez un profil de clé d’API openai-codex lorsque vous voulez intentionnellement une authentification par clé d’API.
• API OpenAI hors agent - accès direct à OpenAI Platform 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 vers openai/* avec le runtime Codex.

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

Le fournisseur, le modèle, le runtime et le canal sont des couches séparées. Si ces libellés se mélangent, lisez Runtimes d’agent avant de modifier la configuration.

# Choix rapide

# Carte de nommage

Les noms sont similaires, mais non interchangeables :

Cela signifie qu’une configuration peut intentionnellement contenir à la fois des références de modèle openai/* et des profils d’authentification openai-codex. 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 point de terminaison 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 points de terminaison compatibles OpenAI qui nécessitent des libellés d’embeddings 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 lot utilisent documentInputType. Consultez la référence de configuration de la mémoire pour l’exemple complet.

# Premiers pas

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

# Authentification native du serveur d'application Codex

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

1. Un profil d'authentification OpenClaw openai-codex explicite lié à l'agent.
2. Le compte existant du serveur d'application, comme une connexion ChatGPT locale avec la CLI Codex.
3. Pour les lancements locaux de serveur d'application stdio uniquement, CODEX_API_KEY, puis OPENAI_API_KEY, lorsque le serveur d'application ne signale aucun compte et nécessite toujours 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 repli par clé API d'environnement n'est que le chemin local stdio sans compte ; elle n'est pas envoyée aux connexions WebSocket du serveur d'application. Lorsqu'un profil Codex de type abonnement est sélectionné, OpenClaw garde aussi CODEX_API_KEY et OPENAI_API_KEY hors du processus enfant stdio de serveur d'application lancé et envoie les identifiants sélectionnés via le RPC de connexion du serveur d'application.

# Génération d'images

Le Plugin openai intégré 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é API OpenAI et la génération d'images 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 texte-vers-image OpenAI comme pour l'édition d'images. gpt-image-1.5, gpt-image-1 et gpt-image-1-mini restent utilisables comme remplacements explicites de 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 d'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 OAuth OpenAI public et OpenAI Codex en réécrivant les requêtes transparentes openai/gpt-image-2 par défaut vers gpt-image-1.5 ; Azure et les endpoints 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é API pour cette requête. Configurez explicitement models.providers.openai avec une clé API, une URL de base personnalisée ou un endpoint Azure lorsque vous voulez la route directe de l'API OpenAI Images à la place. Si cet endpoint d'image personnalisé se trouve sur un LAN/adresse privée de confiance, définissez aussi browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ; OpenClaw garde les endpoints d'image privés/internes compatibles OpenAI bloqués sauf si cette adhésion explicite 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 de vidéos 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 sur l'ensemble des fournisseurs. Elle s'applique par id de modèle, donc openai/gpt-5.5, les références héritées avant réparation comme openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 et les autres références compatibles GPT-5 reçoivent la même couche. 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 couche Heartbeat via les instructions développeur du serveur d'application Codex, de sorte que les sessions openai/gpt-5.x forcées via agentRuntime.id: "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 des 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 partagé d’OpenClaw et la politique de livraison sortante. Les consignes GPT-5 sont toujours activées pour les modèles correspondants. La couche de style d’interaction amicale est séparée 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 Azure.

Utilisez Azure OpenAI lorsque :

• Vous avez déjà un abonnement Azure OpenAI, un quota ou un contrat entreprise
• Vous avez besoin de la résidence régionale des données ou des contrôles de conformité fournis par Azure
• Vous voulez garder le trafic dans une location Azure existante

# 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 (pas 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 par défaut de 600 s pour les appels de génération d’images Azure. Les valeurs timeoutMs propres à l’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 d’API

Définissez AZURE_OPENAI_API_VERSION pour épingler une version Azure preview ou GA spécifique 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 lie les modèles aux déploiements. Pour les requêtes de génération d’images Azure routées via le fournisseur openai inclus, 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 du modèle OpenAI public.

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 routés via le fournisseur openai inclus.

# Disponibilité régionale

La génération d’images Azure est actuellement disponible uniquement dans un sous-ensemble de régions (par exemple eastus2, swedencentral, polandcentral, westus3, uaenorth). Consultez la liste actuelle des régions 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 les exposer uniquement sur certaines versions de modèle. 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, vérifiez le jeu de paramètres pris en charge par votre déploiement et votre version d’API spécifiques dans le portail Azure.

# Configuration avancée

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

# Connexe