Actualizado: junio de 2026 · Apéndice F

Cuando las cosas salen mal

Errores frecuentes organizados por síntoma para diagnosticar sin perder tiempo.

Qué cubre

Diagnóstico de errores frecuentes en Node, OpenClaw, Gateway, modelos, canales, Docker, navegador, seguridad y VPS.

Uso seguro

Copia solo lo que entiendas. Adapta rutas y revisa backups antes de ejecutar comandos que borren, muevan, abran puertos, cambien permisos o toquen secretos.

Volver a El Imperio de Uno Índice de apéndices COMPRAR EL IMPERIO DE UNO

apendice_f.md

Este apéndice está pensado para cuando algo falla y no quieres improvisar. Lee el síntoma, ejecuta solo diagnósticos de lectura, compara la salida esperada y aplica la acción más pequeña posible.

Regla práctica: un bloque copiable debe ser un comando aislado. Los errores, síntomas y explicaciones aparecen como texto normal para que no los pegues por accidente.

NO PEGUES

Antes de pedir ayuda, compartir registros/logs o pegar una salida en un chat, oculta cualquier dato sensible. No pegues API keys, tokens de BotFather, cabeceras Authorization, valores de OPENROUTER_API_KEY, openclaw.json completo, rutas privadas de tu equipo, IPs públicas, dominios reales, signed URLs, cookies ni logs completos. Comparte solo el error mínimo, la versión y el comando de diagnóstico usado.

Node/npm

Node no existe en la terminal

Síntoma visible: La terminal dice que node no se reconoce o que el comando no existe.
Qué significa: Node no está instalado, no está en el PATH o estás usando una terminal distinta a la que configuraste.
Antes de tocar nada: Cierra y abre la terminal. Si estás en Windows, prueba PowerShell normal antes de cambiar permisos.
Diagnóstico seguro: Comprueba la versión visible de Node.

node --version

Salida esperada: una versión como v22.x o v24.x. Para OpenClaw mantén Node 22 o Node 24 salvo que su documentación de tu versión pida otra cosa.

Acción segura: instala o selecciona Node con nvm. Evita arreglar permisos globales con sudo: si npm falla por EACCES, usa nvm o un prefijo de usuario.

npm config set prefix ~/.npm-global

Si no funciona: revisa qué terminal usa tu editor o panel. En servidores, documenta la versión con node --version antes de reinstalar.

Riesgo: SEGURO. No cambia servicios ni datos.

npm dice que falta package.json

Síntoma visible: npm muestra un error ENOENT o parece ejecutar desde la carpeta equivocada.
Qué significa: Estás fuera de la carpeta del proyecto o has descargado una parte incompleta.
Antes de tocar nada: No reinstales dependencias a ciegas. Primero mira dónde estás.
Diagnóstico seguro: Lista la carpeta actual y busca package.json.

ls -la

Salida esperada: debería aparecer package.json. Si no aparece, cambia a la carpeta del proyecto antes de ejecutar npm.

Acción segura: abre la carpeta correcta y vuelve a ejecutar el comando original.

Si no funciona: revisa si descargaste el ZIP completo o solo un subdirectorio.

Riesgo: SEGURO.

OpenClaw install

OpenClaw no arranca o no encuentra configuración

Síntoma visible: El CLI falla al arrancar, no encuentra perfiles o muestra avisos de configuración incompleta.
Qué significa: Puede faltar configuración, una variable de entorno o una versión compatible de Node.
Antes de tocar nada: No pegues openclaw.json en chats. Si contiene secretos, trátalo como credencial.
Diagnóstico seguro: Ejecuta el diagnóstico general de OpenClaw.

openclaw doctor

Salida esperada: secciones con comprobaciones y una línea tipo Comprobación: ok o avisos concretos. Un aviso explica qué falta; no lo tapes con reinstalaciones masivas.

Acción segura: corrige el primer aviso rojo, reinicia la sesión de terminal y vuelve a lanzar openclaw doctor.

