常见问题 FAQ
使用过程中最常遇到的问题与解决方案
「AI 模型」设置里的 AI 提供者是什么？和 API Key 有什么关系？
问题描述
打开设置 → AI provider 页面，看到 Claude Code、Codex CLI、Gemini CLI 等选项，不确定这些是做什么的，也不知道该怎么配置。
设置 → AI provider 页面：管理所有 AI 提供者
解答
AI 提供者（AI Provider）是 SpectrAI 对话的"引擎"——你在新建会话时选择哪个 Provider，会话就会使用对应的 AI 来执行指令。
SpectrAI 支持两大类 Provider：
| 类别 | 代表 | 认证方式 | 说明 |
|---|---|---|---|
| CLI 命令行工具 | Claude Code、Codex CLI、Gemini CLI、iFlow、OpenCode | 各自的命令行登录 | 通过调用本地 CLI 通信，不需要在 SpectrAI 里填 API Key |
| OpenAI 兼容 API | 自定义的 API 提供者 | API Base URL + API Key | 通过 HTTP 调用 API，需要填写 API Key 和接口地址 |
重点理解：
- Claude Code 是一个 CLI 命令行工具，它有自己的认证体系（通过
claude login登录），不是通过在 SpectrAI 里填 API Key 来认证的。 - 如果你想用 Claude 对话，需要先在终端中安装并登录 Claude Code CLI，然后确认 SpectrAI 中路径配置正确。
- 如果你有的是 OpenAI 格式的 API Key（比如第三方中转站），应该添加一个自定义 AI 提供者，选择
OpenAI Compatible API适配器类型。
配置 Claude Code（推荐）
- 确保已安装 Claude Code CLI：
npm install -g @anthropic-ai/claude-code - 在终端运行
claude login完成登录 - 打开 SpectrAI → 设置 → AI provider → 找到 Claude Code 卡片
- 点击编辑，确认 Command 为
claude，如路径有问题参见 FAQ #4 - 点击 Test 按钮验证连通性
使用自定义 API Key
- 打开 SpectrAI → 设置 → AI provider
- 点击底部 「添加自定义 AI 提供者」
- Adapter Type 选择
OpenAI Compatible API - 填写 Name、API Base URL、API Key、Default Model
- 保存后即可在新建会话时选择该 Provider
添加自定义 AI 提供者：填入 API Base URL 和 API Key
设置了 API Key，普通对话仍报 "Invalid API key · Please run /login"
问题描述
在 SpectrAI 的设置里配了 API Key，但新建普通对话时 Claude 一直报错：Invalid API key · Please run /login，且这个 API Key 在其他地方测试可以正常调通。
对话中出现 "Invalid API key · Please run /login" 错误
原因
这个错误来自 Claude Code CLI 本身，不是 SpectrAI 的报错。
Claude Code 使用 Anthropic 账户认证（OAuth 登录），不读取 SpectrAI 中配置的 API Key。当你选择 Claude Code 作为 Provider 时，SpectrAI 启动 claude 命令，Claude Code 发现自己没有登录，就会报此错误。
方案 A：登录 Claude Code CLI（推荐）
- 打开终端（Windows: PowerShell / CMD，macOS: Terminal）
- 运行
claude login - 按提示完成浏览器授权
- 登录成功后回到 SpectrAI，重新创建会话即可
方案 B：使用第三方中转 API Key
如果你有的是中转站 / OpenAI 格式的 API Key，它不能用于 Claude Code CLI。你需要：
- 在 SpectrAI → 设置 → AI provider → 添加自定义 AI 提供者
- Adapter Type 选择
OpenAI Compatible API - 填入你的 API Base URL 和 API Key
- 新建会话时选择你刚创建的这个 Provider，而不是 Claude Code
方案 C：通过环境变量注入 API Key
如果你确实有 Anthropic 官方 API Key（以 sk-ant- 开头），也可以通过环境变量注入：
- 打开 SpectrAI → 设置 → AI provider → 编辑 Claude Code
- 在 Environment Overrides 中添加：
保存后重新创建会话即可。
macOS 安装后提示「应用已损坏，无法打开」
问题描述
在 macOS 上下载安装 SpectrAI 后，双击启动时弹出系统提示："SpectrAI" 已损坏，无法打开。
macOS Gatekeeper 阻止未签名应用运行
原因
这是 macOS 的 Gatekeeper 安全机制导致的，不是应用真的损坏了。由于 SpectrAI 目前没有 Apple 开发者签名，macOS 会阻止未签名的应用运行。
解决方案
打开终端（Terminal.app），依次执行以下两步：
第一步：开启「任何来源」选项
执行后输入 Mac 登录密码（输入时不会显示字符，正常输入后按回车）。
执行成功后，打开 系统设置 → 隐私与安全性，可以看到「安全性」下方已勾选 「任何来源」：
系统设置 → 隐私与安全性 → 允许「任何来源」的应用
第二步：移除隔离属性
执行完毕后，双击 SpectrAI 即可正常打开。
spctl --master-disable 会降低系统安全等级（允许运行任何来源的应用）。如果你介意，可以在成功打开 SpectrAI 后重新启用：sudo spctl --master-enable完整命令汇总
找不到 Claude 可执行路径 / 自动检测失败
问题描述
在 AI provider 设置中，Claude Code 的路径自动检测失败，导致无法启动 Claude 会话。或者点击 Test 按钮提示找不到 claude 命令。
原因
SpectrAI 默认在系统 PATH 中搜索 claude 命令。如果 Claude Code 安装在非标准路径，或 PATH 未正确配置，自动检测就会失败。
第一步：找到 Claude 的实际路径
在终端中执行：
第二步：在 SpectrAI 中手动配置
- 打开 SpectrAI → 设置 → AI provider
- 找到 Claude Code 卡片，点击编辑（铅笔图标）
- 找到 Executable Path 输入框
- 将找到的完整路径粘贴进去，或点击右侧 📁 按钮手动浏览
- 点击旁边的 Test 按钮验证路径是否正确
- 显示 ✅ 后点击 Save 保存
在 Executable Path 中填入 claude 的完整路径，点击 Test 验证
常见路径参考
| 系统 | 安装方式 | 典型路径 |
|---|---|---|
| Windows | npm -g | C:\Users\<用户名>\AppData\Roaming\npm\claude.cmd |
| Windows | nvm | C:\Users\<用户名>\AppData\Roaming\nvm\<版本号>\claude.cmd |
| macOS | npm -g | /usr/local/bin/claude |
| macOS | Homebrew | /opt/homebrew/bin/claude |
| Linux | npm -g | /usr/local/bin/claude 或 ~/.npm-global/bin/claude |