Suanlimao
← Back to all tutorials

Connect your tools

Raycast AI (Custom Providers)

Add an OpenAI-compatible provider in providers.yaml (requires Raycast Pro).

About 6 minFor:Mac and Windows users of Raycast

Before you start

  • A Raycast Pro subscription (custom providers are Pro-only per the docs)
  • A key and a model name

Step 1 · STEP 0x01

Open providers.yaml

Settings → AI → Models & Providers → Custom Providers
1
Reveal Providers Config

File location

~/.config/raycast/ai/providers.yaml (copy providers.template.yaml first)

Diagram only — the real screen in your version may differ

Go to Settings → AI → Models & Providers, click Reveal Providers Config under Custom Providers and copy providers.template.yaml to providers.yaml. The docs stress the file must be named exactly providers.yaml.

Step 2 · STEP 0x02

Write the provider and model

terminal
$ cd ~/.config/raycast/ai$ cp providers.template.yaml providers.yaml
yaml
providers:
  - id: myrelay
    name: My relay
    base_url: https://api.suanlimao.shop/v1
    api_keys:
      myrelay: MYRELAY_API_KEY
    models:
      - id: <MODEL_NAME>
        name: <MODEL_NAME>
        provider: myrelay
        context: 128000
        abilities:
          tools:
            supported: true
          vision:
            supported: false
  • base_url is https://api.suanlimao.shop/v1 — the docs describe it as “an OpenAI-compatible endpoint without the /chat/completions suffix”.
  • api_keys holds environment variable names; the key itself lives in the variable. Each provider needs at least one model with id and name.
  • Fill context and abilities (temperature, vision, system_message, tools, reasoning_effort) from the plaza; see the template file for field details.
The file is watched, so changes apply on save without a restart; on errors Raycast shows “Invalid providers.yaml” — hover for the reason.
Don't guess the model name: open the model plaza, click “Copy model id” on a model card and paste it. A wrong model name is the most common error.

Open the model plaza →

Step 3 · STEP 0x03

Set the key and pick the model in AI Chat

bash
export MYRELAY_API_KEY=<YOUR_API_KEY>
terminal
$ export MYRELAY_API_KEY=<YOUR_API_KEY>
  • The variable name must match api_keys; add it to your shell profile and restart Raycast.
  • Open AI Chat and pick the model under your provider.
Official limits: custom-model requests go straight from your device to the provider and use no Raycast credits, but Cloud Sync is unavailable, image generation is unsupported, and an organisation-managed config overrides the local file.
The full key is shown only once, at creation. Missed it? Revoke it and create a new one.

Create a key →

✓ How to tell it worked

  • AI Chat answers with your model and the Usage page shows the request.

FAQ

“Invalid providers.yaml”?

Hover for the error. Common causes: wrong file name, bad indentation, a provider with no models or a model missing id / name.

401?

The variable is unset or not picked up (restart Raycast after setting it); the docs suggest testing the endpoint with curl first.

Related tutorials

Still stuck?

Read the troubleshooting tutorials first. If that does not help, open a ticket with the request_id, time, model and the exact error (never paste your key).