Si no funciona: guarda la salida mínima en un archivo local y elimina secretos antes de compartirla.

Riesgo: SEGURO.

Una skill promete mucho o pide permisos raros

Síntoma visible: Una skill de ClawHub parece útil, pero no sabes qué hace por dentro.
Qué significa: VirusTotal y metadatos son telemetría, no garantía. Las skills de terceros son no confiables hasta leerlas.
Antes de tocar nada: No instales la skill en tu agente principal. Léela y pruébala aislada.
Diagnóstico seguro: Verifica la ficha y archivos declarados.

openclaw skills verify <slug>

Salida esperada: autor, archivos, permisos solicitados y advertencias. Si no puedes leer SKILL.md o no entiendes permisos, no la instales.

Acción segura: instala primero en un agente de prueba sin secretos ni permisos amplios.

Si no funciona: busca alternativa oficial o escribe un procedimiento manual pequeño.

Riesgo: PRECAUCIÓN.

Gateway

El Gateway no responde

Síntoma visible: El panel, agente o canal no consigue hablar con el Gateway.
Qué significa: El servicio puede estar parado, escuchando en otro puerto o no estar listo.
Antes de tocar nada: No abras puertos públicos para probar. Primero confirma estado local.
Diagnóstico seguro: Consulta estado del Gateway.

openclaw gateway status

Salida esperada: algo equivalente a Gateway: running, puerto local y modo de autenticación activo.

curl -s http://127.0.0.1:18789/healthz

Salida esperada: {"ok":true} o una respuesta de salud equivalente.

curl -s http://127.0.0.1:18789/readyz

Salida esperada: {"ready":true} o una respuesta que indique dependencias listas.

Acción segura: si el servicio está parado, reinicia solo el Gateway con el mecanismo de tu instalación. No cambies bind ni firewall para ocultar un problema local.

Si no funciona: revisa logs del Gateway y el último cambio de configuración.

Riesgo: SEGURO para diagnósticos; PRECAUCIÓN para reinicios.

El Gateway podría estar expuesto

Síntoma visible: Alguien puede acceder al puerto 18789 desde fuera, o ves bind en una IP pública.
Qué significa: Un Gateway escuchando en 0.0.0.0 o IP pública puede quedar accesible desde internet.
Antes de tocar nada: La preferencia segura es loopback: 127.0.0.1:18789. No hay puertos públicos sin auth/VPN/túnel con autenticación.
Diagnóstico seguro: Comprueba estado, socket real y Docker antes de cambiar firewall.

openclaw gateway status --json

Salida esperada segura: bind en 127.0.0.1, auth activa y puerto 18789 no publicado a internet.

ss -tlnp | grep 18789

Salida esperada segura: una línea con 127.0.0.1:18789. 0.0.0.0:18789 o una IP pública es peligroso salvo arquitectura deliberada con autenticación fuerte.

docker compose ps

Salida esperada: servicios en estado running y sin mapeos públicos tipo 0.0.0.0:18789->18789.

Acción segura: vuelve a loopback, pon autenticación y usa VPN, túnel con Access o reverse proxy con auth si de verdad necesitas acceso remoto.

Si no funciona: corta exposición pública antes de depurar comodidad de acceso.

Riesgo: PELIGROSO si hay bind público.

modelos/API keys

El modelo rechaza la petición

Síntoma visible: Ves errores de autenticación, cuota, modelo inexistente o proveedor no disponible.
Qué significa: La API key puede no estar cargada, el modelo cambió, falta saldo o el proveedor está limitando tráfico.
Antes de tocar nada: No pegues la key ni el header Authorization. Describe el proveedor y el código de error, no el secreto.
Diagnóstico seguro: Revisa configuración desde OpenClaw.

openclaw doctor

Salida esperada: proveedor detectado, key presente como referencia segura y avisos de cuota o modelo si aplica.

Acción segura: rota la key si se pegó en un chat, añade un límite de gasto en el proveedor y prueba con un modelo estable antes de producción.

Si no funciona: cambia temporalmente a un modelo de respaldo no crítico y conserva revisión humana.

