16  第14章 配置详解

16.1 配置文件概览

Herdr 使用 TOML 格式的配置文件，所有配置集中在一个文件中管理。配置采用分区（section）设计，每个分区对应一类功能模块。

16.1.1 配置文件位置

平台	路径
macOS	~/.config/herdr/config.toml
Linux	~/.config/herdr/config.toml
Windows	%APPDATA%\herdr\config.toml

16.1.2 打印默认配置

使用以下命令查看 Herdr 的完整默认配置：

# 打印默认配置到终端
herdr --default-config

# 保存到文件作为起始模板
herdr --default-config > ~/.config/herdr/config.toml

16.1.3 配置热重载

修改配置文件后，无需重启 Herdr，执行热重载即可生效：

# 热重载配置
herdr server reload-config

Note

热重载会立即应用大部分配置项。少数需要重启的项（如 default_shell）会在重载时提示。

---

16.2 配置项完整参考

16.2.1 [terminal] — 终端设置

控制 Herdr 内部终端模拟器的行为。

[terminal]
default_shell = "zsh"        # 默认 shell：zsh / bash / fish / nushell
shell_mode = "terminal"      # terminal（交互式）/ shell（原始 shell）
new_cwd = "inherit"          # 新窗格工作目录：inherit（继承当前）/ home / last

配置项	类型	默认值	说明
default_shell	string	"zsh"	新窗格使用的默认 shell
shell_mode	string	"terminal"	terminal 提供完整终端模拟；shell 为原始模式
new_cwd	string	"inherit"	新窗格的初始工作目录策略

Tip

如果你使用 fish 或 nushell，确保已安装并配置好对应的 shell 环境变量。

16.2.2 [worktrees] — Git Worktree 设置

[worktrees]
directory = "~/.cache/herdr/worktrees"  # worktree 存储目录

Herdr 的多 Agent 并行开发依赖 Git worktree。每个 Agent 在独立的 worktree 中操作，避免文件冲突。

配置项	类型	默认值	说明
directory	string	"~/.cache/herdr/worktrees"	worktree 文件存放路径

16.2.3 [remote] — 远程连接设置

[remote]
manage_ssh_config = true   # 自动管理 ~/.ssh/config

当 manage_ssh_config = true 时，Herdr 会自动在 ~/.ssh/config 中添加 Host herdr-* 条目，使远程 attach 像本地 SSH 一样简单。

16.2.4 [keys] — 键绑定设置

[keys]
prefix = "Ctrl+a"    # 前缀键

[keys.navigate]
# 导航模式键绑定（无前缀直接生效）
up = "k"
down = "j"
left = "h"
right = "l"
next_pane = "Tab"
prev_pane = "Shift+Tab"
next_tab = "n"
prev_tab = "p"

[keys.prefix_mode]
# 前缀模式键绑定（需先按前缀键）
new_pane = "h"        # 水平分割
new_vpane = "v"       # 垂直分割
close_pane = "x"
new_tab = "t"
close_tab = "w"
detach = "d"
rename_session = "r"

Warning

修改 prefix 键后，所有前缀模式快捷键都需要配合新的前缀键使用。确保不与终端或 shell 的快捷键冲突。

16.2.4.1 自定义命令键绑定

Herdr 支持将自定义命令绑定到键上，支持四种动作类型：

[[keys.custom]]
key = "Ctrl+e"
action = "popup"           # 弹出式窗格
command = "htop"

[[keys.custom]]
key = "Ctrl+p"
action = "pane"            # 在当前 tab 新增窗格
command = "btop"
split = "horizontal"

[[keys.custom]]
key = "Ctrl+g"
action = "shell"           # 执行 shell 命令
command = "git status"

[[keys.custom]]
key = "Ctrl+Shift+r"
action = "plugin_action"   # 调用插件动作
plugin = "git-flow"
action_name = "checkout"

动作类型	说明	必填字段
popup	弹出式浮层窗格执行命令	command
pane	在当前 tab 新建窗格执行命令	command, split
shell	在当前窗格直接执行命令	command
plugin_action	触发插件定义的动作	plugin, action_name

16.2.5 [theme] — 主题设置

[theme]
name = "tokyonight"       # 内置主题名或 "custom"
auto_switch = true         # 跟随系统明暗模式自动切换
light_name = "github_light"
dark_name = "tokyonight"

