企业官网建设流程全解析

Herdr config.toml 完全解读：每个配置项逐段讲解，新手也能一次看懂

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr

Herdr 是一个让编码 Agent（Claude Code、Codex 等）常驻运行的终端运行时，它的config.toml配置文件完全可选——不改也能用，想自定义主题、快捷键、侧边栏和通知时再逐段调整即可。本文把 Herdr 的config.toml从顶部到底部逐段拆解，讲清每个配置项的含义、默认值和可选值，帮你快速把界面调成自己的样子。

1. 配置文件在哪里、如何一键生成完整默认配置 📁

config.toml的位置跨平台一致（Windows 除外）：

三个实用技巧：

• 打印完整默认配置：执行herdr --default-config，可以把全部配置项（含注释）输出到终端，想拿一份完整模板就用herdr --default-config > ~/.config/herdr/config.toml保存下来。
• 热加载：改完配置不用重启，执行herdr server reload-config，或在应用内按默认快捷键prefix+shift+r即可生效。
• 容错机制：某个配置值写错时，Herdr 会回退到安全默认值并在启动时显示警告，不会直接崩溃。

路径解析与加载逻辑在 src/config/io.rs 中实现；你也可以用环境变量HERDR_CONFIG_PATH覆盖配置文件位置，方便多套配置切换。

2. 顶层开关：onboarding（新手引导）

onboarding = false

• 缺省或为true时，Herdr 首次启动会显示引导设置流程。
• 引导完成或设置onboarding = false后就不再弹出。老用户想跳过引导，写上这一行即可。

3. [theme] 主题配置：内置 18 套配色 + 自定义色板 🎨

[theme] name = "catppuccin" # 默认主题 auto_switch = true # 跟随终端亮/暗外观自动切换 light_name = "catppuccin-latte" dark_name = "catppuccin"

• name：内置主题共 18 套，包括catppuccin、tokyo-night、dracula、nord、gruvbox、one-dark、solarized、kanagawa、rose-pine、vesper等（各自带 light 变体）。写terminal则让 Herdr 跟随外层终端的 ANSI 配色。
• auto_switch：默认false。开启后，外层终端报告亮/暗外观变化时，Herdr 自动在light_name和dark_name之间切换；省略任一侧时自动选用配对主题（如tokyo-night↔tokyo-night-day）。
• [theme.custom]：在基础主题之上逐色覆盖，支持#RGB/#RRGGBB十六进制、命名色、rgb(r,g,b)，以及reset/transparent等重置别名。可覆盖accent、panel_bg、sidebar_bg、active_row_bg、selection_bg、text、green/red/blue/yellow等令牌；开启auto_switch后还能加[theme.custom.light]/[theme.custom.dark]两套分层覆盖。

主题定义与颜色解析见 src/config/theme.rs。

4. [terminal] 终端默认行为：新窗格用什么 Shell、从哪个目录启动

[terminal] default_shell = "nu" # 留空则用 $SHELL，再退到 /bin/sh shell_mode = "auto" # auto / login / non_login new_cwd = "follow" # follow / home / current / 固定路径如 "~/Projects"

• default_shell：新建交互式窗格使用的可执行文件（不是命令串），只影响新建窗格，不改变已存在的窗格。
• shell_mode：auto在 macOS 上以登录 Shell 启动（保证 Homebrew 等 PATH 初始化生效），其他平台保持非登录行为；login/non_login可强制指定。
• new_cwd：新窗格/标签/工作区的启动目录策略。follow继承来源窗格或工作区目录，home恒为$HOME，current用 Herdr 进程目录，也可以直接写固定路径。

5. [keys] 快捷键配置：前缀模式 + 逐条覆盖 ⌨️

Herdr 采用类似 tmux 的前缀模式，默认前缀是ctrl+b，目的是不抢占 Shell、编辑器、终端程序里的普通按键。

[keys] prefix = "ctrl+b" goto = "prefix+g" # 打开会话导航器 new_tab = "prefix+c" next_tab = "prefix+n"

• 按键写法：支持ctrl+a、shift+n、alt+1、cmd+k等组合，以及enter、tab、esc、left/right/up/down、minus、backtick等特殊键名。裸键（如n）会拦截正常输入，除非你有意为之，否则一律建议prefix+开头。
• 一个动作可绑多个键：next_tab = ["prefix+n", "ctrl+alt+]"]。
• 索引跳转：用1..9展开成 9 个快捷键，例如switch_tab = "prefix+1..9"、switch_workspace = "prefix+shift+1..9"、focus_agent = "prefix+alt+1..9"。
• 导航模式专属键：navigate_workspace_up/down、navigate_pane_left/down/up/right只在导航模式生效，默认up/down/h/j/k/l。
• 自定义命令绑定：[[keys.command]]数组可为任意按键挂命令，type可选popup（模态弹出）、pane（临时放大窗格）、shell（后台执行）、plugin_action（调用插件动作），还能用width = "80%"控制弹窗大小。命令执行时会自动注入HERDR_SOCKET_PATH、HERDR_ACTIVE_PANE_ID等环境变量。

常用默认快捷键速查：

觉得默认键位和旧版冲突？执行herdr config reset-keys会备份配置并移除[keys]段，恢复内置 v2 默认键位。按键解析实现在 src/config/keybinds.rs，全部键位默认值定义在 src/config/model.rs。

6. [ui] 界面配置：侧边栏、鼠标与窗格外观

这是配置项最多的段，按功能分四组看：

侧边栏尺寸与状态