Riesgo: PRECAUCIÓN.

Ollama consume recursos o queda expuesto

Síntoma visible: El equipo va lento, el modelo queda cargado o el puerto 11434 aparece accesible.
Qué significa: El modelo local sigue en memoria o el servicio escucha donde no debe.
Antes de tocar nada: No uses ollama serve & como solución principal. Prefiere servicio systemd o app local bien configurada, y bind local.
Diagnóstico seguro: Mira modelos activos.

ollama ps

Salida esperada: lista de modelos cargados, tamaño y tiempo hasta descarga. Si no esperabas ninguno, puedes pararlo.

ollama stop <modelo>

Acción segura: deja Ollama en 127.0.0.1:11434. Si necesitas acceso remoto, usa red privada y autenticación delante.

Si no funciona: revisa el service systemd o configuración local antes de abrir firewall.

Riesgo: PRECAUCIÓN.

canales

Telegram, WhatsApp o Discord no reciben mensajes

Síntoma visible: El canal no responde, no llegan aprobaciones o el agente habla en el chat equivocado.
Qué significa: Puede faltar token, pairing, allowlist o binding del agente al canal.
Antes de tocar nada: No pegues tokens de BotFather ni IDs privados completos en soporte público.
Diagnóstico seguro: Consulta estado de canales.

openclaw channels status

Salida esperada: canal configurado, auth presente como referencia y binding al agente correcto.

Acción segura: limita chats permitidos, activa confirmación humana para envíos externos y separa canales de prueba y producción.

Si no funciona: revisa logs filtrados por canal, no logs completos con tokens.

Riesgo: PRECAUCIÓN.

Docker

Un contenedor no arranca

Síntoma visible: Docker muestra servicios caídos o reinicios constantes.
Qué significa: Puede haber configuración inválida, dependencia caída o variable ausente.
Antes de tocar nada: docker compose down no es un reinicio simple: puede parar todo el stack y romper sesiones. Prefiere docker compose restart <servicio> cuando el problema sea un servicio concreto.
Diagnóstico seguro: Mira estado antes de reiniciar.

docker compose ps

Salida esperada: servicios en running o un servicio concreto marcado como exited/restarting.

docker ps --format "table {{.Names}}	{{.Status}}	{{.Ports}}"

Salida esperada: nombres, estado y puertos publicados. Te permite detectar publicaciones no previstas.

Acción segura: reinicia solo el servicio afectado si sabes cuál es. Si no, revisa logs acotados antes de tocar el stack.

Si no funciona: identifica el primer error real en logs y evita reinicios en bucle.

Riesgo: PRECAUCIÓN.

Docker ocupa demasiado disco

Síntoma visible: El VPS se queda sin espacio y Docker parece el principal consumidor.
Qué significa: Imágenes antiguas, contenedores parados o volúmenes pueden acumularse.
Antes de tocar nada: No uses docker volume prune ni --volumes sin backup verificado. Los volúmenes pueden contener bases de datos, uploads o configuración.
Diagnóstico seguro: Mide primero.

docker system df

Salida esperada: tabla con Images, Containers, Local Volumes y Build Cache. El campo reclaimable indica qué podría limpiarse, no qué debes borrar.

docker volume ls

Salida esperada: lista de volúmenes. Si no reconoces un volumen, no lo borres.

Acción segura: limpia solo recursos que entiendes y que no sostienen servicios críticos. Documenta qué borras.

Si no funciona: aumenta disco o mueve datos tras backup; no fuerces prune agresivo en producción desconocida.

Riesgo: PELIGROSO si borras volúmenes.

navegador

El agente no abre navegador o ve una página distinta

Síntoma visible: La automatización falla, aparece CAPTCHA o el contenido dinámico no carga.
Qué significa: Puede faltar navegador, la web bloquear automatización o la sesión requerir 2FA.
Antes de tocar nada: No metas credenciales reales en pruebas rápidas. Usa perfil persistente y permisos mínimos.
Diagnóstico seguro: Confirma primero el estado general de OpenClaw.

