13｜16 小时 Claude Code：CLI、模式、Slash Commands 与 Checkpoints

34 · CLI 参考手册：命令与全部标志

「你这 claude 后面还能跟参数？我一直就光秃秃敲一个 claude 进去啊。」

「能啊，多了去了。让脚本跑个 claude -p '总结这个 PR'，结果直接吐到文件里，根本没进交互界面。」

「等下——-p 是啥？claude --help 翻了半天没看全。」

这段对话挺常见。很多人用 Claude Code 小半年，一直只会光敲一个 claude 进交互模式，根本不知道这命令背后还挂着几十个标志。这也怪不得谁——官方文档自己都写了一句话：claude --help 不会列出每个标志。你光靠 --help 摸，注定漏一大片。

说白了，前面三十几篇咱们一直在「交互模式」里转：进去、聊天、它干活。但 claude 本质是个命令行工具，命令行工具的玩法远不止「打开一个界面」——它能接管道、能塞进脚本、能按退出码判断成败。今天这一篇就是那张「说明书」：把 claude 的命令、标志、管道用法、退出码一次摊开，以后想查哪条直接翻表。

看完这一篇，你会拿到：

• claude 的核心命令清单：启动、带初始提示、管道、继续 / 恢复会话、更新、登录，各干啥
• 最常用的一批标志（-p / --model / -c / --resume / --permission-mode / --add-dir 等）逐个讲清，配一张完整对照表
• headless（无头）与管道用法：怎么把 Claude 塞进脚本、当 linter、接 jq 处理输出
• 退出码怎么读：脚本里怎么靠它判断「成了还是没成」
• 一套能照着走完的 headless 完整链路：裸调用、管道喂料、结构化输出、退出码判断

01 先分清两个词：命令 vs 标志

动手翻表之前，先把两个最容易混的词钉死。你在终端敲的一整行，拆开看就两样东西：命令（command）和标志（flag）。

类比：寄快递填单子。 claude 是「寄件」这个动作本身；后面跟的 update、mcp 这种是子动作（命令），告诉系统你今天不是寄普通件、是要「更新」或「配 MCP」；再后面那些 -p、--model 是单子上的勾选框（标志），微调这趟怎么寄——加急吗？保价吗？用哪个模型送？动作选一个，勾选框可以勾一堆。

落到具体：

claude update
claude -p "解释这个函数" --model sonnet

• 第一行：claude 是程序，update 是命令（一个子动作，跑完就退出）。
• 第二行：claude 后面没跟命令，直接进会话逻辑；-p 和 --model 都是标志，-p 后面的 "解释这个函数" 是这趟的初始提示。

这俩为啥要分清？因为它们在文档里是分两张表列的，查的时候你得知道自己要查哪张。 想知道「怎么更新 / 怎么登录 / 怎么配 MCP」——查命令表；想知道「怎么换模型 / 怎么不进交互直接出结果 / 怎么让它先别问权限」——查标志表。

还有个贴心细节值得先记：敲错命令它会提示你。官方原文说得很清楚——

如果您输入错误的子命令，Claude Code 会建议最接近的匹配项并退出而不启动会话。例如，claude udpate 会打印 Did you mean claude update?。

手快打错 claude udpate 是常事，每次它都老老实实问你「是不是想敲 claude update」，不会傻乎乎拿错字去启动一个会话。这点小体贴，省了不少「咦怎么没反应」的困惑。

💡 一句话总结：一行命令拆两样——命令是子动作（update、mcp，跑完退出），标志是勾选框（-p、--model，微调这趟怎么跑）；查文档先想清自己要查哪张表。

02 核心命令：启动会话的那几种姿势

先看命令。日常你真正会敲的就那么几条，我按「用途」分三组讲，每组配官方给的标准写法。

第一组：启动会话（最常用）

这组是你 90% 时间在用的：

# 1. 光秃秃启动，进交互模式
claude

# 2. 带一句初始提示启动（进去后它先回答这句）
claude "解释这个项目"

# 3. 不进交互、直接出结果就退出（headless / 打印模式）
claude -p "解释这个函数"

前两条你早就熟了。第三条 claude -p 是这篇要重点讲的「另一种活法」——它不打开那个聊天界面，直接把答案打印到终端然后退出，专门给脚本和管道用。第 04 节细讲。

第二组：接着上次聊（别让它失忆）

还记得第 19 篇说过的吗——每开一个新会话，Claude 就是个「失忆的新实习生」，上回聊到哪它全忘了。这两条命令就是治失忆的：

# 继续「当前目录」最近的那次对话
claude -c
# （--continue 是它的全称，-c 是简写）

# 按 ID 或名字恢复「某一次特定」的对话
claude -r "auth-refactor" "把这个 PR 收尾"
# （--resume 是全称，-r 是简写）

两者的区别就一个词：「最近」还是「指定」。

• -c（--continue）：只认「当前目录里最近那一次」，不用你记 ID，最省事。
• -r（--resume）：点名要哪一次——给会话 ID 或你之前用 --name 起的名字；不给的话，会弹一个交互式列表让你挑。

类比：跟同事接着聊。 -c 是「咱接着刚才那事说」——默认就是最近那档子事，不用解释是哪件；-r 是「上周三那个关于登录重构的事儿，咱继续」——你得明确点出是哪一桩，对方才翻得到那段记忆。

一个顺手的习惯：手头就一条线在推进时用 -c，省得记名字；同时开了好几摊活儿（这个查 bug、那个写测试），才用 -r 点名恢复——前提是启动时用 --name（简写 -n）给每摊起了名，不然一堆 UUID 也认不出哪个是哪个。一套完整流程长这样：

# 启动时起个好认的名字
claude -n "login-refactor"

# 几天后回来，按名字直接恢复这一摊
claude -r "login-refactor"

官方对 --name 的说明很直白——它设置的显示名会出现在 /resume 列表和终端标题里，之后就能用 claude --resume <名字> 恢复。同时推三四个任务时，全靠这个名字认人，比对着一串 550e8400-... 的 UUID 强太多了。

还有个组合值得单独点一下：-c 和 -p 能叠用。claude -c -p "查一下有没有类型错误" 的意思是「接着最近那次对话，但这次走 headless、出结果就退」——它带着上次的上下文，却不进交互界面。脚本里想「分几步推进同一个任务、每步自动跑」时，这个组合特别顺手（第 04 节那个连续 --continue 的例子就是这么串的）。

第三组：维护与账户

剩下这组不常敲，但你得知道它们在：

# 更新到最新版
claude update

# 安装 / 重装本机二进制（可指定版本：2.1.118 / stable / latest）
claude install stable

# 登录 Anthropic 账户
claude auth login

# 查登录状态（已登录退出码 0，未登录退出码 1）
claude auth status

claude install 那个能跟版本号的细节，关键时刻很救命：官方说它接受 2.1.118 这种具体版本号，也接受 stable、latest。设想这样一种情况——某个新版本更新后某个行为变了不合用，用 claude install 2.1.x 回退钉死在上一个稳定版，等问题修了再放开，比干等着舒服多了。

claude auth status 那句「已登录退出码 0、未登录退出码 1」先记着，第 05 节讲退出码时还会回来用它——这是脚本里判断「当前到底登没登录」的标准招。

这几条都需要联网。国内访问 Anthropic 账户体系（登录、更新拉包）如果不通，先开「魔法上网」再敲。

💡 一句话总结：命令分三组记——启动会话（claude / claude "提示" / claude -p）、接着上次聊（-c 认最近、-r 点名恢复）、维护账户（update / install / auth）；-c 和 -r 是治「会话失忆」的两味药。

03 最常用的一批标志：逐个讲清

命令认完了，重头戏是标志。标志几十个，但你日常真正高频用的就七八个——我先把这几个讲透，再给你整张表兜底（第 06 节附完整对照表，那是用来「查」的，这节是用来「懂」的）。

-p / --print：不进交互，直接出结果

最重要的一个，没有之一。加上 -p，Claude 就不打开聊天界面了——它读你的提示、干活、把结果打印出来、退出，整个过程没有人盯着。

claude -p "这个项目的 auth 模块是干啥的"

它是 headless（无头，指没有交互界面、纯命令行跑）模式的开关，也是后面所有「塞进脚本」「接管道」玩法的地基。第 04 节专门展开。

--model：这趟用哪个模型

临时指定这一趟会话用哪个模型，覆盖掉你设置里的默认模型：

claude --model sonnet
claude --model opus
claude --model claude-sonnet-4-6   # 也可以写完整名字

可以用别名（sonnet、opus 指向各自最新款），也可以写完整模型名。模型怎么选、各档什么定位，第 05 篇讲过，这里只管「怎么在命令行临时切」。

--permission-mode：这趟从哪种权限模式开

直接决定「Claude 这趟动手前问不问你」。还记得第 20 篇那根「权限缰绳」吗——这个标志就是在启动那一刻把缰绳松紧定好：

claude --permission-mode plan

官方给的可选值有这几个：

接受 default、acceptEdits、plan、auto、dontAsk 或 bypassPermissions。覆盖设置文件中的 defaultMode。

简单说：plan（只规划不动手）、acceptEdits（自动批准改文件）、bypassPermissions（全放行、慎用）这几个最常用。这些模式各自啥脾气，下一篇（第 35 篇）专门拆，这里你只要知道「用这个标志能在启动时一步到位选好模式」。

--dangerously-skip-permissions：那个名字带 dangerous 的开关

这个标志单拎出来说，因为新手最爱问、也最容易乱用。它的作用就是跳过所有权限提示——官方说得明明白白，它等同于 --permission-mode bypassPermissions：

claude --dangerously-skip-permissions

加上它，Claude 改文件、跑命令一律不再停下来问你，闷头干到底。名字里直接写了 dangerously（危险地），就是 Anthropic 在提醒你掂量。第 20、21 篇反复强调过那根「权限缰绳」——这个开关相当于把缰绳整个撒手。

这里有条该守住的红线：只在「明确隔离、坏了也无所谓」的环境里用它——比如一次性的容器、玩具仓库、CI 里的临时沙箱。在你真正的项目目录、尤其碰得到生产数据的地方，碰都别碰。headless 批处理想少点权限提示，优先用 --allowedTools 精确放行几个工具，或者用 --permission-mode acceptEdits 只放开「改文件」——比一刀切全放行安全得多。

--add-dir：让它多看一个目录

默认 Claude 只能读 / 改你启动时所在的那个目录。--add-dir 给它额外开几个目录的访问权：

claude --add-dir ../apps ../lib

典型场景：你的项目和它依赖的另一个库分在两个文件夹，想让 Claude 同时能动两边。注意官方的一句提醒——

授予文件访问权限；大多数 .claude/ 配置不会从这些目录中发现。

也就是说：--add-dir 只给「读写文件」的权限，不会顺带把那个目录里的 CLAUDE.md、Skill 这些配置也加载进来。别指望加个目录就把人家那套配置也继承了。

--output-format：结果按什么格式吐

只在 -p 打印模式下有意义，控制结果长什么样：

claude -p "总结这个项目" --output-format json

三个选项：text（默认，纯文本）、json（带会话 ID、成本等元数据的结构化结果）、stream-json（一行一个 JSON 事件，实时流式）。脚本里想拿到「这趟花了多少钱」「会话 ID 是啥」，就得用 json——第 04 节会演示拿它喂 jq。

--allowedTools / --disallowedTools：白名单 / 黑名单

预先放行（或拒绝）某些工具，免得 headless 跑到一半卡在权限提示上（没人盯着的脚本一卡就废了）：

claude -p "跑测试并修掉失败" --allowedTools "Bash,Read,Edit"

--allowedTools 列出的工具无需提示直接放行；--disallowedTools 反过来拒绝。它俩用的是权限规则语法（详见第 20 篇），比如 "Bash(git diff *)" 只放行 git diff 开头的命令。

注意和 --tools 的区别——--tools 直接从模型上下文里删掉某个工具、让它完全用不了；--allowedTools 只是跳过权限提示，工具本身还在。

几个 headless 专用的「保险丝」

这几个只在 -p 模式下生效，但很实用，专门防脚本失控：

