# Claude Code 企业控制面与受管配置

> Claude Code: server-managed settings、endpoint-managed settings、managed MCP、Auto mode、analytics、合规和 GitHub Enterprise Server 的企业落地清单。

URL: https://docs.passion8.cc/docs/claude-code/enterprise-controls
Language: zh-CN
Publisher: Passion8

企业部署 Claude Code 时,真正要落地的是一套控制面:谁能用、走哪个 Provider、能访问哪些 MCP、Auto mode 信任哪些基础设施、如何看用量、哪些合规边界不能被本地用户覆盖。

如果你只需要代理、CA、mTLS 和网络 allowlist,先看 [企业网络与集中管控](https://docs.passion8.cc/docs/claude-code/enterprise-admin)。本页聚焦组织级策略和 rollout 后的治理。




通过 `ANTHROPIC_BASE_URL=https://passion8.cc` 接入时,官方 claude.ai 的 server-managed settings 不一定能覆盖你的模型请求路径。关键策略要放在 endpoint-managed settings、MDM、系统配置文件、网关策略或 Passion8 管控面里。




## 控制面地图

| 控制点 | 官方能力 | Passion8/第三方网关下的落地方式 |
| --- | --- | --- |
| Provider 与凭据 | server-managed settings、Claude apps gateway、云 Provider 变量 | endpoint-managed settings、`~/.claude/settings.json` 模板、网关侧密钥 |
| 权限模式 | `permissions`、managed-only settings、Auto mode | 本地/托管 settings 加网关审计 |
| MCP 准入 | `managed-mcp.json`、`allowedMcpServers`、`deniedMcpServers` | 系统文件、MDM、插件市场白名单 |
| 插件分发 | managed plugin marketplace、`enabledPlugins` | 内部 marketplace、受管 settings、仓库 `.claude/settings.json` |
| 用量分析 | Claude Code analytics、OTel | Passion8 用量、网关日志、OTel collector |
| 合规 | ZDR、商业条款、BAA、Trust Center | 以你实际 Provider 和网关日志策略为准 |

## Server-managed 与 endpoint-managed

| 方案 | 适合 | 注意事项 |
| --- | --- | --- |
| Server-managed settings | Claude Team/Enterprise,无 MDM 或未管设备 | 从 Anthropic 服务端拉取,需要 `api.anthropic.com` 可达 |
| Endpoint-managed settings | 有 MDM、Intune、Jamf、GPO、Linux fleet 管理 | 由 OS 或设备管理下发,普通用户更难绕过 |
| 本地模板 | 小团队或 Passion8 快速接入 | 易复制,但不能当强管控边界 |
| 网关策略 | 统一 Provider、审计、预算、模型路由 | 需要确保 headers/body/cache 字段透传正确 |

受管 settings 处于 settings 优先级最高层。server-managed 与 endpoint-managed 不会做深度 merge:通常是谁先提供非空配置,谁就成为本次 managed 来源。调试时用 `/status` 看当前 managed source。

## Server-managed settings 运维点

官方 server-managed settings 从 claude.ai 管理后台配置,客户端启动时拉取,会话中定期轮询。

| 项目 | 说明 |
| --- | --- |
| 权限角色 | 只有 Primary Owner 或 Owner 能管理 |
| 客户端版本 | 需要满足官方要求的 Claude Code 版本 |
| 拉取失败 | 首次无缓存时继续无受管配置运行,除非启用强制刷新 |
| 有缓存启动 | 缓存先应用,再后台刷新 |
| 轮询 | 活跃会话会定期获取更新 |
| 高风险配置 | hooks、托管环境变量、托管指令可能触发安全确认 |

强制要求刷新成功后才能进入会话:

```json
{
  "forceRemoteSettingsRefresh": true
}
```

这个开关适合强管控环境,但要先验证所有客户端都能访问官方 settings 服务。否则用户会直接卡在启动阶段。

## 安全 settings 模板

禁止绕过权限,只允许托管规则生效:

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

给 Auto mode 提供组织边界:

```json
{
  "autoMode": {
    "environment": [
      "$defaults",
      "Organization: acme-corp. Primary use: software development and internal automation",
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted internal domains: *.corp.example.com, api.internal.example.com",
      "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
      "Sensitive remote targets: prod Kubernetes namespaces and production databases"
    ]
  }
}
```

`"$defaults"` 很关键。省略它会替换官方默认规则,可能把 force push、`curl | bash`、生产部署等默认保护拿掉。

## Auto mode 策略

完整配置参考和 denial 复盘流程见 [Auto mode 策略参考](https://docs.passion8.cc/docs/claude-code/auto-mode-policy)。本节只放企业控制面中最关键的边界。

Auto mode 不是简单的 allowlist。它会在权限系统之后再通过 classifier 判断操作是否可自动执行。

| 字段 | 含义 | 风险 |
| --- | --- | --- |
| `environment` | 描述组织、源码、域名、bucket、敏感范围 | 写得太泛会扩大信任边界 |
| `allow` | 对软阻断规则的例外 | 可放行 routine staging 操作 |
| `soft_deny` | 用户明确意图可覆盖的阻断 | 适合需要二次确认的破坏性操作 |
| `hard_deny` | 无条件阻断 | 适合禁止外发源码、修改生产等硬边界 |
| `classifyAllShell` | 所有 shell 命令都进 classifier | 更稳但可能增加摩擦 |

如果某个动作必须永远禁止,用 `permissions.deny`。不要只依赖 Auto mode classifier。

## Managed MCP

默认用户可以自行添加 MCP server。企业环境至少要明确 MCP 策略。

| 模式 | 效果 | 适合 |
| --- | --- | --- |
| 禁用 MCP | 不加载任何 MCP server | 高监管环境、先封后放 |
| 固定部署 | 所有人只加载同一批 server | 内部 GitHub、Sentry、DB 工具 |
| Approved catalog | 用户可从批准列表选择 | 工具多但要受控 |
| Plugin servers only | 只允许插件带来的 MCP | 配合受管插件市场 |
| Denylist | 只阻断已知危险 server | 成熟团队、低摩擦 |

`managed-mcp.json` 不能通过 server-managed settings 下发。常见路径:

| 平台 | 路径 |
| --- | --- |
| macOS | `/Library/Application Support/ClaudeCode/managed-mcp.json` |
| Linux 和 WSL | `/etc/claude-code/managed-mcp.json` |
| Windows | `C:\Program Files\ClaudeCode\managed-mcp.json` |

最小禁用 MCP:

```json
{
  "mcpServers": {}
}
```

固定部署示例:

```json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"]
    }
  }
}
```

不要在系统级 `managed-mcp.json` 里写明文 API Key。优先使用 OAuth、per-user headers、`${VAR}` 展开或 `headersHelper`。

## 插件和市场的组织约束

插件可以带 Skills、agents、hooks、MCP、LSP 和可执行文件。企业里要同时管安装来源和插件内容。

| 控制 | 推荐做法 |
| --- | --- |
| 官方插件 | 允许 `claude-plugins-official`,但记录安装范围 |
| 社区插件 | 默认审核后再允许 |
| 内部插件 | 用内部 marketplace 版本化分发 |
| 安全插件 | 可用 `enabledPlugins` 在项目或 managed settings 中启用 |
| 版本漂移 | 使用 marketplace 的版本字段或 dependency constraints |
| 插件建议 | 用 relevance 配置只向匹配目录推荐 |

插件分发细节见 [插件市场与分发](https://docs.passion8.cc/docs/claude-code/plugin-marketplaces)。

## Analytics 与 OTel

官方 analytics 可以用来衡量团队 adoption、贡献和使用趋势。Passion8 接入时,还需要从网关侧补齐请求、模型、成本和缓存字段。

| 指标 | 作用 |
| --- | --- |
| Active users | 看团队是否真正开始使用 |
| PR 或代码贡献 | 评估 Claude Code 对交付的影响 |
| Plan limits / usage breakdown | 找到缓存 miss、长上下文、MCP 或 subagent 造成的消耗 |
| OTel traces | 追踪工具调用、hooks、MCP、错误和延迟 |
| Gateway usage | 对账 Passion8 成本、模型路由和失败请求 |

建议至少保留这些维度:用户、团队、项目、Provider、模型、请求状态、`cache_creation_input_tokens`、`cache_read_input_tokens`、总成本、trace id。

## GitHub Enterprise Server

自托管 GitHub Enterprise Server 场景要额外确认:

| 项目 | 检查点 |
| --- | --- |
| Web/Code Review | 是否支持连接你的 GHES 域名 |
| 插件市场 | 是否走官方 GitHub 或内部源 |
| OAuth/App | 企业 GitHub App 权限是否覆盖目标 org/repo |
| 网络 | Claude Web/云端会话是否能访问 GHES |
| 审计 | PR review、session、commit attribution 是否能回写 |

如果 GHES 位于内网,通常要结合 Claude apps gateway、VPN、私有网络出口或只使用本地 CLI/IDE。

## 合规边界

| 主题 | 注意 |
| --- | --- |
| OAuth 与 API key | Claude.ai OAuth 面向订阅用户;产品集成和第三方服务应使用 API key 或云 Provider 凭据 |
| ZDR | 以实际 Provider 组织和请求路径为准,第三方网关需要单独确认日志策略 |
| BAA | 官方 BAA 覆盖取决于组织协议和 ZDR 状态 |
| 本地 transcript | 即使 Provider ZDR,本机仍可能保存会话与文件变更记录 |
| WebFetch / MCP | 外部连接器和网页读取可能形成额外数据出口 |

## 上线验收

| 验收项 | 通过标准 |
| --- | --- |
| Provider | `claude -p "ping"` 走预期 Base URL,Passion8 有用量记录 |
| Settings | `/status` 显示预期 managed source,`/permissions` 显示托管规则 |
| Auto mode | 常规内部操作能自动执行,生产/外发/破坏性动作被阻断 |
| MCP | `claude mcp list` 只出现批准 server |
| 插件 | `/plugin` 只展示或推荐批准 marketplace |
| 监控 | OTel 和网关日志能按用户/项目关联 |
| 缓存 | 可看到 cache creation 与 cache read,并能解释 5m/1h TTL 策略 |

## 官方参考

- [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md)
- [Managed MCP](https://code.claude.com/docs/en/managed-mcp.md)
- [Auto mode configuration](https://code.claude.com/docs/en/auto-mode-config.md)
- [Analytics](https://code.claude.com/docs/en/analytics.md)
- [Legal and compliance](https://code.claude.com/docs/en/legal-and-compliance.md)
- [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server.md)