Claude Code 完全指南：从安装到精通（2026 版）

订阅方案#

2.1 macOS / Linux（推荐）#

原生安装器是 Anthropic 官方推荐的方式，一行命令，无需 Node.js：

1
curl -fsSL https://claude.ai/install.sh | bash

安装完成后关闭终端并重新打开，使 PATH 生效。

2.2 Windows#

Windows 支持三种安装方式：

方式一：PowerShell（推荐）

确保已安装 Git for Windows，然后在 PowerShell 中执行：

1
irm https://claude.ai/install.ps1 | iex

Claude Code 在 Windows 上通过 Git Bash 执行命令。如果 Git 未安装，安装器会提示你先安装。

方式二：Git Bash

在 Git Bash 中使用与 macOS/Linux 相同的命令：

1
curl -fsSL https://claude.ai/install.sh | bash

方式三：WSL（Windows Subsystem for Linux）

1
wsl --install          # 安装 WSL2 + Ubuntu
2
# 进入 WSL 后执行
3
curl -fsSL https://claude.ai/install.sh | bash

2.3 其他安装方式#

1
# Homebrew（macOS/Linux）
2
brew install --cask claude-code
3

4
# WinGet（Windows）
5
winget install Anthropic.ClaudeCode
6

7
# npm（已废弃，但仍可用，需要 Node.js 18+）
8
npm install -g @anthropic-ai/claude-code

2.4 安装验证#

1
claude --version    # 确认版本号
2
claude doctor       # 自动检测配置问题并给出修复建议

如果出现 command not found: claude，说明 PATH 未更新：

1
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
2
source ~/.bashrc

Windows 用户如果遇到路径问题，可以在 PowerShell Profile 中设置：

1
$env:CLAUDE_CODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"

3.1 官方 OAuth 认证#

首次运行 claude 会自动打开浏览器进行 OAuth 认证，登录你的 Claude 账户即可。这是最简单的方式，适合有 Pro/Max 订阅的用户。

如果浏览器无法自动打开，按 c 键复制 OAuth URL 手动在浏览器中打开。

3.2 API Key 认证#

对于 CI/CD、无头服务器或偏好按量付费的用户，可以通过环境变量提供 API Key：

1
export ANTHROPIC_API_KEY="sk-ant-..."
2
claude

也可以在 ~/.claude/settings.json 的 env 字段中配置（详见第 4 节）。

3.3 第三方 API 代理配置（重点）#

对于使用第三方 API 中转服务的用户，需要配置以下环境变量：

在 ~/.claude/settings.json 中配置：

1
{
2
  "env": {
3
    "ANTHROPIC_AUTH_TOKEN": "sk-your-token",
4
    "ANTHROPIC_BASE_URL": "https://api.690990.xyz",
5
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
6
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
7
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
8
  }
9
}

关键步骤：跳过引导流程

Claude Code 首次启动时会强制运行引导向导（选择登录方式、打开浏览器认证）。即使你已经配置了 API Token，只要 hasCompletedOnboarding 不为 true，引导流程就会阻断启动。

编辑 ~/.claude.json（注意不是 ~/.claude/settings.json），添加：

1
{
2
  "hasCompletedOnboarding": true
3
}

如果你使用的 API 代理无法访问 claude.ai，WebFetch 工具的域名安全预检会失败。在 ~/.claude/settings.json 中添加：

1
{
2
  "skipWebFetchPreflight": true
3
}

你还可以通过 forceLoginMethod 强制指定登录方式，避免每次启动时的选择提示：

1
{
2
  "forceLoginMethod": "api-key"
3
}

3.4 其他云平台#

Claude Code 还支持 Amazon Bedrock（CLAUDE_CODE_USE_BEDROCK=1）、Google Vertex AI（CLAUDE_CODE_USE_VERTEX=1）和 Microsoft Foundry 等云平台的认证方式，通过各平台的 IAM/OIDC 体系接入。

4.1 配置文件层级#

Claude Code 采用分层配置架构，优先级从高到低：

Managed Settings 的路径因系统而异：

• Windows: C:\ProgramData\ClaudeCode\managed-settings.json
• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux: /etc/claude-code/managed-settings.json

另外还有一个状态文件 ~/.claude.json（注意路径不同），它存储运行时状态而非配置，包括 hasCompletedOnboarding、theme、OAuth 会话信息等。不要将两者混淆。

4.2 settings.json 核心字段#

1
{
2
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
  "model": "opus",
4
  "permissions": { "allow": [], "deny": [] },
5
  "env": {},
6
  "hooks": {},
7
  "skipWebFetchPreflight": false,
8
  "attribution": { "commits": true, "pullRequests": true },
9
  "spinnerTipsEnabled": true,
10
  "alwaysThinkingEnabled": false
11
}

4.3 CLAUDE.md 指令文件#

CLAUDE.md 是用自然语言编写的项目指令文件，在每次会话启动时自动加载，即使上下文压缩也会保留。

加载层级：

编写原则：

