¿Qué es una API Key y por qué la necesitas para OpenClaw?

Imagínate que OpenClaw es un mensajero (gateway) muy eficiente: recibe tus mensajes de WhatsApp o Telegram, los lleva a una oficina de IA (Gemini, Claude, GPT, etc.), espera la respuesta, y te la trae de vuelta. Pero para entrar a esa oficina de IA necesita mostrar un pase de acceso en la puerta — eso es la API Key.

Sin ese pase, el mensajero llega a la puerta de la oficina, la toca, y le dicen: "¿Quién eres tú? No estás en la lista." — que es exactamente lo que significa este error:

⚠️ Agent failed before reply: No API key found for provider "anthropic"

En términos técnicos, una API Key (llave de API) es un token de autenticación que los proveedores de IA usan para identificar quién hace las peticiones a su servicio, medir el uso, y cobrar en consecuencia. Es el equivalente a tus credenciales de acceso, pero en formato de cadena de texto.

💡 Importante: El error de API Key ocurre después de conectar el canal (WhatsApp/Telegram). El canal puede estar perfectamente vinculado, pero si no hay proveedor de IA configurado, el bot se queda callado o manda el error. Si ya conectaste tus canales y el bot no responde, esto es lo primero que debes revisar.

Proveedores de IA Soportados por OpenClaw 🏪

OpenClaw es agnóstico de proveedor — no está casado con ninguna empresa de IA. Soporta de forma nativa:

• Google Gemini → GEMINI_API_KEY / GOOGLE_API_KEY
• Anthropic (Claude) → ANTHROPIC_API_KEY
• OpenAI (GPT) → OPENAI_API_KEY
• Groq → GROQ_API_KEY
• Mistral → MISTRAL_API_KEY
• OpenRouter → OPENROUTER_API_KEY (agrega muchos más mediante un solo proveedor)
• Ollama → sin API Key, corre local en tu máquina
• Y varios más vía configuración de proveedor custom

¿Cuál recomiendo usar?

Para la mayoría de los casos personales: Google Gemini. Las razones:

1. Free tier generoso: Google AI Studio ofrece cuota gratuita real para uso personal — suficiente para un bot de uso moderado sin pagar un peso.
2. Contexto enorme: Gemini 2.5 Flash tiene 1 millón de tokens de contexto. En lenguaje de calle: puede recordar conversaciones kilométricas sin perder el hilo.
3. Velocidad: Gemini Flash es notablemente rápido para respuestas en chat.
4. Fácil de conseguir: Basta con ir a aistudio.google.com y generar la llave — sin esperas ni aprobaciones.

Si necesitas el mejor razonamiento para tareas de código complejas, Claude (Anthropic) es el gold standard en ese terreno, pero tiene costo desde el inicio. OpenRouter es excelente si quieres experimentar con muchos modelos con una sola API Key.

Los 3 Métodos para Configurar tu API Key 🔧

Usaremos Gemini como ejemplo en todos los métodos, pero el proceso es idéntico para cualquier proveedor.

Método 1: Re-hacer el Onboarding (el más limpio) ✅

Este es el método recomendado si estás configurando por primera vez o quieres cambiar de proveedor completamente. El wizard interactivo te lleva de la mano sin tocar ningún archivo.

openclaw onboard

El wizard te preguntará:

> Model/auth provider → selecciona: Google
> Google auth method → selecciona: Google Gemini API Key
> Enter Gemini API Key → pega tu llave aquí
> Default model → google/gemini-2.5-flash (recomendado)

Si quieres saltarte el wizard y hacerlo en una línea (el comando one-liner, el azúcar sintáctica del CLI):

openclaw onboard --auth-choice apiKey --token-provider google --token "TU_GEMINI_API_KEY_AQUI"

Y para establecer el modelo por defecto después:

openclaw models set google/gemini-2.5-flash

Método 2: Variable de Entorno (el estilo "developer pro") 🧑‍💻

Las variables de entorno son la forma más limpia de manejar credenciales — nunca tocan archivos de configuración que podrías committear accidentalmente a un repositorio (el clásico error que convierte código spaghetti en código kamikaze).

Agrega a tu ~/.bashrc o ~/.zshrc:

export GEMINI_API_KEY="tu-api-key-aqui"

Aplica los cambios sin cerrar la terminal:

source ~/.bashrc

Reinicia OpenClaw para que tome la variable:

docker compose down && docker compose up -d --force-recreate

OpenClaw detecta automáticamente GEMINI_API_KEY (y también GOOGLE_API_KEY como fallback) al arrancar, sin necesidad de configuración adicional.

🐳 Si usas Docker: las variables de entorno van en tu docker-compose.yml o en un archivo .env en el mismo directorio. Nunca hardcodees la key directamente en el docker-compose.yml si ese archivo está en un repositorio.

Método 3: Editar el auth-profiles.json (el "cirujano de archivos") 🔬

Este es el método quirúrgico — útil si ya tienes OpenClaw corriendo y solo quieres agregar o cambiar la key sin reiniciar el wizard completo. El archivo que menciona el error es exactamente al que vamos a ir:

nano /home/node/.openclaw/agents/main/agent/auth-profiles.json

O si tienes instalación Docker:

nano ~/openclaw/data/openclaw.json

Busca la sección de env o models y agrega tu key:

{
  "env": {
    "GEMINI_API_KEY": "tu-api-key-aqui"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-2.5-flash"
      }
    }
  }
}

Guarda y reinicia el gateway. Este método es el más directo pero también el más propenso a errores de sintaxis JSON — un símbolo mal puesto y el gateway no arranca (el clásico bug que no es bug, es un error de parseo 😅).

Verificar que la API Key está funcionando ✅

Después de configurar cualquier método, puedes verificar los modelos disponibles:

openclaw models list

O en Docker:

docker exec openclaw-gateway node dist/index.js models list

Deberías ver los modelos de Gemini listados y marcados como disponibles. Luego mándate un mensaje de prueba a WhatsApp o Telegram — si el bot responde, estás listo.

Tips para Gestionar API Keys 🛡️

El mayor pecado en el mundo de las API Keys es tratarlas como texto cualquiera. Aquí van los mandamientos:

• No las comittees al repositorio. Punto. Si usas Git (sistema de control de versiones), agrega siempre un .gitignore que excluya tu .env y cualquier archivo con credenciales. GitHub tiene bots que escanean repositorios públicos buscando API Keys filtradas y las revocan automáticamente — es humillante y peligroso a la vez.
• Rota tus llaves regularmente. Cada 3-6 meses, genera una nueva key en Google AI Studio, actualiza tu config, y revoca la anterior. Es como cambiar la contraseña del WiFi — incómodo pero necesario.
• Una llave por entorno. Si tienes un servidor de producción y uno de pruebas, usa llaves diferentes. Así si algo sale mal en desarrollo, no afecta producción.
• Guárdalas en un gestor de contraseñas. 1Password, Bitwarden, lo que uses — las API Keys van ahí, no en un notas.txt del escritorio.

Alertas y Límites de Gasto 💸

Esto aplica principalmente si usas un proveedor de pago (Anthropic, OpenAI, Gemini de pago). La pesadilla de cualquier developer es abrir el correo y encontrar una factura de $300 dólares porque el bot se fue en bucle infinito.

En Google AI Studio (Gemini):

• Ve a console.cloud.google.com → Billing → Budgets & Alerts
• Crea una alerta al 50%, 80% y 100% de tu presupuesto mensual
• Google te manda un email antes de que explote la factura

En Anthropic (Claude):

• Ve a console.anthropic.com → Settings → Billing
• Configura un spend limit mensual — Anthropic corta el acceso si lo superas (preferible a la factura sorpresa)

En OpenAI:

• Misma lógica: Settings → Billing → Usage limits

Tip general: Empieza con un modelo lite o flash (e.g. gemini-2.5-flash-lite) en lugar del modelo más potente. Para chat cotidiano la diferencia es mínima, pero el costo puede ser 10x menor. Reserva el modelo pesado para tareas que realmente lo necesiten.

Recursos

• Google AI Studio (consigue tu Gemini Key): aistudio.google.com
• Documentación de proveedores OpenClaw: docs.openclaw.ai/concepts/model-providers
• OpenRouter (un proveedor, muchos modelos): openrouter.ai