编码代理与终端 · runtime · 验证于 2026-08-28 ✓ 实测验证

herdr

已验证 2026-08-28持久会话/工作区管理实测通过；编码 agent 的终端运行时（worktree + agent 面板）。

编码 agent 的终端运行时：持久会话、工作区/工作树管理、agent 面板与多工具集成

详细版 → 所属问题域：编码代理与终端 遇到问题？去问题空间 →

你会遇到什么

这个工具解决什么问题：多个 Agent 会话在终端里各干各的，没有统一的面板和管理。Herdr 是面向编码 Agent 的终端运行时：持久会话、工作区/worktree 管理、Agent 面板与集成（session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api）。 什么时候用：

  • 你要持久会话（herdr --session main），退出后还能附着回来；
  • 你要在终端里管多个工作区/worktree；
  • 你要一个 Agent 面板/通知面统一看各 Agent 状态。

什么时候别用：单会话、不需要后台 server 与状态管理时——完整客户端会拉起后台进程。 注意事项：重档条目——启动完整客户端会拉起后台 server（socket + 日志 + session 文件）；Rust 单二进制，无运行时依赖。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

它怎么工作：Rust 单二进制（22.7MB，Linux x86_64），release 资产 gh-proxy 下载即用。herdr status/config check 不拉起 server；herdr --session main 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/，退出会话 server 可能常驻）；herdr server stop 停后台 server。 关键概念：

  • server：后台进程（socket + 日志 + session 文件）；
  • session：持久会话（--session 指定名字）；
  • 子命令面：session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api。

装完它动哪里：~/.config/herdr/ + ~/.local/state/herdr/（启动会话后创建）。

快速修复（不想看讲解，直接跑）

note: release 二进制（本环境实测，gh-proxy 加速）；国内 GitHub 直连慢必须加速
curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x herdr
./herdr --version

预期输出: herdr 0.8.2

一步步来

第 1 步：装二进制（为什么 gh-proxy：国内 GitHub 直连慢，实测路径）

讲解：单二进制下载 + chmod 即用，无运行时依赖。国内 GitHub 直连慢，下载地址统一走 gh-proxy 前缀。装完 --version 验证。

curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x herdr
./herdr --version

预期输出: herdr 0.8.2

装好确认：

  • --version 输出 0.8.2；
  • herdr --help 能看到完整子命令面。

卡住怎么办：

  • 下载超时 → 确认网络能到 gh-proxy；换网络（校园网/代理切换）重试；
  • 想全局用 → 把二进制放到 PATH（如 /usr/local/bin）。

第 2 步：状态与配置检查（不拉起 server）

讲解：status 看客户端版本 + channel + server 状态（not running 时给出 socket 路径）；config check 校验配置（无 config.toml 也通过——首次运行以默认配置为准）。这两条先跑，确认环境再进会话。

herdr status

预期输出: client 版本 0.8.2 + channel stable + server 状态（not running 时给出 socket 路径）

herdr config check

预期输出: config: ok（无 config.toml 时也通过——首次运行以默认配置为准）

装好确认：

  • status 正常输出版本与 server 状态；
  • config check 输出 config: ok。

卡住怎么办：

  • status 异常 → 看输出里的 socket 路径与日志位置；
  • config check 报错 → 按提示修正配置（默认配置即可通过）。

第 3 步：进持久会话（会拉起后台 server）

讲解：herdr --session main 进入持久会话终端面。首次运行创建配置与状态目录；退出会话后 server 可能常驻，不用时 herdr server stop。

herdr --session main

预期输出: 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/；退出会话 server 可能常驻）

装好确认：

  • 进入会话终端；
  • 退出后 herdr status 显示 server 状态。

卡住怎么办：

  • 会话起不来 → 先跑 status/config check 看环境；
  • server 常驻想停 → herdr server stop。

怎么确认修好了

第 1 步：确认命令与配置面正常

讲解：status 与 config check 是本工具的两个自检入口——status 看版本与 server 状态，config check 校验配置；两者都过，说明客户端环境是好的。

herdr status
herdr config check

预期输出: 版本 0.8.2 + channel stable + server 状态；config: ok

卡住怎么办：

  • status 异常 → 看输出里的 socket 路径与日志位置；
  • config check 报错 → 按提示修正配置（默认配置即可通过）。

