Connect Codex

Gebruik Codex in je terminal of de ChatGPT-desktopapp met modellen, MCP-tools en vaardigheden via Unity Gateway. Gebruik de Unity Gateway CLI (ug) om toegang te configureren, of configureer de verbinding handmatig.

Om tools te verbinden met een bestaande Codex-setup, ga je naar MCP-tools toevoegen.

Prerequisites

Je hebt je Azure Databricks workspace-URL nodig en toegang tot de modellen, MCP's en vaardigheden die je wilt gebruiken. Installeer de nieuwste versie van Codex of de ChatGPT-desktopapp.

Als je beheerder je apparaat al heeft geconfigureerd, volg dan de startinstructies van je organisatie.

Codex in de terminal

Installeer ugen voer vervolgens dit commando uit vanuit je projectmap:

ug codex

Volg de instructies om je werkruimte te selecteren en in te loggen. ug configureert de verbinding en opent Codex in je terminal. Begin met dezelfde prompts en commando's die je al gebruikt. Om van model te veranderen, voer /modelin .

Blijf MCP-tools toevoegen of voeg vaardigheden toe om Codex toegang te geven tot data en gedeelde instructies.

ChatGPT-desktop

Installeer en voer dit commando op macOS en Linux ug uit in een interactieve terminal:

ug configure --agents codex

Selecteer je werkruimte en log in. Als je erom vraagt, keur dan de systeemconfiguratie-update goed met je apparaatwachtwoord. ug configureert de Unity Gateway-verbinding en de vernieuwing van het OAuth-token.

Open of herstart de desktop-app en start een Codex-gesprek. Gebruik de modelkiezer om van model te wisselen. Het ug codex commando opent de terminalagent; open normaal gesproken de desktop-app na de configuratie.

Op Windows gebruik je de onderstaande handmatige modelconfiguratie. Je kunt ug mcp add en ug skills add nog steeds gebruiken om hulpmiddelen en vaardigheden toe te voegen en vervolgens de app opnieuw te starten.

Modellen handmatig configureren

Deze instellingen gelden zowel voor de terminal agent als de desktop-app. Sluit Codex en open of maak daarna ~/.codex/config.toml. Gebruik in Windows %USERPROFILE%\.codex\config.toml.

Voeg de volgende instellingen samen in het bestand. Houd model en model_provider op het hoogste niveau, vóór eventuele tabelkoppen, en bewaar niet-gerelateerde instellingen.

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

Vervang de model-placeholder door de volledige Unity Catalog-naam, <workspace-hostname> door je workspace-hostnaam en <databricks-pat> door je persoonlijke toegangstoken. Dit voorbeeld slaat het token lokaal op; houd het bestand privé en gebruik je eigen token.

Voer codex uit vanuit je projectmap of open de desktop-app opnieuw. Als je apparaat instellingen voor beheerde providers heeft, vraag dan je beheerder om deze bij te werken; die instellingen hebben voorrang boven deze gebruikersconfiguratie.

Zie de configuratiereferentie van OpenAI voor velddetails.

Voeg MCP-tools toe

Om system.ai.sandbox, system.ai.web_search, of system.ai.dbsql te gebruiken, moet een accountbeheerder de Unity Gateway-beta inschakelen via de pagina Previews van de accountconsole. Zie Accountpreviews beheren.

  1. Open Unity Gateway > MCPs in je werkruimte. Kies een ingebouwde MCP of registreer je externe MCP-server.
  2. Kopieer de volledige naam van de MCP, zoals system.ai.github of <catalog>.<schema>.<service>.
  3. Bevestig dat je toegang hebt tot de MCP.

Gebruik de Unity Gateway CLI

Installeer ugen voeg dan de MCP toe aan de Codex:

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

Vervang de tijdelijke aanduiding door de naam die je hebt gekopieerd. Gebruik bijvoorbeeld --names system.ai.github voor GitHub. Om services interactief te selecteren, laat --names weg.

Volg bij de eerste installatie de instructies om je werkruimte te selecteren, log in en kies een model. ug configureert zowel model- als MCP-toegang en ververst de inloggegevens. Voor MCP-toegang met je eigen OAuth-app, gebruik de handmatige setup hieronder.

Herstart de Codex met ug codex, of open de desktop-app opnieuw en test dan een tool.

MCP's handmatig configureren

Gebruik een openbare Azure Databricks OAuth-app om in te loggen en je inloggegevens te verversen. Deze instellingen gelden voor de terminal agent en de desktop-app.

Stel een OAuth-app in

  1. Sluit Codex. In ~/.codex/config.toml, voeg deze instellingen toe op het bovenste niveau, vóór eventuele tabelkoppen. Ze geven de lokale OAuth callback een vaste poort:

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

  2. Laat een accountbeheerder Instellingen > App-verbindingen > Verbinding toevoegen openen in de accountconsole. Gebruik een naam zoals codex-mcp, schakel Genereer een clientgeheim uit, stel de redirect-URL in op http://127.0.0.1:8080/callback, en selecteer de ai-gateway-scope. Sla de Client ID op en kopieer deze. Zie Create an OAuth app.

  3. Registreer de MCP in de Codex, waarbij de placeholders worden vervangen:

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

  4. Bekijk de callback-URL die door Codex is weergegeven. Het kan een server-specifiek achtervoegsel bevatten. Laat de beheerder die exacte URL toevoegen aan de redirect-URL's van de OAuth-app voordat je inlogt. Herhaal deze controle bij het toevoegen van een extra server.

  5. Log in en open Codex daarna opnieuw:

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

