# Claude Code 基础使用完整指南：从启动到精通的实战手册

> **课程信息**
>
> - **作者**：老金
> - **GitHub**：https://github.com/KimYx0207
> - **公众号**：老金带你玩AI
> - **X（Twitter）**：老金带你玩AI
> - **个人博客**：https://aiking.dev
> - **预计学时**：4-6小时
> - **难度等级**：⭐ 零基础入门
> - **更新日期**：2026年6月18日
> - **适用版本**：Claude Code v2.1.181（验证于 2026-06-18；旧差量保留为历史基线）
> - **信息来源**：[官方文档](https://code.claude.com/docs) | [GitHub](https://github.com/anthropics/claude-code)
> - **前置要求**：已完成Claude Code安装

---

## 本课学习目标

老金在这篇里故意把第一份 CLAUDE.md 当成练习入口，因为新手要先学会让 AI 看懂项目，而不是一上来追复杂命令。

> **2026-06-18 操作口径**：本章继续讲交互、单次执行和打印模式三条主线。v2.1.181 后，交互态、`-p` 和 Remote Control 都可以使用 `/config key=value` 这类配置入口；配置是否生效仍以本机会话里的 `/status`、`/config` 和 `claude --version` 为准。Fable 5 / Mythos 5 相关变化只作为可关注项，不作为本教程默认模型推荐。

完成本课学习后，你将能够：

1. **理解三种使用模式**：掌握交互模式、单次执行、打印模式的适用场景
2. **熟练使用交互模式**：掌握REPL对话窗口的完整操作技巧
3. **精通30+个Slash命令**：熟练使用所有内置快捷指令
4. **掌握快捷键操作**：提升工作效率的键盘技巧
5. **配置个性化环境**：根据项目需求定制Claude Code
6. **独立排查问题**：使用诊断命令解决大多数常见问题

---

## 先做一个15分钟实操：写出第一份 `CLAUDE.md`

这章很长，但新手不需要先背命令表。先做一件最有价值的事：让 Claude Code 读懂你的项目规则。

`CLAUDE.md` 是 Claude Code 的项目说明书。它不只是备注文件，而是你告诉 Claude “这个项目怎么工作、怎么验证、哪些地方不要乱动”的地方。

### 第一步：进入你的项目目录并启动 Claude Code
```bash
cd 你的项目目录
claude
```

如果你只是想在当前仓库练习，也可以直接在本教程仓库里启动。

### 第二步：让 Claude 先只读分析项目

在 Claude Code 里输入：

```text
阅读这个项目，告诉我：
1. 这个项目是做什么的
2. 常用安装、启动、测试命令是什么
3. 哪些目录或文件最重要
4. 你建议写进 CLAUDE.md 的项目规则是什么

不要修改文件。
```

这一步的目的不是让 Claude 写代码，而是让它先建立项目地图。

### 第三步：创建最小可用的 `CLAUDE.md`

在项目根目录创建 `CLAUDE.md`，先写成这样：

```markdown
# CLAUDE.md

这份文件约束 Claude Code 在本项目里的工作方式，用来减少常见的 AI 编程失误。你可以在此基础上继续补充项目专属规则。

参考来源：https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md

取舍说明：这些规则更偏向谨慎和可验证，而不是最快完成。遇到很小的简单任务时，可以按实际情况简化流程。

## 项目背景

开始修改前，先阅读 README、配置文件和目录结构，确认项目目标、技术栈和关键目录；不要凭经验猜。

## 常用命令

只使用本项目已经声明的命令。优先从 README、`package.json` scripts、Makefile、`pyproject.toml`、`Cargo.toml`、CI 配置中确认。

不要把示例命令写成项目事实；没有确认过的命令不要写进本文件，也不要留下占位文本。

## 1. 写代码前先想清楚

不要假装已经理解，也不要把不确定性藏起来。该说清楚的地方先说清楚。

开始实现前：

- 明确写出你的假设；不确定就问。
- 如果需求存在多种理解，把几种理解列出来，不要悄悄选一个。
- 如果有更简单的做法，要主动说明。
- 该反对时要反对；发现需求不清楚，就停下来指出哪里不清楚。

## 2. 简单优先

只写解决当前问题所需的最少代码，不做猜测式扩展。

- 不添加用户没有要求的功能。
- 不为只用一次的代码设计抽象层。
- 不加入没有被要求的灵活性、配置项或扩展点。
- 不为不可能出现的场景堆错误处理。
- 如果 200 行能改成 50 行，就回头简化。

自检问题：资深工程师看到这段实现，会不会觉得过度设计？如果会，就删减。

## 3. 外科手术式修改

只碰必须修改的地方。只清理自己造成的问题。

编辑已有代码时：

- 不顺手“优化”旁边的代码、注释或格式。
- 不重构没有坏的部分。
- 匹配项目现有风格，即使你个人会用另一种写法。
- 发现无关的废代码可以提一句，不要直接删除。

如果你的改动制造了无用内容：

- 删除由本次改动造成的无用 import、变量、函数。
- 不删除本来就存在的死代码，除非任务明确要求。

检查标准：每一行改动都应该能追溯到用户这次请求。

## 4. 目标驱动执行

把任务转成可验证的目标，然后循环到验证完成。

示例：

- “加校验” -> “先写非法输入测试，再让测试通过”
- “修 bug” -> “先写复现 bug 的测试，再修到测试通过”
- “重构 X” -> “重构前后都确认测试通过”

多步骤任务先写简短计划：

```text
1. [步骤] -> 验证：[检查方式]
2. [步骤] -> 验证：[检查方式]
3. [步骤] -> 验证：[检查方式]
```

清晰的成功标准能让你独立推进；含糊的标准，比如“让它能用”，会导致反复追问。

## 安全边界

- 不读取、打印或提交 `.env*`、密钥、Token、证书等敏感信息。
- 不编辑生成文件、构建产物或锁文件，除非任务明确要求。
- 不新增依赖，除非已经说明理由并获得确认。

## 验收标准

- 每一处改动都能对应到本次需求。
- 没有新增无关依赖、无关文件或无关重构。
- 修改源码后运行相关测试、lint 或 build。
- 如果验证命令不存在、失败或耗时过长，要说明原因和替代检查方式。
- 最终回复说明：改了什么、验证了什么、还剩什么风险。

## 这些规则生效时应该看到

- diff 里无关改动更少。
- 因为过度复杂而返工的次数更少。
- 澄清问题发生在动手前，而不是出错之后。
- 每次修改都有明确验证方式。
```

创建正式 `CLAUDE.md` 前，先让 Claude 根据第二步的分析输出完整版本。命令必须来自项目文件或你亲自确认；没有确认的命令整行删除，不要留空、不要写占位。

### 第四步：验证 `CLAUDE.md` 是否生效

开启一个新会话，输入：

```text
请根据 CLAUDE.md 总结这个项目的工作规则。不要修改文件。
```

如果 Claude 能说出项目用途、常用命令和工作规则，就说明这份 `CLAUDE.md` 已经开始发挥作用。

### 你刚完成了什么

- 让 Claude Code 先读项目，而不是直接乱改。
- 写出第一份项目级指令文件。
- 建立了“先读规则、再动手、最后验证”的基本工作流。

后面的命令、快捷键、会话管理都建立在这个基础上。没有 `CLAUDE.md`，Claude Code 很容易变成一次性问答工具；有了它，才更像一个能长期协作的项目助手。

---

## 学习路径导航（先看这里！）

> **根据你的情况选择学习路径**：这是一篇长教程，不用全看！根据你的目标选择路径。

### 路径A：5分钟快速上手

**适合人群**：急着体验Claude Code，想快速跑起来

**只看这些章节**（其他跳过）：

```
✅ 先做一个15分钟实操：写出第一份 CLAUDE.md
✅ 第二部分：5分钟快速开始（5分钟）
```

**完成后你能达到**：成功启动Claude Code，完成第一次对话，并让 Claude 读到项目规则

---

### 路径B：完整学习（4-6小时）

**适合人群**：想系统掌握所有功能，成为Claude Code高手

**学习顺序**：从头到尾所有章节

**建议分段学习**：
- 第1天（2小时）：第1-3部分（简介+快速开始+交互模式）
- 第2天（1.5小时）：第4部分（Slash命令大全）
- 第3天（1小时）：第5-6部分（快捷键+最佳实践）
- 第4天（0.5小时）：第7部分（FAQ）

---

### 路径C：问题速查（5分钟）

**适合人群**：使用中遇到问题，需要快速解决

**直接跳到**：

```
🔧 第七部分：FAQ - 20个常见问题解答
🔧 /doctor命令 - 系统诊断（第4.8节）
```

**使用方法**：
1. 按 `Ctrl + F` 搜索你的问题关键词
2. 找到对应的Q&A
3. 按步骤解决

---

### 路径D：专项学习（30-60分钟/主题）

**适合人群**：已经会基础命令，想深入某个功能

| 想学什么 | 看哪几节 | 预计时间 |
|----------|---------|---------|
| **Checkpoint回退** | 第4.4节 | 30分钟 |
| **Extended Thinking** | 第4.3节 | 30分钟 |
| **会话管理** | 第4.5节 | 20分钟 |
| **快捷键速查** | 第五部分 | 15分钟 |
| **省钱技巧** | FAQ Q10 | 10分钟 |

---

## 术语表（小白必读）

在开始之前，先了解这些关键术语。**用生活类比帮助理解**：

| 术语 | 英文全称 | 通俗解释 | 生活类比 |
|------|----------|----------|----------|
| **CLI** | Command Line Interface | 命令行界面，通过打字操作电脑 | 发短信指挥别人干活 |
| **交互模式** | Interactive Mode | 可以连续对话的模式，AI记住上下文 | 打电话聊天（可以连续说很多轮） |
| **REPL** | Read-Eval-Print-Loop | 交互模式的技术称呼，读取-执行-打印-循环 | 你说一句AI回一句，不停循环 |
| **打印模式** | Print Mode | 只输出结果，没有额外格式 | 只给答案，不说废话 |
| **Slash命令** | Slash Commands | 以"/"开头的特殊命令 | 微信的"@某人"，快速触发功能 |
| **Token** | - | AI处理文字的计费单位 | 打的士按公里计费，AI按Token计费 |
| **Checkpoint** | - | 检查点，代码和对话的存档点 | 游戏存档，随时可以读档重来 |
| **Rewind** | - | 回退到之前的检查点 | 游戏读档 |
| **Compact** | - | 压缩对话历史，节省Token | 整理房间，扔掉不重要的东西 |
| **Extended Thinking** | - | 扩展思考模式，让AI深度分析 | 让AI写解题过程，不只是答案 |
| **MCP** | Model Context Protocol | 让Claude连接外部工具的插件系统 | 手机安装App，扩展功能 |

---

## 第一部分：基础使用简介


### 1.1 什么是Claude Code

> **一句话理解**：Claude Code是Anthropic公司开发的AI编程助手命令行工具，让你在终端里直接和AI对话写代码。

**生活类比**：
- **传统编程**：你一个人在厨房做菜，从买菜到炒菜全得自己来
- **用Claude Code**：请了一个厨师助手，你说"做宫保鸡丁"，他帮你查菜谱、准备食材、甚至直接帮你炒

### 1.2 三种使用模式对比

Claude Code提供三种使用模式，适合不同场景：

| 模式 | 启动方式 | 特点 | 适用场景 | 生活类比 |
|------|---------|------|---------|----------|
| **交互模式** | `claude` | 连续对话，保持上下文 | 日常开发、复杂任务 | 打电话聊天 |
| **单次执行** | `claude "prompt"` | 执行一次就退出 | 脚本自动化、快速查询 | 发短信问问题 |
| **打印模式** | `claude -p "prompt"` | 只输出纯文本结果 | 管道处理、数据转换 | 只要答案不要废话 |

**选择决策树**：

```
你要做什么？
    │
    ├── 需要多轮对话？
    │       ├── 是 → 交互模式 (claude)
    │       └── 否 ↓
    │
    ├── 需要在脚本中使用？
    │       ├── 是 → 单次执行 (claude "prompt")
    │       └── 否 ↓
    │
    └── 需要把输出传给其他命令？
            ├── 是 → 打印模式 (claude -p "prompt")
            └── 否 → 交互模式 (claude)
```

### 1.3 为什么要学CLI版本

很多人问："不是有VS Code插件吗？为什么学命令行？"

**答案**：CLI版本是最强大、最灵活的版本：

| 能力 | CLI版本 | IDE插件 |
|------|---------|---------|
| **脚本自动化** | 完美支持 | 不支持 |
| **远程服务器** | 完美支持 | 需要图形界面 |
| **CI/CD集成** | 原生支持 | 困难 |
| **管道组合** | 完美支持 | 不支持 |
| **批量处理** | 完美支持 | 手动操作 |

**类比**：就像学开车，手动挡虽然比自动挡难学，但学会后你可以开任何车、跑任何路况。

---

## 第二部分：5分钟快速开始

> **本节目的**：用最快速度完成第一次对话，让你立即看到效果！
>
> ⏱️ **预计时间**：5分钟

### 2.1 第一次启动Claude Code

#### 步骤1：打开终端

**Windows系统**：
- 按 `Win + R`，输入 `cmd` 或 `powershell`，回车
- 或：在开始菜单搜索"终端"或"PowerShell"

**macOS系统**：
- 按 `Cmd + Space`，输入 `Terminal`，回车
- 或：打开"应用程序" → "实用工具" → "终端"

**Linux系统**：
- 按 `Ctrl + Alt + T`（大多数发行版）
- 或：从应用菜单找到"终端"

#### 步骤2：进入项目目录

```bash
# Windows
cd C:\你的项目路径

# macOS/Linux
cd ~/你的项目路径
```

> 如果没有项目，可以创建一个测试目录：
> ```bash
> mkdir test-claude && cd test-claude
> ```

#### 步骤3：启动Claude Code

```bash
claude
```

**你会看到**：

```
Claude Code v2.1.92
Working directory: /你的项目路径
Type your message or /help for commands

You: █
```

> 光标在`You:`后面闪烁，等待你输入，这就说明启动成功了！

### 2.2 第一次对话

**试着输入**：

```
You: 你好，介绍一下你自己
```

**Claude会回答**：

```
你好！我是Claude Code，Anthropic开发的AI编程助手。

我可以帮你：
- 编写和修改代码
- 解释代码逻辑
- 修复Bug
- 重构项目
- 搜索文件
- 运行命令
...

有什么我可以帮助你的吗？
```

完成第一次对话后，进入下一步。

### 2.3 验证Claude Code正常工作

**运行这个测试**：

```
You: 创建一个hello.py文件，内容是打印"Hello Claude Code"
```

**预期结果**：
1. Claude会请求你确认创建文件
2. 你按回车确认
3. 文件创建成功

**验证文件已创建**：

```bash
# 在终端中查看
cat hello.py

# 预期输出：
print("Hello Claude Code")
```

### 2.4 退出Claude Code

输入以下任一命令退出：

```
You: /exit
```

或按快捷键：
- **macOS/Linux**：`Ctrl + D`
- **Windows**：`Ctrl + Z` 然后回车

---

## 第三部分：交互模式详解

> **本节目的**：深入掌握交互模式（REPL）的所有技巧
>
> ⏱️ **预计时间**：45分钟

### 3.1 交互模式是什么

**交互模式**（Interactive Mode）是Claude Code的核心使用方式，也叫REPL模式。

**REPL是什么意思**：

```
R = Read    读取你输入的内容
E = Eval    处理你的请求
P = Print   打印AI的回答
L = Loop    循环等待下一个输入
```

**类比**：就像微信聊天，你说一句，对方回一句，可以一直聊下去。

### 3.2 启动选项详解

#### 基本启动

```bash
# 最简单的启动
claude

# 指定项目目录（不需要先cd）
claude --project /path/to/your/project
```

#### 常用选项

| 选项 | 简写 | 作用 | 适用场景 |
|------|------|------|---------|
| `--dangerously-skip-permissions` | 无 | 跳过权限确认 | 个人项目，节省时间 |
| `--verbose` | 无 | 显示详细日志 | 调试问题 |
| `--model <name>` | `-m` | 指定AI模型 | 需要特定模型 |
| `--continue` | `-c` | 恢复最近会话 | 继续昨天的工作 |
| `--resume <id>` | `-r` | 恢复指定会话 | 恢复特定对话 |

**实用组合**：

```bash
# 快速启动（跳过权限确认）
claude --dangerously-skip-permissions

# 调试模式（看到所有细节）
claude --verbose

# 恢复最近的会话
claude -c

# 使用Opus模型（更强但更贵）
claude --model claude-opus-4-8

# 在独立工作树中启动（并行任务互不干扰）
claude --worktree
# 或简写
claude -w
```

> 💡 **Worktree 模式（v2.1.49+ 新增）**：`--worktree`（`-w`）是 2026年2月新增的重要参数。它会自动创建一个独立的 Git Worktree，让你可以同时运行多个 Claude Code 实例，每个实例在自己的工作目录中独立工作，互不干扰。适合并行开发多个功能、边修 bug 边开发新特性等场景。使用前需要将 `.claude/worktrees/` 添加到 `.gitignore`。

### 3.3 快速输入技巧

#### 快捷输入符号

Claude Code支持两个特殊的输入前缀：

| 前缀 | 作用 | 示例 |
|------|------|------|
| `@` | 文件路径自动补全 | `@src/app.js` |
| `!` | 直接执行bash命令 | `! npm test` |

> 💡 **关于记忆管理**：如需将项目规范写入记忆（CLAUDE.md），请使用 `/memory` 命令，它会打开 CLAUDE.md 供你编辑。

**示例**：

```bash
# 引用文件让Claude分析
You: 分析 @src/components/Button.tsx 的代码结构

# 直接运行命令（不用Claude执行）
You: ! git status

# 添加项目规范到记忆（使用 /memory 命令）
You: /memory
```

#### 多行输入

有时候需要输入多行内容（比如粘贴代码块）：

| 方法 | 快捷键 | 说明 |
|------|--------|------|
| 反斜杠换行 | `\` + Enter | 所有终端通用 |
| macOS默认 | Option + Enter | macOS默认 |
| 终端设置后 | Shift + Enter | 运行 `/terminal-setup` 配置 |
| 控制序列 | Ctrl + J | 换行符 |
| 直接粘贴 | 粘贴代码块 | 自动识别多行 |

**示例**：

```bash
You: 帮我分析这段代码：\
function add(a, b) {\
  return a + b;\
}
```

### 3.4 对话管理技巧

#### 何时清空对话

**用 /clear 的场景**：
- 完成一个任务，要开始完全不同的新任务
- 对话太长，影响响应速度
- 想要"干净"的起点

**不要用 /clear 的场景**：
- 还在解决同一个问题
- 需要参考之前的讨论
- 任务还没完成

#### 何时压缩对话

**用 /compact 的场景**：
- Token使用接近上限（用 `/context` 查看）
- 响应变慢但还需要上下文
- 想省钱但保留关键信息

**对比**：

| 命令 | 效果 | 保留内容 | Token节省 |
|------|------|----------|-----------|
| `/clear` | 完全清空 | 仅CLAUDE.md配置 | 100% |
| `/compact` | 压缩历史 | 关键信息 | 40-60% |

---

## 第四部分：Slash命令大全

> **本节目的**：掌握30+个Slash命令的使用
>
> ⏱️ **预计时间**：60分钟
>
> 📌 **重要提示**：所有Slash命令都必须在交互模式中使用！

### 4.1 基础控制命令

#### /help - 显示帮助

**作用**：显示所有可用命令列表

```bash
You: /help

# 预期输出：
Available Commands:
  /help           Show this help
  /exit           Exit interactive mode
  /clear          Clear conversation history
  /compact        Compact conversation
  ...
```

**什么时候用**：
- 忘记命令名称时
- 想知道有哪些可用命令
- 学习新功能

---

#### /exit - 退出交互模式

**作用**：退出Claude Code，回到命令行

```bash
You: /exit

# 或使用快捷键：
# macOS/Linux: Ctrl + D
# Windows: Ctrl + Z 然后回车
```

> 退出前记得保存重要对话（用 `/export` 命令）！

---

#### /clear - 清空对话历史

**作用**：删除所有对话历史，重新开始

```bash
You: /clear

# 预期输出：
Conversation cleared.
CLAUDE.md configuration retained.
```

> CLAUDE.md的配置不会丢失！

---

#### /compact - 压缩对话历史

**作用**：压缩对话，保留关键信息，节省Token

```bash
You: /compact

# 预期输出：
Conversation compacted.
Key information retained.
Token usage reduced by 45%
```

**带指令压缩**：

```bash
# 告诉Claude保留什么
You: /compact 保留所有关于数据库设计的讨论
```

---

### 4.2 上下文管理命令

#### /context - 可视化上下文使用

**作用**：用彩色网格显示Token使用情况

```bash
You: /context

# 预期输出：
Context Usage Visualization:
████████████░░░░░░░░  60% (120K / 200K tokens)

Breakdown:
- User messages: 45K
- Claude responses: 60K
- Code context: 15K

Recommendation: Context usage healthy
```

**什么时候用**：
- 想知道还能聊多少轮
- 对话很长时检查是否需要压缩
- 了解Token主要用在哪里

---

#### /cost - 显示会话成本

**作用**：查看当前会话的费用与用量相关信息。

**版本说明（以官方 release 为准）**：自 **v2.1.92** 起，对 **subscription（订阅）用户**，`/cost` 会提供 **per-model** 与 **cache-hit** 维度的拆分（原文见 [v2.1.92 release](https://github.com/anthropics/claude-code/releases/tag/v2.1.92)：`Added per-model and cache-hit breakdown to /cost for subscription users`）。非订阅或后续版本若调整行为，**以你本机 `claude /cost` 实际输出为准**，请勿对照旧教程中的示例截图硬套。

**Pro 用户提示（v2.1.92）**：同一 release 写明，Pro 用户在 **prompt cache 已过期** 后回到会话时，底部会出现 **footer hint**，**大致提示**下一轮未命中缓存时大约会发送多少 token（仅为提示，非承诺精确计费）。

```bash
You: /cost
```

---

#### /model - 切换AI模型

**作用**：在会话中切换不同的AI模型

```bash
You: /model

# 预期输出：
Available Models:
1. claude-sonnet-5 (current)
2. claude-opus-4-8
3. claude-haiku-4-5-20251001

Select model (1-3):
```

**直接指定模型**：

```bash
You: /model claude-opus-4-8
```

**快捷键切换**：
- **macOS**：Option + P
- **Windows/Linux**：Alt + P

**模型对比**：

| 模型 | 速度 | 能力 | 成本 | 上下文窗口 | 最大输出 | 适用场景 |
|------|------|------|------|-----------|---------|---------|
| Haiku | 最快 | 基础 | 最低 | 200K | 8K | 简单任务、快速查询 |
| Sonnet | 中等 | 强大 | 中等 | 200K | 64K | 日常开发（推荐） |
| Opus | 较慢 | 最强 | 最高 | **1M** | **128K** | 复杂任务、关键决策 |

> 💡 **v2.1.69+ 新特性**：Opus模型已支持1M（约100万token）上下文窗口和128K输出token。这意味着你可以让Opus阅读整个大型代码库并一次性生成完整的长文件。

---

#### /voice - 语音模式 🆕

**作用**：通过语音与Claude Code交互，无需打字

**一句话理解**：就像给Claude Code加了一个"语音助手"——按住说话，松开发送，Claude听懂后执行。

```bash
You: /voice

# 预期输出：
🎤 Voice mode activated
Press and hold Space to talk, release to send
Say "exit" or press Esc to leave voice mode
```

**操作方式**：
- **按住空格键**说话（push-to-talk），**松开**自动发送
- 说"exit"或按 `Esc` 退出语音模式
- 支持**20种语言**的语音输入（中文、英语、日语等）

**自定义按键绑定**：

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

```json
{
  "voice": {
    "pushToTalk": "Space"
  }
}
```

> ⚠️ **注意**：语音模式需要麦克风权限。首次使用时，系统可能会弹出授权提示。

---

#### /effort - 推理深度控制 🆕

**作用**：调整Claude的"思考深度"，在速度和质量之间取舍

**一句话理解**：就像考试答题——`low`是快速选择题模式，`xhigh`是深度论述题模式。

**三种设置方式**：

```bash
# 方式1：交互式斜杠命令（支持交互式滑块）
/effort

# 方式2：直接指定级别
/effort xhigh

# 方式3：CLI 参数
claude --effort xhigh

# 方式4：环境变量
CLAUDE_CODE_EFFORT_LEVEL=xhigh claude

# 方式5：重置为自动判断
/effort auto
```

**五级对比**（v2.1.105-113 起新增 xhigh 和 max）：

| 级别 | 符号 | 速度 | Token消耗 | 适用场景 |
|------|------|------|----------|---------|
| low | ○ | 最快 | 最少 | 简单问答、格式转换、快速查询 |
| medium | ◐ | 中等 | 中等 | 日常开发、代码修改 |
| high | ● | 较慢 | 较多 | 架构设计、复杂调试 |
| **xhigh** | ◉ | 慢 | 多 | **推荐默认值（Opus 4.8）**，深度推理任务 |
| max | ⬤ | 最慢 | 最多 | 极限推理，关键决策 |

> 💡 **推荐**：如果你使用 Opus 4.8 模型，官方推荐默认使用 `xhigh` 级别以获得最佳推理质量。

> 💡 **状态栏提示**：切换后，终端状态栏会显示当前级别符号，方便随时确认。

> 💡 **Hook 联动**：从 v2.1.121 起，Hook 脚本可以通过 `$CLAUDE_EFFORT` 环境变量感知当前 effort 等级，据此调整检查策略（如 xhigh 时跳过轻量检查）。

---

#### Auto Memories - 自动记忆 🆕

**作用**：Claude Code自动记录和回忆跨会话的重要信息

**一句话理解**：就像一个"自动笔记本"——Claude会把重要发现自动记下来，下次对话时自动翻阅。

**工作原理**：
1. Claude在工作中发现重要信息（如项目偏好、常见问题解法）时，自动写入memory文件
2. 新会话开始时，自动加载相关记忆到上下文
3. MEMORY.md文件的前200行始终加载到对话上下文

**配置方式**：

在 `~/.claude/settings.json` 中指定记忆存储目录：

```json
{
  "autoMemoryDirectory": "~/.claude/memory/"
}
```

**记忆文件格式**：
- 文件名带时间戳，如 `2026-03-18_project-preferences.md`
- 内容为Markdown格式，Claude自动组织
- 可手动编辑或通过 `/memory` 命令管理

> 💡 **与 /memory 的区别**：`/memory` 是手动编辑记忆文件，Auto Memories是Claude自动记录。两者互补，共同构成Claude的"长期记忆"。

---

### 4.3 Extended Thinking（扩展思考）

> ⚠️ **重要**：Extended Thinking不是Slash命令，是通过Tab键或关键词触发的功能！

#### 什么是Extended Thinking

**一句话理解**：让Claude在回答前进行深度思考，展示"解题过程"而不只是答案。

**类比**：就像数学考试，有人直接写答案，有人写完整解题过程。Extended Thinking就是让Claude展示解题过程。

#### 如何启用

**方法1：Tab键切换（最简单）**

```bash
# 在交互模式中按Tab键
按 Tab → 切换Extended Thinking开/关
```

**方法2：关键词触发**

```bash
# 基础思考（约1,500 tokens）
You: think about how to optimize this function

# 深度思考（约3,000 tokens）
You: think hard about the system architecture

# 全面分析（约8,000 tokens）
You: think harder about security vulnerabilities

# 穷尽分析（约16,000 tokens）
You: ultrathink this critical decision
```

**关键词对比**：

| 关键词 | Token预算 | 响应时间 | 适用场景 |
|--------|-----------|----------|----------|
| `think` | ~1,500 | 5-10秒 | 一般问题 |
| `think hard` | ~3,000 | 10-20秒 | 复杂问题 |
| `think harder` | ~8,000 | 20-30秒 | 架构决策 |
| `ultrathink` | ~16,000 | 30-60秒 | 关键决策 |

#### 省钱技巧

> Extended Thinking会消耗更多Token！只在真正需要时使用！

**快速决策**：

| 问题类型 | 推荐方式 | 原因 |
|---------|---------|------|
| 语法查询 | 普通模式 | 简单问题不需要深度思考 |
| 代码分析 | think | 需要基础分析 |
| 架构设计 | think hard | 需要权衡多方案 |
| 技术选型 | ultrathink | 关键决策值得深思 |

---

### 4.4 Rewind/Checkpoint（回退功能）

> Claude Code 2.0 的重要功能，让你大胆实验！

#### 什么是Checkpoint

**一句话理解**：Checkpoint（检查点）就像游戏存档，Rewind（回退）就是读档。

**类比**：
- **没有Checkpoint**：打游戏不存档，失败从头开始
- **有Checkpoint**：随时存档，失败了读档重来

**核心价值**：
- 大胆尝试重构，随时可以回退
- 不仅回退代码，还能清理"被污染"的AI对话状态
- 比Git更强：同时管理代码和对话状态

#### 如何使用Rewind

**方法1：双击Escape键（最快）**

```bash
# 在交互模式中快速按两次Escape键
[按 Esc + Esc]

# 会弹出Rewind菜单：
╭─────────────────────────────────────────╮
│            Rewind Menu                   │
├─────────────────────────────────────────┤
│  Select a checkpoint to rewind to:       │
│                                          │
│  [1] 10:30:15 - Initial state           │
│  [2] 10:32:45 - Added auth module        │
│  [3] 10:35:20 - Modified database.py     │
│  [4] 10:38:10 - Created new tests        │
│                                          │
│  [c] Cancel                              │
╰─────────────────────────────────────────╯
```

**方法2：/rewind命令**

```bash
You: /rewind

# 显示可用的检查点列表，选择要回退到的点
```

#### 三种恢复选项

选择检查点后，会提示选择恢复策略：

| 选项 | 效果 | 适用场景 |
|------|------|---------|
| **仅恢复对话** | 保留代码改动，重置AI上下文 | AI理解错了，但代码改对了 |
| **仅恢复代码** | 保留对话历史，回退文件修改 | 代码改错了，但讨论有价值 |
| **同时恢复** | 代码和对话都回到之前状态 | 完全走错方向，从头来 |

**快速决策表**：

| 代码对吗？ | 对话有用吗？ | 选哪个？ |
|-----------|------------|---------|
| 对 | 不对 | 仅恢复对话 |
| 不对 | 有用 | 仅恢复代码 |
| 不对 | 没用 | 同时恢复 |
| 都对 | 都对 | 按Cancel |

#### 重要限制

> **Critical**：Checkpoint只追踪Claude的文件编辑工具（Write、Edit），**不追踪bash命令修改**！

**会被追踪**：
```bash
You: 修改src/app.py文件
# Claude用Edit工具修改 → ✅ 会创建checkpoint
```

**不会被追踪**：
```bash
You: ! mv src/old.py src/new.py
# bash命令修改 → ❌ 不创建checkpoint
```

**最佳实践**：
- 重要操作让Claude用文件工具修改
- 配合Git使用保护bash命令的修改

---

### 4.5 会话管理命令

#### /resume - 恢复会话

**作用**：恢复之前的对话会话

```bash
# 命令行快速恢复最近会话
$ claude -c
$ claude --continue

# 恢复指定会话
$ claude -r ses_abc123
$ claude --resume ses_abc123

# 交互模式中恢复
You: /resume

# 显示最近会话列表：
Recent Sessions:
─────────────────────────────────────────────────────
ID          Date        Project           Summary
─────────────────────────────────────────────────────
ses_abc123  Today 10:30 my-app           Auth module
ses_def456  Today 09:15 my-app           Bug fixes
ses_ghi789  Yesterday   other-project    API design
─────────────────────────────────────────────────────
```

**什么时候用**：
- 每天早上恢复昨天的工作
- 电脑重启后继续
- 在多个项目间切换

---

#### /export - 导出对话

**作用**：把当前对话导出为纯文本文件

```bash
# 打开导出对话框：复制到剪贴板或保存到文件
You: /export

# 直接保存到指定文件
You: /export ./notes/auth-session.txt
```

> **版本校准（2026-04）**：官方命令参考当前写法是 `/export [filename]`，用途是导出当前对话为 **plain text**。会话内的 `/export --format json`、`/export --format html` 不是当前支持的 slash 参数；在 Claude Code 2.1.92 / 2.1.107 这类版本里输入这些参数，通常仍会按普通文件名/文本导出处理。

**需要结构化输出时**：

```bash
# 非交互 print 模式支持 JSON / stream-json 输出
claude -p "总结当前项目结构" --output-format json
claude -p "检查代码并输出流式事件" --output-format stream-json --verbose
```

`--output-format` 是 CLI print 模式参数，不是会话内 `/export` 的格式参数。

---

#### /rename - 重命名会话

**作用**：给当前会话起个好名字，方便以后查找

```bash
You: /rename auth-module-implementation

# 预期输出：
✓ Conversation renamed
```

**命名建议**：`[项目]-[功能]-[版本]`，如 `my-app-login-api`

---

### 4.6 项目配置命令

#### /init - 初始化项目配置

**作用**：创建CLAUDE.md配置文件，告诉Claude项目信息

```bash
You: /init

# Claude会分析项目并创建CLAUDE.md
Analyzing project structure...
Creating CLAUDE.md...

CLAUDE.md created with:
- Project type: React + TypeScript
- Key files identified
- Coding conventions detected
```

---

#### /memory - 编辑记忆文件

**作用**：打开CLAUDE.md进行编辑

```bash
You: /memory

# 会打开编辑器让你修改CLAUDE.md
```

**快捷添加记忆**：

```bash
# 用#前缀快速添加
You: # 本项目使用pnpm而不是npm
You: # API响应格式必须包含code字段
```

---

#### /permissions - 管理权限

**作用**：查看和修改Claude的权限设置

```bash
You: /permissions

# 显示当前权限设置
Current Permissions:
====================
File Operations:
  ✓ Read files in project
  ✓ Write files (with confirmation)
  ✗ Delete files

Bash Commands:
  ✓ Safe commands (git status, npm test)
  ⚠ Dangerous commands (require confirmation)
```

**权限模式切换**（`Shift + Tab`）：

Claude Code 提供三种权限模式，交互模式中按 `Shift + Tab` 循环切换：

| 模式 | 行为 | 适用场景 |
|------|------|----------|
| **plan** | 只分析不修改，纯只读 | 代码审查、安全探索 |
| **acceptEdits** | 自动接受文件编辑（仍确认危险命令） | 信任项目、快速原型 |
| **bypassPermissions** | 跳过所有确认提示 | 仅限隔离容器环境 |

> **2026-08-06 权限模式口径**：v2.1.200 起，原 "Default" 权限模式在 CLI、VS Code、JetBrains 中已统一改名 **"Manual"**（行为不变，只是名字）。教程里只要看到"Default 模式"或"默认权限模式"，按"Manual 模式"理解即可。此外 `/doctor` 已升级为完整诊断入口（原 `/checkup` 别名），`/commit-push-pr` 可在配置好远端后自动允许 git push，`/fork` 现在把会话拷到后台新 session、原会话内的 subagent 改叫 `/subtask`，`/code-review` 改为后台 subagent 运行。

> **v2.1.90（[release](https://github.com/anthropics/claude-code/releases/tag/v2.1.90)）**：在 **acceptEdits** 模式下，官方将 **`.husky`** 目录纳入 **protected directories**（原文：*`Added .husky to protected directories (acceptEdits mode)`*）。是否影响你仓库里的 Hook 脚本，以当前版本实际提示与官方后续说明为准。

**配置层级**（优先级从高到低）：

```
企业设置 > 项目本地(.claude/settings.local.json) > 项目(.claude/settings.json) > 用户(~/.claude/settings.json)
```

**allow（推荐替代方案）**：

相比危险的 `--dangerously-skip-permissions` 全局跳过，更安全的做法是在配置中精确指定允许的工具：

```json
{
  "permissions": {
    "allow": ["Read", "Grep", "Glob", "Edit"]
  }
}
```

> ⚠️ **安全提醒**：`--dangerously-skip-permissions` 会移除所有确认提示，仅适用于 Docker/VM 等隔离环境中的自动化任务，日常开发请使用 `allow` 精细控制。

---

### 4.7 开发辅助命令

#### /security-review - 安全审查

**作用**：分析当前分支尚未提交的改动，重点找安全问题

```bash
You: /security-review

# Claude会围绕认证、注入、越权、敏感信息暴露等问题审查当前 git diff
```

> ⚠️ **说明**：`/security-review` 专注安全风险。需要通用代码审查时，当前官方命令参考仍提供 `/review [PR]`；需要更深的云端多 Agent 审查时看 `/ultrareview`。

---

#### 待办追踪（没有 /todos slash 命令）

**作用**：Claude 会在复杂多步骤任务中用内部 `TodoWrite` 工具追踪待办，但当前官方命令参考没有 `/todos` 这个用户可输入的 slash 命令。

```bash
# 想查看当前工作项时，直接用自然语言询问
You: 总结一下当前任务进度和剩余待办

# 管理后台运行任务时，用 /tasks
You: /tasks
```

> **不要混淆**：`TodoWrite` 是 Claude/Agent SDK 的内部工具事件，不等于一个 `/todos` slash 命令。`/tasks` 管的是后台任务/后台 Bash，不是普通待办列表。

---

#### /agents - 管理子代理

**作用**：管理和查看Claude的子代理（用于复杂任务分解）

```bash
You: /agents

# 显示活跃的子代理
Active Agents:
- TestAgent: Running unit tests
- DocAgent: Generating documentation
```

---

#### /fast - 快速模式切换

**作用**：切换快速输出模式，使用相同模型但输出速度更快，适合简单任务

```bash
You: /fast

# 切换后提示
Fast mode: enabled
# 再次输入切换回普通模式
You: /fast
Fast mode: disabled
```

> 💡 **说明**：快速模式使用相同的模型，不会切换到更低级的模型，只是优化了输出速度。适合简单的代码修改、快速问答等场景。

---

### 4.8 诊断命令

#### /doctor - 系统诊断

**作用**：检查Claude Code安装的健康状态

```bash
You: /doctor

# 预期输出：
Claude Code Health Check
========================
✓ Claude Code version: 2.1.92 (OK)
✓ Platform: native (OK)
✓ API connection: Connected
✓ Authentication: Valid
✓ MCP servers: 3 connected

Overall Status: Healthy ✓
```

**什么时候用**：
- 遇到奇怪的错误
- 更新后检查是否正常
- 定期健康检查

---

#### /status - 完整状态信息

**作用**：显示版本、模型、账户等完整状态

```bash
You: /status

# 预期输出：
Claude Code Status
==================
Version: 2.1.92 (native)
Model: claude-sonnet-5
Account: your-email@example.com
Plan: Pro

MCP Servers:
  ✓ filesystem (3 tools)
  ✓ github (8 tools)

Session:
  Started: 10:30 AM
  Duration: 45 minutes
  Tokens used: 12,340
```

---

#### /usage - 使用量统计


> **v2.1.149+ 更新**：`/usage` 会按 skills、subagents、plugins、MCP server 等类别拆分用量，排查“为什么额度消耗很快”时先看这里；额外额度入口现在统一写作 `/usage-credits`。

**作用**：显示账户使用量和限制（订阅用户）

```bash
You: /usage

# 预期输出：
Plan Usage
==========
Plan: Pro
Period: Dec 1 - Dec 31

Usage:
  Messages: 1,234 / 5,000
  Tokens: 890K / 5M

Rate Limit:
  Current: 10 req/min
  Status: OK
```

---

### 4.9 其他实用命令

#### /stats - 使用统计

**作用**：显示你的使用习惯统计

```bash
You: /stats

# 预期输出：
Your Statistics
===============
This Week:
  Sessions: 23
  Messages: 456
  Total cost: $12.34

Most used commands:
1. /clear (45 times)
2. /compact (23 times)
3. /export (12 times)
```

---

#### /config - 统一设置入口

**作用**：打开设置界面，统一管理主题、模型、输出样式、编辑模式等

```bash
You: /config
```

> ⚠️ **说明**：`/vim` 已在 v2.1.92 移除。现在想切换 Vim / Normal 编辑模式，请进入 `/config` → Editor mode。

---

#### /release-notes - 查看更新日志

**作用**：查看各版本更新说明。

**版本说明（以官方 release 为准）**：自 **v2.1.92** 起，`/release-notes` 为 **interactive version picker**（交互式版本选择器），不再等同于「固定打印最近几条 bullet」。请在终端内自行选择要查看的版本；完整变更列表以 [GitHub Releases · anthropics/claude-code](https://github.com/anthropics/claude-code/releases) 为准。

```bash
You: /release-notes
```

---

#### /bug - 报告Bug

**作用**：提交Bug报告给Anthropic

```bash
You: /bug

# 会引导你描述问题并发送报告
Describe the bug you encountered:
[输入问题描述]

✓ Bug report submitted. Thank you!
```

---

### 4.10 MCP相关命令

#### /mcp - 管理MCP连接

**作用**：查看和管理MCP服务器连接

```bash
You: /mcp

# 预期输出：
MCP Server Status
=================
✓ filesystem (local)
  Tools: list_directory, read_file, write_file

✓ github (authenticated)
  Tools: create_issue, list_repos, ...

⚠ database (not configured)
```

---

#### /plugin - 管理插件

**作用**：管理 Claude Code 插件，支持发现、安装、启用、禁用、更新

```bash
You: /plugin

# 你会看到 Discover / Installed / marketplace 等交互入口
```

---

#### /reload-plugins / /remote-control / /install-github-app / /tasks


这几个命令在 2.1.92 里都值得认识一下：

| 命令 | 作用 | 适合场景 |
|------|------|----------|
| `/reload-plugins` | 重新加载当前活跃插件 | 刚修改本地 plugin / skill 后不想重启 |
| `/remote-control` | 让当前会话可从 claude.ai / 手机 App 继续 | 离开工位继续当前本地 session |
| `/install-github-app` | 引导配置 Claude GitHub Actions app | 给仓库快速接入 GitHub Actions |
| `/tasks` | 查看并管理后台任务 | 构建、测试、开发服务器等在后台运行时 |
| `/mobile` | 显示下载 Claude 手机 App 的二维码 | 第一次用手机接 Remote Control 时 |

---

#### /hooks - 管理Hooks

**作用**：配置在特定事件触发的自动化脚本

```bash
You: /hooks

# 显示已配置的Hooks
Configured Hooks:
- pre-write: Run ESLint before file writes
- post-commit: Send Slack notification
```

---

## 第五部分：快捷键速查

> **本节目的**：掌握提高效率的键盘快捷键
>
> ⏱️ **预计时间**：15分钟

### 5.1 通用控制

| 快捷键 | 作用 | 备注 |
|--------|------|------|
| `Ctrl + C` | 取消当前输入或生成 | 标准中断 |
| `Ctrl + D` | 退出Claude Code | EOF信号 |
| `Ctrl + L` | 清除终端屏幕 | 保留对话历史 |
| `Ctrl + O` | 切换详细输出 | 显示工具调用细节 |
| `Ctrl + R` | 反向搜索历史命令 | 查找之前输入 |
| `Esc + Esc` | 打开Rewind菜单 | 回退代码/对话 |
| `Tab` | 切换Extended Thinking | 开/关扩展思考 |
| `Shift + Tab` | 切换权限模式 | 自动/计划/普通 |
| `上/下箭头` | 浏览历史命令 | 快速复用 |

### 5.2 模型切换

| 快捷键 | 作用 |
|--------|------|
| `Option + P` (macOS) | 切换AI模型 |
| `Alt + P` (Windows/Linux) | 切换AI模型 |

### 5.3 粘贴图片

| 快捷键 | 平台 |
|--------|------|
| `Ctrl + V` | macOS/Linux |
| `Alt + V` | Windows |

### 5.4 多行输入

| 方法 | 快捷键 | 兼容性 |
|------|--------|--------|
| 反斜杠 | `\` + Enter | 所有终端 |
| macOS默认 | Option + Enter | macOS |
| 配置后 | Shift + Enter | 需运行 `/terminal-setup` |
| 控制序列 | Ctrl + J | 所有终端 |

### 5.5 历史搜索 (Ctrl + R)

**使用步骤**：

1. 按 `Ctrl + R` 进入搜索模式
2. 输入要搜索的关键词
3. 再按 `Ctrl + R` 浏览更早的匹配
4. 按 `Tab` 或 `Esc` 接受当前匹配
5. 按 `Enter` 直接执行
6. 按 `Ctrl + C` 取消搜索

### 5.6 后台运行

| 操作 | 方式 |
|------|------|
| 提示Claude后台运行 | 在提示词中说"在后台运行" |
| 手动转后台 | 按 `Ctrl + B` |
| tmux用户 | 按两次 `Ctrl + B` |

**常见后台命令**：
- 构建工具（webpack、vite）
- 包管理器（npm、yarn）
- 测试运行器（jest、pytest）
- 开发服务器

### 5.7 Vim模式快捷键

如果你在 `/config` → Editor mode 中开启了 Vim 模式，可用这些快捷键：

**模式切换**：

| 命令 | 动作 |
|------|------|
| `Esc` | 进入NORMAL模式 |
| `i` | 在光标前插入 |
| `a` | 在光标后插入 |
| `o` | 在下方新开一行 |

**移动（NORMAL模式）**：

| 命令 | 动作 |
|------|------|
| `h/j/k/l` | 左/下/上/右 |
| `w/b` | 下一个/上一个单词 |
| `0/$` | 行首/行尾 |
| `gg/G` | 文件开头/结尾 |

**编辑（NORMAL模式）**：

| 命令 | 动作 |
|------|------|
| `x` | 删除字符 |
| `dd` | 删除整行 |
| `dw` | 删除单词 |
| `cc` | 修改整行 |
| `.` | 重复上次操作 |

---

## 第六部分：最佳实践

> **本节目的**：掌握高效使用Claude Code的技巧
>
> ⏱️ **预计时间**：30分钟

### 6.1 日常工作流程

**推荐的每日流程**：

```bash
# 1. 早上恢复昨天的会话
$ claude -c

# 2. 检查状态
You: /status

# 3. 开始工作
You: 我今天要完成用户认证模块

# 4. 工作过程中定期检查Token使用
You: /context

# 5. Token使用超过60%时压缩
You: /compact

# 6. 完成重要功能后导出对话
You: /export ~/docs/auth-implementation.md

# 7. 下班前重命名会话
You: /rename auth-module-day2
```

### 6.2 省钱技巧

#### Token优化

| 技巧 | 节省比例 |
|------|---------|
| 简单问题不用Extended Thinking | 70% |
| 定期使用 `/compact` | 40-60% |
| 完成任务后用 `/clear` | 100% |
| 使用Sonnet而非Opus | 80% |
| 简洁描述需求 | 30% |

#### 模型选择策略

```bash
# 简单任务：用Haiku（最便宜）
You: /model claude-haiku-4-5-20251001
You: 这个函数是什么意思？

# 日常开发：用Sonnet（性价比最高）
You: /model claude-sonnet-5
You: 帮我重构这个模块

# 关键决策：用Opus（最强）
You: /model claude-opus-4-8
You: ultrathink 设计这个系统的架构
```

### 6.3 配置别名提高效率

**macOS/Linux**（添加到 `~/.bashrc` 或 `~/.zshrc`）：

```bash
# 快速启动
alias cc="claude --dangerously-skip-permissions"

# 恢复会话
alias cr="claude -c"

# 调试模式
alias ccv="claude --verbose"

# 使用Opus
alias cco="claude --model claude-opus-4-8"
```

**Windows PowerShell**（添加到 `$PROFILE`）：

```powershell
# 编辑配置文件
notepad $PROFILE

# 添加以下内容：
function cc { claude --dangerously-skip-permissions }
function cr { claude -c }
function ccv { claude --verbose }
```

### 6.4 大胆实验的工作方式

**利用Checkpoint放心尝试**：

```bash
# 场景：想尝试激进的重构但担心破坏代码

# 直接开始尝试（Checkpoint自动创建）
You: 帮我用新架构重构这个模块

# 不满意？双击Esc回退
[按 Esc + Esc]
[选择回到之前的检查点]

# 尝试另一个方案
You: 换一种方式，用工厂模式重构

# 还是不满意？继续回退
[按 Esc + Esc]

# 直到找到满意的方案
```

### 6.5 团队协作

**分享会话给团队**：

```bash
# 导出纯文本对话
You: /export shared/auth-discussion.txt

# 需要网页展示时，再用 Markdown/静态站点工具转换展示
```

**创建可复用的 legacy Slash 命令**：

```bash
# 在项目中创建共享命令（兼容方式；新项目长期推荐 Skills）
mkdir -p .claude/commands

# 创建代码审查命令
echo "Review this code for security and performance issues:" > .claude/commands/security-review.md

# 团队成员都可以使用
You: /security-review
```

---

## 第七部分：常见问题FAQ

> **本节目的**：快速解决常见问题
>
> ⏱️ **预计时间**：按需查阅

### Q1: 启动时报错 "claude: command not found"

**原因**：Claude Code没有正确安装或不在PATH中

**解决方案**：

```bash
# 检查是否安装
which claude  # macOS/Linux
where claude  # Windows

# 如果没有输出，优先使用原生安装脚本（macOS/Linux）
curl -fsSL https://claude.ai/install.sh | bash

# Windows 可优先使用 WinGet
# winget install Anthropic.ClaudeCode
```

---

### Q2: 报错 "Authentication failed"

**原因**：当前认证凭据无效，常见于 claude.ai 登录过期、Console / API Key 配置错误，或环境变量没有生效

**解决方案**：

```bash
# 重新登录
claude auth login

# 或检查环境变量
echo $ANTHROPIC_API_KEY  # macOS/Linux
echo %ANTHROPIC_API_KEY%  # Windows

# 如果为空，需要设置API Key
export ANTHROPIC_API_KEY="your-api-key"  # macOS/Linux
set ANTHROPIC_API_KEY=your-api-key  # Windows
```

---

### Q3: 响应很慢怎么办

**可能原因和解决方案**：

| 原因 | 解决方案 |
|------|---------|
| 对话太长 | 使用 `/compact` 压缩 |
| 网络问题 | 检查代理设置 |
| 服务繁忙 | 稍后再试 |
| 使用Opus模型 | 切换到Sonnet |

```bash
# 检查Token使用
You: /context

# 如果超过60%，压缩对话
You: /compact

# 切换到更快的模型
You: /model claude-sonnet-5
```

---

### Q4: 怎么恢复之前的对话

**方法1：命令行恢复**

```bash
# 恢复最近的会话
claude -c

# 恢复指定会话
claude -r ses_abc123
```

**方法2：交互模式恢复**

```bash
You: /resume
# 从列表中选择要恢复的会话
```

---

### Q5: 文件修改后怎么回退

**使用Rewind功能**：

```bash
# 方法1：双击Escape键
[按 Esc + Esc]
# 选择要回退到的检查点
# 选择"仅恢复代码"

# 方法2：/rewind命令
You: /rewind
```

---

### Q6: Claude一直请求确认，太烦了

**解决方案**：使用跳过权限确认的启动选项

```bash
claude --dangerously-skip-permissions
```

> 注意：仅在个人项目或信任的环境中使用！

---

### Q7: 怎么让Claude记住项目规范

**方法1：使用#前缀快速添加**

```bash
You: # 本项目使用TypeScript
You: # 所有API必须返回code字段
```

**方法2：编辑CLAUDE.md**

```bash
You: /memory
# 在编辑器中添加项目规范
```

**方法3：初始化项目**

```bash
You: /init
# Claude会自动分析项目并创建配置
```

---

### Q8: 怎么使用Extended Thinking

**方法1：Tab键切换**

```bash
# 按Tab键开启/关闭
[按 Tab]
```

**方法2：关键词触发**

```bash
You: think about this problem
You: think hard about the architecture
You: ultrathink this critical decision
```

---

### Q9: MCP服务器连不上

**诊断步骤**：

```bash
# 1. 检查配置文件
cat .mcp.json

# 2. 验证JSON格式
# 使用在线工具：https://jsonlint.com/

# 3. 使用/mcp命令查看状态
You: /mcp

# 4. 运行系统诊断
You: /doctor
```

---

### Q10: 怎么省钱

**综合省钱策略**：

1. **选择合适的模型**
   - 简单任务：Haiku（最便宜）
   - 日常开发：Sonnet（性价比高）
   - 关键决策：Opus（按需使用）

2. **优化Token使用**
   - 定期 `/compact` 压缩对话
   - 完成任务后 `/clear` 清空
   - 简洁描述需求

3. **避免不必要的Extended Thinking**
   - 简单问题直接问
   - 只在需要深度分析时用 `think`

4. **监控使用量**
   - 定期 `/cost` 查看费用
   - `/context` 检查Token使用

---

### Q11: 怎么处理大文件

**Claude Code对大文件的处理策略**：

```bash
# 让Claude只读取关键部分
You: 读取 @large-file.js 的前100行

# 或指定函数
You: 分析 @large-file.js 中的handleAuth函数
```

---

### Q12: 怎么批量处理多个文件

**使用单次执行模式**：

```bash
# 批量处理
for file in *.js; do
  claude -p "Add JSDoc comments to $file" > "${file%.js}-documented.js"
done
```

---

### Q13: 输出乱码怎么办

**解决方案**：

```bash
# Windows PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# macOS/Linux
export LANG=en_US.UTF-8
```

---

### Q14: 怎么在远程服务器使用

**SSH到服务器后直接使用**：

```bash
# SSH连接
ssh user@server

# 在服务器上使用Claude Code
claude

# 或使用单次执行
claude -p "分析这个日志文件" < error.log
```

---

### Q15: 怎么集成到CI/CD

**GitHub Actions示例**：

```yaml
- name: Code Review
  run: |
    npm install -g @anthropic-ai/claude-code
    claude -p "Review the changes and check for issues"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

---

### Q16: 会话突然中断怎么办

**会话自动保存，直接恢复**：

```bash
# 恢复最近会话
claude -c
```

---

### Q17: 怎么看Claude在做什么

**启用详细输出**：

```bash
# 启动时启用
claude --verbose

# 运行时切换
Ctrl + O
```

---

### Q18: 怎么取消正在执行的操作

**按 Ctrl + C 中断**：

```bash
# Claude正在生成长回答时
[按 Ctrl + C]
# 会立即停止生成
```

---

### Q19: 怎么更新Claude Code

**更新命令**：

```bash
# 在终端运行
claude update

# 或使用npm更新
npm update -g @anthropic-ai/claude-code
```

---

### Q20: 配置文件在哪里

**配置文件位置**：

| 文件 | 位置 | 作用 |
|------|------|------|
| CLAUDE.md | 项目根目录 | 项目配置 |
| .mcp.json | 项目根目录 | MCP服务器配置 |
| ~/.claude/ | 用户目录 | 全局配置 |
| ~/.claude/commands/ | 用户目录 | 个人 legacy Slash 命令 |

---

## 附录A：完整命令速查表

### CLI启动选项

| 选项 | 简写 | 作用 |
|------|------|------|
| `--version` | `-v` | 显示版本 |
| `--help` | `-h` | 显示帮助 |
| `--print` | `-p` | 打印模式 |
| `--model <name>` | `-m` | 指定模型 |
| `--continue` | `-c` | 恢复最近会话 |
| `--resume <id>` | `-r` | 恢复指定会话 |
| `--project <path>` | 无 | 指定项目目录 |
| `--verbose` | 无 | 详细输出 |
| `--dangerously-skip-permissions` | 无 | 跳过权限确认 |

### Slash命令速查

| 命令 | 作用 |
|------|------|
| `/help` | 显示帮助 |
| `/exit` | 退出 |
| `/clear` | 清空对话 |
| `/compact` | 压缩对话 |
| `/context` | 查看Token使用 |
| `/cost` | 查看费用 |
| `/model` | 切换模型 |
| `/status` | 查看状态 |
| `/doctor` | 系统诊断 |
| `/resume` | 恢复会话 |
| `/export` | 导出对话 |
| `/rename` | 重命名会话 |
| `/init` | 初始化项目 |
| `/memory` | 编辑记忆 |
| `/permissions` | 管理权限 |
| `/security-review` | 安全审查 |
| `/tasks` | 后台任务管理 |
| `/rewind` | 回退功能 |
| `/plan` | 规划模式 |
| `/mcp` | 管理MCP |
| `/plugin` | 管理插件 |
| `/reload-plugins` | 重载插件 |
| `/hooks` | 管理Hooks |
| `/config` | 打开统一设置界面 |
| `/stats` | 使用统计 |
| `/usage` | 使用量 |
| `/insights` | 查看会话/使用洞察 |
| `/schedule` | 计划任务入口 |
| `/statusline` | 状态行定制 |
| `/remote-control` | 远程继续当前本地会话 |
| `/mobile` | 手机 App 下载二维码 |
| `/install-github-app` | GitHub Actions 快速接入 |
| `/tasks` | 管理后台任务 |
| `/theme` | 切换配色主题 |
| `/desktop` | 切到 Claude Code Desktop |
| `/diff` | 查看当前变更和逐轮 diff |
| `/btw` | 提一个不污染主线程的 side question |
| `/chrome` | 管理 Claude in Chrome 集成 |
| `/ultraplan` | ~~在浏览器里草拟并回传 plan~~（v2.1.222 已移除，改用 `/plan` + 工作流 skill） |
| `/release-notes` | 更新日志 |
| `/bug` | 报告Bug |
| `/powerup` | 交互式功能教程（v2.1.90+，见 GitHub release） |
| `/voice` | 语音模式 🆕 |
| `/effort` | 推理深度控制（五级：low/medium/high/xhigh/max）🆕 |
| `/loop` | Bundled skill：定时循环执行 🆕 |
| `/sandbox` | 沙箱隔离模式 🆕 |
| `/color` | 会话颜色设置 🆕 |
| `/copy` | 复制AI回复 🆕 |
| `/branch` | 会话分支 🆕 |
| `/skills` | 查看和搜索已安装的 Skills 🆕 |
| `/proactive` | `/loop` 的别名（v2.1.105+）🆕 |

### 快捷键速查

| 快捷键 | 作用 |
|--------|------|
| `Ctrl + C` | 取消/中断 |
| `Ctrl + D` | 退出 |
| `Ctrl + L` | 清屏 |
| `Ctrl + O` | 切换详细输出 |
| `Ctrl + R` | 搜索历史 |
| `Ctrl + B` | 转后台运行 |
| `Esc + Esc` | Rewind菜单 |
| `Tab` | 切换Extended Thinking |
| `Shift + Tab` | 切换权限模式 |
| `Option/Alt + P` | 切换模型 |

---

## 总结

恭喜你完成了Claude Code基础使用的学习！

**你现在掌握了**：

1. 三种使用模式（交互/单次/打印）
2. 30+个Slash命令
3. 高效快捷键操作
4. Checkpoint/Rewind回退功能
5. Extended Thinking深度思考
6. 省钱和效率技巧

**下一步学习建议**：

1. **Commands系统**：学习自定义Slash命令
2. **MCP集成**：连接外部工具
3. **Hooks系统**：自动化工作流
4. **Skills定制**：创建专业知识技能包

**记住**：最好的学习方式是实践！打开Claude Code，开始你的AI编程之旅吧！

---

> **课程反馈**：如果本教程对你有帮助，欢迎分享给更多人！
>
> **问题反馈**：遇到问题可以使用 `/bug` 命令报告，或在社区提问。
>
> **更新日期**：2026年6月9日
> **版本**：v1.5（对齐 Claude Code v2.1.158 release 差量）

---