Preguntas frecuentes

OpenClaw es un asistente de IA personal que ejecutas en tus propios dispositivos. Responde en las superficies de mensajería que ya usas (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat y plugins de canal incluidos, como QQ Bot) y también puede hacer voz + un Canvas en vivo en plataformas compatibles. El Gateway es el plano de control siempre activo; el asistente es el producto.

OpenClaw no es "solo un wrapper de Claude". Es un plano de control local-first que te permite ejecutar un asistente capaz en tu propio hardware, accesible desde las apps de chat que ya usas, con sesiones con estado, memoria y herramientas, sin entregar el control de tus flujos de trabajo a un SaaS alojado.

Aspectos destacados:

• Tus dispositivos, tus datos: ejecuta el Gateway donde quieras (Mac, Linux, VPS) y mantén el espacio de trabajo + historial de sesiones en local.
• Canales reales, no un sandbox web: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc., más voz móvil y Canvas en plataformas compatibles.
• Independiente del modelo: usa Anthropic, OpenAI, MiniMax, OpenRouter, etc., con enrutamiento y conmutación por error por agente.
• Opción solo local: ejecuta modelos locales para que todos los datos puedan permanecer en tu dispositivo si quieres.
• Enrutamiento multiagente: agentes separados por canal, cuenta o tarea, cada uno con su propio espacio de trabajo y valores predeterminados.
• Código abierto y modificable: inspecciona, amplía y autoaloja sin quedar atado a un proveedor.

Documentación: Gateway, Canales, Multiagente, Memoria.

Buenos primeros proyectos:

• Crear un sitio web (WordPress, Shopify o un sitio estático sencillo).
• Crear el prototipo de una app móvil (esquema, pantallas, plan de API).
• Organizar archivos y carpetas (limpieza, nombres, etiquetas).
• Conectar Gmail y automatizar resúmenes o seguimientos.

Puede manejar tareas grandes, pero funciona mejor cuando las divides en fases y usas subagentes para trabajo en paralelo.

Los logros cotidianos suelen verse así:

• Informes personales: resúmenes de bandeja de entrada, calendario y noticias que te importan.
• Investigación y redacción: investigación rápida, resúmenes y primeros borradores para correos o documentos.
• Recordatorios y seguimientos: avisos y listas de verificación impulsados por Cron o Heartbeat.
• Automatización del navegador: rellenar formularios, recopilar datos y repetir tareas web.
• Coordinación entre dispositivos: envía una tarea desde tu teléfono, deja que el Gateway la ejecute en un servidor y recibe el resultado de vuelta en el chat.

Sí para investigación, calificación y redacción. Puede escanear sitios, crear listas cortas, resumir prospectos y escribir borradores de contacto o textos publicitarios.

Para campañas de contacto o anuncios, mantén a una persona en el circuito. Evita el spam, cumple las leyes locales y las políticas de las plataformas, y revisa todo antes de que se envíe. El patrón más seguro es dejar que OpenClaw redacte y tú apruebes.

Documentación: Seguridad.

OpenClaw es un asistente personal y una capa de coordinación, no un reemplazo de IDE. Usa Claude Code o Codex para el ciclo de programación directa más rápido dentro de un repo. Usa OpenClaw cuando quieras memoria duradera, acceso entre dispositivos y orquestación de herramientas.

Ventajas:

• Memoria persistente + espacio de trabajo entre sesiones
• Acceso multiplataforma (WhatsApp, Telegram, TUI, WebChat)
• Orquestación de herramientas (navegador, archivos, programación, hooks)
• Gateway siempre activo (ejecútalo en un VPS, interactúa desde cualquier lugar)
• Nodos para navegador/pantalla/cámara/exec locales

Muestra: https://openclaw.ai/showcase

Usa sobrescrituras gestionadas en lugar de editar la copia del repo. Coloca tus cambios en ~/.openclaw/skills/<name>/SKILL.md (o añade una carpeta mediante skills.load.extraDirs en ~/.openclaw/openclaw.json). La precedencia es <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → incluidas → skills.load.extraDirs, así que las sobrescrituras gestionadas siguen ganando sobre las skills incluidas sin tocar git. Si necesitas que la skill se instale globalmente pero solo sea visible para algunos agentes, mantén la copia compartida en ~/.openclaw/skills y controla la visibilidad con agents.defaults.skills y agents.list[].skills. Solo las ediciones dignas de upstream deberían vivir en el repo y salir como PR.

Sí. Añade directorios extra mediante skills.load.extraDirs en ~/.openclaw/openclaw.json (precedencia más baja). La precedencia predeterminada es <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → incluidas → skills.load.extraDirs. clawhub instala en ./skills de forma predeterminada, que OpenClaw trata como <workspace>/skills en la siguiente sesión. Si la skill solo debería ser visible para ciertos agentes, combínalo con agents.defaults.skills o agents.list[].skills.

Hoy los patrones compatibles son:

• Trabajos Cron: los trabajos aislados pueden establecer una sobrescritura de model por trabajo.
• Subagentes: enruta tareas a agentes separados con modelos predeterminados diferentes.
• Cambio bajo demanda: usa /model para cambiar el modelo de la sesión actual en cualquier momento.

Consulta Trabajos Cron, Enrutamiento multiagente y Comandos slash.

Usa subagentes para tareas largas o paralelas. Los subagentes se ejecutan en su propia sesión, devuelven un resumen y mantienen tu chat principal receptivo.

Pide a tu bot que "genere un subagente para esta tarea" o usa /subagents. Usa /status en el chat para ver qué está haciendo el Gateway ahora mismo (y si está ocupado).

Consejo sobre tokens: las tareas largas y los subagentes consumen tokens. Si el coste te preocupa, establece un modelo más barato para subagentes mediante agents.defaults.subagents.model.

Documentación: Subagentes, Tareas en segundo plano.

Usa vinculaciones de hilos. Puedes vincular un hilo de Discord a un subagente o destino de sesión para que los mensajes de seguimiento en ese hilo permanezcan en esa sesión vinculada.

Flujo básico:

• Genera con sessions_spawn usando thread: true (y opcionalmente mode: "session" para seguimiento persistente).
• O vincula manualmente con /focus <target>.
• Usa /agents para inspeccionar el estado de la vinculación.
• Usa /session idle <duration|off> y /session max-age <duration|off> para controlar el desenfoque automático.
• Usa /unfocus para desvincular el hilo.

Configuración requerida:

• Valores predeterminados globales: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Sobrescrituras de Discord: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
• Vinculación automática al generar: channels.discord.threadBindings.spawnSessions usa true de forma predeterminada; establécelo en false para desactivar generaciones de sesiones vinculadas a hilos.

Documentación: Subagentes, Discord, Referencia de configuración, Comandos slash.

Comprueba primero la ruta resuelta del solicitante:

• La entrega de subagente en modo finalización prefiere cualquier hilo vinculado o ruta de conversación cuando existe.
• Si el origen de finalización solo lleva un canal, OpenClaw recurre a la ruta almacenada de la sesión solicitante (lastChannel / lastTo / lastAccountId) para que la entrega directa aún pueda tener éxito.
• Si no existe una ruta vinculada ni una ruta almacenada utilizable, la entrega directa puede fallar y el resultado recurre a la entrega de sesión en cola en lugar de publicarse inmediatamente en el chat.
• Los destinos inválidos o obsoletos aún pueden forzar el recurso a cola o el fallo final de entrega.
• Si la última respuesta visible del asistente hijo es el token silencioso exacto NO_REPLY / no_reply, o exactamente ANNOUNCE_SKIP, OpenClaw suprime intencionadamente el anuncio en lugar de publicar progreso anterior obsoleto.
• Si el hijo agotó el tiempo después de solo llamadas a herramientas, el anuncio puede condensarlo en un breve resumen de progreso parcial en lugar de reproducir la salida sin procesar de las herramientas.

Depuración:

openclaw tasks show <runId-or-sessionKey>

Documentación: Subagentes, Tareas en segundo plano, Herramientas de sesión.

Cron se ejecuta dentro del proceso del Gateway. Si el Gateway no se está ejecutando de forma continua, los trabajos programados no se ejecutarán.

Lista de verificación:

• Confirma que Cron está habilitado (cron.enabled) y que OPENCLAW_SKIP_CRON no está configurado.
• Comprueba que el Gateway se ejecuta 24/7 (sin suspensión/reinicios).
• Verifica la configuración de zona horaria del trabajo (--tz frente a la zona horaria del host).

Depuración:

openclaw cron run <jobId>
openclaw cron runs --id <jobId> --limit 50

Documentación: Trabajos Cron, Automatización y tareas.

Revisa primero el modo de entrega:

• --no-deliver / delivery.mode: "none" significa que no se espera ningún envío de respaldo del ejecutor.
• Un destino de anuncio ausente o no válido (channel / to) significa que el ejecutor omitió la entrega saliente.
• Los fallos de autenticación del canal (unauthorized, Forbidden) significan que el ejecutor intentó entregar, pero las credenciales lo bloquearon.
• Un resultado aislado silencioso (solo NO_REPLY / no_reply) se trata como intencionalmente no entregable, así que el ejecutor también suprime la entrega de respaldo en cola.

Para trabajos Cron aislados, el agente aún puede enviar directamente con la herramienta message cuando hay una ruta de chat disponible. --announce solo controla la ruta de respaldo del ejecutor para el texto final que el agente aún no envió.

Depuración:

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

Docs: Trabajos Cron, Tareas en segundo plano.

Normalmente esa es la ruta de cambio de modelo en vivo, no una programación duplicada.

Cron aislado puede conservar una transferencia de modelo en tiempo de ejecución y reintentar cuando la ejecución activa lanza LiveSessionModelSwitchError. El reintento mantiene el proveedor/modelo cambiado, y si el cambio incluía una nueva anulación de perfil de autenticación, Cron también la conserva antes de reintentar.

Reglas de selección relacionadas:

• La anulación de modelo del hook de Gmail gana primero cuando corresponde.
• Luego model por trabajo.
• Luego cualquier anulación de modelo de sesión Cron almacenada.
• Luego la selección normal de modelo predeterminado/del agente.

El bucle de reintento está acotado. Después del intento inicial más 2 reintentos de cambio, Cron aborta en lugar de quedar en un bucle infinito.

Depuración:

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

Docs: Trabajos Cron, CLI de Cron.

Usa comandos nativos openclaw skills o coloca Skills en tu espacio de trabajo. La interfaz de Skills de macOS no está disponible en Linux. Explora Skills en https://clawhub.ai.

openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install <skill-slug>
openclaw skills install <skill-slug> --version <version>
openclaw skills install <skill-slug> --force
openclaw skills update --all
openclaw skills list --eligible
openclaw skills check

openclaw skills install nativo escribe en el directorio skills/ del espacio de trabajo activo. Instala la CLI clawhub separada solo si quieres publicar o sincronizar tus propias Skills. Para instalaciones compartidas entre agentes, coloca la Skill bajo ~/.openclaw/skills y usa agents.defaults.skills o agents.list[].skills si quieres limitar qué agentes pueden verla.

Sí. Usa el programador de Gateway:

• Trabajos Cron para tareas programadas o recurrentes (persisten entre reinicios).
• Heartbeat para comprobaciones periódicas de la "sesión principal".
• Trabajos aislados para agentes autónomos que publican resúmenes o entregan a chats.

Docs: Trabajos Cron, Automatización y tareas, Heartbeat.

No directamente. Las Skills de macOS están controladas por metadata.openclaw.os más los binarios requeridos, y las Skills solo aparecen en el prompt del sistema cuando son elegibles en el host del Gateway. En Linux, las Skills solo para darwin (como apple-notes, apple-reminders, things-mac) no se cargarán a menos que anules esa restricción.

Tienes tres patrones compatibles:

Opción A - ejecuta el Gateway en una Mac (lo más simple). Ejecuta el Gateway donde existan los binarios de macOS y luego conéctate desde Linux en modo remoto o mediante Tailscale. Las Skills se cargan normalmente porque el host del Gateway es macOS.

Opción B - usa un nodo macOS (sin SSH). Ejecuta el Gateway en Linux, empareja un nodo macOS (app de la barra de menús) y configura Comandos de ejecución de Node como "Preguntar siempre" o "Permitir siempre" en la Mac. OpenClaw puede tratar las Skills exclusivas de macOS como elegibles cuando los binarios requeridos existen en el nodo. El agente ejecuta esas Skills mediante la herramienta nodes. Si eliges "Preguntar siempre", aprobar "Permitir siempre" en el prompt añade ese comando a la lista de permitidos.

Opción C - proxy de binarios de macOS por SSH (avanzado). Mantén el Gateway en Linux, pero haz que los binarios de CLI requeridos se resuelvan a wrappers SSH que se ejecutan en una Mac. Luego anula la Skill para permitir Linux, de modo que siga siendo elegible.

1. Crea un wrapper SSH para el binario (ejemplo: memo para Apple Notes):

   #!/usr/bin/env bash
   set -euo pipefail
   exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
   

2. Coloca el wrapper en PATH en el host Linux (por ejemplo ~/bin/memo).

3. Anula los metadatos de la Skill (espacio de trabajo o ~/.openclaw/skills) para permitir Linux:

   ---
   name: apple-notes
   description: Manage Apple Notes via the memo CLI on macOS.
   metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
   ---
   

4. Inicia una sesión nueva para que se actualice la instantánea de Skills.

No integrada hoy.

Opciones:

• Skill / Plugin personalizado: lo mejor para acceso fiable a la API (Notion/HeyGen tienen APIs).
• Automatización del navegador: funciona sin código, pero es más lenta y más frágil.

Si quieres mantener contexto por cliente (flujos de trabajo de agencia), un patrón simple es:

• Una página de Notion por cliente (contexto + preferencias + trabajo activo).
• Pide al agente que obtenga esa página al inicio de una sesión.

Si quieres una integración nativa, abre una solicitud de función o crea una Skill orientada a esas APIs.

Instalar Skills:

openclaw skills install <skill-slug>
openclaw skills update --all

Las instalaciones nativas terminan en el directorio skills/ del espacio de trabajo activo. Para Skills compartidas entre agentes, colócalas en ~/.openclaw/skills/<name>/SKILL.md. Si solo algunos agentes deberían ver una instalación compartida, configura agents.defaults.skills o agents.list[].skills. Algunas Skills esperan binarios instalados mediante Homebrew; en Linux eso significa Linuxbrew (consulta la entrada de preguntas frecuentes de Homebrew Linux arriba). Consulta Skills, Configuración de Skills y ClawHub.

Usa el perfil de navegador user integrado, que se adjunta mediante Chrome DevTools MCP:

openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot

Si quieres un nombre personalizado, crea un perfil MCP explícito:

openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser --browser-profile chrome-live tabs

Esta ruta puede usar el navegador del host local o un nodo de navegador conectado. Si el Gateway se ejecuta en otro lugar, ejecuta un host de nodo en la máquina del navegador o usa CDP remoto en su lugar.

Límites actuales de existing-session / user:

• las acciones están guiadas por referencias, no por selectores CSS
• las cargas requieren ref / inputRef y actualmente admiten un archivo a la vez
• responsebody, exportación PDF, interceptación de descargas y acciones por lotes todavía necesitan un navegador administrado o un perfil CDP sin procesar

Sí. Consulta Aislamiento. Para configuración específica de Docker (Gateway completo en Docker o imágenes de aislamiento), consulta Docker.

La imagen predeterminada prioriza la seguridad y se ejecuta como el usuario node, por lo que no incluye paquetes del sistema, Homebrew ni navegadores incluidos. Para una configuración más completa:

• Conserva /home/node con OPENCLAW_HOME_VOLUME para que las cachés sobrevivan.
• Incluye dependencias del sistema en la imagen con OPENCLAW_DOCKER_APT_PACKAGES.
• Instala navegadores Playwright mediante la CLI incluida: node /app/node_modules/playwright-core/cli.js install chromium
• Configura PLAYWRIGHT_BROWSERS_PATH y asegúrate de que la ruta se conserve.

Docs: Docker, Navegador.

Sí - si tu tráfico privado son MD y tu tráfico público son grupos.

Usa agents.defaults.sandbox.mode: "non-main" para que las sesiones de grupo/canal (claves no principales) se ejecuten en el backend de aislamiento configurado, mientras que la sesión principal de MD permanece en el host. Docker es el backend predeterminado si no eliges uno. Luego restringe qué herramientas están disponibles en sesiones aisladas mediante tools.sandbox.tools.

Guía de configuración + ejemplo de configuración: Grupos: MD personales + grupos públicos

Referencia de configuración clave: Configuración de Gateway

Configura agents.defaults.sandbox.docker.binds como ["host:path:mode"] (p. ej., "/home/user/src:/src:ro"). Los enlaces globales y por agente se fusionan; los enlaces por agente se ignoran cuando scope: "shared". Usa :ro para cualquier cosa sensible y recuerda que los enlaces eluden las paredes del sistema de archivos del aislamiento.

OpenClaw valida las fuentes de enlace contra la ruta normalizada y la ruta canónica resuelta a través del ancestro existente más profundo. Eso significa que los escapes por padre con symlink siguen fallando de forma cerrada incluso cuando el último segmento de ruta todavía no existe, y las comprobaciones de raíz permitida siguen aplicándose después de la resolución de symlinks.

Consulta Aislamiento y Aislamiento vs política de herramientas vs elevado para ver ejemplos y notas de seguridad.

La memoria de OpenClaw son simplemente archivos Markdown en el espacio de trabajo del agente:

• Notas diarias en memory/YYYY-MM-DD.md
• Notas seleccionadas de largo plazo en MEMORY.md (solo sesiones principales/privadas)

OpenClaw también ejecuta un vaciado de memoria silencioso previo a la compactación para recordar al modelo que escriba notas duraderas antes de la compactación automática. Esto solo se ejecuta cuando el espacio de trabajo es escribible (los aislamientos de solo lectura lo omiten). Consulta Memoria.

Pide al bot que escriba el dato en memoria. Las notas de largo plazo pertenecen a MEMORY.md; el contexto de corto plazo va en memory/YYYY-MM-DD.md.

Esta sigue siendo un área que estamos mejorando. Ayuda recordar al modelo que almacene recuerdos; sabrá qué hacer. Si sigue olvidando, verifica que el Gateway esté usando el mismo espacio de trabajo en cada ejecución.

Docs: Memoria, Espacio de trabajo del agente.

Los archivos de memoria viven en disco y persisten hasta que los elimines. El límite es tu almacenamiento, no el modelo. El contexto de sesión sigue limitado por la ventana de contexto del modelo, así que las conversaciones largas pueden compactarse o truncarse. Por eso existe la búsqueda en memoria: trae de vuelta al contexto solo las partes relevantes.

Docs: Memoria, Contexto.

Solo si usas embeddings de OpenAI. Codex OAuth cubre chat/completions y no concede acceso a embeddings, así que iniciar sesión con Codex (OAuth o el inicio de sesión de Codex CLI) no ayuda para la búsqueda semántica de memoria. Los embeddings de OpenAI siguen necesitando una clave de API real (OPENAI_API_KEY o models.providers.openai.apiKey).

Si no configuras un proveedor explícitamente, OpenClaw selecciona automáticamente un proveedor cuando puede resolver una clave de API (perfiles de autenticación, models.providers.*.apiKey o variables de entorno). Prefiere OpenAI si se resuelve una clave de OpenAI; si no, Gemini si se resuelve una clave de Gemini, luego Voyage y después Mistral. Si no hay ninguna clave remota disponible, la búsqueda de memoria permanece deshabilitada hasta que la configures. Si tienes una ruta de modelo local configurada y presente, OpenClaw prefiere local. Ollama es compatible cuando configuras explícitamente memorySearch.provider = "ollama".

Si prefieres mantenerte en local, configura memorySearch.provider = "local" (y opcionalmente memorySearch.fallback = "none"). Si quieres embeddings de Gemini, configura memorySearch.provider = "gemini" y proporciona GEMINI_API_KEY (o memorySearch.remote.apiKey). Admitimos modelos de embeddings de OpenAI, Gemini, Voyage, Mistral, Ollama o locales: consulta Memoria para ver los detalles de configuración.

No: el estado de OpenClaw es local, pero los servicios externos siguen viendo lo que les envías.

• Local de forma predeterminada: las sesiones, los archivos de memoria, la configuración y el espacio de trabajo viven en el host del Gateway (~/.openclaw + tu directorio de espacio de trabajo).
• Remoto por necesidad: los mensajes que envías a proveedores de modelos (Anthropic/OpenAI/etc.) van a sus API, y las plataformas de chat (WhatsApp/Telegram/Slack/etc.) almacenan datos de mensajes en sus servidores.
• Tú controlas la huella: usar modelos locales mantiene los prompts en tu máquina, pero el tráfico de canales sigue pasando por los servidores del canal.

Relacionado: Espacio de trabajo del agente, Memoria.

Todo vive bajo $OPENCLAW_STATE_DIR (predeterminado: ~/.openclaw):

Ruta heredada de un solo agente: ~/.openclaw/agent/* (migrada por openclaw doctor).

Tu espacio de trabajo (AGENTS.md, archivos de memoria, skills, etc.) es independiente y se configura mediante agents.defaults.workspace (predeterminado: ~/.openclaw/workspace).

Estos archivos viven en el espacio de trabajo del agente, no en ~/.openclaw.

• Espacio de trabajo (por agente): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, HEARTBEAT.md opcional. La raíz en minúsculas memory.md solo es entrada de reparación heredada; openclaw doctor --fix puede fusionarla en MEMORY.md cuando ambos archivos existen.
• Directorio de estado (~/.openclaw): configuración, estado de canal/proveedor, perfiles de autenticación, sesiones, registros y Skills compartidas (~/.openclaw/skills).

El espacio de trabajo predeterminado es ~/.openclaw/workspace, configurable mediante:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Si el bot "olvida" después de reiniciar, confirma que el Gateway esté usando el mismo espacio de trabajo en cada lanzamiento (y recuerda: el modo remoto usa el espacio de trabajo del host del gateway, no tu portátil local).

Consejo: si quieres un comportamiento o preferencia duraderos, pídele al bot que lo escriba en AGENTS.md o MEMORY.md en lugar de depender del historial de chat.

Consulta Espacio de trabajo del agente y Memoria.

Pon tu espacio de trabajo del agente en un repositorio git privado y haz una copia de seguridad en algún lugar privado (por ejemplo, GitHub privado). Esto captura la memoria + archivos AGENTS/SOUL/USER y te permite restaurar la "mente" del asistente más tarde.

No hagas commit de nada bajo ~/.openclaw (credenciales, sesiones, tokens o cargas de secretos cifradas). Si necesitas una restauración completa, haz una copia de seguridad tanto del espacio de trabajo como del directorio de estado por separado (consulta la pregunta de migración anterior).

Documentación: Espacio de trabajo del agente.

Consulta la guía dedicada: Desinstalar.

Sí. El espacio de trabajo es el cwd predeterminado y ancla de memoria, no un sandbox estricto. Las rutas relativas se resuelven dentro del espacio de trabajo, pero las rutas absolutas pueden acceder a otras ubicaciones del host a menos que el sandboxing esté habilitado. Si necesitas aislamiento, usa agents.defaults.sandbox o configuraciones de sandbox por agente. Si quieres que un repositorio sea el directorio de trabajo predeterminado, apunta el workspace de ese agente a la raíz del repositorio. El repositorio de OpenClaw es solo código fuente; mantén el espacio de trabajo separado salvo que quieras intencionadamente que el agente trabaje dentro de él.

Ejemplo (repositorio como cwd predeterminado):

{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}

El estado de sesión pertenece al host del gateway. Si estás en modo remoto, el almacén de sesiones que te importa está en la máquina remota, no en tu portátil local. Consulta Gestión de sesiones.

OpenClaw lee una configuración JSON5 opcional desde $OPENCLAW_CONFIG_PATH (predeterminado: ~/.openclaw/openclaw.json):

$OPENCLAW_CONFIG_PATH

Si falta el archivo, usa valores predeterminados razonablemente seguros (incluido un espacio de trabajo predeterminado de ~/.openclaw/workspace).

Los enlaces que no son loopback requieren una ruta de autenticación de gateway válida. En la práctica, eso significa:

• autenticación con secreto compartido: token o contraseña
• gateway.auth.mode: "trusted-proxy" detrás de un proxy inverso consciente de identidad configurado correctamente

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}

Notas:

• gateway.remote.token / .password no habilitan por sí solos la autenticación del gateway local.
• Las rutas de llamadas locales pueden usar gateway.remote.* como respaldo solo cuando gateway.auth.* no está configurado.
• Para autenticación con contraseña, configura gateway.auth.mode: "password" más gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD) en su lugar.
• Si gateway.auth.token / gateway.auth.password está configurado explícitamente mediante SecretRef y no se resuelve, la resolución falla cerrada (sin enmascaramiento por respaldo remoto).
• Las configuraciones de Control UI con secreto compartido se autentican mediante connect.params.auth.token o connect.params.auth.password (almacenado en la configuración de la app/UI). Los modos con identidad, como Tailscale Serve o trusted-proxy, usan encabezados de solicitud en su lugar. Evita poner secretos compartidos en URLs.
• Con gateway.auth.mode: "trusted-proxy", los proxies inversos de loopback en el mismo host requieren gateway.auth.trustedProxy.allowLoopback = true explícito y una entrada de loopback en gateway.trustedProxies.

OpenClaw aplica autenticación del gateway de forma predeterminada, incluido loopback. En la ruta predeterminada normal, eso significa autenticación por token: si no se configura una ruta de autenticación explícita, el inicio del gateway se resuelve en modo token y genera un token solo en tiempo de ejecución para ese inicio, así que los clientes WS locales deben autenticarse. Configura gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN o OPENCLAW_GATEWAY_PASSWORD explícitamente cuando los clientes necesiten un secreto estable entre reinicios. Esto bloquea que otros procesos locales llamen al Gateway.

Si prefieres una ruta de autenticación diferente, puedes elegir explícitamente el modo contraseña (o, para proxies inversos conscientes de identidad, trusted-proxy). Si realmente quieres loopback abierto, configura gateway.auth.mode: "none" explícitamente en tu configuración. Doctor puede generarte un token en cualquier momento: openclaw doctor --generate-gateway-token.

El Gateway observa la configuración y admite recarga en caliente:

• gateway.reload.mode: "hybrid" (predeterminado): aplica en caliente cambios seguros, reinicia para los críticos
• hot, restart, off también son compatibles

Configura cli.banner.taglineMode en la configuración:

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• off: oculta el texto del lema, pero mantiene la línea de título/versión del banner.
• default: usa All your chats, one OpenClaw. cada vez.
• random: lemas graciosos/estacionales rotativos (comportamiento predeterminado).
• Si no quieres ningún banner, configura la variable de entorno OPENCLAW_HIDE_BANNER=1.

web_fetch funciona sin una clave de API. web_search depende del proveedor seleccionado:

• Los proveedores respaldados por API como Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity y Tavily requieren su configuración normal de clave de API.
• Ollama Web Search no requiere clave, pero usa tu host de Ollama configurado y requiere ollama signin.
• DuckDuckGo no requiere clave, pero es una integración no oficial basada en HTML.
• SearXNG no requiere clave y puede ser autohospedado; configura SEARXNG_BASE_URL o plugins.entries.searxng.config.webSearch.baseUrl.

Recomendado: ejecuta openclaw configure --section web y elige un proveedor. Alternativas de entorno:

• Brave: BRAVE_API_KEY
• Exa: EXA_API_KEY
• Firecrawl: FIRECRAWL_API_KEY
• Gemini: GEMINI_API_KEY
• Grok: XAI_API_KEY
• Kimi: KIMI_API_KEY o MOONSHOT_API_KEY
• MiniMax Search: MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY o MINIMAX_API_KEY
• Perplexity: PERPLEXITY_API_KEY o OPENROUTER_API_KEY
• SearXNG: SEARXNG_BASE_URL
• Tavily: TAVILY_API_KEY

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
    },
    tools: {
      web: {
        search: {
          enabled: true,
          provider: "brave",
          maxResults: 5,
        },
        fetch: {
          enabled: true,
          provider: "firecrawl", // optional; omit for auto-detect
        },
      },
    },
}

La configuración de búsqueda web específica del proveedor ahora vive en plugins.entries.<plugin>.config.webSearch.*. Las rutas de proveedor heredadas tools.web.search.* todavía se cargan temporalmente por compatibilidad, pero no deben usarse para configuraciones nuevas. La configuración de reserva de obtención web de Firecrawl vive en plugins.entries.firecrawl.config.webFetch.*.

Notas:

• Si usas listas de permitidos, agrega web_search/web_fetch/x_search o group:web.
• web_fetch está habilitado de forma predeterminada (a menos que se deshabilite explícitamente).
• Si se omite tools.web.fetch.provider, OpenClaw detecta automáticamente el primer proveedor de reserva de obtención listo a partir de las credenciales disponibles. Actualmente el proveedor incluido es Firecrawl.
• Los demonios leen variables de entorno desde ~/.openclaw/.env (o desde el entorno del servicio).

Documentación: Herramientas web.

config.apply reemplaza la configuración completa. Si envías un objeto parcial, todo lo demás se elimina.

La versión actual de OpenClaw protege contra muchas sobrescrituras accidentales:

• Las escrituras de configuración propiedad de OpenClaw validan toda la configuración posterior al cambio antes de escribir.
• Las escrituras inválidas o destructivas propiedad de OpenClaw se rechazan y se guardan como openclaw.json.rejected.*.
• Si una edición directa rompe el arranque o la recarga en caliente, Gateway falla cerrado u omite la recarga; no reescribe openclaw.json.
• openclaw doctor --fix se encarga de la reparación y puede restaurar el último estado correcto conocido mientras guarda el archivo rechazado como openclaw.json.clobbered.*.

Recuperación:

• Revisa openclaw logs --follow en busca de Invalid config at, Config write rejected: o config reload skipped (invalid config).
• Inspecciona el openclaw.json.clobbered.* o openclaw.json.rejected.* más reciente junto a la configuración activa.
• Ejecuta openclaw config validate y openclaw doctor --fix.
• Copia de vuelta solo las claves previstas con openclaw config set o config.patch.
• Si no tienes un último estado correcto conocido ni una carga útil rechazada, restaura desde una copia de seguridad, o vuelve a ejecutar openclaw doctor y reconfigura canales/modelos.
• Si esto fue inesperado, reporta un error e incluye tu última configuración conocida o cualquier copia de seguridad.
• Un agente de codificación local a menudo puede reconstruir una configuración funcional a partir de registros o historial.

Evítalo:

• Usa openclaw config set para cambios pequeños.
• Usa openclaw configure para ediciones interactivas.
• Usa primero config.schema.lookup cuando no estés seguro de una ruta exacta o de la forma de un campo; devuelve un nodo de esquema superficial más resúmenes de hijos inmediatos para profundizar.
• Usa config.patch para ediciones RPC parciales; reserva config.apply solo para reemplazo de configuración completa.
• Si usas la herramienta gateway solo para propietarios desde una ejecución de agente, seguirá rechazando escrituras en tools.exec.ask / tools.exec.security (incluidos los alias heredados tools.bash.* que se normalizan a las mismas rutas exec protegidas).

Documentación: Configuración, Configurar, Solución de problemas de Gateway, Doctor.

El patrón común es un Gateway (por ejemplo, Raspberry Pi) más Nodes y agentes:

• Gateway (central): administra canales (Signal/WhatsApp), enrutamiento y sesiones.
• Nodes (dispositivos): Macs/iOS/Android se conectan como periféricos y exponen herramientas locales (system.run, canvas, camera).
• Agentes (trabajadores): cerebros/espacios de trabajo separados para roles especiales (por ejemplo, "operaciones de Hetzner", "Datos personales").
• Subagentes: generan trabajo en segundo plano desde un agente principal cuando quieres paralelismo.
• TUI: se conecta al Gateway y cambia de agentes/sesiones.

Documentación: Nodes, Acceso remoto, Enrutamiento multiagente, Subagentes, TUI.

Sí. Es una opción de configuración:

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}

El valor predeterminado es false (con interfaz). El modo sin interfaz tiene más probabilidades de activar comprobaciones antibot en algunos sitios. Consulta Navegador.

El modo sin interfaz usa el mismo motor Chromium y funciona para la mayoría de la automatización (formularios, clics, extracción, inicios de sesión). Las diferencias principales:

• No hay ventana de navegador visible (usa capturas de pantalla si necesitas elementos visuales).
• Algunos sitios son más estrictos con la automatización en modo sin interfaz (CAPTCHA, antibot). Por ejemplo, X/Twitter suele bloquear sesiones sin interfaz.

Configura browser.executablePath con tu binario de Brave (o cualquier navegador basado en Chromium) y reinicia el Gateway. Consulta los ejemplos de configuración completos en Navegador.

Los mensajes de Telegram los gestiona el gateway. El gateway ejecuta el agente y solo después llama a los Nodes mediante el Gateway WebSocket cuando se necesita una herramienta de Node:

Telegram → Gateway → Agente → node.* → Node → Gateway → Telegram

Los Nodes no ven tráfico entrante del proveedor; solo reciben llamadas RPC de Node.

Respuesta breve: empareja tu computadora como un Node. El Gateway se ejecuta en otro lugar, pero puede llamar a herramientas node.* (pantalla, cámara, sistema) en tu máquina local mediante el Gateway WebSocket.

Configuración típica:

1. Ejecuta el Gateway en el host siempre encendido (VPS/servidor doméstico).

2. Pon el host del Gateway y tu computadora en la misma tailnet.

3. Asegúrate de que el WS del Gateway sea accesible (enlace de tailnet o túnel SSH).

4. Abre la app de macOS localmente y conéctate en modo Remoto mediante SSH (o tailnet directa) para que pueda registrarse como Node.

5. Aprueba el Node en el Gateway:

   openclaw devices list
   openclaw devices approve <requestId>
   

No se requiere un puente TCP separado; los Nodes se conectan mediante el Gateway WebSocket.

Recordatorio de seguridad: emparejar un Node de macOS permite system.run en esa máquina. Empareja solo dispositivos en los que confíes y revisa Seguridad.

Documentación: Nodes, Protocolo de Gateway, Modo remoto de macOS, Seguridad.

Comprueba lo básico:

• El Gateway está ejecutándose: openclaw gateway status
• Estado del Gateway: openclaw status
• Estado del canal: openclaw channels status

Luego verifica la autenticación y el enrutamiento:

• Si usas Tailscale Serve, asegúrate de que gateway.auth.allowTailscale esté configurado correctamente.
• Si te conectas mediante un túnel SSH, confirma que el túnel local esté activo y apunte al puerto correcto.
• Confirma que tus listas de permitidos (DM o grupo) incluyan tu cuenta.

Documentación: Tailscale, Acceso remoto, Canales.

Sí. No hay un puente "bot a bot" integrado, pero puedes conectarlas de algunas formas fiables:

La más simple: usa un canal de chat normal al que ambos bots puedan acceder (Telegram/Slack/WhatsApp). Haz que el Bot A envíe un mensaje al Bot B y luego deja que el Bot B responda como de costumbre.

Puente CLI (genérico): ejecuta un script que llame al otro Gateway con openclaw agent --message ... --deliver, apuntando a un chat donde escuche el otro bot. Si un bot está en un VPS remoto, apunta tu CLI a ese Gateway remoto mediante SSH/Tailscale (consulta Acceso remoto).

Patrón de ejemplo (ejecutado desde una máquina que pueda llegar al Gateway de destino):

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

Consejo: agrega una medida de seguridad para que los dos bots no entren en bucle interminablemente (solo menciones, listas de permitidos de canales, o una regla de "no responder a mensajes de bots").

Documentación: Acceso remoto, CLI de agente, Envío de agente.

No. Un Gateway puede alojar múltiples agentes, cada uno con su propio espacio de trabajo, valores predeterminados de modelo y enrutamiento. Esa es la configuración normal y es mucho más barata y simple que ejecutar un VPS por agente.

Usa VPS separados solo cuando necesites aislamiento estricto (límites de seguridad) o configuraciones muy distintas que no quieras compartir. De lo contrario, mantén un Gateway y usa múltiples agentes o subagentes.

Sí: los Nodes son la forma principal de llegar a tu portátil desde un Gateway remoto y desbloquean más que acceso de shell. El Gateway se ejecuta en macOS/Linux (Windows mediante WSL2) y es ligero (un VPS pequeño o una máquina de clase Raspberry Pi está bien; 4 GB de RAM son suficientes), así que una configuración común es un host siempre encendido más tu portátil como Node.

• No se requiere SSH entrante. Los Nodes se conectan hacia el Gateway WebSocket y usan emparejamiento de dispositivos.
• Controles de ejecución más seguros. system.run está protegido por listas de permitidos/aprobaciones de Node en ese portátil.
• Más herramientas de dispositivo. Los Nodes exponen canvas, camera y screen además de system.run.
• Automatización de navegador local. Mantén el Gateway en un VPS, pero ejecuta Chrome localmente mediante un host de Node en el portátil, o adjunta Chrome local en el host mediante Chrome MCP.

SSH está bien para acceso de shell ad hoc, pero los Nodes son más simples para flujos de trabajo continuos de agentes y automatización de dispositivos.

Documentación: Nodes, CLI de Nodes, Navegador.

No. Solo debe ejecutarse un gateway por host, a menos que ejecutes intencionalmente perfiles aislados (consulta Múltiples gateways). Los Nodes son periféricos que se conectan al gateway (Nodes de iOS/Android, o "modo Node" de macOS en la app de la barra de menú). Para hosts de Node sin interfaz y control CLI, consulta CLI de host de Node.

Se requiere un reinicio completo para cambios en la superficie de gateway, discovery y Plugin alojado.

Sí.

• config.schema.lookup: inspecciona un subárbol de configuración con su nodo de esquema superficial, la sugerencia de UI coincidente y resúmenes inmediatos de hijos antes de escribir
• config.get: obtiene la instantánea actual + hash
• config.patch: actualización parcial segura (preferida para la mayoría de las ediciones RPC); recarga en caliente cuando es posible y reinicia cuando es necesario
• config.apply: valida + reemplaza la configuración completa; recarga en caliente cuando es posible y reinicia cuando es necesario
• La herramienta de runtime gateway, solo para propietarios, sigue negándose a reescribir tools.exec.ask / tools.exec.security; los alias heredados tools.bash.* se normalizan a las mismas rutas de exec protegidas

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Esto configura tu workspace y restringe quién puede activar el bot.

Pasos mínimos:

1. Instalar + iniciar sesión en el VPS

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up
   

2. Instalar + iniciar sesión en tu Mac

   • Usa la app de Tailscale e inicia sesión en la misma tailnet.

3. Habilitar MagicDNS (recomendado)

   • En la consola de administración de Tailscale, habilita MagicDNS para que el VPS tenga un nombre estable.

4. Usar el nombre de host de la tailnet

   • SSH: ssh [email protected]
   • Gateway WS: ws://your-vps.tailnet-xxxx.ts.net:18789

Si quieres la UI de Control sin SSH, usa Tailscale Serve en el VPS:

openclaw gateway --tailscale serve

Esto mantiene el gateway enlazado a loopback y expone HTTPS mediante Tailscale. Consulta Tailscale.

Serve expone la UI de Control del Gateway + WS. Los Nodes se conectan mediante el mismo endpoint WS del Gateway.

Configuración recomendada:

1. Asegúrate de que el VPS + Mac estén en la misma tailnet.

2. Usa la app de macOS en modo remoto (el destino SSH puede ser el nombre de host de la tailnet). La app tunelizará el puerto del Gateway y se conectará como un Node.

3. Aprueba el Node en el gateway:

   openclaw devices list
   openclaw devices approve <requestId>
   

Docs: Protocolo del Gateway, Descubrimiento, modo remoto de macOS.

Si solo necesitas herramientas locales (pantalla/cámara/exec) en la segunda laptop, añádela como un Node. Eso mantiene un único Gateway y evita configuración duplicada. Las herramientas de Node local son actualmente solo para macOS, pero planeamos extenderlas a otros sistemas operativos.

Instala un segundo Gateway solo cuando necesites aislamiento estricto o dos bots completamente separados.

Docs: Nodes, CLI de Nodes, Múltiples gateways.

OpenClaw lee variables de entorno del proceso padre (shell, launchd/systemd, CI, etc.) y además carga:

• .env del directorio de trabajo actual
• un .env global de reserva desde ~/.openclaw/.env (también conocido como $OPENCLAW_STATE_DIR/.env)

Ningún archivo .env sobrescribe variables de entorno existentes.

También puedes definir variables de entorno inline en la configuración (se aplican solo si faltan en el entorno del proceso):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Consulta /environment para ver la precedencia y las fuentes completas.

Dos soluciones comunes:

1. Coloca las claves faltantes en ~/.openclaw/.env para que se recojan incluso cuando el servicio no herede el entorno de tu shell.
2. Habilita la importación del shell (comodidad opcional):

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Esto ejecuta tu shell de inicio de sesión e importa solo las claves esperadas que falten (nunca sobrescribe). Equivalentes de variables de entorno: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.

openclaw models status informa si la importación del entorno del shell está habilitada. "Shell env: off" no significa que falten tus variables de entorno; solo significa que OpenClaw no cargará automáticamente tu shell de inicio de sesión.

Si el Gateway se ejecuta como servicio (launchd/systemd), no heredará tu entorno de shell. Corrígelo haciendo una de estas cosas:

1. Coloca el token en ~/.openclaw/.env:

   COPILOT_GITHUB_TOKEN=...
   

2. O habilita la importación del shell (env.shellEnv.enabled: true).

3. O añádelo al bloque env de tu configuración (se aplica solo si falta).

Luego reinicia el gateway y comprueba de nuevo:

openclaw models status

Los tokens de Copilot se leen desde COPILOT_GITHUB_TOKEN (también GH_TOKEN / GITHUB_TOKEN). Consulta /concepts/model-providers y /environment.

Envía /new o /reset como mensaje independiente. Consulta Gestión de sesiones.

Las sesiones pueden caducar después de session.idleMinutes, pero esto está deshabilitado de forma predeterminada (valor predeterminado 0). Configúralo con un valor positivo para habilitar la caducidad por inactividad. Cuando está habilitada, el siguiente mensaje después del período de inactividad inicia un id de sesión nuevo para esa clave de chat. Esto no elimina las transcripciones; solo inicia una sesión nueva.

{
  session: {
    idleMinutes: 240,
  },
}

Sí, mediante enrutamiento multiagente y subagentes. Puedes crear un agente coordinador y varios agentes trabajadores con sus propios espacios de trabajo y modelos.

Dicho esto, es mejor verlo como un experimento divertido. Consume muchos tokens y a menudo es menos eficiente que usar un bot con sesiones separadas. El modelo típico que imaginamos es un bot con el que hablas, con diferentes sesiones para trabajo en paralelo. Ese bot también puede generar subagentes cuando sea necesario.

Docs: Enrutamiento multiagente, Subagentes, CLI de agentes.

El contexto de la sesión está limitado por la ventana del modelo. Los chats largos, salidas grandes de herramientas o muchos archivos pueden activar la compactación o el truncamiento.

Qué ayuda:

• Pídele al bot que resuma el estado actual y lo escriba en un archivo.
• Usa /compact antes de tareas largas y /new al cambiar de tema.
• Mantén el contexto importante en el espacio de trabajo y pídele al bot que lo vuelva a leer.
• Usa subagentes para trabajo largo o paralelo, de modo que el chat principal se mantenga más pequeño.
• Elige un modelo con una ventana de contexto más grande si esto ocurre a menudo.

Usa el comando de restablecimiento:

openclaw reset

Restablecimiento completo no interactivo:

openclaw reset --scope full --yes --non-interactive

Luego vuelve a ejecutar la configuración:

openclaw onboard --install-daemon

Notas:

• La incorporación también ofrece Restablecer si detecta una configuración existente. Consulta Incorporación (CLI).
• Si usaste perfiles (--profile / OPENCLAW_PROFILE), restablece cada directorio de estado (los valores predeterminados son ~/.openclaw-<profile>).
• Restablecimiento de desarrollo: openclaw gateway --dev --reset (solo desarrollo; borra la configuración de desarrollo + credenciales + sesiones + espacio de trabajo).

Usa una de estas opciones:

• Compactar (mantiene la conversación, pero resume los turnos anteriores):

  /compact
  

  o /compact <instructions> para orientar el resumen.

• Restablecer (ID de sesión nuevo para la misma clave de chat):

  /new
  /reset
  

Si sigue ocurriendo:

• Habilita o ajusta la poda de sesión (agents.defaults.contextPruning) para recortar salidas antiguas de herramientas.
• Usa un modelo con una ventana de contexto más grande.

Docs: Compaction, Poda de sesión, Gestión de sesiones.

Este es un error de validación del proveedor: el modelo emitió un bloque tool_use sin el input requerido. Normalmente significa que el historial de sesión está obsoleto o dañado (a menudo después de hilos largos o de un cambio de herramienta/esquema).

Corrección: inicia una sesión nueva con /new (mensaje independiente).

Los Heartbeats se ejecutan cada 30m de forma predeterminada (1h al usar autenticación OAuth). Ajústalos o desactívalos:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // or "0m" to disable
      },
    },
  },
}

Si HEARTBEAT.md existe pero está efectivamente vacío (solo líneas en blanco y encabezados Markdown como # Heading), OpenClaw omite la ejecución de Heartbeat para ahorrar llamadas a la API. Si falta el archivo, Heartbeat aún se ejecuta y el modelo decide qué hacer.

Las anulaciones por agente usan agents.list[].heartbeat. Docs: Heartbeat.

No. OpenClaw se ejecuta en tu propia cuenta, así que si estás en el grupo, OpenClaw puede verlo. De forma predeterminada, las respuestas de grupo se bloquean hasta que permites remitentes (groupPolicy: "allowlist").

Si quieres que solo tú puedas activar respuestas de grupo:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

Opción 1 (la más rápida): sigue los logs y envía un mensaje de prueba en el grupo:

openclaw logs --follow --json

Busca chatId (o from) que termine en @g.us, como: [email protected].

Opción 2 (si ya está configurado/en la lista de permitidos): lista los grupos desde la configuración:

openclaw directory groups list --channel whatsapp

Docs: WhatsApp, Directorio, Logs.

Dos causas comunes:

• El control por mención está activado (predeterminado). Debes @mencionar al bot (o coincidir con mentionPatterns).
• Configuraste channels.whatsapp.groups sin "*" y el grupo no está en la lista de permitidos.

Consulta Grupos y Mensajes de grupo.

Los chats directos se fusionan con la sesión principal de forma predeterminada. Los grupos/canales tienen sus propias claves de sesión, y los temas de Telegram / hilos de Discord son sesiones separadas. Consulta Grupos y Mensajes de grupo.

Sin límites estrictos. Decenas (incluso cientos) están bien, pero presta atención a:

• Crecimiento del disco: las sesiones + transcripciones viven en ~/.openclaw/agents/<agentId>/sessions/.
• Costo de tokens: más agentes significa más uso concurrente del modelo.
• Sobrecarga operativa: perfiles de autenticación, workspaces y enrutamiento de canales por agente.

Consejos:

• Mantén un workspace activo por agente (agents.defaults.workspace).
• Poda sesiones antiguas (elimina JSONL o entradas del almacén) si el disco crece.
• Usa openclaw doctor para detectar workspaces sueltos e incompatibilidades de perfil.

Sí. Usa Enrutamiento multiagente para ejecutar varios agentes aislados y enrutar mensajes entrantes por canal/cuenta/par. Slack es compatible como canal y puede vincularse a agentes específicos.

El acceso al navegador es potente, pero no puede "hacer cualquier cosa que pueda hacer una persona": los sistemas anti-bot, los CAPTCHAs y MFA aún pueden bloquear la automatización. Para el control del navegador más fiable, usa Chrome MCP local en el host, o usa CDP en la máquina que realmente ejecuta el navegador.

Configuración recomendada:

• Host de Gateway siempre activo (VPS/Mac mini).
• Un agente por rol (vinculaciones).
• Canal(es) de Slack vinculados a esos agentes.
• Navegador local mediante Chrome MCP o un nodo cuando sea necesario.

Documentación: Enrutamiento multiagente, Slack, Navegador, Nodos.

gateway.port controla el único puerto multiplexado para WebSocket + HTTP (Control UI, hooks, etc.).

Precedencia:

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

Porque "running" es la vista del supervisor (launchd/systemd/schtasks). La prueba de conectividad es la CLI conectándose realmente al WebSocket del Gateway.

Usa openclaw gateway status y confía en estas líneas:

• Probe target: (la URL que la prueba usó realmente)
• Listening: (lo que realmente está enlazado al puerto)
• Last gateway error: (causa raíz común cuando el proceso está vivo pero el puerto no escucha)

Estás editando un archivo de configuración mientras el servicio ejecuta otro (a menudo una incompatibilidad de --profile / OPENCLAW_STATE_DIR).

Solución:

openclaw gateway install --force

Ejecútalo desde el mismo --profile / entorno que quieres que use el servicio.

OpenClaw aplica un bloqueo de runtime enlazando el listener WebSocket inmediatamente al inicio (predeterminado ws://127.0.0.1:18789). Si el enlace falla con EADDRINUSE, lanza GatewayLockError, lo que indica que otra instancia ya está escuchando.

Solución: detén la otra instancia, libera el puerto o ejecútalo con openclaw gateway --port <port>.

Establece gateway.mode: "remote" y apunta a una URL WebSocket remota, opcionalmente con credenciales remotas de secreto compartido:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

Notas:

• openclaw gateway solo se inicia cuando gateway.mode es local (o pasas la marca de anulación).
• La app de macOS observa el archivo de configuración y cambia de modo en vivo cuando cambian estos valores.
• gateway.remote.token / .password son solo credenciales remotas del lado del cliente; no habilitan por sí mismas la autenticación del gateway local.

La ruta de autenticación de tu gateway y el método de autenticación de la UI no coinciden.

Datos (del código):

• Control UI mantiene el token en sessionStorage para la sesión actual de la pestaña del navegador y la URL de gateway seleccionada, por lo que las actualizaciones en la misma pestaña siguen funcionando sin restaurar la persistencia de tokens de larga duración en localStorage.
• En AUTH_TOKEN_MISMATCH, los clientes de confianza pueden intentar un reintento acotado con un token de dispositivo en caché cuando el gateway devuelve pistas de reintento (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
• Ese reintento con token en caché ahora reutiliza los ámbitos aprobados en caché almacenados con el token de dispositivo. Los llamadores con deviceToken explícito / scopes explícitos siguen conservando su conjunto de ámbitos solicitados en lugar de heredar ámbitos en caché.
• Fuera de esa ruta de reintento, la precedencia de autenticación de conexión es primero token/contraseña compartidos explícitos, luego deviceToken explícito, luego token de dispositivo almacenado y luego token de bootstrap.
• Las comprobaciones de ámbito del token de bootstrap tienen prefijo de rol. La allowlist de operador de bootstrap integrada solo satisface solicitudes de operador; los nodos u otros roles no operadores siguen necesitando ámbitos bajo su propio prefijo de rol.

Solución:

• Más rápido: openclaw dashboard (imprime + copia la URL del dashboard, intenta abrirla; muestra una pista de SSH si no hay pantalla).
• Si aún no tienes un token: openclaw doctor --generate-gateway-token.
• Si es remoto, crea primero un túnel: ssh -N -L 18789:127.0.0.1:18789 user@host y luego abre http://127.0.0.1:18789/.
• Modo de secreto compartido: establece gateway.auth.token / OPENCLAW_GATEWAY_TOKEN o gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, luego pega el secreto coincidente en la configuración de Control UI.
• Modo Tailscale Serve: asegúrate de que gateway.auth.allowTailscale esté habilitado y de abrir la URL de Serve, no una URL sin procesar de loopback/tailnet que omita los encabezados de identidad de Tailscale.
• Modo proxy de confianza: asegúrate de entrar mediante el proxy configurado con reconocimiento de identidad, no con una URL de gateway sin procesar. Los proxies local loopback del mismo host también necesitan gateway.auth.trustedProxy.allowLoopback = true.
• Si la incompatibilidad persiste después del único reintento, rota/vuelve a aprobar el token de dispositivo emparejado:
  • openclaw devices list
  • openclaw devices rotate --device <id> --role operator
• Si esa llamada de rotación dice que fue denegada, revisa dos cosas:
  • las sesiones de dispositivo emparejado solo pueden rotar su propio dispositivo, a menos que también tengan operator.admin
  • los valores explícitos de --scope no pueden exceder los ámbitos de operador actuales del llamador
• ¿Sigues bloqueado? Ejecuta openclaw status --all y sigue Solución de problemas. Consulta Dashboard para detalles de autenticación.

El enlace tailnet elige una IP de Tailscale de tus interfaces de red (100.64.0.0/10). Si la máquina no está en Tailscale (o la interfaz está inactiva), no hay nada a lo que enlazarse.

Solución:

• Inicia Tailscale en ese host (para que tenga una dirección 100.x), o
• Cambia a gateway.bind: "loopback" / "lan".

Nota: tailnet es explícito. auto prefiere loopback; usa gateway.bind: "tailnet" cuando quieras un enlace solo de tailnet.

Normalmente no: un Gateway puede ejecutar varios canales de mensajería y agentes. Usa varios Gateways solo cuando necesites redundancia (por ejemplo, un bot de rescate) o aislamiento estricto.

Sí, pero debes aislar:

• OPENCLAW_CONFIG_PATH (configuración por instancia)
• OPENCLAW_STATE_DIR (estado por instancia)
• agents.defaults.workspace (aislamiento de workspace)
• gateway.port (puertos únicos)

Configuración rápida (recomendada):

• Usa openclaw --profile <name> ... por instancia (crea automáticamente ~/.openclaw-<name>).
• Establece un gateway.port único en la configuración de cada perfil (o pasa --port para ejecuciones manuales).
• Instala un servicio por perfil: openclaw --profile <name> gateway install.

Los perfiles también añaden sufijos a los nombres de servicio (ai.openclaw.<profile>; heredado com.openclaw.*, openclaw-gateway-<profile>.service, OpenClaw Gateway (<profile>)). Guía completa: Varios gateways.

El Gateway es un servidor WebSocket, y espera que el primer mensaje sea un frame connect. Si recibe cualquier otra cosa, cierra la conexión con código 1008 (infracción de política).

Causas comunes:

• Abriste la URL HTTP en un navegador (http://...) en lugar de un cliente WS.
• Usaste el puerto o la ruta incorrectos.
• Un proxy o túnel eliminó encabezados de autenticación o envió una solicitud que no era del Gateway.

Soluciones rápidas:

1. Usa la URL WS: ws://<host>:18789 (o wss://... si usas HTTPS).
2. No abras el puerto WS en una pestaña normal del navegador.
3. Si la autenticación está activada, incluye el token/contraseña en el frame connect.

Si usas la CLI o TUI, la URL debería verse así:

openclaw tui --url ws://<host>:18789 --token <token>

Detalles del protocolo: Protocolo del Gateway.

Logs de archivo (estructurados):

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Puedes establecer una ruta estable mediante logging.file. El nivel de log de archivo se controla con logging.level. La verbosidad de consola se controla con --verbose y logging.consoleLevel.

Seguimiento rápido de logs:

openclaw logs --follow

Logs de servicio/supervisor (cuando el gateway se ejecuta mediante launchd/systemd):

• macOS: $OPENCLAW_STATE_DIR/logs/gateway.log y gateway.err.log (predeterminado: ~/.openclaw/logs/...; los perfiles usan ~/.openclaw-<profile>/logs/...)
• Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
• Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

Consulta Solución de problemas para más información.

Usa los ayudantes de gateway:

openclaw gateway status
openclaw gateway restart

Si ejecutas el gateway manualmente, openclaw gateway --force puede recuperar el puerto. Consulta Gateway.

Hay dos modos de instalación en Windows:

1) WSL2 (recomendado): el Gateway se ejecuta dentro de Linux.

Abre PowerShell, entra en WSL y luego reinicia:

wsl
openclaw gateway status
openclaw gateway restart

Si nunca instalaste el servicio, inícialo en primer plano:

openclaw gateway run

2) Windows nativo (no recomendado): el Gateway se ejecuta directamente en Windows.

Abre PowerShell y ejecuta:

openclaw gateway status
openclaw gateway restart

Si lo ejecutas manualmente (sin servicio), usa:

openclaw gateway run

Documentación: Windows (WSL2), Runbook del servicio Gateway.

Empieza con un barrido rápido de salud:

openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow

Causas comunes:

• Autenticación del modelo no cargada en el host del gateway (comprueba models status).
• Emparejamiento/lista de permitidos del canal bloqueando respuestas (comprueba la configuración del canal y los registros).
• WebChat/Dashboard está abierto sin el token correcto.

Si estás en remoto, confirma que la conexión del túnel/Tailscale está activa y que el WebSocket del Gateway es accesible.

Documentación: Canales, Solución de problemas, Acceso remoto.

Esto normalmente significa que la interfaz perdió la conexión WebSocket. Comprueba:

1. ¿El Gateway está en ejecución? openclaw gateway status
2. ¿El Gateway está sano? openclaw status
3. ¿La interfaz tiene el token correcto? openclaw dashboard
4. Si es remoto, ¿el enlace del túnel/Tailscale está activo?

Luego sigue los registros:

openclaw logs --follow

Documentación: Dashboard, Acceso remoto, Solución de problemas.

Empieza con los registros y el estado del canal:

openclaw channels status
openclaw channels logs --channel telegram

Luego compara el error:

• BOT_COMMANDS_TOO_MUCH: el menú de Telegram tiene demasiadas entradas. OpenClaw ya recorta hasta el límite de Telegram y vuelve a intentar con menos comandos, pero aún hay que eliminar algunas entradas del menú. Reduce comandos de plugin/skill/personalizados, o desactiva channels.telegram.commands.native si no necesitas el menú.
• TypeError: fetch failed, Network request for 'setMyCommands' failed!, o errores de red similares: si estás en un VPS o detrás de un proxy, confirma que se permite HTTPS saliente y que DNS funciona para api.telegram.org.

Si el Gateway es remoto, asegúrate de estar mirando los registros en el host del Gateway.

Documentación: Telegram, Solución de problemas de canales.

Primero confirma que el Gateway es accesible y que el agente puede ejecutarse:

openclaw status
openclaw models status
openclaw logs --follow

En la TUI, usa /status para ver el estado actual. Si esperas respuestas en un canal de chat, asegúrate de que la entrega esté activada (/deliver on).

Documentación: TUI, Comandos de barra.

Si instalaste el servicio:

openclaw gateway stop
openclaw gateway start

Esto detiene/inicia el servicio supervisado (launchd en macOS, systemd en Linux). Úsalo cuando el Gateway se ejecute en segundo plano como daemon.

Si lo estás ejecutando en primer plano, deténlo con Ctrl-C y luego:

openclaw gateway run

Documentación: Runbook del servicio Gateway.

• openclaw gateway restart: reinicia el servicio en segundo plano (launchd/systemd).
• openclaw gateway: ejecuta el gateway en primer plano para esta sesión de terminal.

Si instalaste el servicio, usa los comandos de gateway. Usa openclaw gateway cuando quieras una ejecución puntual en primer plano.

Inicia el Gateway con --verbose para obtener más detalle en la consola. Luego inspecciona el archivo de registro para ver errores de autenticación del canal, enrutamiento de modelos y RPC.

Los archivos adjuntos salientes del agente deben incluir una línea MEDIA:<path-or-url> (en su propia línea). Consulta Configuración del asistente de OpenClaw y Envío del agente.

Envío por CLI:

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

Comprueba también:

• El canal de destino admite medios salientes y no está bloqueado por listas de permitidos.
• El archivo está dentro de los límites de tamaño del proveedor (las imágenes se redimensionan a un máximo de 2048 px).
• tools.fs.workspaceOnly=true mantiene los envíos con rutas locales limitados al workspace, temp/media-store y archivos validados por sandbox.
• tools.fs.workspaceOnly=false permite que MEDIA: envíe archivos locales del host que el agente ya puede leer, pero solo para medios y tipos de documentos seguros (imágenes, audio, video, PDF y documentos de Office). Los archivos de texto plano y con apariencia de secretos siguen bloqueados.

Consulta Imágenes.

Trata los DM entrantes como entrada no confiable. Los valores predeterminados están diseñados para reducir el riesgo:

• El comportamiento predeterminado en canales con DM es emparejamiento:
  • Los remitentes desconocidos reciben un código de emparejamiento; el bot no procesa su mensaje.
  • Aprueba con: openclaw pairing approve --channel <channel> [--account <id>] <code>
  • Las solicitudes pendientes tienen un límite de 3 por canal; comprueba openclaw pairing list --channel <channel> [--account <id>] si no llegó un código.
• Abrir los DM públicamente requiere una activación explícita (dmPolicy: "open" y lista de permitidos "*").

Ejecuta openclaw doctor para mostrar políticas de DM riesgosas.

No. La inyección de prompts trata de contenido no confiable, no solo de quién puede enviar DM al bot. Si tu asistente lee contenido externo (búsqueda/obtención web, páginas de navegador, correos electrónicos, documentación, archivos adjuntos, registros pegados), ese contenido puede incluir instrucciones que intenten secuestrar el modelo. Esto puede ocurrir incluso si tú eres el único remitente.

El mayor riesgo aparece cuando las herramientas están activadas: se puede engañar al modelo para exfiltrar contexto o llamar herramientas en tu nombre. Reduce el radio de impacto mediante:

• usar un agente "lector" de solo lectura o sin herramientas para resumir contenido no confiable
• mantener web_search / web_fetch / browser desactivados para agentes con herramientas habilitadas
• tratar también el texto decodificado de archivos/documentos como no confiable: OpenResponses input_file y la extracción de archivos adjuntos de medios envuelven el texto extraído en marcadores explícitos de límite de contenido externo en vez de pasar el texto sin procesar del archivo
• sandboxing y listas de permitidos estrictas para herramientas

Detalles: Seguridad.

Sí, para la mayoría de las configuraciones. Aislar el bot con cuentas y números de teléfono separados reduce el radio de impacto si algo sale mal. Esto también facilita rotar credenciales o revocar acceso sin afectar tus cuentas personales.

Empieza pequeño. Da acceso solo a las herramientas y cuentas que realmente necesitas, y amplía más adelante si hace falta.

Documentación: Seguridad, Emparejamiento.

No recomendamos autonomía completa sobre tus mensajes personales. El patrón más seguro es:

• Mantener los DM en modo de emparejamiento o una lista de permitidos estricta.
• Usar un número o cuenta separados si quieres que envíe mensajes en tu nombre.
• Dejar que redacte y luego aprobar antes de enviar.

Si quieres experimentar, hazlo en una cuenta dedicada y mantenla aislada. Consulta Seguridad.

Sí, si el agente solo chatea y la entrada es confiable. Los niveles más pequeños son más susceptibles al secuestro de instrucciones, así que evítalos para agentes con herramientas habilitadas o cuando lean contenido no confiable. Si debes usar un modelo más pequeño, bloquea las herramientas y ejecútalo dentro de un sandbox. Consulta Seguridad.

Los códigos de emparejamiento se envían solo cuando un remitente desconocido envía un mensaje al bot y dmPolicy: "pairing" está activado. /start por sí solo no genera un código.

Comprueba solicitudes pendientes:

openclaw pairing list telegram

Si quieres acceso inmediato, añade tu id de remitente a la lista de permitidos o configura dmPolicy: "open" para esa cuenta.

No. La política de DM predeterminada de WhatsApp es emparejamiento. Los remitentes desconocidos solo reciben un código de emparejamiento y su mensaje no se procesa. OpenClaw solo responde a chats que recibe o a envíos explícitos que tú activas.

Aprueba el emparejamiento con:

openclaw pairing approve whatsapp <code>

Lista solicitudes pendientes:

openclaw pairing list whatsapp

Prompt de número de teléfono del asistente: se usa para configurar tu lista de permitidos/propietario para que tus propios DM estén permitidos. No se usa para envíos automáticos. Si lo ejecutas en tu número personal de WhatsApp, usa ese número y activa channels.whatsapp.selfChatMode.

La mayoría de los mensajes internos o de herramientas solo aparecen cuando verbose, trace o reasoning están activados para esa sesión.

Corrígelo en el chat donde lo ves:

/verbose off
/trace off
/reasoning off

Si sigue habiendo demasiado ruido, comprueba la configuración de sesión en la interfaz de control y establece verbose en heredar. Confirma también que no estás usando un perfil de bot con verboseDefault configurado como on en la configuración.

Documentación: Pensamiento y verbose, Seguridad.

Envía cualquiera de estos como mensaje independiente (sin barra):

stop
stop action
stop current action
stop run
stop current run
stop agent
stop the agent
stop openclaw
openclaw stop
stop don't do anything
stop do not do anything
stop doing anything
please stop
stop please
abort
esc
wait
exit
interrupt

Estos son disparadores de cancelación (no comandos de barra).

Para procesos en segundo plano (desde la herramienta exec), puedes pedir al agente que ejecute:

process action:kill sessionId:XXX

Resumen de comandos de barra: consulta Comandos de barra.

La mayoría de los comandos deben enviarse como un mensaje independiente que comienza con /, pero algunos atajos (como /status) también funcionan en línea para remitentes en la lista de permitidos.

OpenClaw bloquea la mensajería entre proveedores de forma predeterminada. Si una llamada de herramienta está vinculada a Telegram, no enviará a Discord a menos que lo permitas explícitamente.

Activa la mensajería entre proveedores para el agente:

{
  tools: {
    message: {
      crossContext: {
        allowAcrossProviders: true,
        marker: { enabled: true, prefix: "[from {channel}] " },
      },
    },
  },
}

Reinicia el gateway después de editar la configuración.

El modo de cola controla cómo interactúan los mensajes nuevos con una ejecución en curso. Usa /queue para cambiar de modo:

• steer - pone en cola toda la orientación pendiente para el siguiente límite del modelo en la ejecución actual
• queue - orientación heredada de una en una
• followup - ejecuta mensajes uno por uno
• collect - agrupa mensajes y responde una vez
• steer-backlog - orienta ahora y luego procesa el backlog
• interrupt - cancela la ejecución actual y empieza de nuevo

El modo predeterminado es steer. Puedes agregar opciones como debounce:0.5s cap:25 drop:summarize para modos de seguimiento. Consulta Cola de comandos y Cola de direccionamiento.

En OpenClaw, las credenciales y la selección de modelo están separadas. Configurar ANTHROPIC_API_KEY (o almacenar una clave de API de Anthropic en los perfiles de autenticación) habilita la autenticación, pero el modelo predeterminado real es el que configures en agents.defaults.model.primary (por ejemplo, anthropic/claude-sonnet-4-6 o anthropic/claude-opus-4-6). Si ves No credentials found for profile "anthropic:default", significa que el Gateway no pudo encontrar credenciales de Anthropic en el auth-profiles.json esperado para el agente que se está ejecutando.