配置服务器管理的设置

​

要求

• 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 跳过了获取，包括原因。有关跳过它的提供商和配置，请参阅平台可用性

​

访问控制

• Primary Owner
• Owner

​

仅限托管的设置

​

当前限制

• 设置统一应用于组织中的所有用户。尚不支持按组配置。
• 您无法通过服务器管理的设置分发 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、gatewayInternalNetworks 或 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 在连接 MCP 服务器前最多等待 30 秒以获取。如果获取失败或超时，会话启动时不使用组织的服务器，/status 会说明这一点，它们在后续获取确认它们后连接。有关完整行为（包括首次启动），请参阅何时提供的服务器连接。需要 Claude Code v2.1.259 或更高版本
• Claude Code 在后台获取新鲜设置
• 缓存的设置通过网络故障持久化。如果启动获取失败，Claude 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 或更高版本中：工作负载身份联合变量（例如 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 不应用有效负载中的任何内容，并保持缓存不变：
  • 有效负载中的每个设置都未通过验证。
  • 它们都不回退到更严格的值。
  • 有效负载包含除这两个保留键之外的键。
  启动通知、/status 和 claude doctor 然后报告失败的加载，原因为 no setting in the server response could be applied as written，该条目说明会话运行的策略。强制执行故障关闭启动的客户端在启动时退出。
• 安全批准对话框评估已保存的有效负载，因此被删除的无效条目永远不会被呈现以供批准，也永远不会执行。

​

强制执行故障关闭启动

• 如果网关用 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.enableWeakerNestedSandbox、sandbox.enableWeakerNetworkIsolation、sandbox.filesystem.disabled、sandbox.network.allowAllUnixSockets、sandbox.network.allowUnixSockets 和 sandbox.network.allowMachLookup。仅包含 deny 规则的 sandbox.credentials 块不需要批准，因为它限制沙箱而不给代理凭证。在 v2.1.251 之前，Claude Code 应用这些设置而无需批准
• 自定义环境变量：传递的 env 变量，需要用户批准，例如代理和基础 URL 变量；请参阅环境变量和批准对话框
• Hook 配置：任何 hook 定义

​

批准记忆

• 通过 /login 或 claude auth login 保存的 claude.ai 登录，或无密钥控制台登录：每个组织一个批准，由最近批准的账户持有。
• Claude 应用网关登录：每个网关一个批准。 如果您登出并重新登录到同一网关，当需要批准的设置未更改时，Claude Code 不会再次显示对话框。当这些设置更改、您登录到不同的网关以及您为同一网关接受新证书时，Claude Code 会再次显示它。 Claude Code 不为通过纯 HTTP 到达的环回开发网关保存批准，因此对话框在每次登录后再次出现。
• 任何其他凭证，例如 API 密钥或 CLAUDE_CODE_OAUTH_TOKEN：一个批准用于传递的设置，与该配置目录中设置的缓存副本一起保留。当需要批准的设置更改时，Claude Code 会显示对话框，在您运行 /logout 或 claude auth logout 后，其中任何一个都会删除缓存副本。

• 如果您登出并重新登录，或切换到另一个组织，稍后返回，当这些设置未更改时，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 配置文件，除非该配置文件设置了 Anthropic API 以外的 base_url。需要 Claude Code v2.1.257 或更高版本。

​

审计日志

​

安全考虑

​

另请参阅

• 所有设置：每个设置键
• Endpoint-managed settings：由 IT 部门部署到设备的托管设置
• Authentication：设置用户对 Claude Code 的访问
• Security：安全保障和最佳实践