Claude Code

企业 rollout

Claude Code 企业推广、设置下发、MCP 管控、analytics、auto mode 和自定义网关约束的落地指南。

企业 rollout 的目标不是“让所有人都装上 Claude Code”,而是把 provider、身份、网络、权限、MCP、观测和支持链路一次性设计清楚。否则最常见的问题会集中在三类:用户能跑但不可控、策略下发了但没生效、账单和安全事件无法归因。

组织控制面、受管 settings、managed MCP、Auto mode、analytics 和合规清单见 企业控制面与受管配置。发布公告、champion、drip campaign 和 FAQ 口径见 组织推广与沟通套件

如果使用自定义 ANTHROPIC_BASE_URL、第三方 gateway 或 Passion8,Anthropic 的 server-managed settings 通常不会对模型请求路径上的网关策略生效。企业约束应优先放在 endpoint-managed settings、本地模板、MDM/registry、系统 managed-mcp.json 和网关 policy 里。

#Rollout 决策图

1. Provider / 身份
   ├─ Anthropic Team / Enterprise 直连?
   │  ├─ 是: 使用组织身份、SSO/SCIM、server-managed settings、analytics dashboard
   │  └─ 否: 使用 Passion8/custom gateway、企业 IdP、网关 key 映射和本地/端点策略
   └─ API Key 归属: 个人、团队服务账号、项目 token、短期 token

2. 网络
   ├─ 直连 api.anthropic.com / claude.ai / downloads.claude.ai?
   ├─ 走企业代理、TLS inspection、CA、mTLS?
   └─ 走 Passion8/custom gateway? 明确 Base URL、allowlist、重试、限流和日志边界

3. Settings 下发
   ├─ server-managed settings: 官方云端下发,适合 Anthropic 官方组织管控
   └─ endpoint-managed settings: MDM、注册表、系统文件、本地模板,适合强管控和自定义网关

4. 权限模型
   ├─ 默认权限: allow / ask / deny
   ├─ Auto mode: environment / allow / soft_deny / hard_deny
   └─ 禁止 bypass、限制敏感文件、限制危险 shell、隔离高风险项目

5. MCP
   ├─ 禁用、固定部署、批准目录、只允许插件、denylist
   ├─ managed-mcp.json 走系统路径,不能靠 server-managed settings 下发
   └─ OAuth、headersHelper、环境变量和 token 存储分开治理

6. 观测
   ├─ Adoption: 活跃用户、会话数、接受率、PR/代码贡献
   ├─ Cost: spend、token、模型、项目、团队、缓存命中
   ├─ Tools: Bash、Edit、MCP、Hooks、Auto mode 决策
   └─ Errors: 鉴权、网络、provider 4xx/5xx、工具失败、策略拒绝

7. 培训 / 支持
   ├─ 试点用户、冠军用户、项目模板、默认权限说明
   ├─ 常见排错: Base URL、Token、代理、CA、MCP、settings 合并
   └─ 支持队列: Slack/飞书、工单、升级路径、变更公告

#Settings 下发方式

方式生效来源适合场景关键限制
Server-managed settingsClaude 官方服务端,客户端启动和运行中拉取Anthropic Team / Enterprise 直连、未管设备、轻量统一配置依赖官方身份和官方端点;使用 custom ANTHROPIC_BASE_URL、第三方 gateway、Passion8 时通常不覆盖网关侧行为
Endpoint-managed settingsMDM、macOS managed preferences、Windows registry、Linux 系统文件、镜像模板企业管控设备、Passion8/custom gateway、强制安全策略需要设备管理或安装脚本;变更发布要走 IT 流程
本地模板~/.claude/settings.json、项目 .claude/settings.json、devcontainer 模板试点、小团队、项目级默认配置用户可能修改;不能作为唯一合规控制
网关 policyPassion8/custom gateway 的账户、模型、速率、日志、数据策略自定义 provider、统一计费、模型路由、token 约束只能控制经过网关的模型请求,不能直接控制本机 Bash、MCP 或文件读取

Server-managed settings 和 endpoint-managed settings 的核心差别是信任边界。前者从 Anthropic 官方云端拉取配置,适合官方组织身份和官方 provider;后者由企业设备管理或系统级文件下发,适合强制控制客户端行为,也更适合自定义 provider。

Passion8 场景建议把“能否访问模型、能用哪些模型、预算、限流、日志留存”放在网关 policy,把“本机能读什么、能运行什么命令、MCP 怎么装、Auto mode 边界”放在 endpoint-managed settings 和系统文件。

#Passion8 与 custom gateway

使用 Passion8 或自建 gateway 时,不要假设官方组织配置会自动套到第三方链路上。推荐落地方式:

控制面推荐做法
Base URL通过 endpoint-managed settings、环境模板或 shell profile 下发 ANTHROPIC_BASE_URL=https://passion8.cc
Token用企业密码库、MDM secret、短期 token 或用户自助领取;不要提交到项目仓库
模型和预算在 Passion8/custom gateway 做模型 allowlist、项目预算、团队限额、速率限制
协议兼容验证 tool use、prompt caching、streaming、model discovery、beta 字段和错误格式
审计网关日志按用户、团队、项目、token、模型和请求 ID 归因
回滚保留官方直连 profile 或备用 gateway,并明确切换变量和验证命令
export ANTHROPIC_BASE_URL="https://passion8.cc"
export ANTHROPIC_AUTH_TOKEN="sk-由企业或 Passion8 分发的 token"
claude -p "确认当前 provider、模型和基本工具可用"

第三方 gateway 的关键验收点:

验收项通过标准
请求路径Claude Code 请求不要多拼 /v1;网关能正确处理 Messages API
Streaming长输出不中断,错误能返回可读状态
Prompt cache缓存读写字段能透传或有明确替代策略
Tool use工具调用、MCP 工具引用和 tool result 不被网关破坏
Model picker如启用模型发现,/model 能看到网关允许的模型
错误归因401、403、429、5xx 能区分 token、权限、限流、上游故障

#Managed MCP 策略

Managed MCP 不能通过 server-managed settings 下发。它使用系统级 managed-mcp.json,由管理员、MDM、镜像、安装脚本或配置管理工具放到固定路径。

平台系统路径
macOS/Library/Application Support/ClaudeCode/managed-mcp.json
Linux / WSL/etc/claude-code/managed-mcp.json
WindowsC:\Program Files\ClaudeCode\managed-mcp.json
策略用法
禁用 MCPmcpServers 为空,适合高敏仓库或早期试点
固定部署只下发企业批准的 GitHub、Jira、数据库只读、文档检索 server
Approved catalog允许用户从批准列表安装,同时阻止任意 URL/stdio
Denylist阻止高风险 server、外部 unknown host、可执行任意命令的 stdio
Token 分离MCP 凭据走 OAuth、headersHelper、系统 keychain 或短期 token
{
  "mcpServers": {
    "github-enterprise": {
      "type": "http",
      "url": "https://github.example.com/mcp"
    },
    "docs-readonly": {
      "type": "stdio",
      "command": "/usr/local/bin/company-docs-mcp",
      "args": ["--readonly"]
    }
  }
}

MCP 的安全重点是“工具定义可信、凭据不落盘、输出可审计、写操作可拦截”。不要把 API Key 明文写入 managed-mcp.json;系统路径文件可能被本机用户读取。

#Analytics 与 telemetry

企业 rollout 至少要能回答五个问题:谁在用、花了多少钱、缓存是否有效、工具有没有越界、错误集中在哪里。

指标组推荐指标数据来源
Adoption活跃用户、活跃团队、会话数、任务类型、接受率、试点转正率Anthropic analytics、OpenTelemetry、内部调查、IDE/CLI 启动日志
Costspend、input/output token、模型分布、团队成本中心、单任务成本Anthropic Console、Passion8 控制台、网关日志、OTel metrics
Cachecache read/write token、5m/1h 命中、缓存失效原因、MCP 工具定义变化provider usage、网关日志、OTel、成本报表
ToolsBash/Edit/Read/WebFetch/MCP 调用量、拒绝次数、Hook 失败率、Auto mode 决策OTel logs/traces、Claude Code debug log、SIEM
Errors401/403/429/5xx、TLS/代理失败、MCP timeout、settings 拉取失败、策略 hard denygateway、OTel、helpdesk 工单、客户端 debug log
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.example.com:4317"
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,tool=claude-code"

默认不要打开 prompt、assistant response、tool content 或 raw API body 级别日志。这些内容可能包含源码、客户数据、密钥、工单内容和内部设计。需要排查协议问题时,只在隔离环境短期开启。

#Auto mode 企业配置

Auto mode 适合低风险、可回滚、边界清楚的开发任务。企业配置要同时定义环境、允许项、软拒绝项和硬拒绝项,并保留 "$defaults" 让官方默认安全规则继续生效。

