# Error 401 de OpenClaw: cómo corregir invalid bearer token y missing authentication header

> Un 401 de OpenClaw puede proceder del Gateway, del proveedor del modelo o de Claude CLI. Identifica quién rechaza la conexión y revisa las credenciales que usa el agente o la sesión antes de cambiar tokens.

- URL: https://blog.laozhang.ai/es/posts/openclaw-401-authentication-error
- Published: 2026-04-07
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/es/about)
- Category: Solución de problemas de IA
- Tags: OpenClaw, Error 401, Autenticación, Anthropic, Solución de problemas

---
**Para corregir un error 401 de OpenClaw, empieza por identificar quién lo devuelve.** Si no puedes conectar con el panel, revisa la autenticación del Gateway. Si puedes abrirlo pero el modelo responde con `Authentication failed (provider returned HTTP 401).`, comprueba el proveedor y las credenciales seleccionadas. Si la ejecución usa Claude CLI, revisa el inicio de sesión de Claude Code con el mismo usuario que ejecuta el Gateway.

`invalid bearer token` y `missing authentication header` requieren comprobaciones distintas: el primero indica que el servicio rechazó un token; el segundo, que no recibió la cabecera de autenticación que esperaba. Ninguno demuestra por sí solo que tengas que renovar todas las claves o volver a configurar todos los agentes.

Los procedimientos siguientes corresponden a la documentación consultada el 4 de octubre de 2026. Son pasos de diagnóstico documentados; no se ha realizado una reproducción con credenciales reales ni una llamada de pago para esta guía.

## Identifica el error antes de cambiar credenciales

Busca el mensaje completo en el cliente y en los registros. El token que permite entrar al Gateway, la clave de la API del modelo y el token de un bot de Telegram tienen funciones diferentes.

| Lo que ves | Qué acceso debes revisar | Primera acción |
|---|---|---|
| El panel no conecta; aparece `AUTH_TOKEN_MISSING` o `AUTH_TOKEN_MISMATCH` | Cliente → Gateway | Comprueba el destino y el token compartido del Gateway |
| El modelo devuelve `provider returned HTTP 401` o `invalid bearer token` | OpenClaw → proveedor del modelo, o ejecución nativa seleccionada | Identifica proveedor, cuenta y método de autenticación |
| El proveedor devuelve `missing authentication header` | Petición enviada al proveedor | Comprueba resolución de credenciales, configuración del endpoint y posibles intermediarios |
| Un agente funciona y otro muestra `No API key found` o `No credentials found` | Credenciales y selección del agente afectado | Compara su estado con el de un agente que funcione |
| Claude CLI pide iniciar sesión o devuelve un error de token | Claude Code ejecutado por el Gateway | Consulta `claude auth status --text` como usuario del servicio |

En el equipo donde se ejecuta el Gateway, empieza por estas comprobaciones:

```bash
openclaw --version
openclaw gateway status
openclaw doctor
openclaw models status --agent main
```