# 限制最多跑几轮，超了报错退出（默认无限制）
claude -p --max-turns 3 "查询"

# API 花费一旦超过这个金额就停（单位美元）
claude -p --max-budget-usd 5.00 "查询"

--max-turns 这里藏着一个小坑：写自动化脚本时忘了加它，万一某次 Claude 陷进反复试错的循环，turn 数蹭蹭涨、费用也跟着涨，脚本没人盯就白白烧钱。稳妥的做法是固定给批量脚本都加上 --max-turns，相当于给它定个「最多折腾几个回合」的硬上限，超了就报错退出，反而踏实。

💡 一句话总结：高频标志记这几个——-p 出结果不进交互、--model 切模型、--permission-mode 定权限松紧、--add-dir 多看目录、--output-format json 拿结构化结果、--allowedTools 预放行工具；脚本怕失控就加 --max-turns / --max-budget-usd 当保险丝。

04 headless 与管道：把 Claude 塞进命令行

这一节是 claude -p 真正发光的地方。前面几十篇 Claude 都是「你打开一个窗口跟它聊」，这一节它变成「命令行里一个能接管道的零件」——可以被别的命令喂数据，也可以把结果吐给下一个命令。

类比：流水线上的一个工位。 交互模式像你坐在工作台前一件件手工做；headless 模式则是把 Claude 焊到一条流水线上——上一道工序（比如 cat、git diff）把料送进来，Claude 加工完，结果直接流到下一道（比如写进文件、喂给 jq）。你不用守在旁边，整条线自己跑。

管道：喂数据进去

非交互模式会读 stdin（标准输入），所以你能像对待任何命令行工具一样，用 | 把数据管道喂给它：

cat build-error.txt | claude -p '简明解释这个构建错误的根本原因' > output.txt

这条命令干了三件事：cat 把日志内容吐出来 → 管道喂给 claude -p → 它解释完，> 把结果写进 output.txt。全程没进任何界面，适合塞进任何自动化流程。

这里有个官方明确的上限值得记：从 v2.1.128 起，管道喂进去的内容上限是 10MB，超了 Claude Code 会报清晰错误并以非零状态退出。要处理更大的输入，把内容写进文件、在提示里引用文件路径，别硬管道。

当项目专属 linter 用

把 headless 调用包进脚本，Claude 就成了你项目的「专属审查员」。官方给的这个 package.json 例子很典型——把对 main 的 diff 喂给 Claude，让它挑拼写错误：

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

之后 npm run lint:claude 就能跑。管道喂 diff 的好处：Claude 不需要 Bash 权限去自己读 diff，料是你喂进去的。

接 jq 处理结构化输出

想在脚本里只取结果文本、或者抓会话 ID，就用 --output-format json 配 jq（一个命令行 JSON 处理工具）：

# 只取结果文本
claude -p "总结这个项目" --output-format json | jq -r '.result'

json 格式吐出来的是个带元数据的对象——结果文本在 .result 字段，会话 ID 在 .session_id，还有 total_cost_usd 这趟花了多少钱。脚本要串起多轮对话，靠的就是先抓 session_id 再 --resume：

session_id=$(claude -p "开始审查" --output-format json | jq -r '.session_id')
claude -p "继续那次审查" --resume "$session_id"

给这趟脚本调用安一个「临时身份」

headless 跑批处理时，常常想让 Claude 在这一趟里扮演某个特定角色——比如「你是安全工程师，专挑漏洞」。用 --append-system-prompt 把这条指令追加到默认系统提示末尾，官方这个例子把 PR 的 diff 喂给它做安全审查：

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

这里要分清两个标志，别用错：--append-system-prompt 是「在默认提示后面追加」，Claude 还保留它原本那套编程助手的本事和安全指令，你只是补一条额外要求；--system-prompt 则是「整个替换掉」默认提示——连工具用法、安全约束全没了，得你自己对剩下的一切负责。九成场景你要的是 append（追加），不是 system-prompt（替换）；只有当 Claude 那套「编程助手」的默认身份压根不适合你的任务时，才用替换。

--bare：脚本里启动更快

还有一个专为脚本生的标志 --bare（裸模式）。官方原话：

最小模式：跳过 hooks、skills、plugins、MCP 服务器、自动内存和 CLAUDE.md 的自动发现，以便脚本化调用启动更快。

说白了，普通 claude -p 会把交互会话那一整套上下文（你的 CLAUDE.md、装的 Skill、配的 MCP）全加载一遍；--bare 把这些全跳过，只留 Bash、读文件、改文件三样基本能力，启动快、且在每台机器上结果一致（不会被某人 ~/.claude 里的私货影响）。CI 和脚本里特别有用。官方文档也明确说了：--bare 将在未来版本中成为 -p 的默认值，现在就养成这个习惯挺值当的。

交互模式和 headless 模式的差别，并排看最清楚：

💡 一句话总结：claude -p 把 Claude 变成命令行里能接管道的零件——cat ... | claude -p ... > out.txt 串流水线、--output-format json 配 jq 抓字段、--bare 让脚本启动更快更干净；没人盯的活儿，权限一定要用标志预先放好。

05 退出码：脚本怎么知道「成了还是没成」

这一节短，但写脚本的人绕不开。

类比：考试的「及格 / 不及格」一个数字。 命令行世界里，每条命令跑完都会留下一个「退出码（exit code）」——一个数字，0 代表成功，非 0 代表出了某种问题。它不是给你看的，是给「上一层脚本」看的：脚本靠这个数字判断「这步成了没，要不要继续往下走」。

你在终端可以这样查刚跑完那条命令的退出码：

claude auth status
echo $?

echo $? 打印的就是上一条命令的退出码（$? 是 shell 里存「上条命令退出码」的变量）。

官方文档里明确给了退出码的命令，挑几条你用得上的：

这玩意儿实际怎么用？ 比如 CI 里想「先确认登录了，没登录就直接让流水线失败」，就靠 claude auth status 的退出码：

# 没登录（退出码非 0）就报错退出，不往下跑
claude auth status || { echo "未登录，终止"; exit 1; }

|| 的意思是「前面那条要是失败了（退出码非 0），就执行后面这段」。在一个每天定时跑的脚本里就可以这么干——开头先 claude auth status 探一下，令牌要是过期了，脚本立刻停在这儿报警，而不是傻乎乎往下跑到一半才发现没登录，白白浪费半天。

记住这条朴素的约定就够了：0 = 成功往下走，非 0 = 出事了该停。Claude Code 各个命令都遵守它，你写脚本判断成败时认准这个数字。

💡 一句话总结：退出码是「给脚本看的成绩单」——0 成功、非 0 出问题；claude auth status 用 0/1 报登没登录，--max-turns 超限和管道超 10MB 都以非零退出，脚本里靠 $? 或 || 接住它。

06 标志全表：用来「查」的那一页

前面讲透了高频的，这一节是兜底——把官方文档里你日常碰得到的标志整理成一张表，专门拿来「查」。标志几十个，没必要背，存着随时翻就行。

提醒一句官方原话：claude --help 不会列出每个标志，所以某个标志在 --help 里没出现，不代表它不能用——以官方 CLI 参考文档为准。

我按「干啥用的」分类列，方便你按需求找：

启动与会话

模型与权限

目录与配置

headless 输出与控制（多数仅 -p 生效）

杂项

这张表覆盖了你前期会用到的绝大多数标志。真要查全集（还有几十个偏门的，比如后台会话、agent team、remote control 相关），去翻官方 CLI 参考页——它才是那本「全集说明书」，本节是「常用速查」。

💡 一句话总结：标志按「启动会话 / 模型权限 / 目录配置 / headless 输出 / 杂项」分类查最快；--help 不全，以官方 CLI 参考为准；这张表管常用，偏门的去官方全集翻。

07 动手：把 claude -p 接进命令行管道

光看表不算会，得真把 headless 跑一遍。下面这套全在终端里完成，不进任何交互界面——亲手体会「Claude 当命令行零件」是什么感觉。用最小示例，不依赖你已有的复杂项目。

这几步需要联网，且会消耗一点额度（每次 -p 调用都是一次真实请求）。国内若 API 不通，先开「魔法上网」。

第一步：最朴素的一次 -p 调用

随便找个目录，在终端敲（不是在 claude 会话里）：

claude -p "用一句话说明 git rebase 和 git merge 的核心区别"

预期：终端直接打印出一句回答然后退出，全程没有那个聊天界面弹出来。看到结果一闪而过、提示符又回来了 = headless 模式跑通了。

第二步：把它接进管道，喂数据进去

造一个小文件当「输入料」，管道喂给 Claude：

printf 'def add(a, b):\n    return a - b\n' > buggy.py
cat buggy.py | claude -p "这段代码有个 bug，一句话指出来"

预期：Claude 读到管道喂进去的代码，回一句类似「函数名是 add 但实际做的是减法（a - b）」。看到它能就「你喂进去的内容」作答 = 管道通了——它根本没用工具去读文件，料是 cat 送进它嘴里的。

第三步：要结构化输出，接 jq 取字段

claude -p "用一句话介绍 Python 是什么语言" --output-format json

预期：这次吐出来的不是纯文本，而是一大坨 JSON，里面有 result（结果文本）、session_id、total_cost_usd 等字段。如果你机器上装了 jq，再试这条只取结果：

claude -p "用一句话介绍 Python" --output-format json | jq -r '.result'

预期：这回只打印出那句干净的结果文本，外层 JSON 被 jq 剥掉了。这就是脚本里「只要那句答案、不要一堆元数据」的标准拿法。

第四步：用退出码判断成败

claude auth status
echo $?

预期：如果你已登录，echo $? 打印 0；没登录则打印 1。这个数字就是脚本判断「该不该往下走」的依据——第 05 节那条 claude auth status || ... 就是接住它。

跑通这四步，你就把「单次调用 → 管道喂料 → 结构化输出接 jq → 退出码判断」这条 headless 完整链路亲手走了一遍。以后想把 Claude 塞进任何脚本、CI、定时任务，本质都是这套零件的排列组合。

💡 一句话总结：动手四步把 headless 走通——裸 -p 出结果、管道 cat | claude -p 喂料、--output-format json | jq 取字段、auth status + $? 判成败；这四块拼起来就是一切自动化的地基。

08 小结

这一篇把你天天敲的那行 claude 彻底摊开了——从「只会光敲一个 claude 进界面」，升级到「命令、标志、管道、退出码全门儿清」。

把核心串起来回顾：

你现在应该能： 看着任意一行 claude xxx --yyy 都拆得清「哪个是命令、哪个是标志、各干啥」；想续上之前的对话知道该用 -c 还是 -r；要把 Claude 塞进脚本时，会用 -p 配管道和 --output-format json，还会拿退出码判断这步成没成；遇到没见过的标志，知道去哪张表查、也知道 --help 靠不住得翻官方全集。这套命令行功夫，是你把 Claude Code 从「一个聊天窗口」真正变成「开发工作流里一个可编排零件」的分水岭。

开头那位光敲 claude 的人，学会 -p 加管道之后，就能把每天手动跑的几个检查全写进脚本——那感觉，像是突然把 Claude 从「副驾」请到了「流水线」上。这一篇就是想让你也有这一刻。

下一篇 35「控制与模式」——这一篇里我反复提到 --permission-mode 能选 plan、acceptEdits、bypassPermissions 这几档，但每一档具体是什么脾气、动手前问你几次、什么场景该切到哪档，我一直按下没展开。下一篇就专门把这几种模式掰开揉碎，连同会话里怎么用快捷键随手切换一起讲透。想想看：同样让 Claude 改一堆文件，「每改一个文件问你一次」和「闷头改完再给你看」，效率和安全感能差出十条街——这中间的拿捏，下一篇见。

35 · 控制与模式：开会话时手里那块「调音台」

兄弟们，咱们这一路下来，命令也会敲了、CLAUDE.md 也会写了、权限也配过了，按说该挺顺了。

