PicoClaw 找不到模型 404：模型 ID 和 Anthropic 协议

在 PicoClaw 中，“找不到模型”和 404 是四种不同的故障，只有其中一种发生在你的机器之外。其中三种是本地问题——无法解析的别名、PicoClaw 自己的 Web 后端返回 404，以及未知的协议字符串——第四种是上游 404，其正文会告诉你错误出在路由还是模型 ID。先阅读错误文本，才能避免为了修复拼写错误而更换协议。

此页面假设你已经拥有一个可用的 model_list条目和密钥；配置本身以及 PicoClaw 的费用，详见 PicoClaw 价格与 API 配置。以下内容均读取自已发布的标签 v0.3.1；发布 API 于 2026 年 9 月 21 日确认它是最新版本，发布日期为 2026 年 7 月 3 日。仓库最后一次推送是在 2026 年 9 月 17 日，因此 main领先于该标签——在相关之处会明确说明。2026 年 10 月 1 日，v0.3.1 仍是最新发布版本；随后使用其发行二进制文件针对本地记录端点运行，并使用故意无效的密钥针对 Kunavo 运行；运行结果记录如下。

四种故障，一个短语

因此，首先要确定请求是否离开了你的机器，而字符串本身就能确定这一点。别名不匹配是一个已有记录的案例，而不是假设：PicoClaw issue #958报告了 error creating provider: model "llama3.2" not found in model_list，同时 picoclaw status显示 Ollama 端点可访问，且模型为 llama3.2:latest。该 issue 于 2026 年 3 月 25 日由仓库的过期 issue 机器人关闭。请注意，在此仓库中，被标记为 completed的已关闭 issue 并不意味着已修复——同一个机器人用相同措辞关闭了 #1624。

包装文本会指出实际运行的协议

因为带有 api key 的 anthropic和 anthropic-messages会构建不同的提供商，所以它们的 404 包装方式不同——这使错误字符串成为免费的诊断信息。

为什么 PicoClaw 自己的 404 建议可能会把你引向错误方向

PicoClaw 的 提供商指南告诉你，当“现有的 anthropic 协议返回 404 错误（表示端点不支持 OpenAI 兼容格式）”时，应切换到 anthropic-messages，并补充了能够确定命名的说明：“anthropic 协议使用 OpenAI 兼容格式（/v1/chat/completions），而 anthropic-messages 使用 Anthropic 原生格式（/v1/messages）。”两段引文均于 2026 年 9 月 21 日在 v0.3.1 版本中重新查阅。

该建议对路由 404 正确，对模型 404 错误。同一文件中，在一张表格下方 294 行处，它还与表格的说法相反：表格的 Protocol列在 anthropic行中写着 Anthropic。代码以一种不明显的方式解决了矛盾：anthropic取决于 auth_method，因此是两种协议。使用 oauth或 token时，它会构建原生 Anthropic SDK 提供商，表格是正确的；使用 api key 时，它会落入 openai及其整个家族所使用的同一个 OpenAI 兼容提供商，说明是正确的。

由此直接得到两个后果。对于 openai家族，写入 https://api.kunavo.com而不是 https://api.kunavo.com/v1会拼接出 https://api.kunavo.com/chat/completions——这是由你自己的配置造成的路由 404，也是最常见的一种。在两个 Anthropic 协议中，这种错误不可能发生，因为 /v1无论如何都会被强制设置；但同样的强制意味着，路径必须不以 /v1结尾的网关完全无法通过它们表达，只能改用 openai协议。PicoClaw 自己的文档就使用这一变通方式来连接基础路径以不同版本段结尾的供应商。

