本页面的翻译由 LLM 生成。如果你发现翻译有误,请在 GitHub 上提交 issue 告诉我们。

集成

Herdr 会自动检测它支持的智能体。安装智能体的集成后,Herdr 可以在服务器重启后恢复同一个会话。部分集成还会直接上报智能体的状态。哪些智能体由 Herdr 支持、哪些智能体自己支持 Herdr,见智能体。

当你想要智能体原生会话恢复、直接生命周期上报,或两者都要时,使用集成。完整的状态权威模型见智能体。

安装集成

在 Herdr 中打开设置,用集成标签页为 PATH 上发现的智能体安装推荐集成,或手动运行命令:

herdr integration install pi
herdr integration install omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install devin
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install mastracode
herdr integration install qodercli
herdr integration install qwen
herdr integration install letta
herdr integration install cursor
herdr integration install antigravity-cli
herdr integration install grok

卸载集成

herdr integration uninstall pi
herdr integration uninstall omp
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall copilot
herdr integration uninstall devin
herdr integration uninstall droid
herdr integration uninstall kimi
herdr integration uninstall opencode
herdr integration uninstall kilo
herdr integration uninstall hermes
herdr integration uninstall mastracode
herdr integration uninstall qodercli
herdr integration uninstall qwen
herdr integration uninstall letta
herdr integration uninstall cursor
herdr integration uninstall antigravity-cli
herdr integration uninstall grok

Herdr 对 Linux/macOS 上的集成配置和所有平台的新文件使用原子保存；Windows 上的现有文件先备份再原地更新，以保留权限。如果 Windows 提示存在备份，请在重试前关闭智能体并检查配置：未完成的 .herdr-backup.pending 只能在确认配置正确后删除，不能用于恢复；完整 .herdr-backup 的内容可在需要时写回现有文件（若文件已丢失，先设置其预期权限），确认配置正确后再删除备份。

Herdr 如何使用集成

每个集成都会告诉 Herdr 智能体当前所在的会话,这样 Herdr 就能在服务器重启后恢复它。用 [session] resume_agents_on_restore = false 可以关闭。

Pi、OMP、Kimi Code CLI、OpenCode、Kilo Code CLI 和 MastraCode 的集成还会上报智能体的状态。在它们上报期间,Herdr 使用这些上报,而不是读取屏幕。其他集成则把状态交给屏幕检测。

原生会话恢复需要最新的 Herdr 集成: Pi 集成版本 2、OMP 版本 3、Claude Code 版本 6、Codex 版本 5、GitHub Copilot CLI 版本 2、Devin CLI 版本 2、Droid 版本 2、Kimi Code CLI 版本 3、Qoder CLI 版本 2、Qwen Code 版本 1、Letta Code 版本 1、Cursor Agent CLI 版本 1、Grok CLI 版本 2、OpenCode 版本 5、Kilo Code CLI 版本 1、Hermes Agent 版本 5、MastraCode 版本 1、Antigravity CLI 版本 1。用 herdr integration status 查看已安装版本。

集成你自己的智能体

如果你在开发编码智能体,可以在不为 Herdr 添加原生支持的情况下,从你自己的代码向 Herdr 上报它的状态和恢复命令。参阅为你的智能体添加 Herdr 支持。

Pi

安装 Pi 集成:

herdr integration install pi

Herdr 把内置扩展写入:

~/.pi/agent/extensions/herdr-agent-state.ts

如果设置了 PI_CODING_AGENT_DIR,Herdr 会改为写入 $PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts。如果 Pi agent 目录已经存在,Herdr 会创建 extensions 目录。卸载只删除那个扩展文件。

OMP

安装 OMP 集成:

herdr integration install omp

Herdr 把内置扩展写入:

~/.omp/agent/extensions/herdr-omp-agent-state.ts

如果设置了 PI_CODING_AGENT_DIR,Herdr 会改为写入 $PI_CODING_AGENT_DIR/extensions/herdr-omp-agent-state.ts。如果 OMP agent 目录已经存在,Herdr 会创建 extensions 目录。卸载只删除那个扩展文件。

