Skip to main content
Esta página describe paso a paso el comportamiento, los resultados y los aspectos internos de la incorporación. Para ver una guía, consulte Incorporación (CLI). Para obtener la referencia completa de opciones de la CLI (cada --flag, ejemplos no interactivos y comandos específicos de proveedores), consulte openclaw onboard.

​
Qué hace el asistente

El modo local (predeterminado) guía por:
  • Configuración del modelo y la autenticación (Anthropic, OAuth de la suscripción a OpenAI Code, xAI, OpenCode, endpoints personalizados y más flujos de autenticación propios de proveedores)
  • Ubicación del espacio de trabajo y archivos de arranque
  • Ajustes del Gateway (puerto, enlace, autenticación, Tailscale)
  • Canales y proveedores (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp y otros canales integrados o de plugins)
  • Proveedor de búsqueda web (opcional)
  • Instalación del daemon (LaunchAgent, unidad de usuario de systemd o tarea programada nativa de Windows con alternativa en la carpeta Startup)
  • Comprobación de estado
  • Configuración de Skills
El modo remoto configura esta máquina para conectarse a un Gateway ubicado en otro lugar. No instala ni modifica nada en el host remoto.

​
Detalles del flujo local

1

Detección de la configuración existente

  • Si existe ~/.openclaw/openclaw.json, elija Mantener los valores actuales, Revisar y actualizar o Restablecer antes de la configuración.
  • Volver a ejecutar el asistente no borra nada, salvo que elija explícitamente Restablecer (o pase --reset).
  • El valor predeterminado de --reset de la CLI es config+creds+sessions; use --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 solicita ejecutar openclaw doctor antes de continuar.
  • El restablecimiento mueve el estado a la papelera (nunca lo elimina directamente) y ofrece estos alcances:
    • Solo la configuración
    • Configuración + credenciales + sesiones
    • Restablecimiento completo (también elimina el espacio de trabajo)
2

Modelo y autenticación

3

Espacio de trabajo

  • Valor predeterminado: ~/.openclaw/workspace (configurable).
  • Crea los archivos del espacio de trabajo necesarios para el arranque de la primera ejecución.
  • Al volver a ejecutarlo, una lista de agentes existente conserva su espacio de trabajo de toda la flota, salvo que se confirme explícitamente el traslado. Las nuevas ejecuciones no interactivas muestran una advertencia y conservan el valor actual.
  • Diseño del espacio de trabajo: Espacio de trabajo del agente.
4

Gateway

  • Solicita el puerto, el enlace, el modo de autenticación y la exposición mediante Tailscale.
  • Recomendación: mantenga activada la autenticación mediante token incluso para loopback, de modo que los clientes WS locales deban autenticarse.
  • En el modo de token, la configuración interactiva ofrece:
    • Generar/almacenar token en texto sin formato (predeterminado)
    • Usar SecretRef (activación opcional)
  • En el modo de contraseña, la configuración interactiva también permite almacenarla en texto sin formato o como SecretRef.
  • Ruta no interactiva para SecretRef del token: --gateway-token-ref-env <ENV_VAR>.
    • Requiere una variable de entorno no vacía en el entorno del proceso de incorporación.
    • No se puede combinar con --gateway-token.
  • Desactive la autenticación únicamente si confía plenamente en todos los procesos locales.
  • Los enlaces que no sean loopback siguen requiriendo autenticación.
5

Canales

  • WhatsApp: inicio de sesión opcional mediante código QR
  • Telegram: token del bot
  • Discord: token del bot
  • Google Chat: JSON de la cuenta de servicio + audiencia del webhook
  • Mattermost: token del bot + URL base
  • Signal: instalación opcional de signal-cli + configuración de la cuenta
  • iMessage: ruta de la CLI imsg + acceso a la base de datos de Messages; use un contenedor SSH cuando el Gateway se ejecute fuera de un Mac
  • Seguridad de los mensajes directos: el valor predeterminado es el emparejamiento. El primer mensaje directo envía un código; apruébelo mediante openclaw pairing approve <channel> <code> o use listas de permitidos.
