Zed 想換模型？用 OpenAI 兼容端點接上 API易：2 種 Provider 配置

作者注：分清 Zed 的三條 Agent 路徑，再用 OpenAI-compatible 和 Anthropic-compatible 兩種自定義 Provider 把 API易 接進 Zed，並說明 Base URL、模型 ID、價格和排錯要點。

你在 Zed 裏用 Agent 面板或 Inline Assistant 寫代碼，想換成別的模型，卻發現設置頁裏有 LLM Providers、External Agents、終端線程好幾個入口，不確定 Key 該填在哪。更常見的情況是填了一個第三方網關，結果一直報 404 或鑑權失敗。本文介紹 用 Zed 自定義 Provider（OpenAI-compatible / Anthropic-compatible）接入第三方模型網關 的完整做法，以 API易 爲例走通配置流程。

這不是又一篇“複製粘貼配置就完事”的速查。文章先講清 Zed 三條 AI 路徑各自的模型接入邊界，再給出兩條可以照做的路線。Base URL 什麼時候加 /v1、什麼時候不加，這個最容易出錯的細節會單獨講。

核心價值：讀完本文，你能判斷自己要改的是哪一層配置，並在 5 分鐘內讓 Zed Agent 用上 claude-opus-5-5、claude-sonnet-5-5 這類模型。出了問題，也知道該先查哪一項。

---

Zed 換模型核心要點：先分清三條 Agent 路徑

Zed 是 Atom / Tree-sitter 原班人馬打造的高性能多人協作編輯器。截至 2026-11-13，GitHub 倉庫 zed-industries/zed 約有 94,884 star（GitHub API 觀察）。官方 releases 頁顯示，2026-11-11 的穩定版爲 1.28.1，同日 Preview 爲 1.29.1。macOS、Linux、Windows 都可以直接下載，Web 版尚未正式可用。

在 Zed 裏換模型之前，要先明白一點：官方文檔把 AI 能力分成三條路徑，每條路徑的模型接入方式和鑑權方式都不一樣。如果填錯了地方，配置不會生效，Key 也不會被另一條路徑讀取。

路徑	模型從哪來	鑑權由誰管	典型用途
Zed Agent	LLM Providers（Zed 託管、廠商 Key、訂閱、網關、本地模型）	Zed 本身，Key 存系統鑰匙串	Agent 面板、Inline Assistant、內置工具 / profiles / skills / MCP
External Agents（ACP）	外部 Agent 自己選模型	外部 Agent 自己管	在 Zed 線程裏運行 Claude Agent、Codex、OpenCode、Copilot、Cursor 等
Terminal Threads	由你運行的 CLI / TUI 決定	CLI 自己的配置	在終端線程裏直接跑各類 Agent CLI

Zed Agent 與 External Agent 的接入邊界

“給 Zed Agent 換模型”指的是配置 LLM Providers，也就是 API Access 這一層，這是本文的主線。官方支持的一等廠商有 Anthropic、OpenAI、Google AI、Mistral、DeepSeek、xAI、OpenCode，另外還提供 Anthropic-compatible 和 OpenAI-compatible 兩種自定義端點。第三方網關就是從這兩種自定義端點接進來的。

如果你只是想在面板裏用 Claude Agent 或 OpenCode，那屬於 External Agent，走的是 Agent Client Protocol（ACP）。這種情況下線程由 Zed 託管，運行時、鑑權和模型選擇通常由外部 Agent 自己負責。你在 LLM Providers 裏填的 Key 不會自動共用給它，Claude Agent 需要在自己的線程裏執行 /login。外部 Agent 可以通過命令面板 zed: acp registry 打開註冊表安裝。按官方文檔的說法，Zed 不爲 External Agents 單獨收費，賬單在 Agent 提供方。

---

Zed 自定義 Provider 核心配置要點

兩種自定義端點的差別主要在請求格式上。OpenAI-compatible 走 Chat Completions，Anthropic-compatible 走 Messages API（/v1/messages）。這個差別直接決定了 Base URL 的寫法，也決定了能不能用上 Prompt Cache 計費。

配置項	OpenAI-compatible	Anthropic-compatible
請求格式	/v1/chat/completions	/v1/messages
API易 api_url	https://api.apiyi.com/v1	https://api.apiyi.com（不加 /v1）
模型字段	available_models[].name + max_tokens	available_models
能力開關	默認 tools=true、images=false、chat_completions=true	可配 capabilities.prompt_caching
緩存計費	API易 文檔說明不生效	原生 Messages 格式下生效
適合場景	想用一個 Provider 掛多家模型	主力用 Claude、長上下文、需要緩存

Base URL 爲什麼一個加 /v1、一個不加