[ui] sidebar_width = 26 # 展开宽度（列数），默认 26 sidebar_min_width = 18 # 拖拽下限，默认 18 sidebar_max_width = 36 # 拖拽上限，默认 36 sidebar_start_collapsed = false sidebar_collapsed_mode = "compact" # compact / hidden mobile_width_threshold = 64 # 窄于该列数启用移动端单栏布局

注意sidebar_min_width不能大于sidebar_max_width，否则回退默认值并给出诊断提示。

鼠标与光标

• mouse_capture：是否捕获鼠标事件（默认true）。
• copy_on_select：鼠标选中即复制（默认true）。
• mouse_scroll_lines：每格滚轮滚动行数，默认 3。
• host_cursor：宿主光标策略auto/native/drawn。
• right_click_passthrough_modifier：按住该修饰键（如ctrl、cmd+alt）再右键时，点击直接透传给窗格内的应用；留空或off表示禁用。

窗格与标签外观

• pane_borders、pane_outer_borders、pane_scrollbars、pane_gaps：分别控制分屏边框、外框边框、滚动条、窗格间距，默认全开。
• show_agent_labels_on_pane_borders：未手动命名时，在边框上显示 Agent 名称（默认关）。
• hide_tab_bar_when_single_tab：只有一个标签时隐藏标签行（默认关）。
• tab_bar_position：top（默认）或bottom。
• tab_bar_right：在标签行右端放 tmux 风格状态区，支持zoom、hostname、datetime（strftime 格式）、text、command（定时执行外部脚本）五种条目，配tab_bar_right_separator控制分隔符。
• confirm_close（默认true）：关闭工作区前确认；prompt_new_tab_name（默认true）：新建标签前询问名称。

标题、状态与排序

• window_title：外层终端窗口标题模板，支持{hostname}、{workspace}、{tab}、{pane}、{terminal_title}令牌，默认"{hostname}: {workspace}"；设空则不改动标题。
• status_indicators：Agent 状态指示用dots（默认，彩色圆点）或symbols（不同形状区分 blocked/working/done/idle）。
• agent_panel_sort：侧边栏 Agent 面板排序，spaces（默认，按工作区）或priority。
• [ui.sidebar.agents]/[ui.sidebar.spaces]：用rows数组自定义每行由哪些令牌拼成，内置令牌如state_icon、workspace、branch、git_status、terminal_title_stripped等，还能通过$name引用插件上报的自定义元数据。

完整字段定义见 src/config/model.rs，官方逐项说明见 configuration.mdx。

7. [ui.toast] 与 [ui.sound]：通知与声音 🔔

Toast 通知（后台 Agent 完成或等待输入时提醒）：

[ui.toast] delivery = "herdr" # off / herdr / terminal / system delay_seconds = 1 # 0–3600 秒 [ui.toast.herdr] position = "bottom-right" # 应用内吐司位置

• herdr：应用内吐司；terminal：外层终端通知（SSH 场景也有效）；system：操作系统通知；off：关闭。
• [ui.toast.clipboard]控制复制成功提示的开关与位置。

声音：

[ui.sound] path = "sounds/notification.mp3" # 所有通知共用 done_path = "sounds/done.mp3" # 覆盖“完成”声 request_path = "sounds/request.mp3" # 覆盖“等待输入”声 [ui.sound.agents] droid = "off" claude = "on"

• 只支持mp3，相对路径相对于配置文件所在目录解析。
• [ui.sound.agents]可按 Agent 单独设default/on/off。

声音配置解析在 src/config/sound.rs。

8. [server] 与 [advanced]：无头尺寸和回滚缓冲

[server] headless_cols = 120 # 默认 120 headless_rows = 40 # 默认 40

无客户端连接时，Herdr 服务器用一个 120×40 的虚拟终端做布局；纯 API 编排场景可按需调大。客户端重新附着后以其实际尺寸为准。

[advanced] scrollback_limit_bytes = 10000000 # 每个窗格回滚缓冲上限，默认 10MB

旧的scrollback_lines写法仍被兼容接受。

9. [experimental] 实验功能开关 🧪

全部默认关闭，按需开启：

10. [session]、[worktrees]、[remote]、[update]：其余实用项

• [session]：resume_agents_on_restore = true（默认）——服务器重启恢复会话时，自动续接受支持的 Agent 原生对话；无法续接的窗格照常以普通 Shell 恢复。
• [worktrees]：directory = "~/.herdr/worktrees"（默认）——侧边栏一键创建 Git worktree 检出时的根目录，实际检出位于<directory>/<repo>/<branch-slug>。
• [remote]：manage_ssh_config = true（默认）——herdr --remote自动写入私有的临时 SSH 配置（保活 + 连接复用）；设为false则走原生ssh。
• [update]：channel = "stable" / "preview"选择更新渠道；version_check与manifest_check分别控制版本号检查和 Agent 清单检查，默认均开启。

配置结构总入口是 src/config/model.rs 的Config结构体，所有默认值一目了然。

11. 环境变量速查与排错

排错三板斧：启动警告会明确指向出错的配置项；日志写在~/.config/herdr/下的herdr.log、herdr-client.log、herdr-server.log（自动轮转）；不确定配置是否合法时，参考官方配置手册 config-reference.mdx 逐项核对类型与取值。

小结

Herdr 的config.toml遵循“缺省即可用、覆盖才生效”的原则：12 个顶级配置段各自独立，写错单项只会回退默认并提示。建议先跑herdr --default-config拿全量模板，再按本文顺序只改自己关心的[theme]、[keys]、[ui]三段，其余保持默认即可——这就是最省事的 Herdr 配置入门路径。

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr