Connect Codex
Use Codex in your terminal or the ChatGPT desktop app with models, MCP tools, and skills through Unity Gateway. Use the Unity Gateway CLI (ug) to configure access, or configure the connection manually.
Before you begin
You need your Databricks workspace URL and access to the models, MCP services, and skills you want to use. Install the latest version of Codex or the ChatGPT desktop app.
If your admin has already configured your device, follow your organization's launch instructions.
Codex in the terminal
Use the Unity Gateway CLI (recommended)
Install ug, then run this command from your project directory:
ug codex
Follow the prompts to select your workspace and sign in. ug configures the connection and opens Codex in your terminal. Start working with the same prompts and commands you already use. To change models, enter /model.
To add MCP tools or skills, run these commands in your terminal, then restart Codex:
ug mcp add
ug skills add
Each command lets you select what to add. For manual setup, use the configuration sections below.
ChatGPT desktop
Use the Unity Gateway CLI (recommended)
On macOS and Linux, install ug and run this command in an interactive terminal:
ug configure --agents codex
Select your workspace and sign in. If prompted, approve the system configuration update with your device password. ug configures the Unity Gateway connection and OAuth token refresh.
Open or restart the desktop app and start a Codex conversation. Use the model picker to change models. The ug codex command opens the terminal agent; open the desktop app normally after configuration.
On Windows, use the manual model configuration below. You can still use ug mcp add and ug skills add to add tools and skills, then restart the app.
Configure models manually
These settings apply to both the terminal agent and desktop app. Close Codex, then open or create ~/.codex/config.toml. On Windows, use %USERPROFILE%\.codex\config.toml.
Merge the following settings into the file. Keep model and model_provider at the top level, before any table headers, and preserve unrelated settings.
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>" }
Replace the model placeholder with its full Unity Catalog name, <workspace-hostname> with your workspace hostname, and <databricks-pat> with your personal access token. This example stores the token locally; keep the file private and use your own token.
Run codex from your project directory or reopen the desktop app. If your device has managed provider settings, ask your admin to update them; those settings take precedence over this user configuration.
See OpenAI's configuration reference for field details.
Add MCP tools
Use the Unity Gateway CLI
Run this command and select the services you want to add:
ug mcp add
Restart Codex or the desktop app, then ask it to use a connected tool. ug registers a local proxy that authenticates requests and refreshes credentials.
Configure MCP services manually
Add the following to ~/.codex/config.toml:
[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
http_headers = { Authorization = "Bearer <databricks-pat>" }
Replace the hostname and token, then restart Codex. For another service, use a unique name under mcp_servers and replace system.ai.dbsql with its three-part Unity Catalog name.
For OAuth setup, follow OpenAI's MCP authentication instructions and register a Databricks OAuth application with the exact callback URL Codex uses.
Add skills
Use the Unity Gateway CLI
Run the interactive picker:
ug skills add
Or download a specific published skill:
ug skills add --names <catalog>.<schema>.<skill-name>
Restart Codex or the desktop app. Downloaded skills are available locally in ~/.agents/skills/. Re-run the download to get an updated version.
To expose a schema's skills through MCP instead, run:
ug skills add --location <catalog>.<schema> --mcp
Connect the skill registry manually
Add the following to ~/.codex/config.toml:
[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }
Replace the hostname and token. Keep the trailing slash in the URL. Restart Codex and ask it to use a published skill, such as Use <catalog>.<schema>.<skill-name> to review this query.
The registry loads skill instructions through MCP. To install skill files you already have, place the complete skill folder, including SKILL.md and bundled files, in ~/.agents/skills/.
Unity Gateway skills are in Beta. See Govern skills for enablement and permissions.
Troubleshooting
The desktop app still asks for OpenAI sign-in: On macOS or Linux, rerun ug configure --agents codex interactively and complete the system configuration update. The CLI profile alone does not configure the desktop app. For manual setup, check that model_provider is at the top level and requires_openai_auth = false is in the provider table. Do not add that flag to a provider that uses an auth table for OAuth token refresh.
Requests fail with a WebSocket error: Set supports_websockets = false in the active Databricks provider table. If your admin manages that configuration, ask them to update it. Restart the app afterward.
A model is missing: Check your model permissions. Set model to its full Unity Catalog name in the active configuration and start a new conversation.
An MCP or skill connection fails: Check the URL, permissions, and connector error. For manual connections, also check token expiration. For ug setup problems, run ug doctor. A downloaded skill can remain available even if the registry connection fails.