【Claude】Claude Code 企业/团队环境完整配置指南

关键词：Claude Code、企业配置、团队协作、CLAUDE.md、settings.json、权限管理、availableModels、代理配置、共享配置、.claude 目录

一、企业/团队场景的核心挑战

个人用 Claude Code 很简单：装好、/login、开干。但放到企业或团队环境里，马上出现一堆新问题：

• 每个人都要手动配置一遍，格式还不统一；
• 有的人用了危险权限（--dangerously-skip-permissions），有的人什么都不配置；
• CLAUDE.md 各写各的，AI 的行为在每台机器上都不一样；
• 公司网络有代理、SSL 检测、防火墙，直接访问 API 不通；
• 管理员需要限制模型选择、控制费用；
• CI/CD 管道里也要接入 Claude Code，没有交互式登录。

本文从"配置文件体系"出发，把以上问题一一拆解，给出企业/团队可以直接落地的配置方案。

二、配置文件体系：.claude 目录全解析

Claude Code 的所有配置都围绕.claude目录展开，理解这个目录是企业配置的基础。

2.1 目录结构

~/.claude/ # 用户全局配置（个人机器） settings.json # 全局个人配置 settings.local.json # 本地私有（认证、敏感信息） 项目根目录/ CLAUDE.md # 项目核心指令（提交 git） .claude/ settings.json # 项目级配置（提交 git，团队共享） settings.local.json # 本地私有（不提交 git，写进 .gitignore） rules/ # 路径范围规则（模块化 CLAUDE.md） commands/ # 自定义斜杠命令 agents/ # 子代理定义

2.2 配置优先级（从高到低）

命令行 --model 等标志 ↓ ANTHROPIC_MODEL 等环境变量 ↓ .claude/settings.local.json（项目本地私有） ↓ .claude/settings.json（项目级，团队共享） ↓ ~/.claude/settings.json（用户全局）

团队配置的关键原则：

• 提交到 git 的配置（.claude/settings.json、CLAUDE.md）：放团队共享的设置，不含任何 key/密码；
• 不提交到 git 的配置（.claude/settings.local.json、~/.claude/settings.json）：放个人认证信息、本地路径等私有内容。

确保.gitignore里有：

.claude/settings.local.json

三、CLAUDE.md：AI 行为的统一说明书

CLAUDE.md是最重要的团队配置文件。它被 Claude Code 自动加载到每次会话的上下文，告诉 AI 这个项目是什么、应该怎么工作、有哪些限制。

3.1 一个实用的团队 CLAUDE.md 模板

# 项目名：XXX 后端服务 ## 技术栈 - 语言：TypeScript 5.x - 框架：NestJS 10 - 数据库：PostgreSQL 15 + Redis 7 - 测试：Jest + Supertest ## 代码规范 - 使用 ESLint + Prettier（配置见 .eslintrc.js） - 所有公共函数必须有 JSDoc 注释 - 变量、函数名用 camelCase，类名用 PascalCase - 禁止使用 any 类型，用 unknown + 类型守卫 ## 目录结构约定 - src/modules/：业务模块，每模块独立目录 - src/common/：公共工具、装饰器、过滤器 - src/config/：配置文件，不要在业务代码里 hardcode 配置 ## 禁止操作 - 不要直接修改 package.json 的依赖版本 - 不要改动 .env.example 以外的环境变量文件 - 不要在代码里硬编码任何密钥或连接字符串 - 不要执行 DROP TABLE 等破坏性 SQL - 提交前必须确保 npm run test 通过 ## 数据库操作 - 修改表结构只能通过 migration 文件 - 危险 SQL 操作前先备份或在 dry-run 模式下验证 ## Git 工作流 - 分支命名：feature/xxx、fix/xxx、refactor/xxx - 提交信息遵循 Conventional Commits 规范 - 不要直接 push 到 main/master ## 当前活跃任务 <!-- 可以在这里描述本阶段重点，让 AI 更快进入状态 -->

