Herdr 使用指南：Workspace、Tab、Pane 与 Agent 的日常工作流

Herdr 是一个面向 AI 编码代理的终端工作区管理器。它可以把 Codex、Claude Code 等代理放进持久终端中运行，同时用 Workspace、Tab 和 Pane 组织多个项目。即使关闭本地终端或断开 SSH，远端任务仍能继续运行。

上一篇《在 Ubuntu 远程服务器上安装 Herdr》介绍了安装、PATH、Codex/Claude 集成与远程连接。这篇文章重点讲安装完成后怎样使用 Herdr，包括核心概念、首次启动、日常工作流、默认快捷键、CLI 命令和常见问题。本文基于 Herdr 0.8.2。

先理解 Herdr 的结构

flowchart TB session["Session 持久后台会话"] workspace["Workspace 项目或任务"] tab["Tab 工作页面与终端布局"] agentPane["Pane 运行编码代理"] agent["Agent Codex / Claude 等"] shellPane["Pane 普通 Shell / 服务 / 日志"] session --> workspace workspace --> tab tab --> agentPane agentPane --> agent tab --> shellPane

图表将在接近阅读区域时加载。

这几个概念从大到小依次包含。日常使用时，最重要的是把“项目”“终端”和“代理”分开理解。

Session：持久后台会话

Session 是 Herdr 后台服务器的运行空间。直接执行 herdr 使用默认 Session。它负责持有 Workspace、Tab、Pane 和终端进程，所以客户端脱离后任务仍能继续。

大多数人只需要默认 Session。命名 Session 适合需要完全隔离的工作环境，例如正式工作和临时实验：

herdr session list
herdr session attach work
herdr session attach experiment

不同 Session 拥有独立的 Workspace、Pane、Socket 和运行状态。一个默认 Session 已经可以容纳很多项目，不要把 Session 当成普通项目目录。

Workspace：一个项目或任务

Workspace 是项目级容器，通常对应一个代码仓库、目录或调查任务。例如：

xiaolaiwo.com
decimal
devflow
生产故障排查

第一次从某个项目目录启动 Herdr 时，它会自动创建 Workspace。一个 Workspace 可以包含多个 Tab，并在侧边栏汇总其中所有 Agent 的状态。

Tab：一种工作布局

Tab 类似浏览器标签页，但每个 Tab 保存的是一套终端布局。可以按用途拆分：

Tab：开发
Tab：测试
Tab：日志
Tab：部署

不同 Tab 可以拥有完全不同的 Pane 数量和分割方式。

Pane：一个真实终端

Pane 是实际运行 Shell 和程序的终端窗格。例如：

Pane 1：运行 codex
Pane 2：运行 npm run dev
Pane 3：运行测试
Pane 4：查看日志

关闭 Pane 会结束该终端中的前台程序。Pane 并不等于 Agent：没有启动 AI 程序时，它仍然是一个正常终端。

Agent：Pane 中被识别的编码代理

当 Pane 中运行 Codex、Claude Code、OpenCode、Kimi 等受支持程序时，Herdr 会把它识别为 Agent，并在侧边栏显示状态：

working：正在执行任务。
blocked：等待输入、授权或决策。
done：工作已经完成。
idle：处于空闲状态，等待新任务。
unknown：暂时无法准确判断。

退出 Codex 或 Claude 后，Pane 仍然存在，只是不再显示为 Agent。Herdr 的代理说明列出了当前支持的工具和状态来源。

第一次启动

如果 Herdr 安装在远程 Ubuntu 服务器上，先从本地终端登录服务器：

ssh <SSH_ALIAS>
cd ~/Projects/<PROJECT>
herdr

第一次启动会完成几件事：

启动当前用户的默认 Herdr 后台服务器。
以当前目录创建第一个 Workspace。
创建默认 Tab 和 Pane。
显示 onboarding 引导。

进入 Pane 后，它就是一个普通终端。可以直接启动代理：

codex

或者：

claude

安装了对应 Herdr 集成后，Herdr 可以获得代理的原生会话标识，用于受支持的会话恢复。查看集成状态：

herdr integration status

以后怎样重新进入

默认 Session 已经创建后，再次使用只需要：

ssh <SSH_ALIAS>
herdr

不必再次进入原来的项目目录。Herdr 会连接正在运行的默认 Session，恢复之前的 Workspace、Tab、Pane 和终端界面。

如果本地电脑也安装了 Herdr，可以把本地程序作为轻量客户端，直接通过 SSH 连接远端：

herdr --remote <SSH_ALIAS>

此时界面显示在本地终端中，但代码、Shell、Agent 和后台进程仍运行在远端服务器上。本地直连还可以使用本地按键配置和远程图片粘贴等客户端能力。具体差异可查看Herdr 远程工作说明。

