Connetti Codex

Usa Codex nel tuo terminale o nell'app desktop ChatGPT con modelli, strumenti MCP e competenze tramite Unity Gateway. Usa la CLI Gateway Unity (ug) per configurare l'accesso, oppure configura la connessione manualmente.

Per collegare gli strumenti a una configurazione Codex esistente, vai su Aggiungi strumenti MCP.

Prerequisites

Hai bisogno dell'URL dello spazio di lavoro di Azure Databricks e dell'accesso ai modelli, agli MCP e alle skill che vuoi utilizzare. Installa l'ultima versione di Codex o l'app desktop ChatGPT.

Se il tuo amministratore ha già configurato il tuo dispositivo, segui le istruzioni di lancio della tua organizzazione.

Codex nel terminale

Installa ug, poi esegui questo comando dalla cartella del progetto:

ug codex

Segui le istruzioni per selezionare il tuo spazio di lavoro e accedi. ug configura la connessione e apre Codex nel tuo terminale. Inizia a lavorare con gli stessi prompt e comandi che già usi. Per cambiare modello, inserisci /model.

Continua ad aggiungere strumenti MCP o ad aggiungere skill per dare a Codex accesso ai dati e alle istruzioni condivise.

ChatGPT desktop

Su macOS e Linux, installa ug ed esegui questo comando in un terminale interattivo:

ug configure --agents codex

Seleziona il tuo spazio di lavoro e accedi. Se richiesto, approva l'aggiornamento di configurazione del sistema con la password del dispositivo. ug configura la connessione Unity Gateway e l'aggiornamento del token OAuth.

Apri o riavvia l'app desktop e avvia una conversazione con il Codex. Usa il selettore di modelli per cambiare modello. Il ug codex comando apre l'agente terminale; apri normalmente l'app desktop dopo la configurazione.

Su Windows, usa la configurazione manuale del modello qui sotto. Puoi comunque usare ug mcp add e ug skills add aggiungere strumenti e competenze, poi riavviare l'app.

Configurare i modelli manualmente

Queste impostazioni si applicano sia all'agente terminale che all'app desktop. Chiudi Codex, poi apri o crea ~/.codex/config.toml. In Windows usare %USERPROFILE%\.codex\config.toml.

Unisci le seguenti impostazioni nel file. Mantieni model e model_provider al livello superiore, prima di qualsiasi intestazione di tabella, e preserva le impostazioni non correlate.

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

Sostituisci il segnaposto del modello con il nome completo del Catalogo Unity, <workspace-hostname> con il nome host del tuo workspace e <databricks-pat> con il tuo token di accesso personale. Questo esempio memorizza il token localmente; mantieni il file privato e usa il tuo token.

Esegui codex dalla directory del progetto o riapri l'app desktop. Se il tuo dispositivo ha impostazioni del provider gestito, chiedi al tuo amministratore di aggiornarle; queste impostazioni hanno la precedenza su questa configurazione utente.

Consulta il riferimento di configurazione di OpenAI per i dettagli sul campo.

Aggiungi strumenti MCP

Per utilizzare system.ai.dbsql, system.ai.sandbox o system.ai.web_search, un amministratore dell'account deve abilitare la beta Unity Gateway dalla pagina Previews della console dell'account. Vedi Gestire anteprime dell'account.

  1. Apri gli MCP Unity Gateway > nel tuo spazio di lavoro. Scegli un MCP integrato o registra il tuo server MCP esterno.
  2. Copia il nome completo del MCP, come system.ai.github o <catalog>.<schema>.<service>.
  3. Conferma di avere accesso all'MCP.

Utilizzare l'interfaccia a riga di comando di Unity Gateway

Installa ug, poi aggiungi l'MCP al Codex:

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

Sostituisci il segnaposto con il nome che hai copiato. Ad esempio, usa --names system.ai.github per GitHub. Per scegliere i servizi in modo interattivo, ometti --names.

Alla prima configurazione, segui le istruzioni per selezionare il tuo spazio di lavoro, accedi e scegli un modello. ug configura sia l'accesso al modello che all'MCP e aggiorna le credenziali. Per accedere all'MCP con la tua app OAuth, usa la configurazione manuale qui sotto.

Riavvia Codex con ug codex, oppure riapri l'app desktop, poi prova uno strumento.

Configura gli MCP manualmente

Usa un'app pubblica Azure Databricks OAuth per accedere e aggiornare le credenziali. Queste impostazioni si applicano all'agente del terminale e all'app desktop.

Configura un'app OAuth

  1. Chiudi il Codex. In ~/.codex/config.toml, aggiungi queste impostazioni al livello superiore, prima di qualsiasi intestazione di tabella. Forniscono al callback OAuth locale una porta fissa:

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

  2. Fai aprire a un amministratore Impostazioni > Connessioni app > Aggiungi connessione nella console account. Usa un nome come codex-mcp, deseleziona Genera un segreto client, imposta l'URL di reindirizzamento su http://127.0.0.1:8080/callback, e seleziona l'ambito ai-gateway. Salva e copia l'ID Client. Vedi Crea un'app OAuth.

  3. Registra l'MCP nel Codex, sostituendo i segnaposto:

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

  4. Controlla l'URL di callback stampato da Codex. Può includere un suffisso specifico per il server. Chiedi all'amministratore di aggiungere quell'URL esatto agli URL di reindirizzamento dell'app OAuth prima di accedere. Ripeti questo controllo quando aggiungi un altro server.

  5. Accedi, poi riapri Codex:

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

