你是不是也遇到过这种场景让 Claude Code 在一个改造中的老项目里连续跑一两个小时刚把关联模块捋清楚、改到一半结果终端窗口被误关或者网络闪断又或者上游接口直接给你抛了个 529。重新打开终端你发现自己面对的是一个空白会话——之前喂给它的一堆背景、约束、中间决策全都得重新说一遍。这次 Claude Code 桌面端把/resume恢复会话做成了可视化入口表面上只是多了一个按钮但它背后的变化值得认真聊几句。因为在 Agent 编程里真正贵的不是模型调用而是上下文。一次长任务会话里的背景信息、踩坑过程和阶段性结论就是 Agent 的“工作记忆”。把这个记忆丢掉等于让一个已经干到一半的人失忆然后从头再教一遍。本文会从resume的功能原理、桌面端与 CLI 的形态差异、具体恢复流程、完整示例和排错清单几个角度展开。无论你是刚开始接触 Claude Code 的新手还是已经在团队里重度使用 Agent 编程的开发者这篇文章都会帮你把“会话中断”这件事的成本降下来。1. 这篇文章真正要解决的问题先说结论Claude Code 桌面端新增的/resume恢复会话解决的是 Agent 编程里“长任务中断后上下文丢失”的核心痛点。在传统 IDE 里代码写到一半关闭窗口重新打开后文件还在因为代码保存在磁盘上。但在 Claude Code 这类终端 Agent 工具里状态由两部分组成一部分是磁盘上的文件改动另一部分是会话里累积的对话上下文。文件改动还好说会话上下文一旦丢失Agent 就不记得你之前提过什么约束、做过什么决策、踩过哪些坑。没有/resume的时候开发者通常这么做把最初的需求重新复制一遍逐字粘贴到新会话里手动补齐项目背景、技术栈、目录结构等信息遇到之前已经纠正过的问题还要再次纠正一遍如果任务特别长中途可能还要维护一份“进度笔记”记录改到哪一步了。这些做法不是不能用但它们本质上是在为人脑记忆 Agent 状态既低效又容易遗漏。而resume出现后整个流程变成终端关闭 - 重新打开 claude - 执行/resume- 选择之前的会话 - 无缝继续。这里还要区分一个概念早期 Claude Code CLI 里就已经有--resume参数本次桌面端把它图形化意味着“会话恢复”从一个只有命令行用户熟悉的参数变成了普通用户也能一眼看懂的功能入口。这种变化才是值得关注的地方。什么样的人最应该读这篇文章用 Claude Code 做多文件改造、跨模块重构的重度用户想让 Agent 完成持续数小时的编码任务、但总是被中断问题困扰的开发者刚接触 Claude Code 桌面端、还不清楚 CLI、桌面端和 VSCode 插件有什么区别的新手在团队里尝试把 Agent 会话作为“可交接资产”来管理的工程负责人。2./resume是什么先分清命令、会话和客户端形态要把/resume讲清楚先得理解 Claude Code 里的“会话session”是什么。当你进入某个项目目录并启动claude时工具会创建一个会话。这个会话会记录你输入的所有指令、Agent 的思考过程、执行过的命令、修改过的文件以及最后的结果。对话越多上下文越长Agent 对该任务的“理解”也越深。/resume的核心作用就是把这个历史会话重新加载回上下文窗口让 Agent 接着上次的状态继续工作而不是重新开一个空白的对话。2.1 CLI 中的/resume在终端里使用 Claude Code 时最朴素的使用方式是在对话中输入斜杠命令/resume输入后终端会列出当前项目下所有历史会话并提示你选择要恢复哪一个。选中之后这个会话的全部上下文就会被加载回来。如果不想交互式选择也可以在启动 claude 时直接指定要恢复的会话# 恢复最近一次会话 claude --continue # 恢复指定的 session id claude --resume session-id--continue和--resume的区别在于前者直接延续最近一次会话后者需要指定具体的会话 ID。这两种方式适合不同的场景稍后会展开讲。2.2 桌面端新增的“恢复会话”入口这次桌面端的新变化是把上面这些命令变成了图形化操作。打开桌面端后在会话历史区域可以直接看到之前的项目会话列表点击某一条就能恢复当时的对话状态。它的意义不只是“少敲几个字”而是把“会话”从一个终端内部的临时状态变成了开发者可以浏览、选择、管理的一项资产。就像 IDE 里的“最近打开的文件”一样会话历史变成了“最近打开的上下文”。2.3 几种客户端形态的横向对比Claude Code 现在常见的使用形态有三种终端 CLI、桌面端、VSCode 插件。它们的恢复会话方式不太一样我用一个表格来说明使用形态恢复会话方式适合场景注意点终端 CLI对话中输入/resume或启动时用--resume/--continueSSH 远程开发、习惯终端的开发者需要记忆命令参数但最灵活桌面端会话历史列表点击恢复日常图形化操作、想快速浏览历史会话恢复入口直观适合新手VSCode 插件插件面板/命令面板触发展开历史会话前端、全栈开发边写代码边用 Agent与编辑器集成度更高上下文能关联工作区这里想强调一个判断终端 CLI 的/resume解决的是“命令路径”问题桌面端的恢复会话解决的是“可发现性”问题。Windows 用户和 VSCode 用户未必会记得claude --resume这样的参数但一定会在 UI 上找到“历史会话”按钮。新增这个入口本质上是在降低 Agent 编程的使用门槛。类似的恢复会话机制在 opencode 等开源终端 AI 工具里也能看到。这说明“会话可恢复”正在成为 Agent 编程工具的基础能力而不是某个工具的差异化卖点。真正拉开差距的是谁能把会话管理做得更自然、更好用。3. 为什么恢复会话比想象中重要上下文是 Agent 编程的核心成本很多第一次用 Claude Code 的人会有一个错觉Agent 编程就是把需求告诉模型然后等它写完代码。但实际用过几次就会发现真正的难点是让模型在几十个文件、几千行代码的上下文里保持一致性。3.1 长任务中的上下文价值假设你让 Claude Code 在一个 Spring Boot 项目里完成“新增用户积分流水接口 调整订单实体的级联关系 补齐对应单元测试”。这个任务不是写一个孤立函数而是涉及理解现有项目分层Controller、Service、Mapper、Entity搞清楚订单实体和用户表之间的外键关系遵循项目已有的异常处理风格测试代码要和现有测试基础设施对齐。这些信息里只有一小部分能从代码本身读出来更多是依赖 Agent 在会话过程中通过反复读文件、问问题、看报错来逐步建立的“心理模型”。一旦会话中断这个模型就没了。重新开一个会话Agent 往往要从零开始探索甚至可能因为上下文不足而选择一条和之前不一致的实现路径。3.2 丢失上下文的真实成本从工程角度看丢失上下文的成本可以拆成三部分重复探索成本Agent 重新扫描目录、重新读文件、重新理解业务逻辑这些都要消耗时间和 token。决策不一致成本前一个会话里已经修正过的技术方案新会话可能又绕回去导致代码风格和实现路径不统一。人的沟通成本你需要再次向 Agent 解释背景这种“人反复喂上下文”本质上是在浪费开发者的时间。所以/resume不只是一个便捷功能它是对上面这些成本的一次系统性削减。3.3 从“工具记忆”到“团队资产”再往深一层想可恢复的会话还有一个容易被忽略的价值交接。传统开发中一个任务做了一半要交给另一个同事你需要写文档、口头说明、拉会议。而如果 Agent 会话可以被持久化、被恢复那么一个进行到一半的复杂任务就变成了可复现的工作记录——包括之前的约束、已做的改动、尚未处理的问题。团队里完全可以约定把“Agent 会话摘要”作为交接材料的一部分。谁中途接手谁就通过/resume打开同一个会话接着往下跑。这种工作方式正在把上下文从个人记忆变成团队资产。4. 环境准备Claude Code 桌面端与 CLI 的安装路径要体验/resume先得把 Claude Code 跑起来。下面按使用形态给出安装和配置路径。版本细节以官方文档和实际发布为准这里重点演示通用思路。4.1 安装终端 CLI终端 CLI 是最基础的使用形态其他形态很多也依赖 CLI 的安装。前提是机器上已经配置好 Node.js 环境建议使用较新的稳定版本并确保npm可用。npm install -g anthropic-ai/claude-code安装完成后验证版本claude --version如果输出版本号说明安装成功。此时在任意项目目录下输入claude就会启动一个新的交互式会话。4.2 安装桌面端桌面端可以从官方渠道下载对应操作系统的安装包。Windows、macOS、Linux 分别有不同的安装方式。安装完成后使用 Claude 账号登录即可进入图形化界面。桌面端和 CLI 共用同一套配置目录因此你在 CLI 里用过的历史会话桌面端理论上也能看到。这个设计很重要因为很多开发者是多种形态混用的。4.3 安装 VSCode 插件如果你主要在 VSCode 里工作可以安装 Claude Code 的 VSCode 插件。安装后通常会在编辑器侧边栏或命令面板里出现入口。插件的优势是能预览当前文件改动、在编辑器里直接看到 Agent 的修改使用体验比纯终端更直观。4.4 登录与认证配置使用官方服务时通常需要登录 Claude 账号完成认证。在团队或自动化场景中也可以使用 API Key 方式。这里强调一条安全原则不要把 API Key 写死在项目代码或会话消息里建议通过环境变量注入。export ANTHROPIC_API_KEYyour-api-key如果所在网络环境需要走代理或自定义网关可以通过环境变量ANTHROPIC_BASE_URL指定地址。同样的道理如果接入的是兼容 Anthropic 协议的第三方模型网关也需要在这里配置。4.5 settings.json 与模型配置Claude Code 的全局配置位于~/.claude/settings.json。一个典型的配置如下{ env: { ANTHROPIC_BASE_URL: http://your-gateway:8080, ANTHROPIC_AUTH_TOKEN: your-token, ANTHROPIC_MODEL: your-model-name } }这里要特别提醒一个常见坑如果ANTHROPIC_MODEL配置了当前 Claude Code 版本不认识的模型名启动时就会报类似xxx is not a model this version of claude code recognizes的错误。很多第三方模型包括本地部署模型会通过兼容层接入 Claude Code但不同版本的 Claude Code 能识别的模型名清单可能不一样。遇到这种报错时不要盲目改配置先去确认当前版本支持哪些模型名再对齐网关侧的模型 ID。如果你希望 Agent 默认用中文回答可以在CLAUDE.md或项目级配置里加上一句约定也可以直接在会话开头提。后面会给出示例。5. 核心流程拆解用/resume恢复一次会话下面的流程假设你已经在项目目录里用 CLI 创建过会话然后因为某种原因中断了。我们一步步拆解。5.1 创建一个正常会话在项目目录下启动cd /path/to/your-project claude启动后给 Agent 一个明确的任务。比如请先阅读项目的 README 和整体目录结构然后帮我梳理出订单模块的核心流程。这个阶段Agent 会扫描文件、读取上下文、逐步建立对项目的理解。如果你希望任务进行到一半时可以恢复最好在会话开头就做一件事把目标和约束讲清楚。这样即使中断恢复Agent 也能从会话历史里重新读到这些信息。5.2 会话被中断中断的方式有很多种终端窗口被关闭电脑休眠导致 SSH 连接断开网络波动造成进程退出上游接口返回 529 之类限流错误进程被强制退出。无论哪种方式只要会话没有被正常保存为“已完成”它都会留在历史会话列表里。Claude Code 会把会话内容写到~/.claude/projects/目录下以项目名和会话 ID 组织文件。5.3 执行/resume恢复重新打开终端进入同一个项目目录启动 claudecd /path/to/your-project claude在交互提示符里输入/resume此时终端会列出该项目下的历史会话效果类似? Select a conversation to resume: (1) 2025-03-01 14:22: 梳理订单模块核心流程 (2) 2025-03-01 10:05: 修复登录接口 NPE 问题 (3) 2025-02-28 18:33: 新增用户积分流水接口选择你想继续的那一条按回车会话就会恢复。之后你可以继续输入新指令Agent 会基于之前的完整上下文继续工作。5.4 使用启动参数直接恢复如果你知道要恢复的会话 ID可以直接用参数方式# 恢复最近的会话 claude --continue # 恢复指定会话 claude --resume session-id桌面端的操作则更直观打开应用在历史会话列表里找到目标会话点击“恢复”或“继续”就会加载该会话的所有上下文。5.5 会话文件在磁盘上的位置Claude Code 会把会话文件以 JSONL 格式保存下来路径通常是~/.claude/projects/项目目录名/session-id.jsonl这个文件里逐行记录了用户消息、助手回复、工具调用等结构化数据。它有两个作用理解你的会话历史到底存了什么必要时可以手动备份、迁移或清理。不过直接编辑 JSONL 文件属于风险操作建议不要在生产项目里做。需要清理时优先用工具内的删除会话功能或者明确确认后再手动删除。6. 完整示例一个长任务中断后恢复的真实场景下面用一个贴近实际的例子把整个流程串起来。6.1 场景描述你正在开发一个 Spring Boot 应用任务是为用户模块新增一个“积分明细查询”接口同时修改订单实体的级联关系最后补齐单元测试。这个任务涉及多个文件预计需要较长时间。6.2 第一步开启会话在项目目录下启动 Claude Codecd demo-order-system claude第一条指令这是一个 Spring Boot 项目。请先阅读 pom.xml 和 src 目录结构理解当前项目分层然后开始完成以下任务 1. 新增用户积分明细查询接口路径为 /api/user/{userId}/points/details 2. 修改 Order 实体与 User 实体之间的级联关系确保删除用户时会校验是否存在关联订单 3. 为以上两个改动补充对应的单元测试。 请在动手前先梳理你的实现计划并确认对现有代码的影响范围。这条指令里包含了任务目标、约束和行动顺序等会话恢复时Agent 能重新读到这份完整任务描述不至于忘记最初要求。6.3 第二步Agent 执行并中断Agent 开始读代码逐步实现PointsDetailController、Order实体修改等内容。中途你的终端突然被关闭。此时会话还没有结束它被保留在历史记录里。6.4 第三步恢复会话重新打开终端cd demo-order-system claude输入/resume从列表中选择之前那次“新增用户积分明细查询接口”的会话。恢复后Agent 会重新载入之前的对话内容。你可以先确认一下它现在的状态请总结一下你目前已经完成的改动以及还剩下哪些工作。如果它输出的总结和你的记忆基本一致说明上下文恢复成功。此时可以继续下达新指令继续完成剩下的单元测试注意 mock 掉外部服务调用。Agent 会基于之前已经改完的代码继续工作而不是重新从零开始读项目。6.5 第四步验证恢复效果判断resume是否成功可以从三个信号来看Agent 能准确说出之前改过的文件和关键方法名不需要你重新解释项目背景和分层结构新改动与之前改动的代码风格一致。如果三个信号都符合说明这次恢复是完整有效的。6.6 一个完整的恢复命令示例cd demo-order-system # 方式一交互式选择 claude /resume # 方式二直接恢复最近一次会话 claude --continue # 方式三通过会话 ID 恢复 claude --resume 1f2e3d4c-5b6a-7c8d-9e0f-123456abcdef实际使用中方式一最常用因为它有交互式选择不需要记 ID方式二适合单人单任务的快速恢复方式三适合你明确知道要恢复哪个会话、并且写了脚本来自动化执行的场景。7. 常见问题与排查思路用了/resume之后可能会遇到一些坑。下面按现象、原因、排查方式和解决方案整理成表格问题现象可能原因排查方式解决方案启动时报xxx is not a model this version of claude code recognizes配置的模型名不被当前版本识别检查settings.json里的ANTHROPIC_MODEL确认当前版本支持的模型清单改为当前版本支持的模型名或升级/降级 Claude Code 版本/resume会话列表为空当前目录不是之前创建会话时的项目目录或会话文件被清理检查~/.claude/projects/下是否还有对应的项目目录回到原项目目录再执行/resume若文件已删除则无法恢复恢复后 Agent 不记得之前的事选择了错误的会话或会话文件损坏对比会话开始时间和任务描述查看 JSONL 文件内容是否完整重新选择正确的会话若不可恢复回到最近一次 git 提交重新开始频繁出现 529 错误上游服务限流或负载过高查看错误响应中的 Retry-After 或等待时间提示降低请求频率稍后重试或检查是否到达账号额度上限桌面端历史会话按钮置灰尚未登录或没有在本地创建过会话检查账号登录状态以及在 CLI 里是否已有历史会话先完成登录认证再创建一次会话输出中文乱码终端编码不是 UTF-8或 Windows 终端的代码页问题检查终端编码设置确认chcp输出在 Windows 终端执行chcp 65001切换到 UTF-8或调整终端字体希望 Agent 默认用中文回答但总是英文没有在配置或提示词中约定语言检查CLAUDE.md或会话开头是否有语言要求在CLAUDE.md中加入“请始终使用中文回答”或首条消息明确说明7.1 关于 529 的补充说明529 是 Claude Code 使用中比较常见的限流提示出现在上游负载较高或账号请求频率过快的时候。它并不是你本地配置错了而是服务端在保护资源。遇到 529最有效的办法是等待一段时间再重试或者降低并发任务数量。如果是在自动化脚本里遇到建议做好退避重试逻辑。7.2 关于模型名不识别的问题这类问题在接入第三方模型时特别常见。本质上Claude Code 会维护一个它认识的模型名清单如果你配置的模型 ID 不在清单里就会拒绝启动。解决办法是先查当前版本支持哪些模型名再看你的网关或服务商提供的模型 ID 是否与之一致。有些情况下网关会暴露一个新的模型名你需要让网关把请求映射到 Claude Code 认识的模型上。8. 最佳实践与工程建议会用/resume只是第一步把它用出效果还需要配合一些工程习惯。8.1 会话开始就写清楚任务摘要会话恢复依赖的是历史对话。如果你的第一句话是“帮我看看这个项目”那恢复后的上下文价值就很有限。更推荐的做法是在第一句话里把目标、约束、范围和验收标准都写清楚。这样即使中断恢复Agent 也能从会话历史里读到完整任务定义。任务为订单模块新增导出功能。 约束使用项目已有的 EasyExcel 依赖不要新引入额外库。 范围只改 OrderController 和 OrderService不涉及前端。 验收POST /api/order/export 返回文件下载流。8.2 配合 git 分支使用长任务开始前先创建一个独立分支git checkout -b feat/agent/points-details这样 Agent 在会话里如何折腾都不会污染主分支。即使会话恢复失败你也能从最近一次 commit 快速回到某个稳定状态。8.3 阶段化 checkpoint如果任务特别长可以每隔一段时间让 Agent 输出一次变更摘要请把当前已完成的工作整理成一份变更摘要包括修改的文件、核心逻辑和尚未完成的部分。这份摘要会进入会话上下文。一旦会话丢失或恢复出错你至少能从最近的摘要里知道进行到哪一步重新创建会话的成本也会低很多。8.4 不同项目、不同任务分开会话不要把所有任务堆在同一个会话里。项目 A 的积分查询和项目 B 的订单导出应该用两个独立会话。否则resume时会看到一个又长又杂的上下文不仅恢复慢还容易让 Agent 混淆目标。8.5 会话文件的备份与清理~/.claude/projects/目录会随着使用越来越大。重要项目的会话文件可以纳入备份策略但普通探索性会话建议定期清理。清理前先确认没有正在进行中的任务。8.6 注意安全和密钥不要在会话里输入 API Key、数据库密码、云账号凭证等敏感信息。一方面这些内容会被写入会话文件另一方面Agent 可能在后续代码里错误地引用它们。需要密钥时通过环境变量注入并提醒 Agent 读取环境变量而不是对话内容。8.7 桌面端、CLI、VSCode 插件的选择建议如果你是新手建议从桌面端入手用图形化的历史会话入口理解/resume的恢复逻辑如果你习惯终端操作直接学 CLI 命令--continue和--resume在自动化脚本里很有价值如果你主要在 VSCode 里写代码装插件会更顺手边看 diff 边下达指令恢复会话也在编辑器内完成。三种形态不是互斥的共享的会话机制让它们可以混用。今天在 VSCode 里开始的任务明天在终端里也能恢复只要会话文件和项目目录对得上。8.8 利用 CLAUDE.md 固化项目约定想让 Agent 在恢复会话后快速回到状态除了依赖对话历史还可以建立CLAUDE.md。这个文件可以放项目特有的规范、常用命令、架构说明甚至 Agent 完成任务时需要遵守的步骤。它相当于给 Agent 的“项目手册”每次会话启动都会自动加载。# CLAUDE.md ## 项目说明 这是一个基于 Spring Boot 3 的订单系统。 ## 常用命令 - 启动mvn spring-boot:run - 测试mvn test - 打包mvn package ## 编码规范 - 所有接口返回 ResultT 统一包装 - 日期字段使用 LocalDateTime - 新增依赖前先和架构师确认 ## 语言 - 请始终使用中文回答有了它即使你开了一个新会话Agent 也能快速理解项目背景/resume恢复的负担会小很多。9. 总结与后续学习方向这次写到最后我想把题目里的重点再说透一点/resume恢复会话本质上是把 Agent 的上下文变成了一笔可以“存起来再取出来”的资产。命令本身很简单但它背后代表的工作方式变化值得所有 Agent 编程用户重视。对新手来说先从桌面端的历史会话入口开始用感受一下会话恢复前后的差异对熟练用户来说把claude --continue、claude --resume session-id写进自己的工作流再配合 git 分支和阶段化 checkpoint中断就不再是灾难。下一步你可以继续深入几个方向一是学习 Skill 和CLAUDE.md的配置让 Claude Code 更符合你团队的工作习惯二是研究 settings.json 里各个环境变量的作用特别是接入第三方模型网关时的模型名映射问题三是在团队里推广“Agent 会话摘要交接”的实践把单个开发者的经验沉淀成团队可复用的工作记录。最后提醒一句任何工具都是手段上下文管理才是 Agent 编程的核心能力。现在就去创建一个长任务会话改到一半故意关掉终端再用/resume救回来你会瞬间明白这个功能为什么值得收藏备用。