根據 API易 Base URL FAQ（文檔覈對 2026-11-13），OpenAI 兼容客戶端會在 api_url 後面直接拼接 /chat/completions，所以 api_url 要寫到 /v1 這一級。Anthropic 一側的客戶端會自己拼接 /v1/messages，只能填根域名。如果寫成 https://api.apiyi.com/v1，最終請求就會變成 /v1/v1/messages，直接返回 404。

還有兩點需要注意。Zed 的 API Key 存在系統鑰匙串裏，不會寫進 settings.json；如果對應的環境變量非空，環境變量會優先於鑰匙串生效。另外，只支持 Responses 接口的模型要把 capabilities.chat_completions 設爲 false，否則 Zed 會按 Chat Completions 去調用。

---

Zed 接入 API易 快速上手

下面兩條路線可以只選一條，也可以都配上，在模型選擇器裏切換。動手前先準備好 Key。

🚀 快速開始：登錄後在 API易 令牌頁 api.apiyi.com/token 創建一個令牌，建議爲 Zed 單獨建一個，便於查看用量和隨時吊銷。快速開始文檔 docs.apiyi.com/getting-started 還提供 skill.md / llms.txt，方便讓 Agent 讀取平臺說明。

路線 A：OpenAI-compatible 端點接入 Zed

1. 打開 Agent 設置：在命令面板執行 agent: open settings。不同版本的界面入口名可能略有差異，以 AI / Agent 設置頁裏的 LLM Providers 區塊爲準。
2. 在 LLM Providers 區塊點擊 Add Provider，類型選擇 OpenAI-compatible。
3. Provider 名稱自己起一個，比如 apiyi，對應 settings.json 中的 language_models.openai_compatible.apiyi。
4. API URL 填 https://api.apiyi.com/v1。這裏必須帶 /v1，這也是 API易 OpenAI 兼容頁給出的寫法。
5. API Key 粘貼剛創建的令牌，Zed 會把它存進系統鑰匙串。
6. 添加模型：name 填 API易 型號總表裏的真實 ID，例如 claude-opus-5-5、claude-sonnet-5-5，也可以加 claude-fable-5-2。max_tokens 按型號文檔填寫；不確定時先取保守值，跑通後再調大。
7. 能力開關保持默認即可（tools=true）。需要發圖片時再手動打開 images。
8. 回到 Agent 面板，在模型選擇器裏搜 apiyi 或模型名。近期版本的模型選擇器已經支持模糊搜索，選中後發一條消息驗證。

這條路線的好處是一個 Provider 能掛多家模型。API易 文檔說明，OpenAI 兼容端點 /v1/chat/completions 只需要改一處模型字符串就能換模型。

路線 B：Anthropic-compatible 端點接入 Zed

1. 同樣進入 LLM Providers → Add Provider，類型選擇 Anthropic-compatible。
2. API URL 填 https://api.apiyi.com，只寫根域名，不加 /v1。實際請求會落到 API易 的 Anthropic 原生端點 https://api.apiyi.com/v1/messages。
3. 粘貼同一個令牌，或者另建一個專用令牌。
4. 在 available_models 裏添加 claude-opus-5-5、claude-sonnet-5-5 等 ID。
5. 如果希望長上下文對話能命中緩存，打開 capabilities.prompt_caching。按 API易 Claude 能力頁的說明，緩存計費只在原生 Messages 格式下生效。
6. 在模型選擇器中選中該模型，發一條消息測試。

💡 選擇建議：日常以 Claude 爲主、會話長、經常反覆讀同一批文件，選路線 B 更划算。需要在多家模型之間頻繁切換，選路線 A 更省事。兩條路線可以用同一個 API易 令牌，在 Zed 模型選擇器裏按任務切換。

Claude 模型價格參考（數據日期 2026-11-13）

以下數據來自 API易 型號總表，於 2026-11-13 文檔覈對，單位爲美元 / 每 1M tokens，按量計費。

模型 ID	輸入	輸出	緩存讀	支持端點	可用平臺
claude-opus-5-5	$4	$20	$0.2	chat + messages	API易 apiyi.com
claude-opus-5-5-thinking	同 opus-5-5	同 opus-5-5	同 opus-5-5	以總表爲準	API易 apiyi.com
claude-sonnet-5-5	$2	$10	$0.1	以總表爲準	API易 apiyi.com
claude-fable-5-2	$8	$40	$0.2	以總表爲準	API易 apiyi.com

型號與價格以平臺型號列表爲準。配置前可以打開 docs.apiyi.com/models 覈對當天的數字和分組（總表中 claude-opus-5-5 列有 ClaudeCode、Claude_Reverse、Claude_Enterprise、Default、SVIP 等分組）。

