作者注：分清 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
- 打開 Agent 設置：在命令面板執行
agent: open settings。不同版本的界面入口名可能略有差異，以 AI / Agent 設置頁裏的 LLM Providers 區塊爲準。 - 在 LLM Providers 區塊點擊 Add Provider，類型選擇 OpenAI-compatible。
- Provider 名稱自己起一個，比如
apiyi，對應 settings.json 中的language_models.openai_compatible.apiyi。 - API URL 填
https://api.apiyi.com/v1。這裏必須帶/v1，這也是 API易 OpenAI 兼容頁給出的寫法。 - API Key 粘貼剛創建的令牌，Zed 會把它存進系統鑰匙串。
- 添加模型：name 填 API易 型號總表裏的真實 ID，例如
claude-opus-5-5、claude-sonnet-5-5，也可以加claude-fable-5-2。max_tokens按型號文檔填寫；不確定時先取保守值，跑通後再調大。 - 能力開關保持默認即可（tools=true）。需要發圖片時再手動打開 images。
- 回到 Agent 面板，在模型選擇器裏搜
apiyi或模型名。近期版本的模型選擇器已經支持模糊搜索，選中後發一條消息驗證。
這條路線的好處是一個 Provider 能掛多家模型。API易 文檔說明，OpenAI 兼容端點 /v1/chat/completions 只需要改一處模型字符串就能換模型。
路線 B：Anthropic-compatible 端點接入 Zed
- 同樣進入 LLM Providers → Add Provider，類型選擇 Anthropic-compatible。
- API URL 填
https://api.apiyi.com，只寫根域名，不加 /v1。實際請求會落到 API易 的 Anthropic 原生端點https://api.apiyi.com/v1/messages。 - 粘貼同一個令牌，或者另建一個專用令牌。
- 在 available_models 裏添加
claude-opus-5-5、claude-sonnet-5-5等 ID。 - 如果希望長上下文對話能命中緩存，打開
capabilities.prompt_caching。按 API易 Claude 能力頁的說明，緩存計費只在原生 Messages 格式下生效。 - 在模型選擇器中選中該模型，發一條消息測試。
💡 選擇建議：日常以 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 裏換模型，關鍵是確認要改的是哪一層：
- Zed Agent 換模型：在 LLM Providers 中用 Add Provider 添加 OpenAI-compatible 或 Anthropic-compatible 端點。
- External Agent：Claude Agent、OpenCode 等自行鑑權，Key 不與 Zed Agent 共用。
- 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 下對比效果。
📚 參考資料
- Zed GitHub 倉庫：源碼與 star 數觀察（2026-11-13）
- 鏈接：
github.com/zed-industries/zed -
說明：許可證以 GPL-3.0-or-later 爲主，含 Apache-2.0 組件
-
Zed AI Overview：三條 AI 路徑的官方說明
- 鏈接：
zed.dev/docs/ai/overview -
說明：Zed Agent、External Agents、Terminal Threads 的邊界
-
Zed Use API Access：自定義 Provider 配置
- 鏈接：
zed.dev/docs/ai/use-api-access -
說明：OpenAI-compatible / Anthropic-compatible 字段與鑰匙串存儲
-
Zed External Agents：ACP 外部 Agent
- 鏈接：
zed.dev/docs/ai/external-agents -
說明：Claude Agent、Codex、OpenCode 等的接入方式
-
Zed Releases：版本更新記錄
- 鏈接：
zed.dev/releases/stable -
說明：1.28.1 穩定版與 Preview 更新內容
-
API易 型號總表：模型 ID 與價格
- 鏈接：
docs.apiyi.com/models.md -
說明：輸入 / 輸出 / 緩存讀價格，以當天列表爲準
-
API易 Base URL 配置 FAQ：/v1 規則
- 鏈接：
docs.apiyi.com/faq/base-url-config.md -
說明：OpenAI 兼容與 Claude 原生 Base URL 寫法差異
-
API易 Claude 能力頁：原生與兼容端點
- 鏈接：
docs.apiyi.com/api-capabilities/claude.md -
說明：緩存計費僅在 Messages 格式下生效
-
API易 claude-opus-5-5 上線動態：使用限制
- 鏈接：
docs.apiyi.com/live/2026-09/claude-opus-5-5.md - 說明：思考、tool_choice、effort 默認值說明
作者：API易 技術團隊
技術交流：配置遇到問題，可查閱 docs.apiyi.com 文檔中心，或通過 API易 官網首頁聯繫我們
