Errores de OpenClaw: clave API, Gateway y recuperación de la tarea

Si OpenClaw muestra No API key found, un 401 o un error que impide continuar, identifica primero qué conexión falla. La clave del proveedor permite llamar al modelo; la credencial del Gateway permite entrar a OpenClaw; la identidad del dispositivo y el token de un bot controlan otros accesos. Cambiar una de ellas no corrige automáticamente las demás.

Para empezar, conserva el mensaje completo, la hora y el agente afectado. Comprueba el modelo y la ejecución que usa esa conversación, localiza la procedencia de su credencial y corrige únicamente la condición que explica el fallo. La recuperación se confirma con una respuesta por ese mismo acceso y con la continuación del trabajo pendiente, sin repetir acciones terminadas.

Los procedimientos se apoyan en la documentación consultada el 7 de octubre de 2026. El ejemplo de recuperación de esta guía se ha comprobado con datos ficticios y sin conexión; no se han probado claves reales, llamadas al modelo ni facturas.

Encuentra la primera acción a partir del error

El número HTTP orienta, pero el emisor y el cuerpo del error deciden qué revisar. Un 429 del proveedor del modelo y un 429 del acceso al Gateway tienen causas y tratamientos distintos.

La autenticación de OpenClaw, los errores de conexión al Gateway y la conmutación entre modelos y perfiles distinguen estos accesos y condiciones. No interpretes todos los errores de autenticación como una clave API inválida.

No API key found: revisa el agente y la fuente que usa el proceso

Una clave guardada en tu ordenador no demuestra que el proceso del Gateway pueda utilizarla. Puede estar en otro equipo, pertenecer a otro usuario o quedar fuera de los perfiles seleccionados para ese agente.

En el equipo del Gateway, la comprobación documentada del agente es:

openclaw models status --agent main --json

Sustituye main por el identificador real. Dentro de la conversación afectada, consulta por separado:

/model status
/status

La CLI inspecciona las rutas predeterminadas y de reserva del agente. La sesión puede haber elegido otro modelo o fijado un perfil; /status permite distinguir el modelo seleccionado del que respondió como alternativa. En ejecuciones ACP o nativas, parte del estado de modelo y autenticación pertenece al entorno de ejecución externo. La referencia de models status explica estas diferencias.

En la salida estructurada, busca la relación entre estos campos, sin publicar secretos:

• auth.providers: de dónde proceden las credenciales.
• auth.oauth: estado de los perfiles guardados y caducidad; también puede incluir perfiles de claves API.
• auth.modelRouteIssues: problemas de compatibilidad, ausencia o disponibilidad indeterminada.
• auth.runtimeAuthRoutes: disponibilidad del entorno de ejecución y de su autenticación.

indeterminate requiere resolver el diagnóstico; no significa que el proveedor haya rechazado la clave. Una referencia a archivo o ejecutable puede existir sin que se haya determinado su disponibilidad. También puedes tener una credencial utilizable y un entorno de ejecución que no arranca.

models status sin --probe no hace una llamada de prueba al modelo, aunque puede resolver secretos concretos y consultar estado de autenticación. Si automatizas su lectura, comprueba tanto el código de salida como el cuerpo: ante un fallo, el JSON puede contener un objeto de error. Con --check, 0 indica que no se reconocieron problemas de ruta, ejecución o caducidad; 1 incluye problemas de ausencia, incompatibilidad, indisponibilidad o estado indeterminado; 2 corresponde a caducidad próxima sin un problema de tipo 1. Ninguno sustituye una respuesta del modelo.

Corrige la fuente ausente sin copiar todas las claves

El almacén compartido actual está en ~/.openclaw/state/openclaw.sqlite; un agente puede tener estado y anulaciones locales en ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Un agente sin perfil local puede leer el compartido: no necesita que copies cada secreto. Un perfil local con el mismo identificador, una exclusión en el orden de autenticación o un directorio de estado diferente pueden cambiar el acceso efectivo. Véase almacenamiento y perfiles.

