光谱AI 操作手册

SpectrAI 操作手册 v1.0.4 · 桌面端 · 第 8 章

#概述

SpectrAI 通过 Provider 适配层统一接入不同的 AI 后端，无论是在本地启动 CLI 工具，还是通过 HTTP API 调用云端模型，上层业务逻辑完全无感。每个 Provider 代表一套 AI 接入配置，包含连接方式、鉴权参数和默认模型。本章覆盖所有内置 Provider 的完整接入指南、OpenAI 兼容接口的添加方法，以及上下文摘要、远程控制等场景的 Provider 分配策略，是配置 SpectrAI 最重要的一章。

#核心概念

Provider：SpectrAI 中连接一个 AI 后端的配置单元。每个 Provider 记录接入方式（CLI 命令或 HTTP URL）、API Key、默认模型等信息，可在会话顶部选择器中切换。

内置 Provider：SpectrAI 预设的 Provider，共 12 个：SpectrAI 托管、Claude Code、Codex CLI、Gemini CLI、iFlow CLI、MiMo Code、Grok Build、Kimi Code、Cursor、OpenCode、DevEco Code、GitHub Copilot。内置 Provider 不可删除，但可禁用或修改参数；除 SpectrAI 托管默认启用外，其余内置 Provider 默认禁用，需在使用前启用。

自定义 Provider：用户手动添加的 OpenAI 兼容 API 接入，覆盖 OpenAI、DeepSeek、Kimi、智谱、SiliconFlow、OpenRouter、Ollama 等任意兼容接口。

OpenAI 兼容：遵循 OpenAI Chat Completions 或 Responses API 格式的接口标准，SpectrAI 的 openai-api 适配器可接入任意兼容该格式的服务，无需修改代码。

CLI 类 Provider：以本地命令行进程方式运行的 Provider（Claude Code、Codex CLI、Gemini CLI、Copilot、OpenCode、Cursor、iFlow CLI、MiMo Code、Grok Build、Kimi Code、DevEco Code），SpectrAI 通过 PTY 或 stdio 与进程通信，需要用户在本机安装对应 CLI 工具。其中 Cursor、Grok Build、Kimi Code、MiMo Code、iFlow CLI 采用 ACP（Agent Client Protocol，基于 JSON-RPC 2.0 over stdio）通信。

上下文摘要 Provider（summaryProviderId）：专门用于执行会话上下文压缩摘要的 Provider，与主会话 Provider 解耦。留空时使用当前会话的 Provider，建议指向低成本模型以节省摘要费用。

模型：每个 Provider 可配置一组可用模型，在会话顶部的模型选择器中切换；同 Provider 内切换不重建会话，跨适配器类型切换则需重建。

---

#操作步骤：添加自定义 Provider

将任意 OpenAI 兼容 API 接入 SpectrAI。新建「OpenAI 兼容」Provider 已简化：基础模式下只需填 API Key 与 URL 即可接入，模型列表会自动从接口拉取；名称字段可留默认。

1. 在主界面左侧导航点击底部「设置」图标，进入「设置 → AI Provider」
2. 点击右上角「+ 添加 Provider」按钮
3. 在弹出的「新建 Provider」面板中选择 Provider 模板分组：「官方」/「国产中转」/「海外中转」/「自定义」
4. 点击目标模板卡片（如「DeepSeek」），Base URL 和默认模型自动填入；选「自定义」则手动填写
5. 在「Provider 名称」字段输入易识别的名称（如 DeepSeek 生产），该名称显示在会话切换列表
6. 在「API Key」栏粘贴密钥，点击眼睛图标可预览密钥
7. 在「默认模型」栏确认或修改模型名称
8. 点击「测试连接」按钮，等待连接验证结果
9. 显示「✓ 连接成功」后，点击「保存」完成添加

⚠️ 注意

API Key 以加密形式存储在本地 SQLite 数据库，切勿将 Key 粘贴到会话内容或截图中分享。

---

#操作步骤：会话内切换 Provider

在已有会话中临时更换 AI Provider，无需创建新会话。

