# CLI 代理程式

在你的寫作工作區中，使用你已在終端機執行的代理程式。

把你已安裝的代理程式帶進 Oleafly。**CLI 代理程式** 模式會使用該代理程式的執行環境與登入，讓你可以用已經熟悉的工具，在稿件旁工作。

![設定 → AI 助理 → CLI 代理程式。先在最上方檢查已安裝的代理程式，再展開代理程式完成設定。](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-cli-agents-dark-window-v2.png#view=519,89,883,902)

## 連接代理程式

1. 開啟 **設定 → AI 助理 → CLI 代理程式**，選擇 **檢查已安裝的代理程式**。
2. 展開你的代理程式。**程式** 列會顯示 Oleafly 找到的程式及其位置。
3. 選擇 **測試**。如果卡片要求橋接程式，請先選擇 **安裝橋接程式**。
4. 透過代理程式自己的命令列工具登入。卡片會顯示它的 **登入指令**；開啟專案時，**開啟登入終端機** 會提供一個終端機讓你執行它。
5. 開啟助理，切換到 **CLI 代理程式**，並選擇代理程式。
6. 從小任務開始，例如說明專案結構或修訂一個段落。

如果你切換到尚未就緒的代理程式，助理會顯示一張設定卡片，說明缺少什麼。卡片上的 **設定** 按鈕（例如 **設定 Claude Code**）會在設定中開啟該代理程式。如果只缺少橋接程式，卡片上的 **安裝橋接程式** 會把它安裝起來。

驗證、模型存取與計費都屬於所選的代理程式。支援該 CLI 的帳戶或訂閱，可依該供應商的條款使用；Oleafly 不會另外新增 AI 訂閱。

## 選擇程式

在 **程式** 標籤下，卡片會顯示 Oleafly 啟動的檔案及其來源：**自動偵測到**、**由你選擇**，或 **由 Oleafly 安裝**。對某些代理程式，這一列會改放在 **ACP 橋接** 的詳細資料中。

若要使用另一份副本，請選擇 **選擇…** 並挑選檔案。如果 Oleafly 什麼都沒找到，這一列會顯示 **在這台電腦上找不到**，並提供一個欄位讓你填入位置。輸入或貼上路徑，然後按 Enter 或選擇 **測試**。你挑選或輸入的檔案，必須通過測試才會儲存。**使用自動偵測** 會放棄你的選擇。

Oleafly 會在安裝程式放置代理程式的資料夾中尋找：

- 在 Windows 上，它能找到以 npm、pnpm、Scoop、winget 與類似工具安裝的代理程式，不論位於哪個磁碟機。它每次都會重新讀取搜尋路徑，所以 **檢查已安裝的代理程式** 也能找到你在 Oleafly 開啟期間安裝的代理程式。
- 在 macOS 上，它能找到通常只有你的 shell 才知道的資料夾中的代理程式，例如 `~/.local/bin` 或 nvm 資料夾，即使你是從 Dock 或 Finder 開啟 Oleafly。

當 Oleafly 找到名稱正確但無法使用的檔案時，設定會告訴你它找到了什麼、為什麼不能用。在 Windows 上常見的情況是 PowerShell 指令碼，而 Oleafly 需要的是 `.cmd` 或 `.exe` 版本。**Oleafly 略過的檔案** 會列出每個這類檔案及其原因，例如資料夾、桌面應用程式、`node` 這類 shell 或執行環境，或位於網路位置的副本。

設定中的路徑會保持模糊，直到你將滑鼠移到上面或用 Tab 鍵切換到它們，因此設定的螢幕截圖不會顯示你的檔案存放在哪裡。

## 測試代理程式

**測試** 會在屬於 Oleafly、遠離你專案的空資料夾中啟動代理程式，並等待它回應。它不會儲存任何內容。通過時，你會看到代理程式的名稱與版本。失敗時，你會得到一句說明原因的話，以及一件可以嘗試的事：

| 測試的回報 | 可以嘗試 |
| --- | --- |
| 那裡沒有檔案，或是資料夾、桌面應用程式，或 Oleafly 無法啟動的檔案 | **選擇…** 並挑選程式本身 |
| 橋接程式尚未安裝 | **安裝橋接程式** |
| 代理程式需要 Node.js，或需要更新版本 | **取得 Node.js** |
| 代理程式已啟動但沒有回應、提早停止，或送出了 Oleafly 讀不懂的回覆 | **複製詳細資料**，或用 **開啟終端機** 自己執行 |

如果你選擇的檔案因檔案本身以外的任何原因而失敗，**仍要使用** 會不論如何都儲存它。

## 代理程式目錄

| 代理程式 | CLI 命令 |
| --- | --- |
| Claude Code | `claude` |
| Codex CLI | `codex` |
| Gemini CLI | `gemini` |
| Pi | `pi` |
| OpenCode | `opencode` |
| OpenClaw | `openclaw` |
| Cline | `cline` |
| Hermes Agent | `hermes` |
| CodeBuddy | `codebuddy` |
| Kimi Code | `kimi` |
| Grok Build | `grok` |
| Cursor | `cursor-agent` 或 `agent` |
| DeepSeek Harness | `dsh` |
| Qoder | `qodercli` |

目錄標示了支援的啟動路徑。可用的模型、附件、工作階段接續與用量回報，取決於代理程式提供什麼。設定會在工作階段開始之前回報缺少的需求。

Pi 透過 pi-acp 橋接程式（版本 0.0.34）執行，Oleafly 會讓橋接程式指向你的 Pi 程式。在 Windows 上，它能處理名稱含有空格的專案資料夾。

## 在稿件旁工作

給代理程式一個具體的請求，並在助理面板中追蹤它的回覆、工具活動與權限提示。開啟產生的原始碼，並在 Oleafly 中編譯。

> 讀取引言與方法。列出所有引入方式前後不一致的術語，並附上檔案位置。

如果需要獨立副本與最終審閱，請在[研究任務](/docs/research-tasks/)中選擇可用的代理程式。該頁面列出隔離工作的平台需求。

## 研究起點

新的對話會從代理程式首頁開始，那裡提供研究的起點。選擇其中一個會填入訊息但不會送出，讓你可以先閱讀並調整。如果還沒有開啟任何對話，它會開始一個。

| 起點 | 它要求的內容 |
| --- | --- |
| **文獻檢索** | 針對專案研究問題的附註閱讀清單，使用 `oleafly-literature-sweep` 技能 |
| **相關研究** | 依閱讀清單與參考文獻草擬的相關研究章節，使用 `oleafly-related-work` |
| **引用查核** | 對照稿件的主張與其引用的來源，使用 `oleafly-verify-claims` |
| **稿件審閱** | 審閱完整稿件，使用 `oleafly-review-manuscript` |
| **可重現性查核** | 每項結果要能重現還缺少什麼：程式碼、資料、軟體版本、隨機種子與建置說明 |
| **圖片查核** | 檢查每張圖片與表格：圖說、標籤、交互參照、座標軸標籤與單位、易讀性，以及轉成灰階後仍然清楚的顏色 |
| **Git 審閱** | 摘要未提交的變更與最近的提交，並標出看起來非刻意的編輯。僅在 Git 儲存庫中顯示 |
| **參考文獻整理** | 開啟 **整理參考文獻庫**，在你預覽變更之後，將引用鍵標準化並移除重複項目 |

這些查核與稿件審閱會要求代理程式不要動稿件檔案，並把發現寫入 `research/` 中的檔案，例如 `research/figure-audit.md`。

你選擇的技能（無論是從起點，還是從首頁的技能清單選的）會以標籤形式顯示在訊息上方。Oleafly 會把技能的指示連同你的訊息一起送出，所以拿不到 Oleafly 工具的代理程式（例如 Pi）也能照著做。點選標籤可移除它。如果該專案已關閉這個技能，起點只會填入訊息，而不帶技能。

## 權限請求

當代理程式在行動前先詢問時，卡片會顯示代理程式 **需要權限**，並提供該代理程式自己的選項。如果請求會變更檔案，卡片會列出這些檔案。**顯示變更** 會開啟檔案的差異，讓你在回答之前先閱讀。太大而無法顯示的變更會有相應說明，你可以在這一輪結束後審閱。**關閉** 會取消請求而不允許它。放置兩分鐘沒有處理的請求會過期，代理程式必須重新詢問。

## 審閱並復原變更

在變更了檔案的一輪之後，回覆下方有一行文字說明變更了幾個。**審閱** 會顯示每一項變更，**復原** 與 **重做** 可以逐檔或針對整輪操作。[審閱並復原一輪的變更](/docs/ai-chat/#review-and-undo-a-turn)說明這如何運作，以及它不會動到什麼。

## 對話與匯出

助理標題列有 **新對話**、**已儲存的對話** 與 **代理程式設定**。每段對話都會記錄開始時專案所在的 Git 提交。

若要在 Oleafly 之外保留一份副本，請開啟 **已儲存的對話** 並選擇 **匯出對話…**，然後在儲存對話框中選擇 Markdown 或 JSON。Markdown 檔案的開頭是專案、代理程式、模型、對話開始時所在的提交（會註明未提交的變更），以及開始與最後更新的時間。之後依序是訊息、技能、工具呼叫與變更的檔案。JSON 則保存完整的記錄。

## 自訂代理程式

選擇 **尋找更多代理程式**，可在 ACP 登錄庫中搜尋其他團隊發布的代理程式；或選擇 **新增自訂代理程式**，自行貼上定義。執行之前，請先檢視它的可執行檔或套件、引數與連線需求。登錄定義並不會安裝或啟動代理程式。

## 改用外部用戶端

如果你比較想留在代理程式自己的介面中，請透過 MCP 連接它。[Oleafly 的 MCP 伺服器](/docs/mcp/)會在 Oleafly 保持開啟期間，把應用程式的專案工具提供給它。[`oleafly` 指令](/docs/cli/#connect-an-agent-over-mcp)在應用程式關閉時也能使用，而 [`oleafly-cli` 技能](/docs/cli/#the-oleafly-cli-skill)會教你的代理程式認識它的指令。