openclaw doctor

Salida esperada: navegador o dependencia indicada como disponible, o un aviso concreto de instalación.

Acción segura: baja frecuencia, usa esperas explícitas y pide captura al agente antes de cambiar selectores.

Si no funciona: para webs con CAPTCHA frecuente, usa intervención humana o API oficial.

Riesgo: PRECAUCIÓN.

seguridad/puertos

Quieres tocar firewall o SSH

Síntoma visible: No puedes entrar por SSH o necesitas limitar acceso a un puerto.
Qué significa: Un cambio de firewall puede dejarte fuera del VPS o abrirlo demasiado.
Antes de tocar nada: Mantén una sesión SSH abierta. Usa SSH restringido por origen y no abras 22 a todo internet si puedes evitarlo.
Diagnóstico seguro: Mira estado actual y simula antes de aplicar.

ufw status

Salida esperada: reglas activas y puertos permitidos. Si aparece 22 ALLOW Anywhere, revisa si puedes restringirlo a tu IP.

ufw --dry-run allow from TU_IP_PUBLICA to any port 22 proto tcp

Salida esperada: plan de regla sin aplicarla. Sustituye TU_IP_PUBLICA solo en privado.

Acción segura: aplica reglas desde una sesión abierta y conserva acceso alternativo del proveedor.

Si no funciona: usa consola del proveedor para revertir firewall.

Riesgo: PELIGROSO si pierdes SSH o abres puertos amplios.

VPS/disco/logs

Disco lleno en el VPS

Síntoma visible: Instalaciones fallan, Docker no arranca o los logs dejan de escribirse.
Qué significa: El disco puede estar lleno por logs, Docker, backups antiguos o temporales.
Antes de tocar nada: No borres directorios a ciegas. Mide y conserva historial útil para investigar.
Diagnóstico seguro: Empieza por espacio global y carpetas grandes.

df -h

Salida esperada: tabla de sistemas de archivos. Si la raíz está por encima del 85-90 %, toca actuar con cuidado.

du -h -d1 /var /docker 2>/dev/null

Salida esperada: tamaños por carpeta para localizar el origen antes de borrar.

journalctl --disk-usage

Salida esperada: tamaño total ocupado por journald. Solo después de medir considera vacuum.

journalctl --vacuum-time=3d

Acción segura: vacuum puede liberar espacio, pero borra historial antiguo de investigación. Úsalo solo si ya guardaste lo necesario.

Si no funciona: amplía disco desde el proveedor o mueve datos tras backup.

Riesgo: PRECAUCIÓN; PELIGROSO si borras pruebas necesarias.

backups/rollback

Vas a cambiar configuración y quieres poder volver

Síntoma visible: Necesitas tocar workspace, openclaw.json, Docker o reglas y no sabes si podrás deshacer.
Qué significa: Sin backup verificado, cada arreglo puede convertirse en pérdida de contexto.
Antes de tocar nada: Crea copia local, comprueba que existe y no la subas a un repo público.
Diagnóstico seguro: Lista la carpeta de backup antes y después.

ls -la ~/.openclaw

Salida esperada: carpeta de workspace y configuración visibles con permisos razonables.

cp -a ~/.openclaw/workspace ~/.openclaw/backups/workspace-pre-fix-$(date +%Y%m%d_%H%M%S)

Salida esperada: no imprime nada si copia bien. Después revisa que la carpeta exista.

tar -czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/workspace ~/.openclaw/openclaw.json

Acción segura: cifra el backup si contiene openclaw.json. Si una API key ya se filtró, no basta con borrar: rota la key.

Si no funciona: haz rollback desde snapshot del proveedor o copia anterior verificada.

Riesgo: PRECAUCIÓN porque puede copiar secretos.

This appendix is for the moment when something breaks and you do not want to improvise. Read the symptom, run only read-oriented diagnostics first, compare the expected output, and apply the smallest possible fix.

