使用 Herdr 和 Happy 进行 Agent 会话恢复

背景

在服务器上跑 Claude Code / Codex 这类 CLI Agent，最烦的两件事：

1. SSH 一断，会话就没了。 用 nohup / screen / tmux 能挂后台，但下次回来还得找半天哪个 pane 在跑什么。
2. 手机上没法操作。 出门在外想继续给 Agent 派活、批权限、看结果，纯 SSH 客户端体验很差。

之前的方案是 tmux + Claude Code，能恢复会话，但手机上仍只能敲命令行。这次试了 Herdr + Happy 的组合，把「终端会话保持」和「手机端 Agent 控制」分开解决：

• Herdr：Rust 写的终端多路复用器，专注管理 Agent 会话，自带左侧 Agent 状态栏、分屏、跨 SSH 断开恢复。
• Happy：给 Claude Code / Codex 套一层 wrapper，把会话同步到手机 App，可以远程发消息、批权限、看 diff。

架构大致是：

Herdr Pane
   └── happy claude
          └── Claude Code
                ↕
           Happy 手机 App

下图是 Herdr 的界面，左侧是多个 Agent 区域，中间是 Agent 的展示区域：

这是 Happy 的 App 页面，可以看到同一个 Claude Code 会话已经同步到手机，底部能直接发消息：

安装

一、安装 Herdr

在 Ubuntu 服务器上（先 SSH 登录）：

curl -fsSL https://herdr.dev/install.sh | sh

重新登录，或者：

source ~/.profile

验证：

herdr --version
which herdr

如果提示找不到命令，直接把 ~/.local/bin 加进 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
source ~/.profile

Herdr 是单个 Rust 二进制，支持 Ubuntu x86_64 和 ARM64，不需要 Docker，也不用单独装数据库。

二、确认 Claude Code 已安装

Herdr 不自带 Claude Code，只是管理终端和 Agent。

claude --version

还没登录的话直接运行 claude 按提示授权。你自己原来的 API / 模型配置不受影响，Herdr 不会改变模型或 API 地址。

Codex 同理：codex --version。

三、安装 Agent 集成

Claude Code 跑过、生成了 ~/.claude 目录之后：

herdr integration install claude
# 用 Codex 的话
herdr integration install codex

herdr integration status

集成主要用于保存 Claude/Codex 的 Session ID，服务器或 Herdr 重启后可以恢复原对话。

四、安装 Happy

Happy 要求 Node.js 20+：

node --version
npm install -g happy

happy --version
happy doctor

npm 包现在叫 happy，旧教程里的 happy-coder 已迁移。

登录并绑定手机：

happy auth login

然后在手机装 Happy App（iOS / Android 都有），按终端里的二维码或登录提示完成绑定。

使用

启动 Herdr

进入项目目录：

cd /你的项目目录
herdr

Herdr 会自动拉起后台 Server、创建默认 Workspace、打开终端界面。

在 Herdr 里启动 Happy 包装的 Claude

关键步骤：不要直接运行 claude，而是用 HERDR_AGENT 环境变量 + happy 启动：

HERDR_AGENT=claude happy claude

Codex 用：

HERDR_AGENT=codex happy codex

HERDR_AGENT 是 Herdr 官方给 Wrapper / 沙箱程序准备的识别提示——告诉 Herdr「虽然前台进程叫 happy，但请按 claude 识别」。少了这个变量，左侧 Agents 栏会是空的（Herdr 看到的前台程序是 happy，不在它的 Agent 列表里）。

为了方便，在 ~/.bashrc 里加两个别名：

alias hclaude='HERDR_AGENT=claude happy claude'
alias hcodex='HERDR_AGENT=codex happy codex'

之后直接 hclaude 就行。

恢复之前的 Happy 会话：

happy daemon list
HERDR_AGENT=claude happy resume <Happy会话ID>

常用快捷键

断开 SSH 但保持运行

不要用 exit 结束 Claude，直接按 Ctrl+B 然后 Q。退出 Herdr 界面后关掉 PuTTY/SSH 窗口即可——

• PuTTY 关了
• Herdr Server 继续在跑
• Happy / Claude Code 继续在跑
• npm run dev 之类的开发服务也继续在跑

下次重新 SSH 上去（必须用启动 Herdr 时的同一个 Ubuntu 用户），执行 herdr，就回到原来的界面。

手机访问

手机装 Happy App，登录同一账号，就能看到所有通过 happy claude 启动的会话，可以：

• 继续给 Claude 发任务
• 同意 / 拒绝权限请求
• 查看代码变更
• 接收「完成 / 等待确认」通知
• 在手机和终端之间切换控制权

Happy 默认走官方中继服务器同步，手机不需要连家里内网；官方称会话端到端加密。不想让流量经过第三方的话，可以后续自建 Happy Server。

踩过的坑

1. Herdr 左侧 Agents 栏看不到 Happy 里的 Claude

现象：在 Herdr 里跑 happy claude，左侧 Agents 是空的。

原因：Herdr 原生只识别 claude、codex 这些命令本身，运行 happy claude 时它看到的前台进程是 happy，不在支持列表里。

排查：

pgrep -af 'happy|claude|codex'
herdr agent list

能看到 happy/claude 进程、但 herdr agent list 为空，就确认是包装进程遮挡。

解决：用前面提到的 HERDR_AGENT=claude happy claude 启动。

需要注意：即便这样，手机端把会话切到远程模式后，Herdr 状态栏里的 working/blocked 状态可能偶尔不准——Herdr 和 Happy 没有官方直接集成，只能根据终端内容推断。手机控制本身不受影响。

2. Happy 不能接管已经在跑的 claude 进程

如果你先在 Herdr 里直接运行了 claude，事后是没法让 Happy 无缝接管这个进程的——它没经过 Happy wrapper。必须从一开始就用 happy claude 启动。

3. 家用服务器别把 SSH 22 端口直接暴露公网

如果服务器在家里，外出时先连 WireGuard，再访问内网 IP。SSH 直接暴露公网被扫是家常便饭。

常用管理命令

herdr status              # Herdr 状态
herdr agent list          # Agent 列表
herdr integration status  # 集成状态
herdr update              # 更新 Herdr
herdr server stop         # 真正停掉所有窗口和 Agent（慎用）

最后一条会结束 Pane 里正在运行的 Claude / Codex / 开发服务器，正常使用别执行。

总结

这套组合下来，我的分工是：

• Herdr：多项目状态总览、终端分屏、跨 SSH 断开的会话保持
• Happy：手机端操作 Claude、收通知、批权限
• 测试、日志、开发服务器：跑在 Herdr 的其他 Pane 里

相比之前的 tmux 方案，最大提升是手机上能真正「用」Agent 了，不只是「看」Agent。代价是多了一层 Happy 中继，介意的可以自建 Happy Server。