它到底是什么

--resume（别名 -r）用于恢复一个已保存的会话。官方定义是：按 ID 或名称恢复指定会话，或显示交互式 picker 让你选择。

它接受三种值，也可以不带参数：

会话是绑定到项目目录的已保存对话。Claude Code 在你工作时把它持续写入本地 transcript 文件，所以退出或执行 /clear 之后仍然可以恢复。

用法

# 打开 picker
claude --resume

# 按名称恢复(官方示例)
claude --resume auth-refactor

# 按 session ID 恢复
claude -r "session_id_here"

# 按 transcript 文件路径恢复
claude --resume /path/to/transcript.jsonl

# 恢复的同时 fork 出新会话
claude --resume auth-refactor --fork-session

# 非交互模式下向已有会话追问,并取出结构化结果
claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

会话名可以这样设置：

会话内也可以用 /resume 切换到另一个对话。/resume <name> 精确匹配时直接恢复，名称有歧义时报错，此时不带参数运行 /resume 打开 picker。

Picker 快捷键

每行显示会话名（若已设置，否则为 AI 生成的标题、摘要或首条 prompt）、距上次活动的时间、git 分支和文件大小。

与其他 flag 的组合 / 互斥

claude -p --resume 或 claude -p --continue，仅当会话结束时处于 plan mode，且同时满足以下四个条件，才会以 plan mode 恢复（官方文档要求 v2.1.246 或更高版本）：

• 传了 --permission-prompt-tool
• 没传 --permission-mode 或 --dangerously-skip-permissions
• 没传 --fork-session
• 不是通过 channels 启动

在 settings.json / env 的等价配置

官方文档列出的、影响"能不能恢复"的相关配置如下：

transcript 默认以 JSONL 存放在 ~/.claude/projects/<project>/<session-id>.jsonl。官方文档说明该条目格式是内部格式，随版本变化，脚本不宜直接解析。

运行约束 / 限制

恢复会话时会还原什么

会还原：

• 完整对话历史，包括 tool call 和结果
• 会话使用的 model
• 用 --agent 或 agent 设置启动时的 agent
• 未结束的 goal
• 未过期的 scheduled tasks

不会还原：

• Model：已下线、被 availableModels 禁止、启动时用 --model 或 ANTHROPIC_MODEL 系列环境变量指定了 model、或在使用 provider 专属部署 ID 的平台（Bedrock、Google Cloud Agent Platform、Microsoft Foundry）上时，model 不会被还原
• 崩溃时仍在运行的 tool：不会继续执行或重跑，Claude 在没有其输出的情况下继续
• 后台 Bash 和 monitor 任务
• --mcp-config、--settings、--plugin-dir、--fallback-model、--add-dir 传入的配置：恢复时需重新传入
• 会话中用 /add-dir 加入的目录：不会还原，但 picker 仍会用它们来定位会话

settings.json、settings.local.json 等标准 settings 文件每次启动都会重新读取，不需要重新传。

Permission mode 的恢复规则

经典使用场景

• 接着上次的工作：claude --resume 打开 picker，选择会话继续。
• 并行处理多个任务：用 claude -n <name> 或 /rename 给会话命名，之后 claude --resume <name> 直达。官方文档指出这在同时做多个任务时最有价值。
• 换目录 / 换项目恢复：claude --resume <session-id> 可以在任意目录运行；想在 picker 里跨范围找，用 Ctrl+W 或 Ctrl+A。
• 试另一条思路而不丢原路径：claude --resume <name> --fork-session，原会话保持不变。
• 脚本 / CI 里对已有会话追问：claude -p --resume <session-id> --output-format json "..."，读取 JSON 结果。
• 按 PR 找会话：claude --from-pr 123，或在 picker 搜索框粘贴 PR URL。

常见坑

• 同一会话在两个终端同时恢复且不 fork：两边的消息会交错写进同一份 transcript。要分叉请用 --fork-session。
• --fork-session 不继承"Allow for this session"的权限授予：官方文档说明，用 --fork-session 分叉到独立进程后，新进程没有这些授权，需要重新批准。会话内的 /branch 则会保留这些授权。
• 名称重复会被自动改名：交互式启动或恢复时，若本机另一个存活会话已用该名称，Claude Code 会把你的会话改成带两词后缀的变体（如 auth-refactor-graceful-unicorn）并提示。官方标注 v2.1.232 之前两个会话都保留原名。
• 名称有歧义时不是报错而是 picker:claude --resume <name> 遇到多个同名匹配会打开 picker 并预填搜索词，脚本里不要指望它直接恢复。
• 忘记重新传 --mcp-config / --add-dir 等：这些不会被还原。
• 恢复很久没动的大会话时会弹出选择框：官方文档说明，在 Pro 或 Max 计划上，恢复一个不活跃超过约一小时、且超过 100,000 tokens 的会话时，恢复后、发送第一条消息前会弹出对话框，提供 "Resume from summary"（立即 /compact）、"Resume full session as-is"、"Don't ask me again" 三个选项。此时 prompt cache 已过期，无论选哪项，下一次请求都要完整处理一遍历史。
• claude --continue 与后台会话：如果最近的对话仍在后台运行，Claude Code 会退出并提示 Your most recent conversation is running in the background 及其 session ID。可从 claude agents 附着，或用 claude --resume 选别的会话。恢复已结束的后台会话需要 v2.1.257 或更高版本。

来源

• CLI reference - Claude Code Docs（docs.claude.com/en/docs/claude-code/cli-reference 会 301 重定向到此）
• Manage sessions - Claude Code Docs