Preguntas frecuentes: configuración de primera ejecución

Preguntas y respuestas de inicio rápido y primera ejecución. Para operaciones cotidianas, modelos, autenticación, sesiones y solución de problemas, consulte las preguntas frecuentes principales.

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

Estoy atascado, la forma más rápida de desbloquearse

Utilice un agente de IA local que pueda ver su máquina. Esto es mucho más efectivo que preguntar en Discord, porque la mayoría de los casos “estoy atascado” son problemas de configuración local o del entorno que los ayudantes remotos no pueden inspeccionar.

• Claude Code: https://www.anthropic.com/claude-code/
• OpenAI Codex: https://openai.com/codex/

Estas herramientas pueden leer el repositorio, ejecutar comandos, inspeccionar registros y ayudar a corregir su configuración a nivel de máquina (PATH, servicios, permisos, archivos de autenticación). Déles el código fuente completo mediante la instalación pirateable (git):

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

Esto instala OpenClaw desde una checkout de git, por lo que el agente puede leer el código + los documentos y razonar sobre la versión exacta que está ejecutando. Siempre puede volver a la versión estable más tarde volviendo a ejecutar el instalador sin --install-method git.

Consejo: pida al agente que planifique y supervise la corrección (paso a paso) y luego ejecute solo los comandos necesarios. Esto mantiene los cambios pequeños y facilita su auditoría.

Si descubre un error real o una corrección, por favor abra un issue en GitHub o envíe un PR: https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pulls

Comience con estos comandos (comparta los resultados cuando pida ayuda):

openclaw status
openclaw models status
openclaw doctor

Lo que hacen:

• openclaw status: instantánea rápida del estado de la puerta de enlace/agente + configuración básica.
• openclaw models status: verifica la autenticación del proveedor + disponibilidad del modelo.
• openclaw doctor: valida y repara problemas comunes de configuración/estado.

Otras comprobaciones útiles de CLI: openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose.

Bucle de depuración rápida: Primeros 60 segundos si algo está roto. Documentos de instalación: Instalar, Opciones del instalador, Actualizar.

El latido del corazón (heartbeat) sigue saltándose. ¿Qué significan los motivos de omisión?

Motivos comunes por los que se omite el latido del corazón:

• quiet-hours: fuera de la ventana de horas activas configurada
• empty-heartbeat-file: HEARTBEAT.md existe pero solo contiene scaffolding en blanco o solo con encabezados
• no-tasks-due: el modo de tarea HEARTBEAT.md está activo pero aún no vence ninguno de los intervalos de tarea
• alerts-disabled: toda la visibilidad del latido del corazón está deshabilitada (showOk, showAlerts y useIndicator están desactivados)

En el modo de tarea, las marcas de tiempo de vencimiento solo avanzan después de que se completa una ejecución real del latido del corazón. Las ejecuciones omitidas no marcan las tareas como completadas.

Documentación: Latido del corazón, Automatización.

Forma recomendada de instalar y configurar OpenClaw

El repositorio recomienda ejecutar desde el código fuente y usar la incorporación (onboarding):

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

El asistente también puede crear los activos de la interfaz de usuario automáticamente. Después de la incorporación, generalmente ejecutas el Gateway en el puerto 18789.

Desde el código fuente (colaboradores/desarrolladores):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard

Si aún no tienes una instalación global, ejecútalo a través de pnpm openclaw onboard.

¿Cómo abro el panel después de la incorporación?

El asistente abre tu navegador con una URL del panel limpia (sin token) justo después de la incorporación y también imprime el enlace en el resumen. Mantén esa pestaña abierta; si no se lanzó, copia y pega la URL impresa en la misma máquina.

¿Cómo autentico el tablero en localhost versus remoto?

Localhost (misma máquina):

• Abra http://127.0.0.1:18789/.
• Si solicita autenticación de secreto compartido, pegue el token o contraseña configurado en la configuración de Control UI.
• Fuente del token: gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN).
• Fuente de la contraseña: gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
• Si aún no se ha configurado un secreto compartido, genere un token con openclaw doctor --generate-gateway-token.

No en localhost:

• Tailscale Serve (recomendado): mantenga el enlace loopback, ejecute openclaw gateway --tailscale serve, abra `https://

/. Si gateway.auth.allowTailscaleestrue, los encabezados de identidad satisfacen la autenticación de Control UI/WebSocket (sin secreto compartido pegado, asume host de puerta de enlace confiable); las API HTTP aún requieren autenticación de secreto compartido a menos que use deliberadamente private-ingress noneo autenticación HTTP de proxy confiable. Los intentos de autenticación Serve concurrentes incorrectos del mismo cliente se serializan antes de que el limitador de autenticaciones fallidas los registre, por lo que el segundo reintento incorrecto ya puede mostrarretry later. - **Tailnet bind**: ejecute openclaw gateway —bind tailnet —token ”

“(o configure la autenticación por contraseña), abrahttp://

:18789/, luego pegue el secreto compartido correspondiente en la configuración del tablero. - **Proxy inverso con reconocimiento de identidad**: mantenga la puerta de enlace detrás de un proxy confiable, configure gateway.auth.mode: “trusted-proxy”, luego abra la URL del proxy. Los proxies loopback del mismo host requieren gateway.auth.trustedProxy.allowLoopback = trueexplícito. - **Túnel SSH**:ssh -N -L 18789:127.0.0.1:18789 user@hosty luego abrahttp://127.0.0.1:18789/`. La autenticación de secreto compartido aún se aplica a través del túnel; pegue el token o contraseña configurado si se le solicita.

Consulte [Dashboard](/es/web/dashboard) y [Web surfaces](/es/web) para conocer los modos de enlace y detalles de autenticación.

¿Por qué hay dos configuraciones de aprobación de ejecución para aprobaciones de chat?

Controlan diferentes capas:

• approvals.exec: reenvía las solicitudes de aprobación a los destinos de chat
• `channels.

.execApprovals`: hace que ese canal actúe como un cliente de aprobación nativo para aprobaciones de ejecución

La política de ejecución del host sigue siendo la puerta real de aprobación. La configuración del chat solo controla dónde aparecen las solicitudes de aprobación y cómo las personas pueden responderlas.

En la mayoría de configuraciones **no** necesitas ambas:

- Si el chat ya admite comandos y respuestas, el `/approve` del mismo chat funciona a través de la ruta compartida.
- Si un canal nativo compatible puede inferir los aprobadores de forma segura, OpenClaw ahora habilita automáticamente las aprobaciones nativas优先 por mensaje directo cuando `channels.

.execApprovals.enabledno está establecido o”auto”. - Cuando están disponibles las tarjetas/botones de aprobación nativa, esa interfaz de usuario nativa es la ruta principal; el agente solo debe incluir un comando manual /approvesi el resultado de la herramienta indica que las aprobaciones de chat no están disponibles o la aprobación manual es la única ruta. - Usaapprovals.execsolo cuando las solicitudes también deban reenviarse a otros chats o salas de operaciones explícitas. - Usachannels.

.execApprovals.target: “channel”o”both”solo cuando explícitamente desees que las solicitudes de aprobación se publiquen de nuevo en la sala/tema de origen. - Las aprobaciones de complementos son separadas nuevamente: usan/approvedel mismo chat de forma predeterminada, reenvíoapprovals.plugin` opcional, y solo algunos canales nativos mantienen el manejo nativo de aprobaciones de complementos activo.

Versión corta: el reenvío es para enrutamiento, la configuración del cliente nativo es para una experiencia de usuario específica del canal más rica.
Consulta [Exec Approvals](/es/tools/exec-approvals).

¿Qué tiempo de ejecución necesito?

Se requiere Node >= 22. Se recomienda pnpm. No se recomienda Bun para el Gateway.

¿Funciona en Raspberry Pi?

Sí. Gateway es ligero: la documentación indica 512MB-1GB de RAM, 1 núcleo y unos 500MB de disco como suficientes para uso personal, y tenga en cuenta que una Raspberry Pi 4 puede ejecutarlo.

Si desea margen adicional (registros, medios, otros servicios), se recomiendan 2GB, pero no es un mínimo estricto.

Consejo: una pequeña Raspberry Pi/VPS puede alojar el Gateway, y puede emparejar nodos en su portátil/teléfono para pantalla local/cámara/lienzo o ejecución de comandos. Consulte Nodos.

¿Algún consejo para instalaciones en Raspberry Pi?

Versión corta: funciona, pero espere algunos problemas.

• Use un sistema operativo de 64 bits y mantenga Node >= 22.
• Prefiera la instalación pirateable (git) para poder ver los registros y actualizar rápidamente.
• Comience sin canales/habilidades, luego agréguelos uno por uno.
• Si encuentra problemas binarios extraños, generalmente es un problema de compatibilidad ARM.

Documentación: Linux, Instalación.

Está atascado en wake up my friend / onboarding no se iniciará. ¿Qué ahora?

Esa pantalla depende de que Gateway sea accesible y esté autenticado. La TUI también envía “¡Despierta, amigo!” automáticamente en el primer inicio. Si ve esa línea con sin respuesta y los tokens se mantienen en 0, el agente nunca se ejecutó.

1. Reinicie Gateway:

openclaw gateway restart

2. Verifique estado + auth:

openclaw status
openclaw models status
openclaw logs --follow

3. Si aún se cuelga, ejecute:

openclaw doctor

Si Gateway es remoto, asegúrese de que la conexión del túnel/Tailscale esté activa y que la interfaz de usuario apunte al Gateway correcto. Consulte Acceso remoto.

¿Puedo migrar mi configuración a una nueva máquina (Mac mini) sin repetir la incorporación?

Sí. Copie el directorio de estado y el espacio de trabajo, y luego ejecute Doctor una vez. Esto mantiene su bot “exactamente igual” (memoria, historial de sesiones, autenticación y estado del canal) siempre que copie ambas ubicaciones:

1. Instale OpenClaw en la nueva máquina.
2. Copie $OPENCLAW_STATE_DIR (predeterminado: ~/.openclaw) de la máquina antigua.
3. Copie su espacio de trabajo (predeterminado: ~/.openclaw/workspace).
4. Ejecute openclaw doctor y reinicie el servicio Gateway.

Eso preserva la configuración, los perfiles de autenticación, las credenciales de WhatsApp, las sesiones y la memoria. Si está en modo remoto, recuerde que el host de la puerta de enlace es el propietario del almacén de sesiones y del espacio de trabajo.

Importante: si solo confirma/envía su espacio de trabajo a GitHub, está haciendo una copia de seguridad de memoria + archivos de arranque, pero no del historial de sesiones ni de la autenticación. Estos residen en ~/.openclaw/ (por ejemplo, `~/.openclaw/agents/

/sessions/`).

Relacionado: [Migración](/es/install/migrating), [Dónde residen las cosas en el disco](/es/help/faq#where-things-live-on-disk),
[Espacio de trabajo del agente](/es/concepts/agent-workspace), [Doctor](/es/gateway/doctor),
[Modo remoto](/es/gateway/remote).

¿Dónde puedo ver las novedades de la última versión?

Consulte el registro de cambios de GitHub: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

Las entradas más recientes están en la parte superior. Si la sección superior está marcada como Unreleased, la siguiente sección con fecha es la última versión enviada. Las entradas se agrupan en Highlights, Changes y Fixes (más secciones de documentos/otras cuando sea necesario).

No se puede acceder a docs.openclaw.ai (error SSL)

Algunas conexiones de Comcast/Xfinity bloquean incorrectamente docs.openclaw.ai a través de Xfinity Advanced Security. Desactívelo o añada docs.openclaw.ai a la lista de permitidos, luego inténtelo de nuevo. Por favor, ayúdenos a desbloquearlo informando aquí: https://spa.xfinity.com/check_url_status.

Si aún no puede acceder al sitio, los documentos están reflejados en GitHub: https://github.com/openclaw/openclaw/tree/main/docs

Diferencia entre stable y beta

Stable (estable) y beta son npm dist-tags, no líneas de código separadas:

• latest = estable
• beta = compilación temprana para pruebas

Por lo general, un lanzamiento estable llega primero a beta y luego un paso de promoción explícito mueve esa misma versión a latest. Los mantenedores también pueden publicar directamente en latest cuando sea necesario. Por eso beta y stable pueden apuntar a la misma versión después de la promoción.

Consulte qué cambió: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

Para frases de instalación de una sola línea y la diferencia entre beta y dev, consulte el acordeón de abajo.

¿Cómo instalo la versión beta y cuál es la diferencia entre beta y dev?

Beta es la etiqueta de distribución de npm (dist-tag) beta (puede coincidir con latest después de la promoción). Dev es la cabecera móvil de main (git); cuando se publica, usa la etiqueta de distribución de npm dev.

Frases de una sola línea (macOS/Linux):

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

Instalador de Windows (PowerShell): https://openclaw.ai/install.ps1

Más detalles: Canales de desarrollo y Marcas del instalador.

¿Cómo pruebo las últimas novedades?

Dos opciones:

1. Canal Dev (git checkout):

openclaw update --channel dev

Esto cambia a la rama main y actualiza desde la fuente.

2. Instalación Hackable (desde el sitio del instalador):

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

Eso le da un repositorio local que puede editar y luego actualizar a través de git.

Si prefiere hacer una clonación limpia manualmente, use:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build

Documentación: Actualizar, Canales de desarrollo, Instalación.

¿Cuánto tiempo suele tardar la instalación y la incorporación?

Guía aproximada:

• Instalación: 2-5 minutos
• Incorporación: 5-15 minutos dependiendo de cuántos canales/modelos configures

Si se cuelga, usa Instalador atascado y el bucle de depuración rápida en Estoy atascado.

¿Instalador atascado? ¿Cómo obtengo más comentarios?

Vuelve a ejecutar el instalador con salida detallada:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

Instalación beta con modo detallado:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose

Para una instalación modificable (git):

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose

Equivalente en Windows (PowerShell):

# install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

Más opciones: Opciones del instalador.

La instalación en Windows dice que no se encontró git o que no se reconoce openclaw

Dos problemas comunes en Windows:

1) error de npm spawn git / git no encontrado

