Skip to main content
Respuestas rápidas y solución de problemas más detallada para configuraciones reales (desarrollo local, VPS, múltiples agentes, claves de OAuth/API, conmutación por error de modelos). Para obtener diagnósticos del entorno de ejecución, consulte Solución de problemas. Para consultar la referencia completa de configuración, consulte Configuración.

​
Primeros 60 segundos si algo no funciona

1

Estado rápido

Resumen local rápido: SO + actualización, accesibilidad del Gateway/servicio, agentes/sesiones, configuración del proveedor + problemas del entorno de ejecución (cuando se puede acceder al Gateway).
2

Informe que se puede pegar (seguro para compartir)

Diagnóstico de solo lectura con las últimas líneas del registro (tokens ocultos).
3

Estado del daemon + puerto

Muestra el entorno de ejecución del supervisor frente a la accesibilidad mediante RPC, la URL de destino del sondeo y qué configuración probablemente utilizó el servicio.
4

Sondeos exhaustivos

Sondeo en vivo del estado del Gateway, incluidos los sondeos de canales cuando se admiten (requiere un Gateway accesible). Consulte Estado.
5

Seguir el registro más reciente

Si RPC no está disponible, recurra a:
Los registros de archivos son independientes de los registros del servicio; consulte Registro y Solución de problemas.
6

Ejecutar el doctor (reparaciones)

Repara/migra la configuración y el estado y, a continuación, ejecuta comprobaciones de estado. Consulte Doctor.
7

Instantánea del Gateway (solo WS)

Solicita una instantánea completa al Gateway en ejecución. Consulte Estado.

​
Inicio rápido y configuración de la primera ejecución

Las preguntas y respuestas sobre la primera ejecución —instalación, incorporación, rutas de autenticación, suscripciones y errores iniciales— se encuentran en las Preguntas frecuentes sobre la primera ejecución.

​
¿Qué es OpenClaw?

