如何在 Raycast 中接入自訂 API Key 與外部訂閱，實現零消耗 AI Credits

對於將 Raycast 視為 macOS 核心工作流啟動器的開發者而言，Raycast 自研的 AI 積分額度機制常常成為日常頻繁調用的瓶頸。自 Raycast v2 推出以來，官方全面轉向 AI Credits 計費機制：Raycast Pro 每月提供 500 點額度，Pro+ 提供 3,000 點，Max 提供 7,500 點。當開發者每天在搜尋列按下 Tab 鍵呼叫 Quick AI 查詢終端機指令、重構程式碼，或讓前沿推理模型分析長文本時，這些額度往往在月中便已耗盡。

若開發者本身已按月訂閱 ChatGPT Plus 或 Claude Pro（每月 20 美元），或在 Anthropic Console、OpenAI Platform、Google AI Studio、OpenRouter 擁有開發者餘額，額外向 Raycast 購買儲值包（Top-up）或升級高階方案，就會造成雙重訂閱支出與成本焦慮。

Raycast 原生支援三種「自帶 AI（Bring Your Own AI）」的整合方式，讓開發者直接複用手頭既有的外部訂閱與 API 金鑰，在享受 macOS 快速呼叫體驗的同時，達成對 Raycast AI Credits 的零扣減。

三種免額度整合方案概覽

在進入偏好設定前，可先根據自身既有帳戶資源評估最合適的整合路徑：

先決條件提示：使用 Raycast 的「自帶 AI」功能需具備 Raycast 付費方案（例如最基礎的 Raycast Pro）。免費版 Raycast（Free）不包含 AI 基礎架構。一旦在 Pro 帳號中完成綁定，所有推論對話均由外部帳戶承擔，不會扣減 Raycast 的月度額度。

方案一：直連 Claude Pro 與 ChatGPT Plus 外部訂閱（BYOS）

若開發者每月已支付 20 美元的消費者訂閱，外部訂閱直連（Bring Your Own Subscription） 是最經濟實惠的方案。它完全不產生按量計費的 Token 帳單，而是直接將官方網頁版訂閱的額度無縫延伸至桌面啟動器中。

底層運作架構

Raycast 藉由與 Anthropic 官方的 Claude Code 命令列工具及 OpenAI 的 Codex CLI 於本地溝通。當你在 Raycast 中發起對話時，提示詞會由本地命令列背景服務直接送往 Anthropic 或 OpenAI 官方伺服器，全程不經過 Raycast 的伺服器中轉，Raycast 亦不會儲存或讀取你的登入憑證。

詳細設定步驟

1. 安裝官方命令列工具
   • Claude 用戶：透過 npm 全域安裝 Claude Code：

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

   • ChatGPT 用戶：安裝 Codex CLI，或確認本地已安裝最新版 ChatGPT / Codex 桌面應用程式。
2. 在終端機中完成 OAuth 授權登入
   • Claude：在終端機執行 claude，接著輸入 /login 指令，依指示開啟瀏覽器完成 Claude Pro / Team 帳戶登入。
   • ChatGPT：在終端機執行 codex login，登入你的 ChatGPT Plus / Team 帳號。（請注意：必須登入消費者訂閱帳戶，而非 API Key）。
3. 在 Raycast 中啟用本地訂閱
   • 開啟 Raycast 偏好設定（快捷鍵 ⌘ ,），切換至 AI → Models & Providers。
   • 向下捲動至 Local AI Subscriptions 區塊，開啟 Enable Local AI Subscriptions 開關。
   • 確認下方清單中的 Claude Account 或 ChatGPT Account 顯示已連線與方案名稱。若剛在終端機完成登入，可點擊 Refresh account status 重新整理。
4. 選用訂閱專屬模型
   • 在 Raycast 根搜尋按下 Tab 呼叫 Quick AI，或開啟 AI Chat。
   • 點開模型選單，選擇 Claude Subscription 或 ChatGPT Subscription 區塊內的模型（如 Claude 3.7 Sonnet、Claude 3.5 Sonnet、GPT-4o 或 OpenAI 推理模型）。

額度追蹤與重置機制

訂閱直連模型的調用受限於官方訂閱的滾動配額（例如 Claude 的 5 小時動態視窗或 OpenAI 的頻次上限）：

• 在 AI Chat 輸入框輸入 /usage，即可查看當前時間視窗的使用百分比及重置時間。
• 亦可在 Raycast 根搜尋中執行 Show Claude Usage 或 Show ChatGPT Usage 指令快速檢視。

方案二：自帶 API Key（BYOK）

對於習慣依照 Token 消耗量精準付費、或需要在 iPhone/iPad 行動端使用模型的開發者，自帶 API Key（Bring Your Own Key） 提供跨平台一致的調用體驗。

計費與網路特性

