配置

Herdr 无需配置文件即可使用。当你想自定义按键、主题、侧边栏布局、通知或高级行为时，再添加配置文件。

在查找某项设置或按键绑定？请在配置参考中搜索，其中列出了每个键、类型、默认值和允许值。本页重点介绍设置方法、常用配置方案，以及需要比参考表格更详细说明的配置结构。

配置文件

Herdr 从以下位置读取配置：

Linux and macOS: ~/.config/herdr/config.toml
Windows:          %APPDATA%\herdr\config.toml

运行 herdr --help 可查看系统解析后的配置路径。

打印完整的默认配置：

herdr --default-config

如果想从完整配置开始，可以将其保存为你的配置文件：

herdr --default-config > ~/.config/herdr/config.toml

如果配置值无效，Herdr 会回退到安全的默认值，并显示启动警告。

当 onboarding 缺失或为 true 时，Herdr 会显示首次运行设置。继续完成引导会写入 onboarding = false，并打开设置中的集成标签页。完成设置后，如果想跳过此流程，请设置该值。

onboarding = false

重载配置

编辑 config.toml 后，重载正在运行的服务器：

herdr server reload-config

你也可以打开 Herdr 的全局菜单并选择 reload config。

重载会在不重启窗格的情况下应用大多数 UI 设置。仅启动时生效的设置仍需重启。

主题、侧边栏布局、复制行为等显示设置来自客户端的本地配置，查看 SSH 机器时也一样。窗格默认值、worktree、集成和自定义命令属于运行窗格的服务器。UI 中的 reload config 会同时重载客户端本地设置和选中服务器的配置，本地按键绑定也会更新；指定 --remote-keybindings server 时则使用选中服务器的按键绑定。

无客户端终端尺寸

没有客户端连接时，服务器会使用 120×40 的虚拟终端进行布局并创建新窗格。可通过以下配置更改用于无客户端编排的回退尺寸：

[server]
headless_cols = 160
headless_rows = 50

只有一个客户端连接时,所有标签页都会采用它的尺寸。连接多个客户端时,每个正在查看的标签页会采用最后聚焦、选择或操作它的客户端尺寸。当只剩一个客户端时,所有标签页会立即恢复为该客户端的尺寸。没有客户端连接时,现有窗格 PTY 会保留最后的尺寸,新的无客户端布局会使用配置的回退值。

终端默认值

设置 Herdr 创建新交互式窗格时使用的可执行文件：

[terminal]
default_shell = "nu"

未设置或值为空时，Herdr 会在 Unix 上依次使用 $SHELL 和 /bin/sh。在 Windows 上，如果能从 PATH 解析到 pwsh.exe（PowerShell 7），则使用它，否则使用系统自带的 powershell.exe（Windows PowerShell 5.1）。该值是可执行文件名或路径，而不是 shell 命令行。现有窗格会保留当前 shell，直到重新创建。自定义命令按键绑定中的字符串在 Unix 上通过 /bin/sh -c 执行窗格命令，通过 /bin/sh -lc 执行分离式命令；在 Windows 上则通过 cmd.exe /d /c 执行。

设置 Herdr 如何启动新建交互式窗格的 shell：

[terminal]
shell_mode = "auto"

shell_mode = "auto" 会在 macOS 上启动登录 shell，让 /usr/libexec/path_helper 等仅登录时生效的 PATH 设置和 Homebrew shell 初始化在新窗格中运行。在其他平台上，它会保持现有的非登录 shell 行为。使用 "login" 强制以登录 shell 启动，或使用 "non_login" 禁用登录 shell。命令窗格、分离式自定义命令按键绑定和显式 argv 启动仍使用现有的命令执行路径。

设置新窗格、标签页和工作区的工作目录策略：

[terminal]
new_cwd = "follow"

new_cwd = "follow" 保持默认行为，并继承来源窗格或工作区。没有来源工作区时，Herdr 从 $HOME 启动。使用 "home" 可始终从 $HOME 启动，使用 "current" 可采用 Herdr 的进程目录，也可以指定 "~/Projects" 这样的固定路径。CLI 或 socket API 显式提供的 --cwd 值仍然优先。

