4  第 2 章 · 安装与配置

4.1 系统要求

在开始安装之前，请先确认你的系统满足 Herdr 的运行要求。

4.1.1 支持的操作系统

操作系统	支持状态	最低版本要求	备注
macOS (Apple Silicon)	✅ 完全支持	macOS 12.0 (Monterey)	M1/M2/M3/M4 均可，推荐
macOS (Intel)	✅ 完全支持	macOS 12.0 (Monterey)	性能略低于 Apple Silicon
Linux (x86_64)	✅ 完全支持	内核 5.10+	Ubuntu 20.04+ / Debian 11+ / Arch / Fedora 35+
Linux (ARM64)	✅ 完全支持	内核 5.10+	树莓派 4/5、ARM 服务器
Windows	⚠️ Beta	Windows 11 23H2	需要 WSL2 或原生 Terminal

NoteWindows 用户注意

Windows 目前处于 Beta 阶段，有两种使用方式： 1. 原生安装（推荐）：在 PowerShell 中安装，支持基础功能 2. 通过 WSL2：在 WSL2 的 Linux 环境中安装，可获得完整体验（推荐用于生产环境）

4.1.2 硬件要求

资源	最低要求	推荐配置
CPU	2 核	4 核+
内存	512 MB 可用	2 GB+ 可用
磁盘空间	50 MB（仅 Herdr）	200 MB（含 Agent 集成）
终端	支持 256 色	支持 TrueColor（24 位色）

4.1.3 软件依赖

Herdr 的设计理念是尽量减少外部依赖，但以下工具建议预装：

# 这些不是硬性要求，但预装后体验更好
git --version       # 版本控制（几乎所有 Agent 都需要）
node --version      # Node.js（用于 npx skills 等工具）
python3 --version   # Python（部分 Agent 需要）

Tip终端模拟器推荐

Herdr 在以下终端模拟器中表现最佳： - iTerm2（macOS）——最佳鼠标支持和 TrueColor - Ghostty（macOS/Linux）——新一代终端，性能极佳 - WezTerm（全平台）——跨平台，GPU 加速 - Alacritty（全平台）——极简，极致性能 - Windows Terminal（Windows）——微软官方，体验良好

4.2 安装方式

Herdr 提供了多种安装方式，你可以根据自己的偏好选择。

4.2.1 方式一：一键脚本（推荐新手）

这是最简单的安装方式，适用于 macOS 和 Linux：

# 下载并运行安装脚本
curl -fsSL https://herdr.dev/install.sh | sh

脚本会自动完成以下操作： 1. 检测操作系统和架构 2. 下载对应的预编译二进制文件 3. 安装到 /usr/local/bin/herdr（或 ~/.local/bin/herdr） 4. 添加到 PATH（如果需要） 5. 创建默认配置目录

Tip验证下载完整性

安装脚本会自动校验 SHA256 校验和。如果你想手动验证：

# 查看安装后的版本和构建信息
herdr --version
# 输出示例：herdr 0.7.5 (stable, 2026-04-15, commit a3f2b1c)

4.2.2 方式二：Homebrew（macOS 推荐）

如果你使用 macOS 且已经安装了 Homebrew：

# 添加 Herdr 的 tap（如果尚未添加）
brew tap herdrdev/herdr

# 安装 Herdr
brew install herdr

# 后续更新
brew upgrade herdr

Homebrew 的优势： - ✅ 自动管理依赖 - ✅ 统一更新（brew upgrade） - ✅ 轻松卸载（brew uninstall herdr） - ✅ 与其他开发工具共存

4.2.3 方式三：mise（版本管理推荐）

如果你使用 mise（原 rtx）管理工具版本：

# 安装最新稳定版
mise use -g herdr@latest

# 或者安装指定版本
mise use -g herdr@0.7.5

# 安装 preview 频道
mise use -g herdr@preview

# 查看已安装版本
mise list herdr

