Preguntas frecuentes

OpenClaw es un asistente personal de IA que se ejecuta en los propios dispositivos. Responde en los servicios de mensajería que ya se utilizan (Discord, Google Chat, iMessage, Mattermost, Signal, Slack, Telegram, WebChat, WhatsApp y plugins de canales incluidos, como QQ Bot), y también puede ofrecer voz y un Canvas en vivo en las plataformas compatibles. El Gateway es el plano de control siempre activo; el asistente es el producto.

OpenClaw no es «solo un envoltorio de Claude». Es un plano de control centrado en la ejecución local que ejecuta un asistente competente en el propio hardware, accesible desde las aplicaciones de chat que ya se utilizan, con sesiones con estado, memoria y herramientas, sin entregar los flujos de trabajo a un SaaS alojado.

• Los dispositivos y los datos son propios: ejecute el Gateway donde prefiera (Mac, Linux, VPS) y conserve localmente el espacio de trabajo y el historial de sesiones.
• Canales reales, no un entorno web aislado: Discord/iMessage/Signal/Slack/Telegram/WhatsApp/etc., además de voz móvil y Canvas en las plataformas compatibles.
• Independiente del modelo: utilice Anthropic, MiniMax, OpenAI, OpenRouter, etc., con enrutamiento por agente y conmutación por error.
• Opción exclusivamente local: ejecute modelos locales para que todos los datos puedan permanecer en el dispositivo.
• Enrutamiento multiagente: agentes independientes por canal, cuenta o tarea, cada uno con su propio espacio de trabajo y valores predeterminados.
• Código abierto y modificable: inspecciónelo, amplíelo y alójelo por cuenta propia sin dependencia de un proveedor.

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

Buenos primeros proyectos: crear un sitio web (WordPress, Shopify o un sitio estático); crear el prototipo de una aplicación móvil (esquema, pantallas, plan de API); organizar archivos y carpetas; conectar Gmail y automatizar resúmenes o seguimientos.

Puede gestionar tareas grandes, pero funciona mejor si se dividen en fases y se utilizan subagentes para el trabajo en paralelo.

• Informes personales: resúmenes de la bandeja de entrada, el calendario y las noticias de interés.
• Investigación y redacción: investigación rápida, resúmenes y primeros borradores de correos electrónicos o documentos.
• Recordatorios y seguimientos: avisos y listas de comprobación activados mediante Cron o Heartbeat.
• Automatización del navegador: rellenar formularios, recopilar datos y repetir tareas web.
• Coordinación entre dispositivos: envíe una tarea desde el teléfono, deje que el Gateway la ejecute en un servidor y reciba el resultado en el chat.

Sí, para la investigación, cualificación y redacción: analizar sitios, crear listas de candidatos, resumir clientes potenciales y redactar borradores de mensajes de contacto o textos publicitarios.

Para las campañas de contacto o anuncios, mantenga a una persona en el proceso. Evite el spam, cumpla las leyes locales y las políticas de las plataformas, y revise todo antes de enviarlo. Deje que OpenClaw redacte; una persona debe aprobarlo.

Documentación: Seguridad.

OpenClaw es un asistente personal y una capa de coordinación, no un sustituto del IDE. Utilice Claude Code o Codex para obtener el ciclo de programación directa más rápido dentro de un repositorio. Utilice OpenClaw para disponer de memoria persistente, acceso entre dispositivos y coordinación de herramientas.

• Memoria persistente y espacio de trabajo entre sesiones.
• Acceso multiplataforma (Telegram, WhatsApp, TUI, WebChat).
• Coordinación de herramientas (navegador, archivos, programación, hooks).
• Gateway siempre activo (ejecútelo en un VPS e interactúe desde cualquier lugar).
• Nodes para navegador/pantalla/cámara/ejecución locales.

Muestra: https://openclaw.ai/showcase.

Utilice anulaciones administradas en lugar de editar la copia del repositorio. Coloque los cambios en ~/.openclaw/skills/<name>/SKILL.md (o añada una carpeta mediante skills.load.extraDirs en ~/.openclaw/openclaw.json). Precedencia: <workspace>/skills -> <workspace>/.agents/skills -> ~/.agents/skills -> ~/.openclaw/skills -> incluidas -> skills.load.extraDirs, por lo que las anulaciones administradas tienen prioridad sobre las Skills incluidas sin modificar git. Para realizar una instalación global pero limitar la visibilidad a algunos agentes, mantenga la copia compartida en ~/.openclaw/skills y controle la visibilidad con agents.defaults.skills / agents.list[].skills. Solo las modificaciones aptas para incorporarse al proyecto original deben enviarse como PR contra la copia del repositorio.

Sí: añada directorios mediante skills.load.extraDirs en ~/.openclaw/openclaw.json (la precedencia más baja en el orden anterior). clawhub instala de forma predeterminada en ./skills, que OpenClaw trata como <workspace>/skills en la siguiente sesión. Para limitar la visibilidad a determinados agentes, combínelo con agents.defaults.skills o agents.list[].skills.

Patrones compatibles:

• Trabajos de Cron: los trabajos aislados pueden establecer una anulación de model por trabajo.
• Agentes: enrute las tareas a agentes independientes con diferentes modelos predeterminados, niveles de razonamiento y parámetros de transmisión.
• Cambio bajo demanda: /model cambia el modelo de la sesión actual en cualquier momento.

Ejemplo: el mismo modelo, con diferentes ajustes por agente:

{  agents: {    list: [      {        id: "coder",        model: "xiaomi/mimo-v2.5-pro",        thinkingDefault: "high",        params: { temperature: 0.1 },      },      {        id: "chat",        model: "xiaomi/mimo-v2.5-pro",        thinkingDefault: "off",        params: { temperature: 0.8 },      },    ],  },}

Coloque los valores predeterminados compartidos por modelo en agents.defaults.models["provider/model"].params y después las anulaciones específicas de cada agente en el agents.list[].params plano. No duplique el mismo modelo bajo el agents.list[].models["provider/model"].params anidado; esa ruta se utiliza para el catálogo de modelos y las anulaciones de ejecución por agente.

Consulte Trabajos de Cron, Enrutamiento multiagente, Configuración, Comandos con barra.

Utilice subagentes para tareas largas o paralelas: se ejecutan en su propia sesión, devuelven un resumen y mantienen el chat principal disponible. Pida al bot que «cree un subagente para esta tarea» o utilice /subagents. Utilice /status para comprobar si el Gateway está ocupado en ese momento.

Tanto las tareas largas como los subagentes consumen tokens; establezca un modelo más económico para los subagentes mediante agents.defaults.subagents.model si el coste es importante.

Documentación: Subagentes, Tareas en segundo plano.

Vincule un hilo de Discord a un subagente o destino de sesión para que los mensajes de seguimiento permanezcan en esa sesión vinculada.

• Créelo con sessions_spawn mediante thread: true (opcionalmente, mode: "session" para el seguimiento persistente).
• O vincúlelo manualmente con /focus <target>.
• /agents inspecciona el estado de vinculación.
• /session idle <duration|off> y /session max-age <duration|off> controlan la pérdida automática de foco.
• /unfocus desvincula el hilo.

Configuración: session.threadBindings.enabled (conmutador global), session.threadBindings.idleHours (24 predeterminado; 0 lo desactiva), session.threadBindings.maxAgeHours (0 predeterminado = sin límite estricto) y anulaciones por canal channels.discord.threadBindings.{enabled,idleHours,maxAgeHours}. channels.discord.threadBindings.spawnSessions controla la vinculación automática al crear el subagente (true predeterminado).

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

Compruebe la ruta resuelta del solicitante:

• La entrega del subagente en modo de finalización prefiere un hilo o una ruta de conversación vinculados cuando existen.
• Si el origen de finalización solo contiene un canal, OpenClaw recurre a la ruta almacenada de la sesión del solicitante (lastChannel / lastTo / lastAccountId) para que la entrega directa aún pueda realizarse correctamente.
• Sin una ruta vinculada ni una ruta almacenada utilizable: la entrega directa puede fallar y el resultado pasa a la entrega en cola de la sesión en lugar de publicarse inmediatamente.
• Los destinos no válidos u obsoletos también pueden forzar el uso de la cola o provocar el fallo definitivo de la entrega.
• Si la última respuesta visible del asistente secundario es exactamente NO_REPLY / no_reply o ANNOUNCE_SKIP, OpenClaw omite intencionadamente el anuncio en lugar de publicar avances anteriores obsoletos.

Depuración: openclaw tasks show <lookup>, donde <lookup> es un identificador de tarea, un identificador de ejecución o una clave de sesión.

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

Cron se ejecuta dentro del proceso del Gateway; no se activa si el Gateway no se ejecuta de forma continua.

• Confirme que cron esté habilitado (cron.enabled) y que OPENCLAW_SKIP_CRON no esté definido.
• Confirme que el Gateway se ejecute las 24 horas, todos los días (sin suspensión ni reinicios).
• Verifique la 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.

Compruebe el modo de entrega:

• --no-deliver / delivery.mode: "none": no se espera ningún envío de respaldo del ejecutor.
• Destino de anuncio ausente o no válido (channel / to): el ejecutor omitió la entrega saliente.
• Fallos de autenticación del canal (unauthorized, Forbidden): el ejecutor intentó realizar la entrega, pero las credenciales lo impidieron.
• Un resultado aislado silencioso (solo NO_REPLY / no_reply) se considera intencionadamente no entregable, por lo que también se suprime la entrega de respaldo en cola.

Para los trabajos cron aislados, el agente aún puede enviar directamente con la herramienta message cuando haya una ruta de chat disponible. --announce solo controla la entrega de respaldo del ejecutor para el texto final que el propio agente aún no haya enviado.

Depuración:

openclaw cron runs --id <jobId> --limit 50openclaw tasks show <lookup>

Documentación: Trabajos Cron, Tareas en segundo plano.

Esa es la ruta activa de cambio de modelo, no una programación duplicada. El cron aislado conserva una transferencia de modelo en tiempo de ejecución y vuelve a intentarlo cuando la ejecución activa genera LiveSessionModelSwitchError, manteniendo el proveedor/modelo cambiado (y cualquier sustitución del perfil de autenticación modificada) antes del nuevo intento.

Precedencia de selección del modelo: primero, la sustitución del modelo del hook de Gmail (hooks.gmail.model); después, el model de cada trabajo; luego, cualquier sustitución de modelo almacenada en la sesión cron; y, por último, la selección normal del modelo predeterminado o del agente.

El bucle de reintentos se limita al intento inicial más 2 reintentos de cambio; después, cron se cancela en lugar de continuar indefinidamente.

Depuración:

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

Documentación: Trabajos Cron, CLI de cron.

Utilice comandos nativos de openclaw skills o coloque Skills en el espacio de trabajo; la interfaz de Skills de macOS no está disponible en Linux. Explore Skills en https://clawhub.ai.

openclaw skills search "calendar"openclaw skills search --limit 20openclaw skills install @owner/<skill-slug>openclaw skills install @owner/<skill-slug> --version <version>openclaw skills install @owner/<skill-slug> --forceopenclaw skills install @owner/<skill-slug> --globalopenclaw skills update --allopenclaw skills update --all --globalopenclaw skills list --eligibleopenclaw skills check

De forma predeterminada, openclaw skills install nativo escribe en el directorio skills/ del espacio de trabajo activo. Añada --global para instalar en el directorio compartido de Skills administradas para todos los agentes locales. Instale la CLI independiente clawhub únicamente para publicar o sincronizar sus propias Skills. Utilice agents.defaults.skills o agents.list[].skills para limitar qué agentes pueden ver las Skills compartidas.

Sí, mediante el programador del Gateway:

• Trabajos Cron para tareas programadas o recurrentes (persisten tras los reinicios).
• Heartbeat para comprobaciones periódicas de la sesión principal.
• Trabajos aislados para agentes autónomos que publican resúmenes o realizan entregas en chats.

Documentación: Trabajos Cron, Automatización, Heartbeat.

No directamente. Las Skills de macOS están restringidas por metadata.openclaw.os y por los binarios requeridos, y solo se cargan cuando son aptas en el host del Gateway. En Linux, las Skills exclusivas de darwin (apple-notes, apple-reminders, things-mac) no se cargarán a menos que se anule la restricción.

Hay tres patrones compatibles:

Opción A: ejecutar el Gateway en un Mac (la más sencilla). Ejecute el Gateway donde existan los binarios de macOS y conéctese después desde Linux mediante el modo remoto o Tailscale. Las Skills se cargan normalmente porque el host del Gateway es macOS.

Opción B: utilizar un nodo macOS (sin SSH). Ejecute el Gateway en Linux, vincule un nodo macOS (aplicación de la barra de menús) y configure Node Run Commands como "Always Ask" o "Always Allow" en el Mac. OpenClaw considera aptas las Skills exclusivas de macOS cuando los binarios requeridos existen en el nodo; el agente las ejecuta mediante la herramienta nodes. Con "Always Ask", aprobar "Always Allow" en el aviso añade ese comando a la lista de permitidos.

Opción C: utilizar binarios de macOS mediante un proxy SSH (avanzada). Mantenga el Gateway en Linux, pero haga que los binarios de CLI requeridos se resuelvan como envoltorios SSH que se ejecuten en un Mac; después, modifique la Skill para permitir Linux y que siga siendo apta.

1. Cree un envoltorio SSH para el binario (ejemplo: memo para Apple Notes):

   #!/usr/bin/env bashset -euo pipefailexec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"

2. Coloque el envoltorio en PATH en el host Linux (por ejemplo, ~/bin/memo).
3. Modifique los metadatos de la Skill (en el espacio de trabajo o ~/.openclaw/skills) para permitir Linux:

   ---name: apple-notesdescription: Gestiona Apple Notes mediante la CLI memo en macOS.metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }---

4. Inicie una sesión nueva para actualizar la instantánea de Skills.

Actualmente no está integrada. Opciones:

• Skill o Plugin personalizado: la mejor opción para obtener acceso fiable a la API (ambos tienen API).
• Automatización del navegador: funciona sin código, pero es más lenta y frágil.

Para mantener el contexto por cliente al estilo de una agencia: conserve una página de Notion por cliente (contexto, preferencias y trabajo activo) y solicite al agente que recupere esa página al inicio de cada sesión.

Para una integración nativa, abra una solicitud de funcionalidad o cree una Skill que utilice esas API.

openclaw skills install @owner/<skill-slug>openclaw skills update --all

Las instalaciones nativas se guardan en el directorio skills/ del espacio de trabajo activo; utilice --global para todos los agentes locales o configure agents.defaults.skills / agents.list[].skills para limitar la visibilidad. Algunas Skills requieren binarios instalados mediante Homebrew; en Linux, esto implica Linuxbrew.

Consulte Skills, Configuración de Skills, ClawHub.

Utilice el perfil de navegador integrado user, que se conecta mediante Chrome DevTools MCP:

openclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot

Para utilizar un nombre personalizado, cree un perfil MCP explícito:

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

Puede utilizar el navegador del host local o un nodo de navegador conectado. Si el Gateway se ejecuta en otro lugar, ejecute un host de nodo en la máquina del navegador o utilice CDP remoto.

Limitaciones actuales de los perfiles existing-session / user frente al perfil administrado openclaw:

• click, type, hover, scrollIntoView, drag y select requieren referencias de instantáneas, no selectores CSS.
• Los hooks de carga requieren ref o inputRef, un archivo cada vez, sin element de CSS.
• responsebody, la exportación a PDF, la interceptación de descargas y las acciones por lotes aún requieren la ruta del navegador administrado.

Consulte Navegador para ver la comparación completa.

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

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

• Mantenga /home/node mediante OPENCLAW_HOME_VOLUME para que las cachés persistan.
• Incorpore las dependencias del sistema en la imagen mediante OPENCLAW_IMAGE_APT_PACKAGES.
• Instale los navegadores de Playwright mediante la CLI incluida: node /app/node_modules/playwright-core/cli.js install chromium.
• Defina PLAYWRIGHT_BROWSERS_PATH y haga que esa ruta sea persistente.

Documentación: Docker, Navegador.

Sí, si el tráfico privado corresponde a mensajes directos y el tráfico público a grupos. Configure agents.defaults.sandbox.mode: "non-main" para que las sesiones de grupo o canal (claves que no sean la principal) se ejecuten en el backend de aislamiento configurado mientras la sesión principal de mensajes directos permanece en el host. Docker es el backend predeterminado una vez habilitado el aislamiento. Restrinja mediante tools.sandbox.tools las herramientas disponibles en las sesiones aisladas.

Guía de configuración: Grupos: mensajes directos personales y grupos públicos. Referencia principal: Configuración del Gateway.

Defina agents.defaults.sandbox.docker.binds como ["host:container:mode"] (por ejemplo, "/home/user/src:/src:ro"). Las vinculaciones globales y por agente se combinan; las vinculaciones por agente se ignoran cuando scope: "shared". Utilice :ro para cualquier contenido confidencial; las vinculaciones evitan las barreras del sistema de archivos del entorno aislado.

OpenClaw valida los orígenes de las vinculaciones tanto con la ruta normalizada como con la ruta canónica resuelta mediante el antecesor existente más profundo, por lo que los escapes a través de un directorio padre que sea un enlace simbólico se rechazan de forma segura incluso si el segmento final de la ruta todavía no existe.

Consulte Aislamiento y Entorno aislado frente a política de herramientas y modo elevado.

La memoria de OpenClaw consiste en archivos Markdown en el espacio de trabajo del agente: notas diarias en memory/YYYY-MM-DD.md y notas seleccionadas a largo plazo en MEMORY.md (solo en sesiones principales o privadas).

OpenClaw también ejecuta un vaciado silencioso de memoria previo a la compactación antes de que Compaction resuma la conversación, para recordar al modelo que escriba primero las notas persistentes. Solo se ejecuta cuando se puede escribir en el espacio de trabajo (los entornos aislados de solo lectura lo omiten); deshabilítelo con agents.defaults.compaction.memoryFlush.enabled: false. Consulte Memoria.

Solicite al bot que escriba el dato en la memoria: las notas a largo plazo se guardan en MEMORY.md y el contexto a corto plazo en memory/YYYY-MM-DD.md. Recordar al modelo que almacene recuerdos suele resolver el problema. Si continúa olvidándolos, verifique que el Gateway utilice el mismo espacio de trabajo en cada ejecución.

Documentación: Memoria, Espacio de trabajo del agente.

Los archivos de memoria residen en el disco y persisten hasta que se eliminan; el límite es el almacenamiento, no el modelo. El contexto de sesión sigue estando limitado por la ventana de contexto del modelo, por lo que las conversaciones largas pueden compactarse o truncarse; por eso existe la búsqueda en memoria, que reincorpora al contexto únicamente las partes relevantes.

Documentación: Memoria, Contexto.

Solo si se usan incrustaciones de OpenAI, que es el proveedor predeterminado. OAuth de Codex cubre el chat y las finalizaciones, pero no concede acceso a las incrustaciones, por lo que iniciar sesión con Codex (mediante OAuth o el inicio de sesión de la CLI de Codex) no habilita la búsqueda semántica en memoria. Las incrustaciones de OpenAI siguen necesitando una clave de API real (OPENAI_API_KEY o models.providers.openai.apiKey).

Para mantener todo en local, establezca agents.defaults.memorySearch.provider: "local" (GGUF/llama.cpp). Otros proveedores compatibles: Bedrock, DeepInfra, Gemini (GEMINI_API_KEY o memorySearch.remote.apiKey), GitHub Copilot, LM Studio, Mistral, Ollama, compatible con OpenAI y Voyage. Consulte Memoria y Búsqueda en memoria para obtener información sobre la configuración.

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

• Local de forma predeterminada: las sesiones, los archivos de memoria, la configuración y el espacio de trabajo residen en el host del Gateway (~/.openclaw más el directorio del espacio de trabajo).
• Remoto por necesidad: los mensajes enviados a proveedores de modelos (Anthropic/OpenAI/etc.) se transmiten a sus API, y las plataformas de chat (Slack/Telegram/WhatsApp/etc.) almacenan los datos de los mensajes en sus servidores.
• Se controla el alcance: los modelos locales mantienen las instrucciones en el equipo, pero el tráfico del canal sigue pasando por los servidores del canal.

Información relacionada: Espacio de trabajo del agente, Memoria.

Todo reside en $OPENCLAW_STATE_DIR (valor predeterminado: ~/.openclaw):

La ruta heredada para un único agente ~/.openclaw/agent/* se migra mediante openclaw doctor.

El espacio de trabajo (AGENTS.md, archivos de memoria, skills, etc.) está separado y se configura mediante agents.defaults.workspace (valor predeterminado: ~/.openclaw/workspace).

Estos archivos residen 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 y HEARTBEAT.md opcional. La raíz en minúsculas memory.md solo sirve como entrada para reparaciones heredadas; openclaw doctor --fix puede combinarla con MEMORY.md cuando ambas existen.
• Directorio de estado (~/.openclaw): configuración, estado de canales/proveedores, perfiles de autenticación, sesiones, registros y skills compartidas (~/.openclaw/skills).

El espacio de trabajo predeterminado es ~/.openclaw/workspace y se puede configurar:

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

Si el bot «olvida» después de un reinicio, confirme que el Gateway usa el mismo espacio de trabajo en cada inicio (el modo remoto usa el espacio de trabajo del host del Gateway, no el del portátil local).

Consejo: para que un comportamiento o una preferencia sea duradero, pida al bot que lo escriba en AGENTS.md o MEMORY.md en lugar de depender del historial del chat.

Consulte Espacio de trabajo del agente y Memoria.

Sí. SOUL.md es uno de los archivos de arranque del espacio de trabajo que se inyectan en el contexto del agente. El límite predeterminado de inyección por archivo es de 20000 caracteres; el presupuesto total de arranque para todos los archivos es de 60000 caracteres.

Cambie los valores predeterminados compartidos:

{  agents: {    defaults: {      bootstrapMaxChars: 50000,      bootstrapTotalMaxChars: 300000,    },  },}

O sobrescriba la configuración de un agente en agents.list[].bootstrapMaxChars / bootstrapTotalMaxChars.

Use /context para comprobar los tamaños sin procesar y los inyectados, así como si se produjo un truncamiento. Mantenga SOUL.md centrado en la voz, la postura y la personalidad; coloque las reglas operativas en AGENTS.md y los datos duraderos en la memoria.

Consulte Contexto y Configuración del agente.

Coloque el espacio de trabajo del agente en un repositorio git privado y haga una copia de seguridad en una ubicación privada (por ejemplo, GitHub privado). Esto conserva la memoria junto con los archivos AGENTS/SOUL/USER y permite restaurar posteriormente la «mente» del asistente.

No confirme nada que se encuentre en ~/.openclaw (credenciales, sesiones, tokens y cargas de secretos cifrados). Para una restauración completa, haga copias de seguridad separadas del espacio de trabajo y del directorio de estado.

Documentación: Espacio de trabajo del agente.

Consulte Desinstalación.

Sí. El espacio de trabajo es el cwd predeterminado y el punto de referencia de la memoria, no un entorno aislado estricto. Las rutas relativas se resuelven dentro del espacio de trabajo; las rutas absolutas pueden acceder a otras ubicaciones del host, salvo que se haya habilitado el aislamiento. Para disponer de aislamiento, use agents.defaults.sandbox o la configuración de aislamiento por agente. Para convertir un repositorio en el directorio de trabajo predeterminado, apunte el workspace de ese agente a la raíz del repositorio; el propio repositorio de OpenClaw es solo código fuente, por lo que conviene mantener separado el espacio de trabajo, a menos que se pretenda expresamente que el agente trabaje dentro de él.

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

El estado de las sesiones pertenece al host del Gateway. En modo remoto, el almacén de sesiones relevante se encuentra en la máquina remota, no en el portátil local. Consulte Gestión de sesiones.

OpenClaw lee una configuración JSON5 opcional desde $OPENCLAW_CONFIG_PATH (valor predeterminado: ~/.openclaw/openclaw.json). Si falta el archivo, utiliza valores predeterminados relativamente seguros, incluido un espacio de trabajo predeterminado en ~/.openclaw/workspace.

Las vinculaciones que no sean de bucle invertido requieren una ruta válida de autenticación del Gateway: autenticación mediante secreto compartido (token o contraseña), o gateway.auth.mode: "trusted-proxy" detrás de un proxy inverso con reconocimiento de identidad configurado correctamente.

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

• gateway.remote.token / .password no habilitan por sí mismos la autenticación local del Gateway; las rutas de llamadas locales solo pueden usar gateway.remote.* como alternativa cuando gateway.auth.* no está establecido.
• Para la autenticación mediante contraseña, establezca gateway.auth.mode: "password" junto con gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
• Si gateway.auth.token / .password se configura explícitamente mediante SecretRef y no se resuelve, la resolución se cierra de forma segura (ninguna alternativa remota lo oculta).
• Las configuraciones de la interfaz de control con secreto compartido se autentican mediante connect.params.auth.token o connect.params.auth.password (almacenado en la configuración de la aplicación/interfaz). Los modos basados en identidad, como Tailscale Serve o trusted-proxy, usan en su lugar encabezados de solicitud; evite incluir secretos compartidos en las URL.
• Con gateway.auth.mode: "trusted-proxy", los proxies inversos de bucle invertido en el mismo host requieren gateway.auth.trustedProxy.allowLoopback = true explícito y una entrada de bucle invertido en gateway.trustedProxies.

OpenClaw exige de forma predeterminada la autenticación del Gateway, incluido el bucle invertido. Si no se configura ninguna ruta de autenticación explícita, el inicio selecciona el modo de token y genera un token válido únicamente durante ese inicio, por lo que los clientes WS locales deben autenticarse. Esto impide que otros procesos locales llamen al Gateway.

Configure explícitamente gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN o OPENCLAW_GATEWAY_PASSWORD cuando los clientes necesiten un secreto estable entre reinicios. También puede elegir el modo de contraseña o trusted-proxy para proxies inversos con reconocimiento de identidad. Para un bucle invertido abierto, establezca explícitamente gateway.auth.mode: "none". openclaw doctor --generate-gateway-token genera un token en cualquier momento.

El Gateway supervisa la configuración y admite la recarga en caliente: gateway.reload.mode: "hybrid" (valor predeterminado) aplica en caliente los cambios seguros y reinicia para los críticos. También se admiten hot, restart y off. La mayoría de los cambios de tools.*, políticas de agents.*, session.* y messages.* se aplican inmediatamente sin ninguna acción de recarga; los cambios de vinculación/puerto de gateway.* requieren un reinicio.

Establezca cli.banner.taglineMode:

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

• off: oculta el texto del eslogan, pero conserva la línea de título/versión del banner.
• default: siempre usa All your chats, one OpenClaw..
• random: eslóganes humorísticos/de temporada rotatorios (comportamiento predeterminado).
• Para no mostrar ningún banner, establezca la variable de entorno OPENCLAW_HIDE_BANNER=1.

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

Grok también puede reutilizar el OAuth de xAI de la autenticación del modelo (openclaw onboard --auth-choice xai-oauth).

Recomendado: openclaw configure --section web y elegir un proveedor.

{  plugins: {    entries: {      brave: {        config: {          webSearch: {            apiKey: "BRAVE_API_KEY_HERE",          },        },      },    },  },  tools: {    web: {      search: {        enabled: true,        provider: "brave",        maxResults: 5,      },      fetch: {        enabled: true,        provider: "firecrawl", // opcional; omitir para la detección automática      },    },  },}

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

• Listas de permitidos: añadir web_search/web_fetch/x_search, o group:web para los tres.
• web_fetch está habilitado de forma predeterminada.
• 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; el Plugin oficial de Firecrawl proporciona esa reserva.
• Los demonios leen las variables de entorno de ~/.openclaw/.env (o del entorno del servicio).

Documentación: Herramientas web.

config.apply reemplaza la configuración completa; un objeto parcial elimina todo lo demás.

La versión actual de OpenClaw protege contra la mayoría de las sobrescrituras accidentales:

• Las escrituras de configuración propiedad de OpenClaw validan toda la configuración posterior al cambio antes de escribirla.
• Las escrituras no válidas o destructivas propiedad de OpenClaw se rechazan y se guardan como openclaw.json.rejected.*.
• Una edición directa que impida el inicio o la recarga en caliente hace que el Gateway se cierre de forma segura o que omita la recarga; no reescribe openclaw.json.
• openclaw doctor --fix se encarga de la reparación, puede restaurar la última configuración válida conocida y guarda el archivo rechazado como openclaw.json.clobbered.*.

Recuperación:

• Comprobar openclaw logs --follow para buscar Invalid config at, Config write rejected: o config reload skipped (invalid config).
• Inspeccionar el openclaw.json.clobbered.* o openclaw.json.rejected.* más reciente junto a la configuración activa.
• Ejecutar openclaw config validate y openclaw doctor --fix.
• Volver a copiar únicamente las claves previstas con openclaw config set o config.patch.
• Si no existe una última configuración válida conocida ni una carga rechazada: restaurar desde una copia de seguridad, o volver a ejecutar openclaw doctor y reconfigurar los canales/modelos.
• En caso de pérdida inesperada: informar de un error e incluir la última configuración conocida o una copia de seguridad. Un agente de programación local a menudo puede reconstruir una configuración funcional a partir de los registros o el historial.

Para evitarlo: utilizar openclaw config set para cambios pequeños, openclaw configure para ediciones interactivas, config.schema.lookup para inspeccionar una ruta desconocida (devuelve un nodo de esquema superficial junto con resúmenes de sus elementos secundarios inmediatos) y config.patch para ediciones RPC parciales; reservar config.apply para reemplazar la configuración completa. La herramienta de tiempo de ejecución gateway orientada al agente se niega a reescribir tools.exec.ask / tools.exec.security, incluso mediante los alias heredados tools.bash.*.

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

Patrón habitual: un Gateway (por ejemplo, una Raspberry Pi), además de nodos y agentes.

• Gateway (central): gestiona los canales (Signal/WhatsApp), el enrutamiento y las sesiones.
• Nodos (dispositivos): los equipos Mac y dispositivos iOS/Android se conectan como periféricos y exponen herramientas locales (system.run, canvas, camera).
• Agentes (trabajadores): cerebros/espacios de trabajo independientes para funciones especiales (por ejemplo, operaciones frente a datos personales).
• Subagentes: generan trabajo en segundo plano desde un agente principal para ejecutarlo en paralelo.
• TUI: se conecta al Gateway y permite cambiar de agente o sesión.

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

Sí:

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

El valor predeterminado es false (con interfaz gráfica). El modo sin interfaz gráfica tiene más probabilidades de activar comprobaciones contra bots en algunos sitios (X/Twitter suele bloquear las sesiones sin interfaz gráfica). Utiliza el mismo motor Chromium y funciona para la mayoría de las automatizaciones; la diferencia principal es que no hay una ventana visible del navegador (utilizar capturas de pantalla para el contenido visual). Consultar Navegador.

Establecer browser.executablePath en el binario de Brave (o de cualquier navegador basado en Chromium) y reiniciar el Gateway. Consultar Navegador.

Los mensajes de Telegram son gestionados por el Gateway, que ejecuta el agente y solo entonces llama a los nodos mediante el WebSocket del Gateway cuando se necesita una herramienta de nodo:

Telegram -> Gateway -> Agente -> node.* -> Nodo -> Gateway -> Telegram

Los nodos no ven el tráfico entrante del proveedor; solo reciben llamadas RPC de nodo.

Emparejar el equipo como un nodo. El Gateway se ejecuta en otro lugar, pero puede llamar a las herramientas node.* (pantalla, cámara, sistema) del equipo local mediante el WebSocket del Gateway.

1. Ejecutar el Gateway en el host que permanece siempre encendido (VPS/servidor doméstico).
2. Colocar el host del Gateway y el equipo en la misma red de Tailscale.
3. Asegurarse de que el WebSocket del Gateway sea accesible (vinculación a la red de Tailscale o túnel SSH).
4. Abrir localmente la aplicación para macOS y conectarse en el modo Remoto mediante SSH (o directamente mediante la red de Tailscale) para que se registre como nodo.
5. Aprobar el nodo:

   openclaw devices listopenclaw devices approve <requestId>

No se requiere un puente TCP independiente; los nodos se conectan mediante el WebSocket del Gateway.

Recordatorio de seguridad: emparejar un nodo macOS permite system.run en ese equipo. Emparejar únicamente dispositivos de confianza; consultar Seguridad.

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

Comprobar los aspectos básicos:

openclaw gateway statusopenclaw statusopenclaw channels status

A continuación, verificar la autenticación y el enrutamiento: si se utiliza Tailscale Serve, confirmar que gateway.auth.allowTailscale esté configurado correctamente; si la conexión se realiza mediante un túnel SSH, confirmar que el túnel esté activo y apunte al puerto correcto; confirmar que las listas de permitidos de mensajes directos/grupos incluyan la cuenta correspondiente.

Documentación: Tailscale, Acceso remoto, Canales.

Sí, aunque no existe un puente integrado entre bots.

Opción más sencilla: utilizar un canal de chat normal al que ambos bots puedan acceder (Slack/Telegram/WhatsApp). Hacer que el Bot A envíe un mensaje al Bot B y permitir que el Bot B responda con normalidad.

Puente de CLI (genérico): ejecutar un script que llame al otro Gateway con openclaw agent --message ... --deliver, dirigido a un chat en el que escuche el otro bot. Si uno de los bots se encuentra en una VPS remota, dirigir la CLI a ese Gateway remoto mediante SSH/Tailscale (consultar Acceso remoto):

openclaw agent --message "Hola desde el bot local" --deliver --channel telegram --reply-to <chat-id>

Añadir una medida de protección para que los dos bots no entren en un bucle infinito (solo menciones, listas de canales permitidos o una regla de «no responder a mensajes de bots»).

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

No. Un Gateway aloja varios agentes, cada uno con su propio espacio de trabajo, valores predeterminados de modelo y enrutamiento; esta es la configuración habitual y resulta mucho más económica y sencilla que utilizar una VPS por agente. Utilizar VPS independientes únicamente para un aislamiento estricto (límites de seguridad) o para configuraciones muy diferentes que no se quieran compartir.

Sí: los nodos son la forma principal de acceder al portátil desde un Gateway remoto y permiten mucho más que el acceso al shell. El Gateway se ejecuta en macOS/Linux (Windows mediante WSL2) y es ligero (basta con una VPS pequeña o un equipo de la categoría de Raspberry Pi; 4 GB de RAM son suficientes), por lo que una configuración habitual consiste en un host siempre encendido y el portátil como nodo.

• No se requiere SSH entrante: los nodos establecen una conexión saliente con el WebSocket del Gateway mediante el emparejamiento de dispositivos.
• Controles de ejecución más seguros: system.run está restringido mediante listas de permitidos/aprobaciones del nodo en ese portátil.
• Más herramientas de dispositivo: además de system.run, los nodos exponen canvas, camera y screen.
• Automatización local del navegador: mantener el Gateway en una VPS, pero ejecutar Chrome localmente mediante un host de nodo, o conectarse a la instancia local de Chrome mediante Chrome MCP.

SSH resulta adecuado para el acceso puntual al shell; los nodos son más sencillos para flujos de trabajo continuos de agentes y para automatizar dispositivos.

Documentación: Nodos, CLI de nodos, Navegador.

No. Solo debe ejecutarse un Gateway por host, a menos que se ejecuten intencionadamente perfiles aislados (consultar Varios Gateways). Los nodos son periféricos que se conectan al Gateway (nodos iOS/Android o el «modo nodo» de macOS en la aplicación de la barra de menús). Para hosts de nodo sin interfaz gráfica y control mediante CLI, consultar CLI del host de nodo.

Se requiere un reinicio completo para gateway, discovery y los cambios en las superficies de Plugin alojadas.

Sí:

• config.schema.lookup: inspecciona un subárbol de configuración con su nodo de esquema superficial, la sugerencia de interfaz coincidente y los resúmenes de sus elementos secundarios inmediatos antes de escribir.
• config.get: obtiene la instantánea actual junto con el 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 y reemplaza la configuración completa; recarga en caliente cuando es posible y reinicia cuando es necesario.
• La herramienta de ejecución gateway orientada al agente sigue negándose a reescribir tools.exec.ask / tools.exec.security; los alias heredados tools.bash.* se normalizan a las mismas rutas protegidas.

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

Establece el espacio de trabajo y restringe quién puede activar el bot.

1. Instala e inicia sesión en el VPS:

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

2. Instala e inicia sesión en tu Mac mediante la aplicación Tailscale, en la misma tailnet.
3. Activa MagicDNS en la consola de administración de Tailscale para que el VPS tenga un nombre estable.
4. Usa el nombre de host de la tailnet: SSH ssh user@your-vps.tailnet-xxxx.ts.net; WS del Gateway ws://your-vps.tailnet-xxxx.ts.net:18789.

Para usar la interfaz de control sin SSH, utiliza Tailscale Serve en el VPS:

openclaw gateway --tailscale serve

Esto mantiene el Gateway vinculado a la interfaz de bucle invertido y expone HTTPS mediante Tailscale. Consulta Tailscale.

Serve expone la interfaz de control del Gateway + WS; los Nodes se conectan mediante el mismo punto de conexión WS del Gateway.

1. Asegúrate de que el VPS y el Mac estén en la misma tailnet.
2. Usa la aplicación de macOS en modo remoto (el destino SSH puede ser el nombre de host de la tailnet); esta crea un túnel para el puerto del Gateway y se conecta como Node.
3. Aprueba el Node:

   openclaw devices listopenclaw devices approve <requestId>

Documentación: Protocolo del Gateway, Detección, modo remoto de macOS.

Para usar solo herramientas locales (pantalla/cámara/ejecución) en el segundo portátil, añádelo como Node: un Gateway, sin configuración duplicada. Actualmente, las herramientas locales de Node solo están disponibles en macOS. Instala un segundo Gateway únicamente para obtener aislamiento estricto o dos bots completamente independientes.

Documentación: Nodes, CLI de Nodes, Varios Gateways.

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

• .env desde el directorio de trabajo actual.
• un respaldo global .env desde ~/.openclaw/.env ($OPENCLAW_STATE_DIR/.env).

Ninguno de los archivos .env sobrescribe las variables de entorno existentes. Las claves de credenciales de proveedores y enrutamiento de puntos de conexión son una excepción para el .env del espacio de trabajo: las claves como GEMINI_API_KEY, XAI_API_KEY, MISTRAL_API_KEY o cualquier clave que termine en _ENDPOINT (y otras variables de entorno de autenticación o puntos de conexión de proveedores incluidos) se ignoran en el .env del espacio de trabajo y deben estar en el entorno del proceso, ~/.openclaw/.env o la configuración env.

Las variables de entorno incorporadas en la configuración solo se aplican si no existen en el entorno del proceso:

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

Consulta /environment para conocer todas las fuentes y el orden de precedencia.

Hay dos soluciones:

1. Coloca las claves que faltan en ~/.openclaw/.env para que se carguen incluso cuando el servicio no herede el entorno del shell.
2. Activa la importación del shell (función opcional):

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

   Esto ejecuta el shell de inicio de sesión e importa únicamente las claves esperadas que falten (nunca las sobrescribe). Variables de entorno equivalentes: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.

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

Si el Gateway se ejecuta como servicio (launchd/systemd), no heredará el entorno del shell. Para solucionarlo, coloca el token en ~/.openclaw/.env, activa env.shellEnv.enabled: true o añádelo a la configuración env (solo se aplica si falta); después, reinicia el Gateway y vuelve a comprobarlo:

openclaw models status

Los tokens de Copilot se resuelven en este orden: OPENCLAW_GITHUB_TOKEN, después COPILOT_GITHUB_TOKEN, luego GH_TOKEN y, por último, GITHUB_TOKEN.

Consulta /concepts/model-providers y /environment.

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

Sí. La política de restablecimiento predeterminada es diaria: una sesión cambia a una nueva a una hora local configurada en el host del Gateway (session.reset.atHour, valor predeterminado 4, 0-23), según el momento en que se inició la sesión actual. Como alternativa, cambia al restablecimiento por inactividad mediante mode: "idle" y session.reset.idleMinutes, que hace caducar una sesión después de un período de inactividad (según la última interacción real, no los eventos del sistema de Heartbeat/Cron/ejecución).

{  session: {    reset: { mode: "daily", atHour: 4 },    resetByType: {      group: { mode: "idle", idleMinutes: 120 },      thread: { mode: "daily", atHour: 6 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },  },}

resetByType admite direct (alias heredado dm), group y thread. El valor heredado de nivel superior session.idleMinutes sigue funcionando como alias de compatibilidad para un valor predeterminado del modo de inactividad cuando no se ha definido ningún bloque session.reset/resetByType. Las sesiones con una sesión CLI activa propiedad del proveedor no se interrumpen por el valor predeterminado diario implícito. Consulta Gestión de sesiones para conocer el ciclo de vida completo.

Sí, mediante el enrutamiento multiagente y los subagentes: un agente coordinador y varios agentes de trabajo con sus propios espacios de trabajo y modelos.

Es mejor considerarlo un experimento entretenido: consume muchos tokens y suele ser menos eficiente que un único bot con sesiones independientes. El modelo habitual consiste en un bot con el que se interactúa, con distintas sesiones para realizar trabajo en paralelo y que crea subagentes cuando es necesario.

Documentación: Enrutamiento multiagente, Subagentes, CLI de agentes.

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

• Pide 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.
• Conserva el contexto importante en el espacio de trabajo y pide al bot que vuelva a leerlo.
• Usa subagentes para trabajos largos o en paralelo, de modo que el chat principal se mantenga más pequeño.
• Elige un modelo con una ventana de contexto mayor si esto ocurre con frecuencia.

openclaw reset

Restablecimiento completo no interactivo:

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

Después, vuelve a ejecutar la configuración:

openclaw onboard --install-daemon

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 (valor predeterminado ~/.openclaw-<profile>). Restablecimiento exclusivo para desarrollo: openclaw gateway --dev --reset elimina la configuración de desarrollo, las credenciales, las sesiones y el espacio de trabajo.

• Compactar (conserva la conversación y resume los turnos anteriores): /compact o /compact <instructions> para orientar el resumen.
• Restablecer (nuevo ID de sesión para la misma clave de chat): /new o /reset.

Si sigue ocurriendo, ajusta la depuración de sesiones (agents.defaults.contextPruning) para recortar las salidas antiguas de herramientas o usa un modelo con una ventana de contexto mayor.

Documentación: Compaction, Depuración de sesiones, Gestión de sesiones.

Error de validación del proveedor: el modelo emitió un bloque tool_use sin el campo obligatorio input. Normalmente significa que el historial de la sesión está obsoleto o dañado (a menudo después de hilos largos o de un cambio en una herramienta o esquema).

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

Los Heartbeats se ejecutan cada 30m de forma predeterminada, o cada 1h cuando el modo de autenticación resuelto es OAuth/autenticación mediante token de Anthropic (incluida la reutilización de la CLI de Claude) y heartbeat.every no está definido. Ajústalos o desactívalos:

{  agents: {    defaults: {      heartbeat: {        every: "2h", // o "0m" para desactivarlo      },    },  },}

Si existe HEARTBEAT.md pero está efectivamente vacío (solo contiene líneas en blanco, comentarios Markdown/HTML, encabezados ATX, marcadores de bloques delimitados o elementos de lista vacíos), OpenClaw omite la ejecución del Heartbeat para ahorrar llamadas a la API. Si falta el archivo, el Heartbeat se ejecuta de todos modos y el modelo decide qué hacer.

Las sustituciones por agente usan agents.list[].heartbeat. Documentación: Heartbeat.

No. OpenClaw se ejecuta en tu propia cuenta: si perteneces al grupo, OpenClaw puede verlo. De forma predeterminada, las respuestas en grupos están bloqueadas hasta que se permiten remitentes (groupPolicy: "allowlist").

Para restringir las respuestas del grupo únicamente a ti:

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

La forma más rápida es seguir los registros y enviar un mensaje de prueba al grupo.

openclaw logs --follow --json

Busca chatId (o from) que termine en @g.us, como 1234567890-1234567890@g.us.

Si ya está configurado o incluido en la lista de permitidos, enumera los grupos desde la configuración:

openclaw directory groups list --channel whatsapp

Documentación: WhatsApp, Directorio, Registros.

Dos causas habituales: la restricción por mención está activada de forma predeterminada (se debe mencionar al bot con @ o coincidir con mentionPatterns), o se configuró channels.whatsapp.groups sin "*" y el grupo no está en la lista de permitidos.

Consulte Grupos y Mensajes de grupo.

De forma predeterminada, los chats directos se agrupan en la sesión principal. Los grupos/canales tienen sus propias claves de sesión, y los temas de Telegram y los hilos de Discord son sesiones independientes. Consulte Grupos y Mensajes de grupo.

No hay límites estrictos: se pueden usar decenas o incluso cientos, pero se debe vigilar lo siguiente:

• Crecimiento del disco: las sesiones activas y las transcripciones residen en la base de datos SQLite de cada agente; los artefactos heredados o archivados aún pueden acumularse en ~/.openclaw/agents/<agentId>/sessions/.
• Coste de tokens: más agentes implican un mayor uso simultáneo de modelos.
• Carga operativa: perfiles de autenticación, espacios de trabajo y enrutamiento de canales por agente.

Mantenga un espacio de trabajo activo por agente (agents.defaults.workspace), elimine las sesiones antiguas con openclaw sessions cleanup si aumenta el uso del disco (no edite manualmente el estado activo de SQLite) y use openclaw doctor para detectar espacios de trabajo aislados e incompatibilidades entre perfiles.

Sí, mediante el enrutamiento multiagente: ejecute varios agentes aislados y enrute los mensajes entrantes por canal/cuenta/interlocutor. Slack es compatible como canal y puede vincularse a agentes específicos.

El acceso mediante navegador es potente, pero no permite «hacer cualquier cosa que pueda hacer una persona»: las medidas antibots, los CAPTCHA y la MFA aún pueden bloquear la automatización. Para lograr el control más fiable, use Chrome MCP localmente en el host o CDP en el equipo que ejecuta realmente el navegador.

Configuración recomendada: un host del Gateway siempre activo (VPS/Mac mini), un agente por función (vinculaciones), los canales de Slack vinculados a esos agentes y un navegador local mediante Chrome MCP o un Node cuando sea necesario.

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

gateway.port controla el único puerto multiplexado para WebSocket + HTTP (interfaz de control, hooks, etc.). Precedencia:

--port > OPENCLAW_GATEWAY_PORT > gateway.port > valor predeterminado 18789

«En ejecución» es la perspectiva del supervisor (launchd/systemd/schtasks); la prueba de conectividad corresponde a la CLI conectándose realmente al WebSocket del Gateway. Confíe en estas líneas de openclaw gateway status: Probe target: (la URL que usó la prueba), Listening: (lo que está realmente vinculado al puerto), Last gateway error: (causa raíz habitual cuando el proceso está activo, pero el puerto no está escuchando).

Se está editando un archivo de configuración mientras el servicio utiliza otro (a menudo, una incompatibilidad entre --profile y OPENCLAW_STATE_DIR).

Para corregirlo, ejecute lo siguiente desde el mismo --profile o entorno que deba utilizar el servicio:

openclaw gateway install --force

OpenClaw aplica un bloqueo de ejecución vinculando el listener de WebSocket inmediatamente durante el inicio (valor predeterminado: ws://127.0.0.1:18789). Si la vinculación falla con EADDRINUSE, se genera GatewayLockError («ya hay otra instancia del Gateway escuchando»).

Solución: detenga la otra instancia, libere el puerto o ejecute con openclaw gateway --port <port>.

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

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

• openclaw gateway solo se inicia cuando gateway.mode es local (o se proporciona una marca de anulación).
• La aplicación de macOS supervisa el archivo de configuración y cambia de modo en tiempo real cuando se modifican estos valores.
• gateway.remote.token / .password son únicamente credenciales remotas del lado del cliente; no habilitan por sí solas la autenticación del Gateway local.

La ruta de autenticación del Gateway y el método de autenticación de la interfaz no coinciden.

Datos (procedentes del código):

• La interfaz de control conserva el token en sessionStorage, limitado a la pestaña actual del navegador y a la URL del Gateway seleccionada, por lo que las actualizaciones en la misma pestaña siguen funcionando sin persistencia prolongada del token en localStorage.
• En AUTH_TOKEN_MISMATCH, los clientes de confianza pueden intentar un único reintento limitado con un token de dispositivo almacenado en caché cuando el Gateway devuelve indicaciones de reintento (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
• Ese reintento con el token almacenado en caché reutiliza los ámbitos aprobados almacenados con el token del dispositivo; los invocadores con deviceToken explícito o scopes explícito conservan el conjunto de ámbitos solicitado en lugar de heredar los ámbitos almacenados en caché.
• Fuera de esa ruta de reintento, la precedencia de autenticación de la conexión es: primero el token o la contraseña compartidos explícitos, después deviceToken explícito, luego el token de dispositivo almacenado y, por último, el token de arranque.
• El arranque integrado mediante código de configuración devuelve un token de dispositivo Node con scopes: [], además de un token limitado de transferencia al operador para la incorporación móvil de confianza. La transferencia al operador puede leer la configuración nativa durante la configuración, pero no concede ámbitos de modificación del emparejamiento ni operator.admin.

Solución:

• La opción más rápida: openclaw dashboard (muestra y copia la URL del panel e intenta abrirla; si no hay interfaz gráfica, muestra una sugerencia de SSH).
• Si aún no hay token: openclaw doctor --generate-gateway-token.
• En remoto: cree primero un túnel con ssh -N -L 18789:127.0.0.1:18789 user@host y después abra http://127.0.0.1:18789/.
• Modo de secreto compartido: establezca gateway.auth.token / OPENCLAW_GATEWAY_TOKEN o gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD y, a continuación, pegue el secreto correspondiente en la configuración de la interfaz de control.
• Modo Tailscale Serve: confirme que gateway.auth.allowTailscale esté habilitado y que se esté abriendo la URL de Serve, no una URL directa de bucle invertido o de la Tailnet que omita las cabeceras de identidad de Tailscale.
• Modo de proxy de confianza: confirme que la conexión se realice a través del proxy configurado con reconocimiento de identidad. Los proxies de bucle invertido del mismo host también necesitan gateway.auth.trustedProxy.allowLoopback = true.
• Si la incompatibilidad persiste después del único reintento, rote o vuelva a aprobar el token del dispositivo emparejado:

  openclaw devices listopenclaw devices rotate --device <id> --role operator

• Si se deniega la rotación: las sesiones de dispositivos emparejados solo pueden rotar su propio dispositivo, salvo que también tengan operator.admin, y los valores explícitos de --scope no pueden superar los ámbitos de operador actuales del invocador.
• Si el problema persiste: openclaw status --all y Solución de problemas. Consulte Panel para obtener información detallada sobre la autenticación.

La vinculación tailnet selecciona una IP de Tailscale de las interfaces de red (100.64.0.0/10). Si el equipo no está conectado a Tailscale (o la interfaz está inactiva), el Gateway recurre al bucle invertido en lugar de exponer otra interfaz de red.

Solución: inicie Tailscale en ese host y reinicie el Gateway, o cambie explícitamente a gateway.bind: "loopback" / "lan".

tailnet es explícito; auto da preferencia al bucle invertido. Use gateway.bind: "tailnet" para limitar la exposición fuera del bucle invertido a la Tailnet y conservar al mismo tiempo el listener obligatorio 127.0.0.1 del mismo host.

Normalmente no: un Gateway puede ejecutar varios canales de mensajería y agentes. Use varios Gateways únicamente para redundancia (por ejemplo, un bot de rescate) o aislamiento estricto, y aísle cada uno con sus propios OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, agents.defaults.workspace y un gateway.port único.

Recomendación: openclaw --profile <name> ... por instancia (crea automáticamente ~/.openclaw-<name>), un gateway.port único por configuración de perfil (o --port para ejecuciones manuales) y un servicio por perfil con openclaw --profile <name> gateway install.

Los perfiles también añaden sufijos a los nombres de los servicios: launchd ai.openclaw.<profile>, systemd openclaw-gateway-<profile>.service, Windows OpenClaw Gateway (<profile>). La unidad systemd openclaw-gateway sin calificador solo existe para el perfil predeterminado; el nombre heredado de la unidad systemd anterior al cambio de nombre, clawdbot-gateway, se migra automáticamente.

Guía completa: Varios Gateways.

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

Causas habituales: se abrió la URL HTTP en un navegador en lugar de utilizar un cliente WS, se usó un puerto o una ruta incorrectos, o un proxy/túnel eliminó las cabeceras de autenticación o envió una solicitud ajena al Gateway.

Solución: use la URL WS (ws://<host>:18789 o wss://... mediante HTTPS), no abra el puerto WS en una pestaña normal del navegador e incluya el token o la contraseña en la trama connect cuando la autenticación esté activada. Ejemplo de CLI/TUI:

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

Detalles del protocolo: Protocolo del Gateway.

Registros de archivo (estructurados): /tmp/openclaw/openclaw-YYYY-MM-DD.log. Establezca una ruta estable mediante logging.file; el nivel de registro del archivo mediante logging.level; y el nivel de detalle de la consola mediante --verbose y logging.consoleLevel.

Seguimiento más rápido:

openclaw logs --follow

Registros del servicio/supervisor (cuando el Gateway se ejecuta mediante launchd/systemd):

• Salida estándar de launchd en macOS: ~/Library/Logs/openclaw/gateway.log (los perfiles usan gateway-<profile>.log; la salida de error estándar se suprime).
• Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager.
• Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST.

Consulte Solución de problemas para obtener más información.

openclaw gateway statusopenclaw gateway restart

Si se ejecuta el Gateway manualmente, openclaw gateway --force puede recuperar el puerto. Consulte Gateway.

Hay tres modos de instalación en Windows:

1) Configuración local de Windows Hub: la aplicación nativa administra un Gateway de WSL local propiedad de la aplicación. Abra OpenClaw Companion desde el menú Inicio o la bandeja y, a continuación, use Gateway Setup o la pestaña Connections.

2) Gateway manual en WSL2: el Gateway se ejecuta dentro de Linux.

wslopenclaw gateway statusopenclaw gateway restart

Si nunca instaló el servicio, inícielo en primer plano: openclaw gateway run.

3) CLI/Gateway nativo de Windows: se ejecuta directamente en Windows.

openclaw gateway statusopenclaw gateway restart

Si lo ejecuta manualmente (sin servicio): openclaw gateway run.

Documentación: Windows, Guía operativa del servicio Gateway.

Comprobación rápida del estado:

openclaw statusopenclaw models statusopenclaw channels statusopenclaw logs --follow

Causas habituales: la autenticación del modelo no está cargada en el host del Gateway (compruebe models status), el emparejamiento o la lista de permitidos del canal bloquea las respuestas (compruebe la configuración y los registros del canal), o WebChat/Dashboard está abierto sin el token correcto. Si es remoto, confirme que la conexión del túnel/Tailscale está activa y que se puede acceder al WebSocket del Gateway.

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

Normalmente significa que la interfaz de usuario perdió la conexión WebSocket. Compruebe: ¿se está ejecutando el Gateway (openclaw gateway status)? ¿Funciona correctamente (openclaw status)? ¿Tiene la interfaz de usuario el token correcto (openclaw dashboard)? Si es remoto, ¿está activo el enlace del túnel/Tailscale?

A continuación, siga los registros:

openclaw logs --follow

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

openclaw channels statusopenclaw channels logs --channel telegram

A continuación, identifique el error:

• BOT_COMMANDS_TOO_MUCH: el menú de Telegram tiene demasiadas entradas. OpenClaw ya lo recorta hasta el límite de Telegram y vuelve a intentarlo con menos comandos, pero aun así podrían omitirse algunas entradas del menú. Reduzca los comandos de plugins, skills o personalizados, o desactive channels.telegram.commands.native si no necesita el menú.
• TypeError: fetch failed, Network request for 'setMyCommands' failed! o errores de red similares: en un VPS o detrás de un proxy, confirme que se permite HTTPS saliente y que DNS funciona para api.telegram.org.

Si el Gateway es remoto, compruebe los registros en el host del Gateway.

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

openclaw statusopenclaw models statusopenclaw logs --follow

En la TUI, use /status para ver el estado actual. Si espera respuestas en un canal de chat, confirme que la entrega esté habilitada (/deliver on).

Documentación: TUI, Comandos de barra diagonal.

Si instaló el servicio (launchd en macOS, systemd en Linux):

openclaw gateway stopopenclaw gateway start

En primer plano, deténgalo con Ctrl-C y, a continuación, ejecute openclaw gateway run.

Documentación: Guía operativa del servicio Gateway.

openclaw gateway restart reinicia el servicio en segundo plano (launchd/systemd). openclaw gateway ejecuta el Gateway en primer plano durante esta sesión de terminal. Use los subcomandos del Gateway si instaló el servicio; use la ejecución en primer plano sin subcomandos para una ejecución puntual.

Inicie el Gateway con --verbose para obtener más detalles en la consola y, a continuación, examine el archivo de registro para detectar errores de autenticación del canal, enrutamiento del modelo y RPC.

Los archivos adjuntos salientes del agente deben usar campos de medios estructurados como media, mediaUrl, path o filePath. Consulte Configuración del asistente de OpenClaw y Envío del agente.

openclaw message send --target +15555550123 --message "Aquí lo tiene" --media /path/to/file.png

Compruebe también lo siguiente: que el canal de destino admita medios salientes y no esté bloqueado por listas de permitidos; que el archivo esté dentro de los límites de tamaño del proveedor (las imágenes se redimensionan a un lado máximo de 2048px); tools.fs.workspaceOnly=true limita los envíos desde rutas locales a archivos del espacio de trabajo, del almacén temporal/de medios y validados por el entorno aislado; tools.fs.workspaceOnly=false (valor predeterminado) permite que los envíos estructurados de medios locales usen archivos locales del host que el agente ya puede leer, tanto para medios como para tipos de documentos seguros (imágenes, audio, vídeo, PDF, documentos de Office y documentos de texto validados como Markdown/MD, TXT, JSON, YAML/YML). Esto no es un escáner de secretos: se puede adjuntar un archivo secret.txt o config.json legible por el agente cuando coincidan la extensión y la validación del contenido. Mantenga los archivos confidenciales fuera de las rutas legibles por el agente o mantenga tools.fs.workspaceOnly=true para aplicar restricciones más estrictas a los envíos desde rutas locales.

Consulte Imágenes.

Trate los mensajes directos entrantes como entradas no confiables. Los valores predeterminados reducen el riesgo:

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

Ejecute openclaw doctor para detectar políticas de mensajes directos que presenten riesgos.

No. La inyección de instrucciones está relacionada con el contenido no confiable, no solo con quién puede enviar mensajes directos al bot. Si el asistente lee contenido externo (búsquedas u obtención de contenido web, páginas del navegador, correos electrónicos, documentos, archivos adjuntos o registros pegados), ese contenido puede incluir instrucciones que intenten secuestrar el modelo, incluso si usted es el único remitente.

El mayor riesgo surge cuando las herramientas están habilitadas: se puede engañar al modelo para que filtre contexto o invoque herramientas en su nombre. Reduzca el radio de impacto:

• use un agente «lector» de solo lectura o sin herramientas para resumir contenido no confiable
• mantenga web_search / web_fetch / browser desactivados para los agentes con herramientas habilitadas
• trate también como no confiable el texto decodificado de archivos o documentos: tanto input_file de OpenResponses como la extracción de archivos multimedia adjuntos encapsulan el texto extraído entre marcadores explícitos de límites de contenido externo, en lugar de transmitir directamente el texto sin procesar del archivo
• use un entorno aislado y listas estrictas de herramientas permitidas

Detalles: Seguridad.

El lenguaje y el entorno de ejecución son importantes, pero no constituyen el riesgo principal para un agente personal. Los riesgos prácticos son la exposición del Gateway, quién puede enviar mensajes al bot, la inyección de instrucciones, el alcance de las herramientas, la gestión de credenciales, el acceso al navegador, el acceso de ejecución y la confianza en skills/plugins de terceros.

Rust y WASM pueden proporcionar un aislamiento más sólido para algunas clases de código, pero no resuelven la inyección de instrucciones, las listas de permitidos deficientes, la exposición pública del Gateway, las herramientas con permisos excesivos ni un perfil del navegador que ya tenga sesiones iniciadas en cuentas confidenciales. Considere estos los controles principales: mantenga el Gateway privado o autenticado, use el emparejamiento y listas de permitidos para mensajes directos/grupos, deniegue o aísle las herramientas de riesgo para entradas no confiables, instale únicamente plugins y skills de confianza y ejecute openclaw security audit --deep después de cambiar la configuración.

Detalles: Seguridad, Aislamiento.

openclaw security audit --deepopenclaw gateway status

Una configuración de referencia más segura: el Gateway vinculado a loopback, o expuesto únicamente mediante acceso privado autenticado (tailnet, túnel SSH, autenticación por token/contraseña o un proxy de confianza correctamente configurado); mensajes directos en modo pairing o allowlist; grupos incluidos en listas de permitidos y con requisito de mención, salvo que todos sus miembros sean de confianza; herramientas de alto riesgo (exec, browser, gateway, cron) denegadas o estrictamente limitadas para los agentes que leen contenido no confiable; aislamiento habilitado cuando la ejecución de herramientas requiera un radio de impacto menor.

Las vinculaciones públicas sin autenticación, los mensajes directos o grupos abiertos con herramientas y el control expuesto del navegador son los problemas que deben corregirse primero. Detalles: openclaw security audit.

Trate las skills y los plugins de terceros como código en el que decide confiar. Las páginas de skills de ClawHub muestran el estado del análisis antes de la instalación, pero los análisis no constituyen un límite de seguridad completo. OpenClaw no ejecuta un bloqueo local integrado de código peligroso durante la instalación o actualización de plugins/skills; use security.installPolicy, bajo control del operador, para tomar decisiones locales de permiso o bloqueo.

Patrón más seguro: prefiera autores de confianza y versiones fijadas, revise la skill o el plugin antes de habilitarlo, mantenga restringidas las listas de plugins/skills permitidos, ejecute los flujos de trabajo con entradas no confiables en un entorno aislado y con herramientas mínimas, y evite conceder al código de terceros un acceso amplio al sistema de archivos, la ejecución, el navegador o los secretos.

Detalles: Skills, Plugins, Seguridad.

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

Empiece con poco: conceda acceso únicamente a las herramientas y cuentas que realmente necesite y amplíelo más adelante si fuera necesario.

Documentación: Seguridad, Emparejamiento.

No se recomienda conceder autonomía total sobre los mensajes personales. El patrón más seguro consiste en mantener los mensajes directos en modo de emparejamiento o con una lista de permitidos estricta, usar un número o una cuenta independiente si debe enviar mensajes en su nombre y permitir que redacte los mensajes mientras usted los aprueba antes de enviarlos.

Para experimentar, hágalo en una cuenta dedicada y aislada. Consulte Seguridad.

Sí, si el agente solo usa el chat y la entrada es confiable. Los niveles más pequeños son más susceptibles al secuestro de instrucciones, por lo que deben evitarse para agentes con herramientas habilitadas o al leer contenido no confiable. Si debe usar un modelo más pequeño, restrinja las herramientas y ejecútelo dentro de un entorno aislado. Consulte Seguridad.

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

Compruebe las solicitudes pendientes:

openclaw pairing list telegram

Para obtener acceso inmediato, añada el identificador del remitente a la lista de permitidos o establezca dmPolicy: "open" para esa cuenta.

No. La política predeterminada de mensajes directos de WhatsApp es el emparejamiento. Los remitentes desconocidos solo reciben un código de emparejamiento; su mensaje no se procesa. OpenClaw solo responde a los chats que recibe o a los envíos explícitos que usted inicia.

openclaw pairing approve whatsapp <code>openclaw pairing list whatsapp

La solicitud del número de teléfono del asistente configura la lista de permitidos/propietario para que se permitan sus propios mensajes directos; no se utiliza para el envío automático. Para su número personal de WhatsApp, use ese número y habilite channels.whatsapp.selfChatMode.

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

Para corregirlo en el chat donde aparecen:

/verbose off/trace off/reasoning off

Si sigue habiendo demasiado ruido, compruebe la configuración de la sesión en la interfaz de control y establezca verbose en inherit; confirme que no esté utilizando un perfil de bot con verboseDefault: "on" en la configuración.

Documentación: Razonamiento y modo detallado, Seguridad.

Envíe cualquiera de estas opciones como mensaje independiente (sin barra) para activar una cancelación: 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, do not do that, please stop, stop please, abort, esc, exit, interrupt, halt. También funcionan activadores habituales en otros idiomas (francés, alemán, español, chino, japonés, hindi, árabe y ruso).

Para los procesos en segundo plano iniciados mediante la herramienta exec, solicite al agente que ejecute:

process action:kill sessionId:XXX

La mayoría de los comandos con barra deben enviarse como un mensaje independiente que comience por /, pero algunos atajos (como /status) también funcionan dentro de un mensaje para remitentes incluidos en la lista de permitidos. Consulte Comandos con barra.

OpenClaw bloquea de forma predeterminada la mensajería entre proveedores. Si una llamada a una herramienta está vinculada a Telegram, no enviará mensajes a Discord a menos que lo permita explícitamente; el cambio surte efecto de inmediato, sin necesidad de reiniciar el Gateway:

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

De forma predeterminada, las instrucciones enviadas durante una ejecución se incorporan a la ejecución activa. Use /queue para elegir el comportamiento de la ejecución activa:

• steer (predeterminado): orienta la ejecución activa en el siguiente límite del modelo.
• followup: pone los mensajes en cola y los ejecuta uno por uno cuando finaliza la ejecución actual.
• collect: pone en cola los mensajes compatibles y responde una sola vez cuando finaliza la ejecución actual.
• interrupt: cancela la ejecución actual e inicia una nueva.

Añada opciones a los modos en cola, como debounce:0.5s cap:25 drop:summarize. Consulte Cola de comandos y Cola de orientación.

Las credenciales y la selección del modelo son independientes. 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 se configure en agents.defaults.model.primary (por ejemplo, anthropic/claude-sonnet-4-6 o anthropic/claude-opus-4-6). No credentials found for profile "anthropic:default" significa que el Gateway no pudo encontrar las credenciales de Anthropic en el auth-profiles.json esperado para el agente en ejecución.