Si falta realmente una credencial compatible, utiliza el asistente documentado openclaw models auth add para el proveedor y agente afectados. El comando paste-api-key recibe una clave API; paste-token recibe material de token y cumple otra función. Con varios agentes, indica explícitamente cuál vas a modificar y comprueba qué perfil quedará activo. No edites SQLite manualmente para hacer desaparecer el error.

En OpenAI, la clave API y el acceso ChatGPT/Codex usan el proveedor canónico openai; nombres antiguos openai-codex pueden ser entradas de migración. El asistente de inicio de sesión elige por defecto ChatGPT/Codex; el método api-key debe elegirse expresamente si necesitas ese acceso. Conserva la distinción entre autenticación y ejecución nativa.

Los antiguos auth-profiles.json, auth-state.json y auth.json son entradas de migración, no los archivos actuales de credenciales en ejecución. Conserva los originales y sigue un hallazgo concreto de migración antes de reparar. Borrarlos, forzar una instalación o ejecutar una reparación genérica no fabrica una credencial válida. La referencia de autenticación de la CLI describe los helpers y la compatibilidad actual.

401: comprueba el proveedor, el endpoint y el método de ejecución

Si el error procede del proveedor, confirma que la cuenta y el endpoint pertenecen al mismo servicio. Una clave del proveedor original no tiene por qué autenticar un intermediario con otro baseUrl. Los campos baseUrl, api, identificadores de modelo, cabeceras y plazos pertenecen a models.providers.<id> en la configuración del proveedor; no son filas de credenciales.

Una cabecera ausente exige averiguar por qué no llegó: resolución de la credencial, configuración del endpoint o intermediario. No añadas x-api-key a todos los servicios como receta universal. Si el cuerpo señala facturación o acceso, conserva esa clasificación aunque el número sea 401 o 403; renovar repetidamente una clave vigente no resuelve la condición económica.

Cuando la ejecución usa Claude CLI nativo, el inicio de sesión pertenece a Claude y debe funcionar con el mismo equipo, usuario, PATH y, si se utiliza, CLAUDE_CONFIG_DIR que el servicio. Elegir el entorno nativo y haber iniciado sesión son dos requisitos distintos. OpenClaw no lee, guarda ni renueva los tokens de ese inicio de sesión. El setup-token administrado por OpenClaw es otro método, con su propio flujo interactivo. La guía de autenticación distingue ambos; un nombre de modelo no prueba cobertura de una suscripción ni una forma de facturación.

Para seguir el diagnóstico específico de invalid bearer token o missing authentication header, consulta la guía del error 401 de OpenClaw. Aquí el resultado buscado es identificar la conexión antes de cambiar su acceso.

Si falla el Gateway, el dispositivo o el canal

Un cliente que no entra al Gateway todavía no ha demostrado un fallo del modelo. AUTH_TOKEN_MISSING señala que falta la credencial del Gateway en el cliente autorizado. AUTH_TOKEN_MISMATCH señala una discrepancia; si incluye canRetryWithDeviceToken=true, la documentación permite un reintento con la credencial de dispositivo de confianza. AUTH_DEVICE_TOKEN_MISMATCH requiere recuperar el acceso de ese dispositivo bajo el control de su propietario.

Con AUTH_SCOPE_MISMATCH, el token puede ser válido y los permisos insuficientes. Con PAIRING_REQUIRED, revisa la solicitud y el acceso que se va a aprobar. Introducir otra clave del modelo no sustituye la identidad del dispositivo ni la revisión de permisos. El detalle de conexión y Control UI es el siguiente paso para esas ramas.

El endpoint HTTP de OpenResponses está desactivado por defecto. Un 404 de una ruta desactivada no prueba una clave mala. En los modos HTTP de token o contraseña compartidos, Authorization: Bearer lleva la credencial del Gateway, no la clave de su proveedor; los modos con identidad de proxy tienen otras reglas. Ese acceso compartido concede semántica completa de operador, por lo que no debes tratarlo como un token de lectura restringida. El contrato HTTP de OpenResponses también distingue 401 de autenticación, 403 de permisos y 429 del limitador de intentos fallidos, con Retry-After.