Worktree

设置 Herdr 从侧边栏创建 Git worktree 检出时使用的根目录：

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

Herdr 会在 <directory>/<repo>/<branch-slug> 下创建检出。若要使用同级目录风格的检出，请将其设置为 ~/Projects/herdr-worktrees 这样的目录。应用配置时，相对路径会解析为绝对路径。

Git 工作区行提供 worktree 操作。New worktree 会创建检出：如果输入的分支已存在，则检出该本地分支，否则创建该分支；随后将其作为新的 Herdr 工作区打开，并归组到来源工作区下。Open worktree... 会列出该仓库现有的 Git worktree 检出；选择已打开的检出会聚焦它，选择尚未打开的检出会在同一组中打开它。

归组的 worktree 仍像普通 Herdr 工作区一样工作：可以聚焦、重命名和关闭，也可以拥有自己的标签页和窗格。父行是原始工作区。关闭父行会关闭整个 Herdr 组，但不会删除检出目录或分支。

删除 worktree 检出需要显式操作。在归组的子工作区上使用 Delete worktree checkout... 来运行 git worktree remove。Herdr 会先请求 Git 安全删除。如果 Git 因检出中存在已修改或未跟踪的文件而拒绝，Herdr 会在强制删除前再次确认。分支不会被删除。

远程连接

远程连接默认使用临时保活设置，并在支持时复用连接，以管理 SSH 连接。

[remote]
manage_ssh_config = true

启用后，herdr --remote 会写入一份私有的临时 SSH 配置：先包含用户和系统 SSH 配置，再添加兜底的 ServerAliveInterval 和 ServerAliveCountMax 值。你自己的保活设置优先。Linux 和 macOS 客户端还会为每次远程连接使用私有的 OpenSSH control socket，以复用首次通过身份验证的连接；Windows OpenSSH 不使用此复用方式。设置 manage_ssh_config = false 可通过普通 ssh 进行远程连接，不使用 Herdr 生成的配置或 control socket。

按键绑定

有关前缀键的引导式介绍和经过验证的免前缀配置，请参阅键盘。

Herdr 提供类似 tmux 的前缀模式。默认前缀是 ctrl+b。按键绑定字符串是显式的：prefix+n 表示先按配置的前缀，再按 n；ctrl+alt+n 则是终端模式下的直接快捷键。

一个简短的按键绑定覆盖如下：

[keys]
prefix = "ctrl+b"
goto = "prefix+g"
new_tab = "prefix+c"
next_tab = "prefix+n"
previous_tab = "prefix+p"
focus_pane_left = "prefix+h"
navigate_workspace_down = "j"
navigate_pane_down = "ctrl+j"
split_horizontal = "prefix+minus"

需要通过多个按键进入前缀模式时，keys.prefix 也接受数组。例如，可让 macOS 和远程 Linux 机器共享同一份配置：

[keys]
prefix = ["ctrl+space", "ctrl+s"]

配置的每个前缀都会进入同一个前缀模式，并可触发所有 prefix+... 动作。第一项是状态栏中显示的主前缀；应用内 prefix+? 帮助面板会列出全部前缀。

默认键位以前缀为主，因此 Herdr 不会抢占 shell、编辑器、tmux 或终端应用的输入。在配置参考中搜索 keys. 可查看每个动作及其默认绑定。应用内帮助面板可通过 prefix+? 打开，其中会显示当前生效的绑定。

当一个动作需要多个快捷键时，绑定也可以是数组：

[keys]
next_tab = ["prefix+n", "ctrl+alt+]"]

可选动作默认不设置。使用 prefix+ 可获得前缀模式行为；当你确实需要直接快捷键时，请使用显式的修饰组合键。例如，可以像 tmux 一样通过一次按键调整窗格大小，而无需进入调整大小模式：