1. 在会话底部（输入框下方）工具栏找到当前 Provider 名称（如「Claude Code」），点击它
2. 在弹出的 Provider 列表中选择目标 Provider
3. 若目标 Provider 属于同一适配器类型（如从 Claude Sonnet 切到 Claude Opus），切换即时生效，对话历史完整保留
4. 若目标 Provider 类型不同（如从 Claude Code 切到 DeepSeek），系统弹窗提示「切换将重建会话」，点击「确认」继续

💡 提示

在 Supervisor 模式下，子 Agent 可单独分配 Provider，不必与主 Agent 相同；详见第 4 章 多 Agent 协同。

---

#Provider 设置页与常用操作

进入「设置 → AI 模型 → 模型管理」查看和编辑所有 Provider。设置页布局与常用操作：

• 凭证与模型拆分：编辑面板把「接入凭证」（API Key / URL）与「模型与上下文」分为两块；页面底部为统一「保存修改」按钮。存在未保存改动时会显示「● 有未保存改动」标记，切走前会拦截提醒。
• 上下文窗口预设：在「模型与上下文」里，最大上下文 Token 数 提供 8K / 16K / 32K / 64K / 128K / 200K / 256K / 512K / 1M 预设，也可选「自定义」手填。
• Fast 模式：OpenAI 兼容 Provider 可开启「Fast 模式」，请求带上 service_tier=fast（同模型加速；中转不支持时自动降级）。
• 一键复制 Provider：在 Provider 卡片菜单选择「复制 Provider」，快速基于现有配置创建副本。
• 名称查重：保存时若名称与已有 Provider 重复，会提示「已存在，未重复添加」。
• 排序：被禁用的 Provider 自动排到列表末尾；收藏的 Provider 在会话切换列表中置顶。
• 测连 / 启动失败提示：测试连接或会话启动失败时，失败原因以可理解的人话展示，并附上可点击的下一步操作按钮。

---

#操作步骤：Provider 多 Key 池

⚠️ 注意

多 Key 池为实验性功能，每个 Provider 独立开关，默认关闭。开启后 Key 与 URL 仅在池中维护，编辑面板上方的默认凭证不再生效。

对高频调用或需要多把 Key 轮换的 OpenAI 兼容 Provider，可开启多 Key 池统一管理：

1. 先保存该 Provider，再在其编辑面板中开启「启用多 Key 池」。
2. 点击「管理 Key 池」，批量粘贴多把 Key；每把 Key 可单独设置标签、API Base URL 与组优先级（数字越小越优先）。
3. Key 按 API Base URL 自动分组，可整组启用 / 停用，并按组优先级排序调度。
4. 可开启「锁定默认模型」把会话锁定在默认模型；关闭后可在可用模型列表内切换。
5. 可点击「从 Key 池 URL 拉取」自动获取该 URL 下的可用模型列表。

会话运行时，顶部会显示当前使用的 Key 角标（仅脱敏摘要，完整 Key 不回填、不展示）；点击角标可切换 URL 组或下拉直达「管理 Key 池」。

❌ 不要

期望在 Key 池里看到完整明文 Key。池中只显示脱敏 hint，粘贴保存后无法再次读取完整 Key。

---

#各 Provider 接入指南

SpectrAI（内置托管）

能力简介

SpectrAI 内置托管 Provider（ID: claudeops-builtin）是 SpectrAI 平台自有 AI 接入通道，由 SpectrAI 后端代理转发请求，用户无需自备 API Key、无需科学上网，订阅后开箱即用。适合快速体验 SpectrAI 全功能或不希望管理多个 API Key 的用户。

API Key 获取

托管 Provider 无需用户提供 API Key，额度绑定至 SpectrAI 订阅账号。在「设置 → 账号 → 订阅详情」可查看当前 Token 余量和重置周期。

填写步骤

SpectrAI 托管 Provider 为系统内置，无需手动创建：

1. 进入「设置 → AI Provider」，找到「SpectrAI」卡片（带紫色星形图标）
2. 确认卡片状态显示「已启用」；若显示「余量不足」，点击「去续费」前往订阅页

测试连接

点击「SpectrAI」卡片右侧「...」菜单，选择「测试连接」。显示「✓ 连接成功」表明托管通道正常。若提示「401 未授权」，说明账号 Token 已失效，重新登录即可恢复。

---

Claude Code

能力简介

