中文快速入门 · herdr 0.9.5

herdr 30 分钟上手:给 AI 编程 agent 的终端工作台

同时开着三五个 Claude Code、Codex,总有一个卡在“要不要批准”上没人管?herdr 就是为这件事做的。这篇只讲最常用的 80%,读完能用起来,用到的命令都在本机跑过。

更新于 2026-11-22基于 herdr 0.9.5(Herdr TUI)非官方整理
一分钟版本
  1. herdr 是一个“认识 AI agent 的 tmux”:后台常驻、分屏分标签页,额外能看出每个窗格里的 agent 是在干活、在等你批准,还是干完了。
  2. 装好后在项目目录敲 herdr,在窗格里照常运行 claude / codex。左侧边栏会告诉你哪个项目需要你。
  3. 前缀键是 ctrl+b。先记五个:c 新标签页、v / - 分屏、h j k l 切窗格、w 切工作区、q 脱离。不会就按 ctrl+b ?。
  4. 关掉终端,agent 照跑;再敲 herdr 回来。(电脑合盖睡眠时一样会停,长时间无人值守要放到服务器上。)
  5. 真正拉开差距的是:给 agent 装上 herdr 技能,让 Claude Code 自己开窗格、启动 Codex 去审方案、等它审完再继续。

开始之前 1 分钟

这篇写给谁:会用终端、在用(或打算用)Claude Code、Codex 这类命令行 AI 编程工具的工程师。不需要用过 tmux。

学完能做到:一个窗口里管好多个项目、多个 agent;关掉终端窗口 agent 也不停;一眼看出谁卡住了;会让一个 agent 去调度另一个 agent。

先认清是哪个 herdr

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 用的终端工作区管理器)。拆开说就是两件事:

  1. 它是一个终端复用器(multiplexer,就是 tmux / zellij 那一类):一个后台服务进程替你“养着”所有终端,你的终端窗口只是一个显示器。窗口关了、SSH 断了,里面的程序照跑,回来接上就行。
  2. 它认识 agent:能识别窗格里跑的是 Claude Code、Codex、OpenCode 等 20 多种工具,并把每个 agent 标成“在干活 / 等你批准 / 干完了”,在侧边栏按项目汇总。还提供命令行接口,让 agent 之间能互相开窗格、发任务、等结果。
你的终端窗口 (客户端,只负责显示) 另一台电脑 / 手机 (也可以同时接上来) 脚本 / 另一个 agent herdr pane / agent 命令 (走 JSON 接口) herdr 后台服务(server) 拥有所有真实终端和进程 · 关窗口它也不停 窗格 1:claude working 在干活 识别:进程名 + 读屏幕底部 窗格 2:codex blocked 等你批准 侧边栏立刻标红 窗格 3:npm run dev 普通程序也能跑 只是没有状态灯 窗格 4:claude done 干完,你还没看
图 1 · herdr 的结构。和 tmux 一样是“服务端 + 客户端”;多出来的是状态识别和给程序用的 JSON 接口。依据:官方 concepts 文档、源码 src/server/autodetect.rs。

和 tmux 比

tmuxherdr
后台常驻、断线不丢✔✔(模型一样,前缀键也是 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)”环。

值不值得学如果你只同时跑一个 agent,普通终端就够了。同时跑两个以上,或者经常想关掉终端、断开 SSH 让 agent 自己跑,herdr 省下的“挨个切过去看”的时间很快就能收回成本。它不替换也不包装你的 agent,随时可以退回原来的用法。

安装与第一次启动 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 节。

界面三块

在窗格里照常运行 claude、codex 等,不用加任何参数,herdr 会自动识别。

两个“别敲”

① 在 herdr 的窗格里不要再敲 herdr:默认会被拦下(官方有意这样设计;确实需要时可设 [experimental] allow_nested = true)。
② herdr server(不带子命令)不是看帮助,它会尝试再起一个后台服务。看帮助用 herdr --help;看某组命令的用法,直接敲组名,如 herdr pane。

四个概念,五种状态 4 分钟

目标:脑子里有一张图,后面所有操作都是在这张图上做加减。

Session 会话 一个后台服务;绝大多数人只用默认这一个 Workspace 工作区 = 一个项目 一个仓库 / 一个任务一个;侧边栏按它汇总状态 Tab 标签页 一种布局:agents / logs / server … Pane 窗格 一个真实终端 agent:claude Pane 窗格 npm test (没有 agent) 另一个工作区 比如 my-api 项目 状态向上汇总 窗格里有 agent 卡住 → 标签页、工作区都标红 → 你在侧边栏一眼看到
图 2 · 层级关系。ID 也照这个层级编:工作区 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 不会消失。

最重要的一句:idle 不等于“安全”

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 ? 显示的为准。

练习(5 分钟):搭一个标准的单项目布局
  1. 在项目目录运行 herdr。
  2. ctrl+b v 向右分屏。左边运行 claude,右边运行 git status。
  3. ctrl+b - 把右边再上下切一刀,下面跑测试或开发服务器。
  4. 用 ctrl+b h / l 在左右之间跳,ctrl+b z 放大 Claude 那一格再还原。
  5. ctrl+b c 新开一个叫 logs 的标签页,ctrl+b p / n 来回切。
  6. 给 Claude 派个要跑一会儿的活,然后 ctrl+b q 脱离,直接关掉终端窗口。
  7. 新开一个终端,敲 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 内置了这个功能:

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 Claude Code(写方案) 装了 herdr 技能 审核员 reviewer Codex(另一家模型) 执行者 builder 便宜的模型干体力活 ① 启动并派活 ③ 审过了才派执行 ② 审 → 改 → 再审 agent prompt --wait 等对方变成 idle / blocked agent read 读回结论 一个演示视频里 来回了 7 轮才通过
图 3 · 多 agent 协作的典型流程。“7 轮”来自 B 站 / YouTube 作者“AI随风”的演示视频(2026-08),流程是 Claude Code 写方案、Codex 审、DeepSeek 执行。

方式一:给 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 一下。

我实测踩到的三个坑(herdr 0.9.5 + Claude Code 2.1)
  1. 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 秒。经验:结束标记要写成只有输出里才会出现的样子,再用 ^ 锚定行首。
  2. 第一次进目录时的“信任此文件夹”对话框: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。选项顺序可能随版本变化,别把按键写死在脚本里,每次都先看屏幕。
  3. prompt 被一个没认出来的弹窗吞掉:Claude Code 弹出一个“Teach auto mode…”提示框,herdr 仍然报 idle。agent prompt --wait 2 秒就“成功”返回了,屏幕上却没有任何回答;按 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 用户和几位教学视频作者的真实用法,只挑了说法比较一致的:

两个有争议的地方,按自己情况选

要不要每个 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 明明在等批准,侧边栏却是 idleblocked 判断从严,遇到新样式的对话框会漏判。重要的 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 认不出 agentherdr 只看到 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 ;3Czsh 没绑定这些键: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 打印的模板里每一项都有注释,想改什么先在里面搜。

资料来源

实测本机亲手跑过 一手官方文档、源码 二手社区内容