Agent Zero 的 LiteLLM 模型错误更常见的原因是前缀或角色问题，而不是 key 问题，因为 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 日完成。
先读取状态码，再动 key
当异常携带整数状态码时，_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 | 包括下面两个 provider 解析失败 | 否 |
LiteLLMUnknownProvider（子类为 BadRequestError） | 400 | LiteLLM 在此端点上没有路由的前缀 | 否 |
ContextWindowExceededError（子类为 BadRequestError） | 400 | 上下文过多，而不是 id 错误 | 否 |
NotFoundError | 404 | base URL 的路径错误，或端点不提供该 id | 否 |
RateLimitError | 429 | 上游限流 | 是 |
ServiceUnavailableError, InternalServerError | 5xx | 上游故障 | 是 |
一个异常和一个盲点。models.py 第 638 行会在 got_any_chunk 为 true 时抛出错误，而不是重试，因此流式传输中途到达的临时错误不会重试——“它立即失败了”只是提示，不是证明。而且 configure_litellm() 会在导入时运行，设置 LITELLM_LOG=ERROR 和 litellm.suppress_debug_info = True。在 1.88.1 中，get_llm_provider_logic.py 中的 provider 列表提示受 if litellm.suppress_debug_info is False 保护——LiteLLM 本应借此将你指向其 provider 列表的那一行，正是 Agent Zero 关闭的那一行。
你输入的 id 不是实际发送的 id
每个 provider 有两个标识符，provider config 标题对此有明确说明：provider ID 驱动“the settings UI dropdowns”和 API key 环境变量，而 litellm_provider 是“LiteLLM 中对应的 provider 名称”。后者会被添加为前缀。对于第三方 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 Provider NOT provided … You passed model=…"——未能从该字符串中解析出任何可用信息。exceptions.py 第 902 行的 LiteLLMUnknownProvider 携带的消息为 "Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…"——确实已解析出提供商，但该端点上没有适用于它的路由。当某个提供商能用于一种角色，却不能用于另一种角色时，预期会出现第二种错误。
有一个冲突会把人引向错误字段。Agent Zero 的 FAQ 表示，openai/gpt-5.3 对 OpenRouter 是正确的，但对原生 OpenAI provider 不正确，后者“which goes without prefix”；安装指南的命名表则将 OpenAI 列为 "Model name only"。这些内容描述的是文本框；代码会在其之上添加前缀。明确层级后，两者都成立。该表还存在一个文档错误——其 OpenAI 行使用了 Anthropic 模型 id 作为示例——因此不要复制该单元格。
找出失败的是三个角色中的哪一个
Agent Zero 独立配置三个角色——聊天、实用和嵌入——每个角色都有自己的 provider、模型名称和 API base。设置部分是 chat_model、utility_model 和 embedding_model，而旧版扁平 key 是 chat_model_*、util_model_* 和 embed_model_*；如果用错误的约定搜索 settings.json，将什么也找不到。还有第四个值得了解的可选选择：捆绑的浏览器插件有自己的 model_preset，默认为空，文档说明为空时“Empty uses the effective Main Model”——因此除非你进行设置，否则浏览器工具故障其实是聊天角色以另一个名称发生故障。而且，一次成功的聊天回复只能证明一个角色有效，不能证明三个都有效。
嵌入角色有两个不同之处，会改变排查方式。LiteLLMEmbeddingWrapper.embed 调用 LiteLLM 的 embedding() 时没有 try/except，也没有尝试循环，因此无论异常类是什么，都会在第一次尝试时抛出。并且默认配置是 provider huggingface，名称为 sentence-transformers/all-MiniLM-L6-v2；models.py 会将任何以 sentence-transformers/ 开头的 huggingface 名称路由到进程内包装器，代码称其可避免调用 HuggingFace API，因此该处故障不一定涉及任何网络调用。
Kunavo 不提供嵌入模型，因此 Kunavo key 在 Agent Zero 中可以填充的角色是聊天和实用角色。
OpenRouter 的角色分流已得到确认，也是这里唯一有维护者修复、而非仅凭推断的分支。Issue #1597“OpenRouter embedding models fail due to LiteLLM missing provider route”于 2026 年 5 月 2 日创建，并于 2026 年 8 月 27 日关闭，比同日发布的 v2.11 早数小时。这里需要区分两件容易混淆的事情。配置确实按角色路由提供商——chat 保留原生的 litellm_provider: openrouter，而 embedding 使用 litellm_provider: openai 加上显式的 api_base，对应维护者关于 OpenRouter“尚未受 LiteLLM 支持”的 TODO——但在 v2.10 标签和 main 上，这种分流配置完全相同，因此它不是关闭该 issue 的原因。真正解决问题的是 models.py 中的一行改动：在 v2.10 中，嵌入包装器构建 f"{provider}/{model}" if provider != "openai" else model，丢弃了每个由 openai 路由的嵌入调用的前缀；从 v2.11 开始，它会无条件添加前缀，这就是维护者在关闭说明中表示，包含斜杠的 id 现在会完整到达端点的原因。在该分支上，修复方式是升级，而不是更改设置。
key 的查找方式，以及为什么“更换 key”经常无效
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")——因此未解析的 key 意味着根本不会发送 no api_key argument is sent at all，然后由 LiteLLM 执行自己的环境查找。401 可能来自你从未选择过的凭据。第二次查找使用不同的 service 值：_merge_provider_defaults 会在 原始 provider id 下读取 key，然后 _get_litellm_chat 退回到 get_api_key(provider_name)；此时该名称已经是 LiteLLM provider——openai，对应 other。因此，同一个 .env 中存在 OpenAI key、但 API_KEY_OTHER 未设置时，OpenAI key 会被发送到你的端点。以上内容来自对 main 中这两个函数的阅读；这里未记录，也未进行运行时测试。
安装指南要求将 key 放在 External Services → Other OpenAI-compatible API keys 下，然后将 OpenAI Compatible 设为 provider。附近记录的两个症状并不是模型 id 故障：发送时什么也没有发生，FAQ 将其归因于 Settings 中未设置 key；而 ChatGPT Plus 不包含 API credits——不过捆绑的 OAuth plugin 提供了一个 codex_oauth 连接，可使用 OpenAI 账户登录，因此说“没有订阅可以驱动 Agent Zero”是不正确的。
端点，以及两条看似矛盾的规则
other provider 不提供 默认 api_base，而 ModelConfig.build_kwargs 仅在该字段非空时才转发它——因此空白 API URL 不会发送 base，LiteLLM 会采用其默认的 openai。这里未检查 1.88.1 中它实际解析到哪个主机；如果空白 URL 返回 401，应将其视为需要填写该字段的理由，而不是诊断结论。LiteLLM 的兼容端点页面随后给出两条方向相反的说明：“Do NOT add anything additional to the base url e.g. /v1/embedding”以及“If you see Not Found Error when testing make sure your api_base has the /v1 postfix.”两者可以统一为一条规则——以 /v1 结尾，后面不要再添加任何内容。
在 Docker 下，安装指南明确说明 API 基础 URL 中的 localhost 和 127.0.0.1 指的是容器：请使用 http://host.docker.internal:<port>，或默认 Linux 网桥上类似 http://172.17.0.1:<port> 的网关地址，并将绑定到主机回环地址的服务器改为绑定到 Docker 可访问的地址，例如 0.0.0.0。然后确认你读取的配置就是实际运行时使用的配置：A0_SET_ 预设仅是初始默认值——“一旦某个值保存到 settings.json 中，它就会优先于这些环境变量生效”——并且需要重启。另外，issue #1769（于 2026 年 7 月 15 日创建，仍未关闭）报告称，当模型注册的提供商与实际提供服务的提供商不同时，LiteLLM 会调用 exit(-9)：这是某位报告者的分析，尚未确认，也未在此复现。
错误修复的代价
让失败的实用角色安静下来的最快方法，是将它指向主模型。这样可行，但安装指南所描述的摘要和记忆提取流量会按主模型的费率计费。以下数字是说明性的令牌算术，不是测量得到的任务成本，也不是账单上限：假设一天的主模型工作使用 1200k 输入令牌和 60k 输出令牌，实用流量使用 320k 和 24k，并采用Kunavo 目录中的每百万令牌实时费率。
| 实用角色中的模型 | 每 1M 个令牌的输入 / 输出 | 一天的实用流量 |
|---|---|---|
| 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。不过要注意能力下限：安装指南警告，实用模型必须“strong enough to extract and consolidate memory reliably”，而非常小的模型（约 4B）通常无法可靠地提取上下文。指南将其描述为任务失败，而不是错误，因此这是“模型报错”这一诊断不正确的分支。
Agent Zero 本身无需支付许可费用——其 main 中的 LICENSE 是 MIT 文本，版权归属为 "Agent Zero, s.r.o"——因此费用来自你配置的各角色所使用的模型令牌。Kunavo 的目录金额是计费下限，而不是上限：上游报告费用时，账单金额取目录成本与上游成本乘以适用加价之间的较大值。最低充值金额为预付信用额度 $10。请参阅 billing details。
应放在角色背后的路由
| 方式 | 适用场景 | 在此故障模式下对你的成本 |
|---|---|---|
| 直接调用提供商 API | 全天使用一个供应商，并遵循该供应商自己的缓存和批处理条件 | 每个 provider 都有自己的入口和前缀，因此第二个供应商意味着又有一套名称需要正确配置 |
| 命名网关（OpenRouter） | 你按任务切换模型，并希望 Agent Zero 原生路由 | 仅对聊天原生支持——嵌入入口改为通过 openai 路由，并使用显式 base URL |
通过 other 的 OpenAI 兼容网关 | 在 Agent Zero 没有对应入口的端点上使用一个 key 和一个余额 | 没有可用于自动补全的模型列表，没有默认 base URL；如果自身名称未设置，key 会退回到 OpenAI 名称 |
| 通过 OAuth 插件登录账户 | 你已经为它连接的账户付费——Codex plan、GitHub Copilot——并且不想粘贴 key | 其 README 表示这些连接完全不需要你提供 API key——它们连接的是账户，而不是你的端点；其 Google Cloud Gemini 入口则说明按 Gemini API 计费，而不是从订阅中扣费 |
| 本地模型服务器 | 小规模或私密工作，无按请求收费 | 适用 Docker 地址规则，而实用角色的能力下限在这里影响最明显 |
按角色预算请参阅 Agent Zero API costs；关于第三个角色，请参阅 changing the embedding model；关于 base URL 和前缀的一般约定，请参阅 OpenAI-compatible API。要将 Kunavo key 接入 other：先从 the error reference 开始，然后 create an account。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 key 不正确？
通常不是，状态码可以区分它们。在 Agent Zero 固定使用的 litellm 1.88.1 wheel 中，认证故障是 401 的 AuthenticationError，而两个 provider 解析故障是 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 时重试带状态码的错误——因此两类错误都会在第一次尝试时直接呈现，任何一类都不能证明另一类的情况。更换 key 之前，先检查模型字符串和 base 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 不提供嵌入模型，因此该位置应使用本地默认模型，或使用销售此步骤的 provider。
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 字段中输入 provider 前缀吗？
不应该，Agent Zero 自己的文档也说明了你要填写的字段：其 FAQ 表示，openai/gpt-5.3 对 OpenRouter 是正确的，但对原生 OpenAI provider 不正确，后者“which goes without prefix”；安装指南的命名表则将 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 的行为于 2026 年 9 月 21 日根据 agent0ai/agent-zero main 分支——models.py 和 conf/model_providers.yaml——以及其文档、发布版本和 issues 读取；LiteLLM 异常类和错误字符串则是在 PyPI 中的 litellm 1.88.1 wheel 内读取的，这是 Agent Zero 固定使用的版本。这里没有任何运行时测试：未运行安装，也未端到端复现错误。Kunavo 令牌费率来自实时目录，所有美元数字均为说明性的令牌算术。