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

Herdr config.toml 完全解读每个配置项逐段讲解新手也能一次看懂【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdrHerdr 是一个让编码 AgentClaude Code、Codex 等常驻运行的终端运行时它的config.toml配置文件完全可选——不改也能用想自定义主题、快捷键、侧边栏和通知时再逐段调整即可。本文把 Herdr 的config.toml从顶部到底部逐段拆解讲清每个配置项的含义、默认值和可选值帮你快速把界面调成自己的样子。1. 配置文件在哪里、如何一键生成完整默认配置 config.toml的位置跨平台一致Windows 除外系统配置文件路径Linux / macOS~/.config/herdr/config.tomlWindows%APPDATA%\herdr\config.toml三个实用技巧打印完整默认配置执行herdr --default-config可以把全部配置项含注释输出到终端想拿一份完整模板就用herdr --default-config ~/.config/herdr/config.toml保存下来。热加载改完配置不用重启执行herdr server reload-config或在应用内按默认快捷键prefixshiftr即可生效。容错机制某个配置值写错时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 catppuccinname内置主题共 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 / 固定路径如 ~/Projectsdefault_shell新建交互式窗格使用的可执行文件不是命令串只影响新建窗格不改变已存在的窗格。shell_modeauto在 macOS 上以登录 Shell 启动保证 Homebrew 等 PATH 初始化生效其他平台保持非登录行为login/non_login可强制指定。new_cwd新窗格/标签/工作区的启动目录策略。follow继承来源窗格或工作区目录home恒为$HOMEcurrent用 Herdr 进程目录也可以直接写固定路径。5. [keys] 快捷键配置前缀模式 逐条覆盖 ⌨️Herdr 采用类似 tmux 的前缀模式默认前缀是ctrlb目的是不抢占 Shell、编辑器、终端程序里的普通按键。[keys] prefix ctrlb goto prefixg # 打开会话导航器 new_tab prefixc next_tab prefixn按键写法支持ctrla、shiftn、alt1、cmdk等组合以及enter、tab、esc、left/right/up/down、minus、backtick等特殊键名。裸键如n会拦截正常输入除非你有意为之否则一律建议prefix开头。一个动作可绑多个键next_tab [prefixn, ctrlalt]]。索引跳转用1..9展开成 9 个快捷键例如switch_tab prefix1..9、switch_workspace prefixshift1..9、focus_agent prefixalt1..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等环境变量。常用默认快捷键速查按键作用prefix?快捷键帮助面板prefixw工作区选择器prefixc/prefixn/prefixp新建 / 下一个 / 上一个标签prefixh j k l聚焦左/下/上/右窗格prefixv/prefixminus垂直 / 水平分屏prefixz放大/还原当前窗格prefixb折叠/展开侧边栏prefixq断开连接detach觉得默认键位和旧版冲突执行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、cmdalt再右键时点击直接透传给窗格内的应用留空或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_positiontop默认或bottom。tab_bar_right在标签行右端放 tmux 风格状态区支持zoom、hostname、datetimestrftime 格式、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_indicatorsAgent 状态指示用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] 实验功能开关 全部默认关闭按需开启配置项作用allow_nested允许在一个 Herdr 窗格里再启动 Herdrkitty_graphics实验性 Kitty 图形协议渲染测试终端图片行为时开pane_history把窗格屏幕历史持久化到 session-history.jsonreveal_hidden_cursor_for_cjk_ime为隐藏硬件光标的 TUI 暴露 IME 锚点光标macOS CJK 输入法cjk_ime_agents限制上一条只作用于指定 Agent如[claude, codex]cjk_ime_cursor_shapeIME 锚点光标形状默认steady_blockswitch_ascii_input_source_in_prefix前缀模式下临时切 ASCII 输入源macOS/WindowsWindows 目前仅支持韩文输入法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. 环境变量速查与排错环境变量用途HERDR_CONFIG_PATH覆盖配置文件路径HERDR_SESSION为 CLI 命令指定命名会话HERDR_LOG日志过滤如HERDR_LOGherdrdebugHERDR_DISABLE_SOUND强制禁用声音播放HERDR_SOCKET_PATH低层 socket 路径覆盖排错三板斧启动警告会明确指向出错的配置项日志写在~/.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考