# Claude Code 企业网络与集中管控

> 配置 Claude Code 的代理、CA、mTLS、网络 allowlist、server-managed settings、endpoint-managed settings 和 managed MCP 策略。

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

企业环境通常要同时解决三件事:网络能连通、证书能信任、配置能被集中约束。Claude Code 支持标准代理变量、自定义 CA、mTLS、托管 settings 和 MCP 管控。接入 Passion8 时,还要区分 Anthropic 官方云端能力和第三方网关场景。




如果使用 `ANTHROPIC_BASE_URL=https://passion8.cc` 这类第三方网关,Anthropic 的 server-managed settings 通常不会生效。企业管控应优先用 MDM、系统 managed settings、本地 `settings.json` 模板或网关侧策略。




Provider 登录、云平台变量和网络排错见 Provider 认证与云平台接入。组织部署决策见 [企业部署总览](https://docs.passion8.cc/docs/claude-code/enterprise-deployment-overview)。网关上线验收见 [Gateway 协议上线清单](https://docs.passion8.cc/docs/claude-code/gateway-protocol)。组织级 server-managed settings、managed MCP、Auto mode、analytics、插件市场和合规清单见 [企业控制面与受管配置](https://docs.passion8.cc/docs/claude-code/enterprise-controls)。

## 代理配置

Claude Code 支持常见 HTTP 代理环境变量:

```bash
export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1,192.168.0.0/16,.example.com"
```

需要 Basic Auth 时可以写在 URL 中,但不建议把密码硬编码到脚本:

```bash
export HTTPS_PROXY=http://username:password@proxy.example.com:8080
```

Claude Code 不支持 SOCKS 代理。NTLM、Kerberos 等复杂代理认证通常要通过企业网关或代理适配层处理。

## CA 与 mTLS

默认情况下,Claude Code 会信任内置 Mozilla CA 和系统证书库。企业 TLS 检查代理如果已经把根证书安装进系统证书库,新版运行时通常可以直接工作。

只信任内置 CA:

```bash
export CLAUDE_CODE_CERT_STORE=bundled
```

只信任系统证书库:

```bash
export CLAUDE_CODE_CERT_STORE=system
```

额外 CA:

```bash
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```

mTLS:

```bash
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="passphrase"
```

这些变量可以放进 shell、用户 settings 的 `env` 或企业托管配置。若它们本身用于获取远端托管 settings,首启时不能只依赖 server-managed 的 `env` 下发。

如果问题发生在安装、PATH、下载、代理或 TLS 握手阶段,先看 [安装与登录排错](https://docs.passion8.cc/docs/claude-code/install-troubleshooting)。

## 网络 allowlist

官方 Anthropic 直连通常需要以下域名。接入 Passion8 时,模型流量主要走 `passion8.cc`,但安装、插件、release notes、Chrome bridge、Artifacts 等能力仍可能需要官方域名。

| 域名 | 用途 |
| --- | --- |
| `passion8.cc` | Passion8 网关、控制台和模型请求 |
| `api.anthropic.com` | Anthropic API、server-managed settings、WebFetch 安全检查 |
| `claude.ai` | Claude 账号登录、Web 入口 |
| `platform.claude.com` | Anthropic Console API Key 登录 |
| `downloads.claude.ai` | 原生安装器、插件可执行文件、自动更新 |
| `bridge.claudeusercontent.com` | Claude in Chrome WebSocket bridge |
| `*.claudeusercontent.com` | claude.ai 上的 Artifacts 查看 |
| `raw.githubusercontent.com` | Release notes、插件市场相关数据 |

如果你完全通过 npm、内部镜像或 Passion8 分发,终端用户不一定需要 `downloads.claude.ai`。如果禁用 WebFetch 的预检查或替换 Provider,还要确认你的合规要求是否允许。

## 集中 settings 的两种方式

| 方式 | 适合 | 安全属性 |
| --- | --- | --- |
| Server-managed settings | Claude Teams/Enterprise,无 MDM 或未管设备 | 从 Anthropic 服务端拉取,客户端执行 |
| Endpoint-managed settings | 有 MDM、注册表、系统配置文件 | OS/设备管理下发,更难被普通用户修改 |

server-managed settings 通过 claude.ai Admin Settings 配置,客户端启动和运行中定期拉取。endpoint-managed settings 通过 macOS managed preferences、Windows registry、Linux/系统文件或 MDM 下发。

使用 Passion8 或任何自定义 `ANTHROPIC_BASE_URL` 时,建议把关键约束放在 endpoint-managed settings 或本地模板里,因为官方 server-managed settings 不覆盖第三方 Provider 场景。

涉及请求保留、训练策略、本地 transcript、Telemetry、Feedback、WebFetch 安全检查和 Passion8 网关日志时,统一看 [数据使用与隐私](https://docs.passion8.cc/docs/claude-code/data-usage)。

## 管控示例

阻止绕过权限,并禁止读取常见敏感文件:

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

为 Auto mode 提供企业环境边界:

```json
{
  "autoMode": {
    "environment": [
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted artifact buckets: s3://acme-build-artifacts",
      "Trusted internal domains: *.corp.example.com"
    ]
  }
}
```

强制远端 settings 获取成功后才启动:

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

启用前要确认客户端能访问 `api.anthropic.com`。否则 Claude Code 会直接退出,用户无法进入会话。

## 缓存与安全确认

server-managed settings 的拉取逻辑有几个运维点:

- 启动时会异步拉取,有缓存时先应用缓存。
- 活跃会话会定期轮询更新。
- 解析失败时会尽量保留有效字段,并在调试日志里记录错误。
- hooks、自定义环境变量和托管 `CLAUDE.md` 这类高风险配置可能触发安全确认。
- 在非交互 `-p` 模式下,安全确认不会弹出,配置会直接应用。

如果要排查下发问题,让测试机运行:

```bash
claude --debug-file /tmp/claude-debug.log
```

然后搜索 remote settings、managed settings、validation 等关键词。

如果 settings、Hooks、MCP、Skills 或权限规则在客户端没有按预期出现,继续看 [配置调试与 .claude 目录](https://docs.passion8.cc/docs/claude-code/configuration-debugging)。

## Managed MCP

默认情况下,用户可以添加任意 MCP server。企业环境建议按风险选择策略:

| 策略 | 效果 | 配置方式 |
| --- | --- | --- |
| 禁用 MCP | 不加载任何 server | `managed-mcp.json` 空 server map |
| 固定部署 | 所有人只使用同一组 server | `managed-mcp.json` |
| Approved catalog | 用户可装批准列表中的 server | `allowedMcpServers` 加 `allowManagedMcpServersOnly` |
| 只允许插件 server | 禁止用户自定义 MCP | `strictPluginOnlyCustomization` |
| Denylist | 只封锁已知危险 server | `deniedMcpServers` |

`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` |

固定部署示例:

```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"]
    }
  }
}
```

不要把 API Key 写进这个文件。系统路径里的文件可能被本机用户读取。优先使用 `${VAR}` 展开、OAuth、per-user headers 或 `headersHelper`。

禁用 MCP:

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

验证:

```bash
claude mcp list
claude mcp add --transport http test https://example.com/mcp
```

第二条应被企业策略拒绝。

## Allowlist 与 Denylist

允许列表和拒绝列表可以按 URL、命令或名称匹配。强管控时,不要只按 `serverName` 匹配,因为用户可以重命名 server。

```json
{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://mcp.sentry.dev/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.untrusted.example.com/*" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] }
  ],
  "allowManagedMcpServersOnly": true
}
```

远程 MCP 优先用 `serverUrl`。stdio MCP 优先用完整 `serverCommand`。denylist 总是优先生效。

## Passion8 场景建议

- 本地开发者接入: 用 `ANTHROPIC_BASE_URL=https://passion8.cc` 和 `ANTHROPIC_AUTH_TOKEN` 或 CC-Switch 管理。
- 企业统一接入: 用 MDM 或系统 managed settings 下发 Base URL、权限 deny、沙箱和 MCP 策略。
- 需要远端策略: 如果不走 Anthropic 官方组织登录,不要依赖 Claude server-managed settings。
- 网关侧审计: 结合 Passion8 后台账单、日志和 [监控与分析](https://docs.passion8.cc/docs/claude-code/monitoring)。
- MCP 风险: 把外部 MCP 当作第三方代码执行入口评审,不要只看模型 Provider。

团队落地时,把本页作为管控能力参考,再按 [企业 rollout](https://docs.passion8.cc/docs/claude-code/enterprise-rollout) 的 30/60/90 天节奏推进 provider、settings、MCP、Auto mode、观测和培训。

## 相关页面



- [设置与环境变量](https://docs.passion8.cc/docs/claude-code/settings): 查看 Base URL、Token、settings 层级和环境变量优先级。
- [企业部署总览](https://docs.passion8.cc/docs/claude-code/enterprise-deployment-overview): 按 provider、认证、managed settings、权限和观测规划组织部署。
- [配置调试与 .claude 目录](https://docs.passion8.cc/docs/claude-code/configuration-debugging): 确认客户端实际加载了哪些 settings、Hooks、MCP、Skills 和权限。
- [MCP 工具接入](https://docs.passion8.cc/docs/claude-code/mcp): 配置 HTTP、SSE、stdio、OAuth 和作用域。
- [网关与协议](https://docs.passion8.cc/docs/claude-code/gateway): 理解 Passion8 Base URL、headers、模型发现和常见错误。
- [沙箱与隔离环境](https://docs.passion8.cc/docs/claude-code/sandboxing): 把权限策略和运行时隔离组合起来。
- [Sandbox 与 Dev Container](https://docs.passion8.cc/docs/claude-code/sandbox-devcontainers): Dev Container、自定义容器、VM、凭据保护和网络出口。