Como Conectar Chaves de API Personalizadas e Assinaturas Externas ao Raycast Sem Consumir AI Credits

Para desenvolvedores que utilizam o Raycast como lançador central de comandos no macOS, a cota mensal de créditos de inteligência artificial introduzida no Raycast v2 costuma se tornar um gargalo frequente. O modelo oficial estipula 500 créditos mensais no plano Pro, 3.000 no Pro+ e 7.500 no Max. Ao acionar o Quick AI dezenas de vezes ao dia pressionando Tab a partir da barra de busca para revisar código, gerar regex ou consultar modelos de raciocínio com contextos longos, essa franquia pode se esgotar ainda na metade do mês.

Se você já paga 20 dólares mensais por uma assinatura do ChatGPT Plus ou Claude Pro, ou se mantém saldo de desenvolvimento nos consoles da Anthropic, OpenAI, Google AI Studio ou OpenRouter, não é necessário comprar recargas de créditos (Top-ups) nem arcar com assinaturas duplicadas.

O Raycast oferece três mecanismos nativos no modelo "Bring Your Own AI" que permitem direcionar as requisições para suas próprias contas, garantindo consumo zero dos créditos mensais do Raycast.

Comparativo dos três métodos com consumo zero de créditos

Antes de abrir as preferências do sistema, avalie qual modalidade se ajusta melhor às suas assinaturas e ao seu fluxo de trabalho:

Requisito fundamental: Habilitar assinaturas externas, chaves de API ou provedores customizados exige um plano pago ativo do Raycast (como o Raycast Pro básico). A versão gratuita (Free) não inclui recursos de IA. Quando configurado dentro de um plano Pro, as inferências rodam de forma independente do contador de créditos do Raycast.

Método 1: Conectar assinaturas externas (Claude Pro e ChatGPT Plus)

Para quem já possui uma assinatura fixa de 20 dólares por mês, o Bring Your Own Subscription (BYOS) é a opção com melhor relação custo-benefício. Ela não gera cobranças adicionais por token e aproveita os limites do plano web diretamente no Raycast.

Como funciona nos bastidores

O Raycast estabelece comunicação local com os utilitários de linha de comando oficiais: o Claude Code da Anthropic ou o Codex CLI da OpenAI. Ao enviar uma pergunta no Quick AI ou no AI Chat, o prompt é transmitido diretamente do processo local do seu computador para os servidores da Anthropic ou da OpenAI. O Raycast nunca armazena nem tem acesso às suas credenciais de login.

Passo a passo de configuração

1. Instalar a ferramenta de linha de comando correspondente
   • Para Claude: Instale o Claude Code globalmente via npm no terminal:

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

   • Para ChatGPT: Instale o Codex CLI ou garanta que o aplicativo desktop do ChatGPT / Codex esteja presente no sistema.
2. Efetuar login no terminal
   • Claude: Execute claude no terminal e digite o comando /login. Conclua a autenticação OAuth no navegador com sua conta do Claude Pro ou Team.
   • ChatGPT: Execute codex login no terminal e autentique-se com sua conta do ChatGPT Plus ou Team (utilize sua conta de assinatura comum, não uma chave de API de desenvolvedor).
3. Habilitar assinaturas locais no Raycast
   • Abra os ajustes do Raycast (⌘ ,) e vá até AI → Models & Providers.
   • Role até a seção Local AI Subscriptions e ative a chave Enable Local AI Subscriptions.
   • Verifique se as linhas Claude Account ou ChatGPT Account exibem o status conectado e o tipo de plano. Se acabou de autenticar no terminal, clique em Refresh account status.
4. Escolher os modelos da assinatura
   • Abra o Quick AI pressionando o atalho do Raycast seguido de Tab, ou abra o AI Chat.
   • No seletor de modelos, escolha os itens listados sob as seções Claude Subscription ou ChatGPT Subscription (como Claude 3.7 Sonnet, Claude 3.5 Sonnet, GPT-4o ou modelos de raciocínio da OpenAI).

Acompanhamento de limites

Ao utilizar modelos da assinatura, aplicam-se as janelas de uso do próprio provedor (como o limite móvel de 5 horas do Claude ou os limites de taxa da OpenAI), e não os créditos do Raycast:

• Digite /usage dentro do AI Chat para verificar a porcentagem consumida e a contagem regressiva para o reset da janela.
• Você também pode executar os comandos Show Claude Usage ou Show ChatGPT Usage na busca raiz do Raycast.

Método 2: Conectar chaves de API próprias (BYOK)

Caso prefira o modelo de pagamento pós-pago por token ou precise usar os modelos no aplicativo móvel do Raycast no iPhone/iPad, o Bring Your Own Key (BYOK) oferece uma experiência padronizada entre dispositivos.

Faturamento e características de tráfego