Practical rule: a copyable block should be an isolated command. Errors, symptoms, and explanations appear as normal text so you do not paste them by accident.

DO NOT PASTE

Before asking for help, sharing logs, or pasting output into a chat, hide anything sensitive. Do not paste API keys, BotFather tokens, Authorization headers, OPENROUTER_API_KEY values, full openclaw.json files, private local paths, public IPs, real domains, signed URLs, cookies, or full logs. Share only the minimum error, the version, and the diagnostic command you used.

Node/npm

Node does not exist in the terminal

Visible symptom: The terminal says node is not recognized or the command does not exist.
What it means: Node is not installed, is not on PATH, or you are using a different terminal than the one you configured.
Before touching anything: Close and reopen the terminal. On Windows, try normal PowerShell before changing permissions.
Safe diagnostic: Check the visible Node version.

node --version

Expected output: a version such as v22.x or v24.x. For OpenClaw, keep Node 22 or Node 24 unless the documentation for your version asks for something else.

Safe action: install or select Node with nvm. Avoid fixing global permissions with sudo: if npm fails with EACCES, use nvm or a user prefix.

npm config set prefix ~/.npm-global

If it still fails: check which terminal your editor or panel uses. On servers, document the version with node --version before reinstalling.

Risk: SAFE. It does not change services or data.

npm says package.json is missing

Visible symptom: npm shows ENOENT or appears to run from the wrong folder.
What it means: You are outside the project folder or downloaded an incomplete part.
Before touching anything: Do not reinstall dependencies blindly. First check where you are.
Safe diagnostic: List the current folder and look for package.json.

ls -la

Expected output: package.json should appear. If it does not, move to the project folder before running npm.

Safe action: open the correct folder and rerun the original command.

If it still fails: check whether you downloaded the full ZIP or only a subdirectory.

Risk: SAFE.

OpenClaw install

OpenClaw does not start or cannot find configuration

Visible symptom: The CLI fails on startup, cannot find profiles, or shows incomplete-configuration warnings.
What it means: Configuration, an environment variable, or a compatible Node version may be missing.
Before touching anything: Do not paste openclaw.json into chats. If it contains secrets, treat it as a credential.
Safe diagnostic: Run the general OpenClaw diagnostic.

openclaw doctor

Expected output: sections with checks and a line like Check: ok or specific warnings. A warning explains what is missing; do not hide it with mass reinstalls.

Safe action: fix the first red warning, restart the terminal session, and run openclaw doctor again.

If it still fails: save the minimal output to a local file and remove secrets before sharing it.

Risk: SAFE.

A skill promises too much or asks for strange permissions

Visible symptom: A ClawHub skill looks useful, but you do not know what it does internally.
What it means: VirusTotal and metadata are telemetry, not a guarantee. Third-party skills are untrusted until you read them.
Before touching anything: Do not install the skill in your main agent. Read it and test it in isolation.
Safe diagnostic: Verify the listing and declared files.

openclaw skills verify <slug>

Expected output: author, files, requested permissions, and warnings. If you cannot read SKILL.md or do not understand permissions, do not install it.

Safe action: install first in a test agent with no secrets and no broad permissions.

If it still fails: look for an official alternative or write a small manual procedure.

Risk: CAUTION.

Gateway

The Gateway does not respond

Visible symptom: The panel, agent, or channel cannot talk to the Gateway.
What it means: The service may be stopped, listening on another port, or not ready yet.
Before touching anything: Do not open public ports to test. Confirm local state first.
Safe diagnostic: Check Gateway status.

openclaw gateway status

Expected output: something equivalent to Gateway: running, local port, and active auth mode.

curl -s http://127.0.0.1:18789/healthz

Expected output: {"ok":true} or an equivalent health response.

curl -s http://127.0.0.1:18789/readyz

Expected output: {"ready":true} or a response showing dependencies are ready.

Safe action: if the service is stopped, restart only the Gateway using your installation method. Do not change bind or firewall to hide a local issue.

If it still fails: review Gateway logs and the last configuration change.

