How to Connect Custom API Keys and External Subscriptions to Raycast Without Consuming AI Credits

Developers who rely on Raycast as their central macOS command launcher frequently face a frustrating bottleneck: Raycast's built-in AI credit quota. Introduced with Raycast v2, the AI credit model allocates a fixed monthly allowance—500 credits on Raycast Pro, 3,000 on Pro+, and 7,500 on Max. For engineers invoking Quick AI dozens of times a day from the search bar (Tab), querying large codebases, or utilizing reasoning-heavy frontier models, those credits can evaporate in the middle of a sprint.

If you already pay $20 a month for ChatGPT Plus or Claude Pro, or maintain your own developer balances on Anthropic Console, OpenAI Platform, Google AI Studio, or OpenRouter, you do not need to buy Raycast credit top-ups or pay for duplicative subscriptions.

Raycast natively provides three distinct Bring Your Own AI (BYO-AI) mechanisms that allow you to route conversations directly through your existing accounts without burning a single Raycast AI credit. Here is how each method works and how to set them up step by step.

The Three Zero-Credit Integration Methods at a Glance

Before opening settings, determine which integration pattern matches your existing subscriptions and workflow:

Important requirement: Bringing external subscriptions, API keys, or custom providers into Raycast requires an active paid Raycast plan (such as Raycast Pro). Free accounts do not include AI capabilities. Once connected under a Pro subscription, inference runs completely outside Raycast's credit counter.

Method 1: Bring Your Own Subscription (Claude Pro & ChatGPT Plus)

The most economical option for developers already holding flat-rate consumer subscriptions is Bring Your Own Subscription. Instead of metered token billing, Raycast communicates with official local command-line tools to leverage your unlimited monthly consumer quotas.

How It Works Behind the Scenes

Raycast interfaces locally with Anthropic's Claude Code CLI or OpenAI's Codex CLI. When you trigger Quick AI or AI Chat, your prompt passes straight from the local daemon on your computer to Anthropic or OpenAI servers. Raycast never receives, processes, or stores your login tokens.

Step-by-Step Setup

1. Install the Provider CLI Tooling Ensure you have the respective CLI client installed on your system:
   • For Claude: Install Claude Code via npm:

     npm install -g @anthropic-ai/claude-code
     

   • For ChatGPT: Install the Codex CLI or ensure you have ChatGPT Desktop / Codex Desktop installed on your system.
2. Authenticate in Your Terminal
   • For Claude: Run claude in your terminal and execute the /login slash command. Complete the browser-based OAuth authentication with your Claude Pro or Team account.
   • For ChatGPT: Run codex login in your terminal and authenticate using your ChatGPT Plus or Team credentials. (Note: Make sure to sign in with your consumer account, not an API service key.)
3. Enable Local AI Subscriptions in Raycast
   • Open Raycast and press ⌘ , to open Settings.
   • Navigate to AI → Models & Providers.
   • Scroll down to the Local AI Subscriptions section and toggle on Enable Local AI Subscriptions.
   • Verify that your account details appear under Claude Account or ChatGPT Account. If you just logged in via terminal, click Refresh account status.
4. Select Your Subscription Models
   • Open Quick AI (press Space or your launcher hotkey, then press Tab), or open AI Chat.
   • In the model picker dropdown, navigate to the Claude Subscription or ChatGPT Subscription group.
   • Select models such as Claude 3.7 Sonnet, Claude 3.5 Sonnet, GPT-4o, or OpenAI reasoning models.

Tracking Usage

Subscription models follow the provider's rolling quota (such as Anthropic's 5-hour messaging window or OpenAI's rate ceilings) rather than Raycast credits:

• Type /usage in AI Chat to view the remaining percentage and reset countdown of your provider window.
• Alternatively, run the Show Claude Usage or Show ChatGPT Usage command from Root Search.

Method 2: Bring Your Own Key (Anthropic, OpenAI, Google & OpenRouter)

If you prefer pay-as-you-go API pricing or need access on mobile devices, Bring Your Own Key (BYOK) links your provider API secrets directly to Raycast.

How Billing & Traffic Behave

• Direct Billing: Inference is billed directly to your provider balance or credit card at raw token rates ($ per million tokens). Raycast AI credit consumption is zero.
• Routing: OpenRouter requests are transmitted directly from your device to OpenRouter's API endpoints. For Anthropic, OpenAI, and Google, requests route through Raycast servers to normalize parameters, schemas, and prompt fallbacks, but your custom key is used for authentication.
• Model Selection: Anthropic, OpenAI, and Google keys unlock the models natively curated in Raycast. An OpenRouter key immediately unlocks OpenRouter's entire multi-hundred model directory, including open-weight flagships from DeepSeek, Meta Llama, and Mistral.

Step-by-Step Setup

