终端里的 AI 代理总控台：Herdr 到底解决什么问题

如果你已经在终端里同时跑过 Claude Code 和 Codex，大概遇到过这种情况：两个代理都在干活，你在等其中一个完成，但它到底是卡在授权界面、正在思考、还是已经跑完了，你得到处切窗口。如果 SSH 断了一下，某个代理可能就彻底没了。

Herdr 就是解决这组问题的。

它不是新的 AI 模型，不替换 Claude Code，也不替代 Codex。它是一个运行在终端里的 AI 编程代理运行时与终端复用器，管三件事：保存代理进程、组织多个项目、显示代理状态，以及让代理之间互相调度。用官方文档里那句话理解最直接：

“

Herdr 不是再雇一个 AI，而是给现有的 AI 员工配上工位、门牌、状态灯和总控台。

项目 2026 年成立，属于 YC Fall 2026 批次，GitHub 仓库目前 26.4k Stars，v0.8.0 是截至 2026 年 8 月的最新稳定版。代码用 Rust 写，单二进制，不依赖 Electron，不要求注册账户，官网明确标注无遥测。

谁该装，谁不该装

值得装的人：你经常在 Mac 或 Linux 终端里同时跑两个以上命令行 AI 编程代理（Claude Code、Codex、OpenCode 等），并且任务时长超过十分钟，需要关掉终端或断开 SSH 后代理继续跑。这种人装 Herdr 会明显减少“切窗口查看状态”的时间。

不值得装的人：你每天只开一个 Claude Code，十分钟内搞定，或者主要工作都在 Cursor、Windsurf 这类图形化编辑器里完成。那 Herdr 带来的 Workspace、Tab、状态面板这些概念对你来说属于额外负担，收益覆盖不了学习成本。

Windows 用户注意：原生 Windows 版本目前还是实验性 Beta，基于 ConPTY，已知限制包括不支持原生 herdr --remote、不支持直接终端 Attach、不支持 Live Handoff、剪贴板图片桥接未完成、CJK 输入法光标位置有取舍、二进制还没解决 SmartScreen 签名问题。官方建议 Windows 用户先通过 SSH 连到 Linux 服务器再跑 Herdr，或者在 WSL 里测试。

它和 tmux 的本质区别在哪

用过 tmux 的人，上手 Herdr 时会觉得概念熟悉：后台服务器保留终端会话，你可以随时 detach 再 attach。但 Herdr 多了一层它不做的：

识别每个 Pane 里跑的是不是 AI 编程代理，以及这个代理当前什么状态。

Herdr 会汇总每个代理的状态：

状态 含义
blocked 等待输入、确认、授权或选择
working 正在执行任务
done 已完成，但你还没查看
idle 已完成或等待，且已被查看
unknown Herdr 无法可靠判断当前状态

状态会从单个 Pane 向上汇总到 Tab，再汇总到 Workspace。只要某个项目里有一个代理卡在授权界面，整个 Workspace 的标签就会显示成需要你注意。这就是 Herdr 相比 tmux 的核心价值：当编码代理从一个变成一群，瓶颈不再是生成速度，而是人的注意力调度。

这里有个点要讲清楚：状态判断并非百分之百准确。Herdr 默认通过前台进程和终端画面识别代理，对 Claude Code、Codex 这类集成主要提供原生 Session 标识（用于服务器重启后恢复对话），状态判断仍然主要来自终端画面检测。某些新版本授权界面或特殊提示可能暂时显示成 idle。

如果发现状态判断明显不对，可以运行：

herdr agent explain <代理名称或Pane ID>

它会显示检测到的进程、画面规则、匹配证据和最终判断。这是调试状态识别问题的入口，不是给普通用户日常用的。

安装与首次启动

macOS 推荐 Homebrew：

brew install herdr
herdr --version

Linux 或 macOS 直接安装脚本：

curl -fsSL https://herdr.dev/install.sh | sh
herdr --version

Windows Beta（实验性）：

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

安装脚本会根据操作系统和 CPU 架构选择二进制，并验证 SHA-256。

