模型id必须与腾讯官方标识完全一致，如hunyuan-pro不能写成hunyuan_pro或hunyuanpro；不同平台支持范围不同：cherrystudio默认仅预置hunyuan-pro，openwebui依赖后端路由启用，workbuddy需在mcp server中显式注册。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
检查模型 ID 是否拼写正确
在 CherryStudio、OpenWebUI 或 WorkBuddy 等客户端中填写模型 ID 时，必须与腾讯官方公布的模型标识完全一致，包括大小写和连字符。例如 【hunyuan-pro】 不能写成 hunyuan_pro 或 HunyuanPro。
常见有效模型 ID（截至 2026 年 9 月）：hunyuan-pro、hunyuan-a13b、hunyuan-role-latest、hunyuan-functioncall、tencent/hy3-preview（仅限 OpenRouter）、hunyuan-turbos-vision。
确认所用平台是否支持该模型
不同平台对混元模型的支持范围不同：
CherryStudio 默认只预置 hunyuan-pro，其他模型需手动添加；OpenWebUI 依赖后端 API 兼容性，若后端未启用 hunyuan-a13b 的路由，则前端切换也会失败；WorkBuddy 通过 MCP Server 调用，必须在脚本中显式注册对应模型 ID 才能识别。
若你在 OpenWebUI 中看到“模型不存在”，但 API 地址和密钥测试成功，说明问题出在后端服务未加载该模型——此时需检查你部署的 Ollama / FastAPI / MCP Server 是否已拉取并运行了对应模型镜像或配置了转发规则。
验证 TokenHub 或 CAM 密钥权限范围
方法一：TokenHub API Key 方式（推荐用于 OpenAI 兼容接口）
登录 TokenHub 控制台 → API Key 管理 → 查看对应 Key 的「访问范围」是否勾选了目标模型。例如调用 hunyuan-functioncall 却只勾选了 hunyuan-pro，则会返回模型不可用错误。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
方法二：CAM SecretId/SecretKey 方式（SDK 原生调用）
进入腾讯云 CAM 控制台 → 权限策略 → 检查绑定策略是否包含 hunyuan:ChatCompletions 权限，且 Resource 字段允许访问具体模型名，如 "arn:qcloud:hunyuan:ap-guangzhou:uin/123456789:models/hunyuan-a13b"。
【注意：TokenHub Key 和 CAM 密钥不可混用，前者用于 OpenAI 兼容地址，后者用于原生腾讯云 API 地址】
刷新模型列表缓存
第一步：在 CherryStudio 中，点击设置 → 模型服务 → 腾讯混元 → 点击「检查」按钮右侧的「刷新模型列表」小图标（↻）。
第二步：若使用 OpenWebUI，关闭浏览器标签页，清空 localStorage（开发者工具 → Application → Clear storage → Check Local Storage → Clear），再重新打开设置页面重载外部链接。
第三步：WorkBuddy 用户需重启 MCP Server 进程，并确认终端日志中出现类似 "Registered tool: hunyuan_chat with model=hunyuan-pro" 的提示行，否则模型注册未生效。
