RealRelay.ai
程式碼代理

Pi 設定指南

在 models.json 中把 RealRelay.ai 設為 Pi 程式碼代理的自訂供應商:安裝、新增供應商、檢查連線,並選擇模型與思考層級。

建立 API 密鑰瀏覽模型目錄
協定
OpenAI Chat Completions
基礎位址
https://www.realrelay.ai/v1
官方文件
github.com
已對照工具官方文件核對
2026-10

概覽

Pi 是一個小巧、可擴充的終端機程式碼代理。它會讀取並編輯你專案中的檔案,也會執行指令。要把它接上 RealRelay.ai,請在它的 models.json 檔案中新增一個自訂供應商。該供應商使用 OpenAI Chat Completions API(/v1/chat/completions)。

  • 一組 API 金鑰,在主控台的 API 金鑰頁面取得。

  • 結尾要含 /v1 的基礎位址。Pi 會在後面加上 /chat/completions。

  • 一個模型 ID,完全依照 GET /v1/models 列出的寫法,例如 z-ai/glm-5.2。請挑選支援工具呼叫的模型。

Pi 在 earendil-works/pi 版本庫中開發。Oh My Pi 是另一個獨立專案,有自己的設定格式;請參閱 Oh My Pi 指南。

安裝

請使用 Pi 的安裝程式。它會視需要安裝 Node.js、固定 Pi 的相依套件版本,之後也能以 pi update 更新。

macOS · Linux
curl -fsSL https://pi.dev/install.sh | shpi --version
Windows PowerShell
powershell -c "irm https://pi.dev/install.ps1 | iex"pi --version
npm (Node.js 22.19+)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

npm 方式需要 Node.js 22.19 或更新版本,而且不會固定 Pi 的相依套件版本。

如果 pi --version 印出版本號,就代表安裝成功。如果找不到指令,請開啟新的終端機。

設定

  1. 1

    把金鑰放進環境變數

    設定檔以名稱參照金鑰,所以金鑰本身不會出現在檔案中。請把 sk-*** 換成你的金鑰。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    啟動 Pi 前,先執行 source ~/.zshrc,或開啟新的終端機。

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    啟動 Pi 前,請關閉並重新開啟終端機。

  2. 2

    在 models.json 中加入 RealRelay.ai

    建立 ~/.pi/agent/models.json;如果檔案已存在,請在 providers 物件中新增 realrelay 項目。

    ~/.pi/agent/models.json
    1{2  "$schema": "https://pi.dev/schemas/models.schema.json",3  "providers": {4    "realrelay": {5      "name": "RealRelay.ai",6      "baseUrl": "https://www.realrelay.ai/v1",7      "api": "openai-completions",8      "apiKey": "$REALRELAY_API_KEY",9      "compat": {10        "supportsDeveloperRole": false11      },12      "models": [13        {14          "id": "z-ai/glm-5.2",15          "contextWindow": 200000,16          "maxTokens": 3276817        }18      ]19    }20  }21}

    對於會先思考再回答的模型,請使用這種寫法,讓 Pi 的思考層級能傳到 RealRelay.ai。三項推理設定缺一不可;少了任何一項,你選的層級就不會送出。

    ~/.pi/agent/models.json
    1{2  "$schema": "https://pi.dev/schemas/models.schema.json",3  "providers": {4    "realrelay": {5      "name": "RealRelay.ai",6      "baseUrl": "https://www.realrelay.ai/v1",7      "api": "openai-completions",8      "apiKey": "$REALRELAY_API_KEY",9      "compat": {10        "supportsDeveloperRole": false,11        "supportsReasoningEffort": true12      },13      "models": [14        {15          "id": "z-ai/glm-5.2",16          "contextWindow": 200000,17          "maxTokens": 32768,18          "reasoning": true,19          "thinkingLevelMap": { "xhigh": "high", "max": "high" }20        }21      ]22    }23  }24}

  • "$REALRELAY_API_KEY" 告訴 Pi 在送出請求時從該變數讀取金鑰。啟動 Pi 的終端機中必須設定這個變數。

  • supportsDeveloperRole: false 會讓 Pi 以標準的 system 角色送出指示。RealRelay.ai 上有許多模型會拒絕較新的 developer 角色。

  • contextWindow 與 maxTokens 的預設值是 128,000 與 16,384。RealRelay.ai 不會回報模型的上限,所以請依模型目錄頁面設定。切勿設得比實際上限高;Pi 依 contextWindow 決定何時壓縮對話。

  • 在推理模型寫法中,supportsReasoningEffort 讓 Pi 能送出 reasoning_effort,而 thinkingLevelMap 會把 xhigh 與 max 層級當作 high 送出,讓這兩個層級成為有效值。

  • 若想把 Pi 的檔案放在 ~/.pi/agent 以外的地方,請設定 PI_CODING_AGENT_DIR。

驗證

  1. 1

    直接呼叫端點

    用你的金鑰執行這段指令。若收到含 choices 陣列的 JSON 回覆,就代表位址、金鑰與模型都沒問題。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
  2. 2

    確認 Pi 看得到模型

    --list-models 應會在 realrelay 底下列出你的模型。第二個指令會送出一個提示詞,印出回答後結束。

    Terminal
    pi --list-models realrelaypi --provider realrelay --model "z-ai/glm-5.2" --print "Reply with OK"
  3. 3

    在專案中啟動工作階段

    送出一則簡短訊息。收到回覆即確認整條路徑暢通,而該請求也會出現在主控台的用量日誌中。

    Terminal
    cd /path/to/your/projectpi --provider realrelay --model "z-ai/glm-5.2"

模型

在 Pi 中,/model 會開啟一份可搜尋的清單。在某個模型上按 Ctrl+S,可把它設為新工作階段的預設模型;按 Ctrl+P 則可循環切換模型。開啟 /model 時也會重新載入 models.json,所以修改後不必重新啟動就會生效。

Pi 只提供你在供應商底下列出的模型。每個模型新增一個項目,並各自設定上限:

~/.pi/agent/models.json → providers.realrelay.models
{ "id": "z-ai/glm-5.2", "contextWindow": 200000, "maxTokens": 32768 },{ "id": "deepseek/deepseek-v4-pro", "contextWindow": 200000, "maxTokens": 32768 }

對於推理模型,可在工作階段中以 /thinking 選擇層級,或在命令列使用 --thinking。Pi 只會提供該模型項目允許的層級。

Terminal
pi --provider realrelay --model "z-ai/glm-5.2" --thinking high

哪些模型適合代理使用,請見選擇模型。

疑難排解

  • 模型沒有出現在 /model 中。Pi 會隱藏供應商沒有可用金鑰的模型。請確認啟動 Pi 的終端機中已設定 REALRELAY_API_KEY,且 models.json 是有效的 JSON。

  • 401,或只在某個終端機中能用。那個終端機中沒有該變數。修改 profile 後請開啟新的終端機,或以 echo $REALRELAY_API_KEY 確認。

  • 404。baseUrl 缺少 /v1,或已經以 /chat/completions 結尾。

  • 400 並提到 developer 角色。請在 compat 底下加上 "supportsDeveloperRole": false。

  • 思考層級似乎沒有作用。三項推理設定中少了一項。請對照上方的推理模型寫法檢查你的項目。

  • 400 並提到 reasoning_effort。該模型不接受這個欄位。請對它改用基本寫法,不加推理設定。

  • 長時間工作階段中出現上下文錯誤。contextWindow 大於模型的實際上限。請調低到模型目錄頁面上的數值。