OpenClaw配置本地模型提示模型不存在怎么办？

配置OpenClaw时遇到“model not found”或者“Invalid model name”的提示？别慌，这通常不是网络问题，也不是密钥失效，而是模型名与本地注册路径、实际文件结构或OpenClaw运行时解析逻辑不匹配导致的。先说一个核心判断：这类报错本质上就是程序没认出来你写的那个名字。

确认模型名是否被OpenClaw支持

先跑一遍 openclaw --list-models，看看当前版本内置支持的全部模型名列表。这一步必须做，因为OpenClaw不会自动加载任意字符串作为模型名——它只认白名单中的标识。

接下来，检查你配置中写的模型名，比如 claude-3-opus，是否完全一致出现在上一步输出里。注意大小写、连字符、日期后缀（例如 -2024-05-21）缺一不可。OpenClaw对模型名是严格字符串匹配，

如果该模型名不在列表中，说明它已被弃用或尚未集成进你当前安装的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 文件的目录会被忽略。

排查模型名与路由别名混淆

打开你的 .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。这是最隐蔽的坑之一。