可回头看，头一个月里浪费掉的时间，大半不在「不会用」，而在「不会控」——会话明明已经跑起来了，却只会干一件事：打字、回车、等。它输出跑偏了，傻等它跑完；它一上来就动手改文件，没拦住；明明该让它先出个方案的活儿，直接放它进去乱改一通。

说白了，Claude Code 的交互界面，远不止「输入框 + 回车」这么简单。它底下藏着一整套「会话内的控制手段」：一个键切换它的工作模式、一个键把它从跑偏里拽回来、一个命令让它先谋后动、还有花钱买速度的开关。这些东西第 14 篇露过几个快捷键的脸，第 20 篇讲透了权限那一支，但「会话里到底能怎么操纵它」一直没有集中铺开过。

这么说吧：前面教的是「怎么让 Claude 干活」，这一篇教的是「干活过程中怎么实时操纵它」——像坐在调音台前，不是只会按播放，而是每一路推子都摸得到。

看完这一篇，你会拿到：

• 一张「会话内控制手段」全景图——哪个键管中断、哪个键管切模式、哪个键管换模型，一眼归位
• Shift+Tab 循环权限模式的全貌：默认三档之外的 auto / bypassPermissions / dontAsk 怎么进循环、谁排在谁前面（承接第 20 篇，不重讲权限规则）
• Plan Mode（计划模式）不只是「一种权限模式」，更是一套「先出方案、你审完再动手」的工作流——什么时候该用、批准时那几个选项分别是啥
• 快速模式（fast mode）到底买的是什么、值不值、跟「努力级别」有啥区别
• Vim 编辑模式怎么开、几个最实用的手势，以及一个能照着按的动手练习

01 先建个总框架：会话里你能拨的开关分三类

动手记快捷键之前，先在脑子里把「会话内的控制手段」归个类。它们不是一大把零散的键，而是分管三件不同的事。 类分清了，后面记起来就有挂钩。

类比：坐在调音台前。 录音棚那块大台子上密密麻麻的推子和旋钮，看着唬人，其实就三类：一类管「这一路的音量大小」（推子），一类管「整段录还是停、回到哪一段重录」（走带键），一类管「音色怎么调」（均衡旋钮）。你不用全记，但得知道「想干这件事，手该往哪伸」。Claude Code 的会话控制也一样，三类开关各管一摊。

落到 Claude Code，这三类是：

• 管「它的自主权」——也就是权限模式：Shift+Tab 一键循环 default / acceptEdits / plan，决定它动手前问不问你（第 20 篇主讲）。
• 管「它跑的过程」——中断与重定向：Esc 踩刹车、Esc Esc 倒车回退、Ctrl+C 中断或清输入、Ctrl+B 把任务丢后台。
• 管「它怎么响应」——模型与速度：Option+P 换模型、Option+T 开关扩展思考、/fast 开关快速模式。

并排放一张表，对照着看立刻清楚各管各的：

⚠️ macOS 用户先看这条：表里那些 Option+ 开头的快捷键（Option+P、Option+T、Option+O），在 Mac 上多数需要先把终端的 Option 配成 Meta 键才生效——iTerm2 在「设置 → 配置文件 → 键」里把左/右 Option 设成「Esc+」，Apple Terminal 在「设置 → 配置文件 → 键盘」勾上「使用 Option 作为 Meta 键」。官方有个例外：从 v2.1.132 起，Option+T（切换扩展思考）在 Mac 上无需配置就能用。

这张表你不用背，但「这事归哪一类」这个意识得有——想「让它少问」别去按 Esc，想「喊停」别去按 Shift+Tab，分清了就不会乱抓。

💡 一句话总结：会话里的控制手段分三类——管自主权（Shift+Tab）、管过程（Esc / Ctrl+C / Ctrl+B）、管响应（Option+P / /fast）；记不住具体键不要紧，先记住「想干这事，手该往哪一类伸」。

02 管过程：Esc 是刹车，Esc Esc 是倒车

三类里头，最该先练熟的是「管过程」这一类，因为它救场最频繁。把最常用的几个挑出来，逐个说清「什么时候按、按下去发生啥」。

Esc：它跑偏了，一脚刹车

Esc 干一件事：停下 Claude 当前正在做的事——不管是它正在生成回答，还是正在调某个工具调到一半。按下去，它立刻停，然后把光标交还给你，等你重新发话。

关键是官方这句让人安心的话：

停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止完成的工作。

也就是说，Esc 不是「撤销」，是「暂停 + 交还方向盘」。它已经做完的部分（比如已经读完的文件、已经写好的半个函数）都留着，你只是打断它接下来的动作，改个方向让它继续。

最常用 Esc 的场景：让它改个小功能，结果它领会偏了，吭哧吭哧开始大改五六个文件。要是傻等它跑完再纠正，白白浪费它好几分钟的输出；学乖的做法是——一看方向不对，立刻 Esc，然后补一句「停，我只要改 login.js 那一个函数，别动别的」，它当场掉头。这一个键，重度使用下每天保守得按几十次。

Esc Esc：把对话退回上一个点

连按两下 Esc，行为分两种，取决于你输入框里有没有字：

• 输入框里有字：双 Esc 清空它，并把这段草稿存进历史，等会儿按 ↑ 还能调回来。
• 输入框是空的：双 Esc 打开回退菜单——让你从对话里上一个节点恢复，或者总结一下代码和对话。

第二种就是「倒车」：把整段对话退回到之前某个状态。这块属于检查点（checkpoint）的范畴，第 37 篇专门讲，这里你先记住一个动作：输入框空着的时候双击 Esc，能掀开「回到上一个存档点」的菜单。返工的时候常用——感觉「最近这几轮把事情带沟里了」，双 Esc 退回到沟之前那个干净点，重新开口。

Ctrl+C 和 Ctrl+D：别再当退出键瞎按

这俩新手最容易混，一条条钉死：

• Ctrl+C：有操作在跑就中断它；没有操作在跑，第一次按清空输入框，再按一次才退出 Claude Code。
• Ctrl+D：直接退出 Claude Code 会话（EOF 信号）。

这里有个容易踩的小坑：想清空输入框里打了一半的字，顺手 Ctrl+C 一下，没反应又来一下——结果直接把会话退了。原因在于，空输入框上的第二下 Ctrl+C 是退出。所以清输入框宁可用 Ctrl+U（从光标删到行首）或者干脆 Esc Esc，不轻易连按 Ctrl+C。

Ctrl+B：长命令丢后台，别干等

这个救场也猛。Claude 跑一条要很久的命令时（装依赖、跑构建、起开发服务器），你不必干等——按 Ctrl+B 把它丢到后台，Claude 立刻腾出手来响应你的新指令，那条命令在后台接着跑，输出写进文件，它需要时再读回来。

用 tmux 的兄弟注意：tmux 自己的前缀键也是 Ctrl+B，所以在 tmux 里得按两下才能把任务丢后台。这个点很容易被坑，记牢。

💡 一句话总结：Esc 是刹车（跑偏就拽回来）、Esc Esc 是倒车（退回上一个点）、Ctrl+C 别乱连按（空框第二下就退）、长命令用 Ctrl+B 丢后台——这四下练成肌肉记忆，会话里就再也不会干等或误退了。

03 管自主权：Shift+Tab 循环模式的完整版

权限模式那张「从严到松」的光谱，第 20 篇已经讲透了——default 步步问、acceptEdits 改码免问、plan 只看不动、auto 有分类器兜底、bypassPermissions 完全裸奔、dontAsk 只认预批准。这一节不重讲它们各是啥（忘了回去翻第 20 篇），只补一件那篇没细抠的事：Shift+Tab 这个循环，到底怎么转。

先把基本盘立住：会话里随手按 Shift+Tab，在三种模式间转圈：

default → acceptEdits → plan → （再按回到 default）

当前是哪档，看状态栏。比如切到 acceptEdits，状态栏会亮 ⏵⏵ accept edits on。这是默认循环，只有这三档。

那 auto、bypassPermissions、dontAsk 去哪了？它们不在默认循环里，得满足条件或带参数才会被「插」进来。 官方把规则写得很细，我给你翻译成人话：

• auto（自动模式）：当你的账户满足 auto mode 的全部要求时，它才出现在循环里。第一次循环到它，会弹一个「选择加入」提示，你点同意它才正式入列；要是你选「不，不再询问」，它就被踢出循环。
• bypassPermissions（跳过一切检查）：只有你用 --permission-mode bypassPermissions、--dangerously-skip-permissions 或 --allow-dangerously-skip-permissions 启动之后，它才出现。注意 --allow- 那个变体只是把它加进循环但不立刻激活。
• dontAsk（只认预批准）：永远不进循环，只能用 --permission-mode dontAsk 启动时指定。

更细的一条，官方明确了插队的位置，免得你按到一半发现顺序不对：

启用的可选模式在 plan 之后插入，bypassPermissions 优先，auto 最后。如果您同时启用了两者，您将在前往 auto 的途中循环通过 bypassPermissions。

把这句翻成你按键时的实际体验：假设你两个都启用了，那一圈 Shift+Tab 转下来是这样的——

default → acceptEdits → plan → bypassPermissions → auto → （回到 default）

auto 永远排在最后一个，bypassPermissions 在它前面。记住这个顺序，你就知道再按几下能到你要的那档，不用瞎转。

推荐的实操习惯，跟第 20 篇说的一致——绝大多数时候只在默认三档里 Shift+Tab 手动切：接陌生项目先切 plan 让它通读出方案，信得过方向了切 acceptEdits 放它改，改完想严一点再切回 default。bypassPermissions 只在隔离容器里用启动参数开，别挂进日常循环——这道红线第 20 篇画过，不重复了。

💡 一句话总结：Shift+Tab 默认只在 default / acceptEdits / plan 三档转；auto / bypassPermissions 要满足条件或带启动参数才入列，顺序是 「plan 之后，bypassPermissions 在前、auto 垫底」——记住这个排位，按几下心里就有数。

04 Plan Mode：不止是一种模式，是一套「先谋后动」的工作流

上一节把 plan 当作循环里的一档一笔带过，但它值得单开一节——因为 Plan Mode 的真正价值，不在「它是种只读模式」，而在它背后那套「先出方案、你审完再动手」的完整工作流。 这是用得最频繁、也最推荐小白尽早养成习惯的一个控制手段。

类比：导演喊「先走一遍戏」。 正式开拍前，导演经常让演员先彩排一遍——走位、台词、节奏全过一遍，但不开机、不消耗胶片。看着没问题了，才喊「开机，实拍」。Plan Mode 就是这个「走戏」环节：Claude 把整件事在脑子里走一遍，读文件、做调研、写出「我打算这么改」的方案，但一个字都不真动你的源码；你看完点头，它才「实拍」开始改。

官方把它的行为界定得很清楚：

Plan mode 告诉 Claude 研究并提议更改而不进行更改。Claude 读取文件、运行 shell 命令进行探索，并编写计划，但不编辑您的源代码。

怎么进、怎么出

进 Plan Mode 有两条路：

• Shift+Tab 循环到 plan——管整段会话，直到你切走。
• 单条提示前加 /plan——只让这一条提示走计划模式，适合「就这一件事我想先看方案」。

/plan 帮我把用户登录从 session 改成 JWT，先别动，告诉我你打算怎么改

想中途退出而不批准计划？再按一次 Shift+Tab 循环走就行。

方案出来了，批准时那几个选项是啥

这是 Plan Mode 最有「工作流」味道的一步，也是新手最容易懵的地方。当 Claude 把方案写好，它会停下来问你「接下来怎么办」，给的选项大致是这几个：

• 批准并在 auto mode 中启动——你完全信方向，放它自动干到底。
• 批准并接受编辑——切到 acceptEdits，改码免问，但危险命令还会停。
• 批准并手动审查每个编辑——回到 default 那种步步确认。
• 继续规划并给反馈——方案还不够好，你提意见让它再改方案。

看明白没有？批准计划这一下，等于「同时选定了接下来用哪种权限模式」。 它退出 Plan Mode，直接把会话切到你选的那档，然后开始动手。这就是为什么说 Plan Mode 不是孤立一档，而是串起整条「探索 → 出方案 → 选自主权 → 动手」流程的枢纽。