OMP 集成通过 Herdr 的 socket API 上报智能体标签 omp、生命周期状态和原生会话身份。它不需要对 omp 可执行文件做原生进程检测,并且 Herdr 可以在服务器重启后用 omp --resume=<session> 恢复 OMP 窗格。

Claude Code

安装 Claude Code 钩子:

herdr integration install claude

该钩子在会话启动时把 Claude Code 的会话身份上报给本地 Herdr socket。Claude Code 的状态来自 Herdr 的屏幕清单检测。

Claude 集成 v10 仅匹配文档列出的 SessionStart 来源: startup、resume、clear、compact 和 fork。这会阻止 Grok 的 new 和 load 事件启动导入的 Herdr Claude 钩子,而不会禁用其他 Claude 兼容钩子。升级后请重新安装 Claude 集成,以迁移原有的通配匹配规则。Claude 新增来源值时需要更新集成。

Herdr 默认使用 ~/.claude,设置了 CLAUDE_CONFIG_DIR 时使用后者。Claude 配置目录必须已经存在。安装会写入 hooks/herdr-agent-state.sh,并向 settings.json 添加 Herdr 钩子条目。卸载会移除匹配的钩子条目并删除钩子脚本。

Codex

安装 Codex 钩子:

herdr integration install codex

Codex 钩子通过与其他集成相同的本地 socket API 上报会话身份。Codex 的状态来自 Herdr 的屏幕清单检测。

Herdr 默认使用 ~/.codex,设置了 CODEX_HOME 时使用后者。Codex 配置目录必须已经存在。安装会写入 herdr-agent-state.sh、更新 hooks.json,并确保 config.toml 中有 [features] hooks = true。如果存在已弃用的顶层 codex_hooks 标志,它也会一并移除。卸载会从 hooks.json 中移除 Herdr 条目并删除钩子脚本,但不改动 config.toml。

GitHub Copilot CLI

安装 GitHub Copilot CLI 钩子:

herdr integration install copilot

Copilot 钩子通过与其他集成相同的本地 socket API 上报会话身份。Copilot 的状态来自 Herdr 的屏幕清单检测。

Herdr 默认使用 ~/.copilot,设置了 COPILOT_HOME 时使用后者。Copilot 配置目录必须已经存在。安装会写入 hooks/herdr-agent-state.sh,并向 settings.json 添加一个 SessionStart 钩子条目。卸载会从 settings.json 中移除 Herdr 条目并删除钩子脚本。

在 Copilot 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 copilot --resume=<id> 恢复该窗格。

Devin CLI

安装 Devin CLI 钩子:

herdr integration install devin

该钩子从 Devin 的会话、提示、工具使用、权限和停止事件中上报原生会话身份。Devin 的状态仍来自 Herdr 的屏幕清单和 OSC 检测,因为 Devin 钩子不会在每次权限取消或用户中断后都发出可靠的状态转换。

设置了 XDG_CONFIG_HOME 时,Herdr 使用 $XDG_CONFIG_HOME/devin。否则,在 Linux 和 macOS 上使用 ~/.config/devin,在 Windows 上使用 %APPDATA%\devin。Devin 配置目录必须已经存在。安装在 Unix 上写入 herdr-agent-state.sh,在 Windows 上写入 herdr-agent-state.ps1,并向 config.json 添加 Herdr 钩子条目。钩子在 Devin 运行期间刷新会话引用。卸载会从 config.json 中移除 Herdr 条目并删除钩子脚本。

Herdr 用 devin --resume <id> 恢复保存的 Devin 会话。无论钩子是否安装,屏幕清单检测始终是状态权威。

Kimi Code CLI

安装 Kimi Code CLI 钩子:

herdr integration install kimi

该钩子向 Herdr 上报 Kimi 的会话身份和生命周期状态,用于原生恢复和权威的 idle、working、blocked 状态。需要 Kimi Code CLI 0.14.0 或更新版本。

