ZCode 自訂模型：Claude 與 GPT

ZCode 是智譜推出的桌面 coding agent；用一個 OpenAI 相容供應商指向 Code By AI，就能跑 Claude 與 GPT 模型。

ZCode 是一套 Agentic Development Environment，不只是終端機外殼：Agent 會在對話中操作檔案、終端機、Git 與瀏覽器預覽。它的 Model Settings 面板接受自訂供應商，所以只換模型連線，Agent 與介面都不變。

一條命令配置（macOS / Linux）

先完全退出 ZCode。它會把供應商清單留在記憶體裡，並在儲存或結束時覆寫 ~/.zcode/v2/config.json；執行期間改的內容會被蓋掉。

Copy
1
curl -fsSL https://www.codebyai.net/setup.sh | sh -s -- --zcode

腳本會以隱藏輸入索要 API Key，加入 codebyai 供應商與 gpt-5.6-terra、claude-sonnet-5 兩個模型，備份原檔，並把檔案設為僅本人可讀寫。重跑可輪換金鑰；| sh -s -- --uninstall 會還原它找到的原檔。下面的手動步驟做的是同一件事。

1. 建立 Code By AI API Key

登入 Code By AI，打開 API Keys 頁面建立金鑰。金鑰形如 sk-proj-...。

2. 打開模型設定

在 ZCode 對話框底部打開模型選擇器，點 Manage models，進入 Settings → Model Settings。供應商就是在這裡新增。

3. 新增供應商

1. 在左側供應商列表底部點 Add Provider。
2. 命名為 Code By AI。
3. OpenAI API base URL 設為 https://www.codebyai.net/api/agent/v1。
4. 貼上 Code By AI API Key。
5. 儲存後點 Add Model，填入 gpt-5.6-terra；再點一次 Add Model，填入 claude-sonnet-5。
6. 打開該供應商的啟用開關。

兩個模型家族都走 OpenAI 協定。ZCode 的 Anthropic-messages 模式會送出舊版 thinking 參數，現行 Claude 模型會拒絕；閘道的 Chat Completions 路徑會把 claude-* ID 轉往 Claude 通道，並依 Claude 價格計費，所以一個供應商就能同時服務兩邊。

4. 選模型並測試

開一個工作階段，從模型選擇器挑選任一模型，送出一句簡短問題。能正常回覆，就代表端點、金鑰與模型 ID 都對上了。

模型 ID 與上下文視窗

模型 ID 以 模型廣場 列出的為準；上面兩個是本頁撰寫時的範例。新增到自訂供應商的模型，ZCode 預設給 200,000 token 的上下文視窗。到 Settings → Model Providers → Advanced 打開該模型，可以修改視窗大小與最大輸出 token 數；兩者都要儲存後對新工作階段生效。

疑難排解

• 404 page not found — base URL 不完整或多了一段路徑。請用 https://www.codebyai.net/api/agent/v1，不要接 /chat/completions，也不要重複 /v1。
• 401／金鑰無效 — 金鑰前後有空白、已被刪除或已過期。到 API Keys 頁面重新建立一把再貼上。
• 餘額不足 — 到 Wallet 頁面儲值。
• 400 且提到 reasoning level — 自訂供應商可能不接受 ZCode 提供的最高思考等級。把該模型的 effort 調低；閘道只轉送 ZCode 送出的等級。
• 供應商的模型列表是空的 — 啟用開關沒開，或 Add Model 沒有存到。
• 重新啟動 ZCode 後供應商不見了 — 腳本寫檔時 App 還在執行。請完全退出、再跑一次命令，然後重新開啟。