还有两个官方给的细节，挺实用：

• Ctrl+G 直接编辑方案：方案写出来了，但你想亲手改两笔（比如「这一步删掉，顺序换一下」），按 Ctrl+G 在你的默认文本编辑器里打开它，改完再让 Claude 照着干。
• 批准会自动给会话命名：除非你已经用 --name 或 /rename 起过名，否则批准计划时它会照方案内容自动命名这个会话，以后 /resume 找起来方便。

一个典型用法

说白了，接任何一个不熟的项目，第一件事就是切 Plan Mode 让它通读一遍、出个方案。 比如接手一份别人留下的老代码，几万行，啥都不懂。直接 Shift+Tab 到 plan，扔一句「通读这个项目，告诉我整体结构和你建议从哪改起」。它读了一圈、列了份结构 + 改造建议，看完才能心里有底地放它进去。要是一上来就 acceptEdits 让它瞎改，大概率是一场灾难。 这个习惯，强烈建议你尽早养成。

💡 一句话总结：Plan Mode 是「先走戏后实拍」——它只研究、只出方案、不动源码；批准方案那一下会顺带选定接下来的权限模式（auto / acceptEdits / 手动审查），Ctrl+G 还能让你亲手改方案。接陌生项目先 /plan，稳得多。

05 快速模式（fast mode）：花钱买的是速度，不是质量

⚠️ 研究预览功能，可能变化：fast mode 目前是研究预览版，功能、定价、可用性都可能随时调整；且要求 Claude Code v2.1.36 或更高版本。

讲完「怎么控方向」，再讲一个「控速度」的开关——快速模式。先把最容易误解的一点摆正：

快速模式不是换了个更强的模型，它换的是同一个 Opus 的「跑法」。 官方说得很直接：

快速模式不是一个不同的模型。它使用 Claude Opus，但采用不同的 API 配置，优先考虑速度而不是成本效率。您获得相同的质量和功能，只是响应速度更快。

具体快多少、贵多少？官方给的数字：最多快 2.5 倍，代价是每个 token 更贵。它只在 Opus 4.8 / 4.7 / 4.6 上支持，Sonnet、Haiku 用不了（⚠️ Opus 4.6 的快速模式已弃用，建议用 4.7 或 4.8）。

怎么开

就一个命令：

/fast

输入 /fast 按 Tab 键打开或关闭。开了之后：

• 如果你当时用的是别的模型，它会自动切到 Opus。
• 你会看到提示 Fast mode ON，提示框旁边冒出一个小 ↯ 图标。
• 随时再 /fast 一下，能查当前是开还是关。

有个反直觉的点要记牢：关掉快速模式后，你还停在 Opus 上，模型不会自动切回你原来那个。想换回别的模型，得自己 /model。

值不值：看你这会儿缺速度还是缺钱

到底啥时候开？官方给的判断和实际体感一致——看你这个任务「延迟」和「成本」哪个更要命：

还有一条省钱的关键细节，官方反复强调，也很容易踩：

为了获得最佳成本效率，在会话开始时启用快速模式，而不是在对话中途切换。

为啥？因为第一次开快速模式时，你要为「整个对话上下文」付一次完整的快速模式输入费。对话拖得越长再开，那一下越贵。所以要开就一开始开，别等聊了半天、上下文一大坨了才想起来开。这一下很容易交学费——一个聊了很久的会话中途开 fast，账单上那一下会明显比预期高。

别和「努力级别」搞混

最后澄清一个常见混淆：快速模式 ≠ 调努力级别。这俩都影响速度，但路子完全不同：

一句话：快速模式不牺牲质量、只多花钱；调低努力级别是少思考、可能牺牲质量。 俩还能叠着用——简单任务上「快速模式 + 低努力级别」，速度拉满。

⚠️ 订阅用户额外注意：对 Pro/Max/Team/Enterprise 订阅用户，快速模式只走「使用额度」、不含在订阅速率限制里，从第一个 token 起就按快速模式费率单独计费。换句话说，它是要额外掏钱的，不是订阅白送的。开之前心里有数。

💡 一句话总结：快速模式买的是同一个 Opus 的速度（最多 2.5 倍），代价是更贵；/fast 开关，要开就会话一开始开（中途开那一下更贵）；赶时间就开、跑长任务就关，别和「调努力级别」混为一谈。

06 Vim 编辑模式：给你的输入框装上老司机手势

最后一个控制手段，服务的是「你怎么编辑自己打的字」——Vim 模式。如果你压根没用过 Vim，这一节可以扫一眼就跳过，它不影响你用 Claude Code；但你要是 Vim 老手，开了它输入体验会顺手得多。

Claude Code 的输入框默认是普通文本框（随便打字、方向键移动）。开了 Vim 模式，它就有了 Vim 那套「两种状态」：

• INSERT（插入）模式：跟普通输入框一样，打字就是打字。
• NORMAL（普通）模式：键不再是字符，而是「命令」——h/j/k/l 移光标、dd 删一行、w 跳下一个词、0 跳行首、$ 跳行尾……Vim 那套全套搬过来了。

怎么开

通过 /config 菜单，找到「编辑器模式（Editor mode）」，切成 vim 即可。开了之后：

• 按 Esc 进 NORMAL 模式（这时候按键是命令）。
• 按 i / a / o 等回到 INSERT 模式开始打字。

下面几个是输入框里用得最多的，给完全没接触过的兄弟感受一下：

有个 Vim 老手会喜欢的细节：在 NORMAL 模式下，如果光标已经在输入的最顶或最底、没法再往上/往下移了，这时按 j/k 或方向键，会去翻命令历史。 等于「移动」和「翻历史」无缝接上了。

说句实话，这个模式纯属「锦上添花」。Vim 重度用户开了它编辑长提示确实爽；但对不少小白来说压根没必要碰——普通文本框配上第 02 节那几个快捷键（Ctrl+U 删到行首、Ctrl+W 删词）已经够用了。所以：是 Vim 党就开，不是就别折腾，这不是必修课。

💡 一句话总结：Vim 模式给输入框装上 NORMAL/INSERT 两态和全套 Vim 手势，/config → 编辑器模式开启；Vim 老手开了顺手，纯新手完全可以跳过，不影响任何功能。

07 动手：把这套控制手段连起来跑一遍

光看不练记不住。下面给你设计一个5 分钟、不依赖任何复杂项目的练习，把本篇几个核心控制手段串起来按一遍，每步都给「预期看到啥」，你照着走、对照验证。

随便找一个空目录，claude 启动，然后：

第一步：练 Shift+Tab 切模式，盯状态栏

启动后，连续按几下 Shift+Tab，眼睛盯着状态栏。

预期：状态栏文字在三档之间循环变化——切到 acceptEdits 时显示类似 ⏵⏵ accept edits on，切到 plan 时显示计划模式提示，转一圈回到默认（状态栏那行模式提示消失或显示默认）。确认你能靠状态栏认出当前在哪档。

第二步：进 Plan Mode，让它出个方案（但别真动）

Shift+Tab 切到 plan，然后输入一个会触发它「想动手」的请求：

在当前目录创建一个 hello.txt，里面写一行 "hi from claude"

预期：它不会真的创建文件，而是给你一段「我打算这么做」的说明，末了停下来问你怎么继续（批准并接受编辑 / 手动审查 / 继续规划……）。确认目录里此刻并没有 hello.txt——这就是 Plan Mode「只走戏不实拍」。

第三步：批准方案，观察它切了模式

在它给的选项里，选「批准并接受编辑」（或手动审查那项）。

预期：它退出 Plan Mode，状态栏切到了你选的那档（选了接受编辑就显示 accept edits on），然后真的把 hello.txt 创建出来。确认这时目录里有了文件，且模式已经从 plan 变成你批准时选的那个——亲眼看一遍「批准计划 = 顺带选定权限模式」。

第四步：练 Esc 喊停

再给它派一个稍微长点的活儿（比如「把这个目录下所有文件逐个读一遍并总结」），在它跑起来的当口，按一下 Esc。

预期：它当场停下，把控制权交还给你，光标回到输入框。它已经做完的部分（比如已经读了的文件）保留着。你可以紧接着补一句新指令重定向它。确认 Esc 是「暂停交还」而不是「报错崩溃」。

第五步（选做）：查一下快速模式开关

输入 /fast 按 Tab，看看提示。

预期：如果你的账户支持，会看到 Fast mode ON 和提示框旁的 ↯ 图标；再 /fast 一下关掉。如果你的账户/计划不支持或没开使用额度，会看到类似「fast mode 不可用」的提示——这一步是「能开就体验、不能开也正常」，不必强求。

跑完这五步，本篇的核心控制手段你就全都亲手摸过一遍了。新手尤其要走一遍第二、三步——「在 Plan Mode 里它不动手、批准后才动手并切了模式」这个体感，看十遍文档不如自己按一次。

💡 一句话总结：照着这五步把 Shift+Tab 切模式、Plan Mode 出方案与批准、Esc 喊停、/fast 开关连起来按一遍，每步对照「预期看到啥」自验；尤其第二三步，亲手体会「计划模式只走戏、批准才实拍且顺带切模式」。

08 小结

这一篇把「会话已经开起来之后，你手里那块控制台」铺开讲了一遍。第 20 篇给你的是权限那根缰绳，这一篇给你的是全套操纵杆。

把核心串起来回顾：

你现在应该能： 在一个跑起来的会话里游刃有余地操纵 Claude——Shift+Tab 切到合适的自主权档位、Esc 把跑偏的它一脚拽回来、用 Plan Mode 让陌生项目「先出方案你审完再动手」、按需要 /fast 拿速度、Vim 党还能用熟悉的手势编辑提示。说白了，你从「只会打字回车干等」，升级成了「全程手握操纵杆、随时能控」。

整个第五组「系统配置与优化」走到这儿，配置文件、输出样式、钩子、CLI 标志、控制与模式都铺过了，你对 Claude Code「怎么配、怎么控」已经有了系统的把握。

下一篇 36「斜杠命令（Slash Commands）」，把视线收回到那个最不起眼、却天天在用的小符号上——/。本篇里你已经敲过 /plan、/fast、/config 好几个斜杠命令了，但它们到底有多少、能不能自己造一个属于自己的 / 命令？想想看：那些你天天手打的固定流程，要是能压成一个 / 一键喊出来，会省多少事——下一篇见分晓。

36 · 斜杠命令（Slash Commands）：一个 / 调出 Claude 的所有快捷动作

很多人刚用 Claude Code 那阵，都干过一件挺蠢的事。

每次想清空对话重开，都老老实实做这么一套：先 Ctrl+C 退出 claude，再在终端重新敲 claude 启动，等它重新加载一遍项目、读一遍 CLAUDE.md——前前后后小十秒。这么连着干上一两周，心里还觉得「重启嘛，本来就该这样」。直到翻官方文档，撞见一个 /clear 命令，一句话写着「开一段空上下文的新对话」。这才发现：原来在会话里打三个字符就行，那两周的重启全是白费功夫。

更打脸的是后面。/compact 能把长对话压缩了接着聊、/model 能不重启直接换模型、/init 能一键生成 CLAUDE.md……全是要么之前手动硬来、要么压根不知道能干的事。这些命令一直就躺在那个 / 菜单里，打个斜杠就全列出来了，却一个都没翻过。

说这段糗事是想让你别走弯路：斜杠命令不是「高级玩法」，它是 Claude Code 最基础的控制面板。你在会话里想干的绝大多数「元操作」——不是让它写代码，而是调教它本身——入口都在这一个 /。这一篇先把内置的那批给你认全，再教你把那些天天手打的提示，刻成你自己的一键命令。

看完这一篇，你会拿到：

