連接 Codex

透過 Unity Gateway 在終端機中使用 Codex,搭配模型、MCP 工具和技能。 使用 Unity Gateway CLI(ug) 來設定存取權限,或手動設定連線。

要將工具連接到現有的 Codex 設定,請前往 新增 MCP 工具。

Prerequisites

你需要 Azure Databricks 工作區的 URL、想要使用的模型、MCP 和技能的存取權,以及最新的 Codex 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 測試版。 請參閱 管理帳戶預覽功能。

  1. 在你的工作空間中開啟 Unity Gateway > MCP 。 選擇 內建的 MCP 或 註冊您的外部 MCP 伺服器。
  2. 複製 MCP 的全名,例如 system.ai.github 或 <catalog>.<schema>.<service>。
  3. 確認你有 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 應用程式:

  1. 在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
    
  2. 登入後重新開啟Codex:

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

然後 測試一個工具。

設定一個自訂的 OAuth 應用程式
  1. 關閉 Codex。 在 ~/.codex/config.toml中,將這些設定置於頂層,任何表格標題之前。 它們會給本地 OAuth 回呼一個固定埠:

    mcp_oauth_callback_port = 8080
    mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"
    
  2. 請帳號管理員在帳號主控台中開啟設定> App connections > Add connection。 使用像 codex-mcp 這樣的名稱、清除 產生客戶端密碼、將重新導向 URL 設為 http://127.0.0.1:8080/callback,並選擇 ai-gateway 範圍。 儲存並複製 客戶 ID。 請參見 建立 OAuth 應用程式。

  3. 在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>
    
  4. 請查看 Codex 顯示的回呼網址。 它可以包含伺服器專屬的後綴。 請管理員在登入前,先把這個精確的網址加到 OAuth 應用程式的重定向網址裡。 新增伺服器時重複這個檢查。

  5. 登入後重新開啟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 工具

  1. 在 Codex 輸入 /mcp 並檢查伺服器是否已連接。
  2. 請Codex列出該伺服器的工具,然後請求讀取操作。 在 GitHub 中,請它在你可以存取的倉庫中找到一個議題。 對於自訂伺服器,請使用你註冊時測試過的工具和輸入。
  3. 如果工具呼叫提示你登入,打開 MCP 回傳的登入連結,完成提供者同意,然後重試該呼叫。 這次登入會授予 MCP 存取您外部帳號的權限。
  4. 檢查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 分鐘 才能生效。

下一步