OpenClaw es un asistente personal de IA que se ejecuta en sus propios dispositivos. Responde en las plataformas de mensajería que ya utiliza (Discord, Google Chat, iMessage, Mattermost, Signal, Slack, Telegram, WebChat, WhatsApp y plugins de canal 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 con prioridad local que ejecuta un asistente competente en su propio hardware, accesible desde las aplicaciones de chat que ya utiliza, con sesiones con estado, memoria y herramientas, sin entregar sus flujos de trabajo a un SaaS alojado.
  • Sus dispositivos, sus datos: ejecute el Gateway donde quiera (Mac, Linux, VPS) y mantenga localmente el espacio de trabajo y el historial de sesiones.
  • Canales reales, no un entorno aislado web: 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 su dispositivo.
  • 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: inspeccione, amplíe y autoaloje sin dependencia de un proveedor.
Documentación: Gateway, Canales, Multiagente, Memoria.
Buenos proyectos iniciales: 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 con subagentes para trabajar en paralelo.
  • Informes personales: resúmenes de la bandeja de entrada, el calendario y las noticias que le interesan.
  • 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 por 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 investigar, evaluar y redactar: analizar sitios, crear listas de candidatos, resumir posibles clientes y escribir 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; usted aprueba.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 orquestación de herramientas.
  • Memoria y espacio de trabajo persistentes entre sesiones.
  • Acceso multiplataforma (Telegram, WhatsApp, TUI, WebChat).
  • Orquestació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.
Demostración: https://openclaw.ai/showcase.

​
Skills y automatización

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; de este modo, las anulaciones administradas prevalecen sobre las Skills incluidas sin modificar git. Para realizar una instalación global pero limitar la visibilidad a algunos agentes, conserve la copia compartida en ~/.openclaw/skills y controle la visibilidad con agents.defaults.skills / agents.entries.*.skills. Solo las modificaciones aptas para incorporarse al proyecto original deben enviarse como pull requests 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 se instala en ./skills de forma predeterminada, 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.entries.*.skills.
Patrones compatibles:
  • Trabajos de Cron: los trabajos aislados pueden establecer una anulación de model por trabajo.
  • Agentes: enrute las tareas a agentes separados 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 ajustes distintos por agente:
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.entries.*.params plano. No duplique el mismo modelo en el agents.entries.*.models["provider/model"].params anidado; esa ruta corresponde al catálogo de modelos y a las anulaciones del entorno 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 la capacidad de respuesta del chat principal. 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; configure 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 a un destino de sesión para que los mensajes posteriores que se envíen allí permanezcan en esa sesión vinculada.
  • Créelo con sessions_spawn mediante thread: true (opcionalmente, mode: "session" para un seguimiento persistente).
  • O vincúlelo manualmente con /focus <target>.
  • /agents inspecciona el estado de la vinculación.
  • /session idle <duration|off> y /session max-age <duration|off> controlan la pérdida automática de enfoque.
  • /unfocus desvincula el hilo.
Configuración: session.threadBindings.enabled (interruptor global), session.threadBindings.idleHours (valor predeterminado 24; 0 lo desactiva), session.threadBindings.maxAgeHours (valor predeterminado 0 = sin límite estricto) y session.threadBindings.spawnSessions para la vinculación automática al crear el subagente (valor predeterminado true).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 da prioridad a una ruta de hilo o conversación vinculada cuando existe.
  • 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 pueda completarse.
  • Si no hay ninguna 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 como alternativa o provocar un fallo definitivo de entrega.
  • Si la última respuesta visible del asistente secundario es exactamente NO_REPLY / no_reply o ANNOUNCE_SKIP, OpenClaw omite deliberadamente 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 continuamente.
  • Confirme que Cron esté habilitado (cron.enabled) y que OPENCLAW_SKIP_CRON no esté configurado.
  • Confirme que el Gateway se esté ejecutando 24/7 (sin suspensión ni reinicios).
  • Verifique la zona horaria del trabajo (--tz frente a la zona horaria del host).
Depuración:
Documentación: Trabajos de Cron, Automatización.
Compruebe el modo de entrega:
  • --no-deliver / delivery.mode: "none": no se espera un envío de respaldo del ejecutor.
  • Destino de anuncio ausente o no válido (channel / to): el ejecutor omitió la entrega saliente.
  • Errores 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 de Cron aislados, el agente aún puede enviar directamente mediante 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 todavía no haya enviado.Depuración:
Documentación: Trabajos de Cron, Tareas en segundo plano.
Esa es la ruta activa de cambio de modelo, no una programación duplicada. Cron aislado conserva una transferencia del modelo en tiempo de ejecución y reintenta cuando la ejecución activa genera LiveSessionModelSwitchError, manteniendo el proveedor/modelo al que se cambió (y cualquier sustitución del perfil de autenticación al que se haya cambiado) antes del reintento.Precedencia de selección de modelo: primero, la sustitución del modelo del hook de Gmail (hooks.gmail.model); después, model por trabajo; a continuación, cualquier sustitución de modelo almacenada en la sesión de Cron; y, por último, la selección normal del modelo del agente/predeterminado.El bucle de reintentos se limita al intento inicial más 2 reintentos de cambio; después, Cron se interrumpe en lugar de repetirse indefinidamente.Depuración:
Documentación: Trabajos de Cron, CLI de Cron.
Use comandos openclaw skills nativos 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.
De manera 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 clawhub independiente solo para publicar o sincronizar sus propias Skills. Use agents.defaults.skills o agents.entries.*.skills para limitar qué agentes ven las Skills compartidas.
Sí, mediante el programador del Gateway:
  • Trabajos de 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 de Cron, Automatización, Heartbeat.
No directamente. Las Skills de macOS están condicionadas 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 esa condició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, a continuación, conéctese desde Linux en modo remoto o mediante Tailscale. Las Skills se cargan normalmente porque el host del Gateway es macOS.Opción B: usar un Node de macOS (sin SSH). Ejecute el Gateway en Linux, empareje un Node de macOS (aplicación de la barra de menús) y establezca Node Run Commands en “Always Ask” o “Always Allow” en el Mac. OpenClaw considera aptas las Skills exclusivas de macOS cuando los binarios necesarios existen en el Node; el agente las ejecuta mediante la herramienta nodes. Con “Always Ask”, aprobar “Always Allow” en la solicitud añade ese comando a la lista de permitidos.Opción C: usar binarios de macOS mediante un proxy por SSH (avanzada). Mantenga el Gateway en Linux, pero haga que los binarios de CLI necesarios se resuelvan como envoltorios SSH que se ejecuten en un Mac y, después, anule la Skill para permitir Linux y que siga siendo apta.
  1. Cree un envoltorio SSH para el binario (ejemplo: memo para Apple Notes):
  2. Coloque el envoltorio en PATH en el host Linux (por ejemplo, ~/bin/memo).
  3. Anule los metadatos de la Skill (en el espacio de trabajo o en ~/.openclaw/skills) para permitir Linux:
  4. Inicie una sesión nueva para actualizar la instantánea de Skills.
Actualmente no está integrada. Opciones:
  • Skill / Plugin personalizado: la mejor opción para obtener acceso fiable a la API (ambos disponen de API).
  • Automatización del navegador: funciona sin código, pero es más lenta y frágil.
Para un contexto por cliente al estilo de una agencia: mantenga una página de Notion por cliente (contexto + preferencias + trabajo activo) y solicite al agente que recupere esa página al inicio de una sesión.Para una integración nativa, abra una solicitud de funcionalidad o cree una Skill que use esas API.
Las instalaciones nativas se guardan en el directorio skills/ del espacio de trabajo activo; use --global para todos los agentes locales, o configure agents.defaults.skills / agents.entries.*.skills para limitar la visibilidad. Algunas Skills requieren binarios instalados mediante Homebrew; en Linux, esto significa Linuxbrew.Consulte Skills, Configuración de Skills, ClawHub.
Use el perfil de navegador user integrado, que se conecta mediante Chrome DevTools MCP:
Para usar un nombre personalizado, cree un perfil MCP explícito:
Puede usar el navegador del host local o un Node de navegador conectado. Si el Gateway se ejecuta en otro lugar, ejecute un host de Node en el equipo del navegador o use CDP remoto.Límites actuales de los perfiles existing-session / user frente al perfil administrado openclaw:
  • click, type, hover, scrollIntoView, drag y select requieren referencias de instantánea, no selectores CSS.
  • Los hooks de carga requieren ref o inputRef, un archivo a la vez, sin element de CSS.
  • responsebody, la exportación a PDF, la interceptación de descargas y las acciones por lotes todavía requieren la ruta del navegador administrado.
Consulte Navegador para ver la comparación completa.

​
Aislamiento y memoria

Sí: Aislamiento. Para la configuración específica de Docker (el 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:
  • Haga persistente /home/node mediante OPENCLAW_HOME_VOLUME para conservar las cachés.
  • Integre 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.
  • Establezca PLAYWRIGHT_BROWSERS_PATH y haga persistente esa ruta.
Documentación: Docker, Navegador.
Sí, si el tráfico privado son mensajes directos y el tráfico público son grupos. Configure 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 la sesión principal de mensajes directos permanece en el host. Docker es el backend predeterminado una vez habilitado el aislamiento. Restrinja las herramientas disponibles en las sesiones aisladas mediante tools.sandbox.tools.Guía de configuración: Grupos: mensajes directos personales + grupos públicos. Referencia principal: Configuración del Gateway.
Establezca agents.defaults.sandbox.docker.binds en ["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". Use :ro para cualquier elemento sensible; las vinculaciones eluden 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 mediante directorios padre que sean enlaces simbólicos se rechazan de forma segura incluso cuando el segmento final de la ruta todavía no existe.Consulte Aislamiento y Entorno aislado frente a política de herramientas frente a privilegios elevados.
La memoria de OpenClaw consiste en archivos Markdown del espacio de trabajo del agente: notas diarias en memory/YYYY-MM-DD.md y notas seleccionadas a largo plazo en MEMORY.md (solo sesiones principales/privadas).OpenClaw también ejecuta un vaciado de memoria previo a Compaction silencioso antes de que Compaction resuma la conversación, para recordar al modelo que primero escriba notas persistentes. Solo se ejecuta cuando se puede escribir en el espacio de trabajo (los entornos aislados de solo lectura lo omiten); deshabilítelo mediante 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 los recuerdos suele resolver el problema. Si continúa olvidándolos, verifique que el Gateway use 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 la memoria, que reincorpora al contexto únicamente las partes pertinentes.Documentación: Memoria, Contexto.
Solo si se usan embeddings de OpenAI, que es el proveedor predeterminado. OAuth de Codex cubre el chat y las finalizaciones, pero no concede acceso a embeddings, 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 la memoria. Los embeddings de OpenAI siguen requiriendo una clave de API real (OPENAI_API_KEY o models.providers.openai.apiKey).Para mantener todo en local, configure memory.search.provider: "local" (GGUF/llama.cpp). Otros proveedores compatibles: Bedrock, DeepInfra, Gemini (GEMINI_API_KEY o memory.search.remote.apiKey), GitHub Copilot, LM Studio, Mistral, Ollama, compatible con OpenAI y Voyage. Consulte Memoria y Búsqueda en la memoria para obtener detalles de configuración.

​
Dónde se encuentran los elementos en el disco

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.) llegan a sus API, y las plataformas de chat (Slack/Telegram/WhatsApp/etc.) almacenan datos de los mensajes en sus servidores.
  • Se controla el alcance: los modelos locales mantienen los prompts en el equipo, pero el tráfico de los canales sigue pasando por los servidores del canal.
Relacionado: Espacio de trabajo del agente, Memoria.
Todo se encuentra en $OPENCLAW_STATE_DIR (valor predeterminado: ~/.openclaw):La ruta heredada de agente único ~/.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 es únicamente una entrada de reparación heredada; 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 puede configurarse:
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 conservar un comportamiento o una preferencia, solicite 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 de inyección predeterminado por archivo es de 20000 caracteres; el presupuesto total de arranque entre todos los archivos es de 60000 caracteres.Cambie los valores predeterminados compartidos:
También se puede sobrescribir la configuración de un agente en agents.entries.*.bootstrapMaxChars / bootstrapTotalMaxChars.Use /context para comprobar los tamaños sin procesar e inyectados, y 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 persistentes en la memoria.Consulte Contexto y Configuración del agente.
Coloque el espacio de trabajo del agente en un repositorioio git privado y haga una copia de seguridad en una ubicación privada (por ejemplo, un repositorio privado de GitHub). Esto incluye la memoria y 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 útiles de secretos cifrados). Para una restauración completa, haga copias de seguridad independientes 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 ancla 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 el aislamiento esté habilitado. Para aislar el entorno, 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 repositorio de OpenClaw en sí solo contiene código fuente, por lo que conviene mantener el espacio de trabajo separado, a menos que se pretenda expresamente que el agente trabaje dentro de él.
El estado de las sesiones pertenece al host del Gateway. En modo remoto, el almacén de sesiones pertinente se encuentra en la máquina remota, no en el portátil local. Consulte Gestión de sesiones.

​
Conceptos básicos de configuración

OpenClaw lee una configuración JSON5 opcional desde $OPENCLAW_CONFIG_PATH (valor predeterminado: ~/.openclaw/openclaw.json). Si falta el archivo, utiliza valores predeterminados razonablemente seguros, incluido el espacio de trabajo predeterminado ~/.openclaw/workspace.
Las vinculaciones que no son 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.remote.token / .password no habilitan por sí solos la autenticación local del Gateway; las rutas de llamadas locales pueden usar gateway.remote.* como alternativa solo cuando gateway.auth.* no está definido.
  • Para la autenticación mediante contraseña, configure 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 puede resolver, la resolución se cierra de forma segura (sin que una alternativa remota oculte el fallo).
  • Las configuraciones de la interfaz de control con secreto compartido se autentican mediante connect.params.auth.token o connect.params.auth.password (almacenados en la configuración de la aplicación/interfaz). Los modos que incorporan identidad, como Tailscale Serve o trusted-proxy, utilizan 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, incluso en el bucle invertido. Si no se configura ninguna ruta de autenticación explícita, durante el inicio se selecciona el modo de token y se genera un token exclusivo del entorno de ejecución para 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 se puede elegir el modo de contraseña o trusted-proxy para proxies inversos con reconocimiento de identidad. Para un bucle invertido abierto, configure 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 ante cambios críticos. También se admiten hot, restart y off. La mayoría de los cambios en tools.*, la política 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.
web_fetch funciona sin una clave de API. web_search depende del proveedor seleccionado:Grok también puede reutilizar OAuth de xAI de la autenticación del modelo (openclaw onboard --auth-choice xai-oauth).Recomendación: openclaw configure --section web y seleccione un proveedor.
La configuración de búsqueda web específica del proveedor se encuentra en plugins.entries.<plugin>.config.webSearch.*. Las rutas heredadas del proveedor tools.web.search.* aún se cargan por compatibilidad, pero no deben utilizarse en configuraciones nuevas. La configuración de respaldo de obtención web de Firecrawl se encuentra en plugins.entries.firecrawl.config.webFetch.*.
  • Listas de permitidos: añada web_search/web_fetch/x_search, o group:web para las tres.
  • web_fetch está habilitado de forma predeterminada.
  • Si se omite tools.web.fetch.provider, OpenClaw detecta automáticamente el primer proveedor de respaldo de obtención que esté listo entre las credenciales disponibles; el plugin oficial de Firecrawl proporciona ese respaldo.
  • 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 evita la mayoría de las sobrescrituras accidentales:
  • Las escrituras de configuración propiedad de OpenClaw validan toda la configuración resultante 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:
  • Compruebe openclaw logs --follow para buscar Invalid config at, Config write rejected: o config reload skipped (invalid config).
  • Inspeccione el archivo openclaw.json.clobbered.* o openclaw.json.rejected.* más reciente junto a la configuración activa.
  • Ejecute openclaw config validate y openclaw doctor --fix.
  • Vuelva a copiar únicamente las claves deseadas mediante openclaw config set o config.patch.
  • Si no hay una última configuración válida conocida ni una carga rechazada: restaure una copia de seguridad o vuelva a ejecutar openclaw doctor y configure de nuevo los canales/modelos.
  • En caso de pérdida inesperada: presente un informe de error con la última configuración conocida o una copia de seguridad. Un agente de programación local suele poder reconstruir una configuración funcional a partir de los registros o el historial.
Para evitarlo: use 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; reserve 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), más nodos y agentes.
  • Gateway (central): gestiona los canales (Signal/WhatsApp), el enrutamiento y las sesiones.
  • Nodos (dispositivos): los Mac y dispositivos iOS/Android se conectan como periféricos y exponen herramientas locales (system.run, canvas, camera).
  • Agentes (trabajadores): cerebros y espacios de trabajo independientes para funciones especializadas (por ejemplo, operaciones frente a datos personales).
  • Subagentes: inician 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í:
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 con la mayoría de las automatizaciones; la principal diferencia es que no hay una ventana visible del navegador (use capturas de pantalla para la información visual). Consulte Navegador.
Establezca browser.executablePath en el binario de Brave (o de cualquier navegador basado en Chromium) y reinicie el Gateway. Consulte Navegador.

