使用 Herdr 管理多个 AI 编程代理：从安装、协作到远程接管

适合对象：同时使用 Codex、Claude Code、OpenCode 等终端代理，希望减少窗口混乱、随时查看任务状态的人
适用平台：Linux、macOS；Windows 已提供稳定渠道，仍需检查平台限制
核对时间：2026 年 11 月 7 日；安装入口、支持列表和配置项可能更新，请以 Herdr 官方文档 为准

一、先理解 Herdr 解决的到底是什么问题

如果你只开一个 Codex，让它改完代码就退出，普通终端已经够用。真正让人疲惫的是另一种场景：一个代理在写功能，一个代理在审查代码，一个窗格跑测试，另一个窗格开着开发服务器；有的任务完成了，有的正在等授权，有的仍在输出日志。窗口一多，你就会不断切换、刷新和确认“它到底跑完没有”。

本文继续讲 Herdr TUI，当前官网另有 Herdr app 入口，两者的安装和界面不要混用。

Herdr TUI 的定位是 agent multiplexer，可以理解为“面向 AI 编程代理的终端多路复用器”。它是一个二进制程序，不是网页控制台，也不是新的 AI 模型。Codex 等代理仍然是独立进程，使用各自的账号、配置、权限和上下文；Herdr 负责承载真实终端、保存会话布局、汇总代理状态，并让你在断开终端后重新接回原来的工作现场。官方强调它不要求 Herdr 账号、不依赖 Electron，也不收集遥测数据。产品介绍

这带来三个直接价值：

1. 看得见。 多个项目、窗格和代理集中在一个侧边栏里，Herdr 会显示 working、blocked、done、idle 等状态。
2. 不会因关掉客户端而停工。 正常 detach 只断开界面，后台 server 和窗格进程继续运行。
3. 可以从别处接管。 你可以从另一台电脑或手机 SSH 回去，重新打开同一个会话。

但要注意：Herdr 不是“自动项目经理”。它不会自动替你分解任务、判断结果或消除代码冲突。状态也只是信号：blocked 通常表示识别到批准或提问界面；unknown 表示当前无法可靠分类，不代表任务成功。最终仍要看输出、测试和代码差异。代理状态说明

二、建立正确的心智模型

Herdr 最容易被误解的地方，是把 workspace、tab、pane、agent 和 session 混在一起。建议按下面的层级理解：

• Server：后台进程，真正持有终端窗格和运行中的进程。
• Client：你眼前的 Herdr 界面，可以断开后再连接。
• Workspace：项目级容器，例如“官网”“iOS App”“数据分析”。
• Tab：一个 workspace 里的任务分组，例如“登录功能”或“发布检查”。
• Pane：真实终端窗格；shell、Codex、测试和开发服务器都运行在 pane 中。
• Agent：Herdr 在某个 pane 中识别到的 AI 编程代理。
• Named session：彼此独立的 Herdr server 命名空间。多数人先用 workspace 即可，只有需要完全隔离的 sockets、窗格和运行状态时，才需要多个 named sessions。

关键区别是：正常 detach 和 server 重启不是一回事。 Detach 后原进程还活着；如果执行 herdr server stop，原来的 shell、测试和代理进程都会结束。再次启动时，Herdr 可以恢复布局和工作目录，但普通进程不会凭空继续。只有安装了官方 integration、保存了有效原生会话引用的受支持代理，才可能恢复其对话会话。会话恢复说明

三、安装与首次启动

Linux 或 macOS 最直接的安装方式是：

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

如果你使用 Homebrew：

brew install herdr

官方也提供 mise、Nix 和手动下载方式。当前 Windows 原生版已正式支持。旧 preview 安装不会自动切到 stable，可按官方指南使用 herdr channel set stable；切换前保存工作并检查恢复方式。安装完成后先验证：

herdr --version
herdr status

如果提示找不到命令，先关闭并重开终端，让 PATH 变更生效；仍然失败时，再检查安装目录是否进入 PATH。不要在此时反复执行安装脚本，以免掩盖真正的路径问题。完整安装与更新差异见官方安装指南。

