Raycast AI setup: add custom models


Command	`openllm raycast`
Mode	Persistent. Written to Raycast's config once; reversible.
Talks to	OpenAI-compatible Chat Completions at `<gateway>/v1`
Models	`ultra`, `plus`, `lite`, and every model you have activated
Platform	macOS only
Remove	`openllm raycast uninstall`

Before you begin

Install the OpenLLM CLI on your Mac. See Install.
Install Raycast.
Have at least one model available. See Providers.

Set up with `openllm raycast`

openllm raycast

Raycast runs all the time and reads its config from a fixed path, so OpenLLM cannot attach per session. Instead, the command writes to Raycast's config once:

~/.config/raycast/ai/providers.yaml: adds an openllm provider between the markers # >>> openllm (managed) >>> and # <<< openllm (managed) <<<. It sets base_url to <gateway>/v1, your key under api_keys.default, and one entry per model. Anything outside the markers is left alone.
Raycast preferences (com.raycast.macos): turns on customProviders in aiExperimentalFeatures if it was off, and removes OpenLLM models from aiDisabledModels.
~/.openllm/clients/raycast.json: a record of exactly what it changed, so uninstall can reverse only that.

Then restart Raycast to load the provider.

The command is safe to run again; it replaces the managed block in place. Run it again after you connect a provider or activate models, because Raycast does not discover new models on its own.

The gateway URL is fixed when you run the command: your local daemon at http://127.0.0.1:8787 if it answers, otherwise https://www.openllm.sh. Run openllm raycast again after you start or stop the daemon.

providers.yaml holds your sk-llm key in plain text. When OpenLLM creates the file, only your user can read it; an existing file keeps its permissions. If the file is ever exposed, revoke the key. See If a key leaks.

Choose models

Pick an OpenLLM model in Raycast AI's model picker. The list holds ultra, plus, lite, and every chat model you have activated, with context sizes and capabilities. If the catalog cannot be fetched, only Ultra, Plus, and Lite are added.

To pin a model, choose it by name instead of an alias. To change what the aliases resolve to, edit the chains in Configuration. See Routing and fallback.

Who pays for a request

The model that serves the request decides. Subscription and local models need a running daemon on one of your devices. An API-key hop bills your provider account. Included openllm/ models count against your plan's allowance. See Providers and Plans and limits.

Check that it works

openllm raycast status

This prints one JSON line. "installed": true means the block is in place; api_base shows the gateway and model_count the number of models. Restart Raycast, ask an OpenLLM model something, and check Overview in the app.

Common problems

Symptom	Cause	Fix
No OpenLLM models in Raycast	Raycast has not reloaded	Quit and reopen Raycast
`note: could not update Raycast preferences`	Preferences could not be written	Turn on Custom Providers in Raycast's AI settings yourself
`has an unbalanced OpenLLM managed region — refusing to touch it.`	One marker line was deleted or edited	Remove the leftover marker line, then run the command again
Requests fail after you stop the daemon	The config still points at `127.0.0.1:8787`	Run `openllm raycast` again
New models are missing	The model list is written at setup	Run `openllm raycast` again and restart Raycast
`"stale_ledger": true` in `status`	The block was removed by hand	Run `openllm raycast` or `openllm raycast uninstall`
`openllm raycast is macOS-only.`	You ran it on Linux	Use a Mac

For anything else, see Troubleshooting.

Remove it

openllm raycast uninstall

This removes the managed block from providers.yaml, turns customProviders back off only if OpenLLM turned it on, restores any model entries it removed from aiDisabledModels, and deletes the record. Restart Raycast afterwards.

Last updated on