Referencia del onboarding CLI

Esta página es la referencia completa de openclaw onboard. Para la guía resumida, consulta Asistente de onboarding (CLI).

Qué hace el asistente

El modo local (por defecto) te guía por:

• Configuración de modelo y autenticación (suscripción OpenAI Code con OAuth, API key o setup token de Anthropic, además de opciones para MiniMax, GLM, Ollama, Moonshot y AI Gateway)
• Ubicación del workspace y archivos de bootstrap
• Ajustes del Gateway (puerto, bind, auth, tailscale)
• Canales y proveedores (Telegram, WhatsApp, Discord, Google Chat, plugin de Mattermost, Signal)
• Instalación del daemon (LaunchAgent o unidad de usuario systemd)
• Health check
• Configuración de skills

El modo remoto configura esta máquina para conectarse a un gateway en otra ubicación. No instala ni modifica nada en el host remoto.

Detalles del flujo local

Paso 1: Detección de configuración existente

- Si existe `~/.openclaw/openclaw.json`, puedes elegir Conservar, Modificar o Reiniciar.
- Volver a ejecutar el asistente no borra nada a menos que elijas explícitamente Reiniciar (o pases `--reset`).
- El flag `--reset` del CLI aplica por defecto a `config+creds+sessions`; usa `--reset-scope full` para incluir también el workspace.
- Si la configuración es inválida o contiene claves legacy, el asistente se detiene y pide ejecutar `openclaw doctor` antes de continuar.
- El reinicio usa `trash` y ofrece estos alcances:
  - Solo configuración
  - Configuración + credenciales + sesiones
  - Reinicio completo (también elimina el workspace)

Paso 2: Modelo y autenticación

