Pi Coding Agent 安裝教學 2026：npm 安裝、API Key 設定與 Claude/GPT/Gemini TypeScript 實戰

為什麼「再下一款 IDE Agent」解決不了多模型

2026 年多數團隊的痛苦不是「沒有 Agent」，而是金鑰、模型與執行環境綁死在同一家產品裡。Claude Code 吃 Anthropic 訂閱，Codex CLI 吃 ChatGPT，Cursor 把模型選擇藏進編輯器帳號。你想下午用 Claude 改架構、晚上用 Gemini 掃測試、週末用 GPT 寫提交說明，結果每次都要換視窗、換權限、換上下文。

Pi 把這個假設拆開了。官方定位是最小 harness：預設只給模型 read、write、edit、bash 四件工具；sub-agent、plan mode、權限門、MCP 這些「別人內建的功能」，改成擴充功能、Skills 或 Pi Package，由你依工作流程加。模型是可替換後端，不是產品本體。

非對稱結論是：分水嶺不在 Claude、GPT、Gemini 誰更強，而在 harness 能不能把模型當成可替換的執行後端，並嵌進你自己的 TypeScript 專案。 該升級的是入口（CLI / SDK / RPC）、憑證分層與常開執行節點，不是再下一款更厚的 IDE。站內對「harness 是什麼」的概念拆解，見 Omnigent Agent Harness 完全搞懂；本篇只解決「怎麼把 Pi 裝上、把三家金鑰接上、寫進倉庫」。

Pi 是什麼：最小 harness 的四條入口

先歸類，再談指令。Pi 不是又一個聊天視窗，而是同一套 Agent 迴圈的四種打開方式。分類維度仍是入口、執行、上下文與適合人群。

官網把哲學寫得很直：改 harness，而不是改你的工作流程。擴充是 TypeScript 模組，能註冊工具、斜線指令、快速鍵與 TUI 元件；Skills 按需載入，避免一上來撐爆 prompt cache。套件可以 pi install npm:@scope/pkg 或 pi install git:host/user/repo。完整能力清單以 pi.dev 與 npm 套件說明為準，版本號會變，指令形態比「某月某日的模型名稱」更穩。

Pi vs 封閉 Agent：入口、執行、上下文

選型時若先問「Claude 強還是 GPT 強」，會錯過真正差異。把 Pi、官方 CLI 和 IDE Agent 放在同一張表上，依入口、執行、上下文與適合人群對齊，結論幾乎立刻翻轉。排行榜體裁見 2026 年最佳 AI Coding Agent 排名；本篇不重做名次，只回答「要不要把金鑰從產品裡拆出來」。

Claude Code 與 Codex 在遠端 Mac 上的取捨，見 Claude Code vs Codex：遠端 Mac 開發環境怎麼選。那兩篇回答的是「官方 CLI 怎麼挑」；本篇回答的是「當你已經確定要多模型、還要把迴圈嵌進 TypeScript 時，harness 怎麼裝」。

npm 安裝與 API Key 設定

全域 CLI：先能對話，再談嵌入

官方建議帶 --ignore-scripts 的全域安裝。Pi 正常使用不依賴套件的 install 生命週期腳本；跳過腳本能減少供應鏈意外。Node 版本以你本機 LTS 為準，倉庫宣告的引擎版本號會隨套件更新，不要把某篇部落格裡的次要版本寫成合約。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 或：pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
# 或：bun add -g --ignore-scripts @earendil-works/pi-coding-agent
# 安裝程式備選：curl -fsSL https://pi.dev/install.sh | sh
pi --version

裝完先做兩件事：確認 pi 在 PATH 裡；確認你準備用的供應商至少有一把金鑰或一次 /login。沒有憑證時，TUI 能打開，但模型目錄裡可跑的項目是空的。

金鑰怎麼分層：環境變數、auth.json、一次性覆寫

官方憑證解析順序是：命令列 --api-key → ~/.pi/agent/auth.json → 行程環境變數 → models.json 裡的自訂供應商金鑰。互動裡 /login 會把 OAuth 或 API Key 寫入 auth.json（檔案權限 0600）。auth.json 優先於環境變數，適合「這台機器長期用這把金鑰」；環境變數適合 CI 與一次性實驗。SDK 裡的 setRuntimeApiKey 是行程內覆寫，不寫入磁碟，適合測試與多租戶宿主。

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...   # auth.json 裡對應鍵名是 google