然后进入一个真实项目目录启动：

cd ~/Projects/my-project
herdr

Herdr 会启动或连接默认后台会话。第一次没有 workspace 时会自动创建一个。它支持鼠标操作：点击 pane、tab、workspace 或 agent 可以切换焦点，拖动分隔线调整尺寸，右键可以拆分 pane 或创建 tab。刚开始不需要先背快捷键。

键盘操作采用类似 tmux 的 prefix 模式。默认 prefix 是 ctrl+b：先按住 ctrl+b，松开，再按动作键。最常用的五组是：

随时按 ctrl+b，再按 ? 可以查看当前有效按键。这个设计避免 Herdr 抢走 shell、编辑器和代理本身常用的快捷键。键盘指南

四、把 Codex 接入 Herdr

先确认 Codex CLI 已经能在普通终端中运行。Herdr 不替你安装 Codex，也不接管 Codex 登录信息。进入 Herdr 后，在任意 pane 中直接执行：

codex

Herdr 能通过终端画面识别常见代理。为了让 Codex 的原生会话身份可用于 server 重启后的恢复，再安装官方 integration：

herdr integration install codex
herdr integration status

当前安装会写入 hooks.json，并在 config.toml 启用 [features] hooks = true；还会清理已弃用的顶层 codex_hooks。升级后检查 integration 状态，不要手工重复叠加旧 hook。卸载 integration 不会撤销全部 config.toml 设置。当前 Codex integration

这里要把能力边界说准确：Codex integration 的主要作用是提供原生 session 引用，生命周期状态仍主要来自 Herdr 的 screen manifest 检测。也就是说，安装 integration 不等于 Herdr 获得了 Codex 的全部内部状态，更不等于自动恢复一定成功。integration 过旧时，可以重新执行安装命令更新。Integration 说明

五、照着做：搭建一个四窗格开发现场

假设你要给网站增加一个登录功能，可以创建一个 workspace“官网”，再创建一个 tab“登录功能”，拆成四个 pane：

1. 实现 pane：启动 Codex，让它只负责阅读需求、修改登录相关代码并运行局部检查。
2. 审查 pane：启动另一个代理，明确要求它只读检查 diff、权限边界和错误处理，不直接改文件。
3. 测试 pane：运行单元测试、类型检查或端到端测试，不启动 AI 代理也完全可以。
4. 服务 pane：运行开发服务器并保留请求日志。

给每个代理的任务必须有清晰边界。例如实现代理可以收到：

只修改登录功能涉及的文件。先阅读现有认证逻辑，再实现需求；
不要改部署配置，不要提交 Git；完成后运行类型检查并汇报修改文件。

审查代理则收到：

只做只读审查。检查当前 diff 的身份验证、权限绕过、错误提示和测试覆盖；
按严重程度列出问题，不要修改文件。

这种分工比“开四个代理一起想办法”可靠得多。多个写入型代理同时操作同一个工作目录，依然可能覆盖文件或制造难以理解的中间状态。需要并行写代码时，应给不同任务使用不同 Git worktree 或不同 checkout，完成后再由一个明确负责人合并。Herdr 提供的是运行和观察秩序，不是文件级并发锁。

你也可以从命令行读取和控制代理，适合脚本化协作：

herdr agent list
herdr agent read <代理名或pane-id> --lines 80
herdr agent prompt <代理名或pane-id> "请汇报当前进度" --wait
herdr agent wait <代理名或pane-id> --until done --timeout 600000

多数 CLI 命令返回 JSON，适合确定性自动化。但 agent prompt 会向真实代理发送输入，使用前要确认目标名称或 pane ID，避免把指令发给错误任务。CLI 参考

六、离开电脑后继续运行

本地工作时，按 ctrl+b q detach。此时可以关闭终端窗口，后台 server、代理、测试和开发服务继续运行。回来后执行：

herdr

