Ir al contenido
OpenClaw Docs

Referencia de configuración de CLI

Esta página es la referencia completa de openclaw onboard. Para la guía breve, consulte Onboarding (CLI).

Lo que hace el asistente

Sección titulada «Lo que hace el asistente»

El modo local (predeterminado) le guía a través de:

  • Configuración de modelo y autenticación (suscripción OpenAI Code OAuth, Anthropic Claude CLI o clave API, 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 puerta de enlace (puerto, vinculación, autenticación, tailscale)
  • Canales y proveedores (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, iMessage y otros complementos de canal incluidos)
  • Instalación del demonio (LaunchAgent, unidad de usuario systemd o Tarea programada nativa de Windows con respaldo a la carpeta de Inicio)
  • Verificación de estado
  • Configuración de habilidades

El modo remoto configura esta máquina para conectarse a una puerta de enlace en otro lugar. No instala ni modifica nada en el host remoto.

Detalles del flujo local

Sección titulada «Detalles del flujo local»

  1. Detección de configuración existente

    • Si ~/.openclaw/openclaw.json existe, elija Keep (Mantener), Modify (Modificar) o Reset (Restablecer).
    • Volver a ejecutar el asistente no borra nada a menos que elija explícitamente Reset (o pase --reset).
    • La CLI --reset tiene como valor predeterminado config+creds+sessions; use --reset-scope full para también eliminar el espacio de trabajo.
    • Si la configuración no es válida o contiene claves heredadas, el asistente se detiene y le pide que ejecute openclaw doctor antes de continuar.
    • Reset usa trash y ofrece ámbitos:
      • Solo configuración
      • Configuración + credenciales + sesiones
      • Restablecimiento completo (también elimina el espacio de trabajo)

  2. Modelo y autenticación

  3. Espacio de trabajo

    • Predeterminado ~/.openclaw/workspace (configurable).
    • Siembra archivos de espacio de trabajo necesarios para el ritual de arranque de la primera ejecución.
    • Diseño del espacio de trabajo: Agent workspace.

  4. Puerta de enlace

    • Solicita puerto, enlace, modo de autenticación y exposición a tailscale.
    • Recomendado: mantenga la autenticación por token habilitada incluso para loopback para que los clientes WS locales deban autenticarse.
    • En modo token, la configuración interactiva ofrece:
      • Generar/guardar token en texto sin formato (predeterminado)
      • Usar SecretRef (opcional)
    • En modo contraseña, la configuración interactiva también admite almacenamiento en texto sin formato o SecretRef.
    • Ruta de SecretRef de token no interactivo: `—gateway-token-ref-env

    . - Requiere una var de env no vacía en el entorno del proceso de incorporación. - No se puede combinar con —gateway-token`. - Desactive la autenticación solo si confía completamente en cada proceso local. - Los enlaces que no son de loopback aún requieren autenticación.

  5. Canales

    • WhatsApp: inicio de sesión con QR opcional
    • Telegram: token del bot
    • Discord: token del bot
    • Google Chat: JSON de cuenta de servicio + audiencia del webhook
    • Mattermost: token del bot + URL base
    • Signal: instalación opcional de signal-cli + configuración de cuenta
    • iMessage: ruta de la CLI de imsg + acceso a la base de datos de Messages; use un contenedor SSH cuando el Gateway se ejecuta fuera de Mac
    • Seguridad de MD: el valor predeterminado es el emparejamiento. El primer MD envía un código; apruébelo a través de `openclaw pairing approve

    ` o use listas de permitidos.

Detalles del modo remoto

Sección titulada «Detalles del modo remoto»

El modo remoto configura esta máquina para conectarse a una puerta de enlace en otro lugar.

Lo que configura:

  • URL de la puerta de enlace remota (ws://...)
  • Token si se requiere autenticación en la puerta de enlace remota (recomendado)

Opciones de autenticación y modelo

Sección titulada «Opciones de autenticación y modelo»
Clave de API de Anthropic

Usa ANTHROPIC_API_KEY si está presente o solicita una clave, y luego la guarda para su uso por el demonio.

Suscripción de OpenAI Code (OAuth)

Flujo del navegador; pegue code#state.

Establece agents.defaults.model en openai/gpt-5.5 a través del tiempo de ejecución de Codex cuando el modelo no está configurado o ya es de la familia OpenAI.

Suscripción de OpenAI Code (emparejamiento de dispositivos)

Flujo de emparejamiento del navegador con un código de dispositivo de corta duración.

Establece agents.defaults.model en openai/gpt-5.5 a través del tiempo de ejecución de Codex cuando el modelo no está configurado o ya es de la familia OpenAI.

Clave de API de OpenAI

Usa OPENAI_API_KEY si está presente o solicita una clave, y luego almacena la credencial en los perfiles de autenticación.

Establece agents.defaults.model en openai/gpt-5.5 cuando el modelo no está configurado, openai/*, o openai-codex/*.

OAuth de xAI (Grok)

Inicio de sesión en el navegador para cuentas SuperGrok o X Premium elegibles. Esta es la ruta de xAI recomendada para la mayoría de los usuarios. OpenClaw almacena el perfil de autenticación resultante para los modelos Grok, x_search, y code_execution.

Código de dispositivo de xAI (Grok)

Inicio de sesión en el navegador compatible con entornos remotos con un código corto en lugar de una devolución de llamada de localhost. Use esto desde hosts SSH, Docker o VPS.

Clave de API de xAI (Grok)

Solicita XAI_API_KEY y configura xAI como proveedor de modelos. Use esto cuando desee una clave de API de la Consola xAI en lugar de OAuth de suscripción.

OpenCode

Solicita OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY) y te permite elegir el catálogo Zen o Go. URL de configuración: opencode.ai/auth.

API key (generic)

Guarda la clave por ti.

Vercel AI Gateway

Solicita AI_GATEWAY_API_KEY. Más detalles: Vercel AI Gateway.

Cloudflare AI Gateway

Solicita el ID de cuenta, el ID de gateway y CLOUDFLARE_AI_GATEWAY_API_KEY. Más detalles: Cloudflare AI Gateway.

MiniMax

La configuración se escribe automáticamente. El predeterminado alojado 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. El estándar actualmente incluye step-3.5-flash, y Step Plan también incluye step-3.5-flash-2603. Más detalles: StepFun.

Synthetic (Anthropic-compatible)

Solicita SYNTHETIC_API_KEY. Más detalles: Synthetic.

Ollama (Cloud and local open models)

Solicita Cloud + Local, Cloud only o Local only primero. Cloud only usa OLLAMA_API_KEY con https://ollama.com. Los modos respaldados por el host solicitan la URL base (por defecto http://127.0.0.1:11434), descubren los modelos disponibles y sugieren valores predeterminados. Cloud + Local también comprueba si ese host de Ollama ha iniciado sesión para el acceso en la nube. Más detalles: Ollama.

Moonshot and Kimi Coding

Las configuraciones de Moonshot (Kimi K2) y Kimi Coding se escriben automáticamente. Más detalles: Moonshot AI (Kimi + Kimi Coding).

Custom provider

Funciona con endpoints compatibles con OpenAI y Anthropic.

La incorporación interactiva admite las mismas opciones de almacenamiento de claves API que otros flujos de claves API de proveedores:

  • Pegar clave API ahora (texto sin formato)
  • Usar referencia secreta (referencia de entorno o referencia de proveedor configurada, con validación previa)

Opciones no interactivas:

  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key (opcional; recurre a CUSTOM_API_KEY)
  • --custom-provider-id (opcional)
  • `—custom-compatibility

(opcional; por defectoopenai) - —custom-image-input/—custom-text-input` (opcional; anula la capacidad de entrada del modelo inferida)

Skip

Deja la autenticación sin configurar.

Comportamiento del modelo:

  • Elija el modelo predeterminado de las opciones detectadas o ingrese el proveedor y el modelo manualmente.
  • La incorporación de proveedores personalizados infiere la compatibilidad de imágenes para IDs de modelos comunes y solo pregunta cuando el nombre del modelo es desconocido.
  • Cuando el onboarding comienza desde una elección de autenticación de proveedor, el selector de modelos prefiere automáticamente ese proveedor. 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 estuviera vacío, el selector recurre al catálogo completo en lugar de no mostrar ningún modelo.
  • El asistente ejecuta una verificación del modelo y advierte si el modelo configurado es desconocido o le falta autenticación.

Rutas de credenciales y perfiles:

  • Perfiles de autenticación (claves de API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Importación heredada de OAuth: ~/.openclaw/credentials/oauth.json

Modo de almacenamiento de credenciales:

  • El comportamiento predeterminado del onboarding persiste las claves de API como valores de texto sin formato en los perfiles de autenticación.
  • --secret-input-mode ref habilita el modo de referencia en lugar del almacenamiento de clave en texto sin formato. En la configuración interactiva, puede elegir cualquiera de:
    • 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 previa rápida antes de guardar.
    • Referencias de entorno: valida el nombre de la variable + un valor no vacío en el entorno de onboarding actual.
    • Referencias de proveedor: valida la configuración del proveedor y resuelve el id solicitado.
    • Si la validación previa falla, el onboarding muestra el error y le permite reintentar.
  • En modo no interactivo, --secret-input-mode ref solo se basa en el entorno.
    • Establezca la variable de entorno del proveedor en el entorno del proceso de onboarding.
    • Las banderas de clave en línea (por ejemplo, --openai-api-key) requieren que esa variable de entorno esté configurada; de lo contrario, el onboarding falla rápidamente.
    • Para 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é configurado; de lo contrario, el onboarding falla rápidamente.
  • Las credenciales de autenticación de Gateway admiten opciones de texto sin formato y SecretRef en la configuración interactiva:
    • Modo de token: Generar/almacenar token en texto sin formato (predeterminado) o Usar SecretRef.
    • Modo de contraseña: texto sin formato o SecretRef.
  • Ruta de SecretRef de token no interactivo: --gateway-token-ref-env <ENV_VAR>.
  • Las configuraciones existentes en texto plano siguen funcionando sin cambios.

Salidas e aspectos internos

Sección titulada «Salidas e aspectos internos»

Campos típicos 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 por defecto "coding" si no está establecido; se preservan los valores explícitos existentes)
  • gateway.* (modo, bind, auth, tailscale)
  • session.dmScope (la incorporación local establece esto por defecto a per-channel-peer si no está establecido; se preservan los valores explícitos existentes)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
  • Listas de permitidos (allowlists) de canales (Slack, Discord, Matrix, Microsoft Teams) cuando opta por participar durante las indicaciones (los nombres se resuelven en IDs cuando es posible)
  • skills.install.nodeManager
    • La opción setup --node-manager acepta npm, pnpm o bun.
    • La configuración manual aún puede establecer skills.install.nodeManager: "yarn" más tarde.
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode

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

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

Asistente RPC de puerta de enlace (Gateway wizard RPC):

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

Los clientes (aplicación de macOS y UI de control) pueden renderizar pasos sin reimplementar la lógica de incorporación.

Comportamiento de configuración de Signal:

  • Descarga el recurso de lanzamiento apropiado
  • Lo almacena bajo ~/.openclaw/tools/signal-cli/<version>/
  • Escribe channels.signal.cliPath en la configuración
  • Las compilaciones de 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

Sección titulada «Documentos relacionados»