接入软件
Raycast AI(Custom Providers)
在 providers.yaml 里加一个 OpenAI 兼容提供方(需要 Raycast Pro)。
约 6 分钟适合:用 Raycast 的 Mac / Windows 用户
开始之前
- Raycast Pro 订阅(官方:自定义提供方是 Pro 专属功能)
- 一把 Key 和一个模型名
步骤 1 · STEP 0x01
打开 providers.yaml
Settings → AI → Models & Providers → Custom Providers
1
Reveal Providers Config
文件位置
~/.config/raycast/ai/providers.yaml(先把 providers.template.yaml 复制一份)
进入 Settings → AI → Models & Providers,在 Custom Providers 一节点 Reveal Providers Config,把目录里的 providers.template.yaml 复制为 providers.yaml。官方强调文件名必须正好是 providers.yaml。
步骤 2 · STEP 0x02
写入提供方和模型
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: <模型名>
name: <模型名>
provider: myrelay
context: 128000
abilities:
tools:
supported: true
vision:
supported: falsebase_url填https://api.suanlimao.shop/v1——官方说明是「OpenAI 兼容端点,不带 /chat/completions 后缀」。api_keys里写的是环境变量名,Key 本身放在环境变量里;每个提供方至少要有一个带id和name的模型。context和abilities(temperature、vision、system_message、tools、reasoning_effort)按模型广场的参数填;字段细节以模板文件为准。
文件会被实时监听,保存即生效,不用重启;写错时 Raycast 会显示「Invalid providers.yaml」,悬停可看原因。
模型名不要自己猜:到「模型广场」点模型卡片上的「复制模型名」,再粘贴到软件里。模型名写错是最常见的报错原因。
步骤 3 · STEP 0x03
设置 Key 并在 AI Chat 里选模型
bash
export MYRELAY_API_KEY=<你的 Key>terminal
$ export MYRELAY_API_KEY=<你的 Key>- 环境变量名要与
api_keys里写的一致;写进 shell 配置后重新启动 Raycast。 - 打开 AI Chat,在模型选择里找到你的提供方名下的模型。
官方限制:自定义模型请求直接从你的设备发到提供方,不消耗 Raycast 额度,但不支持 Cloud Sync、不能用于图片生成;公司托管的配置会覆盖本地文件。
完整 Key 只在创建时显示一次,关闭页面就看不到了。没来得及保存?吊销它,再创建一把新的。
✓ 怎么确认成功了
- AI Chat 里能用你的模型回答;控制台「用量」页出现请求。
常见问题
显示 Invalid providers.yaml?
悬停看具体错误。常见原因:文件名不对、缩进错误、某个提供方没有模型或模型缺 id / name。
返回 401?
环境变量没设或没生效(Raycast 要在设置变量后重启);官方建议先用 curl 对地址测一遍。
相关教程
还是不行?
先看排错教程;仍然解决不了,提交工单时附上 request_id、时间、模型和报错原文(不要贴 Key)。