Verbinden Sie den Codex

Verwenden Sie Codex in Ihrem Terminal oder die ChatGPT-Desktop-App mit Modellen, MCP-Tools und Fähigkeiten über Unity Gateway. Verwenden Sie die Unity Gateway CLI (ug) zur Konfiguration des Zugriffs oder konfigurieren Sie die Verbindung manuell.

Um Tools mit einem bestehenden Codex-Setup zu verbinden, gehe zu Add MCP tools.

Prerequisites

Du brauchst die URL deines Azure Databricks Workspaces und Zugriff auf die Modelle, MCPs und Skills, die du nutzen möchtest. Installiere die neueste Version von Codex oder die ChatGPT-Desktop-App.

Wenn Ihr Administrator Ihr Gerät bereits konfiguriert hat, folgen Sie den Startanweisungen Ihrer Organisation.

Codex im Terminal

Installiere und führe ugdann diesen Befehl aus deinem Projektverzeichnis aus:

ug codex

Folgen Sie den Anweisungen, um Ihren Arbeitsbereich auszuwählen und sich anzumelden. ug konfiguriert die Verbindung und öffnet Codex in deinem Terminal. Fang an, mit denselben Eingabeaufforderungen und Befehlen zu arbeiten, die du bereits benutzt. Um die Modelle zu ändern, geben Sie /model ein.

Weiter mit MCP-Tools hinzufügen oder Skills hinzufügen, um Codex Zugriff auf Daten und geteilte Anweisungen zu geben.

ChatGPT-Desktop

Unter macOS und Linux installieren Sie ug und führen Sie diesen Befehl in einem interaktiven Terminal aus:

ug configure --agents codex

Wählen Sie Ihren Arbeitsbereich aus und melden Sie sich an. Wenn du aufgefordert wirst, genehmige das Systemkonfigurationsupdate mit deinem Gerätepasswort. ug konfiguriert die Unity Gateway-Verbindung und die OAuth-Token-Aktualisierung.

Öffne oder starte die Desktop-App neu und starte eine Codex-Konversation. Verwenden Sie den Modellwähler, um das Modell zu wechseln. Der ug codex Befehl öffnet den Terminalagenten; öffne die Desktop-App normalerweise nach der Konfiguration.

Unter Windows verwenden Sie die untenstehende manuelle Modellkonfiguration. Du kannst ug mcp add und ug skills add weiterhin verwenden, um Tools und Fähigkeiten hinzuzufügen, und dann die App neu starten.

Modelle manuell konfigurieren

Diese Einstellungen gelten sowohl für den Terminalagenten als auch für die Desktop-App. Schließen Sie Codex, dann öffnen oder erstellen Sie ~/.codex/config.toml. Unter Windows verwenden Sie %USERPROFILE%\.codex\config.toml.

Fügen Sie die folgenden Einstellungen in die Datei ein. Behalten Sie model und model_provider auf oberster Ebene vor allen Tabellenkopfzeilen bei, und behalten Sie nicht zugehörige Einstellungen bei.

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

Ersetzen Sie den Modell-Platzhalter durch den vollständigen Unity-Katalog-Namen, <workspace-hostname> durch Ihren Workspace-Hostnamen und <databricks-pat> durch Ihr persönliches Zugriffstoken. Dieses Beispiel speichert das Token lokal; halte die Datei privat und benutze dein eigenes Token.

Starte codex aus deinem Projektverzeichnis oder öffne die Desktop-App erneut. Wenn dein Gerät Einstellungen für verwaltete Anbieter hat, bitte deinen Administrator, sie zu aktualisieren; diese Einstellungen haben Vorrang vor dieser Benutzerkonfiguration.

Siehe die Konfigurationsreferenz von OpenAI für Felddetails.

MCP-Werkzeuge hinzufügen

Um system.ai.sandbox, system.ai.web_search oder system.ai.dbsql zu verwenden, muss ein Kontoadministrator die Unity Gateway-Beta auf der Seite Previews in der Kontokonsole aktivieren. Siehe Kontovorschauen verwalten.

  1. Öffnen Sie die Unity Gateway > MCPs in Ihrem Arbeitsbereich. Wählen Sie ein integriertes MCP oder registrieren Sie Ihren externen MCP-Server.
  2. Kopieren Sie den vollständigen Namen des MCP, wie zum Beispiel system.ai.github oder <catalog>.<schema>.<service>.
  3. Bestätigen Sie, dass Sie Zugang zum MCP haben.