前缀键是什么

Herdr 的默认前缀键是 Ctrl+B。前缀组合不是同时按三个键，而是分两步：

按下 Ctrl+B。
松开后，再按动作键。

例如，脱离当前客户端：

Ctrl+B，松开，然后按 q

Herdr 默认以鼠标优先，新用户不必一开始记住所有快捷键。Pane、Tab、Workspace、侧边栏和分割线都可以直接点击或拖动。

最常用的默认快捷键

功能	默认快捷键	说明
快捷键帮助	`Ctrl+B`，然后 `?`	查看当前版本和配置的实时键位
打开设置	`Ctrl+B`，然后 `s`	主题、通知、集成等设置
脱离客户端	`Ctrl+B`，然后 `q`	任务与后台服务器继续运行
选择 Workspace	`Ctrl+B`，然后 `w`	打开 Workspace 导航
全局导航	`Ctrl+B`，然后 `g`	在 Session 内容中快速跳转
新建 Workspace	`Ctrl+B`，然后 `Shift+N`	创建新的项目工作区
新建 Tab	`Ctrl+B`，然后 `c`	为当前 Workspace 新建工作页面
上一个/下一个 Tab	`Ctrl+B`，然后 `p`/`n`	按顺序切换 Tab
切换指定 Tab	`Ctrl+B`，然后 `1`～`9`	按编号直接切换
左右分割	`Ctrl+B`，然后 `v`	创建左右排列的 Pane
上下分割	`Ctrl+B`，然后 `-`	创建上下排列的 Pane
移动 Pane 焦点	`Ctrl+B`，然后 `h/j/k/l`	向左、下、上、右移动
轮换 Pane	`Ctrl+B`，然后 `Tab`	聚焦下一个 Pane
放大 Pane	`Ctrl+B`，然后 `z`	切换当前 Pane 的缩放状态
调整 Pane 大小	`Ctrl+B`，然后 `r`	进入大小调整模式
关闭 Pane	`Ctrl+B`，然后 `x`	结束当前 Pane 中的程序
滚动历史	`Ctrl+B`，然后 `e`	在编辑器中打开当前 Pane 的滚动内容
显示/隐藏侧边栏	`Ctrl+B`，然后 `b`	切换侧边栏
重新加载配置	`Ctrl+B`，然后 `Shift+R`	应用配置文件改动

按键区分大小写。最可靠的做法是使用 Ctrl+B 后按 ? 查看当前运行版本的实际绑定，而不是完全依赖网上旧文章。

脱离、关闭和停止的区别

这是 Herdr 最容易误操作的地方。

操作	影响范围	任务是否继续
`Ctrl+B` 后按 `q`	只脱离当前客户端	继续
关闭本地终端窗口	客户端连接中断	远端后台通常继续
`Ctrl+B` 后按 `x`	关闭当前 Pane	该 Pane 中的程序结束
关闭 Tab	关闭该 Tab 的全部 Pane	相关程序结束
关闭 Workspace	关闭其中全部 Tab 和 Pane	相关程序结束
`herdr server stop`	停止整个 Session 的服务器	全部 Pane 程序结束

日常离开一律优先使用“脱离”。只有明确要结束程序时，才关闭 Pane、Tab、Workspace 或停止服务器。

常用 CLI 命令

启动与状态

herdr
herdr --version
herdr status
herdr status server
herdr status client

herdr 会启动或连接默认 Session。status 用于检查本地客户端、后台服务器和 Socket 状态。

查看当前结构

herdr workspace list
herdr tab list
herdr pane list
herdr agent list

这些命令适合排错和自动化。大部分管理操作也可以直接在 Herdr 界面中用鼠标完成。

Workspace 命令

herdr workspace list
herdr workspace create --help
herdr workspace get --help
herdr workspace focus --help
herdr workspace rename --help
herdr workspace close --help

Workspace 子命令包括 list、create、get、focus、rename 和 close。参数可能随版本变化，真正执行前先查看对应 --help。

Tab 命令

herdr tab list
herdr tab create --help
herdr tab focus --help
herdr tab rename --help
herdr tab close --help

Pane 命令

herdr pane list
herdr pane current
herdr pane layout
herdr pane read --help
herdr pane split --help
herdr pane run --help
herdr pane send-text --help
herdr pane wait-output --help

Pane CLI 不只可以管理布局，还能读取终端输出、发送文字、发送按键、运行命令或等待特定输出，适合脚本和 Agent 自动协调。

Agent 命令

herdr agent list
herdr agent get --help
herdr agent read --help
herdr agent prompt --help
herdr agent focus --help
herdr agent wait --help
herdr agent attach --help
herdr agent explain --help

