Referencia de configuración de la CLI

Esta página es la referencia completa para openclaw onboard. Para la guía breve, consulta Incorporación (CLI).

Qué hace el asistente

El modo local (predeterminado) te guía por:

• Configuración de modelo y autenticación (OAuth de suscripción de OpenAI Code, CLI o clave de API de Anthropic Claude, además de opciones de MiniMax, GLM, Ollama, Moonshot, StepFun y AI Gateway)
• Ubicación del espacio de trabajo y archivos de arranque
• Configuración de Gateway (puerto, enlace, autenticación, Tailscale)
• Canales y proveedores (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage y otros plugins de canal incluidos)
• Instalación del daemon (LaunchAgent, unidad de usuario systemd o tarea programada nativa de Windows con alternativa de carpeta de inicio)
• Comprobación de estado
• Configuración de Skills

El modo remoto configura esta máquina para conectarse a un gateway en otra ubicación. 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 en otra ubicación.

Lo que configuras:

• URL del gateway remoto (ws://...)
• Token si el gateway remoto requiere autenticación (recomendado)

Opciones de autenticación y modelo

Comportamiento del modelo:

• Elige el modelo predeterminado de las opciones detectadas, o introduce el proveedor y el modelo manualmente.
• La incorporación de proveedor personalizado infiere la compatibilidad con imágenes para ID de modelo comunes y solo pregunta cuando se desconoce el nombre del modelo.
• Cuando la incorporación empieza desde una opción de autenticación de proveedor, el selector de modelo prefiere ese proveedor automáticamente. Para Volcengine y BytePlus, la misma preferencia también coincide con sus variantes de plan de codificación (volcengine-plan/*, byteplus-plan/*).
• Si ese filtro de proveedor preferido quedara vacío, el selector vuelve al catálogo completo en lugar de no mostrar modelos.
• El asistente ejecuta una comprobación de modelo y advierte si el modelo configurado es desconocido o no tiene 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 heredada: ~/.openclaw/credentials/oauth.json

Modo de almacenamiento de credenciales:

• El comportamiento de incorporación predeterminado conserva las claves de API como valores de texto plano en los perfiles de autenticación.
• --secret-input-mode ref habilita el modo de referencia en lugar del almacenamiento de claves en texto plano. En la configuración interactiva, puedes elegir:
  • referencia de variable de entorno (por ejemplo keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • referencia de proveedor configurado (file o exec) con alias de proveedor + id
• El modo de referencia interactivo ejecuta una validación preliminar rápida antes de guardar.
  • Referencias de entorno: valida el nombre de la variable + 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 preliminar falla, la incorporación muestra el error y te permite reintentarlo.
• En modo no interactivo, --secret-input-mode ref solo está respaldado por entorno.
  • Define la variable de entorno del proveedor en el entorno del proceso de incorporación.
  • Las marcas de clave en línea (por ejemplo --openai-api-key) requieren que esa variable de entorno esté definida; de lo contrario, la incorporación falla de inmediato.
  • Para proveedores personalizados, el modo ref no interactivo 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é definida; de lo contrario, la incorporación falla de inmediato.
• Las credenciales de autenticación de Gateway admiten opciones de texto plano y SecretRef en la configuración interactiva:
  • Modo de token: Generar/almacenar token en texto plano (predeterminado) o Usar SecretRef.
  • Modo de contraseña: texto plano o SecretRef.
• Ruta de SecretRef de token no interactiva: --gateway-token-ref-env <ENV_VAR>.
• Las configuraciones existentes con texto plano siguen funcionando sin cambios.

Salidas e internos

Campos habituales en ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.skipBootstrap cuando se pasa --skip-bootstrap
• agents.defaults.model / models.providers (si se elige Minimax)
• tools.profile (la incorporación local usa "coding" de forma predeterminada cuando no está definido; los valores explícitos existentes se conservan)
• gateway.* (modo, enlace, autenticación, tailscale)
• session.dmScope (la incorporación local usa per-channel-peer de forma predeterminada cuando no está definido; los valores explícitos existentes se conservan)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Listas de permitidos de canales (Slack, Discord, Matrix, Microsoft Teams) cuando aceptas durante los avisos (los nombres se resuelven a ID cuando es posible)
• skills.install.nodeManager
  • La marca setup --node-manager acepta npm, pnpm o bun.
  • La configuración manual aún puede definir skills.install.nodeManager: "yarn" más adelante.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

openclaw agents add escribe agents.list[] y bindings opcionales.

Las credenciales de WhatsApp van en ~/.openclaw/credentials/whatsapp/<accountId>/. Las sesiones se almacenan en ~/.openclaw/agents/<agentId>/sessions/.

RPC del asistente de Gateway:

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Los clientes (app de macOS y Control UI) pueden renderizar pasos sin volver a implementar la lógica de incorporación.

Comportamiento de configuración de Signal:

• Descarga el recurso de lanzamiento apropiado
• Lo almacena en ~/.openclaw/tools/signal-cli/<version>/
• Escribe channels.signal.cliPath en la configuración
• Las compilaciones JVM requieren Java 21
• Las compilaciones nativas se usan cuando están disponibles
• Windows usa WSL2 y sigue el flujo de signal-cli de Linux dentro de WSL

Documentos relacionados

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