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 consultar una guía, véase Incorporación (CLI). Para consultar la referencia completa de indicadores de la CLI (cada --flag, ejemplos no interactivos y comandos específicos de proveedores), véase 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 propiedad de proveedores)
• Ubicación del espacio de trabajo y archivos de arranque
• Ajustes del Gateway (puerto, vinculación, autenticación, Tailscale)
• Canales y proveedores (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp y otros canales incluidos 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 Inicio)
• 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.

Datos que se configuran:

• URL del Gateway remoto (ws://... o wss://...)
• Token, contraseña o ausencia de autenticación, según la configuración del Gateway remoto

Opciones de autenticación y modelo

Si un paso de configuración del proveedor falla durante la incorporación interactiva (por ejemplo, una opción para reutilizar la CLI sin un inicio de sesión local), el asistente muestra el error y vuelve al selector de proveedores en lugar de cerrarse. Las ejecuciones explícitas de --auth-choice siguen produciendo un fallo inmediato para la automatización.

Comportamiento del modelo:

• Seleccione el modelo predeterminado entre las opciones detectadas o introduzca manualmente el proveedor y el modelo.
• Cuando la incorporación comienza desde una opción de autenticación de proveedor, el selector de modelos prioriza automáticamente ese proveedor. Para 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 devolviera resultados, el selector recurre al 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 de almacenar las claves en texto sin formato. En la configuración interactiva, puede elegir entre:
  • referencia a una variable de entorno (por ejemplo, keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • referencia a un proveedor configurado (file o exec) con alias e 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 respaldo mediante variables de entorno.
  • Defina la variable de entorno del proveedor en el entorno del proceso de incorporación.
  • Los indicadores de claves insertadas directamente (por ejemplo, --openai-api-key) requieren que esa variable de entorno esté definida; de lo contrario, la incorporación falla de inmediato.
  • Para 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 CUSTOM_API_KEY esté definido; 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 un token en texto sin formato (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 con 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 elige 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, de modo que el valor predeterminado main mantiene todos los mensajes directos de los distintos 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 acepta activarlas durante las solicitudes; Discord y Slack también convierten los nombres introducidos en ID
• skills.install.nodeManager
  • El indicador setup --node-manager acepta npm, pnpm o bun.
  • La configuración manual todavía puede establecer skills.install.nodeManager: "yarn" posteriormente.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

openclaw agents add escribe agents.entries.* y, opcionalmente, 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 las entradas de migración heredadas y los artefactos de archivo o soporte.

Recomendaciones de aplicaciones instaladas

Después de que la comprobación de acceso al modelo finalice correctamente, la incorporación interactiva clásica en macOS analiza los nombres de las aplicaciones y los ID de los paquetes sin solicitar permisos de privacidad de macOS. Busca en los catálogos oficiales de plugins y en ClawHub y, después, solicita al modelo configurado que descarte las coincidencias de nombres falsas y recomiende plugins o Skills relevantes. 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 compararon mediante el modelo configurado y la búsqueda de ClawHub». Establezca wizard.appRecommendations en false para desactivar tanto este paso de la incorporación como el acceso del Gateway a los inventarios de aplicaciones de los nodos. 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 indicadores 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 de 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 recurso de versión adecuado de las versiones de GitHub oficiales de signal-cli (compilación nativa, solo Linux x86-64)
• En otras plataformas (macOS, Linux que no sea x64), realiza la instalación mediante Homebrew
• Almacena la instalación del recurso de versión en ~/.openclaw/tools/signal-cli/<version>/
• Escribe channels.signal.cliPath 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