• 一句话说清斜杠命令是什么、为什么它只在消息开头才算数
• 一张「按使用场景分组」的内置命令清单（/help、/clear、/compact、/init、/model、/agents、/mcp、/memory 等），不用背、按需查
• 自己写一个斜杠命令的完整步骤：.claude/commands/ 下扔个 markdown、加 frontmatter、用 $ARGUMENTS 传参
• 一招进阶玩法：让命令在发给 Claude 前自己把 git diff 这类「现场数据」填进去
• 命名空间是怎么回事，为什么插件带的命令永远不会跟你的撞名
• 斜杠命令和 Skill 到底什么关系（一句话：slash command 就是 Skill 的「主动喊」用法，详见第 26 篇）
• 一个能照着跑、给了预期输出的实战：5 分钟刻一个带参数的 /explain 命令并验证

01 先搞懂：斜杠命令到底是个啥，凭什么只在开头算数

先给结论：斜杠命令就是你在 Claude 会话里打的「控制指令」——不是说给 Claude 听让它干活，而是直接命令 Claude Code 这个程序本身：切模型、清上下文、跑个流程、开个面板。

你回想前面三十多篇，跟 Claude 打交道一直分两种话。一种是正经需求：「帮我把这个函数重构一下」「这段报错咋回事」——这是说给模型听的。另一种是元操作：「把对话清了重开」「换成更省的模型」「生成一份项目说明」——这些不该靠跟模型「聊」，而该有个直接的开关。斜杠命令就是这批开关的统一入口。

类比：电视遥控器上那排印好的按钮。 你看电视，调台、调音量、切信源、开菜单——不会冲着电视喊「请帮我把声音调大」，你按遥控器上对应的那颗按钮。每颗按钮干一件确定的事，按下去立刻生效，不用解释、不会理解错。斜杠命令就是 Claude Code 的这排按钮：/clear 是清屏键、/model 是切信源键、/help 是那颗菜单键——打下去执行的是程序写死的固定动作，跟「求模型帮忙」是两码事。

官方对它的定位讲得很干脆：

命令从会话内部控制 Claude Code。它们提供了一种快速切换模型、管理权限、清除上下文、运行工作流等的方法。

这里有个新手最容易栽的点，官方专门强调过——斜杠命令只在消息的开头才被识别：

命令仅在消息开头被识别。命令名称之后的文本作为参数传递给它。

说白了：你得让 / 当这条消息的第一个字符，它才被当成命令。如果你写「帮我看看 /clear 是干嘛的」，这个 /clear 在句子中间，不会被执行，只会被当成普通文字发给 Claude。这个设计是有道理的——否则你跟 Claude 讨论命令本身时，一提到 /clear 对话就被清了，那不乱套了。记住：命令打头，后面跟的全是参数。

落到你真实会遇到的几个瞬间，体会一下这排「按钮」啥时候按：

• 聊着聊着发现模型不够强——不用退出重开，打 /model 当场换上更强的，对话不断。
• 一个任务干完了，想换个全新的活儿——打 /clear 把台面擦干净，旧对话还能 /resume 找回来。
• 刚 clone 了个陌生项目，想让 Claude 先懂它——打 /init，它读一遍代码、给你吐一份 CLAUDE.md。

这几件事的共同点：都不是「让 Claude 写代码」，而是「调教 Claude Code 本身」——这正是斜杠命令的主场。

那怎么知道有哪些命令可用？最省事的办法——在会话里打一个 /，菜单立刻弹出来，列出你当前能用的全部命令；接着再多打几个字母，它会实时筛选。官方原话：

输入 / 查看你可用的每个命令，或输入 / 后跟字母进行筛选。

💡 一句话总结：斜杠命令是 Claude Code 的「控制按钮排」——管的是程序本身（切模型、清上下文、跑流程），不是给模型派活；它只在消息开头才算数，打一个 / 就能看到全部可用命令。

02 内置命令清单：不用背，按「你在干哪一步」来查

内置命令有几十个，真要一个个背，纯属跟自己过不去。Claude Code 官方文档自己也是按「一次会话的典型流程」来组织的——你处在哪一步，自然就该用哪几个。我把最常用的按这个思路理成几组，对着「你现在想干啥」找那一行就行。

先说清楚一件事：这几十个里，绝大多数是「内置命令」（行为写死在 CLI 里，按下去执行固定逻辑），还有一小撮在文档里标着 Skill——那是「捆绑 Skill」，本质是给 Claude 的一份提示，让它用自己的工具去编排完成（比如 /code-review、/debug）。另有更少的几个标着 Workflow——那是多 subagent 并行的动态流程（如 /batch、/deep-research），调用体验一样，底层更复杂，这里知道有这回事即可。三种你都用 / 加名字调，用起来没区别，差别只在底层怎么实现——这个细节第 26 篇讲 Skill 时拆过，这里不展开。

第一组：刚进一个项目，搭场子用的

这一组进新项目时基本是固定套路：先 /init 让它读一遍代码、吐一份 CLAUDE.md 草稿，再 /memory 进去把它瞎猜错的几条改对。省得从零手写那份说明——这套流程头一回用的时候，是真有点惊喜。

第二组：干活干到一半，调状态用的

/clear 和 /compact 这俩最容易混，开头那段栽的坑就是没分清「清空」和「压缩」。一句话切：换个不相干的新活儿用 /clear（台面全擦掉重开），同一个任务但聊太长了用 /compact（把草稿纸整理成一页要点接着干）。第 19 篇专门拆过这对，这里你记住「换任务 clear、续任务 compact」就够。

第三组：活儿要交出去之前，检查用的

第四组：杂项里你早晚会用到的几个

注意：不是每个命令对每个人都显示。 官方说得明白——「可用性取决于你的平台、套餐和环境」。比如 /desktop 只在 macOS 和 Windows 上、且用 Claude 订阅登录时才出现，/upgrade 只在 Pro 和 Max 套餐上才有。你打 / 看到的那张菜单，就是你这台机器、这个账号此刻真正能用的全集——以它为准，别拿别人截图里的命令较真。

这四组我没给全（官方那张总表有几十行），但覆盖了你日常九成的场景。剩下的，临时想干啥，打个 / 加几个字母筛一下，比翻文档实在得多。

💡 一句话总结：内置命令别硬背，按「你在哪一步」分组查——搭场子（/init /memory /mcp /agents）、干活中（/model /clear /compact /context）、交付前（/diff /review /code-review）、杂项（/help /doctor /resume）；菜单是你这台机器的真实全集，打 / 即见。

03 自己刻一个命令：.claude/commands/ 下扔个 markdown 就行

内置命令认全了，真正让斜杠命令好用的，是你能自己造。

为啥要自己造？想想你日常跟 Claude 打交道里那些「重复劳动」——每次让它提交代码都叮嘱同一套规矩、每次审 PR 都打同一段开场白、每次解释代码都强调「说人话别堆术语」。同一段提示打第五遍的时候，就是信号：该把它刻成一个命令了。

类比：给遥控器编一个「学习键」。 好点的万能遥控器上有颗「学习键」——你把一串常用操作（开机→切到 HDMI2→音量调到 15）录进去，以后按一下这颗键，整串动作自动跑完，不用再一颗颗按。自定义斜杠命令就是这颗学习键：你把一段反复要敲的提示「录」成一个命令，以后打一下命令名，那段提示自动发出去。

怎么造？简单到你可能不信——在 .claude/commands/ 目录下扔一个 markdown 文件，文件名就是命令名。官方文档写得很清楚：

.claude/commands/deploy.md 中的文件……会创建 /deploy。

也就是说，你建一个 .claude/commands/commit.md，里面写上你那套提交规矩，它就自动变成了 /commit 命令。文件名（去掉 .md 后缀）就是你打的命令名，零配置。

举个最朴素的例子。你新建 .claude/commands/review.md，里面写：

请审查我当前未提交的改动，重点看三件事：
1. 有没有缺失的错误处理
2. 有没有写死的配置值（端口、密钥、路径）
3. 有没有该补而没补的测试

用中文逐条列出，每条标明在哪个文件。

存好之后，你在会话里打 /review，Claude 收到的就是上面这整段提示——等于你把那段话一字不差地敲了一遍，但你只打了七个字符。

这里有个关于「放哪」的关键区分，跟前面讲 MCP、Skill 时一脉相承：

逻辑跟 Skill 完全一致：这命令是这个项目专属、还想让协作者也用的（比如本项目的发版流程），放项目级并提交进版本库；只有你自己、跨项目通用的（比如你个人的解释代码习惯），放个人级 ~/.claude/commands/。~/.claude/commands/ 里常年躺着几个跨项目的小命令，换到哪个项目都在，这点比每个项目重配省心多了。

💡 一句话总结：自定义命令就是「把反复打的提示录成一键」——在 .claude/commands/ 下放个 markdown，文件名即命令名，零配置；放项目级全队共享、放 ~/.claude/commands/ 个人跨项目通用。

04 给命令加料：前置配置（frontmatter）和 $ARGUMENTS 传参

上一节那个 /review 已经能用了，但它有个明显的局限：内容写死，不能传参。你没法告诉它「就审 src/auth.ts 这一个文件」——它每次都审全部改动。要让命令灵活起来，得加两样东西：前置配置（frontmatter） 和 参数占位符。

用 $ARGUMENTS 接住你传的参数

先解决传参。Claude Code 提供了一个占位符 $ARGUMENTS——命令名后面你打的所有内容，都会替换到这个占位符的位置。官方文档给的例子最直观：

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix

官方原话解释它的效果：

当你运行 /fix-issue 123 时，Claude 收到「Fix GitHub issue 123 following our coding standards…」

看明白了吗？你打 /fix-issue 123，那个 123 就被塞进了 $ARGUMENTS 的位置。一个命令模板，参数随你换——这才是命令真正好用的地方。

还有个贴心的兜底：官方说，如果你传了参数、但命令里压根没写 $ARGUMENTS，Claude Code 会把 ARGUMENTS: <你的输入> 自动追加到命令内容末尾，「以便 Claude 仍然看到你输入的内容」。所以就算你忘了写占位符，参数也不会凭空丢掉。

想传好几个参数？用 $0 $1 按位置取

要是一个命令得传多个参数怎么办？比如「把 SearchBar 组件从 React 迁到 Vue」，这里有三个独立的值。官方提供了按位置取参的写法——$ARGUMENTS[N]，或者更短的 $N（都从 0 开始数）：

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

你运行 /migrate-component SearchBar React Vue，$0 就是 SearchBar、$1 是 React、$2 是 Vue。注意一个坑：官方说这些按位置取的参数走的是「shell 风格的引用」——所以多个词的值要用引号包起来才算一个参数。比如 /my-cmd "hello world" second，$0 才是完整的 hello world，否则会被空格拆开。（而 $ARGUMENTS 不受影响，它永远是你输入的那整串原文。）

用 frontmatter 控制命令的行为

光能传参还不够。你那个 /deploy、/commit 命令是带副作用的——你肯定不希望 Claude「看你代码像写好了」就自作主张帮你部署。这就要靠 frontmatter 来管。

frontmatter 就是写在文件开头两道 --- 之间的一块 YAML 配置（这个概念第 26 篇讲 SKILL.md 时见过，自定义命令文件支持完全相同的 frontmatter）。最该知道的两个字段：

---
description: 把当前改动暂存并提交
disable-model-invocation: true
---

把当前改动提交，commit 信息用中文、前缀按 feat/fix/docs：

1. 先跑测试套件
2. git add 改动
3. 用规范的中文信息提交

• description：一句话说明这命令干啥。Claude 靠它判断「要不要自动用这个命令」，所以建议都写上。
• disable-model-invocation: true：设成 true，这个命令就只有你能手动喊，Claude 不会自动触发它。带副作用、你想亲手掐时机的活儿（部署、提交、发消息），都该加这一条。

这就引出一个你必须搞清的认知，省得它「擅自行动」吓你一跳——你的自定义命令默认是「你和 Claude 都能调」的。你打 /commit 是手动调；但因为你写了 description，Claude 在它觉得对得上的时候，也可能自己调。这正是斜杠命令和 Skill 是「一回事」的体现（详见第 26 篇）——怕它自动乱动手，就加 disable-model-invocation: true 锁成纯手动。/commit 这类命令第一条就该是它，不然有几次它真会差点替你把没看完的改动提交了。

