CLI 代理

如果你已經在使用 Claude Code 或 Codex，就可以在 Perch 中執行它們。在模型選擇器中選擇其中一個，指定一個資料夾，它就會在那裡使用自己的工具工作，並使用你自己的登入身分。你的 Perch 對話與代理都在同一個側欄中，讓你在同一處掌握它們的進度。

每個代理都在專屬的儲存庫副本中、在自己的分支上工作，因此多個代理可以同時工作，而不會動到你的工作目錄。代理完成後，你可以查看它改了什麼，再一鍵合併到你的資料夾，或開啟 pull request。

開始之前

• Perch Desktop 2.5.4 或更新版本，並登入 Pro 或 Ultra 帳號。網頁版 Perch 沒有 CLI 代理。
• 這台電腦上已安裝並登入 Claude Code 或 Codex。 如果 claude 或 codex 能在你的終端機中執行，Perch 就能啟動它。Perch 使用你安裝的版本與你的登入身分，本身並不附帶其中任何一個。
• Git。 在 Windows 上，請安裝 Git for Windows。合併需要 git 2.40 或更新版本。
• 一個已加入 Perch 的資料夾，而且位於至少有一個 commit 的 git 儲存庫中，代理才能擁有自己的副本。

啟動代理

對話的資訊列會顯示代理正在做什麼、它的名稱、資料夾，以及它的分支，例如 agent/add-a-dark-mode-toggle-t-7q2m。

對話會一直使用開始時的代理。若要改回 Perch 自己的模型，請開始新對話。

代理工作時

• 核准請求會交給你。 代理要求某項權限時，會出現一張寫著 Claude asks to go ahead 的卡片，並附上它提供的選項。
• Mode 設定代理自己的模式，與它在 CLI 中的模式相同，例如 Claude 的 Accept edits。
• 隨時傳送後續訊息。 代理工作時，你送出的訊息會先等候，在這一輪結束時送出。你可以附加 PNG、JPEG、GIF 或 WebP 圖片，每張最多 5 MB。
• Diff 會開啟 Changes 面板，列出代理在其副本中變更的每個檔案。
• Open terminal 會在對話旁開啟終端機，位置在代理的儲存庫副本中。
• 同時執行多個代理。 最多可同時執行四個代理，各自在自己的副本中。側欄會顯示哪些代理正在工作。

專屬的儲存庫副本

預設情況下，每個代理都在 git worktree 中工作：也就是你儲存庫的第二份工作目錄，位於自己的資料夾、自己的分支上。代理工作期間，你的資料夾、它所在的分支，以及你尚未 commit 的任何內容都維持原樣，而且兩個代理絕不會編輯相同的檔案。

一個 worktree 只包含 git 追蹤的檔案。Perch 也會帶入大多數專案執行時需要的東西：

• 本機設定檔。 任何層級的 .env 與 .env.* 檔案，只要被 git 忽略，就會複製進來。若要複製其他被忽略的檔案，例如本機設定或憑證，請在儲存庫根目錄的 .worktreeinclude 檔案中，以 .gitignore 語法列出它們。只有在副本中同樣被 git 忽略的檔案才會複製，因此它絕不會出現在 commit 中。最多 200 個檔案，每個 10 MB，總計 50 MB。符號連結會略過。
• Copy node_modules 位於 macOS 的 Options 中，會將你的 node_modules 複製到副本裡。這是 copy-on-write 的複製：幾乎瞬間完成，而且不佔用額外的磁碟空間。
• Setup command 位於 Options 中，會在代理啟動前，於副本中用你的 shell（Windows 上為 PowerShell）執行 npm install 之類的指令。Perch 會為該儲存庫記住這個指令。如果指令失敗或執行超過 15 分鐘，代理仍會啟動，對話中也會說明。對話資訊列中的 Setup log 會顯示它的輸出。

Options 中還有 Worktree folder，也就是建立副本的位置，以及 Account folder：如果你有多個 Claude Code 或 Codex 登入帳號，請選擇要使用的那個帳號的資料夾。兩者都必須位於你的使用者主資料夾內。

關閉 Worktree，代理就會直接在你的資料夾中工作。它做出的變更會隨即出現在你的資料夾中，也就沒有 diff 或合併的步驟。

取回成果

