Configuración Guiada: Configuración Integral de Clawdbot
Lo Que Aprenderás
Con este tutorial podrás:
- ✅ Usar el asistente interactivo para completar la configuración integral de Clawdbot
- ✅ Comprender la diferencia entre los modos QuickStart y Manual
- ✅ Configurar la red Gateway y las opciones de autenticación
- ✅ Configurar los proveedores de modelos AI (setup-token y API Key)
- ✅ Habilitar canales de comunicación (WhatsApp, Telegram, etc.)
- ✅ Instalar y gestionar paquetes de habilidades
Al completar el asistente, Clawdbot Gateway se ejecutará en segundo plano y podrás conversar con el asistente de IA a través de los canales configurados.
Tu Situación Actual
Editar manualmente los archivos de configuración es complicado:
- No se sabe el significado de las opciones de configuración ni sus valores predeterminados
- Es fácil omitir configuraciones clave que impiden el inicio
- Los métodos de autenticación de modelos AI son variados (OAuth, API Key) y no se sabe cuál elegir
- La configuración de canales es compleja y cada plataforma tiene diferentes métodos de autenticación
- No se sabe qué habilidades instalar en el sistema de habilidades
La configuración guiada resuelve estos problemas, guiándote a través de todas las configuraciones mediante preguntas interactivas y proporcionando valores predeterminados razonables.
Cuándo Usar Este Método
- Primera instalación: Nuevos usuarios usando Clawdbot por primera vez
- Reconfiguración: Necesitas modificar la configuración de Gateway, cambiar el modelo de IA o agregar nuevos canales
- Validación rápida: Quieres experimentar las funciones básicas rápidamente sin profundizar en los archivos de configuración
- Solución de problemas: Después de errores de configuración, usar el asistente para reinicializar
Consejo
El asistente detectará las configuraciones existentes y podrás elegir entre conservar, modificar o restablecer la configuración.
Conceptos Fundamentales
Dos Modos
El asistente proporciona dos modos de configuración:
Modo QuickStart (recomendado para principiantes)
- Usa valores predeterminados seguros: Gateway vinculado a loopback (127.0.0.1), puerto 18789, autenticación token
- Omite la mayoría de las opciones de configuración detalladas
- Ideal para uso en una sola máquina, puesta en marcha rápida
Modo Manual (para usuarios avanzados)
- Configura manualmente todas las opciones
- Soporta vinculación LAN, acceso remoto Tailscale, métodos de autenticación personalizados
- Ideal para implementaciones multi-máquina, acceso remoto o entornos de red especiales
Flujo de Configuración
1. Confirmación de advertencia de seguridad
2. Selección de modo (QuickStart / Manual)
3. Configuración de Gateway (puerto, vinculación, autenticación, Tailscale)
4. Autenticación de modelo AI (setup-token / API Key)
5. Configuración de espacio de trabajo (predeterminado ~/clawd)
6. Configuración de canales (WhatsApp / Telegram / Slack, etc.)
7. Instalación de habilidades (opcional)
8. Finalización (inicio de Gateway)Recordatorio de Seguridad
Al inicio, el asistente mostrará una advertencia de seguridad y deberás confirmar lo siguiente:
- Clawdbot es un proyecto amateur, aún en fase beta
- Una vez habilitadas las herramientas, la IA puede leer archivos y ejecutar operaciones
- Prompts maliciosos pueden inducir a la IA a realizar operaciones inseguras
- Se recomienda usar emparejamiento/lista blanca + herramientas de mínimos privilegios
- Realizar auditorías de seguridad periódicamente
Importante
Si no comprendes los mecanismos básicos de seguridad y control de acceso, no habilites herramientas ni expongas Gateway a Internet. Se recomienda pedir ayuda a alguien con experiencia para configurar antes de usar.
🎒 Preparación Antes de Comenzar
Antes de ejecutar el asistente, confirma:
- Clawdbot instalado: Consulta Inicio Rápido para completar la instalación
- Versión de Node.js: Asegúrate de que Node.js sea ≥ 22 (usa
node -vpara verificar) - Cuenta de modelo AI (recomendado):
- Cuenta de Anthropic Claude (suscripción Pro/Max), soporta flujo OAuth
- O tener preparada la API Key de proveedores como OpenAI/DeepSeek
- Cuenta de canal (opcional): Si necesitas usar WhatsApp, Telegram, etc., registra las cuentas correspondientes primero
- Permisos de red: Si necesitas usar Tailscale, asegúrate de tener instalado el cliente de Tailscale
Sígueme
Paso 1: Iniciar el Asistente
Abre la terminal y ejecuta el siguiente comando:
clawdbot onboardPor qué Inicia el asistente de configuración interactivo, guiándote a través de todas las configuraciones necesarias.
Deberías ver:
┌─────────────────────────────────────────────────────┐
│ │
│ Clawdbot onboarding │
│ │
└─────────────────────────────────────────────────────┘Paso 2: Confirmar Advertencia de Seguridad
El asistente primero muestra la advertencia de seguridad (como se describe en la sección "Conceptos Fundamentales").
Por qué Asegura que el usuario comprenda los riesgos potenciales y evite el uso incorrecto que cause problemas de seguridad.
Acción:
- Lee el contenido de la advertencia de seguridad
- Escribe
yo seleccionaYespara confirmar que comprendes los riesgos - Si no aceptas los riesgos, el asistente se cerrará
Deberías ver:
Security warning — please read.
Clawdbot is a hobby project and still in beta. Expect sharp edges.
...
I understand this is powerful and inherently risky. Continue? (y/N)Paso 3: Seleccionar Modo de Configuración
Recomendado para principiantes, usa valores predeterminados seguros:
- Puerto de Gateway: 18789
- Dirección de vinculación: Loopback (127.0.0.1)
- Método de autenticación: Token (generado automáticamente)
- Tailscale: DesactivadoPara usuarios avanzados, configura manualmente todas las opciones:
- Puerto de Gateway personalizado y vinculación
- Seleccionar autenticación Token o Password
- Configurar acceso remoto Tailscale Serve/Funnel
- Configurar detalladamente cada pasoPor qué El modo QuickStart permite a los principiantes ponerse en marcha rápidamente, mientras que el modo Manual permite a los usuarios avanzados un control preciso.
Acción:
- Usa las teclas de dirección para seleccionar
QuickStartoManual - Presiona Enter para confirmar
Deberías ver:
? Onboarding mode
QuickStart Configure details later via clawdbot configure.
Manual Configure port, network, Tailscale, and auth options.Paso 4: Seleccionar Modo de Implementación (solo modo Manual)
Si seleccionas el modo Manual, el asistente preguntará dónde se implementará Gateway:
Gateway se ejecuta en la máquina actual:
- Puede ejecutar el flujo OAuth y escribir credenciales locales
- El asistente completará toda la configuración
- Ideal para desarrollo local o implementación en una sola máquinaGateway se ejecuta en otra máquina:
- El asistente solo configura la URL remota y autenticación
- No ejecuta el flujo OAuth, las credenciales deben configurarse manualmente en el host remoto
- Ideal para escenarios de implementación multi-máquinaPor qué El modo Local soporta el flujo de configuración completo, mientras que el modo Remote solo configura la información de acceso.
Acción:
- Selecciona el modo de implementación
- Si es modo Remote, introduce la URL y token del Gateway remoto
Paso 5: Configurar Gateway (solo modo Manual)
Si seleccionas el modo Manual, el asistente preguntará sobre la configuración de Gateway paso a paso:
Puerto de Gateway
? Gateway port (18789)Explicación:
- Valor predeterminado 18789
- Si el puerto está ocupado, introduce otro puerto
- Asegúrate de que el puerto no esté bloqueado por el firewall
Dirección de Vinculación de Gateway
? Gateway bind
Loopback (127.0.0.1)
LAN (0.0.0.0)
Tailnet (Tailscale IP)
Auto (Loopback → LAN)
Custom IPDescripción de opciones:
- Loopback: Solo accesible desde esta máquina, más seguro
- LAN: Dispositivos en la red local pueden acceder
- Tailnet: Acceso a través de la red virtual Tailscale
- Auto: Primero intenta loopback, si falla cambia a LAN
- Custom IP: Especifica manualmente la dirección IP
Consejo
Se recomienda usar Loopback o Tailnet, evitando exponer directamente a la red local.
Método de Autenticación de Gateway
? Gateway auth
Token Recommended default (local + remote)
PasswordDescripción de opciones:
- Token: Opción recomendada, genera automáticamente un token aleatorio, soporta acceso remoto
- Password: Usa una contraseña personalizada, obligatorio para el modo Tailscale Funnel
Acceso Remoto Tailscale (opcional)
? Tailscale exposure
Off No Tailscale exposure
Serve Private HTTPS for your tailnet (devices on Tailscale)
Funnel Public HTTPS via Tailscale Funnel (internet)Advertencia Tailscale
- Modo Serve: Solo dispositivos en la red Tailscale pueden acceder
- Modo Funnel: Expuesto a través de HTTPS público mediante Tailscale Funnel (requiere autenticación por contraseña)
- Asegúrate de que el cliente Tailscale esté instalado: https://tailscale.com/download/mac
Paso 6: Configurar Espacio de Trabajo
El asistente preguntará por el directorio del espacio de trabajo:
? Workspace directory (~/clawd)Explicación:
- Valor predeterminado
~/clawd(es decir,/Users/tu-nombre-de-usuario/clawd) - El espacio de trabajo almacena historial de sesiones, configuraciones de agentes, datos de habilidades, etc.
- Puedes usar rutas absolutas o relativas
Soporte Multi-Perfil (Profile)
Mediante la configuración de la variable de entorno CLAWDBOT_PROFILE, puedes usar configuraciones independientes para diferentes entornos de trabajo:
| Valor de Profile | Ruta del Espacio de Trabajo | Archivo de Configuración |
|---|---|---|
default o no configurado | ~/clawd | ~/.clawdbot/clawdbot.json |
work | ~/clawd-work | ~/.clawdbot/clawdbot.json (work profile) |
dev | ~/clawd-dev | ~/.clawdbot/clawdbot.json (dev profile) |
Ejemplo:
# Usar profile work
export CLAWDBOT_PROFILE=work
clawdbot onboardDeberías ver:
Ensuring workspace directory: /Users/tu-nombre-de-usuario/clawd
Creating sessions.json...
Creating agents directory...Paso 7: Configurar Autenticación de Modelo AI
El asistente listará los proveedores de modelos AI soportados:
? Choose AI model provider
Anthropic Claude Code CLI + API key
OpenAI Codex OAuth + API key
MiniMax M2.1 (recommended)
Qwen OAuth
Venice AI Privacy-focused (uncensored models)
Google Gemini API key + OAuth
Copilot GitHub + local proxy
Vercel AI Gateway API key
Moonshot AI Kimi K2 + Kimi Code
Z.AI (GLM 4.7) API key
OpenCode Zen API key
OpenRouter API key
Custom API Endpoint
Skip for nowDespués de seleccionar un proveedor, el asistente mostrará los métodos de autenticación específicos según el tipo de proveedor. A continuación se muestran las opciones de autenticación de los principales proveedores:
Métodos de autenticación Anthropic:
claude-cli: Usa la autenticación OAuth existente de Claude Code CLI (requiere acceso a Keychain)token: Pega el setup-token generado medianteclaude setup-tokenapiKey: Introduce manualmente la Anthropic API Key
Método setup-token de Anthropic (recomendado)
Se recomienda usar el método setup-token, razones:
- No necesitas gestionar manualmente la API Key
- Genera un token de larga duración
- Ideal para usuarios con suscripción Pro/Max personal
Flujo:
- Primero ejecuta en otra terminal:
claude setup-token - Este comando abrirá el navegador para autorización OAuth
- Copia el setup-token generado
- En el asistente selecciona
Anthropic→token - Pega el setup-token en el asistente
- Las credenciales se guardan automáticamente en el directorio
~/.clawdbot/credentials/
Método API Key
Si seleccionas API Key:
- El asistente pedirá que introduzcas la API Key
- Las credenciales se guardan en el directorio
~/.clawdbot/credentials/ - Soporta múltiples proveedores, puedes cambiar en cualquier momento
Ejemplo:
? Enter API Key
sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxPaso 8: Seleccionar Modelo Predeterminado
Después de la autenticación exitosa, el asistente mostrará la lista de modelos disponibles:
? Select default model
anthropic/claude-sonnet-4-5 Anthropic Sonnet 4.5 (200k ctx)
anthropic/claude-opus-4-5 Anthropic Opus 4.5 (200k ctx)
openai/gpt-4-turbo OpenAI GPT-4 Turbo
deepseek/DeepSeek-V3 DeepSeek V3
(Keep current selection)Recomendaciones:
- Se recomienda usar Claude Sonnet 4.5 u Opus 4.5 (200k contexto, mayor seguridad)
- Si el presupuesto es limitado, puedes seleccionar la versión Mini
- Haz clic en
Keep current selectionpara conservar la configuración existente
Paso 9: Configurar Canales de Comunicación
El asistente listará todos los plugins de canales de comunicación disponibles:
? Select channels to enable
✓ whatsapp WhatsApp (Baileys Web Client)
✓ telegram Telegram (Bot Token)
✓ slack Slack (Bot Token + App Token)
✓ discord Discord (Bot Token)
✓ googlechat Google Chat (OAuth)
(Press Space to select, Enter to confirm)Acción:
- Usa las teclas de dirección para navegar
- Presiona Barra espaciadora para alternar la selección
- Presiona Enter para confirmar la selección
Optimización Modo QuickStart
En modo QuickStart, el asistente seleccionará automáticamente canales que soportan activación rápida (como WebChat), y omitirá la configuración de política DM, usando valores predeterminados seguros (modo pairing).
Después de seleccionar los canales, el asistente preguntará sobre la configuración de cada canal individualmente:
Configuración de WhatsApp
? Configure WhatsApp
Link new account Open QR code in browser
SkipAcción:
- Selecciona
Link new account - El asistente mostrará un código QR
- Usa WhatsApp para escanear el código QR e iniciar sesión
- Después de iniciar sesión exitosamente, los datos de sesión se guardan en
~/.clawdbot/credentials/
Configuración de Telegram
? Configure Telegram
Bot Token
SkipAcción:
- Selecciona
Bot Token - Introduce el Bot Token obtenido de @BotFather
- El asistente probará si la conexión es exitosa
Obtención de Bot Token
- Busca @BotFather en Telegram
- Envía
/newbotpara crear un nuevo bot - Sigue las instrucciones para configurar el nombre y nombre de usuario del bot
- Copia el Bot Token generado
Configuración de Slack
? Configure Slack
App Token xapp-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Bot Token xoxb-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Signing Secret a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
SkipExplicación: Slack requiere tres credenciales, obtenidas de la configuración de Slack App:
- App Token: Token a nivel de Workspace
- Bot Token: Bot user OAuth token
- Signing Secret: Usado para verificar la firma de las solicitudes
Creación de Slack App
- Visita https://api.slack.com/apps
- Crea una nueva App
- En la página Basic Information obtén el Signing Secret
- En la página OAuth & Permissions instala la App en el Workspace
- Obtén el Bot Token y App Token
Paso 10: Configurar Habilidades (opcional)
El asistente preguntará si deseas instalar habilidades:
? Install skills? (Y/n)Recomendación:
- Selecciona
Ypara instalar habilidades recomendadas (como el gestor de paquetes bird, TTS local sherpa-onnx-tts) - Selecciona
npara omitir, posteriormente puedes gestionar mediante el comandoclawdbot skills
Si seleccionas instalar, el asistente listará las habilidades disponibles:
? Select skills to install
✓ bird Instalación de paquetes macOS Homebrew
✓ sherpa-onnx-tts Motor TTS local (privacidad primero)
(Press Space to select, Enter to confirm)Paso 11: Completar Configuración
El asistente resumirá todas las configuraciones y escribirá el archivo de configuración:
✓ Writing config to ~/.clawdbot/clawdbot.json
✓ Workspace initialized at ~/clawd
✓ Channels configured: whatsapp, telegram, slack
✓ Skills installed: bird, sherpa-onnx-tts
────────────────────────────────────────────────────
Configuration complete!
Next steps:
1. Start Gateway:
clawdbot gateway --daemon
2. Test connection:
clawdbot message send --to +1234567890 --message "Hello!"
3. Manage configuration:
clawdbot configure
Docs: https://docs.clawd.bot/start/onboarding
────────────────────────────────────────────────────Punto de Control ✅
Después de completar el asistente, confirma lo siguiente:
- [ ] Archivo de configuración creado:
~/.clawdbot/clawdbot.json - [ ] Espacio de trabajo inicializado: existe el directorio
~/clawd/ - [ ] Credenciales de modelo AI guardadas: verifica
~/.clawdbot/credentials/ - [ ] Canales configurados: revisa el nodo
channelsenclawdbot.json - [ ] Habilidades instaladas (si se seleccionaron): revisa el nodo
skillsenclawdbot.json
Comandos de Verificación:
## Ver resumen de configuración
clawdbot doctor
## Ver estado de Gateway
clawdbot gateway status
## Ver canales disponibles
clawdbot channels listAdvertencias de Problemas Comunes
Error Común 1: Puerto Ocupado
Mensaje de Error:
Error: Port 18789 is already in useSolución:
- Busca el proceso que ocupa el puerto:
lsof -i :18789(macOS/Linux) onetstat -ano | findstr 18789(Windows) - Detén el proceso en conflicto o usa otro puerto
Error Común 2: Fallo en Flujo OAuth
Mensaje de Error:
Error: OAuth exchange failedPosibles Causas:
- Problemas de red que impiden acceder a los servidores de Anthropic
- Código OAuth expirado o con formato incorrecto
- Navegador bloqueado que impide abrir
Solución:
- Verifica la conexión de red
- Vuelve a ejecutar
clawdbot onboardpara reintentar OAuth - O cambia al método API Key
Error Común 3: Fallo en Configuración de Canal
Mensaje de Error:
Error: WhatsApp authentication failedPosibles Causas:
- Código QR expirado
- Cuenta restringida por WhatsApp
- Dependencias no instaladas (como signal-cli)
Solución:
- WhatsApp: vuelve a escanear el código QR
- Signal: asegúrate de que signal-cli esté instalado (consulta la documentación específica del canal)
- Bot Token: confirma que el formato del token sea correcto y no haya expirado
Error Común 4: Fallo en Configuración de Tailscale
Mensaje de Error:
Error: Tailscale binary not found in PATH or /Applications.Solución:
- Instala Tailscale: https://tailscale.com/download/mac
- Asegúrate de agregarlo al PATH o instalarlo en
/Applications - O omite la configuración de Tailscale, configúralo manualmente más tarde
Error Común 5: Error de Formato en Archivo de Configuración
Mensaje de Error:
Error: Invalid config at ~/.clawdbot/clawdbot.jsonSolución:
# Reparar configuración
clawdbot doctor
# O restablecer configuración
clawdbot onboard --mode resetResumen de Esta Lección
La configuración guiada es la forma recomendada de configurar Clawdbot, guiándote a través de todas las configuraciones necesarias mediante preguntas interactivas:
Puntos Clave:
- ✅ Soporta dos modos: QuickStart y Manual
- ✅ Advertencia de seguridad para recordar riesgos potenciales
- ✅ Detecta automáticamente configuraciones existentes, puedes conservar/modificar/restablecer
- ✅ Soporta flujo Anthropic setup-token (recomendado) y método API Key
- ✅ Soporta entorno multi-perfil CLAWDBOT_PROFILE
- ✅ Configura automáticamente canales y habilidades
- ✅ Genera valores predeterminados seguros (vinculación loopback, autenticación token)
Flujo de Trabajo Recomendado:
- Primer uso:
clawdbot onboard --install-daemon - Modificar configuración:
clawdbot configure - Solución de problemas:
clawdbot doctor - Acceso remoto: configurar Tailscale Serve/Funnel
Siguientes Pasos:
- Iniciar Gateway: Hacer que Gateway se ejecute en segundo plano
- Enviar Primer Mensaje: Comenzar conversación con el asistente de IA
- Conocer Emparejamiento DM: Control de seguridad para remitentes desconocidos
Vista Previa de la Siguiente Lección
En la siguiente lección aprenderemos Iniciar Gateway.
Aprenderás:
- Cómo iniciar el proceso daemon de Gateway
- La diferencia entre modo de desarrollo y modo de producción
- Cómo monitorear el estado de Gateway
- Uso de launchd/systemd para inicio automático
Apéndice: Referencia de Código Fuente
Haz clic para expandir y ver la ubicación del código fuente
Última actualización: 2026-01-27
| Función | Ruta del Archivo | Número de Línea |
|---|---|---|
| Flujo principal del asistente | src/wizard/onboarding.ts | 87-452 |
| Confirmación de advertencia de seguridad | src/wizard/onboarding.ts | 46-85 |
| Configuración de Gateway | src/wizard/onboarding.gateway-config.ts | 28-249 |
| Definición de interfaz del asistente | src/wizard/prompts.ts | 36-52 |
| Configuración de canales | src/commands/onboard-channels.ts | - |
| Configuración de habilidades | src/commands/onboard-skills.ts | - |
| Definición de tipos del asistente | src/wizard/onboarding.types.ts | 1-26 |
| Schema de configuración | src/config/zod-schema.ts | - |
Tipos Clave:
WizardFlow:"quickstart" | "advanced"- Tipo de modo del asistenteQuickstartGatewayDefaults: Configuración predeterminada de Gateway en modo QuickStartGatewayWizardSettings: Configuración de ajustes de GatewayWizardPrompter: Interfaz de interacción del asistente
Funciones Clave:
runOnboardingWizard(): Flujo principal del asistenteconfigureGatewayForOnboarding(): Configurar red y autenticación de GatewayrequireRiskAcknowledgement(): Mostrar y confirmar advertencia de seguridad
Valores de Configuración Predeterminados (Modo QuickStart):
- Puerto de Gateway: 18789
- Dirección de vinculación: loopback (127.0.0.1)
- Método de autenticación: token (genera automáticamente token aleatorio)
- Tailscale: off
- Espacio de trabajo:
~/clawd
Ubicación de Archivos de Configuración:
- Configuración principal:
~/.clawdbot/clawdbot.json - Credenciales OAuth:
~/.clawdbot/credentials/oauth.json - Credenciales API Key:
~/.clawdbot/credentials/ - Datos de sesión:
~/clawd/sessions.json