故障排查
测试连接失败
请检查设置 > 服务中的以下内容：
- “地址类型”和输入内容匹配。服务根地址用于
https://api.openai.com/v1这类基础地址；完整请求地址用于完整的聊天接口。 - 远程服务使用
https。只有http://localhost、http://127.0.0.1等本地服务可以使用明文 HTTP。 - 访问密钥已保存且仍然有效。
- 模型 ID 是服务商接受的名称。
- 响应等待时间足够长。
- 如果启用了代理，先点击“测试代理”确认代理可用。
打开 SpotAsk 的「服务设置」页。未安装 SpotAsk 时此链接不会有反应，可手动打开：SpotAsk 菜单栏图标 → 设置… → 服务设置，或按 ⌘ + , 打开设置。直接使用链接：spotask://settings/provider
无法发现模型
模型发现要求服务使用服务根地址，并且服务商提供模型列表接口。完整请求地址模式不支持自动发现。
如果刷新失败，先检查服务地址和访问密钥。若服务商没有模型列表接口，请手动添加模型并填写准确的模型 ID。
划词助手没有出现
- 在设置 > 划词助手中启用该功能。
- 按提示允许“跨应用读取权限”，并检查当前状态。
- 如果“触发方式”是“显示快捷操作”，请开启“选中文字后自动显示快捷操作”。
- 检查“自动显示范围”。白名单模式只在所选应用中显示；黑名单模式不会在所选应用中显示。
- 也可以手动按划词快捷键：默认是 ⌥ + ⇧ + Space。
- 空选区、安全输入区域，以及不向 macOS 辅助功能暴露选中文字的应用无法读取。
全局快捷键冲突
如果其他应用占用了同一个全局快捷键，请在设置 > 通用中录制其他快捷键；如果主要通过菜单栏或 URL 打开 SpotAsk，也可以把全局快捷键留空。应用内快捷键和全局快捷键是分开设置的。
提示无法读取已保存的服务设置
设置 > 通用 > 清除所有本地数据会重置异常的本地服务数据。之后需要重新添加服务和密钥。
打开 SpotAsk 的「通用」页。未安装 SpotAsk 时此链接不会有反应，可手动打开：SpotAsk 菜单栏图标 → 设置… → 通用，或按 ⌘ + , 打开设置。直接使用链接：spotask://settings/general
智能路由没有给出推荐
检查设置 > 外部提问 > 智能路由：
- 启用外部提问与启用自动路由都是开的，这次对话的标题栏开关也是开的，并且至少启用了一个外部渠道。
- 所选引擎和地址一致。System One 用 System One 根地址，不是聊天补全接口。TypeSafe 官方是
https://api.typesafe.ai。OpenRouter 是https://openrouter.ai/api。OpenAI Decisions 用https://api.openai.com（SpotAsk 会补/v1/decisions），不要粘贴聊天补全接口。 - 决策模型和该引擎匹配：TypeSafe 官方用
jev-1.13.0，OpenRouter 用typesafe/jev-1.13，OpenAI Decisions 用gpt-6-luna。OpenAI 不提供jev。 - 访问密钥属于同一个引擎。TypeSafe 官方和
api.openai.com没有密钥时不会发请求。自定义 OpenAI 地址可以不填密钥。OpenRouter 会拒绝缺失的密钥，或误填的 TypeSafe 密钥。 - 等待上限要够这次请求用。默认 2 秒，最长 5 秒。超时后会回到手动选择渠道，除非你把超时处理设成了在 SpotAsk 内回答。
- 先用设置里的测试提问。它只显示推荐去向，不会打开外部应用。
消息带有附件，或你已经手动选了渠道，会故意跳过决策模型。
远程决策地址必须使用 HTTPS；明文 HTTP 只支持本机 loopback，不支持局域网服务器。自定义服务的模型不能留空。跨 origin 跳转与 HTTPS 降级会被拦截，请直接填写最终可信接口。
设置页测试会分别说明缺密钥、地址或模型错误、401/403 认证或权限失败、404 接口错误、429 限流、其他 HTTP 状态、网络失败、超时及无效或无法识别的答案。前置条件或配置阻止请求时，不显示判断用时。修正提示中的原因后再测试；SpotAsk 不会自动重试或转发至其他外部渠道。
设置提示无法读取已保存的访问密钥时，不代表密钥不存在。原密钥读取失败会保留此前的密钥选择，不会迁移空值。恢复对本机已保存数据的访问后，重新打开外部提问设置即可再次读取。只有确认旧密钥不存在，或成功保存迁移后的密钥，才会清除旧密钥优先标记。
需要更多信息
设置 > 通用 > 诊断可以本地记录最近的请求和选中内容，然后使用“导出日志”生成可分享的文件。日志中不包含密钥。