Herdr 默认使用 ~/.kimi-code,设置了 KIMI_CODE_HOME 时使用后者。Kimi Code 配置目录必须已经存在。安装会写入 hooks/herdr-agent-state.sh,并在 config.toml 中追加 Herdr 管理的 [[hooks]] 条目。卸载会移除 Herdr 管理的配置块并删除钩子脚本。

Herdr 用 kimi --session <id> 恢复保存的 Kimi 会话。

Droid

安装 Droid 钩子:

herdr integration install droid

Droid 钩子通过与其他集成相同的本地 socket API 上报会话身份。生命周期状态仍来自 Herdr 的屏幕清单检测,因为 Droid 钩子没有覆盖所有生命周期转换。

Herdr 的 Droid 钩子使用 ~/.factory。Factory 配置目录必须已经存在。安装会写入 hooks/herdr-agent-state.sh,向 settings.json 添加 Herdr 的 SessionStart 钩子条目,并在 hooks.json 中存在旧的 Herdr Droid 钩子条目时将其移除。卸载会从两个配置文件中移除 Herdr 条目并删除钩子脚本。

在 Droid 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 droid --resume <id> 恢复该窗格。

OpenCode

安装 OpenCode 插件:

herdr integration install opencode

该集成支持 OpenCode V1 1.18.29 及更高版本，以及 OpenCode V2（已验证 beta 19242）。OpenCode 配置目录必须已经存在。Herdr 将服务端入口安装到 ~/.config/opencode/plugins/herdr-agent-state.js，并在该配置目录安装共享 TUI 插件 herdr-tui-session.js 和 V2 TUI 入口 herdr-opencode/tui.js。

安装会在 tui.jsonc 中注册 V1 TUI 插件，并在 cli.json 中注册 V2 TUI 插件，同时保留其他设置和插件。tui.json 中已有的 V1 注册也视为已安装,会直接复用而不创建 tui.jsonc。卸载会从两个 TUI 配置文件中移除 Herdr 注册,同时保留文件和其他设置。如果 OpenCode 仍有 V1 TUI 偏好需要迁移(tui.json 或 kv.json),Herdr 会推迟注册，以便首次启动时执行迁移；此时请先启动一次 opencode2，然后重新安装集成。否则 Herdr 会创建 cli.json 并注册插件。安装后请重启 OpenCode TUI。卸载会删除受管理的插件文件及其配置条目。

V2 生命周期上报在窗格本地的 TUI 中运行。即使多个窗格共享同一个 OpenCode 服务端，事件也只归属于该 TUI 选中的根会话。完成和中断会清除工作状态；待处理的权限请求、表单以及执行失败会使窗格保持阻塞。V2 Mini 和无界面客户端不运行 TUI 插件，因此不提供此生命周期上报。

V1 TUI 跟踪窗格选中的会话及其后代。只要其中任何会话仍在忙碌或重试，就保持 working；存在待处理的权限请求或问题时保持 blocked。连接时会读取已有活动，已取消工具的请求不会在重新连接后再次变成阻塞项。查看子代理时保留原来的会话范围；直接连接子会话时只跟踪它及其后代，不包括兄弟会话。

本地 V1 的 opencode run 和 opencode --mini 保留原有服务端钩子；此变更不会为 Mini 或无界面客户端添加窗格本地的生命周期上报。更新集成后，请同时重启共享 OpenCode 服务器及其 TUI，避免旧服务端上报覆盖窗格本地状态。

该插件在 OpenCode 运行于 Herdr 窗格内时上报生命周期状态和会话身份。在 OpenCode 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 opencode --session <id> 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。

Kilo Code CLI

安装 Kilo Code CLI 插件:

herdr integration install kilo

Herdr 把插件写入 ~/.config/kilo/plugin/herdr-agent-state.js。Kilo 配置目录必须已经存在。卸载只删除那个插件文件。

该插件在 Kilo 运行于 Herdr 窗格内时上报生命周期状态和会话身份。在 Kilo 发出携带会话信息的事件后,Herdr 可以用上报的会话 id 通过 kilo --session <id> 恢复该窗格。插件未安装时,屏幕清单检测仍然可用。

Hermes Agent

安装 Hermes Agent 插件:

herdr integration install hermes

Herdr 写入 Hermes 主目录下的 plugins/herdr-agent-state/,并在 Hermes 主目录的 config.yaml 中启用 herdr-agent-state。HERMES_HOME 在 Unix 上默认为 ~/.hermes,在 Windows 上默认为 %LOCALAPPDATA%\hermes。Hermes 配置目录必须已经存在。安装后请重启 Hermes 以加载插件。卸载会删除插件目录,并从 plugins.enabled 中移除 herdr-agent-state。

该插件在 Hermes 运行于 Herdr 窗格内时上报可恢复的会话 id。Herdr 使用屏幕清单检测 working、idle 和 blocked,并可用上报的会话 id 通过 hermes --resume <id> 恢复该窗格。

Qoder CLI

安装 Qoder CLI 钩子:

herdr integration install qodercli

该钩子向 Herdr 上报 Qoder CLI 的会话身份,用于原生恢复。生命周期状态仍来自 Herdr 的屏幕清单检测,因为 Qoder 钩子没有覆盖所有生命周期转换。

Herdr 默认使用 ~/.qoder,设置了 QODER_CONFIG_DIR 时使用后者。Qoder 配置目录必须已经存在。安装会写入 hooks/herdr-agent-state.sh,并向 settings.json 添加 Herdr 钩子条目。卸载会移除匹配的钩子条目并删除钩子脚本。

Herdr 用 qodercli --resume <id> 恢复保存的 Qoder CLI 会话。

钩子未安装时,屏幕清单检测仍然可用。

Qwen Code

安装 Qwen Code 钩子:

herdr integration install qwen

SessionStart 钩子只上报用于原生恢复的会话身份。生命周期状态仍由 Herdr 的屏幕清单检测决定。

Herdr 默认使用 ~/.qwen,设置了 QWEN_HOME 时使用后者。Qwen 配置目录必须已经存在。安装会写入 hooks/herdr-agent-session.sh（Windows 上为 hooks/herdr-agent-session.ps1）,并向 settings.json 添加 Herdr 条目。卸载只移除匹配条目和托管脚本。

Herdr 用 qwen --resume <id> 恢复保存的 Qwen Code 会话。

Letta Code

Letta Code 集成安装是实验性的 CLI 专用功能，不在 Settings 的集成列表或 JSON 集成 API 中提供。herdr integration status 将其显示为 letta (experimental)。智能体检测和 herdr agent start --kind letta 不受此安装方式限制，均已支持。

安装 Letta Code 钩子:

herdr integration install letta

静默的 SessionStart 钩子会上报会话 ID,用于原生恢复。Letta Code 状态仍来自 Herdr 的屏幕清单检测。

Herdr 使用 ~/.letta。配置目录必须已经存在。安装会写入 hooks/herdr-agent-session.sh（Windows 上为 hooks/herdr-agent-session.ps1）,并向 settings.json 添加 Herdr 条目。卸载只移除匹配条目和托管脚本。

Herdr 用 letta --conversation <id> 恢复命名会话。它把默认会话记录为 default:<agent-id>,并用 letta --conversation default --agent <agent-id> 恢复该会话。

Cursor Agent CLI

安装 Cursor Agent CLI 钩子:

herdr integration install cursor

该钩子在 Cursor Agent CLI 运行于 Herdr 窗格内时,通过 Cursor 的 sessionStart 钩子上报会话身份。Cursor 的状态来自 Herdr 的屏幕清单检测。

Herdr 默认使用 ~/.cursor,设置了 CURSOR_CONFIG_DIR 时使用后者。Cursor 配置目录必须已经存在。安装会写入 herdr-agent-state.sh（Windows 上为 herdr-agent-state.ps1）,并向 hooks.json 添加 Herdr 的 sessionStart 条目。卸载会移除匹配的钩子条目并删除钩子脚本。

在 Cursor 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 cursor-agent --resume <id> 恢复该窗格。Herdr 恢复窗格时,cursor-agent 命令必须在 PATH 上;Herdr 不会启动通用的 agent 命令。

MastraCode

