Andrew的筆記園地

閱讀時間約 9 分鐘

⬇ MD

12 - 設定檔、通知、Plugins 與 Socket API

← 11-遠端與手機工作流 | 00-Index | 下一篇 → 13-疑難排解與術語速查表

設定檔在哪

Herdr 用一個全域 TOML 設定檔。想看所有預設值：

herdr --default-config

改完之後不用重啟整個 session：

herdr server reload-config

reload-config 會套用可重載的設定，不會重啟 pane。（不是每個設定都可熱重載，例如 HERDR_PROCESS_DETECTION 這種 server 啟動時讀的環境變數就要重啟。）

用 HERDR_CONFIG_PATH 可以覆寫設定檔路徑。

一份給你的起手設定

# ── 鍵盤 ────────────────────────────────
[keys]
prefix = "ctrl+b"
# 加上免 prefix 的直接和弦（ctrl+alt 這族最安全）
focus_pane_left  = ["prefix+h", "ctrl+alt+h"]
focus_pane_down  = ["prefix+j", "ctrl+alt+j"]
focus_pane_up    = ["prefix+k", "ctrl+alt+k"]
focus_pane_right = ["prefix+l", "ctrl+alt+l"]
zoom             = ["prefix+z", "ctrl+alt+z"]
 
# ── UI ──────────────────────────────────
[ui]
mouse_capture = true
# Windows / WSL 若中文輸入法候選框位置跑掉，改成 "native"
host_cursor = "auto"
 
# ── 通知（SSH / 手機用 terminal）────────
[ui.toast]
delivery = "terminal"
delay_seconds = 1
 
[ui.toast.herdr]
position = "bottom-right"
 
# ── 聲音 ────────────────────────────────
[ui.sound.agents]
codex = "on"
claude = "on"
 
# ── Worktree 放哪 ───────────────────────
[worktrees]
directory = "~/Projects/worktrees"
 
# ── Agent session 續接（預設就是 true）──
[session]
resume_agents_on_restore = true
 
# ── ⚠️ 預設關閉，想清楚再開 ─────────────
# [experimental]
# pane_history = true

完整選項見官方 Config reference：https://herdr.dev/docs/config-reference/

Sidebar 的 Agent row 可以顯示 metadata token。搭配 05-Agent偵測與狀態機制 講的 report-metadata：

herdr pane report-metadata w1:p2 \
  --source user:fanout \
  --display-agent "Codex: 心臟" \
  --token summary="114-001~012" \
  --state-label working="產出詳解中" \
  --ttl-ms 3600000
  • Pane token 在 Agent row 用 $name 引用（例如 $summary）；workspace token 在 Space row 用。
  • Agent row 也可以選擇顯示 terminal_title 或 terminal_title_stripped（預設 row 不含）。後者會移除一個開頭的活動 / spinner 字元。
  • 文字會被正規化：去掉前後空白、移除控制字元，--title / --display-agent / --state-label / token 值上限 80 字元。
  • --ttl-ms 範圍 1 ~ 86400000（24 小時）。省略就是「留到被取代、清除、或 pane 關閉為止」。
  • ⚠️ 一個 pane 或 workspace 在生命週期內最多接受 32 個不同 source 的 token 回報，清除或過期不會釋放 source 名額。腳本裡不要用「每次跑都換一個 source 名稱」的寫法。

Custom command keybindings（很實用）

把常用指令綁成快捷鍵：

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

四種 type：

type行為
popupsession-modal 彈窗，不改變 tab 版面；接收所有輸入（含 Escape）直到指令結束
pane開一個暫時的 zoom pane，指令結束就關
shell背景 detached 執行
plugin_action呼叫已安裝的 plugin action id

⚠️ Popup 不是 Herdr pane：它不會匯出 HERDR_PANE_ID，也不參與 pane / agent API。要拿底下那個 tiled pane 的 ID 用 HERDR_ACTIVE_PANE_ID。

Custom command 會拿到：HERDR_SOCKET_PATH、HERDR_BIN_PATH、HERDR_ACTIVE_WORKSPACE_ID、HERDR_ACTIVE_TAB_ID、HERDR_ACTIVE_PANE_ID、HERDR_ACTIVE_PANE_CWD。

Windows 注意：custom command 字串走 cmd.exe /d /c，所以環境變數要用 %HERDR_BIN_PATH% 語法。要用 PowerShell 語法就明確呼叫：powershell.exe -NoProfile -Command "..."。

給你的兩個實用綁定

# 快速看目前所有 agent 狀態
[[keys.command]]
key = "prefix+alt+a"
type = "popup"
command = "sh -c 'herdr agent list; read -p \"press enter\"'"
description = "list agents"
 
# 一鍵跑 vault lint
[[keys.command]]
key = "prefix+alt+v"
type = "pane"
command = "python3 _wiki_meta/lint.py"
description = "vault lint"

