Claude Code 如何恢复会话并查找历史记录
了解 Claude Code 如何按名称或 ID 恢复会话、使用选择器切换对话,并找到运行代理的本机上保存的纯文本会话记录。
如何恢复 Claude Code 会话
要恢复 Claude Code 会话,请运行 claude --continue,打开当前目录中的最近一次会话;也可以运行 claude --resume,从列表中选择较早的会话。在已运行的会话中,使用 /resume 命令可切换到其他会话,无需退出。对应的简写形式是 -c 和 -r。
claude --continue
claude --resume
claude --resume auth-refactor如果已知会话名称或 ID,可将其作为参数传入。Claude Code 会直接打开该会话,不显示选择列表。
以下内容均与截至 2026 年 11 月的官方会话文档一致。Claude Code 发布频繁,标志名称和键盘快捷键可能因版本而变化。如果本文内容与终端显示不一致,应以 claude --help 和该页面为准。
会话的实际含义
会话是与项目目录关联的一段已保存对话。它包含完整的消息历史记录,包括 Claude 发起的工具调用及这些调用返回的结果。Claude Code 会在您工作期间持续将其写入磁盘,而不是等到最后一次性保存。因此,即使关闭终端或 SSH 连接中断,对话也不会丢失。
恢复会话不只是恢复文本。完整的对话历史记录会恢复,同时还会恢复该会话使用的模型,以及使用 --agent 启动会话时所使用的子代理。使用 --continue 或会话 ID 从 shell 恢复时,权限模式也会恢复。但出于安全考虑有一个例外:永远不会恢复绕过权限模式。因此,以该模式结束的会话恢复后,会使用新会话的默认模式。从选择器中选择会话,或使用 /resume 切换到会话时,也会恢复计划模式;这两种方式在其他情况下不会沿用已保存的模式。自 v2.1.290 起,从终端恢复会恢复计划模式;自 v2.1.292 起,选择器和 /resume 也会恢复该模式;在更早的版本中,恢复会话同样会丢失计划模式。从 shell 启动时,--permission-mode 会覆盖恢复后的模式。
有些内容不会恢复,因为它们是启动时标志,而不是已保存的状态。使用 --add-dir 添加的目录,以及 --mcp-config、--settings 和 --plugin-dir 等选项,都必须在恢复会话时再次传入。settings.json 等设置文件会在启动时重新读取,因此其中的设置无需再次指定。凭据也是如此:Claude Code 会在启动时根据您的登录信息和环境确定身份验证方式,而不是将其与对话一同恢复。因此,如果您在 VPS 上恢复会话,而 shell 中意外存在 ANTHROPIC_API_KEY,就会出现无效 API 密钥错误,即使上次运行完全正常。
为什么会话历史记录在 VPS 上更重要
有一个事实常常出乎人们的意料。会话记录写入运行代理的那台机器。它不会保存在您的账户中,也不会同步到云端。它只是该机器磁盘上的一个文件。
因此,您留在 VPS 的 tmux 窗口中的会话不会出现在笔记本电脑的选择器中,笔记本电脑上的会话也不会出现在 VPS 上。两者之间不会传输任何内容。如果您像大多数人一样在 VPS 的 tmux 中运行 Claude Code,服务器就是实际累积完整对话历史记录的地方,而您在本地看到的选择器显示的是另一组更小的会话。
不同界面之间也存在同样的分离。桌面应用和 VS Code 扩展各自保存会话历史记录,二者都不是 CLI 的历史记录,尽管桌面应用也可以恢复 CLI 会话。Claude Code 网页版也有自己的会话历史记录。Cowork 的位置更远:默认情况下,其会话运行在 Anthropic 的云端,并保存到您的 Claude 账户,而不是保存到您拥有的硬件上;只有现有的桌面部署会保留本地执行。因此,如果您正在权衡 Cowork 与 Claude Code,会话记录最终保存在哪里也是决策的一部分。
在同一台机器上,搜索范围比您预期的更广。claude --resume <session-id> 会先搜索当前项目目录及其 git worktree,然后搜索该机器上的其他所有项目。需要记住的是“在该机器上”。来自其他主机的会话 ID 不会解析到任何结果,Claude Code 会通过 No conversation found with session ID: <session-id> 告知您这一点。
Claude Code 将会话历史记录存储在哪里
默认情况下,Claude Code 会将会话记录存储在配置目录下,路径格式为 ~/.claude/projects/<project>/<session-id>.jsonl。
<project> 是您的工作目录路径,其中每个非字母数字字符都会替换为连字符。因此,在 /home/deploy/apps/api 中启动的会话会存储在名为 -home-deploy-apps-api 的目录下。如果转换后的名称超过 200 个字符,Claude Code 会截断该名称,并附加完整路径的哈希值,使目录名保持在文件系统限制以内。
该文件采用 JSONL 格式:每行包含一个 JSON 对象。每行可以表示一条消息、一次工具调用或其结果、Claude Code 发送给模型的请求记录,或者一条元数据记录。文件内容是可读文本,可以直接读取。
但不建议基于该文件编写解析器。条目格式属于 Claude Code 的内部实现,并且会随版本变化,因此直接读取这些文件的脚本可能在任何更新后失效。Anthropic 的官方文档建议改用 /export 或文档中说明的脚本接口,原因正是如此。
有两个设置会改变存储位置或保留期限。CLAUDE_CONFIG_DIR 会移动整个配置目录,因此可用于将会话记录存储到单独的卷或加密卷中。cleanupPeriodDays 位于 settings.json 中,用于控制会话记录的保留时间;默认值为 30 天,最小值为 1 天。
这些 transcript 文件中实际包含什么
每个工具结果都会被记录,因此 transcript 包含 Claude 读取的文件内容,以及 Claude 执行的命令输出。Anthropic 的数据使用页面明确说明:Claude Code 会以明文形式在本地将会话 transcript 存储在 ~/.claude/projects/ 下。由于 transcript 还会记录 Claude Code 发送给模型的内容,其中可能包含系统提示、工具定义、请求参数,以及已加载的 CLAUDE.md 文件。
请考虑这对服务器意味着什么。如果 Claude 读取了一个 .env 文件,以查明服务无法启动的原因,那么该文件的内容现在就位于您主目录中的一个 JSONL 文件里。如果某条命令输出了连接字符串,该字符串也会记录在其中。这并不表示发生了泄露。transcript 记录了实际发生的情况,这正是它存在的目的,也正因如此,您必须将其纳入威胁模型。
- 备份:直接备份
/home或/root时,transcript 也会被复制到备份存储位置。请添加排除项,否则您的提示和文件内容副本也会存在于备份存储中。 - 快照和镜像:无论出于何种原因创建的 VPS 快照都会包含整个目录。从该快照克隆镜像以构建第二台服务器时,镜像中也会包含这些内容。
- 服务器上的其他账户:请使用
ls -ld ~/.claude ~/.claude/projects自行检查权限模式,不要假设权限已经严格限制。 - 主动上传:
/feedback命令会主动将会话历史发送给 Anthropic,/bug和/share也会通过相同路径报告。反馈对话框还可能包含同一项目在最近 24 小时或 7 天内的其他会话,而不只是当前会话。这些都是您主动选择的操作,因此确认前请先了解您同意的内容。
如果您不希望生成 transcript,CLAUDE_CODE_SKIP_PROMPT_HISTORY 会禁止写入 transcript,--no-session-persistence 则会在单次非交互式 claude -p 运行中禁止写入。设置任一选项前,请明确了解其中的取舍。resume 读取的就是 transcript,因此没有 transcript 就无法 resume。
如何查找旧对话
使用 claude --resume 打开选择器,或在运行中的会话内使用 /resume。每一行会显示会话名称(如果已设置),否则显示系统生成的标题,还会显示距上次活动的时间、git 分支和文件大小。
选择器支持搜索。按 /,或直接开始输入,以筛选列表。值得掌握的快捷键是用于扩大范围的快捷键:Ctrl+A 显示此计算机上所有项目的会话,Ctrl+W 显示当前仓库的所有 worktree,Ctrl+B 将范围限制为当前 git 分支。按 Space 可在确认恢复前预览会话内容,按 Ctrl+R 可重命名高亮显示的会话。
为会话命名会让查找更简单。使用 claude -n auth-refactor 启动会话,或者在进行到一半、意识到对话已经变成一项实际工作时运行 /rename auth-refactor。之后,可以直接从 shell 按名称恢复已命名的会话。
未命名的会话仍会获得系统生成的标题。后台请求会调用一个小型快速模型,根据你的第一条提示生成摘要。该标题有助于你在选择器中识别会话,也可以作为恢复句柄:claude --resume 会以与自定义名称相同的方式解析它。但未命名交互式会话在运行中会话列表中使用的默认显示名称(例如 my-app-3f)无法用于此目的。将该名称传递给 claude --resume 时,Claude Code 找不到对应会话。
搜索会话记录以找到目标会话
有时您只记得一句话,其他信息都不记得。会话记录是文本文件,因此可以搜索。
grep -rl "nftables" ~/.claude/projects/该命令会输出匹配会话记录的路径。去掉 .jsonl 扩展名后的文件名就是会话 ID,claude --resume <session-id> 接受该 ID。claude --resume 也可以直接接受会话记录的绝对路径。使用 grep 确定要查找的会话,然后恢复该会话,或将其导出后查看实际内容。
需要注意两点。内容经过 JSON 转义,因此包含引号的短语,或跨越换行符的短语,可能无法作为字面字符串匹配。此外,如果匹配内容位于工具结果中,这表示 Claude 看到了该文本,并不表示有人输入过该文本。
读取并导出会话
/export 将当前会话渲染为纯文本,以可读形式写出消息和工具输出,而不是 JSON。未提供参数时,它会打开菜单,让您选择剪贴板或文件。提供文件名后,/export handover.txt 会直接写入该路径。这是将会话从服务器传到笔记本电脑,或将会话附加到工单的正确方式。
对于自动化任务,请使用设计为稳定接口的功能。钩子和状态栏命令会接收一个 transcript_path 字段作为输入,因此 SessionEnd 钩子可以在会话结束时归档记录。您也可以在不打开已保存会话的情况下向其提问:
claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'该命令会向旧会话发送后续提示,并返回结构化 JSON。这比解析可能在下一版本中变更的 JSONL 格式可靠得多。
何时重新开始胜过继续原对话
继续原对话会恢复完整历史,而后续每个请求都会携带这段完整历史。昨天运行了四个小时的对话,今天继续使用的成本很高;长会话中的令牌用量如何累积解释了这些成本的实际来源。
Claude Code 有时会为您采取折中方案。如果您在交互式终端会话中让一个较长的对话保持空闲,并且该会话使用一小时提示缓存,而 Claude 订阅会在您套餐的用量范围内默认将主对话放入该缓存,那么空闲压缩会在大约 54 分钟后执行,时间略早于缓存过期。只有在对话上下文达到令牌阈值后才会执行;该阈值默认为 200,000。同时必须启用自动压缩,并且此时机器处于唤醒状态。在 v2.1.314 之前,Claude Code 还需要从 Anthropic 获取功能标志,因此关闭遥测的订阅用户无法使用此功能;从 v2.1.314 开始,这些用户也可以使用该功能,并且 VS Code 扩展的聊天面板和桌面应用的 Code 选项卡也支持该功能。系统不会先询问您。您返回时,对话中会显示一行以 Compacted while idle, before the prompt cache expired 开头的内容,下一条消息会发送摘要,而不是完整历史。
- 保持启用状态可以降低后续请求的成本,但摘要中被省略的内容将不再可用。您可以使用
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS降低阈值,但低于 100,000 的值会提升到 100,000。 - 在
settings.json中将idleCompaction设置为false可以关闭此功能;在 v2.1.302 或更高版本中,也可以在/config的 Idle compaction 行中关闭。这样对话会保持完整,但每个请求的成本会随对话大小增加。如果您发送下一条消息时缓存已经过期,该请求会重新处理一次完整历史。
对于 Pro 和 Max 套餐,v2.1.304 增加了另一项检查;当前文档也列出了 Ultra 套餐。当您在长时间中断后恢复较长对话,或切换到其他模型,并且此操作预计会占用 5 小时用量上限中较为明显的比例时,Resume this conversation? 对话框会显示估算占比,并允许您继续恢复或开始新对话。如果新对话选项对此作出提示,您提到之前的对话时,Claude 可以查找该对话。
判断其实很简单。如果您接下来要输入的内容依赖之前已经说过的内容,就继续原对话。否则就重新开始。只要留意相关迹象,就很容易发现上下文已经偏离:例如 Claude 提到您一小时前删除的文件,或重新争论您在会话开头已经确定的决定。这就是过时的上下文。继续携带它会同时增加令牌消耗并降低准确性。
如果旧对话中有一个决定或事实将来还会用到,不要依赖继续原对话来保留它。应将其写入每个会话都能访问的位置,这正是Claude Code 的记忆文件的用途。
这里还应了解 /branch。它会复制当前时间点之前的对话,并将您切换到副本,同时保留原对话,使其仍显示在选择器中。您可以用它尝试第二种方法,而不会丢失第一种方法。
resume 与压缩及记忆的区别
这几个概念经常混淆,但它们解决的是不同的问题。
resume 用于在退出、重启或转去处理其他任务后,恢复整个对话。压缩处理的是实时对话中的上下文窗口:/compact 会用摘要替换 Claude 当前保留的内容,使后续请求发送更少的 token。如果问题是上下文窗口已满,应使用压缩工具,管理 Claude Code 上下文窗口对此有完整说明。
记忆又有所不同。CLAUDE.md 文件和自动记忆会在每个会话开始时加载指令和事实,因此它们不是供您返回的对话。它们是您记录下来的内容,这样以后就不必再返回原对话。
如果您希望同时运行两个对话并让它们相互协调,那是另一种机制。Claude Code 会话可以相互发送消息,前提是两个会话都处于运行状态。这与从磁盘恢复昨天的会话是不同的问题。
FAQ
Claude Code 将会话历史存储在哪里?
默认存储在配置目录下的 ~/.claude/projects/<project>/<session-id>.jsonl 中,其中 <project> 是将非字母数字字符替换为连字符后的工作目录路径。每个文件采用 JSONL 格式:每行包含一个 JSON 对象,可以表示一条消息、一次工具调用或其结果、发送给模型的请求记录,或一条元数据。CLAUDE_CONFIG_DIR 可将配置目录移动到其他位置;在 settings.json 中设置 cleanupPeriodDays 可控制会话记录的保留时间,默认值为 30 天,最短为 1 天。
为什么我在笔记本电脑的选择器中看不到 VPS 会话?
因为会话记录写入代理运行所在计算机的磁盘,不会在计算机之间同步。您在 VPS 的 tmux 中进行的对话只存在于 VPS 上。您可以通过 SSH 在 VPS 上恢复该会话;如果需要本地副本,也可以在会话中运行 /export,然后将文本文件复制到本地。
我可以恢复在其他目录中启动的会话吗?
可以,但您需要知道该会话 ID。claude --resume <session-id> 会先在当前项目目录及其 Git 工作树中查找,然后在同一台计算机上的其他项目中查找。在选择器中,Ctrl+A 会将列表扩展到计算机上的所有项目,Ctrl+W 会将列表扩展到当前仓库的所有工作树。如果没有匹配项,Claude Code 会报告 No conversation found with session ID: <session-id>。
我应该恢复旧会话,还是启动新会话?
如果下一条消息依赖该对话中已经讨论的内容,请恢复旧会话。如果不依赖,请启动新会话,因为恢复会重新加载完整历史,之后的每个请求都会继续携带这些内容。请注意上下文漂移:如果会话持续引用您已经删除的文件,说明其中包含过时上下文;这些上下文会在每轮对话中消耗令牌并降低准确性。
我可以阻止 Claude Code 将会话记录写入磁盘吗?
可以。CLAUDE_CODE_SKIP_PROMPT_HISTORY 会禁止写入会话记录;对于单次非交互式 claude -p 运行,--no-session-persistence 会禁止写入会话记录。请先了解这一取舍,因为 resume 依赖会话记录进行恢复;禁用写入后,--continue 和 --resume 将没有可加载的内容。如果您只是担心文件的存储位置,而不是希望完全禁用文件生成,可以将 CLAUDE_CONFIG_DIR 指向加密卷,并改为缩短 cleanupPeriodDays。