6

Búsqueda web

  • Elija un proveedor (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily) u omita este paso.
  • Omita este paso con --skip-search; vuelva a configurarlo más adelante con openclaw configure --section web.
7

Instalación del daemon

  • macOS: LaunchAgent
    • Requiere una sesión de usuario iniciada; para un sistema sin interfaz gráfica, use un LaunchDaemon personalizado (no se incluye).
  • Linux y Windows mediante WSL2: unidad de usuario de systemd
    • El asistente intenta ejecutar loginctl enable-linger <user> para que el Gateway siga activo después de cerrar la sesión.
    • Puede solicitar sudo (escribe en /var/lib/systemd/linger); primero lo intenta sin sudo.
  • Windows nativo: primero una tarea programada
    • Si se deniega la creación de la tarea, OpenClaw recurre a un elemento de inicio de sesión por usuario en la carpeta Startup e inicia el Gateway inmediatamente.
    • Las tareas programadas siguen siendo la opción preferida porque proporcionan un mejor estado del supervisor.
  • Selección del entorno de ejecución: se requiere Node porque el almacén de estado canónico del entorno de ejecución de OpenClaw usa node:sqlite.
8

Comprobación de estado

  • Inicia el Gateway (si es necesario) y ejecuta openclaw health.
  • openclaw status --deep añade la comprobación en vivo del estado del Gateway a la salida de estado, incluidas las comprobaciones de canales cuando se admiten.
9

Skills

  • Lee las Skills disponibles y comprueba los requisitos.
  • Permite elegir el gestor de Node: npm, pnpm o bun.
  • Instala dependencias opcionales para las Skills integradas de confianza cuando el instalador necesario está disponible.
  • Omite los instaladores no disponibles de Homebrew, uv y Go, y después agrupa las Skills afectadas con instrucciones para la configuración manual. Ejecute openclaw doctor después de instalar los requisitos previos que falten.
10

Finalización

  • Resumen y pasos siguientes, incluidas las opciones de aplicaciones para iOS, Android y macOS.
Si no se detecta ninguna interfaz gráfica, el asistente muestra instrucciones de redirección de puertos SSH para la interfaz de control en lugar de abrir un navegador. Si faltan los recursos de la interfaz de control, el asistente intenta compilarlos; la alternativa es pnpm ui:build (instala automáticamente las dependencias de la interfaz).

​
Detalles del modo remoto