[keys]
resize_pane_left = "ctrl+shift+alt+left"
resize_pane_down = "ctrl+shift+alt+down"
resize_pane_up = "ctrl+shift+alt+up"
resize_pane_right = "ctrl+shift+alt+right"

按键字符串支持普通按键、ctrl+a、shift+n、alt+1、cmd+k 等修饰组合键，以及 enter、tab、esc、left、right、up、down 等特殊键。也支持 minus、comma、ampersand、plus、backtick 等命名标点。直接绑定 n 这样的普通可打印键并不安全，因为它会拦截输入；除非你有意设置直接绑定，否则请使用 prefix+n。navigate_workspace_* 和 navigate_pane_* 字段仅在导航模式中生效，可以使用 j 或 k 等普通按键；它们不得使用 prefix+、esc、enter、tab、shift+tab、left、right，也不得使用无修饰键的 1 到 9。左右方向键是向左和向右导航窗格的永久别名。这些导航模式快捷键独立于 focus_pane_down = "prefix+j" 等通用动作绑定；两者使用同一按键时，打开导航模式后，导航模式快捷键优先。Alt、Cmd/Super 以及带修饰键的标点取决于你的终端和 tmux 设置。

如果你已有旧的自定义按键绑定，并想使用新的默认值，请运行 herdr config reset-keys。Herdr 会备份 config.toml，移除 [keys] 和 [[keys.command]]，并在重启或执行 herdr server reload-config 后使用内置的 v2 默认值。

索引跳转

索引式按键绑定在普通按键绑定字段中使用 1..9：

[keys]
switch_tab = "prefix+1..9"
switch_workspace = "prefix+shift+1..9"
focus_agent = "prefix+alt+1..9"

旧版 [keys.indexed] 表仍会出于兼容性而解析，但新配置应优先使用显式的动作字段。

自定义命令按键绑定

自定义命令使用相同的按键绑定语法。

[[keys.command]]
key = "prefix+alt+g"
type = "popup"
command = "lazygit"
description = "run lazygit"
width = "80%"
height = "80%"

type = "popup" 会打开一个会话级模态弹窗,而不改变标签页布局。 弹窗会接收包括 Escape 在内的所有终端输入,直到命令退出。 width 和 height 是可选的;省略时默认为终端大小的一半,数字表示终端单元格数,"80%" 这样的字符串表示终端区域的百分比。 尺寸包含弹窗边框,过小的值会限制为弹窗最小尺寸。 弹窗命令不会收到 HERDR_PANE_ID;可使用 HERDR_ACTIVE_PANE_ID 引用底层平铺窗格。

在 Unix 和 macOS 上,还可以打开一个临时终端,而无需添加分割或标签页:

[[keys.command]]
key = "prefix+t"
type = "popup"
command = "exec \"${SHELL:-sh}\""
description = "open scratch terminal"
width = "80%"
height = "80%"

在 Windows 上,请改用 command = "powershell.exe -NoLogo" 之类的 shell 命令。 退出 shell 即可关闭弹窗并恢复平铺终端视图。

type = "pane" 会打开一个临时窗格，并在命令退出时关闭它。

type = "shell" 会在后台分离运行。

type = "plugin_action" 会调用已安装插件的动作 id。当动作 id 并非全局唯一时，请使用限定 id：

[[keys.command]]
key = "prefix+l"
type = "plugin_action"
command = "example.layout.apply"
description = "apply layout"

可以提供可选的 description。指定后，该描述会在按键绑定帮助面板（通过 prefix+? 打开）中显示，替代默认的 'custom command' 标签。

在相应值可用时，自定义命令会收到 HERDR_SOCKET_PATH、HERDR_BIN_PATH、HERDR_ACTIVE_WORKSPACE_ID、HERDR_ACTIVE_TAB_ID、HERDR_ACTIVE_PANE_ID 和 HERDR_ACTIVE_PANE_CWD。当 Herdr 能检测到聚焦窗格的工作目录时，shell 命令会从该目录运行。

