Configuración e Instalación
Guía de instalación y configuración: Mantén tu OpenClaw personalizado mientras te mantienes actualizado.
Última actualización: 2026-01-01
TL;DR
- **Mantén la personalización fuera del repo:** `~/.openclaw/workspace` (espacio de trabajo) + `~/.openclaw/openclaw.json` (config).
- **Flujo de trabajo Estable:** Instala la app macOS y deja que ejecute su propio Gateway.
- **Flujo de trabajo Bleeding Edge:** Ejecuta el Gateway tú mismo con `pnpm gateway:watch` y conecta la app macOS en modo Local.
Requisitos Previos (Ejecutar desde el Código Fuente)
Estrategia de Personalización (Actualizar sin dolores)
Si quieres "100% personalizado para mí" y actualizaciones fáciles, mantén tu contenido personalizado en:
- **Config:** `~/.openclaw/openclaw.json` (estilo JSON/JSON5)
- **Espacio de trabajo:** `~/.openclaw/workspace` (habilidades, prompts, recuerdos; recomendado como repo git privado)
Inicialización por primera vez:
openclaw setup
Dentro de este repositorio, usa la entrada CLI local:
openclaw setup
Si no está instalado globalmente, usa `pnpm openclaw setup`.
Flujo de Trabajo Estable (Prioridad App macOS)
1. 1. Instala e inicia **OpenClaw.app** (barra de menú).
2. 2. Completa la Incorporación / Permisos (popups de autorización TCC).
3. 3. Confirma que el Gateway está en modo **Native** y ejecutándose (gestionado por la app).
4. 4. Conecta plataformas de chat (ejemplo: WhatsApp):
openclaw channels login
5. 5. Verificación de salud:
openclaw health
Si tu build no tiene incorporación:
- Ejecuta `openclaw setup`, `openclaw channels login` en secuencia, luego inicia el Gateway manualmente (`openclaw gateway`).
Flujo de Trabajo Bleeding Edge (Gateway por Terminal)
Objetivo: Desarrollar el Gateway TypeScript con hot-reload mientras mantienes la UI de la app macOS conectada a tu Gateway.
0) (Opcional) Ejecutar App macOS desde el Código Fuente
Si también quieres usar la última app macOS:
./scripts/restart-mac.sh
1) Iniciar Gateway de Desarrollo
pnpm install pnpm gateway:watch
`gateway:watch` ejecuta el gateway en modo watch, recargando automáticamente ante cambios en TypeScript.
2) Conectar App macOS al Gateway en Ejecución
En **OpenClaw.app**:
- Modo de Conexión: Elige **Local**
La app se conectará al gateway en ejecución en el puerto configurado.
3) Verificar
- El estado del Gateway en la app debería mostrar **"Using existing gateway …"**
- O usa la CLI:
openclaw health
Errores Comunes
- **Desajuste de Puerto:** El WS del Gateway predetermina a `ws://127.0.0.1:18789`; la app y la CLI deben usar el mismo puerto.
- **Ubicaciones de Almacenamiento:**
- Credenciales: `~/.openclaw/credentials/`
- Sesiones: `<code1>~/.openclaw/agents/<agentId>/sessions/</code1>`
- Registros: `/tmp/openclaw/`
Mapa de Almacenamiento de Credenciales
Referencia para depurar autenticación o decidir contenido de respaldo:
- **WhatsApp:** `<code1>~/.openclaw/credentials/whatsapp/<accountId>/creds.json</code1>`
- **Token de bot Telegram:** Config / Env, o `channels.telegram.tokenFile`
- **Token de bot Discord:** Config / Env (archivo de token aún no soportado)
- **Tokens Slack:** Config / Env (`channels.slack.*`)
- **Listas permitidas de emparejamiento:** `<code1>~/.openclaw/credentials/<canal>-allowFrom.json</code1>`
- **Perfiles de Auth de Modelos:** `<code1>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code1>`
- **Importaciones OAuth heredadas:** `~/.openclaw/credentials/oauth.json`
Más detalles: Ver Seguridad .
Actualizando (Sin romper tu config)
- - Trata `~/.openclaw/workspace` y `~/.openclaw/` como "tuyos"; no pongas prompts/config personal dentro del repo `openclaw`.
- - Actualiza el código fuente: `git pull` + `pnpm install` (cuando cambie el lockfile) + continúa usando `pnpm gateway:watch`.
Linux (Servicio de Usuario systemd)
Las instalaciones Linux usan servicios de **usuario** systemd. Por defecto, systemd mata los servicios de usuario al cerrar sesión/inactividad. La incorporación intenta habilitar lingering por ti (puede solicitar sudo). Si no está habilitado, ejecuta:
sudo loginctl enable-linger $USER
Para servidores persistentes o multi-usuario, considera servicios de **sistema** en lugar de servicios de usuario (no se requiere lingering). Ver notas de systemd en Runbook del Gateway .