Configura la autenticación en OpenClaw: Guía de credenciales

¿Alguna vez has pasado horas intentando entender por qué una petición falla a pesar de que tus credenciales parecen correctas? Configurar la autenticación puede ser frustrante cuando el comportamiento de tu aplicación no coincide con lo que esperas, especialmente cuando los errores son crípticos o inconsistentes.

Este documento define la semántica canónica para la resolución y elegibilidad de credenciales que utilizamos en:

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

El objetivo es que el comportamiento en el momento de la selección y durante la ejecución esté siempre alineado.

Códigos de estado estables

• ok
• missing_credential
• invalid_expires
• expired
• unresolved_ref

Credenciales de Token

Las credenciales de token (type: "token") admiten token y/o tokenRef de forma integrada.

Reglas de elegibilidad

1. Un perfil de token no es elegible si faltan tanto token como tokenRef.
2. El campo expires es opcional.
3. Si expires está presente, debe ser un número finito mayor que 0.
4. Si expires no es válido (NaN, 0, negativo, no finito o tiene un tipo incorrecto), el perfil no es elegible y devuelve invalid_expires.
5. Si expires corresponde al pasado, el perfil no es elegible y devuelve expired.
6. El uso de tokenRef no ignora la validación de expires.

Reglas de resolución

1. La semántica del resolver coincide con la semántica de elegibilidad para expires.
2. En los perfiles elegibles, el material del token puede resolverse desde el valor directo o desde tokenRef.
3. Las referencias que no se pueden resolver generan un error unresolved_ref en la salida de models status --probe.

Protección de política OAuth SecretRef

• La entrada SecretRef es solo para credenciales estáticas.
• Si una credencial de perfil es type: "oauth", no admitimos objetos SecretRef para el material de esa credencial.
• Si auth.profiles.<id>.mode es "oauth", rechazamos cualquier entrada keyRef o tokenRef respaldada por SecretRef para ese perfil.
• Las infracciones de esta regla provocan fallos críticos en las rutas de resolución de autenticación al iniciar o recargar.

Mensajería compatible con versiones anteriores

Para mantener la compatibilidad con scripts existentes, los errores de prueba (probe) mantienen esta primera línea sin cambios:

Auth profile credentials are missing or expired.

Podemos añadir detalles más claros para humanos y códigos de estado estables en las líneas siguientes.

---

¿Necesitas ayuda para configurar tus perfiles? Prueba nuestro AI Setup Assistant.

Pasos siguientes

• Guía de configuración de Auth
• Referencia de CLI
• Resolución de problemas comunes