OpenClaw提示“model not found”是因模型名未在白名单中、路径结尾含斜杠、缺少model.yaml元数据文件、配置使用了前端别名而非真实ID、缓存未清除或本地模型非GGUF格式所致。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw配置本地模型时提示“model not found”或“Invalid model name”，说明程序无法识别你指定的模型标识，既不是网络连接问题，也不是密钥失效，而是模型名与本地注册路径、实际文件结构或OpenClaw运行时解析逻辑不匹配。
确认模型名是否被OpenClaw支持
第一步：运行openclaw --list-models，查看当前版本内置支持的全部模型名列表。这一步必须做，因为OpenClaw不会自动加载任意字符串作为模型名——它只认白名单中的标识。
第二步：检查你配置中写的模型名（如claude-3-opus）是否完全一致出现在上一步输出里。注意大小写、连字符、日期后缀（如-2024-05-21）缺一不可。OpenClaw对模型名是严格字符串匹配，【大小写错误或漏掉后缀会导致直接报model_not_found】。
第三步：如果该模型名不在列表中，说明它已被弃用或尚未集成进你当前安装的OpenClaw版本。此时不能强行改配置硬上，必须升级OpenClaw到支持该模型的版本，或降级使用列表中存在的等效模型。
验证本地模型路径是否正确注册
OpenClaw支持通过--model-path参数或.openclaw/config.json中的model_path字段指向本地模型目录。但路径本身不等于模型可用——它只是告诉OpenClaw“去哪找”，不代表OpenClaw能读懂里面的内容。
方法一：使用绝对路径并确保结尾无斜杠
例如写成/home/user/models/claude-3-opus-2024-05-21，而不是/home/user/models/claude-3-opus-2024-05-21/。末尾斜杠会导致OpenClaw内部拼接失败，返回model_not_found。
方法二：检查目录内是否存在model.yaml或config.json描述文件
OpenClaw要求每个本地模型目录下必须包含一个合法的模型元数据文件，用于声明模型类型、权重路径、tokenizer位置等。空目录或只有.bin文件的目录会被忽略。
完整的工作区安全套件：检测未授权修改，扫描提示注入模式，自动响应应对措施——快照恢复、技能隔离、Git回滚和自动保护扫描。智能体工作区的完整安装后安全层。
排查模型名与路由别名混淆
第一步：打开你的.openclaw/config.json，找到"model"字段值
第二步：确认该值是模型真实ID（如claude-3-opus-2024-05-21），而不是前端界面显示的别名（如Claude Opus或Opus (Latest)）。OpenClaw不解析别名，只认底层ID。
第三步：如果配置中用了别名，立刻替换成openclaw --list-models输出里的原始ID。这一步操作起来很简单，直接编辑JSON文件保存即可。
第四步：删除~/.openclaw/cache/目录下的所有内容。OpenClaw会缓存模型解析结果，旧缓存可能锁定错误映射，清空后重启命令才会重新加载配置。
检查模型文件完整性与格式兼容性
如果你用的是自托管LLM（如Llama 3、Qwen2），需确认模型格式是否为OpenClaw当前版本支持的类型。截至2026年7月，OpenClaw v0.8.3仅原生支持GGUF格式模型，不支持Safetensors或HuggingFace原生bin/safetensors目录结构。
运行ls -l $MODEL_PATH，确认主权重文件扩展名为.gguf，且文件名中包含明确的模型标识（如qwen2-7b-instruct.Q5_K_M.gguf）。若看到pytorch_model.bin或model.safetensors，说明格式不兼容，必须先用llama.cpp工具转换。
注意：OpenClaw不会主动报“格式不支持”，而是静默跳过该目录，最终表现为model not found。这是最隐蔽的坑之一。