​
Gateways remotos y nodos

Los mensajes de Telegram los gestiona el Gateway, que ejecuta el agente y solo después llama a los nodos mediante el WebSocket del Gateway cuando se necesita una herramienta de nodo:Telegram -> Gateway -> Agente -> node.* -> Nodo -> Gateway -> TelegramLos nodos no ven el tráfico entrante del proveedor; solo reciben llamadas RPC de nodo.
Empareje su ordenador como nodo. El Gateway se ejecuta en otro lugar, pero puede llamar a herramientas node.* (pantalla, cámara, sistema) de su equipo local mediante el WebSocket del Gateway.
  1. Ejecute el Gateway en el equipo que permanece siempre encendido (VPS/servidor doméstico).
  2. Conecte el equipo del Gateway y su ordenador a la misma red de Tailscale.
  3. Asegúrese de que el WebSocket del Gateway sea accesible (vinculación a la red de Tailscale o túnel SSH).
  4. Abra localmente la aplicación para macOS y conéctese en el modo Remote over SSH (o directamente mediante la red de Tailscale) para que se registre como nodo.
  5. Apruebe el nodo:
No se necesita ningún puente TCP independiente; los nodos se conectan mediante el WebSocket del Gateway.Recordatorio de seguridad: emparejar un nodo de macOS permite system.run en ese equipo. Empareje únicamente dispositivos de confianza; consulte Seguridad.Documentación: Nodos, Protocolo del Gateway, Modo remoto de macOS, Seguridad.
Compruebe los aspectos básicos:
A continuación, verifique la autenticación y el enrutamiento: si utiliza Tailscale Serve, confirme que gateway.auth.allowTailscale esté configurado correctamente; si se conecta mediante un túnel SSH, confirme que el túnel esté activo y apunte al puerto correcto; confirme que las listas de permitidos para mensajes directos/grupos incluyan su cuenta.Documentación: Tailscale, Acceso remoto, Canales.
Sí, aunque no existe un puente integrado entre bots.La opción más sencilla: utilice un canal de chat normal al que ambos bots puedan acceder (Slack/Telegram/WhatsApp). Haga que el bot A envíe un mensaje al bot B y permita que el bot B responda con normalidad.Puente mediante CLI (genérico): ejecute 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 está en un VPS remoto, dirija la CLI a ese Gateway remoto mediante SSH/Tailscale (consulte Acceso remoto):
Añada una medida de protección para evitar que los dos bots 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 del modelo y enrutamiento; esta es la configuración habitual y resulta mucho más económica y sencilla que usar un VPS por agente. Utilice VPS independientes únicamente cuando necesite un aislamiento estricto (límites de seguridad) o configuraciones muy distintas que no desee 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 un VPS pequeño o un equipo similar a una Raspberry Pi; 4 GB de RAM son suficientes), por lo que una configuración habitual consiste en un equipo 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á sujeto a las listas de permitidos y las aprobaciones del nodo en ese portátil.
  • Más herramientas del dispositivo: además de system.run, los nodos exponen canvas, camera y screen.
  • Automatización local del navegador: mantenga el Gateway en un VPS, pero ejecute Chrome localmente mediante un equipo nodo, o conéctese al Chrome local mediante Chrome MCP.
