我开源了 cc-session-migrate ：让 Claude Code 会话在多台机器之间自由迁移

本文永久链接 – https://tonybai.com/2026/07/20/introducing-cc-session-migrate

大家好，我是Tony Bai。

【导读】一个解决 Claude Code 跨机器开发痛点的开源工具，支持会话迁移、集群管理和 S3 自动备份。

GitHub：https://github.com/bigwhite/cc-session-migrate

痛点：你的 Session 被困在了那台机器上

如果你已经在使用 Claude Code 进行日常开发，大概率遇到过这样的场景：

上午在 MacBook 上开了一场长对话，Claude 帮你理清了一个复杂的架构设计，甚至写好了几个关键模块的骨架代码。下午你切到 Linux 服务器上想继续推进——打开终端，输入 claude --resume，结果被告知：

No sessions found.

因为 Claude Code 的会话数据存储在本地磁盘 ~/.claude/ 下。换一台机器，上下文就断了。

如果你同时在多台机器上开发（笔记本 + 台式机 + 远程服务器），这个问题会被反复触发。手动 scp 整个 ~/.claude/ 目录？可以，但很粗暴，而且容易覆盖其他机器上的会话。

csm（cc-session-migrate） 就是为了解决这个问题而生的。

csm 是什么

csm 是一个用 Go 编写的 CLI 工具，核心能力三句话概括：

跨机器迁移 — 把 Claude Code 会话从一台机器拉到另一台，支持 claude --resume 无缝续接
集群管理 — 多个开发节点组成开发集群，互相可见、可互相进行迁移会话操作
S3 自动备份 — 会话数据定期备份到 R2/MinIO 等 S3 兼容存储，防止丢失

架构：Hub-and-Spoke，不是 Mesh

最初的设计是 Mesh 架构——每个节点都监听一个端口，其他节点直连。听起来简单，但一落地就碰到了 NAT 穿透问题：

笔记本在公司内网，没有公网 IP
家里的台式机在路由器后面，需要端口映射
每次加一台机器，就要配一遍防火墙

所以最终采用了 Hub-and-Spoke（中心辐射） 架构，和 Consul、Nomad 的 Agent 模式类似：

                        ┌──────────────────────┐
                        │   Server (Leader)     │
                        │   公网 Linux 服务器    │
                        │   HTTP + WS :9827     │
                        └──────┬───────────┬────┘
                     WebSocket │           │ WebSocket
                      (出站)   │           │  (出站)
                    ┌──────────┘           └──────────┐
                    ▼                                 ▼
            ┌──────────────┐                  ┌──────────────┐
            │ Agent: 笔记本 │                  │ Agent: 台式机 │
            │ (MacBook)    │                  │ (Home PC)    │
            │  无需监听端口  │                  │  无需监听端口  │
            └──────────────┘                  └──────────────┘

这个架构的核心优势在于：所有 Agent 只建立出站 WebSocket 连接，不需要监听任何端口。不管你在公司内网、家里 Wi-Fi 还是咖啡馆热点，只要能访问服务器 IP，就能加入集群。

Server 端充当"中继站"，所有会话操作（list / pull / push）都通过 Server 转发。

5 分钟上手

安装

Linux（推荐作为 Server 节点）：

git clone https://github.com/bigwhite/cc-session-migrate.git
cd cc-session-migrate
make build
sudo ./scripts/install.sh --local ./bin/cc-session-migrate

macOS / Windows：

go install github.com/bigwhite/cc-session-migrate@latest
alias csm='cc-session-migrate'  # 写入 ~/.zshrc 或 ~/.bashrc

搭建集群

Step 1 — 在 Linux 服务器上启动 Server 模式：

sudo sed -i 's/CSM_AGENT_ROLE=agent/CSM_AGENT_ROLE=server/' /etc/cc-session-migrate/env
sudo systemctl enable --now cc-session-migrate
cat ~/.csm/config.yaml    # 查看生成的 auth-token

Step 2 — 在笔记本上以 Agent 模式加入：

csm agent --server-addr <server-ip>:9827 --auth-token <token> --name my-macbook

Step 3 — 验证：

$ csm cluster list
NAME               ROLE    ADDRESS               STATUS  OS
server01           server  xx.xx.xx.xx:9827      online  
my-macbook         agent                         online  darwin/amd64
server02           agent                         online  linux/amd64

迁移会话

# 查看本地节点的会话列表
csm session list 

# 查看远程节点的会话列表
csm session list --node my-macbook

# 拉取一个会话到本地（需要指定本地项目路径）
csm session pull <session-id> --from my-macbook --project ~/go/src/my-project

