如何在 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 密钥，在享受桌面快捷呼出的同时，实现对 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。

底层工作原理

Raycast 巧妙利用了 Anthropic 官方的 Claude Code 命令行工具以及 OpenAI 的 Codex CLI。当你在 Raycast 中触发对话时，Prompt 直接由本地常驻命令行守护进程发送给 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. 选择订阅专属模型
   • 在主界面按下快捷键再按 Tab 呼出 Quick AI，或打开 AI Chat。
   • 展开模型选择菜单，选择 Claude Subscription 或 ChatGPT Subscription 分类下的模型（如 Claude 3.7 Sonnet、Claude 3.5 Sonnet、GPT-4o、o 系列推理模型）。

额度监控与限制机制

使用订阅直连模型时，计费机制遵循官方订阅的时间窗口（例如 Claude 的 5 小时滚动限制或 OpenAI 的频次配额）：

• 在 AI Chat 输入框中输入 /usage，即可调出面板查看当前时间窗口的剩余用量百分比及重置倒计时。
• 也可以在 Raycast 根搜索中执行 Show Claude Usage 或 Show ChatGPT Usage 命令直接查看。

方案二：接入自有 API Key（BYOK）

对于偏好 Pay-as-you-go（按量计费）或需要在 iPhone/iPad 移动端调用模型的开发者，自带 API Key（Bring Your Own Key） 提供了跨设备一致的调用路径。

费用与调用特性

• 计费独立：模型推理费用直接在对应 API 平台后台按 Token 费率扣除（使用绑定的外币信用卡或账户预存额度），Raycast AI 积分配额完全不受影响。
• 流量路由：接入 OpenRouter 时，所有请求从本地设备直发 OpenRouter 服务器；接入 Anthropic、OpenAI 和 Google 时，请求会经由 Raycast 服务器统一格式并添加回退保障，但鉴权完全基于你填写的私有 Key。
• 模型覆盖：OpenRouter 的 API Key 会直接解锁 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） 按钮。
   • 选择服务商，粘贴对应的私有 Key，点击 Verify 进行连通性校验，校验通过后点击 Save。
3. iOS 移动端配置
   • 打开 Raycast iOS 应用，点击右上角头像进入 Account Avatar → AI → Custom API Keys。
   • 选择服务商并粘贴密钥，点击 Verify 即可完成同步。

界面标识确认

在模型选择列表中，凡是通过自定义 API Key 驱动的模型，其右侧都会标有专属的 钥匙图标（Key icon）。只要选择带有该图标的模型，月度的 500 / 3,000 / 7,500 点 Raycast Credits 就处于零消耗的安全保护之下。

方案三：通过 providers.yaml 配置自定义网关与本地模型

在企业研发环境或深度 AI 玩家的工作流中，经常需要接入团队统一代理（如 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. 系统会在访达中打开 ~/.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 会自动热加载（Hot-reload），设置面板中立即显示识别到的服务商与模型数量，随后在 Quick AI 与 AI Chat 中均可直接调用。

核心注意事项与排错指引

在实施上述免额度调用方案时，开发者需了解以下技术边界：

1. Raycast Pro 是核心前置条件 Raycast Free（免费版）不具备 AI 功能，因此也无法开启 BYOK、BYOS 或 Custom Providers。利用入门级的 Raycast Pro 方案搭配已有的 Claude Pro 或 ChatGPT Plus 订阅，是规避高额 Raycast Max 费用与积分购买的最佳实践。
2. 云端工具调用（如生图）仍会消耗 Credits 常规文本问答、代码补全、网页读取在外部订阅和 API Key 下完全免扣点。但个别由 Raycast 官方云端托管运行的功能（例如原生 AI Image Generation），在执行图像生成步骤时仍会动用 Raycast 自有云端模型，从而扣除少许月度 AI Credits。
3. 服务商速率限制不等于 Credits 耗尽 使用外部订阅遭遇“Rate Limit reached”提示时，是触发了 Anthropic 或 OpenAI 的小时/周度限额，购买 Raycast Credits 并不能解除该封顶。此时可通过输入 /usage 查看解禁时间，或临时切换至备用的 BYOK 密钥模型继续编码。
4. 命令行工具环境变量与 PATH 识别 若 Raycast 提示未检测到 Claude Code 或 Codex，通常是 GUI 应用未继承终端环境的非标准路径。Raycast 会自动检索系统的 PATH、Homebrew 默认目录（如 Apple Silicon 的 /opt/homebrew/bin）、npm 全局 bin 路径以及 ~/.local/bin。在终端确认命令能正常输出版本号后，重启 Raycast 即可建立连接。

通过配置外部订阅或自带 API Key，开发者既能保留 Raycast 丝滑的系统级快捷呼出体验，又能彻底甩开月度 AI Credits 耗尽的焦虑，消除重复支付的账单负担。

参考资料

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