Connetti Codex

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

Usa Codex CLI con modelli open-source supportati tramite Unity Gateway per aiutare a ridurre i costi degli agenti di codifica.

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, accesso ai modelli, MCP e competenze che vuoi usare, e l'ultima CLI di Codex.

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

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.

Usa il tuo abbonamento ChatGPT

Per eseguire Codex sul tuo abbonamento ChatGPT Go, Plus, Pro o Enterprise tramite Unity Gateway, chiedi al tuo amministratore un servizio di abbonamento modello ChatGPT. Consulta supporto per gli abbonamenti ChatGPT per i requisiti, la configurazione degli amministratori, il funzionamento e le limitazioni.

Passa il nome completamente qualificato del servizio fornitore modello (<catalog>.<schema>.<name>) a --provider e l'URL dello spazio di lavoro a --workspace:

ug codex --provider main.default.chatgpt_subscription --workspace https://<workspace>.databricks.com

Se Codex non ha effettuato l'accesso con ChatGPT, ug esegue codex login per aprire l'accesso nel browser. Un login con una chiave API non conta. ug configura Codex per inviare l'header Databricks-Model-Provider-Service e punta Codex a un proxy di aggiornamento locale invece che direttamente all'endpoint Unity Gateway. Il proxy inoltra ogni richiesta a https://<workspace-url>/ai-gateway/codex/v1 e aggiunge l'intestazione X-Databricks-AI-Gateway-Token. Poiché il servizio non memorizza alcuna credenziale, il proxy fa passare il tuo accesso/login a ChatGPT senza memorizzarlo.

Se incontri problemi, esci con codex logout, poi riesegui il comando per accedere di nuovo.

Note

--provider per un servizio provider con modello di abbonamento ChatGPT è supportato solo con ug codex. Smart Routing non è supportato con un servizio provider con modello di abbonamento ChatGPT.

Configura manualmente un abbonamento a ChatGPT

Usa la configurazione manuale solo se non puoi usare ug.

  1. Ottieni un token di Azure Databricks. L'intestazione X-Databricks-AI-Gateway-Token trasporta un token Azure Databricks che autentica la richiesta a Unity Gateway. Unity Gateway attribuisce il controllo di accesso e i log di utilizzo all'identità legata a questo token, quindi usa un token che appartiene all'utente che fa la query. Selezionare una delle opzioni seguenti:

    • OAuth da utente a macchina (U2M) con la CLI di Databricks (consigliata). Accedi una volta con la CLI, poi conia un token OAuth di breve durata:

      databricks auth login --host https://<workspace-url>
databricks auth token --host https://<workspace-url> | jq -r .access_token

      Vedi Autorizza l'accesso degli utenti a Azure Databricks con OAuth e Autenticazione per la CLI Databricks. Un token U2M OAuth scade tra circa 1 ora, quindi per un uso interattivo devi sostituirlo nella tua configurazione quando scade. Per automatizzare l'aggiornamento del token, usa ug, che esegue un proxy locale che aggiorna il token OAuth per te su ogni richiesta.

    • Token di accesso personale (PAT), come backup. Se non puoi usare OAuth, crea un PAT e usalo come <databricks-token>. Un PAT non scade sulla cadenza OAuth di 1 ora, ma è una credenziale di lunga durata legata alla tua identità. Vedere Autenticazione con i token di accesso personale di Azure Databricks (legacy).

  2. Chiudi Codex, poi apri o crea ~/.codex/config.toml. In Windows usare %USERPROFILE%\.codex\config.toml. Unisci le seguenti impostazioni nel file. Tieni model_provider al livello superiore, prima di qualsiasi header di tabella, e conserva impostazioni non correlate.

    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>" }
    • Sostituire <workspace-url> con l'URL dell'area di lavoro.
    • Sostituisci <databricks-token> con il token Azure Databricks del passaggio precedente.
    • Sostituisci <catalog>.<schema>.<name> con il nome completamente qualificato del tuo modello di servizio di fornitore.

    requires_openai_auth = true fa sì che Codex invii la propria procedura di accesso a ChatGPT. Non aggiungere una auth tabella a questo fornitore. Tieni il file privato, perché memorizza il tuo token Azure Databricks.

  3. Avvia Codex:

    codex

  4. Se non sei già connesso, Codex ti invita ad autenticarti. Seleziona Accedi con ChatGPT e accedi con il tuo account ChatGPT. Un login con chiave API non funziona con un servizio provider del modello in abbonamento ChatGPT. Se incontri problemi, esci con codex logout e accedi di nuovo.

Le tue richieste Codex ora passano attraverso Unity Gateway. Le richieste vengono addebitate al tuo abbonamento ChatGPT e ottieni accesso centralizzato, routing e governance dell'uso.

Esegui nel calcolo di Azure Databricks

Per eseguire Codex su computazione serverless o su un cluster dedicato senza installare ug, connettiti tramite il tunnel SSH ed esegui codex. L'agent è preconfigurato per Unity Gateway. Vedi Esegui agenti di codifica in una sessione SSH.

Configurare i modelli manualmente

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 dal tuo elenco di progetti. 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

system.ai.dbsql, system.ai.sandbox, e system.ai.web_search sono in Beta. Per utilizzarli, un amministratore dell'account deve abilitare Enhanced Unity Gateway in anteprima dalla pagina Anteprime della console dell'account. Unity Gateway stesso è generalmente disponibile. 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 la CLI del Codex con ug codex, poi testa uno strumento.

Configura gli MCP manualmente

Usa un'app pubblica Azure Databricks OAuth per accedere e aggiornare le credenziali.

Per usare l'ID client Codex predefinito, che non richiede un account admin per creare un'app OAuth:

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

    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.json

  2. Accedi, poi riapri Codex:

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

Poi prova uno strumento.

Configura un'app OAuth personalizzata

  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>?o=<workspace-id>" \
  --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, l'ID dello spazio di lavoro e il token:

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql?o=<workspace-id>"
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 la CLI del Codex. 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

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

  • Manca un modello: Controlla i permessi del tuo modello. 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: