設定伺服器管理的設定

​

需求

• Claude for Teams 或 Claude for Enterprise 方案
• 您的 Claude 組織中的擁有者或主要擁有者角色，以檢視和編輯配置
• 對 api.anthropic.com 的網路存取

​

在伺服器管理和端點管理的設定之間選擇

​

設定伺服器管理的設定

{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
        ]
      }
    ]
  }
}

​

驗證設定傳遞

• 已傳遞的設定已載入
• 您的組織未設定伺服器管理的設定
• 擷取失敗，包含原因以及是否仍然套用快取原則
• Claude Code 略過了擷取，包含原因。請參閱平台可用性以了解略過擷取的提供者和設定

​

存取控制

• 主要擁有者
• 擁有者

​

僅限受管的設定

​

目前的限制

• 設定統一套用到組織中的所有使用者。尚不支援每個群組的設定。
• 您無法透過伺服器管理的設定分發 managed-mcp.json 檔案。改為在該處傳遞 allowedMcpServers 和 deniedMcpServers 原則金鑰。在 Claude Code v2.1.259 或更新版本上，您也可以透過 managedMcpServers 提供遠端伺服器，其僅接受 http 和 sse 伺服器，且不會以檔案的方式進行獨佔控制。 Claude Code 在其系統路徑部署的 managed-mcp.json 與受管設定層級分開讀取，因此當伺服器管理的設定生效時，檔案仍然適用。
• 限制於作業系統層級原則來源的設定，例如 policyHelper 和 wslInheritsWindowsSettings，不會被接受。改為透過 MDM 或系統 managed-settings.json 檔案部署它們。policyHelper 以該方式部署時，只有在其來源是在受管層級內的優先順序下選擇的來源時，才會執行。

​

設定傳遞

​

設定優先順序

​

跨受管來源的個別金鑰例外

• 跨來源鎖定金鑰：一小組金鑰，例如沙箱允許清單鎖定，列在受管設定頁面上。當任何管理員控制的受管來源設定它們時，Claude Code 會遵守它們；使用者可寫入的 HKCU 登錄層級被排除。當 policyHelper 提供受管設定時，其輸出是這些檢查讀取的唯一來源，除了 forceRemoteSettingsRefresh，Claude Code 在啟動時直接從管理員來源讀取它。
• env 區塊：除了與認證金鑰配對的遙測單位和路由變數（下面涵蓋）外，它會跨管理員控制的來源按金鑰合併。對於每個環境變數，定義它的最高優先順序來源會獲勝，較低的管理員來源會填入較高來源未設定的變數。因此，端點管理的 env 項目會在伺服器管理的設定未設定該變數時套用，或在快取的伺服器值等待伺服器確認時被保留時套用。需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，Claude Code 僅套用選定來源的整個 env 區塊。
  • 遙測單位：OTEL_EXPORTER_OTLP_* 匯出器金鑰、OTEL_LOG_* 內容擷取切換、OTEL_LOGS_EXPORTER 以及測試版追蹤變數 ENABLE_BETA_TRACING_DETAILED 和 BETA_TRACING_ENDPOINT 遵循設定任何這些變數的最高來源作為一個單位。傳遞 otelHeadersHelper 認證金鑰的來源也會聲稱該單位，但僅在它是選定來源時才會放置這些變數：未被選定但傳遞該金鑰的來源不會貢獻其中任何一個，仍然會阻止較低來源填入它們。無論哪種方式，來自一個來源的匯出器端點永遠無法與來自另一個來源的認證配對。
  • 認證配對的路由：將路由變數與選定來源專用認證金鑰（例如 apiKeyHelper 或 otelHeadersHelper）配對的來源，僅在它贏得該位置時才會貢獻這些路由變數。
• 閘道登入金鑰：Claude Code 永遠不會從伺服器管理的設定讀取 forceLoginGatewayUrl 或 forceLoginMethod 的 "gateway" 值，因此選擇伺服器管理的設定既不會提供閘道登入，也不會隱藏在 MDM 原則或受管設定檔中設定的登入。managedSourcesBehavior 項目說明機器上的哪個管理員來源提供它們。

​

擷取和快取行為

• 當開發人員在啟動時登入時（例如在首次執行或 /logout 之後），Claude Code 會等待最多五秒鐘以進行擷取，然後才會開啟工作階段。當原則及時到達時，Claude Code 會從第一個畫面強制執行它，並在其上顯示您的 companyAnnouncements。當承載需要安全核准時，Claude Code 會結束等待，並在開發人員核准後套用承載
• 在任何其他啟動中，以及當該五秒鐘等待時間用完時，Claude Code 會在擷取繼續進行時開啟工作階段，因此在設定載入和限制生效之前會經過一個簡短的視窗
• 如果擷取失敗，Claude Code 會在沒有伺服器管理的設定的情況下繼續，並在互動工作階段中警告沒有遠端原則適用；端點管理的設定仍然適用。如果受管來源設定 forceRemoteSettingsRefresh，Claude Code 會改為結束