有一项说法应视为尚无定论。PicoClaw 议题 #269 中唯一的评论声称，向 /v1/chat/completions 发送 POST 请求会在 Anthropic 处返回 404，因为正确的端点是 /v1/messages。Anthropic 自己的文档与此相矛盾：它提供了一个 OpenAI SDK 兼容层，其中 base_url 为 https://api.anthropic.com/v1/，并将 authorization 标头标记为“完全支持”（于 2026 年 9 月 21 日核查）；同时在同一页面提醒，该兼容层“对于大多数使用场景而言，不被视为长期或可用于生产的解决方案”。议题 #269 于 2026 年 3 月 13 日关闭，没有关闭评论——议题 API 显示其中只有一条评论，即上面的分析，来自一个与仓库没有关联的账户——因此实际是什么解决了问题仍未知。比起这两种说法，应更相信你自己的 404 响应正文。

当 404 针对的是模型 ID 时

PicoClaw 议题 #1624——于 2026 年 3 月 16 日开启、2026 年 3 月 31 日关闭——记录了将带点号的 Claude ID 配置为 "model": "anthropic/claude-sonnet-4.6" 时返回的确切正文：Status: 404，并附有 {"error":{"code":"not_found_error","message":"model: claude-sonnet-4.6 was not found. Did you mean claude-sonnet-4-6?"…。其标题和唯一评论于 2026 年 9 月 21 日从议题 API 重新查阅：评论来自过期议题机器人，因此议题虽已关闭，但没有证据表明问题已修复。

“您是否想输入……”提示就是判断依据。只有解析了请求的端点才会返回这种提示，因此路由已正常工作，更改协议也无济于事。PicoClaw 不会替您修正拼写的原因很具体，而且可以核实：strings.ReplaceAll(model, ".", "-") 在仓库中只出现了一次，位于 pkg/providers/anthropic/provider.go 的第 219 行，也就是 OAuth 和令牌路径使用的 SDK 提供程序。anthropic_messages/provider.go 和 openai_compat/provider.go 均不包含它。这两项结论已于 2026 年 9 月 21 日在 v0.3.1 上重新核查；本页面撰写前的研究也于同一天从 main 重新获取了相同文件，结果一致。2026 年 10 月 1 日运行 v0.3.1 二进制程序，确认了两条 API 密钥路径上的情况：带点号的 ID 原样传到了端点，返回的是端点自身的 404（参见运行 v0.3.1 得到的结果）。OAuth 和令牌路径是唯一包含该重写逻辑的路径，此次未运行该路径。

PicoClaw 自己的文件对拼写也存在分歧：provider_metadata.go为两个 Anthropic 条目列出带连字符的 ID，提供商指南中的 anthropic示例使用带点的 ID，而 anthropic-messages通过 GetDefaultModel返回带点的默认值——这正是 #1624 显示被拒绝的拼写。Anthropic 的 模型概览中打印的每个 Claude API ID 都使用连字符，该页面还将 Claude Sonnet 4.6 和 Claude Opus 4.6 列在“Legacy models (still available)”下——因此，今天在 Anthropic 上 4.6 ID 返回 404 并不是因为已退役。这排除了一个原因，但不是所有原因：不携带该模型的网关仍可能拒绝带连字符的 ID。应从你正在调用的端点复制 ID，而不是从 README 复制。

明确写出两个条目，并保留带连字符的 ID。密钥不属于此文件——PicoClaw 从 ~/.picoclaw/.security.yml读取密钥，详见配置指南。

{
  "agents": {
    "defaults": {
      "model_name": "kunavo-sonnet"
    }
  },
  "model_list": [
    {
      "model_name": "kunavo-sonnet",
      "provider": "openai",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com/v1"
    },
    {
      "model_name": "kunavo-sonnet-native",
      "provider": "anthropic-messages",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com"
    }
  ]
}

第一个条目自行提供 /v1，因为 OpenAI 兼容家族会将 /chat/completions按原样拼接到 api_base上。第二个条目有意省略它，用于展示在 anthropic-messages中两种拼写都会规范化为相同的基础 URL。Kunavo 发布的基础 URL 对于 聊天补全是 https://api.kunavo.com/v1，对于 Messages 路由是 https://api.kunavo.com/v1/messages。两组 URL 算术能够对应起来，是两组文档之间的算术关系——2026 年 10 月 1 日，两个条目都使用 v0.3.1、故意无效的密钥针对 Kunavo 运行：openai条目到达 /v1/chat/completions，anthropic-messages条目到达 /v1/messages，两者都收到 Kunavo 的 401 响应。这证明了 URL，而不是一次已完成的请求：本文没有任何内容声称集成经过测试。关于基础 URL 问题的一般形式，请参阅Anthropic 基础 URL 文档。

