OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Advanced setup

Configuración

Resumen

Elija un flujo de configuración según la frecuencia con la que desee recibir actualizaciones y si desea ejecutar el Gateway personalmente:

  • La personalización se encuentra fuera del repositorio: mantenga la configuración y el espacio de trabajo en ~/.openclaw/openclaw.json y ~/.openclaw/workspace/ para que las actualizaciones del repositorio no los afecten.
  • Flujo estable (recomendado para la mayoría): instale la aplicación para macOS y deje que ejecute el Gateway incluido.
  • Flujo de vanguardia (desarrollo): ejecute el Gateway personalmente mediante pnpm gateway:watch y, después, permita que la aplicación para macOS se conecte en modo Local.

Requisitos previos (desde el código fuente)

  • Se recomienda Node 24.15+ (Node 22 LTS, actualmente 22.22.3+, sigue siendo compatible)
  • Se requiere pnpm para las copias de trabajo del código fuente. OpenClaw carga los plugins incluidos desde los paquetes del espacio de trabajo pnpm extensions/* en modo de desarrollo, por lo que npm install en la raíz no prepara todo el árbol de código fuente.
  • Docker (opcional; solo para configuración en contenedores/E2E; consulte Docker)

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

Si desea que esté «100 % adaptado a sus necesidades» y que las actualizaciones sean sencillas, mantenga sus personalizaciones en:

  • Configuración: ~/.openclaw/openclaw.json (similar a JSON/JSON5)
  • Espacio de trabajo: ~/.openclaw/workspace (Skills, indicaciones, memorias; conviértalo en un repositorio git privado)

Inicialice las carpetas de configuración y del espacio de trabajo una sola vez, sin ejecutar el asistente de incorporación completo:

bash
openclaw setup --baseline

¿Aún no hay una instalación global? Ejecútelo desde este repositorio:

bash
pnpm openclaw setup --baseline

(openclaw setup sin --baseline es un alias de openclaw onboard y ejecuta el asistente interactivo completo).

Ejecutar el Gateway desde este repositorio

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

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

Flujo estable (primero la aplicación para macOS)

  1. Instale e inicie OpenClaw.app (barra de menús).
  2. Complete la lista de comprobación de incorporación y permisos (solicitudes de TCC).
  3. Asegúrese de que el Gateway esté en modo Local y en ejecución (la aplicación lo administra).
  4. Vincule las plataformas (por ejemplo, WhatsApp):
bash
openclaw channels login
  1. Comprobación básica:
bash
openclaw health

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

  • Ejecute openclaw setup, después openclaw channels login y, a continuación, inicie el Gateway manualmente (openclaw gateway).

Flujo de vanguardia (Gateway en una terminal)

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

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

Si también desea usar la versión más reciente de la aplicación para macOS:

bash
./scripts/restart-mac.sh

1) Iniciar el Gateway de desarrollo

bash
pnpm install# Solo en la primera ejecución (o después de restablecer la configuración o el espacio de trabajo local de OpenClaw)pnpm openclaw setuppnpm gateway:watch

gateway:watch inicia o reinicia el proceso de supervisión del Gateway en una sesión de tmux con nombre (openclaw-gateway-watch-main) y se conecta automáticamente desde terminales interactivas. Los shells no interactivos permanecen desconectados y muestran tmux attach -t openclaw-gateway-watch-main; use OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch para mantener desconectada una ejecución interactiva o pnpm gateway:watch:raw para usar el modo de supervisión en primer plano. El supervisor detiene el servicio de Gateway instalado del perfil activo antes de tomar el control de su puerto configurado o predeterminado, lo que evita que el supervisor del servicio sustituya el proceso iniciado desde el código fuente. El servicio permanece instalado; ejecute pnpm openclaw gateway start cuando termine la supervisión. El panel de tmux permanece disponible después de un fallo de inicio para que otra terminal u otro agente puedan conectarse o capturar sus registros. El supervisor recarga cuando hay cambios relevantes en el código fuente, la configuración y los metadatos de los plugins incluidos. Si el Gateway supervisado finaliza durante el inicio, gateway:watch ejecuta openclaw doctor --fix --non-interactive una vez y vuelve a intentarlo; establezca OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 para desactivar esa fase de reparación exclusiva del desarrollo. pnpm gateway:watch no vuelve a compilar dist/control-ui, así que vuelva a ejecutar pnpm ui:build después de cambios en ui/ o use pnpm ui:dev mientras desarrolla la interfaz de Control.

2) Dirigir la aplicación para macOS al Gateway en ejecución

En OpenClaw.app:

  • Connection Mode: 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 debe mostrar "Using existing gateway …"
  • O mediante la CLI:
bash
openclaw health

Errores comunes

  • Puerto incorrecto: el WebSocket del Gateway usa ws://127.0.0.1:18789 de forma predeterminada; mantenga la aplicación y la CLI en el mismo puerto.
  • Ubicación del estado:
    • Estado del canal/proveedor: ~/.openclaw/credentials/
    • Perfiles de autenticación del modelo: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Sesiones y transcripciones: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
    • Artefactos de sesiones heredados o archivados: ~/.openclaw/agents/<agentId>/sessions/
    • Registros: /tmp/openclaw/

Mapa de almacenamiento de credenciales

Utilice esta información al depurar la autenticación o decidir qué debe incluirse en las copias de seguridad:

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Token del bot de Telegram: configuración/entorno o channels.telegram.tokenFile (solo archivos normales; se rechazan los enlaces simbólicos)
  • Token del bot de Discord: configuración/entorno o SecretRef (proveedores de entorno/archivo/ejecución)
  • Tokens de Slack: configuración/entorno (channels.slack.*)
  • Listas de permitidos para el 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
  • Contenido de secretos respaldado por archivos (opcional): ~/.openclaw/secrets.json
  • Importación de OAuth heredado: ~/.openclaw/credentials/oauth.json Más detalles: Seguridad.

Actualización (sin estropear la configuración)

  • Mantenga ~/.openclaw/workspace y ~/.openclaw/ como «sus propios elementos»; no coloque indicaciones ni configuraciones personales en el repositorio openclaw.
  • Actualización del código fuente: git pull + pnpm install + continúe usando pnpm gateway:watch.

Linux (servicio de usuario de systemd)

Las instalaciones en Linux utilizan un servicio de usuario de systemd. De forma predeterminada, systemd detiene los servicios del usuario al cerrar sesión o quedar inactivo, lo que finaliza el Gateway. La incorporación intenta habilitar la persistencia de la sesión de usuario (puede solicitar sudo). Si aún está desactivada, ejecute:

bash
sudo loginctl enable-linger $USER

Para servidores siempre activos o multiusuario, considere usar un servicio de sistema en lugar de un servicio de usuario (no requiere persistencia de la sesión). Consulte el manual operativo del Gateway para obtener información sobre systemd.

Documentación relacionada

Was this useful?
On this page

On this page