---
title: "12 - 設定檔、通知、Plugins 與 Socket API"
type: note
specialty: Programming
tags: [herdr從0開始使用教學, 12-設定, config, plugin, socket-api]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

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

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

---

## 設定檔在哪

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

```bash
herdr --default-config
```

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

```bash
herdr server reload-config
```

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

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

---

## 一份給你的起手設定

```toml
# ── 鍵盤 ────────────────────────────────
[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 自訂顯示

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

```bash
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（很實用）

把常用指令綁成快捷鍵：

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

四種 `type`：

| type | 行為 |
|---|---|
| `popup` | session-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 "..."`。

### 給你的兩個實用綁定

```toml
# 快速看目前所有 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` 兩節有完整說明。

日常夠用的只有：

```toml
[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 之間都可攜）。

```bash
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 wrappers** | Shell 腳本、簡單編排、人工除錯 ← **你的情境** |
| **Raw socket API** | 自訂工具、協定 client、事件訂閱者 |

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

要拿 schema：

```bash
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_SESSION` | CLI 指令要用哪個具名 session |
| `HERDR_SOCKET_PATH` | 低階 socket 路徑覆寫 |
| `HERDR_BIN_PATH` | 目前 Herdr binary 路徑（plugin / custom command 用）|
| `HERDR_PROCESS_DETECTION` | Linux process 偵測策略：`native`（預設）或 `child-groups` |
| `HERDR_LOG` | log filter，例如 `HERDR_LOG=herdr=debug` |
| `HERDR_DISABLE_SOUND` | 即使開了聲音通知也不播 |
| `HERDR_AGENT` | 告訴 Herdr 某個 wrapper 後面是哪個 agent |

---

## 🔗 相關筆記

- [[11-遠端與手機工作流]] — 上一步：通知在遠端情境的用法
- [[13-疑難排解與術語速查表]] — 下一步：排錯
- [[04-日常操作-滑鼠與鍵盤]] — keybinding 語法
- [[06-CLI與自動化基礎]] — CLI 層（你主要該用的層）

---

*最後更新：2026-08-04*