Agent Zero 的 LiteLLM 模型錯誤，比起金鑰問題，更常是前綴或角色問題，因為 Agent Zero 從不傳送你輸入的模型名稱。 在 agent0ai/agent-zero main 上，models.py 會在每次 LiteLLM 呼叫前建立 f"{provider}/{model}"——聊天在第 385 行，嵌入在第 800 行——而 provider 部分來自 conf/model_providers.yaml，不是下拉式選單標籤。
兩項版本資訊決定了其餘內容的意義。最新版本是v2.12，發布於 2026 年 9 月 9 日，而舊的 frdel/agent-zero 路徑現在會解析到 agent0ai/agent-zero，因此較舊的複製命令和 issue 連結會遇到重新導向。此外，requirements.txt 固定使用 litellm==1.88.1，註解為 # CVE-2026-42271 fix: patched floor is 1.83.7。PyPI 將其日期記為 2026 年 6 月 9 日，而目前的 1.102.0 來自 2026 年 9 月 20 日。請以 1.88.1 檢查症狀，而不是參考 LiteLLM 目前的文件。全部查閱於 2026 年 9 月 21 日。
先讀取狀態碼，再處理金鑰
當例外帶有整數狀態碼時，_is_transient_litellm_error 只根據該狀態碼決定：408、429、500、502、503 和 504 為 true，任何其他 5xx 也為 true，其餘所有狀態均為 false。只有沒有狀態碼時，才會改以比對例外類別——包括逾時和連線錯誤——因此「沒有狀態」是唯一可以在沒有 4xx/5xx 可供指認時發生重試的情況。下表中的每個類別都帶有狀態碼，且內容是在 litellm 1.88.1 wheel 中讀取的。
| litellm 1.88.1 中的類別 | 狀態 | 在此通常代表什麼 | 是否重試？ |
|---|---|---|---|
AuthenticationError | 401 | 端點拒絕了憑證，或根本沒有收到憑證 | 否 |
BadRequestError | 400 | 包括以下兩種供應商解析失敗 | 否 |
LiteLLMUnknownProvider（BadRequestError 的子類別） | 400 | LiteLLM 在此端點上沒有路由的前綴 | 否 |
ContextWindowExceededError（BadRequestError 的子類別） | 400 | 內容過多，而不是錯誤的 id | 否 |
NotFoundError | 404 | 基礎 URL 的路徑錯誤，或端點不提供該 id | 否 |
RateLimitError | 429 | 上游限流 | 是 |
ServiceUnavailableError, InternalServerError | 5xx | 上游錯誤 | 是 |
一個例外與一個盲點。當 got_any_chunk 為 true 時，models.py 第 638 行會直接引發錯誤而不重試，因此串流中途出現的暫時性錯誤不會重試——「立即失敗」只是提示，不是證明。此外，configure_litellm() 會在匯入時執行，設定 LITELLM_LOG=ERROR 和 litellm.suppress_debug_info = True。在 1.88.1 中，get_llm_provider_logic.py 裡的 provider-list 提示受 if litellm.suppress_debug_info is False 保護——LiteLLM 原本會用來指向其供應商清單的那一行，正是 Agent Zero 關閉的那一行。
你輸入的 id 不是實際傳送的 id
每個供應商都有兩個識別碼，而 provider config 標頭正是如此說明：provider ID 驅動「設定 UI 下拉式選單」和 API 金鑰環境變數，而 litellm_provider 是「LiteLLM 中對應的供應商名稱」。第二個識別碼會被加到前面。對第三方 OpenAI 相容端點而言，provider id 是 other（「Other OpenAI compatible」），其 litellm_provider 是 openai，而 _adjust_call_args 也會將 other 重新映射為 openai。線上傳送的值是 openai/<your-model>，即 LiteLLM 文件所述的格式。因此請輸入純 id：根據這兩處程式碼，自行加上前綴會得到 openai/openai/gpt-4o——這是對程式碼的推理，而非觀察到的錯誤。
解析失敗時，1.88.1 有兩種不同的訊息字串，兩者的狀態碼皆為 400。get_llm_provider_logic.py 會拋出 BadRequestError，訊息為 "未提供 LLM 供應商 … 您傳入了 model=…" — 無法從字串推導出任何可用的資訊。LiteLLMUnknownProvider 位於 exceptions.py 第 902 行，帶有訊息 "此端點的 LLM 供應商未對應。您傳入了 model=…, custom_llm_provider=…" — 已推導出供應商，但在該端點上沒有適用於此供應商的路由。當某個供應商可用於一種角色，卻無法用於另一種角色時，預期會出現第二種訊息。
有一個衝突會把人引向錯誤欄位。Agent Zero 的 FAQ 表示，openai/gpt-5.3 對 OpenRouter 是正確的，但對原生 OpenAI 供應商不正確，後者「不帶前綴」；而 安裝指南的命名表將 OpenAI 列為「Model name only」。這些內容描述的是文字輸入框；程式碼則會在其上加上前綴。只要說明所處層級，兩者都是真的。該表格還有一項文件錯誤——OpenAI 那一列使用 Anthropic 模型 id 作為範例——因此不要複製該儲存格。
確認失敗的是三種角色中的哪一個
Agent Zero 分別設定三種角色——聊天、utility 和嵌入——每種都有自己的 provider、模型名稱和 API base。設定區段是 chat_model、utility_model 和 embedding_model，而舊版扁平鍵則是 chat_model_*、util_model_* 和 embed_model_*；若用錯誤的慣例搜尋 settings.json，就找不到任何內容。還有第四個值得了解的選用設定：內建瀏覽器外掛有自己的 model_preset，預設為空，文件說明為「空白時使用有效的 Main Model」——因此除非你設定它，瀏覽器工具失敗其實是聊天角色以另一個名稱失敗。此外，一次成功的聊天回覆只能證明一個角色運作，不代表三個角色都正常。
嵌入角色在兩方面有所不同，會影響問題分類。LiteLLMEmbeddingWrapper.embed 會以 embedding() 呼叫 LiteLLM，沒有 try/except，也沒有嘗試迴圈，因此無論類別為何，都會在第一次嘗試時引發錯誤。此外，內建預設值是 provider huggingface，名稱為 sentence-transformers/all-MiniLM-L6-v2；models.py 會將任何以 sentence-transformers/ 開頭的 huggingface 名稱路由至程序內包裝器，程式碼描述其可避免 HuggingFace API 呼叫，因此那裡的錯誤不一定涉及任何網路呼叫。
Kunavo 不提供嵌入模型，因此 Kunavo 金鑰可在 Agent Zero 中填入的角色只有聊天和 utility。
OpenRouter 是已確認的角色分流，也是此處唯一有維護者修正而非推論的分支。Issue #1597「OpenRouter embedding models fail due to LiteLLM missing provider route」於 2026 年 5 月 2 日開啟，並於 2026 年 8 月 27 日關閉，時間就在同日 v2.11 發布前數小時。這裡需要分開看待兩件容易混淆的事。設定確實會按角色路由 provider——chat 保留原生 litellm_provider: openrouter，而 embedding 則使用 litellm_provider: openai 加上明確的 api_base，並附有維護者的 TODO，指出 OpenRouter「尚未受到 LiteLLM 支援」——但這種分流在 v2.10 標籤和 main 上完全相同，因此不是關閉 issue 的原因。真正的變更只有 models.py 的一行：在 v2.10 中，嵌入包裝器建立了 f"{provider}/{model}" if provider != "openai" else model，使每個由 openai 路由的嵌入都遺失前綴；從 v2.11 起則無條件加上前綴，因此維護者的結案備註表示，包含斜線的 id 現在會完整抵達端點。在該分支上，修正方式是升級，而不是變更設定。
金鑰查找，以及為什麼「更換金鑰」經常沒有用
get_api_key(service) 會依固定順序讀取三個環境名稱，並回退到字面字串 "None"。
# Provider id `other` ("Other OpenAI compatible"). models.py reads these
# three names in this order and stops at the first non-empty value.
API_KEY_OTHER=sk-...
# OTHER_API_KEY=sk-...
# OTHER_API_TOKEN=sk-...
# A comma in the value is not a syntax error: models.py splits on it
# and rotates the resulting keys round-robin.該佔位符會被過濾——呼叫位置會在附加它之前檢查 api_key not in ("None", "NA")——因此未解析的金鑰表示完全不會傳送 api_key 引數，而 LiteLLM 會改用自己的環境查找。一個 401 可能來自你從未選擇的憑證。第二次查找使用不同的 service 值：_merge_provider_defaults 會以 原始 provider id 讀取金鑰，接著 _get_litellm_chat 回退到 get_api_key(provider_name)；到這時，該名稱已經是 LiteLLM provider——openai，對應 other。因此，如果同一個 .env 中設有 OpenAI 金鑰但未設定 API_KEY_OTHER，OpenAI 金鑰就會被傳送到你的端點。以上內容來自 main 上的這兩個函式；未載於文件，且未在此進行執行期測試。
安裝指南將金鑰放在 External Services → Other OpenAI-compatible API keys 下，然後將 OpenAI Compatible 設為 provider。附近記載的兩個症狀不是模型 id 錯誤：如果傳送時毫無反應，FAQ 將原因歸咎於未在 Settings 中設定金鑰；而 ChatGPT Plus 不包含 API 額度——不過內建的 OAuth plugin 會提供 codex_oauth 連線，使用 OpenAI 帳戶登入，因此說「沒有訂閱就無法驅動 Agent Zero」是不正確的。
端點，以及兩條看似矛盾的規則
other provider 不提供預設的 api_base，而 ModelConfig.build_kwargs 只有在該欄位非空時才會轉送——因此空白的 API URL 不會傳送基礎 URL，LiteLLM 的標準 openai 預設值會生效。這在 1.88.1 中會解析到哪個主機，此處未進行檢查；若空白 URL 出現 401，應將其視為需要填寫欄位的理由，而不是診斷結果。LiteLLM 的相容端點頁面接著提供兩項方向相反的說明：「不要在基礎 URL 後附加任何內容，例如 /v1/embedding」以及「如果測試時看到 Not Found Error，請確認你的 api_base 有 /v1 後綴」。兩者可整合為一條規則——以 /v1 結尾，後面不要再加任何內容。
在 Docker 下，安裝指南明確指出，API base URL 中的 localhost 和 127.0.0.1 代表容器：請使用 http://host.docker.internal:<port>，或在預設 Linux bridge 上使用例如 http://172.17.0.1:<port> 的 gateway 位址；如果伺服器繫結至主機 loopback，請將其移至 Docker 可連線的位址，例如 0.0.0.0。接著確認你讀取的設定就是實際執行的設定：A0_SET_ 預設值只會在初始時使用——「一旦某個值儲存於 settings.json，就會優先於這些環境變數」——並且需要重新啟動。另一方面，issue #1769（於 2026 年 7 月 15 日開啟，目前仍未關閉）回報，當模型註冊的 provider 與實際提供服務的 provider 不同時，LiteLLM 會呼叫 exit(-9)：這是其中一名回報者的分析，尚未確認，也未在此重現。
錯誤修正的代價
讓失敗的 utility 角色停止報錯，最快的方法是將它指向主模型。這樣確實可運作，但其流量會以主模型的費率計費；安裝指南將這些流量描述為摘要和記憶擷取。以下數字是說明性的 token 算術，不是實測任務成本，也不是帳單上限：假設主模型一天的工作量為 1200k 個輸入 tokens 和 60k 個輸出 tokens，utility 流量為 320k 和 24k，並採用每百萬 tokens 的即時 Kunavo 目錄費率。
| utility 欄位中的模型 | 每 1M 的輸入／輸出 | 單日 utility 流量 |
|---|---|---|
| Claude Sonnet 4.6 | $2.10 / $10.50 | $0.924 |
| GPT-5.6 Terra | $0.70 / $4.20 | $0.325 |
| Claude Haiku 4.5 | $0.70 / $3.50 | $0.308 |
主要角色本身在當天的模型費用為 $3.150；將工具角色合併進來會增加 Claude Sonnet 4.6 的 $0.924 費用，而 Claude Haiku 4.5 的模型費用為 $0.308。不過請留意能力下限：安裝指南警告，工具模型必須「足夠強大，才能可靠地擷取並整合記憶」，而約 4B 的非常小型模型通常無法可靠地完成內容擷取。指南將此描述為任務失敗，而不是錯誤，因此此處若診斷為「模型發生錯誤」便是不正確的。
Agent Zero 本身不收取授權費——其主分支上的 LICENSE 是 MIT 授權文字，著作權標示為「Agent Zero, s.r.o」——因此費用來自你為各角色設定的模型 Token。Kunavo 的目錄金額是計費下限，而非上限：上游回報費用時，帳單金額取目錄成本與上游成本乘以適用加價率兩者中較高者。最低儲值金額為 $10 的預付額度。請參閱 計費詳細資訊。
要在角色後方設定哪種路由
| 方式 | 適用時機 | 此失敗模式下你需支付的費用 |
|---|---|---|
| 直接使用供應商 API | 全天使用同一供應商，遵循該供應商自身的快取與批次條款 | 每個供應商都有自己的項目與前綴，因此新增第二個供應商就多了一組必須正確設定的名稱 |
| 具名閘道（OpenRouter） | 你會依任務切換模型，並希望 Agent Zero 原生進行路由 | 僅原生支援聊天——嵌入項目改由 openai 路由，並改用明確的基礎 URL |
透過 other 使用 OpenAI 相容閘道 | 在 Agent Zero 沒有對應項目的端點上，使用一組金鑰與一個餘額 | 沒有可供自動完成的模型清單、沒有預設基礎 URL，而且若未設定自有名稱，金鑰會回退使用 OpenAI 名稱 |
| 透過 OAuth 外掛程式登入帳戶 | 你已經支付它所連接的帳戶費用——例如 Codex 方案或 GitHub Copilot——而且不想貼上金鑰 | 其 README 表示這些連線完全不會要求你提供 API 金鑰——它們連接的是帳戶，而不是你的端點；此外，其 Google Cloud Gemini 項目明確表示會按照 Gemini API 計費，而不是使用訂閱方案計費 |
| 本機模型伺服器 | 適合小型或私密工作，且不收取每次請求費用 | Docker 位址規則仍然適用，而工具角色的能力下限在此處影響最為明顯 |
如需依角色進行預算規劃，請參閱 Agent Zero API 費用；如需了解第三個項目，請參閱變更嵌入模型；如需一般性的基礎 URL 與前綴慣例，請參閱 OpenAI 相容 API。若要將 Kunavo 金鑰接上 other：先從錯誤參考開始，再建立帳戶。Agent Zero 尚未針對 Kunavo 的端點進行執行期測試，因此嘗試期間請保留一條可運作的路由。
常見問題
為什麼 Agent Zero 會拒絕拼寫正確的模型名稱？
因為 Agent Zero 傳送的不是你輸入的名稱。在 agent0ai/agent-zero main 上，models.py 會在每次 LiteLLM 呼叫前建立 f"{provider}/{model}"——聊天角色在第 385 行，嵌入角色在第 800 行；其中 provider 部分是 conf/model_providers.yaml 中的 litellm_provider 值，而不是 Settings 下拉式選單中的標籤。對於 provider id `other`（「Other OpenAI compatible」），該值是 openai，而 _adjust_call_args 會再次重新映射，因此 LiteLLM 實際收到的是 openai/<your-model>。請輸入不含前綴的純 id。根據這兩處程式碼，如果你自行輸入 openai/gpt-4o，結果會是 openai/openai/gpt-4o——這是從程式碼推論出的結果，並非觀察到或記錄在文件中的行為。來源查閱於 2026 年 9 月 21 日。
Agent Zero 中的 LiteLLM 模型錯誤，是否表示我的 API 金鑰錯了？
通常不是，而狀態碼可以區分兩者。在 Agent Zero 固定使用的 litellm 1.88.1 wheel 中，驗證錯誤會在 401 回傳 AuthenticationError；另外兩種供應商解析錯誤則是 400：get_llm_provider_logic.py 會以「LLM Provider NOT provided」引發 BadRequestError，而 LiteLLMUnknownProvider——exceptions.py 第 902 行中 BadRequestError 的子類別——會帶有「Unmapped LLM provider for this endpoint」。兩者都帶有整數 status_code，而 Agent Zero 的 _is_transient_litellm_error 只會在 408、429 和 5xx 時重試帶有狀態碼的錯誤——因此兩種錯誤類別都會在第一次嘗試時直接呈現，彼此都不能作為另一者的證據。在更換金鑰前，請先檢查模型字串和基礎 URL。
為什麼 Agent Zero 中只有嵌入模型失敗？
因為該角色的路由和重試方式不同於聊天角色。models.py 中的 LiteLLMEmbeddingWrapper.embed 會呼叫 LiteLLM 的 embedding()，沒有 try/except，也沒有嘗試迴圈，因此無論錯誤類別為何，都會在第一次嘗試時引發；聊天路徑則會重試暫時性錯誤。該角色的內建預設值是 provider huggingface，名稱為 sentence-transformers/all-MiniLM-L6-v2；models.py 會將任何以 sentence-transformers/ 開頭的 huggingface 名稱路由至程序內包裝器，程式碼描述其可避免呼叫 HuggingFace API——因此那裡的失敗完全可能不涉及網路呼叫。OpenRouter 是文件中明確區分的案例：conf/model_providers.yaml 對聊天原生路由，但對嵌入則使用 litellm_provider openai 加上明確的 api_base，並附有維護者 TODO。Kunavo 不提供嵌入模型，因此該欄位應使用本機預設值，或使用提供這項功能的供應商。
Agent Zero 使用哪個 LiteLLM 版本？
agent0ai/agent-zero main 上的 requirements.txt 固定使用 litellm==1.88.1，並附有內嵌註解「CVE-2026-42271 fix: patched floor is 1.83.7」。PyPI 記錄 1.88.1 於 2026 年 6 月 9 日上傳，而目前版本為 1.102.0，於 2026 年 9 月 20 日上傳。因此，LiteLLM 在 1.88.1 之後加入的行為、參數支援和錯誤文字不會存在於 Agent Zero 安裝中；以 LiteLLM 目前的文件檢查某個症狀，可能是在描述你實際未執行的程式碼。查閱於 2026 年 9 月 21 日；當然，在容器內手動執行 pip install 可能會改變版本。
我應該在 Agent Zero 的 Model Name 欄位中輸入供應商前綴嗎？
不用，而且 Agent Zero 自己的文件也同意你填寫的欄位應如此處理：其 FAQ 表示，openai/gpt-5.3 對 OpenRouter 是正確的，但對原生 OpenAI 供應商不正確，後者「不帶前綴」；安裝指南的命名表則將 OpenAI 列為「Model name only」。這些句子描述的是文字輸入框；程式碼接著會在你輸入的內容上再加上 LiteLLM provider。只要說清楚所處層級，兩者都是真的；混淆兩者的句子則不是。對該表格另有一項提醒：OpenAI 那一列使用 Anthropic 模型 id 作為範例，因此它說明的是格式，而不是可運作的 OpenAI id。
為什麼 Agent Zero 會重試某個錯誤，卻不重試另一個？
當例外帶有 HTTP 狀態時，狀態會單獨決定結果，其他因素都不影響。models.py 中的 _is_transient_litellm_error 會先檢查整數 status_code：408、429、500、502、503 和 504 為 true，任何其他 5xx 也為 true，其餘所有狀態均為 false——因此無論 400 或 401 看起來多麼嚴重，都會被視為最終錯誤。只有在沒有狀態碼時，才會改以比對例外類別，包括逾時和連線錯誤；因此沒有 HTTP 狀態的失敗仍可能被重試。另一個閘門也容易讓人誤判：當 got_any_chunk 為 true 時，models.py 第 638 行會直接引發錯誤而不重試，因此串流開始後才發生的暫時性錯誤也不會重試。「立即失敗」本身不能證明錯誤是 400 或 401。
Agent Zero 的行為取自 agent0ai/agent-zero main 分支——models.py 與 conf/model_providers.yaml——以及其文件、版本發布資訊與問題追蹤，資料截至 2026 年 9 月 21 日；LiteLLM 的例外類別與錯誤字串則讀自 PyPI 上 litellm 1.88.1 套件中的內容，也就是 Agent Zero 鎖定的版本。本文沒有進行任何執行期測試：未執行安裝，也未端對端重現任何錯誤。Kunavo Token 費率來自即時目錄，而所有美元數字皆為示意性的 Token 計算。