Theme 與 sidebar 版面

Herdr 有內建主題，也可以自訂 sidebar row 版面（哪些欄位、順序、token 放哪）。這部分選項很多，官方文件的 ## Theme 和 ## UI and sidebar / ### Sidebar row layouts 兩節有完整說明。

日常夠用的只有：

[ui]
mouse_capture = true

以及 prefix+b 開關 sidebar。

Plugins（可以先跳過）

Herdr 的 plugin 是可分享的可執行工作流套件——Bash 腳本、JavaScript app、Lua、Rust binary 都行。

核心設計：Herdr 擁有 host 面（安裝、manifest 驗證、keybinding、終端 pane、事件、context 注入、socket 存取）；plugin 擁有自己的實作語言、相依、檔案和持久狀態。

🔑 沒有獨立的 plugin SDK。整個 Herdr CLI 就是 plugin API。 你自己能跑的 herdr ... 指令，plugin 都能跑。多數 plugin 應該透過 HERDR_BIN_PATH 呼叫 Herdr（這樣在 Unix socket 和 Windows named pipe 之間都可攜）。

herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
herdr plugin list [--json]
herdr plugin link <path>              # 本機開發
herdr plugin enable <plugin_id>
herdr plugin uninstall <plugin_id>
herdr plugin action invoke <action_id>
herdr plugin config-dir <plugin_id>

社群 plugin 索引在 https://herdr.dev/plugins/（自動索引打了 herdr-plugin GitHub topic 的公開 repo）。

⚠️ 信任問題（重要）

Plugin 就是在你機器上執行的一般程式碼。安裝或 link 時，它的 build 和 runtime 指令以你的身分、用你的環境執行，而且可以呼叫完整的 Herdr CLI。

Marketplace 的收錄是自動且未經審核的——上架只代表那個 repo 自己打了 tag，不代表 Herdr 審查過。

實務守則：

  • 只裝你信任的作者 / repo
  • 先看過 herdr-plugin.toml 和它要跑的腳本（plugin install 在互動式終端會顯示預覽）
  • 用 --ref 釘住特定版本
  • ⚠️ 你的機器上有醫學筆記和理財資料，這條特別要遵守

📌 給你的建議：現階段先不要裝任何 plugin。你的需求（多 agent 編排）用 CLI + 一個 shell 腳本就完全滿足了，沒必要引入信任風險。 Plugin 在 Windows 是 preview / best effort，也是另一個先跳過的理由。

Socket API（要寫工具時才需要）

Herdr 有一套本機 socket API，給需要檢視或控制 running session 的腳本和 agent 用。

三層整合，選對層很重要：

層用途
Agent skill教 coding agent 從 pane 裡面用 Herdr ← 你的情境
CLI wrappersShell 腳本、簡單編排、人工除錯 ← 你的情境
Raw socket API自訂工具、協定 client、事件訂閱者

👉 大多數自動化應該從 CLI wrapper 開始。 只有在你需要直接的 request/response 控制、或長生命週期的事件訂閱時，才用 raw socket API。 你目前的需求完全落在前兩層。

要拿 schema：

herdr api schema                                  # 摘要
herdr api schema --json                           # 完整 JSON Schema
herdr api schema --output herdr-api.schema.json   # 寫檔

Schema 涵蓋 raw request、成功回應、錯誤回應、發出的事件、訂閱事件。

唯一可能對你有用的 raw 功能：事件訂閱

CLI 的 wait 是「等一個狀態」。如果你想要「持續監看所有 agent 的狀態變化」（例如寫一個把狀態推到手機的小工具），那要用 socket 的事件訂閱。

但講白了：herdr notification show + [ui.toast] delivery = "terminal" 已經解決 90% 的通知需求，先別自己造輪子。

環境變數速查

變數用途
HERDR_ENV在受管理的 pane process 裡是 1 ← agent skill 的守門條件
HERDR_PANE_ID / HERDR_TAB_ID / HERDR_WORKSPACE_ID目前 pane 的公開 ID
HERDR_CONFIG_PATH覆寫設定檔路徑
HERDR_SESSIONCLI 指令要用哪個具名 session
HERDR_SOCKET_PATH低階 socket 路徑覆寫
HERDR_BIN_PATH目前 Herdr binary 路徑（plugin / custom command 用）
HERDR_PROCESS_DETECTIONLinux process 偵測策略：native（預設）或 child-groups
HERDR_LOGlog filter，例如 HERDR_LOG=herdr=debug
HERDR_DISABLE_SOUND即使開了聲音通知也不播
HERDR_AGENT告訴 Herdr 某個 wrapper 後面是哪個 agent

🔗 相關筆記

最後更新：2026-08-04

關係圖譜

反向連結