腾讯混元接入第三方工具后模型不显示，主因是API配置错误或模型ID未手动添加；需核对API地址与密钥格式，手动填入有效模型ID，并验证连接、清除缓存、硬刷新页面。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
腾讯混元接入第三方工具（如 Chatbox、CherryStudio、OpenWebUI）后，界面中不显示混元模型、下拉菜单为空或仅显示“未加载模型”，说明 API 配置虽完成但模型注册未生效，常见于模型 ID 填写错误、服务端未响应或客户端缓存未刷新。
确认 API 密钥与基础地址是否匹配
打开工具的模型设置页，核对两项关键参数：API 地址必须为 https://api.hunyuan.cloud.tencent.com/v1/（结尾带斜杠），不是控制台首页地址，也不是 TokenHub 页面链接；API 密钥必须是 TokenHub 中创建的 Key（格式为 hunyuan_ 开头的 32 位字符串），不是腾讯云 CAM 的 SecretId/SecretKey。
若填错任意一项，工具会静默失败——既不报错也不加载模型列表，这是最隐蔽的卡点。
手动添加混元模型 ID（关键步骤）
多数客户端默认只预置少量模型名，不会自动拉取混元全量模型列表。你必须手动添加具体模型 ID：
方法一：在 CherryStudio 或 OpenWebUI 的「添加模型」表单中，填写以下任一有效模型 ID（区分大小写，不可拼错）：
hunyuan-turbos-latest
hunyuan-pro
hunyuan-functioncall
hunyuan-a13b
hunyuan-embedding
方法二：Chatbox 用户需在「自定义提供方」设置页点击「高级设置」→勾选「启用模型发现」→保存后重启客户端，再进入对话页刷新模型下拉框。
注意：hunyuan-turbos-vision、hunyuan-t1-vision 等视觉类模型仅支持图像生成接口（/v1/images/generations），不能用于 chat/completions 对话，填入后也不会出现在对话模型列表中。
验证连接并强制刷新模型缓存
第一步：在设置页点击「检查连接」或「Test Connection」按钮，确认返回状态码为 200 且提示「Connection successful」；
第二步：关闭客户端 → 删除本地缓存目录（Chatbox 缓存在 %APPDATA%\Chatbox\models；CherryStudio 在 ~/.cherrystudio/cache；OpenWebUI 在 /app/backend/data/cache）→ 重新启动；
第三步：进入新对话页，长按 Ctrl + F5（Windows）或 Cmd + Shift + R（macOS）硬刷新页面，避免浏览器缓存旧模型列表。
这一步操作起来很简单，直接把文件拖进去就行。
