Pi Agent 完整實戰教學：npm 一鍵安裝、串接 OpenAI／Anthropic／本地模型，跑一輪真實任務給你看

Pi Agent 安裝前檢查：Node.js 環境、npm 來源與一鍵安裝實錄

接下來要實際動手安裝 Pi Agent。官方套件名稱是 @earendil-works/pi-coding-agent，安裝方式很單純，就是用 npm 一行指令搞定。但「一行指令」能不能成功，取決於安裝前的地基有沒有打穩。這一節先檢查三件事：Node.js 版本、npm registry 連線狀態、以及終端機目前所在的工作目錄。三項都確認沒問題，再執行安裝，驗證版本與資料夾結構。

檢查一：Node.js 版本是否達標

Pi Agent 是以 TypeScript 撰寫的 CLI 工具，執行環境需要 Node.js。官方並未明文列出最低版本門檻，但根據套件性質與社群回報，建議使用 Node.js 20 以上的長期支援版本，Node.js 22 或更新版本更穩妥。原因在於 Pi Agent 依賴現代 JavaScript 的語法與原生 API，舊版 Node.js 可能缺少必要的執行環境，導致安裝過程沒有報錯，啟動時卻冒出奇怪的錯誤訊息。

打開終端機，輸入以下指令檢查目前版本：

node -v

正常輸出會類似 v22.14.0。若輸出的是 v18.x 或更舊的版本，建議先升級 Node.js。台灣讀者常用的升級方式有兩種：一是直接到 Node.js 官方網站下載最新 LTS 安裝檔，覆蓋安裝即可；二是使用 nvm（Node Version Manager）切換版本。使用 nvm 的好處是可以在不同專案間自由切換 Node.js 版本，避免全域環境互相干擾。執行 nvm install 22 與 nvm use 22 就能完成切換。

順帶一提，檢查 Node.js 版本的同時，也建議一併檢查 npm 版本：

npm -v

npm 通常會隨著 Node.js 一起安裝，但版本過舊可能影響套件解析，建議使用 npm 10 以上。

檢查二：npm registry 連線狀態

第二個關鍵檢查是 npm registry。Pi Agent 套件發布在 npm 官方 registry 上，如果終端機的 npm 來源被設定成其他鏡像，或是公司內網的私有 registry，就可能出現兩種狀況：第一，根本找不到 @earendil-works/pi-coding-agent 這個套件；第二，找到的是過期或不相容的版本。很多安裝失敗的案例，問題都不在套件本身，而是 registry 設定擋在中間。

檢查目前使用的 registry：

npm config get registry

正常應該回傳 https://registry.npmjs.org/。如果回傳的是其他網址，例如中國市場常見的 npmmirror 鏡像，或公司內部的 Verdaccio 伺服器，請先確認該來源是否同步了這個套件。若不確定，最保險的做法是暫時切回官方來源，指令如下：

npm config set registry https://registry.npmjs.org/

另外可以實際測試 registry 的連線品質，執行：

npm ping

這個指令會向 registry 送出測試要求，順利的話會回傳類似 PING https://registry.npmjs.org/ 的訊息。若卡住不動或出現逾時錯誤，代表網路層有問題，可能是公司防火牆阻擋、VPN 未開啟、或 DNS 解析異常。此時先排除網路障礙再繼續，否則安裝過程會卡在等待回應。

檢查三：終端機工作目錄

第三個檢查經常被忽略，卻最容易造成混亂。npm 安裝套件時，會把套件放在目前工作目錄底下的 node_modules 資料夾。如果在不適當的目錄執行安裝，例如系統根目錄、使用者家目錄、或已經有其他專案的資料夾，後續會很難管理。

安裝前先確認目前位置：

pwd

建議的做法是為 Pi Agent 建立一個專屬資料夾，例如：

mkdir pi-playground
cd pi-playground

這樣一來，所有相關檔案都會集中在同一個目錄，日後要刪除或備份都很直覺。另外，執行 ls -la 看一下資料夾內容，確認沒有殘留的舊版 node_modules 或 package-lock.json，避免版本衝突。

執行一鍵安裝

三個檢查都通過後，就可以執行安裝了。官方提供的指令是：

npm install @earendil-works/pi-coding-agent

這個指令會把套件安裝在目前資料夾的 node_modules 中，並在 package.json 裡記錄相依關係。若目前資料夾還沒有 package.json，npm 會自動建立。安裝過程會看到進度條跑動，結束後出現類似以下輸出：

added 214 packages in 12s

安裝的套件數量會隨相依項目增減，重點是沒有出現 ERR! 開頭的錯誤訊息。若出現權限錯誤，例如 EACCES，代表目前使用者沒有寫入權限，請不要在指令前面加上 sudo 強行安裝，比較好的做法是修正資料夾的擁有者，或改用 nvm 管理 Node.js 環境，這樣就不會有全域寫入權限的問題。

另外，若希望全域都能直接使用 pi 指令，可以改用：

npm install -g @earendil-works/pi-coding-agent

但筆者建議先以專案內安裝的方式試跑，確認使用習慣後再決定是否裝到全域。專案內安裝的好處是版本明確，不同專案可以各自鎖定不同版本的 Pi Agent，不會互相干擾。

安裝後的版本驗證

安裝完成後，先做最基本的驗證，確認執行檔有正確連結：

npx pi --version

若安裝的是專案內套件，npx 會自動找到 node_modules/.bin/ 底下的執行檔。正常會回傳版本號，例如 0.1.0 或更新的版本。如果出現 command not found，代表 PATH 設定有問題，檢查 node_modules/.bin 是否存在，確認安裝過程是否真的完成。

接著可以查看說明文件：

npx pi --help

這個指令會列出 Pi Agent 支援的子指令與參數，包括如何設定模型供應商、如何啟動互動模式等。看到完整的說明輸出，代表安裝檔案沒有缺漏。

資料夾結構說明

安裝完成後，資料夾內會多出以下結構：

• node_modules/：存放所有相依套件，包括 Pi Agent 本身與其依賴的程式庫。這個資料夾可以隨時刪除，再用 npm install 重建。
• package.json：記錄專案名稱、版本、相依套件清單。若原本不存在，npm 會自動產生。
• package-lock.json：鎖定每個相依套件的確切版本。Pi Agent 官方強調供應鏈硬化，所有 npm 相依套件都固定版本，lockfile 是 ground truth，因此這份檔案非常重要，建議提交到版本控制系統。