如果某个代理没有显示、状态不正确，使用 agent explain 查看 Herdr 的识别依据。agent prompt、wait 和 attach 更适合自动化或多代理协作。

Session 命令

herdr session list
herdr session attach work
herdr session stop work
herdr session delete work

删除前必须先停止命名 Session。删除会清除对应的持久状态，不要把它当成普通退出命令。

集成管理

herdr integration status
herdr integration install codex
herdr integration install claude
herdr integration uninstall codex
herdr integration uninstall claude

只安装服务器上实际使用的代理集成。官方集成可能提供生命周期状态、原生会话标识或两者之一，具体行为以Integrations 文档为准。

配置、更新与补全

herdr --default-config
herdr config check
herdr server reload-config
herdr channel show
herdr update
herdr completion zsh

Linux 和 macOS 的配置文件默认位于：

~/.config/herdr/config.toml

直接安装的正式版建议保持 stable 通道。只有明确愿意承担预览版回归风险时，才切换 preview。

怎样修改配置

Herdr 没有配置文件也能工作。先查看完整默认配置：

herdr --default-config

编辑 ~/.config/herdr/config.toml 后，先检查语法：

herdr config check

然后重新加载：

herdr server reload-config

也可以在运行界面中按 Ctrl+B 后按 Shift+R。不要直接复制来源不明的整份配置；优先只覆盖需要调整的字段，并参考官方配置说明。

日志与排错

默认 Session 的日志通常位于：

~/.config/herdr/herdr.log
~/.config/herdr/herdr-client.log
~/.config/herdr/herdr-server.log

常用检查顺序：

herdr --version
herdr status
herdr session list
herdr integration status
herdr config check
herdr agent list

Agent 没有被识别

确认程序确实运行在 Herdr Pane 中，而不是 Herdr 外面的普通 SSH 终端：

printf '%sn' "$HERDR_ENV"
herdr agent list
herdr integration status

在 Herdr Pane 中，HERDR_ENV 应该存在。进一步检查指定 Agent：

herdr agent explain <TARGET> --json

快捷键没有反应

先按 Ctrl+B 后按 ? 查看实时绑定。如果直接组合键无效，可能是 macOS、Ghostty 或外层终端提前拦截。Herdr 默认前缀键方案一般比自定义全局组合键更稳定。

SSH 异常断开后终端输入异常

如果鼠标移动产生转义字符、输入不回显或回车异常，可以在当前终端执行：

stty sane
reset

stty sane 恢复终端输入输出的合理默认值，reset 重新初始化终端显示状态。它们不会删除 Herdr 的远端会话。

不要在 tmux 中嵌套启动 Herdr

Herdr 本身已经负责 Pane、Tab、Workspace 和持久 Session。再套一层 tmux 会增加按键冲突和终端能力差异，还可能让 Herdr 只能看到 tmux 进程而无法正确识别后面的 Agent。除非有明确原因，否则直接在 Ghostty 或普通 SSH 终端中运行 Herdr。

进阶：让 Agent 控制 Herdr

Herdr 提供 CLI、Socket API 和 Agent skill，可以让编码代理读取 Pane 输出、拆分终端、创建 Workspace、发送命令和等待其他 Agent 状态。查看当前版本自带的 Agent skill：

herdr --skill

查看 CLI 总帮助：

herdr --help
herdr pane --help
herdr agent --help

这类功能适合自动化，不是首次使用的必需项。先熟悉默认界面、脱离和恢复流程，再逐步增加自动操作。

一套最简单的日常流程

# 1. 登录服务器
ssh <SSH_ALIAS>

# 2. 连接默认 Herdr Session
herdr

# 3. 在 Pane 中启动代理
codex

# 4. 需要时分屏
Ctrl+B，然后 v

# 5. 离开但保留任务
Ctrl+B，然后 q

# 6. 下次重新连接
ssh <SSH_ALIAS>
herdr

如果只记住一件事，就是：离开使用 detach，结束工作才 close 或 stop。

总结

Herdr 的使用逻辑并不复杂：

Session 负责持久运行。
Workspace 对应项目。
Tab 对应一种工作页面或布局。
Pane 是真实终端。
Agent 是 Pane 中被 Herdr 识别的 Codex、Claude 等程序。
Ctrl+B 后按 q只脱离客户端，不会结束任务。
再次执行 herdr即可恢复原来的工作界面。

第一次使用建议从一个项目、一个 Agent 和两三个 Pane 开始，不要急着创建很多命名 Session。熟悉 Workspace、Tab、Pane 的层级后，再使用 CLI、插件和多代理自动化。完整参考可查看Herdr 官方文档和CLI Reference。