透過 Unity Gateway 在終端機中使用 Codex,搭配模型、MCP 工具和技能。 使用 Unity Gateway CLI(ug) 來設定存取權限,或手動設定連線。
要將工具連接到現有的 Codex 設定,請前往 新增 MCP 工具。
Prerequisites
你需要 Azure Databricks 工作區的 URL、想要使用的模型、MCP 和技能的存取權,以及最新的 Codex CLI。
如果您的管理員已經設定了您的裝置,請依照組織的啟動指示操作。
建議使用 Unity Gateway CLI(建議)
安裝 ug,然後從你的專案目錄執行這個指令:
ug codex
依照指示選擇你的工作區並登入。
ug 設定連線並在終端機中開啟 Codex。 開始使用你已經使用的相同提示詞和指令。 要更改模型,請輸入 /model。
繼續 新增 MCP 工具 或 新增技能,讓 Codex 能存取資料並使用共用指示。
在 Azure Databricks 運算資源上執行
若要在無伺服器運算或專用叢集上執行 Codex,無需安裝 ug,請連接 SSH 隧道並執行 codex。 代理程式已為 Unity Gateway 預先設定。 請參見「在 SSH 會話中執行編碼代理程式」。
手動設定模型
關閉Codex,然後開啟或創建 ~/.codex/config.toml。 針對 Windows,請使用 %USERPROFILE%\.codex\config.toml。
將以下設定合併到檔案中。 保留 model_provider 和 model 於頂層,並放在任何表格標頭之前,同時保留其他無關設定。
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>" }
將模型預留位置替換為其完整的 Unity Catalog 名稱,將 <workspace-hostname> 替換為您的工作區主機名稱,並將 <databricks-pat> 替換為您的個人存取權杖。 此範例將標記儲存在本地;檔案保持私密,並使用您自己的標記。
從你的專案目錄執行 codex 。 如果你的裝置有受管理的提供者設定,請你的管理員更新;這些設定優先於使用者設定。
詳情請參閱 OpenAI 的配置參考。
新增 MCP 工具
要使用 system.ai.dbsql、system.ai.sandbox 或 system.ai.web_search,帳號管理員必須從帳號主控台的 Previews 頁面啟用 Unity Gateway 測試版。 請參閱 管理帳戶預覽功能。
- 在你的工作空間中開啟 Unity Gateway > MCP 。 選擇 內建的 MCP 或 註冊您的外部 MCP 伺服器。
- 複製 MCP 的全名,例如
system.ai.github或<catalog>.<schema>.<service>。 - 確認你有 MCP 的存取權限。
使用 Unity Gateway CLI
安裝 ug,然後將MCP加入Codex:
ug mcp add --agents codex --names <catalog>.<schema>.<service>
把佔位符換成你複製的名字。 例如,GitHub 請使用 --names system.ai.github。 若要互動式選擇服務,請省略 --names。
第一次設定時,依照指示選擇工作區、登入並選擇模型。
ug 配置模型與 MCP 存取權限,並刷新憑證。 若要用自己的 OAuth 應用程式存取 MCP,請使用以下手動設定。
使用 ug codex 重新啟動 Codex CLI,然後 測試工具。
手動設定多個 MCP
使用公開的 Azure Databricks OAuth 應用程式登入並刷新憑證。
要使用預設的 Codex 客戶端 ID,其使用不需要帳號管理員建立 OAuth 應用程式:
在Codex中註冊MCP,取代佔位符:
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登入後重新開啟Codex:
codex mcp login databricks-tools --scopes ai-gateway,offline_access
然後 測試一個工具。
設定一個自訂的 OAuth 應用程式
關閉 Codex。 在
~/.codex/config.toml中,將這些設定置於頂層,任何表格標題之前。 它們會給本地 OAuth 回呼一個固定埠:mcp_oauth_callback_port = 8080 mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"請帳號管理員在帳號主控台中開啟設定> App connections > Add connection。 使用像
codex-mcp這樣的名稱、清除 產生客戶端密碼、將重新導向 URL 設為http://127.0.0.1:8080/callback,並選擇ai-gateway範圍。 儲存並複製 客戶 ID。 請參見 建立 OAuth 應用程式。在Codex中註冊MCP,取代佔位符:
codex mcp add databricks-tools \ --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>" \ --oauth-client-id <client-id>請查看 Codex 顯示的回呼網址。 它可以包含伺服器專屬的後綴。 請管理員在登入前,先把這個精確的網址加到 OAuth 應用程式的重定向網址裡。 新增伺服器時重複這個檢查。
登入後重新開啟Codex:
codex mcp login databricks-tools --scopes ai-gateway,offline_access
有關回調設定,請參閱 OpenAI 的 MCP 認證說明。 然後 測試一個工具。
使用個人存取權杖進行本地測試
將以下內容加入 ~/.codex/config.toml 中,並將主機名稱、工作區 ID 和權杖替換為實際值:
[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql?o=<workspace-id>"
http_headers = { Authorization = "Bearer <databricks-pat>" }
對於另一個 MCP,請在 mcp_servers 下方使用唯一名稱,並以其全名替換 system.ai.dbsql。 保持檔案私密,然後重新啟動 Codex 並測試工具。
測試 MCP 工具
- 在 Codex 輸入
/mcp並檢查伺服器是否已連接。 - 請Codex列出該伺服器的工具,然後請求讀取操作。 在 GitHub 中,請它在你可以存取的倉庫中找到一個議題。 對於自訂伺服器,請使用你註冊時測試過的工具和輸入。
- 如果工具呼叫提示你登入,打開 MCP 回傳的登入連結,完成提供者同意,然後重試該呼叫。 這次登入會授予 MCP 存取您外部帳號的權限。
- 檢查Codex是否會呼叫工具並回傳結果。 光靠文字回覆並不能驗證連線。
若要使用 Azure Databricks 資料,請連線至 system.ai.genie_one_mcp 以處理商業問題,或連線至 system.ai.dbsql 以使用 SQL。 例如,請要求 SQL MCP 執行 SELECT 1 AS result。
關於權限、政策與使用情況,請參見 「治理 MCP」。
新增技能
使用 Unity Gateway CLI
執行互動式選擇器:
ug skills add
或者下載特定已發表的技能:
ug skills add --names <catalog>.<schema>.<skill-name>
重新啟動 Codex CLI。 下載的技能可在 ~/.agents/skills/ 中於本機使用。 請重播下載以取得更新版本。
若要透過 MCP 揭露結構的技能,請執行:
ug skills add --location "<catalog>.<schema>" --via mcp
手動連線技能登錄檔
將以下內容新增至 ~/.codex/config.toml:
[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }
替換主機名稱和標記。 網址裡的尾斜線要保留。 重新啟動Codex並要求它使用已發表的技能,例如: Use <catalog>.<schema>.<skill-name> to review this query.
登錄檔會透過 MCP 載入技能指令。 若要安裝您已有的技能檔案,請將完整的技能資料夾(包括 SKILL.md 和隨附的檔案)放到 ~/.agents/skills/ 中。
Unity Gateway 技能還在測試階段。 請參見 治理技能 以了解啟用與權限。
Troubleshooting
請求失敗時會出現 WebSocket 錯誤:在活躍的 Azure Databricks 提供者資料表中設定
supports_websockets = false。 如果你的管理員負責管理該設定,請他們更新。 之後再重啟應用程式。缺少一個模型:請檢查你的模型權限。 在活躍設定中設定
model為完整的 Unity 目錄名稱,然後開始新的對話。MCP 或技能連線失敗: 檢查網址、權限及連接器錯誤。 手動連線時,也要檢查令牌過期。 遇到
ug設定問題時,請執行ug doctor。 下載的技能即使登錄檔連線失敗仍可保留。Workspace 登入是可以的,但有個工具會要求你登入: 打開 MCP 回傳的登入連結,登入外部服務提供者,然後重新嘗試該呼叫。 Workspace 與身分識別提供者登入是分開的步驟。
OAuth 回報重定向不匹配或連線逾時 :將 OAuth 應用程式的重定向 URL 與 Codex 報告的精確網址(包括任何後綴)相符,並檢查 網路存取。 OAuth 應用程式的變更可能需要 長達 30 分鐘 才能生效。