Ante ese 429 local de autenticación, corrige el cliente y respeta la espera. Cambiar modelo, IP u origen para evitar el bloqueo no recupera la credencial correcta. Un código WebSocket 1008 necesita su detalle de política; no identifica por sí solo una clave API rechazada.

openclaw gateway status comprueba por defecto servicio y conexión con autenticación; --require-rpc añade la comprobación del permiso de lectura y --no-probe se limita al servicio. No demuestra permisos de escritura o administración, ni acceso al modelo. Al indicar --url, debes aportar credenciales explícitas: no se usa automáticamente la configuración o la clave del entorno. La referencia de estado del Gateway explica también las diferencias entre el usuario del servicio y quien ejecuta la CLI.

Si el error viene de un canal, comprueba su destino, token y permisos específicos. Un modelo que responde desde el panel y un bot que no entrega mensajes forman dos pruebas distintas. Del mismo modo, /healthz demuestra que el proceso vive, no que el proveedor esté listo. Un stream puede conectarse y terminar en response.failed; conserva el resultado final, no solo la apertura de conexión.

429, cooldown y contexto: espera o cambia la entrada correcta

Para un 429 del modelo, limita primero las solicitudes nuevas. Lee el cuerpo y la cadena de intentos para distinguir límite temporal, ventana de uso agotada y problema de facturación. Respeta el mínimo indicado por el proveedor: Retry-After puede expresar segundos enteros o una fecha HTTP; OpenClaw también contempla indicaciones en milisegundos. Un mínimo largo no se recorta para enviar antes. Si rebasa el tiempo disponible, deja el trabajo pendiente o utiliza una alternativa ya aprobada y compatible.

El modo integrado documenta hasta diez intentos totales para 429 y, para otros fallos transitorios, ocho reintentos con una ventana de caída consecutiva de 90 segundos. Una respuesta completa limpia esa ventana; una respuesta parcial o actividad de herramientas no la limpia. Cancelación y plazo de la tarea siguen siendo límites. Son políticas del entorno integrado, no una invitación a envolver el turno entero en otro bucle. retry.provider.maxRetries es un ajuste de sesión integrado, no una clave genérica de openclaw.json. Véase política de reintentos.

all in cooldown puede reflejar estado persistente. Las esperas internas de 30 segundos, un minuto o cinco minutos no son un plazo universal de restablecimiento del proveedor; una desactivación por facturación o autenticación permanente puede comenzar con diez minutos y no desaparecer al reiniciar o recargar saldo. La conmutación por error diferencia espera, perfiles y modelos.

Las alternativas tampoco son automáticas en todas las sesiones: un modelo elegido expresamente puede ser estricto, y un agente sin reservas no inventa una cadena. El modelo que ganó como reserva responde a ese turno; el siguiente vuelve a empezar por el seleccionado. Comprueba capacidad de herramientas, tratamiento de datos y condiciones de cobro antes de aprobar otro proveedor. Para espera y cuotas, continúa con cómo recuperar un 429 de OpenClaw.

Cambiar temporalmente a otro perfil apto del mismo proveedor no elimina la selección estricta del modelo ni cambia permanentemente el perfil fijado por el usuario. La rotación de varias claves configuradas es otro mecanismo y solo se activa ante señales compatibles de límite, cuota o recursos agotados; no multiplica una cuota compartida. Una clave fijada mediante la anulación de clave activa impide esa rotación. Evita eliminar perfiles como prueba rutinaria: borrar una clave guardada no la revoca en el proveedor, y eliminar autenticación a través de un Gateway activo puede abortar ejecuciones que la utilizan.