關於 claude-opus-5-5 的使用限制，API易 上線動態（2026-09-23）提到三點：思考無法設爲 disabled；tool_choice 設爲 any / tool 會返回 400；effort 默認 medium。如果 Zed Agent 調用工具時出現 400，先排查這幾項。

---

Zed 自定義端點常見報錯排查

自定義 Provider 出錯時，大多數問題出在 URL、Key 和模型名這三處。下表按出現頻率排序，可以逐項檢查。

現象	常見原因	處理方式
404 Not Found	Anthropic-compatible 填了 /v1，路徑變成 /v1/v1/messages	改回根域名 https://api.apiyi.com
404 / 路徑不對	OpenAI-compatible 漏了 /v1	改爲 https://api.apiyi.com/v1
401 / 鑑權失敗	令牌錯誤、已刪除，或環境變量覆蓋了鑰匙串	到 api.apiyi.com/token 重新覈對，清空衝突的環境變量
模型不存在	ID 拼寫錯誤或使用了別名	照 docs.apiyi.com/models 複製原始 ID
400（工具調用）	tool_choice 爲 any / tool，或嘗試關閉思考	按上線動態說明調整
圖片無效	OpenAI-compatible 默認 images=false	在 capabilities 中打開 images
只支持 Responses 的模型報錯	仍按 Chat Completions 調用	將 capabilities.chat_completions 設爲 false

🎯 排錯建議：遇到 404，先把 Zed 設置裏的 api_url 和 API易 Base URL FAQ（docs.apiyi.com/faq/base-url-config）逐字對照。大部分問題都是 /v1 多寫或少寫了一次。

---

使用 Zed 自定義 Provider 的風險提示

• 非官方託管：OpenAI-compatible / Anthropic-compatible 自定義 Provider 是 Zed 提供的通用接入能力，第三方網關不屬於 Zed 官方託管服務。出現服務問題時，需要找網關方處理。
• Key 與賬單由你負責：令牌和用量計費都在你自己的賬戶下。建議爲 Zed 單獨建令牌，定期查看用量，不要把 Key 寫進 settings.json 後提交到倉庫。Zed 默認使用鑰匙串存儲，本身就降低了這個風險。
• External Agent 的條款在提供方：Claude Agent、Codex 等外部 Agent 的訂閱、配額和使用條款由各自提供方決定，與 Zed Agent 的 Provider 配置相互獨立。
• 版本差異：本文界面描述基於 1.28.x / 1.29.x 的官方文檔與 releases 信息（觀察日期 2026-11-13），後續版本的入口名稱可能會調整。

---

常見問題 FAQ

Q1：Zed 的 OpenAI 兼容端點是什麼？

它是 LLM Providers 裏的一種自定義 Provider 類型。只要服務端實現了 Chat Completions 接口，就可以通過 api_url 和模型列表接入 Zed Agent，不需要等 Zed 官方適配。

Q2：在 LLM Providers 裏填的 Key，Claude Agent 能直接用嗎？

不能。Claude Agent 屬於 External Agent，鑑權由它自己管理，需要在它的線程裏執行 `/login`。LLM Providers 裏的 Key 只給 Zed Agent 使用。

Q3：OpenAI-compatible 和 Anthropic-compatible 該選哪個？

主力用 Claude、需要緩存計費時選 Anthropic-compatible；想用一個 Provider 掛多家模型時選 OpenAI-compatible。按 API易 文檔說明，緩存計費只在原生 Messages 格式下生效。

Q4：模型 ID 應該填什麼？

填平臺型號總表裏的原始 ID，例如 `claude-opus-5-5`、`claude-sonnet-5-5`、`claude-fable-5-2`。建議直接從 docs.apiyi.com/models 複製，避免手打拼錯導致“模型不存在”。

Q5：配置完一直 404，怎麼排查？

先看 `/v1`：OpenAI-compatible 要帶，Anthropic-compatible 不能帶。如果路徑沒問題，再檢查模型 ID 是否和 API易 型號列表一致。

Q6：API Key 存在哪裏？會被同步到倉庫嗎？

Zed 把 Key 存在系統鑰匙串，不寫進 settings.json，所以分享設置文件時不會帶出 Key。需要注意的是，同名環境變量非空時會優先於鑰匙串，排查 401 時別忘了檢查環境變量。

Q7：這套配置有哪些已知限制？

OpenAI-compatible 默認不開圖片能力；`claude-opus-5-5` 的思考不能關閉，`tool_choice` 設爲 any / tool 會返回 400。另外，自定義 Provider 不是 Zed 官方託管服務，穩定性取決於網關方。

---

Zed 接入 API易 核心要點 Key Takeaways

