Connect Codex

Utilisez Codex dans votre terminal ou l’application de bureau ChatGPT avec les modèles, les outils MCP et les compétences via Unity Gateway. Utilisez l’interface de ligne de commande Unity Gateway (ug) pour configurer l’accès, ou configurez la connexion manuellement.

Pour connecter des outils à une configuration Codex existante, allez dans Ajouter des outils MCP.

Prerequisites

Vous avez besoin de l’URL de votre espace de travail Azure Databricks et de l’accès aux modèles, MCP et compétences que vous souhaitez utiliser. Installez la dernière version de Codex ou l’application de bureau ChatGPT.

Si votre administrateur a déjà configuré votre appareil, suivez les instructions de lancement de votre organisation.

Codex dans le terminal

Installez ug, puis exécutez cette commande depuis le répertoire de votre projet :

ug codex

Suivez les instructions pour sélectionner votre espace de travail et vous connecter. ug configure la connexion et ouvre Codex dans votre terminal. Commencez à travailler avec les mêmes indications et commandes que vous utilisez déjà. Pour changer de modèle, entrez /model.

Continuez à ajouter des outils MCP ou à ajouter des compétences pour donner au Codex accès aux données et instructions partagées.

Ordinateur de bureau ChatGPT

Sur macOS et Linux, installez ug et exécutez cette commande dans un terminal interactif :

ug configure --agents codex

Sélectionnez votre espace de travail et connectez-vous. Si vous le demandez, approuvez la mise à jour de configuration système avec le mot de passe de votre appareil. ug configure la connexion Unity Gateway et le rafraîchissement du jeton OAuth.

Ouvrez ou redémarrez l’application de bureau et lancez une conversation Codex. Utilisez le sélecteur de modèles pour changer de modèle. La ug codex commande ouvre l’agent du terminal ; ouvre normalement l’application de bureau après la configuration.

Sous Windows, utilisez la configuration manuelle du modèle ci-dessous. Vous pouvez toujours utiliser ug mcp add et ug skills add ajouter des outils et des compétences, puis redémarrer l’application.

Configurez les modèles manuellement

Ces paramètres s’appliquent à la fois à l’agent terminal et à l’application de bureau. Fermez le Codex, puis ouvrez ou créez ~/.codex/config.toml. Sous Windows, utilisez la commande %USERPROFILE%\.codex\config.toml.

Fusionnez les paramètres suivants dans le fichier. Conservez model et model_provider au niveau supérieur, avant tout en-tête de tableau, et préservez les paramètres non associés.

model = "<catalog>.<schema>.<model-name>"
model_provider = "databricks"

[model_providers.databricks]
name = "Databricks"
base_url = "https://<workspace-hostname>/ai-gateway/codex/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
http_headers = { Authorization = "Bearer <databricks-pat>" }

Remplacez le modèle provisoire par son nom complet du catalogue Unity, <workspace-hostname> par votre nom d’hôte d’espace de travail, et <databricks-pat> par votre jeton d’accès personnel. Cet exemple stocke le jeton localement ; gardez le fichier privé et utilisez votre propre jeton.

Exécutez codex depuis votre répertoire de projet ou rouvrez l’application de bureau. Si votre appareil a des paramètres gérés du fournisseur, demandez à votre administrateur de les mettre à jour ; ces paramètres ont priorité sur cette configuration utilisateur.

Voir la référence de configuration d’OpenAI pour les détails sur le champ.

Ajouter des outils MCP

Pour utiliser system.ai.dbsql, system.ai.sandbox, ou system.ai.web_search, un administrateur de compte doit activer la bêta Unity Gateway depuis la page Aperçus de la console de compte. Voir Gérer les aperçus du compte.

  1. Ouvrez Unity Gateway MCPs > dans votre espace de travail. Choisissez un MCP intégré ou enregistrez votre serveur MCP externe.
  2. Copiez le nom complet du MCP, comme system.ai.github ou <catalog>.<schema>.<service>.
  3. Confirmez que vous avez accès au MCP.

Utilisez l’interface de ligne de commande Unity Gateway

Installez ug, puis ajoutez le MCP au Codex :

ug mcp add --agents codex --names <catalog>.<schema>.<service>

Remplacez l’espace réservé par le nom que vous avez copié. Par exemple, utilisez --names system.ai.github pour GitHub. Pour choisir les services de manière interactive, omettez --names.

Lors de la première configuration, suivez les instructions pour sélectionner votre espace de travail, vous connecter et choisir un modèle. ug configure à la fois l’accès au modèle et au MCP, et actualise les informations d’identification. Pour accéder au MCP avec votre propre application OAuth, utilisez la configuration manuelle ci-dessous.

Redémarrez Codex avec ug codex, ou rouvrez l’application de bureau, puis testez un outil.

Configurez les MCP manuellement

Utilisez une application publique Azure Databricks OAuth pour vous connecter et rafraîchir les identifiants. Ces paramètres s’appliquent à l’agent terminal et à l’application de bureau.

Configurez une application OAuth

  1. Fermez le Codex. Dans ~/.codex/config.toml, ajoutez ces réglages au niveau supérieur, avant tout en-tête de tableau. Ils donnent au callback OAuth local un port fixe :

    mcp_oauth_callback_port = 8080
mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"

  2. Demandez à un administrateur de compte d’ouvrir Paramètres > Connexions d’application > Ajouter une connexion dans la console du compte. Utilisez un nom tel que codex-mcp, décochez Générer une clé secrète client, définissez l’URL de redirection sur http://127.0.0.1:8080/callback, et sélectionnez l’étendue ai-gateway. Sauvegardez et copiez l’identifiant client. Voir Créer une application OAuth.

  3. Enregistrez le MCP dans le Codex, en remplaçant les espaces réservés :

    codex mcp add databricks-tools \
  --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>" \
  --oauth-client-id <client-id>

  4. Vérifiez l’URL de rappel imprimée par Codex. Il peut inclure un suffixe spécifique au serveur. Faites ajouter à l’administrateur cette URL exacte aux URL de redirection de l’application OAuth avant de vous connecter. Répétez cette vérification lors de l’ajout d’un autre serveur.

  5. Connectez-vous, puis rouvrez Codex :

    codex mcp login databricks-tools --scopes ai-gateway,offline_access

Pour les paramètres de rappel d’URL, consultez les instructions d’authentification MCP d’OpenAI. Ensuite, testez un outil.

Utilisez un jeton d’accès personnel pour les tests locaux

Ajouter ce qui suit à ~/.codex/config.toml, remplaçant le nom d’hôte et le jeton :

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
http_headers = { Authorization = "Bearer <databricks-pat>" }

Pour un autre MCP, utilisez un nom unique sous mcp_servers et remplacez system.ai.dbsql par son nom complet. Gardez le fichier privé, puis redémarrez Codex et testez un outil.

Tester un outil MCP

  1. Dans Codex, saisissez /mcp et vérifiez que le serveur est connecté.
  2. Demandez à Codex de lister les outils de ce serveur, puis demandez une opération de lecture. Pour GitHub, demandez-lui de trouver un problème dans un dépôt auquel vous pouvez accéder. Pour un serveur personnalisé, utilisez un outil et des paramètres que vous avez testés lors de l’enregistrement.
  3. Si un appel d’outil vous invite à vous connecter, ouvrez le lien de connexion envoyé par le MCP, accordez le consentement du fournisseur, puis réessayez l’appel. Cette connexion donne au MCP l’accès à votre compte externe.
  4. Vérifiez que Codex effectue un appel à l’outil et renvoie son résultat. Une réponse textuelle seule ne confirme pas la connexion.

Pour utiliser les données Azure Databricks, connectez-vous à system.ai.genie_one_mcp pour des questions métier ou à system.ai.dbsql pour SQL. Par exemple, demandez au MCP SQL d’exécuter SELECT 1 AS result.

Pour les permissions, les politiques et l’utilisation, voir Gouverner un MCP.

Ajouter des compétences

Utilisez l’interface de ligne de commande Unity Gateway

Exécutez le sélecteur interactif :

ug skills add

Ou téléchargez une compétence spécifique publiée :

ug skills add --names <catalog>.<schema>.<skill-name>

Redémarrez Codex ou l’application de bureau. Les compétences téléchargées sont disponibles localement dans ~/.agents/skills/. Relance le téléchargement pour obtenir une version mise à jour.

Pour exposer les compétences d’un schéma via MCP, exécutez plutôt :

ug skills add --location "<catalog>.<schema>" --via mcp

Connectez manuellement le registre des compétences

Ajoutez les éléments suivants à ~/.codex/config.toml:

[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }

Remplacez le nom d’hôte et le jeton. Conservez le slash final dans l’URL. Redémarrez Codex et demandez-lui d’utiliser une compétence publiée, comme Use <catalog>.<schema>.<skill-name> to review this query.

Le registre charge les instructions de compétence via MCP. Pour installer les fichiers de skill que vous possédez déjà, placez le dossier complet de la skill, y compris SKILL.md et les fichiers inclus, dans ~/.agents/skills/.

Les compétences de la passerelle Unity sont en bêta. Voir Compétences de gouvernance pour l’habilitation et les autorisations.

Troubleshooting

  • L’application de bureau demande toujours la connexion OpenAI : Sur macOS ou Linux, relancez ug configure --agents codex l’écran de façon interactive et terminez la mise à jour de configuration système. Le profil CLI seul ne configure pas l’application de bureau. Pour la configuration manuelle, vérifiez que model_provider se trouve au niveau supérieur et que requires_openai_auth = false figure dans la table des fournisseurs. N’ajoutez pas ce drapeau à un fournisseur qui utilise une table auth pour actualiser les jetons OAuth.

  • Les requêtes échouent avec une erreur WebSocket : Défini supports_websockets = false dans la table active des fournisseurs Azure Databricks. Si votre administrateur gère cette configuration, demandez-lui de la mettre à jour. Redémarre l’application ensuite.

  • Un modèle manque : Vérifiez vos autorisations de modèle. Définissez model sur son nom complet dans Unity Catalog dans la configuration active et démarrez une nouvelle conversation.

  • Une connexion MCP ou Skill échoue : Vérifiez l’URL, les permissions et l’erreur du connecteur. Pour les connexions manuelles, vérifiez également l’expiration du jeton. Pour les ug problèmes de configuration, exécutez ug doctor. Une compétence téléchargée peut rester disponible même si la connexion au registre échoue.

  • La connexion Workspace fonctionne, mais un outil vous demande de vous connecter : Ouvrez le lien de connexion envoyé par le MCP, connectez-vous au fournisseur externe, puis réessayez l’appel. La connexion à l’espace de travail et la connexion au fournisseur sont des étapes distinctes.

  • OAuth signale un désaccord de redirection ou la connexion expire : Associez l’URL de redirection de l’application OAuth à l’URL exacte que le Codex rapporte, y compris n’importe quel suffixe, et vérifiez l’accès au réseau. Les modifications de l’application OAuth peuvent prendre jusqu’à 30 minutes avant de prendre effet.

Étapes suivantes

  • Dernière mise à jour :