pi
# 互動：/login 選供應商；/model 或 Ctrl+L 切換；Ctrl+S 存為啟動預設

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

key 欄位還支援 $ENV_VAR 插值，以及 !op read 'op://…' 這類指令取值（行程內快取）。遠端或無頭機器上，OpenRouter 一類瀏覽器回呼走不通時，官方要求把最終重新導向 URL 或授權碼貼回登入提示——SSH 上的雲端 Mac 特別常見。供應商對照表以 providers.md 為準。

接入 Claude、GPT、Gemini

Pi 為每個內建供應商維護一份「能跑工具」的模型目錄；已設定的目錄會自動重新整理，也可 pi update --models 強制拉一次。驗證可以是訂閱（Claude Pro/Max、ChatGPT Plus/Pro Codex、GitHub Copilot）或 API Key。切換用 /model、Ctrl+L，常用模型用 Ctrl+P 循環；/scoped-models 決定循環名單。

pi --list-models claude
pi --list-models gpt
pi --list-models gemini

pi --provider anthropic --thinking high "把 src/ 裡的迴圈改成可測函式"
pi --model openai/gpt-4o -p "用三句話總結本倉庫的入口模組"
pi --provider google -p "唯讀：列出未涵蓋的測試檔案"

# 會話內切換，不必重裝
# /model   或 Ctrl+L
# Ctrl+P   在 scoped 名單裡循環

模型 ID 會隨目錄重新整理而變。官方範例裡出現過 claude-opus-4-5、claude-sonnet-4-5、gpt-4o、gpt-5.1 這類寫法；落地時以 pi --list-models 和 SDK 的 getAvailable() 為準，不要把部落格裡的快照 ID 寫進正式環境腳本。自訂閘道（Ollama、vLLM、公司代理）走 ~/.pi/agent/models.json，前提是對方講 OpenAI / Anthropic / Google 其中一種 API；OAuth 或私有協定用擴充功能，不要硬改 CLI。

若你真正要的是「自己寫 HTTP、自己解析 JSON」，那是 Function Calling 層，不是 harness 層。對照 Function Calling 與 JSON API 和 GPT-5.6 API 教學：那兩篇教你直接打供應商；本篇教你讓 Pi 替你管工具迴圈，只換後端。

TypeScript 專案實戰

CLI 解決「人在終端機裡指揮」；SDK 解決「倉庫裡的腳本也能指揮」。SDK 打在同一個 npm 套件裡，不必另裝。最小閉環是：本機相依套件 → 三把金鑰只進環境 → ModelRuntime 選模型 → createAgentSession 發一條唯讀任務 → dispose()。

npm init -y
npm install @earendil-works/pi-coding-agent
# package.json 裡加上 "type": "module"

