Herdr 安装、配置与使用记录

这篇记录了我在 macOS 27.0 / Apple Silicon arm64 上配置和使用 Herdr 的过程，使用的版本是 0.8.2（stable 频道）。

0. 常用操作速查

事项	内容
启动/附加	`herdr`（默认会话）
分离（不停止进程）	前缀键 `ctrl+alt+k` → `q`（或直接关终端窗口）
重新附加	`herdr`
真正停止全部	`herdr server stop`
查看绑定列表	`ctrl+alt+k` → `?`
向右拆分窗格	`ctrl+alt+k` → `v`（或右键菜单 Split Right）
向下拆分窗格	`ctrl+alt+k` → `minus`（或右键菜单 Split Down）
新标签页	点击 tab 栏右侧 `+` 加号（不在右键菜单中）
切换标签页	`ctrl+alt+k` → `n` / `p`（或点击）
配置热重载	`herdr server reload-config`
配置位置	`~/.config/herdr/config.toml`
查看完整默认配置	`herdr --default-config`

1. Herdr 是什么

Herdr 是面向 AI 编码代理的终端工作区管理器（Terminal Workspace Manager）。

它和 tmux 一样是多路复用器（multiplexer）：后台服务器持有终端进程，客户端附加后显示这些终端。分离客户端、关闭终端或断开 SSH 后，窗格中的进程仍会继续运行。Herdr 还支持鼠标操作，并能检测窗格里的 AI 编码代理、显示它们的状态。

基本概念

概念	说明
Session	后台服务器命名空间。`herdr` = 附加默认会话；`herdr session attach work` = 命名会话（独立运行时）。多数人只用默认会话
Workspace	项目级容器，每个仓库/任务/调查一个，含标签页和窗格。侧边栏按工作区汇总代理状态
Tab	工作区内的布局，用于分离 agents、logs、server 等视图
Pane	真实终端，可向右/向下拆分，客户端分离后仍存活
Agent	Herdr 在窗格内识别的进程（如 claude、codex）
Modes	终端模式（按键发给窗格）/ 前缀模式（`前缀+动作键`）/ 导航模式

2. 安装

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

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

我配置时已装好 0.8.2，安装位置是 ~/.local/bin/herdr，没有重新执行上面的安装命令。更新可使用 herdr update；如果通过包管理器安装，则由包管理器更新。

3. 首次启动与引导

启动步骤

cd 进入项目目录，运行 herdr
首次运行时应出现引导流程（onboarding），介绍鼠标操作和前缀键

工作区界面

我从 ~/Developer/steady-pal 创建了 steady-pal 工作区。进入后没有出现引导，直接显示了工作区界面：

左侧侧边栏的 spaces 区域显示工作区名（如 steady-pal）及分支名（main）
顶部标签页显示 steady-pal git:(main)，点击 × 可关闭
左下角有 new、menu、agents、grouped 按钮
中间是运行 shell 的终端窗格（pane）

引导（onboarding）没有出现

从配置注释看，onboarding 与首次运行通知设置有关，~/.config/herdr/config.toml 中的注释是 # Show first-run notification setup on startup. Missing also shows onboarding; set false after you've chosen. # onboarding = true。可能是之前安装过或已有状态，所以没有再次显示。

没有引导不影响使用。检查环境时，可用 herdr status 查看客户端状态、herdr status server 查看服务器状态；日志位于 ~/.config/herdr/herdr-server.log。

启动前检查

先检查 HERDR_ENV。如果已经是 HERDR_ENV=1，说明当前就在 Herdr 窗格内，不要再次运行 herdr，否则会尝试嵌套启动，Herdr 会阻止这一操作。

4. 鼠标操作

我试过的操作

操作	方法	实测结果
聚焦窗格/标签页	鼠标点击	✅
拆分窗格	窗格空白处右键 → Split Right / Split Down	✅ 菜单只有 `split right`、`split down` 之类
调整窗格大小	拖动窗格间分割线	✅
切换标签页	点击 tab	✅

