heicode/docs/reference/claude-code-enterprise-controls-zh.md

# Claude Code 企业管控体系（权限 · 分配 · 设置）阅读参考

> 整理自 Claude 官方文档（中文）：admin-setup / authentication / server-managed-settings / settings / managed-mcp / auto-mode-config / permissions / permission-modes / mcp / costs / monitoring-usage / analytics。
> 本文是**忠实还原 Claude 体系**的学习参考（不含任何二次设计），用于深读理解「Claude 如何做团队/企业的权限与分配」。
> 每条尽量标注来源：`[AS]`=admin-setup `[AU]`=authentication `[SM]`=server-managed-settings `[S]`=settings `[MCP]`=managed-mcp `[AM]`=auto-mode-config `[PM]`=permission-modes `[P]`=permissions `[M]`=mcp `[$]`=costs/usage/analytics。

---

## 导读：读完你应能回答

1. **三档**（个人/团队/企业）各能用哪些管控？ → §1
2. **客户端怎么登录、多凭证时实际用哪个？** → §2 + 附录B·流程D
3. **组织里有哪些角色、谁能改托管设置？** → §3
4. **6 种权限模式**（含 `auto`/`dontAsk`）分别什么含义、auto 怎么被管理员开关？ → §3.5–3.6
5. **设置有几层、谁压谁、数组怎么合并？** → §4
6. **管理员在控制台下发的策略，怎么到客户端并强制生效？** → §5 + 附录B·流程A
7. **能锁哪些键？权限规则 `Tool(specifier)` 到底怎么写？** → §6 + §6.8
8. **怎么集中管控 MCP、allow/deny 怎么判、凭据怎么处理？** → §7 + 附录B·流程B
9. **auto-mode 分类器怎么判一次操作（如 force push）？** → §8 + 附录B·流程C
10. **支出上限/速率/用量归属/看板在哪配？** → §9
11. **所有真实配置 JSON 长什么样？** → 附录A

> **建议阅读顺序**：§0 三层模型 → §1 三档 → §5 服务端托管（最核心机制）→ §4 优先级 → §3.5 权限模式 → §7/§8 MCP 与 auto-mode → 附录A 示例 + 附录B 流程对照着看 → §12 速查表收尾。

---

## 0. 全局心智模型：三层控制

Claude Code 的企业管控可拆成三层 + 两条贯穿能力：

| 层 | 机制 | 决定什么 |
|---|---|---|
| **身份与准入** | 提供商(provider) + 计划(plan) + 座位(seat) + 邀请/角色 + SSO/SCIM/域名捕获 | 谁能用、用哪个组织身份 |
| **策略下发** | server-managed-settings（控制台下发 JSON，最高优先级、不可本地覆盖） | 客户端能/不能做什么 |
| **能力供给** | managed-mcp + 插件/agent 下发 | 客户端有哪些工具/MCP/agent 可用 |
| 贯穿①**分配/计费** | 模型限制、支出上限、速率、用量归属 | 用多少、花多少 |
| 贯穿②**审计/合规** | Compliance API、审计日志、ZDR | 留痕与数据留存 |

---

## 1. 提供商与计划（根选择）

### 1.1 API 提供商（决定计费 + 认证 + 合规 + 可用功能）[AS]
- **Claude for Teams / Enterprise**（默认推荐，按座位订阅，claude.ai 与 Claude Code 同一订阅）
- **Claude Console**（API 优先 / 按量付费）
- **Amazon Bedrock**（继承 AWS 合规与计费）
- **Google Vertex AI**（继承 GCP）
- **Microsoft Foundry**（继承 Azure）

### 1.2 计划层级：个人 / 团队 / 企业（核心分水岭）[AU]

这是整个管控体系的**主线**——「谁能用哪些管控/分配能力」首先由订阅层决定。

**三层定位（authentication 原文，唯一权威出处）：**
- **个人 Pro / Max**：用 Claude.ai 账户登录的**个人**订阅。文档对个人层**只描述登录**，不赋予任何组织管控能力（没有管理控制台、没有成员/座位、不能下发策略）。
- **Claude for Teams**：「**自助服务计划，具有协作功能、管理工具和计费管理。最适合较小的团队。**」——有管理员仪表板、集中按座位计费、能邀请成员。
- **Claude for Enterprise**：「**在 Teams 之上添加 SSO、域名捕获(domain capture)、基于角色的权限(role-based permissions)、合规性 API(compliance API)、托管策略设置(managed policy settings)，用于组织范围配置。最适合有安全/合规要求的大型组织。**」

> Teams 与 Enterprise **共享**：团队成员可用 Claude Code + 网页版 Claude、集中计费、团队管理。Enterprise 是在 Teams 上**叠加**那 5 项。

### 1.3 能力 × 层级 对照表（来源已标注；文档未点名层级的标「未明确」）

| 能力 | 个人 Pro/Max | Teams | Enterprise | 出处 / 是否明确 |
|---|---|---|---|---|
| Claude.ai 账户登录 | ✅ | ✅ | ✅ | [AU] 明确 |
| 管理员仪表板 / 邀请成员 | ❌ | ✅ | ✅ | [AU] 明确 |
| 集中计费 / 按座位订阅 | n/a（个人订阅） | ✅ | ✅ | [AU][AS] 明确 |
| 用量看板 Analytics（每用户指标/贡献/排行榜） | ❌ | ✅（仅 Anthropic 提供商） | ✅（仅 Anthropic 提供商） | [AS] 明确「Teams 和 Enterprise」 |
| 支出上限 spend limits / Cost tracking | n/a | ✅（仅 Anthropic 提供商） | ✅（仅 Anthropic 提供商） | [AS] 仅注明「仅 Anthropic」，未细分 Teams/Ent |
| **server-managed-settings（服务端托管设置）** | ❌ | ✅ | ✅ | [SM][AS] **明确：Teams 和 Enterprise 均可**（Teams 2.1.38+ / Ent 2.1.30+）。见下「⚠️ 矛盾」 |
| **SSO / SAML** | ❌ | ❌ | ✅ | [AU] 明确 Enterprise 专属 |
| **域名捕获(domain capture)** | ❌ | ❌ | ✅ | [AU] 明确 Enterprise |
| **基于角色的权限(role-based permissions)** | ❌ | ❌ | ✅ | [AU] 明确 Enterprise |
| **合规性 API(compliance API)** | ❌ | ❌ | ✅ | [AU] 明确 Enterprise |
| **ZDR（零数据保留）** | ❌ | ❌ | ✅ | [AS] 明确「Enterprise 可用」 |
| SCIM 自动配置 | ❌ | 未明确 | 未明确（强烈指向 Enterprise） | [AS] 只说「在账户级配置」，未点名层级 |
| `managed-mcp.json`（固定 MCP 集，独占控制） | ❌ | ✅ | ✅ | [MCP] **与订阅层无关**，靠 MDM/管理员写系统路径；**无法经 server-managed 下发** |
| `allowedMcpServers`/`deniedMcpServers` 策略下发 | ❌ | ✅ | ✅ | [MCP][SM] 经 server-managed → 故 Teams+ |
| auto-mode 本身 | ✅（经 Anthropic API） | ✅ | ✅ | [AM] 明确「所有用户」 |
| auto-mode **组织级管控**（`autoMode` 经托管设置下发） | ❌ | ✅ | ✅ | [AM] 依赖 server-managed → Teams+ |

