providers.yaml 하나로 Raycast AI에 카탈로그 모델 넣기.

빠른 답: Custom Providers를 활성화하고 파일 하나를 편집하세요.

OpenAI 호환 엔드포인트를 위한 Raycast의 경로는 고급 사용자를 겨냥해 기본적으로 비활성화되어 있는 Custom Providers 기능입니다. Raycast Settings의 AI 섹션 맨 아래에서 이를 활성화하고, Reveal Providers Config로 설정 폴더를 연 다음, 제공되는 providers.template.yaml을 providers.yaml로 복사하세요. 이 파일은 ~/.config/raycast/ai/providers.yaml에 있습니다. 각 프로바이더 항목은 id, 표시 이름, base_url, api_keys 블록을 받습니다; 피커에 넣고 싶은 각 모델은 자신의 id, 표시 이름, 컨텍스트 윈도우를 명시적으로 선언하며, Raycast가 그 모델에 무엇을 요구할 수 있는지 설명하는 abilities 블록도 함께 둡니다. base_url 형태는 내장된 로컬 모델 예제와 같은 관례를 따르며 /v1 루트를 가리키므로, APIsRouter의 값은 https://api.apisrouter.com/v1입니다. 이 파일은 자격 증명을 담고 있으니 다른 시크릿 파일처럼 다루세요.

providers:
  - id: apisrouter
    name: APIsRouter
    base_url: https://api.apisrouter.com/v1
    api_keys:
      default: sk-APIsRouter-...
    models:
      - id: claude-sonnet-4-6
        name: Claude Sonnet 4.6
        context: 200000
        abilities:
          temperature:
            supported: true
          tools:
            supported: true
      - id: claude-haiku-4-5-20251001
        name: Claude Haiku 4.5
        context: 200000
        abilities:
          temperature:
            supported: true

비슷하게 들리지만 다른 Raycast의 두 기능.

Raycast는 여러분의 AI 접근을 가져오는 두 가지 방법을 문서화하는데, 하나를 검색하면 다른 하나가 자꾸 나오므로 이 구분을 명확히 짚어둘 가치가 있습니다. Raycast 매뉴얼의 BYOK 페이지인 Bring Your Own Keys는 여러분 개인의 Anthropic, Google, OpenAI 키(iOS에서는 OpenRouter)를 Raycast AI에 연결합니다. Pro 구독 없이도 작동한다고 문서화된 더 단순한 기능이지만, 커스텀 엔드포인트는 아닙니다: 요청은 API 통합을 위해 Raycast의 서버를 거치며, 매뉴얼은 Raycast AI에 이미 있는 모델만 접근 가능하다고 명시합니다. 게이트웨이 키는 거기에 꽂히지 않습니다, BYOK는 절대 URL을 묻지 않기 때문입니다. Custom Providers는 이 페이지가 설정하는 기능입니다: 여러분 자신의 base_url, 여러분 자신의 키, 여러분 자신이 선언한 모델, 요청이 여러분이 지정한 곳으로 갑니다. 이는 멀티벤더 게이트웨이, 로컬 서버, Raycast의 내장 목록에 없는 어떤 모델을 위한 경로입니다. 그 대가는 명시성입니다: Raycast는 엔드포인트의 모델 목록을 대신 가져오지 않으므로(그 편의는 대기 중인 기능 요청입니다), 피커는 여러분의 YAML이 선언한 것만 정확히 보여줍니다, 그 이상도 이하도 아닙니다.

정직하게 모델 선언하기: id, 컨텍스트, 능력.

자동 발견이 없으므로 YAML은 계약이며, 그 안의 각 필드는 실제 역할을 합니다. 모델 id는 게이트웨이의 /v1/models 목록과 정확히 일치해야 합니다; 이것이 요청에 실려 이동하는 값입니다. name은 Raycast가 보여주는 라벨일 뿐입니다. context 값은 Raycast에게 요청 하나에 얼마나 많은 대화 기록을 담을 수 있는지 알려주므로, 과소평가하면 능력을 낭비하고 과대평가하면 모델이 거부하는 요청을 만듭니다; 선언하는 id의 문서화된 윈도우를 쓰세요. abilities 블록은 사람들이 흔히 잘못 다루는 부분입니다. 이는 Raycast가 각 모델에 무엇을 의존할 수 있는지 선언합니다: temperature 제어, 비전 입력, 시스템 메시지, 툴 사용, 추론 강도. 모델에 없는 능력을 선언하면 깔끔한 오류 대신 Raycast 기능 안에서 헷갈리는 런타임 실패가 발생하고, 실제로 있는 능력을 빠뜨리면 해당 Raycast 동작이 조용히 비활성화됩니다. 최소한으로 시작하세요, AI 확장 기능과 쓸 모델에는 temperature와 tools 정도로, 그런 다음 모델 문서에 대해 확인하며 능력을 추가하세요. 이 파일을 UI에서 관리하도록 특별히 만들어진 커뮤니티 유지 Raycast 확장 기능이 존재하며, 각 변경 전 자동 백업 기능도 있으니, YAML을 직접 다루는 것이 취향이 아니라면 알아둘 가치가 있습니다. 어느 쪽이든, Raycast는 디스크에서 파일을 읽으므로, 편집 후에는 AI 설정에 잠시 시간을 주거나 기능을 껐다 켜서 피커가 현재 파일을 반영하는지 확인하세요.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50
# declare these ids verbatim in providers.yaml

런처를 위한 모델 선택.

선언된 모든 모델이 같은 키로 청구되므로, 비교 루프는 피커 전환입니다: 같은 빠른 커맨드를 두 id로 하루 실행한 다음, 콘솔에서 모델별 지출을 읽고 그 자리를 얻은 쪽을 남기세요.

