diff --git a/docs/reference/claude-code-enterprise-controls-zh.md b/docs/reference/claude-code-enterprise-controls-zh.md index 6e38651..ee9caeb 100644 --- a/docs/reference/claude-code-enterprise-controls-zh.md +++ b/docs/reference/claude-code-enterprise-controls-zh.md @@ -1,8 +1,26 @@ # Claude Code 企业管控体系(权限 · 分配 · 设置)阅读参考 -> 整理自 Claude 官方文档(中文):admin-setup / authentication / server-managed-settings / settings / managed-mcp / auto-mode-config。 +> 整理自 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。 +> 每条尽量标注来源:`[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 速查表收尾。 --- @@ -109,12 +127,18 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力: ## 3. 管理员、角色、座位、准入(admin-setup) -### 3.1 角色 [AU] -文档明确出现的角色来自 **Claude Console 侧**(邀请用户时分配): -- **Claude Code 角色**:只能创建 Claude Code API 密钥。 +### 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 密钥。 -> Enterprise 的「基于角色的权限(role-based permissions)」是一项能力点,完整角色清单(owner/admin/member 等)在《Enterprise Administrator Guide》,本组文档未逐项展开。**不要臆造完整角色表。** +**组织角色(仅确认存在 + 零散能力)**: +- 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 账户级别」的**管理控制台**配置。 @@ -131,6 +155,28 @@ 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 ` 或持久化 `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) @@ -228,6 +274,30 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力: ### 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 访问) @@ -271,10 +341,20 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力: - **不对称**:`allowManagedMcpServersOnly` 让用户/项目/本地 allow 失效(只受管 allow 生效),**但 deny 始终合并** → 用户**能为自己收紧、不能放宽**。与 `allowManagedPermissionRulesOnly` 是两个独立标志。 - **`allowAllClaudeAiMcps: true`**(v2.1.149+,仅托管源生效):让 claude.ai 连接器与 `managed-mcp.json` 共存;allow/deny 仍生效,但插件 server 仍禁止。 -### 7.5 凭据(重要安全约束)[MCP] -- **不要在 `env` 块放 API key/凭据**(机器上任何用户都能读该文件)。 -- 改用**按用户(per-user)**:`${VAR}` 环境变量扩展、OAuth 或 per-user headers、`headersHelper`(连接时动态生成凭据)。 -- (文档未出现「集中托管单一密钥」字段,均为 per-user —— 待确认是否他处提供。) +### 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] | 限制 | 用户看到 | @@ -331,13 +411,33 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力: --- -## 9. 用量 · 计费 · 审计 · 合规 [AS] +## 9. 用量 · 计费 · 审计 · 合规 [AS][$] -- **Usage monitoring**:OpenTelemetry 导出会话/工具/令牌(所有提供商)。 -- **Analytics dashboard**:每用户指标、贡献跟踪、排行榜(仅 Anthropic 提供商,入口 claude.ai/analytics/claude-code)。 -- **Cost tracking**:spend limits、rate limits、使用归属(仅 Anthropic);云提供商走 AWS Cost Explorer / GCP Billing / Azure Cost Management。 -- **审计/合规**:审计跟踪、Compliance API(Enterprise)、ZDR(Enterprise)、请求级审计(放 LLM gateway)。 -- **限制可用模型**:文档**没有**直接的「模型允许列表」设置键用于此(`availableModels` 是限制 `/model` 选择项);账户级限制等价手段是 LLM gateway 按敏感度路由 + 沙箱域名允许列表。 +### 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 按敏感度路由 + 沙箱域名白名单。 --- @@ -366,6 +466,159 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力: --- +## 附录 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 @@ -373,5 +626,9 @@ Claude Code 的企业管控可拆成三层 + 两条贯穿能力: - 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} -> 文档外链未展开、设计前建议再抓:《Claude Enterprise Administrator Guide》(完整角色清单、SSO/SAML 字段、SCIM 属性映射、域名捕获流程);`permission-modes` 页(auto-mode 在 Enterprise 的管理员启用开关)。 +> **文档之外才有的内容(无法从 code.claude.com 获取)**:完整组织角色权限矩阵(Primary Owner/Owner/Admin/Member/Billing 各能做什么)、SSO/SAML 字段、SCIM 属性映射、域名捕获流程 —— 均在《Claude Enterprise Administrator Guide》(claude.com)。`iam` / `identity-and-access-management` 页**不存在(404)**。