• Faturamento direto: O custo das requisições é debitado diretamente no cartão ou saldo pré-pago da sua conta de API junto à provedora, a tarifas de atacado por milhão de tokens. Nenhum crédito do Raycast é descontado.
• Roteamento de rede: Requisições com chaves do OpenRouter vão direto do dispositivo para a infraestrutura do OpenRouter. Para Anthropic, OpenAI e Google, as chamadas passam pelos servidores do Raycast para padronização de parâmetros e fallbacks, mas autenticadas com sua chave individual.
• Catálogo estendido: Uma chave do OpenRouter desbloqueia de imediato todo o catálogo da plataforma (incluindo modelos de peso aberto como DeepSeek-V3, DeepSeek-R1 e Meta Llama), sem precisar esperar que o Raycast os lance oficialmente.

Passo a passo de configuração

1. Obter a chave de API na plataforma de origem
   • Anthropic: Console → Settings → API Keys
   • OpenAI: Platform → API Keys
   • Google: Google AI Studio → Get API Key
   • OpenRouter: Account Settings → Keys
2. Configuração no Desktop (macOS / Windows)
   • Acesse Settings → AI → Models & Providers no Raycast.
   • Na seção API Keys, clique no botão + (Plus).
   • Escolha o provedor no menu, cole sua chave de API e clique em Verify. Após a validação, clique em Save.
3. Configuração no iOS
   • No Raycast para iOS, toque no seu Avatar de Conta → AI → Custom API Keys.
   • Selecione o provedor, insira a chave e toque em Verify.

Indicador visual de uso

No menu de seleção de modelos do Raycast, os modelos que operam via BYOK exibem um ícone de chave (Key icon) ao lado do nome. Enquanto você mantiver selecionado um modelo com esse símbolo, sua cota mensal de 500, 3.000 ou 7.500 créditos permanecerá totalmente preservada.

Método 3: Provedores personalizados com providers.yaml (Proxies e LLMs locais)

Em infraestruturas corporativas ou fluxos avançados —como direcionar chamadas por meio de um proxy compartilhado com LiteLLM, usar gateways como Vercel AI Gateway ou Cloudflare AI Gateway, conectar ao AWS Bedrock ou rodar modelos locais sem internet com o LM Studio—, o Raycast aceita qualquer endpoint compatível com o protocolo OpenAI API por meio de um arquivo YAML.

Configuração prática

1. Abra o Raycast em Settings → AI → Models & Providers.
2. Desça até a seção Custom Providers e clique em Reveal Providers Config.
3. O Finder abrirá a pasta ~/.config/raycast/ai/, contendo o modelo oficial providers.template.yaml.
4. Copie esse arquivo como providers.yaml na mesma pasta.
5. Edite o providers.yaml configurando seus endpoints e modelos.

Exemplo para Vercel AI Gateway:

providers:
  - id: vercel_gateway
    name: "Vercel AI Gateway"
    base_url: https://ai-gateway.vercel.sh/v1
    api_keys:
      vercel: SUA_CHAVE_DE_GATEWAY
    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

Exemplo para um servidor local com LM Studio (sem envio de dados para a internet e custo zero):

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. Salve o arquivo. O Raycast detecta as modificações em tempo real sem exigir reinicialização do aplicativo, tornando os modelos imediatamente acessíveis no Quick AI e no AI Chat.

Regras importantes e solução de problemas

Ao implementar integrações com consumo zero de créditos, mantenha em mente estes aspectos operacionais:

1. Assinatura Raycast Pro é pré-requisito O plano gratuito (Raycast Free) não dá acesso ao módulo de IA e, portanto, não permite ativar BYOK ou BYOS. Combinar o plano Pro básico com uma assinatura existente do Claude Pro ou ChatGPT Plus é a estratégia mais econômica para evitar upgrades caros para os planos Pro+ ou Max.
2. Ferramentas na nuvem do Raycast ainda consomem créditos Perguntas textuais, depuração de código e leitura de links rodam 100% livres de débito de créditos. No entanto, recursos executados nos servidores do Raycast (como a ferramenta nativa de geração de imagens) acionam modelos em nuvem do próprio Raycast e continuam descontando dos créditos mensais.
3. Diferença entre Rate Limit do provedor e saldo zerado Se você receber uma mensagem de limite de requisições excedido ao usar uma assinatura externa, isso reflete a limitação horária da Anthropic ou da OpenAI. Comprar créditos do Raycast não desbloqueia essa restrição. Utilize /usage para checar o horário de liberação ou alterne para um modelo com chave de API (BYOK).
4. Resolução de PATH no macOS Caso o Raycast informe que o Claude Code ou o Codex CLI não foram encontrados, certifique-se de que o executável está em um caminho padrão do sistema. O Raycast analisa o PATH, os diretórios do Homebrew (/opt/homebrew/bin no Apple Silicon), os diretórios globais do npm e ~/.local/bin. Após validar a execução no terminal, reinicie o Raycast.

Ao integrar assinaturas externas ou chaves próprias, desenvolvedores no macOS mantêm a agilidade imbatível dos atalhos do Raycast e eliminam por completo a ansiedade em torno do esgotamento de cotas de créditos.

Referências

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