Pi 設定

Pi 是一款終端機程式碼代理，以 @earendil-works/pi-coding-agent 之名發佈。它內建多種 API 協定的傳輸層，因此無論是 OpenAI 相容或 Anthropic 相容端點，都能用來連接 CodeByAI——你唯一需要手寫的只有一個 JSON 檔案。

1. 安裝 Pi

macOS 或 Linux：

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

使用 npm（Node.js 22.19 或更新版本）：

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

在 Windows 上請使用 powershell -c "irm https://pi.dev/install.ps1 | iex"。

2. 建立模型設定

Pi 的設定放在 ~/.pi/agent/，並從 models.json 讀取自訂端點：

• macOS / Linux：~/.pi/agent/models.json
• Windows：C:\Users\YourUserName\.pi\agent\models.json

該資料夾可能還不存在；請先建立它，再建立 models.json：

Copy
1
{
2
  "$schema": "https://pi.dev/schemas/models.schema.json",
3
  "providers": {
4
    "codebyai": {
5
      "name": "CodeByAI",
6
      "baseUrl": "https://www.codebyai.net/api/agent",
7
      "api": "openai-completions",
8
      "apiKey": "$CODEBYAI_API_KEY",
9
      "models": [
10
        {
11
          "id": "gpt-5.6-terra",
12
          "name": "GPT-5.6 Terra",
13
          "contextWindow": 200000,
14
          "maxTokens": 32768
15
        }
16
      ]
17
    },
18
    "codebyai-claude": {
19
      "name": "CodeByAI (Claude)",
20
      "baseUrl": "https://www.codebyai.net/api/agent",
21
      "api": "anthropic-messages",
22
      "apiKey": "$CODEBYAI_API_KEY",
23
      "models": [
24
        {
25
          "id": "claude-sonnet-5",
26
          "name": "Claude Sonnet 5",
27
          "contextWindow": 200000,
28
          "maxTokens": 32768
29
        }
30
      ]
31
    }
32
  }
33
}

以下是重點：

• api 是傳輸協定。openai-completions 會呼叫 /chat/completions，對應 GPT 系列；anthropic-messages 會呼叫 /v1/messages，對應 Claude 系列。每種協定各設一個供應商項目，是最簡單的做法。
• baseUrl 只到 /api/agent 為止。請勿在後面加上 /v1：閘道會把路徑其餘部分轉發到上游，因此 /api/agent/v1/chat/completions 會回應 404 page not found。
• apiKey 支援 $VARIABLE 與 ${VARIABLE} 插值，因此檔案中不會存有任何機密。
• models 中的 id 必須屬於該供應商的協定：GPT 系列（例如 gpt-5.6-terra）放在 openai-completions，Claude 系列放在 anthropic-messages。對不屬於該端點的模型，chat 端點會回 400。contextWindow 只用來規劃 Pi 自己的上下文預算，而 maxTokens 會成為請求的輸出上限——Pi 在 OpenAI 相容路徑以 max_completion_tokens、在 Anthropic 路徑以 max_tokens 送到上游。

3. 提供 API Key

Copy
1
export CODEBYAI_API_KEY="sk-proj-xxxx"

把它加入 ~/.zshrc 或 ~/.bashrc，即可跨工作階段保留。金鑰本身請在 API Keys 頁面建立。Pi 也接受在命令列以 --api-key 傳入，供單次執行使用。

4. 啟動 Pi

Copy
1
cd your-project
2
pi --model codebyai/gpt-5.6-terra

若想透過 Anthropic 相容路線使用 Claude 模型：

Copy
1
pi --model codebyai-claude/claude-sonnet-5

若想在開始工作階段前確認 Pi 能看到哪些模型：

Copy
1
pi --list-models codebyai

5. 疑難排解

• 404 page not found：baseUrl 結尾多了 /v1，請移除。
• 出現 No models available，或 pi --list-models 中看不到這個供應商：啟動 Pi 的 shell 中 CODEBYAI_API_KEY 為空，Pi 因此略過整個項目。不存在的模型 id 一樣會被列出來，所以看不到模型幾乎都是金鑰沒設。
• 在 openai-completions 供應商出現 HTTP 403，訊息為 Invalid key! Your api-key is invalid or expired：金鑰已被刪除、輸入錯誤或已過期。換成 anthropic-messages 供應商時，閘道不會回錯誤狀態，而是以 200 把同一句話當純文字回傳，因此 Pi 只會顯示 Anthropic stream ended without a stop reason——看到這則訊息同樣要當成金鑰問題。
• 額度不足：請在 錢包 頁面儲值。