Migrar OpenClaw a una nueva máquina

Esta guía migra un Gateway de OpenClaw de una máquina a otra sin repetir el onboarding.

Conceptualmente es simple:

Copia el directorio de estado ($OPENCLAW_STATE_DIR, por defecto: ~/.openclaw/) — incluye config, auth, sesiones y estado de canales.
Copia tu workspace (~/.openclaw/workspace/ por defecto) — incluye archivos del agente (memoria, prompts, etc.).

Pero hay errores comunes con perfiles, permisos y copias parciales.

Antes de empezar (qué estás migrando)

1) Identifica tu directorio de estado

La mayoría de instalaciones usan el valor por defecto:

Directorio de estado: ~/.openclaw/

Pero puede ser diferente si usas:

--profile <name> (suele ser ~/.openclaw-<profile>/)
OPENCLAW_STATE_DIR=/some/path

Si no estás seguro, ejecuta en la máquina antigua:

openclaw status

Busca menciones de OPENCLAW_STATE_DIR / perfil en la salida. Si ejecutas múltiples gateways, repite para cada perfil.

2) Identifica tu workspace

Valores por defecto comunes:

~/.openclaw/workspace/ (workspace recomendado)
una carpeta personalizada que creaste

Tu workspace es donde viven archivos como MEMORY.md, USER.md y memory/*.md.

3) Entiende qué preservarás

Si copias ambos (directorio de estado y workspace), conservas:

Configuración del gateway (openclaw.json)
Perfiles de auth / API keys / tokens OAuth
Historial de sesiones + estado del agente
Estado de canales (ej. login/sesión de WhatsApp)
Archivos del workspace (memoria, notas de skills, etc.)

Si copias solo el workspace (ej. vía Git), no conservas:

sesiones
credenciales
logins de canales

Esos viven bajo $OPENCLAW_STATE_DIR.

Pasos de migración (recomendados)

Paso 0 — Hacer backup (máquina antigua)

En la máquina antigua, detén el gateway primero para que los archivos no cambien durante la copia:

openclaw gateway stop

(Opcional pero recomendado) archiva el directorio de estado y workspace:

cd ~
tar -czf openclaw-state.tgz .openclaw
tar -czf openclaw-workspace.tgz .openclaw/workspace

Paso 1 — Instalar OpenClaw en la nueva máquina

En la máquina nueva, instala el CLI (y Node si es necesario):

Consulta: Instalación

Paso 2 — Copiar directorio de estado + workspace a la nueva máquina

Copia ambos usando scp, rsync -a por SSH, o un disco externo.

Después de copiar, asegúrate de que:

Los directorios ocultos fueron incluidos (ej. .openclaw/)
La propiedad de archivos es correcta para el usuario que ejecuta el gateway

Paso 3 — Ejecutar Doctor (migraciones + reparación de servicio)

En la máquina nueva:

openclaw doctor

Luego:

openclaw gateway restart
openclaw status

Errores comunes (y cómo evitarlos)

Error: desajuste de perfil / directorio de estado

Si ejecutaste el gateway antiguo con un perfil (o OPENCLAW_STATE_DIR) y el nuevo gateway usa uno diferente, verás síntomas como config que no toma efecto, canales faltantes o historial de sesiones vacío.

Error: copiar solo `openclaw.json`

openclaw.json no es suficiente. Siempre migra la carpeta $OPENCLAW_STATE_DIR completa.

Error: permisos / propiedad

Si copiaste como root o cambiaste de usuario, el gateway puede no poder leer credenciales/sesiones.

Error: secretos en backups

$OPENCLAW_STATE_DIR contiene secretos. Trata los backups como secretos de producción.

Lista de verificación

En la nueva máquina, confirma:

openclaw status muestra el gateway ejecutándose
Tus canales siguen conectados
El dashboard se abre y muestra sesiones existentes
Tus archivos del workspace están presentes