Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Si estás configurando por primera vez, empieza con Primeros pasos. Para detalles de incorporación, consulta Incorporación (CLI).

​
Resumen

Elige un flujo de configuración según la frecuencia con la que quieras recibir actualizaciones y si quieres ejecutar el Gateway por tu cuenta:
  • La personalización vive fuera del repositorio: mantén tu configuración y espacio de trabajo en ~/.openclaw/openclaw.json y ~/.openclaw/workspace/ para que las actualizaciones del repositorio no los toquen.
  • Flujo estable (recomendado para la mayoría): instala la app de macOS y deja que ejecute el Gateway incluido.
  • Flujo de última generación (desarrollo): ejecuta el Gateway por tu cuenta mediante pnpm gateway:watch y luego deja que la app de macOS se conecte en modo Local.

​
Requisitos previos (desde el código fuente)

  • Se recomienda Node 24 (Node 22 LTS, actualmente 22.16+, sigue siendo compatible)
  • pnpm es obligatorio para checkouts desde código fuente. OpenClaw carga plugins incluidos desde los paquetes del espacio de trabajo pnpm extensions/* en modo de desarrollo, así que npm install en la raíz no prepara todo el árbol de código fuente.
  • Docker (opcional; solo para configuración/e2e en contenedores; consulta Docker)

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

Si quieres algo “100 % adaptado a mí” y actualizaciones sencillas, mantén tu personalización en:
  • Configuración: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
  • Espacio de trabajo: ~/.openclaw/workspace (skills, prompts, memorias; conviértelo en un repositorio git privado)
Inicializa una vez: 
openclaw setup
Desde dentro de este repositorio, usa la entrada de CLI local: 
openclaw setup
Si todavía 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 estable (primero la app de macOS)

  1. Instala e inicia OpenClaw.app (barra de menús).
  2. Completa la lista de incorporación/permisos (avisos de TCC).
  3. Asegúrate de que el Gateway esté en Local y en ejecución (la app lo administra).
  4. Vincula superficies (ejemplo: WhatsApp):
openclaw channels login
  1. Comprobación básica:
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 última generación (Gateway en una terminal)

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

​
0) (Opcional) Ejecuta también la app de macOS desde el código fuente

Si también quieres la app de macOS en la última generación: 
./scripts/restart-mac.sh

​
1) Inicia el Gateway de desarrollo

pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch
gateway:watch inicia o reinicia el proceso de vigilancia del Gateway en una sesión tmux con nombre y se adjunta automáticamente desde terminales interactivas. Los shells no interactivos permanecen separados e imprimen tmux attach -t openclaw-gateway-watch-main; usa OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch para mantener separada una ejecución interactiva, o pnpm gateway:watch:raw para el modo de vigilancia en primer plano. El observador recarga ante cambios relevantes en el código fuente, la configuración y los metadatos de plugins incluidos. Si el Gateway observado se cierra durante el arranque, gateway:watch ejecuta openclaw doctor --fix --non-interactive una vez y reintenta; define OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 para desactivar esa pasada de reparación solo para desarrollo. pnpm openclaw setup es el paso único de inicialización de configuración/espacio de trabajo local para un checkout nuevo. pnpm gateway:watch no recompila dist/control-ui, así que vuelve a ejecutar pnpm ui:build después de cambios en ui/ o usa pnpm ui:dev mientras desarrollas la Control UI.

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

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

​
3) Verifica

  • El estado del Gateway en la app debería indicar “Usando gateway existente …”
  • O mediante CLI:
openclaw health

​
Problemas comunes

  • Puerto incorrecto: el WS del Gateway usa de forma predeterminada ws://127.0.0.1:18789; mantén la app y la CLI en el mismo puerto.
  • Dónde vive el estado:
    • Estado de canal/proveedor: ~/.openclaw/credentials/
    • Perfiles de autenticación del modelo: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • 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 (solo archivo normal; se rechazan enlaces simbólicos)
  • Token de bot de Discord: configuración/env o SecretRef (proveedores env/file/exec)
  • Tokens de Slack: configuración/env (channels.slack.*)
  • Listas de permisos de emparejamiento:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (cuenta predeterminada)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (cuentas no predeterminadas)
  • Perfiles de autenticación del modelo: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Carga útil de secretos respaldada por archivo (opcional): ~/.openclaw/secrets.json
  • Importación de OAuth heredado: ~/.openclaw/credentials/oauth.json Más detalles: Seguridad.

​
Actualización (sin destrozar tu configuración)

  • Mantén ~/.openclaw/workspace y ~/.openclaw/ como “tus cosas”; no pongas prompts/configuración personales en el repositorio openclaw.
  • Actualizar el código fuente: git pull + pnpm install + seguir usando pnpm gateway:watch.

​
Linux (servicio de usuario systemd)

Las instalaciones de Linux usan un servicio de usuario systemd. De forma predeterminada, systemd detiene los servicios de usuario al cerrar sesión o quedar inactivo, lo que mata el Gateway. La incorporación intenta habilitar 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 el runbook del Gateway para las notas de systemd.

​
Documentos relacionados