在 Windows 上，自定义命令字符串使用 cmd.exe /d /c，因此环境变量应采用 %HERDR_BIN_PATH% 语法。若要运行 PowerShell 语法，请显式调用它，例如 powershell.exe -NoProfile -Command "..."。

主题

选择内置主题：

[theme]
name = "catppuccin"

在配置参考中搜索 theme.name 可查看所有内置主题。如果想让 Herdr UI 颜色跟随宿主终端的 ANSI 调色板，请使用 terminal。

在 Unix 上，Herdr 还会在调整大小或收到 SIGWINCH 后重绘时重新读取宿主终端的颜色。如果主题切换器通过 OSC 更改终端颜色却不发送明暗通知，请在应用新调色板后执行 kill -WINCH <client-pid>。目标应是已连接的 Herdr 客户端，而不是服务器；现有窗格会继续运行。直接通过 herdr terminal attach 连接的会话会把调色板查询交给所连接的应用。

要让 Herdr 在宿主终端报告明暗外观变化时自动切换自身的 UI 主题，请启用主题自动切换：

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

auto_switch 默认为 false，因此现有主题配置会保持手动行为。如果省略 light_name 或 dark_name，且配置的 name 存在对应的内置姊妹主题，Herdr 会使用该主题，例如 tokyo-night/tokyo-night-day 或 gruvbox/gruvbox-light。在设置中手动选择主题会禁用 auto_switch。

你可以覆盖单个颜色：

[theme.custom]
sidebar_bg = "#181825"
active_row_bg = "#1e1e2e"
selection_bg = "#313244"
panel_bg = "reset"
accent = "#a6e3a1"
green = "#a6e3a1"
blue = "#89b4fa"
red = "#f38ba8"
yellow = "#f9e2af"

sidebar_bg 可单独设置桌面侧边栏的背景色。省略时，侧边栏继续使用宿主终端背景。active_row_bg 可更改当前 Space 和已聚焦 Agent 行的背景色，而不会影响分隔线或滚动条轨道。selection_bg 可更改侧边栏中 Navigate 模式光标行的背景色。

颜色值支持十六进制、命名颜色、rgb(r,g,b)，以及 reset、default、none、transparent 等重置别名。

启用 auto_switch 后，可以通过明暗模式子表在共享自定义颜色之上应用不同的覆盖值：

[theme.custom]
accent = "#89b4fa"

[theme.custom.light]
panel_bg = "#eff1f5"
text = "#4c4f69"

[theme.custom.dark]
panel_bg = "#1e1e2e"
text = "#cdd6f4"

有效调色板按以下顺序应用：内置主题、[theme.custom]，然后是 [theme.custom.light] 或 [theme.custom.dark]。省略模式子表时，会保留现有的共享覆盖行为。

UI 与侧边栏

侧边栏是 Herdr 的主仪表盘。在配置参考中搜索 ui.，可查看尺寸、折叠模式、Agent 面板排序、鼠标行为、窗格边框和其他显示设置。

ui.pane_borders 接受 "auto"（默认值，仅为分割窗格显示边框）、"always"（也为单个窗格显示边框）或 "off"。单窗格的所有边都是外边，因此还需要 ui.pane_outer_borders = true 才会显示边框。旧的布尔值仍然有效：true 对应 "auto"，false 对应 "off"。

在 [ui] 下设置 tab_bar_position = "bottom"，可将桌面标签栏放到终端窗格下方。Prefix、Navigate、Copy 和 Resize 模式栏会在显示期间临时替换底部标签栏。默认值为 "top"。

可在标签栏右侧配置一个类似 tmux 的有序状态区：

[ui]
tab_bar_right = [
  { type = "zoom" },
  { type = "hostname" },
  { type = "datetime", format = "%H:%M" },
  { type = "text", text = "prod" },
  { type = "command", command = "~/.config/herdr/status.sh", interval_seconds = 5, timeout_seconds = 2 },
]
tab_bar_right_separator = " · "