装完之后，如果你主要用 Claude Code 和 Codex，建议先装集成：

herdr integration install claude
herdr integration install codex
herdr integration status

这些集成会在 Claude Code 和 Codex 的配置目录里安装 Herdr Hook，主要作用是记录原生 Session ID。这样 Herdr 后台服务器重启后可以恢复原来的对话。卸载集成时，Herdr 会移除自己添加的 Hook。

然后从项目根目录启动：

cd ~/Projects/my-project
herdr

首次启动时，Herdr 会创建或连接默认后台 Session，并自动创建一个 Workspace、一个 Tab 和一个根 Pane。

上手：先不用记快捷键

Herdr 对新手友好的一点是：可以先完全用鼠标操作，不用学快捷键。

进入后你可以直接：

  1. 在当前 Pane 输入 claude 启动 Claude Code；
  2. 右键当前 Pane，选择向右拆分；
  3. 在右侧 Pane 输入 codex 启动 Codex；
  4. 再创建一个 Tab；
  5. 在新 Tab 里运行测试或开发服务器；
  6. 观察左侧 Agents 区域的状态变化。

鼠标操作覆盖了：点击切换 Pane、Tab、Workspace 或 Agent，拖动分割线调整大小，右键菜单创建 Tab 或拆分 Pane，鼠标拖选文字直接复制，双击单词复制。

等你熟悉了布局，再逐步用快捷键提升效率。prefix 默认指：先按 Ctrl+B，松开，再按后面的键。