Claude Code 是 Anthropic 官方 AI 编程 CLI，擅长代码生成、多文件重构、代码审查和复杂任务拆解。内置可选 Claude Opus 4.6（深度推理）、Claude Sonnet 4.6（速度与质量平衡）与 Claude Haiku 4.5（轻量高速）三种模型，上下文窗口 200K token。

API Key 获取地址

有两种接入方式：

• OAuth 订阅：已订阅 Claude Pro/Team 的用户，无需 API Key，执行 claude login 完成 OAuth 授权即可。
• Anthropic 官方 API Key：前往 https://console.anthropic.com/settings/keys 创建密钥（需先在 https://console.anthropic.com/signup 注册账号，访问需科学上网）。

⚠️ 注意

中转站或第三方 OpenAI 兼容 Key 请勿填到 Claude Code 内置配置，应通过「添加 Provider」新建自定义 OpenAI 兼容 Provider。

填写步骤

Claude Code 是系统内置 Provider，无需新建记录：

1. 打开 SpectrAI 内置终端，执行 npm install -g @anthropic-ai/claude-code 安装 CLI
2. 安装完成后执行 claude --version 验证版本
3. 在终端执行 claude login，在弹出的浏览器页面完成 Anthropic 账号 OAuth 授权（订阅用户推荐此方式）
4. 若使用官方 API Key：进入「设置 → AI Provider → Claude Code」，点击「编辑」，在「API Key」栏粘贴 sk-ant-... 格式密钥
5. 若 claude 命令不在系统 PATH，在「可执行文件路径」字段填写完整路径：
   • Windows 示例：C:\Users\<用户名>\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\cli.js
   • Windows 示例：C:\Users\<用户名>\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\cli.js
6. Windows 用户：确认「Git Bash 路径」字段可用（通常自动探测；若探测失败，手动填写 C:\Program Files\Git\bin\bash.exe）
7. 在「默认模型」中选择 claude-opus-4-6、claude-sonnet-4-6 或 claude-haiku-4-5-20251001，点击「保存」

测试连接

点击「设置 → AI Provider → Claude Code」的「测试连接」。CLI 进程成功启动后显示「✓ 连接成功」。

常见失败原因：

• claude: command not found：CLI 未安装或不在 PATH，重新执行安装命令或填写 executablePath
• 401 Unauthorized：OAuth Token 过期，执行 claude login 重新授权；或 API Key 填写有误
• Windows 上「bash.exe 不可用」：Git 未安装或安装在非标准路径，手动设置 gitBashPath

---

Codex CLI

能力简介

Codex CLI 是 OpenAI 官方 AI 编程 CLI，面向代码实现、Bug 修复和大型代码库分析场景，内置代码全自动模式（--full-auto），无需人工确认即可完成复杂改造。上下文窗口 128K token。SpectrAI 默认使用更稳定的 Codex App Server 适配层（codex-appserver），模型选择器会随内置 Codex 的模型目录更新（当前为 GPT-6 / GPT-5.6 家族）。

API Key 获取地址

• OAuth 登录：已订阅 ChatGPT Plus/Pro 的用户，执行 codex login 完成 OAuth 授权。
• OpenAI 官方 API Key：前往 https://platform.openai.com/api-keys 创建密钥（需先在 https://platform.openai.com/signup 注册，访问需科学上网）。

⚠️ 注意

中转站 Key 不适用于此内置配置，请通过「添加 Provider」新增自定义 OpenAI 兼容 Provider。

填写步骤

1. 在终端执行 npm install -g @openai/codex 安装 CLI，完成后执行 codex --version 验证
2. 在终端执行 codex login，在浏览器授权页完成 OpenAI 账号授权（订阅用户推荐此方式）
3. 若使用 API Key：进入「设置 → AI Provider → Codex CLI」，点击「编辑」，在「API Key」栏粘贴 sk-... 格式密钥
4. 在「默认模型」中从下拉列表选择模型（当前提供 GPT-6 / GPT-5.6 家族，以本机内置 Codex 目录为准），点击「保存」

测试连接

点击「设置 → AI Provider → Codex CLI」的「测试连接」，验证 Codex 进程可正常启动并响应。

常见失败原因：

• codex: command not found：CLI 未安装，重新执行 npm install -g @openai/codex
• 401 Unauthorized：API Key 无效或 OAuth Token 过期，重新执行 codex login
• 429 Too Many Requests：请求频率超限，稍等片刻后重试

