Autenticación

OpenClaw soporta OAuth y claves API para proveedores de modelos. Para hosts de gateway siempre activos, las claves API suelen ser la opción más predecible. Los flujos de suscripción/OAuth también están soportados cuando coinciden con el modelo de tu cuenta del proveedor.

Consulta /concepts/oauth para el flujo OAuth completo y la estructura de almacenamiento. Para autenticación basada en SecretRef (proveedores env/file/exec), consulta Gestión de secretos. Para las reglas de elegibilidad/código de razón de credenciales usadas por models status --probe, consulta Semántica de credenciales de autenticación.

Configuración recomendada (clave API, cualquier proveedor)

Si ejecutas un gateway de larga duración, comienza con una clave API para el proveedor que hayas elegido. Para Anthropic específicamente, la autenticación por clave API es la opción segura y se recomienda sobre la autenticación por setup-token de suscripción.

  1. Crea una clave API en la consola de tu proveedor.
  2. Colócala en el host del gateway (la máquina que ejecuta openclaw gateway).
export <PROVIDER>_API_KEY="..."
openclaw models status
  1. Si el Gateway se ejecuta bajo systemd/launchd, es preferible colocar la clave en ~/.openclaw/.env para que el daemon pueda leerla:
cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

Después reinicia el daemon (o reinicia tu proceso Gateway) y vuelve a verificar:

openclaw models status
openclaw doctor

Si prefieres no gestionar variables de entorno tú mismo, el asistente de incorporación puede almacenar claves API para uso del daemon: openclaw onboard.

Consulta Ayuda para detalles sobre herencia de entorno (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: setup-token (autenticación por suscripción)

Si usas una suscripción de Claude, el flujo de setup-token está soportado. Ejecútalo en el host del gateway:

claude setup-token

Luego pégalo en OpenClaw:

openclaw models auth setup-token --provider anthropic

Si el token fue creado en otra máquina, pégalo manualmente:

openclaw models auth paste-token --provider anthropic

Si ves un error de Anthropic como:

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

…usa una clave API de Anthropic en su lugar.

Advertencia: El soporte de setup-token de Anthropic es solo compatibilidad técnica. Anthropic ha bloqueado cierto uso de suscripción fuera de Claude Code en el pasado. Úsalo solo si decides que el riesgo de política es aceptable, y verifica los términos actuales de Anthropic tú mismo.

Entrada manual de token (cualquier proveedor; escribe auth-profiles.json + actualiza la configuración):

openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter

Las referencias de perfil de autenticación también están soportadas para credenciales estáticas:

  • Las credenciales api_key pueden usar keyRef: { source, provider, id }
  • Las credenciales token pueden usar tokenRef: { source, provider, id }

Verificación compatible con automatización (exit 1 cuando expirado/faltante, 2 cuando está por expirar):

openclaw models status --check

Los scripts opcionales de operaciones (systemd/Termux) están documentados aquí: /automation/auth-monitoring

claude setup-token requiere un TTY interactivo.

Verificar el estado de autenticación del modelo

openclaw models status
openclaw doctor

Comportamiento de rotación de claves API (gateway)

Algunos proveedores soportan reintentar una solicitud con claves alternativas cuando una llamada API alcanza un límite de tasa del proveedor.

  • Orden de prioridad:
    • OPENCLAW_LIVE_<PROVIDER>_KEY (sustitución única)
    • <PROVIDER>_API_KEYS
    • <PROVIDER>_API_KEY
    • <PROVIDER>_API_KEY_*
  • Los proveedores de Google también incluyen GOOGLE_API_KEY como respaldo adicional.
  • La misma lista de claves se deduplica antes de usarse.
  • OpenClaw reintenta con la siguiente clave solo para errores de límite de tasa (por ejemplo 429, rate_limit, quota, resource exhausted).
  • Los errores que no son de límite de tasa no se reintentan con claves alternativas.
  • Si todas las claves fallan, se devuelve el error final del último intento.

Controlar qué credencial se usa

Por sesión (comando de chat)

Usa /model <alias-o-id>@<profileId> para fijar una credencial de proveedor específica para la sesión actual (ejemplos de ids de perfil: anthropic:default, anthropic:work).

Usa /model (o /model list) para un selector compacto; usa /model status para la vista completa (candidatos + siguiente perfil de autenticación, más detalles del endpoint del proveedor cuando está configurado).

Por agente (sustitución CLI)

Establece un orden de perfil de autenticación explícito para un agente (almacenado en el auth-profiles.json de ese agente):

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

Usa --agent <id> para apuntar a un agente específico; omítelo para usar el agente predeterminado configurado.

Solución de problemas

”No credentials found”

Si el perfil de token de Anthropic falta, ejecuta claude setup-token en el host del gateway, y luego vuelve a verificar:

openclaw models status

Token por expirar/expirado

Ejecuta openclaw models status para confirmar qué perfil está por expirar. Si el perfil falta, vuelve a ejecutar claude setup-token y pega el token de nuevo.

Requisitos

  • Cuenta de suscripción de Anthropic (para claude setup-token)
  • Claude Code CLI instalado (comando claude disponible)
arrow_back
Anterior
Configuration Examples
Siguiente
Auth Credential Semantics
arrow_forward