Note为什么推荐 mise？

如果你需要在多个项目中使用不同版本的 Herdr（例如测试兼容性），mise 允许你为每个项目目录设置不同的版本。只需要在项目根目录创建 .mise.toml：

[tools]
herdr = "0.7.5"

4.2.4 方式四：Nix（NixOS 用户）

如果你使用 Nix 包管理器：

# 使用 Nix Flakes 安装（推荐）
nix profile install github:herdrdev/herdr/v0.7.5

# 或临时运行（不安装到系统）
nix run github:herdrdev/herdr/v0.7.5 -- --version

如果你使用 NixOS，可以在 configuration.nix 中添加：

# configuration.nix
{ pkgs, ... }:
{
  environment.systemPackages = with pkgs; [
    # Herdr 尚未进入 nixpkgs 主仓库，使用 Flake
    # 需要在 flake.nix 中添加 herdr 的 input
  ];
}

4.2.5 方式五：手动下载二进制

如果你不想使用任何包管理器，可以直接从 GitHub Releases 下载：

# 1. 访问 GitHub Releases 页面
# https://github.com/herdrdev/herdr/releases

# 2. 根据你的系统选择对应的文件：
#    - macOS Apple Silicon: herdr-0.7.5-aarch64-apple-darwin.tar.gz
#    - macOS Intel:         herdr-0.7.5-x86_64-apple-darwin.tar.gz
#    - Linux x86_64:        herdr-0.7.5-x86_64-unknown-linux-musl.tar.gz
#    - Linux ARM64:         herdr-0.7.5-aarch64-unknown-linux-musl.tar.gz
#    - Windows:             herdr-0.7.5-x86_64-pc-windows-msvc.zip

# 3. 下载并解压（以 macOS Apple Silicon 为例）
curl -fsSL -o /tmp/herdr.tar.gz \
  https://github.com/herdrdev/herdr/releases/download/v0.7.5/herdr-0.7.5-aarch64-apple-darwin.tar.gz
tar -xzf /tmp/herdr.tar.gz -C /tmp

# 4. 移动到 PATH 目录
sudo mv /tmp/herdr /usr/local/bin/herdr
sudo chmod +x /usr/local/bin/herdr

# 5. 验证安装
herdr --version

Warning手动安装的注意事项

手动安装意味着你需要自己管理更新。建议定期检查 GitHub Releases 页面或关注 Herdr 的 Release 公告。你可以使用 herdr update 命令来检查和安装更新（即使是通过手动方式安装的）。

4.2.6 方式六：Windows PowerShell

Windows 用户可以使用 PowerShell 安装：

# 使用 PowerShell 安装脚本
irm https://herdr.dev/install.ps1 | iex

# 或使用 winget（如果已收录）
winget install herdrdev.herdr

# 或使用 Scoop
scoop bucket add herdr https://github.com/herdrdev/scoop-herdr
scoop install herdr

4.3 验证安装

无论使用哪种安装方式，安装完成后请验证：

# 查看版本号
herdr --version
# 预期输出：herdr 0.7.5 (stable, 2026-04-15)

# 查看构建详情
herdr --version --verbose
# 预期输出包含：commit hash、构建时间、Rust 版本、目标平台

# 查看 PATH 中的位置
which herdr    # macOS/Linux
where herdr    # Windows

Tip首次运行自检

安装完成后，运行以下命令进行自检：

herdr doctor

这个命令会检查： - 二进制文件完整性 ✅ - 配置目录权限 ✅ - 终端兼容性（颜色支持、鼠标支持） ✅ - 已安装的 Agent 集成 ✅ - 系统资源是否充足 ✅

4.4 更新与频道管理

4.4.1 更新 Herdr

Herdr 内置了自更新功能：

# 检查是否有新版本
herdr update --check

# 更新到最新版本（当前频道）
herdr update

# 强制更新（跳过确认）
herdr update --force

