Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Nutze Codex in deinem Terminal 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.
Verwenden Sie Codex CLI mit unterstützten Open-Source-Modellen über Unity Gateway, um die Kosten für Codieragenten zu senken.
Um Tools mit einem bestehenden Codex-Setup zu verbinden, gehe zu Add MCP tools.
Prerequisites
Du brauchst die URL deines Azure Databricks Workspaces, Zugriff auf die Modelle, MCPs und Skills, die du nutzen möchtest, sowie die neueste Codex CLI.
Wenn Ihr Administrator Ihr Gerät bereits konfiguriert hat, folgen Sie den Startanweisungen Ihrer Organisation.
Verwenden Sie die Unity Gateway CLI (empfohlen)
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.
Bringen Sie Ihr eigenes ChatGPT-Abonnement mit
Um Codex mit deinem eigenen ChatGPT Go, Plus, Pro oder Enterprise-Abonnement über Unity Gateway zu betreiben, frage deinen Administrator nach einem ChatGPT-Abonnementmodell-Anbieter. Siehe Support für ChatGPT-Abonnements für Anforderungen, Admin-Setup, Funktionsweise und Einschränkungen.
Übergeben Sie den vollqualifizierten Namen des Modellanbieter-Dienstes (<catalog>.<schema>.<name>) an --provider und die Arbeitsbereich-URL an --workspace:
ug codex --provider main.default.chatgpt_subscription --workspace https://<workspace>.databricks.com
Wenn Codex nicht mit ChatGPT angemeldet ist, führt ugcodex login aus, um die Browser-Anmeldung zu öffnen. Eine API-Schlüsselanmeldung zählt nicht.
ug konfiguriert Codex so, dass er den Databricks-Model-Provider-Service-Header sendet und Codex auf einen lokalen Refresh-Proxy verweist, anstatt direkt auf den Unity-Gateway-Endpunkt zu verweisen. Der Proxy leitet jede Anfrage an https://<workspace-url>/ai-gateway/codex/v1 weiter und fügt den Header X-Databricks-AI-Gateway-Token hinzu. Da der Dienst keine Zugangsdaten speichert, lässt der Proxy deine ChatGPT-Anmeldung durch, ohne sie zu speichern.
Wenn du auf Probleme stößt, melde dich ab mit codex logout, und führe dann den Befehl erneut aus, um dich anzumelden.
Note
--provider für einen ChatGPT-Abonnementmodell-Anbieterdienst wird nur mit ug codex unterstützt. Smart Routing wird bei einem ChatGPT-Abonnementmodell-Anbieterdienst nicht unterstützt.
Konfigurieren Sie ein ChatGPT-Abonnement manuell
Benutze die manuelle Einrichtung nur, wenn du ug nicht nutzen kannst.
Azure Databricks-Token abrufen. Der Header
X-Databricks-AI-Gateway-Tokenenthält ein Azure Databricks-Token, das die Anfrage bei Unity Gateway authentifiziert. Unity Gateway ordnet Zugriffskontroll- und Nutzungsprotokolle der mit diesem Token verknüpften Identität zu, also verwenden Sie ein Token, das dem anfragenden Benutzer gehört. Wählen Sie eines der folgenden Szenarien aus:OAuth Benutzer-zu-Computer (U2M) mit der Databricks CLI (empfohlen). Melde dich einmal mit der CLI an und präge dann einen kurzlebigen OAuth-Token:
databricks auth login --host https://<workspace-url> databricks auth token --host https://<workspace-url> | jq -r .access_tokenSiehe Autorisieren des Benutzerzugriffs auf Azure Databricks mit OAuth und Authentifizierung für die Databricks-CLI. Ein U2M OAuth-Token läuft in etwa 1 Stunde ab, daher musst du ihn für interaktive Nutzung in deiner Konfiguration ersetzen, wenn er abläuft. Um die Token-Aktualisierung zu automatisieren, verwenden Sie
ug, der einen lokalen Proxy ausführt, der das OAuth-Token bei jeder Anfrage für Sie aktualisiert.Personal Access Token (PAT) als Backup. Wenn du OAuth nicht verwenden kannst, erstelle einen PAT und verwende ihn als
<databricks-token>. Ein PAT läuft nicht mit dem 1-Stunden-OAuth-Rhythmus ab, ist aber eine langlebige Qualifikation, die an Ihre Identität gebunden ist. Siehe Authentifizieren mit persönlichen Zugriffstokens von Azure Databricks (Legacy).
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. Belassen Siemodel_providerauf der obersten Ebene, vor Tabellenüberschriften, und behalten Sie nicht zusammenhängende Einstellungen bei.model_provider = "databricks" [model_providers.databricks] name = "Databricks" base_url = "https://<workspace-url>/ai-gateway/codex/v1" wire_api = "responses" requires_openai_auth = true http_headers = { "X-Databricks-AI-Gateway-Token" = "Bearer <databricks-token>", "Databricks-Model-Provider-Service" = "<catalog>.<schema>.<name>" }- Ersetzen Sie
<workspace-url>durch Ihre Arbeitsbereichs-URL. - Ersetzen Sie
<databricks-token>durch das Azure Databricks-Token aus dem vorherigen Schritt. - Ersetzen Sie
<catalog>.<schema>.<name>durch den vollqualifizierten Namen Ihres Modellanbieterdienstes.
requires_openai_auth = trueveranlasst Codex, eine eigene ChatGPT-Anmeldeanforderung zu senden. Füge diesem Anbieter keineauth-Tabelle hinzu. Halte die Datei privat, weil sie dein Azure Databricks-Token speichert.- Ersetzen Sie
Start Codex:
codexWenn du noch nicht angemeldet bist, fordert Codex dich zur Authentifizierung auf. Wähle Mit ChatGPT anmelden und melde dich mit deinem ChatGPT-Konto an. Eine Anmeldung mit einem API-Schlüssel funktioniert nicht mit einem ChatGPT-Abonnementmodell-Anbieterdienst. Wenn Sie Probleme haben, melden Sie sich mit
codex logoutab und dann erneut an.
Deine Codex-Anfragen werden jetzt über Unity Gateway geleitet. Anfragen werden auf dein ChatGPT-Abonnement abgerechnet, und du erhältst zentralen Zugriff, Routing und Nutzungssteuerung.
Auf Azure Databricks Compute ausführen
Um Codex auf serverlosem Computing oder einem dedizierten Cluster ohne ug zu installieren auszuführen, verbinden Sie sich mit dem SSH-Tunnel und führen Sie codex aus. Der Agent ist für Unity Gateway vorkonfiguriert. Siehe Coding agents in einer SSH-Sitzung ausführen.
Modelle manuell konfigurieren
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.
Führe codex aus deinem Projektverzeichnis aus. 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
system.ai.dbsql, system.ai.sandbox, und system.ai.web_search befinden sich in der Beta. Um sie zu nutzen, muss ein Kontoadministrator die Vorschau des Enhanced Unity Gateway auf der Seite Previews der Kontokonsole aktivieren. Unity Gateway selbst ist jetzt verfügbar. Siehe Kontovorschauen verwalten.
- Öffnen Sie die Unity Gateway > MCPs in Ihrem Arbeitsbereich. Wählen Sie ein integriertes MCP oder registrieren Sie Ihren externen MCP-Server.
- Kopieren Sie den vollständigen Namen des MCP, wie zum Beispiel
system.ai.githuboder<catalog>.<schema>.<service>. - 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 die Codex-CLI mit ug codexneu und teste dann ein Werkzeug.
MCPs manuell konfigurieren
Verwenden Sie eine öffentliche Azure Databricks OAuth-App, um sich anzumelden und die Zugangsdaten zu aktualisieren.
Um die Standard-Codex-Client-ID zu verwenden, für die zum Erstellen einer OAuth-App kein Kontoadministrator erforderlich ist:
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>?o=<workspace-id>" \ --oauth-client-id https://chatgpt.com/oauth/codex/client.jsonMelden Sie sich an und öffnen Sie Codex erneut:
codex mcp login databricks-tools --scopes ai-gateway,offline_access
Dann ein Tool testen.
Richte eine individuelle OAuth-App ein
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"Lass einen Kontoadministrator in der KontokonsoleEinstellungen > App-Verbindungen > Verbindung hinzufügen öffnen. Verwenden Sie einen Namen wie
codex-mcp, löschen Sie Client-Secret generieren, setzen Sie die Redirect-URL aufhttp://127.0.0.1:8080/callbackund wählen Sie den Scopeai-gatewayaus. Speichere und kopiere die Client-ID. Siehe Eine OAuth-App erstellen.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>?o=<workspace-id>" \ --oauth-client-id <client-id>Ü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.
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 Tool testen.
Verwenden Sie einen persönlichen Zugriffstoken für lokale Tests
Füge Folgendes zu ~/.codex/config.toml hinzu und ersetze den Hostnamen, die Arbeitsbereich-ID und das Token:
[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql?o=<workspace-id>"
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
- Geben Sie im Codex ein
/mcpund prüfen Sie, ob der Server verbunden ist. - 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 Sie zugreifen können. Für einen benutzerdefinierten Server verwenden Sie ein Tool und Eingaben, die Sie während der Registrierung getestet haben.
- Wenn Sie bei einem Tool-Aufruf zur Anmeldung aufgefordert werden, öffnen Sie den vom MCP bereitgestellten Anmeldelink, erteilen Sie die erforderliche Zustimmung beim Anbieter und wiederholen Sie anschließend den Aufruf. Diese Anmeldung verschafft dem MCP Zugriff auf Ihr externes Konto.
- Ü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>
Starte die Codex CLI neu. 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
Anfragen schlagen mit einem WebSocket-Fehler fehl: Legen Sie
supports_websockets = falsein 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
modelin 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
ugEinrichtungsproblemen führeug doctoraus. 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.