---

Gemini CLI

能力简介

Gemini CLI 是 Google 官方 AI 编程 CLI，使用 Gemini 2.5 Pro / Flash 系列模型，上下文窗口 128K token，适合多模态任务（含图片分析）、超长文档处理和代码协作场景。Gemini CLI 要求 Node.js v24+，SpectrAI 通过 nvm 自动切换至正确版本（配置值 24.11.0），无需手动干预。

API Key 获取地址

前往 https://aistudio.google.com/apikey 创建 Gemini API Key（需 Google 账号，访问需科学上网；免费额度较充足，适合个人开发者试用）。

填写步骤

1. 在终端执行 npm install -g @google/gemini-cli，完成后执行 gemini --version 验证
2. 进入「设置 → AI Provider → Gemini CLI」，点击「编辑」
3. 在「API Key」字段粘贴 Google AI Studio 的密钥
4. 确认「Node.js 版本」字段显示 24.11.0（SpectrAI 自动填入，无需修改）
5. 在「默认模型」中选择 gemini-2.5-pro（高质量）或 gemini-2.5-flash（高速），点击「保存」

测试连接

点击「测试连接」，等待 Gemini CLI 进程启动（首次启动约需 10–30 秒，nvm 切换版本需要额外时间）。

常见失败原因：

• gemini: command not found：CLI 未安装，重新执行安装命令
• 403 Permission Denied：API Key 未在 Google Cloud Console 启用 Generative Language API
• 启动超时（超过 30 秒无响应）：nvm 未安装或 Node.js v24 版本未拉取，先在终端执行 nvm install 24.11.0

---

GitHub Copilot

能力简介

GitHub Copilot 通过 copilot-sdk 适配器接入，适合已持有 GitHub Copilot 订阅（Individual / Business / Enterprise）的用户，直接复用 Copilot 订阅额度，无需额外 API 费用。

API Key 获取地址

需要有效的 GitHub Copilot 订阅（https://github.com/features/copilot）。接入无需单独 API Key，通过 GitHub OAuth 授权鉴权。

填写步骤

1. 按照 GitHub Copilot 官方文档完成 CLI 代理程序安装，并执行 GitHub OAuth 授权
   [ 截图 ]

   GitHub Copilot CLI 授权完成确认

   截图待补素材
2. 进入「设置 → AI Provider → GitHub Copilot」，确认卡片状态显示「已启用」
3. 若 Copilot 命令不在系统 PATH，点击「编辑」手动填写 copilot 的可执行路径

测试连接

点击「测试连接」，系统启动 Copilot 进程并验证授权状态。

常见失败原因：

• copilot: command not found：CLI 代理程序未安装，参考 GitHub 官方文档完成安装
• 401 Unauthorized：GitHub OAuth 授权过期，重新执行 Copilot CLI 登录流程
• 订阅已到期：前往 github.com/settings/copilot 续费

---

OpenCode

能力简介

OpenCode 是 HTTP-first 的 AI 编码助手，通过 opencode-sdk 适配器以 HTTP 协议与本地 OpenCode 服务通信。OpenCode 内部可对接多家 AI 服务商（在 OpenCode 自身配置中设置），适合偏好轻量 HTTP 通信方式的用户。

API Key 获取地址

OpenCode 项目主页：https://github.com/opencode-ai/opencode。目标 AI 服务的 API Key 配置在 OpenCode 自身的配置文件中，与 SpectrAI 的 Provider 配置分开管理。

填写步骤

1. 按照 OpenCode 官方文档安装并启动本地 OpenCode 服务，执行 opencode --version 验证
2. 进入「设置 → AI Provider → OpenCode」，确认卡片显示「已启用」
3. 如本地服务端口非默认，点击「编辑」修改连接参数，保存

测试连接

点击「测试连接」，SpectrAI 连接本地 OpenCode 服务。服务未运行时显示「连接失败」，先在终端启动 OpenCode 服务再重试。

---

Cursor

能力简介

Cursor 通过 cursor-acp 适配器接入，使用 Cursor Agent Protocol（ACP over JSON-RPC 2.0 on stdio）通信。适合已购买 Cursor 订阅、希望在 SpectrAI 中统一调度 Cursor Agent 的用户。

API Key 获取地址

