02 - 安裝與環境選擇（Windows / WSL2 / iPhone）

← 01-什麼是Herdr | 00-Index | 下一篇 → 03-核心概念

---

先做決定：原生 Windows 還是 WSL2？

這是整份教學最重要的一個決定，因為它會影響後面所有多 agent 編排能不能穩定跑。

Herdr 的穩定版（stable channel）只出 Linux 與 macOS 的 binary。原生 Windows 支援目前是 experimental beta，而且只走 preview channel。

項目	原生 Windows（beta）	WSL2 內的 Linux Herdr（stable）
發布通道	preview only（beta，可能 regress）	stable
本機持久 session / pane	beta 可用	✅ 完整
Agent 偵測方式	掃 pane shell 的子 process 樹	✅ Unix foreground process group（原生設計）
herdr agent attach（單 agent 直連）	❌ 不支援	✅
herdr --remote <host>	❌ 不支援	✅
Live server handoff（更新不中斷）	❌ 不支援	✅
Plugins	preview、best effort	✅
剪貼簿貼圖給 agent	unverified	✅（macOS/Linux 路徑）
游標 / CJK 輸入法定位	partial（見下方）	✅
Windows Terminal 體驗	原生，最順	一樣在 Windows Terminal 裡開

👉 建議：用 WSL2

理由不是「Windows beta 不能用」，而是本教學的重點——多 agent 編排 高度依賴 agent 偵測的準確度。官方文件對 Windows 偵測的說法是：

Windows agent process detection scans descendants of the pane shell and recognizes direct agents plus common command wrappers. It is useful for Codex, Claude, and similar agents, but it is not the same as Unix foreground process-group detection.

也就是說 Codex / Claude 在 Windows 上能被認出來，但那條路徑是 best-effort。當你要靠 agent wait 判斷「這個 Codex 到底做完沒」時，偵測準確度直接決定編排會不會卡死。