某一輪變更了檔案時，對話下方會出現一張卡片說明，例如：「Claude changed 4 files in its own copy of perch-app. They're not in your folder yet.」對話的資訊列會持續顯示數量，直到你取回這些變更。Review changes 會開啟 diff。

合併到你的分支

Merge into main 會以你資料夾目前所在的分支命名，它會把代理的所有變更以一個 commit 放到你的分支上。Commit 訊息一開始是對話的標題，你可以修改它。之後，Remove the copy 會刪除代理的 worktree 與分支。

Perch 絕不會為了合併而 stash、reset 或覆寫你資料夾中的任何內容。遇到下列情況時，它會停下來告訴你：

• 你的資料夾有尚未 commit 的變更。 請先 commit，再合併。
• 相同的檔案在你的分支與代理的副本中都有變更。 Ask Claude to fix 會傳訊息給代理，請它在自己的副本中解決。完成後，再合併一次。
• 你的資料夾不在任何分支上，或 git 版本早於 2.40。

其他完成方式

合併按鈕旁的選單還有另外兩個選項：

• Commit only 會在代理自己的分支上 commit 這些變更。你的資料夾不會改變。
• Open pull request 會將代理的分支推送到 origin，並開啟 pull request。如果已安裝 GitHub CLI（gh），Perch 會替你開啟。若未安裝，Perch 會開啟 GitHub 建立新 pull request 的頁面。若是其他 git 託管服務，Perch 會推送分支，再由你在該服務上開啟 pull request。

關閉對話

如果你要關閉的對話，其副本中仍有不在你資料夾中的變更，Perch 會先詢問你：Merge first、Keep the copy（它的 worktree 與分支維持原處），或 Discard（刪除副本與它的分支，包括其中的變更）。

你自己的方案

CLI 代理以你自己的 Claude Code 或 Codex 登入帳號執行，因此它們的用量計入該方案，而不是你的 Perch 用量。傳給它們的訊息不會使用你的 Perch 內含用量。

Perch 會依各代理回報的內容，顯示它自己的上限：5-hour limit 與 Weekly limit，以及各自的重設時間。你可以在模型選擇器中代理的卡片上，以及 Settings › Usage 的 On this computer 下方找到它們；代理接近上限時，訊息框上方也會出現提醒。代理在這台電腦上第一次回覆後，這些資訊才會出現。

隱私

• 對話留在這台電腦上。 CLI 代理的對話不會儲存到你的 Perch 帳號，因此不會出現在網頁版 Perch 或你的手機上。
• 代理與它自己的服務通訊。 你的訊息會從 Claude Code 傳到 Anthropic，或從 Codex 傳到 OpenAI，與你自己使用 CLI 時相同。訊息不會經過 Perch 的伺服器。
• 每個代理只取得它需要的東西。 Perch 啟動代理時，只會提供一份簡短的環境變數清單：不含其他代理的金鑰，也不含任何屬於 Perch 的內容。

搭配子工作階段

Perch 可以把工作的一部分交給 Claude Code 或 Codex。提出要求即可，例如「讓 Codex 在它自己的工作階段中修好那個不穩定的測試」，Perch 就會建議一個在該代理上執行的子工作階段，位於對話資料夾的新 worktree 中。與任何子工作階段一樣，它只會在你選擇 Start 後才開始，並回報給開啟它的對話。代理的核准請求仍然會交給你。

疑難排解

我在模型選擇器中看不到 On this computer。 請確認你已在 Perch Desktop 2.5.4 或更新版本中登入 Pro 或 Ultra 帳號。

代理顯示 Not installed。 請安裝它，讓 claude 或 codex 位於你的 PATH 中，然後結束並重新開啟 Perch。

代理顯示 Needs sign-in。 選擇 Sign in in a terminal，它會替你執行 claude 或 codex login。完成登入後，選擇 Try again。

代理顯示它的 CLI 版本比 Perch 需要的舊。 請更新它。Claude Code 請執行 claude update。Codex 則依你安裝時的方式，透過 npm 或 Homebrew 更新。

代理顯示它需要 Node 22。 這則訊息來自 2.5.4 之前的桌面版建置。請更新 Perch Desktop，它不需要 Node 就能執行代理。

資料夾無法建立 worktree。 資料夾必須位於至少有一個 commit 的 git 儲存庫中。你也可以關閉 Worktree。

在 Windows 上無法移除副本。 副本中有檔案正在其他程式中開啟。請關閉該檔案，然後再試一次。