状态区默认为空。添加 zoom 后，活动标签页处于缩放状态时会显示固定的 ZOOM 标记；它与现有的逐标签页 Z 标记相互独立。hostname、datetime 和 command 在 Herdr 服务器上解析，因此使用 herdr --remote 时会显示远程机器的值。日期时间条目使用 strftime 格式。由于该值是服务器本地的墙上时钟时间，需要 UTC 偏移量或 Unix 时间戳的 %z、%s 等指令会被拒绝。

命令条目会立即运行，之后按 interval_seconds 刷新，不会阻塞渲染，也不会与上一次运行重叠。间隔范围为 1–31,536,000 秒，超时范围为 1–3,600 秒。Herdr 使用成功输出的最后一行，并移除以 ESC 开头的终端控制序列，而不将其解释为样式；执行失败、输出为空或超过 timeout_seconds 后会清除该值。命令会获得与自定义命令按键绑定相同的活动工作区、标签页、窗格、socket、二进制文件和工作目录上下文。Linux、macOS 和 Windows 均支持命令条目；Linux 和 macOS 使用 /bin/sh -lc，Windows 使用 cmd.exe /d /c。

分隔符只会出现在可见条目之间。设置 tab_bar_right_separator = "" 可直接连接条目。标签栏较窄时，整个状态区会让位给标签页及其控件。

外层终端窗口标题

Herdr 会模拟各窗格中的终端，因此窗格内写入的 OSC 0/OSC 2 标题只会停留在 Herdr。Herdr 会向自己所运行的终端写入自己的标题，窗口管理器和终端标签栏读取的正是这个标题：

[ui]
window_title = "{hostname}: {workspace}"

可用记号为 {hostname}、{workspace}、{tab}、{pane}（聚焦窗格的手动名称）和 {terminal_title}（聚焦窗格自身的终端标题，已去除加载动画字符）。用 {{ 和 }} 表示字面花括号。没有值的记号会渲染为空。

标题在 Herdr 服务器上生成，因此即使通过 herdr --remote 连接或经由 SSH 运行 herdr，{hostname} 仍然指向运行窗格的那台机器。设置 window_title = "" 可以不改动外层终端标题。

client.window_title.set 会覆盖配置的标题，直到 client.window_title.clear 将其交还。

智能体状态默认使用紧凑的彩色圆点。若要同时通过形状和颜色区分 blocked、working、done、idle 与 unknown 状态，请在设置中选择 distinct symbols，或配置：

[ui]
status_indicators = "symbols"

这些符号是静态的，因此该选项不会启用旋转动画。

侧边栏行布局

展开的桌面侧边栏会将 rows 中的每个内层数组渲染为一行。以下是完整的默认布局：

[ui.sidebar.agents]
row_gap = 0
rows = [
  ["state_icon", "machine", "workspace", "tab"],
  ["agent"],
]

[ui.sidebar.spaces]
row_gap = 0
rows = [
  ["state_icon", "workspace"],
  ["branch", "git_status"],
]

Agent 行支持以下内置 token：

• state_icon — 智能体语义状态的彩色图标。
• state_text — idle、working、blocked、done 或 unknown；如果报告中包含显示标签，也会一并显示。
• machine — 客户端连接多台机器时显示机器标签；只有一台本地机器时省略。
• workspace — 工作区名称。
• tab — 标签页名称（如有）。
• pane — 窗格名称（如有）。
• agent — 检测到或报告的智能体显示名称。
• terminal_title — 经过安全规范化的最新 OSC 0/2 终端标题。
• terminal_title_stripped — 从终端标题开头移除一个可识别的活动或旋转指示符字形及其后空白后的结果。
• $name — 名为 name 的自定义窗格元数据。

Space 行支持以下内置 token：

• state_icon — Space 汇总后智能体状态的彩色图标。
• state_text — Space 汇总后智能体状态的文本。
• workspace — 工作区名称。
• branch — Git 分支（如有）。
• git_status — 非零时显示 Git ahead 和 behind 数量。
• $name — 名为 name 的自定义工作区元数据。