Risk: SAFE for diagnostics; CAUTION for restarts.

The Gateway may be exposed

Visible symptom: Someone can reach port 18789 from outside, or you see bind on a public IP.
What it means: A Gateway listening on 0.0.0.0 or a public IP can be reachable from the internet.
Before touching anything: The safe preference is loopback: 127.0.0.1:18789. No public ports without auth/VPN/tunnel with authentication.
Safe diagnostic: Check status, real socket, and Docker before changing firewall.

openclaw gateway status --json

Safe expected output: bind on 127.0.0.1, auth enabled, and port 18789 not published to the internet.

ss -tlnp | grep 18789

Safe expected output: a line with 127.0.0.1:18789. 0.0.0.0:18789 or a public IP is dangerous unless you deliberately built strong authentication around it.

docker compose ps

Expected output: services running and no public mappings like 0.0.0.0:18789->18789.

Safe action: return to loopback, add authentication, and use VPN, tunnel with Access, or reverse proxy with auth if you truly need remote access.

If it still fails: cut public exposure before debugging convenience.

Risk: DANGEROUS if bind is public.

models/API keys

The model rejects the request

Visible symptom: You see authentication, quota, missing-model, or provider-unavailable errors.
What it means: The API key may not be loaded, the model may have changed, balance may be missing, or the provider may be rate-limiting traffic.
Before touching anything: Do not paste the key or Authorization header. Describe the provider and error code, not the secret.
Safe diagnostic: Review configuration from OpenClaw.

openclaw doctor

Expected output: provider detected, key present as a safe reference, and quota/model warnings if applicable.

Safe action: rotate the key if it was pasted into a chat, add a provider spend limit, and test with a stable model before production.

If it still fails: switch temporarily to a non-critical fallback model and keep human review.

Risk: CAUTION.

Ollama uses too many resources or is exposed

Visible symptom: The machine slows down, the model stays loaded, or port 11434 appears reachable.
What it means: The local model is still in memory or the service is listening where it should not.
Before touching anything: Do not use ollama serve & as the main fix. Prefer a properly configured systemd service or local app, and local bind.
Safe diagnostic: See active models.

ollama ps

Expected output: loaded models, size, and time until unload. If you did not expect any, you can stop it.

ollama stop <modelo>

Safe action: keep Ollama on 127.0.0.1:11434. If you need remote access, put a private network and authentication in front.

If it still fails: review the systemd service or local configuration before opening firewall.

Risk: CAUTION.

channels

Telegram, WhatsApp, or Discord do not receive messages

Visible symptom: The channel does not respond, approvals do not arrive, or the agent speaks in the wrong chat.
What it means: A token, pairing, allowlist, or agent-to-channel binding may be missing.
Before touching anything: Do not paste BotFather tokens or full private IDs into public support.
Safe diagnostic: Check channel status.

openclaw channels status

Expected output: configured channel, auth present as a reference, and binding to the correct agent.

Safe action: limit allowed chats, enable human confirmation for external sends, and separate test and production channels.

If it still fails: review channel-filtered logs, not full logs with tokens.

Risk: CAUTION.

Docker

A container does not start

Visible symptom: Docker shows stopped services or constant restarts.
What it means: Configuration may be invalid, a dependency may be down, or a variable may be missing.
Before touching anything: docker compose down is not a simple restart: it can stop the whole stack and break sessions. Prefer docker compose restart <servicio> when one service is the problem.
Safe diagnostic: Check status before restarting.

docker compose ps

Expected output: services in running or one service marked exited/restarting.

docker ps --format "table {{.Names}}	{{.Status}}	{{.Ports}}"

Expected output: names, status, and published ports. This helps you spot unexpected exposure.

Safe action: restart only the affected service if you know which one it is. Otherwise, inspect scoped logs before touching the stack.

If it still fails: identify the first real error in logs and avoid restart loops.

Risk: CAUTION.

Docker uses too much disk

