I want model selection to be part of my desktop workflow, not a reason to open another application. Raycast’s custom providers make that possible: configure an OpenAI-compatible endpoint, supply your own API key, and select a model inside Raycast AI.
For this setup, I’m using CometAPI, a unified gateway exposing hundreds of models through an OpenAI-style REST API. The integration hinges on https://api.cometapi.com/v1, Raycast’s providers.yaml, and a valid token. The main thing to watch is version-specific configuration: use the template shipped with your installed Raycast version.
Decide What You’re Connecting
Raycast is a macOS productivity launcher with commands, scripts, and AI features. Its AI surfaces include Quick AI for launcher prompts, AI Chat for conversations with attachments and context, and AI Commands or extensions for reusable workflows. It also supports local models through Ollama and remote providers through Bring Your Own Key (BYOK) and custom providers.
Raycast added BYOK in v1.100.0, with BYOK and Custom Providers rolling out during 2025. I’d start with a recent release and check Settings → AI for the controls available in that installation.
The gateway’s catalog spans text, images, embeddings, audio, and video, but I would not treat that catalog as a list of capabilities automatically available in Raycast AI. Chat integration and endpoint-specific integrations are different pieces of work.
For code explanation, refactor suggestions, unit tests, PR summaries, and README drafts, the chat path is the relevant starting point. Image generation needs an extension that calls the image endpoint. Semantic search needs an embedding index and a script or cloud function that Raycast can query. Audio support, including TTS and STT, depends on the underlying model; specialized video backends include Sora and Veo.
Check the Prerequisites First
You need macOS, a recent Raycast installation with the relevant custom-provider controls, and an account with a valid gateway API key. Create a token in the provider’s console and keep it out of shared configuration.
Raycast also needs HTTPS access to api.cometapi.com. On a corporate network, check the proxy and firewall before debugging YAML. Terminal and cURL are enough for a basic connectivity check; Python, Node, and OpenAI SDKs are optional tools for more detailed testing. Standard OpenAI-style clients can use the gateway by overriding base_url.
I’d test authentication and model-list access before touching Raycast. With your token already available locally as GATEWAY_API_KEY, this requests the OpenAI-style models endpoint:
curl --fail-with-body --silent --show-error \
'https://api.cometapi.com/v1/models' \
--header "Authorization: Bearer ${GATEWAY_API_KEY}"
This checks that endpoint, not a complete chat workflow. Automatic model discovery still depends on the provider exposing a compatible models response and your Raycast version supporting discovery.
Configure From Raycast’s Own Template
Locate the Configuration
Open Preferences → AI, find Custom Providers or Custom OpenAI-compatible APIs, and choose Reveal Providers Config. Use the directory Raycast reveals rather than guessing a configuration path.
Raycast provides a template, usually named providers.template.yaml. Copy it to providers.yaml in that directory, or edit the existing configuration if you already have custom providers.
The exact schema can differ across releases. Common provider entries include id, name, base_url, and an optional models block, but the installed template should determine their nesting and syntax. I would not paste a supposedly universal YAML example over that template.
Set the Endpoint and Credentials
Add a provider entry using the template’s structure. Give it a distinct identifier and a recognizable display name, then set base_url to https://api.cometapi.com/v1. There is no trailing period in that URL.
Add the token through Raycast’s custom API-key or secure credential fields where supported. Never commit a real token in a shared providers.yaml. macOS Keychain is another option where the integration supports it; environment-variable injection is appropriate for a local proxy you control, not something to assume Raycast’s YAML supports automatically.
You may not need to enumerate every model manually. Raycast can discover models through a properly implemented OpenAI-style GET /v1/models endpoint when that discovery path is supported. Otherwise, follow the template’s model configuration and use exact model identifiers from the provider.
Reload and Run a Small Test
Return to Raycast and refresh models if your version offers that action. If the provider or models do not appear, restart the app.
Open Quick AI, explicitly choose a model from the new provider, and submit a short prompt. I’d keep this first request minimal: it should establish that credentials, model selection, and the response path work before adding attachments, long context, or tools.
Debug the Boundary That Failed
No models in the picker: Check that providers.yaml is in the exact directory opened by Reveal Providers Config. Compare its structure with the installed template, then refresh or restart. If discovery is unavailable, check whether explicit model entries are required.
401 or invalid-token responses: Confirm that the token is valid and has not expired. Run the direct request above and verify that authentication uses Authorization: Bearer …. A failed direct request is a reason to resolve credentials or endpoint access before changing Raycast settings.
Model-specific failures: Verify the model ID first. OpenAI compatibility can still leave differences in response shapes or streaming behavior. If a request fails while streaming, test a non-streaming request directly to narrow the problem, then raise the incompatibility with the provider if needed.
Slow responses: Measure the models you actually intend to use. Gateway routing can introduce variable latency, and a model that works well for a long reasoning task may be a poor choice for an interactive launcher command.
Make the Workflow Worth Keeping
I’d use lightweight, fast models for selected-text summaries, action-item extraction, and short lookups. For deeper reasoning, choose a higher-capacity model; for larger inputs, evaluate context capacity as well. Model selection is a practical cost and latency control, not just a preference.
Track usage in the gateway dashboard and configure budget alerts where available. Shorter system messages and deliberate context management can reduce token use without turning every prompt into an optimization exercise.
For recurring tasks, duplicate a built-in Raycast AI Command and adjust its prompt. Utility commands benefit from predictable instructions and consistent output formats; ideation commands can be more open-ended. Documentation drafting and PR summaries are useful starting points because the output is easy to inspect.
Finally, local credentials do not make remote inference local. Before sending sensitive code, notes, or attachments, read both Raycast’s and the provider’s privacy documentation. I’d keep the initial setup narrow: one tested model, one useful command, and a clear understanding of where the request goes.
Originally published at cometapi.com
Top comments (0)