💡 一句话总结：$ARGUMENTS 接住命令名后的全部输入、$0/$1 按位置取（多词值要加引号）；frontmatter 里 description 让 Claude 知道何时用、disable-model-invocation: true 锁成纯手动——带副作用的命令务必加后者。

05 进阶一招：让命令自带「现场数据」

到这儿你的命令已经能传参了，但还有个更狠的招——让命令在发给 Claude 之前，自己先把现场数据填进去。这招叫动态上下文注入（dynamic context injection），是自定义命令文件最被低估的一个能力。

先说它解决什么。你那个 /review 命令，里头写的是「请审查我当前未提交的改动」——但 Claude 拿到这句话，还得自己去跑一遍 git diff 才知道你改了啥。能不能在它读到命令之前，就把 diff 直接塞好？能。

写法是在命令里写 !`命令` ——一个感叹号加反引号包住一条 shell 命令。官方文档讲得很清楚：

!`<command>` 语法在将内容发送给 Claude 之前运行 shell 命令。命令输出替换占位符，因此 Claude 接收实际数据，而不是命令本身。

举个例子，把 /review 升级一下。你在 .claude/commands/review.md 里这么写：

## 当前改动

!`git diff HEAD`

## 说明

审查上面这段改动，重点看缺失的错误处理、写死的配置值、该补的测试。用中文逐条列出。

那行 !`git diff HEAD` 会发生什么？官方说的执行顺序是这样的：

1. Claude Code 先把 git diff HEAD 跑了
2. 把这条命令的输出替换到那一行
3. Claude 看到的，是已经填好你此刻真实 diff 的完整提示

也就是说，Claude 拿到手的不是「去跑个 diff」，而是「这是用户的改动：……（真实内容），请审查」。这是预处理，不是 Claude 自己执行的——它只看到最终填好的结果。给那个 /review 加上这一行之后，明显能感觉它「上来就进入状态」，不用再绕一圈先查改动了。

几个用之前得知道的细节，免得踩坑：

• 感叹号得在行首、或紧跟空白后才生效。要是写成 KEY=!cmd“ 这种紧贴在别的字符后面，它就被当成普通文字，命令不会跑。
• 多行命令别用内联写法，改用 ```! 开头的围栏代码块（里面一行一条命令）。
• 这能力能被关掉：设置里有个 disableSkillShellExecution，设成 true 后这些命令一律不执行、替换成英文提示 [shell command execution disabled by policy]。在团队的托管设置里它最有用——防止有人在共享仓库的命令里塞个乱跑的 shell 命令。

顺带一个自动补全的小贴士：frontmatter 里加一行 argument-hint（比如 argument-hint: [issue-number]），你打命令名时自动补全会提示「这命令该传啥参数」。命令多了之后，这点提示能帮你少翻文档。

💡 一句话总结：!`命令` 能让斜杠命令在发给 Claude 前先把现场数据（如 git diff）填进去，Claude 拿到的是真实数据而非「去跑个命令」；感叹号要在行首、多行用 ```! 块、团队可用 disableSkillShellExecution 一键禁掉。

06 命名空间：为什么插件带的命令永远不撞名

自己造命令多了、再装几个插件（每个插件也带一堆命令），一个现实问题就来了：会不会撞名？ 比如你写了个 /review，装的某个插件里也有个 /review，打下去到底跑哪个？

先说会撞的那种和不会撞的那种，关键看命令从哪来。

你自己的命令之间：靠优先级定胜负

如果是你自己的 .claude/commands/ 文件和 .claude/skills/ 里的 Skill 同名——官方给了明确规则：

如果 skill 和命令共享相同的名称，skill 优先。

也就是说，你有个 .claude/commands/deploy.md，又有个 .claude/skills/deploy/SKILL.md，打 /deploy 走的是那个 Skill。记住这条「同名 Skill 赢」就行，平时你也很少会故意造俩同名的。

插件带的命令：靠命名空间，根本不会撞

插件的处理方式更彻底——它压根不跟你抢名字。官方原话：

插件 skills 使用 plugin-name:skill-name 命名空间，因此它们不能与其他级别冲突。

类比：手机通讯录里给同名的人加公司前缀。 你通讯录里有俩「张伟」，你会怎么存？多半备注成「张伟（红杉）」「张伟（高瓴）」——加个前缀，俩人就再也不会混。命名空间干的就是这事：插件 my-plugin 里那个 review，在你这儿叫 /my-plugin:review，前面那截插件名就是「公司前缀」。所以哪怕你自己也有个 /review，俩命令一个带前缀一个不带，井水不犯河水。

这就是为什么前面第 24 篇讲插件时说「插件 Skill 永远不会跟你的撞名」——靠的就是这套 插件名:命令名 的命名空间。装多个插件、每个都带 review，它们分别是 /plugin-a:review、/plugin-b:review，各喊各的。

还有一类带「双下划线」的命令你可能撞见：MCP server 暴露的提示。官方说它们用 /mcp__<server>__<prompt> 这种格式，从连上的 server 动态发现。看到一个 /mcp__github__xxx 别懵——那是某个 MCP server 自带的命令（详见第 22 篇）。

💡 一句话总结：自己的命令同名时 「Skill 赢过 command」；插件命令靠 插件名:命令名 命名空间，天生不撞；MCP server 的命令是 /mcp__<server>__<prompt> 格式——三种来源，认前缀就不会乱。

07 斜杠命令和 Skill：到底什么关系，一句话理清

学到这儿你可能犯嘀咕了：斜杠命令、Skill，这俩听着怎么这么像？我刚在 .claude/commands/ 写的东西，跟第 26 篇在 .claude/skills/ 写的 SKILL.md，到底啥区别？

这是个好问题，也是新手最容易绕进去的一个结。一句话给你解开：

自定义斜杠命令，已经被官方合并进了 Skill 体系。 你的 .claude/commands/ 文件照样能用，但 Skill 是「升级版」——多了能带配套文件、能由 Claude 自动触发、描述先进上下文而长文档调用时才加载（而非全量预载）这几样本事。

官方那句原话很直接：

自定义命令已合并到 skills 中。.claude/commands/deploy.md 中的文件和 .claude/skills/deploy/SKILL.md 中的 skill 都会创建 /deploy 并以相同的方式工作。

所以这俩根本不是对立的两个东西，而是同一个能力的两种写法。换个角度说：「斜杠命令」更像是一种「调用方式」（你打 / 主动喊），而 Skill 是那个被喊的「本体」。第 26 篇那张表已经把 Skill、slash 命令、Subagent 的定位讲透了，这里我只补一张「同一件事，两种写法怎么选」的对照：

一条经验法则： 就一段提示、自己手动喊一下的小活儿（像那个 /review），老式 .claude/commands/ 一个 markdown 最省事，别折腾；一旦你发现「想给它配个模板」「想塞份长文档但别占上下文」「想让它自己判断该不该用」——就该升级成 Skill（怎么写见第 26、27 篇，懒得手写就用第 28 篇的 skill-creator）。

说白了，你这一篇学的「自定义斜杠命令」，就是 Skill 体系最轻量的那个入口。先用它把「一键提示」这件事玩顺，需要更多本事了，平滑升级到 Skill 就行——官方文档明确说「你现有的文件继续工作」，.claude/commands/ 是被正式支持的写法，没有被废弃的意思。

💡 一句话总结：自定义斜杠命令已经合并进 Skill 体系——老式 .claude/commands/ 是最轻量入口（纯一段提示、手动喊），需要配套文件 / 自动触发 / 渐进式披露时就升级成 Skill；两者创建同名命令、用法完全一致。

08 动手：5 分钟刻一个带参数的 /explain 命令

光看不练记不住。下面带你从零刻一个真正能用、还能传参的斜杠命令——一个「用大白话解释代码 / 报错」的 /explain。全程不依赖任何复杂环境，一个空目录就能跑通。

第一步：建命令目录（Mac / Linux）

在你随便一个项目目录下（没有就 mkdir 一个空的进去），创建 .claude/commands/ 文件夹：

mkdir -p .claude/commands

Windows 用户：在项目根目录下手动新建 .claude\commands\ 这两层文件夹即可。

预期：项目下多了 .claude/commands/ 这个空目录。

第二步：写命令文件

用你顺手的编辑器，把下面内容存成 .claude/commands/explain.md：

---
description: 用大白话解释一段代码或一个报错。当用户想搞懂某段代码或某个报错时使用。
---

请用初学者能懂的大白话，解释下面这个东西：

$ARGUMENTS

要求：
1. 先一句话说它整体在干啥
2. 再逐行 / 逐段拆开说清楚
3. 如果是报错，指出最可能的原因和怎么改
4. 少堆术语，能用生活类比就用

注意两处：开头 --- 框起来的是 frontmatter，那句 description 让 Claude 知道这命令干啥；正文里那个 $ARGUMENTS，就是用来接住你待会儿传进去的代码 / 报错。

预期：.claude/commands/ 里有了一个 explain.md。

第三步：启动 Claude，确认命令已被识别

claude

进去后先打一个 /（光打斜杠，别回车），看弹出的菜单：

预期：菜单里能看到 /explain，旁边是你写的那句 description。看到它在菜单里 = 命令已被正确加载。 如果没看到，多半是文件没存对地方——确认它在 .claude/commands/explain.md，不是别的路径。

第四步：带参数喊它

现在真正用它——打命令名，后面跟上你想解释的东西（这串会被塞进 $ARGUMENTS）：

/explain print(sum([1,2,3]) / len([1,2,3]))

预期：Claude 收到的是你那段完整提示、其中 $ARGUMENTS 已被换成 print(sum([1,2,3]) / len([1,2,3]))。它会按你写的四步来——先一句话说整体（算这三个数的平均值）、再逐段拆、术语少、能类比就类比。你只打了命令名加一段代码，那整套「解释要求」自动生效了，这就是 $ARGUMENTS 的威力。

第五步：换个参数再来一次

同一个命令，换成解释报错：

/explain ZeroDivisionError: division by zero

预期：同样触发 /explain，但这次 $ARGUMENTS 变成了那条报错，Claude 会按第 3 条要求重点说「最可能的原因和怎么改」（除数为 0 了）。一个模板，参数随你换——这正是自定义命令比手打提示强的地方。

跑通这五步，你就把自定义斜杠命令最核心的三件事——「文件名即命令名」「frontmatter 加 description」「$ARGUMENTS 传参」——亲手验证了一遍。以后想刻任何命令，本质都是这套流程，无非换个文件名、换段提示、按需加 frontmatter 字段。

💡 一句话总结：刻命令就三步——.claude/commands/ 下放个 markdown（文件名即命令名）、加 description、用 $ARGUMENTS 留参数位；打 / 看它进菜单没，再带不同参数喊两次，亲手验证比记十条文档都实在。

09 小结

这一篇把斜杠命令从「你每天敲、但没摸透的入口」给你掀开看了——它是 Claude Code 的控制面板，从内置的几十个开关到你自己刻的一键流程，全在一个 / 后面。

把核心要点串起来回顾：

你现在应该能： 打一个 / 就看懂那张菜单、按「你在哪一步」找到该用的内置命令；把自己反复打的提示刻成一个 .claude/commands/ 下的命令，用 $ARGUMENTS 让它接参数、用 frontmatter 管它的行为；分得清命令同名时谁赢、插件命令为啥不撞；并且想明白了斜杠命令和 Skill 本就是一回事——前者是后者最轻量的入口，玩顺了随时能往上升级。

回头看开头那两周的「重启大法」——说到底就是没翻过那个 / 菜单。这一篇之后，但凡你想对 Claude Code 本身做点啥，第一反应该是先打个斜杠看看有没有现成的开关；没有，就花两分钟刻一个。这点习惯，能帮你省下那一大把白费的时间。

下一篇 37「检查点（Checkpoints）」——这一篇末尾那个 /rewind 我只一笔带过，下一篇专门拆它。Claude 改了一通代码，方向跑偏了怎么办？总不能每次都靠手动 git reset 或者干瞪眼。 下一篇教你用 Claude Code 内置的检查点机制，像打游戏存档读档一样，把代码和对话一起「倒带」回某个干净的状态。想想看：要是每改几步就自动有个「存档点」，你试错的胆子是不是能大不少？

