連接 Claude Code

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

透過 Unity Gateway 使用 Claude Code 搭配支援的開源模型,有助於降低編碼代理程式的成本。

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

Prerequisites

你需要你的 Azure Databricks workspace URL、你想用的模型存取權,以及最新的 Claude Code。

如果您的管理員已經設定了您的裝置,請依照組織的登入與啟動指示操作。

安裝 ug,然後從你的專案目錄執行這個指令:

ug claude

依照指示選擇你的工作區並登入。 ug 設定連線並在你的終端機中開啟 Claude Code。 開始使用你已經使用的相同提示詞和指令。 要更改模型,請輸入 /model。

繼續 新增 MCP 工具 以連接資料與服務。 要下載共享技能,請執行 ug skills add 並選擇你想要的技能。 請參閱 新增工具與技能 以獲取更多選項。

請自備 Claude 訂閱

若想透過 Unity Gateway 在您自己的 Claude Pro、Max、Enterprise 或 Team 訂閱上執行 Claude Code,請向管理員申請 Claude Max/Enterprise 模式的服務提供者服務。 請參閱 Claude Max 與 Anthropic Enterprise 支援,了解需求、管理設定、運作方式及限制。

將模型提供者服務的完全限定名稱<catalog>.<schema>.<name>()傳給 --provider ,並將工作區 URL 傳給 --workspace:

ug claude --provider main.default.claude_subscription --workspace https://<workspace>.databricks.com

ug 設定 Claude Code 發送 Databricks-Model-Provider-Service 標頭,並將 Claude Code 指向本地的重新整理代理,而非直接指向 Unity Gateway 端點。 代理伺服器會將每個請求轉送到 https://<workspace-url>/ai-gateway/anthropic,並加入 X-Databricks-AI-Gateway-Token 標頭。 因為服務不會儲存憑證,所以ug會轉發你的 Anthropic OAuth 權杖,而不是 API 金鑰。

如果 Claude Code 提示你驗證,請選擇選項 1 - Claude 帳號並訂閱,並用你的 Anthropic 帳號登入。 如果遇到問題,請使用 claude /logout 登出,然後再登入。

Note

--provider 用於 Claude Max/Enterprise 模型提供者服務時,僅支援 ug claude。

手動設定 Claude 訂閱

只有在無法使用 ug時才使用手動設定。

  1. 取得 Azure Databricks 權杖。 X-Databricks-AI-Gateway-Token 標頭包含 Azure Databricks 權杖,用於驗證傳送至 Unity Gateway 的要求。 Unity Gateway 會將存取控制和使用記錄歸因於與此權杖綁定的身分,因此請使用屬於提出查詢之使用者的權杖。 選取下列其中一項:

    • OAuth 用戶對機器(U2M)搭配 Databricks CLI(建議)。 先用 CLI 登入一次,然後鑄造一個短命的 OAuth 代幣:

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

      請參閱 Authorize user access to Azure Databricks with OAuth and Authentication for the Databricks CLI。 U2M OAuth 代幣約一小時後到期,因此互動使用時必須重新整理並匯出變數。 要自動化 token 更新,可以使用 ug,它會運行本地代理,每次請求都會幫你刷新 OAuth token 。

    • 個人存取權杖(PAT),作為備份。 如果你無法使用 OAuth,請建立一個 PAT,並將其作為 <databricks-token> 使用。 PAT 不會依 OAuth 每 1 小時的週期到期,但它是與你的身分綁定的長期有效認證憑證。 請參見 用Azure Databricks個人存取憑證認證(舊版)。

  2. 在您的 shell 設定檔中加入以下內容(~/.zshrc 或 ~/.bashrc):

    export ANTHROPIC_BASE_URL="https://<workspace-url>/ai-gateway/anthropic"
    export ANTHROPIC_CUSTOM_HEADERS="X-Databricks-AI-Gateway-Token: Bearer <databricks-token>
    Databricks-Model-Provider-Service: <catalog>.<schema>.<name>"
    
    • 用你的工作區網址替換 <workspace-url> 。
    • 用上一步驟的 Azure Databricks token 來替換<databricks-token>。
    • 請用您服務模式的完整名稱來取代 <catalog>.<schema>.<name> 。
  3. 啟動 Claude 程式碼:

    claude
    
  4. 如果你還沒登入,Claude Code 會提示你驗證。 選擇選項一 - Claude 帳號並訂閱,並用你的 Anthropic 帳號登入。 如果遇到問題,請使用 claude /logout 登出,然後再登入。

你的 Claude Code 請求現在改由 Unity Gateway 轉送。 這些請求會計入你的 Anthropic 訂閱費用,並且你可享有集中式的存取、路由與使用管理。

