推出帶有行動裝置管理(MDM)的程式碼代理

Important

這項功能位於 測試版 (Beta) 中。 要使用它,工作區管理員必須從預覽頁面開啟 Unity Gateway 管理設定。 請參閱 管理 Azure Databricks 預覽。

使用行動裝置管理(MDM)和 Unity Gateway CLI 來分發團隊的程式碼代理設定。 管理員會在工作區發佈設定,開發者則使用熟悉的代理,搭配已設定的模型、MCP 伺服器及技能。

支援的 MDM 軟體:

  • Jamf Pro (macOS),搭配現成的佈建指令碼

你的 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 政策只在執行期間使用服務主體來讀取已發佈的設定檔。 開發者會以自己的身分進行驗證。 腳本會暫時使用服務主體的認證,以便該 ug 主體能連接工作區並下載編碼代理程式的設定。

  1. 將ug-mdm-provisioning到你的工作區,例如 。

  2. 只開啟 Workspace 存取 權限。 服務主體不需要其他權益。 請參閱 權限管理。

  3. 授權服務主體存取已發佈配置中的模型、MCP 伺服器及技能,包括所需的 Unity Catalog 權限。 請參見 「授予模型、MCP 伺服器與技能存取權」。

  4. 在服務主體的 Secrets 標籤中,點選 Generate secret。 選擇與你的輪替原則相符的有效期。 在 範圍中,點選 其他 API,新增 ai-gateway 和 unity-catalog 範圍,並將每個設定為 讀取。 請參閱 步驟 1:建立 OAuth 密碼。

    產生 OAuth 秘密對話框,並在「其他 API」下新增 ai-gateway 和 unity-catalog 範圍,兩者皆設為讀取

  5. 複製客戶 ID 和密鑰。 關閉對話框後,你無法再次查看秘密。

搭配你的 MDM 軟體一起部署

Important

安裝 ug 在裝置上每個使用者都能執行的共用位置,而不是在 root 使用者的首頁目錄。 ug configure 在全機代理設定中記錄路徑 ug,每個開發者的代理程式會從該路徑執行 ug 以進行身分驗證。

Jamf Pro(macOS)

這些步驟將使用 Jamf Pro 把 Claude Code 和 Codex 部署到 macOS 裝置。 每個裝置需要:

  • 對你工作區 URL 的網路存取,PyPI(pypi.org 和 github.com)、GitHub(raw.githubusercontent.com 和 astral.sh)、nodejs.org、registry.npmjs.org 和 files.pythonhosted.org。
  • Xcode 的命令列工具,或允許腳本使用 softwareupdate 安裝它們的權限。 ug可從 GitHub 安裝,這需要 git。

新增指令碼

  1. 在 Jamf Pro 中,請前往 設定 > 電腦管理 > 腳本 > 新增,並將腳本命名為 Unity Gateway provision。

    Jamf Pro 新腳本頁面在「一般」標籤頁上,顯示名稱為 Unity Gateway provision

  2. 在 腳本 標籤中,貼上以下腳本:

    查看配置腳本
    #!/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. It also adds `claude` and
    # `codex` aliases to /etc/zshrc and /etc/bashrc, so users launch with
    # `claude` or `codex` in a new terminal, with no sudo.
    #
    # 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, nodejs.org and npmjs.org.
    
    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
    NODE_VERSION=22.23.5
    NODE_SHA256=89fadefd7798158d8990ca9ed7dbb58f8ca7593adb92fe3da8a445db99415533
    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
    # ug's npm installer must put agents on every user's PATH, not in root's home.
    export npm_config_prefix=/usr/local
    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
    
    # ug configure installs missing agents with npm; provide a shared Node.js runtime.
    if ! command -v node >/dev/null || ! command -v npm >/dev/null; then
      tmp="$(mktemp -d)"
      trap 'rm -rf "$tmp"' EXIT
      package="node-v$NODE_VERSION.pkg"
      /usr/bin/curl -fsSL -o "$tmp/$package" \
        "https://nodejs.org/dist/v$NODE_VERSION/$package"
      printf '%s  %s\n' "$NODE_SHA256" "$tmp/$package" | /usr/bin/shasum -a 256 -c -
      /usr/sbin/installer -pkg "$tmp/$package" -target /
    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
    
    /usr/local/bin/ug configure --global --mdm --workspace "$WORKSPACE" \
      --agents claude,codex </dev/null
    unset DATABRICKS_BEARER resp
    
    # Aliases for every user's interactive zsh and bash shells. The block is
    # rewritten on each run, which restores it if a macOS update resets
    # the file.
    for rc in /etc/zshrc /etc/bashrc; do
      [ -f "$rc" ] || continue
      sed -i '' '/^# BEGIN unity-gateway/,/^# END unity-gateway/d' "$rc"
      cat >>"$rc" <<'ALIASES'
    # BEGIN unity-gateway (managed by MDM)
    alias claude='UG_SKIP_OS_SETTINGS=1 ug claude'
    alias codex='UG_SKIP_OS_SETTINGS=1 ug codex'
    # END unity-gateway
    ALIASES
    done
    
  3. 在 選項 索引標籤中,標示 參數 4Workspace URL、參數 5Client ID 和 參數 6Client secret。

    Jamf Pro 腳本選項標籤,參數 4 標記為 Workspace URL,參數 5 標記為用戶端 ID,參數 6 標記為用戶端密鑰

  4. 選取儲存。