37 · 检查点（Checkpoints）：随时能倒带的安全网

都说检查点是你的「后悔药」，有它兜底就能放开手脚让 Claude 大干一场——说句实话，把它当 git 用，迟早翻车。

设想一个刚上手 Claude Code 的人，听说有 /rewind 这玩意儿，整个人就松了，让 Claude 一口气改十几个文件，中间还跑了几条 rm 和 mv 清理目录。改到第三轮发现方向不对，淡定地 /rewind 想跳回去——结果代码是回去了一部分，但那几个被 rm 删掉的文件，一个都没回来。当场就懵了：「不是说能撤销吗？」

能撤销，但撤销的是 Claude 用编辑工具改的那些文件，不是它跑 bash 命令在你磁盘上留下的痕迹，更不是 git 那种永久历史。检查点是个「会话级的本地撤销」，强在快、强在自动、强在连对话都能一起退；但它有清清楚楚的边界，越界的事它管不了。

这一篇就干两件事：一是把检查点这套「自动存档 + 倒带」讲到你闭眼能操作；二是把它的边界钉死——哪些能回、哪些回不来、什么时候该靠它、什么时候必须上 git。搞清楚边界，它才是真安全网，不然就是个会骗你的安全网。

看完这一篇，你会拿到：

• 一句话讲明白检查点是什么、它什么时候自动帮你存（不用你手动操作）
• /rewind 和「空输入框双击 Esc」两种打开方式，以及回退菜单里那几个选项分别干嘛
• 一张「能回滚 vs 回不来」对照表——代码、对话能回，bash 副作用和外部状态回不来
• 检查点和 git 的明确分工：什么时候用哪个，为什么不能拿一个替另一个
• 一个能照着跑、给了预期输出的实战：亲手制造一次「改错」再倒带回去

01 检查点是什么：它在你每次发话前，偷偷拍了张快照

先给结论：检查点是 Claude Code 自动给你的代码拍的「编辑前快照」——你每发一条提示，它就拍一张；事后想退回哪张，一句 /rewind 跳回去。

第 07 篇你已经见过它一面，知道改错了能 /rewind 兜底。这一篇往深里走。先回想一下你跟 Claude 干活的节奏：你发一句指令 → 它「想 → 做 → 看」转一圈、改几个文件 → 你看结果再发下一句（这个循环第 03 篇讲过）。检查点干的事，就是在每一句指令落地之前，先把当时的代码状态拍下来留底。

类比：录像机（DVR）的时间轴回放。 你家那台能回放的机顶盒，节目是连续录下来的，但它在每个节目切换的地方都打了个「章节标记」。你想重看某一段，不用从头快进，直接拖到那个章节标记上一点就跳过去了。检查点就是这个味道：你发的每一条提示，都是时间轴上的一个章节标记；/rewind 就是把整盘带子拖回某个标记重来。 区别只在于——录像机回放是「看」，检查点回放是真把代码和对话退回到那一刻，让你能换个走法重录。

官方对它的定位是这样的：

当您与 Claude 合作时，checkpointing 会自动捕获每次编辑前代码的状态。这个安全网让您可以放心地执行雄心勃勃的大规模任务，因为您始终可以返回到之前的代码状态。

注意那个词——自动。这是检查点最爽的一点，也是它和 git 最大的体感差别：你什么都不用做。 git 是你得记着 git commit，忘了提交就没存上；检查点是 Claude 在背后默默拍，你压根不用操心「我存了没」。

官方列了四类最典型的用场，我每条配一个你真实会遇到的画面：

• 探索替代方案：A 实现做完不满意，退回起点重来 B 方案，起点完好无损，不用怕「试坏了回不去」。
• 从错误中恢复：它改完某个文件，测试反而挂了，你又懒得手动一行行抠回去——退回上一个检查点，干净。
• 迭代功能：让 Claude 把整个模块重写一遍练手，写完发现不如原来——跳回重写前，跟没发生过一样，敢放手试。
• 释放上下文空间：调试聊了一长串，前面的设置说明想留、中间的试错想丢——这就用上「总结」了（第 03 节讲）。

体会一下这四类的共同点：它们都是「我想大胆往前冲，又怕冲坏了回不来」——检查点就是来消掉这份「怕」的。

💡 一句话总结：检查点是 Claude 每次编辑前自动拍的代码快照，你每发一条提示就多一个「章节标记」，事后一句 /rewind 就能把代码和对话倒带回那一刻——全程自动，不用你手动存。

02 它到底什么时候存、存哪、留多久

检查点既然是「自动」的，那你得知道它自动的规律——什么时机拍、拍的东西放哪、能放多久。这三点官方写得很清楚，我一条条给你对。

触发时机：每条提示一个检查点

规律就一句话：你每发一条提示（prompt），Claude Code 就创建一个新检查点。 官方原话：

每个用户提示都会创建一个新的 checkpoint。

所以时间轴上的「章节标记」密度，是跟着你说话的节奏走的——你发十句指令，就有十个可以跳回去的点。这也解释了为什么后面回退菜单里列出来的，正是你这次会话发过的每一条提示：每条提示既是一次「动手的开始」，也是一个「可以退回去的存档点」。

把这个节奏画出来，你一眼就懂检查点是怎么沿着你的对话「一路落点」的：

这张图画的是：你每发一条提示，Claude 动手之前先落一个检查点（蓝色节点）；等改到提示 3 发现搞砸了，一句 /rewind 就能顺着那条虚线跳回检查点 1，把提示 2、3 的改动连同对话一起退掉——这正是它「随时能倒带」的本质。

存哪：藏在你的 ~/.claude 里

快照不是凭空记在内存里的，它落到了磁盘上。官方文档（claude-directory.md）里点了名：

file-history/<session>/ —— Claude 更改的文件的编辑前快照，用于 checkpoint 恢复。

也就是说，每个会话的「编辑前快照」都存在 ~/.claude/file-history/<session>/ 这个目录下。你不用去碰它，但知道它在哪有两个好处：一是明白检查点是真有实体文件撑着、不是玄学；二是哪天你好奇 Claude Code 在你机器上占了多少地方，知道这块归它管。

跨会话：关了重开，存档还在

既然落了磁盘，就有个很实用的特性——检查点跨会话不丢。官方原话：

Checkpoints 在会话之间持久存在，因此您可以在恢复的对话中访问它们。

什么意思？你今天干到一半 Ctrl+D 退出，明天用 claude --resume（或 --continue）把这个会话续上，之前那一串检查点还在，照样能 /rewind 倒带回昨天某个点。容易误以为 /rewind 只在当前这次开着的窗口里有效，关掉就清零——可实际上续一个三天前的会话，回退菜单里那些老提示居然还能跳，它是真存在盘上、跟着会话走的。所以「存档」这事，连「关机重开」这一关它都扛得住，只受那个 cleanupPeriodDays 期限管。

留多久：默认 30 天，可调

检查点不会永远留着，官方设了个自动清理：

在 30 天后自动清理（可配置）。

这个「可配置」具体是哪个开关？是 settings.json 里的 cleanupPeriodDays（第 31 篇专门讲过 settings.json 的用户级 / 项目级配置）。官方 settings.md 说它默认 30 天清理不活跃会话的记录、最少 1 天，设成 0 会被直接拒绝——这个值同时管着检查点快照的留存。对小白的建议：别动它。 默认值够用了，你真正需要长期保存的进度，本来就该交给 git（下面第 05 节细说），而不是指望检查点替你存半年。

哪天翻 ~/.claude 想清理空间，注意到 file-history 这个目录，才反应过来：原来每天那一堆 /rewind 的「后悔药」，都是这儿在默默兜着。 平时根本感知不到它存在，这恰恰是「自动」的好处。

把这三点拢成一张表：

💡 一句话总结：检查点每条提示存一个，落在 ~/.claude/file-history/ 里、跨会话不丢、默认按 cleanupPeriodDays 清理；这套规律你只需知道、不用操作——它全自动。

03 怎么倒带：/rewind、双击 Esc，和那张回退菜单

知道了它在背后默默存，现在学怎么把它调出来用。入口就两个，记死了：/rewind 命令，或者空输入框双击 Esc。

两个入口

第一个，在会话里敲斜杠命令：

/rewind

第二个，更快——在输入框为空时，连按两下 Esc：

（输入框空着，连按 Esc Esc）

这两个都会弹出同一个回退菜单（rewind menu）。官方原话：

运行 /rewind，或在提示输入为空时按两次 Esc，打开回溯菜单。

这里有个第 14 篇就埋过的坑，必须再敲一遍黑板：

如果提示输入包含文本，双 Esc 会清除它而不是打开菜单。清除的文本会保存到您的输入历史记录中，因此在您完成回溯菜单后，按 Up 可以调用它。

翻译成人话：输入框里有字的时候，双击 Esc 是「清空这段字」，不是打开菜单。 想倒带，先确保输入框是空的。新手很容易在这儿栽跟头——打了半句话想反悔，狂按 Esc，字没了菜单也没出来，一脸懵。记住：先清空，再 Esc Esc。 拿不准就老老实实敲 /rewind，它不挑输入框空不空。

回退菜单里在选什么

菜单弹出来，它列的是你这次会话发过的每一条提示——也就是时间轴上那一串「章节标记」。你先选一个「想退回到的点」，再选「怎么退」。这第二步是关键，因为退法不止一种。

官方给的几个操作，我逐个翻译：

中间那两个「只退一半」的选项，新手常犯嘀咕「为啥要分开退」。各举一个真实场景就通了：

• 只「恢复代码」：你跟 Claude 来回聊了五轮终于定下方案，它照着改了，结果代码跑挂了。你想退掉这堆烂代码，但那五轮讨论的来龙去脉不能丢（重新解释一遍太累）——这时选「恢复代码」，代码回到改之前，对话原封不动，让它带着原来的理解重写一遍。
• 只「恢复对话」：反过来，它改出来的代码你挺满意、想留着，可这轮对话被你问的几个无关问题带歪了，越聊越乱——选「恢复对话」，把对话退回到歪掉之前那个点，代码留在现状，你重新组织思路接着指挥。

看懂没——「恢复代码 / 恢复对话」是给你拆开来精修的两个旋钮，不是非得「代码和对话」一起退。这里面最常用的其实是「恢复代码」：方案没问题，就是 Claude 写歪了，退掉代码让它重写，比从头描述需求省事得多。

而这里最容易混的，是「恢复」和「总结」根本是两回事。 别被放在同一个菜单里就以为它们干类似的活：

• 恢复（restore） = 真的往回退状态：把代码、对话、或两者都退回选中的点。这是「时光倒流」。
• 总结（summarize） = 不动磁盘上的文件，只是把对话的某一侧压缩成 AI 生成的摘要、腾出上下文空间。这是「整理桌面」，不是倒带。

官方把这层区别说得很直白：

恢复选项恢复状态：它们撤销代码更改、对话历史或两者。总结选项将对话的一部分压缩为 AI 生成的摘要，而不改变磁盘上的文件。

看出来了吗——「总结」其实是第 19 篇那个 /compact 的精确版。/compact 是把整个对话压一遍，而这里的「从此处 / 到此处总结」，是让你挑一个点，只压它的一侧：跑偏的旁支用「从此处总结」砍掉，冗长的开场用「到此处总结」压扁。官方自己也是这么对照的：

这类似于 /compact，但更有针对性：您不是总结整个对话，而是选择所选消息的哪一侧进行压缩。

还有个贴心细节：选了「恢复对话」或「从此处总结」之后，被选中那条消息的原始提示会自动填回输入框，你可以改一改重新发——相当于「退回到说这句话之前，给你个重说的机会」。（选「到此处总结」则不一样：它把你留在对话末尾、输入框空着。）

两个新手常卡的小问题

「回退菜单弹出来是空的 / 没几个点可选」——正常。菜单列的是你这次会话发过的提示，你才刚开张、只发了一两句，自然没几个点可退。检查点是「边干边攒」的，发得越多、可退的点越多。