El modo remoto configura esta máquina para conectarse a un Gateway ubicado en otro lugar. No instala ni modifica nada en el host remoto. Lo que se configura:
  • URL del Gateway remoto (ws://... o wss://...)
  • Token, contraseña o ausencia de autenticación, de acuerdo con la configuración del Gateway remoto
1

Descubrimiento (opcional)

Si dns-sd (macOS) o avahi-browse (Linux) está disponible, la incorporación ofrece buscar balizas de Gateway Bonjour/mDNS antes de recurrir a la introducción manual de la URL. También se intenta el descubrimiento DNS-SD de área amplia cuando está configurado. Documentación: Descubrimiento del Gateway, Bonjour.
2

Método de conexión

Cuando se selecciona una baliza, elija WebSocket directo o un túnel SSH:
  • Directo: se conecta mediante wss:// y solicita confiar en la huella digital TLS descubierta (anclaje de confianza en el primer uso; solo se ancla si se acepta).
  • Túnel SSH: muestra un comando ssh -N -L 18789:127.0.0.1:18789 <user>@<host> que debe ejecutarse primero y después se conecta al endpoint del túnel local.
3

Autenticación

Elija token (recomendado), contraseña o ausencia de autenticación y, después, almacénelo opcionalmente como SecretRef en lugar de texto sin formato.
Si el Gateway solo usa loopback y no se puede descubrir, use manualmente un túnel SSH o una tailnet. Se acepta ws:// en texto sin formato para loopback, literales de IP privada, .local y URL de Tailnet *.ts.net; otros nombres DNS privados requieren OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1.

​
Opciones de autenticación y modelos

Si un paso de configuración de proveedor falla durante la incorporación interactiva (por ejemplo, una opción de reutilización de la CLI sin un inicio de sesión local), el asistente muestra el error y vuelve al selector de proveedores en lugar de salir. Las ejecuciones explícitas de --auth-choice siguen fallando inmediatamente para facilitar la automatización.
Usa ANTHROPIC_API_KEY si está presente o solicita una clave y, después, la guarda para que la use el daemon.
Ruta local preferida en la incorporación/configuración interactiva; reutiliza un inicio de sesión existente de la CLI de Claude cuando está disponible.
Flujo del navegador; pegue code#state.En una configuración nueva sin modelo principal, establece agents.defaults.model en openai/gpt-5.6-sol mediante el entorno de ejecución de Codex.
Flujo de emparejamiento en el navegador con un código de dispositivo de corta duración.En una configuración nueva sin modelo principal, establece agents.defaults.model en openai/gpt-5.6-sol mediante el entorno de ejecución de Codex.
Usa OPENAI_API_KEY si está presente o solicita una clave y, después, almacena la credencial en los perfiles de autenticación.En una configuración nueva sin modelo principal, establece agents.defaults.model en openai/gpt-5.6; el identificador de modelo de API directa sin calificar se resuelve en el nivel Sol.Al añadir OpenAI o volver a autenticarlo, se conserva un modelo principal explícito existente, incluido openai/gpt-5.5. Si la cuenta no ofrece GPT-5.6, seleccione openai/gpt-5.5 explícitamente; OpenClaw no lo cambia silenciosamente por una versión inferior.
Inicio de sesión mediante navegador para cuentas de SuperGrok o X Premium aptas. Esta es la opción de xAI recomendada para la mayoría de los usuarios. OpenClaw almacena el perfil de autenticación resultante para los modelos Grok, Grok web_search, x_search y code_execution.
Inicio de sesión mediante navegador apto para entornos remotos, con un código corto en lugar de una devolución de llamada a localhost. Utilícelo desde hosts SSH, Docker o VPS.
Solicita XAI_API_KEY y configura xAI como proveedor de modelos. Utilice esta opción cuando prefiera una clave de API de xAI Console en lugar del OAuth de la suscripción.
Solicita OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY) y permite elegir el catálogo Zen o Go (una clave de API sirve para ambos). URL de configuración: opencode.ai/auth.
Almacena la clave.
Solicita AI_GATEWAY_API_KEY. Más información: Vercel AI Gateway.
Solicita el ID de cuenta, el ID del gateway y CLOUDFLARE_AI_GATEWAY_API_KEY. Más información: Cloudflare AI Gateway.
La configuración se escribe automáticamente. El valor predeterminado alojado es MiniMax-M3; la configuración mediante clave de API utiliza minimax/... y la configuración mediante OAuth utiliza minimax-portal/.... Más información: MiniMax.
La configuración se escribe automáticamente para StepFun estándar o Step Plan en endpoints de China o globales. Actualmente, la modalidad estándar incluye step-3.5-flash y Step Plan también incluye step-3.5-flash-2603. Más información: StepFun.
Solicita SYNTHETIC_API_KEY. Más información: Synthetic.
Primero solicita Cloud + Local, Cloud only o Local only. Cloud only utiliza OLLAMA_API_KEY con https://ollama.com. Los modos respaldados por un host solicitan la URL base (valor predeterminado: http://127.0.0.1:11434), detectan los modelos disponibles y sugieren valores predeterminados. Cloud + Local también comprueba si ese host de Ollama ha iniciado sesión para acceder a la nube. Más información: Ollama.
Las configuraciones de Moonshot (Kimi K2) y Kimi Coding se escriben automáticamente. Más información: Moonshot AI (Kimi + Kimi Coding).
Funciona con endpoints compatibles con OpenAI, OpenAI Responses y Anthropic.La incorporación interactiva admite las mismas opciones de almacenamiento de claves de API que los flujos de claves de API de otros proveedores:
  • Pegar la clave de API ahora (texto sin formato)
  • Usar referencia de secreto (referencia de entorno o referencia de proveedor configurada, con validación previa)