在 Azure Databricks 計算上執行

若想在無伺服器運算或專用叢集上執行 Claude Code(無需安裝 ug),請連接 SSH 隧道並執行 claude。 代理程式已為 Unity Gateway 預先設定。 請參見「在 SSH 會話中執行編碼代理程式」。

手動設定 Claude 程式碼

將以下設定合併為 ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_MODEL": "<model-api-name>",
    "ANTHROPIC_BASE_URL": "https://<workspace-hostname>/ai-gateway/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<databricks-personal-access-token>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-databricks-use-coding-agent-mode: true",
    "CLAUDE_CODE_USE_GATEWAY": "1",
    "ENABLE_PROMPT_CACHING_1H": "1",
    "ENABLE_TOOL_SEARCH": "true"
  }
}

用你的工作區主機名稱替換 <workspace-hostname> ,不帶 https://。 設定<model-api-name>為支援 Anthropic Messages API 的模型服務的完整 Unity 目錄名稱。 這可以是 Claude 模型,也可以是 相容的開源模型。 提供你的 Azure Databricks 個人存取權杖。

從你的專案目錄執行 claude 。 其他設定請參見 Claude Code 設定。

自動模式

自動模式 是 Claude Code 的權限模式,能減少例行的權限提示。 安全分類器會審查擬議的工具動作,例如shell指令或檔案編輯,這些動作本應需您批准,並決定是否可繼續進行。

透過 Unity Gateway 的 Anthropic 模型會使用 Anthropic 原生的自動模式檢查功能。 對於由 Azure Databricks 託管且支援函式呼叫的非 Anthropic 基礎模型,Unity Gateway 提供分類器。 關於維護的模型清單及各模型功能,請參見 Databricks 提供的模型。

自動模式與 服務政策 提供互補檢查:

  • 自動模式安全分類器根據對話與自動模式規則,決定擬議的工具動作是否可繼續執行。
  • 服務政策將貴組織的治理規則套用至其所附加的模型、模型提供者或 MCP 服務上的請求與回應,包括 MCP 工具呼叫與結果。 部分 內建服務政策 也使用模型作為安全分類器,但其決策涉及受控服務互動。

自動模式核准不會凌駕於強制執行的服務政策之上。 例如,MCP 服務的政策即使在自動模式允許該動作時,也可能要求對破壞性工具呼叫進行人工批准。

Claude Code 在參考分類器前會評估明確 permissions.deny 的規則與內容範圍限定 permissions.ask 規則。 匹配的拒絕規則會阻擋該動作,而匹配的詢問規則則需要顯示權限提示。 自動模式也能根據對話與分類器規則封鎖操作,或者在檢查無法產生有效判定時封鎖操作。

在設定連線 ug後,請以自動模式啟動 Claude Code:

ug claude -- --permission-mode auto

手動連線時,執行 claude --permission-mode auto。 關於 ug 參數轉發,請參見 ug CLI 參考。

配置受信任的基礎設施

請描述貴組織的可信倉庫、網域與服務在 autoMode.environment 中。 這些條目幫助分類器區分對您的基礎設施的預期存取與應該阻擋的行為。 例如,將一個 autoMode 區塊合併到你的使用者設定中 ~/.claude/settings.json:

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/example-org and its repositories",
      "Trusted internal services: builds.internal.example.com"
    ]
  }
}

將範例條目替換成你組織的基礎設施。 條目為自然語言描述。 新增自己的環境項目時,請保留 "$defaults",以保留內建的環境條目。

分類器讀取 autoMode 使用者設定、管理設定或內嵌 --settings 設定。 它不會從 project .claude/settings.json 或 .claude/settings.local.json 讀取這個區塊。 管理員可以透過管理設定來分發共享設定。

關於規則自訂、管理設定以及檢視被封鎖的動作,請參見 「設定自動模式」。

追蹤分類器使用情況

Unity Gateway 傳送的檢查會將提出的工具引數與對話上下文傳送到獨立的分類器模型。 分類器請求會產生額外的模型費用,並可能增加延遲。

分類器請求會出現在 system.ai_gateway.usage 中,設定 invocation_metadata.source 為 SAFEGUARD_CLASSIFIER。 利用這個值區分安全檢查請求,並將其令牌使用量和延遲與你的程式碼模型請求區分開來。 請參閱 使用追蹤 以了解存取需求及使用表結構。

新增 MCP 工具