> **⚠️ 文档内部矛盾（需知道）**：authentication 的市场定位句把「**托管策略设置(managed policy settings)**」列为 **Enterprise 专属**；但功能页 server-managed-settings 与 admin-setup 明确写「**Claude for Teams 或 Enterprise** 均可用」。**以更具体的功能页为准：server-managed-settings 这个具体功能 Teams 即可用**；authentication 那句更像笼统概述。

> **关键认知**：六篇文档**大多按「提供商」(Anthropic 直连 / Console / 云) 而非「订阅层」组织内容**。很多管控（managed-mcp、permissions、沙箱）能不能用，**更取决于「是否走 Anthropic 直连 + 有无管理员写盘权限」，而非 Teams/Enterprise 之分**。订阅层主要卡的是：成员/座位/计费（Teams+）、server-managed 下发（Teams+）、SSO/SCIM/域名捕获/角色权限/合规 API/ZDR（Enterprise）。

### 1.4 计费方式差异 [AS]
- **Teams / Enterprise**：Claude Code 与 claude.ai 同在**一个按座位订阅**下，无需自建基础设施（默认推荐）。
- **Console**：API 优先 / **按量付费**。
- **Bedrock / Vertex / Foundry**：继承对应云的合规与计费，支出经 AWS Cost Explorer / GCP Billing / Azure Cost Management 查看。

---

## 2. 认证（authentication）

### 2.1 登录 / 鉴权方式（逐项 + 适用场景）[AU]
1. **Claude.ai 账户登录（浏览器 OAuth）**：个人 Pro/Max，以及 Teams/Enterprise 成员（管理员邀请后用 Claude.ai 账户登录）。首次运行 `claude` 自动开浏览器；WSL2/SSH/容器里按 `c` 复制 URL、粘贴 login code。
2. **Claude Console 凭证登录**：API 计费优先；管理员先在 Console 邀请并分配角色。
3. **云提供商凭证（Bedrock/Vertex/Foundry）**：设环境变量，无需浏览器登录。
4. **`ANTHROPIC_API_KEY`**：直连 Anthropic API（`X-Api-Key` 头）；交互模式首次提示批准并记忆，`/config` 的「使用自定义 API 密钥」开关可改；`-p` 非交互模式下只要存在就用。
5. **`ANTHROPIC_AUTH_TOKEN`**：`Authorization: Bearer` 头，用于经 LLM 网关/代理路由（网关用 bearer token 而非 API key）。
6. **`apiKeyHelper` 脚本**：返回 API key 的 shell 脚本，用于动态/轮换凭证（如 vault 短期令牌）；默认 5 分钟或遇 HTTP 401 刷新，`CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 可调；执行 >10 秒会告警。
7. **`CLAUDE_CODE_OAUTH_TOKEN`（长期 token）**：`claude setup-token` 生成的**一年期 OAuth 令牌**，用于 CI/脚本（无浏览器）；需 Pro/Max/Team/Enterprise；**仅限推理**，不能建 Remote Control 会话；`--bare` 模式不读它。
8. **订阅 OAuth 凭证（`/login`）**：Pro/Max/Team/Enterprise 的默认方式。

### 2.2 认证优先级（多凭证并存，从高到低）[AU]
1. 云提供商（`CLAUDE_CODE_USE_BEDROCK` / `_VERTEX` / `_FOUNDRY`）
2. `ANTHROPIC_AUTH_TOKEN`
3. `ANTHROPIC_API_KEY`（批准后）
4. `apiKeyHelper`
5. `CLAUDE_CODE_OAUTH_TOKEN`
6. `/login` 订阅 OAuth

**常见陷阱**：有订阅但环境里也有 `ANTHROPIC_API_KEY` 时，API key 批准后优先；若该 key 属已禁用/过期组织会认证失败，需 `unset` 回退。`apiKeyHelper` / `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` **仅终端 CLI 生效**；Claude Desktop 和远程会话**只用 OAuth**。

### 2.3 凭证存储 [AU]
- macOS：加密 Keychain。
- Linux：`~/.claude/.credentials.json`（权限 0600）。
- Windows：`%USERPROFILE%\.claude\.credentials.json`（继承用户目录 ACL）。
- `CLAUDE_CONFIG_DIR` 改配置位置；`ANTHROPIC_BASE_URL` 改 API 端点。

### 2.4 企业级强制 [AU][AS]
- **SSO**：Enterprise 能力；Console 侧也可设 SSO。SSO/SCIM 预配在「账户级」配置（细节在《Enterprise Administrator Guide》，文档外链未展开）。
- **域名捕获(domain capture)**：Enterprise 能力，等价「域名验证 / 同域用户自动归属」。
- **强制登录**：见 §4 的 `forceLoginMethod` / `forceLoginOrgUUID`。

---

## 3. 管理员、角色、座位、准入（admin-setup）

### 3.1 角色 [AU][$]
> ⚠️ **重要事实**：Claude Code 官方文档**没有**完整的组织角色权限矩阵；`iam` / `identity-and-access-management` 页**不存在(404)**。完整的「各角色能做/不能做」表在文档**外**的《Claude Enterprise Administrator Guide》。下面是文档里能**确证**的全部：

**Console 角色**（邀请用户时分配，与 Claude Code 直接相关的两种）[AU]：
- **Claude Code 角色**：只能创建 Claude Code 类型 API 密钥。
- **Developer 角色**：可创建任何类型 API 密钥。

**组织角色（仅确认存在 + 零散能力）**：
- analytics 页确认这套角色名存在：**Primary Owner / Owner / Admin / Developer / Billing**（通过 `UsageView` 权限——该权限授予以上 5 个角色，用于访问用量看板）。[$]
- 改**服务端托管设置**：仅 **Primary Owner / Owner**。[SM]
- 看 Team/Enterprise **Analytics 看板**：**Admin + Owner**；配置贡献指标(GitHub)：需 **Owner**。[$]
- **完整能力边界（各角色具体能做什么）文档未给**，需查外链企业管理员指南。Console 角色 ↔ claude.ai 组织角色的映射也未明确。

### 3.2 座位(seat) [AS]
- SSO、SCIM 预配、座位分配在「Claude 账户级别」的**管理控制台**配置。
- **座位 = Claude Code 访问的硬开关**：若用户座位「不包括 Claude Code 访问权限」，登录会报「您还没有被添加到您的组织」，需在管理控制台更新座位。

### 3.3 管理员能做的控制动作 [AS][AU]
- **成员与准入**：管理员仪表板/Console 邀请成员（Console 路径 Settings → Members → Invite，支持批量），邀请时分配角色，靠座位分配决定谁能用 Claude Code。
- **策略强制**：通过托管设置（§4/§5），优先于本地开发者配置，可锁定权限/沙箱/MCP/插件/hooks/版本下限等。
- **用量与支出**：Usage monitoring（OpenTelemetry，所有提供商）、Analytics dashboard（每用户指标/贡献/排行榜，仅 Anthropic 提供商）、Cost tracking（spend limits / rate limits / 使用归属，仅 Anthropic）；云提供商侧走各自账单。
- **数据与审计**：ZDR（Enterprise）、审计跟踪、Compliance API、请求级审计（放 LLM gateway）。

### 3.4 分发与验证 [AS]
- **分发**：订阅 → 邀请成员（分角色/座位）→ 成员装 Claude Code 用对应账户登录；云路线分发环境变量与凭证生成说明。
- **验证生效**：开发者跑 `/status`，显示 `Enterprise managed settings (remote|plist|HKLM|HKCU|file)`，表明策略来源与生效。
- **切换/排障**：`/logout`→`/login` 切账号；缺企业认证选项跑 `claude update` 后重启终端。

### 3.5 权限模式（permission modes，共 6 种）[PM][P]
这是「客户端干活时，哪些操作不用问就放行」的总开关。共 **6 种**（注意比常被列的 5 种多一个 `dontAsk`）：

| 模式 | 不问就放行的范围 | 写「受保护路径」 | 适用 |
|---|---|---|---|
| `default` | 仅只读 | 提示 | 入门 / 敏感工作 |
| `acceptEdits` | 读 + 文件编辑 + 常见 FS 命令（`mkdir touch mv cp rm rmdir sed`） | 提示 | 迭代中的代码 |
| `plan` | 仅只读（先探索出计划，不改源码） | 提示 | 改动前探索 |
| `auto` | **所有操作，但每次经后台分类器安全检查**（研究预览） | 路由到分类器 | 长任务、减少打扰 |
| `dontAsk` | 仅预先批准的工具，其余**自动拒绝** | 拒绝 | 锁定的 CI / 脚本 |
| `bypassPermissions` | 所有操作，跳过检查（`rm -rf /`、`rm -rf ~` 仍有断路器提示） | 允许(v2.1.126+) | **仅隔离容器/VM** |

- 切换：CLI 按 `Shift+Tab` 循环 `default → acceptEdits → plan`；`auto`/`dontAsk`/`bypassPermissions` 需 `claude --permission-mode <mode>` 或持久化 `permissions.defaultMode`。
- **仓库无法自授**：`.claude/settings.json` / `.local.json` 里设 `defaultMode:"auto"` 会被**忽略**，必须放 `~/.claude/settings.json`（防检入仓库自我提权）。
- `bypassPermissions` **不防提示注入**；想「无提示但有安全检查」用 `auto`。
- **受保护路径**（除 bypass 外永不自动批准写）：`.git .config/git .vscode .idea .husky .cargo .devcontainer .yarn .mvn .claude`（`.claude/commands|agents|skills|worktrees` 例外）；及 `.mcp.json .claude.json .npmrc .bashrc/.zshrc` 等文件。

### 3.6 auto-mode 的管理员启用与锁定 [PM]
- **所有计划**都支持 auto mode，但 **Team / Enterprise 上管理员必须先在 `https://claude.ai/admin-settings/claude-code` 启用**，用户才能开。
- **锁定**：托管设置里 `permissions.disableAutoMode: "disable"`（覆盖一切，用户不可改）。
- **模型要求**：Anthropic API 需 Opus 4.6+ / Sonnet 4.6；Bedrock/Vertex/Foundry 仅 Opus 4.7/4.8 且需 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；需 Claude Code v2.1.83+。

