---
title: "02 - 安裝與環境選擇（Windows / WSL2 / iPhone）"
type: note
specialty: Programming
tags: [herdr從0開始使用教學, 02-安裝, windows, wsl]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 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 不能用」，而是本教學的重點——**[[08-Claude當大腦-Codex當雙手|多 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 用來定位中文輸入法候選字視窗的游標**，所以中文輸入法的候選框可能出現在錯的位置。要改回原生游標：
>
> ```toml
> [ui]
> host_cursor = "native"
> ```
>
> 代價是游標可能在大量輸出時閃爍或殘留。這是目前的取捨。

---

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

### 1. 裝 WSL2

在 PowerShell（管理員）：

```powershell
wsl --install -d Ubuntu
```

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

### 2. 裝 Herdr

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

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

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

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

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

### 3. 裝兩個 agent

```bash
# 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：

```bash
sudo apt update && sudo apt install -y jq
```

### 5. 驗證

```bash
herdr --version
herdr
```

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

---

## 路線 B：原生 Windows beta

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

```powershell
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](https://getmoshi.app/)（其他 SSH app 也可以，例如 Termius、Blink）。

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

1. **在 WSL2 裡跑 sshd**（比開 Windows 的 OpenSSH Server 再轉進 WSL 單純）：
   ```bash
   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 進去之後：
   ```bash
   herdr
   ```
   就接回**同一個 session**，你電腦上跑到一半的那幾個 Codex 原封不動在那裡。

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

---

## 更新與通道

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

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

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

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

```bash
herdr update --handoff
```

---

## 安裝後建議做的兩件事

### 1. 裝 agent integration

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

```bash
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 補全

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

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

---

## 🔗 相關筆記

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

---

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