Cursor 订阅页：https://cursor.sh/pricing。接入无需单独 API Key，Cursor 代理程序通过本地授权文件鉴权。

填写步骤

1. 确认 Cursor 已安装，且 cursor-agent 命令可用（通过 Cursor 应用自带的 CLI 组件提供）
2. 进入「设置 → AI Provider → Cursor」，确认卡片显示「已启用」
3. 模型列表会从 cursor-agent CLI 自动拉取；在会话或编辑面板选择模型后即时切换生效（无需重建会话）。

测试连接

点击「测试连接」，验证 cursor-agent acp 进程可正常启动。失败时确认 Cursor 应用已登录且版本支持 ACP 协议（Cursor v0.40+ 起支持）。若点「停止」按钮无反应，升级 Cursor 应用后重试。

---

iFlow CLI

能力简介

iFlow CLI 通过 iflow-acp 适配器接入，采用 ACP over JSON-RPC 2.0 on stdio 通信协议。适合企业内网部署 iFlow AI 工作流平台的团队，由企业管理员统一下发配置。

API Key 获取地址

iFlow 为企业私有部署产品，API Key 和服务地址由企业管理员提供，无公开注册入口。

填写步骤

1. 由企业管理员提供 iFlow CLI 安装包，完成安装后执行 iflow --version 验证
2. 进入「设置 → AI Provider → iFlow CLI」，点击「编辑」
3. 填写企业管理员提供的连接参数，点击「保存」

测试连接

点击「测试连接」，验证 iFlow CLI 进程可正常启动并接收请求。连接失败时联系企业管理员确认服务地址和授权配置。

---

Grok Build

能力简介

Grok Build 通过 grok-acp 适配器接入（ACP over JSON-RPC 2.0 on stdio），使用 xAI 的 Grok 系列模型，支持会话内计划 / Todo、动态推理力度调整。内置可选模型 grok-4.5 与 grok-composer-2.5-fast，默认 grok-4.5。

API Key 获取地址

Grok Build 需先安装 xAI 官方的 grok CLI 并完成登录鉴权（凭证由 CLI 自身管理）。具体安装与登录方式以 xAI 官方渠道为准。

填写步骤

1. 在本机安装 xAI 官方 grok CLI 并完成登录，确认 grok 命令可用
   [ 截图 ]

   终端验证 grok 命令

   截图待补素材
2. 进入「设置 → AI 模型 → 模型管理 → Grok Build」，确认卡片显示「已启用」
3. 在「默认模型」中选择 grok-4.5 或 grok-composer-2.5-fast，点击「保存」

测试连接

点击「测试连接」，验证 grok 进程可正常启动。失败时确认 CLI 已登录且在系统 PATH 中。

---

Kimi Code

能力简介

Kimi Code 通过 kimi-acp 适配器接入（官方 kimi acp，非 OpenAI 兼容 API），适合已有月之暗面 Kimi 账号、希望在 SpectrAI 中调度 Kimi 编码 Agent 的用户。

API Key 获取地址

Kimi Code 需先安装月之暗面官方 kimi CLI 并完成登录鉴权，凭证由 CLI 自身管理。具体安装与登录方式以月之暗面官方渠道为准。

填写步骤

1. 在本机安装官方 kimi CLI 并完成登录，确认 kimi 命令可用
   [ 截图 ]

   终端验证 kimi 命令

   截图待补素材
2. 进入「设置 → AI 模型 → 模型管理 → Kimi Code」，确认卡片显示「已启用」

测试连接

点击「测试连接」，验证 kimi acp 进程可正常启动。失败时确认 CLI 已登录且版本支持 ACP 协议。

⚠️ 注意

此处的 Kimi Code 是官方 CLI（ACP 协议）接入，与「OpenAI 兼容 Provider 接入指南」中通过 HTTP API 接入的「月之暗面 Kimi」是两条不同路径，按需选择其一。

---

MiMo Code

能力简介

MiMo Code 是小米推出的编码 CLI（npm 包 @mimo-ai/cli，基于 OpenCode fork），通过 mimo-acp 适配器接入。默认使用免费匿名额度模型 mimo/mimo-auto（无需登录即可试用），另提供 xiaomi/mimo-v2.5-pro、xiaomi/mimo-v2.5 等多个模型。

