Raycast에 커스텀 API 키와 외부 구독을 연동하여 AI 크레딧 소진 없이 모델을 사용하는 방법

macOS 환경에서 Raycast를 핵심 런처로 사용하는 개발자들에게 Raycast v2부터 도입된 'AI 크레딧(AI Credits)' 한도는 작업 흐름을 끊는 주된 요인이 되곤 합니다. 공식 요금제 기준으로 Raycast Pro는 월 500 크레딧, Pro+는 3,000 크레딧, Max는 7,500 크레딧을 제공합니다. 그러나 검색창에서 Tab 키로 Quick AI를 실행하여 터미널 명령어를 조회하거나, 코드 리팩터링 및 정규표현식을 생성하고, 긴 컨텍스트의 최신 추론 모델을 자주 호출하다 보면 월 중순에 크레딧이 조기 소진되기 십상입니다.

이미 매달 20달러의 ChatGPT Plus나 Claude Pro를 정기 결제하고 있거나, Anthropic Console, OpenAI Platform, Google AI Studio, OpenRouter에 API 잔액을 보유하고 있다면, Raycast의 추가 크레딧 충전(Top-up)을 구매하거나 상위 요금제로 업그레이드하여 비용을 중복 지출할 필요가 없습니다.

Raycast는 자체 AI 크레딧 차감 없이 외부 구독과 API 키를 직접 활용할 수 있는 'Bring Your Own AI' 기능을 공식 지원합니다. 각 연동 방식의 특징과 단계별 설정 방법을 상세히 정리합니다.

크레딧 소진 없는 3가지 연동 방식 비교

설정을 시작하기 전, 본인이 보유한 계정 상태와 사용 목적에 맞는 방식을 선택하십시오.

필수 전제 조건: 외부 구독이나 API 키를 Raycast에 연동하려면 Raycast 유료 플랜(기본 Raycast Pro)이 활성화되어 있어야 합니다. 무료 플랜(Free)에는 AI 엔진 자체가 포함되지 않습니다. Pro 플랜에 외부 구독을 연결하면 Raycast의 월간 크레딧 차감 없이 무제한에 가까운 호출이 가능해집니다.

방법 1: 외부 구독 직결 연동 (Claude Pro 및 ChatGPT Plus)

이미 월 20달러 구독료를 지불하고 있는 개발자에게 가장 경제적인 선택지는 **Bring Your Own Subscription(BYOS)**입니다. 토큰별 추가 비용이 발생하지 않으며 웹 구독의 플랫 요금제 한도를 Raycast 런처에서 그대로 활용할 수 있습니다.

동작 원리 및 아키텍처

Raycast는 로컬에 설치된 Anthropic의 공식 CLI 도구인 Claude Code 또는 OpenAI의 Codex CLI와 로컬에서 통신합니다. Quick AI나 AI Chat에서 질문을 입력하면, 프롬프트가 단말의 로컬 데몬을 통해 Anthropic 또는 OpenAI 서버로 직접 전송됩니다. Raycast 서버는 중간에 개입하지 않으며 사용자의 로그인 자격 증명을 열람하거나 저장하지 않습니다.

단계별 설정 절차

1. 프로바이더 공식 CLI 설치
   • Claude 사용자: 터미널에서 npm을 통해 Claude Code를 전역 설치합니다.

     npm install -g @anthropic-ai/claude-code
     

   • ChatGPT 사용자: Codex CLI를 설치하거나 시스템에 ChatGPT 데스크톱 앱/Codex 앱이 정상 설치되어 있는지 확인합니다.
2. 터미널에서 로그인 인증 완료
   • Claude: 터미널에서 claude를 실행한 후 /login 명령어를 입력하고 브라우저에서 Claude Pro/Team 계정 로그인을 진행합니다.
   • ChatGPT: 터미널에서 codex login을 실행하고 ChatGPT Plus/Team 계정으로 로그인합니다(API 키가 아닌 구독 계정으로 로그인해야 합니다).
3. Raycast에서 로컬 AI 구독 활성화
   • Raycast 환경설정(⌘ ,)을 열고 AI → Models & Providers로 이동합니다.
   • Local AI Subscriptions 항목을 찾아 Enable Local AI Subscriptions 토글을 켭니다.
   • 아래 목록의 Claude Account 또는 ChatGPT Account 행에 계정 및 플랜 정보가 표시되는지 확인합니다. 방금 터미널에서 인증했다면 Refresh account status를 클릭합니다.