配置项	类型	默认值	说明
name	string	"tokyonight"	单一主题
auto_switch	bool	false	启用明暗自动切换
light_name	string	—	亮色主题
dark_name	string	—	暗色主题

16.2.5.1 自定义主题

当 name = "custom" 时，使用 [theme.custom] 定义颜色：

[theme.custom]
bg = "#1a1b26"
fg = "#c0caf5"
border = "#414868"
sidebar_bg = "#16161e"
sidebar_active = "#7aa2f7"
pane_border = "#3b4261"
accent = "#7aa2f7"
success = "#9ece6a"
warning = "#e0af68"
error = "#f7768e"

16.2.5.2 内置主题列表

主题名	风格	适配明暗
tokyonight	Tokyo Night	暗
github_light	GitHub Light	亮
github_dark	GitHub Dark	暗
catppuccin	Catppuccin Mocha	暗
gruvbox	Gruvbox	暗
nord	Nord	暗
dracula	Dracula	暗
solarized_light	Solarized Light	亮
solarized_dark	Solarized Dark	暗
rose_pine	Rosé Pine	暗

16.2.6 [ui] — 界面设置

[ui]
sidebar_width = 30           # 侧边栏宽度（字符）
sidebar_visible = true       # 启动时显示侧边栏
pane_borders = true          # 显示窗格边框
mouse_capture = true         # 捕获鼠标事件
status_bar = true            # 显示底部状态栏

配置项	类型	默认值	说明
sidebar_width	int	30	侧边栏宽度（单位：字符列）
sidebar_visible	bool	true	启动时是否显示侧边栏
pane_borders	bool	true	是否绘制窗格边框线
mouse_capture	bool	true	是否启用鼠标支持
status_bar	bool	true	是否显示底部状态栏

16.2.6.1 侧边栏行布局（Sidebar Row Layouts）

侧边栏的每一行都可以自定义显示内容：

[[ui.sidebar_rows]]
type = "session_list"      # 显示 session 列表
show_path = true           # 显示工作目录
show_status = true         # 显示 Agent 状态指示器

[[ui.sidebar_rows]]
type = "agent_status"      # 显示当前 tab 的 Agent 状态面板
show_idle = true           # 显示 Idle 状态的 Agent

[[ui.sidebar_rows]]
type = "clock"             # 显示时钟
format = "%H:%M:%S"
timezone = "local"

可用的行类型：

行类型	说明
session_list	已注册的 session 列表
agent_status	当前 workspace 的 Agent 状态概览
clock	实时时钟
worktree_info	Git worktree 状态摘要
custom	自定义 shell 命令输出

16.2.7 [ui.toast] — 通知设置

[ui.toast]
enabled = true              # 启用 toast 通知
duration = 3000             # 显示时长（毫秒）
position = "top-right"      # 位置：top-right / top-left / bottom-right / bottom-left

16.2.8 [sound] — 声音设置

[sound]
enabled = false             # 关闭声音通知
volume = 0.5                # 音量（0.0 - 1.0）
done_sound = "bell"         # Agent 完成时的提示音
blocked_sound = "alert"     # Agent 被 Block 时的提示音

Tip

在共享办公环境中建议保持 enabled = false，使用 toast 通知替代。

16.2.9 [session] — Session 设置

[session]
resume_agents_on_restore = true   # 恢复 session 时自动重启 Agent

当 resume_agents_on_restore = true，Herdr 会在 herdr attach 恢复 session 时，自动重新启动之前运行的 Agent（状态为 Running 的 Agent）。

16.2.10 [experimental] — 实验性功能

[experimental]
pane_history = true         # 窗格输出历史记录
kitty_graphics = true       # Kitty 图形协议支持（图片显示）

配置项	类型	默认值	说明
pane_history	bool	false	记录窗格输出历史，支持回滚查看
kitty_graphics	bool	false	启用 Kitty 图形协议，支持在终端内显示图片

Warning

实验性功能可能在未来版本中变更或移除。不建议在生产环境中依赖这些功能。

16.2.11 [update] — 更新设置

[update]
manifest_check = true       # 启动时检查 Agent 清单更新
check_interval = 3600       # 检查间隔（秒）
auto_update = false         # 是否自动安装更新

---

16.3 配置文件示例

16.3.1 场景一：极简配置

适合个人开发者，只需基本功能：

# ~/.config/herdr/config.toml — 极简配置

[terminal]
default_shell = "zsh"

[keys]
prefix = "Ctrl+a"

