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.
Avant de commencer
You need your Databricks workspace URL and access to the models, MCP services, and skills you want to use. Install the latest version of Codex or the ChatGPT desktop app.
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 :
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.
Pour ajouter des outils ou des compétences MCP, exécutez ces commandes dans votre terminal, puis redémarrez Codex :
ug mcp add
ug skills add
Chaque commande vous permet de sélectionner ce qu'il faut ajouter. Pour la configuration manuelle, veuillez utiliser les sections de configuration ci-dessous.
Bureau ChatGPT
Utilisez Unity Gateway CLI (recommandé)
Sous macOS et Linux, installez ug et exécutez cette commande dans un terminal interactif :
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.
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
Utilisez la CLI de Unity Gateway
Exécutez cette commande et sélectionnez les services que vous souhaitez ajouter :
ug mcp add
Restart Codex or the desktop app, then ask it to use a connected tool. ug enregistre un proxy local qui authentifie les requêtes et effectue un refresh des identifiants.
Configurer manuellement les services MCP
Ajouter les éléments suivants à ~/.codex/config.toml:
[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
http_headers = { Authorization = "Bearer <databricks-pat>" }
Remplacez le hostname et le jeton, puis redémarrez Codex. Pour un autre service, utilisez un nom unique sous mcp_servers et remplacez system.ai.dbsql par son nom Unity Catalog en trois parties.
Pour la configuration d'OAuth, suivez les instructions d'authentification MCP d'OpenAI et enregistrez une application OAuth Databricks avec l'URL de rappel exacte qu'utilise Codex.
Ajouter des compétences
Utilisez la CLI de Unity Gateway
Exécuter le sélecteur interactif :
ug skills add
Ou download une compétence publiée spécifique :
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 :
ug skills add --location <catalog>.<schema> --mcp
Connectez manuellement le registre des compétences
Ajouter 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 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.