操作 快捷键
帮助 Ctrl+B，然后 ?
新建 Tab Ctrl+B，然后 C
向右拆分 Ctrl+B，然后 V
向下拆分 Ctrl+B，然后 -
Pane 之间移动 Ctrl+B，然后 H/J/K/L
下一个/上一个 Tab Ctrl+B，然后 N/P
Workspace 导航 Ctrl+B，然后 W
新建 Workspace Ctrl+B，然后 Shift+N
新建 Git Worktree Ctrl+B，然后 Shift+G
收起/展开侧边栏 Ctrl+B，然后 B
放大当前 Pane Ctrl+B，然后 Z
复制模式 Ctrl+B，然后 [
分离客户端 Ctrl+B，然后 Q

完整快捷键列表可以在 Herdr 里按 Ctrl+B，再按 ? 搜索查看。

最要命的功能：终端关了代理还在跑

普通终端窗口一关，里面的代理、测试或服务器通常会退出。Herdr 把这些进程放在后台服务器拥有的真实终端里，所以你可以关掉当前终端、断开 SSH，之后重新运行 herdr，回到原来的终端和代理。

测试方式：在 Pane 里跑一个代理或命令，然后按 Ctrl+B、Q 分离。Herdr 界面退出，但后台进程继续跑。再执行 herdr 就能回到原来的会话。

这个机制适用的场景：

  • Claude Code 执行长时间重构；
  • Codex 扫描大型代码库；
  • 后台运行测试、构建或开发服务器；
  • 在远程 GPU、云服务器、Mac Mini 上跑代理；
  • 工作中途换电脑、换终端，甚至用手机查看状态。

限制要讲清楚：Herdr 能抵抗终端关闭和 SSH 断线，但不能让关机或休眠中的电脑继续计算。如果 Herdr 后台服务器本身被停止，或者整台机器重启，任意 Shell、测试、服务器等普通进程不会继续存活。Herdr 只能恢复 Workspace、Tab、Pane、目录和布局；安装了官方集成的部分 AI 代理，可以恢复原来的对话 Session。

所以真正需要跑几个小时甚至几天的任务，最好放在不会休眠的远程服务器或常开主机上。

要真正结束所有 Pane 和代理，运行：

herdr server stop

停止服务器会结束其拥有的进程。不要在重要长任务运行期间执行这条命令。

最推荐的工作区布局

对 Claude Code + Codex 的组合，官方推荐一个比较实用的布局：

Workspace：当前项目
│
├── Tab：agents
│   ├── 左侧 Pane：Claude Code，实现功能
│   └── 右侧 Pane：Codex，独立审查
│
├── Tab：runtime
│   ├── 左侧 Pane：开发服务器
│   └── 右侧 Pane：测试或类型检查
│
└── Tab：review
    ├── git diff
    └── lazygit 或其他代码审查工具

角色分工可以固定为：

角色 任务
Claude Code 阅读上下文、实现主要功能
Codex 检查 Diff、找边界问题、验证实现
测试 Pane 持续运行测试、Lint、构建
人 控制任务边界、处理授权、审查最终 Diff

不要一开始同时跑十几个代理。实用并发量通常是：

  • 1 个主实现代理；
  • 1 个独立审查代理；
  • 1 个测试或服务器 Pane；
  • 最多再增加 1 个资料调查代理。

超过这个数量，节省的执行时间会重新变成人的协调成本。

Git Worktree：多个代理不能共享同一个目录

多个代理同时修改代码时，不要让它们共享同一个工作目录。这是 Herdr 内置 Git Worktree 工作流要解决的问题。

在主仓库中创建独立 Worktree：

cd ~/Projects/my-app

herdr worktree create \
  --cwd "$PWD" \
  --branch feat/search \
  --base main \
  --label search

Herdr 会：

  1. 创建或检出 feat/search 分支；
  2. 在默认 Worktree 目录中创建独立 Checkout；
  3. 新建对应 Workspace；
  4. 将其与主仓库 Workspace 分组显示。

默认 Worktree 根目录是 ~/.herdr/worktrees，可以通过配置修改。

这里的删除行为要特别注意：关闭 Workspace 只关闭 Herdr 中的界面，不删除 Checkout。只有明确执行 herdr worktree remove 才会调用 Git 删除 Worktree，而且不会删除分支——只删 Worktree Checkout。

推荐规则：一个会写代码的任务对应一个 Worktree；只读审查代理可以与实现代理共享 Worktree。

适合中文 Mac 用户的配置

配置文件在 ~/.config/herdr/config.toml。下面是一份可以直接复制使用的配置：

mkdir -p ~/.config/herdr

cat > ~/.config/herdr/config.toml <<'EOF'
onboarding = false

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

[terminal]
new_cwd = "follow"

[ui]
agent_panel_sort = "priority"
show_agent_labels_on_pane_borders = true

[ui.toast]
delivery = "system"
delay_seconds = 1

[ui.sound]
enabled = true

[session]
resume_agents_on_restore = true

[worktrees]
directory = "~/.herdr/worktrees"

[experimental]
pane_history = false
reveal_hidden_cursor_for_cjk_ime = true
cjk_ime_agents = ["claude", "codex", "pi"]
switch_ascii_input_source_in_prefix = true
EOF

herdr server reload-config

这份配置做的事情：

  • 根据系统深浅模式自动切换主题；
  • 代理列表优先按紧急状态（blocked > done > working）排列；
  • 在 Pane 边框显示代理名称，不用切到 Agents 面板就能看到哪个 Pane 跑着什么代理；
  • 使用 macOS 系统通知（远程 SSH 使用时，delivery = "terminal" 通常更合适）；
  • 支持支持的代理在服务器重启后恢复原对话；
  • 修复部分 Claude Code、Codex TUI 里中文输入法候选框位置问题；
  • 进入 Herdr 前缀模式时临时切到英文输入源，避免中文输入法干扰快捷键；
  • pane_history = false 保持关闭，避免把终端里的密钥、提示词或日志写入磁盘。

代理调度另一个代理：最独特的玩法

Herdr 不只是给人看状态，它还提供 CLI、Socket API 和 Agent Skill。代理本身可以：

  • 创建 Workspace 和 Tab；
  • 拆分 Pane；
  • 启动另一个代理；
  • 给另一个代理发送提示词；
  • 读取另一个 Pane 的输出；
  • 等待测试结束；
  • 等待某个代理进入完成或阻塞状态；
  • 收集其他代理的审查结果。

下面这段是官方推荐模式的简化版本。它会在当前 Pane 右侧创建新 Pane，启动一个 Codex 审查代理，给它发送任务并读取结果。

需要本机安装 jq：

split=$(
  herdr pane split \
    --current \
    --direction right \
    --no-focus
)

review_pane=$(
  printf '%s\n' "$split" |
  jq -r '.result.pane.pane_id'
)

herdr agent start reviewer \
  --kind codex \
  --pane "$review_pane"

herdr agent prompt reviewer \
  "只读审查当前 Git diff。按严重程度列出问题，不要修改文件。" \
  --wait \
  --timeout 600000

herdr agent read reviewer \
  --source recent-unwrapped \
  --lines 160

这段展示的是 Herdr 最独特的四个能力：

  • split：创建工作位置；
  • start：启动指定类型的代理；
  • prompt：发送任务并等待状态变化；
  • read：获取代理的终端输出。

Herdr 的自动化层区分 Layout、Pane 和 Agent 三种对象，CLI 返回结构化 JSON，适合编写稳定的 Shell 脚本或让主代理编排辅助代理。

v0.8.0 还可以直接输出内置 Agent Skill：

herdr --skill

安装或注入这个 Skill 后，Claude Code、Codex 等代理能知道自己正运行在 Herdr 中，并通过 HERDR_ENV=1 和 Herdr CLI 管理相邻 Pane、测试和辅助代理。

远程服务器和手机怎么连

三种方式：

# 本地直接跑
herdr

# SSH 到服务器再跑 Herdr
ssh you@server
herdr

# 本地 Herdr 作为远程瘦客户端
herdr --remote workbox

第三种方式需要在 ~/.ssh/config 中配置：

Host workbox
  HostName server.example.com
  User you
  Port 22

然后直接执行 herdr --remote workbox。本地 Herdr 会通过 SSH 连接远程服务器，优先使用远程已有的匹配版本，必要时交互式提示安装。这个模式可以用本地快捷键，并把本地剪贴板中的图片桥接到远程代理。

手机和平板的使用方式更简单：装任意 SSH 客户端，连接运行 Herdr 的服务器，执行 herdr，在窄屏响应式界面里查看 Agent 状态，进入 blocked 的 Pane 完成授权，再分离。Herdr 不需要单独的移动 App 或 Web 控制台。

隐私、安全和插件

无遥测不等于完全不联网。 官网明确标注“不需要账户、无遥测”，但默认情况下 Herdr 会：

  • 检查新版本；
  • 从 Herdr 官网获取代理检测规则更新；
  • 安装插件时访问 GitHub；
  • 使用 --remote 时通过 SSH 访问远程服务器。

严格离线环境可以配置关闭版本检查和代理检测规则检查：

[update]
version_check = false
manifest_check = false

但要注意：关闭 manifest_check 后，Herdr 仍会使用二进制内置规则，可能无法及时识别 Claude Code、Codex 新版本出现的授权界面。

Pane History 默认关闭，不要轻易打开。 正常分离时，终端内容存在运行中的后台服务器里。如果开启 [experimental] pane_history = true，Herdr 会将近期终端内容写入 session-history.json。里面可能包含 API Key、Token、文件路径、提示词、命令输出、私有代码。所以默认关闭是有原因的。

插件市场不是审核市场。 Herdr 插件市场是对带有 herdr-plugin GitHub Topic 的公开仓库自动建立的索引，不代表官方审查或认可。插件本质上是可执行程序，可以运行构建命令、响应事件、打开 Pane，调用 Herdr CLI 或 Socket API。

安装插件前建议检查：

  • 仓库拥有者；
  • 最近提交；
  • herdr-plugin.toml；
  • 构建脚本；
  • Shell、JavaScript 或 Rust 入口文件；
  • 是否访问网络；
  • 是否读取环境变量和本地文件；
  • 是否可以固定到明确的 Git Commit 或 Tag。

不要把 --yes 用于来源不明的非交互安装。

Herdr 不是安全沙箱。 它负责管理终端，不负责限制代理权限。Claude Code、Codex、插件以及普通命令，仍以当前系统用户权限运行。

生产环境建议：

  • 使用独立非管理员账户；
  • 一个任务一个 Git Worktree；
  • 不向实验机器注入生产密钥；
  • 保留代理授权确认；
  • 对破坏性命令使用容器或虚拟机；
  • 最终合并前人工审查 Git Diff。

更新、诊断和卸载

Homebrew 安装的更新：

brew upgrade herdr

直接安装脚本安装的更新：

herdr update

查看更新通道：

herdr channel show

不要在重要长任务运行期间切换 Preview 或执行需要重启服务器的更新。如果客户端与服务器协议不兼容，Herdr 会要求停止旧服务器——而停止服务器会结束 Pane 中的进程。实验性的 herdr update --handoff 可以尝试迁移运行中的终端，但官方标注为 Best Effort。

常用诊断命令：

herdr -V
herdr status
herdr integration status
herdr agent list
herdr agent explain <代理或Pane>
herdr server agent-manifests
herdr server reload-config

日志默认位置：

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

需要详细日志时：

HERDR_LOG=herdr=debug herdr

macOS 完整卸载：

herdr integration uninstall claude
herdr integration uninstall codex
herdr server stop

Homebrew 安装的：

brew uninstall herdr

直接脚本安装的二进制默认在：

rm -f ~/.local/bin/herdr

需要保留配置备份：

mv ~/.config/herdr ~/.config/herdr.backup

不要直接删除 ~/.herdr/worktrees，里面可能有尚未提交的代码。

操作速览

  • 安装：brew install herdr（Mac）或 curl -fsSL https://herdr.dev/install.sh | sh（Linux）
  • 安装集成：herdr integration install claude 和 codex
  • 启动：cd ~/Projects/my-project && herdr
  • 分离：Ctrl+B 松开后按 Q
  • 重新连接：herdr
  • 停止服务器：herdr server stop
  • 配置位置：~/.config/herdr/config.toml
  • 日志位置：~/.config/herdr/herdr*.log
  • Worktree 默认目录：~/.herdr/worktrees

FAQ

Herdr 和 tmux 什么关系？
Herdr 不是 tmux 的替代品，而是在终端复用器基础上增加了 AI 代理状态识别和代理间调度能力。如果你只需要持久化几个普通 Shell，用 tmux 或 Zellij 足够；如果你同时跑多个 AI 编程代理，Herdr 的状态汇总和远程持久化比 tmux 更省注意力。

状态识别不准怎么办？
运行 herdr agent explain <代理名称或Pane ID>，查看 Herdr 检测到的进程、画面规则和匹配证据。如果确认是代理新版本界面变化导致的误判，可以等待 Herdr 更新代理检测规则（默认会自动拉取），或在 GitHub 仓库提 Issue。

代理之间的对话能恢复吗？
安装了官方集成（如 herdr integration install claude）的代理，在 Herdr 服务器重启后可以恢复原来的对话 Session。没有安装集成的代理只能恢复终端布局和目录，对话历史不会保留。

远程服务器上跑 Herdr 需要注意什么？
建议把服务器放在不会休眠的常开机器上。远程使用时，ui.toast.delivery 设为 terminal 而不是 system，避免通知发到服务器本地而非你当前操作的终端。herdr --remote 模式需要 SSH 配置正确。

插件到底安全吗？
插件市场是自动索引，不是官方审核。安装插件前检查仓库、提交记录、herdr-plugin.toml 和入口文件，固定到明确的 Git Commit 或 Tag，不要对来源不明的插件使用 --yes 跳过交互确认。

怎么卸载干净？
先 herdr integration uninstall claude && herdr integration uninstall codex，再 herdr server stop，然后根据安装方式卸载二进制，最后备份后删除 ~/.config/herdr。注意 ~/.herdr/worktrees 里有代码，不要直接删。

Windows 能用吗？
原生 Windows 版本是实验性 Beta，限制较多。官方建议 Windows 用户先通过 SSH 连接 Linux 服务器再跑 Herdr，或者在 WSL 里测试。正式生产环境暂不推荐。

Herdr 收费吗？
截至 v0.8.0，核心软件可以直接免费安装使用。官方仓库只列出了企业合作联系方式，没有看到面向个人用户的公开订阅套餐。