Guía de migración

OpenClaw admite tres rutas de migración: importar desde otro sistema de agentes, mover una instalación existente a una nueva máquina y actualizar un complemento en su lugar.

Importar desde otro sistema de agentes

Utilice los proveedores de migración incluidos para traer instrucciones, servidores MCP, habilidades, configuración de modelo y (opcional) claves API a OpenClaw. Los planes se previsualizan antes de cualquier cambio, los secretos se redactan en los informes y la aplicación está respaldada por una copia de seguridad verificada.

Migrating from Claude

Importar el estado de Claude Code y Claude Desktop, incluyendo CLAUDE.md, servidores MCP, habilidades y comandos de proyecto.

Migrating from Hermes

Importar la configuración de Hermes, proveedores, servidores MCP, memoria, habilidades y claves .env admitidas.

El punto de entrada de la CLI es openclaw migrate. La incorporación también puede ofrecer migración cuando detecta un origen conocido (openclaw onboard --flow import).

Mover OpenClaw a una nueva máquina

Copie el directorio de estado (~/.openclaw/ de forma predeterminada) y su espacio de trabajo para conservar:

• Configuración — openclaw.json y todos los ajustes de la puerta de enlace.
• Autenticación — auth-profiles.json por agente (claves de API más OAuth), más cualquier estado de canal o proveedor bajo credentials/.
• Sesiones — historial de conversaciones y estado del agente.
• Estado del canal — inicio de sesión de WhatsApp, sesión de Telegram y similares.
• Archivos del espacio de trabajo — MEMORY.md, USER.md, habilidades y avisos.

Tip

Ejecute openclaw status en la máquina antigua para confirmar la ruta de su directorio de estado. Los perfiles personalizados usan `~/.openclaw-

/o una ruta establecida medianteOPENCLAW_STATE_DIR`.

Pasos de la migración

1. Stop the gateway and back up

   En la máquina antigua, detenga la puerta de enlace para que los archivos no cambien a mitad de la copia y luego archive:

   openclaw gateway stop
   cd ~
   tar -czf openclaw-state.tgz .openclaw

   Si utiliza varios perfiles (por ejemplo, ~/.openclaw-work), archive cada uno por separado.

2. Instalar OpenClaw en la nueva máquina

   Instale la CLI (y Node si es necesario) en la nueva máquina. Está bien si la incorporación crea un ~/.openclaw/ nuevo. Lo sobrescribirá a continuación.

3. Copiar el directorio de estado y el espacio de trabajo

   Transfiera el archivo a través de scp, rsync -a o una unidad externa, luego extráigalo:

   cd ~
   tar -xzf openclaw-state.tgz

   Asegúrese de que se hayan incluido los directorios ocultos y que la propiedad de los archivos coincida con el usuario que ejecutará el gateway.

4. Ejecutar doctor y verificar

   En la nueva máquina, ejecute Doctor para aplicar las migraciones de configuración y reparar los servicios:

   openclaw doctor
   openclaw gateway restart
   openclaw status

Si Telegram o Discord utilizan la reserva de entorno predeterminada (TELEGRAM_BOT_TOKEN o DISCORD_BOT_TOKEN), verifique que el directorio de estado migrado .env contenga esas claves sin imprimir los valores secretos:

awk -F= '/^(TELEGRAM_BOT_TOKEN|DISCORD_BOT_TOKEN)=/ { print $1 "=present" }' ~/.openclaw/.env

openclaw doctor también advierte cuando una cuenta predeterminada de Telegram o Discord habilitada no tiene un token configurado y la variable de entorno coincidente no está disponible para el proceso del doctor.

Errores comunes

Discrepancia de perfil o directorio de estado

Si el gateway antiguo usaba --profile o OPENCLAW_STATE_DIR y el nuevo no, los canales aparecerán desconectados y las sesiones estarán vacías. Inicie el gateway con el mismo perfil o directorio de estado que migró, luego vuelva a ejecutar openclaw doctor.

Copiar solo openclaw.

Solo el archivo de configuración no es suficiente. Los perfiles de autenticación del modelo se encuentran en `agents/

/agent/auth-profiles.jsony el estado del canal y del proveedor se encuentra encredentials/`. Migre siempre el directorio de estado completo.

Permisos y propiedad

Si copió como root o cambió de usuario, es posible que la puerta de enlace no pueda leer las credenciales. Asegúrese de que el directorio de estado y el espacio de trabajo sean propiedad del usuario que ejecuta la puerta de enlace.

Modo remoto

Si su interfaz apunta a una puerta de enlace remota, el host remoto posee las sesiones y el espacio de trabajo. Migre el host de la puerta de enlace en sí, no su computadora portátil local. Consulte las preguntas frecuentes.

Secretos en copias de seguridad

El directorio de estado contiene perfiles de autenticación, credenciales de canal y otro estado del proveedor. Almacene las copias de seguridad cifradas, evite canales de transferencia inseguros y rote las claves si sospecha una exposición.

Lista de verificación

En la nueva máquina, confirme:

• openclaw status muestra que la puerta de enlace se está ejecutando.
• Los canales siguen conectados (no es necesario volver a emparejarlos).
• El panel se abre y muestra las sesiones existentes.
• Los archivos del espacio de trabajo (memoria, configuraciones) están presentes.

Actualizar un complemento en su lugar

Las actualizaciones de complementos en su lugar conservan el mismo id y claves de configuración del complemento, pero pueden mover el estado en disco al diseño actual. Las guías de actualización específicas de cada complemento se encuentran junto a sus canales:

• Migración de Matrix: límites de recuperación del estado cifrado, comportamiento de las instantáneas automáticas y comandos de recuperación manual.

Relacionado

• openclaw migrate: referencia de CLI para importaciones entre sistemas.
• Resumen de instalación: todos los métodos de instalación.
• Doctor: verificación de estado posterior a la migración.
• Desinstalar: eliminar OpenClaw por completo.