若使用全域安裝，則不會有這些檔案，執行檔會放在 Node.js 全域的 bin 目錄中。

安裝失敗的常見原因與排除

即使前面三項檢查都通過，安裝仍可能遇到突發狀況。最常見的是網路連線不穩，npm 在下載大型套件時中斷，解法是重新執行安裝指令，npm 會自動續傳或重新下載。是防毒軟體或企業資安軟體阻擋 npm 執行子程序，這在台灣的企業環境中並不少見，需與 IT 部門確認 npm 是否在白名單內。

另一個容易忽略的點是 npm cache 損壞。若反覆安裝都失敗，可以執行：

npm cache verify

然後再重試一次安裝。若還是失敗，可以暫時用 npm cache clean --force 清空快取，但這是手段，不建議常態使用。

小結

Pi Agent 的安裝門檻確實很低，只要 Node.js 20 以上、npm registry 指向官方來源、工作目錄乾淨，一行指令就能完成。但門檻低不代表不需要檢查，環境差異往往才是安裝失敗的主因。把這三項檢查變成習慣，往後安裝任何 npm 套件都能少走冤枉路。

安裝完成只是起點，下一步是設定模型供應商。Pi Agent 本身不綁定任何特定 AI 服務，支援 OpenAI、Anthropic、Google 等二十多家供應商，超過三百種模型。要接上哪一家、API 金鑰怎麼設定、以及如何用 OpenRouter 或本地模型降低成本，下一節會實際操作給讀者看。

pi 指令啟動與專案設定：從 pi init 到第一個對話

上一章完成安裝之後，讀者手上已經有了一個可以執行的 pi 指令。接下來要面對的問題是：這個指令第一次打下去會發生什麼事？是直接跳出對話框，還是要先做一堆設定？以 Pi Agent 的極簡哲學來看，開發者 Mario Zechner 的目標是讓使用者「打開就能用」，但模型供應商的 API 金鑰總得先交代清楚，不然模型呼叫無從發生。這一段我們實際操作一遍，從 pi init 建立設定檔開始，一路走到第一次對話成功。

為什麼要先跑 pi init

安裝完成後，直接輸入 pi 其實也能啟動互動式 CLI，Pi 會以預設值嘗試連線。問題是預設值不見得符合需求，例如模型供應商沒指定、API 金鑰沒設定，程式會先卡在驗證階段，連對話框都進不去。與其讓使用者碰壁，不如先執行 pi init 把環境一次設定到位。

pi init 的動作可以用一句話概括：在專案資料夾裡建立一個設定檔，把模型供應商、模型名稱、API 金鑰來源等參數寫進去。這個設定檔就是日後每次啟動 pi 的依據，也是讓工作環境「可重複使用」的關鍵。官方文件在 pi.dev/docs 有詳細說明，建議讀者先開著那份文件，邊看邊操作。

設定檔的存放位置

執行 pi init 之後，程式會在使用者的家目錄底下建立一個名為 .pi 的資料夾，設定檔主體通常叫做 config.json。這個位置的好處是跨專案共用，意思是你在 A 專案設好的模型供應商與金鑰，換到 B 專案時不必重新設定。如果團隊希望每個專案各自獨立，也可以在專案根目錄手動放置設定檔，Pi 會優先讀取專案層級的設定，再回退到家目錄的全域設定。

開啟設定檔會看到幾個主要區塊：model 指定供應商與模型名稱，apiKey 指向環境變數或直接寫入金鑰，temperature 控制回應的隨機程度，還有 extensions 列出要掛載的擴充套件。初次產生的檔案通常只含基本欄位，其他參數會在後續操作中慢慢被補上。

模型供應商註冊的兩種方式

Pi Agent 本身不綁定任何特定 AI 服務，這是它與 Claude Code 或 Codex 最明顯的差異。根據官方 GitHub 的說明，Pi 支援 OpenAI、Anthropic、Google 等二十多家供應商，超過三百種模型，統一透過 pi-ai 套件呼叫 API。註冊供應商有兩種常見路徑。

第一種是設定環境變數，例如使用 Anthropic 模型時先執行 export ANTHROPIC_API_KEY=你的金鑰，使用 OpenAI 就設定 OPENAI_API_KEY。這種做法把金鑰留在 shell 層級，不寫進設定檔，安全性較高，也符合「設定檔可以進版本控制」的需求。

第二種是透過 pi init 的互動選單選擇供應商，程式會引導使用者貼上 API 金鑰，並寫入設定檔。這種方式方便，但要注意設定檔若被同步到公開 repository，金鑰等於直接外洩。作者在 README 中特別提醒過供應鏈安全，建議金鑰一律用環境變數管理。

另外一個實用選項是透過 OpenRouter 這類聚合服務。只要註冊一組 OpenRouter 金鑰，就能在同一個介面底下切換各家模型，對想比較模型表現、又不想維護多組金鑰的使用者非常友善。如果偏好本地模型，也可以把供應商指向 Ollama 或 LM Studio，跑完 pi init 之後在互動選單中選擇本地端點即可。

第一次啟動：你看到的介面元素

設定完成後，在專案目錄輸入 pi，畫面會出現一個簡潔的互動式介面。最上方是模型名稱與當前工作目錄的顯示，讓使用者確認自己正在跟哪個模型對話。中間是對話歷史區域，每一輪的問答都會往上捲動，就像一般的終端聊天室。最下方是輸入列，支援多行輸入，需要送出時按 Enter 即可。

介面上最值得注意的，是右側或底部的工具列區域。Pi 的核心工具只有四個，分別是 read、write、edit 與 bash，這個設計呼應作者 Mario Zechner 在 起源文章 中的主張：frontier model 經過大規模強化學習之後，早就不需要一萬個 token 的 system prompt 來提醒自己該怎麼寫程式，只需要幾個工具就夠了。介面上會看到這四個工具的狀態燈，模型正在執行工具時，對應的燈號會亮起，使用者可以即時掌握目前的執行階段。

