中文快速入门 · herdr 0.9.5
herdr 30 分钟上手:给 AI 编程 agent 的终端工作台
同时开着三五个 Claude Code、Codex,总有一个卡在“要不要批准”上没人管?herdr 就是为这件事做的。这篇只讲最常用的 80%,读完能用起来,用到的命令都在本机跑过。
- herdr 是一个“认识 AI agent 的 tmux”:后台常驻、分屏分标签页,额外能看出每个窗格里的 agent 是在干活、在等你批准,还是干完了。
- 装好后在项目目录敲
herdr,在窗格里照常运行claude/codex。左侧边栏会告诉你哪个项目需要你。 - 前缀键是 ctrl+b。先记五个:c 新标签页、v / - 分屏、h j k l 切窗格、w 切工作区、q 脱离。不会就按 ctrl+b ?。
- 关掉终端,agent 照跑;再敲
herdr回来。(电脑合盖睡眠时一样会停,长时间无人值守要放到服务器上。) - 真正拉开差距的是:给 agent 装上 herdr 技能,让 Claude Code 自己开窗格、启动 Codex 去审方案、等它审完再继续。
开始之前 1 分钟
这篇写给谁:会用终端、在用(或打算用)Claude Code、Codex 这类命令行 AI 编程工具的工程师。不需要用过 tmux。
学完能做到:一个窗口里管好多个项目、多个 agent;关掉终端窗口 agent 也不停;一眼看出谁卡住了;会让一个 agent 去调度另一个 agent。
2026 年 10 月起,herdr.dev 首页宣传的是一个新的桌面 App(底层是 herdr-core,命令行工具叫 hc,从 releases.herdr.dev/app 安装)。官方 FAQ 原话:它和原来的终端版是“两个独立程序,不共享 agent”。
本文讲的是原来的终端版 Herdr TUI(GitHub 仓库 herdrdev/herdr,命令就叫 herdr),文档入口在 herdr.dev/tui,还有官方中文文档。别照着首页的 hc 命令操作。
30 分钟路线
| 时间 | 内容 | 做完你能 |
|---|---|---|
| 0–4′ | 是什么、安装 | 启动 herdr,看懂界面三块区域 |
| 4–8′ | 概念和状态 | 说清工作区 / 标签页 / 窗格的关系,读懂状态灯 |
| 8–14′ | 动手练快捷键 | 不碰鼠标完成分屏、切换、放大、脱离 |
| 14–20′ | 后台常驻、多项目、通知 | 知道什么情况下活会丢,开好通知 |
| 20–25′ | agent 指挥 agent | 让 Claude Code 叫 Codex 审方案 |
| 25–30′ | 远程、踩坑、速查 | 避开新手最常掉的坑 |
这篇不讲的 20%:插件开发、主题和侧边栏自定义、原始 socket 协议、Windows 细节、自定义 agent 识别规则。用到时再查官方文档。
herdr 是什么,解决什么问题 3 分钟
目标:知道它和普通终端、和 tmux 差在哪,决定值不值得学。
官方一句话:Terminal workspace manager for AI coding agents(给 AI 编程 agent 用的终端工作区管理器)。拆开说就是两件事:
- 它是一个终端复用器(multiplexer,就是 tmux / zellij 那一类):一个后台服务进程替你“养着”所有终端,你的终端窗口只是一个显示器。窗口关了、SSH 断了,里面的程序照跑,回来接上就行。
- 它认识 agent:能识别窗格里跑的是 Claude Code、Codex、OpenCode 等 20 多种工具,并把每个 agent 标成“在干活 / 等你批准 / 干完了”,在侧边栏按项目汇总。还提供命令行接口,让 agent 之间能互相开窗格、发任务、等结果。
src/server/autodetect.rs。和 tmux 比
| tmux | herdr | |
|---|---|---|
| 后台常驻、断线不丢 | ✔ | ✔(模型一样,前缀键也是 ctrl+b) |
| 鼠标 | 要配置 | 默认就能点、拖、右键、选中即复制 |
| 知道 agent 在干嘛 | 不知道,得一个个切过去看 | 侧边栏亮灯,按项目汇总,卡住的一眼可见 |
| 让 agent 调度 agent | 只能 send-keys 硬塞 | 有“等它状态变成空闲 / 卡住”的命令(靠读屏推断,不是 100% 准) |
| Git worktree、多台机器 | 靠脚本 | 内置 |
| 成熟度 | 二十年老将 | 0.x 版本,更新很快,GitHub 上有 500 多个未关闭 issue |
一些背景数据(2026-11-22 查):Rust 写的单文件程序,Apache-2.0 开源;GitHub 约 5.2 万 star;2026 年 3 月第一个版本,到 10 月已发 61 个正式版;8 月加入 Y Combinator,9 月拿了 600 万美元种子轮(官方博客)。主要作者是 Can Celik(GitHub ogulcancelik)。
同类工具(社区说法,非官方对比):cmux 是 macOS 原生 App,自带可编程浏览器,但只能在 Mac 上用;claude-squad 更轻,基于 tmux,一个任务一个 worktree,没有 API;Conductor 是图形界面,Mac 专用、闭源;zellij 开箱体验好,但不懂 agent 状态。Thoughtworks 技术雷达 2026-11 期把 herdr 放在“评估(Assess)”环。
安装与第一次启动 3 分钟
目标:装好、启动、看懂界面。
# macOS / Linux 任选一种
brew install herdr
curl -fsSL https://herdr.dev/install.sh | sh
# 确认版本
herdr --version
Windows 用 PowerShell:powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"(Windows 版功能有差异,见官方 Windows 页)。
然后进入你的项目目录,启动:
cd ~/code/my-project
herdr
第一次会有引导:选通知方式、安装 agent 集成。建议把你用的 agent 的集成都装上(也可以之后按 ctrl+b s 进设置里装,或用命令 herdr integration install claude)。集成的作用见第 5 节。
界面三块
- 左侧边栏上半:Spaces(工作区)。一个项目一行,显示 git 分支和该项目里最紧急的 agent 状态。
- 左侧边栏下半:Agents。所有工作区里的 agent 列在一起,谁卡住了看这里。
- 右边主区:顶部是标签页,下面是分好的窗格。
在窗格里照常运行 claude、codex 等,不用加任何参数,herdr 会自动识别。
① 在 herdr 的窗格里不要再敲 herdr:默认会被拦下(官方有意这样设计;确实需要时可设 [experimental] allow_nested = true)。
② herdr server(不带子命令)不是看帮助,它会尝试再起一个后台服务。看帮助用 herdr --help;看某组命令的用法,直接敲组名,如 herdr pane。
四个概念,五种状态 4 分钟
目标:脑子里有一张图,后面所有操作都是在这张图上做加减。
w1、标签页 w1:t1、窗格 w1:p2。依据:官方 concepts 文档,ID 格式本机实测。| 概念 | 是什么 | 怎么用 |
|---|---|---|
| 工作区 Workspace | 项目级容器(侧边栏叫 Space) | 一个仓库一个。这是 herdr 最核心的组织方式 |
| 标签页 Tab | 工作区里的一种布局 | 按用途分:写代码的 agent 一页,日志和服务一页 |
| 窗格 Pane | 一个真实终端 | 向右或向下切分;关客户端也不会停 |
| Agent | 窗格里被识别出来的 AI 工具 | 自动识别,不用你登记 |
| 会话 Session | 一个独立的后台服务 | 官方建议“先用工作区分项目”,只有要完全隔离时才开命名会话 |
五种状态:侧边栏的灯是什么意思
| 状态 | 意思 | 你该做什么 |
|---|---|---|
| blocked | 在等你:批准命令、回答问题、做选择 | 优先处理,不处理它就一直停着 |
| working | 正在干活 | 不用管 |
| done | 干完了,你还没看过 | 去看结果、给下一步 |
| idle | 空闲,你已经看过了 | 随时可以派新活 |
| unknown | 认出了 agent 但判断不了状态 | 自己切过去看 |
颜色对应关系来自源码 src/client/shell.rs:黄 = working、红 = blocked、青 = done、绿 = idle、灰 = unknown,具体色值随主题变化(官方文档没写,源码和 lustoykov 的教学视频说法一致)。分不清颜色的话,可在配置里设 ui.status_indicators = "symbols",改用不同形状。
done 和 idle 的区别只在“你看没看过”(源码里就是 (Idle, 没看过) → Done)。每个终端窗口各记各的:在 A 窗口看过,B 窗口里的 done 不会消失。
herdr 判断 blocked 是故意从严的:只有屏幕上出现它认识的批准或提问界面,才会标 blocked。agent 弹出一个新样式的对话框时,herdr 可能把它当成 idle。官方文档原话:“idle status is not authorization to approve an action”(idle 不代表可以替它批准)。第 8 节有我实测碰到的例子。
动手:先用鼠标,再记五个键 6 分钟
目标:不查表完成分屏、切换、放大、脱离。
鼠标就能干完所有事
官方建议新手先用鼠标:点窗格、标签页、工作区、agent 就是切过去;拖分隔线调大小;右键出菜单(分屏、新建标签页、worktree 等);拖选文字松手即复制,不用按 Ctrl+C;按住 Ctrl 点链接直接打开。
前缀键是什么
你在窗格里敲的键默认都发给窗格里的程序(比如 Claude Code)。要给 herdr 本身下命令,先按一下前缀键 ctrl+b,松开,再按动作键。下文 prefix+c 的意思就是:按 ctrl+b,松开,再按 c。
先记这五个(官方推荐)
| 做什么 | 按键 | 备注 |
|---|---|---|
| 新建标签页 | ctrl+b c | 默认会问你起个名字 |
| 向右 / 向下分屏 | ctrl+b v / ctrl+b - | v 像一条竖线,- 像一条横线 |
| 在窗格间移动 | ctrl+b hjkl | 左 下 上 右(vim 方向) |
| 工作区导航 | ctrl+b w | 上下键选工作区,回车确认,Esc 退出 |
| 脱离(detach) | ctrl+b q | 界面退出,所有程序继续跑 |
再加五个,够用一个月
| 做什么 | 按键 |
|---|---|
| 看所有快捷键(按 / 搜索) | ctrl+b ? |
| 跳到任意 agent(在列表里按 b 只看 blocked) | ctrl+b g |
| 放大 / 还原当前窗格 | ctrl+b z |
| 关闭当前窗格 | ctrl+b x |
| 新建工作区 | ctrl+b shift+n |
完整列表见文末速查卡。注意:herdr --default-config 打印的配置模板漏了复制模式(ctrl+b [)和交换窗格(ctrl+b shift+h/j/k/l),源码里这两个是有默认键的。以 ctrl+b ? 显示的为准。
- 在项目目录运行
herdr。 - ctrl+b v 向右分屏。左边运行
claude,右边运行git status。 - ctrl+b - 把右边再上下切一刀,下面跑测试或开发服务器。
- 用 ctrl+b h / l 在左右之间跳,ctrl+b z 放大 Claude 那一格再还原。
- ctrl+b c 新开一个叫
logs的标签页,ctrl+b p / n 来回切。 - 给 Claude 派个要跑一会儿的活,然后 ctrl+b q 脱离,直接关掉终端窗口。
- 新开一个终端,敲
herdr。布局、Claude 的进度都还在。
想免前缀?(可选)
官方调研了主流终端后推荐用 ctrl+alt 组合做直接快捷键(几乎没被占用,也不受 macOS Option 键合成特殊字符的影响)。在 ~/.config/herdr/config.toml 里一个动作可以绑多个键:
[keys]
focus_pane_left = ["prefix+h", "ctrl+alt+h"]
focus_pane_right = ["prefix+l", "ctrl+alt+l"]
new_tab = ["prefix+c", "ctrl+alt+c"]
split_vertical = ["prefix+v", "ctrl+alt+d"]
zoom = ["prefix+z", "ctrl+alt+z"]
# 改前缀:prefix = "ctrl+a"
改完按 ctrl+b shift+r 或运行 herdr server reload-config 生效。改乱了用 herdr config reset-keys 恢复(会先备份)。注意避开系统已占用的组合:KDE 下 ctrl+alt+l 是锁屏(上面示例里的这个键要换掉),Ubuntu / Fedora 下 ctrl+alt+t 是开终端,GNOME 等环境下 ctrl+alt+方向键 是切桌面。
关掉终端,活还在跑 3 分钟
目标:分清“脱离”和“停止服务”,知道哪种情况会丢东西。
| 操作 | 命令 | 结果 |
|---|---|---|
| 脱离 | ctrl+b q 或直接关窗口 | 只有界面退出,所有程序照跑 |
| 接回来 | herdr | 回到原样 |
| 看服务状态 | herdr status | 客户端和服务端版本、是否需要重启 |
| 停掉一切 | herdr server stop | 所有窗格里的进程都会被结束(只停默认会话) |
| 停掉某个命名会话 | herdr session stop 名字 | 用过 herdr --session 的话,要单独停 |
什么能活下来
| 情况 | 进程还在 | 布局回来 | agent 对话接得上 |
|---|---|---|---|
| 脱离后再接上 | ✔ | ✔ | ✔(进程根本没停) |
| 服务重启 / 电脑重启 | ✘ | ✔ | 只有装了集成的 agent 能接上 |
| 升级 herdr | 旧服务继续跑 | 重启后 ✔ | 同上 |
这就是第 2 节建议装集成的原因:集成会把 agent 的会话 ID 报给 herdr。服务重启后,herdr 在原来的窗格里自动执行 claude --resume <id> 或 codex resume <id>,把对话接回来。
装集成会改你的全局配置:对 Claude Code,0.9.5 会在 ~/.claude/settings.json 里加一个 SessionStart 钩子,指向 ~/.claude/hooks/herdr-agent-state.sh(源码 src/integration/claude_settings.rs,本机 settings.json 实测也只有这一条)。脚本在 herdr 外面运行时直接退出,没有副作用。社区评测里说“写了 4 个钩子”的是旧版本的行为;重装集成会顺手清掉旧钩子。Claude Code 和 Codex 的状态仍然靠读屏幕判断,集成只管会话恢复。
herdr integration status # 看装了哪些、是否过期
herdr integration install claude # 也支持 codex、opencode、pi 等
升级 herdr(brew upgrade herdr)不会替换正在运行的后台服务,这样做是为了不杀掉你的进程。所以升级后界面是新的,服务端功能还是旧的。用 herdr status 看 server_binary_stale。想用新功能,挑个没活在跑的时候 herdr server stop 再 herdr。另外,herdr update 只适用于官方脚本安装的情况;用 brew 装的就用 brew 升级。
多项目并行 3 分钟
目标:同时推进几个项目,不乱、不漏。
一个项目一个工作区
ctrl+b shift+n 新建工作区(新窗格默认沿用当前目录,进去 cd 到别的项目即可)。ctrl+b shift+w 改名。侧边栏会把每个工作区里最紧急的状态顶上来:哪个项目亮红灯,就去哪个。
agent 一多,用 ctrl+b g 打开“跳转”列表:每个 agent 一行,按 / 搜名字、分支、路径;按 b / w / i / d 只看 blocked / working / idle / done,a 看全部,回车跳过去。
同一个仓库开几个 agent:用 worktree
两个 agent 改同一个目录会互相踩文件。Git 的 worktree(工作树)可以把同一个仓库的不同分支检出到不同目录。herdr 内置了这个功能:
- 在侧边栏选中工作区,按 ctrl+b shift+g,输入分支名。分支存在就检出,不存在就新建。
- 检出的目录默认在
~/.herdr/worktrees/<仓库>/<分支名转成的目录名>(feat/login不会变成两层目录),作为一个新工作区,挂在原工作区下面。 - 每个 worktree 工作区里各开一个 agent,各干各的。
- 删除检出(右键菜单里的 Delete worktree checkout)会调用
git worktree remove,有未提交改动会再问一次;分支永远不删。
herdr worktree create --branch feat/login --base main --label login
herdr worktree list
通知:默认是关的 1 分钟
很多人以为 agent 卡住时 herdr 会弹通知,其实弹窗通知默认关闭(ui.toast.delivery = "off"),只有声音默认开(后台工作区的 agent 状态变化时响一下)。想要弹窗,在 ~/.config/herdr/config.toml 加:
[ui.toast]
delivery = "system" # herdr=界面内提示 terminal=让外层终端发通知(SSH 也能用) system=系统通知 off=关
macOS 用 system 时建议先 brew install terminal-notifier,否则会退回 osascript,通知显示成“脚本编辑器”,点了也跳不回终端。通知还显示在屏幕上时,按 ctrl+b o 直接跳到发通知的那个窗格;错过了就用 ctrl+b g 再按 b 只看 blocked。当前标签页里的事件不会弹通知。
杀手锏:让 agent 指挥 agent 5 分钟
目标:让 Claude Code 自己开窗格、启动 Codex 审方案、等审完再继续。这是 herdr 和 tmux 拉开差距的地方。
思路很简单:herdr 的所有操作都有命令行版本,输出 JSON。agent 本来就会跑命令,所以只要它知道这些命令,就能像你一样操作 herdr。为什么不在一个工具里切换模型?因为每家的 agent 工具对自家模型适配得最好(Claude Code 配 Claude、Codex 配 GPT),让它们各自在自己的工具里干活、互相传话,能把每个组合的长处都用上。
方式一:给 agent 装上技能,用大白话指挥(推荐)
# 给支持 skills 的 agent(Claude Code 等)全局安装 herdr 技能
npx skills add herdrdev/herdr --skill herdr -g
# 或者让 agent 自己读本机版本匹配的说明
herdr --skill
npx skills add 装的是 GitHub 主分支上最新的技能文件,可能比你本机的 herdr 新,里面会提到本机版本还没有的命令。两者对不上时,以 herdr --skill 打印的为准(它和本机程序版本一致)。
然后在 herdr 的窗格里启动 Claude Code(技能会先检查环境变量 HERDR_ENV=1,不在 herdr 里它会拒绝操作),直接说:
用 herdr 在右边开一个窗格,启动 codex,起名 reviewer,
让它审核 docs/plan.md,只提意见不改代码。
等它审完,把意见逐条读回来,你修改方案后再发给它复审,直到它说通过。
Claude 会自己去跑类似下面“方式二”里的那些命令。你在侧边栏能看到新 agent 冒出来、状态在 working 和 idle 之间切换。
方式二:自己写脚本(看懂原理)
三层命令,从粗到细:布局(workspace / tab / pane 的增删)→ 窗格(跑命令、读输出、等输出)→ agent(按名字启动、派活、等状态)。下面每一条我都在一个隔离的测试会话里跑过:
# 0. 确认自己在 herdr 窗格里
test "$HERDR_ENV" = 1 && echo "在 herdr 里,当前窗格 $HERDR_PANE_ID"
# 1. 向右开个窗格,不抢焦点;新窗格 ID 从返回的 JSON 里取,别猜
P=$(herdr pane split --current --direction right --no-focus | jq -r '.result.pane.pane_id')
# 2. 启动审核员。这里用便宜的 Claude Haiku 演示(我实测就用的它);
# 换成 Codex 写 --kind codex。-- 后面是传给 agent 自己的参数
herdr agent start reviewer --kind claude --pane "$P" -- --model haiku
# 3. 派活,并等到它干完(idle/done)或卡住(blocked)
herdr agent prompt reviewer "审核 docs/plan.md,列出问题" --wait --timeout 300000
# 4. 读结果;看状态;看 herdr 为什么判成这个状态
herdr agent read reviewer --source recent-unwrapped --lines 120
herdr agent get reviewer
herdr agent explain reviewer
跑普通命令(测试、服务器)用窗格命令:
herdr pane run "$P" 'npm test; echo "EXIT=$?"'
herdr pane wait-output "$P" --regex '^EXIT=[0-9]+$' --timeout 120000
herdr pane read "$P" --source recent-unwrapped --lines 80
为什么不直接等 PASS / FAIL:wait-output 会先检查屏幕上已有的内容,上一轮测试留下的结果会让它立刻返回;各测试框架的输出格式也不一样。让命令最后打印一个自己定的结束标记(顺便带上退出码)最稳。^ 锚定行首,而你敲进去的那行命令以提示符开头,不会被误匹配。复用同一个窗格时,先 clear 一下。
wait-output --match立刻返回:我执行pane run p2 "echo hello-from-herdr; sleep 1; echo DONE-MARK",再wait-output p2 --match DONE-MARK,它立刻就返回了。匹配到的是屏幕上你敲进去的那行命令(里面也有 DONE-MARK),命令本身还没跑完。第二次我改成pane run p2 "sleep 3; echo RESULT=\$((40+2))"+wait-output p2 --regex "^RESULT=42":发出去的命令行里只有$((40+2)),没有42(\$的反斜杠不能省,否则你自己的 shell 会先把它算成 42),而且以提示符开头,所以只会匹配真正的输出行,实测等足了 3 秒。经验:结束标记要写成只有输出里才会出现的样子,再用^锚定行首。- 第一次进目录时的“信任此文件夹”对话框:
agent start返回agent_not_ready,状态是blocked。这是正确行为。先agent read reviewer --source visible看清选项。我在 Claude Code 2.1.321 上看到第一项是No, exit,第二项才是Yes, I trust this folder,所以发的是agent send-keys reviewer down enter。选项顺序可能随版本变化,别把按键写死在脚本里,每次都先看屏幕。 - prompt 被一个没认出来的弹窗吞掉:Claude Code 弹出一个“Teach auto mode…”提示框,herdr 仍然报
idle。agent prompt --wait2 秒就“成功”返回了,屏幕上却没有任何回答;按esc关掉弹窗再重发才正常。原因是--wait只要看到对方状态动过一次(短暂的 working 或 blocked)、再回到空闲就会返回。它跟踪的是状态变化,不保证你这一条 prompt 真的被执行了。完全没动静时它会返回agent_prompt_stalled。GitHub 上还有更严重的 issue #6081:prompt 被当成答案提交进了 Claude 的提问框。
所以自动化的规矩:
- 派活前先
agent read看一眼屏幕;派完再agent read确认它真的在回答你这一条。 --wait一定加--timeout(不加会无限等)。超时不代表没发出去,别盲目重发。- 检查退出码:出错时 JSON 写在 stderr、退出码 1(参数写错是 2)。按
code字段分别处理:agent_blocked(对方卡在批准框,herdr 一个字都没发)、agent_prompt_stalled(发了但没看到动静)、timeout。 - 脚本里把 done 和 idle 都当成“可以派活”。“看过没有”记在服务端,
agent read不算看过,别拿它们做判断。 - 长回复读不全时,让对方把结果写进文件,你再去读文件。
值得照抄的分工模式
下面是 Hacker News 用户和几位教学视频作者的真实用法,只挑了说法比较一致的:
- 一个项目一个工作区,标签页按角色分:实现者、审查者、
npm run dev、日志各占一个。开发服务器和测试 watcher 放在 agent 窗格外面,不要让 agent 在自己会话里跑长命令。 - 让主 agent 自己搭班子:“新建一个 workers 标签页,2×2 四个窗格,每格一个 agent,给它们和你自己都起好名字”。之后在任何窗格里都能用
herdr agent prompt lead "..."给主 agent 发消息。 - 绕开单家额度上限:Claude Code 自带的 subagent 只能用 Claude;用 herdr 派活,哪家 CLI 还有额度就派给哪家。
- 写方案 / 审方案 / 执行 分给三家:强模型写方案,另一家模型审(视角不同,更容易挑出毛病),便宜模型执行,最后强模型验收。
- 开发和测试分开:一个窗格跑 agent,另一个窗格用
pane run+wait-output跑测试,agent 改完自己去等测试结果。 - 补能力短板:执行模型看不了图,就让一个能看图的 agent 先把截图描述成文字,再转交给它。
要不要每个 agent 一个 worktree?有人十几个 worktree 把硬盘吃满,干脆让所有 agent 都在 main 上干活、靠 herdr 发消息协调;也有人坚持“每个 worktree 只有一个 agent 能写代码,其余只写文档和方案”。我的建议:会改同一批文件的 agent 必须分开 worktree;只读或者范围完全不重叠的,可以共用一个目录。
同时开几个?社区里有人说超过 3 个就管不过来,也有人练到 6–7 个,还有人同时开 10 个以上之后觉得太累,干脆自己写了工具。瓶颈很快会从工具变成你的注意力。先从 2–3 个开始。另外,herdr 不替你提交代码,agent 改完记得 commit。
远程与手机 1 分钟
| 场景 | 怎么做 |
|---|---|
| agent 跑在服务器上 | ssh 服务器 后运行 herdr,和 tmux 一样。断线不丢,手机 SSH 客户端也能接(界面会适配窄屏) |
| 界面在本地画,进程在远端跑 | herdr --remote 服务器:用本地的主题和快捷键,还能把本地剪贴板里的图片粘过去 |
| 本地 + 几台服务器,在同一个窗口里看 | herdr machine add you@server --label server:侧边栏合并显示所有机器的 agent,一台断线不影响别的 |
社区经验:日常远程优先用 herdr --remote。SSH 上去再开 herdr 时整个界面要从服务器传回来,网络一般时打字会有明显延迟(Alejandro AO 的教学视频)。手机上可以用 Termius、Blink、Moshi 这类 SSH / Mosh 客户端,终端宽度不超过 64 列时,herdr 会自动切成手机单栏布局;觉得挤可以按 ctrl+b b 收起侧边栏。注意:官方新出的手机 App 连的是新桌面版,连不上 TUI。
认证完全走 OpenSSH,herdr 不保存密码或私钥;连不上时先单独 ssh 服务器 确认通了。脚本要控制远端机器,加 --machine,后面填保存时的 label(不能填 SSH 地址):herdr --machine server agent list。注意不同机器的 ID 可能重复(两台都有 w1:p1)。
踩坑清单
来自官方故障排查文档、GitHub issue 和本文的实测,按碰到的概率排序:
| 症状 | 原因和解决 |
|---|---|
| agent 明明在等批准,侧边栏却是 idle | blocked 判断从严,遇到新样式的对话框会漏判。重要的 agent 自己切过去看;herdr agent explain <名字> 能看到它命中了哪条规则。 |
| Claude 还在后台等任务,侧边栏却显示 done / idle,还反复弹“完成” | Claude Code 开着后台 monitor 时,前台输入框是空闲的,herdr 就按空闲算(issue #1217,0.9.5 仍能复现)。我实测时屏幕底部就有“1 monitor still running”,状态却是 idle。看到 done 别急着派新活,先看一眼。 |
在窗格里敲了 exit,agent 没了 | exit 是真的结束 shell 和里面的进程。想离开用 ctrl+b q,不要用 exit。 |
| 没收到任何通知 | 弹窗默认关闭,见第 7 节。 |
| 复制不到本机剪贴板 | herdr 靠外层终端的 OSC 52 写剪贴板,终端不支持时会静默失败(#2399);macOS 走 SSH 时可能复制到了远端剪贴板(#4833,未修)。换个支持 OSC 52 的终端(Ghostty、iTerm2、kitty、WezTerm 等),或者改用 herdr --remote。 |
| 内网或隐私敏感环境里发现 herdr 经常访问 herdr.dev | 它会定期拉取最新的 agent 识别规则并检查更新。不需要的话在配置的 [update] 段设 manifest_check = false、version_check = false。所以“完全不联网”的说法不对。 |
| 升级了,新功能却没有 | 旧的后台服务还在跑。herdr status 看一下,空闲时 herdr server stop && herdr。 |
| 重启电脑后 agent 对话没了 | 重启会结束进程。装集成后能自动 resume;屏幕历史默认不保存(可能含密钥),需要的话开 [experimental] pane_history = true。 |
| 窗格里开了 tmux,herdr 认不出 agent | herdr 只看到 tmux 进程。如果你的 shell 配置会自动进 tmux,加一个判断:[[ -z $TMUX && $HERDR_ENV != 1 ]] && tmux new -A -s main。 |
macOS 上钥匙串、本地网络权限、SSH_AUTH_SOCK 失效 | 后台服务是从 SSH 或后台任务里第一次启动的,继承了错误的系统上下文。在正常的图形终端里 herdr server stop 再 herdr。 |
| 中文输入法下前缀键没反应 | 0.9.5 已修复,先升级。还可以开 [experimental] switch_ascii_input_source_in_prefix = true(按前缀时临时切成英文输入)。 |
| 按一次回车 / Tab 触发两次 | 外层终端太旧(kitty < 0.33、Alacritty < 0.15、foot < 1.20),升级终端。 |
Option+方向键出现 ;3D ;3C | zsh 没绑定这些键:bindkey $'\e[1;3D' backward-word、bindkey $'\e[1;3C' forward-word。 |
| 复制模式里按 ctrl+b 想往上翻页 | ctrl+b 在那里仍然是前缀键。用 PageUp 或 ctrl+u。 |
排查三板斧:herdr --version、herdr status、看 ~/.config/herdr/herdr-server.log。
速查卡
前缀 ctrl+b,按完松开再按下表的键。数据来源:herdr 0.9.5 源码 src/config/model.rs 中的默认值。
窗格
向右 / 向下分屏v / -
移动焦点h j k l
交换位置shift+h j k l
循环切换tab
放大 / 还原z
调整大小r
关闭x
重命名shift+p
复制模式[
标签页
新建c
下一个 / 上一个n / p
第 1–9 个1…9
重命名shift+t
关闭shift+x
工作区
导航w
新建shift+n
重命名shift+w
关闭shift+d
新建 worktreeshift+g
全局
所有快捷键?
跳到任意 agentg
跳到通知来源o
侧边栏开关b
设置(装集成)s
重载配置shift+r
脱离q
常用命令
herdr # 启动或接回默认会话
herdr status # 客户端 / 服务端版本,是否需要重启
herdr server stop # 停掉服务和所有窗格进程(慎用)
herdr server reload-config # 重新加载 config.toml
herdr --default-config # 打印带注释的完整默认配置
herdr integration install claude # 装集成,重启后能接回对话
herdr session list # 命名会话;herdr --session 名字 进入独立会话
herdr session stop 名字 # 停掉某个命名会话
herdr agent list # 所有 agent、所在窗格和状态
herdr agent read 名字 --source recent-unwrapped --lines 120
herdr agent prompt 名字 "..." --wait --timeout 300000
herdr agent send-keys 名字 esc # 发按键:esc / enter / ctrl+c / down …
herdr pane split --current --direction right --no-focus
herdr pane run 窗格ID 'npm test; echo "EXIT=$?"'
herdr pane wait-output 窗格ID --regex '^EXIT=[0-9]+$' --timeout 120000
配置文件在 ~/.config/herdr/config.toml,没有也能用。herdr --default-config 打印的模板里每一项都有注释,想改什么先在里面搜。
资料来源
实测本机亲手跑过 一手官方文档、源码 二手社区内容
- 实测herdr 0.9.5(Homebrew,macOS),在独立的命名会话
herdr --session tutorial-lab中跑通了第 8 节的全部命令;Claude Code 2.1.321。 - 一手官方文档(英文)herdr.dev/tui/docs,中文 herdr.dev/zh-cn/tui/docs:quick-start、concepts、keyboard、agents、integrations、session-state、configuration、agent-automation、troubleshooting 等页。
- 一手给 AI 看的引导:herdr.dev/agent-guide.md、herdr.dev/llms.txt;本机
herdr --skill。 - 一手源码 github.com/herdrdev/herdr @ v0.9.5:默认快捷键
src/config/model.rs,状态映射src/app/api_helpers.rs,Claude 识别规则src/detect/manifests/claude.toml,自动拉起服务src/server/autodetect.rs,Claude 集成src/integration/assets/claude/herdr-agent-state.sh。 - 一手GitHub issue:#6081(prompt 被提交进提问框)、#808(macOS 系统权限)、#1340(AGPL 改 Apache-2.0)。
- 一手官方博客:加入 Y Combinator(2026-08-06)、600 万美元种子轮(2026-09-08)。
- 二手视频:AI随风《AI超强终端herdr,让Agent互相通信,新手入门教程》youtu.be/3ZVWhFI5bpw(2026-08-11,11 分钟,本文用 whisper 转写了全文)。视频里“近 3 万 star”是当时的数字。
- 二手英文视频:Jilles《Herdr in about 6 minutes》qnIu-Xu64H0;Alejandro AO《Herdr Crash Course》Ct-mtWqV3Ro;lustoykov《Beginner To Advanced in 15 min》WTmCkYMelIU;Academind《herdr is a must use》2CR9tDNAzB0。
- 二手Hacker News 讨论:48756578、49201003(加入 YC)、50298436(桌面 App 发布)。
- 二手博客:flaviocopes How to manage coding agents with Herdr;少数派 从分屏到放牧 Agent;techstackups Herdr vs T3 Code vs Amp;Thoughtworks 技术雷达。