• 獨立計費：推論費用直接在對應的 API 供應商平台扣款，Raycast AI Credits 額度完全不受影響。
• 網路傳輸：使用 OpenRouter 時，請求直接由裝置傳送至 OpenRouter 伺服器；使用 Anthropic、OpenAI 與 Google 時，請求會經由 Raycast 伺服器標準化格式並提供容錯機制，但完全使用你輸入的金鑰完成驗證。
• 完整模型支援：輸入 OpenRouter API 金鑰即可解鎖 OpenRouter 全站數百款模型目錄（包含 DeepSeek-V3、DeepSeek-R1、Llama 3 等熱門開源旗艦模型），無需等待 Raycast 官方排程適配。

詳細設定步驟

1. 取得服務商 API 金鑰
   • Anthropic: 控制台 Settings → API Keys
   • OpenAI: Platform → API Keys
   • Google: Google AI Studio → Get API Key
   • OpenRouter: Account Settings → Keys
2. 桌面端（macOS / Windows）設定
   • 開啟 Raycast Settings → AI → Models & Providers。
   • 捲動至 API Keys 區塊，點擊 +（Plus） 符號。
   • 於下拉選單中選擇服務商，貼上對應的金鑰，點擊 Verify 進行連線測試，通過後點擊 Save。
3. iOS 行動端設定
   • 開啟 Raycast iOS，點擊右上角個人頭像進入 Account Avatar → AI → Custom API Keys。
   • 點選服務商，貼上金鑰並點擊 Verify 即可完成綁定。

介面辨識標籤

在模型選擇選單中，成功啟用自帶 API Key 的模型旁邊會附帶一個清楚的 金鑰圖示（Key icon）。只要選用標有金鑰圖示的模型，你的 Raycast AI Credits 月度額度就會處於零消耗狀態。

方案三：使用 providers.yaml 配置自訂閘道與本地模型

針對團隊共用代理（例如 LiteLLM）、多模型統一閘道（Vercel AI Gateway、Cloudflare AI Gateway）、雲端推論平台（AWS Bedrock）或本機離線運行的開源模型（LM Studio、Ollama、OpenClaw），Raycast 支援透過本地 YAML 檔案接入任何與 OpenAI API 相容的自訂端點。

設定步驟與範例

1. 開啟 Raycast Settings → AI → Models & Providers。
2. 捲動至 Custom Providers 區塊，點擊 Reveal Providers Config。
3. 系統將在 Finder 中開啟 ~/.config/raycast/ai/ 資料夾，內含官方範本 providers.template.yaml。
4. 將範本複製並更名為同資料夾下的 providers.yaml。
5. 編輯 providers.yaml，填入端點位址、金鑰與模型清單。例如連接 Vercel AI Gateway：

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

若欲連接本地離線運行的 LM Studio 伺服器（完全無外網流量、零額度開銷）：

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. 儲存檔案後，Raycast 會自動偵測並即時重載，設定介面隨即顯示已註冊的服務商與模型數量，於 Quick AI 與 AI Chat 中皆可自由選取。

注意事項與常見問題排除

在設定免額度調用時，請特別留意以下細節：

1. Raycast Pro 為必備前置條件 免費版 Raycast 不支援 AI 模組，因此無法開啟外部訂閱或 API Key 功能。選擇基礎的 Raycast Pro 搭配手頭現有的 Claude Pro 或 ChatGPT Plus，是兼顧極致效率與合理支出的最佳組合。
2. 少數雲端原生工具仍會扣除 Credits 純文字對話、程式碼重構、網頁讀取等工作完全免扣點；但少數由 Raycast 官方伺服器執行的工具（例如原生 AI Image Generation），在生成圖片時仍會呼叫 Raycast 官方模型，進而消耗微量月度 AI Credits。
3. 區分供應商頻次限制與積分耗盡 若在使用外部訂閱時遭遇頻率上限（Rate Limit）錯誤，此為 Anthropic 或 OpenAI 本身的短時用量保護，加購 Raycast Credits 並無法解除限制。此時可透過 /usage 確認解鎖時間，或暫時切換至 BYOK 金鑰模型繼續工作。
4. 終端機環境變數與 PATH 辨識 若 Raycast 顯示未找到 Claude Code 或 Codex CLI，通常是 GUI 應用程式未繼承客製化 shell 環境變數。Raycast 會自動掃描系統 PATH、Homebrew 預設目錄（Apple Silicon 下為 /opt/homebrew/bin）、npm 全域路徑及 ~/.local/bin。在終端機確認指令正常運作後，重啟 Raycast 即可解決。

透過導入外部訂閱與自帶金鑰，開發者得以完美保留 Raycast 秒級快捷鍵調用的高效體驗，同時徹底告別月度 AI 額度提早耗盡的焦慮。

參考資料

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