# 用 claude --resume 继续开发（注意：必须用完整的 session ID）
claude --resume 47f57b56-48b3-4405-b01d-3b8591874fe2

一条命令，上午在笔记本上讨论的架构方案，下午就能在服务器上继续推进。

开发中踩过的坑

开源之前，分享几个开发过程中比较有代表性的技术问题。

1. Claude Code 的项目目录编码

Claude Code 把会话文件存储在 ~/.claude/projects/<encoded-path>/ 下。编码规则是把路径中的 / 和 . 都替换为 -：

/Users/tonybai/go/src/github.com/bigwhite/myproject
→ -Users-tonybai-go-src-github-com-bigwhite-myproject

这意味着 github.com 变成了 github-com，解码时所有 - 都会被替换回 /——这是一个有损编码：你无法区分原始的 - 和由 / 或 . 编码来的 -。

解法：不靠解码，而是从会话 JSONL 文件的第一行读取 cwd 字段，拿到真实的源路径。然后做路径重映射。

2. 跨机器路径不一致

MacBook 上的项目路径是 /Users/tonybai/go/src/my-project，Linux 服务器上是 /home/tonybai/go/src/my-project。csm 在打包时会记录源路径，解包时通过 --project 参数指定目标路径，自动完成：

项目目录重命名（RenameProjectDir）
JSONL 文件内的路径替换（RemapPaths）
history.jsonl 记录更新

3. history.jsonl 格式对齐

Claude Code 的 history.jsonl 格式是 {sessionId, project, display, timestamp}，而不是直觉上以为的 {sessionId, cwd}。格式不对会导致 claude --resume 找不到会话。csm 严格按照 Claude Code 的格式写入历史记录。

4. claude –resume 不支持前缀匹配

csm 的 session pull 支持 8 字符前缀匹配，但 claude --resume 必须使用完整的 UUID。这是一个容易混淆的点，README 中已做了重点标注。

S3 自动备份

除了实时迁移，csm 还支持将会话数据备份到 S3 兼容存储：

# 配置 Cloudflare R2（或其他 S3 兼容存储）
csm backup config \
  --endpoint https://xxx.r2.cloudflarestorage.com \
  --bucket csm-backups \
  --access-key $ACCESS_KEY \
  --secret-key $SECRET_KEY

# 手动备份
csm backup create

# 查看备份历史
csm backup list

# 从备份恢复
csm backup restore --node server-01 --session <session-id>

守护进程模式下还支持定时自动备份（增量，基于文件 mtime），过期备份自动清理（默认保留 30 天）。

技术栈

组件	选型	说明
CLI 框架	cobra + viper	Go 生态标配，YAML 配置 + 环境变量覆盖
通信协议	WebSocket (gorilla)	双向通信，低延迟，NAT 友好
S3 客户端	aws-sdk-go-v2	兼容 R2、MinIO 等任何 S3 协议存储
定时任务	robfig/cron	自动备份调度
日志	log/slog	Go 1.21+ 标准库结构化日志

整个项目零 CGO 依赖，交叉编译非常方便：

GOOS=linux GOARCH=amd64 go build -o csm-linux-amd64
GOOS=darwin GOARCH=arm64 go build -o csm-darwin-arm64
GOOS=windows GOARCH=amd64 go build -o csm-windows-amd64.exe

为什么开源

作为 Claude Code 的重度用户，多机开发是我的日常。csm 最初只是为了解决自己的痛点，写着写着发现它其实是个通用需求——任何在多台机器上使用 Claude Code 的开发者可能都会需要。

与其让它仅仅躺在我的机器里，不如开源出来，也欢迎大家积极提 PR 和 Issue。

GitHub：https://github.com/bigwhite/cc-session-migrate

如果你觉得有用，给个 Star 就是最大的支持。当然，也欢迎请我喝杯咖啡 ☕

还在为“复制粘贴喂AI”而烦恼？我的新专栏 《AI原生开发工作流实战》 将带你：

告别低效，重塑开发范式
驾驭AI Agent(Claude Code)，实现工作流自动化
从“AI使用者”进化为规范驱动开发的“工作流指挥家”

扫描下方二维码，开启你的AI原生开发之旅。

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

想写出更地道、更健壮的Go代码，却总在细节上踩坑？
渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。

痛点：你的 Session 被困在了那台机器上#

csm 是什么#

架构：Hub-and-Spoke，不是 Mesh#

5 分钟上手#

安装#

搭建集群#

迁移会话#

开发中踩过的坑#

1. Claude Code 的项目目录编码#

2. 跨机器路径不一致#

3. history.jsonl 格式对齐#

4. claude –resume 不支持前缀匹配#

S3 自动备份#

技术栈#

为什么开源#

📚 相关文章