【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.mdAI 行为的统一说明书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_PROXYhttp://proxy.company.com:8080 export HTTP_PROXYhttp://proxy.company.com:8080 # 如果代理需要认证 export HTTPS_PROXYhttp://username:passwordproxy.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_UNAUTHORIZED0——这会完全禁用证书验证是安全漏洞。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/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 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 json6.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_RETRIES3 # 或者在容量波动时无限等待 export CLAUDE_CODE_RETRY_WATCHDOG1七、团队 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.com7.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 } }八、常见团队配置问题问题 1CLAUDE.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 等都 OKgit 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]\) REQUIRED2.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/settings.json提交 git 共享.local.json不提交放私有信息CLAUDE.md精简有效的项目指令用 rules/ 按路径拆分节省 Token权限allow/deny规则明确化deny优先模型控制availableModels白名单限制成本企业网络HTTPS_PROXYNODE_EXTRA_CA_CERTS绝不用TLS_REJECT_UNAUTHORIZED0CI/CDSecrets 注入 key或apiKeyHelper动态获取RETRY_WATCHDOG扛容量波动Onboarding提供模板文件 清单新人自助配置良好的团队配置本质上是把个人的最佳实践用配置文件的方式固化为团队标准。一次配置好所有人受益。参考Claude Code 官方配置文档、官方团队协作指南、社区.claude目录配置实战、企业 CI/CD 集成案例。
