在 Ubuntu 远程服务器上安装 Herdr：配置 Codex 与 Claude 持久会话

在家用服务器或远程开发机上运行 Codex、Claude Code 等编码代理时，最让人头疼的往往不是启动命令，而是 SSH 断开、笔记本合盖或网络切换后，终端里的任务也跟着中断。Herdr 是一个面向编码代理的终端工作区管理器：它像终端复用器一样让进程持续运行，同时能够识别代理状态，并把多个项目、标签页和窗格集中展示在一个终端界面中。

本文记录一次在 Ubuntu 远程主机上安装 Herdr，并为现有 Codex CLI 与 Claude Code 配置会话集成的完整过程。所有网络地址、用户名、主机名和凭据均已脱敏，示例不能直接反推出真实服务器信息。

部署目标与环境

本地 Mac / SSH 客户端
        |
        | SSH（经 Tailscale 私网）
        v
Ubuntu 26.04 LTS x86_64
        |
        +-- Herdr 0.8.2
        +-- Codex CLI
        +-- Claude Code

本次主机只通过 SSH 访问，没有为 Herdr 开放额外的公网端口。Herdr 的后台服务、终端进程和 Unix Socket 都运行在远端普通用户权限下。

先配置一个脱敏的 SSH 别名

不要在日常命令和文档里反复写真实 IP、用户名与密钥位置。可以先在本地 ~/.ssh/config 中配置别名：

Host home-agent
    HostName 100.x.y.z
    User <REMOTE_USER>
    IdentityFile ~/.ssh/<PRIVATE_KEY>
    IdentitiesOnly yes
    ServerAliveInterval 15
    ServerAliveCountMax 8

先验证普通 SSH 登录：

ssh home-agent

如果直接对 IP 执行 ssh 100.x.y.z，OpenSSH 可能使用本地用户名，而不是服务器实际账号，最终出现 Permission denied (publickey,password)。使用 SSH 别名可以同时固定目标地址、用户名和私钥，减少这种误判。

安装前检查

登录后确认操作系统、架构、Shell 和基础工具：

id -un
hostname
uname -srm
sed -n '1,12p' /etc/os-release
printf '%s\n' "$SHELL" "$PATH"
command -v curl
command -v codex
command -v claude
command -v herdr || true

本文对应的是 Linux x86_64。Herdr 官方也提供 macOS、Windows、Linux aarch64 等安装方式，具体以官方安装文档为准。

安装 Herdr stable 版

官方的一行安装命令是：

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

在需要保留审计过程的服务器上，我更习惯先把脚本下载到临时文件，执行成功后再删除：

herdr_installer_file=$(mktemp)
trap 'rm -f "$herdr_installer_file"' EXIT

curl -fsSL https://herdr.dev/install.sh -o "$herdr_installer_file"
sh "$herdr_installer_file"

安装器会自动检测平台、读取 stable 发布清单并下载匹配的二进制文件。本次安装结果为：

detected linux/x86_64
downloading v0.8.2
installed herdr to /home/<REMOTE_USER>/.local/bin/herdr

确认版本：

~/.local/bin/herdr --version

输出：

herdr 0.8.2

处理 PATH

Herdr 的直接安装方式默认把程序放到 ~/.local/bin/herdr。Ubuntu 的 ~/.profile 通常已经包含下面这段逻辑：

if [ -d "$HOME/.local/bin" ]; then
    PATH="$HOME/.local/bin:$PATH"
fi

重新登录 SSH 后，先确认登录 Shell 能找到 Herdr：

bash -lc 'command -v herdr && herdr --version'

如果只在 ~/.profile 中配置了 PATH，那么带远程命令的非登录 SSH 会话不一定读取它。脚本里可以显式使用 ~/.local/bin/herdr，或者通过 bash -lc 执行。不要因为一次非交互检查找不到命令，就重复安装。

为 Codex 与 Claude 安装 Herdr 集成

Herdr 不依赖集成也能运行代理并进行基础检测。官方集成的主要价值是让 Herdr 获取原生会话标识，从而在服务器重启后恢复受支持的代理会话。

先只检查服务器上实际存在的代理：

bash -lc '
for cmd in codex claude; do
    command -v "$cmd" || true
done
'

然后安装对应集成：

herdr integration install codex
herdr integration install claude

这两个命令会以合并方式更新用户级配置：

• Codex：在 ~/.codex/ 下安装 Herdr hook，更新 hooks.json，并在 config.toml 中启用 hooks 功能。
• Claude Code：在 ~/.claude/hooks/ 下安装 Herdr hook，并更新 settings.json。

不要为服务器上不存在的代理批量安装集成。以后新增代理时，再按需执行对应的 herdr integration install <name>。支持列表与各集成的具体行为可查看Herdr Integrations 文档。

验证集成与现有 CLI

先确认 Herdr 看到的集成状态：

herdr integration status | grep -E '^(codex|claude):'

正常结果类似：

claude: current (v8) (.../herdr-agent-state.sh)
codex: current (v8) (.../herdr-agent-state.sh)

再确认安装集成没有破坏原有命令：

herdr --version
codex --version
claude --version

还可以只检查 hook 是否存在和可执行，避免把配置文件中的其他内容打印到终端或日志：

test -x ~/.codex/herdr-agent-state.sh && echo 'Codex hook OK'
test -x ~/.claude/hooks/herdr-agent-state.sh && echo 'Claude hook OK'

为什么没有创建 systemd 服务

Herdr 默认就是“后台服务器 + 前台客户端”的结构。第一次执行 herdr 时，它会自动启动当前用户的后台会话；客户端退出或 SSH 断开后，后台服务器和窗格里的进程仍会继续运行。因此普通使用不需要自己编写 systemd 服务，也不需要开放监听端口。