新建标签页的位置

官方 agent-guide.md 说右键菜单包含新建标签页等操作，但本机 0.8.2 的右键菜单只有拆分窗格（split right / split down）。

新建标签页要点击 tab 栏右侧的 +。弹出的小窗可以自定义名称，默认按数字递增，例如 2。

5. 代理状态（Agent States）

五种状态

状态	含义	图标（官方 README）	本机实测
working	代理正在运行（思考/编辑/执行）	🟡 黄色实心圆	✅ 已实测（输入提示词运行时）
blocked	代理在等人：审批、提问、权限弹窗	🔴 红色圆点	✅ 已实测（Claude 等待人工确认时）
done	工作完成，还没被查看	🔵 蓝色	未实测（需集成触发）
idle	代理空闲，等在提示符	🟢 绿色实心圆	✅ 已实测（Claude 回复完回提示符）
unknown	无法分类的窗格	灰色（无官方规格）	未实测

状态颜色的来源

herdr.dev/docs/agents/ 只定义了 working/blocked/done/idle 的含义，没有给出颜色。表中的颜色来自官方 GitHub README（github.com/dmonad/herdr）。当时看到一篇第三方中文文章把绿色解释为运行中，与官方说明不一致，这里按官方说明记录。

需要排查状态时，用 herdr agent explain <target> --json 查看分类规则及匹配证据，用 herdr agent list 查看 Herdr 识别到的代理。

查看代理识别结果

Claude 空闲时：state: idle，匹配规则 live_prompt_box（优先级 950，prompt_box_body 区域）
规则示例：osc_title_working（终端标题含工作标记）、live_turn_working（底部非空行）、bash_permission_prompt（“do you want to proceed?”）等

6. 安装 Claude Code 集成

它是什么

herdr integration install claude 安装的是一个 hook 脚本：~/.claude/hooks/herdr-agent-state.sh。

工作原理

能力	由谁负责
状态检测（颜色圆点）	屏幕检测（screen manifest detection）——Herdr 自动识别窗格内容
会话恢复（session restore）	集成（hook 上报 Claude Code 会话身份到 Herdr socket）

集成属于 Session identity 类，上报会话引用，供服务器重启后恢复 pane 使用；它不负责提供权威的生命周期状态。恢复行为受 [session] resume_agents_on_restore 控制，默认启用。

会话恢复需要 Claude Code 集成 v6 及以上；本机当时安装的是 v8。

安装

herdr integration install claude

安装会修改哪些文件

hook 脚本：~/.claude/hooks/herdr-agent-state.sh（可执行）
修改 settings.json：~/.claude/settings.json 添加 Herdr hook 条目

卸载

herdr integration uninstall claude

卸载时会从 settings.json 移除 hook 条目，并删除 hook 文件。

新会话才会加载集成

Hook 在 Claude Code 会话启动时加载。安装时已经运行的会话不受影响，下次新开的 Claude 会话才会带上集成。

验证时，在新会话里运行 herdr agent list，检查集成字段或会话引用。

7. 前缀键的冲突与配置

默认前缀键

默认：ctrl+b
三种模式：终端模式（按键直接给窗格）/ 前缀模式（ctrl+b 后按动作键）/ 导航模式

与 emacs 风格快捷键的冲突

键	占用情况	冲突程度
ctrl+b（默认）	zsh/emacs 的 backward-char（后退光标）	中：连续按两次会误触发 toggle_sidebar
ctrl+k（曾考虑）	zsh/emacs 的 kill-line（删除到行尾）—— 本机实测确认：`bindkey "^K"` 返回 `kill-line`	高：单按即冲突，kill-line 失效
ctrl+alt+k（最终选择）	无占用（实测 zsh/vim 均无此绑定）	无

我的配置

