Saltar al contenido principal

​
Referencia de onboarding

Esta es la referencia completa para openclaw onboard. Para una descripción general de alto nivel, consulta Onboarding (CLI).

​
Detalles del flujo (modo local)

1

Detección de configuración existente

  • Si existe ~/.openclaw/openclaw.json, elige Conservar / Modificar / Restablecer.
  • Volver a ejecutar el onboarding no borra nada a menos que elijas explícitamente Restablecer (o pases --reset).
  • CLI --reset usa por defecto config+creds+sessions; usa --reset-scope full para eliminar también el espacio de trabajo.
  • Si la configuración no es válida o contiene claves heredadas, el asistente se detiene y te pide que ejecutes openclaw doctor antes de continuar.
  • El restablecimiento usa trash (nunca rm) y ofrece estos alcances:
    • Solo configuración
    • Configuración + credenciales + sesiones
    • Restablecimiento completo (también elimina el espacio de trabajo)
2

Modelo/Auth

  • Clave de API de Anthropic: usa ANTHROPIC_API_KEY si está presente o solicita una clave, y luego la guarda para el uso del daemon.
  • Anthropic Claude CLI: opción preferida de asistente Anthropic en onboarding/configure. En macOS, el onboarding comprueba el elemento del Keychain “Claude Code-credentials” (elige “Always Allow” para que los inicios de launchd no se bloqueen); en Linux/Windows reutiliza ~/.claude/.credentials.json si existe y cambia la selección del modelo a una referencia canónica claude-cli/claude-*.
  • Anthropic setup-token (heredado/manual): vuelve a estar disponible en onboarding/configure, pero Anthropic informó a los usuarios de OpenClaw que la ruta de inicio de sesión de Claude de OpenClaw cuenta como uso de harness de terceros y requiere Extra Usage en la cuenta de Claude.
  • Suscripción a OpenAI Code (Codex) (Codex CLI): si existe ~/.codex/auth.json, el onboarding puede reutilizarlo. Las credenciales reutilizadas de Codex CLI siguen siendo administradas por Codex CLI; cuando expiran, OpenClaw vuelve a leer primero esa fuente y, cuando el proveedor puede actualizarlas, escribe la credencial actualizada de nuevo en el almacenamiento de Codex en lugar de asumir su administración.
  • Suscripción a OpenAI Code (Codex) (OAuth): flujo en el navegador; pega code#state.
    • Configura agents.defaults.model en openai-codex/gpt-5.4 cuando el modelo no está configurado o es openai/*.
  • Clave de API de OpenAI: usa OPENAI_API_KEY si está presente o solicita una clave, y luego la almacena en perfiles de autenticación.
    • Configura agents.defaults.model en openai/gpt-5.4 cuando el modelo no está configurado, es openai/* o openai-codex/*.
  • Clave de API de xAI (Grok): solicita XAI_API_KEY y configura xAI como proveedor de modelos.
  • OpenCode: solicita OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY, consíguela en https://opencode.ai/auth) y te permite elegir el catálogo Zen o Go.
  • Ollama: solicita la URL base de Ollama, ofrece el modo Cloud + Local o Local, detecta los modelos disponibles y descarga automáticamente el modelo local seleccionado cuando es necesario.
  • Más detalles: Ollama
  • Clave de API: almacena la clave por ti.
  • Vercel AI Gateway (proxy multimodelo): solicita AI_GATEWAY_API_KEY.
  • Más detalles: Vercel AI Gateway
  • Cloudflare AI Gateway: solicita Account ID, Gateway ID y CLOUDFLARE_AI_GATEWAY_API_KEY.
  • Más detalles: Cloudflare AI Gateway
  • MiniMax: la configuración se escribe automáticamente; el valor alojado predeterminado es MiniMax-M2.7. La configuración con clave de API usa minimax/..., y la configuración con OAuth usa minimax-portal/....
  • Más detalles: MiniMax
  • StepFun: la configuración se escribe automáticamente para StepFun estándar o Step Plan en endpoints de China o globales.
  • Actualmente, Standard incluye step-3.5-flash, y Step Plan también incluye step-3.5-flash-2603.
  • Más detalles: StepFun
  • Synthetic (compatible con Anthropic): solicita SYNTHETIC_API_KEY.
  • Más detalles: Synthetic
  • Moonshot (Kimi K2): la configuración se escribe automáticamente.
  • Kimi Coding: la configuración se escribe automáticamente.
  • Más detalles: Moonshot AI (Kimi + Kimi Coding)
  • Omitir: aún no se configura autenticación.
  • Elige un modelo predeterminado entre las opciones detectadas (o introduce manualmente provider/model). Para obtener la mejor calidad y menor riesgo de inyección de prompts, elige el modelo más potente y de última generación disponible en tu pila de proveedores.
  • El onboarding ejecuta una comprobación del modelo y avisa si el modelo configurado es desconocido o si falta autenticación.
  • El modo de almacenamiento de claves de API usa por defecto valores de perfil de autenticación en texto plano. Usa --secret-input-mode ref para almacenar en su lugar referencias respaldadas por variables de entorno (por ejemplo keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
  • Los perfiles de autenticación se almacenan en ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (claves de API + OAuth). ~/.openclaw/credentials/oauth.json es solo heredado y solo para importación.
  • Más detalles: /concepts/oauth
Consejo para entornos headless/servidor: completa OAuth en una máquina con navegador y luego copia el auth-profiles.json de ese agente (por ejemplo ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, o la ruta correspondiente $OPENCLAW_STATE_DIR/...) al host del gateway. credentials/oauth.json es solo una fuente heredada de importación.
3

Espacio de trabajo

  • Valor predeterminado ~/.openclaw/workspace (configurable).
  • Inicializa los archivos del espacio de trabajo necesarios para el ritual de arranque del agente.
  • Diseño completo del espacio de trabajo + guía de respaldo: Espacio de trabajo del agente
4

Gateway

  • Puerto, bind, modo de autenticación, exposición con tailscale.
  • Recomendación de autenticación: mantén Token incluso para loopback para que los clientes WS locales deban autenticarse.
  • En modo token, la configuración interactiva ofrece:
    • Generar/almacenar token en texto plano (predeterminado)
    • Usar SecretRef (opcional)
    • Quickstart reutiliza SecretRefs existentes de gateway.auth.token en los proveedores env, file y exec para el sondeo del onboarding y el arranque del panel.
    • Si ese SecretRef está configurado pero no puede resolverse, el onboarding falla de forma temprana con un mensaje claro de corrección en lugar de degradar silenciosamente la autenticación en tiempo de ejecución.
  • En modo contraseña, la configuración interactiva también admite almacenamiento en texto plano o mediante 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 puede combinarse con --gateway-token.
  • Desactiva la autenticación solo si confías plenamente en todos los procesos locales.
  • Los binds que no son loopback siguen requiriendo autenticación.
5

Canales

  • WhatsApp: inicio de sesión opcional con código QR.
  • Telegram: token de bot.
  • Discord: token de bot.
  • Google Chat: JSON de cuenta de servicio + audiencia del webhook.
  • Mattermost (plugin): token de bot + URL base.
  • Signal: instalación opcional de signal-cli + configuración de cuenta.
  • BlueBubbles: recomendado para iMessage; URL del servidor + contraseña + webhook.
  • iMessage: ruta heredada de CLI imsg + acceso a la base de datos.
  • Seguridad de DM: el comportamiento predeterminado es el emparejamiento. El primer DM envía un código; apruébalo mediante openclaw pairing approve <channel> <code> o usa listas de permitidos.
6

Búsqueda web

  • Elige un proveedor compatible como Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG o Tavily (u omítelo).
  • Los proveedores respaldados por API pueden usar variables de entorno o configuración existente para una configuración rápida; los proveedores sin clave usan en su lugar sus requisitos previos específicos.
  • Omítelo con --skip-search.
  • Configúralo más tarde: openclaw configure --section web.
7

Instalación del daemon

  • macOS: LaunchAgent
    • Requiere una sesión de usuario iniciada; para entornos headless, usa un LaunchDaemon personalizado (no se incluye).
  • Linux (y Windows mediante WSL2): unidad de usuario de systemd
    • El onboarding intenta habilitar lingering mediante loginctl enable-linger <user> para que el Gateway siga activo después de cerrar sesión.
    • Puede pedir sudo (escribe en /var/lib/systemd/linger); primero lo intenta sin sudo.
  • Selección de runtime: Node (recomendado; necesario para WhatsApp/Telegram). Bun no está recomendado.
  • Si la autenticación por token requiere un token y gateway.auth.token está gestionado mediante SecretRef, la instalación del daemon lo valida, pero no conserva valores de token resueltos en texto plano dentro de los metadatos del entorno del servicio del supervisor.
  • Si la autenticación por token requiere un token y el token SecretRef configurado no está resuelto, se bloquea la instalación del daemon con instrucciones prácticas.
  • Si gateway.auth.token y gateway.auth.password están configurados y gateway.auth.mode no está configurado, se bloquea la instalación del daemon hasta que el modo se configure explícitamente.
8

Comprobación de estado

  • Inicia el Gateway (si es necesario) y ejecuta openclaw health.
  • Consejo: openclaw status --deep agrega el sondeo de estado en vivo del gateway a la salida de estado, incluidos los sondeos de canales cuando son compatibles (requiere un gateway accesible).
9

Skills (recomendado)

  • Lee las Skills disponibles y comprueba los requisitos.
  • Te permite elegir un administrador de Node: npm / pnpm (bun no recomendado).
  • Instala dependencias opcionales (algunas usan Homebrew en macOS).
10

Finalizar

  • Resumen + pasos siguientes, incluidas las apps de iOS/Android/macOS para funciones adicionales.
Si no se detecta ninguna GUI, el onboarding imprime instrucciones de reenvío de puertos SSH para la Control UI en lugar de abrir un navegador. Si faltan los recursos de la Control UI, el onboarding intenta compilarlos; el mecanismo alternativo es pnpm ui:build (instala automáticamente las dependencias de la UI).

​
Modo no interactivo

Usa --non-interactive para automatizar o crear scripts de onboarding: 
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
Agrega --json para obtener un resumen legible por máquina. Token SecretRef del gateway en modo no interactivo: 
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
--gateway-token y --gateway-token-ref-env son mutuamente excluyentes.
--json no implica el modo no interactivo. Usa --non-interactive (y --workspace) para scripts.
Los ejemplos de comandos específicos por proveedor se encuentran en Automatización de CLI. Usa esta página de referencia para la semántica de los flags y el orden de los pasos.

​
Agregar agente (no interactivo)

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

​
RPC del asistente de Gateway

El Gateway expone el flujo de onboarding mediante RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Los clientes (app de macOS, Control UI) pueden representar los pasos sin volver a implementar la lógica de onboarding.

​
Configuración de Signal (signal-cli)

El onboarding puede instalar signal-cli desde los lanzamientos de GitHub:
  • Descarga el recurso del lanzamiento correspondiente.
  • Lo almacena en ~/.openclaw/tools/signal-cli/<version>/.
  • Escribe channels.signal.cliPath en tu configuración.
Notas:
  • Las compilaciones JVM requieren Java 21.
  • Se usan compilaciones nativas cuando están disponibles.
  • Windows usa WSL2; la instalación de signal-cli sigue el flujo de Linux dentro de WSL.

​
Lo que escribe el asistente

Campos habituales en ~/.openclaw/openclaw.json:
  • agents.defaults.workspace
  • agents.defaults.model / models.providers (si se eligió Minimax)
  • tools.profile (el onboarding local usa por defecto "coding" cuando no está configurado; se conservan los valores explícitos existentes)
  • gateway.* (mode, bind, auth, tailscale)
  • session.dmScope (detalles del comportamiento: Referencia de configuración de CLI)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Listas de permitidos de canales (Slack/Discord/Matrix/Microsoft Teams) cuando optas por ellas durante los prompts (los nombres se resuelven a IDs cuando es posible).
  • skills.install.nodeManager
    • setup --node-manager acepta npm, pnpm o bun.
    • La configuración manual aún puede usar yarn configurando skills.install.nodeManager directamente.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
openclaw agents add escribe agents.list[] y bindings opcionales. Las credenciales de WhatsApp se almacenan en ~/.openclaw/credentials/whatsapp/<accountId>/. Las sesiones se almacenan en ~/.openclaw/agents/<agentId>/sessions/. Algunos canales se distribuyen como plugins. Cuando eliges uno durante la configuración, el onboarding te pedirá instalarlo (npm o una ruta local) antes de poder configurarlo.

​
Documentación relacionada