SSH es adecuado para el acceso ocasional al shell; los nodos son más sencillos para los flujos de trabajo continuos de los agentes y la automatización de dispositivos.Documentación: Nodos, CLI de nodos, Navegador.
No. Solo debe ejecutarse un Gateway por equipo, salvo que se ejecuten intencionadamente perfiles aislados (consulte 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 equipos nodo sin interfaz gráfica y el control mediante CLI, consulte CLI del equipo nodo.Se requiere un reinicio completo para gateway, discovery y los cambios en las superficies de plugins alojados.
Sí:
  • config.schema.lookup: inspecciona un subárbol de configuración con su nodo de esquema superficial, la sugerencia de interfaz coincidente y resúmenes de los elementos secundarios inmediatos antes de escribir.
  • config.get: obtiene la instantánea actual y su hash.
  • config.patch: actualización parcial segura (preferida para la mayoría de las ediciones RPC); realiza una recarga en caliente cuando es posible y reinicia cuando es necesario.
  • config.apply: valida y reemplaza la configuración completa; realiza una recarga en caliente cuando es posible y reinicia cuando es necesario.
  • La herramienta de tiempo 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.
Establece el espacio de trabajo y restringe quién puede activar el bot.
  1. Instale e inicie sesión en el VPS:
  2. Instale e inicie sesión en su Mac mediante la aplicación Tailscale, en la misma tailnet.
  3. Habilite MagicDNS en la consola de administración de Tailscale para que el VPS tenga un nombre estable.
  4. Use 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, utilice Tailscale Serve en el VPS:
Esto mantiene el Gateway vinculado a la interfaz de bucle invertido y expone HTTPS mediante Tailscale. Consulte Tailscale.
Serve expone la interfaz de control y el WS del Gateway; los Nodes se conectan mediante el mismo punto de conexión WS del Gateway.
  1. Asegúrese de que el VPS y el Mac estén en la misma tailnet.
  2. Use la aplicación para macOS en modo remoto (el destino SSH puede ser el nombre de host de la tailnet): crea un túnel para el puerto del Gateway y se conecta como Node.
  3. Apruebe el Node:
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ñádalo como Node: un solo Gateway, sin duplicar la configuración. Actualmente, las herramientas locales de Node solo están disponibles en macOS. Instale un segundo Gateway únicamente para obtener aislamiento estricto o dos bots completamente independientes.Documentación: Nodes, CLI de Nodes, Varios Gateways.

​
Variables de entorno y carga de .env

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 valor alternativo 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 de enrutamiento de puntos de conexión son una excepción para el archivo .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 archivo .env del espacio de trabajo y deben definirse en el entorno del proceso, en ~/.openclaw/.env o en la configuración env.Las variables de entorno insertadas directamente en la configuración solo se aplican si no están presentes en el entorno del proceso:
Consulte /environment para conocer todas las prioridades y fuentes.
Hay dos soluciones:
  1. Coloque las claves que faltan en ~/.openclaw/.env para que se carguen incluso cuando el servicio no herede el entorno de su shell.
  2. Habilite la importación del shell (función opcional):
    Esto ejecuta su 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á habilitada. “Shell env: off” no significa que falten sus variables de entorno; solo significa que OpenClaw no cargará automáticamente su shell de inicio de sesión.Si el Gateway se ejecuta como servicio (launchd/systemd), no heredará el entorno de su shell. Para solucionarlo, coloque el token en ~/.openclaw/.env, habilite env.shellEnv.enabled: true o añádalo a la configuración env (solo se aplica si falta); después, reinicie el Gateway y vuelva a comprobarlo:
Los tokens de Copilot se resuelven en este orden: OPENCLAW_GITHUB_TOKEN, luego COPILOT_GITHUB_TOKEN, después GH_TOKEN y, por último, GITHUB_TOKEN.Consulte /concepts/model-providers y /environment.

​
Sesiones y varios chats

Envíe /new o /reset como mensaje independiente. Consulte Gestión de sesiones.
No, de forma predeterminada. Las sesiones conservan el mismo sessionId, y Compaction limita el contexto activo del modelo a medida que crecen las conversaciones. /new y /reset siguen disponibles, o puede habilitar los restablecimientos automáticos mediante mode: "daily" o mode: "idle". El modo diario cambia de periodo a las session.reset.atHour (valor predeterminado: 4, 0-23) en el host del Gateway; el modo inactivo utiliza session.reset.idleMinutes desde la última interacción real, no desde eventos del sistema de Heartbeat/Cron/ejecución.
resetByType admite direct, group y thread. Doctor migra las entradas heredadas dm a direct; el esquema rechaza dm. El valor heredado de nivel superior session.idleMinutes sigue funcionando como alias de compatibilidad para un valor predeterminado del modo inactivo cuando no se establece ningún bloque session.reset/resetByType. Consulte 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 trabajadores 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, distintas sesiones para el trabajo en paralelo y subagentes que se crean cuando son necesarios.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 una gran cantidad de archivos pueden activar Compaction o el truncamiento.
  • Pida al bot que resuma el estado actual y lo escriba en un archivo.
  • Use /compact antes de tareas largas y /new al cambiar de tema.
  • Mantenga el contexto importante en el espacio de trabajo y pida al bot que vuelva a leerlo.
  • Use subagentes para trabajos largos o paralelos, de modo que el chat principal se mantenga más pequeño.
  • Elija un modelo con una ventana de contexto mayor si esto ocurre con frecuencia.
Restablecimiento completo no interactivo:
Después, vuelva a ejecutar la configuración:
La incorporación también ofrece Restablecer si detecta una configuración existente; consulte Incorporación (CLI). Si utilizó perfiles (--profile / OPENCLAW_PROFILE), restablezca cada directorio de estado (valor predeterminado: ~/.openclaw-<profile>). Restablecimiento solo para desarrollo: openclaw gateway --dev --reset elimina la configuración de desarrollo, las credenciales, las sesiones y el espacio de trabajo.
  • Compaction (conserva la conversación y resume los turnos anteriores): /compact o /compact <instructions> para orientar el resumen.
  • Restablecimiento (nuevo ID de sesión para la misma clave de chat): /new o /reset.
Si sigue ocurriendo, ajuste la depuración de sesiones (agents.defaults.contextPruning) para recortar las salidas antiguas de herramientas o utilice 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, esto 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: inicie 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 de Anthropic o autenticación mediante token (incluida la reutilización de Claude CLI) y heartbeat.every no está establecido. Ajústelos o desactívelos:
Si HEARTBEAT.md existe, 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 de Heartbeat para ahorrar llamadas a la API. Si falta el archivo, Heartbeat se sigue ejecutando y el modelo decide qué hacer.Las anulaciones por agente utilizan agents.entries.*.heartbeat. Documentación: Heartbeat.
No. OpenClaw se ejecuta en su propia cuenta: si forma parte del grupo, OpenClaw puede verlo. De forma predeterminada, las respuestas en grupos están bloqueadas hasta que se permitan remitentes (groupPolicy: "allowlist").Para restringir las respuestas en grupos únicamente a usted:
La forma más rápida es seguir los registros y enviar un mensaje de prueba en el grupo.
Busque chatId (o from) que termine en @g.us, como 1234567890-1234567890@g.us.Si ya está configurado o incluido en la lista de permitidos, enumere los grupos desde la configuración:
Documentación: WhatsApp, Directorio, Registros.
Hay dos causas habituales: la restricción por mención está habilitada de forma predeterminada (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 y 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 crear decenas o incluso cientos, pero tenga en cuenta:
  • 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.
  • Sobrecarga 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 SQLite activo) y use openclaw doctor para detectar espacios de trabajo aislados y discrepancias entre perfiles.
Sí, mediante el enrutamiento multiagente: ejecute varios agentes aislados y enrute los mensajes entrantes por canal, cuenta o interlocutor. Slack es compatible como canal y puede vincularse a agentes específicos.El acceso mediante navegador es potente, pero no permite «hacer todo lo que puede hacer una persona»: las medidas antibots, los CAPTCHA y la MFA aún pueden bloquear la automatización. Para obtener el control más fiable, use Chrome MCP localmente en el host o CDP en el equipo que realmente ejecuta el navegador.Configuración recomendada: un host del Gateway siempre activo (VPS/Mac mini), un agente por función (vinculaciones), canales de Slack vinculados a esos agentes y un navegador local mediante Chrome MCP o un nodo cuando sea necesario.Documentación: Enrutamiento multiagente, Slack, Navegador, Nodos.

​
Modelos, conmutación por error y perfiles de autenticación

Las preguntas y respuestas sobre modelos —valores predeterminados, selección, alias, cambio, conmutación por error y perfiles de autenticación— se encuentran en las preguntas frecuentes sobre modelos.

​
Gateway: puertos, «ya está en ejecución» y modo remoto

gateway.port controla el único puerto multiplexado para WebSocket + HTTP (interfaz de control, hooks, etc.). Precedencia:
«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 utilizada por 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 discrepancia entre --profile y OPENCLAW_STATE_DIR).Para corregirlo, ejecute lo siguiente desde el mismo --profile o entorno que deba utilizar el servicio:
OpenClaw impone un bloqueo de ejecución vinculando el listener de WebSocket inmediatamente al iniciarse (valor predeterminado: ws://127.0.0.1:18789). Si la vinculación falla con EADDRINUSE, genera GatewayLockError («otra instancia del Gateway ya está 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:
  • openclaw gateway solo se inicia cuando gateway.mode es local (o se pasa una opción 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; por sí solas, no habilitan 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, de modo que las actualizaciones dentro de la misma pestaña siguen funcionando sin conservar el token de forma prolongada en localStorage.
  • En AUTH_TOKEN_MISMATCH, los clientes de confianza pueden intentar un 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 junto al token del dispositivo; los llamadores que usan explícitamente deviceToken / scopes 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 al conectarse 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 de nodo con scopes: [], además de un token de transferencia de operador limitado para la incorporación móvil de confianza. La transferencia de operador puede leer la configuración nativa durante la configuración, pero no concede ámbitos de modificación de vinculación ni operator.admin.
Solución:
  • 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 indicación de SSH).
  • Si aún no hay un token: openclaw doctor --generate-gateway-token.
  • Acceso remoto: primero cree 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, después, 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 loopback o tailnet que omita las cabeceras de identidad de Tailscale.
  • Modo de proxy de confianza: confirme que el acceso se realiza mediante el proxy configurado con reconocimiento de identidad. Los proxies de loopback en el mismo host también necesitan gateway.auth.trustedProxy.allowLoopback = true.
  • Si la discrepancia persiste después del único reintento, rote o vuelva a aprobar el token del dispositivo vinculado:
  • Si se deniega la rotación: las sesiones de dispositivos vinculados 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 llamador.
  • 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á desactivada), el Gateway recurre a loopback 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 a loopback. Use gateway.bind: "tailnet" para limitar la exposición fuera de loopback a la Tailnet y, al mismo tiempo, conservar el listener obligatorio 127.0.0.1 del mismo host.
Por lo general, no: un Gateway puede ejecutar varios canales de mensajería y agentes. Use varios Gateways únicamente para obtener redundancia (por ejemplo, un bot de rescate) o un 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 un sufijo a los nombres de los servicios: launchd ai.openclaw.<profile>, systemd openclaw-gateway-<profile>.service, Windows OpenClaw Gateway (<profile>). La unidad de systemd openclaw-gateway sin calificador solo existe para el perfil predeterminado; el nombre heredado de la unidad de 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 otro mensaje 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 usar un cliente WS, se utilizó un puerto o una ruta incorrectos, o un proxy o túnel eliminó las cabeceras de autenticación o envió una solicitud ajena al Gateway.Solución: use la URL de WS (ws://<host>:18789 o wss://... mediante HTTPS), no abra el puerto de 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:
Detalles del protocolo: Protocolo del Gateway.

​
Registro y depuración

Registros de archivos (estructurados): /tmp/openclaw/openclaw-YYYY-MM-DD.log para el perfil predeterminado o /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log para un perfil con nombre. Establezca una ruta estable mediante logging.file; el nivel de registro de archivos mediante logging.level; y el nivel de detalle de la consola mediante --verbose y logging.consoleLevel.Forma más rápida de seguirlos:
Registros del servicio o 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.
Si ejecuta el Gateway manualmente, openclaw gateway --force puede recuperar el puerto. Consulte Gateway.
Tres modos de instalación en Windows:1) Configuración local de Windows Hub: la aplicación nativa administra un Gateway de WSL local y propiedad de la aplicación. Abra OpenClaw Companion desde el menú Inicio o la bandeja del sistema y, después, use Gateway Setup o la pestaña Connections.2) Gateway manual de WSL2: el Gateway se ejecuta dentro de Linux.
Si nunca instaló el servicio, inícielo en primer plano: openclaw gateway run.3) CLI/Gateway nativo de Windows: se ejecuta directamente en Windows.
Si lo ejecuta manualmente (sin servicio): openclaw gateway run.Documentación: Windows, Guía operativa del servicio del Gateway.
Comprobación rápida del estado:
Causas habituales: la autenticación del modelo no está cargada en el host del Gateway (compruebe models status), la vinculación o la lista de permitidos del canal bloquea las respuestas (compruebe la configuración y los registros del canal), o WebChat/Panel está abierto sin el token correcto. Si el acceso es remoto, confirme que la conexión del túnel o de Tailscale esté activa y que se pueda acceder al WebSocket del Gateway.Docs: Canales, Solución de problemas, Acceso remoto.
Normalmente significa que la interfaz de usuario perdió la conexión WebSocket. Compruebe: ¿está ejecutándose 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:
Docs: Panel de control, Acceso remoto, Solución de problemas.
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í pueden 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 permiten las conexiones HTTPS salientes y que el DNS funciona para api.telegram.org.
Si el Gateway es remoto, compruebe los registros en el host del Gateway.Docs: Telegram, Solución de problemas de canales.
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).Docs: TUI, Comandos con barra.
Si instaló el servicio (launchd en macOS, systemd en Linux):
En primer plano, deténgalo con Ctrl-C y, a continuación, ejecute openclaw gateway run.Docs: Manual operativo 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 simple en primer plano para una ocasió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.

​
Medios y archivos adjuntos

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.
Compruebe también que el canal de destino admita medios salientes y no esté bloqueado por listas de permitidos; que el archivo se encuentre dentro de los límites de tamaño del proveedor (las imágenes se redimensionan hasta un lado máximo de 2048px); tools.fs.workspaceOnly=true limita los envíos mediante 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 pueda 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 analizador de secretos: se puede adjuntar un secret.txt o config.json que el agente pueda leer cuando la extensión y la validación de contenido coincidan. Mantenga los archivos confidenciales fuera de las rutas legibles por el agente o conserve tools.fs.workspaceOnly=true para aplicar restricciones más estrictas a los envíos mediante rutas locales.Consulte Imágenes.

​
Seguridad y control de acceso

Trate los mensajes directos entrantes como entradas que no son de confianza. Los valores predeterminados reducen el riesgo:
  • El comportamiento predeterminado en los canales que admiten 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 arriesgadas.
No. La inyección de instrucciones está relacionada con el contenido que no es de confianza, 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), dicho contenido puede incluir instrucciones que intenten secuestrar el modelo, incluso si usted es el único remitente.El mayor riesgo aparece cuando las herramientas están habilitadas: se puede engañar al modelo para que exfiltre 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 que no sea de confianza
  • mantenga web_search / web_fetch / browser desactivados para los agentes con herramientas habilitadas
  • trate también como no fiable el texto decodificado de archivos o documentos: tanto input_file de OpenResponses como la extracción de archivos multimedia adjuntos envuelven el texto extraído en marcadores explícitos de límite de contenido externo, en lugar de pasar 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 importan, pero no constituyen el principal riesgo 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 y plugins de terceros.Rust y WASM pueden proporcionar un aislamiento más sólido para algunas clases de código, pero no solucionan 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 de 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 y grupos, deniegue o aísle las herramientas arriesgadas para entradas que no sean de confianza, instale únicamente plugins y Skills de confianza y ejecute openclaw security audit --deep después de cambiar la configuración.Detalles: Seguridad, Aislamiento.
Una base más segura: el Gateway vinculado a loopback o expuesto únicamente mediante acceso privado autenticado (tailnet, túnel SSH, autenticación mediante token/contraseña o un proxy de confianza configurado correctamente); mensajes directos en modo pairing o allowlist; grupos incluidos en la lista de permitidos y sujetos a menciones, a menos que todos los miembros sean de confianza; herramientas de alto riesgo (exec, browser, gateway, cron) denegadas o con un alcance estrictamente limitado para los agentes que leen contenido que no sea de confianza; 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 una barrera de seguridad completa. OpenClaw no ejecuta un bloqueo local integrado de código peligroso durante la instalación o actualización de plugins o Skills; use security.installPolicy, administrado por el operador, para tomar decisiones locales de permitir o bloquear.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 y Skills permitidos, ejecute los flujos de trabajo con entradas que no sean de confianza en un entorno aislado con un conjunto mínimo de herramientas y evite otorgar al código de terceros un acceso amplio al sistema de archivos, a la ejecución, al navegador o a secretos.Detalles: Skills, Plugins, Seguridad.
Sí, para la mayoría de las configuraciones. Aislar el bot con 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 sus cuentas personales.Empiece con poco: otorgue acceso únicamente a las herramientas y cuentas que realmente necesite y amplíelo más adelante si es necesario.Docs: Seguridad, Emparejamiento.
No recomendamos otorgarle autonomía total sobre sus mensajes personales. El patrón más seguro es 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 permitirle redactarlos mientras usted los aprueba antes de enviarlos.Para experimentar, hágalo en una cuenta dedicada y aislada. Consulte Seguridad.
Sí, si el agente solo utiliza el chat y la entrada es de confianza. Los niveles más pequeños son más susceptibles al secuestro mediante instrucciones, por lo que deben evitarse para agentes con herramientas habilitadas o al leer contenido que no sea de confianza. 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:
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 activa.
La solicitud del número de teléfono del asistente de configuración establece su lista de permitidos/propietario para que se permitan sus propios mensajes directos; no se utiliza para enviar mensajes automáticamente. En su número personal de WhatsApp, use ese número y habilite channels.whatsapp.selfChatMode.

​
Comandos de chat, cancelación de tareas y «no se detiene»

La mayoría de los mensajes internos o de herramientas solo aparecen cuando las opciones verbose, trace o reasoning están habilitadas para esa sesión.Corríjalo en el chat donde los vea:
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é usando un perfil de bot con verboseDefault: "on" en la configuración.Docs: Razonamiento y salida detallada, Seguridad.
Envía cualquiera de estos elementos 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 los 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 por la herramienta exec, solicita al agente que ejecute:
La mayoría de los comandos con barra deben enviarse como un mensaje independiente que comience con /, pero algunos atajos (como /status) también funcionan integrados en el mensaje para remitentes incluidos en la lista de permitidos. Consulta 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 se permita explícitamente; el cambio entra en vigor de inmediato, sin necesidad de reiniciar el Gateway:
De forma predeterminada, las instrucciones enviadas durante una ejecución se incorporan a la ejecución activa. Usa /queue para elegir el comportamiento de la ejecución activa:
  • steer (predeterminado): guía 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ñade opciones a los modos de cola, como debounce:0.5s cap:25 drop:summarize. Consulta Cola de comandos y Cola de direccionamiento.

​
Varios

Las credenciales y la selección del modelo son independientes. Configurar ANTHROPIC_API_KEY (o guardar 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.
¿El problema persiste? Pregunta en Discord o abre un debate en GitHub.

​
Relacionado