第一次啟動時，Pi 會先讀取設定檔，確認 API 金鑰有效，然後在畫面上印出一行提示，例如「已連接 Anthropic Claude Sonnet」，看到這行文字就代表準備就緒。此時輸入「你是誰」或「列出目前目錄的檔案」，就能得到模型回應，第一個對話就成功了。

把起手式變成固定流程

反覆操作幾次之後，可以歸納出一套固定的起手式流程，往後開新專案時直接照做：

1. 確認 Node.js 版本在 20 以上，並檢查 npm registry 是否指向官方來源。
2. 用 npm install -g @earendil-works/pi-coding-agent 安裝最新版本。
3. 設定環境變數，至少準備一組模型供應商的 API 金鑰。
4. 在專案目錄執行 pi init，選擇供應商與模型，產生設定檔。
5. 輸入 pi 啟動互動式 CLI，確認連線提示出現。

這套流程在 Composio 於 2026-08-10 發表的實測 中也被驗證過，該測試花了 100 小時比較 Pi 與 Claude Code，Pi 在自訂工具評估中通過 20／30 個任務，每個成功任務的成本是 0.028 美元，而 Claude Code 是 16／30 個、0.195 美元。成本差距接近七倍，對用量大的團隊來說，這個起手式流程能直接轉換成可觀的節省。

不過，作者在官方 README 中一再強調，Pi 沒有內建的權限系統，預設以啟動者的權限執行所有指令。這代表若以 root 身分啟動，模型就有完整的系統控制權。社群與文件都建議，正式環境務必搭配容器或 sandbox 隔離，比如用 Docker 包住整個工作目錄，把損害範圍限制在容器內。

當第一個對話成功送出、模型開始回應的那一刻，Pi 的極簡設計會立刻讓使用者感受到與其他 coding agent 的差異。沒有複雜的 onboarding 流程，沒有嚇人的權限設定畫面，有的只是乾淨的對話框與四個工具。下一章會實際指派一個真實任務，讓模型從讀取檔案、修改程式到執行測試，完整跑一輪，驗證這套極簡架構在實務上的表現。

串接 OpenAI 與 Anthropic：API Key、環境變數與模型切換實測

Pi Agent 的核心優勢之一，就是透過 pi-ai 這個統一介面，一口氣支援超過二十家供應商、三百多個模型。官方 GitHub 儲存庫上明確標示，OpenAI、Anthropic、Google 都在支援清單之中（2026 年 8 月查證）。對比 Claude Code 只能綁定 Anthropic 的模型，Pi 讓使用者自行決定每一次對話要用哪一家模型，這正是按量計費精神的最佳體現。以下我們實際操作一遍，從 API Key 的環境變數設定開始，一路測到模型切換。

API Key 的環境變數設定

Pi Agent 讀取 API Key 的方式與多數開源工具相同，優先從環境變數取得。OpenAI 對應的是 OPENAI_API_KEY，Anthropic 對應的是 ANTHROPIC_API_KEY。第一次設定的時候，我們可以在終端機直接輸入 export 指令，這個方法只對目前這個終端視窗有效，關掉就沒有了，適合快速測試。

export OPENAI_API_KEY="sk-你的金鑰"
export ANTHROPIC_API_KEY="sk-ant-你的金鑰"
pi

如果要長期使用，建議把這兩行寫進 shell 設定檔，例如 zsh 使用者編輯 ~/.zshrc，bash 使用者編輯 ~/.bashrc。還有另一個更安全的方式，就是在專案目錄放一個 .env 檔案，Pi 啟動時會自動載入。這樣一來，API Key 不會散落在 shell 歷史紀錄裡，專案換人接手時也比較好管理。務必把 .env 加進 .gitignore，避免不小心把金鑰推上 Git 儲存庫。

設定檔中的 provider 區塊

除了環境變數，Pi 也允許在設定檔中明確定義 provider 區塊。設定檔通常放在專案根目錄，我們可以在此指定各家供應商的預設模型、API 位址，甚至是自訂的 baseUrl。例如想把 OpenAI 的請求導向相容閘道，只需要改 baseUrl 欄位即可。以下是簡化的示意內容，實際欄位名稱以官方文件為準：

