Referencia de configuración de la CLI

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

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

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.

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.

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.

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):

openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

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

• Centro de incorporación: Incorporación (CLI)
• Automatización y scripts: Automatización de la CLI
• Referencia de comandos: openclaw onboard