• Instala Git para Windows y asegúrate de que git esté en tu PATH.
• Cierra y vuelve a abrir PowerShell, luego vuelve a ejecutar el instalador.

2) openclaw no se reconoce después de la instalación

• Tu carpeta bin global de npm no está en el PATH.

• Verifica la ruta:

  npm config get prefix

• Añade ese directorio a tu PATH de usuario (no se necesita sufijo \bin en Windows; en la mayoría de los sistemas es %AppData%\npm).

• Cierra y vuelve a abrir PowerShell después de actualizar el PATH.

Si quieres la configuración de Windows más fluida, usa WSL2 en lugar de Windows nativo. Documentación: Windows.

La salida del ejecutable de Windows muestra texto chino ilegible, ¿qué debo hacer?

Esto suele ser una discrepancia en la página de códigos de la consola en los shells nativos de Windows.

Síntomas:

• La salida de system.run/exec muestra el chino como mojibake
• El mismo comando se ve bien en otro perfil de terminal

Solución rápida en PowerShell:

chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

Luego reinicie el Gateway y reintente su comando:

openclaw gateway restart

Si aún reproduce esto en la última versión de OpenClaw, realice un seguimiento o reporte en:

• Issue #30640

La documentación no respondió a mi pregunta: ¿cómo obtengo una mejor respuesta?

Utilice la instalación hackable (git) para tener el código fuente y la documentación completa localmente, luego pregunte a su bot (o Claude/Codex) desde esa carpeta para que pueda leer el repositorio y responder con precisión.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

Más detalles: Instalación y Opciones del instalador.

¿Cómo instalo OpenClaw en Linux?

Respuesta corta: siga la guía de Linux y luego ejecute la incorporación (onboarding).

• Ruta rápida en Linux + instalación del servicio: Linux.
• Tutorial completo: Comenzando.
• Instalador + actualizaciones: Instalación y actualizaciones.

¿Cómo instalo OpenClaw en un VPS?

Cualquier VPS de Linux funciona. Instale en el servidor y luego use SSH/Tailscale para acceder al Gateway.

Guías: exe.dev, Hetzner, Fly.io. Acceso remoto: Gateway remoto.

¿Dónde están las guías de instalación en la nube/VPS?

Mantenemos un centro de alojamiento con los proveedores comunes. Elige uno y sigue la guía:

• Alojamiento VPS (todos los proveedores en un solo lugar)
• Fly.io
• Hetzner
• exe.dev

Cómo funciona en la nube: el Gateway se ejecuta en el servidor y tú accedes a él desde tu portátil/teléfono mediante la interfaz de Control (o Tailscale/SSH). Tu estado + espacio de trabajo residen en el servidor, así que trata el host como la fuente de verdad y haz copias de seguridad.

Puedes emparejar nodos (Mac/iOS/Android/headless) con ese Gateway en la nube para acceder a la pantalla/cámara/lienzo local o ejecutar comandos en tu portátil mientras mantienes el Gateway en la nube.

Centro: Plataformas. Acceso remoto: Gateway remoto. Nodos: Nodos, CLI de Nodos.

¿Puedo pedirle a OpenClaw que se actualice a sí mismo?

Respuesta corta: posible, no recomendado. El flujo de actualización puede reiniciar el Gateway (lo que interrumpe la sesión activa), puede necesitar una comprobación git limpia y puede pedir confirmación. Más seguro: ejecuta las actualizaciones desde un shell como operador.

Usa la CLI:

openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag

openclaw update —no-restart

Si debes automatizarlo desde un agente:

```bash
openclaw update --yes --no-restart
openclaw gateway restart

Documentación: Actualizar, Actualización.

¿Qué hace realmente la incorporación?

openclaw onboard es la ruta de configuración recomendada. En modo local te guía a través de:

• Configuración de modelo/autenticación (OAuth del proveedor, claves API, token de configuración de Anthropic, además de opciones de modelos locales como LM Studio)
• Ubicación del espacio de trabajo + archivos de inicio
• Configuración del Gateway (bind/puerto/auth/tailscale)
• Canales (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, además de complementos de canal incluidos como QQ Bot)
• Instalación del Demonio (LaunchAgent en macOS; unidad de usuario systemd en Linux/WSL2)
• Verificaciones de estado y selección de habilidades

También advierte si tu modelo configurado es desconocido o le falta autenticación.

¿Necesito una suscripción a Claude u OpenAI para ejecutar esto?

No. Puedes ejecutar OpenClaw con claves de API (Anthropic/OpenAI/u otras) o con modelos solo locales para que tus datos permanezcan en tu dispositivo. Las suscripciones (Claude Pro/Max u OpenAI Codex) son formas opcionales de autenticar esos proveedores.

Para Anthropic en OpenClaw, la división práctica es:

• Clave de API de Anthropic: facturación normal de la API de Anthropic
• CLI de Claude / autenticación de suscripción Claude en OpenClaw: el personal de Anthropic nos dijo que este uso está permitido nuevamente, y OpenClaw está tratando el uso de claude -p como sancionado para esta integración a menos que Anthropic publique una nueva política

Para hosts de pasarela de larga duración, las claves de API de Anthropic siguen siendo la configuración más predecible. El OAuth de OpenAI Codex es explícitamente compatible con herramientas externas como OpenClaw.

OpenClaw también admite otras opciones de estilo de suscripción alojadas, incluyendo Plan de codificación en la nube de Qwen, Plan de codificación de MiniMax y Plan de codificación de Z.AI / GLM.

Documentos: Anthropic, OpenAI, Qwen Cloud, MiniMax, Z.AI (GLM), Modelos locales, Modelos.

¿Puedo usar la suscripción Claude Max sin una clave de API?

Sí.

El personal de Anthropic nos indicó que el uso de la CLI de Claude al estilo OpenClaw está permitido nuevamente, por lo que OpenClaw trata la autenticación por suscripción de Claude y el uso de claude -p como autorizados para esta integración a menos que Anthropic publique una nueva política. Si desea la configuración del lado del servidor más predecible, utilice una clave de API de Anthropic en su lugar.

¿Admites la autenticación de suscripción de Claude (Claude Pro o Max)?

Sí.

El personal de Anthropic nos dijo que este uso está permitido nuevamente, por lo que OpenClaw trata el reuso de la CLI de Claude y el uso de claude -p como sancionados para esta integración a menos que Anthropic publique una nueva política.

El token de configuración de Anthropic todavía está disponible como una ruta de token compatible con OpenClaw, pero ahora OpenClaw prefiere el reuso de la CLI de Claude y claude -p cuando está disponible. Para cargas de trabajo de producción o multiusuario, la autenticación con clave de API de Anthropic sigue siendo la opción más segura y predecible. Si deseas otras opciones alojadas de estilo de suscripción en OpenClaw, consulta OpenAI, Qwen / Model Cloud, MiniMax y Modelos GLM.

¿Por qué veo el error rate_limit_error HTTP 429 de Anthropic?

Eso significa que su límite de cuota/tasa de Anthropic se ha agotado para la ventana actual. Si utiliza Claude CLI, espere a que la ventana se restablezca o actualice su plan. Si utiliza una clave de API de Anthropic, verifique la Consola de Anthropic para el uso/facturación y aumente los límites según sea necesario.

Si el mensaje es específicamente: Extra usage is required for long context requests, la solicitud está intentando usar la ventana de contexto de 1M de Anthropic (un modelo Claude 4.x con capacidad GA de 1M o una configuración heredada context1m: true). Eso solo funciona cuando sus credenciales son elegibles para la facturación de contexto largo (facturación por clave de API o la ruta de inicio de sesión de Claude de OpenClaw con Uso Extra habilitado).

Consejo: configure un modelo alternativo para que OpenClaw pueda seguir respondiendo mientras un proveedor tiene limitada su tasa. Vea Modelos, OAuth y /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

¿Está soportado AWS Bedrock?

Sí. OpenClaw tiene un proveedor Amazon Bedrock (Converse) incluido. Con los marcadores de entorno de AWS presentes, OpenClaw puede descubrir automáticamente el catálogo de Bedrock de transmisión/texto y fusionarlo como un proveedor implícito amazon-bedrock; de lo contrario, puede habilitar explícitamente plugins.entries.amazon-bedrock.config.discovery.enabled o agregar una entrada de proveedor manual. Vea Amazon Bedrock y Proveedores de modelos. Si prefiere un flujo de clave administrada, un proxy compatible con OpenAI frente a Bedrock sigue siendo una opción válida.

¿Cómo funciona la autenticación de Codex?

OpenClaw admite OpenAI Code (Codex) a través de OAuth (inicio de sesión de ChatGPT). Use openai/gpt-5.5 para la configuración común: autenticación de suscripción ChatGPT/Codex más ejecución nativa del servidor de aplicaciones Codex. Las referencias heredadas de GPT de Codex son configuración heredada reparada por openclaw doctor --fix. El acceso directo con clave de API de OpenAI permanece disponible para superficies de API de OpenAI que no son de agentes y para modelos de agentes a través de un perfil de clave de API ordenado openai. Consulte Proveedores de modelos y Incorporación (CLI).

¿Por qué OpenClaw todavía menciona el prefijo heredado de OpenAI Codex?

openai es el identificador del proveedor y del perfil de autenticación tanto para las claves de API de OpenAI como para OAuth de ChatGPT/Codex. Todavía puede ver el prefijo heredado de OpenAI Codex en la configuración heredada y advertencias de migración. Las configuraciones más antiguas también lo usaban como prefijo de modelo:

• openai/gpt-5.5 = autenticación de suscripción ChatGPT/Codex con tiempo de ejecución nativo de Codex para turnos de agente
• referencia heredada de GPT-5.5 de Codex = ruta de modelo heredada reparada por openclaw doctor --fix
• openai/gpt-5.5 más un perfil de clave de API ordenado openai = autenticación con clave de API para un modelo de agente OpenAI
• identificadores de perfil de autenticación heredados de Codex = identificador de perfil de autenticación heredado migrado por openclaw doctor --fix

Si desea la ruta directa de facturación/límite de la plataforma OpenAI, configure OPENAI_API_KEY. Si desea la autenticación de suscripción ChatGPT/Codex, inicie sesión con openclaw models auth login --provider openai. Mantenga la referencia del modelo como openai/gpt-5.5; las referencias de modelos heredados de Codex son configuración heredada que openclaw doctor --fix reescribe.

¿Por qué los límites de OAuth de Codex pueden diferir de los de ChatGPT web?

Codex OAuth utiliza ventanas de cuota gestionadas por OpenAI y dependientes del plan. En la práctica, esos límites pueden diferir de la experiencia del sitio web/aplicación de ChatGPT, incluso cuando ambos están vinculados a la misma cuenta.

OpenClaw puede mostrar las ventanas de uso/cuota del proveedor actualmente visibles en openclaw models status, pero no inventa ni normaliza los derechos de acceso de ChatGPT-web en acceso directo a la API. Si desea la ruta directa de facturación/límites de la plataforma de OpenAI, use openai/* con una clave de API.

¿Admite la autenticación de suscripción de OpenAI (Codex OAuth)?

Sí. OpenClaw es totalmente compatible con OAuth de suscripción a OpenAI Code (Codex). OpenAI permite explícitamente el uso de OAuth de suscripción en herramientas/flujos de trabajo externos como OpenClaw. El proceso de incorporación puede ejecutar el flujo de OAuth por usted.

Consulte OAuth, Proveedores de modelos y Incorporación (CLI).

¿Cómo configuro OAuth de Gemini CLI?

Gemini CLI utiliza un flujo de autenticación de complemento, no un id de cliente o secreto en openclaw.json.

Pasos:

1. Instale Gemini CLI localmente para que gemini esté en PATH
   • Homebrew: brew install gemini-cli
   • npm: npm install -g @google/gemini-cli
2. Habilite el complemento: openclaw plugins enable google
3. Inicie sesión: openclaw models auth login --provider google-gemini-cli --set-default
4. Modelo predeterminado después del inicio de sesión: google-gemini-cli/gemini-3-flash-preview
5. Si las solicitudes fallan, configure GOOGLE_CLOUD_PROJECT o GOOGLE_CLOUD_PROJECT_ID en el host de la puerta de enlace

Esto almacena los tokens de OAuth en perfiles de autenticación en el host de la puerta de enlace. Detalles: Proveedores de modelos.

¿Está bien un modelo local para chats casuales?

Por lo general no. OpenClaw necesita un contexto grande + una seguridad sólida; las tarjetas pequeñas truncan y filtran. Si es necesario, ejecute la compilación del modelo más grande que pueda localmente (LM Studio) y consulte /gateway/local-models. Los modelos más pequeños/cuantizados aumentan el riesgo de inyección de avisos (prompt-injection) - consulte Seguridad.

¿Cómo mantengo el tráfico del modelo alojado en una región específica?

Elija endpoints anclados a la región. OpenRouter expone opciones alojadas en EE. UU. para MiniMax, Kimi y GLM; elija la variante alojada en EE. UU. para mantener los datos en la región. Aún puede listar Anthropic/OpenAI junto a estos usando models.mode: "merge" para que las alternativas (fallbacks) permanezcan disponibles mientras respeta el proveedor regional que seleccione.

¿Tengo que comprar un Mac Mini para instalar esto?

No. OpenClaw se ejecuta en macOS o Linux (Windows vía WSL2). Un Mac mini es opcional: algunas personas compran uno como un host siempre activo, pero un VPS pequeño, un servidor doméstico o una caja clase Raspberry Pi también funciona.

Solo necesita una Mac para herramientas exclusivas de macOS. Para iMessage, use iMessage con imsg en cualquier Mac conectado a Messages. Si la Gateway se ejecuta en Linux o en otro lugar, configure channels.imessage.cliPath en un contenedor SSH que ejecute imsg en ese Mac. Si desea otras herramientas exclusivas de macOS, ejecute la Gateway en una Mac o empareje un nodo macOS.

Documentación: iMessage, Nodos, Modo remoto Mac.

¿Necesito un Mac mini para la compatibilidad con iMessage?

Necesita algún dispositivo macOS iniciado en Messages. No tiene por qué ser un Mac mini - cualquier Mac funciona. Use iMessage con imsg; el Gateway puede ejecutarse en ese Mac, o puede ejecutarse en otro lugar con un contenedor SSH cliPath.

Configuraciones comunes:

• Ejecute el Gateway en Linux/VPS y configure channels.imessage.cliPath en un contenedor SSH que ejecute imsg en un Mac iniciado en Messages.
• Ejecute todo en el Mac si desea la configuración de máquina única más sencilla.

Documentación: iMessage, Nodos, Modo remoto de Mac.

Si compro un Mac mini para ejecutar OpenClaw, ¿puedo conectarlo a mi MacBook Pro?

Sí. El Mac mini puede ejecutar el Gateway y su MacBook Pro puede conectarse como un nodo (dispositivo complementario). Los nodos no ejecutan el Gateway; proporcionan capacidades adicionales como pantalla/cámara/lienzo y system.run en ese dispositivo.

Patrón común:

• Gateway en el Mac mini (siempre activo).
• MacBook Pro ejecuta la aplicación macOS o un host de nodo y se empareja con el Gateway.
• Use openclaw nodes status / openclaw nodes list para verlo.

Documentación: Nodos, CLI de Nodos.

¿Puedo usar Bun?

Bun no está recomendado. Vemos errores de tiempo de ejecución, especialmente con WhatsApp y Telegram. Usa Node para gateways estables.

Si aún quieres experimentar con Bun, hazlo en un gateway que no sea de producción sin WhatsApp/Telegram.

Telegram: what goes in allowFrom?

channels.telegram.allowFrom es el ID de usuario de Telegram del remitente humano (numérico). No es el nombre de usuario del bot.

La configuración solicita solo IDs de usuario numéricos. Si ya tienes entradas @username heredadas en la configuración, openclaw doctor --fix puede intentar resolverlas.

Más seguro (sin bot de terceros):

• Envía un mensaje privado a tu bot, luego ejecuta openclaw logs --follow y lee from.id.

Bot API oficial:

• Envía un mensaje privado a tu bot, luego llama a `https://api.telegram.org/bot

