Raycast AI with a custom OpenAI-compatible endpoint
Raycast is a launcher with an AI layer, and unlike the editors in this cluster it does not ask you to pick a provider from a dropdown. Custom models come from a YAML file that you write and Raycast watches.
The file is unusually well specified, and unusually unforgiving in two places. The base URL must exclude the route, and the abilities block is a declaration of what your model can do rather than a description of it.
https://aicomp.ai/v1).
Create one free →
One local file, and an enterprise file that overrides it
There are two routes into the same system, and they are not additive:
| Route | Where | Effect |
|---|---|---|
| Personal | ~/.config/raycast/ai/providers.yaml | Your own providers, merged with Raycast's built-ins |
| Enterprise | uploaded in the AI Control Center | Replaces any local file, and members cannot add their own |
If your configuration has no effect in a managed environment, the cause is usually the second row: the local file is ignored entirely, not merged. Worth checking before you debug the YAML.
The personal file is watched for changes. Saving it updates the provider list without a restart, which makes iteration fast And means a half-written file is read as soon as you save it.
Invalid YAML does not break your setup. Raycast shows a badge next to the config entry and keeps your previously loaded models working. That is good behaviour, and it is also why a typo can hide: everything appears to work, and only the new provider is missing.
The base URL must not carry the route
Each provider entry takes an OpenAI-compatible base URL, and the manual is explicit that it is the endpoint without the chat completions suffix. Raycast appends the route itself.
This is the same ownership rule as most OpenAI-SDK-based clients, and it is still the most common error, because the value people have on hand, copied out of a provider's docs, is frequently the full request address. A doubled route returns a 404 whose body contains the concatenated path, which is the clue worth reading before you edit anything else.
The abilities block is a promise, not a summary
Every model entry can declare five abilities: temperature, vision, system message, tool use and reasoning effort. Each takes a supported: true or supported: false.
The defaults are the trap:
- Omitted abilities are not neutral. System messages and temperature are assumed supported; vision and tool use are assumed not supported.
- Declaring an unsupported ability makes requests fail. Turning on
toolsfor a model that does not implement tool calling does not degrade gracefully (the request errors). - Without tools, no Raycast tools. Web search, page reading and image search are opt-in, and a model only receives them if it declares
tools: supported: true.
So a model that works perfectly in a curl test can still fail here, because Raycast is sending a system message or a temperature value the endpoint rejects, and the failure names the model, not the abilities line that caused it.
Model identity is two fields, not one
Each entry under a provider has an id and a name, and they serve different masters:
idhas to match the identifier the provider expects on the wire.nameis free text for the picker.provideroptionally selects which alias inapi_keysto use, for a provider that fronts several credentials.
The optional context field is worth setting even when it is not required, because it is what Raycast uses when it decides how much of a conversation to keep. A model with a 200k window declared as 8k will be truncated silently rather than erroring.
Image generation is not available for custom provider models at all That one is a documented limitation rather than a configuration problem, and no amount of abilities editing changes it.
What a launcher session costs
A launcher is an interactive, bursty client: short prompts, short answers, and long idle gaps. That shape is dominated by input tokens, because command-style questions are re-sent with context each time and the answers are one paragraph.
A working month here is about 180k input and 35k output tokens a day, or 3.6M input and 0.7M output across 20 working days. It is the opposite balance from an agent loop, which is why a model chosen for coding agents is rarely the right pick here.
| Model | Gateway rate in / out per 1M tokens | One day | 20 days |
|---|---|---|---|
| claude-sonnet-5 | $1.00 / $5.00 | $0.35 | $7.10 |
| gpt-5.6-sol | $2.5 / $15.00 | $0.97 | $19.50 |
| deepseek-v4-pro | $0.66 / $1.98 | $0.19 | $3.76 |
| qwen3.8-max | $1.00 / $3.00 | $0.29 | $5.70 |
One day = 180k input + 35k output on this page's workload. 20 days = 3.6M input and 0.7M output. Rates checked 2026-10-15, gateway rates move with upstream promotions, so verify the current number in your dashboard before committing to a budget.
For an interactive assistant, latency usually matters more than the per-token rate. The <a href="/guides/cheapest-models-by-workload/">re-ranked index</a> sorts by workload shape rather than by headline price, which is the comparison a bursty client actually needs.
FAQ
FAQ
Does Raycast need the base URL to include the chat completions route?
No, it must exclude it. The provider entry takes the version root, and Raycast appends the operation path. A full request address produces a doubled path and a 404 that echoes the concatenation.
Why did my provider file have no effect?
Check whether an enterprise configuration is uploaded. In a managed organisation it replaces the local file rather than merging with it, and members cannot override it.
My custom model fails but the same endpoint works in curl. Why?
Almost always the abilities block. Raycast assumes system messages and temperature are supported unless you say otherwise, and it assumes tool use and vision are not. Declaring an ability the model lacks makes the request fail rather than degrade.
Can custom models use Raycast's web search?
Only if two things are true: the file has a top-level tools block, and the model declares tool use as supported. Raycast's own tools run on Raycast's servers and require a paid plan.
Do I need to restart Raycast after editing the file?
No. The file is watched, and the provider list refreshes on save. If a new entry is missing, the file is invalid. Raycast keeps the last good model list working and shows an error badge instead.
Related
- Tools that take one endpoint, the full matrix, including which clients want a root and which want a full path
- Base URL not working — the doubled-path failure in general form
- OpenAI-compatible endpoints — the request shape a custom provider has to serve
- Zencoder with a custom endpoint — another YAML-or-JSON provider map with its own silent failure
- LobeChat with a custom endpoint — a chat client configured through a settings screen rather than a file
- Official vs gateway prices — how the two price columns on this site are measured