如何在 Raycast 中使用 CometAPI——实用指南

Raycast 的 AI 功能现已支持通过 providers.yaml 自定义提供方接入任意兼容 OpenAI 的提供方。CometAPI 是一个网关 API，在 OpenAI 风格的 REST 接口之下汇聚了数百个模型——因此你可以将 Raycast 指向 https://api.cometapi.com/v1，添加你的 CometAPI 密钥，就能在 Raycast AI（聊天、命令、扩展）中使用 CometAPI 的模型。

什么是 Raycast？

Raycast 是一款面向 macOS 的效率启动器，它将命令、脚本以及——并且越来越多地——AI 直接集成到你的操作系统中。其 AI 子系统提供聊天、AI 命令、模型选择、扩展（让 LLM 执行动作的工具），以及使用本地模型（通过 Ollama）或自带密钥 / 自定义提供方（Bring Your Own Key / Custom Providers）连接远程模型提供方的能力。Raycast 提供模型选择器、AI 设置，以及一个 providers.yaml 模板，供高级用户自定义以添加 OpenAI 兼容的后端。

Raycast 已在 2025 年逐步推出 BYOK（Bring Your Own Key）和 Custom Providers，使用户能够使用自己的 API 密钥和自定义端点运行 Raycast AI（从而实现更灵活的成本管理与私有提供方选项）。这一变更为从终端用户的 Raycast 偏好设置集成 CometAPI奠定了技术基础。

Raycast 如何向用户呈现 AI？

• Quick AI：从启动器即时发出提示。
• AI Chat：带附件/上下文的对话会话。
• AI Commands/Extensions：开发者构建的使用 LLM 的命令或工具。
  （你可以在 Settings → AI 管理模型、BYOK 密钥和自定义提供方。）

什么是 CometAPI？

CometAPI 是一个 API 聚合平台，通过单一、OpenAI 风格的 REST 接口暴露数百个不同的 AI 模型（文本、图像、音频、视频、向量）。相比为 OpenAI、Anthropic、Google、Midjourney、Runway 等分别编写并维护特定客户端代码，你只需调用 CometAPI 的端点，并通过模型字符串选择所需模型。此简化对于实验、成本/故障切换路由，以及计费与可观测性集中化非常有价值。

关键能力

• 文本/聊天补全与助理（OpenAI 式聊天 API）。
• 图像生成与图像编辑端点。
• 语义搜索/RAG（检索增强生成）的向量。
• 音频（当底层模型支持时的 TTS 与 STT）。
• 面向专用后端的视频生成（Sora、Veo 等）。
  CometAPI 还提供 SDK 代码片段和 OpenAI 风格的请求格式，便于直接移植现有代码。

此时之所以重要：市场正在转向网关 API（方便的单一端点、更低的价格选项以及模型可选性）。CometAPI 是该领域的商业参与者之一，因此结合 Raycast 的自定义提供方支持，可让你从 macOS 工作流中立即访问广泛的模型目录。

为什么要将 CometAPI 与 Raycast 集成？

简短答案：在不更换工具的前提下，直接在你的 Raycast AI 流程（Quick AI、AI Chat 或自定义 AI 命令）中运行 CometAPI 暴露的任意模型。

好处：

• 在保持身处 Raycast 的同时，为不同任务（摘要、代码、向量、图像生成）使用更便宜/更快或更专业的模型。
• 通过 CometAPI 实现集中计费与限流，同时在 Raycast 中控制模型选择。
• 最小化代码改动：Raycast 支持兼容 OpenAI 的自定义提供方与 BYOK，因此接入 CometAPI 通常只需替换 base_url 和 API 密钥。

（这些能力之所以可行，是因为 Raycast 支持自定义提供方与 BYOK，而 CometAPI 在 https://api.cometapi.com/v1. 暴露了兼容 OpenAI 的端点。）

这种集成有哪些适用场景？

1. 开发者助手：代码讲解、重构建议、单元测试生成、PR 摘要——从 Raycast 调用并获得内联回答。
2. 笔记与摘要：选中文本，使用 Raycast 命令借助 CometAPI 的摘要模型生成摘要或提取行动项。
3. 文档撰写：通过 Raycast AI 命令生成函数文档或 README 片段，并在本地快速迭代。
4. 图像/多媒体生成：如果 CometAPI 暴露了图像端点，你可以使用调用图像端点的 Raycast 扩展（例如 “Generate Image from Prompt” 扩展）——适合快速打样。
5. 向量与语义搜索：使用 CometAPI 的向量为本地搜索工作流提供能力——Raycast 可作为前端，通过本地小脚本或云函数查询你的向量索引。

需要准备哪些环境与条件？

开始之前，请确保已准备好以下内容：

系统与 Raycast

• macOS（Raycast 为原生 macOS 应用）。
• 已安装 Raycast。建议使用支持 Custom Providers / BYOK 的新版本（Raycast 在 v1.100.0 引入了 BYOK，并持续推出 Custom Providers）。如果你的 Raycast 版本较旧，请更新。

账户与密钥

• CometAPI 账户与有效的 CometAPI API 密钥（你将在 Raycast 设置或环境变量中使用它）。请参阅 CometAPI 控制台/文档。

可选的开发者工具（用于测试或本地开发）

• 终端（用于 cURL）。
• 如果想在接入 Raycast 之前直接测试 CometAPI 访问，可使用 Python / Node / OpenAI SDK。CometAPI 支持通过覆盖 base_url 直接使用标准 SDK。

