配置服务器托管设置

通过服务器下发的设置集中配置组织内的 Claude Code，无需设备管理基础设施。

通过服务器托管设置，组织的 Owner 可以在 claude.ai 控制台的 Admin Settings > Claude Code > Managed settings 中集中配置 Claude Code。在支持服务器托管下发的平台上，当用户通过组织 OAuth 登录或直接配置的 API 密钥进行身份验证时，Claude Code 客户端会自动获取这些设置。请参阅平台可用性。

此方式适合尚未部署设备管理基础设施，或需要管理非托管设备上用户设置的组织。

要求

使用服务器托管设置需要满足以下条件：

• 使用 Claude for Teams 或 Claude for Enterprise 方案
• 在 Claude 组织中拥有 Owner 或 Primary Owner 角色，以便查看和编辑配置
• Claude for Teams 需要 Claude Code 2.1.38 或更高版本，Claude for Enterprise 需要 2.1.30 或更高版本
• 能够通过网络访问 api.anthropic.com

在服务器托管设置与端点托管设置之间选择

Claude Code 支持两种集中配置方式。服务器托管设置由 Anthropic 的服务器下发配置。端点托管设置则通过操作系统原生策略（macOS 托管偏好设置、Windows 注册表）或托管设置文件直接部署到设备。

如果设备已加入 MDM 或端点管理解决方案，端点托管设置能提供更强的安全保证，因为操作系统可以保护设置文件不被用户修改。端点托管设置不会下发到云端会话，因此在 Web 上使用 Claude Code 的组织还应配置服务器托管设置。

配置服务器托管设置

{
  "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" }
        ]
      }
    ]
  }
}

{
  "autoMode": {
    "environment": [
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
      "Trusted internal domains: *.corp.example.com"
    ]
  }
}

验证设置下发

要确认设置已生效，请让一位用户重启 Claude Code。如果配置中包含会触发安全审批对话框的设置，用户会在启动时看到说明这些托管设置的提示。也可以让用户运行 /permissions 查看实际生效的权限规则，以验证托管权限规则是否启用。

访问控制

以下角色可以管理服务器托管设置：

• Primary Owner
• Owner

设置更改会应用于组织中的所有用户，因此请仅向可信人员授予访问权限。

仅限托管设置的配置项

大多数设置键在任何作用域中均可使用。少数键只会从托管设置中读取，放在用户或项目设置文件中不会生效。完整列表请参阅仅限托管设置的配置项。不在该列表中的设置仍可放入托管设置，并获得最高优先级。

当前限制

服务器托管设置存在以下限制：

• 设置统一应用于组织中的所有用户。目前尚不支持按组配置。
• 无法通过服务器托管设置分发 managed-mcp.json 文件。请改为通过服务器托管设置下发 allowedMcpServers 和 deniedMcpServers 策略键。
• policyHelper 和 wslInheritsWindowsSettings 等仅限操作系统级策略来源的设置不会生效。请改为通过 MDM 或系统级 managed-settings.json 文件部署。

设置下发

设置优先级

服务器托管设置和端点托管设置都位于 Claude Code 设置层级的最高层。包括命令行参数在内，其他设置层级都无法覆盖它们。

在托管层级内，如果配置了 policyHelper，它会优先于包括服务器托管设置在内的所有其他托管来源：其输出将成为本次运行唯一的托管配置。

否则，Claude Code 使用第一个下发非空配置的来源。它会先检查服务器托管设置，再检查端点托管设置。不同来源不会合并：只要服务器托管设置下发了任何键，其他端点托管设置就会被忽略。如果服务器托管设置未下发任何内容，则应用端点托管设置。

有一项例外：只要任一由管理员控制的托管来源设置了少量跨来源锁定键（例如沙箱允许列表锁），这些键就会生效；用户可写的 HKCU 注册表层级不在此范围内。

如果您在管理控制台中清空服务器托管配置，以便回退到端点托管的 plist 或注册表策略，请注意，缓存设置会一直保留在客户端计算机上，直到下次成功获取设置。运行 /status 可查看当前使用的托管来源。

获取与缓存行为

Claude Code 会在启动时从 Anthropic 的服务器获取设置，并在活跃会话期间每小时轮询更新。

首次启动且没有缓存设置时：

• Claude Code 异步获取设置
• 如果获取失败，Claude Code 会在不应用托管设置的情况下继续运行
• 设置加载前会存在一个短暂窗口，其间限制尚未生效

后续启动且已有缓存设置时：

• 缓存设置会在启动时立即生效，但下文所述的传输、路由和身份验证环境变量除外
• Claude Code 在后台获取最新设置
• 即使发生网络故障，缓存设置仍会保留。暂缓应用的环境变量会继续保持暂缓状态，直到成功获取设置

从 v2.1.198 开始，在服务器确认本次会话的负载之前，Claude Code 会暂缓应用缓存 env 块中的三类变量。这样可以防止缓存的代理、证书颁发机构、端点或凭据值重定向、拦截设置获取请求，或改变该请求的身份验证方式；该请求正是用来确认负载的。此加固措施仅适用于从服务器获取的设置缓存；通过 MDM 或 managed-settings.json 部署的端点托管设置不受影响。暂缓应用的类别包括：

• 代理和 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 等提供商选择变量，以及 ANTHROPIC_BEDROCK_BASE_URL 等提供商端点 URL
• 身份验证凭据，例如 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 CLAUDE_CODE_OAUTH_TOKEN

缓存 env 块中的其他所有键（例如遥测和 OpenTelemetry 配置）仍会像以往一样在启动时生效。成功获取设置后，暂缓的变量会在本次会话剩余时间内生效。