/getUpdatesy leemessage.from.id`.

Terceros (menos privado):

- Envía un mensaje privado a `@userinfobot` o `@getidsbot`.

Consulte [/channels/telegram](/es/channels/telegram#access-control-and-activation).

Can multiple people use one WhatsApp number with different OpenClaw instances?

Sí, a través del enrutamiento multiagente. Vincule el mensaje directo de WhatsApp de cada remitente (par kind: "direct", remitente E.164 como +15551234567) a un agentId diferente, para que cada persona obtenga su propio espacio de trabajo y almacén de sesiones. Las respuestas aún provienen de la misma cuenta de WhatsApp, y el control de acceso de mensajes directos (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) es global por cuenta de WhatsApp. Consulte Enrutamiento multiagente y WhatsApp.

Can I run a "fast chat" agent and an "Opus for coding" agent?

Sí. Utilice el enrutamiento multiagente: asigne a cada agente su propio modelo predeterminado y luego vincule las rutas entrantes (cuenta de proveedor o pares específicos) a cada agente. Un ejemplo de configuración se encuentra en Enrutamiento multiagente. Consulte también Modelos y Configuración.

¿Homebrew funciona en Linux?

Sí. Homebrew es compatible con Linux (Linuxbrew). Configuración rápida:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install

Si ejecutas OpenClaw a través de systemd, asegúrate de que el PATH del servicio incluya `/home/linuxbrew/.linuxbrew/bin` (o tu prefijo de brew) para que las herramientas instaladas con `brew` se resuelvan en shells que no son de inicio de sesión.
Las compilaciones recientes también anteponen directorios comunes de bin de usuario en los servicios systemd de Linux (por ejemplo `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) y respetan `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` y `FNM_DIR` cuando están configurados.

Diferencia entre la instalación hackable de git y la instalación con npm

• Instalación hackable (git): check-out completo del código fuente, editable, lo mejor para los colaboradores. Ejecutas las compilaciones localmente y puedes aplicar parches al código/documentación.
• instalación npm: instalación global de CLI, sin repositorio, lo mejor para “solo ejecutarlo”. Las actualizaciones provienen de las dist-tags de npm.

Documentación: Introducción, Actualización.

¿Puedo cambiar entre instalaciones de npm y git más adelante?

Sí. Usa openclaw update --channel ... cuando OpenClaw ya esté instalado. Esto no borra tus datos - solo cambia la instalación del código de OpenClaw. Tu estado (~/.openclaw) y tu espacio de trabajo (~/.openclaw/workspace) permanecen intactos.

De npm a git:

openclaw update --channel dev

De git a npm:

openclaw update --channel stable

Añade --dry-run para previsualizar primero el cambio de modo planeado. El actualizador ejecuta seguimientos del Doctor, actualiza las fuentes de los complementos para el canal objetivo y reinicia la puerta de enlace a menos que pases --no-restart.

El instalador también puede forzar cualquier modo:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

Consejos de copia de seguridad: consulta Estrategia de copia de seguridad.

¿Debo ejecutar la puerta de enlace en mi portátil o en un VPS?