4.4.2 频道管理

Herdr 提供两个发布频道：

频道	描述	稳定性	更新频率	适用人群
stable	稳定版	⭐⭐⭐⭐⭐	每 4-6 周	生产环境、日常使用
preview	预览版	⭐⭐⭐	每 1-2 周	尝鲜、测试新功能

# 查看当前频道
herdr channel

# 切换到 preview 频道
herdr channel set preview

# 切换回 stable 频道
herdr channel set stable

# 切换频道后自动更新
herdr channel set preview && herdr update

Note频道切换的影响

切换频道不会影响你现有的配置和数据。所有配置文件（~/.config/herdr/）保持不变。只是二进制文件的来源不同。你可以在任何时候自由切换频道。

4.5 配置文件

4.5.1 配置文件位置

Herdr 的配置文件位于 ~/.config/herdr/ 目录下：

~/.config/herdr/
├── config.toml          # 主配置文件
├── agents/              # Agent 配置
│   ├── claude.toml      # Claude Code 配置
│   ├── codex.toml       # Codex 配置
│   └── ...
├── skills/              # 自定义 Agent Skills
└── sessions/            # 会话数据（自动管理）

4.5.2 首次启动引导

第一次运行 herdr 时，Herdr 会启动交互式引导（onboarding）：

$ herdr

╭─────────────────────────────────────────────╮
│   欢迎使用 Herdr！                           │
│   让我们花 30 秒完成初始设置                  │
╰─────────────────────────────────────────────╯

步骤 1/4：选择你的主要使用场景
  > 1. AI Coding Agent 开发（Claude Code / Codex 等）
    2. 远程服务器管理
    3. 通用终端工作空间

步骤 2/4：检测到以下已安装的 Agent
  ✅ Claude Code (v1.2.3)
  ✅ Codex CLI (v0.9.1)
  ❌ Gemini CLI — 未检测到

步骤 3/4：选择前缀键（prefix key）
  > 1. Ctrl+b（tmux 默认，推荐 tmux 用户）
    2. Ctrl+a（更易按到，推荐新用户）
    3. 自定义

步骤 4/4：设置完成！
  配置文件：~/.config/herdr/config.toml
  输入 `herdr` 开始使用。

4.5.3 主配置文件详解

引导完成后，你会得到一个基础的 config.toml。以下是一个完整的配置示例：

# ~/.config/herdr/config.toml
# Herdr 主配置文件

# ── 基础设置 ──────────────────────────────────
[general]
# 前缀键（触发快捷命令的组合键）
prefix = "C-a"           # Ctrl+a

# 是否启用鼠标支持
mouse = true

# 是否启用 TrueColor（24位色）
true_color = true        # 现代终端建议开启

# 默认 Shell（留空则使用 $SHELL 环境变量）
default_shell = ""

# 启动时自动创建的工作区名称
default_workspace = "main"

# ── Agent 设置 ────────────────────────────────
[agent]
# Agent 状态检测间隔（毫秒）
detection_interval = 500

# Agent 状态变化时是否发送通知
notify_on_status_change = true

# 通知触发的状态（可选：idle, working, blocked, done）
notify_statuses = ["blocked", "done"]

# ── 外观设置 ──────────────────────────────────
[ui]
# 侧边栏宽度（字符数）
sidebar_width = 32

# 侧边栏位置（left / right / hidden）
sidebar_position = "left"

# 主题（dark / light / auto）
theme = "auto"

# 标签栏样式（tabs / segments / compact）
tab_style = "tabs"

# ── Server 设置 ───────────────────────────────
[server]
# 是否在后台运行（允许 detach 后保持运行）
daemon = true

# 会话存储目录
session_dir = "~/.config/herdr/sessions"

# 自动清理超过 N 天的会话
cleanup_after_days = 7

Tip配置文件的优先级

