Guía de referencia: openclaw onboard

Configurar un proyecto desde cero suele ser un proceso tedioso. Pasas demasiado tiempo editando archivos de configuración y revisando que cada parámetro sea correcto en lugar de escribir código. Para evitar perder el tiempo en tareas repetitivas, lo ideal es usar herramientas que automaticen el setup inicial.

Aquí tienes la referencia completa para usar el asistente de configuración y dejar todo listo rápidamente.

Requisitos previos

Para ejecutar el asistente, solo necesitas:

• Acceso a la CLI de OpenClaw.

Inicio rápido

Esta es la ruta de 5 minutos para tener tu proyecto configurado. Sigue estos pasos:

1. Ejecuta el comando del asistente en tu terminal:

openclaw onboard

2. Responde a las preguntas que aparecen en la CLI para definir los parámetros de tu proyecto.
3. El asistente generará los archivos necesarios automáticamente.

Si necesitas una explicación conceptual más amplia, puedes consultar la vista general del wizard.

Solución de problemas

• El comando no se reconoce: Verifica que la CLI esté instalada correctamente en tu path global o local.
• Configuración incompleta: Si el proceso se detiene, puedes volver a ejecutar openclaw onboard para iniciar el asistente de nuevo.

¿Necesitas ayuda personalizada con un error específico? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Onboarding Wizard: Vista general
• Configuración de API y Gateway
• Gestión de nodos en Node.js

¿Alguna vez has pasado horas configurando un agente local solo para que falle por una variable de entorno mal puesta o un conflicto de archivos? Configurar herramientas de automatización suele ser un dolor de cabeza, especialmente cuando hay múltiples APIs y canales de comunicación de por medio. Aquí te explico cómo OpenClaw maneja este proceso para que no pierdas el tiempo.

Requisitos previos

Para empezar con el pie derecho, asegúrate de tener a mano lo siguiente (según lo que planees usar):

• Archivo de configuración ~/.openclaw/openclaw.json (si ya lo tienes).
• API keys de tus proveedores (Anthropic, OpenAI, xAI, etc.).
• Node.js instalado (evita Bun para el Daemon).
• Acceso a terminal con permisos para configurar servicios (sudo opcional en Linux).

Inicio rápido

Si quieres el camino más rápido de 5 minutos, sigue estos pasos:

1. Ejecuta el wizard de configuración. Si detecta un archivo existente, elige Keep o Modify.
2. Configura tu modelo principal. Si usas Anthropic y tienes la variable ANTHROPIC_API_KEY, el wizard la detectará automáticamente.
3. Define tu Workspace. Por defecto se usará ~/.openclaw/workspace.
4. Configura el Gateway. Mantén el modo Token por seguridad, incluso en local.
5. Instala el Daemon para que OpenClaw corra de fondo. En macOS usa LaunchAgent y en Linux systemd.

Detalles del flujo (local mode)

1. Detección de configuración existente

Si ya existe ~/.openclaw/openclaw.json, puedes elegir entre Keep / Modify / Reset. Ejecutar el wizard de nuevo no borra nada a menos que elijas Reset o pases el flag --reset.

El flag --reset por defecto limpia config+creds+sessions. Si necesitas una limpieza total, usa --reset-scope full para incluir el workspace. Ten en cuenta que el reset usa trash (nunca rm). Si tu configuración es inválida o tiene llaves antiguas, el wizard se detendrá y te pedirá ejecutar openclaw doctor.

2. Modelos y Autenticación

Aquí es donde conectas el cerebro de tu agente. Estas son las opciones disponibles:

• Anthropic: Usa ANTHROPIC_API_KEY o introduce una clave manualmente. Para OAuth en macOS, el wizard busca en el Keychain “Claude Code-credentials” (elige “Always Allow”). En Linux/Windows, intenta reusar ~/.claude/.credentials.json. También puedes usar claude setup-token y pegar el token.
• OpenAI Code (Codex): Si usas la suscripción de Codex CLI, puede reusar ~/.codex/auth.json. Para OAuth, sigue el flujo del navegador y pega el code#state. Esto establece agents.defaults.model a openai-codex/gpt-5.2.
• OpenAI API: Usa OPENAI_API_KEY si está presente o solicita una para guardarla en los perfiles de autenticación.
• Proxies y otros proveedores: Soporta xAI (Grok), OpenCode Zen (OPENCODE_API_KEY), Vercel AI Gateway (AI_GATEWAY_API_KEY), Cloudflare AI Gateway (Account ID, Gateway ID y API Key), MiniMax M2.5, Synthetic y Moonshot (Kimi).

