Herdr 自定义命令键位绑定：popup、pane 与 shell 三种 type 的配置与调用上下文

Herdr 自定义命令键位绑定：popup、pane 与 shell 三种 type 的配置与调用上下文

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

在 Herdr 里跑 coding agent 时，经常需要临时调起 lazygit、开个临时 shell 或者后台跑一个长任务。Herdr 的[[keys.command]]配置可以把任意命令绑到键盘上，并通过type字段选择执行形式：popup（会话内弹窗）、pane（临时放大面板）、shell（后台分离运行）。本文的任务是：在config.toml里正确写出这三种绑定，理解命令实际以什么 shell、什么工作目录、携带哪些环境变量被调用，最后用键位帮助面板验证绑定生效。适用前提是 Herdr 客户端已可正常运行，且能编辑本机配置文件。

找到并编辑配置文件

Herdr 无需配置文件即可运行，自定义键位绑定时才需要添加它。配置文件位置：

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

执行herdr --help可以看到你系统上解析后的配置路径。如果想要一份完整的起始配置，把默认配置直接导出保存：

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

herdr --default-config会打印完整默认配置，也可以只把它当参考，在现有配置里追加[[keys.command]]表。

键位字符串怎么写

自定义命令使用与 Herdr 其他键位相同的语法。默认 prefix 是ctrl+b：

• prefix+alt+g表示先按ctrl+b松开，再按alt+g；
• ctrl+alt+g这种带修饰键的组合则是不经过 prefix 的直接快捷键。

键位字符串接受普通键、修饰键组合（ctrl+a、shift+n、alt+1、cmd+k）以及enter、tab、esc、方向键等特殊键。像n这样的无修饰可打印键会拦截正常输入，除非你有意为之，否则建议用prefix+前缀。一个动作也可以绑定多个快捷键，写成数组：

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

配置三种 type

三种type都写在[[keys.command]]表里，必填字段是key、type、command，description可选。

type = "popup"：会话内弹窗

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

popup打开一个会话内模态弹窗，不改变当前 tab 布局。弹窗会接收所有终端输入（包括 Escape），直到里面的命令退出后自动关闭。width和height是可选的：

• 省略时为默认半尺寸弹窗；
• 数字表示终端单元格数；
• 字符串如"80%"表示终端区域的比例；
• 尺寸包含弹窗边框，小于最小值的数值会被钳制到最小值。

在 Unix 和 macOS 上，popup 还可以提供一个临时终端，不需要新增 split 或 tab：

[[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"：临时放大面板

[[keys.command]] key = "prefix+shift+g" type = "pane" command = "lazygit" description = "lazygit in zoomed pane"

pane打开一个临时放大面板，命令退出时面板自动关闭。

type = "shell"：后台分离运行

[[keys.command]] key = "prefix+shift+s" type = "shell" command = "my-agent-state.sh" description = "run state script in background"

shell在后台分离运行命令，不占用前台焦点，适合不阻塞当前操作的脚本。

除这三种之外，文档还定义了type = "plugin_action"来调用已安装插件的动作 id（动作 id 不全局唯一时用限定 id，如command = "example.layout.apply"），本文不展开。

description设置后会显示在键位帮助面板里；不设置时显示默认的'custom command'标签。

调用上下文：命令实际如何被执行

写command字符串前需要理解执行环境，否则命令在错误的工作目录或 shell 里跑会查不到文件、拿不到变量。

执行用的 shell。在 Unix 上，pane 类命令字符串通过/bin/sh -c执行，detached 类命令通过/bin/sh -lc执行；在 Windows 上通过cmd.exe /d /c执行。Windows 下环境变量用%HERDR_BIN_PATH%这类语法；如果要用 PowerShell 语法，必须显式调用，例如powershell.exe -NoProfile -Command "..."。

传入的环境变量。当对应值可用时，自定义命令会收到以下环境变量：

变量	含义
HERDR_SOCKET_PATH	Herdr socket 路径
HERDR_BIN_PATH	herdr 可执行文件路径
HERDR_ACTIVE_WORKSPACE_ID	当前活动 workspace id
HERDR_ACTIVE_TAB_ID	当前活动 tab id
HERDR_ACTIVE_PANE_ID	当前活动 pane id
HERDR_ACTIVE_PANE_CWD	当前活动 pane 的工作目录

工作目录。当 Herdr 能检测到聚焦 pane 的工作目录时，shell 命令从该目录运行。

popup 的一个特例。popup 命令不会收到HERDR_PANE_ID，要指向上层平铺 pane 时使用HERDR_ACTIVE_PANE_ID。

配置归属。pane 默认值、worktrees、integrations 和自定义命令属于 pane 实际运行的那个 Herdr server。通过herdr --remote查看远程机器时，自定义命令绑定随远程 server 的配置走，而不是本地客户端配置。

应用修改并验证

编辑完config.toml后重载运行中的 server：

herdr server reload-config

也可以在 Herdr 的全局菜单里选择reload config。重载会同时应用客户端本地配置和所选 server 的配置，本地键位绑定也会随之重载；只有少数启动时设置需要重启才生效。

验证方式：

1. 在 Herdr 里按prefix+?打开键位帮助面板，确认新绑定的快捷键出现在列表里；按/可以过滤动作名，Backspace 编辑过滤词，ctrl+u清空。
2. 检查帮助面板中该绑定显示的是你配置的description，而不是'custom command'，说明这条绑定被正确解析。
3. 实际按下快捷键，确认行为与type一致：popup弹出会话内弹窗且布局不变，pane打开临时放大面板并在命令退出后关闭，shell不抢占前台并在后台运行。

如果配置值无效，Herdr 会回退到安全默认值并在启动时给出警告，此时按警告提示修正[[keys.command]]条目。想彻底恢复默认键位时，herdr config reset-keys会备份config.toml、删除[keys]和[[keys.command]]，重启或执行herdr server reload-config后使用内置默认值。

限制与注意事项

• popup 的宽高小于弹窗最小值时会被钳制，不能通过配置得到比最小尺寸更小的弹窗。
• popup 在命令退出前持有全部输入（包括 Escape），弹窗内程序若依赖 Escape 作为自身快捷键会受到影响。
• 键位绑定、prefix 等设置与终端自身、tmux 的快捷键可能冲突；默认键位优先走 prefix 就是为了不抢占 shell、编辑器和终端程序的输入，直接快捷键绑定前需自行确认终端环境不冲突。
• 排查绑定行为异常时，日志文件在~/.config/herdr/herdr.log（客户端与 server 另有herdr-client.log、herdr-server.log），日志自动轮转。
• 完整的键位字段、类型与默认值可以在 Config reference 中按keys.过滤查看；自定义命令绑定是用户自定义表，不在该参考的逐键列表中，以 Configuration 的 Custom command keybindings 一节为准。键位语法与 prefix-free 玩法的更多说明见 Keyboard。

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