設定伺服器管理的設定

需求

• 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 略過了擷取，包含原因。請參閱平台可用性以了解略過擷取的提供者和設定

為群組提供不同的設定

• 屬於具有組態之群組的成員：其所屬群組中排名最高的組態
• 其他任何人，包括唯一具有組態的所屬群組已被刪除的成員：全體適用組態（如果您有設定）

存取控制

• 主要擁有者
• 擁有者

僅限受管的設定

目前的限制

• 在 Team 方案中，設定統一套用到組織中的所有使用者。群組組態需要 Enterprise 方案。
• 您無法透過伺服器管理的設定分發 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，以及 beta 追蹤變數 ENABLE_BETA_TRACING_DETAILED 和 BETA_TRACING_ENDPOINT，會以單元形式跟隨設定其中任一項的最高來源。傳遞 otelHeadersHelper 憑證鍵的來源也會佔據此單元，但只有在它是所選來源時才會套用這些變數：未被選取但傳遞了該鍵的來源不會提供其中任何變數，且仍會阻止較低來源補上這些變數。無論哪種情況，來自某個來源的匯出器端點都絕不會與來自另一個來源的憑證配對。
  • 與憑證配對的路由：將路由變數與僅限所選來源的憑證鍵（例如 apiKeyHelper 或 otelHeadersHelper）配對的來源，只有在贏得該位置時才會提供這些路由變數。
• allowedProviders：在電腦上設定的清單與伺服器受管清單，會依照其項目的範圍說明所述方式組合。需要 Claude Code v2.1.285 或更新版本
• 第一方登入鍵：forceLoginOrgUUID 以及 forceLoginMethod 的 "claudeai" 和 "console" 值。如果您也部署了 MDM 政策或受管設定檔，請在每個用戶端都執行 v2.1.299 或更新版本之前，同時在該處以及 claude.ai 的伺服器受管設定中設定這些鍵。關於之後應在何處設定這些鍵，以及套用哪個來源的值，請參閱哪個受管來源提供登入鍵。
• 閘道登入鍵：Claude Code 絕不會從伺服器受管設定讀取 forceLoginGatewayUrl、gatewayInternalNetworks 或 forceLoginMethod 的 "gateway" 值，因此在那裡設定的值既不會套用，也不會遮蔽在 MDM 政策或受管設定檔中設定的值。managedSourcesBehavior 項目說明了由電腦上的哪個管理來源提供這些值。

當電腦的 apiKeyHelper 未生效時

• 該檔案或政策啟用了雲端提供者，或任何來源設定了 Anthropic 以外的 API 位址
• 伺服器受管設定未設定 helper，也未指定 Anthropic 的 API 位址

擷取與快取行為

• 當開發人員在啟動時登入，例如首次執行或執行 /logout 之後，Claude Code 會在開啟工作階段之前等待擷取最多五秒。若政策及時送達，Claude Code 會從第一個畫面就強制執行該政策，並在該畫面上顯示您的 companyAnnouncements。若 payload 需要安全性核准，Claude Code 會結束等待，並在開發人員核准後套用該 payload
• 在任何其他啟動情況下，以及五秒等待逾時時，Claude Code 會在擷取持續進行的同時開啟工作階段，因此在設定載入且限制生效之前會有一段短暫的空窗期
• 如果擷取失敗，Claude Code 會在沒有伺服器受管設定的情況下繼續執行，並在互動式工作階段以及 Claude Desktop 的 Code 分頁中警告沒有套用任何遠端政策；端點受管設定仍會套用。如果受管來源設定了 forceRemoteSettingsRefresh，Claude Code 則會改為結束

• 快取的設定會在啟動時立即套用，但以下項目除外：快取的 modelPricing 和 managedMcpServers 值；Claude Code 在伺服器確認 payload 之前暫緩的環境變數；快取的外掛清單對內建防護所做的移除、重新定位或停用；以及在端點受管來源自行列出或啟用外掛的電腦上，僅由快取清單啟用之外掛的組織歸屬
• 快取的 modelPricing 在工作階段的擷取確認 payload 之前不會套用。在那之前，開發人員在 /usage 和狀態列中看到的費用數字皆為定價
• 快取的 managedMcpServers 區塊在工作階段的擷取確認 payload 之前不會套用。Claude Code 會在連線 MCP 伺服器之前等待該擷取最多 30 秒。如果擷取失敗或逾時，工作階段會在沒有組織伺服器的情況下啟動，/status 會註明此情況，而這些伺服器會在之後的擷取確認它們後連線。如需完整行為（包括首次啟動），請參閱提供的伺服器何時連線。需要 Claude Code v2.1.259 或更新版本
• 快取的 prependPlugins、appendPlugins 或 enabledPlugins 值，在工作階段的擷取確認 payload 之前，無法移除內建防護、變更其位置或將其關閉
• 在端點受管來源自行列出或啟用外掛的電腦上，僅由快取清單啟用的外掛在擷取確認 payload 之前，會被視為使用者的外掛，而非您組織的外掛
• Claude Code 會在背景擷取最新設定
• 如果工作階段的提供者不在快取的 allowedProviders 清單中，Claude Code 可以先等待該擷取完成並再次檢查，然後才拒絕。如果擷取失敗，該工作階段會被拒絕
• 快取的設定在網路故障期間會持續保留。如果啟動時的擷取失敗，Claude Code 會在互動式工作階段以及 Code 分頁中警告目前生效的是快取的政策
• 在擷取成功之前，啟動時暫緩的值會持續暫緩

• 代理伺服器與 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 或更新版本）：Workload Identity Federation 變數（例如 ANTHROPIC_FEDERATION_RULE_ID 和 ANTHROPIC_IDENTITY_TOKEN）、設定檔與設定目錄選擇器 ANTHROPIC_PROFILE 和 ANTHROPIC_CONFIG_DIR，以及作業系統目錄變數 HOME、XDG_CONFIG_HOME、APPDATA 和 USERPROFILE

• 透過 MDM 或 managed-settings.json 設定的端點受管 env 區塊。此來源需要 Claude Code v2.1.223 或更新版本。在 v2.1.223 之前，請使用 shell 環境或使用者設定，讓代理伺服器與快取的伺服器 payload 一起套用。
• shell 環境
• 使用者設定

傳遞設定中的無效項目

• 以 ~/.claude/remote-settings.json 快取執行的啟動，會以寫入該快取的擷取相同的方式處理無效項目：
  • 未通過驗證的項目會持續被捨棄。
  • 失敗即關閉的鍵會保留其較嚴格的值。
  • 無效的 cleanupPeriodDays 或 desktopSessionCleanupPeriodDays 值會保留在快取副本中，且永遠不會套用。
• 當以下三項條件全部成立時，Claude Code 不會套用 payload 中的任何內容，並保持快取不變：
  • payload 中的每個設定都未通過驗證。
  • 其中沒有任何設定回退至較嚴格的值。
  • payload 包含上述兩個保留期鍵以外的鍵。
  此時啟動通知、/status 和 claude doctor 會回報載入失敗，原因為 no setting in the server response could be applied as written，且該項目會說明工作階段執行時所依據的政策。強制失敗即關閉的啟動的用戶端則會改為在啟動時結束。如果啟動因訊息指出您的組織要求 before a session can start 取得其設定而停止，請參閱 Claude Code 無法載入您組織的設定。
• 安全性核准對話框會評估挽救後的 payload，因此被移除的無效項目永遠不會呈現供核准，也永遠不會執行。

強制失敗即關閉的啟動

• 如果閘道以 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 會執行該可執行檔
• 沙箱網路與隔離設定：讓沙箱代理伺服器能讀取、重新路由或驗證流量，或削弱沙箱隔離的沙箱設定：sandbox.network.tlsTerminate、sandbox.network.httpProxyPort、sandbox.network.socksProxyPort、sandbox.credentials、sandbox.allowAppleEvents、sandbox.allowNestedUserNamespaces、sandbox.enableWeakerNestedSandbox、sandbox.enableWeakerNetworkIsolation、sandbox.filesystem.disabled、sandbox.network.allowAllUnixSockets、sandbox.network.allowUnixSockets 和 sandbox.network.allowMachLookup。僅包含 deny 規則的 sandbox.credentials 區塊不需要核准，因為它只是限制沙箱，並未提供憑證給代理伺服器。在 v2.1.251 之前，Claude Code 會在未經核准的情況下套用這些設定
• 自訂環境變數：需要使用者核准的傳遞 env 變數，例如代理伺服器與 base-URL 變數；請參閱環境變數與核准對話框
• Hook 組態：任何 hook 定義

核准記憶

• 由 /login 或 claude auth login 儲存的 claude.ai 登入，或無金鑰 Console 登入：每個組織一個核准，由最近一次核准的帳戶持有。
• Claude apps 閘道登入：每個閘道一個核准。 如果您登出後再登入同一個閘道，只要需要核准的設定未變更，Claude Code 就不會再次顯示對話框。當這些設定變更、您登入不同的閘道，或您為同一個閘道接受新的憑證時，Claude Code 會再次顯示對話框。 對於透過純 HTTP 連線的本機迴路開發閘道，Claude Code 不會儲存核准，因此每次登入後都會再次出現對話框。
• 任何其他憑證，例如 API 金鑰或 CLAUDE_CODE_OAUTH_TOKEN：對傳遞的設定一個核准，與該設定目錄中的設定快取副本一起保存。當需要核准的設定變更時，以及在您執行 /logout 或 claude auth logout（兩者都會刪除快取副本）之後，Claude Code 會再次顯示對話框。

• 如果您登出後再登入，或切換到另一個組織後再返回，只要這些設定未變更，Claude Code 就不會再次顯示對話框，除非在此期間另一個帳戶已在同一個設定目錄中為該組織核准過這些設定。
• 如果您使用不同的帳戶登入同一個組織，即使設定未變更，Claude Code 也會再次顯示對話框。該帳戶的核准會取代先前的核准，因此當您切換回來時，Claude Code 會再顯示一次對話框。

• 無法顯示對話框的互動式工作階段：Claude Code 不會套用傳遞的設定，並保留上次核准的設定。對話框會出現在下一個能顯示它的工作階段中。
• claude install 或 claude update：Claude Code 在這兩個命令執行期間都不會顯示對話框。命令會以上次核准的設定執行，對話框則會出現在您的下一個互動式工作階段中。如果 Claude Code 在啟動時等待設定擷取，例如設定了 forceRemoteSettingsRefresh 或在 Claude apps 閘道部署上，它會改為在命令執行期間顯示對話框，而從管道執行的安裝會失敗；請參閱安裝期間出現 Raw mode is not supported。在 v2.1.246 之前，Claude Code 也會嘗試在這兩個命令執行期間顯示對話框。
• 輸出至終端機但無法從鍵盤讀取的 claude plugin 命令：當 Claude Code 未在啟動時等待設定擷取時，該命令不會套用傳遞的設定。若沒有快取的設定，變更您的外掛或市集的命令會以錯誤停止。若有快取的設定，命令會以上次核准的設定執行。對話框會在您下次於終端機中執行 claude 時出現。 當您以管道傳送或重新導向該命令的輸入，且在 macOS 和 Linux 上它也無法開啟 /dev/tty 時，該命令就無法從鍵盤讀取。如果您也以管道傳送或重新導向其輸出，該次執行則會改為非互動式，而傳遞的設定只會在該次執行中套用。
• 錯誤在您回答之前關閉了對話框：Claude Code 不會套用傳遞的設定，並保留上次核准的設定。它會在下一個能顯示對話框的工作階段中再次顯示。
• 非互動式執行，例如 claude -p、Agent SDK 工作階段，或 VS Code 擴充功能聊天面板或桌面應用程式 Code 分頁中的工作階段：Claude Code 無法顯示對話框。當傳遞的設定需要核准時，這些設定只會在該次執行中套用。 Claude Code 不會將這些設定記錄為已核准，也不會將其寫入本機快取，而下一個互動式工作階段會顯示對話框。在使用者於互動式工作階段中核准之前，每次非互動式執行都會在啟動時再次擷取設定。

環境變數與核准對話框

• 功能與命令切換
• 模型選擇與行為設定，例如 ANTHROPIC_MODEL、DISABLE_PROMPT_CACHING 和 CLAUDE_CODE_EFFORT_LEVEL
• 上下文視窗與壓縮設定，例如 DISABLE_AUTO_COMPACT，但不包括 CLAUDE_CODE_DISABLE_1M_CONTEXT
• 終端機 UI 與無障礙選項
• 數值限制、預算與逾時

• 代理伺服器或 base-URL 變數
• OTEL_EXPORTER_OTLP_ENDPOINT
• CLAUDE_CODE_DISABLE_1M_CONTEXT

平台可用性

• Team 或 Enterprise OAuth 登入
• 透過 CLAUDE_CODE_OAUTH_TOKEN 提供的 OAuth token
• 直接設定的 API 金鑰
• user_oauth Anthropic 設定檔，除非該設定檔將 base_url 設為 Anthropic API 以外的位址。需要 Claude Code v2.1.257 或更新版本。

• OAuth token：使用 claude setup-token 產生 token，為您的 Team 或 Enterprise 組織授權該 token，並在作業的環境中將其設為 CLAUDE_CODE_OAUTH_TOKEN。從該環境中移除任何優先於該 token 的憑證，例如 ANTHROPIC_API_KEY。
• 端點受管設定：將受管設定檔部署至執行該作業的機器。

稽核記錄

安全性考量

另請參閱

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