Respuesta corta: si deseas confiabilidad 24/7, usa un VPS. Si quieres la menor fricción y no te importa el modo de suspensión/reinicios, ejecútalo localmente.

Portátil (puerta de enlace local)

• Ventajas: sin costo de servidor, acceso directo a archivos locales, ventana del navegador en vivo.
• Desventajas: suspensión/caídas de red = desconexiones, las actualizaciones/reinicios del sistema interrumpen, debe permanecer encendido.

VPS / nube

• Ventajas: siempre activo, red estable, sin problemas de suspensión del portátil, más fácil de mantener en ejecución.
• Desventajas: a menudo se ejecuta sin pantalla gráfica (usa capturas de pantalla), acceso remoto a archivos solamente, debes usar SSH para las actualizaciones.

Nota específica de OpenClaw: WhatsApp/Telegram/Slack/Mattermost/Discord funcionan bien desde un VPS. La única compensación real es navegador sin pantalla gráfica frente a una ventana visible. Consulta Navegador.

Recomendación predeterminada: VPS si has tenido desconexiones de la puerta de enlace anteriormente. Lo local es excelente cuando usas activamente el Mac y deseas acceso a archivos locales o automatización de la interfaz de usuario con un navegador visible.

¿Qué tan importante es ejecutar OpenClaw en una máquina dedicada?

No es obligatorio, pero recomendado para mayor fiabilidad y aislamiento.

• Host dedicado (VPS/Mac mini/Raspberry Pi): siempre encendido, menos interrupciones por suspensión/reinicio, permisos más limpios, más fácil de mantener en ejecución.
• Portátil/escritorio compartido: totalmente aceptable para pruebas y uso activo, pero espera pausas cuando el equipo se suspenda o se actualice.

Si quieres lo mejor de ambos mundos, mantén el Gateway en un host dedicado y empareja tu portátil como un nodo para herramientas locales de pantalla/cámara/exec. Consulta Nodos. Para orientación de seguridad, lee Seguridad.

¿Cuáles son los requisitos mínimos de VPS y el sistema operativo recomendado?

OpenClaw es ligero. Para un Gateway básico + un canal de chat:

• Mínimo absoluto: 1 vCPU, 1GB de RAM, ~500MB de disco.
• Recomendado: 1-2 vCPU, 2GB de RAM o más para tener margen (registros, medios, múltiples canales). Las herramientas de nodo y la automatización del navegador pueden consumir muchos recursos.

SO: usa Ubuntu LTS (o cualquier Debian/Ubuntu moderno). La ruta de instalación en Linux es la más probada allí.

Documentación: Linux, Alojamiento VPS.

¿Puedo ejecutar OpenClaw en una VM y cuáles son los requisitos?

Sí. Trata una VM igual que un VPS: debe estar siempre encendida, ser accesible y tener suficiente RAM para el Gateway y cualquier canal que habilites.

Orientación básica:

• Mínimo absoluto: 1 vCPU, 1GB de RAM.
• Recomendado: 2GB de RAM o más si ejecutas múltiples canales, automatización del navegador o herramientas de medios.
• SO: Ubuntu LTS u otro Debian/Ubuntu moderno.

Si estás en Windows, WSL2 es la configuración estilo VM más fácil y tiene la mejor compatibilidad de herramientas. Consulta Windows, Alojamiento VPS. Si estás ejecutando macOS en una VM, consulta macOS VM.

Relacionado

• Preguntas frecuentes — las preguntas frecuentes principales (modelos, sesiones, gateway, seguridad, más)
• Resumen de instalación
• Para empezar
• Solución de problemas