文件：~/.config/herdr/config.toml

# herdr configuration
# 由 Claude Code 于 2026-08-21 协助创建，仅自定义前缀键，其余使用默认值

[keys]
# 前缀键从默认的 ctrl+b 改为 ctrl+alt+k：
# - ctrl+alt 是 Herdr 官方推荐的 macOS 安全键族（不受 option 组合行为影响）
# - 避免与 zsh/emacs 的 ctrl+k (kill-line) 冲突
# - 释放 ctrl+b 给 shell 的 emacs 风格导航使用
prefix = "ctrl+alt+k"

选择原因

官方明确推荐 ctrl+alt 作为 macOS 上的安全键族：option 组合可能被终端转换为特殊字符，例如 alt+k 失效；ctrl+alt 不受影响，能可靠传输，也很少被 OS、外部终端或窗格程序占用。

我的 caps lock 已映射为 ctrl，按 ctrl+alt+k 比较顺手，也能把 ctrl+b 留给 shell 的 emacs 导航。

重新加载配置

herdr server reload-config

返回 {"status":"applied"} 表示成功。

macOS 上的 alt 键

alt 就是 macOS 的 option 键（⌥），在终端语境中也会写作 option 或 ⌥。多数 macOS 终端会把纯 alt+字母 组合成特殊字符，因此这类绑定不可靠；ctrl+alt 不受影响。

改用 `ctrl+alt+k` 后的常用快捷键

操作	绑定
查看所有绑定	`ctrl+alt+k` → `?`
分离	`ctrl+alt+k` → `q`
新标签页	`ctrl+alt+k` → `c`
下一个/上一个标签页	`ctrl+alt+k` → `n` / `p`
向右拆分	`ctrl+alt+k` → `v`
向下拆分	`ctrl+alt+k` → `minus`
关闭窗格	`ctrl+alt+k` → `x`
切换侧边栏	`ctrl+alt+k` → `b`
聚焦窗格（hjkl）	`ctrl+alt+k` → `h/j/k/l`
工作区选择器	`ctrl+alt+k` → `w`

8. 为 Claude Code 安装 Herdr 技能（Skill）

它是什么

Herdr 自带技能文件（skills/herdr/SKILL.md），用于指导编码代理在窗格内控制 Herdr，包括拆分窗格、在不抢焦点的情况下运行命令、读取输出和等待其他代理。

安装命令

npx skills add herdrdev/herdr --skill herdr -g

安装位置与检查

安装到 ~/.agents/skills/herdr/SKILL.md
Claude Code 符号链接：~/.claude/skills/herdr -> ../../.agents/skills/herdr
验证：ls -la ~/.claude/skills/herdr

代理可以执行的操作

herdr pane split —— 拆分窗格（--no-focus 保持焦点，--current 定位）
herdr pane run / wait-output / read —— 在其他窗格运行命令、等待输出并读取结果
herdr agent prompt / wait / read / get —— 给其他代理发任务、等待、读取
需要 HERDR_ENV=1，只有在 Herdr 窗格内启动的代理才能控制窗格
禁止运行裸 herdr（会启动/附加 TUI）

如何生效

需要在 Herdr 窗格里启动 claude，会话才能使用这个技能。我最初的会话开在普通终端里，因此没有生效。

9. 分离与重连

分离后再连接

按 ctrl+alt+k → q 分离
退出 Herdr 界面，回到普通 shell 提示符
关闭终端窗口，服务器进程不受影响
重新运行 herdr 附加
Claude 仍在原来的窗格里，界面与分离前一致

关键概念

分离只断开客户端，服务器和所有窗格进程仍继续运行。再次运行 herdr 可以重新附加；herdr server stop 才会停止服务器及 pane 进程。

10. 遇到问题时怎么检查

