Asistente de Incorporación
Guías para usar el asistente de incorporación para configurar OpenClaw manualmente o mediante flujo guiado.
El asistente de incorporación es la forma **recomendada** de configurar OpenClaw en macOS, Linux o Windows (via WSL2; muy recomendado). Te guía a través de la configuración de conexiones de Gateway locales o remotas, canales, habilidades y valores predeterminados del espacio de trabajo.
Entrada principal:
openclaw onboard
La forma más rápida de tener el primer chat: UI de Control Abierto (no se necesita configuración de canal). Ejecuta
`openclaw dashboard` luego chatea en el navegador. Docs: Dashboard.
Reconfiguración posterior:
openclaw configure
Recomendado: Establece la clave API de Brave Search para que los agentes puedan usar `web_search`
(`web_fetch` funciona sin clave). La forma más fácil: `openclaw configure --section web`
Almacenará `tools.web.search.apiKey`. Docs: Herramienta Web.
Inicio Rápido vs. Modo Avanzado
El asistente comienza en **Inicio Rápido** (configuración predeterminada) vs **Avanzado** (control total).
**Inicio Rápido** mantiene los valores predeterminados:
Gateway Local (loopback)
Espacio de trabajo predeterminado (o existente)
Puerto del Gateway **18789**
Auth del Gateway **token** (autogenerado, incluso en loopback)
Exposición Tailscale **desactivada**
DMs de Telegram + WhatsApp predeterminados a **lista permitida** (se te pedirá tu número)
**Avanzado** muestra cada paso (modo, espacio de trabajo, gateway, canales, daemon, habilidades).
Qué Hace el Asistente
**Modo Local (Predeterminado)** te guía a través de:
Modelos/Auth (sub OpenAI Codex via OAuth, clave API Anthropic (recomendado) o setup-token (pegar), más opciones para MiniMax/GLM/Moonshot/AI Gateway)
Ubicación del espacio de trabajo + archivos de inicialización
Configuración del Gateway (puerto/enlace/auth/Tailscale)
Proveedores (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)
Instalación del daemon (LaunchAgent / unidad de usuario systemd)
Verificaciones de salud
Habilidades (recomendadas)
**Modo Remoto** solo configura el cliente local para conectarse a un Gateway en otro lugar. **No** instala ni cambia nada en el host remoto.
Para añadir más agentes aislados (espacio de trabajo + sesiones + auth separados), usa:
openclaw agents add '<nombre>'
Consejo: `--json` **no** significa no interactivo. Usa `--non-interactive` (junto con `--workspace`) para scripts.
Detalles del Flujo (Local)
1. Detección de Configuración Existente
Si `~/.openclaw/openclaw.json` existe, elige **Mantener / Modificar / Reiniciar**.
Volver a ejecutar el asistente **nunca** elimina nada a menos que elijas explícitamente **Reiniciar** (o pases `--reset`).
Si la configuración es inválida o tiene claves heredadas, el asistente se detiene y te pide ejecutar `openclaw doctor` antes de continuar.
Reiniciar usa `trash` (nunca `rm`) y ofrece ámbitos:
- Solo configuración
- Configuración + Credenciales + Sesiones
- Reinicio completo (elimina también el espacio de trabajo)
2. Modelos/Auth
**Clave API Anthropic (Recomendado)**: Usa `ANTHROPIC_API_KEY` si está presente o solicita la clave, luego guarda para uso del daemon.
**OAuth Anthropic (CLI Claude Code)**: En macOS, el asistente verifica el ítem del llavero "Claude Code-credentials" (elige "Permitir Siempre" para evitar bloqueo de launchd); en Linux/Windows, reutiliza `~/.claude/.credentials.json` si está presente.
**Token Anthropic (Pegar setup-token)**: Ejecuta `claude setup-token` en cualquier máquina y pega el token.
**Sub OpenAI Codex (CLI Codex)**: Si `~/.codex/auth.json` existe, el asistente puede reutilizarlo.
**Sub OpenAI Codex (OAuth)**: Flujo del navegador; pega `code#state`.
Establece `agents.defaults.model` a `openai-codex/gpt-5.2` cuando no está establecido o `openai/*`.
**Clave API OpenAI**: Usa `OPENAI_API_KEY` si está presente o solicita, guardando en `~/.openclaw/.env` para launchd.
**OpenCode Zen (Proxy multi-modelo)**: Solicita `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`, consíguela en opencode.ia/auth).
**Claves API**: Almacena claves para ti.
**Vercel AI Gateway (Proxy multi-modelo)**: Solicita `AI_GATEWAY_API_KEY`. Más info: Vercel AI Gateway
**MiniMax M2.1**: Configuración escrita automáticamente. Más info: MiniMax
**Synthetic (Compatible con Anthropic)**: Solicita `SYNTHETIC_API_KEY`. Más info: Synthetic
**Moonshot (Kimi K2)**: Configuración escrita automáticamente.
**Kimi Coding**: Configuración escrita automáticamente. Más info: Moonshot AI
**Omitir**: Sin auth configurado aún.
Elige el modelo predeterminado de las opciones detectadas (o entrada manual).
El asistente ejecuta verificaciones de modelo y advierte si el modo es desconocido o falta auth.
Creds OAuth almacenadas en `<code1>~/.openclaw/credentials/oauth.json</code1>`; Config Auth en `<code2>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code2>`. Más info: <link6>Conceptos OAuth</link6>
3. Espacio de Trabajo
Por defecto `~/.openclaw/workspace` (configurable).
Genera archivos del espacio de trabajo para la ceremonia de inicio del agente.
Diseño completo del espacio de trabajo y guía de respaldo: Espacio de Trabajo del Agente
4. Gateway
Puerto, Enlace, Modo Auth, Exposición Tailscale.
Recomendación de auth: Mantén **token** incluso en loopback para asegurar que los clientes WS locales deban autenticarse.
Solo desactiva auth si confías en cada proceso local.
Enlaces no loopback requieren auth.
5. Canales
WhatsApp: Login QR opcional.
Telegram: Token de bot.
Discord: Token de bot.
Google Chat: JSON de cuenta de servicio + audiencia webhook.
Mattermost (plugin): Token de bot + URL Base.
Signal: Instalación opcional de `signal-cli` + configuración de cuenta.
iMessage: Ruta CLI local `imsg` + acceso DB.
Seguridad DM: Por defecto en modo Emparejamiento. El primer DM envía un código; aprueba via `<code2>openclaw pairing approve <canal> <código>'</code2>` o usa lista permitida.
6. Instalación del Daemon
macOS: LaunchAgent. Requiere sesión de usuario conectado; para headless, usa LaunchDaemon personalizado.
Linux (y Windows via WSL2): unidad de usuario systemd. El asistente intenta `<code1>loginctl enable-linger <usuario>'</code1>` para mantener el Gateway activo después de cerrar sesión.
Puede solicitar sudo (escribiendo en `/var/lib/systemd/linger`); intenta primero sin sudo.
**Elección de Runtime:** Node (recomendado; necesario para WhatsApp/Telegram). Bun **no recomendado**.
7. Verificaciones de Salud
Inicia el Gateway (si es necesario) y ejecuta `openclaw health`.
Consejo: `openclaw status --deep` añade sonda de salud del Gateway a la salida de estado.
8. Habilidades (Recomendadas)
Lee las habilidades disponibles y verifica prerrequisitos.
Elige un gestor de Node: **npm / pnpm** (Bun no recomendado).
Instala dependencias opcionales (algunas via Homebrew en macOS).
9. Finalización
Resumen + Pasos siguientes, incluyendo apps iOS/Android/macOS.
Si no se detecta GUI, el asistente imprime instrucciones de reenvío de puerto SSH para la UI de Control en lugar de abrir el navegador.
Si faltan los assets de la UI de Control, el asistente intenta construirlos; fallback es `pnpm ui:build`.
Modo Remoto
El modo remoto configura el cliente local para conectarse a un Gateway en otro lugar.
Lo que necesitas establecer:
URL del Gateway Remoto (`ws://...`)
Token si el Gateway remoto requiere auth (recomendado)
Notes:
No se realiza instalación remota ni cambios de daemon.
Si el Gateway es solo loopback, usa túnel SSH o tailnet.
Consejos de descubrimiento: macOS: Bonjour (`dns-sd`); Linux: Avahi (`avahi-browse`)
Añadir Otro Agente
Usa `<code1>openclaw agents add <nombre>'</code1>` para crear un agente separado con su propio espacio de trabajo, sesiones y auth. Ejecutar sin `<code2>--workspace</code2>` inicia el asistente.
Establece:
`agents.list[].name`
`agents.list[].workspace`
`agents.list[].agentDir`
Notes:
El espacio de trabajo predeterminado sigue `<code1>~/.openclaw/workspace-<agentId>'</code1>`.
Añade `bindings` para enrutar mensajes entrantes (el asistente puede hacerlo).
Flags no interactivos: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
Modo No Interactivo
Usa `--non-interactive` para automatización o incorporación scripteada:
openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Añade `--json` para resumen legible por máquina.
Ejemplo Z.AI:
openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$Z_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Ejemplo Vercel AI Gateway:
openclaw onboard --non-interactive \ --mode local \ --auth-choice ai-gateway-api-key \ --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Ejemplo Moonshot:
openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Ejemplo Synthetic:
openclaw onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Ejemplo OpenCode Zen:
openclaw onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODE_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback
Ejemplo Añadir Agente (No interactivo):
openclaw agents add work \ --workspace ~/.openclaw/workspace-work \ --model openai/gpt-5.2 \ --bind whatsapp:biz \ --non-interactive \ --json
RPC del Asistente del Gateway
El Gateway expone el flujo del asistente via RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). Los clientes (app macOS, UI de Control) pueden renderizar pasos sin reimplementar la lógica de incorporación.
Configuración de Signal (signal-cli)
El asistente puede instalar `signal-cli` (desde releases de GitHub):
Descarga el asset de release apropiado.
Almacena en `<code1>~/.openclaw/tools/signal-cli/<versión>/</code1>`.
Escribe `channels.signal.cliPath` en tu configuración.
Notes:
Los builds JVM requieren **Java 21**.
Builds nativos preferidos si están disponibles.
Windows usa WSL2; la instalación sigue el flujo de Linux dentro de WSL.
Qué Escribe el Asistente
Campos típicos en `~/.openclaw/openclaw.json`:
`agents.defaults.workspace`
`agents.defaults.model` / `models.providers` (si Minimax)
`gateway.*` (modo, enlace, auth, Tailscale)
`channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
Listas permitidas de canales (Slack/Discord/Matrix/Teams) cuando se opta (nombres resueltos a IDs donde sea posible).
`skills.install.nodeManager`
`wizard.*` (lastRunAt, lastRunVersion, lastRunCommit, lastRunCommand, lastRunMode)
`openclaw agents add` escribe `agents.list[]` y `bindings` opcional.
Creds de WhatsApp en `<code1>~/.openclaw/credentials/whatsapp/<accountId>/</code1>`. Sesiones en `<code2>~/.openclaw/agents/<agentId>/sessions/</code2>`.
Algunos canales se proporcionan como plugins. Cuando se seleccionan, el asistente solicita instalar (npm o ruta local) antes de configurar.