- La matriz completa de opciones está en [Opciones de autenticación y modelo](#opciones-de-autenticación-y-modelo).

Paso 3: Workspace

- Por defecto `~/.openclaw/workspace` (configurable).
- Genera los archivos del workspace necesarios para el ritual de bootstrap de primera ejecución.
- Estructura del workspace: [Workspace del agente](/docs/concepts/agent-workspace).

Paso 4: Gateway

- Pide puerto, bind, modo de autenticación y exposición vía Tailscale.
- Recomendado: mantén la autenticación por token activa incluso para loopback, así los clientes WS locales deben autenticarse.
- En modo token, el onboarding interactivo ofrece:
  - **Generar/almacenar token en texto plano** (por defecto)
  - **Usar SecretRef** (opt-in)
- En modo password, el onboarding interactivo también permite almacenamiento en texto plano o SecretRef.
- Ruta no interactiva para token SecretRef: `--gateway-token-ref-env <ENV_VAR>`.
  - Requiere una variable de entorno no vacía en el entorno del proceso de onboarding.
  - No se puede combinar con `--gateway-token`.
- Desactiva la autenticación solo si confías plenamente en todos los procesos locales.
- Los binds fuera de loopback igualmente requieren autenticación.

Paso 5: Canales

- [WhatsApp](/docs/channels/whatsapp): login opcional por QR
- [Telegram](/docs/channels/telegram): token del bot
- [Discord](/docs/channels/discord): token del bot
- [Google Chat](/docs/channels/googlechat): JSON de cuenta de servicio + audience del webhook
- [Mattermost](/docs/channels/mattermost) plugin: token del bot + URL base
- [Signal](/docs/channels/signal): instalación opcional de `signal-cli` + configuración de cuenta
- [BlueBubbles](/docs/channels/bluebubbles): recomendado para iMessage; URL del servidor + contraseña + webhook
- [iMessage](/docs/channels/imessage): ruta del CLI `imsg` legacy + acceso a la base de datos
- Seguridad de DMs: por defecto se usa emparejamiento. El primer DM envía un código; apruébalo con
  `openclaw pairing approve <canal> <código>` o usa allowlists.

Paso 6: Instalación del daemon

- macOS: LaunchAgent
  - Requiere sesión de usuario iniciada; para uso headless, usa un LaunchDaemon personalizado (no incluido).
- Linux y Windows vía WSL2: unidad de usuario systemd
  - El asistente intenta ejecutar `loginctl enable-linger <usuario>` para que el gateway siga activo después de cerrar sesión.
  - Puede pedir sudo (escribe en `/var/lib/systemd/linger`); primero intenta sin sudo.
- Selección de runtime: Node (recomendado; requerido para WhatsApp y Telegram). Bun no es recomendado.

Paso 7: Health check

- Inicia el gateway (si es necesario) y ejecuta `openclaw health`.
- `openclaw status --deep` añade sondas de health del gateway a la salida de estado.

Paso 8: Skills

- Lee las skills disponibles y verifica requisitos.
- Te permite elegir gestor de paquetes: npm o pnpm (bun no es recomendado).
- Instala dependencias opcionales (algunas usan Homebrew en macOS).

Paso 9: Finalización

- Resumen y siguientes pasos, incluyendo opciones para las apps de iOS, Android y macOS.

Nota: Si no se detecta interfaz gráfica, el asistente imprime instrucciones de port-forward por SSH para la Control UI en lugar de abrir un navegador. Si faltan los assets de la Control UI, el asistente intenta compilarlos; el fallback es pnpm ui:build (instala automáticamente las dependencias de UI).

Detalles del modo remoto

El modo remoto configura esta máquina para conectarse a un gateway en otra ubicación.

Info: El modo remoto no instala ni modifica nada en el host remoto.

Lo que configuras:

• URL del gateway remoto (ws://...)
• Token si la autenticación del gateway remoto es requerida (recomendado)

Nota:

• Si el gateway es solo loopback, usa túnel SSH o una tailnet.
• Pistas de descubrimiento:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Opciones de autenticación y modelo

Usa `ANTHROPIC_API_KEY` si está presente, o pide la key, y luego la guarda para el daemon.

- macOS: busca el ítem de Keychain "Claude Code-credentials"
- Linux y Windows: reutiliza `~/.claude/.credentials.json` si existe

En macOS, elige "Always Allow" para que los inicios vía launchd no se bloqueen.

Ejecuta `claude setup-token` en cualquier máquina, luego pega el token.
Puedes darle un nombre; déjalo en blanco para usar el valor por defecto.

Si existe `~/.codex/auth.json`, el asistente puede reutilizarlo.

Flujo por navegador; pega `code#state`.

Define `agents.defaults.model` como `openai-codex/gpt-5.4` cuando el modelo no está definido o es `openai/*`.

Usa `OPENAI_API_KEY` si está presente, o pide la key, y luego almacena la credencial en los perfiles de auth.

Define `agents.defaults.model` como `openai/gpt-5.1-codex` cuando el modelo no está definido, es `openai/*`, o es `openai-codex/*`.

Pide `XAI_API_KEY` y configura xAI como proveedor de modelos.

Pide `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`) y te deja elegir entre el catálogo Zen o Go.
URL de configuración: [opencode.ai/auth](https://opencode.ai/auth).

Almacena la key por ti.

Pide `AI_GATEWAY_API_KEY`.
Más detalles: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Pide account ID, gateway ID y `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Más detalles: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

La configuración se escribe automáticamente.
Más detalles: [MiniMax](/docs/providers/minimax).

Pide `SYNTHETIC_API_KEY`.
Más detalles: [Synthetic](/docs/providers/synthetic).

Pide la URL base (por defecto `http://127.0.0.1:11434`), luego ofrece modo Cloud + Local o solo Local.
Descubre modelos disponibles y sugiere valores por defecto.
Más detalles: [Ollama](/docs/providers/ollama).

Las configuraciones de Moonshot (Kimi K2) y Kimi Coding se escriben automáticamente.
Más detalles: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Funciona con endpoints compatibles con OpenAI y compatibles con Anthropic.

El onboarding interactivo admite las mismas opciones de almacenamiento de API key que los demás flujos de proveedores:
- **Pegar API key ahora** (texto plano)
- **Usar referencia de secreto** (ref de entorno o ref de proveedor configurado, con validación previa)

Flags no interactivos:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (opcional; usa `CUSTOM_API_KEY` como fallback)
- `--custom-provider-id` (opcional)
- `--custom-compatibility <openai|anthropic>` (opcional; por defecto `openai`)

Deja la autenticación sin configurar.

Comportamiento del modelo:

• Elige el modelo por defecto entre las opciones detectadas, o ingresa proveedor y modelo manualmente.
• El asistente ejecuta una verificación del modelo y advierte si el modelo configurado es desconocido o le falta autenticación.

Rutas de credenciales y perfiles:

• Credenciales OAuth: ~/.openclaw/credentials/oauth.json
• Perfiles de auth (API keys + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Modo de almacenamiento de credenciales:

• El comportamiento por defecto del onboarding persiste las API keys como valores en texto plano en los perfiles de auth.
• --secret-input-mode ref activa el modo de referencia en lugar de almacenamiento en texto plano. En el onboarding interactivo, puedes elegir entre:
  • referencia de variable de entorno (por ejemplo keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • referencia de proveedor configurado (file o exec) con alias de proveedor + id
• El modo de referencia interactivo ejecuta una validación rápida antes de guardar.
  • Refs de entorno: valida el nombre de la variable + valor no vacío en el entorno actual del onboarding.
  • Refs de proveedor: valida la configuración del proveedor y resuelve el id solicitado.
  • Si la validación falla, el onboarding muestra el error y te permite reintentar.
• En modo no interactivo, --secret-input-mode ref solo funciona con variables de entorno.
  • Define la variable de entorno del proveedor en el entorno del proceso de onboarding.
  • Los flags de key inline (por ejemplo --openai-api-key) requieren que esa variable de entorno esté definida; de lo contrario, el onboarding falla inmediatamente.
  • Para proveedores personalizados, el modo no interactivo con ref almacena models.providers.<id>.apiKey como { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • En ese caso de proveedor personalizado, --custom-api-key requiere que CUSTOM_API_KEY esté definida; de lo contrario, el onboarding falla inmediatamente.
• Las credenciales de autenticación del Gateway admiten opciones de texto plano y SecretRef en el onboarding interactivo:
  • Modo token: Generar/almacenar token en texto plano (por defecto) o Usar SecretRef.
  • Modo password: texto plano o SecretRef.
• Ruta no interactiva para token SecretRef: --gateway-token-ref-env <ENV_VAR>.
• Las configuraciones existentes en texto plano siguen funcionando sin cambios.

Nota: Consejo para servidores y uso headless: completa OAuth en una máquina con navegador, luego copia ~/.openclaw/credentials/oauth.json (o $OPENCLAW_STATE_DIR/credentials/oauth.json) al host del gateway.

Salidas e internos

Campos típicos en ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.model / models.providers (si se eligió Minimax)
• tools.profile (el onboarding local lo establece en "coding" por defecto cuando no está definido; los valores explícitos existentes se preservan)
• gateway.* (modo, bind, auth, tailscale)
• session.dmScope (el onboarding local lo establece en per-channel-peer por defecto cuando no está definido; los valores explícitos existentes se preservan)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Allowlists de canales (Slack, Discord, Matrix, Microsoft Teams) cuando optas por ellas durante las preguntas (los nombres se resuelven a IDs cuando es posible)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add escribe agents.list[] y bindings opcionales.

Las credenciales de WhatsApp van en ~/.openclaw/credentials/whatsapp/<accountId>/. Las sesiones se almacenan en ~/.openclaw/agents/<agentId>/sessions/.

Nota: Algunos canales se entregan como plugins. Cuando se seleccionan durante el onboarding, el asistente pide instalar el plugin (npm o ruta local) antes de la configuración del canal.

RPC del asistente del Gateway:

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Los clientes (app de macOS y Control UI) pueden renderizar los pasos sin re-implementar la lógica del onboarding.

Comportamiento de la configuración de Signal:

• Descarga el asset de release correspondiente
• Lo almacena en ~/.openclaw/tools/signal-cli/<version>/
• Escribe channels.signal.cliPath en la configuración
• Los builds JVM requieren Java 21
• Los builds nativos se usan cuando están disponibles
• Windows usa WSL2 y sigue el flujo de signal-cli para Linux dentro de WSL

Documentación relacionada

• Hub de onboarding: Asistente de onboarding (CLI)
• Automatización y scripts: Automatización CLI
• Referencia del comando: openclaw onboard