第 2 步：确认会话能进（可选，会拉起后台 server）

讲解：能进入 --session main 的持久会话终端面，说明二进制到运行链路全部通；退出后记得用 herdr server stop 停掉常驻 server。

herdr --session main

预期输出: 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/）

卡住怎么办：

  • 会话起不来 → 先跑 status/config check 看环境；
  • server 常驻想停 → herdr server stop。

其它环境的表现（常见变体）

  • 非 Linux x86_64：官方提供 darwin 等平台二进制（本机未实测，命令面一致）；Windows 无官方原生支持，建议 WSL 内使用。
  • 想全局用：把二进制放到 PATH（如 /usr/local/bin），之后直接 herdr 而非 ./herdr。
  • 后台进程：完整客户端会拉起 server（socket + 日志 + session 文件）；不用时 herdr server stop，配置与状态留在 ~/.config/herdr/ 与 ~/.local/state/herdr/，不会自动删除。

日常使用

启动与入口

  • 会话：herdr --session <名字>；
  • 状态：herdr status；
  • 后台 server：herdr server stop 停止。

常用操作

操作一：查看命令面（本环境实测）

herdr --help

预期输出: session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api 等子命令

操作二：状态检查（本环境实测；不拉起 server）

herdr status

预期输出: client 版本 0.8.2 + channel stable + server 状态（not running 时给出 socket 路径）

操作三：配置校验（本环境实测）

herdr config check

预期输出: config: ok（无 config.toml 时也通过——首次运行以默认配置为准）

操作四：启动/附着持久会话（会拉起后台 server）

herdr --session main

预期输出: 进入持久会话终端面（首次运行创建 ~/.config/herdr/ + ~/.local/state/herdr/agent-detection/；退出会话 server 可能常驻）

操作五：停止后台 server

herdr server stop

预期输出: server stopped（通过 socket API）

数据与目录

  • 配置：~/.config/herdr/；
  • 状态/agent 检测：~/.local/state/herdr/。

卸载与清理

note: 单二进制删除（按实际安装路径）；专属目录自动删；运行中的 server 先停
herdr server stop 2>/dev/null || true
rm -f /usr/local/bin/herdr ~/.local/bin/herdr
rm -rf ~/.config/herdr ~/.local/state/herdr
command -v herdr >/dev/null 2>&1 && echo '残留: herdr 仍存在' || echo 'herdr removed: OK'

预期输出: herdr removed: OK

依赖警告

  • 版本：[0.8.2, 0.8.2] 锁定（收录实测版本）。
  • 环境：Linux x86_64；无运行时依赖；/usr/local/bin 可写（或放用户 PATH）。
  • 网络：GitHub 直连慢，必须 gh-proxy 前缀（实测路径）；官方 install.sh 走 herdr.dev（未实测）。
  • 写面：~/.config/herdr/ + ~/.local/state/herdr/（启动会话后创建）。
  • 后台进程：完整客户端会拉起 server（socket + 日志 + session 文件）。
  • 共装：冲突矩阵无对子（专属目录写面，与常用工具不重叠）；组合包 combo-governance-stack / combo-env-init 均有其成员位。

FAQ（常见问题）

  • 问：为什么退出会话后 server 还在？答：持久会话设计——server 可能常驻；不用时 herdr server stop。
  • 问：下载慢？答：用安装段的 gh-proxy 前缀；官方 install.sh（herdr.dev）未实测。
  • 问：和别的工具冲突吗？答：冲突矩阵无对子——专属目录写面，不碰 ~/.claude.json 等共享注册面。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。
验证证据
  • 实测：实测记录（本地留存）（2026-08-28，release 二进制下载 + version/help/status/config check 冒烟）；实测复现日志（2026-08-30）（gh-proxy 下载二进制 + --version 复核 + update 命令面）；实测复现日志（2026-08-30）（agent-guide 推荐命令 npx skills add herdrdev/herdr --skill herdr -g 实测成功 + 写面检查）。
  • 未实测：持久会话与 server 启动（会拉起后台进程，未在本环境长跑）；官方 install.sh（herdr.dev）。

引用：herdr · 验证于 2026-08-28 · v0.8.2~0.8.2

相关问题（问题域）

出问题了？排障方案

排障手册：herdr