• 保持在 200 行以内（约 2500 tokens），过长会导致重要指令被忽略
• 包含：项目概览、构建/测试命令、架构要点、代码风格约定
• 用 /init 命令自动生成初始版本，再手动精简
• 复杂规则拆分到 .claude/rules/*.md 中模块化管理

4.4 权限模式#

Claude Code 提供四种权限模式，按 Shift+Tab 循环切换：

[!DANGER]

bypassPermissions 模式会跳过所有安全确认，包括删除文件、执行危险命令等。仅在可丢弃的环境中使用（如 Docker 容器、临时分支），且务必配合 Git 版本控制。

4.5 allowedTools / blockedTools 精细控制#

权限系统支持三级规则，评估顺序为：deny → allow → ask。deny 始终优先。

1
{
2
  "permissions": {
3
    "allow": [
4
      "Read",
5
      "Edit",
6
      "Glob",
7
      "Grep",
8
      "Bash(npm run *)",
9
      "Bash(git status)",
10
      "WebSearch",
11
      "mcp__github__*"
12
    ],
13
    "deny": [
14
      "Bash(rm -rf *)",
15
      "Bash(git push --force *)",
16
      "Read(**/.env)"
17
    ]
18
  }
19
}

通配符语法：

4.6 交互式权限管理#

在 Claude Code 中输入 /permissions 即可打开交互式权限管理器，实时添加、修改或删除规则，无需手动编辑 JSON 文件。

当 Claude Code 请求权限时，你也可以选择 Always allow 将该工具永久加入允许列表。

5.1 Hooks：确定性的自动化#

Hooks 是在 Claude Code 生命周期特定节点自动执行的 Shell 命令。与提示词不同，Hooks 保证执行 — 你不需要”希望” Claude 记得格式化代码，PostToolUse Hook 会在每次文件写入后自动运行。

截至 2026 年 2 月，Hooks 系统支持 14 种生命周期事件和 3 种处理器类型（command、prompt、agent）。最常用的是：

PreToolUse 退出码：

• 0 — 允许操作
• 2 — 拦截操作（stderr 内容会反馈给 Claude）
• 其他非零 — 非阻塞错误，显示给用户

5.2 实战示例#

自动格式化（PostToolUse）：

1
{
2
  "hooks": {
3
    "PostToolUse": [{
4
      "matcher": "Write|Edit",
5
      "hooks": [{
6
        "type": "command",
7
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null; exit 0"
8
      }]
9
    }]
10
  }
11
}

阻止危险命令（PreToolUse）：

1
{
2
  "hooks": {
3
    "PreToolUse": [{
4
      "matcher": "Bash",
5
      "hooks": [{
6
        "type": "command",
7
        "command": "if echo \"$TOOL_INPUT\" | grep -qE 'rm -rf|git reset --hard|git push --force'; then echo 'Blocked dangerous command' >&2; exit 2; fi"
8
      }]
9
    }]
10
  }
11
}

配置方式有两种：在 Claude Code 中输入 /hooks 使用交互式菜单，或直接编辑 settings.json。

5.3 MCP：Model Context Protocol#

MCP 是 Anthropic 开发的开放标准，为 AI 工具连接外部系统提供统一的中间件协议。截至 2026 年 2 月，生态中已有超过 200 个 MCP 服务器。

在 settings.json 中配置 MCP 服务器：

1
{
2
  "mcpServers": {
3
    "github": {
4
      "command": "npx",
5
      "args": ["-y", "@modelcontextprotocol/server-github"],
6
      "env": {
7
        "GITHUB_TOKEN": "ghp_..."
8
      }
9
    }
10
  }
11
}

MCP 工具的命名规则为 mcp__<服务器名>__<工具名>，可在权限系统中使用通配符控制访问：

1
{
2
  "permissions": {
3
    "allow": ["mcp__github__*"],
4
    "deny": ["mcp__github__delete_*"]
5
  }
6
}

5.4 MCP Tool Search#

当你配置了大量 MCP 服务器时，工具定义会占用大量上下文窗口。MCP Tool Search 功能通过按需动态加载工具来解决这个问题，最高可减少 95% 的上下文消耗。当工具描述超过上下文窗口的 10% 时，Claude Code 会自动启用此功能。

5.5 推荐配置与最佳实践#

入门三件套： GitHub、Brave Search、Playwright — 这三个 MCP 服务器覆盖了 90% 的开发需求。

最佳实践：

• Hooks 用于必须执行的操作（格式化、lint、安全检查）
• MCP 用于扩展能力（数据库查询、浏览器自动化、外部 API）
• PreToolUse Hooks 优先用于安全策略，PostToolUse 用于清理和反馈
• 用 claude --debug 调试 Hooks 执行
• MCP 权限精确到工具级别，避免使用 mcp__*__* 全放行

6.1 常用斜杠命令#

6.2 键盘快捷键#

6.3 子代理与自定义代理#

子代理（Subagent）是运行在独立上下文窗口中的专业 AI 助手。Claude Code 内置两个子代理：

• Explore — 文件发现和代码搜索，保持主对话上下文整洁
• Plan — Plan Mode 下的调研代理

你可以在 .claude/agents/ 目录下创建自定义代理，用 YAML 前置元数据和 Markdown 正文定义：

