Cómo conectar claves API personalizadas y suscripciones externas a Raycast sin consumir AI Credits

Para los desarrolladores que utilizan Raycast como su lanzador de comandos principal en macOS, la cuota mensual de créditos de inteligencia artificial introducida en Raycast v2 suele convertirse en un molesto cuello de botella. La estructura oficial de Raycast asigna 500 créditos mensuales en el plan Pro, 3.000 en Pro+ y 7.500 en Max. Al invocar Quick AI decenas de veces al día pulsando Tab desde la barra de búsqueda para depurar código, generar expresiones regulares o consultar modelos avanzados de razonamiento, esa asignación puede agotarse a mitad del mes.

Si ya pagas 20 dólares al mes por una suscripción a ChatGPT Plus o Claude Pro, o si mantienes saldos de desarrollo en Anthropic Console, OpenAI Platform, Google AI Studio u OpenRouter, no necesitas comprar paquetes de recarga (Top-ups) ni pagar suscripciones duplicadas.

Raycast incluye de forma nativa tres mecanismos de integración conocidos como "Bring Your Own AI" que permiten canalizar las consultas a través de tus cuentas existentes sin descontar un solo crédito del saldo mensual de Raycast.

Comparativa de los tres métodos de integración sin consumo de créditos

Antes de abrir los ajustes de la aplicación, evalúa cuál de las siguientes opciones se adapta mejor a tus suscripciones actuales y a tu flujo de trabajo:

Requisito fundamental: Para habilitar cualquiera de estas modalidades externas en Raycast se requiere una suscripción de pago activa a Raycast (como el plan básico Raycast Pro). La versión gratuita (Free) no incluye funciones de IA. Una vez vinculadas en el plan Pro, las consultas se ejecutan de manera independiente al contador de créditos de Raycast.

Método 1: Conectar suscripciones externas (Claude Pro y ChatGPT Plus)

Para los desarrolladores que ya pagan una tarifa plana de 20 dólares al mes, Bring Your Own Subscription (BYOS) es la alternativa más rentable. No genera cargos adicionales por token y traslada los límites de tu plan web directamente a la interfaz de Raycast.

Funcionamiento interno

Raycast se comunica a nivel local con las herramientas de línea de comandos oficiales de los proveedores: Claude Code para Anthropic y Codex CLI para OpenAI. Al enviar una consulta en Quick AI o AI Chat, el mensaje viaja directamente desde el proceso local de tu máquina a los servidores de Anthropic u OpenAI. Raycast nunca intercepta, almacena ni gestiona tus credenciales de inicio de sesión.

Pasos de configuración

1. Instalar la herramienta de línea de comandos correspondiente
   • Para Claude: Instala Claude Code mediante npm en tu terminal:

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

   • Para ChatGPT: Instala Codex CLI o asegúrate de tener instalada la aplicación de escritorio de ChatGPT / Codex.
2. Iniciar sesión en la terminal
   • Claude: Ejecuta claude en tu terminal e introduce el comando /login. Completa la autenticación web en el navegador con tu cuenta de Claude Pro o Team.
   • ChatGPT: Ejecuta codex login en tu terminal e inicia sesión con tus credenciales de ChatGPT Plus o Team (asegúrate de usar la cuenta de suscripción y no una clave API).
3. Activar las suscripciones locales en Raycast
   • Abre los ajustes de Raycast con ⌘ , y navega a AI → Models & Providers.
   • Desplázate hasta la sección Local AI Subscriptions y activa el interruptor Enable Local AI Subscriptions.
   • Comprueba que en Claude Account o ChatGPT Account aparezca tu cuenta conectada con su respectivo plan. Si acabas de iniciar sesión en la terminal, haz clic en Refresh account status.
4. Seleccionar los modelos de tu suscripción
   • Pulsa tu atajo de lanzador seguido de Tab para abrir Quick AI, o ingresa a AI Chat.
   • En el selector de modelos, elige aquellos situados bajo las categorías Claude Subscription o ChatGPT Subscription (por ejemplo, Claude 3.7 Sonnet, Claude 3.5 Sonnet, GPT-4o o modelos de la serie o de OpenAI).

Control de cuotas y consumo

Al utilizar modelos vinculados a tu suscripción, se aplican los límites dinámicos fijados por el proveedor (como la ventana móvil de 5 horas de Claude o los límites periódicos de OpenAI), no los créditos de Raycast:

• Escribe /usage en AI Chat para consultar el porcentaje de uso actual y el tiempo restante para el reinicio de tu cuota.
• También puedes ejecutar los comandos Show Claude Usage o Show ChatGPT Usage desde la búsqueda principal de Raycast.

Método 2: Conectar claves API propias (BYOK)

Si prefieres la tarificación por uso exacto de tokens o requieres acceder a los modelos desde la aplicación móvil de Raycast en iOS, Bring Your Own Key (BYOK) es la vía idónea.

Facturación y flujo de datos

