Herdr GPUI：安装与工作流
编程 Agent 实用指南
Herdr GPUI 是连接独立安装的 Herdr 后台程序的第三方桌面客户端。在这里了解两个项目的分工、准备运行环境，并建立你的第一个编程 Agent 工作流。先完成一个本地项目，再增加并行任务或远程主机。
同样的机器。 更多的思考。
工作中…
空闲
阻塞
先区分三个部分：Herdr 管理终端进程与会话状态，桌面客户端提供图形界面，编程 Agent 使用自己的安装、账号和配置完成开发任务。界面连接成功与 Agent 能正常工作，是需要分别验证的两件事。
GPUI 是构建客户端所用的 Rust 界面框架，不是 AI 模型或模型服务商。理解这层关系，有助于出错时找到需要检查的组件。本站与桌面客户端项目均独立于 Herdr 官方。
阅读 Herdr 核心概念
桌面界面展示 Herdr 后台程序中的终端会话与 Agent 活动，真正执行编码任务的仍是已经安装的 Agent。发布包和技术细节以客户端仓库为准，本指南帮助你理解安装顺序与验证步骤。
查看客户端仓库先安装后台程序，再单独安装桌面客户端。下面的命令按操作系统安装 Herdr 并启动终端界面。安装图形客户端不会替你安装或升级后台程序；请记住两个组件各自的安装方式，以便以后选择正确的更新方法。
$ brew install herdr
$ herdrmacOS 原生客户端
使用 Homebrew、系统为 macOS 14.2 或更新版本时，可用下列额外命令安装并打开客户端。排查桌面连接失败前，先确认终端能够找到 herdr 命令。
brew install penso/tap/herdr-gpui
open -a HerdrLinux 与 Windows 客户端构建仍属实验阶段。请按系统与处理器架构选择发布包，并检查当前要求和限制。有可下载的软件包，不代表各平台都支持全部桌面功能。
客户端下载与平台要求- 1
准备一个小项目
选择熟悉的仓库和结果明确的小任务，例如解释一个模块。首次尝试不宜直接对陌生代码库进行大范围修改。
- 2
打开工作区
在项目目录运行 herdr。工作区组织项目，标签页组织相关视图，窗格承载终端进程。使用清楚的名称，方便识别每个项目与任务。
- 3
运行一个已安装的 Agent
先完成 Agent 自身的认证，再在窗格中启动 Claude Code、Codex、OpenCode 或 Pi。增加布局前，确认它能正常启动并访问目标项目。
- 4
检查结果，再增加窗格
检查第一次回答和实际文件修改。分割窗格与切换工作区可参考快速开始文档。一个正常运行的单 Agent 会话，也能成为后续排障的参照。
Herdr 在现有终端中运行，GPUI 则提供独立桌面客户端。按界面偏好、系统要求、远程访问与会话行为选择，并验证一个完整流程：打开项目、运行 Agent、检查修改、重新连接。
并行工作从独立任务和明确负责人开始。例如，一个 Agent 调查失败的测试，另一个解释受影响模块；汇总发现后再授权重叠编辑。若两个任务都要改文件，可以使用独立 Git 工作树，让每个任务拥有自己的分支与工作目录。
不同窗格并不等于文件隔离：两个终端可能指向同一份检出。为每个任务写明范围、预期结果与验证方式。可以让一个 Agent 先调查失败原因并报告修复建议，再让另一个在独立工作树中更新文档。
合并前逐一检查结果。更多可见会话便于观察进度，但布局本身不保证正确性、安全合并或更快交付。只有任务足够独立、你有时间检查输出时，才增加并发。
Herdr 显示工作中、阻塞、完成、空闲等 Agent 状态，帮助你在多个项目中判断下一步看哪里。状态是导航线索：遇到阻塞时，打开终端阅读实际请求。
显示完成后，仍需检查修改与执行过的验证，再认定任务结束。状态检测和集成随 Agent 而异。状态异常时先查看终端输出和集成配置，不要直接推断底层任务已经停止。
先确认本地会话可用，再添加远程主机。验证普通 SSH 访问，并检查远端是否具备任务所需的后台程序、项目文件、Agent CLI 和认证。每台机器拥有自己的运行时与进程；连接主机不会自动复制本地仓库、工具或账号配置。
原生客户端支持保存 SSH 主机，但其平台限制与 Herdr 终端界面不同。按客户端当前要求操作，不要假设所有前端都支持全部后台功能。先在远程项目执行只读任务，允许编辑前核对主机与工作目录。
Herdr 区分分离客户端与停止服务器。正常分离时，终端进程可以在后台继续运行；服务器或机器重启是另一种情况，原进程不会存活。会话恢复可能找回布局并续接受支持的 Agent 对话，但不会保存所有运行程序的完整状态。
依赖恢复行为前，先阅读会话状态文档。长任务应使用版本控制并保存有意义的进展。重新连接后，先检查终端和仓库状态，避免重复启动同一个任务。
桌面应用找不到 Herdr 时，先检查后台程序是否已安装、是否能被发现。重新安装编程 Agent 通常无法解决后台程序缺失。终端能连接但 Agent 无法启动时，单独运行 Agent 命令并阅读它自己的认证或配置错误。
只有远程设备失败时，先验证 SSH，再修改本地无关设置。显示异常时，区分客户端偏好与 Herdr 共享设置。持久 GUI 覆盖应写入 config-gpui.local.toml；config-gpui.toml 是可能被替换的受管理默认配置。编辑前先查阅客户端文档。
求助时记录操作系统、客户端版本、后台程序版本、失败操作与准确错误，复制日志前移除凭据。具体信息可以帮助区分网络、运行时、Agent 与显示问题，而不是把所有失败混在一起。
继续阅读安装详解、独立 Agent 工作树的任务规划，或连接排障清单。这些指南围绕具体问题展开，不重复首页概览。涉及版本行为时，请同时参考上游文档。
Herdr GPUI 是 Herdr 官方应用吗？
不是。客户端仓库明确说明该项目与 Herdr 无隶属关系，也不由 Herdr 官方背书或支持。本站同样是独立指南；发布与支持信息请以各项目上游资料为准。
使用界面需要 AI 账号吗？
账号与模型要求取决于你运行的编程 Agent。安装 Herdr 或原生客户端不会提供模型权限，也不会配置 Agent 凭据。请单独完成 Agent 设置，并验证它的命令可以正常运行。
应该一开始就使用多个 Agent 吗？
先运行一个会话并检查结果。能够划分独立任务、检查输出后，再增加并行工作。多个窗格本身不能隔离文件，也不能保证修改安全。
页面中的工作区图片是实时会话吗？
不是。图片用于说明工作方式，不是浏览器里运行 Agent 的截图。软件需要在你自己的电脑上安装运行，步骤生成器只供你检查并复制命令。