4. 구독 전용 모델 선택
   • 단축키 후 Tab 키로 Quick AI를 열거나 AI Chat을 실행합니다.
   • 모델 선택 메뉴에서 Claude Subscription 또는 ChatGPT Subscription 그룹 아래의 모델(Claude 3.7 Sonnet, Claude 3.5 Sonnet, GPT-4o, OpenAI 추론 모델 등)을 선택합니다.

사용량 및 할당량 확인

구독 모델은 Raycast 크레딧이 아닌 프로바이더의 롤링 제한(Claude의 5시간 사용량 창, OpenAI의 빈도 제한)을 따릅니다:

• AI Chat 입력창에 /usage를 입력하면 현재 시간대의 사용량 비율과 리셋 남은 시간을 바로 확인할 수 있습니다.
• 루트 검색에서 Show Claude Usage 또는 Show ChatGPT Usage 명령어를 실행하여 확인할 수도 있습니다.

방법 2: 자체 API 키 등록 (BYOK)

토큰당 과금(Pay-as-you-go) 방식을 선호하거나 iPhone/iPad 등 iOS 모바일 단말에서도 동일한 환경을 유지하고 싶다면 Bring Your Own Key(BYOK) 방식이 적합합니다.

과금 및 네트워크 동작

• 직접 과금: 추론 비용은 해당 API 제공업체 콘솔에 등록된 카드나 선불 잔액에서 토큰 단위로 직접 결제됩니다. Raycast AI 크레딧은 전혀 소진되지 않습니다.
• 라우팅: OpenRouter 키를 등록한 경우 모든 요청이 로컬 단말에서 OpenRouter로 직통 전송됩니다. Anthropic, OpenAI, Google의 경우 통일된 API 스펙 처리와 폴백 보장을 위해 Raycast 서버를 경유하지만, 인증은 사용자가 입력한 개인 키로 수행됩니다.
• 방대한 모델군: OpenRouter 키를 연동하면 Raycast의 기본 탑재 모델뿐 아니라 OpenRouter가 호스팅하는 수백 가지 최신 모델(DeepSeek-V3, DeepSeek-R1, Meta Llama 계열 등)을 즉시 이용할 수 있습니다.

단계별 설정 절차

1. 공급사 콘솔에서 API 키 발급
   • Anthropic: Console → Settings → API Keys
   • OpenAI: Platform → API Keys
   • Google: Google AI Studio → Get API Key
   • OpenRouter: Account Settings → Keys
2. 데스크톱(macOS / Windows) 설정
   • Raycast Settings → AI → Models & Providers로 이동합니다.
   • API Keys 섹션에서 + (Plus) 버튼을 클릭합니다.
   • 프로바이더를 선택하고 API 키를 붙여넣은 뒤 Verify를 클릭하여 유효성을 검증하고 Save를 누릅니다.
3. iOS 모바일 설정
   • Raycast iOS 앱에서 우측 상단 프로필을 탭하고 AI → Custom API Keys로 진입합니다.
   • 해당 업체를 선택한 뒤 키를 입력하고 Verify를 완료합니다.

정상 연결 확인

모델 목록에서 자체 API 키가 활성화된 모델 옆에는 **열쇠 아이콘(Key icon)**이 표시됩니다. 이 열쇠 아이콘이 붙은 모델을 사용하는 동안에는 매월 지급되는 500 / 3,000 / 7,500 Raycast 크레딧이 완벽하게 보존됩니다.

방법 3: providers.yaml을 통한 커스텀 프로바이더 설정

팀 단위 공유 프록시(LiteLLM), 다중 모델 통합 게이트웨이(Vercel AI Gateway, Cloudflare AI Gateway), 클라우드 기반 파운데이션 모델(AWS Bedrock), 또는 로컬 머신에서 구동하는 오픈소스 모델(LM Studio, Ollama)을 연동해야 할 경우, Raycast는 YAML 기반의 OpenAI 호환 커스텀 설정을 지원합니다.

설정 방법 및 예시