安装 MastraCode 钩子:

herdr integration install mastracode

该钩子向 Herdr 上报 MastraCode 生命周期状态和线程身份,用于权威的 idle、working、blocked 状态和原生恢复。MastraCode 没有屏幕清单兜底;当 MastraCode 在 Herdr 窗格内运行时,状态来自该钩子。

Herdr 使用 ~/.mastracode。安装会写入 hooks/herdr-agent-state.sh（Windows 上为 hooks/herdr-agent-state.ps1）,并把 Herdr 命令条目添加到 hooks.json;目录不存在时会创建。卸载会删除匹配的钩子条目和钩子脚本。

Herdr 用 mastracode --thread <id> 恢复保存的 MastraCode 线程。

Antigravity CLI

安装 Antigravity CLI 钩子:

herdr integration install antigravity-cli

Herdr 默认使用 ~/.gemini/config/,设置了 ANTIGRAVITY_CLI_CONFIG_DIR 时使用后者。这是 Antigravity CLI 读取全局自定义配置的目录,并且必须已经存在。安装会写入 hooks/herdr-agent-state.sh（Windows 上为 herdr-agent-state.ps1）,并向 hooks.json 添加由 Herdr 管理的 herdr 块。Antigravity CLI 按钩子名称管理 hooks.json,因此安装只会重写该块,不会改动其他命名钩子。卸载会移除 herdr 块并删除钩子脚本。

该集成仅上报会话。它会上报窗格当前运行的对话,但不上报智能体状态,因此 Herdr 仍根据 Antigravity CLI 在屏幕上绘制的内容判断 working、idle 和 blocked。

钩子在 PreInvocation 时运行,所以 Herdr 会在发送第一个提示词后获知对话。此后,Herdr 服务器重启时可以用 agy --conversation <id> 恢复窗格。

Grok CLI

安装 Grok CLI 钩子:

herdr integration install grok

该钩子在 Grok CLI 运行于 Herdr 窗格内时,通过 Grok 的 SessionStart 钩子上报会话身份。Grok 的状态来自 Herdr 的屏幕清单检测。

Herdr 默认使用 ~/.grok,设置了 GROK_HOME 时使用后者。Grok 配置目录必须已经存在。Grok 会合并该目录中的所有 hooks/*.json 文件,因此安装会写入独立的 hooks/herdr.json,其中包含 Herdr 的 SessionStart 条目,并同时写入 hooks/herdr-agent-state.sh（Windows 上为 hooks/herdr-agent-state.ps1）;它不会修改其他钩子文件。卸载只会删除这两个由 Herdr 管理的文件。

Grok 发出会话启动事件后,Herdr 可以用上报的会话 id 通过 grok --resume <id> 恢复窗格。

自定义状态标签

集成只把生命周期状态作为语义状态上报。例如,上报智能体为 working 时,不在生命周期报告中添加展示字段。

herdr pane report-agent w1:p1 \
  --source custom:docs \
  --agent docs-bot \
  --state working

与 Herdr 管理的集成并行运行的用户钩子,应该使用元数据而不是 report-agent。元数据只改变展示,不会夺走集成对 idle、working、blocked 或会话恢复的权威。--agent 和 --applies-to-source 只守卫展示字段 (--title、--display-agent 和 --state-label)。令牌补丁始终生效;上报方负责清除或刷新 TTL。--display-agent 修改显示名称。

herdr pane report-metadata "$HERDR_PANE_ID" \
  --source user:claude-title \
  --agent claude \
  --title "Refactor auth middleware" \
  --display-agent "Claude: auth" \
  --token summary="refactor auth" \
  --state-label working="refactoring auth" \
  --ttl-ms 3600000

令牌和状态标签只影响视觉。等待、通知和工作区汇总仍使用语义状态。

调试集成状态

列出已知的智能体:

herdr agent list

需要验证 Herdr 能看到什么时,读取窗格:

herdr pane read w1:p1 --source recent --lines 50

如果集成状态看起来不对,先确认智能体运行在 Herdr 内部,并且相关的钩子或插件是为同一个用户账号安装的。