Solucion de Problemas
Problemas comunes y soluciones para desplegar y gestionar agentes en OpenClaws.
Problemas de Despliegue
El despliegue tarda mas de lo esperado
El primer despliegue en un nodo nuevo puede tardar mas porque la imagen del contenedor de OpenClaw necesita descargarse. Los despliegues posteriores son mas rapidos gracias al cache de imagenes.
- Despliegue normal: 30-60 segundos
- Primer despliegue (descarga de imagen): 60-120 segundos
- Si el despliegue excede 3 minutos, verifica el estado de la asignacion de Nomad en el panel de control
El agente muestra "provisioned" pero no "running"
Esto generalmente significa que el contenedor inicio pero la verificacion de salud aun no ha pasado. El sidecar de la malla de servicios (Envoy) tarda ~30 segundos en registrarse. Espera y actualiza el panel de control.
Si el agente permanece en estado "provisioned" por mas de 2 minutos, el contenedor puede estar en un ciclo de fallos. Causas comunes:
- Clave de API de Anthropic invalida (el descifrado Transit tiene exito pero la clave es incorrecta)
- OOM kill del contenedor (poco probable con planificacion honesta)
- Problemas con el token de Vault (verifica la configuracion de Identidad de Carga de Trabajo de Nomad)
Problemas con Claves API
La clave de API de Anthropic no funciona
La clave se cifra via Vault Transit antes de almacenarla. Si el descifrado Transit falla al iniciar el contenedor, el agente no podra llamar al API de Anthropic.
- Verifica que la clave sea valida en console.anthropic.com
- Intenta rotar la clave usando el panel de control o el API
- Verifica que la clave Transit (
openclaw) este disponible en Vault
La rotacion de clave fallo
La rotacion de clave genera una nueva clave API y actualiza Vault. Si la rotacion falla, la clave anterior sigue siendo valida. El contenedor se reinicia automaticamente cuando los secretos cambian (via change_mode = "restart" de Nomad).
Problemas Multi-Agente
Los agentes no pueden comunicarse entre si
La comunicacion entre agentes requiere que los tres elementos de configuracion esten presentes. Verifica:
1. tools.agentToAgent.enabled = true in openclaw.json?
2. tools.agentToAgent.allow includes ALL agent IDs?
3. Each agent has subagents.allowAgents configured?
4. Each agent has auth-profiles.json at ~/.openclaw/agents/{id}/agent/?Nota: La herramienta agents_list solo muestra el agente que la llama. Esto es normal — sessions_spawn funciona entre agentes de todas formas.
Problemas de Chat
Los mensajes de chat expiran por timeout
El proxy de chat tiene un timeout de 120 segundos para respuestas del LLM. Si el agente esta procesando una solicitud compleja, puede exceder este timeout.
- Intenta dividir solicitudes complejas en mensajes mas pequenos y enfocados
- Si los timeouts persisten, el contenedor del agente puede estar bajo presion de recursos
- Considera subir a un plan superior para mas memoria
"Connection refused" al chatear
El proxy de chat enruta a traves de endpoints internos del VPC. Si el contenedor del agente se esta reiniciando o reprogramando, la conexion puede estar temporalmente no disponible. Espera a que el agente muestre el estado "Running".
Problemas de Almacenamiento
Los datos no persisten entre reinicios
Los datos persistentes se almacenan en un GCE Persistent Disk montado en /openclaw-data. El directorio ~/.openclaw es un enlace simbolico a /openclaw-data/oc-{user}/.
Ten en cuenta que el archivo de configuracion openclaw.json se copia de nuevo en cada inicio del contenedor (en caso de que los agentes hayan cambiado), pero los datos de conversacion y archivos persisten.
El contenedor se movio a un nodo diferente
Nomad maneja automaticamente la desconexion/reconexion del PD cuando las asignaciones se mueven entre nodos. Puede haber un retraso de 15-30 segundos durante la conexion. Tus datos se preservan.
Obtener Ayuda
Si estas experimentando un problema no cubierto aqui:
- Verifica el estado del agente y los detalles de asignacion en el panel de control
- Revisa los logs de asignacion de Nomad (disponibles a traves del panel de control)
- Visita la Referencia API para el manejo de errores especificos por endpoint