• 快取設定在啟動時立即套用，除了快取的 modelPricing 和 managedMcpServers 值以及 Claude Code 保留的環境變數，直到伺服器確認承載
• 快取的 modelPricing 在工作階段的擷取確認承載之前不會套用。在那之前，開發人員在 /usage 中看到的成本數字和狀態行是列表價格
• 快取的 managedMcpServers 區塊在工作階段的擷取確認承載之前不會套用。Claude Code 會等待最多 30 秒鐘以進行該擷取，然後才會連接 MCP 伺服器。如果擷取失敗或逾時，工作階段會在沒有組織伺服器的情況下啟動，/status 會說明這一點，它們會在稍後的擷取確認它們後連接。請參閱提供的伺服器何時連接以了解完整行為，包括首次啟動。需要 Claude Code v2.1.259 或更新版本
• Claude Code 在背景擷取新鮮設定
• 快取設定透過網路故障持續存在。如果啟動擷取失敗，Claude Code 會在互動工作階段中警告快取原則正在生效
• 在擷取成功之前，在啟動時保留的值會保持被保留

• Proxy 和 TLS 設定，例如 HTTPS_PROXY、NODE_EXTRA_CA_CERTS 以及 mTLS 用戶端憑證變數 CLAUDE_CODE_CLIENT_CERT 和 CLAUDE_CODE_CLIENT_KEY
• API 路由和提供者選擇，包括 ANTHROPIC_BASE_URL、提供者選擇變數（例如 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_VERTEX）以及提供者端點 URL（例如 ANTHROPIC_BEDROCK_BASE_URL）
• 驗證認證，例如 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 CLAUDE_CODE_OAUTH_TOKEN
• 設定目錄選擇器 CLAUDE_CONFIG_DIR
• 認證來源和設定目錄選擇器，在 Claude Code v2.1.223 或更新版本中：工作負載身分識別聯盟變數（例如 ANTHROPIC_FEDERATION_RULE_ID 和 ANTHROPIC_IDENTITY_TOKEN）、設定檔和設定目錄選擇器 ANTHROPIC_PROFILE 和 ANTHROPIC_CONFIG_DIR，以及作業系統目錄變數 HOME、XDG_CONFIG_HOME、APPDATA 和 USERPROFILE

​

傳遞設定中的無效項目

• ~/.claude/remote-settings.json 中的快取會儲存已移除無效項目的已修復承載，除了無效的 cleanupPeriodDays 和 desktopSessionCleanupPeriodDays 值，它們會保留在快取副本中，永遠不會被套用。
• 當承載中沒有欄位可以被修復，且承載不僅是那些保留金鑰時，Claude Code 會拒絕承載、保留最後接受的快取設定，並將 Remote settings: Settings validation failed - no fields could be salvaged 寫入偵錯日誌。設定 forceRemoteSettingsRefresh 時，CLI 會改為結束。
• 安全核准對話方塊會評估已修復的承載，因此被移除的無效項目永遠不會被呈現以供核准，也永遠不會執行。

​

強制執行失敗關閉啟動

• 如果閘道以 401 回答有人值守的互動啟動，且此設定已關閉，閘道已結束該登入。Claude Code 會列印 Cloud gateway session expired — run /login to reconnect.，並開啟未登入閘道的工作階段，直到使用者執行 /login。
• 當擷取以任何其他方式失敗，或在除 claude auth 子命令之外的任何其他啟動類型中失敗時，用戶端會以錯誤結束。

{
  "forceRemoteSettingsRefresh": true
}

​

安全核准對話方塊

• Shell 命令設定：執行 shell 命令的設定，例如 apiKeyHelper、statusLine 和 otelHeadersHelper
• 沙箱二進位設定：sandbox.bwrapPath、sandbox.socatPath 和 sandbox.ripgrep。這些設定中的每一個都指向可執行檔，Claude Code 會執行該可執行檔
• 沙箱網路和隔離設定：沙箱設定，讓沙箱 Proxy 讀取、重新路由或驗證流量，或削弱沙箱的隔離：sandbox.network.tlsTerminate、sandbox.network.httpProxyPort、sandbox.network.socksProxyPort、sandbox.credentials、sandbox.allowAppleEvents、sandbox.enableWeakerNestedSandbox、sandbox.enableWeakerNetworkIsolation、sandbox.filesystem.disabled、sandbox.network.allowAllUnixSockets、sandbox.network.allowUnixSockets 和 sandbox.network.allowMachLookup。僅包含 deny 規則的 sandbox.credentials 區塊不需要核准，因為它會限制沙箱，而不會給 Proxy 認證。在 v2.1.251 之前，Claude Code 會在沒有核准的情況下套用這些設定
• 自訂環境變數：傳遞的 env 變數，需要使用者核准，例如 Proxy 和基底 URL 變數；請參閱環境變數和核准對話方塊
• Hook 設定：任何 hook 定義

