问题排查
33-AI 能力接入 · 2026-10-12 · 2.5 KB
接入类问题九成是三类：Key 没配上、地址/占位符没填全、清单有缓存 ⇒ 按现象查最快。
本专题手工维护（2026-10-12 建）；⚠ 报错文案以应用当前版本为准（本页快照 2026-10-12）。
一、先按这个顺序查（三步定因）
① 看「API Key 管理」：那家**填了 Key 吗**？（留空并失焦 = 会删掉 ✓）
② 看「AI 咨询服务商」：选了吗？（不选 = 走默认那家 ✓）
③ 关掉助手面板再打开：清单有缓存，重开才刷新 ✓
二、按现象查（对照表）
| 现象 | 多半原因 | 处置 |
|---|---|---|
| 模型下拉空 / 显示「（暂未接入，请到设置配置 API Key）」 | 一个 Key 都没配 | 按 §二 路径 A 或 B 配一个 ✓ |
| 配了但某家模型没出现 | ① 清单缓存（约 10 分钟）② 每家最多列 8 个 ③ 该模型非对话被过滤 | 重开面板；要看全 ⇒ 用服务商控制台 ✓ |
| 积分通道分组不出现 | 没配 / 配了但没重启 | 填 endpoint＋publishableKey ⇒ 重启应用 ✓ |
| 某个云模板在菜单里消失 | 该模板需要的服务商没配 Key（缺 Key = 直接消失，不是置灰） | 到 API Key 管理 补那家的 Key ✓ |
| 模板管理页出现「缺 API Key」角标 | 同上（角标说明"会自动禁用"） | 补 Key ✓ |
| 音乐模板不可用 | ⚠ 它要的不是 Key，而是 Music3 音乐服务地址 | 设置 → 远程 ComfyUI → 填该地址 ✓ |
| 报"占位符未配置 / 含未替换的占位符" | 服务商地址里有 ${WORKSPACE_ID} 之类没填 | 填对应项（百炼 ⇒ WorkspaceId 输入框）✓ |
| 助手能聊但不能调工具 / 工具调用被写成文本 | 会话上下文过长（带工具定义就超上限） | 开新会话，或先把上下文压缩 ✓ |
| 额度不足 / 被限流 | 积分用完或触发限流 | 换模型或等一会；查看积分余额 ✓ |
| 鉴权失败 | 云服务配置变了 / Key 被禁用 | 重新核对 Key / 重新开通云服务 ✓ |
| 参数不匹配 | 模型 id 无效或该模型不支持该调用 | 换模型 ✓ |
| "服务暂不可用" | 上游网关/模型临时故障 | 重试或换模型 ✓ |
| 明明保存了，重启后又空了 | 可能改的不是同一份配置（多份设置文件 / 换过数据目录） | 确认你在当前应用的设置里操作 ✓ |
三、报错原文速查（照应用原话）
| 你会看到 | 意思 |
|---|---|
未配置任何 API Key（设置→API Key 管理）。 | 一个都没配 ✓ |
未配置可用大模型 API Key（设置→API 服务商）。 ➕ 也可在模型下拉选择「WorkBuddy 积分通道」的模型（免 Key）。 | 没有可用对话模型（含"可走积分通道"的提示）✓ |
未配置 xxx 的 API Key 或地址（设置→API 服务商）。 | 指定的那家缺 Key 或地址 ✓ |
服务商 xxx 的 API 地址包含 ${WORKSPACE_ID} 占位符，但未配置 WorkspaceId… | 百炼没填 WorkspaceId ✓ |
服务商 xxx 的 API 地址包含未替换的占位符…请到「设置 → API Key 管理」补全 | 自建/自定义地址里占位符没填 ✓ |
WorkBuddy 积分通道未配置：请在应用数据目录的 settings.json 顶层 workbuddy 段填写 endpoint 与 publishableKey…保存后重启应用… | 积分通道没配（或没重启）✓ |
WorkBuddy 积分额度不足或触发限流（…）…查看积分余额。 | 积分/限流问题 ✓ |
WorkBuddy 云服务鉴权失败（…）…请重新开通云服务或检查应用配置。 | 云服务配置失效 ✓ |
这一轮的工具通道不可用（多半是会话上下文过长…）…请开一个新会话再让它做同一件事。 | 上下文太长 ⇒ 工具调用没执行 ✓ |
请先在「设置 → API 服务商 Key」为 APIMart 配置 API Key，再选择模型 | APIMart 系节点缺 Key ✓ |
⚠ 其余错误（超时、网络不通、上游 4xx/5xx 原文）多数会原样透出 ⇒ 排查时把它一起记下来 ✓
四、要报障时，把这四样一起给
① 你配了哪几家（服务商名 + 是否填了 WorkspaceId / 自定义地址）✓
② 当时在做什么（发消息 / 选模板 / 跑任务）+ 面板上的原话截图 ✓
③ 模型下拉里**有没有**模型、选的是哪个 ✓
④ 报错原文（最好含 requestId / 状态码；⛔ **别贴出 Key 本身**）✓
⚠ 一条安全提示：贴日志/截图前遮掉 Key（以及 settings.json 别整份外发）✓
五、不在这张表里的问题
| 现象 | 去看 |
|---|---|
| 助手用法、会话、只读/全能力、写画布被拒 | 《AI 助手》卷的《问题排查》✓ |
| ComfyUI 连不上、引擎自检、云实例地址 | 《ComfyUI 本地部署》《云算力接入》✓ |
| 外部客户端（MCP）连不上本应用 | 《MCP 指南》卷 ✓ |
来源：E:/workbuddyProj/unlimitCanvas/ai_manual/ai_access/04-问题排查.md