token 会按配置顺序渲染。Herdr 通常使用 · 分隔相邻值，并在 state_icon 后使用一个空格。缺失值及其分隔符会消失；当一行中的所有 token 都没有值时，该行会消失。已有的自定义行不会改变；如果希望在自定义的多机器布局中显示机器标识，请显式添加 machine。每个布局最多可包含 16 行，每行最多可包含 16 个 token。

也可以用内联样式表定义 token：

[ui.sidebar.agents]
rows = [
  ["state_icon", { token = "workspace", bold = false }, "tab"],
  [{ token = "$summary", fg = "#89b4fa", bold = true, dim = false }],
]

fg 只接受严格的 #RGB 或 #RRGGBB，bold 和 dim 接受布尔值。省略字段会保留上下文样式；显式 false 会移除对应修饰。样式只作用于当前出现位置。为 git_status 设置 fg 后，ahead 和 behind 会使用同一种颜色，而不是默认的绿色和红色。token 样式不会改变分隔符或行背景。

文本值 token 还可以包含最多 16 条有序的 rules。每条规则必须恰好包含一个条件：equals、contains、starts_with、gt 或 lt，并可选地覆盖 fg、bold 和 dim：

[ui.sidebar.agents]
rows = [
  ["state_icon", "workspace", "tab"],
  [{ token = "machine", fg = "#fff", rules = [{ equals = "Local", fg = "#f55" }, { equals = "Fedora", ignore_case = true, fg = "#51a2da" }] }, "agent"],
  [{ token = "$load", fg = "#fff", rules = [{ gt = 80, fg = "#f55", bold = true }, { gt = 50, fg = "#fc0" }] }],
]

只有第一条匹配的规则生效。指定的样式字段覆盖当前位置的默认值，未指定的字段保持继承。没有规则匹配时保留默认样式。匹配使用显示截断前的完整值。在规则中设置 hide = true 可移除匹配的 token 及其分隔符；没有剩余 token 的行也会消失。例如，{ token = "machine", fg = "#61afef", rules = [{ equals = "Local", hide = true }] } 会在机器标签恰好为 Local 时隐藏机器 token。它比较的是标签，而不是连接类型。设置 hide = false 或省略时，token 保持可见。没有覆盖字段的规则一旦匹配，仍会停止后续匹配并保留默认值。

equals、contains 和 starts_with 接受字符串，默认区分大小写。添加 ignore_case = true 可忽略 ASCII 大小写，非 ASCII 字符仍区分大小写。空字符串遵循普通字符串匹配：空的 equals 只匹配空值，空的 contains 或 starts_with 匹配任何已存在的值。

gt 和 lt 接受有限数值阈值，分别进行严格大于和小于比较，不包含等于。整个值必须能解析为有限数值；支持小数和指数形式，但带空白、单位、NaN 或无穷大的值不会匹配。数值规则不接受 ignore_case。比较使用浮点数，不保证大整数的精确比较。

规则适用于 Agent 行、rows_by_agent 覆盖和 Space 行中的文本值内置 token 及自定义 $name token。上例中，$load 报告 "90" 时显示红色粗体，"60" 时显示黄色，"90%" 时保持白色。未报告的 token 仍然不显示。state_icon 和复合 token git_status 仅接受固定样式，不支持规则。未知条件或格式错误的规则会在加载配置时被拒绝；不支持正则表达式、模糊匹配或脚本。

row_gap 分别控制 Agent 和 Space 面板中条目之间的空白终端行数。默认值为 0，会紧密排列条目；设为 1 可恢复之前的间距。它不会在 rows 声明的内容行之间添加间距。连续缩进的 worktree 子项仍会作为一个 Space 组紧密排列。

在 rows_by_agent 下为已知智能体覆盖完整的 Agent 布局：

[ui.sidebar.agents]
rows = [
  ["state_icon", "agent", "state_text"],
  ["workspace", "tab"],
]