system.ai.dbsql、system.ai.sandbox 和 system.ai.web_search 都處於測試階段。 要使用這些預覽功能,帳號管理員必須從帳號主控台的 Previews 頁面啟用 Enhanced Unity Gateway 預覽。 Unity Gateway 本身已正式可用。 請參閱 管理帳戶預覽設定。

  1. 在你的工作空間中開啟 Unity Gateway > MCP 。 選擇 內建的 MCP 或 註冊您的外部 MCP 伺服器。

  2. 複製 MCP 的全名,例如 system.ai.github 或 <catalog>.<schema>.<service>。

  3. 確認你有 MCP 的存取權限。

  4. 安裝ug後,將 MCP 加入 Claude Code:

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

    把佔位符換成你複製的名字。 例如,GitHub 請使用 --names system.ai.github。 若要互動式選擇服務,請省略 --names。

第一次設定時,依照指示選擇工作區、登入並選擇模型。 ug 配置模型與 MCP 存取權限,並刷新憑證。 使用 ug claude 重新啟動 Claude 程式碼,然後 測試工具。

手動新增 MCP 工具

請使用下方 預設的 Claude Code 客戶端 ID ,或 自行設定 OAuth 應用程式。 要新增預設客戶端 ID 的 MCP,請執行:

claude mcp add --transport http --scope user \
  --client-id https://claude.ai/oauth/claude-code-client-metadata --callback-port 3118 \
  databricks-tools \
  "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>?o=<workspace-id>"

替換主機名稱、 工作區 ID 和 MCP 名稱。 打開 Claude Code,輸入 /mcp,並用你的 Azure Databricks 帳號登入伺服器。 用不同伺服器名稱重複這個步驟,針對每個想新增的 MCP,然後 測試某個工具。

使用你自己的 OAuth 應用程式
  1. 請帳號管理員在帳號主控台中開啟設定> App connections > Add connection。

  2. 輸入名稱,例如 claude-code-mcp;若為公用用戶端,取消勾選產生用戶端密碼,將重新導向 URL 設為 http://localhost:8080/callback,然後選擇 ai-gateway 範圍。 儲存並複製 客戶 ID。 請參見 建立 OAuth 應用程式。

  3. 使用該用戶端 ID 及匹配的回調埠註冊 MCP:

    claude mcp add --transport http --scope user \
      --client-id <client-id> --callback-port 8080 \
      databricks-tools \
      "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>"
    
  4. 打開 Claude Code,輸入 /mcp,然後登入。 如果您的組織需要機密用戶端,請在指令中新增 --client-secret 並在提示時輸入密碼。

測試 MCP 工具

  1. 在 Claude Code 中輸入 /mcp 並檢查伺服器是否已連接。
  2. 請 Claude 列出該伺服器的工具,然後請求讀取操作。 在 GitHub 中,請它在你可以存取的倉庫中找到一個議題。 對於自訂伺服器,請使用你註冊時測試過的工具和輸入。
  3. 如果工具呼叫提示你登入,打開 MCP 回傳的登入連結,完成提供者同意,然後重試該呼叫。
  4. 檢查 Claude 是否會呼叫工具並回傳結果。 光靠文字回覆並不能驗證連線。

若要使用 Azure Databricks 資料,請連線至 system.ai.genie_one_mcp 以處理商業問題,或連線至 system.ai.dbsql 以使用 SQL。 例如,請要求 SQL MCP 執行 SELECT 1 AS result。

關於權限、政策與使用情況,請參見 「治理 MCP」。

手動連接技能

若要將已發佈的 Unity Gateway 技能公開為工具,請將技能登錄註冊為 HTTP MCP 伺服器:

claude mcp add --transport http --scope user \
  --header "Authorization: Bearer <databricks-personal-access-token>" \
  databricks-skill-registry \
  "https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>"

用你的工作區、代幣和技能架構替換佔位符。 在 ?schema 前保留結尾斜線。 若要包含多個結構,重複參數: ?schema=main.default&schema=ml.prod。

重新啟動 Claude Code,並檢查與 /mcp 的連線。 請使用技能的完整名稱來要求 Claude 使用該技能,例如 Use <catalog>.<schema>.<skill-name> to review this query.。此連線會將技能作為 MCP 工具公開;ug skills add 則會下載技能以供原生探索。

Troubleshooting

  • Claude 程式碼無法連接:如果你使用 ug,請執行 ug doctor。 手動設定時,請檢查工作區主機名稱、標記、模型名稱和模型權限。

  • Claude Code OAuth 會回報重定向不匹配或連線逾時: 對於自訂的 OAuth 應用程式,請將其重定向 URL 與回調主機和埠口比對,並檢查 網路存取。 OAuth 應用程式的變更可能需要 長達 30 分鐘 才能生效。

下一步