Aller au contenu principal
Dernière mise à jour le

Connecter Codex

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

Pour connecter des outils à une configuration Codex existante, accédez à Ajouter des outils MCP.

Prérequis​

Vous avez besoin de l'URL de votre workspace Databricks et d'un accès aux modèles, aux MCP et aux compétences que vous souhaitez utiliser. Installez la dernière version de Codex ou de 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​

Utilisez Unity Gateway CLI (recommandé)​

Installez ug, puis exécutez cette commande à partir du répertoire de votre projet :

Bash
ug codex

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

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

Bureau ChatGPT​

Utilisez Unity Gateway CLI (recommandé)​

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

Bash
ug configure --agents codex

Sélectionnez votre Workspace et connectez-vous. Si vous y êtes invité, approuvez la mise à jour de la configuration du système à l’aide du mot de passe de votre appareil. ug configure la connexion à la passerelle Unity et le refresh des jetons OAuth.

Ouvrez ou redémarrez l'application de bureau et start une conversation Codex. Utilisez le sélecteur de modèle pour changer de modèle. La commande ug codex ouvre l'agent de terminal ; ouvrez l'application de bureau normalement 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 pour ajouter des outils et des compétences, puis redémarrer l'application.

Configurer les modèles manuellement​

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

Merge les paramètres suivants dans le fichier. Conservez model et model_provider au niveau supérieur, avant les en-têtes de table, et préservez les paramètres sans rapport.

Toml
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 l’espace réservé du modèle par son nom Unity Catalog complet, <workspace-hostname> par le hostname de votre workspace et <databricks-pat> par votre jeton d’accès personnel. Cet exemple stocke le jeton localement ; veillez à garder le fichier privé et utilisez votre propre jeton.

Run codex from your project directory or reopen the desktop app. If your device has managed provider settings, ask your admin to update them; those settings take precedence over this user configuration.

Consultez la référence de configuration d'OpenAI pour plus de détails sur les champs.

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 de Unity Gateway à partir de la page Previews de la console du compte. Consultez Gérer les aperçus du compte.

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

Utilisez la CLI de Unity Gateway​

Installez ug, puis ajoutez le serveur MCP à Codex :

Bash
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 workspace, vous connecter et choisir un modèle. ug configure à la fois l'accès aux modèles et aux outils MCP et refresh les identifiants. Pour un accès 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​

Use a public Databricks OAuth app to sign in and refresh credentials. These settings apply to the terminal agent and desktop app.

Configurer une application OAuth

  1. Fermez Codex. Dans ~/.codex/config.toml, ajoutez ces paramètres au niveau supérieur, avant tout en-tête de table. Ils attribuent un port fixe au callback local OAuth :

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

  2. Demandez à un administrateur de compte d'ouvrir Settings > App connections > Add connection dans la console du compte. Utilisez un nom tel que codex-mcp, décochez Générer un secret client , définissez l'URL de redirection sur http://127.0.0.1:8080/callback et sélectionnez le périmètre ai-gateway. Enregistrez et copiez l' ID de client . Consultez Créer une application OAuth.

  3. Enregistrer le MCP dans Codex en remplaçant les placeholders :

    Bash
    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 affichée par Codex. Il peut inclure un suffixe spécifique au serveur. Demandez à l'administrateur d'ajouter 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 :

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

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

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

Ajoutez les éléments suivants à ~/.codex/config.toml, en remplaçant le hostname et le jeton :

Toml
[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. Préservez la confidentialité du fichier, puis redémarrez Codex et testez un outil.

Tester un outil MCP​

  1. Dans Codex, entrez /mcp et vérifiez que le serveur est connecté.
  2. Demandez à Codex de répertorier les outils de ce serveur, puis demandez une opération de lecture. Pour GitHub, demandez-lui de trouver un problème dans un repository auquel vous pouvez accéder. Pour un serveur personnalisé, utilisez un outil et des entrées que vous avez testés lors de l'enregistrement.
  3. Si un appel d'outil vous invite à vous connecter, ouvrez le Link de connexion renvoyé par le MCP, terminez le consentement du fournisseur, puis réessayez l'appel. Cette connexion donne au MCP accès à votre compte externe.
  4. Vérifiez que Codex effectue un appel d'outil et renvoie son résultat. Une seule réponse textuelle ne permet pas de vérifier la connexion.

Pour utiliser des données Databricks, connectez system.ai.genie_one_mcp pour les questions métiers ou system.ai.dbsql pour SQL. Par exemple, demandez au serveur MCP SQL d'exécuter SELECT 1 AS result.

Pour en savoir plus sur les autorisations, les politiques et l'utilisation, consultez Gouverner un MCP.

Ajouter des compétences​

Utilisez la CLI de Unity Gateway​

Exécuter le sélecteur interactif :

Bash
ug skills add

Ou download une compétence publiée spécifique :

Bash
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/. Réexécutez le download pour obtenir une version mise à jour.

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

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

Connectez manuellement le registre des compétences​

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

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

Remplacez le hostname et le jeton. Conservez la barre oblique de fin dans l'URL. Redémarrez Codex et demandez-lui d'utiliser une compétence publiée, telle que Use <catalog>.<schema>.<skill-name> to review this query.

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

Les compétences Unity Gateway sont en version bêta. Consultez la rubrique Gérer les compétences pour en savoir plus sur l'activation et les autorisations.

Dépannage​

  • L’application de bureau demande toujours une connexion OpenAI : sous macOS ou Linux, réexécutez ug configure --agents codex de manière interactive et terminez la mise à jour de la configuration du système. Le profil CLI à lui seul ne configure pas l’application de bureau. Pour une configuration manuelle, vérifiez que model_provider se trouve au niveau supérieur et que requires_openai_auth = false est présent dans la table des fournisseurs. N’ajoutez pas cet indicateur à un fournisseur qui utilise une table auth pour le refresh du jeton OAuth.

  • Les requêtes échouent avec une erreur WebSocket : définissez supports_websockets = false dans la table du fournisseur Databricks active. Si votre administrateur gère cette configuration, demandez-lui de la mettre à jour. Redémarrez l'application ensuite.

  • Un modèle est manquant : vérifiez les autorisations de votre modèle. Définissez model sur son nom Unity Catalog complet dans la configuration active et start une nouvelle conversation.

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

  • La connexion au workspace fonctionne, mais un outil vous demande de vous connecter : Ouvrez le link de connexion renvoyé par le MCP, connectez-vous au fournisseur externe, puis réessayez l’appel. La connexion au workspace et celle au fournisseur sont deux étapes distinctes.

  • OAuth signale une incompatibilité de redirection ou la connexion expire : faites correspondre l'URL de redirection de l'application OAuth à l'URL exacte signalée par Codex, y compris tout suffixe, et vérifiez l'accès réseau. Les modifications apportées à l'application OAuth peuvent prendre jusqu'à 30 minutes pour être effectives.

Étapes suivantes​

Sur cette page