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。contextWindow 與 maxTokens 只影響 Pi 自身的預算計算，不會送到上游。

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 中看不到這個 provider：啟動 Pi 的 shell 中 CODEBYAI_API_KEY 為空，Pi 因此略過整個項目。不存在的模型 id 一樣會被列出來，所以看不到模型幾乎都是金鑰沒設。
• 回應開頭是 Hello! How can I help you with your software engineering tasks today?（HTTP 403）：閘道沒有收到任何 API 金鑰，代表這個 shell 中的變數為空。另一種 403 的訊息是 Invalid key!，表示金鑰已被刪除或輸入錯誤。
• 額度不足：請在 錢包 頁面儲值。