Important
這項功能位於 測試版 (Beta) 中。 要使用它,工作區管理員必須從預覽頁面開啟 Unity Gateway 管理設定。 請參閱 管理 Azure Databricks 預覽。
使用行動裝置管理(MDM)和 Unity Gateway CLI 來分發團隊的程式碼代理設定。 管理員會在工作區發佈設定,開發者則使用熟悉的代理,搭配已設定的模型、MCP 伺服器及技能。
你的 MDM 軟體會在每個裝置上執行一個帶有管理員權限的配置腳本。 腳本會安裝 ug、Databricks CLI 以及以全機器層級安裝編碼代理程式,然後執行 ug configure,它會為整個裝置安裝工作區的編碼代理設定。 開發者接著在沒有管理員權限的情況下啟動代理程式,並以自己的 Azure Databricks 帳號登入。
Note
MDM 配置會配置 Claude Code 和 Codex,這些都具有全機器的設定。 它不會在 Visual Studio Code 中設定 GitHub Copilot CLI 或 GitHub Copilot。 開發者自行使用 ug configure --agents copilot 設定 GitHub Copilot。
使用 MDM 部署
配置程式碼代理
啟用團隊使用的代理程式,並在工作區中發布設定。 請參見 設定程式設計代理。
每個已啟用的代理程式都必須在設定中至少有一個模型,讓下一個步驟中的服務主體名稱可以使用。 例如,Claude 程式碼需要 Claude 模型。
ug configure 跳過任何沒有模型的代理程式。
建立佈建服務主體
MDM 政策只在執行期間使用服務主體來讀取已發佈的設定檔。 開發者會以自己的身分進行驗證。
只開啟 Workspace 存取 權限。 服務主體不需要其他權益。 請參閱 權限管理。
授權服務主體存取已發佈配置中的模型、MCP 伺服器及技能,包括所需的 Unity Catalog 權限。 請參見 「授予模型、MCP 伺服器與技能存取權」。
在服務主體的 Secrets 標籤中,點選 Generate secret。 選擇與你的輪替原則相符的有效期。 在 範圍中,點選 其他 API,新增
ai-gateway和unity-catalog範圍,並將每個設定為 讀取。 請參閱 步驟 1:建立 OAuth 密碼。
複製客戶 ID 和密鑰。 關閉對話框後,你無法再次查看秘密。
搭配你的 MDM 軟體一起部署
Important
安裝 ug 在裝置上每個使用者都能執行的共用位置,而不是在 root 使用者的首頁目錄。
ug configure 在全機代理設定中記錄路徑 ug,每個開發者的代理程式會從該路徑執行 ug 以進行身分驗證。
Jamf Pro(macOS)
這些步驟將使用 Jamf Pro 把 Claude Code 和 Codex 部署到 macOS 裝置。 每個裝置需要:
- 可存取你的工作區 URL 的網路、PyPI(
pypi.org和files.pythonhosted.org)、GitHub(github.com和raw.githubusercontent.com)、astral.sh,以及downloads.claude.ai。 - Xcode 的命令列工具,或允許腳本使用
softwareupdate安裝它們的權限。ug可從 GitHub 安裝,這需要git。
新增指令碼
在 Jamf Pro 中,請前往 設定 > 電腦管理 > 腳本 > 新增,並將腳本命名為
Unity Gateway provision。在 腳本 標籤中,貼上以下腳本:
查看配置腳本
#!/bin/bash # # macOS MDM provisioning script, written for Jamf Pro policies: install # ug, the Databricks CLI, Claude Code and Codex machine-wide and run # `ug configure` as root, which installs the workspace policy at # /etc/unitygateway/managed-settings.json. # Users then launch with no sudo: # # UG_SKIP_OS_SETTINGS=1 ug claude (or: ug codex) # # Jamf parameters ($1-$3 are reserved by Jamf): # $4 Databricks workspace URL, starting with https:// # $5 Service principal OAuth client id # $6 Service principal OAuth client secret # # The token is used for this run only; developers sign in with their own # OAuth. Needs access to PyPI, GitHub, astral.sh and downloads.claude.ai. set -euo pipefail umask 022 export HOME=/var/root export PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin WORKSPACE="${4%/}" PREFIX=/usr/local/unity-gateway CLAUDE_RELEASES=https://downloads.claude.ai/claude-code-releases CODEX_RELEASES=https://github.com/openai/codex/releases/latest/download UG_REPO=https://github.com/databricks/unity-gateway UV_URL=https://astral.sh/uv/install.sh CLI_URL=https://raw.githubusercontent.com CLI_URL="$CLI_URL/databricks/setup-cli/main/install.sh" CLT_MARKER=/tmp/.com.apple.dt.CommandLineTools CLT_MARKER="$CLT_MARKER.installondemand.in-progress" # ug must be in a shared path: the machine-wide agent settings # run it by absolute path for every user. export UV_TOOL_DIR="$PREFIX/tools" export UV_TOOL_BIN_DIR=/usr/local/bin export UV_PYTHON_INSTALL_DIR="$PREFIX/python" export UV_PYTHON_PREFERENCE=only-managed mkdir -p /usr/local/bin # Get ug from git if ! xcode-select -p >/dev/null 2>&1; then touch "$CLT_MARKER" clt="$(softwareupdate -l 2>/dev/null \ | sed -n 's/^\* Label: \(Command Line Tools.*\)$/\1/p' \ | tail -n1)" softwareupdate -i "$clt" rm -f "$CLT_MARKER" fi if ! command -v uv >/dev/null; then curl -LsSf "$UV_URL" \ | env UV_INSTALL_DIR=/usr/local/bin UV_NO_MODIFY_PATH=1 sh fi uv tool install --force "git+$UG_REPO" if [ ! -x /usr/local/bin/databricks ]; then curl -fsSL "$CLI_URL" | sh fi # Download into a private temporary directory, not fixed /tmp paths tmp="$(mktemp -d)" trap 'rm -rf "$tmp"' EXIT # Install Claude Code if [ ! -x /usr/local/bin/claude ]; then case "$(uname -m)" in arm64) platform=darwin-arm64 ;; *) platform=darwin-x64 ;; esac version="$(curl -fsSL "$CLAUDE_RELEASES/latest")" base="$CLAUDE_RELEASES/$version" checksum="$(curl -fsSL "$base/manifest.json" \ | plutil -extract "platforms.$platform.checksum" raw -o - -)" curl -fsSL -o "$tmp/claude" "$base/$platform/claude" echo "$checksum $tmp/claude" | shasum -a 256 -c - install -m 755 "$tmp/claude" /usr/local/bin/claude fi # Install Codex if [ ! -x /usr/local/bin/codex ]; then case "$(uname -m)" in arm64) target=aarch64-apple-darwin ;; *) target=x86_64-apple-darwin ;; esac curl -fsSL "$CODEX_RELEASES/codex-$target.tar.gz" \ | tar -xzf - -C "$tmp" "codex-$target" install -m 755 "$tmp/codex-$target" /usr/local/bin/codex fi # Get short lived credential; curl reads the client id and secret from # stdin (-K -) so they don't appear in its arguments. resp="$(printf 'user = "%s:%s"\n' "$5" "$6" \ | curl -sS -K - \ -d grant_type=client_credentials \ --data-urlencode 'scope=ai-gateway:read unity-catalog:read' \ "$WORKSPACE/oidc/v1/token")" if ! DATABRICKS_BEARER="$(printf '%s' "$resp" \ | plutil -extract access_token raw -o - -)"; then echo "Token request to $WORKSPACE failed: $resp" >&2 exit 1 fi export DATABRICKS_BEARER ug configure --global --workspace "$WORKSPACE" \ --agents claude,codex </dev/null在 選項 索引標籤中,標示 參數 4
Workspace URL、參數 5Client ID和 參數 6Client secret。選取儲存。
這個腳本只有在 Claude Code、Codex 和 Databricks CLI 缺失時才安裝,並且每次執行時都會重新安裝 ug。 第一次安裝後,它不會更新代理程式或 CLI。 為了讓它們保持最新狀態,請修改腳本,使其符合你在裝置上更新軟體的方式。
建立政策
請前往電腦> 原則> 新增。
在 一般 中,將 觸發條件 設為 定期簽到,並將 執行頻率 設為 每天一次。 每個裝置每天都會執行
ug configure,並套用你在工作區發布的設定更新。在腳本中,添加,並將Priority設為
Unity Gateway provision。 輸入參數:Parameter Value 4(工作區網址) 你的工作區網址,開頭是 https://.5(客戶識別碼) 服務主體的用戶端識別碼。 6(用戶端密鑰) 服務主體名稱的秘密。 在 Scope 中,選擇要作為目標的裝置。 先從一小組試點裝置開始。
選取儲存。 Jamf Pro 會在每個目標裝置下一次檢查時執行該政策。
Warning
Jamf Pro 會將政策參數以命令列參數傳遞給腳本。 任何本地使用者都能讀取用戶端 ID 和用戶端密鑰,例如在腳本執行時用 ps,而能查看原則的 Jamf Pro 管理員也能讀取這些資訊。 腳本不會把憑證或權杖寫入磁碟。 為減少洩漏影響,僅授予 服務主體識別工作區存取 權限,使用短暫的秘密壽命,並定期輪替秘密。
在開發者機器上啟動代理程式
在裝置上執行政策後,開發者會從終端機啟動代理程式,且不需管理員權限:
UG_SKIP_OS_SETTINGS=1 ug claude
UG_SKIP_OS_SETTINGS=1 ug codex
UG_SKIP_OS_SETTINGS=1 告訴 ug 使用 MDM 政策安裝的設定。 開發者可以在他們的 shell 設定檔中設定 UG_SKIP_OS_SETTINGS=1,即可在每個工作階段使用它。 第一次啟動會開啟瀏覽器,開發者登入 Azure Databricks。 編碼代理程式的活動則歸因於個別開發者,而非服務主體。
要縮短啟動指令,為開發者提供可設定變數並啟動代理程式的別名,例如在使用 MDM 部署的 shell 設定檔中:
alias claude='UG_SKIP_OS_SETTINGS=1 ug claude'
alias codex='UG_SKIP_OS_SETTINGS=1 ug codex'
推出 Claude 桌面版
同一 ug configure 執行也會為裝置上的每個使用者設定 Claude 桌面應用程式。 要支援 Claude 桌面,請在佈建腳本執行 ug configure 之前,先在該腳本中安裝 Claude 桌面。 上面提到的 Jamf Pro 腳本並未安裝 Claude 桌面版。
使用者第一次開啟 Claude 桌面時,會用自己的 Azure Databricks 帳號登入。 使用者也可以 匯入 claude.ai 專案和聊天內容。
驗證部署
在試驗裝置上,使用開發者的作業系統帳號登入並檢查:
- 代理程式會根據已設定的模型啟動並回應。
- 已設定的 MCP 伺服器與技能皆可使用,開發者可使用它們。
- 請求會出現在 Unity Gateway 使用追蹤中,若啟用追蹤則會出現追蹤。 請參見 監控編碼代理活動。
在更改佈建指令碼或已發布的設定後,重複這些檢查。
維護憑證與設定
若要輪換服務主體的密碼:
- 為服務主體產生一個新的密碼。
- 更新你的 MDM 原則中的密碼。
- 當原則在你的裝置上執行後,刪除舊的密碼。
如果密鑰已洩漏,請立即輪換密鑰並刪除舊密鑰。 腳本請求的令牌壽命很短,且腳本不會寫入裝置,因此沒有每個裝置的憑證可供撤銷。
要更新設定,請在工作區中發布變更。 裝置會在下一次執行政策時套用它們。 請參見 同步設定更新。
Troubleshooting
| 錯誤 | Cause |
|---|---|
Token request to ... failed: {"error":"invalid_client"...} |
MDM 政策中的客戶端 ID 或秘密密碼錯誤,或密碼已過期。 |
Token request ... failed: ... Scopes ... are not assigned to the client |
密鑰沒有 ai-gateway:read 和 unity-catalog:read 的範圍。 |
None of the coding agents enabled by your workspace configuration are available |
沒有任何已啟用的代理程式具有服務主體可使用的模型,例如,Claude Code 已設定,但未配置 Claude 模型。 |