---

## 4. 设置体系与优先级（settings）

### 4.1 作用域与优先级（从高到低）[S]
1. **Managed（托管，最高）** —— 服务器管理 / MDM-OS 策略 / 系统级 `managed-settings.json`；影响机器所有用户；**无法被任何下层覆盖，包括命令行参数**。
2. **命令行参数**（`--settings <file-or-json>`）—— 临时会话覆盖。
3. **Local 本地项目**（`.claude/settings.local.json`，gitignored）—— 个人、仅本仓库。
4. **Project 共享项目**（`.claude/settings.json`，提交到 git）—— 团队共享。
5. **User 用户（最低）**（`~/.claude/settings.json`；Windows `%USERPROFILE%\.claude`）—— 个人全局。

### 4.2 Managed 层内部子优先级 [S][SM]
`server-managed > MDM/OS 级策略 > 基于文件(managed-settings.d/*.json + managed-settings.json) > HKCU 注册表(仅 Windows)`。
**只用一个 managed 源，层间不合并** —— 若 server-managed 下发了任意键，端点托管（MDM/文件）被**完全忽略**。[SM]

### 4.3 合并规则 [S]
- **标量值**：高层压低层（谁高谁赢）。例：user 允许 `Bash(npm run *)`，project deny 它，则被阻止。
- **数组设置**：跨作用域**「连接 + 去重」而非替换**（如 `permissions.allow`、`sandbox.filesystem.allowWrite`）。低层能**添加**条目但**不能删**高层条目。
- **权限规则评估顺序**：先 `deny` → 再 `ask` → 最后 `allow`，**第一个匹配的规则获胜**。

