編碼代理配置架構

此參考描述編碼代理配置中的每個欄位。 若要發布和管理設定,請參見 「配置編碼代理程式」。

以下配置會使用所有支援欄位。 在實際配置中,只設定團隊需要的欄位,並且每個代理只設定一個模型來源。 欄位名稱與 JSON 編輯器和 API 中的鍵相符。

{
  "default_agent": "CODING_AGENT_CLAUDE_CODE",
  "enabled_agents": [
    {
      "agent": "CODING_AGENT_CLAUDE_CODE",
      "config": {
        "models": {
          "model_services": [
            "system.ai.claude-opus-5-5",
            "system.ai.claude-sonnet-5-5",
            "system.ai.claude-haiku-5-5",
            "system.ai.claude-fable-5"
          ]
        },
        "default_models": {
          "default_model": "system.ai.claude-sonnet-5-5",
          "default_opus_model": "system.ai.claude-opus-5-5",
          "default_sonnet_model": "system.ai.claude-sonnet-5-5",
          "default_haiku_model": "system.ai.claude-haiku-5-5",
          "default_fable_model": "system.ai.claude-fable-5"
        },
        "smart_routing": { "enabled": true },
        "http_headers": { "x-team": "platform" },
        "tracing": { "enabled": true },
        "agent_native_settings": {
          "deniedMcpServers": [{ "serverName": "untrusted-server" }]
        }
      }
    },
    {
      "agent": "CODING_AGENT_CODEX",
      "config": {
        "models": {
          "unity_catalog_location": "main.default"
        },
        "default_models": {
          "default_model": "main.default.gpt-6-sol"
        },
        "smart_routing": { "enabled": false },
        "http_headers": {},
        "tracing": { "enabled": false }
      }
    },
    {
      "agent": "CODING_AGENT_GITHUB_COPILOT",
      "config": {
        "models": {
          "model_services": ["system.ai.claude-sonnet-5-5", "system.ai.gpt-5-5"]
        },
        "default_models": {
          "default_model": "system.ai.gpt-5-5"
        },
        "tracing": { "enabled": true },
        "vscode_integration": { "enabled": true }
      }
    }
  ],
  "mcp_servers": {
    "unity_catalog_location": "system.ai"
  },
  "skills": {
    "names": ["main.team_skills.code_review", "main.team_skills.test_writer"]
  },
  "smart_defaults": {
    "budget_id": "123e4567-e89b-12d3-a456-426614174000",
    "tiers": [
      {
        "spending_percentage": 0.8,
        "recommended_agent": "CODING_AGENT_CODEX",
        "recommended_model": "main.default.glm-5-3"
      }
    ]
  }
}

最上層欄位

Field 類型 Description
default_agent 字串(枚舉) 當沒有啟用智慧預設層級時,代理程式會在裸 ug 狀態下啟動。 必須出現在 enabled_agents。 有效值: CODING_AGENT_CLAUDE_CODE, CODING_AGENT_CODEX, CODING_AGENT_GITHUB_COPILOT。 啟用 smart_defaults 的階級會覆蓋它。
enabled_agents 物件陣列 透過各代理提供的 ug 服務及其每個代理的配置。 每位特工最多只能出現一次。 參見 enabled_agents[]。
mcp_servers 物件 MCP 伺服器,讓啟用的代理程式可以使用。 參見 mcp_servers。
skills 物件 技能要提供給啟用的代理。 參見 skills。
smart_defaults 物件 以支出為基礎的建議,隨著預算消耗而切換預設代理人與模型。 參見 smart_defaults。

enabled_agents

Field 類型 Description
agent 字串(枚舉) 這個條目所設定的編碼代理。 有效值: CODING_AGENT_CLAUDE_CODE, CODING_AGENT_CODEX, CODING_AGENT_GITHUB_COPILOT。
config 物件 每個代理的設定。 參見 config。

config