症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：维护者 检索素材（herdrdev/herdr issue #3232/#3261 匿名检索 2026-08-28）+ 本市场实测（2026-08-28 cli-smoke v0.8.2 + 2026-08-29 server 生命周期实测）。
采集纪律：零账号匿名检索；未碰 GitHub 写。check-words HARD 0。

基本信息

  • 条目名称：herdr（herdrdev/herdr，Apache-2.0，v0.8.2 收录）
  • 求助信号：help=185 / recent3m=185 / trend=up（demand 基线 demand-signal-20260828）
  • 角色：anchor；分类：runtime
  • 本市场安装路径：curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64 && chmod +x herdr && ./herdr --version（2026-08-28 实测；gh-proxy 加速，GitHub 直连慢）
  • 命令名：herdr（小写；常见拼写 herder/herdr 混淆，无同名热门项目）；子命令面：session/workspace/worktree/tab/notification/agent/pane/integration/server/config/channel/api/completion

症状 → 原因 → 解法 → 验证证据

1. herdr server start 无效 / 后台 server 未拉起

症状

输入 herdr server start 不启动 server，只打印 server 子命令列表（help 文本）；herdr status 显示 server: not running；~/.config/herdr/ 下没有 herdr.sock。

原因

v0.8.2 命令面里不存在 server start 子命令。正确启动面有两个：

  • herdr（TUI 完整客户端）——正常使用路径，自动拉起后台 server；
  • herdr server（headless）——前台运行 server，脚本化时用 nohup herdr server & 放后台；
  • 停止面 = herdr server stop（经 API socket）；确认面 = herdr status（server: running / not running）。

解法

  1. 交互使用：直接 herdr 开 TUI（server 自动拉起），无需显式 start。
  2. 脚本化：nohup herdr server > /tmp/herdr-server.log 2>&1 &，然后 herdr status 确认 running。
  3. 停止：herdr server stop；再次 herdr status 确认 not running。
  4. 写面确认：~/.config/herdr/ 下应出现 .plugins.lock、herdr-client.sock、herdr.sock、herdr-server.log。

验证证据

本站实测记录（2026-08-29）

  • 2026-08-28：herdr 完整客户端启动 12s 验证创建 ~/.config/herdr/（.plugins.lock、herdr-client.log、herdr-server.log、session.json）+ ~/.local/state/herdr/agent-detection/（19 个 agent 清单 toml，只读情报文件）；工作区（cwd）零写入。

2. Windows PowerShell 无法安装

症状

Windows 系统用 PowerShell 执行官方安装命令失败（下载被重置/脚本执行报错）。

原因

PowerShell 的 Web 下载对 GitHub release 支持差/易被重置；官方安装器 08-22 已修（issue #3131 避免 PowerShell web 下载、#3133 增加本地 cmd installer bootstrap），但 issue #3232（open 2026-08-25）仍有人踩旧路径。

解法

  1. 升级到含修复的安装器，或直接下载二进制（herdr-linux-x86_64 对应 Windows 资产），不用 PowerShell 下载。
  2. 国内网络：二进制走 gh-proxy 前缀加速。

验证证据

  • 素材：herdrdev/herdr issue #3232（open，2026-08-25）/ #3131 / #3133（closed 修复安装器），2026-08-28 匿名检索。
  • 本环境 WSL Linux，Windows PowerShell 路径未实测（如实标注）。

3. SSH 会话中文显示/输入失败

症状

通过 SSH 远程使用 herdr 时，中文显示乱码或输入无效。

原因

与终端编码/远程 locale 相关（issue #3261 open，2026-08-26）；非 herdr 本体缺陷信号。

解法

  1. 检查远程会话 locale：locale 应含 UTF-8（如 LANG=en_US.UTF-8 / zh_CN.UTF-8）。
  2. SSH 终端编码统一 UTF-8；tmux 类终端面确认 set -g status-utf8（如适用）。

验证证据

  • 素材：issue #3261（open，2026-08-26）匿名检索摘要。
  • 本环境无远端会话，未实测（如实标注）。

所属组合包 （2）

矩阵暂无该工具对子。

← 返回工具货架 ｜ 遇到其它问题？去 问题空间 提交求助卡 ｜ 预检与证据记录由维护流程本地留存，仅公开结论与来源