### 4.4 端点托管的存放形式 [S]
- **服务端托管**：Claude.ai Web 控制台，**无本地路径**。
- **MDM/OS**：macOS `com.anthropic.claudecode` managed preferences；Windows `HKLM\SOFTWARE\Policies\ClaudeCode`（`Settings` 值含 JSON）或 `HKCU\...`（最低）。
- **文件型**：macOS `/Library/Application Support/ClaudeCode/`、Linux/WSL `/etc/claude-code/`、Windows `C:\Program Files\ClaudeCode\`（旧 `C:\ProgramData\` 自 v2.1.75 弃用）；支持 `managed-settings.d/` 目录（数字前缀控制合并序）。
- **`policyHelper`**：管理员部署的可执行文件，启动时动态计算 managed 设置（仅 MDM/系统文件源，输出 `managedSettings` 信封）。

---

## 5. 服务端托管设置（server-managed-settings）

### 5.1 是什么 [SM]
管理员在 Claude.ai Web 控制台（**Admin Settings → Claude Code → Managed settings**）集中下发 JSON；客户端用组织凭证登录后自动接收。专为**无 MDM / 非托管设备**的组织设计。需 Teams/Enterprise + 客户端能访问 `api.anthropic.com`。

### 5.2 工作机制 [SM]
- **下发者**：仅 `Primary Owner` 和 `Owner` 角色可管理。
- **拉取/缓存**：客户端**启动时异步从服务器获取**，活动会话期间**每小时轮询**一次；缓存本地持久化，网络故障下仍生效；多数设置更新无需重启自动应用（OpenTelemetry 等高级设置例外）。
- **应用形式**：管理员侧纯 JSON；客户端侧本质是 Managed 层（最高优先级）。传输靠组织 OAuth 身份 + `api.anthropic.com`，**无本地文件路径**。
- **首次无缓存窗口**：获取前有一小段「策略未强制执行」窗口；获取失败则继续运行而不带托管设置。
- **故障关闭(fail-closed)**：设 `forceRemoteSettingsRefresh: true`，客户端启动时**阻塞直到成功拉取**，失败则**退出**而非裸跑；此设置自我延续（本地缓存同样强制）。注意：`claude auth login` 等子命令（v2.1.139+）**不受**此阻塞，以便凭证过期时能重认证。
- **安全批准对话框**：含 shell 命令、未知 env 变量、任何 hook 定义的设置，用户启动时会看到批准弹窗，拒绝则 Claude Code 退出（`-p` 非交互模式跳过批准直接应用）。

### 5.3 能否本地覆盖 / 绕过 [SM]
- **不能覆盖**：Managed 层无法被 user/project/local/命令行覆盖；用户篡改缓存文件 → 下次服务器拉取恢复。
- **会被绕过的情形**：用不同组织登录 → 不下发；配置第三方模型提供商（Bedrock/Vertex/Foundry/自定义 `ANTHROPIC_BASE_URL`）→ **server-managed 被完全绕过**。
- **安全定性**：server-managed 是**客户端控制(client-side control)**。非托管设备上有 sudo/管理员权限的用户仍可改二进制/文件系统/网络；要更强保证须用 MDM 端点托管。可用 `ConfigChange` hook 检测/阻止未授权运行时改动。

### 5.4 审计与当前限制 [SM]
- **审计**：设置变更通过 Compliance API / 审计日志导出，含操作类型、账户、设备、新旧值引用。
- **限制**：统一应用全组织（**暂不支持分组**）；`managed-mcp.json` **不能**经此下发（改用 `allowedMcpServers`/`deniedMcpServers`）；`policyHelper`、`wslInheritsWindowsSettings` 等仅限 OS 级策略的键不被遵守。

---

## 6. 关键设置键名清单（settings，真实写法）

> 按类别整理，便于查阅哪些适合做「企业强制」。

### 6.1 仅 Managed 设置生效的键（放 user/project 无效，最适合企业强制）[S]
- `allowManagedPermissionRulesOnly` —— 只认 managed 权限规则，禁 user/project 定义 allow/ask/deny。
- `allowManagedHooksOnly` —— 只加载 managed/SDK/强制启用插件的 hooks。
- `allowManagedMcpServersOnly` —— 只认 managed 的 MCP 允许列表（deny 仍全源合并）。
- `forceRemoteSettingsRefresh` —— 故障关闭启动。
- `claudeMd` —— 组织级注入的 CLAUDE.md 指令。
- `strictKnownMarketplaces` / `blockedMarketplaces` / `pluginSuggestionMarketplaces` / `pluginTrustMessage` —— 插件市场允许/阻止/信任提示。
- `strictPluginOnlyCustomization` —— 锁定 skills/agents/hooks/MCP 只能来自插件或 managed（可传 `true` 或数组如 `["skills","hooks"]`）。
- `channelsEnabled` / `allowedChannelPlugins` —— 频道开关与允许列表。
- `allowAllClaudeAiMcps`、`parentSettingsBehavior`（`"first-wins"`/`"merge"`）、`sshConfigs`（只读）。

### 6.2 权限（企业强制核心）[S]
- `permissions.allow` / `permissions.ask` / `permissions.deny` —— 数组，语法 `Tool` 或 `Tool(specifier)`，如 `Bash(curl *)`、`Read(./.env)`、`WebFetch(domain:example.com)`。
- `permissions.deny` 典型用于排除敏感文件：`Read(./.env)`、`Read(./secrets/**)`。
- `permissions.additionalDirectories` —— 额外可访问工作目录。
- `permissions.defaultMode` —— `default`/`acceptEdits`/`plan`/`auto`/`dontAsk`/`bypassPermissions`（项目/本地设 `auto` 被忽略，防仓库自授）。
- `permissions.disableBypassPermissionsMode: "disable"` —— 禁用 `--dangerously-skip-permissions`。
- `skipDangerousModePermissionPrompt`。

### 6.3 模型 / 认证 / 登录 [S]
- `model`、`availableModels`（限制 `/model` 可选模型，如 `["sonnet","haiku"]`）、`modelOverrides`、`minimumVersion`。
- `apiKeyHelper`（生成 `X-Api-Key`/`Bearer` 的脚本）、`forceLoginMethod`（`claudeai`/`console`）、`forceLoginOrgUUID`（强制属于特定 Anthropic 组织，空数组 fail-close）。

### 6.4 env / hooks / 遥测 / 自动更新 [S]
- `env` —— 注入每会话及子进程的环境变量（如 `CLAUDE_CODE_ENABLE_TELEMETRY`、`OTEL_METRICS_EXPORTER`）。
- `hooks` —— 生命周期事件命令；相关约束键 `allowedHttpHookUrls`、`httpHookAllowedEnvVars`、`disableAllHooks`。
- 自动更新：`autoUpdatesChannel`（`stable`/`latest`）；完全禁用用 env 里的 `DISABLE_AUTOUPDATER`。
- 遥测：`env` 中 `CLAUDE_CODE_ENABLE_TELEMETRY`、`feedbackSurveyRate`（设 0 抑制）、`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`。

### 6.5 MCP 开关 [S]
- `enableAllProjectMcpServers`、`enabledMcpjsonServers`、`disabledMcpjsonServers`（`.mcp.json` 内的批准/拒绝）。
- `allowedMcpServers` / `deniedMcpServers`（managed-settings 中，**deny 优先于 allow**，全作用域生效）。

### 6.6 沙箱 sandbox（网络/文件系统准入）[S]
- `sandbox.enabled`、`sandbox.failIfUnavailable`（硬门）、`allowUnsandboxedCommands: false`（禁逃生舱）。
- `sandbox.filesystem.allowWrite/denyWrite/denyRead/allowRead`、`filesystem.allowManagedReadPathsOnly`（仅 managed）。
- `sandbox.network.allowedDomains/deniedDomains/allowManagedDomainsOnly`（仅 managed，deny 优先且全源合并）、`httpProxyPort`/`socksProxyPort`、`allowLocalBinding`。

### 6.7 其他可锁项 [S]
`disableAgentView`、`disableAutoMode`、`disableRemoteControl`、`disableSkillShellExecution`、`disableWorkflows`、`includeGitInstructions`、`attribution`/`includeCoAuthoredBy`（提交归属）、`companyAnnouncements`、`cleanupPeriodDays`、`minimumVersion`、`autoUpdatesChannel`。

### 6.8 权限规则语法 `Tool(specifier)`（深入）[P]
规则 = `Tool` 或 `Tool(specifier)`；评估 **deny → ask → allow**，首个匹配胜，deny 永不可被覆盖。裸 `Bash`（=`Bash(*)`）作 deny 会把工具从上下文整个移除；带范围 `Bash(rm *)` 保留工具、仅拦匹配项。

**Bash**（`*` 可在任意位置）：
- `Bash(npm run build)` 精确 · `Bash(npm run test *)` 前缀 · `Bash(* install)` 结尾 · `Bash(git * main)` 跨参数。
- **空格语义关键**：`Bash(ls *)`（有空格）匹配 `ls -la` 但不匹配 `lsof`；`Bash(ls*)`（无空格）两者都匹配。
- `:*` 后缀 ≡ 尾部 ` *`：`Bash(ls:*)` ≡ `Bash(ls *)`，仅在模式**末尾**识别。
- 复合命令（`&& || ; |` 换行）各子命令须独立匹配；包装器 `timeout/nice/nohup/stdbuf`（及无标志 `xargs`）剥离后再匹配，但 `npx/docker exec/direnv` **不**剥离；`find -exec/-delete`、`watch` 总是提示。
- 只读命令集（`ls cat echo pwd head tail grep find wc which diff stat` 及 git 只读）不可配置、各模式免提示。

**Read / Edit**（gitignore 风格，4 种锚点 —— 易错）：
| 写法 | 含义 |
|---|---|
| `//path` | **文件系统根**绝对路径，如 `Read(//Users/a/secrets/**)` |
| `~/path` | 主目录 |
| `/path` | **项目根相对**（**不是绝对！**），如 `Edit(/src/**/*.ts)` |
| `path` / `./path` | 当前目录相对 |
- `*` 单层、`**` 递归；裸文件名任意深度：`Read(.env)` ≡ `Read(**/.env)`。Windows 路径规范化为 POSIX（`C:\Users\a`→`/c/Users/a`）。
- deny 也覆盖 Bash 里的 `cat/head/tail/sed`，但**不**覆盖 Python/Node 子进程的间接读写（需沙箱做 OS 级强制）。

**WebFetch**：`WebFetch(domain:example.com)`（`WebSearch` 只能裸工具名，无 specifier）。
**MCP**：`mcp__puppeteer`（该 server 全部工具）· `mcp__puppeteer__*`（同效）· `mcp__puppeteer__navigate`（单工具）。**无法对 MCP 工具的参数做过滤**，只到工具名粒度。
**Agent(子代理)**：`Agent(Explore)`、`Agent(Plan)`、`Agent(my-custom-agent)`。

---

## 7. 受管 MCP（managed-mcp：控制组织的 MCP 访问）

### 7.1 背景 [MCP]
- 默认任何人都能连任意 MCP server；Anthropic 只对其[目录](https://claude.ai/directory)连接器做上架审查，**不对任意 MCP 做安全审计或托管**。
- **Claude Code 没有内置 MCP registry**供用户浏览安装；批准目录模式需管理员在内部 wiki 分享 `claude mcp add` 命令，或经托管插件市场（`/plugin`）分发。

### 7.2 七种控制模式 [MCP]
| 模式 | 功能 | 配置 |
|---|---|---|
| 禁用 MCP | 任何地方都不加载 | `managed-mcp.json` 带空映射 `{"mcpServers": {}}` |
| 固定部署 | 每个用户拿到相同 server，无法添加其他 | `managed-mcp.json` 含想要的 server |
| 批准的目录 | 发布批准列表，用户可加，其他被阻止 | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |
| 仅插件 server | server 只能来自插件 | `strictPluginOnlyCustomization` 含 `mcp` |
| 软允许列表 | 强制允许列表，用户可扩展 | `allowedMcpServers`（不带 only 开关） |
| 仅拒绝列表 | 阻止已知坏 server，放行其余 | `deniedMcpServers` |
| 无限制 | 用户随意添加 | 不部署任何托管 MCP 配置 |

### 7.3 `managed-mcp.json`（集中下发一批 MCP）[MCP]
- **独占控制**：部署后 Claude Code **仅加载该文件定义的 server**；用户无法添加/修改/使用其他 MCP（**包括插件提供的**），并默认禁止 claude.ai 连接器（除非 `allowAllClaudeAiMcps`）。
- **格式**：同项目级 `.mcp.json`，顶层键 `mcpServers`，每 server 支持 `type`（`http`/`stdio`/`sse`）、`url`、`command`、`args`、`env`。
- **部署路径**（系统级，需管理员权限，一般 MDM/Jamf/GPO/Intune 下发）：
  - macOS `/Library/Application Support/ClaudeCode/managed-mcp.json`
  - Linux/WSL `/etc/claude-code/managed-mcp.json`
  - Windows `C:\Program Files\ClaudeCode\managed-mcp.json`
- **关键限制**：`managed-mcp.json` **无法经 server-managed-settings 交付**，只能靠能写系统路径的进程部署。
- **完全禁用**：部署 `{"mcpServers": {}}`；用户 `/mcp` 看不到任何 server，`claude mcp add` 报企业策略错误；之前配过的 server 下次启动**静默停止加载**。

### 7.4 白/黑名单与三步评估 [MCP]
- 两字段：`allowedMcpServers`（白）、`deniedMcpServers`（黑），均为**条目对象数组**，每条用单键标识：
  - `serverUrl` —— 远程 URL，支持 `*` 通配（HTTP/SSE）；
  - `serverCommand` —— stdio 的**精确命令+参数**（逐参数精确匹配）；
  - `serverName` —— 用户分配标签，**仅精确匹配、不展开通配**。
- **安全警告**：仅用 `serverName` 的白名单**不是安全控制**（用户能把任意 server 命名为 `github`）；真正强制须用 `serverCommand` 或 `serverUrl`。
- **未设置 vs 空数组**：`allowedMcpServers` 未设=允许全部，`[]`=不允许任何，有内容=仅允许匹配；`deniedMcpServers` 未设/`[]`=都不阻止，有内容=阻止匹配。
- **三步评估**（对所有 server，含 `managed-mcp.json`）：
  1. **合并列表**：各源 allow/deny 合并；`allowManagedMcpServersOnly: true` 时只保留托管 allow，**deny 始终从每源合并**；
  2. **检查拒绝**：匹配即阻止，**没有任何东西能覆盖 deny**；
  3. **检查允许**：未设放行所有过了 deny 的；已设按类型匹配（远程必须匹配 `serverUrl`；stdio 必须匹配 `serverCommand`；仅当 allow 不含对应类型条目时 `serverName` 才生效）。
- **不对称**：`allowManagedMcpServersOnly` 让用户/项目/本地 allow 失效（只受管 allow 生效），**但 deny 始终合并** → 用户**能为自己收紧、不能放宽**。与 `allowManagedPermissionRulesOnly` 是两个独立标志。
- **`allowAllClaudeAiMcps: true`**（v2.1.149+，仅托管源生效）：让 claude.ai 连接器与 `managed-mcp.json` 共存；allow/deny 仍生效，但插件 server 仍禁止。

### 7.5 凭据（重要安全约束 + 真实写法）[MCP][M]
- **不要在 `env` 块放 API key/凭据**（机器上任何用户都能读该文件）。**没有「集中托管凭据保管库」**——managed-mcp 只集中管「服务器」，凭据始终 per-server。
- 四种 per-user 方式：
  1. **`${VAR}` 扩展**：语法 `${VAR}` / `${VAR:-default}`，可用于 `command`/`args`/`env`/`url`/`headers`。例：
     ```json
     { "mcpServers": { "api": {
       "type": "http",
       "url": "${API_BASE_URL:-https://api.example.com}/mcp",
       "headers": { "Authorization": "Bearer ${API_KEY}" } }}}
     ```
     必需变量未设且无默认 → 配置解析失败。
  2. **静态 headers**：`--header "Authorization: Bearer xxx"` 或 JSON 的 `headers` 字段。
  3. **`headersHelper`（动态头）**：指向脚本，须向 stdout 输出**键值对 JSON 对象**；shell 执行、**10 秒超时、每次连接都跑（无缓存）**，动态头覆盖同名静态 header。注入环境变量 `CLAUDE_CODE_MCP_SERVER_NAME`/`CLAUDE_CODE_MCP_SERVER_URL`。例：`"headersHelper": "/opt/bin/get-headers.sh"`。
  4. **OAuth 2.0**：HTTP server 返回 401/403 即标记需认证，用 `/mcp` 走浏览器流；可 `--callback-port` 固定回调、`--client-id/--client-secret`（密钥进系统钥匙串不进配置）、`oauth.scopes` 限范围。

### 7.6 用户侧报错 + 监控 [MCP]
| 限制 | 用户看到 |
|---|---|
| 存在 `managed-mcp.json` 且 add | `enterprise MCP configuration is active and has exclusive control over MCP servers` |
| 命中拒绝列表 | `server is explicitly blocked by enterprise policy` |
| 不在允许列表 | `not allowed by enterprise policy` |
| 既有 server 被新策略阻止 | **静默从 `/mcp`、`claude mcp list` 消失，无警告** |
- 监控：OTel 导出后设 `OTEL_LOG_TOOL_DETAILS=1`，工具事件含 MCP server 与工具名。
- 验证：托管机上 `claude mcp list`（应只剩托管 server）、`claude mcp add ...`（应被拒）。

---

## 8. 自动模式（auto-mode-config）

### 8.1 是什么 [AM]
- 让 Claude Code **无需权限提示即可运行**：把**每个工具调用路由到一个分类器(classifier)**，分类器**阻止任何不可逆、破坏性、或指向你环境之外的操作**。
- 开箱即用**只信任工作目录 + 当前代码库已配置的远程**；推送到公司 SCM 组织、写团队云桶等会被阻止，直到加入 `autoMode.environment`。
- 可用性：Anthropic API 全员可用；Bedrock/Vertex/Foundry 需先设 `CLAUDE_CODE_ENABLE_AUTO_MODE`；Team/Enterprise 上还涉及管理员启用（详见 permission-modes 页，**待确认细节**）。

### 8.2 配置读取范围 [AM]
| 范围 | 文件 | 用途 |
|---|---|---|
| 单开发者 | `~/.claude/settings.json` | 个人受信基础设施 |
| 单项目单开发者 | `.claude/settings.local.json`（gitignored） | 按项目受信桶/服务 |
| **组织范围** | **server-managed-settings** | 分发给所有开发者 |
| 按调用 | `--settings` 标志 / Agent SDK 内联 JSON | 自动化覆盖 |
- 分类器还读取与 Claude 相同的 **CLAUDE.md**（如「从不强制推送」同时指导 Claude 与分类器）。
- **关键隔离**：分类器**不从 `.claude/settings.json`（共享项目设置）读取 `autoMode`** → 被 check-in 的代码库**无法注入自己的允许规则**。

### 8.3 配置字段（`autoMode` 块下，内容是自然语言散文）[AM]
- `autoMode.environment` —— 受信基础设施（代码库、桶、域、内部服务）。多数组织唯一需要设的字段。
- `autoMode.allow` —— 例外（覆盖 soft_deny）。
- `autoMode.soft_deny` —— 破坏性操作，用户意图或 allow 可覆盖。
- `autoMode.hard_deny` —— 无条件安全边界，用户意图与 allow 都不能覆盖。
- **`"$defaults"` 字面字符串**：在数组里包含它会把内置默认拼接进来并继续继承版本更新；**不含则替换整段默认**（Danger：漏掉会丢弃强制推送、`curl|bash`、生产部署等内置 soft_deny 与内置数据泄露/绕过 hard_deny）。

### 8.4 分类器内部优先级（四层）[AM]
1. `hard_deny` 无条件阻止；
2. `soft_deny` 阻止（可被用户意图/allow 覆盖）；
3. `allow` 覆盖匹配的 `soft_deny`；
4. **明确用户意图**覆盖剩余 soft_deny（须「直接且具体」，如「强制推送此分支」算，泛泛「清理代码库」不算）。

### 8.5 与权限系统的关系（重要）[AM]
- **分类器是权限系统之后的「第二道门」**。`permissions.deny`（基于工具模式）在分类器**之前**先跑，是**硬边界**；`autoMode` 是其后的语义判断层。
- `autoMode` 合并是**累加(additive)的，不是硬策略边界**：开发者能扩展 environment/allow/soft_deny/hard_deny，**不能删除托管条目**；但因 allow 是 soft_deny 的例外，**开发者新增 allow 可覆盖组织的 soft_deny**。
- → **结论**：对「无论用户意图或分类器配置如何都必须永不运行」的操作，要用**托管设置里的 `permissions.deny`**（咨询分类器**之前**阻断，不可覆盖），而非 `autoMode`。

### 8.6 CLI 验证 [AM]
- `claude auto-mode defaults` —— 打印内置 environment/allow/soft_deny/hard_deny。
- `claude auto-mode config` —— 打印应用设置后**实际生效**的规则（`$defaults` 已展开）。
- `claude auto-mode critique` —— AI 审查自定义规则（标记模糊/冗余/易误报）。
- 拒绝记录在 `/permissions` 的「最近拒绝」；按 `r` 重试；可用 `PermissionDenied` hook 编程响应。

---

## 9. 用量 · 计费 · 审计 · 合规 [AS][$]

### 9.1 支出上限（spend limits）
- **Claude API（Console）**：在 Claude Code **workspace** 上设工作区支出上限（首次用 Console 账户认证会自动建名为「Claude Code」的 workspace）。
- **Pro/Max**：`/usage-credits` 命令设每月使用额度上限（改限额需账户计费权限）。
- **Bedrock/Vertex/Foundry**：Anthropic **不从云端发指标**；有企业用 LiteLLM 按 key 跟踪（第三方，未经 Anthropic 安全审计）。

### 9.2 速率限制（rate limits）
- **组织级**（非按个人）设 TPM/RPM；Console workspace 的 Limits 页设工作区速率限制以保护其他生产负载。
- 文档给了每用户 TPM/RPM 建议表（按团队规模递减：1–5 人 ~200k–300k TPM；500+ 人 ~10k–15k TPM）。Agent 团队（plan 模式）约 7× 标准会话 token。

### 9.3 用量归属（attribution）
- **`/usage` 命令**：把用量归到 skills/subagents/plugins/各 MCP server（占比），`d`/`w` 切 24h/7d；**仅本机本地历史**，不含其他设备/claude.ai。
- **Analytics 团队洞察**：API key 用户按 key 标识，OAuth 用户按邮箱；「本月支出 / 本月代码行」按用户。
- **PR 归属**（Team/Enterprise + GitHub App）：合并前 21 天~后 2 天的会话参与匹配；含 CC 行的 PR 标 `claude-code-assisted`；开发者重写 >20% 不归属；排除 lockfile/生成代码/构建目录/>1000 字符行。

### 9.4 Analytics 看板（位置与权限）
| 计划 | 入口 URL | 内容 | 看板权限 |
|---|---|---|---|
| Team/Enterprise | `claude.ai/analytics/claude-code` | 使用/贡献(GitHub)/排行榜/CSV 导出 | Admin + Owner（配贡献指标需 Owner） |
| API (Console) | `platform.claude.com/claude-code` | 使用/支出/团队洞察 | `UsageView`（Developer/Billing/Admin/Owner/Primary Owner） |
- 关键指标：含 CC 的 PR、含 CC 的代码行（「有效行」>3 字符规范化）、含 CC 的 PR%、建议接受率、接受的代码行。**ZDR 组织无法用贡献指标**，仅显示使用指标。
- 每用户 token/成本估算 → 需配 **OpenTelemetry**（`CLAUDE_CODE_ENABLE_TELEMETRY=1` + OTLP/Prometheus 导出），可经托管设置由 MDM 下发且用户不可覆盖。

### 9.5 审计 / 合规 / 模型限制
- **审计/合规**：审计跟踪、Compliance API（Enterprise）、ZDR（Enterprise）、请求级审计（放 LLM gateway）；server-managed 设置变更经 Compliance API 导出（操作类型/账户/设备/新旧值引用）。
- **限制可用模型**：没有直接的「模型允许列表」键做账户级限制（`availableModels` 只限 `/model` 选择项）；账户级等价手段是 LLM gateway 按敏感度路由 + 沙箱域名白名单。

---

## 10. 速查表

### 10.1 设置优先级（高→低）
`Managed（server-managed > MDM/OS > 文件 > HKCU）` > `命令行 --settings` > `项目 local` > `项目 shared` > `用户全局`。
（Managed 层不可被任何下层覆盖；Managed 内部「只用一个源、不合并」。）

### 10.2 权限/MCP 评估顺序
- 权限规则：`deny → ask → allow`，第一个匹配获胜。
- MCP：`合并 → 查 deny（最高，不可覆盖）→ 查 allow`。
- auto-mode：`hard_deny → soft_deny →（allow / 明确用户意图覆盖 soft_deny）`；硬边界另由 `permissions.deny` 在分类器前把守。

### 10.3 数组合并的不对称原则（贯穿全体系）
托管下发的数组项**只能被下层扩展、不能被删除**；deny 始终全源合并、不可覆盖 → 用户**能自我收紧、不能自我放宽**。

### 10.4 企业强制最常用项
- 权限：`permissions.deny` + `allowManagedPermissionRulesOnly`
- 模型：`availableModels`、`minimumVersion`
- 网络/FS：`sandbox.network.allowedDomains` + `allowManagedDomainsOnly`、`sandbox.enabled`
- 登录：`forceLoginMethod`、`forceLoginOrgUUID`
- 能力开关：`disableBypassPermissionsMode`、`disableRemoteControl`、`disableAgentView`、`disableAutoMode`
- MCP：`allowedMcpServers`/`deniedMcpServers` + `allowManagedMcpServersOnly`，或系统级 `managed-mcp.json`（独占）
- 启动：`forceRemoteSettingsRefresh`（fail-closed）

---

## 附录 A：真实配置示例合集（逐字转录，照着改即可）

### A1. 服务端托管设置：硬禁危险操作 + 仅托管规则 [A]
```json
{
  "permissions": {
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}
```
全员拒 `curl`、拒读 `.env`/secrets；禁 `--dangerously-skip-permissions`；锁死，用户/项目自定义权限规则全失效。

### A2. 全组织「编辑后审计」hook [A]
```json
{ "hooks": { "PostToolUse": [ {
  "matcher": "Edit|Write",
  "hooks": [ { "type": "command", "command": "/usr/local/bin/audit-edit.sh" } ]
} ] } }
```
每次 Edit/Write 后跑审计脚本（含 shell 命令的设置会触发用户启动时的「安全批准对话框」）。

### A3. 标准 settings.json 骨架 [S]
```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)"],
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
  },
  "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "OTEL_METRICS_EXPORTER": "otlp" },
  "companyAnnouncements": ["Welcome to Acme! Review docs.acme.com", "Reminder: code reviews required"]
}
```

### A4. fail-closed 启动 [A]
```json
{ "forceRemoteSettingsRefresh": true }
```
启动阻塞直到拉到新设置，失败则 CLI 退出（不裸奔）；自我延续；启用前确保能连 `api.anthropic.com`。

### A5. 沙箱（网络/文件系统准入）[S]
```json
{ "sandbox": {
  "enabled": true,
  "filesystem": { "allowWrite": ["/tmp/build", "~/.kube"], "denyRead": ["~/.aws/credentials"] },
  "network": {
    "allowedDomains": ["github.com", "*.npmjs.org"],
    "deniedDomains": ["uploads.github.com"],
    "allowUnixSockets": ["/var/run/docker.sock"],
    "allowLocalBinding": true
  }
} }
```
`network.allowedDomains` 是出站白名单，对所有子进程（kubectl/terraform/npm…）都生效，不止 Claude 自己的工具。

### A6. managed-mcp.json：固定 MCP 集（独占控制）[C]
```json
{ "mcpServers": {
  "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" },
  "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" },
  "company-internal": {
    "type": "stdio",
    "command": "/usr/local/bin/company-mcp-server",
    "args": ["--config", "/etc/company/mcp-config.json"],
    "env": { "COMPANY_API_URL": "https://internal.example.com" }
  }
} }
```
部署后只加载这三个；用户无法增改（含插件 server）。**完全禁用 MCP** = `{"mcpServers": {}}`。**不要在 `env` 放密钥**。

### A7. allowedMcpServers / deniedMcpServers（硬白+黑名单）[C]
```json
{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] },
    { "serverUrl": "https://*.internal.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ],
  "allowManagedMcpServersOnly": true
}
```
白名单含 `serverUrl` 条目 → 所有远程 server 必须匹配 URL（改名混不进）；deny 永远优先。**未设=放行全部；`[]`=拒绝全部**。

### A8. autoMode 四字段（含 `$defaults`）[D]
```json
{ "autoMode": {
  "environment": ["$defaults", "Source control: github.example.com/acme-corp and all repos under it"],
  "allow": ["$defaults", "Writing to s3://acme-scratch/ is allowed: ephemeral 7-day bucket"],
  "soft_deny": ["$defaults", "Never run database migrations outside the migrations CLI"],
  "hard_deny": ["$defaults", "Never send repository contents to third-party code-review APIs"]
} }
```
内容是**自然语言散文**（不是正则）。**任一字段漏掉 `"$defaults"` 就会替换该段全部内置默认**（会丢掉强制推送、`curl|bash`、生产部署等内置拦截）。

### A9. MCP 动态凭据 headersHelper / `${VAR}` [M]
```json
{ "mcpServers": { "internal-api": {
  "type": "http",
  "url": "${API_BASE_URL:-https://api.example.com}/mcp",
  "headers": { "Authorization": "Bearer ${API_KEY}" },
  "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
} } }
```
`headersHelper` 向 stdout 输出键值对 JSON、10 秒超时、每次连接都跑；动态头覆盖同名静态 header。

### A10. CI 长期令牌 [F]
```bash
claude setup-token            # 走 OAuth，打印一年期令牌（不保存）
export CLAUDE_CODE_OAUTH_TOKEN=your-token
```
仅限推理，不能建 Remote Control 会话。

---

## 附录 B：端到端流程（分步骤）

### 流程 A — 服务端托管设置：下发 → 拉取 → 应用 → fail-closed [A][E]
1. 管理员进 **Admin Settings > Claude Code > Managed settings**（仅 Primary Owner/Owner），粘贴 JSON，保存部署（统一应用全员，暂不支持分组）。
2. 客户端用组织凭证认证时收到设置；**启动拉取 + 活动会话每小时轮询**。
3. 首次无缓存：异步拉取，失败则照常运行（无托管设置）；有一小段「限制未生效」窗口。
4. 有缓存：缓存立即应用 → 后台拉新 → 缓存能穿越断网存活。
5. 冲突合并：托管层最高（命令行都压不过）；托管内部「先非空源胜、源间不合并」；数组类跨源合并去重（开发者只能扩展、不能删）。
6. fail-closed（`forceRemoteSettingsRefresh:true`）：启动阻塞直到拉到，失败则退出；但 `claude auth login`（v2.1.139+）豁免，避免凭证过期锁死。
7. 用户弹窗：含 shell 命令/未知 env/任何 hook 时启动弹「安全批准」，拒绝即退出（`-p` 非交互模式跳过、直接应用）。
8. 验证：`/status` 看到 `Enterprise managed settings (remote)`；`/permissions` 看生效的托管权限。

### 流程 B — MCP allow/deny 三步评估（走例子）[C]
配置：`allowedMcpServers: [{serverName:"github"}, {serverCommand:["npx","-y","approved-package"]}]`
- stdio、命令 `["node","server.js"]`、名为 `github` → **拒绝**（allow 含 serverCommand 条目 → stdio 必须匹配命令；命令不符，且 serverName 因有 serverCommand 而失效）。
- http、名为 `github` → **放行**（allow 无 serverUrl 条目 → serverName 生效）。
- stdio、命令 `["npx","-y","approved-package"]` → **放行**（命令精确匹配）。
- deny 覆盖：某 server 同时匹配 allow `https://*.example.com/*` 与 deny `https://staging.example.com/api` → **deny 优先 → 拒绝**。