Sustituye `main` por el identificador del agente que falla. Añade `--json` si necesitas consultar los detalles estructurados. Estos comandos ayudan a separar estado del servicio y autenticación del modelo; `models status` sin `--probe` **no envía una petición de prueba al modelo**, aunque puede resolver secretos configurados y consultar el estado de autenticación. Así lo distingue la [referencia de la CLI de modelos](https://docs.openclaw.ai/cli/models#read-status-correctly).

Si falla una conversación concreta, ejecuta también `/model status` dentro de ella. La CLI inspecciona la configuración del agente, mientras que la sesión puede tener otro modelo, otro método de ejecución o un perfil fijado explícitamente. Anota el proveedor y modelo reales, el perfil seleccionado, la versión y el usuario del servicio; oculta las claves y tokens cuando compartas registros.

## Si el panel no conecta: token del Gateway y permisos del dispositivo

El token compartido del Gateway autoriza a un cliente a conectarse a OpenClaw. No autentica las llamadas a Anthropic, OpenRouter u otro proveedor de modelos. Cambiar la clave de una API no corrige un `AUTH_TOKEN_MISSING` del panel.

La [guía actual de conexión y autenticación](https://docs.openclaw.ai/gateway/troubleshooting/agent-replies-and-control-ui#auth-detail-codes-quick-map) diferencia estas situaciones:

- **`AUTH_TOKEN_MISSING`:** el cliente no envió el token compartido requerido. En una terminal interactiva del equipo del Gateway, usa `openclaw gateway auth-token --show`, introduce el resultado en el cliente y vuelve a conectar. Mantén ese resultado en tu equipo; no lo publiques en un registro o captura.
- **`AUTH_TOKEN_MISMATCH`:** el token enviado no coincide. Si el error incluye `canRetryWithDeviceToken=true`, permite el reintento de confianza con el token del dispositivo; si persiste, sigue la recuperación de discrepancias indicada en la guía oficial.
- **`AUTH_DEVICE_TOKEN_MISMATCH`:** el token guardado para ese dispositivo está obsoleto o revocado. Revisa su aprobación o rotación, en lugar de cambiar la clave del proveedor.
- **`AUTH_SCOPE_MISMATCH`:** el dispositivo tiene un token reconocido, pero sus permisos no cubren la operación. Debes aprobar los permisos solicitados o volver a emparejarlo; renovar el token compartido no resuelve esa diferencia.
- **`PAIRING_REQUIRED`:** la identidad del dispositivo necesita aprobación. Consulta `openclaw devices list`, revisa qué acceso solicita y aprueba la petición correspondiente con `openclaw devices approve <requestId>`.

La comprobación de éxito es que ese cliente se conecte al Gateway con los permisos necesarios. Después podrás comprobar el modelo por separado. No desactives la autenticación para hacer desaparecer el error.

## Si aparece `invalid bearer token`: renueva el acceso que se está usando

El mensaje significa que el servicio que responde no acepta el token recibido. La causa puede ser caducidad, revocación o selección de una credencial distinta de la que esperabas; el texto por sí solo no identifica cuál. Antes de volver a autenticarte, distingue una clave API, un token guardado por OpenClaw y el inicio de sesión nativo de Claude CLI.

### Clave API del proveedor

Comprueba que la clave corresponde al proveedor y al endpoint seleccionados. Una clave de Anthropic no sirve como token del Gateway ni como clave de un servicio intermediario. Si has cambiado `baseUrl`, confirma también qué servicio espera autenticar esa petición.

En un Gateway que funciona como servicio, una clave exportada en tu terminal puede no estar disponible para `systemd` o `launchd`. La [documentación de autenticación](https://docs.openclaw.ai/gateway/authentication#recommended-setup-api-key-any-provider) indica que la clave debe estar en el equipo del Gateway y ser accesible a su proceso; contempla `~/.openclaw/.env` y la configuración mediante `openclaw onboard`. Revisa el entorno del servicio, configura la clave allí si falta y reinicia el Gateway tras el cambio.

Si el proveedor ha revocado la clave, reemplázala mediante su consola y actualiza la configuración que realmente usa el servicio. Si ya tienes una clave vigente, no la rotes repetidamente mientras otra credencial o un perfil fijado sigue siendo el seleccionado.

### Claude CLI nativo

Ejecuta estas comprobaciones **en el equipo del Gateway y como el usuario que ejecuta su servicio**, con el mismo entorno:

```bash
claude --version
claude auth status --text
```

Si la sesión está ausente o caducada, el procedimiento documentado es:

```bash
claude auth login
openclaw gateway restart
```

El servicio debe encontrar el ejecutable `claude` en su `PATH`. Si utiliza `CLAUDE_CONFIG_DIR`, ese directorio selecciona otro inicio de sesión de Claude: entrar con tu usuario personal o en otro equipo no prueba que el servicio tenga acceso.

En esta modalidad, **Claude Code administra su propio inicio de sesión y la renovación de tokens**. OpenClaw no lee, guarda ni renueva los tokens del inicio de sesión nativo. No los copies a una base de datos de OpenClaw. Estos pasos y límites aparecen en la [guía de Anthropic para OpenClaw](https://docs.openclaw.ai/providers/anthropic#troubleshooting).

### Token o setup-token guardado por OpenClaw

Es una modalidad diferente del inicio de sesión nativo anterior. Revisa qué perfil utiliza el agente y renueva ese acceso mediante el método correspondiente. La [documentación general de autenticación](https://docs.openclaw.ai/gateway/authentication#anthropic-setup-token) mantiene la opción `openclaw models auth login --provider anthropic --method setup-token`; cuando hay varios agentes configurados, añade `--agent` con el identificador afectado. El comando requiere una terminal interactiva.

La guía específica de Anthropic recomienda una clave API para nuevas configuraciones cuando la autenticación mediante token caduca o se revoca. Esto no significa que todos los setup-token hayan dejado de estar soportados. Tampoco basta con ver que un token se ha guardado: la recuperación se confirma cuando funciona una petición por el mismo acceso que fallaba.

## Si aparece `missing authentication header`: comprueba la petición al proveedor

Una cabecera ausente no se corrige necesariamente generando otra clave. El servicio receptor informa de que no recibió la autenticación esperada; todavía tienes que averiguar si faltaba en OpenClaw, si la configuración no permitió resolverla o si un intermediario la eliminó.

1. **Identifica el proveedor y endpoint efectivos.** Consulta el agente con `openclaw models status --agent main` y la sesión con `/model status`. Comprueba que no estás viendo el resultado de un modelo alternativo.
2. **Revisa la procedencia de la credencial.** Busca si se obtiene del entorno, de la configuración o de un perfil guardado. Una referencia a un secreto no demuestra que se haya podido resolver. Si el estado es `indeterminate`, revisa su diagnóstico antes de sustituir la clave.
3. **Comprueba la configuración de la API.** Según la [guía de autenticación](https://docs.openclaw.ai/gateway/authentication#manual-token-entry), `baseUrl`, `api`, identificadores de modelo y cabeceras pertenecen a la configuración del proveedor, no al almacén de perfiles de autenticación. No intentes arreglarlos editando la base de credenciales.
4. **Si empezó tras una actualización, revisa migración y versión.** Conserva el error exacto y compara los resultados antes y después de una corrección controlada. Evita cambiar simultáneamente versión, modelo y clave: dejarías de saber qué cambio influyó.

Hay antecedentes públicos que justifican investigar una regresión cuando la clave y su selección ya se han verificado. En el [issue #51056](https://github.com/openclaw/openclaw/issues/51056), el autor informó de este error con OpenRouter en OpenClaw `2026.3.13` sobre Linux. En el [issue #97934](https://github.com/openclaw/openclaw/issues/97934), otro usuario lo informó en `2026.6.10` sobre macOS y describió una recuperación al volver a `2026.6.1` y ejecutar `doctor --fix`.

Son informes de esos usuarios y versiones. No prueban que la versión que tienes instalada padezca el mismo fallo ni justifican volver hoy a `2026.6.1`. Si necesitas escalar el problema, aporta versión, sistema, proveedor, modelo, perfil sin secretos y el resultado de la comprobación controlada.

## Si solo falla un agente: credenciales compartidas y perfiles locales

En el almacenamiento actual, un agente puede leer credenciales compartidas sin tener una copia propia. La [documentación de OAuth y almacenamiento](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live) distingue, para el directorio de estado predeterminado:

| Almacén | Función |
|---|---|
| `~/.openclaw/state/openclaw.sqlite` | Credenciales compartidas |
| `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite` | Credenciales locales del agente y estado de selección, uso y espera |

`OPENCLAW_STATE_DIR` cambia la raíz utilizada. Un perfil local con el **mismo identificador** tiene prioridad sobre el perfil compartido. Por tanto, un agente puede seguir usando una credencial local obsoleta mientras otro lee la credencial compartida renovada. Si no existe ese perfil local, el agente consulta el almacén compartido; no lo clona.

Compara el agente afectado con uno que funcione:

```bash
openclaw models status --agent main --json
openclaw models status --agent work --json
```

`main` y `work` son ejemplos: usa tus identificadores. Comprueba proveedor, modelo configurado, perfil, origen de las credenciales y estado de disponibilidad. Si existe una sustitución local obsoleta, corrige ese perfil mediante las herramientas de autenticación; no copies tokens OAuth entre agentes ni edites SQLite a mano. Si necesitas una cuenta independiente, configura un inicio de sesión independiente para ese agente.

Las cuentas personales de usuarios tienen registros privados separados. Además, el inicio de sesión nativo de Claude CLI sigue perteneciendo a Claude Code: no aparece automáticamente como una credencial compartida de OpenClaw. La [sección de Anthropic sobre claves ausentes](https://docs.openclaw.ai/providers/anthropic#troubleshooting) confirma que un agente nuevo no necesita otra clave si ya existe un perfil compartido utilizable.

### Tras una actualización: JSON antiguo y `doctor --fix`

`auth-profiles.json`, `auth-state.json` y ciertos `auth.json` antiguos son entradas de migración, no los archivos de credenciales usados actualmente durante la ejecución. Si aparece `AUTH_PROFILE_MIGRATION_REQUIRED`, revisa primero la versión y el diagnóstico de `openclaw doctor`, y conserva una copia de seguridad antes de reparar.

Para formatos admitidos, `openclaw doctor --fix` importa valores verificados a SQLite y archiva el original con una marca de tiempo. No sustituye una credencial almacenada utilizable por un valor antiguo. La excepción es `credentials/oauth.json`: su importador se ha retirado y la [documentación de migración](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live) exige pasar por `2026.9.5` para importar ese archivo antes de instalar la versión más reciente.

Cuando persiste un 401 tras volver a autenticarte después de una actualización, la [guía de actualizaciones y recuperación](https://docs.openclaw.ai/gateway/troubleshooting/updates-and-rollbacks#after-an-update) también indica que `doctor --fix` busca copias OAuth antiguas por agente que ocultan el perfil compartido actual. Úsalo para ese diagnóstico, no como una reparación universal de cualquier 401.

Si un binario antiguo rechaza una configuración escrita por otro más reciente, no borres `meta.lastTouchedVersion` para forzarlo. Una vuelta de versión requiere comprobaciones de compatibilidad o una copia anterior verificada junto con su versión correspondiente.

## Qué autenticación elegir después de recuperar el servicio

![Diferencias entre clave API, setup-token y Claude CLI para el usuario y proceso del Gateway](https://blog.laozhang.ai/posts/es/openclaw-401-authentication-error/img/metodos-autenticacion-comprobables.webp)

Para un servidor que debe seguir funcionando sin una sesión personal abierta, la [guía de autenticación del Gateway](https://docs.openclaw.ai/gateway/authentication) recomienda una clave API como opción más predecible, con facturación explícita del proveedor. Para uso local, reutilizar el inicio de sesión de Claude CLI puede ser adecuado si el ejecutable y la cuenta están disponibles para el usuario del Gateway.

Comprueba también cómo se factura la selección real. La [guía de Anthropic](https://docs.openclaw.ai/providers/anthropic#choose-a-model-route) distingue la API directa de Claude CLI y advierte de que el nombre del proveedor no prueba qué facturación se aplica. Claude CLI puede usar una cuenta con clave API seleccionada explícitamente; elegir un modelo Claude no garantiza que la llamada quede cubierta por una suscripción.

La decisión práctica es conservar un método que puedas identificar, renovar y comprobar en ese equipo. Cambiar de proveedor solo para ocultar el 401 deja sin resolver el acceso original y añade otra variable al diagnóstico.

## Cómo comprobar que el 401 está resuelto

![Validación del mismo acceso y condiciones de estado exclusivo y Gateway detenido para usar probe](https://blog.laozhang.ai/posts/es/openclaw-401-authentication-error/img/verificar-401-probe-exclusivo.webp)

Primero vuelve a consultar el estado del agente y `/model status` en la conversación afectada. Si usas `--check`, interpreta el resultado según la [referencia oficial](https://docs.openclaw.ai/cli/models#read-status-correctly): `0` significa que la comprobación no encontró problemas de autenticación o ejecución en las rutas configuradas; **no garantiza que una petición al modelo vaya a funcionar**. `1` indica un problema o disponibilidad indeterminada; `2`, una credencial próxima a caducar sin un problema de tipo `1`.

Una petición breve en la conversación original permite comprobar el mismo modelo y la misma selección de cuenta. Es una llamada real y puede consumir tokens. El resultado buscado es una respuesta del modelo sin el error de autenticación, no solo un inicio de sesión completado o un perfil presente en el almacén.

### Prueba directa con `--probe`: detén primero el Gateway

`openclaw models status --probe` envía peticiones reales, puede tener coste y activar límites de uso. Además, crea sesiones internas temporales y requiere **uso exclusivo del directorio de estado configurado**. No lo ejecutes mientras el Gateway u otro proceso estén usando ese estado. La [documentación de probes](https://docs.openclaw.ai/cli/models#status) exige detener primero un Gateway en ejecución.

Este ejemplo limita la prueba al agente `main` y al proveedor `anthropic`. Sustitúyelos por los que quieres diagnosticar:

```bash
openclaw gateway stop
openclaw models status --agent main --probe --probe-provider anthropic --probe-concurrency 1 --probe-max-tokens 8
```

Si necesitas limitarla también a un perfil concreto, añade `--probe-profile` con su identificador real. `--probe-max-tokens` es un límite aplicado en la medida de lo posible, no una garantía de coste cero.

**Espera a que el comando termine y se completen el trabajo aceptado y la limpieza antes de reiniciar.** Los resultados pueden aparecer antes de que concluya esa limpieza; una interrupción o un timeout no certifican que se hayan liberado las sesiones y el bloqueo. Atiende cualquier error de limpieza y no lances pruebas concurrentes sobre el mismo directorio. Solo después inicia de nuevo el servicio:

```bash
openclaw gateway start
```

Un resultado `ok` corresponde al modelo y perfil probados; no demuestra que una conversación con otra selección funcione. Si aparece `no_model`, no se ha podido elegir un modelo para probar. Si aparece `excluded_by_auth_order`, el perfil quedó fuera del orden configurado. Un resultado de límite de uso, facturación o timeout tampoco es prueba de que la clave esté mal.

## Preguntas frecuentes

### ¿Tengo que renovar el token del Gateway si el proveedor devuelve HTTP 401?

No por ese motivo. El token del Gateway permite conectar el cliente a OpenClaw; la credencial del proveedor permite llamar al modelo. Revisa el acceso que devuelve el error. Si el panel funciona y la respuesta dice `provider returned HTTP 401`, empieza por el proveedor, el agente y la selección de la sesión.

### ¿Qué hago con `Please run /login · API Error: 401 Invalid bearer token`?

Identifica qué programa emitió el mensaje. Si proviene de Claude Code usado mediante Claude CLI, comprueba `claude auth status --text` e inicia sesión con `claude auth login` como usuario del Gateway. Si se trata de un token guardado por OpenClaw, renueva ese perfil mediante sus herramientas de autenticación. No copies el token nativo de Claude Code al almacén de OpenClaw. [Referencia de Anthropic](https://docs.openclaw.ai/providers/anthropic#troubleshooting).

### ¿Cada agente necesita una clave API propia?

No. Los agentes pueden consultar el almacén compartido. Un perfil local con el mismo identificador sustituye al compartido, por lo que conviene revisar esa prioridad cuando solo falla un agente. Las cuentas personales y los inicios de sesión nativos tienen sus propios límites. [Almacenamiento de autenticación](https://docs.openclaw.ai/concepts/oauth#storage-where-tokens-live).

### ¿Setup-token sigue soportado?

Sí, la documentación general conserva esa modalidad. La guía específica de Anthropic recomienda una clave API para nuevas configuraciones cuando los tokens caducan o se revocan. El soporte del método no garantiza que tu token siga vigente ni determina qué cubre tu suscripción. [Autenticación de Anthropic](https://docs.openclaw.ai/gateway/authentication#anthropic-setup-token).

### ¿`No available auth profile (all in cooldown)` es otro 401?

No necesariamente. Consulta `openclaw models status --agent main --json` y los motivos de `auth.unusableProfiles`. Un perfil puede estar en espera por límites de uso u otra indisponibilidad. Corrige el motivo indicado; no vuelvas a autenticarte solo porque aparece la palabra `cooldown`. [Diagnóstico de perfiles de Anthropic](https://docs.openclaw.ai/providers/anthropic#troubleshooting).