1. Raycast Settings → AI → Models & Providers를 엽니다.
2. Custom Providers 항목으로 스크롤하여 Reveal Providers Config를 클릭합니다.
3. Finder에 ~/.config/raycast/ai/ 폴더가 열리며 공식 템플릿인 providers.template.yaml이 나타납니다.
4. 해당 템플릿을 동일 폴더 내에 복사하고 파일명을 providers.yaml로 변경합니다.
5. providers.yaml 파일을 편집하여 엔드포인트와 모델을 선언합니다.

Vercel AI Gateway 연동 예시:

providers:
  - id: vercel_gateway
    name: "Vercel AI Gateway"
    base_url: https://ai-gateway.vercel.sh/v1
    api_keys:
      vercel: YOUR_GATEWAY_API_KEY
    models:
      - id: anthropic/claude-3-7-sonnet
        name: "Claude 3.7 Sonnet"
        context: 200000
        abilities:
          temperature:
            supported: true
          vision:
            supported: true
          system_message:
            supported: true
          tools:
            supported: true
          reasoning_effort:
            supported: true

로컬 오프라인 LM Studio 연동 예시(완전 무료 및 네트워크 유출 제로):

providers:
  - id: lmstudio_local
    name: "LM Studio Local"
    base_url: http://localhost:1234/v1
    models:
      - id: qwen2.5-coder-32b-instruct
        name: "Qwen 2.5 Coder 32B"
        context: 32768
        abilities:
          temperature:
            supported: true
          system_message:
            supported: true

6. 파일을 저장하면 Raycast가 변경 사항을 즉시 자동 반영합니다. Quick AI 및 AI Chat의 모델 선택 드롭다운에 등록된 모델이 즉시 추가됩니다.

핵심 주의사항 및 트러블슈팅

크레딧 소진 없는 환경을 구축할 때 알아두어야 할 주요 사항들입니다:

1. Raycast Pro 플랜 필요 Raycast Free(무료 버전)에는 AI 엔진 접근 권한이 없으므로 BYOK나 BYOS 기능을 활성화할 수 없습니다. 하지만 기본 Raycast Pro 요금제와 기존 Claude Pro/ChatGPT Plus 구독을 결합하는 구성이 상위 Pro+/Max 요금제나 추가 크레딧 구매보다 훨씬 합리적입니다.
2. 서버 호스팅 네이티브 도구의 크레딧 소비 일반 텍스트 질의응답, 코드 작성, 웹 문서 읽기는 외부 구독과 API 키로 완전히 처리됩니다. 단, Raycast 자체 클라우드 인프라에서만 동작하는 일부 기능(예: 자체 AI Image Generation 이미지 생성)은 Raycast의 클라우드 모델을 거치므로 소량의 월간 크레딧이 차감됩니다.
3. 프로바이더 Rate Limit과 크레딧 고갈의 구별 외부 구독 모델 사용 도중 요청 한도 초과 오류가 발생한 경우, 이는 Anthropic이나 OpenAI 자체의 시간당 사용량 제한에 도달한 것입니다. Raycast 크레딧을 구매해도 이 제한은 풀리지 않습니다. /usage를 통해 제한 해제 시간을 확인하거나 임시로 BYOK 모델을 선택하여 작업을 이어가십시오.
4. macOS 환경에서 CLI 도구의 PATH 인식 문제 Raycast에서 Claude Code나 Codex CLI를 찾을 수 없다는 안내가 뜬다면, GUI 앱이 커스텀 셸 환경변수를 불러오지 못한 상태일 수 있습니다. Raycast는 시스템 PATH, Homebrew 기본 경로(Apple Silicon의 /opt/homebrew/bin), npm 전역 bin 폴더, ~/.local/bin을 순차적으로 탐색합니다. 터미널에서 정상 실행을 확인한 후 Raycast를 완전히 종료했다가 다시 실행하십시오.

외부 구독과 자체 API 키를 적극 활용하면 Raycast의 타의 추종을 불허하는 단축키 속도를 누리면서도 월말 크레딧 소진에 대한 압박과 중복 지출 부담을 완전히 없앨 수 있습니다.

참고 자료

• AI | Raycast Manual
• Bring Your Own Subscription | Raycast Manual
• Bring Your Own Key | Raycast Manual
• Custom Providers | Raycast Manual
• AI Credits | Raycast Manual