每個 enabled_agents 項目都有 config 一個物件,設定每個代理的模型來源、預設模型以及 Unity Gateway 功能。

Field 類型 Description
models 物件 特工的模範來源。 設定一個來源。 參見 models。
default_models 地圖 代理人啟動的預設模型。 參見 default_models。
smart_routing 物件 支援時會將代理加入 智慧路由(Smart Routing )執行子代理任務。 只需一個 enabled 布林值。 不支援 GitHub Copilot。
http_headers 地圖 將標頭附加於該代理的每個閘道請求上,作為鍵值字串對。 標頭值對工作區中的每位開發者都可見,所以不要在裡面放秘密。 標頭名稱必須是有效的 HTTP 欄位名稱,且標頭值不得包含控制字元。 保留用於閘道認證、身份或路由的名稱會被拒絕,包括 Authorization、 Proxy-Authorization、 Cookie、 Host,以及任何以 X-Forwarded-為 的名稱。
tracing 物件 針對 Claude Code、Codex 和 GitHub Copilot 的每個代理人客戶端追蹤。 只需一個 enabled 布林值。
vscode_integration 物件 僅限 GitHub Copilot,且必須使用。 只需一個 enabled 布林值。 true當開發者執行 ug configure時,也會在 Visual Studio Code 中設置 Copilot。 false只設定 Copilot CLI,並移除先前的 Visual Studio Code 設定。 其他代理無法設定這個欄位。
agent_native_settings 物件 代理自身的設定,as-is ug 寫入代理機器的全機管理設定檔。 僅支援部分代理人。 參見 agent_native_settings。

模型

models 可以包含以下其中一種。 範例請參見「 為每個代理人選擇模型來源」。

Field 類型 Description
model_services 字串陣列 提供完整的 Unity 目錄模型服務名稱靜態清單。
model_provider_service 字串 完整的 Unity 目錄名稱,為模型提供者服務。 所有型號都會上市。
unity_catalog_location 字串 目錄與結構catalog.schema()。 開發者所擁有 EXECUTE 的所有模型服務都會開放。
sources 字串陣列 將公開的個別模型與萬用字元清單。 最多接受 100 個條目,且必須非空白且唯一。 無法與其他模型來源欄位合併使用。 請參閱下方的入口形狀、通配符規則及範例。

每個 sources 條目是模型服務名稱、模型提供者服務背後的模型,或萬用字元:

  • catalog.schema.model-service: 一個模型服務,例如 system.ai.claude-haiku-5-5。
  • catalog.schema.model-provider-service.model:模型提供者服務背後的一個模型,例如 main.default.anthropic_prod.claude-sonnet-5-5。 模型 ID 可以包含點,例如 main.default.openai_prod.gpt-4.1。
  • catalog.schema.*:結構中所有模型服務。 該結構必須包含至少一個模型服務。
  • catalog.schema.model-provider-service.*:該模型供應商服務背後的每一個模型。 提供者服務必須存在。

萬用字元必須是整個最後一個區段。 像 這樣的 system.ai.claude-* 部分模式會被拒絕。 目錄、結構與服務名稱不區分大小寫匹配。 提供者模型 ID 以區分大小寫相符。 sources 不可與 model_services、 model_provider_service、 或 unity_catalog_location結合。

若要將模型提供者服務、Azure Databricks 模型服務及兩個萬用字元表單混合,請設定sources為:

{
  "models": {
    "sources": [
      "main.default.anthropic_prod.claude-sonnet-5-5",
      "system.ai.claude-haiku-5-5",
      "main.default.*",
      "main.default.openai_prod.*"
    ]
  }
}

啟用 智慧路由 時,清單可包含模型提供者服務背後的外部模型,路由器則從清單中所有模型中選擇。 當兩個項目解析為相同模型時,路由器只會依列表順序使用第一個項目。

default_models

