学习目标:掌握 Claude Code 在 macOS / Linux / Windows 三大平台的完整安装流程,理解
settings.json四层配置作用域,精通权限规则语法与六种权限模式,学会用 Hooks 扩展安全边界,最终为团队构建一套可复现、可管控的 Claude Code 开发环境。适用人群:刚接触 Claude Code 的开发者、需要在团队中推行 AI 编码工具的技术负责人、关注安全合规的 DevOps 工程师。
| 项目 | 最低要求 |
|---|---|
| 操作系统 | macOS 13.0+、Ubuntu 20.04+、Debian 10+、Alpine 3.19+、Windows 10 1809+ |
| 硬件 | 4 GB+ RAM,x64 或 ARM64 处理器 |
| 网络 | 需要互联网连接(支持 HTTP 代理) |
| Shell | Bash / Zsh / PowerShell / CMD |
| 地区 | Anthropic 支持的国家或地区 |
| 可选依赖 | Git(强烈推荐)、Node.js 18+(仅 npm 安装方式需要) |
flowchart TD
A[选择安装方式] --> B{你的平台?}
B -->|macOS / Linux / WSL| C[Native Install 推荐]
B -->|macOS| D[Homebrew]
B -->|Windows 原生| E[WinGet / PowerShell]
B -->|需要版本锁定| F[npm 安装]
C --> C1["curl -fsSL https://claude.ai/install.sh | bash"]
D --> D1["brew install --cask claude-code"]
E --> E1["winget install Anthropic.ClaudeCode"]
F --> F1["npm install -g @anthropic-ai/claude-code"]
C1 --> G[✅ 自动后台更新]
D1 --> H[⚠️ 需手动 brew upgrade]
E1 --> H
F1 --> I[⚠️ 需手动 npm update]
style C fill:#d4edda,stroke:#28a745
style G fill:#d4edda,stroke:#28a745
macOS / Linux / WSL:
curl -fsSL https://claude.ai/install.sh | bash
Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
Windows CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
自动更新:Native 安装会在后台自动更新,保持最新版本。这是 Anthropic 官方推荐的方式。
# 稳定版(约滞后一周,跳过有重大回归的版本)
brew install --cask claude-code
# 最新版(发布即更新)
brew install --cask claude-code@latest
# 手动更新
brew upgrade claude-code
winget install Anthropic.ClaudeCode
# 手动更新
winget upgrade Anthropic.ClaudeCode
Windows 原生 vs WSL:如果项目在 Windows 文件系统上用原生安装;项目在 Linux 文件系统上用 WSL。原生 Windows 不支持沙箱功能,WSL 支持完整功能集。
npm install -g @anthropic-ai/claude-code
# 安装特定版本
npm install -g @anthropic-ai/[email protected]
# 锁定最低版本(package.json)
"@anthropic-ai/claude-code": ">=1.0.25"
# Debian / Ubuntu
curl -fsSL https://claude.ai/install.sh | bash # 自动检测 apt
# Fedora / RHEL
curl -fsSL https://claude.ai/install.sh | bash # 自动检测 dnf
# Alpine
curl -fsSL https://claude.ai/install.sh | bash # 自动检测 apk
claude --version
预期输出:
Claude Code v1.0.xx
flowchart LR
A[认证方式选择] --> B[Anthropic Account<br/>默认 · 最简单]
A --> C[API Key<br/>适合企业用户]
A --> D[Amazon Bedrock<br/>AWS 用户]
A --> E[Google Vertex AI<br/>GCP 用户]
A --> F[Azure Foundry<br/>微软云用户]
B --> B1[浏览器登录]
C --> C1["export ANTHROPIC_API_KEY=sk-..."]
D --> D1[配置 AWS credentials]
E --> E1[配置 gcloud auth]
F --> F1[配置 Azure credentials]
claude
# 首次启动自动引导浏览器登录
export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude
持久化到 Shell 配置:
# ~/.bashrc 或 ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.zshrc
source ~/.zshrc
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
claude
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=my-project-id
gcloud auth application-default login
claude
| 问题 | 原因 | 解决方案 |
|---|---|---|
Authentication failed |
API Key 过期或无效 | 检查 Key 前缀是否为 sk-ant- |
Rate limit exceeded |
账户配额耗尽 | 升级计划或等待重置 |
Country not supported |
地区不在支持列表 | 使用代理或 API Key 方式 |
npm install 权限错误 |
全局目录不可写 | 使用 Native Install 或修复 npm prefix |
Claude Code 的配置系统类似 CSS 层叠规则——更具体的设置总是覆盖更一般的。
flowchart BT
A["User 作用域<br/>~/.claude/settings.json<br/>个人全局偏好"] --> B["Project 作用域<br/>.claude/settings.json<br/>团队共享配置"]
B --> C["Local 作用域<br/>.claude/settings.local.json<br/>个人项目覆盖"]
C --> D["Managed 作用域<br/>最高优先级 · 不可覆盖<br/>企业 IT 部署"]
D --> E["命令行参数<br/>临时会话覆盖"]
style D fill:#f8d7da,stroke:#dc3545
style E fill:#fff3cd,stroke:#ffc107
| 作用域 | 文件位置 | 影响范围 | 是否共享 |
|---|---|---|---|
| Managed | 服务器/MDM/注册表 | 所有用户 | IT 部署,不可覆盖 |
| User | ~/.claude/settings.json |
你的所有项目 | 不共享 |
| Project | .claude/settings.json |
项目所有协作者 | 提交到 Git |
| Local | .claude/settings.local.json |
仅你在此项目 | Git 自动忽略 |
命令行参数 > Managed > Local > Project > User
示例:如果 User 设置 spinnerTipsEnabled: true,Project 设置 spinnerTipsEnabled: false,最终生效的是 false(Project 覆盖 User)。
步骤 1:创建全局用户配置
// ~/.claude/settings.json
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(git log:*)",
"Bash(git diff:*)",
"Bash(git status:*)",
"Bash(npm test:*)",
"Bash(npm run lint:*)"
],
"deny": [
"Bash(rm -rf /*)",
"Bash(rm -rf ~/*)"
]
},
"spinnerTipsEnabled": true,
"preferredNotifChannel": "iterm2"
}
步骤 2:创建项目级团队配置
// .claude/settings.json(提交到 Git)
{
"permissions": {
"allow": [
"Bash(npm run build:*)",
"Bash(npm run test:*)",
"Bash(docker compose:*)",
"Edit",
"Write"
],
"deny": [
"Bash(rm -rf:*)"
]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $CLAUDE_FILE_PATH"
}
]
}
]
}
}
步骤 3:创建个人本地覆盖
// .claude/settings.local.json(不提交 Git)
{
"permissions": {
"allow": [
"Bash(kubectl:*)",
"Bash(aws:*)"
]
},
"model": "claude-sonnet-4-6"
}
Claude Code 提供六种权限模式,通过 defaultMode 或 CLI 标志控制:
| 模式 | 说明 | 适用场景 |
|---|---|---|
default |
标准模式:首次使用工具时逐个确认 | 新手入门、安全优先 |
acceptEdits |
自动接受文件编辑和常见文件系统命令(mkdir, touch, mv, cp) | 日常开发 |
plan |
Plan Mode:只读探索,不修改源文件 | 代码审查、架构调研 |
auto |
自动批准工具调用,后台验证动作是否与请求一致 | 自主编码(研究预览) |
dontAsk |
自动拒绝未预批准的工具调用 | CI/CD 流水线 |
bypassPermissions |
跳过所有权限提示(根目录/主目录删除仍需确认) | 容器/VM 隔离环境 |
设置方式:
// settings.json
{
"defaultMode": "acceptEdits"
}
# CLI 临时覆盖
claude --mode auto
claude --dangerously-skip-permissions # 等同于 bypassPermissions
权限规则格式:Tool 或 Tool(specifier)
规则求值顺序:deny → ask → allow,最先匹配的规则生效,所以 deny 永远优先。
flowchart LR
A[工具调用请求] --> B{匹配 deny?}
B -->|是| C[❌ 拒绝/隐藏]
B -->|否| D{匹配 ask?}
D -->|是| E[🔔 弹出确认]
D -->|否| F{匹配 allow?}
F -->|是| G[✅ 自动批准]
F -->|否| E
style C fill:#f8d7da,stroke:#dc3545
style G fill:#d4edda,stroke:#28a745
style E fill:#fff3cd,stroke:#ffc107
{
"permissions": {
"allow": ["Bash"],
"deny": ["WebFetch"]
}
}
Bash → 允许所有 Bash 命令WebFetch → 完全禁止网页抓取(工具从上下文中移除){
"permissions": {
"allow": [
"Bash(npm run build)",
"Bash(npm test)",
"Bash(git commit*)",
"Read(./src/**)",
"WebFetch(domain:docs.python.org)"
],
"deny": [
"Bash(rm -rf *)",
"Read(./.env)",
"Edit(./.env)"
]
}
}
| 规则 | 效果 |
|---|---|
Bash(npm run build) |
精确匹配该命令 |
Bash(git commit*) |
通配符匹配所有 git commit 变体 |
Read(./src/**) |
允许读取 src 下所有文件 |
WebFetch(domain:docs.python.org) |
仅允许抓取指定域名 |
Read(./.env) |
禁止读取 .env 文件 |
复合命令:&&、||、;、| 连接的命令,每部分独立匹配。
{
"permissions": {
"allow": ["Bash(npm run build)"],
"deny": ["Bash(rm *)"]
}
}
npm run build && rm -rf dist → 被拒绝(rm 部分匹配 deny 规则)。
进程包装器:npx、bunx 等会检查实际执行的子命令。
{
"permissions": {
"allow": ["Bash(npx jest)"]
}
}
npx jest → 允许。npx rm -rf / → 拒绝。
只读命令:以下命令无需权限确认:
- cat, head, tail, ls, find, grep, rg, wc, sort, uniq
- git log, git diff, git status, git branch --list
- echo, pwd, which, env
| 工具 | specifier 示例 | 说明 |
|---|---|---|
Read |
Read(./src/**) |
文件读取 |
Edit |
Edit(./src/**/*.ts) |
文件编辑 |
Write |
Write(./dist/**) |
文件写入 |
WebFetch |
WebFetch(domain:api.example.com) |
网页抓取 |
Agent |
Agent |
子代理 |
MCP(server:tool) |
MCP(github:create_issue) |
MCP 工具 |
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(npm *)",
"Bash(node *)",
"Bash(npx *)",
"Bash(git *)",
"Edit",
"Write"
],
"deny": [
"Bash(rm -rf *)",
"Bash(sudo *)",
"Read(./.env.production)",
"Edit(./.env.production)"
]
}
}
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(git log*)",
"Bash(git diff*)",
"Bash(git show*)"
],
"deny": [
"Edit",
"Write",
"Bash"
]
},
"defaultMode": "plan"
}
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Edit",
"Write",
"Bash(npm *)",
"Bash(git *)"
]
},
"defaultMode": "dontAsk"
}
Hooks 允许你在 Claude Code 执行工具操作前后运行自定义脚本,实现权限系统无法覆盖的精细控制。
sequenceDiagram
participant U as 用户
participant C as Claude Code
participant H as Hook 脚本
participant T as 工具
U->>C: 发起请求
C->>C: 准备调用工具
C->>H: PreToolUse Hook
H-->>C: approve / deny / 修改参数
alt Hook 批准
C->>T: 执行工具
T-->>C: 返回结果
C->>H: PostToolUse Hook
H-->>C: 处理完成
else Hook 拒绝
C-->>U: 报告被拒绝
end
C->>H: Notification Hook(异步通知)
C->>H: Stop Hook(会话结束时)
| Hook 类型 | 触发时机 | 用途 |
|---|---|---|
PreToolUse |
工具调用前 | 拦截、修改、记录 |
PostToolUse |
工具调用后 | 格式化、验证、通知 |
Notification |
通知事件时 | 桌面通知、Webhook |
Stop |
会话结束时 | 清理、汇总 |
Hook 脚本执行时自动获得以下环境变量:
| 变量 | 说明 |
|---|---|
$CLAUDE_TOOL_NAME |
被调用的工具名称 |
$CLAUDE_FILE_PATH |
操作的文件路径(Read/Edit/Write) |
$CLAUDE_SESSION_ID |
当前会话 ID |
$CLAUDE_COMMAND |
Bash 命令内容 |
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
}
]
}
]
}
}
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "case \"$CLAUDE_FILE_PATH\" in *.env*|*secret*|*credential*) exit 2;; *) exit 0;; esac"
}
]
}
]
}
}
exit 2 = 拒绝操作,exit 0 = 批准,exit 1 = 错误。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo \"[$(date -Iseconds)] BASH: $CLAUDE_COMMAND\" >> ~/.claude/audit.log"
}
]
}
]
}
}
flowchart TD
ROOT[".claude/ 目录"] --> A["settings.json<br/>团队共享配置(提交 Git)"]
ROOT --> B["settings.local.json<br/>个人本地配置(Git 忽略)"]
ROOT --> C["CLAUDE.md<br/>项目级指令文件"]
ROOT --> D["commands/<br/>自定义斜杠命令"]
ROOT --> E["agents/<br/>自定义子代理"]
ROOT --> F["skills/<br/>自动触发技能"]
ROOT --> G["hooks/<br/>Hook 脚本文件"]
ROOT --> H["workflows/<br/>工作流脚本"]
ROOT --> I["memory/<br/>持久化记忆文件"]
ROOT --> J["worktrees/<br/>Git 工作树"]
style ROOT fill:#e7f3ff,stroke:#0066cc
style A fill:#d4edda,stroke:#28a745
style B fill:#fff3cd,stroke:#ffc107
# 方法 1:CLI 初始化
cd my-project
claude init
# 方法 2:手动创建
mkdir -p .claude/commands .claude/agents
touch .claude/settings.json
touch .claude/settings.local.json
echo ".claude/settings.local.json" >> .gitignore
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(npm *)",
"Bash(node *)",
"Bash(npx *)",
"Bash(git *)",
"Bash(docker *)",
"Edit",
"Write"
],
"deny": [
"Bash(rm -rf /*)",
"Bash(sudo *)",
"Bash(curl * | bash)"
]
},
"defaultMode": "acceptEdits",
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "case \"$CLAUDE_FILE_PATH\" in *.env*|*.key|*secret*) exit 2;; *) exit 0;; esac"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
]
},
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
对于需要集中管控的组织,Claude Code 支持 Managed Settings——最高优先级,不可被用户或项目配置覆盖。
| 平台 | 部署机制 |
|---|---|
| macOS | com.anthropic.claudecode managed preferences domain,通过 Jamf/Kandji 等 MDM 推送配置描述文件 |
| Windows | HKLM\SOFTWARE\Policies\ClaudeCode 注册表键,Settings 值包含 JSON(通过 GPO 部署) |
| Linux | /etc/claude-code/managed-settings.json 文件 |
| 服务器 | Anthropic Admin Console 远程推送 |
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(npm test*)",
"Bash(npm run lint*)",
"Edit",
"Write"
],
"deny": [
"Bash(sudo *)",
"Bash(rm -rf *)",
"Bash(curl * | bash)",
"Bash(chmod 777*)",
"WebFetch"
],
"disableBypassPermissionsMode": "disable",
"disableAutoMode": "disable"
},
"allowedModels": ["claude-sonnet-4-6"],
"blockSensitiveFiles": true
}
disableBypassPermissionsMode: "disable"确保任何用户都无法使用--dangerously-skip-permissions绕过权限。
假设你是一个 5 人前端团队的 Tech Lead,需要为团队搭建 Claude Code 环境。项目使用 React + TypeScript + npm。
每个团队成员执行:
# macOS
curl -fsSL https://claude.ai/install.sh | bash
# 验证
claude --version
claude
# 浏览器打开 → 登录 Anthropic 账户 → 完成认证
cd my-react-project
claude init
// .claude/settings.json
{
"permissions": {
"allow": [
"Read",
"Glob",
"Grep",
"Bash(npm *)",
"Bash(node *)",
"Bash(npx *)",
"Bash(git *)",
"Edit",
"Write"
],
"deny": [
"Bash(rm -rf *)",
"Bash(sudo *)",
"Read(./.env.local)",
"Edit(./.env.production)"
]
},
"defaultMode": "acceptEdits",
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}
]
}
]
}
}
git add .claude/settings.json
git commit -m "feat: add shared Claude Code configuration"
git push
git pull
claude
# 尝试: "帮我修复 src/App.tsx 中的 TypeScript 错误"
# 预期: 自动格式化 + 无需手动确认编辑权限
flowchart TD
A[验证安装] --> B["claude --version ✅"]
B --> C[验证认证]
C --> D["启动 claude 无报错 ✅"]
D --> E[验证权限]
E --> F["尝试编辑文件 → 自动批准 ✅"]
F --> G[验证 Hooks]
G --> H["编辑文件后自动 prettier ✅"]
H --> I[验证安全]
I --> J["尝试 rm -rf → 被拒绝 ✅"]
J --> K[🎉 配置完成]
style K fill:#d4edda,stroke:#28a745
| 症状 | 排查命令 | 解决方案 |
|---|---|---|
command not found: claude |
which claude |
重新安装或检查 PATH |
npm EACCES |
npm config get prefix |
使用 Native Install 或修复 npm 全局目录权限 |
install.sh 校验失败 |
sha256sum $(which claude) |
重新下载安装脚本 |
| WSL 启动报错 | echo $WSL_DISTRO_NAME |
确保 WSL 2 + Ubuntu 20.04+ |
| 症状 | 原因 | 解决方案 |
|---|---|---|
| 每次都弹确认 | 未配置 allow 规则 |
添加到 permissions.allow |
| 配置了但还弹确认 | 规则语法错误 | 检查 specifier 是否精确匹配 |
| deny 规则不生效 | allow 在 deny 之前 | deny 始终优先——检查是否有拼写错误 |
| Hook 脚本不执行 | 脚本无执行权限 | chmod +x your-hook.sh |
# 查看当前所有生效的权限
claude /permissions
# 检查 settings.json 语法
cat .claude/settings.json | python3 -m json.tool
# 查看配置层级
echo "User: ~/.claude/settings.json"
echo "Proj: .claude/settings.json"
echo "Local: .claude/settings.local.json"
# 启动交互式会话
claude
# 指定模式启动
claude --mode plan # 只读计划模式
claude --mode auto # 自主模式
claude --mode acceptEdits # 自动接受编辑
# 非交互模式(管道/脚本)
claude -p "解释这个函数的作用" < src/utils.ts
echo "修复 lint 错误" | claude -p
# 会话管理
claude --resume # 恢复上次会话
claude --continue # 继续上次对话
# 更新
claude update # 手动检查更新
# 配置
claude config # 打开配置 UI
claude /permissions # 管理权限规则
# 版本信息
claude --version
claude --changelog
bypassPermissions 模式用于日常开发.claude/settings.local.json 加入 .gitignorerm -rf、sudo、curl | bash 等危险命令.env、*.key、*secret* 等敏感文件.claude/settings.json 中定义统一的权限基准[!tip] 51学通信知识星球 星主:爱卫生(微信:gprshome201101)——公众号「51学通信」创办者,19 年通信行业运维与讲师经验,著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书(各大电商平台有售)。 星球定位:深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域,主打运维岗位与信令分析。 当前规模:5200 篇主题 / 990 个回答,198 元/年。 加入福利:加入星球后请加爱卫生微信,拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题,另有群内分享。 AI 加持:51学通信知识星球已作为 skill 接入 WorkBuddy,使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例,做总结、找文档和 PPT 等场景全覆盖。
