人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载本指南针对 PicoClaw 启动或调用模型时最常见的两类报错 ——Error creating provider: model openrouter/free not found in model_list与 OpenRouter 返回的free is not a valid model ID—— 从症状、根因到配置修复给出完整排查路径并深入到model_list的 provider/model 两步解析原理与底层源码实现。读完本文你将能够正确配置agents.defaults.model_name与model_list条目彻底避开 OpenRouter 免费层路由的经典配置陷阱并掌握排查同类 模型未找到 错误的方法。症状你会看到以下错误之一在 PicoClaw 中配置 OpenRouter 免费模型时通常会在启动 Agent 或发送首条消息时遇到以下两类报错Error creating provider: model openrouter/free not found in model_listOpenRouter 返回 HTTP 400free is not a valid model ID第一类错误来自 PicoClaw 本地解析阶段第二类错误来自 OpenRouter 服务端的拒绝响应。两者往往是同一个配置问题在不同阶段的表现形式model_list中的model字段被直接当作请求参数发送给上游 API而它并不是一个 OpenRouter 认可的有效模型路由 ID。根因PicoClaw 的 provider/model 两步解析规则要理解这个报错必须先理解 PicoClaw 解析 provider 与 model 的两步规则该规则同样记录在 provider 解析文档 中如果配置中显式设置了provider字段则model字段会被原样发送给该 provider不做任何改写。如果省略了provider字段PicoClaw 会把model中第一个/之前的内容当作 provider把第一个/之后的内容当作最终发送给上游的运行时模型 ID。针对 OpenRouter 免费层路由官方文档见 troubleshooting.md 与 SKILL.md 中的 OpenRouterfree is not a valid model ID 一节给出的结论非常明确推荐显式设置provider。逐条对比配置写法解析结果结论model: free未选中任何 providerfree被当作裸模型名错误free不是可直接路由的 OpenRouter 模型配置且默认会被归到openai协议下provider: openrouter, model: freeprovider 为openrouterOpenRouter 收到free正确显式指定 providerfree触发 OpenRouter 自动免费层路由model: openrouter/freeprovider 解析为openrouter运行时模型 ID 解析为free也兼容利用斜杠前缀的隐式解析注意仓库中另一份多语言版本的文档如 troubleshooting.pt-br.md在示例中使用了model: openrouter/free这种隐式写法而最新版英文文档 troubleshooting.md 则推荐显式provider: openrouter, model: free。两者都能工作但显式provider是更稳妥、可读性更高的推荐写法——它不依赖斜杠切分逻辑也避免误判含多个斜杠的模型 ID。修复步骤正确配置 model_list在~/.picoclaw/config.json或你通过配置路径参数指定的其他配置文件中按以下两步修改agents.defaults.model_name必须匹配model_list中某个条目的model_name。例如默认模型名设为openrouter-free就必须能在model_list中找到一个model_name同为openrouter-free的条目否则启动时会直接报model xxx not found in model_list or providers参见 GetModelConfig 的错误分支。该条目的model字段必须是 OpenRouter 认可的有效模型 ID。推荐同时显式设置provider为openrouter。可选的有效模型 ID 示例free—— OpenRouter 自动免费层路由google/gemini-2.0-flash-exp:freemeta-llama/llama-3.1-8b-instruct:free以最新版推荐写法显式 provider为例一个最小可用的配置片段如下{ agents: { defaults: { model_name: openrouter-free } }, model_list: [ { model_name: openrouter-free, provider: openrouter, model: free, api_keys: [sk-or-v1-YOUR_OPENROUTER_KEY], api_base: https://openrouter.ai/api/v1 } ] }如果你的配置沿用了隐式写法也可以写成model: openrouter/free并在model_list中保留同样的model_name别名效果等价{ model_name: openrouter-free, model: openrouter/free, api_keys: [sk-or-v1-YOUR_OPENROUTER_KEY], api_base: https://openrouter.ai/api/v1 }两种写法共同的关键点在于agents.defaults.model_name引用的是model_list条目的别名model_name字段而model字段才是真正发送给上游 API 的模型标识。OpenRouter 的 API Key 需要在 OpenRouter Keys 中的配置示例。源码级原理provider/model 是如何被解析的ExtractProtocol两步解析的核心实现PicoClaw 在创建 provider 时会调用ExtractProtocol来解出协议provider与运行时模型 ID两个值。该函数的完整注释与实现位于 pkg/providers/factory_provider.gofunc ExtractProtocol(cfg *config.ModelConfig) (protocol, modelID string) { if cfg nil { return , } model : strings.TrimSpace(cfg.Model) if provider : strings.TrimSpace(cfg.Provider); provider ! { return NormalizeProvider(provider), model } return SplitModelProviderAndID(model, openai) }其行为与文档描述的规则完全一致Provider字段优先当Provider为空时回退到从Model推断且裸模型名不含/默认归入openai协议。这也解释了为什么只写model: free时free会被当作普通 OpenAI 兼容模型的 ID 发送——它根本不会命中 OpenRouter 的任何免费路由。函数注释中还给出了几个典型解析示例Model openai/gpt-4o→(openai, gpt-4o)Model nvidia/z-ai/glm-5.1→(nvidia, z-ai/glm-5.1)只有第一个/之前是 provider其余保留Provider nvidia, Model z-ai/glm-5.1→(nvidia, z-ai/glm-5.1)Model gpt-4o→(openai, gpt-4o)SplitModelProviderAndID斜杠切分与未知前缀兜底当provider缺省时实际执行切分的是 pkg/providers/provider_catalog.go 中的SplitModelProviderAndID。它的一个关键细节是只有第一个/段落在受支持的 provider 名单IsSupportedModelProvider中时才被当作 provider 剥离否则整个字符串都视为模型 ID并回退到默认 provider。这意味着像openrouter/free这样以已知协议名开头的写法可以正确解析而一个既无显式 provider 又不以受支持协议名开头的裸 ID 则会落入默认的openai协议——这正是model: free场景的失败路径。GetModelConfigmodel_name 别名查找与轮询解析的入口是 pkg/config/config.go 中的GetModelConfig它以agents.defaults.model_name传入的别名在model_list中查找匹配项找不到时返回model xxx not found in model_list or providers如果存在多个同名条目还会通过rrCounter做轮询以实现负载均衡。完整的模型条目字段定义model_name、provider、model、api_keys、api_base等见 ModelConfig 结构体其中model_name被明确注释为 User-facing alias for the model面向用户的别名而model是 optionally provider-prefixed可选带 provider 前缀的模型标识。排查同类错误的扩展清单除了 OpenRouter 免费层问题model ... not found in model_list还可能有其他成因仓库的 SKILL.md 与 model-list 迁移文档 给出了通用排查清单别名是否匹配agents.defaults.model_name与model_list条目的model_name是否完全一致区分大小写。条目是否启用model_list中目标条目的enabled是否为true。若省略该字段加载时会按规则推断——具有 API key 或使用保留名local-model的条目会被自动启用见 ModelConfig 注释。provider/model 写法是否符合规则优先使用显式provider加原生模型 ID 的写法使用provider/model兼容写法时/前的段落必须是受支持的 provider 名。迁移兼容性如果是从旧版providers配置迁移而来旧配置会自动迁移到model_list同时api_key与api_keys会被合并若出现unknown provider xxx in model xxx/model-name报错说明协议名不受支持应改用受支持的provider值。总结free is not a valid model ID与model ... not found in model_list本质上是同一个配置误区把 OpenRouter 的免费层快捷路由free当成了普通模型名直接写在model字段里却没有正确声明 provider。修复的关键只有两点——在model_list条目中显式设置provider: openrouter并确保agents.defaults.model_name与条目的model_name别名一一对应。理解了ExtractProtocol的两步解析逻辑后这类模型路由问题基本可以做到一次定位、立即修复。如需进一步了解 PicoClaw 的完整调试流程可参阅 debug 指南若要理解其他模型路由与回退机制可阅读 providers 参考文档。赞分享人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载相关推荐PicoClaw 排障指南修复 model not found in model_list 与 OpenRouter free is not a valid model IDPicoClaw 排障指南修复 model not found in model_list 与 OpenRouter free is not a val人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆Flipper Zero 车库门 Sub-GHz 破解完整教程从信号捕获到 12 位暴力破解Flipper Zero 车库门 Sub GHz 破解完整教程从信号捕获到 12 位暴力破解 这个 Flipper Zero 资源仓库收录了大量 Sub GH人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆Paperless-ngx 在 Kubernetes 上 granian 报 is not a valid port number 怎么修复Paperless ngx 在 Kubernetes 上 granian 报 is not a valid port number 怎么修复 在 Kuberne后端前端全文检索OCR知识管理上一篇Cua Driver Computer History跨平台加密操作历史的架构设计与预览实现下一篇从卡顿到丝滑xyflow性能监控工具实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考