• 런처 AI는 순간적인 작업입니다: 이것 요약해, 저것 다시 써, 선택 영역 설명해. claude-haiku-4-5-20251001과 gemini-3.5-flash는 창 애니메이션이 끝나기 전에 돌아오는데, 이것이 Raycast 사용자가 기대하는 느낌입니다.
• AI Chat 세션과 긴 초안 작업은 claude-sonnet-4-6이나 gpt-5.5의 값을 합니다; 빠른 티어와 함께 선언하고 작업마다 피커에서 전환하세요.
• 툴을 호출하는 AI 확장 기능은 믿을 만한 툴 사용을 가진 모델이 필요하며, abilities 블록도 그에 맞춰 선언되어야 합니다; claude-sonnet-4-6이 거기서는 안전한 첫 선택입니다.
• deepseek-v4-flash는 손대는 모든 텍스트 필드에 AI를 연결하는 사용자를 위한 물량 선택입니다; 끊임없는 작은 완성이 쌓이며, 빠른 티어가 그 습관을 잔액에서 눈에 띄지 않게 유지해 줍니다.
• 많은 모델을 투기적으로 두기보다 적은 모델을 신중하게 선언하세요: 항목 하나하나가 스크롤을 지나쳐야 하는 피커 행이며, YAML은 다른 id가 필요한 날 쉽게 확장할 수 있습니다.

사용한 만큼 지불 · 공식 요금보다 저렴

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Raycast에 특유한 실패 패턴.

Custom Providers를 의도했는데 BYOK를 설정하는 것이 최상위 실수이며, 여러분의 잘못이 아닙니다: 두 기능이 검색 공간을 공유하기 때문입니다. 진행 중인 플로우가 벤더 키는 물어보지만 URL은 절대 묻지 않는다면, BYOK에 있는 것이고 게이트웨이는 거기 속하지 않습니다. Settings, AI로 돌아가 맨 아래의 Custom Providers 토글을 찾으세요. 파일이 무시되는 경우는 보통 기능 토글이 꺼져 있거나, 파일이 여전히 providers.template.yaml로 이름 붙어 있거나, YAML에 문법 오류가 있어서, Raycast가 로드할 유효한 것이 없는 경우입니다. 이 경우 피커는 단순히 커스텀 모델을 보여주지 않습니다. 더 깊은 것을 의심하기 전에 YAML을 검증하세요. 일부 Raycast 기능에서는 오류가 나는데 다른 기능은 정상인 모델은 능력 불일치입니다: 툴을 능력 없는 모델에 선언했을 때 툴을 쓰는 AI 확장 기능은 실패하는데 일반 채팅은 작동하거나, 능력이 있는 모델에서 아예 선언되지 않았거나. 크기 때문에 거부되는 요청은 과장된 context 값을 가리킵니다. 그리고 플랫폼 경계를 정직하게 유의하세요: Custom Providers는 Mac에서, 로컬 설정 파일로 구성됩니다. 여러분의 Raycast 사용의 일부가 다른 곳에 있다면, 그곳이 이 기능을 무엇을 지원하는지 매뉴얼을 확인한 뒤 동등성을 가정하세요.

어떤 사람들이 게이트웨이를 통해 Raycast AI를 쓰는가.

• 런처에서 살다시피 하며 어떤 모델을 만질 수 있는지 구독이 결정하지 않는 빠른 카탈로그 id로 퀵 AI 커맨드를 쓰고 싶은 파워 유저.
• 이미 에디터와 터미널 도구를 게이트웨이로 라우팅하고 있으며 런처도 같은 키에 두고, 모든 표면에 걸쳐 사용량 로그 하나를 원하는 사람들.
• Raycast의 내장 목록에 없는 모델을 원하는 사용자, DeepSeek와 GLM id도 포함해서, YAML에 한 번 선언하면 앱 어디서든 사용 가능합니다.
• 자신의 확장 기능 뒤에 특정 툴 사용 가능 모델이 필요한, 호스팅된 목록에 좌우되지 않고 id로 고정하는 AI 확장 기능 빌더.
• 특정 벤더의 결제 수단에 접근할 수 없는 개발자. 카드 없이 충전만으로 사용할 수 있어 프로바이더별 가입 의존성이 사라집니다.

엔드포인트 검증 및 첫 커맨드 디버깅.

먼저 모델 curl을 실행해 그 출력에서 id를 YAML로 복사하세요; 기억으로 id를 타이핑하는 것이 여기서 model-not-found 오류의 주된 원인입니다, 그 파일이 Raycast가 가진 유일한 모델 출처이기 때문입니다. 그런 다음 토글을 켜고, 피커가 여러분이 선언한 이름을 보여주는지 확인하고, 빠른 모델로 퀵 AI 커맨드 하나를 실행하세요. 빈 피커는 토글, 파일 이름, 또는 YAML 문법 문제입니다. 인증 오류는 api_keys 블록입니다. Not-found 오류는 방금 curl한 목록과 id가 맞지 않는 것입니다. 채팅에서는 작동하는데 AI 확장 기능에서 실패하는 커맨드는 그 모델의 능력 선언 문제입니다. 커맨드가 흐르기 시작하면 APIsRouter 콘솔에서 요청별 모델, 토큰 수, 지출을 볼 수 있습니다. 런처 AI는 몇 개의 큰 요청이 아니라 수백 개의 작은 요청이며, 사용량 로그는 그 패턴이 모델별, 일별 숫자가 되는 곳입니다, 게이트웨이를 통해 라우팅하는 다른 모든 도구와 같은 페이지에서요.

curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001",
       "messages":[{"role":"user","content":"ping"}]}'

자주 묻는 질문