3.2 CLAUDE.md 最佳实践

按路径拆分（path-scoped rules）：全局 CLAUDE.md 只放项目级通用规范，具体模块的说明放到.claude/rules/下，按路径按需加载：

.claude/ rules/ backend.md # src/backend/ 下的规范 frontend.md # src/frontend/ 下的规范 database.md # 数据库操作规范

这样每次会话只加载相关规则，节省上下文 Token。

保持精简：CLAUDE.md 不是文档仓库，只写"AI 需要知道才能正确干活"的内容。超过 500 行通常是过度的。定期用/doctor检查是否过大。

四、settings.json：权限与行为配置

4.1 项目级配置（提交 git）

// 项目/.claude/settings.json { "model": "sonnet", "permissions": { "allow": [ "Bash(git *)", "Bash(npm run *)", "Bash(npx *)", "Bash(docker *)", "Read(**)", "Write(src/**)", "Write(tests/**)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force *)", "Bash(DROP *)", "Write(.env*)", "Write(package.json)" ] } }

权限规则说明：

• allow列表：明确允许，不再弹确认框；
• deny列表：直接拒绝，连提示都不出；
• 未在两个列表里的操作：默认弹框让用户确认。

4.2 限制可用模型（管理员控制成本）

通过availableModels白名单，让团队成员只能使用批准的模型：

{ "availableModels": ["claude-sonnet-4-5", "claude-haiku-4-5"], "model": "claude-sonnet-4-5" }

设置后，不在列表里的模型在/model选择器里不可见，通过--model或环境变量强制使用受限模型时会被替换。

4.3 用户全局配置（不提交，个人机器）

// ~/.claude/settings.json { "env": { "ANTHROPIC_API_KEY": "sk-ant-api03-...", "API_TIMEOUT_MS": "1200000", "NODE_EXTRA_CA_CERTS": "/Users/你的用户名/certs/company-ca.pem" } }

五、企业网络配置

5.1 公司代理

企业网络通常需要通过代理访问外网。在启动 Claude Code 的环境里设置：

export HTTPS_PROXY=http://proxy.company.com:8080 export HTTP_PROXY=http://proxy.company.com:8080 # 如果代理需要认证 export HTTPS_PROXY=http://username:password@proxy.company.com:8080

写进~/.claude/settings.json的env块永久生效：

{ "env": { "HTTPS_PROXY": "http://proxy.company.com:8080" } }

5.2 SSL/TLS 证书（企业 CA）

企业网络的 SSL 检测设备会替换证书，需要让 Node.js 信任公司的 CA：

{ "env": { "NODE_EXTRA_CA_CERTS": "/path/to/company-ca.pem" } }

绝对不要设置NODE_TLS_REJECT_UNAUTHORIZED=0——这会完全禁用证书验证，是安全漏洞。

5.3 自定义 API 网关 / LLM 中继

如果公司统一走内部 LLM 网关（常见于大型企业合规要求）：

{ "env": { "ANTHROPIC_BASE_URL": "https://llm-gateway.company.com/anthropic", "ANTHROPIC_API_KEY": "内部网关的key" } }

注意：网关需要转发anthropic-beta请求头，否则会触发Extra inputs are not permitted错误。

六、CI/CD 集成配置

6.1 基本原则

CI 环境无法交互式登录，需要通过环境变量或apiKeyHelper脚本注入认证信息。

推荐方式：GitHub Actions / GitLab CI 通过 Secrets 注入

GitHub Actions 示例：

# .github/workflows/claude-review.yml name: Claude Code Review on: pull_request: jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Install Claude Code run: npm install -g @anthropic-ai/claude-code - name: Run Claude Code task env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # 企业网络可能需要 HTTPS_PROXY: ${{ secrets.CORPORATE_PROXY }} NODE_EXTRA_CA_CERTS: /etc/ssl/certs/company-ca.pem run: | claude -p "审查这次 PR 的代码变更，重点检查安全问题和代码规范" \ --max-turns 5 \ --output-format json