1
---
2
name: code-reviewer
3
description: Reviews code for quality, security, and maintainability
4
tools: [Read, Grep, Glob, Bash]
5
model: sonnet
6
---
7

8
You are an expert code reviewer. Review code for:
9
- Security vulnerabilities
10
- Performance issues
11
- Code style consistency
12
...

• 用户级代理 → ~/.claude/agents/（所有项目可用）
• 项目级代理 → .claude/agents/（仅当前项目，项目级覆盖用户级同名代理）

对于需要多个代理并行协作的场景，可以使用 Agent Teams 功能（需设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）。

6.4 Skills 技能系统#

Skills 是 Claude 自动调用的能力扩展，定义在 .claude/skills/ 中，每个 Skill 包含一个 SKILL.md 描述文件。与斜杠命令不同，Skills 由 Claude 根据上下文自动匹配触发，也可通过 /skill-name 手动调用。

6.5 IDE 集成#

VS Code 扩展（推荐）：

在扩展市场搜索 “Claude Code” 安装。提供原生图形化界面，主要特性：

• @ 引用文件并指定行范围（如 @app.ts#5-10）
• 多标签页并行对话
• Checkpoint 回退系统（悬停消息点击 rewind）
• @terminal:name 引用终端输出

快捷键：Cmd+Esc / Ctrl+Esc 在编辑器和 Claude 之间切换焦点。

JetBrains 插件：

Settings → Plugins → Marketplace → 搜索 “Claude Code”。核心优势是编辑建议直接在 JetBrains 原生 Diff 视图中展示。

CLI + IDE 混合使用：

在外部终端运行 claude 后，输入 /ide 连接到当前打开的 IDE。推荐使用 VS Code 扩展处理日常开发和 Diff 审查，CLI 处理 MCP 配置、高级命令和自动化管道。

7.1 ~/.claude.json — 跳过引导#

1
{
2
  "hasCompletedOnboarding": true
3
}

由于我使用第三方 API 代理，无法完成官方的浏览器 OAuth 流程。手动设置 hasCompletedOnboarding 跳过引导向导，直接通过环境变量中的 Token 认证。

7.2 settings.json — 核心配置#

环境变量：

1
{
2
  "env": {
3
    "ANTHROPIC_AUTH_TOKEN": "sk-your-token",
4
    "ANTHROPIC_BASE_URL": "https://api.mechat.top",
5
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
6
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 64000,
7
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
8
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-opus-4-6",
9
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
10
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-haiku-4-5"
11
  }
12
}

逐项说明：

精细权限控制：

1
{
2
  "permissions": {
3
    "allow": [
4
      "Read",
5
      "Edit",
6
      "Glob",
7
      "Grep",
8
      "Bash(npm run *)",
9
      "Bash(git status)",
10
      "WebSearch",
11
      "mcp__github__*"
12
    ],
13
    "deny": [
14
      "Bash(rm -rf *)",
15
      "Bash(git push --force *)",
16
      "Read(**/.env)"
17
    ]
18
  }
19
}

设计思路：

• 允许 npm run * — 所有 npm 脚本（构建、测试、lint）无需确认
• 允许 git commit * — 提交操作自动放行
• 允许 git * main — 主分支相关的 Git 操作（如 git merge main、git rebase main）
• 允许 * --version — 任何工具的版本检查
• 拒绝 git push * — 推送操作必须由我手动执行，防止意外推送到远程

这个策略的核心原则是：本地操作自动化，远程操作手动控制。

WebFetch 预检跳过：

1
{
2
  "skipWebFetchPreflight": true
3
}

因为我的网络环境无法直接访问 claude.ai 的域名安全检查 API，设置此项跳过预检。配合权限系统中对 WebFetch 的域名限制使用，保持安全性。

7.3 CLAUDE.md 编写参考#

1
## Project Overview
2
[1-2 句项目简介]
3

4
## Commands
5
- **Dev:** `pnpm dev`
6
- **Build:** `pnpm build`
7
- **Test:** `pnpm test`
8
- **Lint:** `pnpm lint`
9

10
## Architecture
11
[关键目录说明、技术栈、路径别名]
12

13
## Code Style
14
- [格式化工具与规则]
15
- [命名约定]
16
- [提交规范]
17

18
## Key Decisions
19
- [为什么选择 X 而不是 Y]
20
- [已知限制和注意事项]

编写心得：

• 不要照搬文档，只写 Claude 需要但无法从代码中推断的信息
• 构建命令必须写，这是 Claude 执行操作的基础
• 代码风格约定写明即可避免反复纠正
• 犯过的错误写进去，防止 Claude 重蹈覆辙
• 定期清理过时内容，保持精简

7.4 配置心得#

1. 优先使用项目级配置（.claude/settings.json）而非全局配置，不同项目可以有不同的权限和 Hooks 策略
2. 敏感信息放在 settings.local.json 中，它不会被提交到 Git
3. 在 70% 上下文使用率时主动执行 /compact，不要等到自动压缩（性能在 80% 后明显下降）
4. 将研究密集型任务委派给子代理，它们有独立的上下文窗口，不会污染主对话
5. 每个不相关的任务启动新会话，用 /clear 保持上下文清洁