Asistente de onboarding (CLI)

El asistente de onboarding es la forma recomendada de configurar OpenClaw en macOS, Linux o Windows (vía WSL2; muy recomendado). Configura un Gateway local o una conexión a un Gateway remoto, además de canales, skills y valores por defecto del workspace, todo en un solo flujo guiado.

openclaw onboard

Info: El camino más rápido al primer chat: abre la Control UI (no necesitas configurar ningún canal). Ejecuta openclaw dashboard y chatea desde el navegador. Documentación: Dashboard.

Para reconfigurar más adelante:

openclaw configure
openclaw agents add <nombre>

Nota: --json no implica modo no interactivo. Para scripts, usa --non-interactive.

Consejo: El asistente de onboarding incluye un paso de búsqueda web donde puedes elegir un proveedor (Perplexity, Brave, Gemini, Grok o Kimi) y pegar tu API key para que el agente pueda usar web_search. También puedes configurar esto después con openclaw configure --section web. Documentación: Herramientas web.

QuickStart vs Avanzado

El asistente comienza ofreciendo QuickStart (valores por defecto) vs Avanzado (control total).

QuickStart (valores por defecto)

- Gateway local (loopback)
- Workspace por defecto (o workspace existente)
- Puerto del Gateway **18789**
- Autenticación del Gateway por **Token** (auto-generado, incluso en loopback)
- Política de herramientas por defecto para nuevas instalaciones locales: `tools.profile: "coding"` (un perfil explícito existente se preserva)
- Aislamiento de DMs por defecto: el onboarding local escribe `session.dmScope: "per-channel-peer"` cuando no está definido. Detalles: [Referencia del onboarding CLI](/docs/start/wizard-cli-reference#outputs-and-internals)
- Exposición vía Tailscale **Desactivada**
- DMs en Telegram + WhatsApp por defecto en modo **allowlist** (se te pedirá tu número de teléfono)

Avanzado (control total)

- Expone cada paso (modo, workspace, gateway, canales, daemon, skills).

Qué configura el asistente

Modo local (por defecto) te guía por estos pasos:

  1. Modelo/Auth — elige cualquier proveedor/flujo de autenticación compatible (API key, OAuth o setup-token), incluyendo Custom Provider (compatible con OpenAI, compatible con Anthropic, o Unknown con auto-detección). Selecciona un modelo por defecto. Nota de seguridad: si este agente ejecutará herramientas o procesará contenido de webhooks/hooks, usa el modelo más potente de última generación disponible y mantén la política de herramientas estricta. Los modelos más débiles o antiguos son más fáciles de manipular por prompt injection. Para ejecuciones no interactivas, --secret-input-mode ref almacena referencias respaldadas por variables de entorno en los perfiles de auth en lugar de valores de API key en texto plano. En modo no interactivo con ref, la variable de entorno del proveedor debe estar definida; pasar flags de key inline sin esa variable de entorno falla inmediatamente. En ejecuciones interactivas, elegir el modo de referencia de secretos te permite apuntar a una variable de entorno o a una referencia de proveedor configurada (file o exec), con una validación rápida antes de guardar.
  2. Workspace — Ubicación de los archivos del agente (por defecto ~/.openclaw/workspace). Genera archivos de bootstrap.
  3. Gateway — Puerto, dirección de bind, modo de autenticación, exposición vía Tailscale. En modo de token interactivo, puedes elegir entre almacenamiento de token en texto plano por defecto u optar por SecretRef. Ruta no interactiva para token SecretRef: --gateway-token-ref-env <ENV_VAR>.
  4. Canales — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles o iMessage.
  5. Daemon — Instala un LaunchAgent (macOS) o una unidad de usuario systemd (Linux/WSL2). Si la autenticación por token requiere un token y gateway.auth.token es gestionado por SecretRef, la instalación del daemon lo valida pero no persiste el token resuelto en los metadatos del entorno del servicio supervisor. Si la autenticación por token requiere un token y el SecretRef configurado no está resuelto, la instalación del daemon se bloquea con indicaciones sobre cómo proceder. Si tanto gateway.auth.token como gateway.auth.password están configurados y gateway.auth.mode no está definido, la instalación del daemon se bloquea hasta que el modo se defina explícitamente.
  6. Health check — Inicia el Gateway y verifica que esté corriendo.
  7. Skills — Instala skills recomendadas y dependencias opcionales.

Nota: Volver a ejecutar el asistente no borra nada a menos que elijas explícitamente Reset (o pases --reset). El flag --reset del CLI aplica por defecto a configuración, credenciales y sesiones; usa --reset-scope full para incluir el workspace. Si la configuración es inválida o contiene claves legacy, el asistente te pide ejecutar openclaw doctor primero.

Modo remoto solo configura el cliente local para conectarse a un Gateway en otra ubicación. No instala ni modifica nada en el host remoto.

Añadir otro agente

Usa openclaw agents add <nombre> para crear un agente independiente con su propio workspace, sesiones y perfiles de auth. Ejecutarlo sin --workspace lanza el asistente.

Qué configura:

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

Notas:

  • Los workspaces por defecto siguen el patrón ~/.openclaw/workspace-<agentId>.
  • Añade bindings para enrutar mensajes entrantes (el asistente puede hacerlo).
  • Flags no interactivos: --model, --agent-dir, --bind, --non-interactive.

Referencia completa

Para desgloses paso a paso detallados y las salidas de configuración, consulta Referencia del onboarding CLI. Para ejemplos no interactivos, consulta Automatización CLI. Para la referencia técnica más profunda, incluyendo detalles de RPC, consulta Referencia del asistente.

Documentación relacionada

arrow_back
Anterior
Onboarding Overview
Siguiente
Onboarding
arrow_forward