Setup

Nota: Si es tu primera vez configurando, empieza por Primeros pasos. Para detalles del asistente, consulta Asistente de onboarding.

Última actualización: 2026-01-01

Resumen rápido

  • La personalización vive fuera del repositorio: ~/.openclaw/workspace (workspace) + ~/.openclaw/openclaw.json (configuración).
  • Flujo estable: instala la app de macOS; deja que ejecute el Gateway integrado.
  • Flujo bleeding edge: ejecuta el Gateway tú mismo con pnpm gateway:watch y conecta la app de macOS en modo Local.

Requisitos previos (desde el código fuente)

  • Node >=22
  • pnpm
  • Docker (opcional; solo para configuración en contenedor o e2e: consulta Docker)

Estrategia de personalización (para que las actualizaciones no rompan nada)

Si quieres “100% a tu medida” y actualizaciones sin dolor, mantén tu personalización en:

  • Configuración: ~/.openclaw/openclaw.json (JSON/JSON5)
  • Workspace: ~/.openclaw/workspace (skills, prompts, memorias; conviértelo en un repositorio git privado)

Inicialización única:

openclaw setup

Desde dentro de este repositorio, usa la entrada CLI local:

openclaw setup

Si aún no tienes una instalación global, ejecútalo con pnpm openclaw setup.

Ejecutar el Gateway desde este repositorio

Después de pnpm build, puedes ejecutar el CLI empaquetado directamente:

node openclaw.mjs gateway --port 18789 --verbose

Flujo estable (primero la app de macOS)

  1. Instala y abre OpenClaw.app (barra de menú).
  2. Completa el checklist de onboarding/permisos (ventanas de TCC).
  3. Verifica que el Gateway está en modo Local y corriendo (la app lo gestiona).
  4. Vincula superficies (ejemplo: WhatsApp):
openclaw channels login
  1. Comprobación rápida:
openclaw health

Si el onboarding no está disponible en tu build:

  • Ejecuta openclaw setup, luego openclaw channels login, y después inicia el Gateway manualmente (openclaw gateway).

Flujo bleeding edge (Gateway en terminal)

Objetivo: trabajar en el Gateway TypeScript, obtener recarga en caliente y mantener la UI de la app de macOS conectada.

0) (Opcional) Ejecutar la app de macOS desde el código fuente

Si también quieres la app de macOS en bleeding edge:

./scripts/restart-mac.sh

1) Iniciar el Gateway en modo desarrollo

pnpm install
pnpm gateway:watch

gateway:watch ejecuta el gateway en modo watch y recarga ante cambios en TypeScript.

2) Apuntar la app de macOS a tu Gateway en ejecución

En OpenClaw.app:

  • Modo de conexión: Local La app se conectará al gateway corriendo en el puerto configurado.

3) Verificar

  • El estado del Gateway en la app debería mostrar “Using existing gateway …”
  • O desde el CLI:
openclaw health

Errores frecuentes

  • Puerto incorrecto: El WebSocket del Gateway usa por defecto ws://127.0.0.1:18789; mantén app + CLI en el mismo puerto.
  • Dónde vive el estado:
    • Credenciales: ~/.openclaw/credentials/
    • Sesiones: ~/.openclaw/agents/<agentId>/sessions/
    • Logs: /tmp/openclaw/

Mapa de almacenamiento de credenciales

Usa esto para depurar autenticación o decidir qué respaldar:

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Token de bot de Telegram: config/env o channels.telegram.tokenFile (solo archivos regulares; los symlinks se rechazan)
  • Token de bot de Discord: config/env o SecretRef (proveedores env/file/exec)
  • Tokens de Slack: config/env (channels.slack.*)
  • Allowlists de emparejamiento:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (cuenta por defecto)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (cuentas adicionales)
  • Perfiles de auth de modelos: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Payload de secretos en archivo (opcional): ~/.openclaw/secrets.json
  • Importación OAuth legacy: ~/.openclaw/credentials/oauth.json Más detalles: Seguridad.

Actualizar (sin romper tu configuración)

  • Mantén ~/.openclaw/workspace y ~/.openclaw/ como “tus cosas”; no pongas prompts ni configuración personal dentro del repositorio openclaw.
  • Para actualizar el código fuente: git pull + pnpm install (cuando haya cambiado el lockfile) + sigue usando pnpm gateway:watch.

Linux (servicio de usuario systemd)

Las instalaciones en Linux usan un servicio de usuario de systemd. Por defecto, systemd detiene los servicios de usuario al cerrar sesión o en idle, lo que mata el Gateway. El onboarding intenta activar lingering por ti (puede pedir sudo). Si sigue desactivado, ejecuta:

sudo loginctl enable-linger $USER

Para servidores siempre activos o multiusuario, considera un servicio de sistema en lugar de un servicio de usuario (no necesita lingering). Consulta la Guía operativa del Gateway para las notas sobre systemd.

Documentación relacionada

arrow_back
Anterior
Session Management Compaction
Siguiente
Pi Dev
arrow_forward