权限与网络

• 确保 Raycast 与 macOS 的网络策略允许对 api.cometapi.com 的 HTTPS 访问。
• 如果处于公司网络与代理/防火墙环境，确认 api.cometapi.com 可达。

本地文件与位置

Raycast 的 AI “提供方配置”位于 Raycast 的配置目录下名为 providers.yaml 的文件中（应用可显示可复制的提供方模板）。你将编辑或创建 providers.yaml 以定义自定义提供方。

如何将 Raycast 与 CometAPI 集成？

核心思路：在 Raycast 中注册 CometAPI 为一个兼容 OpenAI 的自定义提供方，将 Raycast 指向 https://api.cometapi.com/v1，并在 Raycast 的自定义 API 密钥中加入你的 Comet 令牌。

步骤 1：获取你的 CometAPI 密钥

1. 在 CometAPI 注册并打开控制台/仪表盘。
2. 创建一个 API 令牌。将该令牌安全保存（或留待下一步使用）。

步骤 2：打开 Raycast 的 AI 设置并启用自定义提供方

1. 在 Raycast 中：Preferences → AI。
2. 找到 “Custom Providers”（或 “Custom OpenAI-compatible APIs”），点击 Reveal Providers Config。Raycast 将在 Finder 中打开配置目录，并提供模板文件（通常为 providers.template.yaml），复制并重命名为 providers.yaml。

步骤 3：在 providers.yaml 中添加 CometAPI 提供方

创建或编辑 providers.yaml 文件。Raycast 所需的确切架构可能因版本不同而异，但社区模板与 Raycast 手册展示了通用结构：包含 id、name、base_url 以及可选的 models 区块的提供方条目列表。下面是一个安全、可用的示例，用于注册 CometAPI 为 OpenAI-co

重要说明

• 将 YOUR_COMETAPI_KEY 替换为安全引用——个人使用可直接粘贴令牌，更好的做法是：如果支持，存入 macOS 钥匙串 / Raycast 的安全字段。
• base_url 是关键：将其指向 https://api.cometapi.com/v1. Raycast 将对兼容 OpenAI 的调用使用该基础 URL。
• 你不一定需要预先列出所有模型——如果你的提供方暴露了符合规范的 GET /v1/models 端点，Raycast 可以获取模型列表。若 CometAPI 暴露了模型列表，Raycast 可刷新并显示可用模型。

步骤 4：刷新模型并测试

• 返回 Raycast 后，可能需要重启应用或使用“Refresh Models”命令（取决于版本），以便 Raycast 从新提供方获取模型并填充模型选择器。如果未显示模型，建议刷新或重启。
• 使用一个简单的 Quick AI 提示，从模型选择器中选择 CometAPI 的模型并运行测试提示。

在 Raycast 中使用 CometAPI 的最佳实践

安全最佳实践： 切勿在共享的 providers.yaml 中硬编码令牌。优先使用 Raycast 的安全字段或 macOS 钥匙串；如果使用本地代理，可通过环境变量注入密钥。若有敏感数据，请阅读 CometAPI 与 Raycast 的隐私文档。

可靠性与性能： 请测试你打算使用的模型的延迟——网关 API 的路由可能存在波动。对于交互式工作流（自动摘要、快速查询），优先选择更小、更快的模型；对于更深入的推理任务，则选择更高上下文能力的模型。

成本控制： 积极利用模型选择：短任务选用轻量模型，重推理选择高能力模型。在 CometAPI 仪表盘跟踪用量并设置预算提醒。考虑通过程序化提示降低 token 使用（例如更短的系统消息、高效的上下文管理）。

提示工程与用户体验： 制作 Raycast AI Commands（复制内置命令并调整提示）时，对实用型命令（摘要、分拣、搜索）保持提示的确定性；对创意型工作流允许更开放的提示。推荐在内置命令基础上复制并自定义提示。

如何排查常见问题？

Raycast 中不显示模型： 确保 providers.yaml 位于通过 “Reveal Providers Config” 打开的确切文件夹中。以模板为基线并重启 Raycast。重启或“Refresh Models”通常有效。

401 / invalid token： 确认你的 CometAPI 令牌有效且未过期。尝试上面的 curl 测试。仔细检查是否使用了 Bearer 令牌以及 Authorization 头是否正确。

模型错误或返回格式不兼容： CometAPI 旨在兼容 OpenAI，但某些边缘情况可能存在（模型 ID、流式行为）。如果 Raycast 期望特定的流式格式而 CometAPI 的输出略有差异，先尝试非流式调用，必要时联系 CometAPI 支持。

结论

CometAPI 为你提供统一的、多厂商的模型访问（文本、图像、音频、视频），并让团队集中计费与路由。Raycast 则在你的桌面工作流上下文中，提供即时、以键盘为先的模型调用入口。二者结合可使模型实验与桌面自动化更加顺畅——你可以为成本或质量随时切换模型、将密钥保留在本地，并继续沿用脚本与应用中熟悉的 OpenAI 风格用法。

如果你想立即尝试，请在 Playground 中探索 CometAPI 的模型（Gemini 3 Pro Preview API 等）的能力，并参考 API 指南获取详细说明。访问前，请确保你已登录 CometAPI 并获得 API 密钥。CometAPI 提供远低于官方的价格，帮助你完成集成。

准备好了吗？→ use CometAPI in Raycast today ！

如果你想了解更多技巧、指南与新闻，请关注我们的 VK、X 和 Discord！