{
  "providers": {
    "openai": {
      "model": "gpt-4o"，
      "apiKey": "${OPENAI_API_KEY}"
    }，
    "anthropic": {
      "model": "claude-sonnet"，
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  }
}

這裡的 apiKey 欄位可以填入金鑰本身，也可以寫成指向環境變數的參照。實務上建議優先使用環境變數，因為設定檔一旦進入版本控制，直接寫死的金鑰就會變成資安漏洞。Anthropic 區塊若沒有特別指定，Pi 會自動讀取 ANTHROPIC_API_KEY，這點對初學者相當友善。

指定模型：gpt-4o 與 claude-sonnet 的實際呼叫

完成基本設定後，我們用同一句提示詞分別呼叫兩個模型。測試指令可以透過命令列參數指定模型，也可以進入對話後用斜線指令切換，詳細用法可查閱 pi.dev 官方文件。我們選的提示詞是：「請用 TypeScript 寫一個函式，計算第 n 個費式數列數字，並說明時間複雜度」。這個問題同時考驗程式碼生成能力與原理說明能力。

先以 gpt-4o 執行。Pi 啟動後，在對話框輸入提示詞，模型很快回應了一份遞迴實作，並補充了以動態規劃實作的版本。OpenAI 的回應風格偏向直接給出最佳解，時間複雜度的說明簡潔扼要。接著我們切換到 Anthropic 的 claude-sonnet，用同樣的提示詞再問一次。Claude 的回應多了逐步推導的過程，先解釋費式數列的遞迴關係，再列出三種實作方式。

比較兩者的內容，gpt-4o 的程式碼較精簡，註解較少；claude-sonnet 的版本則在每個函式上方附上說明區塊，並額外列出空間複雜度。兩者的核心邏輯都正確，差異主要在說明風格。對需要快速理解的開發者來說，Claude 的逐步說明比較容易上手；對想要直接複製貼上的場景，OpenAI 的精簡風格反而更快。

模型切換的過程相當流暢。使用命令列參數的方式，啟動時指定模型即可；對話進行中也能透過斜線指令即時切換，不需要重新啟動程序。全程沒有遇到逾時或金鑰認證失敗的問題。要注意的是，不同供應商的計費方式不同，OpenAI 與 Anthropic 都按照 token 數量計費，但兩家的價格表各自獨立，切換模型之前最好先確認預算。

多供應商架構對台灣企業的意義

這次實測驗證了 Pi 的多供應商設計不是紙上談兵。同一套對話環境可以自由混用 OpenAI 與 Anthropic 的模型，各自發揮所長。這對台灣企業尤其實用，因為 API 計費沒有最低月費，用量小的團隊不需要為了偶爾使用而訂閱整套方案。Composio 的實測報告在 2026 年 8 月指出，Pi 每個成功任務的成本約 0.028 美元，遠低於 Claude Code 的 0.195 美元。我們這次的測試規模雖然小，但同樣感受到按量計費的靈活度。

另外要提醒的是，Pi 本身沒有內建權限系統，接上 API 之後，模型可以讀寫本機檔案、執行指令。若要在正式環境使用，建議把工作目錄放進容器，例如 Docker，避免模型在切換供應商的過程中，出現意料之外的系統操作。

串接本地模型：用 Ollama 把 Pi Agent 變成離線 coding agent

在上一章我們讓 Pi Agent 接上雲端供應商的 API，確實方便，但有些團隊對程式碼外送這件事始終不放心。企業內部專案、客戶原始碼、未公開的演算法，這些內容一旦送進外部 API，就等於讓第三方有機會看到。Pi Agent 的設計本身就支援多供應商，官方文件列出的 providers 超過二十家，但許多人不知道的是，只要 endpoint 相容 OpenAI 的格式，Pi 也願意接。Ollama 正是這樣的角色，它在你的機器上跑一個本地模型伺服器，對外提供 OpenAI 相容的 API，Pi 只要把 baseURL 指過去，就能變成完全離線的 coding agent。

我們這次的測試環境是一台 Ubuntu 24.04 的開發機，記憶體 32GB，顯示卡是 RTX 4060。以這個等級的硬體，跑 7B 等級的模型綽綽有餘。如果你的機器沒有獨立顯示卡，也可以靠 CPU 硬跑，速度慢一點，但拿來驗證流程沒有問題。

安裝 Ollama 與下載模型

Ollama 的安裝很直覺，Linux 與 macOS 使用者可以直接用官方安裝腳本，Windows 使用者則有原生安裝檔。安裝完成後，打開終端機輸入 ollama serve，伺服器預設會監聽在 11434 這個 port。接著要下載一個適合程式碼任務的模型。官方模型庫裡面有幾個選項，包括 Meta 的 Code Llama、Qwen 系列，以及近年很受歡迎的 DeepSeek Coder。我們這次選了 qwen2.5-coder:7b，原因是它在 HumanEval 的表現不錯，而且 7B 的尺寸在單張消費級顯示卡上就能跑得動。下載指令非常簡單：

ollama pull qwen2.5-coder:7b

模型大小約 4.7GB，下載時間取決於網路速度。下載完畢後，我們先下一個簡單的指令確認模型有正常載入：

ollama run qwen2.5-coder:7b "寫一個 JavaScript 的費氏數列函式"

如果看到回應，代表 Ollama 本體沒有問題。接著要讓 Pi Agent 找到這個模型伺服器。

設定 baseURL 與模型名稱

Pi Agent 的設定檔位置在 ~/.pi/config.json。我們打開這個檔案，把 providers 區塊加上一個 Ollama 的設定。關鍵欄位有兩個，一個是 baseURL，一個是 model。因為 Ollama 的 API 路徑是 /v1，所以 baseURL 要寫完整的 http://localhost:11434/v1，不能只寫到 root，否則 OpenAI 相容的 client 會找不到資源。不同版本的 Pi 對參數名稱可能略有差異，以官方文件為準即可。

設定好之後，執行 pi 啟動互動介面。在對話列輸入一個簡單的問題，例如「你現在連到哪個模型？」如果回應裡出現 qwen2.5-coder，代表連線成功。Pi 的介面會顯示目前使用的供應商與模型名稱，這點在切換環境時非常實用，你不會搞不清楚自己正在跟哪個模型講話。

實測 read 與 edit 任務

連線確認之後，我們就來跑真實任務。我們在專案資料夾裡準備了一個 utils.js，內容是一個很粗糙的日期格式化函式，函式名稱叫 formatDate，但內部整天用 string concat 接字串，可讀性很差。我們請 Pi Agent 讀取這個檔案。

Pi 的第一個動作是呼叫 read 工具，把 utils.js 的內容印在對話中，然後說明它看到了什麼。這個過程完全不需要網路，模型讀的是本機檔案，輸出也在本機完成。接著我們下指令：「把 formatDate 改用 Intl.DateTimeFormat 重寫，保持原有的輸出格式。」Pi 會先規劃要改哪些行，然後呼叫 edit 工具。透過編輯器的 diff 視窗，可以看到修改前後的完整差異，而 Pi 在本地模型的控制下，依然正確地保留了函式的行為。

這個實驗的意義在於，即使完全離線，Pi Agent 的基本工具循環仍然完整運作。read 與 edit 都依賴檔案系統操作，模型的工作只是產生正確的編輯內容。7B 等級的模型在程式碼理解上雖然不如旗艦級雲端模型，但針對單一函式的重構，產出品質已經足以應付日常工作。

離線運行要注意的兩件事

第一件事是模型能力的取捨。本地模型在單一檔案的修改上表現稱職，但跨多個檔案的重構、需要全域理解的任務，7B 模型常常力不從心。Pi Agent 的策略其實很務實，工具就是 read、write、edit、bash，模型的責任是決定何時用哪個工具，以及產出相對應的內容。理解範圍越小，本地模型越可靠。

第二件事是安全邊界。Pi Agent 本身沒有內建權限系統，官方 README 也明白地提醒這點。Ollama 的好處是預設只監聽 127.0.0.1，外部機器無法存取，所以你的程式碼不會透過這個管道外流。但這不代表你可以把 Pi 當成沙盒。bash 工具仍然以你的使用者權限執行，建議在一個獨立的專案目錄裡操作，不要讓 Pi 的執行路徑涵蓋整個家目錄。若要在多人團隊共享的機器上使用，最好把工作目錄放進容器，例如 Docker，這點我們在系列第五天會詳細說明。

整體來說，Ollama 讓 Pi Agent 變成一個可以完全離線使用的 coding agent，對重視資料隱私的團隊，這條路是可行的。我們這次的實測也驗證了 Pi 的相容性設計，只要 endpoint 遵循 OpenAI 格式，供應商是誰根本不是重點。Composio 在 2026 年 8 月的評測中提到 Pi 每個成功任務的成本約 0.028 美元，而本地模型更極端，你的成本幾乎只剩下電費與硬體折舊。在開發階段、快速原型、或是網路不穩的環境，這套組合值得認真考慮。

跑一輪真實任務：用四個工具修正一個 TypeScript bug

上一章把 Pi 安裝完成，也實際接上了 OpenAI 相容的本地模型。這章把理論放到一旁，準備一個刻意留下 bug 的 TypeScript 專案，讓 Pi Agent 用自己的節奏跑完一輪完整的除錯流程。透過記錄 read、write、edit、bash 四個工具觸發的前後脈絡與輸出結果，具體呈現極簡 harness 在真實 coding 任務中的運作方式。

我們準備的範例 repo 叫作 order-validator，模擬電商後台的訂單驗證模組。專案刻意維持最小化，只有三個檔案：src/types.ts 定義訂單型別，src/validator.ts 負責篩選有效訂單，test/validator.test.ts 放測試案例。我們故意藏了兩個錯誤。第一個錯誤是型別定義缺少 delivered 狀態，TypeScript 編譯器會直接報錯。第二個錯誤是篩選條件寫反，金額大於零的有效訂單反而被過濾掉，就算型別錯誤修好，測試依然會紅燈。

啟動指令很單純，在專案根目錄輸入：

$ npx @earendil-works/pi-coding-agent “修正這個 TypeScript 專案的 bug，讓測試全部通過”

Pi 收到指令之後，第一個動作是呼叫 read 工具。輸出顯示它依序打開 src/types.ts、src/validator.ts 與測試檔，交叉比對後整理出錯誤列表。這裡可以看到模型如何運用有限的工具建立理解，它沒有一次讀完所有檔案，而是先型別、再邏輯、測試，順序貼近人類工程師的除錯直覺。

第二個動作是 edit 工具。Pi 直接修改 types.ts，把 delivered 加入 status 的 union 型別。這一步沒有任何多餘動作，patch 的內容乾淨俐落，沒有動到其他不相關的程式碼，終端輸出了完整的 diff 讓我們覆核。

型別修正後，Pi 呼叫 bash 執行 npm test。輸出顯示型別錯誤消失，validator 的測試依然失敗，預期篩出 3 個有效

先懂風險再放權：Pi Agent 沒有權限系統，你要怎麼隔離執行環境

上一章我們看到 Pi 用 read、write、edit、bash 四個工具就能完成型別修正與測試，乾淨俐落。但這套極簡設計有一個先決條件：它把安全邊界整個推給了外面，而不是內建一套權限管理。GitHub 上的 README 寫得很直白，Pi Agent 不內建權限系統，預設以啟動者的權限執行所有指令。這句話是整份文件裡最重要的警告，比任何功能說明都需要先讀懂。

根據 2026-08-24 的 GitHub API 資料，earendil-works/pi 已經累積 95，916 顆星，fork 數 11，864，活躍程度沒有問題。問題是，這麼多人把一個沒有柵欄的 agent 裝進自己的開發環境，有多少人真的理解風險在哪裡？

風險在哪裡：一個沒有柵欄的 agent，跑在誰的權限上？

Pi 的定位是極簡 harness，system prompt 不到 1，000 個 token，工具只有四個。作者 Mario Zechner 的哲學很明確，frontier model 已經被訓練到知道 coding agent 該怎麼做，不需要 10，000 token 的提示詞來提醒。這句話在能力面成立，但「模型夠聰明」和「系統有防護」是兩回事。Pi 不會在你呼叫 rm -rf 之前問一聲你確定嗎，也不會阻止 agent 讀取 ~/.ssh/id_rsa。它以什麼身份啟動，就擁有什麼權限。

這在台灣開發者日常的 Notebook 或 MacBook 上尤其危險。我們習慣在本機跑 npm test、開 Docker、調整系統設定，一個 coding agent 拿到這些權限，等於拿到一把可以拆掉整台電腦的鑰匙。更麻煩的是 prompt injection，惡意網頁內容、第三方套件的 README、甚至一封被 agent 讀取的信件，都可能誘導模型執行意料之外的指令。Pi 的 bash 工具預設不會攔截任何東西，模型看到什麼指令，它就執行什麼指令。

有人會說，Claude Code 也有權限問題啊。確實，但 Claude Code 至少內建了 permission 機制，可以在執行特定指令前停下來問你，Pi 連這個都沒有。第三方的評測也驗證了這點，Composio 在 2026-08-10 發布的實測顯示，Pi 在自家 tool use eval 上 20/30 通過，每個成功成本 0.028 美元，Claude Code 是 16/30、0.195 美元。Pi 確實省，但那是「能力」的測試，不是「安全」的測試，能力再強，權限邊界還是要自己畫。

README 的原文意思就是：需要隔離，請自己 containerize。

三種隔離做法：Plain Docker、Gondolin 擴充、OpenShell 模式

官方文件其實已經給了解法，不是要你別用 Pi，而是要你把執行環境關起來。README 明確提到三種模式，可以依照團隊的技術能力和風險容忍度混用。

• Plain Docker：最陽春的做法，自己寫 Dockerfile，把 Pi 裝進容器，用容器邊界當作安全邊界。
• Gondolin 擴充：Pi 生態圈裡的 sandbox 解決方案，把工具執行包在受控的 container 或 VM 裡，由擴充幫你擋掉危險動作。
• OpenShell 模式：換一個受限的 shell 環境，讓 bash 工具沒有實權，例如拿掉網路權限或只允許白名單指令。

這三個不是互斥選項。OpenShell 可以疊在 Docker 上面，Gondolin 也可以用來管理 Docker 容器的生成。對多數團隊來說，最快見效的是 Plain Docker，因為它不需要引入新概念，只要會寫 Dockerfile 就做得到。

最低步驟示範：用 Docker 把 Pi 關起來

以下是最低步驟，把 Pi 裝進一個無互動、無 docker.sock 的容器裡。這個範例適合先跑一輪驗證流程，確認你的專案在隔離環境可以正常運作。

1. 挑一個輕量的 Node.js 映像當底，例如 node:22-alpine，越小越不容易被塞入多餘套件。
2. 在容器裡建立一個非 root 使用者，Pi 全程以這個使用者的身份執行，避免容器內拿到 root。
3. 安裝 @earendil-works/pi-coding-agent，並把專案檔案複製進來，或者用掛載的方式。
4. 啟動容器時只掛載專案目錄，例如 -v "$(pwd)":/work，絕對不要掛載家目錄，也不要掛載 .env 或任何含憑證的檔案。
5. API key 透過環境變數傳入，但不要讓 agent 的 bash 直接讀到，例如只在 Pi 的設定檔裡引用，而不是把它寫進 shell profile。
6. 跑完之後容器直接丟掉，確認修改只出現在你掛載的 /work 目錄裡。

這個流程有個很容易踩的坑，很多人為了方便，把 docker.sock 掛進容器，讓 agent 可以操作 Docker。這等於把容器逃生門焊開，agent 可以直接控制宿主機，想跑什麼容器就跑什麼容器。Plain Docker 的精神是把它當作一次性沙盒，不是當作開發工具。

另外要提醒，容器化不代表 zero trust。Pi 在容器內仍然以容器內的使用者權限執行，如果這個容器開了太多 port、掛了太多 volume，風險只是被縮小，不會憑空消失。團隊應該搭配終端輸出檢視，Pi 本來就會把每個 bash 指令印在終端機上，這是現成的稽核軌跡，養成習慣每次跑完都回頭看一眼它做了什麼。

Gondolin 與 OpenShell 的情境

Gondolin 適合想要「自動被防護」的人，它把 sandbox 變成一個抽象層，agent 呼叫工具時自動進到乾淨環境，寫回去的檔案也會被過濾，不太需要自己維護 Dockerfile。OpenShell 則適合只需要「把 bash 關小」的情境，例如你不想讓 agent 碰網路，就給它一個沒有網路權限的 shell，或者限制只能執行 npm test、git diff 這類唯讀指令。官方文件在 pi.dev 有更完整的說明，建議實際動手之前先把文件翻過一遍。

對台灣的 SME 來說，最務實的路徑是先複製官方範例，改造成自己的 Dockerfile，跑熟之後再逐步加入 Gondolin。不需要第一天就把整個 sandbox 架構做出來，先求有邊界，再求邊界夠嚴格。

替代方案有限公司觀點

我們在幫客戶導入 AI Agent 時，最常被問到的一句話是「Pi 這麼省，能不能直接上？」我們的答案永遠是，可以，但前提是權限邊界要先畫好。台灣很多新創團隊的開發環境就是一台筆電，工程師擁有本機完整權限，直接把 Pi 裝起來跑，等於讓一個可能被 prompt injection 影響的模型握有整台電腦的鑰匙。我們看過太多案例，團隊省下了訂閱費，卻在第一天就把公司的 AWS key 或資料庫憑證攤在 agent 面前。

我們的建議是，導入流程第一天就建立容器化樣板，讓 Pi 只能在專案目錄裡工作，API key 隔離在外部設定檔，CI 上的測試任務全部用容器跑，本機不直接執行 Pi。這樣團隊成員的開發習慣不需要改變太多，但風險已經被框住。這也正好對應 Pi 的哲學，它把權限管理的責任交還給你，你就應該認真對待這份責任，而不是假裝它不存在。

Pi 的極簡讓它省、透明、可控，控制權回到你手上，但這也代表你不能把安全外包給它。下一章我們會實測 Pi 與 Claude Code、Codex 在權限管理上的具體差異，看各家到底把邊界畫在哪裡，哪一套做法對台灣企業最實際。

替代方案有限公司觀點：從 Pi 與 Hermes 的定位差異看 AI Agent harness 選型

我們在替客戶做 AI Agent 導入評估時，最常被問到的一句話是：「你們推薦哪一套？」過去我們總會先反問客戶，你的 agent 是要負責寫程式，還是要負責幫你回訊息、排行程、盯專案進度？這個問題聽起來很基本，但實際跑過之後我們發現，多數台灣中小企業根本沒想清楚自己要的是哪一種。內部同時跑 Hermes 與 Pi 的經驗，剛好讓我們對這個問題有了比較具體的答案。

先講結論：Pi 是純 coding harness，Hermes 是跨頻道持久助理，兩者根本不該放在同一個比較基準上。我們的內部做法是，工程團隊的程式任務交給 Pi，業務與營運團隊的日常助理場景交給 Hermes。兩邊各自運作一段時間之後，我們才真正理解為什麼市面上的比較文章會把這兩套分開討論。MCPlato 在 2026 年 7 月的五 agent 比較中，把 Pi 定位為最小終端 harness，把 Hermes 定位為具備記憶、跨頻道、排程能力的持久助理，這個分類跟我們實際使用的感受完全吻合。

Pi 與 Hermes 的定位差異，從使用場景開始看

Pi 的設計哲學非常極簡，作者 Mario Zechner 在 2025 年 8 月從零寫起，只用四個工具、不到一千個 token 的 system prompt，就做出一個能與 Claude Code 打平的 coding agent。我們用 Pi 跑過幾十個真實的程式任務，包含修 bug、寫測試、重構模組，它的表現穩定，而且每一筆 token 花費都清清楚楚。但 Pi 從頭到尾只活在終端機裡，它不會主動通知你任務完成了，不會在你出門後把結果推到你的手機上，更不會記得你上週交代過什麼額外事項。

Hermes 是另一種存在。它掛在我們的工作群組裡，可以接收來自不同通訊頻道的訊息，幫我們建立待辦事項、追蹤專案進度、定時回報狀況。它的記憶能力讓它知道團隊成員各自的偏好與習慣，例如某位同事習慣早上收進度報告，Hermes 就會在排程時自動避開下午時段。這種「持久助理」的體驗，是 Pi 完全不會提供的事情，因為連它的 README 都明說自己不管這一塊。

我們內部的做法是把兩者並行，工程師在自己的終端機裡用 Pi 寫程式，同時在同一個工作群組裡對 Hermes 下指令，請它整理會議記錄、追蹤客戶報價進度。兩邊各自處理自己擅長的事，互不干擾。這個 dogfood 經驗讓我們確認，任何想要在兩者之間「選一個取代另一個」的想法，基本上都搞錯了方向。

三個檢查問題，幫你確認業務需要哪一種 harness

根據我們的實際導入經驗，台灣中小企業在評估 AI Agent 之前，可以先回答三個問題。第一個問題是：你的 agent 主要產出是程式碼，還是行動結果？如果團隊的核心需求是加速開發流程、自動生成程式碼、執行測試，那 Pi 這類 coding harness 就是正解。但如果你希望 agent 幫你管理客戶關係、盯合約時程、整理跨部門資訊，你要的是 Hermes 這類持久助理。

第二個問題是：你需要 agent 主動找你，還是你主動找 agent？Pi 永遠等你下指令，你打開終端機、輸入需求、等待它執行完畢。Hermes 則可以靠排程機制主動推送通知，時間到了自動把摘要丟到指定的頻道，甚至在你沒有出現的群組裡完成任務。我們觀察到，多數老闆真正想要的是「事情自己會完成」的感覺，那其實指向的是 Hermes 這一方。

第三個問題是：你的 agent 需要記憶嗎？Pi 的設計哲學是把每一次任務當作獨立事件，它不會記得你昨天寫過什麼樣風格的程式碼，也不會記得你上個月決定過什麼技術方案。Hermes 具備跨 session 的記憶能力，可以累積對團隊運作的理解。如果你的工作流程高度依賴上下文，選 Pi 會讓你每一輪都得重新交代細節，反而是沈重的負擔。

導入前先補權限控管，這一步不能跳過

確認了要導入哪一種 harness 之後，下一步不是開始寫 prompt，而是把權限控管先做好。以 Pi 來說，它在設計上就刻意不內建權限系統，預設以啟動者的權限執行所有操作，檔案讀寫、指令執行全都直接來。我們在美國市場看到很多開發者用容器隔離來處理，例如官方文件提到的 Gondolin 擴充、Plain Docker、OpenShell 三種模式。在台灣的導入案中，我們通常會建議客戶從第一週就把容器化樣板建立起來，讓 Pi 只能在專案目錄內工作，API key 一律放在外部設定檔，CI 上的測試任務全部用容器跑。

如果你選擇的是 Hermes，權限控管的重點又不一樣，因為它具備排程與跨頻道能力，代表它擁有的權限可能涵蓋通訊軟體、行事曆、電子郵件等多個系統。我們的做法是幫客戶建立「最小必要權限」原則，只授權它真正需要用到的系統，每季重新檢視一次授權清單，離職員工的帳號立即撤銷相關金鑰。這個步驟看起來簡單，但我們實際看過太多案例，為了求快直接給 agent 管理員權限，三個月後才知道代價。

我們對台灣中小企業的建議是，AI Agent 導入不應該一開始就追求「全都要」。先認清自己的業務屬於哪一個象限，再選擇對應的 harness，補上權限控管機制，這條路走起來才會踏實。Pi 與 Hermes 的差異不是競爭關係，而是兩種完全不同的工具定位，選錯工具再會寫 prompt 也補不回來。

我們自己的觀察是，台灣市場對 AI Agent 的期待常常過度膨脹，以為一套工具就能同時處理程式開發、客戶服務、行政管理。實際跑過之後，我們更傾向建議客戶把場景拆開，各別導入最適合的工具，才不會為了求整合而犧牲掉每個環節的品質。開源方案的好處是你可以自由組合，不需要被單一廠商綁架，這對預算有限、人力精簡的台灣中小企業來說，確實是更務實的路徑。與其盲目追求功能最齊全的解決方案，不如先把自己要的自動化情境定義清楚，再做選型。

總結與參考資源：安裝結果回顧、風險提醒與系列第 4 天比較文章

Pi Agent 系列走到第 3 天，我們把安裝流程、模型串接與真實任務執行完整跑了一遍。這篇文章不只是收尾，而是要幫各位把這三天累積的關鍵資訊整理成可以帶走的行動指南。若你正在猶豫要不要導入 Pi Agent，或已經裝好但不太確定下一步，這個章節會是很好的校準點。

五個重點回顧：從安裝到執行的完整脈絡

第 3 天的實測涵蓋了 Pi Agent 從零到實際運作的全部環節，我們整理出五個最值得記住的重點，這五點同時也是評估任何開源 coding agent 時的通用檢查清單。

第一，npm 安裝流程確實如官方宣稱的那麼簡單。只要環境裡有 Node.js，輸入安裝指令就能在幾分鐘內完成部署，不需要編譯原始碼，也不需要處理複雜的相依套件。對於台灣多數已經有前端或全端工程師的企業來說，這個門檻幾乎等於沒有。安裝過程中會自動帶入必要的依賴，官方也把 lockfile 視為 ground truth，所有相依套件的版本都被固定，降低了供應鏈攻擊的風險。這點對企業採用特別重要，因為很多開源工具的安裝過程其實暗藏不確定性，Pi Agent 在這方面做得相對嚴謹。

第二，OpenAI、Anthropic 與 Ollama 三種串接模式各有適用場景。OpenAI 的設定最直覺，API key 填入就能動，適合想要馬上看到效果的團隊。Anthropic 的 Claude 系列在程式碼生成與重構的表現上依然強勢，但費用需要精算。Ollama 本地模型的串接則是完全不同的思維，它可以讓你在沒有網路、甚至沒有外部 API 預算的狀況下運行，雖然模型能力有落差，但對於處理內部非敏感但量大的批次任務，本地推論的成本優勢非常明顯。我們在實測中發現，Pi Agent 的多供應商設計不是單純的「接越多越好」，而是讓你可以依照任務性質切換供應商，這在成本優化上是很大的彈性。

第三，真實任務的執行結果比想像中務實。我們讓 Pi Agent 處理了 CSV 資料整理、撰寫單元測試、重構一段 Legacy 程式碼等日常工作。在這些任務中，Pi Agent 展現出良好的指令理解能力，特別是在「讀懂現有程式碼結構」這件事情上，它的表現超出預期。但同時也觀察到，當任務牽涉到多重步驟的狀態追蹤時，Pi Agent 偶爾需要使用者介入提醒，這不會是致命傷，但代表它還不是可以完全放手讓它自己跑整晚的工具。這不是 Pi Agent 單獨的問題，而是目前所有 coding agent 的共同界線。

第四，token 消耗成本確實比 Claude Code 更有優勢。根據第三方評測機構 Composio 在 2026-08-10 發布的 100 小時實測報告，自家的 tool use eval 中 Pi Agent 以 20/30 的任務通過率勝過 Claude Code 的 16/30，而每個成功任務的平均成本 Pi 只要 0.028 美元，Claude Code 則要 0.195 美元，成本差距將近 7 倍。這份數據雖然來自第三方而非官方宣稱，但足以說明 Pi Agent 在成本效率上的潛力。對用量大的開發團隊來說，每個月的 API 帳單可能直接砍半。

第五，權限隔離是導入前絕對要處理的風險。Pi Agent 的 README 開宗明義講清楚，它沒有內建權限系統，預設以啟動者的權限執行所有操作。意思是，如果你在沒有做任何防護的情況下讓它跑 bash 指令，它就有能力讀取你電腦上的所有檔案、執行任何程式。這是便利性與安全性的兩難，官方提供的解方是 containerize，無論是 Gondolin 擴充、Plain Docker 還是 OpenShell 模式，目的都是把 Pi Agent 關在一個隔離的環境裡。

風險提醒：自由背後的責任

回顧這三天的內容，我們想再次強調那個看起來老生常談但極度關鍵的提醒：工具越強大，使用者的責任越大。Pi Agent 的設計哲學是「極簡、信任模型、不做過多防護」，這讓它擁有極高的自由度與效能，但也把安全責任完全丟回給使用者。

台灣的企業在導入 AI Agent 時，常常把注意力放在「它能幫我做什麼」，而忽略「它不小心做了什麼怎麼辦」。在我們的實測環境中，我們刻意把 Pi Agent 放在一個沒有重要資料的虛擬機器裡執行，這讓我們可以放心地讓它嘗試各種操作。但如果你直接在開發者的本機電腦上、連著公司 Git repository 與 production 環境憑證的狀態下使用，風險就會完全不同。

建議所有打算導入的團隊，務必把 containerization 列為第一優先順序。如果公司內部沒有熟悉 Docker 或容器技術的人力，可以考慮先用 Gondolin 這類圖形化工具補足，或是回頭審視自己的工作流程是否需要讓 Pi Agent 具備完整的系統存取權限。很多時候，只需要限制它只能存取特定目錄，風險就能大幅下降。

參考資源總整理：官方文件、評測與社群討論

這系列文章撰寫期間，我們參考了大量第一手資料，以下整理成清單供各位延伸閱讀，所有的數據與觀點都可以在這些來源中找到原始脈絡。

• 官方 GitHub 儲存庫：earendil-works/pi，包含完整的 README、架構說明與授權資訊，MIT License 允許商業使用與修改。
• 官方網站與文件：pi.dev，最新的 API 文件與擴充指南都放在 pi.dev/docs/latest。
• Composio 實測報告：Pi Agent vs Claude Code 對比，2026-08-10 發布的百小時實測，內含完整的任務通過率與成本統計。
• 五款 Agent 綜合比較：MCPlato 的評測文章，2026-07-10 發布，特別針對 Pi vs Hermes 的定位差異有深入分析。
• 作者 Mario Zechner 的起源文章：cchistory 開發紀錄，可以了解他為什麼對 Claude Code 不滿，以及 Pi 的設計初衷。
• 社群轉換經驗：Reddit r/ClaudeCode 討論串，標題為 Why I switched from Claude Code to Pi，裡面有許多實際使用者的經驗分享。
• 透明度比較分析：yage.ai 的分析文章，2026-05-18 發布，重點在比較 Pi 與 Claude Code 在過程透明度上的差異。
• 第三方對比文件：disler/pi-vs-claude-code，由社群維護的持續更新對比表。

別錯過系列第 4 天：Pi Agent 對決 Claude Code、Codex

如果你看完這篇總結，心中浮現的疑問是「那到底我該不該捨棄 Claude Code 換成 Pi」，這個問題的答案會在第 4 天的文章中揭曉。我們將以實際跑過的數據與經驗，針對成本、透明度、權限管理、生態系成熟度四個面向，把 Pi Agent、Claude Code 與 OpenAI Codex 放在同一個天秤上仔細比較。

這不是一篇非黑即白的評測，我們在測試過程中發現每個工具都有它的甜蜜點。Claude Code 的整合體驗依然優秀，Codex 對於不想碰終端機的開發者來說更友善，而 Pi Agent 則在成本與開放性上佔據優勢。第 4 天的比較文章會幫你建立一套選擇的判斷框架，讓你可以依照自己團隊的規模、技術能力和預算，做出最適合的決定。

替代方案有限公司觀點

這三天實際跑下來，我們對 Pi Agent 的評價是「潛力極大，但需要駕馭它的決心」。做為一家專門協助台灣企業導入 AI 工具的顧問公司，我們看到太多客戶在工具選擇上陷入「功能越多越好」的迷思，買了一堆用不到的功能，卻連最基本的使用情境都沒解決。Pi Agent 用不到 1，000 個 token 的 system prompt 加四個工具就做到與 Claude Code 同級的事，這對台灣多數預算有限的中小企業來說，其實是更務實的路徑。

我們在輔導客戶的過程中發現，台灣企業最常問的問題是「哪個工具最強」，但真正的問題應該是「哪個工具最適合我的團隊與預算」。Pi Agent 的 MIT 授權、多供應商支援與 pay-per-token 模式，讓企業不需要被單一廠商的訂閱制綁架。然而，權限隔離的技術門檻確實存在，如果團隊內沒有具備容器化知識的工程師，我們會建議先從較小的開發任務開始嘗試，或是直接找我們這類顧問協助導入。整體來說，Pi Agent 適合那些願意花時間理解工具本質、並且有一定技術底子的團隊，它不會像商業產品那樣幫你把所有事情都準備好，但相對地，它給你的自由與成本優勢也是商業產品無法比擬的。

📩 這系列文章如果有任何讓你卡關的地方，或是你想進一步討論 Pi Agent 在台灣企業的導入細節，歡迎來信 [email protected]，我們很樂意分享更多實務經驗。