配置服务器管理的设置
通过 Claude.ai 上基于网络的界面为您的组织集中配置 Claude Code，无需设备管理基础设施。
服务器管理的设置允许组织所有者通过 claude.ai 控制台中的 Admin Settings > Claude Code > Managed settings 集中配置 Claude Code。Claude Code 客户端在用户使用组织 OAuth 登录或直接配置的 API 密钥进行身份验证时自动获取这些设置，在支持服务器管理交付的平台上。请参阅平台可用性。
这种方法专为没有设备管理基础设施的组织或需要为非托管设备上的用户管理设置的组织而设计。
要求
要使用服务器管理的设置，您需要：
- Claude for Teams 或 Claude for Enterprise 计划
- 您的 Claude 组织中的所有者或主要所有者角色，以查看和编辑配置
- Claude for Teams 的 Claude Code 版本 2.1.38 或更高版本，或 Claude for Enterprise 的版本 2.1.30 或更高版本
- 对
api.anthropic.com的网络访问
在服务器管理和端点管理的设置之间选择
Claude Code 支持两种集中配置方法。服务器管理的设置从 Anthropic 的服务器传递配置。端点管理的设置通过本机操作系统策略（macOS 托管首选项、Windows 注册表）或托管设置文件直接部署到设备。
| 方法 | 最适合 | 安全模型 |
|---|---|---|
| 服务器管理的设置 | 没有 MDM 的组织，或非托管设备上的用户 | 在身份验证时从 Anthropic 的服务器传递的设置 |
| 端点管理的设置 | 具有 MDM 或端点管理的组织 | 通过 MDM 配置文件、注册表策略或托管设置文件部署到设备的设置 |
如果您的设备已在 MDM 或端点管理解决方案中注册，端点管理的设置提供更强的安全保证，因为设置文件可以在操作系统级别受到保护，防止用户修改。端点管理的设置不会到达云会话，因此在网络上使用 Claude Code 的组织也应该配置服务器管理的设置。
配置服务器管理的设置
打开管理控制台
在 claude.ai 控制台中，转到 Admin Settings > Claude Code > Managed settings。
如果链接将您重定向到不同的 Admin Settings 页面而不是 Claude Code 页面，您的账户没有所需的角色。Admin 和其他非 Owner 角色无法查看或编辑托管设置，因此请要求您的组织中的 Owner 或 Primary Owner 进行更改。请参阅访问控制。
定义您的设置
将您的配置添加为 JSON。支持 settings.json 中可用的所有设置，除了限制于操作系统级别策略传递的设置外；有关该简短列表，请参阅当前限制。这包括 hooks、环境变量 和仅限托管的设置，如 allowManagedPermissionRulesOnly。
此示例强制执行权限拒绝列表，防止用户绕过权限，并将权限规则限制为在托管设置中定义的规则：
{
"permissions": {
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"disableBypassPermissionsMode": "disable"
},
"allowManagedPermissionRulesOnly": true
}
Hooks 使用与 settings.json 中相同的格式。
此示例在整个组织中每次文件编辑后运行审计脚本：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
]
}
]
}
}
要配置 auto mode 分类器，使其了解您的组织信任的存储库、存储桶和域：
{
"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"
]
}
}
由于 hooks 执行 shell 命令，用户在应用前会看到安全批准对话框。有关 autoMode 条目如何影响分类器阻止的内容以及关于 environment、allow、soft_deny 和 hard_deny 字段的重要警告，请参阅配置 auto mode。
保存并部署
保存您的更改。Claude Code 客户端在下次启动或每小时轮询周期时接收更新的设置。
验证设置传递
要确认设置正在被应用，请要求用户重新启动 Claude Code。如果配置包含触发安全批准对话框的设置，用户会在启动时看到描述托管设置的提示。您还可以通过让用户运行 /permissions 来验证托管权限规则是否处于活动状态，以查看其有效的权限规则。
访问控制
以下角色可以管理服务器管理的设置：
- 主要所有者
- 所有者
限制对受信任人员的访问，因为设置更改适用于组织中的所有用户。
仅限托管的设置
大多数设置键可在任何范围内工作。少数几个键仅从托管设置中读取，当放置在用户或项目设置文件中时无效。有关完整列表，请参阅仅限托管的设置。任何不在该列表上的设置仍然可以放置在托管设置中，并具有最高优先级。
当前限制
服务器管理的设置有以下限制：
- 设置统一应用于组织中的所有用户。尚不支持按组配置。
managed-mcp.json文件无法通过服务器管理的设置分发。改为在那里传递allowedMcpServers和deniedMcpServers策略键。- 限制于操作系统级别策略源的设置，如
policyHelper和wslInheritsWindowsSettings，不被遵守。改为通过 MDM 或系统managed-settings.json文件部署它们。
设置传递
设置优先级
服务器管理的设置和端点管理的设置都占据 Claude Code 设置层次结构中的最高层。没有其他设置级别可以覆盖它们，包括命令行参数。
在托管层内，配置的 policyHelper 优先于所有其他托管源，包括服务器管理的设置：其输出成为该运行的唯一托管配置。否则，首先传递非空配置的源获胜。首先检查服务器管理的设置，然后检查端点管理的设置。源不合并：如果服务器管理的设置传递任何键，其他端点管理的设置将被完全忽略。有一个例外适用：当任何管理员控制的托管源设置一小组跨源锁定键（例如沙箱允许列表锁）时，这些键会被遵守；用户可写的 HKCU 注册表层被排除。如果服务器管理的设置不传递任何内容，端点管理的设置将应用。
如果您清除管理控制台中的服务器管理配置，意图回退到端点管理的 plist 或注册表策略，请注意缓存的设置在客户端机器上持久化，直到下次成功获取。运行 /status 查看哪个托管源处于活动状态。
获取和缓存行为
Claude Code 在启动时从 Anthropic 的服务器获取设置，并在活动会话期间每小时轮询一次更新。
首次启动而无缓存的设置：
- Claude Code 异步获取设置
- 如果获取失败，Claude Code 继续运行而不使用托管设置
- 在设置加载之前有一个简短的窗口，其中限制尚未被强制执行
后续启动且有缓存的设置：
- 缓存的设置在启动时立即应用
- Claude Code 在后台获取新鲜设置
- 缓存的设置通过网络故障持久化
Claude Code 自动应用设置更新而无需重新启动，除了高级设置（如 OpenTelemetry 配置）需要完全重新启动才能生效。
已传递设置中的无效条目
已传递的有效负载使用与其他托管源相同的规则进行容错解析。当有效负载包含未通过架构验证的条目时，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）不受此检查的限制，因此当过期的凭证是设置获取失败的原因时，用户可以重新身份验证。
安全批准对话框
某些可能带来安全风险的设置在应用前需要明确的用户批准：
- Shell 命令设置：执行 shell 命令的设置
- 自定义环境变量：不在已知安全允许列表中的变量
- Hook 配置：任何 hook 定义
- 托管 CLAUDE.md 内容：通过托管设置传递的
claudeMd值
当这些设置存在时，用户会看到一个安全对话框，解释正在配置的内容。用户必须批准才能继续。如果用户拒绝设置，Claude Code 会退出。
平台可用性
服务器管理的设置需要直接连接到 api.anthropic.com，并且交付需要会话使用组织 OAuth 登录或直接配置的 API 密钥进行身份验证：由 apiKeyHelper 脚本返回的密钥不会触发设置获取。在使用第三方模型提供商时，服务器管理的设置不可用：
- Amazon Bedrock
- Google Vertex AI
- Microsoft Foundry
- Claude Platform on AWS
- 通过
ANTHROPIC_BASE_URL或第三方 LLM gateways 的自定义 API 端点
对于 Bedrock、Vertex AI 和 Foundry 部署，自托管的 Claude apps gateway 提供等效的远程管理设置交付：网关登录的客户端从网关而不是 api.anthropic.com 获取管理设置。启动时的失败语义不同：无法到达网关的网关客户端以错误退出，而不是回退到缓存的设置，而每小时的后台刷新在两个通道上都是故障开放的。
审计日志
设置更改的审计日志事件可通过合规 API 或审计日志导出获得。请联系您的 Anthropic 账户团队以获取访问权限。
审计事件包括执行的操作类型、执行操作的账户和设备，以及对先前值和新值的引用。
安全考虑
服务器管理的设置提供集中的策略强制执行，但它们作为客户端控制运行，而不是安全边界。在非托管设备上，用户不需要管理员或 sudo 访问权限来绕过它们。
| 场景 | 行为 |
|---|---|
| 用户编辑缓存的设置文件 | 篡改的文件在启动时应用，但正确的设置在下次服务器获取时恢复 |
| 用户删除缓存的设置文件 | 首次启动行为发生：设置异步获取，有一个简短的未强制执行的窗口 |
| 用户运行修改的 Claude Code 二进制文件 | 能够运行修改的客户端的用户可以绕过任何客户端控制 |
| 用户运行较旧的 Claude Code 版本 | 早于服务器管理设置的版本不会获取或应用它们 |
| API 不可用 | 如果可用，缓存的设置应用，否则托管设置在下次成功获取前不被强制执行。使用 forceRemoteSettingsRefresh: true 时，CLI 退出而不是继续，除了 claude auth 子命令 |
| 用户使用不同的组织进行身份验证 | 不为托管组织外的账户传递设置 |
| 用户配置第三方模型提供商 | 服务器管理的设置被绕过。这包括设置 CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_MANTLE、CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_FOUNDRY、CLAUDE_CODE_USE_ANTHROPIC_AWS 或非默认的 ANTHROPIC_BASE_URL |
| 网络流量被拦截或重定向 | 禁用的 TLS 验证或拦截的流量可以改变客户端接收的设置 |
要检测运行时配置更改，请使用 ConfigChange hooks 来记录修改或在未授权的更改生效前阻止它们。
要限制用户可以使用客户端提供的凭证访问的组织，请参阅 Claude 帮助中心中的使用租户限制强制执行网络级访问控制。为了获得更强的强制执行保证，请在已在 MDM 解决方案中注册的设备上使用端点管理的设置。
另请参阅
用于管理 Claude Code 配置的相关页面：
- Settings：完整的配置参考，包括所有可用的设置
- Endpoint-managed settings：由 IT 部门部署到设备的托管设置
- Authentication：设置用户对 Claude Code 的访问
- Security：安全保障和最佳实践