Visible symptom: The VPS runs out of space and Docker appears to be the main consumer.
What it means: Old images, stopped containers, or volumes can accumulate.
Before touching anything: Do not use docker volume prune or --volumes without a verified backup. Volumes can hold databases, uploads, or configuration.
Safe diagnostic: Measure first.

docker system df

Expected output: a table with Images, Containers, Local Volumes, and Build Cache. The reclaimable field says what might be cleaned, not what you should delete.

docker volume ls

Expected output: a list of volumes. If you do not recognize a volume, do not delete it.

Safe action: clean only resources you understand and that do not support critical services. Document what you delete.

If it still fails: increase disk or move data after backup; do not force aggressive prune on unknown production.

Risk: DANGEROUS if you delete volumes.

browser

The agent cannot open the browser or sees a different page

Visible symptom: Automation fails, CAPTCHA appears, or dynamic content does not load.
What it means: The browser may be missing, the website may block automation, or the session may require 2FA.
Before touching anything: Do not put real credentials into quick tests. Use a persistent profile and minimum permissions.
Safe diagnostic: Confirm OpenClaw's general state first.

openclaw doctor

Expected output: browser or dependency shown as available, or a concrete installation warning.

Safe action: reduce frequency, use explicit waits, and ask the agent for a screenshot before changing selectors.

If it still fails: for frequent CAPTCHA sites, use human intervention or an official API.

Risk: CAUTION.

security/ports

You want to touch firewall or SSH

Visible symptom: You cannot enter through SSH or need to limit access to a port.
What it means: A firewall change can lock you out of the VPS or open it too broadly.
Before touching anything: Keep an SSH session open. Restrict SSH by source when possible and avoid opening 22 to the whole internet.
Safe diagnostic: Check current state and simulate before applying.

ufw status

Expected output: active rules and allowed ports. If 22 ALLOW Anywhere appears, consider restricting it to your IP.

ufw --dry-run allow from TU_IP_PUBLICA to any port 22 proto tcp

Expected output: rule plan without applying it. Replace TU_IP_PUBLICA only in private.

Safe action: apply rules from an open session and keep provider console access available.

If it still fails: use the provider console to revert firewall.

Risk: DANGEROUS if you lose SSH or open broad ports.

VPS/disk/logs

Disk full on the VPS

Visible symptom: Installs fail, Docker does not start, or logs stop writing.
What it means: The disk may be full because of logs, Docker, old backups, or temporary files.
Before touching anything: Do not delete directories blindly. Measure and preserve useful history for investigation.
Safe diagnostic: Start with global space and large folders.

df -h

Expected output: filesystem table. If root is above 85-90 percent, proceed carefully.

du -h -d1 /var /docker 2>/dev/null

Expected output: folder sizes to locate the source before deleting.

journalctl --disk-usage

Expected output: total size used by journald. Only after measuring should you consider vacuum.

journalctl --vacuum-time=3d

Safe action: vacuum can free space, but deletes old investigation history. Use it only after saving what you need.

If it still fails: expand disk from the provider or move data after backup.

Risk: CAUTION; DANGEROUS if you delete needed evidence.

backups/rollback

You are about to change configuration and want a way back

Visible symptom: You need to touch workspace, openclaw.json, Docker, or rules and do not know if you can undo it.
What it means: Without a verified backup, every fix can turn into lost context.
Before touching anything: Create a local copy, confirm it exists, and do not upload it to a public repo.
Safe diagnostic: List the backup folder before and after.

ls -la ~/.openclaw

Expected output: workspace and configuration folders visible with reasonable permissions.

cp -a ~/.openclaw/workspace ~/.openclaw/backups/workspace-pre-fix-$(date +%Y%m%d_%H%M%S)

Expected output: no output if the copy succeeds. Then verify the folder exists.

tar -czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/workspace ~/.openclaw/openclaw.json

Safe action: encrypt the backup if it contains openclaw.json. If an API key already leaked, deleting it is not enough: rotate the key.

If it still fails: roll back from a provider snapshot or a previous verified copy.

Risk: CAUTION because it may copy secrets.