​

核准記憶

• 由 /login 或 claude auth login 儲存的 claude.ai 登入，或無金鑰主控台登入：每個組織一次核准，由最近核准的帳戶持有。
• Claude 應用程式閘道登入：每個閘道一次核准。 如果您登出並重新登入同一個閘道，Claude Code 在需要核准的設定保持不變時不會再次顯示對話方塊。當這些設定變更、您登入不同的閘道，以及當您接受同一閘道的新憑證時，Claude Code 會再次顯示它。 Claude Code 不會為透過純 HTTP 到達的迴圈開發閘道儲存任何核准，因此對話方塊會在每次登入後再次出現。
• 任何其他認證，例如 API 金鑰或 CLAUDE_CODE_OAUTH_TOKEN：一次核准傳遞的設定，與該設定目錄中設定的快取副本一起保留。當需要核准的設定變更，以及在您執行 /logout 或 claude auth logout 後（其中任何一個都會刪除快取副本），Claude Code 會再次顯示對話方塊。

• 如果您登出並重新登入，或切換到另一個組織，稍後返回，Claude Code 在這些設定保持不變時不會再次顯示對話方塊，除非另一個帳戶在同一設定目錄中為該組織核准了它們。
• 如果您使用不同的帳戶登入同一個組織，Claude Code 即使設定保持不變也會再次顯示對話方塊。該帳戶的核准會取代前一個，因此當您切換回去時，Claude Code 會再次顯示對話方塊。

• 無法顯示對話方塊的互動工作階段：Claude Code 不會套用傳遞的設定，並保留最後核准的設定。對話方塊會在下一個可以顯示它的工作階段中出現。需要 Claude Code v2.1.211 或更新版本。
• claude install 或 claude update：Claude Code 在任何命令期間都不會顯示對話方塊。該命令會使用最後核准的設定執行，對話方塊會在您的下一個互動工作階段中出現。如果 Claude Code 在啟動時等待設定擷取，例如設定 forceRemoteSettingsRefresh 或在 Claude 應用程式閘道部署上，它會改為在命令期間顯示對話方塊，並且從管道執行的安裝執行會失敗；請參閱安裝期間的 Raw mode is not supported。在 v2.1.246 之前，Claude Code 也嘗試在這些命令期間顯示對話方塊。
• 錯誤在您回答前關閉對話方塊：Claude Code 不會套用傳遞的設定，並保留最後核准的設定。它會在下一個可以顯示它的工作階段中再次顯示對話方塊。
• 非互動執行，例如 claude -p 或 Agent SDK 工作階段：Claude Code 無法顯示對話方塊，因此當傳遞的設定需要核准時，它僅針對該執行套用它們。它不會將它們記錄為已核准或寫入本機快取，下一個互動工作階段會顯示對話方塊。在使用者在互動工作階段中核准之前，每個非互動執行都會在啟動時再次擷取設定。在 v2.1.207 之前，非互動執行會將設定儲存為已核准，因此後來的互動工作階段永遠不會為它們顯示對話方塊。

​

環境變數和核准對話方塊

• 功能和命令切換
• 模型選擇和行為設定，例如 ANTHROPIC_MODEL、DISABLE_PROMPT_CACHING 和 CLAUDE_CODE_EFFORT_LEVEL
• 內容視窗和壓縮設定，例如 DISABLE_AUTO_COMPACT
• 終端 UI 和協助工具選項
• 數值限制、預算和逾時

​

平台可用性

• Team 或 Enterprise OAuth 登入
• 透過 CLAUDE_CODE_OAUTH_TOKEN 提供的 OAuth 權杖
• 直接配置的 API 金鑰
• 一個 user_oauth Anthropic 設定檔，除非設定檔設定了 base_url 不同於 Anthropic API。需要 Claude Code v2.1.257 或更新版本。

​

稽核記錄

​

安全考量

​

另請參閱

• 所有設定：每個設定鍵
• Endpoint-managed settings：由 IT 部門部署到裝置的受管設定
• Authentication：設定使用者對 Claude Code 的存取
• Security：安全保護措施和最佳實踐