Pi 安裝與 OmniProxy 設定

Pi 是一款小巧的終端機助理，也就是直接在命令列中與你對話、讀取檔案並完成工作的程式。它的系統提示較短，預設工具也不多；需要其他命令、流程或介面時，可以再透過擴充功能加入。擴充功能可以理解為替 Pi 增加能力的元件，完成後也能分享給其他人。

子代理是把部分工作交給另一個助理處理，而計畫模式則是先整理步驟，再開始執行。這兩項並非預設功能，可以請 Pi 自行建立，或安裝其他人分享的套件。

安裝前準備

macOS 和 Linux 使用安裝指令碼，也就是一行會自動完成下載與安裝的命令。Windows 使用 Pi 首頁提供的 PowerShell 命令；PowerShell 是 Windows 內建的命令列環境。也可以將 Pi 安裝到 WSL，也就是 Windows 裡的 Linux 環境。

如果選擇透過 npm 安裝，需要先準備 Node.js 22.19 或更新版本。npm 是搭配 Node.js 使用的套件管理工具，可以從命令列安裝 Pi。

macOS Linux

install.sh

curl 官方指令碼
相依套件由安裝程式固定
更新使用 pi update

Windows

install.ps1

官方網站的 PowerShell 命令
Git for Windows 提供 Bash
也可以進入 WSL

已有 Node

npm

需要 Node 22.19+
套件名稱是 pi-coding-agent
加入 --ignore-scripts

安裝指令碼會鎖定相依套件版本。透過 npm 安裝不會鎖定間接相依套件，並且需要加上 --ignore-scripts。

安裝並首次啟動

在 macOS 或 Linux 開啟終端機後，執行：

curl -fsSL https://pi.dev/install.sh | sh

在 Windows 開啟 PowerShell，然後執行：

powershell -c "irm https://pi.dev/install.ps1 | iex"

如果已安裝 Node.js 22.19 或更新版本，也可以使用 Quickstart 中的替代命令：

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

安裝指令碼在互動式終端機中可能會暫停並提出問題，需要依照畫面指示繼續操作。如果已有符合要求的 Node，這行 npm 命令不會進入提問流程。若要安裝到其他目錄，請加上 --prefix /你的目錄。2026-10-09 以此方式安裝的版本是 Pi 1.1.0。

一般的 npm 安裝不需要執行相依套件的生命週期指令碼，也就是套件在安裝過程中自動執行的指令碼。安裝指令碼會鎖定相依套件版本，之後使用 pi update 更新。透過 npm 安裝時，更新方式以所用的套件管理工具為準。Nix 使用者應從 Pi 的 flake 安裝；flake 是 Nix 用來描述軟體和相依套件的設定，pi update 無法更新透過 Nix 安裝的版本。

安裝完成後，先確認終端機能找到 Pi：

pi --version

在 Windows 上，如果要讓模型執行 Bash 命令，建議大多數直接使用 Windows 的使用者安裝 Git for Windows。Bash 是 Pi 用來執行部分命令的命令環境。Pi 會依序尋找 ~/.pi/agent/settings.json 中的 shellPath、Program Files 裡的 Git Bash，以及 PATH 中的 bash.exe。shellPath 用來指定 Bash 的位置，而 PATH 是系統尋找命令時使用的目錄清單。

啟動後，可以輸入 !printf 'Bash is working\n' 進行檢查。如果檔案和工具都已位於 WSL 中，請在該 Linux 環境內依照 Quickstart 安裝。

接著進入準備讓 Pi 查看或處理的資料夾，再啟動 Pi：

cd /path/to/folder
pi

這個資料夾會成為 Pi 目前的工作範圍，用於探索檔案與設定，也會用來將工作階段分組。

從 OmniProxy 取得連線參數

先從 OmniProxy 準備以下三項資料：

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: 從 OmniProxy 目前的模型清單完整複製

baseUrl 是 Pi 傳送請求的 API 位址，必須寫到 /v1。apiKey 是存取 API 時使用的金鑰。Model ID 是要呼叫的模型名稱，必須從 OmniProxy 目前的模型清單完整複製。

api 請依照相容 API 範例填入 openai-completions。這個欄位會告訴 Pi 應使用哪一種 API 格式傳送請求。

模型 ID 必須完整複製，名稱中的斜線也要保留。2026-10-09 供應商文件中的兩個對照 ID 是 gemini-3.8-flash 和 grok-4.7。請勿照抄清單中不存在的名稱。