默认会话的本地 Socket 位于：

~/.config/herdr/herdr.sock

它不是 TCP 端口，其他机器不能直接从公网访问。远程使用走原有 SSH 通道即可。

第一次启动

进入一个实际项目目录，再启动 Herdr：

ssh home-agent
cd ~/Projects/<PROJECT>
herdr

第一次启动会显示 onboarding 引导。Herdr 本身可以不创建 config.toml，默认配置已经能够工作；建议先完成引导并熟悉默认操作，再按需修改 ~/.config/herdr/config.toml。完整默认配置可以随时打印：

herdr --default-config

推荐先记住这些操作：

• 直接用鼠标点击窗格、标签页和工作区，拖动分隔线调整大小。
• 在当前窗格中执行 codex 或 claude，Herdr 会自动识别代理。
• Ctrl+B，松开后按 v：左右分屏。
• Ctrl+B，松开后按减号：上下分屏。
• Ctrl+B，松开后按 c：新建标签页。
• Ctrl+B，松开后按 q：脱离客户端，后台任务继续运行。
• 再次执行 herdr：重新连接默认会话。

按键区分大小写；准确的实时按键列表以 Ctrl+B 后按 ? 打开的帮助面板为准。官方也建议新用户先使用鼠标，再逐步记忆快捷键。

从本地终端直接连接远端 Herdr

如果本地也安装了相同版本的 Herdr，可以把本地程序作为轻量客户端，通过 SSH 连接远端服务器：

herdr --remote home-agent

这种方式会读取现有 SSH 配置，远端的工作区与代理仍运行在 Ubuntu 上，但界面显示在本地终端。它还可以桥接本地剪贴板等客户端能力。另一种最简单的方式仍然是先 ssh home-agent，再在远端运行 herdr。两种模式的区别可参考远程工作说明。

运行状态与维护

查看默认会话是否运行：

herdr session list --json

查看运行状态：

herdr status
herdr status server
herdr status client

修改配置后重新加载：

herdr server reload-config

直接安装的 Herdr 使用 stable 更新通道。检查并安装更新：

herdr update

只有在确实要结束所有窗格进程时，才停止后台服务器：

herdr server stop

注意：这与脱离客户端不同。脱离只关闭界面连接，停止服务器会结束该会话拥有的窗格进程。

回滚集成

如果暂时不需要代理会话恢复，可以使用 Herdr 自己的卸载命令移除集成，而不是手工删除 JSON 或 TOML 中的片段：

herdr integration uninstall codex
herdr integration uninstall claude

命令只移除 Herdr 管理的 hook 与对应配置项，不会卸载 Codex CLI 或 Claude Code。

常见问题

通过 IP 登录时认证失败

检查 ssh -G home-agent 展开的 hostname、user 和 identityfile。直接使用 IP 时，SSH 不会自动套用仅写在别名块中的用户名与私钥设置。

安装成功但提示 herdr: command not found

先执行绝对路径：

~/.local/bin/herdr --version

然后确认登录 Shell 的 PATH：

bash -lc 'printf "%s\n" "$PATH"; command -v herdr'

如果 ~/.profile 中还没有 ~/.local/bin，补充 PATH 后重新登录。自动化脚本则优先使用绝对路径，避免 Shell 启动模式差异。

集成显示 not installed

确认对应代理的配置目录已经存在，且命令属于当前用户：

command -v codex claude
ls -ld ~/.codex ~/.claude
herdr integration status

随后只重装异常的那个集成。不要用 sudo 安装用户级 Herdr 集成，否则 hook 可能被写入 root 的主目录。

关闭 SSH 后任务是否继续

只要是从 Herdr 窗格中启动的任务，并且使用 Ctrl+B 后按 q 正常脱离，Herdr 后台服务器会继续持有终端进程。重新登录并执行 herdr 即可恢复界面。关于断线、重启和代理原生会话恢复的差异，可查看持久化与远程访问文档。

脱敏检查清单

发布安装记录前，至少检查并替换以下内容：

• 真实公网 IP、Tailscale IP、域名和内网网段。
• 服务器用户名、主机名、SSH 别名和私钥文件名。
• Codex、Claude、GitHub、云平台等令牌与账号信息。
• 真实项目路径、仓库地址、客户名称和业务命令。
• 终端输出中可能出现的邮箱、设备名、Socket 路径与会话名。

本文统一使用 100.x.y.z、<REMOTE_USER>、<PRIVATE_KEY>、<PROJECT> 和 home-agent 等占位符。软件版本、操作系统大版本和通用用户目录结构不属于登录凭据，因此保留用于复现与排错。

总结

这次部署的关键并不是多写一个守护服务，而是把几个边界处理清楚：

1. 通过 SSH 别名固定远端账号与私钥，避免原始 IP 登录时选错用户。
2. 使用官方 stable 安装器把 Herdr 放入普通用户的 ~/.local/bin。
3. 确认登录 Shell 的 PATH，而不是看到一次 command not found 就重复安装。
4. 只为服务器上已有的 Codex 与 Claude 安装官方集成。
5. 使用 Herdr 自带的后台会话保持任务，不额外开放端口或创建 systemd 服务。
6. 发布前对地址、账号、主机名、项目路径和凭据做完整脱敏。

完成后，日常流程就很简单：SSH 到服务器，在项目目录运行 herdr，从窗格里启动编码代理，离开时脱离客户端，需要时再重新连接。安装和配置细节可继续查阅Herdr 官方文档。