Por defecto, las keys se guardan en texto plano. Si prefieres usar referencias a variables de entorno, usa --secret-input-mode ref.

Tip para servidores/headless: Completa el OAuth en una máquina con navegador y luego copia ~/.openclaw/credentials/oauth.json al host del gateway.

3. Workspace

El valor predeterminado es ~/.openclaw/workspace. Aquí se guardan los archivos necesarios para el arranque del agente. Puedes consultar más en Agent workspace.

4. Gateway

Configura el puerto, bind y modo de autenticación. Mi recomendación es que mantengas el modo Token incluso para conexiones locales.

• En modo token, puedes generar uno en texto plano o usar un SecretRef.
• Si prefieres no usar el modo interactivo para el token, usa --gateway-token-ref-env <ENV_VAR>.
• Desactiva la autenticación solo si confías plenamente en cada proceso local de tu máquina.

5. Channels

Puedes conectar OpenClaw con varias plataformas:

• WhatsApp/Telegram/Discord: Requieren tokens de bot o escaneo de QR.
• Google Chat: Necesitas el JSON de la cuenta de servicio.
• BlueBubbles: Es la opción recomendada para iMessage.
• Seguridad: Por defecto se usa “pairing”. El primer mensaje directo enviará un código que debes aprobar con openclaw pairing approve <channel> <code>.

6. Web search

Elige un proveedor como Perplexity, Brave, Gemini, Grok o Kimi. El wizard detectará automáticamente las keys de tus variables de entorno. Puedes saltar este paso con --skip-search.

7. Instalación del Daemon

• macOS: Configura un LaunchAgent (requiere sesión de usuario iniciada).
• Linux: Configura una unidad de usuario en systemd. El wizard intentará ejecutar loginctl enable-linger <user> para que el Gateway siga activo tras cerrar sesión.
• Runtime: Usa Node.js. Bun no es recomendable para esta tarea.

8. Health check y Skills

Al finalizar, se iniciará el Gateway y se ejecutará openclaw health. Puedes usar openclaw status --deep para ver un estado detallado. Finalmente, podrás elegir un gestor de paquetes (npm / pnpm) para instalar las Skills y sus dependencias.

Solución de problemas

• Configuración inválida: Si el wizard se detiene, ejecuta openclaw doctor para identificar llaves antiguas o errores de formato.
• Fallo en el Daemon: Si usas un token vía SecretRef y este no se puede resolver, la instalación del daemon se bloqueará con instrucciones claras para corregirlo.
• Sin interfaz gráfica: Si el wizard no detecta un entorno GUI, imprimirá instrucciones para hacer un port-forward por SSH y acceder a la Control UI.
• OAuth bloqueado: En macOS, asegúrate de seleccionar “Always Allow” cuando se solicite acceso al Keychain para evitar que el proceso de fondo se detenga.

¿Necesitas ayuda específica con tu configuración? Prueba nuestro AI Setup Assistant.

Próximos pasos

• Vercel AI Gateway
• Cloudflare AI Gateway
• Conceptos de OAuth
• Canales compatibles

¿Alguna vez has intentado automatizar un despliegue y te has quedado bloqueado porque la CLI se detiene a pedirte una confirmación? Es frustrante cuando quieres integrar una herramienta en tus scripts o configurar varios entornos rápidamente y tienes que responder a cada prompt de forma manual. Para estos casos, lo mejor es saltarse la interfaz interactiva.

El modo no interactivo permite que tus procesos de CI/CD o scripts de configuración local se ejecuten de principio a fin sin interrupciones.

Requisitos previos

• openclaw CLI instalada.
• Node.js (si utilizas el flag --install-daemon).
• API keys de tus proveedores configuradas como variables de entorno.

Inicio rápido

Para automatizar el onboarding, usa el flag --non-interactive. Este comando configura openclaw con Anthropic, define el puerto del Gateway y omite la instalación de skills:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

Si necesitas un resumen que otros scripts puedan procesar, añade el flag --json.

Configuración de Gateway token

Si prefieres usar una referencia de entorno para el token del Gateway en lugar de pasar el valor directamente, usa SecretRef:

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

Es importante recordar que --gateway-token y --gateway-token-ref-env son mutuamente excluyentes.

Ejemplos por proveedor

Ejemplo con Gemini

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice gemini-api-key \
      --gemini-api-key "$GEMINI_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Ejemplo con Z.AI

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice zai-api-key \
      --zai-api-key "$ZAI_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Ejemplo con 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 con Cloudflare AI Gateway

    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice cloudflare-ai-gateway-api-key \
      --cloudflare-ai-gateway-account-id "your-account-id" \
      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback

Ejemplo con 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 con 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 con 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

Añadir un agente (non-interactive)

También puedes crear agentes de forma directa. Este comando añade un agente llamado “work” con un modelo específico y salida en formato JSON:

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Solución de problemas

• —json no activa el modo automático: Ten cuidado aquí. Usar --json no implica que la CLI entre en modo no interactivo. Para scripts, debes incluir explícitamente --non-interactive (y normalmente --workspace).
• Conflictos de flags en Gateway: Si intentas usar --gateway-token y --gateway-token-ref-env al mismo tiempo, el comando fallará. Elige uno solo.

¿Necesitas ayuda para configurar tu entorno? Prueba el AI Setup Assistant.

Próximos pasos

• Configuración de Workspace
• Gestión de Agentes
• Seguridad del Gateway
• Referencia completa de la CLI

---
title: Configura tu Gateway con el Wizard RPC
description: Aprende a integrar el flujo de configuración del Gateway mediante RPC y a gestionar la instalación automática de signal-cli.
---

Configurar el onboarding de una herramienta técnica suele ser un proceso repetitivo y propenso a errores. Si estás construyendo un cliente para el Gateway, lo último que quieres es programar manualmente cada paso de la instalación de dependencias o la validación de estados en diferentes plataformas.

Es frustrante tener que sincronizar la lógica de configuración entre una aplicación de escritorio y una interfaz web. Por eso, el Gateway centraliza este proceso para que tú solo tengas que preocuparte de mostrar la interfaz.

## Requisitos previos

- Acceso al Gateway y su interfaz RPC.
- **Java 21** (obligatorio para builds de JVM).
- **WSL2** configurado si estás trabajando en Windows.

## Inicio rápido

El Gateway expone todo el flujo del wizard a través de RPC. Esto permite que clientes como la app de macOS o la Control UI rendericen los pasos sin necesidad de implementar la lógica de onboarding de nuevo.

### Métodos RPC disponibles

Puedes interactuar con el wizard usando estos comandos:

- `wizard.start`: Inicia el proceso de configuración.
- `wizard.next`: Avanza al siguiente paso del flujo.
- `wizard.cancel`: Detiene el proceso actual.
- `wizard.status`: Consulta el estado actual del wizard.

### Configuración de Signal (signal-cli)

El wizard puede gestionar automáticamente la instalación de `signal-cli` directamente desde los releases de GitHub:

1. **Descarga**: Obtiene el asset correspondiente a tu arquitectura.
2. **Almacenamiento**: Guarda los archivos en `~/.openclaw/tools/signal-cli/<version>/`.
3. **Configuración**: Escribe automáticamente la ruta en `channels.signal.cliPath` dentro de tu archivo de configuración.

Si hay builds nativos disponibles, el wizard los priorizará sobre los de JVM. En el caso de Windows, la instalación se realiza dentro de WSL2 siguiendo el flujo estándar de Linux.

## Solución de problemas

- **Error de versión de Java**: Si utilizas builds de JVM, el sistema fallará si no tienes instalado **Java 21**. Verifica tu versión antes de iniciar el wizard.
- **Entorno Windows**: Recuerda que la instalación de `signal-cli` en Windows depende de WSL2. Si el wizard falla, asegúrate de que tu entorno de Linux dentro de Windows esté operativo.

