安裝 Pi 並設定 OmniProxy

Pi 是一款小型終端機助手——一個能直接在命令列與您對話、讀取檔案並完成任務的程式。它具有簡短的系統提示詞，預設僅包含少量工具。若您需要其他指令、工作流程或介面，可稍後透過擴充功能加入。擴充功能是為 Pi 增加能力的元件，您在建立後亦可與他人分享。

子代理（Subagents）將任務的一部分委派給其他助手，而計畫模式（Plan mode）則在執行開始前組織步驟。這兩項功能預設皆未包含，但您可以要求 Pi 建立它們，或安裝他人分享的套件。

開始之前

macOS 與 Linux 使用安裝指令碼——一個自動下載並安裝 Pi 的單一指令。在 Windows 上，請使用 Pi 首頁提供的 PowerShell 指令。PowerShell 是 Windows 內建的命令列環境。您也可以在 WSL（Windows 內的 Linux 環境）中安裝 Pi。

若您選擇使用 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。

首次安裝與啟動 Pi

在 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 或更高版本，您也可以使用快速入門中的替代指令：

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

安裝指令碼可能會在互動式終端機中暫停以詢問問題。請依照螢幕提示繼續。若您已有相容的 Node 版本，此 npm 指令將不會詢問問題。若要將 Pi 安裝至其他目錄，請加入 --prefix /your/directory。在 2026-10-09，此指令安裝了 Pi 1.1.0。

一般的 npm 安裝不需要相依套件生命週期指令碼，即套件在安裝期間自動執行的指令碼。安裝指令碼會鎖定相依套件；之後，請使用 pi update 更新 Pi。對於 npm 安裝，請使用您的套件管理員提供的更新方法。Nix 使用者應從 Pi 的 flake 安裝。flake 是一種描述軟體及其相依套件的 Nix 配置，而 pi update 無法更新 Nix 安裝。

安裝後，請先確認您的終端機可以找到 Pi：

pi --version

在 Windows 上，若您希望模型執行 Bash 指令，建議大多數本地使用者安裝 Git for Windows。Bash 是 Pi 用來執行部分指令的命令環境。Pi 會依序檢查 ~/.pi/agent/settings.json 中的 shellPath 設定、Program Files 下的 Git Bash，以及 PATH 上的 bash.exe。shellPath 指定了 Bash 的位置，而 PATH 是系統搜尋指令的目錄列表。

啟動 Pi 後，您可以輸入 !printf 'Bash is working\n' 進行檢查。若您的檔案與工具已在 WSL 中，請依照快速入門在該 Linux 環境中安裝 Pi。

接下來，進入您希望 Pi 檢查或處理的資料夾，然後啟動它：

cd /path/to/folder
pi

此資料夾成為 Pi 當前的運作範圍。Pi 使用它來發現檔案與配置，並將對話分組。

從 OmniProxy 取得連線數值

首先，從 OmniProxy 取得這三個數值：

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy the full ID from the current OmniProxy model list

baseUrl 是 Pi 發送請求的 API 端點，必須包含 /v1。apiKey 是用於存取 API 的金鑰。Model ID 是要呼叫的模型名稱，必須從當前 OmniProxy 模型列表中完整複製。

將 api 設為 openai-completions，如相容 API 範例所示。此欄位告知 Pi 在發送請求時使用哪種 API 格式。

複製完整的模型 ID，包含名稱中的任何斜線。在 2026-10-09，供應商文件中的兩個參考 ID 為 gemini-3.8-flash 與 grok-4.7。請勿複製列表中不存在的名稱。

輸入工具設定

Pi 的使用者層級自訂模型配置儲存在 models.json。此檔案位於代理目錄中，預設為 ~/.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 模型列表中的完整模型 ID 相符。input 表示該模型在此處配置為文字輸入。

apiKey 可以輸入為字面數值，或輸入為 $NAME 或 ${NAME}，讓 Pi 從環境變數讀取。以 ! 開頭的數值會被視為指令，並在每次請求時執行。請勿將真實金鑰提交至儲存庫。若 Gateway 不驗證金鑰，您可以使用僅在本地機器上使用的佔位字串。在 2026-10-09，Pi 成功讀取了此配置的檔案。

開啟 /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 "Read the first line of the file you specify. Do not modify the file."

在此，--tools read 僅啟用讀取工具，且任務亦明確指示 Pi 不要修改檔案。在 2026-10-09，Pi 1.1.0 成功讀取了檔案內容。首次回應耗時約兩分鐘。

您也可以使用互動模式：進入目錄，執行 pi，然後使用 /model 選擇模型。快速入門中的一個範例任務要求 Pi 解釋儲存庫如何組織以及如何執行其檢查。觀察它是否讀取檔案並提供解釋，然後在 OmniProxy 的請求記錄中確認來源與模型 ID。

啟動

Pi 啟動

先 cd 到資料夾
pi --version 產生輸出
模型名稱出現在介面底部

任務

它讀取了目錄

詢問儲存庫如何組織
檢視它列出的檔案
不要僅依賴成功的配置儲存

記錄

在 Gateway 中可見

來源為 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 網站與快速入門。模型檔案請參閱選擇模型與配置。Windows 命令環境請參閱在 Windows 上執行 Pi。範例中使用的模型 ID，請參閱 Gemini 模型列表與 xAI 模型頁面。

將所有佔位符替換為您自己的 OmniProxy 配置值。切勿發布真實金鑰。

保存的結果或 HTTP 200 單獨存在並不證明完整的 Agent 相容性。請在 OmniProxy 的呼叫記錄中檢查來源與模型。

官方來源 · Pi ↗