Un 400 con context length exceeded requiere otra acción: guarda resultados, decisiones y petición pendiente; reduce un archivo o salida enorme, o compacta el historial cuando el modo lo permita. No elimines todo el trabajo ni repitas la misma entrada sin cambios. La ventana anunciada puede ser mayor que la cargada en un servidor local. La recuperación de contexto y compactación desarrolla esa rama. Un 400 por cuerpo inválido, en cambio, necesita corregir la petición; no basta con hacerla más corta.

Docker, secretos, TLS y configuración: corrige el proceso que falla

Si funciona en tu terminal y falla como servicio, compara procedencia y presencia de la variable necesaria, equipo, usuario y proceso activo. No publiques sus valores ni un volcado completo del entorno. OpenClaw no reemplaza normalmente valores ya presentes en el proceso; el .env del directorio de trabajo no acepta credenciales de proveedor ni controles protegidos. El .env global del directorio de estado sí es una fuente de confianza para claves del proveedor. Los servicios administrados por OpenClaw tienen reglas específicas de actualización. Consulta precedencia del entorno.

En Docker Compose, cambiar el entorno requiere recrear el Gateway para aplicarlo; un simple restart no incorpora las variables nuevas. Prepara ese cambio con el estado persistente conservado y las operaciones aceptadas resueltas. La documentación de entorno de Docker es la referencia; una receta antigua con otro usuario, imagen o montaje no demuestra cómo funciona tu contenedor.

Con un SecretRef explícito que falla, restaura su fuente y sigue el procedimiento autorizado de recarga. En rutas compatibles, la referencia activa tiene precedencia sobre texto plano, y un perfil de SQLite puede ocultar una referencia de configuración. Un proveedor declarado indisponible por esa referencia no puede saltarse el fallo recurriendo al entorno o a otros perfiles. Algunos diagnósticos pueden utilizar una instantánea preparada mientras el envío real sigue siendo estricto. Por eso una lectura de estado satisfactoria no prueba que el secreto esté disponible para enviar. Véase operación de secretos.

Ante TLS, revisa el certificado, su cadena y la configuración de confianza del proceso correcto. Mantén la validación activada. En Node, NODE_EXTRA_CA_CERTS añade certificados PEM al arrancar el proceso; asignarlo después en process.env no cambia la confianza ya cargada. Un cliente que fija explícitamente ca usa otras reglas. La referencia de Node describe estas condiciones; desactivar TLS no es una reparación de clave API.

Para un error de configuración, consulta el archivo activo y el esquema de tu instalación antes de modificarlo. La validación comprueba estructura y compatibilidad de referencias, pero no demuestra que el backend acepte el secreto ni que todos los parámetros particulares de un proveedor funcionen. Un parche de objeto combina campos; arrays y escalares se reemplazan y null elimina. Conserva ajustes ajenos al problema. La CLI de configuración detalla estas operaciones. Un error de base de datos de solo lectura, un plugin que no arranca o una herramienta que falla requieren su diagnóstico local; no rotación automática de claves.

Recupera el paso pendiente con un límite de tiempo

Antes de reanudar, clasifica cada acción: terminada y comprobada, pendiente o de resultado desconocido. Si un envío o escritura pudo ser aceptado antes del timeout, comprueba su resultado externo antes de repetirlo. Un POST no es automáticamente idempotente, y repetir un identificador de trabajo no inventa una garantía del proveedor. Así lo delimita HTTP sobre reintentos e idempotencia.

El siguiente programa completo de Python 3 es un planificador sin conexión. Lee un registro JSON ficticio y decide si detenerse, aplazar o programar otro intento. Calcula una decisión sin enviar peticiones, esperar, cambiar cuentas ni configurar OpenClaw. Su presupuesto de tres intentos es una elección ilustrativa para un plan de recuperación; no sustituye la política interna. Úsalo después de que haya terminado la cadena de intentos de OpenClaw, sin añadir otro bucle sobre un turno que sigue activo.

Guárdalo como plan_recuperacion.py:

import json
import math
import re
import sys
from datetime import datetime
from email.utils import parsedate_to_datetime