1. Obtain Your API Key
   • Anthropic: Console → Settings → API Keys (sk-ant-...)
   • OpenAI: Platform → API Keys (sk-...)
   • Google: Google AI Studio → Get API Key
   • OpenRouter: Account Settings → Keys (sk-or-...)
2. Configure on Desktop (macOS / Windows)
   • Open Raycast Settings → AI → Models & Providers.
   • Scroll to the API Keys section and click the + (Plus) button.
   • Select your provider from the dropdown.
   • Paste the secret key and click Verify. Raycast executes a test handshake against the provider endpoint.
   • Click Save.
3. Configure on iOS
   • Open Raycast iOS, tap your Account Avatar in the upper right corner.
   • Go to AI → Custom API Keys, tap the target provider, paste your key, tap Verify, and return.

Identifying BYOK in the Interface

Once active, an explicit Key icon appears beside the model name in the model picker. As long as that model is selected, your monthly 500/3,000/7,500 Raycast AI credit balance remains completely untouched.

Method 3: Custom Providers via providers.yaml (Gateways, Proxies & Local LLMs)

For advanced engineering setups—such as proxying requests through a shared team gateway (LiteLLM), routing via Vercel AI Gateway / Cloudflare AI Gateway, calling AWS Bedrock, or running local offline inference via LM Studio—Raycast supports full OpenAI-compatible endpoint configuration via YAML.

Configuration Procedure

1. Open Raycast Settings → AI → Models & Providers.
2. Scroll to Custom Providers and click Reveal Providers Config.
3. Raycast will open ~/.config/raycast/ai/ in Finder. Inside, you will see providers.template.yaml.
4. Copy providers.template.yaml to providers.yaml in the same directory.
5. Populate your endpoints and models. For example, to connect LiteLLM or Vercel AI Gateway:

providers:
  - id: team_gateway
    name: "Vercel AI Gateway"
    base_url: https://ai-gateway.vercel.sh/v1
    api_keys:
      team_gateway: YOUR_GATEWAY_API_KEY
    models:
      - id: anthropic/claude-3-7-sonnet
        name: "Claude 3.7 Sonnet (Gateway)"
        context: 200000
        abilities:
          temperature:
            supported: true
          vision:
            supported: true
          system_message:
            supported: true
          tools:
            supported: true
          reasoning_effort:
            supported: true

Or for a local, privacy-first LM Studio server:

providers:
  - id: lmstudio_local
    name: "LM Studio Local"
    base_url: http://localhost:1234/v1
    models:
      - id: qwen2.5-coder-32b-instruct
        name: "Qwen 2.5 Coder 32B"
        context: 32768
        abilities:
          temperature:
            supported: true
          system_message:
            supported: true

6. Save the file. Raycast detects changes instantly without requiring an application restart. Your custom models will appear in Quick AI and AI Chat under their respective provider headings.

Critical Rules, Edge Cases & Caveats

To ensure you never accidentally consume Raycast credits, keep the following architectural nuances in mind:

1. Raycast Pro Tier Prerequisite You cannot bring your own keys or external subscriptions on Raycast Free. The Bring Your Own AI feature set is exclusive to paid tiers (Raycast Pro, Pro+, and Max). However, pairing the entry-level Raycast Pro plan with your existing Claude Pro or ChatGPT Plus subscription is drastically cheaper than upgrading to higher Raycast credit tiers or buying credit top-ups.
2. Server-Side Native Tools Consume Credits While chat completion, text drafting, code generation, and web-page reading run on your external subscription or custom key, certain Raycast cloud tools—specifically native image generation—always execute on Raycast cloud models and deduct from your monthly Raycast AI credits.
3. Provider Rate Limits vs Credit Depletion If a prompt fails with a rate-limit error while using an external subscription, buying Raycast AI credits will not resolve it. The limit is enforced by OpenAI or Anthropic's hourly usage policy. Type /usage to view your reset window, or momentarily switch to a BYOK model or local model to keep coding.
4. CLI PATH Troubleshooting on macOS If Raycast reports that Claude Code or Codex CLI is not found, Raycast may not have inherited your custom shell environment. Raycast scans standard locations: PATH, Homebrew default prefixes (/opt/homebrew/bin on Apple Silicon), npm global bins ($(npm config get prefix)/bin), and ~/.local/bin. Restart Raycast after verifying the CLI executes cleanly in a standalone Terminal window.

By routing heavy AI tasks through Bring Your Own Subscription or BYOK, macOS developers retain Raycast's unmatched speed and shortcut integration while eliminating token anxiety and double billing.

References

• AI | Raycast Manual
• Bring Your Own Subscription | Raycast Manual
• Bring Your Own Key | Raycast Manual
• Custom Providers | Raycast Manual
• AI Credits | Raycast Manual