Verwenden Sie die Unity Gateway CLI

Installiere ugund füge dann das MCP zum Codex hinzu:

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

Ersetze den Platzhalter durch den Namen, den du kopiert hast. Verwenden Sie zum Beispiel --names system.ai.github für GitHub. Um Dienste interaktiv auszuwählen, lassen Sie --names weg.

Beim ersten Einrichten folgen Sie den Anweisungen, wählen Sie Ihren Arbeitsbereich aus, melden Sie sich an und wählen Sie ein Modell aus. ug konfiguriert sowohl den Modell- als auch den MCP-Zugriff und aktualisiert die Zugangsdaten. Für den MCP-Zugriff mit deiner eigenen OAuth-App nutze die untenstehende manuelle Einrichtung.

Starte Codex neu mit ug codex, oder öffne die Desktop-App erneut und teste dann ein Tool.

MCPs manuell konfigurieren

Verwenden Sie eine öffentliche Azure Databricks OAuth-App, um sich anzumelden und die Zugangsdaten zu aktualisieren. Diese Einstellungen gelten für den Terminalagenten und die Desktop-App.

Richte eine OAuth-App ein

  1. Codex schließen. In ~/.codex/config.toml, fügen Sie diese Einstellungen auf der obersten Ebene hinzu, vor allen Tabellenüberschriften. Sie geben dem lokalen OAuth-Rückruf einen festen Port:

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

  2. Lass einen Kontoadministrator in der KontokonsoleEinstellungen > App-Verbindungen > Verbindung hinzufügen öffnen. Verwenden Sie einen Namen wie codex-mcp, deaktivieren Sie Generiere ein Client-Secret, legen Sie die Umleitungs-URL auf http://127.0.0.1:8080/callback fest, und wählen Sie den ai-gateway-Bereich aus. Speichere und kopiere die Client-ID. Siehe Eine OAuth-App erstellen.

  3. Registrieren Sie das MCP im Codex und ersetzen Sie die Platzhalter:

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

  4. Überprüfen Sie die von Codex ausgegebene Callback-URL. Sie kann ein serverspezifisches Suffix enthalten. Lass den Administrator vor der Anmeldung genau diese URL zu den Weiterleitungs-URLs der OAuth-App hinzufügen. Wiederhole diese Kontrolle, wenn du einen weiteren Server hinzufügst.

  5. Melden Sie sich an und öffnen Sie Codex erneut:

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

Für Rückrufeinstellungen siehe die MCP-Authentifizierungsanleitung von OpenAI. Dann ein Werkzeug testen.

Verwenden Sie einen persönlichen Zugriffstoken für lokale Tests

Fügen Sie Folgendes zu ~/.codex/config.toml hinzu und ersetzen Sie dabei den Hostnamen und das Token:

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

Für ein anderes MCP verwenden Sie unter mcp_servers einen eindeutigen Namen und ersetzen Sie system.ai.dbsql durch seinen vollständigen Namen. Halte die Datei privat, starte dann Codex neu und teste ein Tool.

MCP-Tool testen

  1. Geben Sie im Codex ein /mcp und prüfen Sie, ob der Server verbunden ist.
  2. Fordern Sie Codex auf, die Tools dieses Servers aufzulisten, und fordern Sie dann eine Leseoperation an. Für GitHub bitte GitHub, ein Problem in einem Repository zu finden, auf das du zugreifen kannst. Für einen benutzerdefinierten Server verwenden Sie ein Tool und Eingaben, die Sie während der Registrierung getestet haben.
  3. Wenn ein Tool-Anruf dich zum Anmelden auffordert, öffne den vom MCP zurückgegebenen Login-Link, erteile die Zustimmung beim Anbieter und versuche dann den Anruf erneut. Diese Anmeldung verschafft dem MCP Zugriff auf Ihr externes Konto.
  4. Überprüfen Sie, ob Codex einen Werkzeugaufruf macht und sein Ergebnis zurückgibt. Eine Textantwort allein bestätigt die Verbindung nicht.