API Key 获取地址

默认模型 mimo/mimo-auto 使用免费匿名额度，无需登录；使用其他 xiaomi/* 模型时按小米 MiMo 官方要求登录。安装方式以小米 MiMo 官方渠道为准。

填写步骤

1. 在本机安装 mimo CLI（@mimo-ai/cli），确认 mimo 命令可用
2. 进入「设置 → AI 模型 → 模型管理 → MiMo Code」，确认卡片显示「已启用」
3. 在「默认模型」中确认或切换模型（默认 mimo/mimo-auto），点击「保存」

测试连接

点击「测试连接」，验证 mimo 进程可正常启动。默认 mimo/mimo-auto 无需登录即可测通。

---

DevEco Code

能力简介

DevEco Code 是华为鸿蒙开发方向的编码 CLI（基于 OpenCode 扩展），通过 deveco-code 适配器以 HTTP/SSE 通信，免费提供 glm-5 模型，上下文窗口约 200K token。适合鸿蒙应用开发场景。

API Key 获取地址

DevEco Code 使用华为开发者账号 OAuth 鉴权（由 deveco CLI 内部管理令牌刷新），仅支持中国大陆华为账号，无需单独填写 API Key。安装方式以华为 DevEco 官方渠道为准。

填写步骤

1. 在本机安装华为 deveco CLI 并用华为开发者账号完成登录，确认 deveco 命令可用
2. 进入「设置 → AI 模型 → 模型管理 → DevEco Code (GLM-5)」，确认卡片显示「已启用」

测试连接

点击「测试连接」，验证 deveco 进程可正常启动并接收请求。失败时确认已用华为账号登录（access token 有效期较短，由 CLI 自动刷新）。

---

#OpenAI 兼容 Provider 接入指南

SpectrAI 的 openai-api 适配器兼容任意符合 OpenAI Chat Completions 格式的接口。下列模板已预置 Base URL 和默认模型，选择模板后仅需填写 API Key 即可。

OpenAI（官方）

能力简介

OpenAI 官方 API，接入 GPT-5 系列模型，适合需要最新 OpenAI 模型能力的场景，支持 Function Calling、Vision、Responses API 等高级特性，可通过 reasoningEffort 参数控制推理强度。

API Key 获取地址

前往 https://platform.openai.com/api-keys 创建密钥（需 OpenAI Platform 账号，注册地址 https://platform.openai.com/signup，访问需科学上网）。

填写步骤

1. 进入「设置 → AI Provider → 添加 Provider」，在「官方」分组点击「OpenAI」模板
2. Base URL 自动填入 https://api.openai.com/v1（无需修改）
3. 在「API Key」字段粘贴 sk-... 格式密钥
4. 默认模型填写 gpt-5.4 或按需调整，点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。返回「✓ 连接成功」表示鉴权有效。若提示 401，检查 Key 格式；若提示「网络不可达」，需配置代理（见详细配置中的代理设置）。

---

DeepSeek

能力简介

DeepSeek 是国内低成本通用推理模型，deepseek-chat 综合性价比高，适合高频调用、代码生成和文档处理场景；deepseek-reasoner 为深度推理版本。无需科学上网，国内直连速度快。

API Key 获取地址

前往 https://platform.deepseek.com/api_keys 创建密钥（需 DeepSeek 平台账号，支持国内手机号注册）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「DeepSeek」模板
2. Base URL 自动填入 https://api.deepseek.com/v1
3. 在「API Key」字段粘贴密钥，默认模型填写 deepseek-chat
4. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。401 表示 Key 无效；402 表示账户余额不足，前往 DeepSeek 控制台充值。

---

硅基流动 SiliconFlow

能力简介

硅基流动是国内模型聚合平台，可统一接入 DeepSeek-V3、Qwen、Yi、Llama 等多种开源和国产模型，按实际 Token 用量计费，适合需要在不同模型间快速测试的场景。

API Key 获取地址

前往 https://cloud.siliconflow.cn/account/ak 创建密钥（需手机号注册，新注册用户有免费 Token 额度）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「硅基流动 SiliconFlow」模板
2. Base URL 自动填入 https://api.siliconflow.cn/v1
3. 粘贴 API Key，默认模型填写 deepseek-ai/DeepSeek-V3 或其他模型全名
4. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。硅基流动模型名称为 <机构>/<模型> 格式（如 deepseek-ai/DeepSeek-V3），若模型名填写错误会返回 404，需核对 SiliconFlow 控制台的模型列表确认正确名称。

---

智谱 GLM

能力简介

智谱 GLM 系列（GLM-4.5 等）是国内代表性大语言模型，适合中文问答、文档总结和代码辅助场景，提供完整的国内合规保证，无需科学上网。

API Key 获取地址

前往 https://open.bigmodel.cn/usercenter/apikeys 创建密钥（需智谱开放平台账号）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「智谱 GLM」模板
2. Base URL 自动填入 https://open.bigmodel.cn/api/paas/v4
3. 粘贴 API Key，默认模型填写 glm-4.5
4. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。智谱 API Key 创建后有时需数分钟生效，若首次测试失败，稍等后重试。

---

月之暗面 Kimi

能力简介

Moonshot Kimi 适合中文长文处理和通用助手场景，提供 8K / 32K / 128K 多种上下文规格，适合需要超大上下文窗口的阅读分析和长对话任务，无需科学上网。

API Key 获取地址

前往 https://platform.moonshot.cn/console/api-keys 创建密钥（需月之暗面平台账号）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「月之暗面 Kimi」模板
2. Base URL 自动填入 https://api.moonshot.cn/v1
3. 粘贴 API Key，默认模型填写 moonshot-v1-8k（或 moonshot-v1-128k 以获得 128K 上下文）
4. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。注意选择正确的模型规格，8K / 32K / 128K 计费单价不同；模型名称错误会返回 404。

---

OpenRouter

能力简介

OpenRouter 是海外聚合平台，一个 Key 可访问 OpenAI、Anthropic、Mistral、Meta Llama 等数百个模型，适合需要对比不同模型效果或试用小众模型的场景，所有请求通过 OpenRouter 统一计费。

API Key 获取地址

前往 https://openrouter.ai/keys 创建密钥（需 OpenRouter 账号，访问需科学上网）。

填写步骤

1. 进入「添加 Provider」，在「海外中转」分组点击「OpenRouter」模板
2. Base URL 自动填入 https://openrouter.ai/api/v1
3. 粘贴 OpenRouter API Key（sk-or-... 格式）
4. 默认模型填写目标模型的 OpenRouter 标识，如 openai/gpt-4o-mini 或 anthropic/claude-3-haiku
5. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。OpenRouter 模型名格式为 <provider>/<model-slug>，填错会返回 404；连接失败时检查是否需要配置代理。

---

Google Gemini API（HTTP 直连）

能力简介

除 Gemini CLI 外，还可通过 OpenAI 兼容入口直接调用 Gemini API，无需本地安装任何 CLI，适合只需 HTTP API 的轻量接入方式。支持 Gemini 2.5 Pro / Flash 系列。

API Key 获取地址

前往 https://aistudio.google.com/apikey 创建密钥（需 Google 账号，访问需科学上网）。

填写步骤

1. 进入「添加 Provider」，在「官方」分组点击「Google Gemini」模板
2. Base URL 自动填入 https://generativelanguage.googleapis.com/v1beta/openai
3. 粘贴 Google API Key，默认模型填写 gemini-2.5-pro 或 gemini-2.5-flash
4. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。若提示「403 Permission Denied」，需前往 Google Cloud Console 启用 Generative Language API；访问失败时检查代理设置。

---

#内置 Provider 与自定义 Provider 对比

---

#详细配置

下表列出 Provider 相关的全部持久化设置项。

全局 Provider 设置（影响所有会话）：

单个 Provider 设置（在各 Provider 的「编辑」面板中配置）：

---

#高级用法

Ollama 本地模型接入

Ollama 在本地运行开源大模型（如 Llama 3、Qwen2.5、DeepSeek-R1 等），完全离线，无 API 费用，适合隐私敏感或无外网环境。

1. 从 https://ollama.com 下载安装 Ollama
2. 在终端执行 ollama pull qwen2.5-coder:7b 拉取目标模型（可按需替换模型名）
3. 执行 ollama serve 启动本地服务（默认监听 http://localhost:11434）
4. 在「添加 Provider」中选择「自定义」，Base URL 填写 http://localhost:11434/v1
5. API Key 填写任意非空字符串（Ollama 本地不鉴权，但 SpectrAI 表单要求 Key 非空）
6. 默认模型填写已拉取的模型名，如 qwen2.5-coder:7b

🔧 高级

Ollama 支持 GPU 加速；安装 NVIDIA/AMD 驱动后拉取模型即自动启用。显存不足时自动降级 CPU 推理，速度较慢。

Cloudflare Workers 反向代理

若 OpenAI 或 Anthropic 官方 API 在大陆无法直连，可通过 Cloudflare Workers 搭建免费反代，在 SpectrAI 中将 Base URL 替换为 Workers 自定义域名，其余配置不变。搭建流程参考社区文档，关键词：「Cloudflare Workers OpenAI Proxy」。

🔧 高级

Cloudflare Workers 每日有免费请求配额（10 万次），超限后需付费升级 Workers Paid 计划。

摘要专用低成本 Provider

会话上下文压缩默认使用当前会话的 Provider 执行摘要，消耗该 Provider 的额度。若希望将摘要任务路由到低成本 Provider（如 DeepSeek），在「设置 → AI Provider → 高级 → 摘要 Provider」中设置 summaryProviderId 指向目标 Provider 的 ID。

多 Key 管理与负载分发

SpectrAI 已内置多 Key 池（实验性），可为单个 OpenAI 兼容 Provider 维护多把 Key、按 URL 分组与组优先级调度，并在会话角标切换当前 Key。配置方式见上文操作步骤：Provider 多 Key 池。

也可继续用代理服务方案：在自建的 OneAPI / LiteLLM 等代理中配置多 Key 池，SpectrAI 侧只填写代理地址和代理的统一访问 Key。

---

#常见问题

测试连接一直显示「连接中…」无反馈

对 HTTP API（OpenAI 兼容），优先检查 Base URL 是否可达：在浏览器地址栏访问 <base-url>/models，若超时则说明网络不通，需配置代理或使用其他 Base URL。对 CLI 类 Provider（如 Claude Code、Gemini CLI），检查 CLI 是否正确安装；Windows 用户同时确认 Git Bash 路径正确。若 CLI 首次启动较慢（超过 30 秒），考虑调大「状态配置」中的 startupStuckMs 阈值。

添加 Provider 保存后，会话切换列表里看不到

进入「设置 → AI Provider」找到对应条目，确认右侧启用开关处于打开状态（enabled: true）。若 Provider 被设置为禁用，切换列表会将其过滤；重新打开开关后刷新会话列表即可显示。

提示 402 余量不足或账户欠费

对 SpectrAI 内置托管 Provider，表示当前订阅 Token 已用完，前往「设置 → 账号 → 订阅」续费或升级套餐。对第三方 API Provider，表示对应账号余额不足，前往对应控制台充值。

大陆能否直接使用 OpenAI 或 Anthropic 官方 API

OpenAI 和 Anthropic 官方 API 接入点在大陆通常无法直连，需要科学上网或使用反向代理。DeepSeek、SiliconFlow、智谱、Kimi 等国产服务无需科学上网，可在国内直接访问。

切换 Provider 后，历史对话消息变少

跨适配器类型切换（如从 Claude Code 切到 DeepSeek）会触发会话重建，原 CLI 会话中的消息历史无法直接迁移。SpectrAI 会生成一段摘要作为新会话的上下文背景，但无法完整还原所有历史细节。建议在会话开始前规划好 Provider 选择，减少跨类型切换。

Gemini CLI 报「Node.js 版本不兼容」

Gemini CLI 要求 Node.js v24+。SpectrAI 会通过 nvm 自动切换至 24.11.0，但前提是系统已安装 nvm。若系统未安装 nvm，先从 https://github.com/nvm-sh/nvm 安装，再执行 nvm install 24.11.0 拉取版本，重新测试连接即可。

---

#相关章节

• 第 1 章 账号与激活 — SpectrAI 订阅与内置 Provider 额度管理
• 第 3 章 AI 会话基础 — 会话内切换模型和 Provider 的完整操作流程
• 第 7 章 远程控制 — 远程控制专用 Provider 配置（remoteControlProviderId）
• 第 9 章 设置与快捷键 — 全局设置项与快捷键 SoT（单一事实源）