网关也可能有意返回 404，这不是 PicoClaw 的错误。Kunavo 会对暂时暂停的模型返回 404，正文会命名该模型以及应改用的替代模型，并会从 /v1/models中省略暂停的模型；应匹配该消息的结构，而不是匹配某个具体名称，因为暂停的模型会发生变化。Kunavo 也不提供 embedding、text-to-speech 或 speech-to-text 模型，因此，命名其中任何一种模型的 model_list条目无论选择哪种协议都会返回 404——应将这些条目指向其他提供商，并在 Kunavo 密钥上只保留聊天条目。

运行 v0.3.1 的结果

2026 年 10 月 1 日，我们在一次性容器中运行了 v0.3.1 发布二进制文件，并使用发布版本自带的校验和文件验证了其校验和；每次只使用一个 model_list 条目，并使用了 picoclaw agent -m。端点是一个本地录制服务器，其行为当时与 Kunavo 的路由一致——/v1/* 是 API，其他路径均返回 HTML 404 页面（Kunavo 现在会对这些路径返回包含修复说明的 JSON 404；请参见 Kunavo 行）——并且它了解 claude-sonnet-5 和 claude-sonnet-4-6，但不了解带点的 ID；最后三行使用了真实的 api.kunavo.com，但密钥被刻意设为无效，因此这些请求均未产生计费。

本次运行确定了两件仅凭源代码阅读只能推测的事情。错误包装确实会写明实际运行的 provider，因此可以放心根据它判断协议；带点的 ID 会在两条 API 密钥路径中原样发送，因此，引用带点 ID 的“找不到模型”错误，应通过重新拼写 ID 来修复，而不是切换协议。本次未覆盖：OAuth 和 token 路径、启动器的 Web UI、流式传输，以及任何通过 Kunavo 完成的请求——Kunavo 行特意使用了无效密钥。

最简检查顺序

1. 是否有任何内容离开了机器？ 如果终端错误包含 not found in model_list 且没有 HTTP 状态码，则问题发生在本地。将 agents.defaults.model_name 设置为与某个 model_name 条目相同，然后停止。
2. 它是否来自 localhost？ 在 PicoClaw Web UI 中选择默认模型时，浏览器出现 404，说明的是同一个不匹配问题，只是由 PicoClaw 自己的后端提供。没有涉及任何模型 API。
3. 运行的是哪个 provider？ 将包装文本与上表进行匹配。如果包装文本与您认为配置的协议不匹配，则 provider 字段或模型前缀并不是您以为的值。
4. 是路由 404 还是模型 404？ 如果正文写明了您的模型——尤其带有 您是否想指提示——则是模型 404：修正 ID。如果是 HTML 页面、空正文或一般性的 not-found，则是路由 404：在执行其他操作前，根据表格重新推导拼接后的 URL。
5. 询问端点提供哪些服务。 PicoClaw 无法对任一 Anthropic 协议执行此操作，因为两个目录条目都未设置 fetch 标志。使用 curl 请求网关自身的 /v1/models，或暂时让同一个网关指向 openai 协议。跨 provider 的模型未找到介绍了该方法，而 Anthropic 404 模型未找到介绍了 ID 本身有问题的情况。
6. 现在才切换协议，并且仅当第 4 步表明是路由 404 时才切换。如果阻碍因素是身份验证标头而不是线格式，身份验证令牌与 API 密钥会解释其中差异。
7. 使用一轮工具调用重新验证，而不是发送普通聊天轮次。 一个能够回答简单消息的配置，仍可能在第一次工具调用时失败，因此用于确认修复结果的有界任务应包含一次工具调用。

协议选择的成本

最大的成本影响是提示缓存，而且这是结构性因素，而不是设置项。在 PicoClaw v0.3.1 中，唯一会发出缓存断点的代码位于 pkg/providers/anthropic/provider.go，并且只有 OAuth 和 token 路径会到达这里。使用 API 密钥时——即普通的自带密钥场景——两个 Anthropic 协议都不会发送 cache_control。对于 Anthropic 自己的兼容层，这一影响会进一步叠加，因为其文档明确写道：“不支持提示缓存，但 Anthropic SDK 支持。”对于会为 OpenAI 格式调用方插入断点的网关，节省的成本会在网关处恢复；Kunavo 的 缓存文档说明了这一点，并精确限定为：通过 /v1/chat/completions 或 /v1/responses 访问的 Claude 模型。同一页面说明，cache_control 在原生 Messages 路由上会原样透传——因此 anthropic-messages 条目两边都不会获得断点，下面第二列仅描述 openai 协议条目。未检查其他网关是否会插入断点，这些情况也都不是从 PicoClaw 内部观察到的。

这里的数值是说明性的令牌算术，不是经过测量的任务成本，也不是账单上限。假设一次 agent 轮次包含 10 个工具轮次，每轮都会重新发送相同的 20,000 个令牌前缀（系统提示、工具 schema、截至目前的对话记录），新增 1,000 个输入令牌，并返回 600 个输出令牌。这些比例仅为说明而作的假设。第一列按完整费率为每一轮的输入计费；第二列从第二轮开始按缓存读取费率为重复前缀计费。费率是实时的 Kunavo 目录每百万令牌价格。

在这些假设下，Claude Sonnet 4.6 会从 $0.504 降至 $0.164，而完成的工作相同。请将第二列视为乐观估计：缓存写入按其自身费率计费，且两个方向都未建模；如果前缀每轮都发生变化，则完全不会成为缓存命中。在将其视为预算之前，请按每天的轮次数进行缩放。

同时请将两笔账单分开。PicoClaw 本身免费——该仓库采用 MIT 许可证，任何协议（包括两个 Anthropic 协议）都不需要购买任何东西才能使用。持续产生的成本是按您 provider 的费率计算的模型令牌费用。Kunavo 的目录金额是计费下限而非上限：上游报告费用后，账单取目录成本与上游成本乘以适用加价两者中的较高值。最低充值金额为预付余额 $10，这是资金最低要求，而不是任务费用或订阅费——请参见 计费详情。

直接供应商、网关、订阅或本地

要选择的是运行时而不是路由？PicoClaw 与 OpenClaw从部署形态上比较了两者。如果您最终选择网关并希望为密钥充值，请创建 Kunavo 账户，然后发送一个包含工具调用的有界任务，并查看您的账户实际记录的费用。

常见问题

于 2026 年 9 月 21 日核查。本任务中已在 v0.3.1 标签下重新验证：提供商指南中的协议说明和 Anthropic 供应商行、factory_provider.go 中的 anthropic 分支和默认分支、NormalizeBaseURL、anthropic-messages 的 URL、标头和 404 字符串、openai_compat 的 URL 拼接和 Bearer 标头、三个 HTTP 请求发出前的“not found in model_list”字符串、Web 后端的 404、点号替换为连字符的唯一一处代码、提供商选项表的 SupportsFetch 列，以及 docs/operations/troubleshooting.md 中的 OpenRouter 示例；此外还核查了发布版本 API（v0.3.1，于 2026 年 7 月 3 日发布）以及议题 #1624、#958 和 #269 的标题、状态、日期和评论。Anthropic 的 OpenAI-SDK 兼容性页面也于当天查阅。于 2026 年 10 月 1 日运行：在容器中使用 v0.3.1 发布二进制程序访问本地请求记录端点，并使用无效密钥访问 Kunavo——覆盖上表中的每一行。未验证：main 上除研究中进行差异比较的文件之外的任何内容、是什么导致议题 #269 关闭、OAuth 和令牌路径，以及任何通过 Kunavo 完成的请求。Kunavo 的令牌费率来自实时目录，此处每个美元金额均为用于说明的令牌费用计算。