La incorporación infiere la compatibilidad con imágenes para los ID habituales de modelos de visión (GPT-4o/4.1/5.x, Claude 3/4, Gemini, Qwen-VL, LLaVA, Pixtral y similares) y solo pregunta cuando se desconoce el nombre del modelo.Opciones no interactivas:
  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key (opcional; utiliza CUSTOM_API_KEY como alternativa)
  • --custom-provider-id (opcional)
  • --custom-compatibility <openai|openai-responses|anthropic> (opcional; valor predeterminado: openai)
  • --custom-image-input / --custom-text-input (opcional; sustituye la capacidad de entrada del modelo inferida)
Deja la autenticación sin configurar.
Comportamiento de los modelos:
  • Seleccione el modelo predeterminado entre las opciones detectadas o introduzca manualmente el proveedor y el modelo.
  • Cuando la incorporación comienza a partir de una opción de autenticación de proveedor, el selector de modelos da preferencia automáticamente a ese proveedor. En el caso de Volcengine y BytePlus, la misma preferencia también coincide con sus variantes de planes de programación (volcengine-plan/*, byteplus-plan/*).
  • Si ese filtro de proveedor preferido no produjera resultados, el selector utiliza el catálogo completo en lugar de no mostrar ningún modelo.
  • El asistente ejecuta una comprobación del modelo y advierte si el modelo configurado es desconocido o carece de autenticación.
Rutas de credenciales y perfiles:
  • Perfiles de autenticación (claves de API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Importación de OAuth heredado: ~/.openclaw/credentials/oauth.json
Modo de almacenamiento de credenciales:
  • El comportamiento predeterminado de la incorporación conserva las claves de API como valores de texto sin formato en los perfiles de autenticación.
  • --secret-input-mode ref activa el modo de referencia en lugar del almacenamiento de claves en texto sin formato. En la configuración interactiva, se puede elegir entre:
    • referencia de variable de entorno (por ejemplo, keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
    • referencia de proveedor configurada (file o exec) con alias + ID del proveedor
  • El modo de referencia interactivo ejecuta una validación previa rápida antes de guardar.
    • Referencias de entorno: valida el nombre de la variable y que tenga un valor no vacío en el entorno de incorporación actual.
    • Referencias de proveedor: valida la configuración del proveedor y resuelve el ID solicitado.
    • Si la validación previa falla, la incorporación muestra el error y permite volver a intentarlo.
  • En el modo no interactivo, --secret-input-mode ref solo admite variables de entorno.
    • Defina la variable de entorno del proveedor en el entorno del proceso de incorporación.
    • Las opciones de clave insertada (por ejemplo, --openai-api-key) requieren que se defina esa variable de entorno; de lo contrario, la incorporación falla de inmediato.
    • En los proveedores personalizados, el modo no interactivo 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 se defina CUSTOM_API_KEY; de lo contrario, la incorporación falla de inmediato.
  • Las credenciales de autenticación del Gateway admiten opciones de texto sin formato y SecretRef en la configuración interactiva:
    • Modo de token: Generar/almacenar token en texto sin formato (valor predeterminado) o Usar SecretRef.
    • Modo de contraseña: texto sin formato o SecretRef.
  • Ruta de SecretRef de token no interactiva: --gateway-token-ref-env <ENV_VAR>.
  • Las configuraciones existentes de texto sin formato siguen funcionando sin cambios.
Consejo para servidores y entornos sin interfaz gráfica: complete OAuth en una máquina con navegador y, a continuación, copie el archivo auth-profiles.json de ese agente (por ejemplo, ~/.openclaw/agents/<agentId>/agent/auth-profiles.json o la ruta $OPENCLAW_STATE_DIR/... correspondiente) al host del gateway. credentials/oauth.json es únicamente una fuente de importación heredada.

​
Resultados y funcionamiento interno

Campos habituales en ~/.openclaw/openclaw.json:
  • agents.defaults.workspace
  • agents.defaults.skipBootstrap cuando se proporciona --skip-bootstrap
  • agents.defaults.model / models.providers (si se selecciona Minimax)
  • tools.profile (la incorporación local utiliza de forma predeterminada "coding" cuando no está definido; se conservan los valores explícitos existentes)
  • gateway.* (modo, enlace, autenticación, Tailscale)
  • session.dmScope (la incorporación conserva los valores explícitos y, de lo contrario, lo deja sin definir, por lo que el valor predeterminado main mantiene todos los mensajes directos de todos los canales en la sesión principal continua del agente, que es el valor predeterminado para agentes personales. Para bandejas de entrada compartidas o multiusuario, utilice per-channel-peer; openclaw security audit recomienda el aislamiento cuando detecta tráfico de mensajes directos de varios usuarios)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Listas de permitidos de canales (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) cuando se aceptan durante las indicaciones; Discord y Slack también resuelven los nombres introducidos a ID
  • skills.install.nodeManager
    • La opción setup --node-manager acepta npm, pnpm o bun.
    • La configuración manual todavía puede definir skills.install.nodeManager: "yarn" posteriormente.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
  • wizard.securityAcknowledgedAt
openclaw agents add escribe agents.entries.* y el valor opcional bindings. Las credenciales de WhatsApp se almacenan en ~/.openclaw/credentials/whatsapp/<accountId>/. Las sesiones activas y las transcripciones se almacenan en ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. El directorio ~/.openclaw/agents/<agentId>/sessions/ se utiliza para entradas de migración heredadas y artefactos de archivo o soporte.
Algunos canales se proporcionan como plugins. Cuando se seleccionan durante la configuración, el asistente solicita instalar el plugin (mediante npm o una ruta local) antes de configurar el canal.

​
Recomendaciones de aplicaciones instaladas

Después de que la comprobación de acceso al modelo se complete correctamente, la incorporación interactiva clásica en macOS analiza los nombres de las aplicaciones y los ID de paquetes sin solicitar permisos de privacidad de macOS. Busca en los catálogos oficiales de plugins y en ClawHub y, a continuación, pide al modelo configurado que descarte las coincidencias de nombres falsas y recomiende plugins o Skills pertinentes. Las coincidencias recomendadas se seleccionan de forma predeterminada; las coincidencias opcionales requieren una selección explícita. La pantalla de resultados enumera las aplicaciones detectadas y muestra: «Los nombres de las aplicaciones se asociaron mediante el modelo configurado y la búsqueda de ClawHub». Defina wizard.appRecommendations como false para desactivar tanto este paso de incorporación como el acceso del Gateway a los inventarios de aplicaciones del Node. El análisis no se utiliza en el inicio rápido ni en la incorporación fuera de macOS.

​
Configuración no interactiva

--non-interactive requiere --accept-risk (confirma que los agentes son potentes y que el acceso completo al sistema conlleva riesgos):
Referencia completa de opciones y ejemplos específicos de proveedores: openclaw onboard, Automatización de la CLI.

​
RPC del asistente del Gateway

  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status
Los clientes (la aplicación para macOS y la interfaz de control) pueden representar los pasos sin volver a implementar la lógica de incorporación.

​
Comportamiento de la configuración de Signal

  • Descarga el artefacto de versión apropiado de las versiones oficiales de GitHub de signal-cli (compilación nativa, solo Linux x86-64)
  • En otras plataformas (macOS y Linux que no sea x64), realiza la instalación mediante Homebrew
  • Almacena la instalación del artefacto de versión en ~/.openclaw/tools/signal-cli/<version>/
  • Escribe channels.signal.transport.cliPath con kind: "managed-native" en la configuración
  • Windows nativo todavía no es compatible; ejecute la incorporación dentro de WSL2 para obtener la ruta de instalación de Linux

​
Documentación relacionada