而且 WSL2 對你完全沒有額外成本：兩個 repo 都是 git + Node/Python，本來就在 Linux 上跑得更順（Taiwan_IM_board 的 tools/*.py、Obsidian-med-note 的 ImageMagick 截圖 SOP 都是）。

⚠️ 一個 WSL 也有的小地雷：Herdr 在原生 Windows 與 WSL 上，預設 host_cursor = "auto" 會把游標畫成終端格子內容（為了避免 ConPTY 重繪時游標閃爍）。這個畫出來的游標不是 Windows 用來定位中文輸入法候選字視窗的游標，所以中文輸入法的候選框可能出現在錯的位置。要改回原生游標：

[ui]
host_cursor = "native"

代價是游標可能在大量輸出時閃爍或殘留。這是目前的取捨。

---

路線 A（建議）：WSL2 + Linux Herdr

1. 裝 WSL2

在 PowerShell（管理員）：

wsl --install -d Ubuntu

裝完重開機，設好 Linux 使用者名稱與密碼。之後都在 Windows Terminal 開 Ubuntu 分頁 工作。

2. 裝 Herdr

curl -fsSL https://herdr.dev/install.sh | sh

安裝腳本會抓對應平台的 binary 並放到 PATH。若之後 herdr 指令找不到，重開終端機或檢查安裝目錄有沒有在 PATH 上。

也可以用你已經在用的套件管理器：

brew install herdr        # 如果有 Homebrew
mise use -g herdr         # 如果有 mise

Homebrew / mise / Nix 安裝的版本只走 stable channel，而且更新要用該套件管理器（herdr update 在那些安裝上是停用的）。

3. 裝兩個 agent

# Claude Code
npm install -g @anthropic-ai/claude-code   # 依官方最新安裝方式為準
claude                                      # 首次啟動登入 Claude Pro 帳號
 
# Codex CLI
npm install -g @openai/codex                # 依官方最新安裝方式為準
codex                                       # 首次啟動用 ChatGPT Plus 帳號登入

兩個 CLI 的安裝方式各自官方可能會變（npm / brew / 安裝腳本），以官方文件為準。這裡的重點是：兩支指令都要在同一個 WSL 環境的 PATH 上，Herdr 才能在 pane 裡啟動它們。

4. 裝 jq（編排必備）

Herdr 的控制指令回傳 JSON，後面所有腳本都靠 jq 抽 ID：

sudo apt update && sudo apt install -y jq

5. 驗證

herdr --version
herdr

看到 TUI 就成功了。按 ctrl+b 再按 q 可以 detach 離開。

---

路線 B：原生 Windows beta

如果你就是想在 Windows 原生跑（例如專案在 C:\ 上、不想跨檔案系統）：

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

要知道的事：

• Windows 版只從 preview channel 發布，Herdr 在 Windows 上會自動預設 preview，不用改設定。herdr channel set stable 在 Windows 上會被拒絕。
• 安裝器把各版本放在 %USERPROFILE%\.herdr\packages\standalone\releases，用 %LOCALAPPDATA%\Programs\Herdr\bin 指向目前版本（用 junction 切換，所以更新不用覆蓋正在跑的 herdr.exe）。
• 更新後要重啟正在跑的 Herdr session（Windows 沒有 live handoff）。
• 手動下載的話，herdr-windows-x86_64.zip 裡除了 herdr.exe 還有 app-local ConPTY runtime，整個資料夾要一起保留，不能只複製 exe。

Windows 版的貼上與複製

• 複製：直接在 pane 裡拖選文字即可（Herdr 自己處理）。
• 貼上：用 Windows Terminal 的 ctrl+shift+v。多行貼上會用 bracketed paste 包起來，所以 shell 和 agent prompt 會當成一次貼上，不會每行各自送出。
• 想用外層終端機自己的右鍵貼上：按住 shift 再右鍵。

---

iPhone 怎麼進來？

iPhone 上不會跑 Herdr。 官方的答案很直接：不需要 mobile app、也沒有 web dashboard，裝一個 SSH client，連到跑 agent 的那台機器，在那邊跑 herdr 就好。TUI 會自己適應窄螢幕。

官方在 iPhone 上推薦 moshi（其他 SSH app 也可以，例如 Termius、Blink）。

要讓 iPhone 連回你的 Windows PC，你需要（以下是環境搭建建議，非 Herdr 官方文件內容）：

1. 在 WSL2 裡跑 sshd（比開 Windows 的 OpenSSH Server 再轉進 WSL 單純）：

   sudo apt install -y openssh-server
   sudo systemctl enable --now ssh

   WSL2 的網路是 NAT，要從外部連進來需要 port forwarding 或用下一項。

2. 用 Tailscale 之類的 mesh VPN 把手機和電腦放進同一個私網——這是最省事、也最安全的做法（不用開 router port、不用固定 IP）。Tailscale 有 Linux 版可以直接裝在 WSL2 裡。

3. 手機 SSH 進去之後：

   herdr

   就接回同一個 session，你電腦上跑到一半的那幾個 Codex 原封不動在那裡。

⚠️ 注意：從 Windows 端要連到別台機器時，原生 Windows 的 herdr --remote 不支援。官方建議是先 ssh you@server 再在對方跑 herdr。詳見 11-遠端與手機工作流。

---

更新與通道

herdr update              # 從設定的通道下載安裝
herdr channel show        # 看目前是 stable 還是 preview
herdr channel set preview # 想搶先拿修正時
herdr channel set stable  # 換回穩定版（Linux/macOS 直裝）

更新完，如果新版改了 client/server 協定，Herdr 會問你要不要停掉舊 server。停 server 會結束所有 pane process，所以：

herdr server stop   # 停掉預設 session
herdr               # 再開一次

想試不中斷的實驗性移轉（Unix only）：

herdr update --handoff

---

安裝後建議做的兩件事

1. 裝 agent integration

讓 Herdr 拿到 agent 的原生 session 資訊（server 重啟後可以續接對話）：

herdr integration install claude
herdr integration install codex
herdr integration status

• claude integration 會寫 ~/.claude/hooks/herdr-agent-state.sh 並更新 settings.json。~/.claude 目錄必須已經存在（所以先跑過一次 claude）。
• codex integration 會寫 ~/.codex/herdr-agent-state.sh、更新 hooks.json、確保 config.toml 有 [features] hooks = true。同樣**~/.codex 要先存在**。
• ⚠️ 這兩個都是 session identity 型 integration，不是 lifecycle 權威。Claude 與 Codex 的 working/idle/blocked 仍然來自 Herdr 的畫面偵測（screen manifest）。這點很重要，05-Agent偵測與狀態機制 會細講。

2. 開 shell 補全

herdr completion bash > ~/.local/share/bash-completion/completions/herdr
# 或 zsh：
mkdir -p ~/.zfunc && herdr completion zsh > ~/.zfunc/_herdr

指令樹很大，補全會省下大量查文件的時間。

---

🔗 相關筆記

• 01-什麼是Herdr — 先搞懂它是什麼
• 03-核心概念 — 下一步：四層模型
• 11-遠端與手機工作流 — iPhone 連回來的完整做法
• 13-疑難排解與術語速查表 — 裝不起來 / 指令找不到時看這裡
• Codex 02 - 安裝與第一次啟動 — Codex 本身的安裝與登入

---

最後更新：2026-08-04