Herdr 配置文件的加载优先级（从高到低）： 1. 命令行参数（herdr --prefix C-s） 2. 项目级配置（./herdr.toml） 3. 环境变量（HERDR_PREFIX=C-s） 4. 用户配置（~/.config/herdr/config.toml） 5. 默认值

4.6 安装 Agent Skill

为了让 AI Agent 更好地与 Herdr 配合工作，建议安装 Herdr 的 Agent Skill。这个 Skill 会让 Agent 理解 Herdr 的概念（工作区、窗格、状态等），从而更智能地使用 Herdr。

# 安装 Herdr Agent Skill（全局安装）
npx skills add herdrdev/herdr --skill herdr -g

# 验证安装
npx skills list | grep herdr
# 预期输出：herdr v0.7.5 [installed, global]

NoteAgent Skill 是什么？

Agent Skill 是一种描述性文件，告诉 AI Agent 如何使用某个工具。安装 Herdr Skill 后，当你对 Claude Code 说「帮我在新的 pane 里启动测试服务器」，它会知道如何调用 Herdr 的分屏命令，而不是给你返回一个不知道怎么执行的 shell 命令。

4.6.1 Skill 的作用

安装 Agent Skill 后，Agent 能够：

能力	未安装 Skill	已安装 Skill
理解「在工作区中分屏」	❌ 不理解	✅ 自动执行
主动报告状态	❌ 不会	✅ 通过标记符与 Herdr 通信
在正确的 pane 中运行命令	❌ 随机选择	✅ 智能选择
响应其他 Agent 的状态	❌ 不能	✅ 感知全局状态

4.7 安装 Agent 集成

Herdr 支持与主流 Coding Agent 的深度集成。集成安装后，Herdr 可以更精确地检测 Agent 状态、支持自定义命令等。

# 查看可用的 Agent 集成
herdr integration list
# 输出：
#   claude    — Claude Code (Anthropic)     [not installed]
#   codex     — Codex CLI (OpenAI)          [not installed]
#   gemini    — Gemini CLI (Google)         [not installed]
#   cursor    — Cursor Agent                [not installed]
#   openclaw  — OpenClaw                    [not installed]
#   aider     — Aider                       [not installed]

# 安装 Claude Code 集成（最常用）
herdr integration install claude

# 安装多个集成
herdr integration install codex gemini

# 安装所有可用的集成
herdr integration install --all

4.7.1 集成安装做了什么

每个集成的安装过程会做以下几件事：

flowchart TD
    A[herdr integration install claude] --> B[检测 Claude Code 是否已安装]
    B --> C{已安装？}
    C -- 否 --> D[⚠️ 提示先安装 Claude Code]
    C -- 是 --> E["创建 Agent 配置文件<br/>~/.config/herdr/agents/claude.toml"]
    E --> F["注入状态标记符<br/>让 Herdr 能识别 Claude 的状态"]
    F --> G["注册自定义命令<br/>如 :claude.new, :claude.review"]
    G --> H[✅ 集成完成]

4.7.2 Agent 配置文件示例

安装 Claude 集成后，会生成 ~/.config/herdr/agents/claude.toml：

# ~/.config/herdr/agents/claude.toml
# Claude Code Agent 集成配置

[agent]
# Agent 名称（显示在侧边栏中）
name = "Claude Code"

# 启动命令
command = "claude"

# 状态检测规则
[detection]
# 工作中状态的输出特征（正则表达式）
working_pattern = "^\\s*[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]"

# 空闲状态的输出特征
idle_pattern = "^claude>\\s"

# 等待输入的特征
waiting_pattern = "\\?\\s*$"

# 完成标记
done_marker = "✨ Done!"

# 自定义命令
[commands]
# 在侧边栏右键菜单中添加的自定义操作
new_task = "claude --message '{prompt}'"
review = "claude --message '请审查当前文件的代码质量'"

4.8 常见安装问题与解决方案

4.8.1 问题 1：command not found: herdr