[theme]
name = "tokyonight"

[ui]
sidebar_width = 24
pane_borders = true

16.3.2 场景二：多 Agent 重度用户

适合需要频繁编排多个 Agent 的高级开发者：

# ~/.config/herdr/config.toml — 多 Agent 配置

[terminal]
default_shell = "zsh"
new_cwd = "inherit"

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

[keys]
prefix = "Ctrl+a"

[keys.prefix_mode]
new_pane = "h"
new_vpane = "v"
close_pane = "x"
new_tab = "t"

[[keys.custom]]
key = "Ctrl+e"
action = "popup"
command = "lazygit"

[[keys.custom]]
key = "Ctrl+Shift+t"
action = "shell"
command = "herdr agent start tester"

[theme]
name = "catppuccin"

[ui]
sidebar_width = 32
sidebar_visible = true
pane_borders = true
mouse_capture = true

[[ui.sidebar_rows]]
type = "agent_status"
show_idle = true

[[ui.sidebar_rows]]
type = "session_list"
show_path = true
show_status = true

[ui.toast]
enabled = true
duration = 3000
position = "top-right"

[sound]
enabled = true
volume = 0.3
done_sound = "bell"

[session]
resume_agents_on_restore = true

[experimental]
pane_history = true
kitty_graphics = true

16.3.3 场景三：远程开发

适合通过 SSH 连接到远程服务器使用 Herdr 的场景：

# ~/.config/herdr/config.toml — 远程开发配置

[terminal]
default_shell = "bash"      # 远程服务器可能没有 zsh
new_cwd = "inherit"

[worktrees]
directory = "/tmp/herdr-worktrees"  # 使用 /tmp 避免磁盘空间不足

[remote]
manage_ssh_config = true

[keys]
prefix = "Ctrl+a"

[theme]
auto_switch = true
light_name = "github_light"
dark_name = "tokyonight"

[ui]
sidebar_width = 28
pane_borders = true
mouse_capture = false       # SSH 下鼠标可能不正常

[ui.toast]
enabled = true
duration = 4000

[session]
resume_agents_on_restore = false  # 远程环境手动恢复更可控

[update]
manifest_check = false      # 远程离线时不检查更新

---

16.4 配置管理技巧

16.4.1 配置继承与覆盖

Herdr 支持在工作目录下放置局部配置文件，覆盖全局配置：

# 全局配置
~/.config/herdr/config.toml

# 项目局部配置（可选）
~/projects/my-app/.herdr/config.toml

局部配置仅覆盖其中出现的配置项，未列出的项继续使用全局配置。

16.4.2 配置验证

修改配置后，使用验证命令检查语法和合法性：

# 验证配置文件
herdr config validate

# 验证并显示生效后的配置（合并全局 + 局部）
herdr config show

16.4.3 配置版本管理

建议将配置文件纳入 Git 版本管理：

# 创建配置仓库
cd ~/.config/herdr
git init
git add config.toml
git commit -m "Initial Herdr configuration"

# 或使用 dotfiles 管理
# chezmoi / stow / yadm 等

Tip团队配置共享

将团队通用的配置项（键绑定、主题、Agent 编排模板）放在项目 .herdr/ 目录中，通过 Git 共享给所有团队成员。个人偏好（如 shell 类型、字体大小）保留在全局 ~/.config/herdr/config.toml。

flowchart TD
    A[启动 Herdr] --> B{项目有 .herdr/config.toml?}
    B -->|是| C[加载全局配置]
    C --> D[合并项目局部配置]
    D --> E[最终生效配置]
    B -->|否| E
    E --> F[运行]
    G[herdr config validate] --> H{配置合法?}
    H -->|是| I[✅ 通过]
    H -->|否| J[❌ 报错并提示]

---

16.5 小结

本章全面介绍了 Herdr 的配置体系：

• 配置文件位于 ~/.config/herdr/config.toml，使用 TOML 格式
• 支持 热重载，修改后执行 herdr server reload-config 即可生效
• 配置分为 11 个主要分区，覆盖终端、界面、键绑定、主题、远程等
• 自定义键绑定支持四种动作类型：popup、pane、shell、plugin_action
• 三种典型配置场景：极简、多 Agent、远程开发
• 支持 全局 + 局部配置 的继承与覆盖机制

掌握配置管理是高效使用 Herdr 的基础。下一章将介绍故障排除方法，帮助你在遇到问题时快速定位和解决。