“Unknown model”或“model not found”错误表明模型ID未被识别，主因是Model ID拼写错误（含大小写、前缀volcengine/缺失、符号误写）、跨项目使用API Key与模型、Endpoint区域或版本不匹配（须用v3路径）、客户端未填完整接口地址或未手动切换至新配置模型。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
调用火山引擎大模型时提示“Unknown model”或“model not found”，说明请求中指定的模型标识符未被服务端识别，常见于Dify、OpenClaw、WorkBuddy等第三方平台接入场景，错误直接阻断模型调用流程。
确认模型ID是否拼写完全正确
从火山引擎控制台「方舟→模型服务→已开通模型」页面右侧复制完整Model ID，例如volcengine/doubao-seed-2-0-pro-260215，不要手动删减volcengine/前缀，也不要把-误写为_或空格。大小写必须与控制台显示完全一致——doubao-seed写成Doubao-Seed即触发404。
这一步操作起来很简单，直接把控制台里带灰底的完整字符串整段复制，粘贴后不要做任何编辑。
注意：【volcengine/前缀不可省略】，部分客户端文档示例会省略该前缀，但火山引擎实际校验强制要求包含。
验证模型是否在当前项目&区域真实部署
登录火山引擎控制台→进入「方舟大模型平台」→点击左上角「账号全部资源」下拉框→确认当前选中的项目空间名称。
在该同一项目空间内，打开两个页面：①「推理接入点」或「模型列表」，查看目标模型状态是否为「已开通」；②「API密钥管理」，核对正在使用的API Key创建时所属项目是否与此一致。
【不同项目间的API Key与Model ID无法互通】。主账号下多个项目共存时，从A项目复制的Key去调B项目的模型，系统不会提示“项目不匹配”，只会返回404或403。
若发现模型未在当前项目开通，立即前往「模型服务→开通模型」页面，搜索并勾选目标模型（如doubao-seed-2-0-pro-260215），点击「开通」按钮完成部署。
检查Endpoint端点是否匹配模型版本与区域
方法一：使用官方最新端点格式
北京区域正确写法为https://ark.cn-beijing.volces.com/api/v3/chat/completions，上海区域为https://ark.cn-shanghai.volces.com/api/v3/chat/completions。区域标识（cn-beijing）必须与模型部署区域严格一致。
方法二：用curl快速验证端点有效性
执行命令：curl -X GET "https://ark.cn-beijing.volces.com/api/v1/models" -H "Authorization: Bearer YOUR_API_KEY"。若返回200及模型数组，说明端点+Key组合有效；若返回404，说明端点路径已升级（如v2变v3）或区域标识错误。
注意：【v2端点已强制停用】，所有请求必须使用v3及以上版本路径。
逐项排查客户端配置中的三层路由
第一步：接口地址层级是否填到末级
以WorkBuddy为例，必须填写完整endpoint：https://ark.cn-beijing.volces.com/api/v3/chat/completions，只填根地址https://ark.cn-beijing.volces.com会导致404。
第二步：模型标识是否与服务商控制台展示的ID完全一致
从「已开通模型」列表中复制ID，不要从文档、社区帖或旧截图中手打——版本号260215漏一位或错一位都会报Unknown model。
第三步：客户端能力声明是否超出模型实际支持范围
WorkBuddy配置中勾选了「工具调用」，但目标模型未开放该能力，部分网关会将请求拦截并伪装成404。此时应先关闭所有非必需能力开关，仅保留基础聊天功能，配通后再逐项开启验证。
最后一步：切换模型生效
在客户端对话界面右下角的模型菜单中，手动选择你刚配置的自定义模型名称。保存配置≠自动切换——不手动选中，所有对话仍默认走原模型。
