Configuración para desarrolladores

Configuración

ℹ️ Si estás configurando por primera vez, comienza con Primeros pasos. Para detalles del asistente, consulta Asistente de incorporación.

Última actualización: 2026-01-01

TL;DR

  • La personalización vive fuera del repositorio: ~/.openclaw/workspace (espacio de trabajo) + ~/.openclaw/openclaw.json (configuración).
  • Flujo de trabajo estable: instala la aplicación macOS; déjala ejecutar el Gateway incluido.
  • Flujo de trabajo de vanguardia: ejecuta el Gateway tú mismo mediante pnpm gateway:watch, luego deja que la aplicación macOS se conecte en modo Local.

Requisitos previos (desde el código fuente)

  • Node >=22
  • pnpm
  • Docker (opcional; solo para configuración/e2e en contenedores — ver Docker)

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

Si quieres algo "100% personalizado para mí" y actualizaciones fáciles, mantén tu personalización en:

  • Configuración: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
  • Espacio de trabajo: ~/.openclaw/workspace (habilidades, prompts, recuerdos; hazlo un repositorio git privado)

Inicializa una vez:

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 mediante pnpm openclaw setup.

Ejecutar el Gateway desde este repositorio

Después de pnpm build, puedes ejecutar la CLI empaquetada directamente:

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

Flujo de trabajo estable (primero la aplicación macOS)

  1. Instala + inicia OpenClaw.app (barra de menú).
  2. Completa la lista de verificación de incorporación/permisos (solicitudes TCC).
  3. Asegúrate de que el Gateway esté en Local y ejecutándose (la aplicación lo gestiona).
  4. Vincula superficies (ejemplo: WhatsApp):
openclaw channels login
  1. Verificación de funcionamiento:
openclaw health

Si la incorporación no está disponible en tu compilación:

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

Flujo de trabajo de vanguardia (Gateway en una terminal)

Objetivo: trabajar en el Gateway TypeScript, obtener recarga en caliente, mantener la interfaz de usuario de la aplicación macOS conectada.

0) (Opcional) Ejecutar también la aplicación macOS desde el código fuente

Si también quieres la aplicación macOS en la vanguardia:

./scripts/restart-mac.sh

1) Iniciar el Gateway de desarrollo

pnpm install
pnpm gateway:watch

gateway:watch ejecuta el gateway en modo de observación y se recarga con los cambios de TypeScript.

2) Dirigir la aplicación macOS a tu Gateway en ejecución

En OpenClaw.app:

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

3) Verificar

  • El estado del Gateway en la aplicación debería mostrar "Usando gateway existente …"
  • O mediante la CLI:
openclaw health

Errores comunes

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

Mapa de almacenamiento de credenciales

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

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Token de bot de Telegram: configuración/env o channels.telegram.tokenFile
  • Token de bot de Discord: configuración/env o SecretRef (proveedores env/file/exec)
  • Tokens de Slack: configuración/env (channels.slack.*)
  • Listas de permitidos de emparejamiento:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (cuenta predeterminada)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (cuentas no predeterminadas)
  • Perfiles de autenticación de modelos: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Carga útil de secretos respaldada por archivo (opcional): ~/.openclaw/secrets.json
  • Importación heredada de OAuth: ~/.openclaw/credentials/oauth.json Más detalles: Seguridad.

Actualizar (sin arruinar tu configuración)

  • Mantén ~/.openclaw/workspace y ~/.openclaw/ como "tus cosas"; no pongas prompts/configuración personal en el repositorio openclaw.
  • Actualizar el código fuente: git pull + pnpm install (cuando cambie el archivo de bloqueo) + sigue usando pnpm gateway:watch.

Linux (servicio de usuario systemd)

Las instalaciones de Linux usan un servicio de usuario systemd. Por defecto, systemd detiene los servicios de usuario al cerrar sesión/inactividad, lo que mata el Gateway. La incorporación intenta habilitar la permanencia por ti (puede solicitar 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 se necesita permanencia). Consulta el Manual del Gateway para ver las notas sobre systemd.

Documentación relacionada

Inmersión profunda en gestión de sesionesFlujo de trabajo de desarrollo Pi