• Facturación directa: El consumo se deduce de tu saldo prepago o tarjeta registrada en la consola del proveedor a sus tarifas estándar por millón de tokens. Los AI Credits de Raycast permanecen intactos.
• Enrutamiento: Las solicitudes enviadas mediante una clave de OpenRouter van directamente de tu equipo a OpenRouter. Con Anthropic, OpenAI y Google, las peticiones pasan por los servidores de Raycast para homogeneizar formatos y controlar respuestas, utilizando siempre tu propia clave para la autenticación.
• Catálogo de modelos: Una clave de OpenRouter desbloquea de inmediato todo su catálogo de cientos de modelos (incluyendo DeepSeek-V3, DeepSeek-R1 y pesos abiertos de Meta Llama), sin depender de actualizaciones en Raycast.

Pasos de configuración

1. Obtener la clave API en la consola del proveedor
   • Anthropic: Console → Settings → API Keys
   • OpenAI: Platform → API Keys
   • Google: Google AI Studio → Get API Key
   • OpenRouter: Account Settings → Keys
2. Configuración en el escritorio (macOS / Windows)
   • Entra en Settings → AI → Models & Providers.
   • En la sección API Keys, haz clic en el botón + (Plus).
   • Selecciona el proveedor en el menú desplegable, pega tu clave y haz clic en Verify. Una vez validada, pulsa Save.
3. Configuración en iOS
   • En Raycast para iOS, pulsa en tu Avatar de cuenta → AI → Custom API Keys.
   • Selecciona el proveedor, introduce tu clave y pulsa Verify.

Indicador visual de clave activa

En la lista de selección de modelos, aquellos que funcionen mediante tu propia clave API mostrarán un icono de llave (Key icon) junto a su nombre. Mientras selecciones un modelo con este distintivo, no se descontarán créditos de tu cuenta de Raycast.

Método 3: Proveedores personalizados con providers.yaml (Proxies y LLMs locales)

Para arquitecturas corporativas o configuraciones técnicas avanzadas —como enrutar tráfico a través de un proxy compartido con LiteLLM, usar pasarelas como Vercel AI Gateway o AWS Bedrock, o ejecutar modelos locales sin conexión con LM Studio—, Raycast admite cualquier endpoint compatible con la especificación OpenAI API mediante un archivo YAML.

Pasos de configuración

1. Abre Raycast Settings → AI → Models & Providers.
2. Desplázate hasta Custom Providers y pulsa en Reveal Providers Config.
3. Se abrirá la carpeta ~/.config/raycast/ai/ en el Finder, donde encontrarás providers.template.yaml.
4. Duplica la plantilla y renómbrala como providers.yaml en esa misma carpeta.
5. Edita el archivo con la definición de tus proveedores y modelos.

Ejemplo para Vercel AI Gateway:

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

Ejemplo para un servidor local de LM Studio (completamente gratuito y privado):

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. Al guardar los cambios, Raycast recarga la configuración de manera automática. Tus nuevos modelos estarán disponibles de inmediato en Quick AI y AI Chat.

Consideraciones críticas y resolución de problemas

Antes de completar la integración, ten en cuenta los siguientes detalles operativos:

1. El plan Raycast Pro es un requisito indispensable La versión gratuita Raycast Free no incluye capacidades de IA, por lo que no permite activar BYOK ni suscripciones externas. Sin embargo, mantener el plan de entrada Raycast Pro junto a tu suscripción de Claude Pro o ChatGPT Plus resulta mucho más económico que contratar los niveles Pro+ o Max de Raycast.
2. Las herramientas en la nube de Raycast pueden consumir créditos Las conversaciones de texto, la asistencia con código y la lectura de páginas web no consumen créditos cuando usas suscripciones o claves externas. No obstante, herramientas que dependen exclusivamente de la infraestructura de Raycast (como la generación nativa de imágenes) continuarán utilizando modelos propietarios y deducirán créditos mensuales.
3. Límites de frecuencia del proveedor frente a créditos agotados Si recibes un error de límite de solicitudes al utilizar una suscripción externa, se debe a las restricciones horarias de OpenAI o Anthropic. Comprar créditos en Raycast no solucionará este bloqueo. Consulta /usage para ver cuándo se restablece la ventana o cambia temporalmente a un modelo configurado con BYOK.
4. Reconocimiento del PATH en macOS Si Raycast indica que no encuentra Claude Code o Codex CLI, comprueba que las herramientas estén en rutas habituales. Raycast analiza la variable PATH, las rutas de Homebrew (/opt/homebrew/bin en Apple Silicon), los binarios globales de npm y ~/.local/bin. Tras comprobar que el comando responde en la terminal, reinicia Raycast.

Al canalizar tus tareas de inteligencia artificial hacia tus propias suscripciones o claves API, conservas la inmediatez y potencia del teclado en macOS mientras eliminas los costes duplicados y la preocupación por el límite de créditos.

Referencias

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