Claude Code 深度学习手册

主题

服务端托管设置 ​

通过 Claude.ai 网页控制台集中下发配置，无需 MDM 设备管理。

是什么 ​

服务端托管设置（Server-managed settings）让管理员通过 Claude.ai 上的网页界面集中配置 Claude Code。当用户用组织凭证认证时，Claude Code 客户端会自动接收这些设置。

它面向没有设备管理（MDM）基础设施、或需要为非托管设备上的用户管理配置的组织。仅对 Claude for Teams 和 Claude for Enterprise 客户开放。

怎么工作 ​

  • 管理员在 Claude.ai 的 Admin Settings > Claude Code > Managed settings 中以 JSON 形式定义配置。
  • 支持 settings.json 中几乎所有设置（含 hooks、环境变量、以及 allowManagedPermissionRulesOnly 等 managed-only 设置），仅排除限定 OS 级下发的少数键。
  • 保存后，客户端在下次启动或每小时轮询时接收更新；多数更新无需重启即生效（OpenTelemetry 等高级设置除外，需完整重启）。
  • 客户端在启动时拉取设置，会话活跃期间每小时轮询；首次无缓存时异步拉取，拉取失败则继续但短暂不强制；有缓存时立即生效并后台刷新，网络故障下缓存仍持续。
  • 涉及 shell 命令、非安全白名单的自定义环境变量、或任何 hook 配置时，用户启动时会看到安全审批对话框，须批准才应用，拒绝则 Claude Code 退出（-p 非交互模式跳过审批直接应用）。
  • 服务端托管设置与端点托管设置同处设置层级最高层，命令行参数也无法覆盖；二者不合并：服务端只要下发任意键，端点设置即被整体忽略，仅当服务端无内容时端点设置才生效。
  • 用 /status 查看当前生效的托管来源，用 /permissions 查看生效的权限规则。

怎么配置 / 用法 ​

权限拒绝列表 + 禁止绕过 + 仅允许托管权限规则：

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

每次文件编辑后运行审计脚本（hook）：

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

强制启动时拉取（fail-closed），拉取失败则 CLI 退出：

json
{ "forceRemoteSettingsRefresh": true }

什么时候用 ​

  • 组织没有 MDM 或端点管理基础设施。
  • 需要为非托管设备上的用户统一管理配置。
  • 希望对全组织集中强制权限策略、hooks、环境变量等。
  • 作为 Claude for Teams 或 Claude for Enterprise 客户需要中心化策略下发。

限制 / 坑 ​

  • 设置对组织内所有用户统一生效，暂不支持按用户组分别配置。
  • managed-mcp.json 无法通过服务端托管设置下发；应改用其中的 allowedMcpServers / deniedMcpServers 策略键。
  • 限定 OS 级来源的设置（如 policyHelper、wslInheritsWindowsSettings）不被采纳，须经 MDM 或系统级 managed-settings.json 部署。
  • 属于客户端侧控制；在非托管设备上具备 admin/sudo 权限的用户可篡改二进制、文件系统或网络配置。
  • 使用第三方模型提供方（Bedrock、Vertex AI、Microsoft Foundry、自定义 ANTHROPIC_BASE_URL/LLM 网关）时不可用，会被绕过。

硬事实速查（12 条） ​

  • 仅 Claude for Teams 与 Claude for Enterprise 可用。
  • 版本要求：Claude for Teams 需 Claude Code 2.1.38 或更高；Claude for Enterprise 需 2.1.30 或更高。
  • 需要能访问 api.anthropic.com 的网络。
  • 配置入口：Claude.ai 的 Admin Settings > Claude Code > Managed settings。
  • 仅 Primary Owner 和 Owner 两种角色可管理服务端托管设置。
  • 客户端启动时拉取设置，活跃会话每小时轮询一次更新。
  • 设置精度：服务端托管与端点托管同为最高层，命令行参数都无法覆盖；服务端优先检查，下发任意键即整体忽略端点设置，不合并。
  • forceRemoteSettingsRefresh: true 启用 fail-closed：启动时阻塞直到刷新成功，失败则 CLI 退出；该设置会本地缓存自我延续。
  • 自 v2.1.139 起，claude auth login 等 claude auth 子命令豁免 fail-closed 检查，便于过期凭证时重新认证。
  • -p 非交互模式下跳过安全审批对话框，直接应用设置。
  • 清空服务端配置后，客户端缓存设置仍持续到下次成功拉取；切换到其他组织认证时不下发该组织设置。
  • 运行时配置变更可用 ConfigChange hooks 记录或拦截；设置以 settings.json 相同的 JSON 格式编写。

官方出处：https://code.claude.com/docs/en/server-managed-settings