如果组织需要通过代理访问 api.anthropic.com，请在 shell 环境或用户设置中配置代理，而不要只在托管 env 块中设置。首次启动时没有缓存，因此最初获取设置本来就需要从这些来源配置代理。

Claude Code 会自动应用设置更新，无需重启；但 OpenTelemetry 配置等高级设置除外，它们需要完全重启才能生效。

下发设置中的无效条目

下发的负载采用宽容解析，规则与其他托管来源相同。如果负载中的某个条目未通过 schema 验证，Claude Code 会移除该条目、显示验证错误，并应用其余所有有效设置。有关字段级行为（包括如何处理安全强制字段），请参阅托管设置中的无效条目。此功能要求 Claude Code v2.1.169 或更高版本。

服务器托管下发还具有以下行为：

• ~/.claude/remote-settings.json 中的缓存只存储移除无效条目后的负载。原始无效负载从不持久保存。
• 如果负载中的字段均无法保留，Claude Code 会继续使用上次接受的缓存设置，并记录致命错误。
• 安全审批对话框只评估移除无效条目后的负载，因此被移除的无效条目既不会提交审批，也绝不会执行。

要调试下发问题，请运行 claude --debug-file <path>，并在日志中搜索 Remote settings。向整个组织推广负载更改前，请先在测试计算机上使用 claude doctor 验证。

强制启动时采用故障关闭策略

默认情况下，如果启动时无法获取远程设置，CLI 会在不应用托管设置的情况下继续运行。对于不能接受这段短暂无策略生效窗口的环境，请在托管设置中设置 forceRemoteSettingsRefresh: true。

启用此设置后，CLI 会在启动时阻塞，直到重新获取到远程设置。如果获取失败，CLI 会退出，而不会在缺少策略的情况下继续运行。此设置具有延续性：一旦由服务器下发，它也会缓存在本地，因此后续启动时，即使新会话尚未首次成功获取设置，也会强制执行相同行为。

要启用此功能，请将该键添加到托管设置配置：

{
  "forceRemoteSettingsRefresh": true
}

您也可以在端点托管的 MDM 配置文件或系统级 managed-settings.json 文件中设置此键，以便在首次启动、尚未收到任何服务器负载之前就强制采用故障关闭。从 v2.1.191 开始，此标志是上述优先级规则的例外：只要任一托管来源设置了它，即使同时存在缓存的服务器托管负载也会生效，因此在已有服务器托管设置时，通过 MDM 下发的值不会被忽略。

设置获取请求还会发送 Cache-Control: no-cache 标头，防止中间 HTTP 代理返回过期响应。

启用此设置前，请确保网络策略允许连接 api.anthropic.com。如果无法访问该端点，CLI 会在启动时退出，用户将无法启动 Claude Code。

从 v2.1.139 开始，claude auth 子命令（例如 claude auth login）不受此检查限制，因此当设置获取失败是由凭据过期造成时，用户仍可重新进行身份验证。

安全审批对话框

某些可能带来安全风险的设置必须获得用户明确批准，Claude Code 才会应用：

• Shell 命令设置：会执行 shell 命令的设置
• 自定义环境变量：不在已知安全允许列表中的变量
• Hook 配置：任何 Hook 定义
• 托管的 CLAUDE.md 内容：通过托管设置下发的 claudeMd 值

存在这些设置时，用户会看到一则安全对话框，说明将要配置的内容。用户必须批准才能继续。如果用户拒绝这些设置，Claude Code 会退出。

平台可用性

服务器托管设置要求直接连接 api.anthropic.com，并且会话必须通过组织 OAuth 登录或直接配置的 API 密钥进行身份验证，才能下发设置。由 apiKeyHelper 脚本返回的密钥不会触发设置获取。

使用第三方模型提供商时，服务器托管设置不可用：

• Amazon Bedrock
• Google Cloud Agent Platform
• Microsoft Foundry
• Claude Platform on AWS
• 通过 ANTHROPIC_BASE_URL 使用的自定义 API 端点，或第三方 LLM 网关

对于 Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 部署，自托管的 Claude 应用网关可以提供等效的远程托管设置下发能力：通过网关登录的客户端从网关而不是 api.anthropic.com 获取托管设置。两者在启动时的失败语义不同：网关客户端无法访问网关时会报错退出，而不是回退到缓存设置；每小时一次的后台刷新则在两种下发渠道中都采用故障开放策略。

审计日志

可通过合规 API 或审计日志导出获取设置更改的审计日志事件。请联系 Anthropic 客户团队申请访问权限。

审计事件包括执行的操作类型、执行操作的账号和设备，以及对旧值和新值的引用。

安全注意事项

服务器托管设置可以集中执行策略，但它是一种客户端控制机制，而非安全边界。在非托管设备上，用户无需 admin 或 sudo 权限即可绕过这些设置。

要检测运行时配置变更，请使用 ConfigChange Hook记录修改，或在未经授权的更改生效前将其阻止。

要限制用户可使用客户端提供的凭据访问哪些组织，请参阅 Claude Help Center 中的使用 Tenant Restrictions 强制实施网络级访问控制。如需更有力的强制执行保证，请在已加入 MDM 解决方案的设备上使用端点托管设置。

另请参阅

管理 Claude Code 配置的相关页面：

• 设置：完整的配置参考，包括所有可用设置
• 端点托管设置：由 IT 部署到设备的托管设置
• 身份验证：设置 Claude Code 用户访问权限
• 安全：安全保障措施和最佳实践