Claude Code /rename 详解：给你的会话取个有意义的名字

为什么需要 /rename

用 Claude Code 开发一段时间后，你的会话历史会越来越长。默认情况下，会话只有时间戳标识——要找回三天前某次调试的上下文，只能靠记忆猜测，或者逐条翻看。

/rename 解决的就是这个问题：给当前会话起一个有意义的名字，让历史记录变得可查找、可回溯。

基础用法

/rename 有两种调用方式：

手动命名：

/rename fix-auth-token-expiry

直接指定名称，立即生效，输出：

Session renamed to: fix-auth-token-expiry

AI 自动命名：

/rename

不带任何参数时，Claude Code 会调用 Haiku 模型分析当前会话内容，自动生成一个名称。如果会话内容太少（还没有实质性对话），会提示：

Could not generate a name: no conversation context yet. Usage: /rename <name>

AI 自动命名怎么工作的

不带参数执行 /rename 时，后台流程如下：

第一步：提取会话文本

从当前会话的消息记录中提取对话内容，只保留用户和 Claude 的实际文本消息，跳过工具调用结果、系统消息、meta 消息等非对话内容。

如果对话文本超过 1000 个字符，只取最后 1000 个字符——尾部截取，让最近的上下文优先，因为最近的对话最能代表这次会话在做什么。

第二步：调用 Haiku 生成 kebab-case 名称

将提取出的对话文本发给 Haiku，系统提示是：

“Generate a short kebab-case name (2-4 words) that captures the main topic of this conversation. Use lowercase words separated by hyphens.”

并给出几个示例：fix-login-bug、add-auth-feature、refactor-api-client、debug-test-failures。

Haiku 返回 JSON 格式结果，Claude Code 解析其中的 name 字段作为最终名称。

第三步：应用名称

生成的名称和手动指定的名称走完全相同的保存流程。

之所以选 Haiku 而不是更强的模型：命名是一个简单的摘要任务，Haiku 速度快、成本低，完全够用。

启动时命名：-n 参数

除了在会话中用 /rename，还可以在启动 Claude Code 时直接指定会话名：

claude -n fix-login-bug
# 或
claude --name fix-login-bug

这样会话从一开始就有名字，不用事后再补命名。名称会立即写入会话标题缓存，在 /resume 列表中显示。

Plan 模式退出时的自动命名

这是一个很少被人注意到的细节。

当你在 Plan 模式（/plan）中制定完计划、即将进入执行阶段时，Claude Code 会自动尝试给会话命名——前提是当前会话还没有名字。

触发时机：你确认退出 Plan 模式（点击 Accept Plan）的瞬间。

触发后，Claude Code 用 generateSessionName 分析你写的 Plan 内容（取前 1000 个字符，头部截取而不是尾部——因为 Plan 的目标通常在开头），生成一个 kebab-case 名称，自动保存，source 标记为 'auto'（区别于 /rename 手动触发的 'user'）。

自动命名有保护机制：

如果当前会话已经有名字（无论手动还是之前自动命名的），不会覆盖
如果是”清除上下文”（clear-context），跳过这个保护，允许为新的执行会话命名

双标题系统

Claude Code 内部维护两套标题，存储在同一个会话的 .jsonl 文件中：

类型	字段	entry 类型	来源	优先级
用户自定义标题	`customTitle`	`custom-title`	`/rename`、`-n` 启动参数、Plan 模式自动命名	高
AI 自动标题	`aiTitle`	`ai-title`	系统后台自动生成	低

读取时，customTitle 始终覆盖 aiTitle——你主动命的名永远优先，系统兜底但不抢占。

为什么要用两种不同的 entry 类型，而不是同一个字段？

这是刻意的设计，注释里写得很清楚：

防止 AI 标题覆盖用户标题：/resume 恢复会话时只从 custom-title 类型的 entry 恢复标题，不会把 AI 自动生成的 ai-title 当成用户设置的名字
防止 re-append 时出错：会话文件尾部重写时，只会重新追加 custom-title，不会重新追加 ai-title，避免旧的 AI 标题覆盖了中途用户手动改的名字
独立的写入语义：AI 标题可以覆盖上一条 AI 标题，但永远不能覆盖用户标题

两种 AI 命名格式的区别

Claude Code 有两套 AI 自动命名，格式完全不同：

来源	格式	示例
`/rename`（无参数）	kebab-case，2-4 个单词	`fix-auth-token-expiry`
系统自动命名（后台）	Sentence case，3-7 个单词	`Fix login button on mobile`

/rename 生成的是机器友好的短标签，适合在终端显示和脚本引用；系统自动命名生成的是更自然的短句，适合在 UI 列表中展示。

两者的 Haiku 调用参数、prompt 和 JSON 字段名也不同（/rename 用 name 字段，系统用 title 字段），是完全独立的两个生成器。

保存位置

命名结果以两条记录写入会话文件（~/.claude/projects/<project-hash>/<session-id>.jsonl）：

custom-title 记录：保存名称，供 /resume 等列表类命令展示
agent-name 记录：同步更新终端提示栏显示的代理名称，让你在会话进行中也能看到当前名称

两者写入同一个 .jsonl 文件，追加到末尾，不产生额外文件。

和 claude.ai 的同步

如果你通过 Claude Desktop 或 claude.ai/code 使用 Claude Code，/rename 还会把新名称同步到云端 Bridge 会话：

检测当前会话是否关联了 Bridge 会话 ID（replBridgeSessionId）
如果有，异步调用 updateBridgeSessionTitle 更新云端标题
同步是非阻塞的（fire-and-forget），失败也只是静默跳过，不影响本地命名

这意味着你在终端里 /rename，claude.ai 上的会话列表也会更新。

Swarm 模式下不能重命名

如果当前会话是 Swarm（多 Agent 并行）中的 Teammate 子会话，/rename 会拒绝执行：

Cannot rename: This session is a swarm teammate. Teammate names are set by the team leader.

Teammate 的名字由 Team Leader 统一管理，个体不能自行修改，避免协作中出现混乱。

和 /resume 配合使用

/rename 的价值在 /resume 里最直观地体现出来：

  1. fix-auth-token-expiry          2 hours ago
  2. add-payment-webhook            yesterday
  3. debug-memory-leak-prod         3 days ago
  4. 1745123456789                  4 days ago   ← 没命名，只有时间戳

命了名的会话一眼就能认出来，没命名的只剩时间戳。

养成习惯：开始一个新任务时就 /rename，或者让 Plan 模式帮你自动命名，几个月后的你会感谢现在的你。

实用建议

开始时命名：确定要做什么了，先 /rename fix-xxx，再开始干活。

用 -n 启动：从命令行启动时带上名字 claude -n refactor-api-client，省去会话里再 /rename 的步骤。

不知道叫什么就 /rename（无参数）：让 AI 帮你想，通常比你临时想的名字更准确，因为它是基于实际对话内容生成的，不是基于你最初的预期。

配合 Plan 模式：用 /plan 制定计划时，退出 Plan 模式会自动命名，不用手动操作。

写在最后

/rename 是个小命令，但它解决了一个真实的问题：AI 编程的上下文管理。

代码提交到 git 有记录，但和 Claude 的对话默认是无名的、难以检索的。/rename 让每次有价值的会话都有一个可辨识的标签，双标题系统、Bridge 同步、Plan 模式自动命名——这些细节加在一起，构成了一个认真设计过的会话管理体验。

好记性不如烂笔头——/rename 就是给 AI 对话的那支笔。