default_models 是模型名稱的預設鍵對應。 當來源是模型提供者服務時,模型名稱為模型 ID;否則則為完整的 Unity 目錄模型服務名稱。 靜態 model_services 清單中,所有預設值也必須同時出現在該清單中。 使用 sources 清單時,每個預設必須是條目所包含的特定模型,該模型 sources 可以直接列出或以萬用字元匹配。 預設不能是萬用卡。

  • default_model:代理人的整體預設值。 除非客服啟用 智慧路由 ,否則必須如此。 GitHub Copilot 不支援智慧路由,因此 GitHub Copilot 條目總是需要它。
  • 每個家族的鍵(default_opus_model、default_sonnet_modeldefault_haiku_model和default_fable_model):可選。 只用 Claude Code。
Key 適用對象 Description
default_model 所有代理人 整體上是上市時的預設模型。
default_opus_model 僅限 Claude Code Opus 家族的預設。
default_sonnet_model 僅限 Claude Code 十四行詩家族的預設。
default_haiku_model 僅限 Claude Code 俳句家族的預設。
default_fable_model 僅限 Claude Code Fable 家族的預設。

agent_native_settings

agent_native_settings 將代理自身的管理設定傳給開發者的機器。 當開發者在互動終端機中執行 ug configure 時,會 ug 將每個金鑰寫入代理的全機管理設定檔,該檔案優先於開發者對該代理的設定。 鍵和值使用代理程式自己的格式,請參考代理文件了解每個設定的功能。

僅接受下表中的代理與金鑰。 設定 agent_native_settings 為另一個代理或使用其他金鑰的設定,在儲存時會被拒絕。

代理程式 管理設定檔案 接受的金鑰 Reference
克勞德密碼 /etc/claude-code/managed-settings.json (Linux)、 /Library/Application Support/ClaudeCode/managed-settings.json (macOS) allowManagedMcpServersOnly、allowedMcpServers、deniedMcpServers、enableAllProjectMcpServers、enabledMcpjsonServers、disabledMcpjsonServers Claude Code 管理的 MCP 設定

如果你移除了某個金鑰,或開發者切換到設定中沒有設定該金鑰的工作區, ug 下一次執行時會從管理的設定檔中移除它,除非有人在寫入後 ug 手動修改了該值。 要移除寫出的 ug 設定,執行 ug revert.

如果你設定 Claude Code 的 allowedMcpServers, ug 會把它從這個配置註冊的 MCP 伺服器加入清單,這樣它們就能保持可用。 要阻擋其中一個,請從 中移除。mcp_servers

mcp_servers

mcp_servers 可以包含以下其中之一:

Field 類型 Description
names 字串陣列 Unity 目錄的資源名稱要精確。
unity_catalog_location 字串 目錄與結構catalog.schema()。 包含了所有相關資源。

技能

skills 可以包含以下其中之一:

Field 類型 Description
names 字串陣列 Unity 目錄的資源名稱要精確。
unity_catalog_location 字串 目錄與結構catalog.schema()。 包含了所有相關資源。

smart_defaults

Field 類型 Description
budget_id 字串(UUID) 預算是 budget_configuration_id。
tiers 物件陣列 花分階級。 達到門檻的最高等級適用。

tiers

每個項目 tiers 可包含以下內容:

Field 類型 Description
spending_percentage number 此層級啟動時,預算的比例(0–1)。 例如,是 0.8 80%。
recommended_agent 字串(枚舉) 用代理人來切換預設值。 必須出現在 enabled_agents。 有效值: CODING_AGENT_CLAUDE_CODE, CODING_AGENT_CODEX, CODING_AGENT_GITHUB_COPILOT。
recommended_model 字串 在這個層級啟用時,可以切換到預設模式的模型。

API 也會回傳你未設定的唯讀或伺服器管理欄位,包括 name、 workspace_id、 create_time、 updated_user_idcreated_user_idupdate_timeretrieved_time和 。