「我手滑选错了点，退过头了，能不能再退回来？」——先别慌。检查点本身是跨会话留在磁盘上的（第 02 节说过），并不会因为你 /rewind 一次就消失；菜单里那些点通常还在，你可以再开一次回退菜单，挑一个更靠后的点调整。不过具体每个版本的菜单行为可能有差异，最稳的还是那条老规矩：动手干高风险的活之前，先 git commit 一笔——git 那条「永久历史」永远是你退无可退时的最后一道防线（下一节细说）。

💡 一句话总结：倒带入口就俩——/rewind 或空输入框双击 Esc；菜单里先选「退回哪个点」再选「怎么退」，「恢复」是真退状态、「总结」只压上下文不动文件，这俩千万别混；退过头别慌，真兜底的是提前 git commit。

04 边界在哪：能回滚什么，什么死活回不来

这一节是全篇的命门，开头那个栽进去的跟头就栽在这儿。检查点不是万能撤销键，它只盯着一类东西——Claude 用「文件编辑工具」做的直接改动。 越过这条线的，它一概管不了。

类比还是那台录像机：它只录了「屏幕上的画面」，没录「你家客厅里真实发生的事」。 你倒带回去，画面是回去了，但你刚才在客厅打翻的那杯咖啡、寄出去的那封信、删掉的那个文件——现实世界里已经发生的事，倒带带不回来。 检查点拍的是「代码文件的快照」，它管得了文件内容的来回；管不了 Claude 跑命令在你系统里掀起的真实动静。

具体哪些回得来、哪些回不来，官方在「限制」一节列得很清楚，我整理成一张对照表——这张表你得记牢：

最该刻进脑子的是头两条「回不来」，官方专门拎出来强调。先看 bash 命令这条：

Checkpointing 不跟踪由 bash 命令修改的文件。例如，如果 Claude Code 运行 rm file.txt、mv old.txt new.txt、cp source.txt dest.txt……这些文件修改无法通过回溯撤销。只有通过 Claude 的文件编辑工具进行的直接文件编辑才会被跟踪。

这就是开头那个坑——Claude 是用 rm 删的文件，不是用编辑工具改的，所以 /rewind 救不回来。 划重点：「Claude 改文件」分两种——用它的编辑工具改（受跟踪、能回退），和用 bash 命令改（不受跟踪、回不来）。这俩在你眼里都是「它动了我的文件」，但在检查点眼里天差地别。

怎么当场分清它走的是哪种？看它在干活时打出来的工具调用名（第 14 篇讲过 Ctrl+O 能展开详细转录）：

• 看到 Edit、Write、MultiEdit 这类编辑工具在动——受检查点跟踪，改坏了 /rewind 能救。
• 看到 Bash 在跑 rm、mv、cp、>（重定向覆盖）这类命令——不受跟踪，改坏了 /rewind 救不回。

这俩在转录里写得清清楚楚。养成「让它干高风险活时瞄一眼工具名」的习惯，你就能在它真动手前判断：这步要是搞砸，我还有没有 /rewind 这张后悔药。判断为「没有」的，就老老实实先 git commit。

再看「外部更改」这条：

Checkpointing 仅跟踪在当前会话中编辑过的文件。您在 Claude Code 外部对文件所做的手动更改以及来自其他并发会话的编辑通常不会被捕获，除非它们碰巧修改了与当前会话相同的文件。

意思是：你自己拿别的编辑器改的、或者另开一个 Claude Code 会话改的，这个会话的检查点不认。

这里有条值得照办的土规矩：凡是让 Claude 干「删文件、移目录、改数据库、发请求」这类带不可逆副作用的活，绝不指望 /rewind 兜底——该 git commit 的先提交，该备份的先备份。 检查点只在「它用编辑工具改坏了代码」这种场景下，才是真靠得住的后悔药。

把「新手以为它能救」和「实际能不能救」摆一起，开头那个反共识就立住了：

中间那几行的「❌」，全是开头那类坑的变体——它们的共同点是「改动跑到了检查点的视野之外」：要么走的是 bash 而非编辑工具，要么发生在 Claude Code 之外，要么干脆是把变化推到了外部系统。只要一件事的后果落在了「磁盘上的代码文件」之外，检查点就够不着。 记死这一句，比记那张限制表更省脑子。

💡 一句话总结：检查点只管编辑工具改的文件 + 对话，这俩能回；bash 命令的副作用（rm/mv）、外部改动、已发出的请求一律回不来——一句话判断：后果落在「代码文件」之外的，它都够不着，别拿 /rewind 当保险。

05 和 git 的分工：本地撤销 vs 永久历史，谁也替不了谁

讲到这儿，开头那句「别把检查点当 git 用」就能彻底讲透了。很多人一上手就纠结「有了检查点，还要不要 git？」——答案是：要，而且它俩根本不抢饭碗。

官方把这层关系一句话钉死，值得你裱起来：

将 checkpoints 视为「本地撤销」，将 Git 视为「永久历史」。

类比：草稿本上的涂改 vs 交出去归档的正式文件。 检查点像你在草稿本上写写画画——写错一笔随手擦掉重写，快、随意、只对你自己有意义，本子用完（30 天后）也就扔了。git 像你把定稿打印出来、签字、归进档案柜——留痕、能给别人看、能追溯到任意一版、永久保存。你不会因为草稿本能擦就不归档正式文件，也不会因为要归档就连打草稿都拿正式文件来回改。两样都得有，各干各的。

官方给的分工清单：

• 继续使用版本控制（例如 Git）进行提交、分支和长期历史；
• Checkpoints 补充但不替代适当的版本控制。

把它俩并排放，区别一目了然：

注：git 同样管不了已发出的请求、数据库改动等外部副作用，只是能帮你恢复磁盘上已提交的文件。

什么时候用哪个，我给你一套土办法：

• 小步快跑、随时反悔 → 检查点。改一版不行 /rewind，再试一版，完全不用碰 git，丝滑。
• 干完一个像样的阶段、想长期存下来 → git commit。一个功能做通了、测试过了，提交一笔，这才是「永久存档」。
• 要让 bash 副作用也能回滚 → 只能靠 git。上一节说了检查点管不了 rm，但只要你提交得勤，git 能把整个工作区的状态找回来。

比较稳的节奏是这样：让 Claude 干活的过程中，靠检查点随时倒带试错；每完成一个能跑通的小阶段，立刻 git commit 钉一个永久存档点。 这俩配合起来，等于「细粒度的随手撤销」叠上「粗粒度的永久里程碑」，双保险。真正会咬人的教训是：太信检查点，一个下午没 commit 过，结果会话崩了重开，虽然代码文件还在，但那一长串「章节标记」全断了——想退回三小时前某个中间态，退不了了。所以更该养成「跑通就提交」的肌肉记忆。

关于 git 怎么跟 Claude Code 配合（让它帮你写 commit message、管分支），第 43 篇「Git 工作流」 有专篇，这里你只要先记住一条：检查点是本地撤销、git 是永久历史，前者补充后者、绝不替代。

最后补一个进阶岔路，官方提了一句：如果你想换个方法试试、又想原封不动保住当前会话，别用「总结」（它会改你当前会话的上下文），而是用 fork：

claude --continue --fork-session

它会基于当前会话叉出一条新分支去试，原会话完好。这招你先知道有，真到「想并行试两种思路」时再翻第 34 篇的「继续 / 恢复会话」。

💡 一句话总结：检查点 = 自动的本地撤销（细、快、纯本地、会过期），git = 手动的永久历史（可追溯、可协作、不丢）；小步试错靠检查点，里程碑和副作用回滚靠 git，跑通一个阶段就 commit。

06 动手：亲手制造一次「改错」，再倒带回去

光看不练记不住。下面这套最小流程，带你亲手走一遍「Claude 改文件 → 你反悔 → /rewind 倒带回去」的完整闭环。不依赖任何复杂项目，随便找个空文件夹就能跑。打开终端跟着走。

第一步：建个玩具文件夹，放一个一眼能看懂的文件

mkdir ~/rewind-demo && cd ~/rewind-demo
git init
printf 'hello\n' > note.txt
git add note.txt && git commit -m "init: 初始 note"

预期：note.txt 里就一行 hello，并且 git 提交了一笔（待会儿好对比检查点和 git 的区别）。

第二步：启动 Claude，让它改这个文件

claude

进去后发第一条指令（这条提示会触发第一个检查点）：

把 note.txt 的内容改成三行：apple、banana、cherry，用编辑工具改

预期：Claude 用编辑工具把 note.txt 改成三行水果（default 模式下它会先给 diff 等你批准，批准它）。特意强调「用编辑工具」，是为了让这次改动落进检查点的跟踪范围——这正是 /rewind 能救的那一类。

第三步：再发一条，把它改得更「面目全非」

再把这三行全删掉，换成一行：这是我不想要的版本

预期：note.txt 现在只剩「这是我不想要的版本」。到这儿你已经发了两条提示，时间轴上有两个章节标记了。

第四步：打开回退菜单，倒带

确保输入框是空的，然后连按两下 Esc（或者直接敲 /rewind）：

（输入框空着，Esc Esc）

预期：弹出回退菜单，列出你刚才发的那两条提示。选中第一条提示（改成三行水果那次）之前的点，再选「恢复代码和对话」。

第五步：验证倒带成功

回到终端（或用 ! 在会话里跑），看一眼文件：

! cat note.txt

预期：note.txt 变回了一行 hello——你两次改动全被退掉了，代码和对话都回到了改之前。看到 hello 回来 = 检查点倒带成功。 这就是「本地撤销」的威力：你没敲一个 git 命令，纯靠检查点就把两轮改动干净退回去了。

第六步（关键对照）：验证 bash 副作用回不来

现在故意让它用 bash 命令删文件，体会第 04 节那条边界。在会话里发：

用 bash 命令（rm）把 note.txt 删掉

它删完之后，再 /rewind 试图退回删除之前那个点，选「恢复代码」。然后看：

! ls

预期：note.txt 没回来，ls 里找不到它。这就印证了——bash 命令（rm）改的东西，检查点跟踪不到、/rewind 救不回。 想找回？这时候才轮到 git 上场：

git checkout note.txt

（这条会用 git 里那笔 init 提交把文件恢复出来。）预期：note.txt 带着 hello 回来了——git 这个「永久历史」，补上了检查点够不着的那块。

跑完这六步，你就把本篇最核心的两件事亲手验证过了：检查点能丝滑倒带编辑工具的改动（第五步），但管不了 bash 副作用——那得靠 git（第六步）。 这一正一反两个结果，比前面讲十遍边界都记得牢。

💡 一句话总结：这套实战让你亲眼看到——编辑工具改的，/rewind 一键退回；bash rm 删的，检查点束手无策、得靠 git checkout 找回。一正一反，边界就刻进去了。

07 小结

这一篇把 Claude Code 那张「自动安全网」彻底拆开了——检查点是它每次编辑前自动拍的代码快照，让你随时倒带，但它有清清楚楚的边界，跟 git 是搭档不是替身。

把核心要点串成一张表，揣兜里：

你现在应该能： 说清检查点是什么、它什么时候自动帮你存；用 /rewind 或双击 Esc 打开回退菜单，分得清「恢复」和「总结」的区别；心里有一条清晰的边界线——编辑工具改的能回，bash 副作用和外部状态回不来；并且知道它和 git 怎么分工、什么时候该提交。把这条边界刻牢，检查点才是真正能托底的安全网，而不是一个会在关键时刻骗你的「假后悔药」。

回到开头那句：检查点确实是后悔药，但它治的是「代码改坏了」，治不了「rm 删错了」——前者放心 /rewind，后者老老实实 git commit 在前头兜着。 分清这两味药，你就能比开头那位少摔一跤。

下一篇 38「插件参考手册」——你一路学下来的 Skill、Hook、Subagent、MCP，还有这一篇的种种命令，怎么打包成一个能装能卸、能分享给别人的「插件」？第 24 篇带你入了门，这一篇是把插件的完整结构和清单字段摊开当工具书查。想想看：如果你想把自己这套顺手的配置，做成一个朋友「装上即用」的包，它内部到底长什么样？