# claude-account-switch-migration

**Repository Path**: fly542/claude-account-switch-migration

## Basic Information

- **Project Name**: claude-account-switch-migration
- **Description**: Claude 桌面端换账号后历史 Session 迁移指南
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude 桌面端换账号后历史 Session 迁移指南

换账号后 Claude Code 桌面端的左侧 sidebar 看不到旧 session？把旧账号的 session metadata 文件拷到新账号目录就好，对话原文不用动。

> **🤖 你是 Claude / AI agent，被丢了这个链接、让你「迁移 session / 恢复换号前的对话 / 照这个仓库做」？**
> 别只读不做。跳到下面 [给 AI agent 的执行说明](#给-ai-agent-的执行说明照着跑就做完) 按 4 步执行，全程自治，只有最后「重启桌面端」交回人类。

---

## 给 AI agent 的执行说明（照着跑就做完）

你（Claude）被要求把用户换号前的历史对话找回来。环境是 **Windows**。按下面做，不用问多余问题：

**1. 拿到脚本。** 同机通常已 clone 在 `C:\Users\david\claude-account-switch-migration`。没有就：

```powershell
git clone https://github.com/xing0325/claude-account-switch-migration
cd claude-account-switch-migration
```

**2. 先 dry-run 预览（必跑，不动任何文件）：**

```powershell
pwsh -File .\migrate.ps1 -All      # powershell.exe 也行
```

看它打印的账号表，确认标着 `← 目标(新号)` 的那行 = 用户**当前登录的新号**（通常 session 数最少、最近活动最新）。探测错了就用 `-Target <UUID前缀>` / `-Source <UUID前缀>` 纠正。

**3. 没问题就执行：**

```powershell
pwsh -File .\migrate.ps1 -All -Apply
```

脚本自动备份新号 workspace，再把**所有旧号**的 session metadata 拷过去（已存在的跳过）。打印 `完成：拷贝 N 个` 即成功。

**4. ⚠️ 最后一步你做不了，必须交回人类：**

让用户**彻底退出 Claude 桌面端**（任务管理器 `Ctrl+Shift+Esc` → 结束所有 `Claude.exe`）再重开。

> **绝对不要自己去 kill `Claude.exe`** —— 你这个 agent 就跑在 Claude 桌面端进程里，杀了它 = 杀了你自己，任务当场中断、迁移可能只做一半。明确对用户说一句：「我已经把 session 迁移完了，请你手动彻底退出 Claude 再重开，重启后旧对话就回到 sidebar 了。」

做完即可。**别去动 `~/.claude/projects/` 下的 `.jsonl`**（那是对话原文，不用碰）。想懂原理 / 排查异常，继续往下读人类版。

---

## 适用场景

- Claude Code 桌面端切换了登录账号（公司号 ↔ 个人号、新购账号、号被ban换号等）
- 旧账号下做过的对话在新账号 sidebar 里全部消失
- 但你确认 `~/.claude/projects/<...>/*.jsonl` 文件还在硬盘上

如果是上面情况，本指南直接能用。如果是 .jsonl 也没了，本指南救不了 —— 那是真丢了。

---

## 原理

桌面端的 session 信息分两层存：

| 内容 | 路径 | 谁绑定 |
|---|---|---|
| Sidebar 元数据（title、cwd、时间戳） | `%APPDATA%\Claude\claude-code-sessions\<account-id>\<workspace-id>\local_*.json` | **账号-scoped** |
| 实际对话内容（jsonl） | `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl` | **账号无关** |

每个 `local_*.json` 里有 `cliSessionId` 字段，正好等于 `.jsonl` 的文件名（不含 `.jsonl`）。两边靠它配对。

换账号 = 桌面端启用一个新的 `<account-id>` 子目录。新目录刚建是空的，于是 sidebar 看着像 session 全没了。但 `.jsonl` 在 `~/.claude/projects/` 下，没动。

**修复思路：把旧账号下的 `local_*.json` 拷到新账号下，sidebar 就能再次列出来。**

---

## 一键脚本（推荐）

仓库带了 [`migrate.ps1`](migrate.ps1)，**自动探测**新旧账号和各自 workspace，不用手填 UUID。默认只预览不动文件：

```powershell
# 1. 先登录新账号、随便发一条消息（让新账号目录生成出来）
# 2. 预览（dry-run，安全）：
.\migrate.ps1
# 3. 确认探测对了，再真正执行：
.\migrate.ps1 -Apply
# 4. 任务管理器结束所有 Claude.exe → 重开
```

探测逻辑：

- **目标(新号)** = mtime 最新的账号目录（你刚登录进去的那个）
- **源(待迁移)** = 其余账号里 `local_*.json` 最多的那个（累积历史最全的）
- **workspace** = 每个账号下 session 最多的子目录（自动跳过 `*BACKUP*` 目录）

探测选错时手动覆盖：`.\migrate.ps1 -Source <旧账号UUID前缀> -Target <新账号UUID前缀> -Apply`。
想把第二个老号也合并进来，换个 `-Source` 再跑一次即可（非覆盖，安全叠加）。

> 多账号场景：脚本会把探测到的所有账号 + 各自 session 数打成一张表，跑 `-Apply` 前先核对「角色」列对不对。

下面的手动版是脚本跑不动时的兜底，原理一样。

---

## 操作步骤（Windows，手动版）

### 0. 准备

关一下 Claude 桌面端再操作更稳。任务管理器（`Ctrl+Shift+Esc`）→ 找所有 `Claude.exe` 进程 → 结束任务。不关也行，只是最后必须重启才能看见效果。

### 1. 找到新旧账号目录

```powershell
Get-ChildItem 'C:\Users\david\AppData\Roaming\Claude\claude-code-sessions' |
  Sort-Object LastWriteTime -Descending |
  Select-Object LastWriteTime, Name
```

会列出若干个 UUID 目录。

- **mtime 最新的那个 = 当前账号**
- 其他 = 旧账号

每个账号目录下还有一层 workspace UUID 子目录。同样按 mtime 取最新的。

### 2. 备份新账号当前 workspace（不要省）

```powershell
$NEW = 'C:\Users\david\AppData\Roaming\Claude\claude-code-sessions\<NEW_ACCOUNT_UUID>\<NEW_WORKSPACE_UUID>'
Copy-Item $NEW ($NEW + '__BACKUP_BEFORE_MIGRATION') -Recurse -Force
```

把 `<NEW_ACCOUNT_UUID>` / `<NEW_WORKSPACE_UUID>` 替换成第 1 步看到的实际值。

### 3. 拷贝旧账号 metadata 到新账号

```powershell
$OLD = 'C:\Users\david\AppData\Roaming\Claude\claude-code-sessions\<OLD_ACCOUNT_UUID>\<OLD_WORKSPACE_UUID>'
$copied = 0; $skipped = 0
Get-ChildItem $OLD -Filter 'local_*.json' -File | ForEach-Object {
  $target = Join-Path $NEW $_.Name
  if (Test-Path $target) { $skipped++ } else { Copy-Item $_.FullName $target; $copied++ }
}
"copied: $copied, skipped: $skipped"
```

`if (Test-Path $target)` 这行是防呆 —— 不覆盖新账号已有的 session metadata（避免误伤当天的对话）。

### 4. 重启 Claude 桌面端

任务管理器结束所有 `Claude.exe` → 从开始菜单重开。

仅关闭主窗口不够，托盘里可能还有后台进程。**必须彻底退出**才会重新扫描 metadata 目录。

### 5. 验证

打开桌面端，看左侧 sidebar 的 Ungrouped 区域（或其他分组）。应该出现迁移过来的 session 标题。

点进任意一个：

- ✅ 能看到完整对话历史 → 成功
- ⚠️ 显示 "session not found" 或空白 → 看 [故障排查](#故障排查)

---

## 回滚

迁移没效果 / 出问题，一键回到迁移前：

```powershell
$NEW = 'C:\Users\david\AppData\Roaming\Claude\claude-code-sessions\<NEW_ACCOUNT_UUID>\<NEW_WORKSPACE_UUID>'
Remove-Item $NEW -Recurse -Force
Rename-Item ($NEW + '__BACKUP_BEFORE_MIGRATION') (Split-Path $NEW -Leaf)
```

`.jsonl` 文件全程没动，不会丢对话。

---

## 故障排查

### Sidebar 完全没出现迁移的 session

可能原因：

1. **没真正重启桌面端** —— 托盘进程还在，加载的是内存缓存。任务管理器确认 `Claude.exe` 全没了再开。
2. **拷贝到了错的 workspace UUID** —— 一个账号下可能有多个 workspace，挑了不活跃的那个。回滚后 Step 1 重新比对 mtime。
3. **桌面端走了别的缓存源** —— 较新版本可能用 IndexedDB 缓存了列表。试着删 `%APPDATA%\Claude\IndexedDB\`（**这步有风险，会清窗口位置等设置，但不会动 session**），再重启。

### 点进 session 显示 "找不到对话"

`local_<uuid>.json` 里 `cliSessionId` 对应的 `.jsonl` 在 `~/.claude/projects/` 下找不到。常见原因：

- `.jsonl` 真的被删了（清磁盘空间时手抖）
- 跨电脑迁移时只搬了 metadata 没搬 `.jsonl`

解决：把缺的 `.jsonl` 文件补回 `~/.claude/projects/<encoded-cwd>/` 下。`encoded-cwd` 通常是 cwd 路径把 `:` 和 `\` 换成 `-`，比如 `C:\Users\david` → `C--Users-david`。

### Title 显示空白 / Untitled

桌面端可能要重新生成 title，无害。也可以手动编辑 `local_<uuid>.json` 里的 `title` 字段。

---

## metadata 文件长这样

`local_<uuid>.json` 实例（字段随版本增减，关键的几个稳定）：

```json
{
  "sessionId": "local_7e325bc0-1c26-4938-af2f-290e7882b60b",
  "cliSessionId": "2a257fc4-40f8-4fa7-b77b-6d44a768c403",
  "cwd": "C:\\Users\\david",
  "originCwd": "C:\\Users\\david",
  "lastFocusedAt": 1782733015931,
  "createdAt": 1782733015616,
  "lastActivityAt": 1782733023237,
  "model": "claude-opus-4-8",
  "effort": "max",
  "isArchived": false,
  "title": "Session migration across accounts",
  "titleSource": "auto",
  "permissionMode": "bypassPermissions",
  "enabledMcpTools": { "...": true },
  "remoteMcpServersConfig": [ /* 见下方提醒，可能很大 */ ]
}
```

关键字段（迁移只靠这几个，其余都是显示/恢复用）：

- `cliSessionId` —— 指向 `~/.claude/projects/<encoded-cwd>/<这个值>.jsonl`，**两边配对的命根子**
- `cwd` —— 决定 sidebar 分组到哪个 project
- `title` / `titleSource` —— sidebar 显示文字
- `isArchived` —— 设 `true` 可以从 sidebar 隐藏但保留

> ⚠️ **文件可能很大（100KB+）**：新版把整个 `remoteMcpServersConfig`（每个远程 MCP server 及其所有 tool 的完整 inputSchema）内嵌进了 `local_*.json`，比早期的 `[]` 膨胀几十倍。直接整文件拷贝不受影响；但若你想手动 grep / 编辑，注意别被这一大坨 schema 干扰，也别用会截断大文件的工具去搬。新增字段如 `lastFocusedAt`、`enabledMcpTools` 同理 —— 整文件拷就行，不用挑字段。

---

## 跨平台路径对照

| 平台 | sidebar metadata | `.jsonl` 对话 |
|---|---|---|
| Windows | `%APPDATA%\Claude\claude-code-sessions\` | `~\.claude\projects\` |
| macOS | `~/Library/Application Support/Claude/claude-code-sessions/` | `~/.claude/projects/` |
| Linux | `~/.config/Claude/claude-code-sessions/` | `~/.claude/projects/` |

macOS / Linux 路径按 Electron 默认 userData 推断，未亲测，仅供参考。

---

## 一行迁移脚本（Windows，懒人版）

> 一般直接用 [`migrate.ps1`](migrate.ps1) 就行（自动探测、带预览和备份）。下面这段是不想跑脚本、想手动填 UUID 直接贴进 PowerShell 的版本：

```powershell
$OLD_ACCT = '<OLD_ACCOUNT_UUID>'
$OLD_WS   = '<OLD_WORKSPACE_UUID>'
$NEW_ACCT = '<NEW_ACCOUNT_UUID>'
$NEW_WS   = '<NEW_WORKSPACE_UUID>'
$base = "$env:APPDATA\Claude\claude-code-sessions"
$src = "$base\$OLD_ACCT\$OLD_WS"
$dst = "$base\$NEW_ACCT\$NEW_WS"
Copy-Item $dst ($dst + '__BACKUP_BEFORE_MIGRATION') -Recurse -Force
$c = 0; $s = 0
Get-ChildItem $src -Filter 'local_*.json' -File | ForEach-Object {
  $t = Join-Path $dst $_.Name
  if (Test-Path $t) { $s++ } else { Copy-Item $_.FullName $t; $c++ }
}
"copied: $c, skipped: $s. now restart Claude desktop."
```

---

## 写作背景 / 版本

- 首次写作: 2026-05-29，实测 Claude Code desktop `2.1.149` / Windows 11
- 触发场景: 用户切了全新账号，56 个旧 session 不见，迁移 56 个 metadata 后 sidebar 恢复
- 2026-06-29 复核更新:
  - 加了自动探测脚本 [`migrate.ps1`](migrate.ps1)（替代手填 4 个 UUID）
  - 核对路径结构、`cliSessionId` 配对机制依旧有效（未变）
  - `model` 已到 `claude-opus-4-8`；`local_*.json` 新增 `lastFocusedAt`/`enabledMcpTools` 字段，且 `remoteMcpServersConfig` 现在内嵌完整 MCP schema，单文件可达 100KB+（整文件拷贝不受影响）
  - 实测多账号叠加迁移正常（老号 56 个里 55 个已在当前号中，非覆盖逻辑只补 1 个）

如发现新版本路径变了 / 字段变了，欢迎提 PR 更新。