Hoe gebruik je CometAPI in Raycast — een praktische gids

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 端点，并通过模型字符串选择你想要的模型即可。这种简化对于实验、成本/故障切换路由以及统一计费和可观测性都非常有价值。

核心能力

• 文本/聊天补全和 assistants（类似 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）。
• Python / Node / OpenAI SDK，如果你想在接入 Raycast 之前先直接测试 CometAPI 访问。CometAPI 支持通过覆盖 base_url 使用标准 SDK 直接调用。

权限与网络

• 确保 Raycast 和你的 macOS 网络策略允许向 api.cometapi.com 发起 HTTPS 请求。
• 如果你处于企业环境并使用代理/防火墙，请确认 api.cometapi.com 可达。

本地文件与位置

Raycast 的 AI providers 配置 位于 Raycast 配置目录下的 providers.yaml 中（应用可显示一个 providers 模板供你复制）。你将编辑或创建 providers.yaml 来定义自定义提供商。

如何将 Raycast 与 CometAPI 集成？

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

第 1 步：获取你的 CometAPI 密钥

1. 前往 CometAPI 注册并打开控制台 / 仪表板。
2. 创建 API token 。将该 token 复制到安全位置（或保留供下一步使用）。

第 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 所需的确切 schema 可能因版本而异，但社区模板和 Raycast 手册展示了常见结构：一个提供商条目列表，其中包含 id、name、base_url 以及可选的 models 块。下面是一个安全且可用的示例，用于将 CometAPI 注册为 OpenAI 兼容提供商

重要说明

• 将 YOUR_COMETAPI_KEY 替换为安全引用——可以直接粘贴 token（个人使用），但更推荐：如果支持的话，将其存储在 macOS Keychain / Raycast 的安全字段中。
• base_url 是最关键的一行：将其指向 https://api.cometapi.com/v1. Raycast 将使用该基础 URL 发起兼容 OpenAI 的调用。
• 你不一定需要预先列出所有模型——如果你的提供商暴露了规范实现的 OpenAI 风格 GET /v1/models 端点，Raycast 可以从中获取模型列表。如果 CometAPI 暴露模型列表，Raycast 就可以刷新并显示可用模型。

第 4 步：刷新模型并测试

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

在 Raycast 中使用 CometAPI 的最佳实践

安全最佳实践： 永远不要在共享的 providers.yaml 中硬编码 token。优先使用 Raycast 的安全字段或 macOS Keychain；如果你使用本地代理，也可以通过环境变量在本地注入密钥。如果涉及敏感数据，请阅读 CometAPI 和 Raycast 的隐私文档。

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

成本控制： 积极利用模型选择：短任务使用轻量模型，复杂推理使用高能力模型。在 CometAPI 仪表板中跟踪用量并设置预算提醒。还可以通过更高效的提示来减少 token 消耗（例如更短的 system message、更高效的上下文管理）。

提示工程与用户体验： 在创建 Raycast AI Commands（复制内置命令并调整提示词）时，实用型命令（摘要、分类、搜索）的提示应尽量保持确定性，而头脑风暴类工作流可以更开放。推荐的方式是复制内置命令并自定义提示。

如何排查常见问题？

模型没有出现在 Raycast 中：确认 Raycast 的 providers.yaml 位于 Reveal Providers Config 显示的确切文件夹中。以模板为基准，并重启 Raycast。重启或“Refresh Models”通常会有帮助。

401 / token 无效：确认你的 CometAPI token 有效且未过期。尝试上文提到的 curl 测试。再次检查你使用的是 Bearer token，并确保 Authorization header 正确。

模型错误或响应格式不兼容：CometAPI 目标是兼容 OpenAI，但某些边缘情况仍可能存在（模型 ID、流式传输行为等）。如果 Raycast 期望特定的流式格式，而 CometAPI 输出略有差异，请先尝试非流式调用；如有需要，请联系 CometAPI 支持。

结论

CometAPI 为你提供统一的多厂商模型访问能力（文本、图像、音频、视频），并让团队可以集中管理计费和路由。Raycast 则为你提供一个即时、键盘优先的入口，可在桌面工作流上下文中调用这些模型。两者结合，让模型实验和桌面自动化变得顺畅无阻——你可以根据成本或质量切换模型，将密钥保留在本地，并继续使用你在脚本和应用中已经熟悉的 OpenAI 风格模式。

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

准备好开始了吗？→ 今天就在 Raycast 中使用 CometAPI！

如果你想了解更多 AI 技巧、指南和新闻，欢迎在 VK、X 和 Discord 上关注我们！