[ui.sidebar.agents.rows_by_agent]
claude = [
  ["state_icon", "agent", "state_text"],
  ["terminal_title_stripped"],
  ["workspace", "tab"],
]

覆盖项会替换 rows，而不是扩展它。覆盖项的键是区分大小写的规范智能体 ID，例如 claude、codex 和 pi。不接受 claude-code 等检测别名。没有覆盖项的智能体（包括自定义报告的智能体）会使用 rows。

自定义 $name token 是动态值，而不是字面文本。先将 token 添加到布局，再通过脚本或插件报告其值：

[ui.sidebar.agents]
rows = [
  ["state_icon", "agent", "$model"],
  ["$summary"],
  ["workspace", "tab"],
]

herdr pane report-metadata <pane_id> \
  --source my-agent-hook \
  --token model=opus \
  --token summary="reviewing authentication"

自定义 Space token 可用同样的方式通过 herdr workspace report-metadata 报告。未报告的自定义 token 会直接消失。

元数据上报方只提供值；样式由本地侧边栏配置控制。有关限制、清除、顺序和过期值的信息，请参阅 CLI 参考：报告元数据。

侧边栏行设置仅影响展开的桌面侧边栏。折叠视图和移动视图仍使用紧凑布局。

通知

当后台智能体完成任务或需要输入时，Herdr 可以通知你：

[ui.toast]
delivery = "herdr"
delay_seconds = 1

[ui.toast.herdr]
position = "bottom-right"

选择 herdr 可使用应用内 toast，选择 terminal 可使用适合 SSH 场景的外层终端通知，选择 system 可使用本地操作系统通知服务，选择 off 可禁用弹出通知。Herdr 会抑制活动标签页的弹出通知。在配置参考中搜索 ui.toast，可查看位置、延迟行为和剪贴板反馈设置。

在 macOS 上，system 会先尝试 terminal-notifier；如果它不可用或执行失败，则回退到 /usr/bin/osascript。该回退方式会在通知中心显示为 Script Editor，并且无法激活承载 Herdr 的终端。可运行 brew install terminal-notifier 安装 terminal-notifier。如果 Herdr 检测到受支持的终端，点击通知时它可以激活该终端应用。也可以选择 terminal，让受支持的外层终端负责发送通知。

声音

声音通知通过本地 Herdr 客户端播放。自定义声音必须是 mp3 文件；相对路径从配置文件所在目录解析。

[ui.sound]
path = "sounds/notification.mp3"
done_path = "sounds/done.mp3"
request_path = "sounds/request.mp3"

path 为所有声音通知设置同一种声音。done_path 和 request_path 只覆盖完成和需要输入时的声音。

按智能体覆盖声音设置时，可使用 default、on 或 off。键应使用检测到的智能体标签，例如 claude、codex、devin 或 droid。Droid 默认静音。

[ui.sound.agents]
droid = "off"
claude = "on"

高级配置

在配置参考中搜索回滚缓冲区限制、嵌套启动以及其他高级或实验性设置。启用窗格屏幕历史前，请参阅会话状态与恢复；该指南说明了保存窗格内容带来的安全取舍。

Kitty graphics

应用和插件通过窗格终端输出中发出的标准 Kitty graphics 协议进行集成。Herdr 默认在兼容的外层终端中渲染这些图像。外部 socket 窗格覆盖层 API 已被移除，也没有替代的 socket 图像 API。

弹窗、菜单和通知会在其覆盖区域周围裁剪图像；每幅图像的其余部分仍然可见，覆盖层关闭后，被遮挡的部分会恢复显示。图像不会随对话框背景一起变暗。

Herdr 会自动选择符合条件的文件传输方式，无需更改应用或切换环境变量。在本地 Unix Ghostty 客户端上，它可以通过临时文件发送图像数据，而不是将其编码到终端输出中。系统会先用一个小型文件读取探测来检查支持情况。其他终端、通过 SSH 启动的客户端和嵌套多路复用器仍使用内联输出进行最后一跳优化。