{
  "autoMode": {
    "environment": [
      "Company source code lives under github.example.com/acme and approved internal GitLab groups.",
      "Production credentials are never available in developer workstations.",
      "Approved package registries are npm.corp.example.com and pypi.corp.example.com.",
      "Network egress goes through the corporate proxy and approved gateways."
    ],
    "allow": [
      "$defaults",
      "Read(./src/**)",
      "Read(./docs/**)",
      "Edit(./src/**)",
      "Edit(./tests/**)",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git diff *)"
    ],
    "soft_deny": [
      "Bash(npm install *)",
      "Bash(pip install *)",
      "WebFetch(*)",
      "mcp__jira__create_*"
    ],
    "hard_deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/*private_key*)",
      "Bash(curl * | sh)",
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "mcp__prod_database__write_*"
    ]
  }
}

soft_deny 用于需要人工确认或建议改走流程的操作,例如安装依赖、访问外网、创建工单。hard_deny 用于不允许模型尝试的操作,例如读取密钥、删除目录、推送代码、写生产数据库。

#安全基线

控制项要求
Devcontainer / sandbox高风险仓库默认在 devcontainer、VM、受限 worktree 或 sandbox 中运行;不要把生产凭据挂进容器
禁 bypass禁用 bypass permissions mode,避免用户一键绕过企业策略
敏感文件 deny拒绝 .env、密钥、证书、token、客户导出、生产 dump、云凭据目录
代理 / CA / mTLS统一代理变量、根证书、客户端证书和 allowlist;首启需要的网络不能只依赖远端 settings 下发
Token 管理使用短期 token、个人 token 或团队服务账号映射;支持吊销、轮换、最小权限和成本中心归因
ZDR 边界ZDR 只覆盖特定 provider 的数据保留承诺;不自动覆盖本地 transcript、MCP server、OTel、debug log、Passion8/custom gateway 日志或企业代理日志
更新与版本固定最低版本、发布窗口、回滚包和变更公告;新能力先在试点 ring 验证
支持提供 Base URL、Token、代理、CA、MCP、settings、Auto mode 的排错脚本和升级路径

Endpoint-managed settings 示例:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://passion8.cc",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.example.com:4317",
    "HTTPS_PROXY": "http://proxy.corp.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-root-ca.pem"
  },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./**/*private_key*)",
      "Bash(curl * | sh)",
      "Bash(rm -rf *)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true,
  "forceRemoteSettingsRefresh": false
}

如果机器必须离线或只能访问 Passion8/custom gateway,不要启用依赖 api.anthropic.com 的强制远端刷新。否则客户端可能在拿不到官方远端 settings 时直接阻断启动。

#30 / 60 / 90 rollout

阶段目标管控动作验收指标
0-30 天小范围试点,验证 provider、网络、权限和成本选 20-50 名试点用户;下发 Passion8/custom gateway profile;配置代理、CA、mTLS;禁 bypass;敏感文件 deny;MCP 默认禁用或只开放只读 server;开启基础 OTel安装成功率、首个任务成功率、401/403/429/5xx 分布、单用户日均成本、缓存读写是否出现、支持工单类型
31-60 天扩到核心工程团队,形成默认模板endpoint-managed settings 进入 MDM/registry;发布项目 .claude/settings.json 模板;引入 approved MCP catalog;Auto mode 只开放低风险 allow;建立 dashboard 和成本中心归因周活用户、任务完成率、工具拒绝率、MCP timeout、cache hit、团队成本、Top errors、用户培训完成率
61-90 天规模化推广,进入常态治理分 ring 发布版本;按团队启用更细 Auto mode;网关 policy 分层;token 自动轮换;ZDR/日志边界完成审计;支持手册和升级路径固定覆盖团队数、留存率、平均任务成本下降、严重安全事件为 0、策略命中可解释、回滚演练通过

#发布检查清单

检查项通过标准
Provider官方直连、Passion8 或 custom gateway 的身份、token、模型、预算和回滚路径已确认
网络代理、CA、mTLS、allowlist、离线安装和首启路径已验证
Settingsserver-managed 与 endpoint-managed 的职责分离明确;自定义网关场景不依赖 server-managed settings 作为唯一控制
权限deny 覆盖敏感文件和危险命令;禁 bypass;项目模板不含 token
MCPmanaged-mcp.json 已通过系统路径下发;凭据不写明文;写操作有策略
Auto modeautoMode.environmentallowsoft_denyhard_deny 已配置,且 allow 包含 "$defaults"
Observabilityadoption、cost、cache、tools、errors 有 dashboard 和告警
隐私ZDR、transcript、OTel、debug log、网关日志、代理日志的边界已写入内部说明
培训试点材料、常见排错、支持渠道、变更公告和升级路径已发布

#相关页面

Support / 支持

Need help? / 需要帮助?

接入、计费与模型异常可邮件联系;服务可用性以状态页为准。For setup, billing, or model issues, email us. Check the status page for uptime.

也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right