herdrdev/herdr · 上手攻略

仓库：herdrdev/herdr
链接：https://github.com/herdrdev/herdr
分类：agent · developer-tool · infrastructure
作者：Tom
更新：2026-09-28

一、是什么

Herdr 是一个用 Rust 编写的终端多路复用器（terminal multiplexer），定位是「coding agent 的运行时」。它将 Claude Code、Codex、Cursor、OpenCode、Grok 等 coding agent 的终端管理起来，提供跨机器会话保持、agent 状态追踪（working/blocked/idle/done）、多机器统一视图、agent 间相互协调等能力。

它的核心使用体验与 tmux 类似（prefix+b 快捷键、分屏、新建 tab），但增加了： - detach 后 agent 继续运行（SSH 断开或关闭终端窗口不影响） - 机器重启后恢复工作区布局（部分 agent 会话可恢复，原始进程不保留） - 多台机器统一管理（本地 + 多台 SSH 机器在同一窗口） - agent 原生 API（agent 可通过 CLI / Socket API 控制 Herdr 本身）

一句话：Herdr = tmux + session persistence + multi-machine + agent awareness。

二、解决什么问题

用 coding agent 跑长任务时，常见痛点：

SSH 断开 = 工作丢失——agent 在远程机器跑着，一旦网络抖动或本地关机，一切重来
多个机器上的 agent 无法统一管理——需要分别 SSH 到不同机器查看状态，效率低
不知道 agent 跑到哪了——需要主动去翻日志才知道是 blocked、idle 还是完成
agent 之间无法互相等待/通信——多个 agent 协作时，一个 agent 不知道另一个是否已完成
tmux 操作复杂——新用户学习曲线陡峭，与日常 IDE/编辑器操作习惯不同

Herdr 在这些场景下补了 tmux 的短板，同时原生支持 agent 协作。

三、快速安装

安装方式

# 官方安装脚本（Linux/macOS）
curl -fsSL https://herdr.dev/install.sh | sh

# Homebrew
brew install herdr

# mise
mise use -g herdr

# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

⚠️ Windows 端点保护版需要单独文档：herdr.dev/docs/windows-beta/

启动

# 在项目目录启动
herdr

# 或指定工作区
herdr --workspace my-project

Herdr 会自动启动或附加到一个默认后台 session，无需手动管理 socket。

四、核心用法

基本操作

# 启动 Herdr（进入项目目录）
herdr

# 在新 pane 中运行 coding agent
claude
# 或
codex
# 或
pi
# 或
opencode

# detach（断开连接，agent 继续运行）
# 按 Ctrl+b 然后按 q
# 等价于 tmux 的 detach

# 重新附加
herdr

键盘快捷键（tmux 风格）

快捷键	功能
`Ctrl+b, v`	垂直分屏
`Ctrl+b, -`	水平分屏
`Ctrl+b, c`	新建 tab
`Ctrl+b, n / p`	切换下一个 / 上一个 tab
`Ctrl+b, w`	工作区导航
`Ctrl+b, shift+n`	新建工作区
`Ctrl+b, q`	detach（断开连接，agent 继续运行）
`Ctrl+b, ?`	显示所有快捷键
`Ctrl+b, [`	进入复制模式

多机器管理

# 连接远程机器（需先在远程机器上安装 Herdr）
# 在本地 Herdr 中：
herdr connect user@remote-host

# 远程机器会在 sidebar 中出现，可统一管理多个机器的 pane

Agent Skill 安装（让 agent 控制 Herdr）

Herdr 提供一个标准化的 skill 文件，使 coding agent 可以从内部控制 Herdr：

# 通过 npx skills 安装（全局）
npx skills add herdrdev/herdr --skill herdr -g

# 安装后，在 Herdr pane 中运行 agent
herdr
claude

# agent 内部可通过 HERDR_ENV=1 判断是否在 Herdr 环境中
# agent 可用命令：split pane / read output / wait another agent / start sibling agents

详细 agent skill 文档：herdr.dev/docs/agent-skill/

停止服务

# 停止 Herdr 服务并结束所有 pane
herdr server stop

五、典型适用场景

场景	为什么用 Herdr
远程服务器上跑长任务	SSH 断开后 agent 继续运行，不丢进度
多机器开发	本地 + 2~3 台远程机器在同一窗口，统一管理
Coding agent 协作	一个 agent 可以触发另一个，等另一个真正 blocked 再切走
多项目并行	每个项目一个 workspace，sidebar 一目了然
从手机/Tablet 接入工作	Herdr reattach 到现有 session，手机上查看进度
插件扩展	Herdr 支持插件系统，可扩展 pane 和工作流

六、坑与注意

⚠️ Windows 仍在 beta

Windows 端点保护版功能可能与 macOS/Linux 有差异，建议生产环境优先使用 Linux/macOS。

⚠️ session state 恢复有前提

文档明确指出：服务器/机器重启后，原始进程不保留，但工作区布局（workspace layout）可以恢复。需要真正的进程持久化，应配合 systemd 等进程管理器。

⚠️ agent skill 需要 HERDR_ENV=1

如果 agent 在 Herdr pane 外运行（没有设置 HERDR_ENV=1），skill 文件包含 guardrail 会让 agent 停止并提示「not running inside a Herdr pane」。这是安全设计，不要尝试绕过。

⚠️ 不支持 agent 代码执行后自动恢复

如果 agent 在执行过程中崩溃，原始进程不保留，需要 agent 自己实现 checkpoint/resume 逻辑（Herdr 只负责终端状态，不负责 agent 内部状态）。

⚠️ 快捷键与 tmux 相同，但 prefix 默认是 `Ctrl+b`

如果你已重度使用 tmux，Herdr 的 prefix 快捷键是冲突的，需要重新配置：

# 在配置文件中修改 prefix（herdr 配置文件路径见 herdr.dev/docs/configuration/）

⚠️ 安装脚本需要网络访问

curl -fsSL ... | sh 依赖网络访问下载二进制，闭网环境需要手动下载 release 包：

# 从 GitHub releases 手动下载
https://github.com/herdrdev/herdr/releases

⚠️ `herdr` 命令名与项目名「herdr」不完全一致

命令行工具名为 herdr（不是 herdrdev 或其他），项目名是 herdr，slug 计算为 herdrdev-herdr。

七、与同类对比

工具	特点	与 Herdr 对比
tmux	终端复用事实标准，插件丰富	Herdr 操作更直观，agent awareness 开箱即用；但 tmux 生态更成熟
screen	古老的 session 管理	Herdr 比 screen 更现代，支持多机器统一视图
tmuxp / tat	tmux session 配置管理	Herdr 原生 workspace 概念比配置管理更灵活
Zellij	Rust 编写的 tmux 替代	Zellij 侧重通用 terminal 多路复用，无 agent 协调能力
Devin（AI 平台）	云端 AI coding agent	Herdr 管理本地/远程实体机器，Devin 是云端黑盒
Cursor / Claude App	各自独立 agent 界面	Herdr 可以把这些 agent 的终端统一管理在一个窗口

八、一句话结论

Herdr 是 coding agent 时代的多路复用器标杆——如果你在多台机器上跑多个 coding agent、需要 SSH 断开后任务继续、或想让 agent 之间互相等待协调，它比 tmux 顺手得多；但如果你只需要基础的终端复用，tmux/screen 依然够用，Herdr 的额外能力需要你真的有这类场景。