Frequently Asked Questions

Overview

Navigate to Settings → AI provider to find options like Claude Code, Codex CLI, and Gemini CLI — and learn how to configure them.

Settings → AI provider: manage all your AI providers

Answer

AI Providers are the engines behind SpectrAI sessions — whichever provider you pick when starting a session determines which AI executes your instructions.

SpectrAI supports two categories of providers:

Category	Examples	Auth method	Notes
CLI Tools	Claude Code、Codex CLI、Gemini CLI、iFlow、OpenCode	Each CLI's own login	Communicates via local CLI — no API Key needed in SpectrAI
OpenAI-compatible API	Custom API provider	API Base URL + API Key	Calls the API over HTTP — requires an API Key and endpoint URL

Key concepts:

• Claude Code is a CLI tool with its own auth flow (log in via claude login). It does not use any API Key you enter in SpectrAI.
• To use Claude, install and log in to the Claude Code CLI in a terminal first, then confirm the path is correct in SpectrAI.
• If you have an OpenAI-format API Key (e.g. a relay service), add a custom AI provider and choose the OpenAI Compatible API adapter type.

Set Up Claude Code (Recommended)

1. Ensure Claude Code CLI is installed: npm install -g @anthropic-ai/claude-code
2. Run claude login in a terminal to authenticate
3. Open SpectrAI → Settings → AI provider → find the Claude Code card
4. Click edit, confirm Command is set to claude — if the path fails, see FAQ #4
5. Click the Test button to verify connectivity

Using a Custom API Key

1. Open SpectrAI → Settings → AI provider
2. Click "Add custom AI provider" at the bottom
3. Set Adapter Type to OpenAI Compatible API
4. Fill in Name, API Base URL, API Key, and Default Model
5. Save, then select this provider when starting a new session

Adding a custom AI provider: enter your API Base URL and API Key

Overview

You configured an API Key in SpectrAI settings, but new chat sessions keep showing Invalid API key · Please run /login — even though the key works fine elsewhere.

"Invalid API key · Please run /login" error in a chat session

Root Cause

This error comes from Claude Code CLI itself, not from SpectrAI.

Claude Code uses Anthropic account auth (OAuth login) and ignores any API Key configured in SpectrAI. When you select Claude Code as your provider, SpectrAI launches the claude command, and Claude Code throws this error if it finds no active login session.

Option A: Log in to Claude Code CLI (Recommended)

1. Open a terminal (Windows: PowerShell / CMD; macOS: Terminal)
2. Run claude login
3. Follow the prompts to complete browser-based authorization
4. Return to SpectrAI and start a new session

Option B: Use a Third-Party Relay API Key

If you have a relay service or OpenAI-format API Key, it cannot be used with Claude Code CLI. Instead:

1. Go to SpectrAI → Settings → AI provider → Add custom AI provider
2. Set Adapter Type to OpenAI Compatible API
3. Enter your API Base URL and API Key
4. When starting a new session, select this provider instead of Claude Code

Option C: Inject API Key via Environment Variable

If you have an official Anthropic API Key (starting with sk-ant-), you can inject it via environment variable:

1. Open SpectrAI → Settings → AI provider → edit Claude Code
2. Under Environment Overrides, add:

Save and start a new session.

Overview

After downloading and installing SpectrAI on macOS, double-clicking the app shows: "SpectrAI is damaged and can't be opened."

macOS Gatekeeper blocking an unsigned app

Root Cause

This is caused by macOS Gatekeeper, not actual app corruption. Because SpectrAI is currently unsigned, macOS blocks it from running.

Fix

Open Terminal (Terminal.app) and run the two commands below:

Step 1: Allow apps from any source

Enter your Mac login password when prompted (characters are not shown — type normally and press Return).

Afterward, open System Settings → Privacy & Security to confirm "Anywhere" is now selected under Security:

System Settings → Privacy & Security → Allow apps from Anywhere

Step 2: Remove the quarantine flag

Once done, double-click SpectrAI and it will open normally.

Full Command Summary

Overview

In AI provider settings, Claude Code path auto-detection fails, preventing Claude sessions from starting. Or clicking the Test button shows that the claude command cannot be found.

Root Cause

SpectrAI searches for claude in the system PATH by default. If Claude Code is installed in a non-standard location or PATH is misconfigured, auto-detection will fail.

Step 1: Find the actual Claude path

Run in a terminal:

Step 2: Manually configure in SpectrAI

1. Open SpectrAI → Settings → AI provider
2. Find the Claude Code card and click edit (pencil icon)
3. Locate the Executable Path field
4. Paste the full path, or click the 📁 button to browse
5. Click the Test button to verify the path
6. Once ✅ appears, click Save

Enter the full path to claude in Executable Path, then click Test

Common Path Reference

OS	Install method	Typical path
Windows	npm -g	C:\Users\<username>\AppData\Roaming\npm\claude.cmd
Windows	nvm	C:\Users\<username>\AppData\Roaming\nvm\<version>\claude.cmd
macOS	npm -g	/usr/local/bin/claude
macOS	Homebrew	/opt/homebrew/bin/claude
Linux	npm -g	/usr/local/bin/claude or ~/.npm-global/bin/claude

1. Visit the mobile page on the official site and scan the QR code or click "Download APK"
2. On Android go to Settings → Security/Privacy → enable "Allow apps from this source" (or grant permission when prompted during install)
3. Open the downloaded APK file to complete installation
4. Launch the app, scan the QR code to log in, and link your desktop account

All chat history, session data, and provider configuration are stored in a local SQLite database. Your data never leaves your device. Login only syncs an auth token (for subscription validation) — conversation content always stays local.

OS	Storage path
Windows	%APPDATA%\光谱AI\
macOS	~/Library/Application Support/光谱AI/

The official purchase flow is: buy a redemption code from 链动小铺 → redeem it in the client. The website does not accept direct payments.

1. Purchase an official SpectrAI redemption code from 链动小铺 (pricing and checkout happen there; find the store link via client Settings → Upgrade plan).
2. Download and log in to the SpectrAI desktop app, go to Settings → Upgrade plan, and enter the redemption code to activate.
3. If the plan level does not update after activation, go to the avatar menu → "Refresh plan status". If the issue persists, submit a report via the feedback page.