import {
  createAgentSession,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const runtime = await ModelRuntime.create();

if (process.env.ANTHROPIC_API_KEY) {
  await runtime.setRuntimeApiKey("anthropic", process.env.ANTHROPIC_API_KEY);
}
if (process.env.OPENAI_API_KEY) {
  await runtime.setRuntimeApiKey("openai", process.env.OPENAI_API_KEY);
}
if (process.env.GEMINI_API_KEY) {
  await runtime.setRuntimeApiKey("google", process.env.GEMINI_API_KEY);
}

const preferred =
  runtime.getModel("anthropic", "claude-opus-4-5") ??
  runtime.getModel("openai", "gpt-4o") ??
  (await runtime.getAvailable())[0];

if (!preferred) {
  throw new Error("沒有可用模型：先 export 三家金鑰之一，或跑 pi --list-models");
}

const { session } = await createAgentSession({
  model: preferred,
  thinkingLevel: "low",
  tools: ["read", "bash"],
  sessionManager: SessionManager.inMemory(),
  modelRuntime: runtime,
});

try {
  session.subscribe((event) => {
    if (
      event.type === "message_update" &&
      event.assistantMessageEvent.type === "text_delta"
    ) {
      process.stdout.write(event.assistantMessageEvent.delta);
    }
  });
  await session.prompt(
    "唯讀：列出目前目錄的 TypeScript 入口檔案，並指出最可能缺少測試的一處。不要改檔案。"
  );
} finally {
  session.dispose();
}

這段程式碼刻意把工具收成 read + bash，會話用記憶體、不寫入磁碟。CI 裡審查腳本不該預設擁有 write/edit。要持久會話，改用 SessionManager.create(process.cwd())；要和 CLI 共用同一把長期金鑰，不要呼叫 setRuntimeApiKey，讓 runtime 去讀 ~/.pi/agent/auth.json。自訂 auth 路徑時，把 authPath / modelsPath 指到應用程式自己的目錄，避免多服務搶同一份家目錄檔案。SDK 事件、轉向（steer）與後續（followUp）的語意見 sdk.md。

AGENTS.md：把倉庫規矩寫給所有模型

Pi 啟動時會拼接 ~/.pi/agent/AGENTS.md、上層目錄和目前目錄的 AGENTS.md（或 CLAUDE.md）。某層若存在 AGENTS.override.md，該層只載入覆寫檔案。這就是「換模型不換規矩」的落點：Claude、GPT、Gemini 讀同一份入口、測試指令與紅線。需要替換系統提示時用 .pi/SYSTEM.md，追加用 APPEND_SYSTEM.md。

# 本倉庫給 Pi 的規矩
- 套件管理：npm。不要擅自改成 pnpm。
- 檢查：npm test && npm run lint
- 紅線：不要提交 .env、auth.json、*.pem
- 預設唯讀；只有使用者明確說「可以改檔案」才用 write/edit

無頭 CI 不會跳出專案信任框。沒有已儲存的 trust 決策時，非互動模式跟全域 defaultProjectTrust：ask（預設）和 never 會忽略專案層 .pi/ 資源，always 才信任。單次覆寫用 --approve / --no-approve。把 Pi 塞進自建 runner 時，先把信任策略寫進機器映像檔，再談模型。GitHub Actions 與雲端 Mac runner 的分層，見 GitHub Actions macOS 自建 Runner 與雲端 Mac。

場景怎麼選

真正該問的不是「要不要裝 Pi」，而是第一約束：要互動改程式碼、要把 Agent 寫成腳本，還是只要一家官方 CLI 的開箱即用體驗。

「Cloud Mac 為什麼是 Agent 執行層」的產品判斷，見 Cloud Mac 為什麼成為 2026 iOS 開發標配。本篇補的是節點上的那一層：npm、金鑰、模型切換與 TypeScript 腳本。

推薦組合

允許工具疊加。Pi 解決的是「可替換模型的 coding harness」；它不負責給你一台不合蓋的 Mac，也不負責替你付三家帳單。

• 個人日常組合：全域 pi + ANTHROPIC_API_KEY 作預設 + 另外兩把金鑰備用 + 倉庫 AGENTS.md。互動裡 Ctrl+L 換模型，規矩不換。
• TypeScript 倉庫組合：全域 CLI 給人用，devDependencies 裡再裝一份 SDK 給腳本用。審查走唯讀工具；改檔案另開一條人工確認的指令。
• CI 組合：pi -p 或 SDK 腳本 + GitHub Actions Secrets + 自建 macOS runner。信任策略用 --approve 寫死，不要在日誌裡印出金鑰。
• 多供應商閘道組合：OpenRouter / Cloudflare AI Gateway 一把金鑰打多家模型；仍用 Pi 的 /model 切換。適合不想在每台機器上散落三把原廠金鑰的團隊。
• 最小驗證組合：只裝 CLI，只 export 一把金鑰，跑 pi -p "列出目前目錄的 ts 檔案"。四拍跑通（安裝→憑證→一次任務→可重現）再加第二家模型與 SDK。

多智能體課堂或 IM 分身不是 Pi 的主場：那些要編排與閘道，見 OpenMAIC 與多智能體協作時代。Pi 更適合「同一套讀改跑迴圈，換後端繼續幹」。

常見誤區

• 把 Pi 理解成 Claude Code 的免費複製。它故意不做 sub-agent 和 plan mode。你要的功能用擴充功能或 Package 加，不要抱怨「核心太瘦」然後回去等下一款 IDE。
• 三把金鑰塞進同一份會進 git 的 dotenv。開發機用 shell profile 或 1Password；CI 用 Secrets；共用機器用 0600 的 auth.json。SDK runtime key 不寫入磁碟，不能代替機器憑證。
• 把部落格裡的模型 ID 寫死進正式環境。目錄會重新整理。腳本應 getAvailable() 或 --list-models，再用穩定的 provider 前綴做兜底。
• 在 CI 裡給 Agent 預設 write/edit。審查與巡檢用唯讀白名單；改檔案另開人工門閂。
• 無頭模式還指望跳出 trust 對話框。先設 defaultProjectTrust 或傳 --approve，否則專案層 Skills 根本不會載入。
• 在會休眠的筆電上跑長時 SDK 任務。會話樹能還原，但 bash 中途被休眠打斷的副作用不會自動回復。長時任務放到常開節點。

落地步驟

1. 寫清不可妥協項：只要互動、只要腳本，還是兩條都要；第一週是否必須同時接三家模型；CI 是否允許寫磁碟。
2. 安裝 CLI 並做一次空跑：npm install -g --ignore-scripts @earendil-works/pi-coding-agent，pi --version，確認 PATH。
3. 只接一把金鑰：export 或 /login，pi -p "列出目前目錄"。驗收標準是「可重現」，不是「回覆更長」。
4. 再接第二、第三家：補 OPENAI_API_KEY / GEMINI_API_KEY，用 /model 或 --provider 各跑同一條提示，確認規矩來自 AGENTS.md 而不是模型脾氣。
5. 把 SDK 寫進倉庫：專案相依套件 + 一條唯讀 scripts/pi-review.ts。工具白名單寫死在程式碼裡。
6. 選定執行環境：本機試用可以；CI 與長時任務放到常開雲端 Mac 或自建 runner，日誌去識別化，金鑰不進成品。
7. 再加擴充與觀測：需要 plan mode / MCP / 權限門時再裝 Package。先能量化用量、失敗回退與人工接管，再擴能力。

FAQ

Pi Coding Agent 和 Claude Code 是什麼關係？

Claude Code 是 Anthropic 的官方 coding 工作流程，模型與入口綁在一起。Pi 是第三方最小 harness，可以用 Anthropic 金鑰或 Claude 訂閱，也可以同時接 OpenAI 與 Gemini。它不取代「官方深度整合」，它取代的是「換模型就要換整套工具」。

必須同時設定 Claude、GPT、Gemini 嗎？

不必。一把金鑰就能跑通安裝驗收。第二把金鑰的意義是：同一套 AGENTS.md 和工具白名單，依任務換後端。沒有第二家帳單時，先不要為「多模型」增加維運面。

全域 npm 安裝和專案裡的 SDK 會衝突嗎？

不會搶同一條指令，但版本可能漂移。約定：人用全域 CLI，腳本鎖專案 package.json 的版本。兩者讀同一份 ~/.pi/agent 時，注意不要在腳本裡用 runtime key 蓋掉機器上的長期金鑰。

Gemini 的環境變數為什麼不是 GOOGLE_API_KEY？

官方表把 Gemini API Key 寫成 GEMINI_API_KEY，auth.json 鍵名卻是 google。Vertex 走 ADC 與專案／地區變數，和 AI Studio 的 Gemini 金鑰不是同一條路。以 providers.md 為準，不要憑常識猜鍵名。

Windows / 無頭雲端 Mac 能裝嗎？

能。npm 全域套件跨平台；官網另有 install.sh 與 PowerShell 安裝程式。無頭機器用 pi -p、RPC 或 SDK，不要依賴 TUI。OpenRouter 一類 OAuth 在 SSH 上要貼上回呼。雲端 Mac 上更該先固化 Node 版本、PATH 與 auth.json 權限。

為什麼還要雲端 Mac？本機裝 npm 不夠嗎？

本機夠用來學指令。不夠用來跑夜間審查、合蓋後的長時修復，以及和 Xcode / 簽名同一套環境的 CI。Pi 把模型解耦了，但 bash 與檔案工具仍然綁在那台正在跑行程的機器上。

總結

Pi Coding Agent 的安裝教學，表面上是 npm、環境變數與三家模型 ID；真正要落地的是一條分層：harness 與模型分開，金鑰與倉庫分開，互動入口與腳本入口分開。2026 年 9 月能站得住的用法，是全域 CLI 給人，SDK 給倉庫，AGENTS.md 給所有後端，常開節點給長時任務。

非對稱結論仍然成立：分水嶺不在 Claude、GPT、Gemini 誰更強，而在你能不能把模型當成可替換後端。先跑通一把金鑰的一次 pi -p，再加第二家模型與 TypeScript 腳本；需要執行面時，再把行程從會休眠的筆電挪到雲端 Mac。該升級的是入口、憑證與節點，不是再下一款 IDE Agent。