Per le impostazioni di callback, consulta le istruzioni di autenticazione MCP di OpenAI. Poi prova uno strumento.

Usa un token di accesso personale per i test locali

Aggiungi quanto segue a ~/.codex/config.toml, sostituendo il nome host e il token:

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

Per un altro MCP, usa un nome unico sotto mcp_servers e sostituisci system.ai.dbsql con il suo nome completo. Tieni il file privato, poi riavvia Codex e testa uno strumento.

Testa uno strumento MCP

  1. Nel Codex, inserisci /mcp e verifica che il server sia connesso.
  2. Chiedi a Codex di elencare gli strumenti di quel server, poi richiedi un'operazione di lettura. Per GitHub, chiedigli di trovare un problema in un repository a cui puoi accedere. Per un server personalizzato, usa uno strumento e gli input che hai testato durante la registrazione.
  3. Se una chiamata tramite strumento ti chiede di accedere, apri il link di accesso restituito dall'MCP, completa il consenso del fornitore, poi riprova la chiamata. Questo accesso dà all'MCP l'accesso al tuo account esterno.
  4. Controlla che Codex effettui una chiamata allo strumento e restituisca il risultato. Una sola risposta testuale non verifica la connessione.

Per utilizzare Azure Databricks data, connettiti system.ai.genie_one_mcp per domande aziendali o system.ai.dbsql per SQL. Ad esempio, chiedi al SQL MCP di eseguire SELECT 1 AS result.

Per permessi, politiche e utilizzo, vedi Governare un MCP.

Aggiungere competenze

Utilizzare l'interfaccia a riga di comando di Unity Gateway

Esegui il selezionatore interattivo:

ug skills add

Oppure scarica una specifica abilità pubblicata:

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

Riavvia Codex o l'app desktop. Le abilità scaricate sono disponibili localmente in ~/.agents/skills/. Rifai il download per ottenere una versione aggiornata.

Per esporre le competenze di uno schema tramite MCP, esegui:

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

Collega manualmente il registro delle competenze

Aggiungere quanto segue a ~/.codex/config.toml:

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

Sostituisci il nome host e il token. Mantieni lo slash finale nell'URL. Riavvia il Codex e chiedigli di usare un'abilità pubblicata, come ad esempio Use <catalog>.<schema>.<skill-name> to review this query.

Il registro carica le istruzioni delle abilità tramite MCP. Per installare i file delle skill già disponibili, colloca la cartella completa della skill, compresi SKILL.md e i file inclusi nel pacchetto, in ~/.agents/skills/.

Le abilità Unity Gateway sono in Beta. Vedi Competenze di Governo per abilitazione e permessi.

Troubleshooting

  • L'app desktop richiede ancora l'accesso OpenAI: Su macOS o Linux, riesegui ug configure --agents codex in modo interattivo e completa l'aggiornamento della configurazione di sistema. Il profilo CLI da solo non configura l'app desktop. Per la configurazione manuale, controlla che model_provider sia al livello superiore e requires_openai_auth = false che sia nella tabella dei fornitori. Non aggiungere quel flag a un provider che utilizza una auth tabella per l'aggiornamento dei token OAuth.

  • Le richieste non riescono a causa di un errore di WebSocket: Imposta supports_websockets = false nella tabella attiva del provider Azure Databricks. Se il tuo amministratore gestisce quella configurazione, chiedigli di aggiornarla. Riavvia l'app dopo.

  • Manca un modello: Controlla i permessi dei tuoi modelli. Imposta model il nome completo del Catalogo Unity nella configurazione attiva e avvia una nuova conversazione.

  • Una connessione MCP o skill fallisce: Controlla l'URL, i permessi e l'errore del connettore. Per le connessioni manuali, controlla anche la scadenza del token. Per problemi ug di setup, esegui ug doctor. Un'abilità scaricata può rimanere disponibile anche se la connessione al registro fallisce.

  • L'accesso Workspace funziona, ma uno strumento ti chiede di effettuare il login: Apri il link di accesso restituito dall'MCP, accedi al provider esterno, poi riprova la chiamata. L'accesso allo spazio di lavoro e il login del fornitore sono passaggi separati.

  • OAuth segnala una discrepanza di reindirizzamento o la connessione scade: Abbina l'URL di reindirizzamento dell'app OAuth con l'URL esatto che il Codex segnala, incluso qualsiasi suffisso, e controlla l'accesso alla rete. Le modifiche all'app OAuth possono impiegare fino a 30 minuti per avere effetto.

Passaggi successivi

  • Ultimo aggiornamento: