Incorporación

`openclaw onboard`

Incorporación guiada completa para la configuración local o remota de Gateway. Úselo cuando desee que OpenClaw recorra la autenticación del modelo, el espacio de trabajo, la puerta de enlace, los canales, las habilidades y el estado en un solo flujo.

Guías relacionadas

Centro de incorporación de la CLI

Recorrido del flujo interactivo de la CLI.

Descripción general de la incorporación

Cómo se integra la incorporación de OpenClaw.

Referencia de configuración de la CLI

Resultados, funcionamiento interno y comportamiento por paso.

Automatización de la CLI

Opciones no interactivas y configuraciones con scripts.

Incorporación de la aplicación de macOS

Flujo de incorporación para la aplicación de la barra de menús de macOS.

Ejemplos

openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow import utiliza proveedores de migración propiedad de complementos como Hermes. Solo se ejecuta en una configuración nueva de OpenClaw; si existe una configuración, credenciales, sesiones o archivos de memoria/identidad del espacio de trabajo, restablezca o elija una configuración nueva antes de importar.

--modern inicia la vista previa de la incorporación conversacional de Crestodian. Sin --modern, openclaw onboard mantiene el flujo de incorporación clásico.

En una instalación nueva donde falta el archivo de configuración activo o no tiene configuraciones creadas (vacío o solo metadatos), openclaw desnudo también inicia el flujo de incorporación clásico. Una vez que un archivo de configuración tiene configuraciones creadas, openclaw desnudo abre Crestodian en su lugar.

Se acepta ws:// en texto sin formato para bucle de retorno, literales de IP privada, .local y URL de puerta de enlace de Tailnet *.ts.net. Para otros nombres de DNS privados de confianza, configure OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 en el entorno del proceso de incorporación.

Configuración regional

La incorporación interactiva utiliza la configuración regional del asistente de CLI para el texto fijo de configuración. El orden de resolución es:

OPENCLAW_LOCALE
LC_ALL
LC_MESSAGES
LANG
Respaldo en inglés

Las configuraciones regionales del asistente compatibles son en, zh-CN y zh-TW. Los valores de configuración regional pueden usar formas de sufijo de guion bajo o POSIX como zh_CN.UTF-8. Los nombres de productos, nombres de comandos, claves de configuración, URL, ID de proveedores, ID de modelos y etiquetas de complementos/canales permanecen literales.

Ejemplo:

OPENCLAW_LOCALE=zh-CN openclaw onboard

Proveedor personalizado no interactivo:

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --custom-image-input

--custom-api-key es opcional en el modo no interactivo. Si se omite, la incorporación verifica CUSTOM_API_KEY. OpenClaw marca los ID de modelo de visión comunes como con capacidad de imagen automáticamente. Pase --custom-image-input para ID de visión personalizados desconocidos, o --custom-text-input para forzar metadatos de solo texto. Use --custom-compatibility openai-responses para puntos de conexión compatibles con OpenAI que admitan /v1/responses pero no /v1/chat/completions.

LM Studio también admite una clave de indicador específica del proveedor en modo no interactivo:

openclaw onboard --non-interactive \
  --auth-choice lmstudio \
  --custom-base-url "http://localhost:1234/v1" \
  --custom-model-id "qwen/qwen3.5-9b" \
  --lmstudio-api-key "$LM_API_TOKEN" \
  --accept-risk

Ollama no interactivo:

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

--custom-base-url por defecto es http://127.0.0.1:11434. --custom-model-id es opcional; si se omite, la incorporación usa los valores predeterminados sugeridos por Ollama. Los ID de modelos en la nube como kimi-k2.5:cloud también funcionan aquí.

Almacenar las claves del proveedor como referencias en lugar de texto sin formato:

openclaw onboard --non-interactive \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --accept-risk

Con --secret-input-mode ref, la incorporación escribe referencias respaldadas por variables de entorno en lugar de valores de clave en texto plano. Para proveedores respaldados por perfil de autenticación, esto escribe entradas keyRef; para proveedores personalizados, esto escribe models.providers.<id>.apiKey como una referencia de entorno (por ejemplo, { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

Contrato del modo no interactivo ref:

Establezca la variable de entorno del proveedor en el entorno del proceso de incorporación (por ejemplo, OPENAI_API_KEY).
No pase indicadores de clave en línea (por ejemplo, --openai-api-key) a menos que esa variable de entorno también esté establecida.
Si se pasa un flag de clave en línea sin la variable de env requerida, la incorporación falla rápidamente con orientación.

Opciones de token de Gateway en modo no interactivo:

--gateway-auth token --gateway-token <token> almacena un token en texto plano.
--gateway-auth token --gateway-token-ref-env <name> almacena gateway.auth.token como un SecretRef de entorno.
--gateway-token y --gateway-token-ref-env son mutuamente excluyentes.
--gateway-token-ref-env requiere una variable de entorno no vacía en el entorno del proceso de incorporación.
Con --install-daemon, cuando la autenticación de token requiere un token, los tokens de puerta de enlace administrados por SecretRef se validan pero no se persisten como texto plano resuelto en los metadatos del entorno del servicio supervisor.
Con --install-daemon, si el modo de token requiere un token y el token SecretRef configurado no está resuelto, la incorporación falla de forma segura con orientación de remediación.
Con --install-daemon, si tanto gateway.auth.token como gateway.auth.password están configurados y gateway.auth.mode no está definido, la incorporación bloquea la instalación hasta que el modo se establezca explícitamente.
La incorporación local escribe gateway.mode="local" en la configuración. Si un archivo de configuración posterior carece de gateway.mode, trátelo como un daño en la configuración o una edición manual incompleta, no como un acceso directo válido en modo local.
La incorporación local instala los complementos descargables seleccionados cuando la ruta de configuración elegida los requiere.
La incorporación remota solo escribe información de conexión para la Gateway remota y no instala paquetes de complementos locales.
--allow-unconfigured es una puerta de escape separada del tiempo de ejecución de la puerta de enlace. No significa que la incorporación pueda omitir gateway.mode.

Ejemplo:

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
  --accept-risk

Estado de salud de la puerta de enlace local no interactiva:

A menos que pase --skip-health, la incorporación espera a que una puerta de enlace local sea accesible antes de salir con éxito.
--install-daemon inicia primero la ruta de instalación de la puerta de enlace administrada. Sin él, ya debe tener una puerta de enlace local en ejecución, por ejemplo openclaw gateway run.
Si solo desea escrituras de configuración/espacio de trabajo/inicialización en automatización, use --skip-health.
Si gestiona los archivos del espacio de workspace usted mismo, pase --skip-bootstrap para establecer agents.defaults.skipBootstrap: true y omitir la creación de AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md y BOOTSTRAP.md.
En Windows nativo, --install-daemon intenta primero las Tareas Programadas y recurre a un elemento de inicio de sesión en la carpeta Inicio por usuario si se deniega la creación de la tarea.

Comportamiento de incorporación interactiva con el modo de referencia:

Elige Usar referencia secreta cuando se te solicite.
Luego elige entre:
- Variable de entorno
- Proveedor de secretos configurado (file o exec)
La incorporación realiza una validación previa rápida antes de guardar la referencia.
- Si la validación falla, la incorporación muestra el error y te permite reintentar.

Elecciones de endpoint Z.AI no interactivas

# Promptless endpoint selection
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# Other Z.AI endpoint choices:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn

Ejemplo no interactivo de Mistral:

openclaw onboard --non-interactive \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

Notas de flujo

Tipos de flujo

quickstart: indicaciones mínimas, genera automáticamente un token de gateway.
manual: indicaciones completas para el puerto, enlace y autenticación (alias de advanced).
import: ejecuta un proveedor de migración detectado, previsualiza el plan y luego lo aplica después de la confirmación.

Prefiltrado de proveedores

Cuando una elección de autenticación implica un proveedor preferido, el proceso de incorporación prefiltra los selectores de modelo predeterminado y lista de permitidos a ese proveedor. Para Volcengine y BytePlus, esto también coincide con las variantes del plan de codificación (volcengine-plan/*, byteplus-plan/*).

Si el filtro del proveedor preferido no arroja modelos cargados aún, el proceso de incorporación vuelve al catálogo sin filtrar en lugar de dejar el selector vacío.

Acciones de seguimiento de búsqueda web

Algunos proveedores de búsqueda web activan indicaciones de seguimiento específicas del proveedor:

Grok puede ofrecer una configuración opcional de x_search con el mismo perfil OAuth de xAI o clave API y una elección de modelo x_search.
Kimi puede solicitar la región de la API de Moonshot (api.moonshot.ai vs api.moonshot.cn) y el modelo de búsqueda web de Kimi predeterminado.

Otros comportamientos

Comportamiento del alcance DM de incorporación local: Referencia de configuración de CLI.
Primer chat más rápido: openclaw dashboard (Interfaz de usuario de Control, sin configuración de canal).
Proveedor personalizado: conecte cualquier punto de conexión compatible con OpenAI o Anthropic, incluidos los proveedores alojados no listados. Use Desconocido para detectar automáticamente.
Si se detecta el estado de Hermes, la incorporación ofrece un flujo de migración. Use Migrate para planes de ejecución en seco, modo de sobrescritura, informes y mapeos exactos.

Comandos de seguimiento comunes

openclaw channels add
openclaw configure
openclaw agents add <name>

Use openclaw setup en su lugar cuando solo necesite la configuración/espacio de trabajo base. Use openclaw configure más tarde para cambios específicos y openclaw channels add para la configuración solo de canales.