如果代码和代理运行在远程服务器，有两条路线。

最简单的是先 SSH，再在服务器上启动 Herdr：

ssh you@server
herdr

这种方式适合手机 SSH 客户端，也最接近 tmux 的使用习惯。另一种是在本机直接让 Herdr 通过 SSH 连接远端：

herdr --remote workbox
# 或
herdr --remote ssh://you@server:2222

此时本机 Herdr 是薄客户端，远端 server 持有进程。它还能桥接部分本地桌面能力，例如把本地剪贴板图片复制到远端临时文件后粘贴路径。首次配置远端时，先确保普通 ssh workbox 能成功；如果密钥带口令而当前环境不能弹出提示，先把密钥载入 ssh-agent，再连接 Herdr。

不要把远程 attach 写成“云同步”。代码、凭据和代理进程仍然留在你连接的那台机器上，Herdr 只是通过 SSH 传输界面和输入。远程使用指南

七、配置提醒和恢复策略

先用下面的命令查看完整默认配置，再只覆盖自己理解的项目：

herdr --default-config

如果你同时跑多个长任务，建议打开后台通知：

[ui.toast]
delivery = "herdr"
delay_seconds = 1

[ui.toast.herdr]
position = "bottom-right"

delivery 还可以设为 terminal、system 或 off。Herdr 默认不会为当前活动 tab 弹出完成提醒，避免重复干扰。声音提醒由本地 client 播放，也可以按代理类型单独关闭。配置指南

关于恢复，建议遵守三条规则：

• 日常离开只 detach，不要执行 server stop。
• 长任务开始前，确认代码已落盘、重要命令可重复执行，不把终端画面当唯一记录。
• experimental.pane_history 默认关闭是有原因的：保存的 pane 内容可能包含 token、提示词和命令输出。除非理解风险，否则不要为了“看起来能恢复”而打开它。

八、常见问题与排查顺序

1. 侧边栏没有识别到 Codex。 先确认 Codex 确实运行在 Herdr pane 中，而不是外部终端；再执行 herdr integration status。即使暂时不能识别丰富状态，终端进程仍可正常使用。

2. 状态一直是 blocked。 切换到该 pane，检查是否在等待权限确认、问题回答或登录。不要只从状态颜色推断失败。

3. 重新启动后进程没继续。 检查自己是 detach 还是停止了 server。完整 server 重启会终止普通进程；布局恢复、画面历史和代理原生会话恢复是三种不同机制。

4. SSH 远程连接失败。 先运行普通 ssh <host>，确认地址、端口、用户名、密钥和 host key 都正确，再运行 herdr --remote <host>。不要先归因于 Herdr。

5. 快捷键冲突。 先用鼠标完成操作，再通过 herdr --default-config 查看按键名并修改 [keys]。终端快捷键要穿过操作系统、外层终端和 pane 内程序三层，某些组合可能先被其中一层截获。

6. 想在 Herdr 里面再启动 Herdr。 嵌套运行默认不允许。多数情况下应该新建 workspace 或 named session，而不是创建多层 multiplexer。

九、十分钟上手清单

最后把整个流程压缩成一次可执行练习：

1. 安装后运行 herdr --version；
2. 进入一个 Git 项目，执行 herdr；
3. 新建 workspace 和 tab；
4. 拆成两个 pane，一个运行 codex，一个运行测试；
5. 执行 herdr integration install codex 并检查状态；
6. 给 Codex 一个边界清晰、可验收的小任务；
7. 按 ctrl+b q detach；
8. 重新执行 herdr，确认任务和终端仍在；
9. 查看输出、测试和 diff，而不是只看 done；
10. 确认不再需要进程后，才执行 herdr server stop。

Herdr 真正的价值不是让代理变聪明，而是让多个代理的运行现场变得可见、可返回、可管理。先把一个项目、两个 pane 和一次 detach 跑通，再逐步增加 workspace、远程连接与自动化命令。这样得到的是稳定的工作系统，而不是更复杂的终端迷宫。