6.2 apiKeyHelper（动态获取 key）

适合从 Vault、AWS Secrets Manager、1Password 等密钥管理系统动态获取 key：

// ~/.claude/settings.json（在 CI runner 上预置） { "apiKeyHelper": "/usr/local/bin/get-claude-key.sh" }

#!/bin/bash # /usr/local/bin/get-claude-key.sh # 从 AWS Secrets Manager 获取 key aws secretsmanager get-secret-value \ --secret-id claude-api-key \ --query SecretString \ --output text

确保脚本输出的第一行就是 key，没有多余的前缀或换行。

6.3 CI 专用重试配置

# 脚本里更快暴露失败 export CLAUDE_CODE_MAX_RETRIES=3 # 或者在容量波动时无限等待 export CLAUDE_CODE_RETRY_WATCHDOG=1

七、团队 onboarding 标准流程

把以下步骤整理成团队文档，让新人可以自助完成配置：

7.1 新人配置清单

□ 安装 Node.js 20+（推荐 nvm） □ npm install -g @anthropic-ai/claude-code □ 配置 ~/.claude/settings.json（从团队模板复制，填入个人 key） □ 如有企业代理：配置 HTTPS_PROXY + NODE_EXTRA_CA_CERTS □ 运行 /login 或确认 ANTHROPIC_API_KEY 已设置 □ 在项目目录下运行 /doctor 确认无配置错误 □ 验证：claude --version && curl -I https://api.anthropic.com

7.2 团队 settings.json 模板

提供一个settings.template.json，团队成员复制为~/.claude/settings.json并填入个人信息：

{ "_comment": "复制为 ~/.claude/settings.json，填入你的 key，不要提交到 git", "model": "sonnet", "env": { "ANTHROPIC_API_KEY": "在这里填入你的 API key", "HTTPS_PROXY": "http://proxy.company.com:8080", "NODE_EXTRA_CA_CERTS": "/path/to/company-ca.pem", "API_TIMEOUT_MS": "1200000" } }

八、常见团队配置问题

问题 1：CLAUDE.md 越写越大，影响性能

症状：上下文利用率一开始就很高，/context all显示 memory 占用很大。

解法：

• 用/doctor检查文件大小；
• 把不常用的规范移到.claude/rules/路径规则，只在相关目录加载；
• 删除 AI 其实不需要知道的内容（历史变更记录、详细的 API 文档——让 AI 直接读文档更好）。

问题 2：权限配置冲突（allow 和 deny 都能匹配）

当一个操作同时匹配allow和deny规则时，deny优先。

{ "permissions": { "allow": ["Bash(git *)"], // 允许所有 git 命令 "deny": ["Bash(git push *)"] // 但禁止 push // 结果：git status、git add 等都 OK，git push 被拦 } }

问题 3：项目配置不生效

检查你是否在正确的工作目录下启动 claude——Claude Code 从当前目录向上查找.claude/settings.json，不在项目目录下启动就找不到项目配置。

问题 4：团队成员用了不同版本的 Claude Code

建议在 CLAUDE.md 里写明建议版本，或者在 CI 里强制检查：

# CI 里验证版本 CLAUDE_VERSION=$(claude --version | grep -o '[0-9]\+\.[0-9]\+\.[0-9]\+') REQUIRED="2.1.100" if [ "$(printf '%s\n' "$REQUIRED" "$CLAUDE_VERSION" | sort -V | head -n1)" != "$REQUIRED" ]; then echo "Claude Code 版本过低，请运行 claude update" exit 1 fi

九、总结

企业/团队使用 Claude Code 的配置要点：

良好的团队配置本质上是"把个人的最佳实践，用配置文件的方式固化为团队标准"。一次配置好，所有人受益。

参考：Claude Code 官方配置文档、官方团队协作指南、社区.claude目录配置实战、企业 CI/CD 集成案例。