¿Necesitas ayuda específica con tu configuración? Consulta al [AI Setup Assistant](/docs/#docs-chat).

## Próximos pasos

- [Referencia completa de la API RPC](/docs/#rpc-api)
- [Configuración avanzada de canales](/docs/#channels-config)
- [Guía de uso de WSL2 con el Gateway](/docs/#wsl2-guide)

¿Alguna vez has sentido que pierdes el control cuando un instalador automático empieza a crear archivos por todo tu sistema? Es frustrante no saber exactamente qué cambió o dónde se guardaron esas configuraciones importantes que luego necesitas editar a mano.

Entender qué hace el wizard de OpenClaw te quita ese estrés. En lugar de ser una caja negra, aquí verás exactamente qué campos se escriben y dónde vive cada pieza de tu configuración para que siempre tengas el control total de tu entorno.

Requisitos previos

• Tener instalado OpenClaw en tu sistema.
• Acceso a tu terminal para ejecutar el wizard o comandos CLI.
• Credenciales de los channels que planeas configurar (Telegram, Discord, etc.).

Inicio rápido

Si quieres ver los resultados del wizard de inmediato, sigue estos pasos:

1. Ejecuta el wizard de onboarding para generar tu configuración inicial.
2. Abre el archivo ~/.openclaw/openclaw.json para revisar los campos creados.
3. Usa el comando openclaw agents add para añadir nuevos agentes a la lista agents.list[].
4. Verifica que tus sesiones se estén guardando en ~/.openclaw/agents/<agentId>/sessions/.

Detalles de la configuración

El wizard escribe campos específicos en tu archivo ~/.openclaw/openclaw.json. Estos son los valores principales que verás:

• agents.defaults.workspace
• agents.defaults.model / models.providers (esto último si eliges Minimax)
• tools.profile: Por defecto es "coding" si no se define; si ya existen valores explícitos, se mantienen.
• gateway.*: Incluye configuraciones de mode, bind, auth y tailscale.
• session.dmScope: Define detalles del comportamiento (puedes ver más en CLI Onboarding Reference).
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Allowlists de channels para Slack, Discord, Matrix o Microsoft Teams cuando aceptas participar durante los prompts (los nombres se convierten en IDs cuando es posible).
• skills.install.nodeManager
• Metadatos del wizard: wizard.lastRunAt, wizard.lastRunVersion, wizard.lastRunCommit, wizard.lastRunCommand y wizard.lastRunMode.

Cuando usas el comando openclaw agents add, el sistema escribe en agents.list[] y añade bindings opcionales.

En cuanto a las credenciales sensibles, los datos de WhatsApp se guardan en ~/.openclaw/credentials/whatsapp/<accountId>/.

Es importante que sepas que algunos channels se entregan como plugins. Si eliges uno durante el onboarding, el wizard te pedirá instalarlo (vía npm o una ruta local) antes de que puedas configurarlo.

Solución de problemas

• El perfil de herramientas no es el que esperaba: Si no configuras tools.profile, el proceso de onboarding local siempre usará "coding" por defecto.
• No encuentro las credenciales de WhatsApp: Recuerda que no están en el JSON principal, sino en la ruta específica de credentials/whatsapp/.
• Faltan campos de un channel específico: Algunos channels requieren la instalación de un plugin externo. El wizard te avisará si necesitas instalarlo mediante npm antes de continuar.
• IDs de canales no legibles: El wizard intenta resolver nombres a IDs automáticamente en las allowlists de Slack, Discord, Matrix y Microsoft Teams.

Si tienes dudas sobre algún parámetro específico o necesitas ayuda con un error que no aparece aquí, prueba el AI Setup Assistant.

Próximos pasos

• Onboarding Wizard: Una visión general de cómo funciona el proceso.
• Onboarding: Guía para la aplicación de macOS.
• Gateway configuration: Referencia completa de configuración.
• Channels: Configura WhatsApp, Telegram, Discord, Google Chat, Signal o iMessage.
• Skills: Aprende a usar y configurar skills.