填寫工具設定

Pi 的使用者層級自訂模型設定會寫入 models.json。這個檔案位於 agent 目錄，預設目錄是 ~/.pi/agent，因此完整路徑是 ~/.pi/agent/models.json。如果設定了環境變數 PI_CODING_AGENT_DIR，Pi 會改用該變數指定的目錄；環境變數可以理解為系統提供給程式讀取的一項設定值。

依照相容 API 範例填寫：

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers 用來列出接入的服務，models 則用來列出可選擇的模型。每個模型的 id 都必須對應 OmniProxy 目前模型清單中的完整 Model ID，input 則表示此處設定的是文字輸入。

apiKey 可以直接填入字面值，也可以寫成 $NAME 或 ${NAME}，讓 Pi 從環境變數讀取。以 ! 開頭的值會被視為命令，並在每次提出請求時執行。請勿將真實金鑰提交至程式碼儲存庫。如果閘道不驗證金鑰，可以填入一串僅在本機使用的預留字元。2026-10-09 已透過此方式成功讀取檔案。

開啟 /model 會重新載入這個檔案。/model 是 Pi 中用來查看和選擇模型的入口。在 Pi 能夠解析憑證之前，自訂模型不會出現在 /model 中。選取模型後按下 Ctrl+S，可以將它設為新工作階段的預設模型。

檔案

models.json

預設目錄 ~/.pi/agent
在 providers 中新增一項
api 使用 completions

位址

baseUrl

填寫至 /v1
apiKey 可填寫變數
模型 id 必須精確

選用

/model

開啟後會重新載入檔案
選取剛才的模型
Ctrl+S 可儲存為預設值

修改檔案後，在 Pi 中開啟 /model，確認模型已經出現。

驗證實際工作

完成設定後，可以在包含檔案的目錄中進行一次非互動式檢查。非互動式是指不進入持續對話，Pi 完成這一項工作後就會結束。請將 --model 後面的內容換成 OmniProxy 目前清單中的完整 ID：

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "讀出你指定檔案的第一行，不要修改檔案。"

這裡的 --tools read 只開放讀取工具，工作內容也明確要求不要修改檔案。2026-10-09 使用 Pi 1.1.0 成功讀取了檔案內容。第一次回覆約需兩分鐘。

也可以採用互動方式：進入目錄後執行 pi，再使用 /model 選取模型。Quickstart 中的一個範例工作，是請 Pi 說明這個程式碼儲存庫的組織方式，以及如何執行檢查。觀察它是否讀取了檔案並提供說明，然後在 OmniProxy 的呼叫記錄中確認來源和模型 ID。

啟動

pi 能開啟

先 cd 到資料夾
pi --version 有輸出
介面底部有模型名稱

任務

它讀取了目錄

詢問儲存庫的組織方式
查看它列出的檔案
不要只確認設定已儲存

記錄

閘道看得到

來源是 Pi
模型 ID 一致
金鑰保留在本機

介面底部顯示模型名稱後，仍需完成一次實際工作。

常見錯誤

找不到 pi：重新開啟終端機後，再試一次 pi --version。透過 npm 安裝時，請確認全域 bin 位於 PATH 中。
/model 中沒有自訂模型：確認 models.json 位於 ~/.pi/agent/、apiKey 能夠被解析，然後重新開啟 /model。
Windows 顯示找不到 Bash：安裝 Git for Windows，或在 ~/.pi/agent/settings.json 中設定 shellPath。JSON 中的反斜線必須寫成兩個。
請求遭到拒絕：確認 api 是否為 openai-completions，以及 baseUrl 是否以 /v1 結尾。不要只因服務自稱相容，就啟用額外的相容選項。
模型 ID 無效：從 OmniProxy 目前的清單重新複製。

官方參考資料

安裝命令請參閱 Pi 官網和 Quickstart。模型檔案請參閱 Choose a Model 和 Configuration。Windows 的命令環境請參閱 Run Pi on Windows。範例所用的模型 ID 請參閱 Gemini 模型清單和 xAI 模型頁面。

用你自己的 OmniProxy 設定取代每個佔位符。不要發布真實金鑰。

儲存成功或 HTTP 200 不單獨代表完整 Agent 相容性。請在 OmniProxy 呼叫記錄中確認來源和模型。

官方來源 · Pi ↗