• 先分路徑：Zed Agent 走 LLM Providers，External Agent 自己管鑑權。
• 兩種端點：OpenAI-compatible 走 chat，Anthropic-compatible 走 messages。
• URL 規則：OpenAI 兼容填 /v1，Claude 原生只填根域名。
• 模型 ID：照 API易 型號總表複製 claude-opus-5-5 等原始 ID。
• 緩存計費：需要緩存時用 Anthropic-compatible 並開啓 prompt_caching。
• 排錯順序：依次檢查 /v1、令牌、模型 ID、工具參數。
• 上手方式：在 api.apiyi.com/token 建專用令牌，5 分鐘即可配完。

---

總結

在 Zed 裏換模型，關鍵是確認要改的是哪一層：

1. Zed Agent 換模型：在 LLM Providers 中用 Add Provider 添加 OpenAI-compatible 或 Anthropic-compatible 端點。
2. External Agent：Claude Agent、OpenCode 等自行鑑權，Key 不與 Zed Agent 共用。
3. Base URL：OpenAI 兼容填 https://api.apiyi.com/v1，Anthropic 兼容填 https://api.apiyi.com，/v1 多寫或少寫都會 404。

配置之前，建議先在 docs.apiyi.com/models 覈對當天的型號與價格，再從令牌頁創建 Zed 專用 Key。先用 claude-sonnet-5-5 跑通，再按任務切換到 claude-opus-5-5。可以通過 API易 apiyi.com 用同一個令牌在兩種 Provider 下對比效果。

---

📚 參考資料

1. Zed GitHub 倉庫：源碼與 star 數觀察（2026-11-13）
2. 鏈接：github.com/zed-industries/zed

3. 說明：許可證以 GPL-3.0-or-later 爲主，含 Apache-2.0 組件

4. Zed AI Overview：三條 AI 路徑的官方說明

5. 鏈接：zed.dev/docs/ai/overview

6. 說明：Zed Agent、External Agents、Terminal Threads 的邊界

7. Zed Use API Access：自定義 Provider 配置

8. 鏈接：zed.dev/docs/ai/use-api-access

9. 說明：OpenAI-compatible / Anthropic-compatible 字段與鑰匙串存儲

10. Zed External Agents：ACP 外部 Agent

11. 鏈接：zed.dev/docs/ai/external-agents

12. 說明：Claude Agent、Codex、OpenCode 等的接入方式

13. Zed Releases：版本更新記錄

14. 鏈接：zed.dev/releases/stable

15. 說明：1.28.1 穩定版與 Preview 更新內容

16. API易 型號總表：模型 ID 與價格

17. 鏈接：docs.apiyi.com/models.md

18. 說明：輸入 / 輸出 / 緩存讀價格，以當天列表爲準

19. API易 Base URL 配置 FAQ：/v1 規則

20. 鏈接：docs.apiyi.com/faq/base-url-config.md

21. 說明：OpenAI 兼容與 Claude 原生 Base URL 寫法差異

22. API易 Claude 能力頁：原生與兼容端點

23. 鏈接：docs.apiyi.com/api-capabilities/claude.md

24. 說明：緩存計費僅在 Messages 格式下生效

25. API易 claude-opus-5-5 上線動態：使用限制

26. 鏈接：docs.apiyi.com/live/2026-09/claude-opus-5-5.md
27. 說明：思考、tool_choice、effort 默認值說明

---

作者：API易 技術團隊
技術交流：配置遇到問題，可查閱 docs.apiyi.com 文檔中心，或通過 API易 官網首頁聯繫我們

延伸閱讀

• 手把手教程：一個 Key 接上所有 Agent，用開源 magpie 統一接入 API 網關（以 Claude Code、Codex、Pi、Hermes 爲例）:一份能照着做完的教程：約 30 分鐘讓你機器上所有編程 Agent（以 Claude Code、Codex、Pi、Hermes 爲例）共用一個 API Key 和一個網關地址。含 magpie 界面截圖、逐步接入流程、原生配置對照和報錯排查表。
• Antigravity 大更新曝光：4 個新變化，用 Magpie 接上 APIYI:拆解 Antigravity 大更新的新 UI、語音 Agent、雲執行和 Gemini 4 Carbon，標清證據等級，並給出用 Magpie 把 APIYI 接進 Antigravity 的 3 條路線與 5 步配置。
• OpenCode 怎麼用 Claude 訂閱？3 步接入，5 個限制:OpenCode 2.2.3 新增 Claude Agent：本機裝好 Claude Code、跑一次 claude auth login，就能在 /connect 裏用 Claude 訂閱跑 Claude 模型。本文講清它和 3 月被下架插件的區別、3 步接入、並行讀文件爲何變串行，以及 5 個限制；沒有訂閱或團隊共用，也可用 API易 按量調用 Claude Opus 5.5。