# 原因：herdr 不在 PATH 中
# 解决方案 1：手动添加到 PATH
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc    # macOS (zsh)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc   # Linux (bash)
source ~/.zshrc  # 或 source ~/.bashrc

# 解决方案 2：创建符号链接
sudo ln -sf /opt/herdr/bin/herdr /usr/local/bin/herdr

# 解决方案 3：查看 herdr 实际安装位置
find / -name "herdr" -type f 2>/dev/null

4.8.2 问题 2：鼠标不工作

# 原因：终端模拟器不支持鼠标报告，或被禁用
# 解决方案 1：在配置中确认鼠标已启用
# 编辑 ~/.config/herdr/config.toml
# [general]
# mouse = true

# 解决方案 2：检查终端模拟器设置
# iTerm2: Preferences → General → Selection → "Enable mouse reporting"
# GNOME Terminal: 菜单 → Preferences → "Enable mouse reporting"

# 解决方案 3：确认终端类型
echo $TERM
# 如果输出不含 "mouse" 相关字样，可能需要设置：
export TERM=xterm-256color

4.8.3 问题 3：颜色显示异常

# 原因：终端不支持 TrueColor 或 TERM 变量设置错误
# 解决方案 1：关闭 TrueColor
# 编辑 ~/.config/herdr/config.toml
# [ui]
# true_color = false

# 解决方案 2：设置正确的 TERM 变量
# 在 ~/.zshrc 或 ~/.bashrc 中添加：
export TERM=xterm-256color

# 对于 tmux 内部使用：
# 如果在 tmux 内部运行 herdr，需要：
export COLORTERM=truecolor

4.8.4 问题 4：herdr update 失败

# 原因：网络问题或权限问题
# 解决方案 1：检查网络
curl -fsSL https://herdr.dev/releases/latest --output /dev/null -w "%{http_code}"
# 应该返回 200

# 解决方案 2：手动下载并覆盖
# 参见"手动下载二进制"部分

# 解决方案 3：检查写入权限
ls -la $(which herdr)
# 如果所有者是 root，需要 sudo：
sudo herdr update

4.8.5 问题 5：Agent 集成安装失败

# 原因：Agent 未安装或版本不兼容
# 诊断步骤：
herdr integration install claude --verbose

# 常见子原因：
# 1. Claude Code 未安装 → 先安装 Claude Code
# 2. Claude Code 版本过旧 → 升级到最新版
# 3. 配置目录权限问题 → sudo chown -R $USER ~/.config/herdr/

Warning遇到其他问题？

1. 运行 herdr doctor 进行全面诊断
2. 查看 Herdr 日志：cat ~/.config/herdr/herdr.log
3. 搜索 GitHub Issues：https://github.com/herdrdev/herdr/issues
4. 加入社区 Discord 寻求帮助：https://discord.gg/herdr

4.9 本章小结

Tip安装要点速查

1. 推荐安装方式：新手用一键脚本，macOS 用户用 Homebrew，多版本管理用 mise
2. 安装后必做：
   • 运行 herdr --version 验证安装
   • 运行 herdr doctor 检查环境
   • 运行 herdr 完成首次引导
3. 推荐配置：
   • 安装 Agent Skill：npx skills add herdrdev/herdr --skill herdr -g
   • 安装 Agent 集成：herdr integration install claude
4. 配置文件：~/.config/herdr/config.toml
5. 更新方式：herdr update（或通过包管理器更新）

4.10 延伸阅读

• 配置文件完整参考：https://herdr.dev/docs/config
• Agent 集成开发指南：https://herdr.dev/docs/integrations
• 自定义 Agent Skill：https://herdr.dev/docs/skills
• Homebrew tap：https://github.com/herdrdev/homebrew-herdr
• 故障排除指南：https://herdr.dev/docs/troubleshooting

---

现在你已经成功安装了 Herdr，让我们在下一章中快速上手，启动你的第一个工作区。