Voor callback-instellingen, zie de MCP-authenticatie-instructies van OpenAI. Test vervolgens een hulpmiddel.

Gebruik een persoonlijk toegangstoken voor lokaal testen

Voeg het volgende toe aan ~/.codex/config.toml, ter vervanging van de hostnaam en token:

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

Voor een andere MCP gebruik een unieke naam onder mcp_servers en vervang system.ai.dbsql door de volledige naam. Houd het bestand privé, start Codex opnieuw op en test een tool.

Test een MCP-tool

  1. In Codex voer /mcp in en controleer je of de server verbonden is.
  2. Vraag Codex om de tools van die server te vermelden en vraag vervolgens een leesoperatie aan. Voor GitHub, vraag het om een issue te vinden in een repository waar je toegang toe hebt. Voor een aangepaste server gebruik je een tool en invoer die je tijdens de registratie hebt getest.
  3. Als een tool-oproep je vraagt in te loggen, open dan de inloglink die door de MCP wordt teruggegeven, voltooi de toestemming van de provider en probeer de oproep daarna opnieuw. Deze aanmelding geeft de MCP toegang tot je externe account.
  4. Controleer of Codex een tool-aanroep maakt en het resultaat teruggeeft. Een tekstantwoord alleen bevestigt de connectie niet.

Om Azure Databricks-data te gebruiken, maak verbinding via system.ai.genie_one_mcp voor zakelijke vragen of system.ai.dbsql voor SQL. Vraag bijvoorbeeld de SQL MCP om SELECT 1 AS result uit te voeren.

Voor permissies, beleidsregels en gebruik, zie Govern an MCP.

Vaardigheden toevoegen

Gebruik de Unity Gateway CLI

Gebruik de interactieve picker:

ug skills add

Of download een specifieke gepubliceerde vaardigheid:

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

Start Codex of de desktopapp opnieuw op. Gedownloade vaardigheden zijn lokaal beschikbaar in ~/.agents/skills/. Voer de download opnieuw uit om een bijgewerkte versie te krijgen.

Om de vaardigheden van een schema via MCP bloot te stellen, voer je uit:

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

Verbind het vaardigheidsregister handmatig

Voeg het volgende toe aan ~/.codex/config.toml:

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

Vervang de hostnaam en token. Laat de slash aan het einde van de URL staan. Herstart Codex en vraag hem een gepubliceerde vaardigheid te gebruiken, zoals Use <catalog>.<schema>.<skill-name> to review this query.

Het register laadt instructies voor vaardigheden via MCP. Om skill-bestanden te installeren die je al hebt, plaats je de complete skill-map, inclusief SKILL.md en gebundelde bestanden, in ~/.agents/skills/.

Unity Gateway-vaardigheden bevinden zich in de bètafase. Zie Vaardigheden beheren voor inschakelen en machtigingen.

Troubleshooting

  • De desktop-app vraagt nog steeds om inloggen bij OpenAI: Voer op macOS of Linux ug configure --agents codex opnieuw interactief uit en voltooi de update van de systeemconfiguratie. Het CLI-profiel alleen configureert de desktop-app niet. Voor handmatige installatie, controleer dat dat model_provider op het hoogste niveau is en requires_openai_auth = false in de provider table staat. Voeg die vlag niet toe aan een provider die een auth tabel gebruikt voor OAuth-tokenvernieuwing.

  • Verzoeken falen met een WebSocket-fout: Ingesteld supports_websockets = false in de actieve Azure Databricks provider-tabel. Als je beheerder die configuratie beheert, vraag dan of ze het kunnen updaten. Herstart de app daarna.

  • Er ontbreekt een model: Controleer de rechten van je model. Stel model in de actieve configuratie in op de volledige Unity Catalog-naam en start een nieuw gesprek.

  • Een MCP- of vaardigheidsverbinding faalt: Controleer de fout URL, permissies en connector. Controleer voor handmatige verbindingen ook de vervaldatum van token. Voer ug doctor uit voor problemen met het instellen van ug. Een gedownloade vaardigheid kan beschikbaar blijven, zelfs als de registerverbinding faalt.

  • Workspace-aanmelden werkt, maar een tool vraagt je in te loggen: Open de inloglink die door de MCP wordt teruggegeven, log in bij de externe provider en probeer de aanroep daarna opnieuw. Werkruimte en aanmelden bij de provider zijn aparte stappen.

  • OAuth meldt een redirect-mismatch of de verbinding loopt uit: Koppel de redirect-URL van de OAuth-app aan de exacte URL die Codex meldt, inclusief eventuele achtervoegsels, en controleer de netwerktoegang. Wijzigingen in de OAuth-app kunnen tot 30 minuten duren voordat ze van kracht worden.

Volgende stappen 

  • Laatst bijgewerkt om