API Key 与连接问题

在哪里配置 API Key？

1. 打开「设置」（左下角齿轮图标）
2. 进入「算力服务」页面
3. 在供应商列表中找到对应的 Provider（如 OpenAI、Anthropic 等）
4. 点击配置，输入你的 API Key

或者通过资源管理器的「算力」入口进入 AI 服务管理页面。

提示"API Key 无效"？

1. 检查 Key 是否完整 --- 确保复制 API Key 时没有遗漏开头或结尾的字符
2. 检查 Key 是否过期 --- 部分供应商的 Key 有有效期，前往供应商官网确认
3. 检查账户余额 --- 如果供应商账户余额不足，Key 可能会被暂停使用
4. 确认 Key 权限 --- 确保 Key 有调用对应模型的权限

连接超时怎么办？

如果请求模型 API 时频繁超时：

1. 检查网络连接 --- 确保你能正常访问对应供应商的网站
2. 检查代理设置 --- 如果你使用代理，确保代理配置正确且允许访问 API 端点
3. 尝试更换端点 --- 部分供应商有多个 API 端点（如 OpenAI 的不同区域），可以在 Provider 配置中修改
4. 减少请求频率 --- 如果短时间内发送大量请求，可能触发供应商的速率限制

如何理解聊天区的网络提示？

较新的 DesireCore 会分别判断本地 Agent Service、设备网络和模型供应商是否可达，而不是只看系统是否连接了 Wi-Fi：

提示	含义	建议
网络不可达，正在等待网络恢复	公网、DNS、代理或路由当前不可用	先检查 DNS、代理、VPN 和系统网络；原任务会暂停等待，恢复后自动继续，不要反复重发
模型服务商暂时不可达，正在自动重试	仅当前 Provider 异常，其他网络可能正常	等待自动重试，或切换到另一个可用 Provider
网络异常，正在确认任务状态	网络刚刚波动，系统正在与后端核对原任务是否仍在运行	等待状态确认，避免重复创建同一任务
本地服务连接中	桌面端正在连接本机 Agent Service，与公网是否可用无关	如果长时间不恢复，重启 DesireCore 并检查本地安全软件是否拦截

网络恢复后，DesireCore 会先核对原会话状态，再决定继续等待或恢复重试。只有界面明确显示任务已失败时，才需要手动重新发送。

某个模型显示"不可用"？

模型不可用的常见原因：

原因	解决方法
Provider 未启用	在算力服务页面启用对应的 Provider
Provider 已删除	重新添加该 Provider 并配置 API Key
模型已下线	供应商可能已停用该模型，选择其他替代模型
API Key 无权限	确认你的 Key 有访问该模型的权限

如何添加自定义 Provider？

DesireCore 支持兼容 OpenAI API 格式的自定义 Provider（如本地部署的 Ollama）：

1. 在算力服务页面点击添加供应商
2. 选择「自定义（OpenAI 兼容）」
3. 填写 API 端点地址（如 http://localhost:11434/v1）
4. 配置认证信息（如有需要）

本地模型

如果你在本地运行了 Ollama 或其他兼容 OpenAI API 的模型服务，可以直接添加为自定义 Provider，无需 API Key。

API 调用会产生费用吗？

如果你使用自备 API Key，调用 AI 模型 API 的费用由对应供应商收取；如果使用官方云端算力，会消耗订阅额度或 credit。费用取决于：

• 你选择的模型（不同模型价格不同）
• 消息的长度（按 Token 计费）
• 对话的上下文长度

你可以在模型选择器中查看各模型的参考价格。建议在供应商官网设置用量预算和告警。

多个 Provider 配置了同类模型，使用哪个？

DesireCore 使用以下优先级：

1. 对话中手动选择的模型（最高优先级）
2. 全局默认映射中指定的模型
3. 第一个可用的 Provider 中的默认模型

如何验证 API Key 是否配置成功？

配置 API Key 后，系统会自动进行连通性验证。验证结果会在 Provider 卡片上显示：

• 绿色状态 --- 连接成功
• 红色/橙色状态 --- 连接失败或 Key 无效