Um Azure Databricks-Daten zu verwenden, verbinden Sie system.ai.genie_one_mcp für Geschäftsfragen oder system.ai.dbsql für SQL. Zum Beispiel kann der SQL-MCP aufgefordert werden, SELECT 1 AS result auszuführen.

Für Berechtigungen, Richtlinien und Nutzung siehe Verwalten eines MCP.

Hinzufügen von Fähigkeiten

Verwenden Sie die Unity Gateway CLI

Nutzen Sie den interaktiven Picker:

ug skills add

Oder lade eine bestimmte veröffentlichte Fähigkeit herunter:

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

Neustarte Codex oder die Desktop-App. Heruntergeladene Skills sind lokal verfügbar in ~/.agents/skills/. Führe den Download erneut aus, um eine aktualisierte Version zu erhalten.

Um stattdessen die Fähigkeiten eines Schemas durch MCP zu zeigen, führe aus:

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

Verbinden Sie das Fertigkeitsregister manuell

Fügen Sie Folgendes zu ~/.codex/config.toml hinzu:

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

Ersetze den Hostnamen und das Token. Behalte den nachlaufenden Schrägstrich in der URL. Starte Codex neu und bitte ihn, eine veröffentlichte Fähigkeit zu verwenden, wie zum Beispiel Use <catalog>.<schema>.<skill-name> to review this query.

Das Register lädt Skill-Anweisungen über MCP. Um bereits vorhandene Skill-Dateien zu installieren, platziere den vollständigen Skill-Ordner einschließlich SKILL.md und der gebündelten Dateien in ~/.agents/skills/.

Die Unity-Gateway-Fähigkeiten befinden sich in der Beta. Siehe Governance-Fähigkeiten für Aktivierung und Berechtigungen.

Problembehandlung

  • Die Desktop-App fragt weiterhin nach einer OpenAI-Anmeldung: Auf macOS oder Linux kann man interaktiv erneut ausführen ug configure --agents codex und das Systemkonfigurationsupdate abschließen. Das CLI-Profil allein konfiguriert die Desktop-App nicht. Für die manuelle Einrichtung prüfen Sie, ob das model_provider auf der obersten Ebene ist und requires_openai_auth = false in der Anbieter-Tabelle steht. Füge dieses Flag nicht einem Anbieter hinzu, der eine auth Tabelle für die OAuth-Token-Aktualisierung verwendet.

  • Anfragen schlagen mit einem WebSocket-Fehler fehl: Legen Sie supports_websockets = false in der aktiven Azure Databricks-Providertabelle fest. Wenn dein Administrator diese Konfiguration verwaltet, bitte ihn, sie zu aktualisieren. Starte die App danach neu.

  • Ein Modell fehlt: Überprüfen Sie Ihre Modellberechtigungen. Lege model in der aktiven Konfiguration auf seinen vollständigen Unity Catalog-Namen fest und starte eine neue Unterhaltung.

  • Wenn eine MCP- oder Skill-Verbindung fehlschlägt: Überprüfen Sie die URL, die Berechtigungen und den Fehler des Connectors. Prüfen Sie bei manuellen Verbindungen auch das Token-Ablaufdatum. Bei ug Einrichtungsproblemen führe ug doctor aus. Eine heruntergeladene Fähigkeit kann auch dann verfügbar bleiben, wenn die Registry-Verbindung fehlschlägt.

  • Die Anmeldung im Arbeitsbereich funktioniert, aber ein Tool bittet dich, dich anzumelden: Öffne den vom MCP zurückgegebenen Login-Link, melde dich beim externen Anbieter an und versuche den Aufruf erneut. Arbeitsbereich und Anmeldung beim Anbieter sind getrennte Schritte.

  • OAuth meldet, dass die Weiterleitungs-URL nicht übereinstimmt oder dass die Verbindung abläuft: Gleiche die Weiterleitungs-URL der OAuth-App mit der exakten URL ab, die Codex meldet, einschließlich eines beliebigen Suffixes, und überprüfe den Netzwerkzugang. Änderungen der OAuth-App können bis zu 30 Minuten dauern, bis sie wirksam werden.

Nächste Schritte

  • Zuletzt aktualisiert um