Respuestas rápidas y solución de problemas más profunda para configuraciones del mundo real (desarrollo local, VPS, multiagente, claves OAuth/API, conmutación por error de modelos). Para el diagnóstico en tiempo de ejecución, consulte Solución de problemas. Para la referencia completa de configuración, consulte Configuración.
Resumen local rápido: SO + actualización, accesibilidad de puerta de enlace/servicio, agentes/sesiones, configuración del proveedor + problemas de tiempo de ejecución (cuando la puerta de enlace es accesible).
Informe copiable (seguro para compartir)
Ventana de terminal
openclawstatus--all
Diagnóstico de solo lectura con el final del registro (tokens redactados).
Demonio + estado del puerto
Ventana de terminal
openclawgatewaystatus
Muestra el tiempo de ejecución del supervisor frente a la accesibilidad RPC, la URL de destino de la sonda y qué configuración usó probablemente el servicio.
Sondas profundas
Ventana de terminal
openclawstatus--deep
Ejecuta una prueba de estado del gateway en vivo, incluyendo pruebas de canal cuando se admiten
(requiere un gateway accesible). Consulte Estado.
Preguntas y respuestas de primera ejecución — instalación, incorporación, rutas de autenticación, suscripciones, fallos iniciales —
se encuentran en las Preguntas frecuentes de primera ejecución.
OpenClaw es un asistente de IA personal que ejecutas en tus propios dispositivos. Responde en las plataformas de mensajería que ya utilizas (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat y complementos de canal incluidos como QQ Bot) y también puede hacer voz + un Canvas en vivo en las plataformas compatibles. El Gateway es el plano de control siempre activo; el asistente es el producto.
Propuesta de valor
OpenClaw no es “simplemente un envoltorio de Claude”. Es un plano de control local primero que te permite ejecutar un
asistente capaz en tu propio hardware, accesible desde las aplicaciones de chat que ya usas, con
sesiones con estado, memoria y herramientas, sin ceder el control de tus flujos de trabajo a un
SaaS alojado.
Aspectos destacados:
Tus dispositivos, tus datos: ejecuta el Gateway donde quieras (Mac, Linux, VPS) y mantiene el
espacio de trabajo + historial de sesiones local.
Canales reales, no un entorno web de pruebas: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc.,
además de voz móvil y Canvas en plataformas compatibles.
Agnóstico a modelos: usa Anthropic, OpenAI, MiniMax, OpenRouter, etc., con enrutamiento
y conmutación por error por agente.
Opción solo local: ejecuta modelos locales para que todos los datos puedan permanecer en tu dispositivo si lo deseas.
Enrutamiento multiagente: agentes separados por canal, cuenta o tarea, cada uno con su propio
espacio de trabajo y valores predeterminados.
Código abierto y modificable: inspecciona, extiende y aloja por ti mismo sin bloqueo de proveedor.
Crear un sitio web (WordPress, Shopify o un sitio estático simple).
Prototipar una aplicación móvil (esquema, pantallas, plan de API).
Organizar archivos y carpetas (limpieza, nomenclatura, etiquetado).
Conectar Gmail y automatizar resúmenes o seguimientos.
Puede manejar tareas grandes, pero funciona mejor cuando las divides en fases y
usas subagentes para el trabajo en paralelo.
¿Cuáles son los cinco casos de uso cotidianos más importantes de OpenClaw?
Los logros cotidianos generalmente se ven así:
Briefings personales: resúmenes de la bandeja de entrada, el calendario y las noticias que te interesan.
Investigación y redacción: investigaciones rápidas, resúmenes y primeros borradores para correos electrónicos o documentos.
Recordatorios y seguimientos: avisos y listas de verificación impulsados por cron o latidos.
Automatización del navegador: llenar formularios, recopilar datos y repetir tareas web.
Coordinación entre dispositivos: enviar una tarea desde tu teléfono, dejar que el Gateway la ejecute en un servidor y recibir el resultado en el chat.
¿Puede OpenClaw ayudar con la generación de leads, la prospección, los anuncios y los blogs para un SaaS?
Sí para investigación, calificación y redacción. Puede escanear sitios, crear listas cortas,
resumir prospectos y redactar borradores de textos de prospección o anuncios.
Para campañas de prospección o anuncios, mantenga a una persona en el circuito. Evite el spam, cumpla con las leyes locales y
las políticas de la plataforma, y revise todo antes de enviarlo. El patrón más seguro es dejar que
OpenClaw redacte y usted apruebe.
¿Cuáles son las ventajas frente a Claude Code para el desarrollo web?
OpenClaw es un asistente personal y una capa de coordinación, no un reemplazo de IDE. Utilice
Claude Code o Codex para el ciclo de codificación directa más rápido dentro de un repositorio. Use OpenClaw cuando desee
memoria duradera, acceso entre dispositivos y orquestación de herramientas.
Ventajas:
Memoria persistente + espacio de trabajo a través de sesiones
¿Cómo personalizo las habilidades sin ensuciar el repositorio?
Utilice anulaciones administradas en lugar de editar la copia del repositorio. Ponga sus cambios en `~/.openclaw/skills/
/SKILL.md(o añada una carpeta medianteskills.load.extraDirsen~/.openclaw/openclaw.json). La precedencia es
/skills→
/.agents/skills→/.agents/skills→/.openclaw/skills→ integradas →skills.load.extraDirs, por lo que las anulaciones administradas siguen teniendo prioridad sobre las habilidades integradas sin tocar git. Si necesita la habilidad instalada globalmente pero solo visible para algunos agentes, mantenga la copia compartida en ~/.openclaw/skillsy controle la visibilidad conagents.defaults.skillsyagents.list[].skills`. Solo las ediciones dignas de upstream deben residir en el repositorio y salir como PRs.
¿Puedo cargar habilidades desde una carpeta personalizada?
Sí. Añada directorios adicionales mediante skills.load.extraDirs en ~/.openclaw/openclaw.json (menor precedencia). La precedencia predeterminada es `
/skills→
/.agents/skills→/.agents/skills→/.openclaw/skills→ integradas →skills.load.extraDirs. clawhubse instala en./skillsde forma predeterminada, lo cual OpenClaw trata como
/skillsen la siguiente sesión. Si la habilidad solo debe ser visible para ciertos agentes, combínelo conagents.defaults.skillsoagents.list[].skills`.
¿Cómo puedo usar diferentes modelos para diferentes tareas?
Hoy los patrones compatibles son:
Trabajos de Cron: los trabajos aislados pueden establecer una anulación model por trabajo.
Sub-agentes: enrutar tareas a agentes separados con diferentes modelos predeterminados.
Cambio a demanda: usar /model para cambiar el modelo de la sesión actual en cualquier momento.
El bot se congela mientras realiza trabajos pesados. ¿Cómo puedo delegar eso?
Utilice sub-agentes para tareas largas o paralelas. Los sub-agentes se ejecutan en su propia sesión,
devuelven un resumen y mantienen su chat principal receptivo.
Pida a su bot que “genere un sub-agente para esta tarea” o use /subagents.
Use /status en el chat para ver lo que el Gateway está haciendo ahora mismo (y si está ocupado).
Consejo sobre tokens: las tareas largas y los sub-agentes consumen tokens. Si el costo es una preocupación, configure un
modelo más económico para los sub-agentes a través de agents.defaults.subagents.model.
¿Cómo funcionan las sesiones de subagente vinculadas a hilos en Discord?
Utilice enlaces de hilos. Puede vincular un hilo de Discord a un subagente o un objetivo de sesión para que los mensajes de seguimiento en ese hilo permanezcan en esa sesión vinculada.
Flujo básico:
Genere con sessions_spawn usando thread: true (y opcionalmente mode: "session" para un seguimiento persistente).
O vincule manualmente con `/focus
. - Use /agentspara inspeccionar el estado del enlace. - Use/session idle
y/session max-age
para controlar el auto-desenfoque. - Use/unfocus` para desvincular el hilo.
- Sobrescrituras de Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`.
- Auto-vincular al generar: `channels.discord.threadBindings.spawnSessions` se predetermina a `true`; configúrelo en `false` para desactivar la generación de sesiones vinculadas a hilos.
Documentación: [Sub-agentes](/es/tools/subagents), [Discord](/es/channels/discord), [Referencia de configuración](/es/gateway/configuration-reference), [Comandos de barra](/es/tools/slash-commands).
Un subagente finalizó, pero la actualización de finalización fue al lugar equivocado o nunca se publicó. ¿Qué debería verificar?
Verifique primero la ruta del solicitante resuelta:
La entrega de subagente en modo de finalización prefiere cualquier ruta de hilo o conversación vinculada cuando existe una.
Si el origen de la finalización solo lleva 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 tener éxito.
Si no existe ni una ruta vinculada ni una ruta almacenada utilizable, la entrega directa puede fallar y el resultado recurre a la entrega en cola de la sesión en lugar de publicarse inmediatamente en el chat.
Los objetivos inválidos o obsoletos aún pueden forzar la reversión a la cola o el fallo final de la entrega.
Si la última respuesta visible del asistente del hijo es el token silencioso exacto NO_REPLY / no_reply, o exactamente ANNOUNCE_SKIP, OpenClaw suprime intencionalmente el anuncio en lugar de publicar un progreso anterior obsoleto.
Si el hijo agotó el tiempo de espera después de solo llamadas a herramientas, el anuncio puede colapsarlo en un breve resumen de progreso parcial en lugar de reproducir la salida cruda de la herramienta.
Depuración:
Ventana de terminal
openclawtasksshow
Documentación: [Sub-agentes](/es/tools/subagents), [Tareas en segundo plano](/es/automation/tasks), [Herramientas de sesión](/es/concepts/session-tool).
Cron o recordatorios no se ejecutan. ¿Qué debería verificar?
Cron se ejecuta dentro del proceso Gateway. Si el Gateway no se está ejecutando continuamente,
los trabajos programados no se ejecutarán.
Lista de verificación:
Confirme que cron está habilitado (cron.enabled) y OPENCLAW_SKIP_CRON no está establecido.
Verifique que el Gateway se esté ejecutando 24/7 (sin suspensiones/reinicios).
Verifique la configuración de zona horaria para el trabajo (--tz vs zona horaria del host).
Depuración:
Ventana de terminal
openclawcronrun
openclaw cron runs —id
—limit 50
Documentación: [Trabajos de cron](/es/automation/cron-jobs), [Automatización](/es/automation).
Cron se ejecutó, pero no se envió nada al canal. ¿Por qué?
Primero verifique el modo de entrega:
--no-deliver / delivery.mode: "none" significa que no se espera un envío de respaldo (fallback) del ejecutor.
Un objetivo de anuncio (announce) faltante o no válido (channel / to) significa que el ejecutor omitió la entrega saliente.
Fallos de autenticación del canal (unauthorized, Forbidden) significan que el ejecutor intentó entregar pero las credenciales lo bloquearon.
Un resultado aislado silencioso (solo NO_REPLY / no_reply) se trata como intencionalmente no entregable, por lo que el ejecutor también suprime la entrega de respaldo en cola.
Para trabajos cron aislados, el agente aún puede enviar directamente con la herramienta message
cuando hay una ruta de chat disponible. --announce solo controla la ruta de
respaldo del ejecutor para el texto final que el agente aún no ha enviado.
Depuración:
Ventana de terminal
openclawcronruns--id
—limit 50
openclaw tasks show
Documentación: [Trabajos Cron](/es/automation/cron-jobs), [Tareas en segundo plano](/es/automation/tasks).
¿Por qué una ejecución de cron aislada cambió de modelo o reintentó una vez?
Ese suele ser la ruta de cambio de modelo en vivo, no una programación duplicada.
El cron aislado puede persistir un cambio de modelo en tiempo de ejecución y reintentar cuando la ejecución
activa lanza LiveSessionModelSwitchError. El reintento mantiene el proveedor/modelo
cambiado, y si el cambio llevaba una nueva anulación de perfil de autenticación, cron
también la persiste antes de reintentar.
Reglas de selección relacionadas:
La anulación de modelo del enlace de Gmail gana primero cuando es aplicable.
Luego model por trabajo.
Luego cualquier anulación de modelo de sesión de cron almacenada.
Luego la selección normal de modelo de agente/predeterminado.
El bucle de reintento está limitado. Después del intento inicial más 2 reintentos de cambio,
cron aborta en lugar de hacer un bucle infinito.
Depuración:
Ventana de terminal
openclawcronruns--id
—limit 50
openclaw tasks show
Documentación: [Trabajos Cron](/es/automation/cron-jobs), [CLI de cron](/es/cli/cron).
¿Cómo instalo habilidades en Linux?
Use comandos nativos de openclaw skills o coloque habilidades en su espacio de trabajo. La interfaz de usuario de habilidades de macOS no está disponible en Linux.
Explore habilidades en https://clawhub.ai.
¿Puedo ejecutar habilidades exclusivas de Apple macOS desde Linux?
No directamente. Las habilidades de macOS están limitadas por metadata.openclaw.os más los binarios necesarios, y las habilidades solo aparecen en el prompt del sistema cuando son elegibles en el host de Gateway. En Linux, las habilidades exclusivas de darwin (como apple-notes, apple-reminders, things-mac) no se cargarán a menos que anules la limitación.
Tienes tres patrones admitidos:
Opción A: ejecutar el Gateway en una Mac (lo más sencillo).
Ejecuta el Gateway donde existen los binarios de macOS y luego conéctate desde Linux en modo remoto o a través de Tailscale. Las habilidades se cargan normalmente porque el host del Gateway es macOS.
Opción B: usar un nodo macOS (sin SSH).
Ejecuta el Gateway en Linux, empareja un nodo macOS (aplicación de la barra de menús) y establece Node Run Commands (Comandos de ejecución de nodo) en “Always Ask” (Preguntar siempre) o “Always Allow” (Permitir siempre) en la Mac. OpenClaw puede tratar las habilidades exclusivas de macOS como elegibles cuando los binarios necesarios existen en el nodo. El agente ejecuta esas habilidades a través de la herramienta nodes. Si eliges “Preguntar siempre”, aprobar “Permitir siempre” en el prompt añade ese comando a la lista de permitidos.
Opción C: proxy de binarios de macOS a través de SSH (avanzado).
Mantén el Gateway en Linux, pero haz que los binarios de CLI necesarios se resuelvan en envoltorios SSH que se ejecutan en una Mac. Luego anula la habilidad para permitir Linux y que siga siendo elegible.
Crea un envoltorio SSH para el binario (ejemplo: memo para Apple Notes):
#!/usr/bin/env bash
set-euopipefail
execssh-Tuser@mac-host/opt/homebrew/bin/memo"$@"
Coloca el envoltorio en PATH en el host de Linux (por ejemplo ~/bin/memo).
Anula los metadatos de la habilidad (espacio de trabajo o ~/.openclaw/skills) para permitir Linux:
---
name: apple-notes
description: Manage Apple Notes via the memo CLI on macOS.
Inicia una nueva sesión para que se actualice la instantánea de habilidades.
¿Tienes una integración con Notion o HeyGen?
No está integrado de forma nativa hoy en día.
Opciones:
Habilidad / complemento personalizado: es lo mejor para un acceso confiable a la API (tanto Notion como HeyGen tienen APIs).
Automatización del navegador: funciona sin código, pero es más lento y más frágil.
Si deseas mantener el contexto por cliente (flujos de trabajo de agencia), un patrón sencillo es:
Una página de Notion por cliente (contexto + preferencias + trabajo activo).
Pídele al agente que obtenga esa página al inicio de una sesión.
Si deseas una integración nativa, abre una solicitud de función o crea una habilidad
orientada a esas APIs.
Instalar habilidades:
Ventana de terminal
openclawskillsinstall
openclaw skills update —all
Las instalaciones nativas se ubican en el directorio del espacio de trabajo activo `skills/`. Para habilidades compartidas entre todos los agentes locales, usa `openclaw skills install
/SKILL.md). Si solo algunos agentes deben ver una instalación compartida, configura agents.defaults.skillsoagents.list[].skills`. Algunas habilidades esperan binarios instalados a través de Homebrew; en Linux eso significa Linuxbrew (consulta la entrada de FAQ de Homebrew Linux anterior). Consulta Habilidades, Configuración de habilidades y ClawHub.
¿Cómo uso mi Chrome con sesión iniciada existente con OpenClaw?
Usa el perfil de navegador user integrado, que se conecta a través de Chrome DevTools MCP:
Ventana de terminal
openclawbrowser--browser-profileusertabs
openclawbrowser--browser-profileusersnapshot
Si deseas un nombre personalizado, crea un perfil MCP explícito:
Esta ruta puede usar el navegador del host local o un nodo de navegador conectado. Si la Gateway se ejecuta en otro lugar, ejecuta un host de nodo en la máquina del navegador o usa CDP remoto en su lugar.
Límites actuales en existing-session / user:
las acciones están basadas en referencias, no en selectores CSS
las cargas requieren ref / inputRef y actualmente admiten un archivo a la vez
responsebody, exportación de PDF, intercepción de descargas y acciones por lotes aún necesitan un navegador administrado o un perfil CDP sin formato
¿Existe una documentación dedicada sobre el aislamiento (sandboxing)?
Sí. Consulte Sandboxing. Para la configuración específica de Docker (puerta de enlace completa en Docker o imágenes de sandbox), consulte Docker.
Docker se siente limitado: ¿cómo habilito todas las funciones?
La imagen predeterminada prioriza la seguridad y se ejecuta como el usuario node, por lo que no incluye
paquetes del sistema, Homebrew ni navegadores integrados. Para una configuración más completa:
Persista /home/node con OPENCLAW_HOME_VOLUME para que las cachés sobrevivan.
Incorpore dependencias del sistema en la imagen con OPENCLAW_IMAGE_APT_PACKAGES.
Instale los navegadores de Playwright a través de la CLI integrada:
node /app/node_modules/playwright-core/cli.js install chromium
Configure PLAYWRIGHT_BROWSERS_PATH y asegúrese de que la ruta se persista.
¿Puedo mantener los MDs personales pero hacer que los grupos sean públicos/en aislamiento con un solo agente?
Sí, siempre que su tráfico privado sean los MDs y su tráfico público sean los grupos.
Use agents.defaults.sandbox.mode: "non-main" para que las sesiones de grupo/canal (claves no principales) se ejecuten en el backend de aislamiento configurado, mientras que la sesión principal de MDs permanezca en el host. Docker es el backend predeterminado si no elige uno. Luego, restrinja las herramientas disponibles en las sesiones aisladas a través de tools.sandbox.tools.
Establezca agents.defaults.sandbox.docker.binds en ["host:path:mode"] (ej., "/home/user/src:/src:ro"). Los enlaces globales + por agente se fusionan; los enlaces por agente se ignoran cuando scope: "shared". Use :ro para cualquier cosa sensible y recuerde que los enlaces omiten las barreras del sistema de archivos del sandbox.
OpenClaw valida los orígenes de enlace tanto con la ruta normalizada como con la ruta canónica resuelta a través del ancestrio existente más profundo. Eso significa que los escapes de enlace simbólico principal fallan cerrados incluso cuando el último segmento de ruta aún no existe, y las comprobaciones de raíz permitida todavía se aplican después de la resolución del enlace simbólico.
La memoria de OpenClaw son solo archivos Markdown en el espacio de trabajo del agente:
Notas diarias en memory/YYYY-MM-DD.md
Notas curadas a largo plazo en MEMORY.md (solo sesiones principales/privadas)
OpenClaw también ejecuta un flush de memoria de precompactación silenciosa para recordarle al modelo
que escriba notas duraderas antes de la autocompactación. Esto solo se ejecuta cuando el espacio de trabajo
es escribible (los sandboxes de solo lectura lo omiten). Consulte Memory.
La memoria sigue olvidando cosas. ¿Cómo hago que se quede?
Pídale al bot que escriba el hecho en la memoria. Las notas a largo plazo pertenecen a MEMORY.md,
el contexto a corto plazo va en memory/YYYY-MM-DD.md.
Esta es todavía un área que estamos mejorando. Ayuda recordarle al modelo que almacene memorias;
él sabrá qué hacer. Si sigue olvidando, verifique que el Gateway esté usando el mismo
espacio de trabajo en cada ejecución.
¿La memoria persiste para siempre? ¿Cuáles son los límites?
Los archivos de memoria residen en el disco y persisten hasta que los elimine. El límite es su
almacenamiento, no el modelo. El contexto de sesión todavía está limitado por la ventana
de contexto del modelo, por lo que las conversaciones largas pueden compactarse o truncarse. Por eso
existe la búsqueda de memoria: recupera solo las partes relevantes al contexto.
¿La búsqueda de memoria semántica requiere una clave de API de OpenAI?
Solo si usa embeddings de OpenAI. Codex OAuth cubre chat/completions y
no otorga acceso a embeddings, por lo que iniciar sesión con Codex (OAuth o el
inicio de sesión de CLI de Codex) no ayuda para la búsqueda de memoria semántica. Los embeddings de
OpenAI todavía necesitan una clave de API real (OPENAI_API_KEY o models.providers.openai.apiKey).
Si no configura un proveedor explícitamente, OpenClaw selecciona uno automáticamente cuando puede
resolver una clave de API (perfiles de autenticación, models.providers.*.apiKey, o variables de entorno).
Prefiere OpenAI si se resuelve una clave de OpenAI, de lo contrario Gemini si se resuelve una clave de
Gemini, luego Voyage, luego Mistral. Si no hay ninguna clave remota disponible, la búsqueda de
memoria permanece deshabilitada hasta que la configure. Si tiene una ruta de modelo local
configurada y presente, OpenClaw
prefiere local. Ollama es compatible cuando configura explícitamente
memorySearch.provider = "ollama".
Si prefiere mantenerse local, configure memorySearch.provider = "local" (y opcionalmente
memorySearch.fallback = "none"). Si desea embeddings de Gemini, configure
memorySearch.provider = "gemini" y proporcione GEMINI_API_KEY (o
memorySearch.remote.apiKey). Admitimos modelos de embedding OpenAI, Gemini, Voyage, Mistral, Ollama o locales
consulte Memoria para obtener detalles de configuración.
¿Todos los datos utilizados con OpenClaw se guardan localmente?
No - el estado de OpenClaw es local, pero los servicios externos siguen viendo lo que les envías.
Local de forma predeterminada: las sesiones, los archivos de memoria, la configuración y el espacio de trabajo residen en el host del Gateway
(~/.openclaw + tu directorio de espacio de trabajo).
Remoto por necesidad: los mensajes que envías a los proveedores de modelos (Anthropic/OpenAI/etc.) van a
sus API, y las plataformas de chat (WhatsApp/Telegram/Slack/etc.) almacenan los datos de los mensajes en sus
servidores.
Controlas la huella: el uso de modelos locales mantiene las indicaciones (prompts) en tu máquina, pero el tráfico
del canal todavía pasa a través de los servidores del canal.
Todo se encuentra en $OPENCLAW_STATE_DIR (predeterminado: ~/.openclaw):
Ruta
Propósito
$OPENCLAW_STATE_DIR/openclaw.json
Configuración principal (JSON5)
$OPENCLAW_STATE_DIR/credentials/oauth.json
Importación heredada de OAuth (copiada en los perfiles de autenticación en el primer uso)
`$OPENCLAW_STATE_DIR/agents/
/agent/auth-profiles.json| Perfiles de autenticación (OAuth, claves API y opcionalkeyRef/tokenRef) | | $OPENCLAW_STATE_DIR/secrets.json | Carga secreta opcional respaldada en archivo para proveedoresfileSecretRef | |$OPENCLAW_STATE_DIR/agents/
/agent/auth.json | Archivo de compatibilidad heredada (entradas estáticasapi_keydepuradas) | |$OPENCLAW_STATE_DIR/credentials/ | Estado del proveedor (p. ej.whatsapp/
/creds.json) | | $OPENCLAW_STATE_DIR/agents/ | Estado por agente (agentDir + sesiones) | |$OPENCLAW_STATE_DIR/agents/
/sessions/ | Historial y estado de la conversación (por agente) | |$OPENCLAW_STATE_DIR/agents/
/sessions/sessions.json` | Metadatos de la sesión (por agente) |
Ruta heredada de agente único: `~/.openclaw/agent/*` (migrada por `openclaw doctor`).
Su **espacio de trabajo** (AGENTS.md, archivos de memoria, habilidades, etc.) es independiente y se configura a través de `agents.defaults.workspace` (predeterminado: `~/.openclaw/workspace`).
Estos archivos viven en el espacio de trabajo del agente, no en ~/.openclaw.
Espacio de trabajo (por agente): AGENTS.md, SOUL.md, IDENTITY.md, USER.md,
MEMORY.md, memory/YYYY-MM-DD.md, HEARTBEAT.md opcional.
La raíz en minúsculas memory.md es solo entrada de reparación heredada; openclaw doctor --fix
puede fusionarla en MEMORY.md cuando existen ambos archivos.
Directorio de estado (~/.openclaw): configuración, estado del canal/proveedor, perfiles de autenticación, sesiones, registros,
y habilidades compartidas (~/.openclaw/skills).
El espacio de trabajo predeterminado es ~/.openclaw/workspace, configurable vía:
Si el bot “olvida” después de un reinicio, confirme que el Gateway está usando el mismo
espacio de trabajo en cada inicio (y recuerde: el modo remoto usa el espacio de trabajo del host de la puerta de enlace,
no de su computadora portátil local).
Consejo: si desea un comportamiento o preferencia duradero, pídale al bot que lo escriba en
AGENTS.md o MEMORY.md en lugar de confiar en el historial de chat.
Coloque su espacio de trabajo del agente en un repositorio git privado y respáldelo en algún lugar
privado (por ejemplo, GitHub privado). Esto captura la memoria + los archivos AGENTS/SOUL/USER
y le permite restaurar la “mente” del asistente más tarde.
No confirme nada bajo ~/.openclaw (credenciales, sesiones, tokens o cargas útiles de secretos cifrados).
Si necesita una restauración completa, respalde tanto el espacio de trabajo como el directorio de estado
por separado (consulte la pregunta de migración anterior).
¿Pueden los agentes trabajar fuera del espacio de trabajo?
Sí. El espacio de trabajo es el cwd predeterminado y el ancla de memoria, no un espacio aislado estricto.
Las rutas relativas se resuelven dentro del espacio de trabajo, pero las rutas absolutas pueden acceder a otras
ubicaciones del host a menos que se habilite el modo sandbox. Si necesita aislamiento, use
agents.defaults.sandbox o configuraciones de sandbox por agente. Si
desea que un repositorio sea el directorio de trabajo predeterminado, apunte el
workspace de ese agente a la raíz del repositorio. El repositorio de OpenClaw es solo código fuente; mantenga el
espacio de trabajo separado a menos que desee intencionalmente que el agente trabaje dentro de él.
Ejemplo (repositorio como cwd predeterminado):
{
agents: {
defaults: {
workspace: "~/Projects/my-repo",
},
},
}
Modo remoto: ¿dónde está el almacén de sesiones?
El estado de la sesión es propiedad del host de la puerta de enlace. Si está en modo remoto, el almacén de sesiones que le importa está en la máquina remota, no en su portátil local. Consulte Gestión de sesiones.
OpenClaw lee una configuración opcional de JSON5 desde $OPENCLAW_CONFIG_PATH (predeterminado: ~/.openclaw/openclaw.json):
$OPENCLAW_CONFIG_PATH
Si falta el archivo, usa valores predeterminados relativamente seguros (incluyendo un espacio de trabajo predeterminado de ~/.openclaw/workspace).
Establecí gateway.bind: "lan" (o "tailnet") y ahora nada escucha / la interfaz de usuario dice no autorizado
Los enlaces que no son de bucle local requieren una ruta de autenticación de puerta de enlace válida. En la práctica, eso significa:
autenticación de secreto compartido: token o contraseña
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",
},
},
}
Notas:
gateway.remote.token / .passwordno habilitan la autenticación de la puerta de enlace local por sí mismos.
Las rutas de llamadas locales pueden usar gateway.remote.* como alternativa solo cuando gateway.auth.* no está establecido.
Para la autenticación por contraseña, establezca gateway.auth.mode: "password" más gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD) en su lugar.
Si gateway.auth.token / gateway.auth.password está configurado explícitamente a través de SecretRef y sin resolver, la resolución falla cerrada (sin enmascaramiento de alternativa remota).
Las configuraciones de la interfaz de usuario de control con secreto compartido se autentican a través de connect.params.auth.token o connect.params.auth.password (almacenado en la configuración de la aplicación/interfaz). Los modos con identidad, como Tailscale Serve o trusted-proxy, utilizan encabezados de solicitud en su lugar. Evite poner secretos compartidos en URL.
Con gateway.auth.mode: "trusted-proxy", los proxies inversos de bucle local del mismo host requieren gateway.auth.trustedProxy.allowLoopback = true explícito y una entrada de bucle local en gateway.trustedProxies.
¿Por qué necesito un token en localhost ahora?
OpenClaw aplica la autenticación de puerta de enlace de forma predeterminada, incluido el bucle local. En la ruta predeterminada normal, esto significa autenticación por token: si no se configura ninguna ruta de autenticación explícita, el inicio de la puerta de enlace resuelve al modo token y genera un token solo para el tiempo de ejecución para ese inicio, por lo que los clientes WS locales deben autenticarse. Configure gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN o OPENCLAW_GATEWAY_PASSWORD explícitamente cuando los clientes necesiten un secreto estable entre reinicios. Esto bloquea que otros procesos locales llamen a la Gateway.
Si prefieres una ruta de autenticación diferente, puedes elegir explícitamente el modo de contraseña (o, para proxies inversos con conocimiento de identidad, trusted-proxy). Si realmente quieres un bucle local abierto, establece gateway.auth.mode: "none" explícitamente en tu configuración. Doctor puede generar un token para ti en cualquier momento: openclaw doctor --generate-gateway-token.
¿Tengo que reiniciar después de cambiar la configuración?
La Gateway observa la configuración y admite la recarga en caliente (hot-reload):
gateway.reload.mode: "hybrid" (predeterminado): aplica cambios seguros en caliente, reinicia para los críticos
hot, restart, off también son compatibles
¿Cómo desactivo los lemas divertidos de la CLI?
Establezca cli.banner.taglineMode en la configuración:
{
cli: {
banner: {
taglineMode: "off", // random | default | off
},
},
}
off: oculta el texto del lema pero mantiene la línea de título/versión del banner.
default: usa All your chats, one OpenClaw. cada vez.
Si no quieres ningún banner, establece la variable de entorno OPENCLAW_HIDE_BANNER=1.
¿Cómo activo la búsqueda web (y la recuperación web)?
web_fetch funciona sin una clave API. web_search depende del proveedor
que hayas seleccionado:
Los proveedores con API como Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity y Tavily requieren su configuración normal de clave API.
Ollama Web Search no requiere clave, pero utiliza tu host de Ollama configurado y requiere ollama signin.
DuckDuckGo no requiere clave, pero es una integración no oficial basada en HTML.
SearXNG es gratuito/autoalojado; configura SEARXNG_BASE_URL o plugins.entries.searxng.config.webSearch.baseUrl.
Recomendado: ejecuta openclaw configure --section web y elige un proveedor.
Alternativas de entorno:
Brave: BRAVE_API_KEY
Exa: EXA_API_KEY
Firecrawl: FIRECRAWL_API_KEY
Gemini: GEMINI_API_KEY
Grok: XAI_API_KEY
Kimi: KIMI_API_KEY o MOONSHOT_API_KEY
MiniMax Search: MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY o MINIMAX_API_KEY
Perplexity: PERPLEXITY_API_KEY o OPENROUTER_API_KEY
SearXNG: SEARXNG_BASE_URL
Tavily: TAVILY_API_KEY
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
},
},
},
},
},
tools: {
web: {
search: {
enabled: true,
provider: "brave",
maxResults: 5,
},
fetch: {
enabled: true,
provider: "firecrawl", // optional; omit for auto-detect
},
},
},
}
La configuración de búsqueda web específica del proveedor ahora se encuentra en `plugins.entries.
.config.webSearch.. Las rutas de proveedor heredadas tools.web.search.todavía se cargan temporalmente por compatibilidad, pero no se deben usar para configuraciones nuevas. La configuración de recuperación (fetch) alternativa de Firecrawl se encuentra enplugins.entries.firecrawl.config.webFetch.*`.
Notas:
- Si usas listas de permitidos, añade `web_search`/`web_fetch`/`x_search` o `group:web`.
- `web_fetch` está activado por defecto (a menos que se desactive explícitamente).
- Si se omite `tools.web.fetch.provider`, OpenClaw detecta automáticamente el primer proveedor de recuperación (fetch) alternativo listo a partir de las credenciales disponibles. Hoy el proveedor incluido es Firecrawl.
- Los demonios leen las variables de entorno de `~/.openclaw/.env` (o del entorno del servicio).
Documentación: [Web tools](/es/tools/web).
config.apply borró mi configuración. ¿Cómo me recupero y evito esto?
config.apply reemplaza la configuración completa. Si envías un objeto parcial, todo lo demás se elimina.
El OpenClaw actual protege contra muchos sobrescrituras accidentales:
Las escrituras de configuración propiedad de OpenClaw validan la configuración completa posterior al cambio antes de escribir.
Las escrituras inválidas o destructivas propiedad de OpenClaw se rechazan y guardan como openclaw.json.rejected.*.
Si una edición directa rompe el inicio o la recarga en caliente, Gateway falla de forma segura (fails closed) u omite la recarga; no reescribe openclaw.json.
openclaw doctor --fix posee la reparación y puede restaurar el último estado conocido válido mientras guarda el archivo rechazado como openclaw.json.clobbered.*.
Recuperación:
Verifica openclaw logs --follow para ver Invalid config at, Config write rejected: o config reload skipped (invalid config).
Inspecciona el openclaw.json.clobbered.* o openclaw.json.rejected.* más reciente junto a la configuración activa.
Ejecuta openclaw config validate y openclaw doctor --fix.
Copia de vuelta solo las claves deseadas con openclaw config set o config.patch.
Si no tienes un último estado conocido válido ni una carga útil rechazada, restaura desde una copia de seguridad, o vuelve a ejecutar openclaw doctor y reconfigura los canales/modelos.
Si esto fue inesperado, reporta un error e incluye tu última configuración conocida o cualquier copia de seguridad.
Un agente de codificación local a menudo puede reconstruir una configuración funcional a partir de los registros o el historial.
Evitarlo:
Usa openclaw config set para cambios pequeños.
Usa openclaw configure para ediciones interactivas.
Usa config.schema.lookup primero cuando no estés seguro de una ruta exacta o la forma del campo; devuelve un nodo de esquema superficial además de resúmenes de hijos inmediatos para profundizar.
Usa config.patch para ediciones RPC parciales; mantén config.apply solo para el reemplazo completo de la configuración.
Si estás utilizando la herramienta de solo propietario gateway desde una ejecución de agente, aún así rechazará las escrituras en tools.exec.ask / tools.exec.security (incluyendo los alias heredados tools.bash.* que se normalizan a las mismas rutas de ejecución protegidas).
¿Puede ejecutarse el navegador OpenClaw sin interfaz gráfica (headless)?
Sí. Es una opción de configuración:
{
browser: { headless: true },
agents: {
defaults: {
sandbox: { browser: { headless: true } },
},
},
}
El valor predeterminado es false (con interfaz). Es más probable que el modo headless active verificaciones anti-bot en algunos sitios. Consulte Navegador.
El modo headless utiliza el mismo motor Chromium y funciona para la mayor parte de la automatización (formularios, clics, scraping, inicios de sesión). Las principales diferencias son:
Sin ventana de navegador visible (use capturas de pantalla si necesita elementos visuales).
Algunos sitios son más estrictos con la automatización en modo headless (CAPTCHAs, anti-bot).
Por ejemplo, X/Twitter a menudo bloquea las sesiones headless.
¿Cómo uso Brave para el control del navegador?
Establezca browser.executablePath en su binario de Brave (o cualquier navegador basado en Chromium) y reinicie el Gateway.
Vea los ejemplos completos de configuración en Navegador.
¿Cómo se propagan los comandos entre Telegram, el gateway y los nodos?
Los mensajes de Telegram son gestionados por el gateway. El gateway ejecuta el agente y
solo entonces llama a los nodos a través del Gateway WebSocket cuando se necesita una herramienta de nodo:
Los nodos no ven el tráfico entrante del proveedor; solo reciben llamadas RPC de nodo.
¿Cómo puede mi agente acceder a mi ordenador si el Gateway está alojado de forma remota?
Respuesta corta: empareja tu ordenador como un nodo. El Gateway se ejecuta en otro lugar, pero puede
llamar a herramientas node.* (pantalla, cámara, sistema) en tu máquina local a través del Gateway WebSocket.
Configuración típica:
Ejecuta el Gateway en el host siempre activo (VPS/servidor doméstico).
Pon el host del Gateway + tu ordenador en la misma tailnet.
Asegúrate de que el Gateway WS sea accesible (enlace tailnet o túnel SSH).
Abre la aplicación de macOS localmente y conéctate en modo Remote over SSH (o tailnet directa)
para que pueda registrarse como un nodo.
Aprobar el nodo en el Gateway:
Ventana de terminal
openclawdeviceslist
openclawdevicesapprove
No se requiere un puente TCP separado; los nodos se conectan a través del Gateway WebSocket.
Recordatorio de seguridad: emparejar un nodo macOS permite `system.run` en esa máquina. Solo
empareja dispositivos en los que confíes y revisa [Security](/es/gateway/security).
¿Pueden dos instancias de OpenClaw comunicarse entre sí (local + VPS)?
Sí. No hay un puente “bot-a-bot” integrado, pero puedes configurarlo de algunas
formas confiables:
Lo más sencillo: usa un canal de chat normal al que ambos bots puedan acceder (Telegram/Slack/WhatsApp).
Haz que el Bot A envíe un mensaje al Bot B y luego deja que el Bot B responda como de costumbre.
Puente CLI (genérico): ejecuta un script que llame al otro Gateway con
openclaw agent --message ... --deliver, apuntando a un chat donde el otro bot
escuche. Si un bot está en un VPS remoto, apunta tu CLI a ese Gateway remoto
a través de SSH/Tailscale (ver Acceso remoto).
Patrón de ejemplo (ejecutar desde una máquina que pueda alcanzar el Gateway de destino):
Ventana de terminal
openclawagent--message"Hello from local bot"--deliver--channeltelegram--reply-to
Consejo: añade una barrera de protección para que los dos bots no entren en un bucle infinito (solo menciones, listas
de permitidos del canal, o una regla de "no responder a mensajes de bots").
Docs: [Acceso remoto](/es/gateway/remote), [CLI del Agente](/es/cli/agent), [Envío del Agente](/es/tools/agent-send).
¿Necesito VPS separados para múltiples agentes?
No. Un Gateway puede alojar múltiples agentes, cada uno con su propio espacio de trabajo, valores predeterminados de modelo
y enrutamiento. Esa es la configuración normal y es mucho más barata y sencilla que ejecutar
un VPS por agente.
Use VPS separados solo cuando necesite un aislamiento estricto (límites de seguridad) o configuraciones
muy diferentes que no desee compartir. De lo contrario, mantenga un Gateway y
use múltiples agentes o subagentes.
¿Hay algún beneficio en usar un nodo en mi portátil personal en lugar de SSH desde un VPS?
Sí: los nodos son la forma principal de alcanzar su portátil desde una puerta de enlace remota, y
desbloquean más que el acceso a shell. La puerta de enlace funciona en macOS/Linux (Windows a través de WSL2) y es
ligera (un pequeño VPS o una caja de clase Raspberry Pi está bien; 4 GB de RAM son suficientes), por lo que una configuración
común es un host siempre activo más su portátil como nodo.
No se requiere SSH entrante. Los nodos se conectan al WebSocket de la puerta de enlace y usan el emparejamiento de dispositivos.
Controles de ejecución más seguros.system.run está limitado por listas de aprobación/aprobaciones de nodos en ese portátil.
Más herramientas de dispositivo. Los nodos exponen canvas, camera y screen además de system.run.
Automatización del navegador local. Mantenga la puerta de enlace en un VPS, pero ejecute Chrome localmente a través de un host de nodo en el portátil, o adjúntese al Chrome local en el host a través de Chrome MCP.
SSH está bien para el acceso ad-hoc al shell, pero los nodos son más simples para flujos de trabajo de agentes continuos y
automatización de dispositivos.
¿Los nodos ejecutan un servicio de puerta de enlace?
No. Solo se debe ejecutar una puerta de enlace por host a menos que intencionalmente ejecute perfiles aislados (consulte Múltiples puertas de enlace). Los nodos son periféricos que se conectan
a la puerta de enlace (nodos iOS/Android, o macOS “modo nodo” en la aplicación de la barra de menús). Para hosts de nodos sin cabeza
y control CLI, consulte CLI de host de nodo.
Se requiere un reinicio completo para gateway, discovery y cambios en la superficie del plugin alojado.
¿Hay una forma de API/RPC para aplicar la configuración?
Sí.
config.schema.lookup: inspeccionar un subárbol de configuración con su nodo de esquema superficial, sugerencia de interfaz coincidente e resúmenes de hijos inmediatos antes de escribir
config.get: obtener la instantánea actual + hash
config.patch: actualización parcial segura (preferida para la mayoría de ediciones RPC); recarga en caliente cuando es posible y reinicia cuando es requerido
config.apply: validar + reemplazar la configuración completa; recarga en caliente cuando es posible y reinicia cuando es requerido
La herramienta de tiempo de ejecución gateway (solo para el propietario) aún se niega a reescribir tools.exec.ask / tools.exec.security; los alias tools.bash.* heredados se normalizan a las mismas rutas de ejecución protegidas
Configuración mínima sensata para una primera instalación
Si deseas la interfaz de usuario de Control sin SSH, usa Tailscale Serve en el VPS:
Ventana de terminal
openclawgateway--tailscaleserve
Esto mantiene la puerta de enlace vinculada al loopback y expone HTTPS a través de Tailscale. Consulta Tailscale.
¿Cómo conecto un nodo Mac a una puerta de enlace (Gateway) remota (Tailscale Serve)?
Serve expone el UI de Control de Gateway + WS. Los nodos se conectan a través del mismo endpoint WS del Gateway.
Configuración recomendada:
Asegúrese de que el VPS + Mac estén en la misma tailnet.
Use la aplicación macOS en modo Remoto (el destino SSH puede ser el nombre de host de la tailnet).
La aplicación tunelizará el puerto del Gateway y se conectará como un nodo.
Apruebe el nodo en la puerta de enlace:
Ventana de terminal
openclawdeviceslist
openclawdevicesapprove
Documentación: [Protocolo de Gateway](/es/gateway/protocol), [Descubrimiento](/es/gateway/discovery), [modo remoto de macOS](/es/platforms/mac/remote).
¿Debo instalar en un segundo portátil o simplemente agregar un nodo?
Si solo necesita herramientas locales (pantalla/cámara/exec) en el segundo portátil, agréguelo como un
nodo. Eso mantiene un solo Gateway y evita configuración duplicada. Las herramientas de nodo local son
actualmente exclusivas de macOS, pero planeamos extenderlas a otros sistemas operativos.
Instale un segundo Gateway solo cuando necesite aislamiento estricto o dos bots completamente separados.
OpenClaw lee las variables de entorno del proceso principal (shell, launchd/systemd, CI, etc.) y adicionalmente carga:
.env desde el directorio de trabajo actual
un respaldo global .env desde ~/.openclaw/.env (también conocido como $OPENCLAW_STATE_DIR/.env)
Ninguno de los archivos .env anula las variables de entorno existentes.
También puede definir variables de entorno en línea en la configuración (se aplican solo si faltan en el entorno del proceso):
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: { GROQ_API_KEY: "gsk-..." },
},
}
Véase /environment para obtener la precedencia completa y las fuentes.
Inicié la puerta de enlace mediante el servicio y mis variables de entorno desaparecieron. ¿Qué hago?
Dos soluciones comunes:
Coloque las claves faltantes en ~/.openclaw/.env para que se detecten incluso cuando el servicio no herede el entorno de su shell.
Habilite la importación del shell (comodidad opcional):
{
env: {
shellEnv: {
enabled: true,
timeoutMs: 15000,
},
},
}
Esto ejecuta su shell de inicio de sesión e importa solo las claves esperadas faltantes (nunca anula). Equivalentes de variables de entorno:
OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.
Establecí COPILOT_GITHUB_TOKEN, pero el estado de los modelos muestra "Shell env: off." ¿Por qué?
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á
su shell de inicio de sesión automáticamente.
Si la puerta de enlace se ejecuta como un servicio (launchd/systemd), no heredará su entorno
del shell. Solución haciendo una de estas cosas:
Coloque el token en ~/.openclaw/.env:
COPILOT_GITHUB_TOKEN=...
O habilite la importación del shell (env.shellEnv.enabled: true).
O añádalo a su bloque env de configuración (se aplica solo si falta).
Luego reinicie la puerta de enlace y verifique de nuevo:
Envíe /new o /reset como un mensaje independiente. Véase Session management.
¿Las sesiones se reinician automáticamente si nunca envío /new?
Las sesiones pueden expirar después de session.idleMinutes, pero esto está deshabilitado de forma predeterminada (predeterminado 0).
Establézcalo en un valor positivo para habilitar la expiración por inactividad. Cuando está habilitado, el mensaje siguiente
después del periodo de inactividad inicia un nuevo id de sesión para esa clave de chat.
Esto no elimina las transcripciones: simplemente inicia una nueva sesión.
{
session: {
idleMinutes: 240,
},
}
¿Hay alguna forma de crear un equipo de instancias de OpenClaw (un CEO y muchos agentes)?
Sí, a través del enrutamiento multiagente y los subagentes. Puede crear un agente
coordinador y varios agentes trabajadores con sus propios espacios de trabajo y modelos.
Dicho esto, esto es mejor visto como un experimento divertido. Consume muchos tokens y a menudo
es menos eficiente que usar un bot con sesiones separadas. El modelo típico que
imaginamos es un bot con el que hablas, con diferentes sesiones para trabajo paralelo. Ese
bot también puede generar subagentes cuando sea necesario.
¿Por qué se truncó el contexto a mitad de la tarea? ¿Cómo lo evito?
El contexto de la sesión está limitado por la ventana del modelo. Chats largos, salidas de herramientas grandes o muchos
archivos pueden activar la compactación o el truncamiento.
Lo que ayuda:
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 lo lea de nuevo.
Use subagentes para trabajo largo o paralelo para que el chat principal se mantenga más pequeño.
Elija un modelo con una ventana de contexto más grande si esto sucede a menudo.
¿Cómo restablezco completamente OpenClaw pero manteniéndolo instalado?
Use el comando de restablecimiento:
Ventana de terminal
openclawreset
Restablecimiento completo no interactivo:
Ventana de terminal
openclawreset--scopefull--yes--non-interactive
Luego vuelva a ejecutar la configuración:
Ventana de terminal
openclawonboard--install-daemon
Notas:
La incorporación también ofrece Restablecer si detecta una configuración existente. Consulte Onboarding (CLI).
Si usó perfiles (--profile / OPENCLAW_PROFILE), restablezca cada directorio de estado (los predeterminados son `~/.openclaw-
). - Restablecimiento de desarrollo: openclaw gateway —dev —reset` (solo para desarrolladores; borra la configuración de desarrollo + credenciales + sesiones + espacio de trabajo).
Estoy recibiendo errores de "contexto demasiado grande" - ¿cómo restablezco o compacto?
Use uno de estos:
Compactar (mantiene la conversación pero resume los turnos anteriores):
/compact
o `/compact
` para guiar el resumen.
- **Restablecer** (ID de sesión nuevo para la misma clave de chat):
```
/new
/reset
```
Si sigue sucediendo:
- Habilite o ajuste el **recorte de sesiones** (`agents.defaults.contextPruning`) para eliminar el resultado antiguo de las herramientas.
- Use un modelo con una ventana de contexto más grande.
Documentación: [Compactación](/es/concepts/compaction), [Recorte de sesiones](/es/concepts/session-pruning), [Gestión de sesiones](/es/concepts/session).
¿Por qué veo "LLM request rejected: messages.content.tool_use.input field required"?
Este es un error de validación del proveedor: el modelo emitió un bloque tool_use sin el input requerido. Generalmente significa que el historial de la sesión está obsoleto o corrupto (a menudo después de hilos largos o un cambio de herramienta/esquema).
Solución: inicie una sesión nueva con /new (mensaje independiente).
¿Por qué recibo mensajes de latido cada 30 minutos?
Los latidos se ejecutan cada 30m de forma predeterminada (1h al usar autenticación OAuth). Ajusta o desactívalos:
{
agents: {
defaults: {
heartbeat: {
every: "2h", // or "0m" to disable
},
},
},
}
Si HEARTBEAT.md existe pero está efectivamente vacío (solo líneas en blanco y encabezados
de markdown como # Heading), OpenClaw omite la ejecución del latido para ahorrar llamadas a la API.
Si falta el archivo, el latido aún se ejecuta y el modelo decide qué hacer.
Las anulaciones por agente usan agents.list[].heartbeat. Documentación: Heartbeat.
¿Necesito añadir una "cuenta de bot" a un grupo de WhatsApp?
No. OpenClaw se ejecuta en tu propia cuenta, por lo que si estás en el grupo, OpenClaw puede verlo.
De forma predeterminada, las respuestas grupales están bloqueadas hasta que permitas remitentes (groupPolicy: "allowlist").
Si deseas que solo tú puedas activar las respuestas grupales:
{
channels: {
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
¿Cómo obtengo el JID de un grupo de WhatsApp?
Opción 1 (la más rápida): muestra los registros en tiempo real y envía un mensaje de prueba en el grupo:
Ventana de terminal
openclawlogs--follow--json
Busca chatId (o from) que termine en @g.us, como:
[email protected].
Opción 2 (si ya está configurado/en la lista permitida): enumera los grupos desde la configuración:
¿Los grupos/hilos comparten el contexto con los MD?
Los chats directos se colapsan en la sesión principal de forma predeterminada. Los grupos/canales tienen sus propias claves de sesión, y los temas de Telegram / los hilos de Discord son sesiones separadas. Consulte Grupos y Mensajes de grupo.
¿Cuántos espacios de trabajo y agentes puedo crear?
Sin límites estrictos. Docenas (incluso cientos) están bien, pero tenga en cuenta lo siguiente:
Crecimiento del disco: las sesiones y las transcripciones residen en `~/.openclaw/agents/
/sessions/`.
- Costo de tokens: más agentes significan más uso simultáneo del modelo.
- Sobrecarga de operaciones: perfiles de autenticación por agente, espacios de trabajo y enrutamiento de canales.
Consejos:
- Mantenga un espacio de trabajo **activo** por agente (`agents.defaults.workspace`).
- Pode sesiones antiguas (elimine JSONL o entradas de almacenamiento) si el disco crece.
- Use `openclaw doctor` para detectar espacios de trabajo huérfanos y discrepancias de perfil.
¿Puedo ejecutar varios bots o chats al mismo tiempo (Slack) y cómo debo configurarlo?
Sí. Utilice el Enrutamiento Multiagente para ejecutar varios agentes aislados y enrutar los mensajes entrantes por
canal/cuenta/par. Slack es compatible como canal y puede vincularse a agentes específicos.
El acceso del navegador es potente, pero no “hacer cualquier cosa que un humano pueda”; el anti-bot, los CAPTCHAs y la MFA aún pueden
bloquear la automatización. Para el control del navegador más confiable, use Chrome MCP local en el host,
o use CDP en la máquina que realmente ejecuta el navegador.
Configuración de mejores prácticas:
Host de puerta de enlace siempre activo (VPS/Mac mini).
Un agente por rol (vinculaciones).
Canal(es) de Slack vinculados a esos agentes.
Navegador local a través de Chrome MCP o un nodo cuando sea necesario.
Preguntas y respuestas sobre modelos — valores predeterminados, selección, alias, cambio, conmutación por error, perfiles de autenticación —
se encuentran en las Preguntas frecuentes sobre modelos.
Gateway: puertos, “ya se está ejecutando” y modo remoto
¿Por qué el estado de openclaw gateway dice "Runtime: running" (tiempo de ejecución: en ejecución) pero "Connectivity probe: failed" (sondeo de conectividad: fallido)?
Porque “running” es la vista del supervisor (launchd/systemd/schtasks). El sondeo de conectividad es la CLI conectándose realmente al WebSocket de la puerta de enlace.
Use openclaw gateway status y confíe en estas líneas:
Probe target: (la URL que realmente usó el sondeo)
Listening: (lo que realmente está vinculado al puerto)
Last gateway error: (causa raíz común cuando el proceso está vivo pero el puerto no está escuchando)
¿Por qué el estado de openclaw gateway muestra "Config (cli)" y "Config (service)" diferentes?
Está editando un archivo de configuración mientras el servicio está ejecutando otro (a menudo una discrepancia de --profile / OPENCLAW_STATE_DIR).
Solución:
Ventana de terminal
openclawgatewayinstall--force
Ejecute eso desde el mismo --profile / entorno que desee que use el servicio.
¿Qué significa "another gateway instance is already listening" (otra instancia de la puerta de enlace ya está escuchando)?
OpenClaw aplica un bloqueo en tiempo de ejecución vinculando el oyente de WebSocket inmediatamente al inicio (por defecto ws://127.0.0.1:18789). Si la vinculación falla con EADDRINUSE, lanza GatewayLockError indicando que otra instancia ya está escuchando.
Solución: detenga la otra instancia, libere el puerto o ejecute con `openclaw gateway —port
`.
¿Cómo ejecuto OpenClaw en modo remoto (el cliente se conecta a una puerta de enlace en otro lugar)?
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",
},
},
}
Notas:
openclaw gateway solo se inicia cuando gateway.mode es local (o pasas la marca de anulación).
La aplicación de macOS observa el archivo de configuración y cambia los modos en vivo cuando estos valores cambian.
gateway.remote.token / .password son solo credenciales remotas del lado del cliente; no habilitan la autenticación de la puerta de enlace local por sí mismas.
La Interfaz de Control dice "no autorizado" (o sigue reconectando). ¿Qué hacer ahora?
La ruta de autenticación de su puerta de enlace y el método de autenticación de la interfaz no coinciden.
Datos (del código):
La Interfaz de Control mantiene el token en sessionStorage para la sesión actual de la pestaña del navegador y la URL de la puerta de enlace seleccionada, por lo que las actualizaciones en la misma pestaña siguen funcionando sin restaurar la persistencia del token de localStorage a largo plazo.
En AUTH_TOKEN_MISMATCH, los clientes de confianza pueden intentar un reintento limitado con un token de dispositivo en caché cuando la puerta de enlace devuelve sugerencias de reintento (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
Ese reintento de token en caché ahora reutiliza los alcances aprobados en caché almacenados con el token del dispositivo. Los llamadores deviceToken explícitos / scopes explícitos aún mantienen su conjunto de alcances solicitados en lugar de heredar los alcances en caché.
Fuera de esa ruta de reintento, la precedencia de autenticación de conexión es primero token/contraseña compartido explícito, luego deviceToken explícito, luego token de dispositivo almacenado, luego token de arranque.
El arranque del código de configuración integrado es solo para nodos. Después de la aprobación, devuelve un token de dispositivo de nodo con scopes: [] y no devuelve un token de operador transferido.
Solución:
Lo más rápido: openclaw dashboard (imprime + copia la URL del tablero, intenta abrirla; muestra una sugerencia SSH si no tiene interfaz gráfica).
Si aún no tiene un token: openclaw doctor --generate-gateway-token.
Si es remoto, abra un túnel primero: ssh -N -L 18789:127.0.0.1:18789 user@host y luego 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, luego pegue el secreto correspondiente en la configuración de la Interfaz de Control.
Modo Tailscale Serve: asegúrese de que gateway.auth.allowTailscale esté habilitado y de que está abriendo la URL de Serve, no una URL de bucle invertido/tailnet sin procesar que omita los encabezados de identidad de Tailscale.
Modo de proxy de confianza: asegúrese de estar accediendo a través del proxy con reconocimiento de identidad configurado, no a través de una URL de puerta de enlace sin procesar. Los proxies de bucle invertido del mismo host también necesitan gateway.auth.trustedProxy.allowLoopback = true.
Si la discrepancia persiste después del reintento, rote/vuelva a aprobar el token del dispositivo emparejado:
openclaw devices list
`openclaw devices rotate —device
—role operator`
Si esa llamada de rotación dice que fue denegada, verifique dos cosas:
las sesiones de dispositivo emparejado solo pueden rotar su propio dispositivo a menos que también tengan operator.admin
los valores --scope explícitos no pueden exceder los alcances de operador actuales de la persona que llama
¿Sigues atascado? Ejecute openclaw status --all y siga Solución de problemas. Consulte Tablero para obtener detalles de autenticación.
Establecí gateway.bind tailnet pero no puede vincular y nada escucha
tailnet bind elige una IP de Tailscale de sus interfaces de red (100.64.0.0/10). Si la máquina no está en Tailscale (o la interfaz está caída), no hay nada a lo que vincularse.
Solución:
Inicie Tailscale en ese host (para que tenga una dirección 100.x), o
Cambie a gateway.bind: "loopback" / "lan".
Nota: tailnet es explícito. auto prefiere el loopback; use gateway.bind: "tailnet" cuando desee un vinculo exclusivo a tailnet.
¿Puedo ejecutar varios Gateways en el mismo host?
Generalmente no: un Gateway puede ejecutar múltiples canales de mensajería y agentes. Use múltiples Gateways solo cuando necesite redundancia (ej: bot de rescate) o aislamiento estricto.
Sí, pero debe aislar:
OPENCLAW_CONFIG_PATH (configuración por instancia)
OPENCLAW_STATE_DIR (estado por instancia)
agents.defaults.workspace (aislamiento del espacio de trabajo)
gateway.port (puertos únicos)
Configuración rápida (recomendada):
Use `openclaw —profile
…por instancia (crea automáticamente~/.openclaw-
). - Establezca un gateway.portúnico en cada configuración de perfil (o pase—portpara ejecuciones manuales). - Instale un servicio por perfil:openclaw —profile
gateway install`.
Los perfiles también sufijan los nombres de servicio (`ai.openclaw.
¿Qué significa "handshake no válido" / código 1008?
El Gateway es un servidor WebSocket, y espera que el primer mensaje sea
un marco connect. Si recibe cualquier otra cosa, cierra la conexión
con el código 1008 (violación de política).
Causas comunes:
Abrió la URL HTTP en un navegador (http://...) en lugar de un cliente WS.
Usó el puerto o la ruta incorrectos.
Un proxy o túnel eliminó los encabezados de autenticación o envió una solicitud que no es del Gateway.
Soluciones rápidas:
Use la URL WS: `ws://
:18789(owss://…si es HTTPS). 2. No abra el puerto WS en una pestaña normal del navegador. 3. Si la autenticación está activa, incluya el token/contraseña en el marcoconnect`.
Si está usando la CLI o la TUI, la URL debería verse así:
```
openclaw tui --url ws://
:18789 —token
Detalles del protocolo: [Gateway protocol](/es/gateway/protocol).
Puede establecer una ruta estable a través de logging.file. El nivel de registro de archivo se controla mediante logging.level. La verbosidad de la consola se controla mediante --verbose y logging.consoleLevel.
Visualización de registros más rápida:
Ventana de terminal
openclawlogs--follow
Registros de servicio/supervisor (cuando el gateway se ejecuta a través de launchd/systemd):
Error de Telegram setMyCommands. ¿Qué debo comprobar?
Empiece con los registros y el estado del canal:
Ventana de terminal
openclawchannelsstatus
openclawchannelslogs--channeltelegram
Luego compare el error:
BOT_COMMANDS_TOO_MUCH: el menú de Telegram tiene demasiadas entradas. OpenClaw ya recorta hasta el límite de Telegram y reintenta con menos comandos, pero algunas entradas del menú aún deben eliminarse. Reduzca los comandos de complemento/habilidad/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: si está en un VPS o detrás de un proxy, confirme que el HTTPS saliente está permitido y que el DNS funciona para api.telegram.org.
Si el Gateway es remoto, asegúrese de estar mirando los registros en el host del Gateway.
¿Cómo detengo y luego inicio completamente el Gateway?
Si instaló el servicio:
Ventana de terminal
openclawgatewaystop
openclawgatewaystart
Esto detiene/inicia el servicio supervisado (launchd en macOS, systemd en Linux).
Use esto cuando el Gateway se ejecuta en segundo plano como un demonio.
Si se está ejecutando en primer plano, deténgalo con Ctrl-C y luego:
ELI5: reinicio de openclaw gateway vs openclaw gateway
openclaw gateway restart: reinicia el servicio en segundo plano (launchd/systemd).
openclaw gateway: ejecuta el gateway en primer plano para esta sesión de terminal.
Si instalaste el servicio, usa los comandos de gateway. Usa openclaw gateway cuando
quieras una ejecución única en primer plano.
Manera más rápida de obtener más detalles cuando algo falla
Inicia el Gateway con --verbose para obtener más detalles en la consola. Luego inspecciona el archivo de registro en busca de errores de autenticación de canal, enrutamiento de modelo y RPC.
- El canal de destino admite medios salientes y no está bloqueado por listas de permitidos.
- El archivo está dentro de los límites de tamaño del proveedor (las imágenes se redimensionan a un máximo de 2048px).
- `tools.fs.workspaceOnly=true` mantiene los envíos de rutas locales limitados al espacio de trabajo, temp/media-store y archivos validados por el sandbox.
- `tools.fs.workspaceOnly=false` permite que `MEDIA:` envíe archivos locales de host que el agente ya puede leer, pero solo para medios más tipos de documentos seguros (imágenes, audio, video, PDF y documentos de Office). Los archivos de texto plano y similares a secretos todavía están bloqueados.
Trata los MD entrantes como entradas no confiables. Los valores predeterminados están diseñados para reducir el riesgo:
El comportamiento predeterminado en los canales con capacidad de MD es emparejamiento:
Los remitentes desconocidos reciben un código de emparejamiento; el bot no procesa su mensaje.
Aprueba con: `openclaw pairing approve —channel
[—account
]
- Las solicitudes pendientes están limitadas a **3 por canal**; verificaopenclaw pairing list —channel
[—account
] si un código no llegó. - Abrir los MD públicamente requiere optar explícitamente (dmPolicy: “open”y lista blanca”*”`).
Ejecuta `openclaw doctor` para exponer políticas de MD riesgosas.
¿La inyección de comandos (prompt injection) es solo una preocupación para los bots públicos?
No. La inyección de comandos se trata sobre contenido no confiable, no solo sobre quién puede enviar MD al bot.
Si tu asistente lee contenido externo (búsqueda/recuperación web, páginas del navegador, correos electrónicos,
documentos, archivos adjuntos, registros pegados), ese contenido puede incluir instrucciones que intentan
secuestrar el modelo. Esto puede suceder incluso si tú eres el único remitente.
El mayor riesgo ocurre cuando se habilitan las herramientas: el modelo puede ser engañado para
exfiltrar contexto o llamar a herramientas en tu nombre. Reduce el radio de impacto:
usando un agente “lector” de solo lectura o sin herramientas para resumir contenido no confiable
manteniendo web_search / web_fetch / browser desactivado para agentes con herramientas habilitadas
tratando también el texto de archivos/documentos decodificados como no confiable: OpenResponses
input_file y la extracción de archivos adjuntos de medios ambos envuelven el texto extraído en
marcadores de límite de contenido externo explícitos en lugar de pasar el texto sin procesar del archivo
sandboxing y listas blancas estrictas de herramientas
¿Mi bot debería tener su propio correo electrónico, cuenta de GitHub o número de teléfono?
Sí, para la mayoría de las configuraciones. Aislar el bot con cuentas y números de teléfono separados
reduce el radio de impacto si algo sale mal. Esto también facilita la rotación
de credenciales o la revocación del acceso sin afectar tus cuentas personales.
Empieza pequeño. Otorga acceso solo a las herramientas y cuentas que realmente necesites y amplía
más tarde si es necesario.
¿Puedo darle autonomía sobre mis mensajes de texto y es seguro?
No recomendamos la autonomía total sobre tus mensajes personales. El patrón más seguro es:
Mantén los MD en modo de emparejamiento o en una lista blanca estricta.
Usa un número o cuenta separado si quieres que envíe mensajes en tu nombre.
Déjalo redactar y luego aprueba antes de enviar.
Si quieres experimentar, hazlo en una cuenta dedicada y mantenla aislada. Consulta
Seguridad.
¿Puedo usar modelos más baratos para tareas de asistente personal?
Sí, si el agente es solo de chat y la entrada es de confianza. Los niveles más pequeños son más susceptibles al secuestro de instrucciones, así que evítalos para agentes con herramientas habilitadas o al leer contenido que no es de confianza. Si debes usar un modelo más pequeño, restringe las herramientas y ejecútalo dentro de un espacio aislado (sandbox). Consulta
Seguridad.
Ejecuté /start en Telegram pero no recibí un código de emparejamiento
Los códigos de emparejamiento se envían solo cuando un remitente desconocido envía un mensaje al bot y
dmPolicy: "pairing" está habilitado. /start por sí solo no genera un código.
Comprueba las solicitudes pendientes:
Ventana de terminal
openclawpairinglisttelegram
Si quieres acceso inmediato, añade tu ID de remitente a la lista blanca o establece dmPolicy: "open"
para esa cuenta.
WhatsApp: ¿enviará mensajes a mis contactos? ¿Cómo funciona el emparejamiento?
No. La política predeterminada de DM de WhatsApp es emparejamiento. Los remitentes desconocidos solo reciben un código de emparejamiento y su mensaje no se procesa. OpenClaw solo responde a los chats que recibe o a los envíos explícitos que usted activa.
Aprobar el emparejamiento con:
Ventana de terminal
openclawpairingapprovewhatsapp
Listar solicitudes pendientes:
```bash
openclaw pairing list whatsapp
El indicador del número de teléfono del asistente: se usa para configurar su lista de permitidos/propietario para que se permitan sus propios MD. No se usa para el envío automático. Si ejecuta en su número personal de WhatsApp, use ese número y habilite channels.whatsapp.selfChatMode.
Comandos de chat, abortar tareas y “no se detendrá”
¿Cómo evito que los mensajes internos del sistema aparezcan en el chat?
La mayoría de los mensajes internos o de herramientas solo aparecen cuando verbose, trace o reasoning están habilitados
para esa sesión.
Solución en el chat donde lo ve:
/verbose off
/trace off
/reasoning off
Si sigue siendo ruidoso, verifique la configuración de la sesión en la interfaz de usuario de control y establezca verbose
en inherit. También confirme que no está usando un perfil de bot con verboseDefault establecido
en on en la configuración.
La mayoría de los comandos deben enviarse como un mensaje independiente que comienza con /, pero algunos atajos (como /status) también funcionan en línea para remitentes en la lista de permitidos.
¿Cómo envío un mensaje de Discord desde Telegram? ("Cross-context messaging denied")
OpenClaw bloquea la mensajería entre proveedores (cross-provider) de forma predeterminada. Si una llamada a una herramienta está vinculada
a Telegram, no se enviará a Discord a menos que lo permita explícitamente.
Habilite la mensajería entre proveedores para el agente:
Reinicie la puerta de enlace (gateway) después de editar la configuración.
¿Por qué parece que el bot "ignora" los mensajes rápidos?
Por defecto, los indicadores durante la ejecución se dirigen a la ejecución activa. Use /queue para elegir el comportamiento de la ejecución activa:
steer - guiar la ejecución activa en el próximo límite del modelo
followup - poner en cola los mensajes y ejecutarlos uno a uno después de que termine la ejecución actual
collect - poner en cola los mensajes compatibles y responder una vez después de que termine la ejecución actual
interrupt - abortar la ejecución actual y comenzar de nuevo
El modo predeterminado es steer. Puede agregar opciones como debounce:0.5s cap:25 drop:summarize para los modos en cola. Consulte Cola de comandos y Cola de dirección.
¿Cuál es el modelo predeterminado para Anthropic con una clave de API?
En OpenClaw, las credenciales y la selección del modelo son separadas. Establecer ANTHROPIC_API_KEY (o almacenar una clave de API de Anthropic en perfiles de autenticación) habilita la autenticación, pero el modelo predeterminado real es el que configure en agents.defaults.model.primary (por ejemplo, anthropic/claude-sonnet-4-6 o anthropic/claude-opus-4-6). Si ve No credentials found for profile "anthropic:default", significa que la puerta de enlace (Gateway) no pudo encontrar las credenciales de Anthropic en la auth-profiles.json esperada para el agente que se está ejecutando.