腳本會在每次執行時重新安裝ug,並且只有在缺少 Databricks CLI 時才會安裝它。 如果缺少 Node.js 或 npm,腳本會在檢查固定的 SHA-256 校驗碼後安裝官方 Node.js 22.23.5 套件。 ug configure 然後在共用 PATH 上重複使用現有代理程式,或透過 Unity Gateway 內建安裝程式透過 npm 安裝 Claude Code 和 Codex。 工作區未啟用的代理程式則未安裝。 腳本不會更新 Node.js、代理程式或 CLI;為了保持它們的最新,請修改腳本以符合您更新裝置軟體的方式。

配置了此早期腳本版本的 Mac 會保留其原生代理程式安裝;執行新腳本並不等於遷移到 npm。 要將這些 Mac 移至 npm,請使用軟體管理程序移除舊的原生安裝,然後再次執行該政策。

建立政策

  1. 請前往電腦> 原則> 新增。

  2. 在 一般 中,將 觸發條件 設為 定期簽到,並將 執行頻率 設為 每天一次。 每個裝置每天都會執行 ug configure ,並套用你在工作區發布的設定更新。

    Jamf Pro 新政策一般選項,選取定期簽入觸發條件,且執行頻率設為每日一次

  3. 在腳本中,添加,並將Priority設為Unity Gateway provision。 輸入參數:

    Parameter Value
    4(工作區網址) 你的工作區網址,開頭是 https://.
    5(客戶識別碼) 服務主體的用戶端識別碼。
    6(用戶端密鑰) 服務主體名稱的秘密。

    Jamf Pro 政策腳本選項顯示 Unity Gateway 配置腳本,優先順序設為 After,並以工作區 URL、用戶端 ID 及用戶端密鑰的佔位符值

  4. 在 Scope 中,選擇要作為目標的裝置。 先從一小組試點裝置開始。

  5. 選取儲存。 Jamf Pro 會在每個目標裝置下一次檢查時執行該政策。

告訴開發人員

政策在裝置上執行後,開發者會開啟新的終端機並照常執行 codex 或 claude。 第一次啟動會開啟瀏覽器,開發者登入 Azure Databricks。 編碼代理程式的活動則歸因於個別開發者,而非服務主體。

推出 Claude 桌面版

同一 ug configure 執行也會為裝置上的每個使用者設定 Claude 桌面應用程式。 要支援 Claude 桌面,請在佈建腳本執行 ug configure 之前,先在該腳本中安裝 Claude 桌面。 上面提到的 Jamf Pro 腳本並未安裝 Claude 桌面版。

使用者第一次開啟 Claude 桌面時,會用自己的 Azure Databricks 帳號登入。 使用者也可以 匯入 claude.ai 專案和聊天內容。

驗證部署

在試驗裝置上,使用開發者的作業系統帳號登入並檢查:

  • 代理程式會根據已設定的模型啟動並回應。
  • 已設定的 MCP 伺服器與技能皆可使用,開發者可使用它們。
  • 請求會出現在 Unity Gateway 使用追蹤中,若啟用追蹤則會出現追蹤。 請參見 監控編碼代理活動。

在更改佈建指令碼或已發布的設定後,重複這些檢查。

維護憑證與設定

若要輪換服務主體的密碼:

  1. 為服務主體產生一個新的密碼。
  2. 更新你的 MDM 原則中的密碼。
  3. 當原則在你的裝置上執行後,刪除舊的密碼。

要更新設定,請在工作區中發布變更。 裝置會在下一次執行政策時套用它們。 請參見 同步設定更新。

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 模型。