问题	检查方法
代理未检测到/状态错误	`herdr agent list`（查看识别结果）；`herdr agent explain <target> --json`（看分类原因）；`herdr integration status`（看集成）
键绑定无效	外层终端或桌面环境可能占用了这组快捷键。macOS 上避免纯 `alt+字母`（被组合成特殊字符）；选 `ctrl+alt` 或功能键
启动/socket 异常	日志在 `~/.config/herdr/`（Linux/macOS）；`herdr status`、`herdr status server`、`herdr status client`
远程使用	SSH 到机器后运行 `herdr`（类 tmux），或 `herdr --remote <host>` 作瘦客户端

11. 使用时的注意事项

不要在 Herdr 窗格内再运行 herdr：先检查 HERDR_ENV=1 是否已设置，如果已设置，就不要重复启动
引导（onboarding）可能不出现：没有出现引导也不影响使用
右键菜单没有“新建标签页”：点击 tab 栏 + 加号，而不是右键菜单
颜色规格不在网页文档：看官方 GitHub README；第三方文章可能与官方矛盾
macOS 上纯 alt+字母 不可靠：会被组合成特殊字符；用 ctrl+alt 或功能键
ctrl+k 在 zsh/emacs 中是 kill-line：作为前缀键会与 emacs 行编辑冲突，不推荐
集成安装后当前会话不生效：hook 在会话启动时加载，需新开 Claude 会话
修改配置无需重启：herdr server reload-config 热重载
技能需要 HERDR_ENV=1：只有 Herdr 窗格内启动的代理才有控制 Herdr 的能力

12. 当时的本机环境

项目	值
系统	macOS 27.0 / Apple Silicon arm64
Herdr 版本	0.8.2（stable 频道）
安装位置	`~/.local/bin/herdr`
配置文件	`~/.config/herdr/config.toml`（仅自定义 prefix）
日志位置	`~/.config/herdr/herdr-server.log`、`herdr-client.log`
Socket	`~/.config/herdr/herdr.sock`
工作区	`steady-pal`（`/Users/dongxu/Developer/steady-pal`）
已安装集成	claude（v8，`~/.claude/hooks/herdr-agent-state.sh`）
已安装技能	herdr（`~/.agents/skills/herdr`，链接到 `~/.claude/skills/herdr`）
前缀键	`ctrl+alt+k`
caps lock	已映射为 ctrl

13. 官方资源

代理指南（Agent Guide）：https://herdr.dev/agent-guide.md
概念文档：https://herdr.dev/docs/concepts/
键盘文档：https://herdr.dev/docs/keyboard/
代理文档：https://herdr.dev/docs/agents/
集成文档：https://herdr.dev/docs/integrations/
安装文档：https://herdr.dev/docs/install/
配置参考：https://herdr.dev/docs/configuration/
技能文件（GitHub）：https://raw.githubusercontent.com/herdrdev/herdr/master/skills/herdr/SKILL.md

0. 常用操作速查

1. Herdr 是什么

基本概念

2. 安装

3. 首次启动与引导

启动步骤

工作区界面

引导（onboarding）没有出现

启动前检查

4. 鼠标操作

我试过的操作

新建标签页的位置

5. 代理状态（Agent States）

五种状态

状态颜色的来源

查看代理识别结果

6. 安装 Claude Code 集成

它是什么

工作原理

安装

安装会修改哪些文件

卸载

新会话才会加载集成

7. 前缀键的冲突与配置

默认前缀键

与 emacs 风格快捷键的冲突

我的配置

选择原因

重新加载配置

macOS 上的 alt 键

改用 ctrl+alt+k 后的常用快捷键

8. 为 Claude Code 安装 Herdr 技能（Skill）

它是什么

安装命令

安装位置与检查

代理可以执行的操作

如何生效

9. 分离与重连

分离后再连接

关键概念

10. 遇到问题时怎么检查

11. 使用时的注意事项

12. 当时的本机环境

13. 官方资源

改用 `ctrl+alt+k` 后的常用快捷键