Connect Codex

Utilisez Codex dans votre terminal avec des modèles, des outils MCP et des skills 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, de l’accès aux modèles, aux MCP et aux compétences que vous souhaitez utiliser, ainsi que de la dernière version de Codex CLI.

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

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.

Configurez les modèles manuellement

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 annuaire de projet. 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 la ligne de commande Codex avec ug codex, puis testez un outil.

Configurez les MCP manuellement

Utilisez une application publique Azure Databricks OAuth pour vous connecter et rafraîchir les identifiants.

Pour utiliser l’identifiant client Codex par défaut, qui n’a pas besoin d’un administrateur de compte pour créer une application OAuth :

  1. 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>?o=<workspace-id>" \
  --oauth-client-id https://chatgpt.com/oauth/codex/client.json

  2. Connectez-vous, puis rouvrez Codex :

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

Ensuite, testez un outil.

Configurez une application OAuth personnalisée

  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>?o=<workspace-id>" \
  --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

Ajoutez ce qui suit à ~/.codex/config.toml, remplaçant le nom d’hôte, l’identifiant de l’espace de travail et le jeton :

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql?o=<workspace-id>"
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 l’interface en ligne de commande Codex. 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

  • 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 :