对于符合条件的本地客户端，原生 RGBA 图像从服务器传到客户端时使用 Herdr 所有的快照路径，而不是像素字节。不支持的客户端和失败的传输会回退到内联传送。远程服务器路径绝不会转发到本地终端。图像放置、裁剪和可见性仍由 Herdr 控制。

在 Linux 上，Herdr 读取整文件、未压缩 RGBA 上传的像素前，可以使用写时复制快照。这要求文件系统支持克隆到 Herdr 的私有 /var/tmp 存储。不支持的文件系统、临时文件上传、共享内存和其他格式会使用普通加载器。每个快照上限为 16 MiB，总上限为 64 MiB；动画和不受支持的客户端会在需要时读取像素。Herdr 接受图像后绝不会依赖可变的生产者路径。

PNG 上传仍会进行完整解码和验证。Herdr 不会把损坏图像的验证推迟到外层终端。

要禁用 Kitty graphics 渲染，请设置：

[terminal]
kitty_graphics = false

为兼容现有配置，旧的 experimental.kitty_graphics 设置仍然可用。若两者同时设置，terminal.kitty_graphics 优先。

更改此设置后，需要重启受影响的 Herdr 服务器或重新连接客户端。在远程会话中，服务器端设置控制 Kitty graphics 解析，本地客户端设置控制向外层终端输出图形。

智能体会话恢复

默认情况下，Herdr 会在服务器重启后恢复受支持的智能体对话：

[session]
resume_agents_on_restore = true
startup_per_agent_delay_ms = 100

为减少启动时的资源争用，自动恢复默认每隔 100 毫秒启动一个智能体。第一个满足条件的智能体会立即启动。设置 startup_per_agent_delay_ms = 0 可禁用间隔。手动启动和显式连接终端不受影响。修改后需重启 Herdr 服务器。

只有通过官方集成获得有效原生会话引用的窗格才能恢复；其他窗格会作为普通 shell 恢复。有关受支持的智能体和持久化行为，请参阅会话状态与恢复。

IME 光标跟踪

在 macOS 上，隐藏硬件光标的 AI 智能体 TUI 可能导致原生输入法候选窗口无法跟随聚焦窗格。使用以下设置可为这些窗格显示光标锚点：

[experimental]
reveal_hidden_cursor_for_cjk_ime = true
cjk_ime_agents = ["claude", "pi", "codex"]

限制 cjk_ime_agents 可以避免在无关应用中额外显示硬件光标。在配置参考中搜索这些键，可查看接受的智能体名称和光标形状。

前缀输入源切换

在 macOS 和 Windows 上，当前缀命令和由前缀启动的模式处于活动状态时，Herdr 可以临时切换到支持 ASCII 的输入源：

[experimental]
switch_ascii_input_source_in_prefix = true

在 macOS 上，会切换到当前支持 ASCII 的键盘布局；在 Windows 上，会将 IME 切换到英文（ASCII）输入。返回终端输入或进入文本字段时，Herdr 会恢复之前的输入源。此设置在其他平台上无效。

Windows 上仅支持韩语 IME

目前 Windows 上的支持仅限于韩语 IME。使用其他语言的 IME 时，此设置不会改变输入源。

环境变量

变量	用途
HERDR_CONFIG_PATH	覆盖配置文件路径。
HERDR_SESSION	为 CLI 命令选择命名会话。
HERDR_SOCKET_PATH	覆盖底层 socket 路径。
HERDR_LOG	设置日志过滤，例如 HERDR_LOG=herdr=debug。
HERDR_DISABLE_SOUND	即使 [ui.sound] enabled = true 也禁用声音播放。

日志

日志有助于诊断启动警告、集成状态或 socket API 行为。

常见日志文件：

~/.config/herdr/herdr.log
~/.config/herdr/herdr-client.log
~/.config/herdr/herdr-server.log

日志会自动轮转。报告问题时，请附上当前日志和轮转后的同级日志文件。