def espera_minima(headers, now):
    headers = {k.lower(): str(v).strip() for k, v in headers.items()}
    floors = []
    value = headers.get("retry-after")
    if value is not None:
        if re.fullmatch(r"[0-9]+", value):
            floors.append(int(value))
        else:
            date = parsedate_to_datetime(value)
            if date is None or date.tzinfo is None:
                raise ValueError("Retry-After debe ser segundos o fecha HTTP con zona")
            floors.append(max(0, math.ceil((date - now).total_seconds())))
    value_ms = headers.get("retry-after-ms")
    if value_ms is not None:
        if not re.fullmatch(r"[0-9]+", value_ms):
            raise ValueError("retry-after-ms debe ser un entero no negativo")
        floors.append(math.ceil(int(value_ms) / 1000))
    return max(floors, default=0)


def decidir(record, now):
    attempt = record["attempt"]
    maximum = record["max_attempts"]
    if not (type(attempt) is int and type(maximum) is int
            and 1 <= attempt <= maximum):
        raise ValueError("Presupuesto de intentos inválido")
    deadline = datetime.fromisoformat(record["deadline"])
    if deadline.tzinfo is None:
        raise ValueError("El plazo necesita zona horaria")
    remaining = (deadline - now).total_seconds()
    if record.get("cancelled") or remaining <= 0:
        return {"action": "detener", "reason": "cancelación o plazo agotado"}
    if record["outcome"] not in ("unknown", "known_failed", "completed"):
        raise ValueError("Resultado de la operación no reconocido")
    if record["outcome"] == "unknown":
        return {"action": "comprobar_resultado", "reason": "no repetir efectos inciertos"}
    if record["issuer"] != "provider" or record["operation"] != "model":
        return {"action": "diagnosticar_conexion", "reason": "no es la llamada al modelo"}
    category = record["category"]
    if category in ("auth", "billing", "context", "refusal", "config", "tls"):
        return {"action": "corregir", "reason": category}
    status = record["status"]
    if 200 <= status < 300:
        if record["outcome"] == "completed":
            return {"action": "continuar", "reason": "respuesta del modelo completada"}
        return {"action": "diagnosticar", "reason": "HTTP correcto sin respuesta completada"}
    if category not in ("rate_limit", "transient"):
        return {"action": "diagnosticar", "reason": "error sin clasificación recuperable"}
    if not record["replay_safe"]:
        return {"action": "detener", "reason": "repetición no autorizada o insegura"}
    if attempt == maximum:
        return {"action": "detener", "reason": "sin intentos restantes"}
    floor = espera_minima(record["headers"], now)
    delay = max(floor, min(2 ** (attempt - 1), 30))
    # Se reserva tiempo para la siguiente operación; nunca se envía antes del mínimo.
    request_budget = record["request_budget_seconds"]
    if request_budget <= 0:
        raise ValueError("El siguiente intento necesita tiempo positivo")
    if delay + request_budget > remaining:
        return {"action": "aplazar", "minimum_wait_seconds": floor}
    return {"action": "programar", "wait_seconds": delay,
            "next_attempt": attempt + 1,
            "completed_actions": record["completed_actions"]}


if __name__ == "__main__":
    if len(sys.argv) != 3:
        raise SystemExit("Uso: python3 plan_recuperacion.py registro.json fecha_ISO")
    try:
        with open(sys.argv[1], encoding="utf-8") as source:
            record = json.load(source)
        now = datetime.fromisoformat(sys.argv[2])
        if now.tzinfo is None:
            raise ValueError("La hora actual necesita zona horaria")
        print(json.dumps(decidir(record, now), ensure_ascii=False))
    except (KeyError, ValueError, TypeError, OSError) as error:
        raise SystemExit("Registro inválido: " + str(error))

Este archivo registro.json es una entrada para el ejemplo, no configuración de OpenClaw. La clasificación rate_limit presupone que ya has interpretado el cuerpo y su emisor; el programa no deduce causas a partir del número:

{
  "issuer": "provider",
  "operation": "model",
  "status": 429,
  "category": "rate_limit",
  "headers": {"Retry-After": "12"},
  "outcome": "known_failed",
  "replay_safe": true,
  "attempt": 1,
  "max_attempts": 3,
  "request_budget_seconds": 8,
  "deadline": "2026-10-07T12:00:40+00:00",
  "cancelled": false,
  "completed_actions": ["informe guardado y comprobado"]
}

Ejecuta únicamente la simulación:

python3 plan_recuperacion.py registro.json 2026-10-07T12:00:00+00:00

Devuelve programar, una espera de 12 segundos y el siguiente intento 2, conservando la acción terminada. Si cambias Retry-After a 120, devuelve aplazar: no reduce ese mínimo a los 40 segundos disponibles. Con outcome: "unknown", pide comprobar el resultado y no propone reenviar. Con el último intento consumido, se detiene sin programar otra espera.

La fecha HTTP se convierte en una espera redondeada hacia arriba y los milisegundos tampoco se redondean hacia abajo. Estas reglas siguen la semántica de Retry-After. En un sistema real añade el jitter y los límites de concurrencia que correspondan al componente que administra los reintentos; conserva además registro persistente de operaciones y comprobaciones. Una alternativa aprobada puede ser una decisión posterior, pero el ejemplo no cambia de cuenta ni de modelo por su cuenta.

Qué prueba confirma que el fallo se ha resuelto

Tras corregir la condición, utiliza una petición breve sin efectos externos en la misma conversación, agente, proveedor, modelo y método de ejecución que fallaban. Identifica el perfil efectivo y confirma qué modelo respondió. Un catálogo visible, GET /models con 200 o un perfil almacenado no prueban inferencia; una respuesta de otro modelo prueba su acceso, no el original.

Si optas por models status --probe, es una llamada real que puede consumir tokens y activar límites. La documentación requiere uso exclusivo del directorio de estado: prepara una ventana de mantenimiento, detén el Gateway de forma controlada, deja terminar trabajo aceptado y limpieza incluso tras una interrupción, y delimita proveedor, perfil y presupuesto de la prueba. Los valores por defecto de timeout, concurrencia y tokens no garantizan un coste total. Consulta las condiciones de la prueba real antes de realizarla.

Después retoma solo el paso pendiente y comprueba su resultado. Si necesitas una herramienta, verifica esa capacidad con una acción pequeña y autorizada: responder texto no demuestra que funcione una herramienta o un canal. La configuración de modelos y herramientas de OpenClaw desarrolla esa comprobación. Conservar un resultado de prueba no equivale a una factura, un reembolso o garantía para todas las tareas.

Preguntas frecuentes

¿Tengo que generar otra clave si aparece No API key found?

Solo si falta realmente el acceso necesario. Primero comprueba agente, perfil, fuente y proceso del Gateway. Una clave existente en otro usuario o una referencia explícita que falla requieren corregir esa selección o fuente; crear otra clave no demuestra que el proceso vaya a usarla.

¿Por qué el Gateway funciona pero el modelo falla?

Son conexiones diferentes. El estado del Gateway comprueba el servicio y ciertos permisos de conexión; la llamada al proveedor utiliza su propia autenticación y entorno de ejecución. La respuesta del modelo en el acceso afectado es la comprobación que falta.

¿Reiniciar elimina all in cooldown?

No necesariamente: hay estado persistente y bloqueos por perfil. Identifica el primer error de la cadena, respeta la espera del proveedor y corrige facturación o autenticación si ese es el motivo. No confundas esos bloqueos con el 429 del limitador de acceso al Gateway.

¿Un timeout significa que la tarea no hizo nada?

No. El modelo o una herramienta pueden haber aceptado trabajo antes de perderse la respuesta. Comprueba archivos, entregas e identificadores de operaciones antes de repetir efectos. La ausencia de respuesta tampoco demuestra ausencia de cargos.