### 流程 C — auto-mode 判一次操作（force push 例子）[D]
分类器在权限系统**之后**跑，四级：`hard_deny`（无条件）→ `soft_deny`（可被覆盖）→ `allow`（soft_deny 例外）→ **明确用户意图**（覆盖剩余 soft_deny）。
- 强制推送 = 内置 `soft_deny`。
- 用户说「清理一下代码库」（泛化）→ 不算明确意图 → **拦截**。
- 用户说「force push 这个分支」（直接具体）→ 算明确意图 → **放行**。
- 管理员把强推加进 `hard_deny` → 无论用户怎么说都**拦截**。
> 真正「绝不允许」要放托管 `permissions.deny`（在分类器**之前**、不可覆盖），不要只靠 autoMode。

### 流程 D — 客户端认证选哪个凭据 [F]
多凭证并存按序选一：① 云提供商（`CLAUDE_CODE_USE_BEDROCK/_VERTEX/_FOUNDRY`）→ ② `ANTHROPIC_AUTH_TOKEN`（Bearer）→ ③ `ANTHROPIC_API_KEY`（X-Api-Key，批准后）→ ④ `apiKeyHelper` → ⑤ `CLAUDE_CODE_OAUTH_TOKEN` → ⑥ `/login` 订阅 OAuth。
> 陷阱：有订阅但又设了 `ANTHROPIC_API_KEY` → key 批准后优先；若该 key 属过期组织会认证失败，需 `unset` 回退，`/status` 确认当前方法。Web/远程会话**只用 OAuth**，不读这些 env。

---

## 附：原始文档清单
- admin-setup：https://code.claude.com/docs/zh-CN/admin-setup
- authentication：https://code.claude.com/docs/zh-CN/authentication
- server-managed-settings：https://code.claude.com/docs/zh-CN/server-managed-settings
- settings：https://code.claude.com/docs/zh-CN/settings
- managed-mcp：https://code.claude.com/docs/zh-CN/managed-mcp
- auto-mode-config：https://code.claude.com/docs/zh-CN/auto-mode-config
- permission-modes：https://code.claude.com/docs/zh-CN/permission-modes
- permissions：https://code.claude.com/docs/zh-CN/permissions
- mcp：https://code.claude.com/docs/zh-CN/mcp
- costs / monitoring-usage / analytics / model-config / security：https://code.claude.com/docs/zh-CN/{costs,monitoring-usage,analytics,model-config,security}

> **文档之外才有的内容（无法从 code.claude.com 获取）**：完整组织角色权限矩阵（Primary Owner/Owner/Admin/Member/Billing 各能做什么）、SSO/SAML 字段、SCIM 属性映射、域名捕获流程 —— 均在《Claude Enterprise Administrator Guide》（claude.com）。`iam` / `identity-and-access-management` 页**不存在(404)**。