diff --git a/docs/es/channels/telegram.md b/docs/es/channels/telegram.md index bb9e7f807..2544fc1c8 100644 --- a/docs/es/channels/telegram.md +++ b/docs/es/channels/telegram.md @@ -1,29 +1,29 @@ --- read_when: - - Trabajando en funciones de Telegram o webhooks + - Trabajando en funciones o Webhooks de Telegram summary: Estado de compatibilidad, capacidades y configuración del bot de Telegram title: Telegram x-i18n: - generated_at: "2026-04-05T12:38:49Z" + generated_at: "2026-04-20T05:21:25Z" model: gpt-5.4 provider: openai - source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477 source_path: channels/telegram.md workflow: 15 --- -# Telegram (Bot API) +# Telegram (API de Bot) -Estado: listo para producción para MD de bots + grupos mediante grammY. El sondeo largo es el modo predeterminado; el modo webhook es opcional. +Estado: listo para producción para MD de bot + grupos mediante grammY. El sondeo largo es el modo predeterminado; el modo Webhook es opcional. - - La política predeterminada de MD para Telegram es pairing. + + La política predeterminada de MD para Telegram es la vinculación. - + Diagnóstico entre canales y guías de reparación. - + Patrones y ejemplos completos de configuración de canales. @@ -31,14 +31,14 @@ Estado: listo para producción para MD de bots + grupos mediante grammY. El sond ## Configuración rápida - + Abre Telegram y chatea con **@BotFather** (confirma que el identificador sea exactamente `@BotFather`). Ejecuta `/newbot`, sigue las indicaciones y guarda el token. - + ```json5 { @@ -53,12 +53,12 @@ Estado: listo para producción para MD de bots + grupos mediante grammY. El sond } ``` - Variable de entorno de respaldo: `TELEGRAM_BOT_TOKEN=...` (solo cuenta predeterminada). - Telegram **no** usa `openclaw channels login telegram`; configura el token en config/env y luego inicia el gateway. + Variable de entorno alternativa: `TELEGRAM_BOT_TOKEN=...` (solo cuenta predeterminada). + Telegram **no** usa `openclaw channels login telegram`; configura el token en la config/entorno y luego inicia Gateway. - + ```bash openclaw gateway @@ -66,44 +66,44 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Los códigos de pairing caducan después de 1 hora. + Los códigos de vinculación vencen después de 1 hora. - - Añade el bot a tu grupo y luego configura `channels.telegram.groups` y `groupPolicy` para que coincidan con tu modelo de acceso. + + Agrega el bot a tu grupo, luego configura `channels.telegram.groups` y `groupPolicy` para que coincidan con tu modelo de acceso. -El orden de resolución del token tiene en cuenta la cuenta. En la práctica, los valores de configuración tienen prioridad sobre la variable de entorno de respaldo, y `TELEGRAM_BOT_TOKEN` solo se aplica a la cuenta predeterminada. +El orden de resolución del token reconoce cuentas. En la práctica, los valores de la configuración tienen prioridad sobre la variable de entorno alternativa, y `TELEGRAM_BOT_TOKEN` solo se aplica a la cuenta predeterminada. -## Configuración en el lado de Telegram +## Configuración del lado de Telegram - - Los bots de Telegram usan **Privacy Mode** de forma predeterminada, lo que limita qué mensajes de grupo reciben. + + Los bots de Telegram usan de forma predeterminada el **Modo privacidad**, que limita qué mensajes de grupo reciben. - Si el bot debe ver todos los mensajes del grupo, haz una de estas dos cosas: + Si el bot debe ver todos los mensajes del grupo, haz una de estas opciones: - - desactiva el modo de privacidad mediante `/setprivacy`, o - - convierte al bot en administrador del grupo. + - desactivar el modo privacidad con `/setprivacy`, o + - convertir el bot en administrador del grupo. - Al cambiar el modo de privacidad, elimina y vuelve a añadir el bot en cada grupo para que Telegram aplique el cambio. + Al cambiar el modo privacidad, elimina y vuelve a agregar el bot en cada grupo para que Telegram aplique el cambio. - + El estado de administrador se controla en la configuración del grupo de Telegram. - Los bots administradores reciben todos los mensajes del grupo, lo que resulta útil para un comportamiento siempre activo en grupos. + Los bots administradores reciben todos los mensajes del grupo, lo que es útil para un comportamiento de grupo siempre activo. - + - - `/setjoingroups` para permitir/denegar añadidos a grupos + - `/setjoingroups` para permitir/negar agregados a grupos - `/setprivacy` para el comportamiento de visibilidad en grupos @@ -112,7 +112,7 @@ El orden de resolución del token tiene en cuenta la cuenta. En la práctica, lo ## Control de acceso y activación - + `channels.telegram.dmPolicy` controla el acceso a mensajes directos: - `pairing` (predeterminado) @@ -120,19 +120,19 @@ El orden de resolución del token tiene en cuenta la cuenta. En la práctica, lo - `open` (requiere que `allowFrom` incluya `"*"`) - `disabled` - `channels.telegram.allowFrom` acepta ID numéricos de usuario de Telegram. Los prefijos `telegram:` / `tg:` se aceptan y se normalizan. + `channels.telegram.allowFrom` acepta ID numéricos de usuario de Telegram. Los prefijos `telegram:` / `tg:` se aceptan y normalizan. `dmPolicy: "allowlist"` con `allowFrom` vacío bloquea todos los MD y la validación de configuración lo rechaza. - El onboarding acepta entrada `@username` y la resuelve a ID numéricos. + La configuración solicita solo ID numéricos de usuario. Si actualizaste y tu configuración contiene entradas de lista de permitidos `@username`, ejecuta `openclaw doctor --fix` para resolverlas (mejor esfuerzo; requiere un token de bot de Telegram). - Si antes dependías de archivos de lista de permitidos del almacén de pairing, `openclaw doctor --fix` puede recuperar entradas en `channels.telegram.allowFrom` en flujos de lista de permitidos (por ejemplo, cuando `dmPolicy: "allowlist"` aún no tiene ID explícitos). + Si antes dependías de archivos de lista de permitidos del almacén de vinculación, `openclaw doctor --fix` puede recuperar entradas en `channels.telegram.allowFrom` en flujos de lista de permitidos (por ejemplo, cuando `dmPolicy: "allowlist"` todavía no tiene IDs explícitos). - Para bots de un solo propietario, prefiere `dmPolicy: "allowlist"` con ID numéricos explícitos en `allowFrom` para mantener la política de acceso de forma duradera en la configuración (en lugar de depender de aprobaciones de pairing previas). + Para bots de un solo propietario, prefiere `dmPolicy: "allowlist"` con IDs numéricos explícitos en `allowFrom` para mantener una política de acceso persistente en la configuración (en lugar de depender de aprobaciones de vinculación anteriores). - Confusión habitual: aprobar el pairing de MD no significa "este remitente está autorizado en todas partes". - El pairing concede acceso solo a MD. La autorización del remitente en grupos sigue viniendo de las listas de permitidos explícitas de la configuración. - Si quieres "estoy autorizado una vez y funcionan tanto los MD como los comandos de grupo", coloca tu ID numérico de usuario de Telegram en `channels.telegram.allowFrom`. + Confusión habitual: aprobar la vinculación de MD no significa “este remitente está autorizado en todas partes”. + La vinculación concede acceso solo a MD. La autorización de remitentes en grupos sigue viniendo de listas de permitidos explícitas en la configuración. + Si quieres “estoy autorizado una vez y funcionan tanto los MD como los comandos de grupo”, coloca tu ID numérico de usuario de Telegram en `channels.telegram.allowFrom`. - ### Encontrar tu ID de usuario de Telegram + ### Cómo encontrar tu ID de usuario de Telegram Más seguro (sin bot de terceros): @@ -140,7 +140,7 @@ El orden de resolución del token tiene en cuenta la cuenta. En la práctica, lo 2. Ejecuta `openclaw logs --follow`. 3. Lee `from.id`. - Método oficial de Bot API: + Método oficial de la API de Bot: ```bash curl "https://api.telegram.org/bot/getUpdates" @@ -150,29 +150,29 @@ curl "https://api.telegram.org/bot/getUpdates" - + Se aplican juntos dos controles: 1. **Qué grupos están permitidos** (`channels.telegram.groups`) - sin configuración `groups`: - con `groupPolicy: "open"`: cualquier grupo puede pasar las comprobaciones de ID de grupo - - con `groupPolicy: "allowlist"` (predeterminado): los grupos se bloquean hasta que añadas entradas en `groups` (o `"*"`) - - `groups` configurado: actúa como lista de permitidos (ID explícitos o `"*"`) + - con `groupPolicy: "allowlist"` (predeterminado): los grupos se bloquean hasta que agregues entradas en `groups` (o `"*"`) + - `groups` configurado: actúa como lista de permitidos (IDs explícitos o `"*"`) 2. **Qué remitentes están permitidos en grupos** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (predeterminado) - `disabled` - `groupAllowFrom` se usa para filtrar remitentes en grupos. Si no está configurado, Telegram recurre a `allowFrom`. + `groupAllowFrom` se usa para el filtrado de remitentes en grupos. Si no se configura, Telegram usa `allowFrom` como respaldo. Las entradas de `groupAllowFrom` deben ser ID numéricos de usuario de Telegram (los prefijos `telegram:` / `tg:` se normalizan). No pongas ID de chat de grupo o supergrupo de Telegram en `groupAllowFrom`. Los ID de chat negativos pertenecen a `channels.telegram.groups`. - Las entradas no numéricas se ignoran para la autorización del remitente. - Límite de seguridad (`2026.2.25+`): la autenticación de remitentes en grupos **no** hereda aprobaciones del almacén de pairing de MD. - El pairing sigue siendo solo para MD. Para grupos, configura `groupAllowFrom` o `allowFrom` por grupo/por tema. - Si `groupAllowFrom` no está configurado, Telegram recurre a `allowFrom` de la configuración, no al almacén de pairing. - Patrón práctico para bots de un solo propietario: configura tu ID de usuario en `channels.telegram.allowFrom`, deja `groupAllowFrom` sin definir y permite los grupos objetivo en `channels.telegram.groups`. - Nota de ejecución: si falta por completo `channels.telegram`, la ejecución usa por defecto el modo cerrado `groupPolicy="allowlist"` a menos que `channels.defaults.groupPolicy` esté configurado explícitamente. + Las entradas no numéricas se ignoran para la autorización de remitentes. + Límite de seguridad (`2026.2.25+`): la autenticación de remitentes en grupos **no** hereda aprobaciones del almacén de vinculación de MD. + La vinculación sigue siendo solo para MD. Para grupos, configura `groupAllowFrom` o `allowFrom` por grupo/tema. + Si `groupAllowFrom` no está configurado, Telegram usa como respaldo `allowFrom` de la configuración, no el almacén de vinculación. + Patrón práctico para bots de un solo propietario: configura tu ID de usuario en `channels.telegram.allowFrom`, deja `groupAllowFrom` sin configurar y permite los grupos objetivo en `channels.telegram.groups`. + Nota de tiempo de ejecución: si `channels.telegram` falta por completo, los valores predeterminados de tiempo de ejecución cierran el acceso con `groupPolicy="allowlist"` salvo que `channels.defaults.groupPolicy` esté configurado explícitamente. Ejemplo: permitir a cualquier miembro en un grupo específico: @@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Ejemplo: permitir solo a usuarios específicos dentro de un grupo específico: + Ejemplo: permitir solo usuarios específicos dentro de un grupo específico: ```json5 { @@ -209,21 +209,21 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - Error habitual: `groupAllowFrom` no es una lista de permitidos de grupos de Telegram. + Error común: `groupAllowFrom` no es una lista de permitidos de grupos de Telegram. - - Coloca los ID negativos de grupo o supergrupo de Telegram como `-1001234567890` en `channels.telegram.groups`. - - Coloca los ID de usuario de Telegram como `8734062810` en `groupAllowFrom` cuando quieras limitar qué personas dentro de un grupo permitido pueden activar el bot. + - Coloca ID negativos de grupo o supergrupo de Telegram como `-1001234567890` en `channels.telegram.groups`. + - Coloca ID de usuario de Telegram como `8734062810` en `groupAllowFrom` cuando quieras limitar qué personas dentro de un grupo permitido pueden activar el bot. - Usa `groupAllowFrom: ["*"]` solo cuando quieras que cualquier miembro de un grupo permitido pueda hablar con el bot. - - Las respuestas en grupo requieren mención de forma predeterminada. + + Las respuestas en grupos requieren mención de forma predeterminada. La mención puede venir de: - - una mención nativa `@botusername`, o + - mención nativa `@botusername`, o - patrones de mención en: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -249,29 +249,29 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Obtener el ID del chat de grupo: + Cómo obtener el ID del chat del grupo: - reenvía un mensaje del grupo a `@userinfobot` / `@getidsbot` - o lee `chat.id` desde `openclaw logs --follow` - - o inspecciona `getUpdates` de Bot API + - o inspecciona `getUpdates` de la API de Bot ## Comportamiento en tiempo de ejecución -- Telegram pertenece al proceso del gateway. -- El enrutamiento es determinista: las respuestas entrantes de Telegram vuelven a Telegram (el modelo no elige canales). -- Los mensajes entrantes se normalizan en la envoltura de canal compartida con metadatos de respuesta y marcadores de posición de medios. -- Las sesiones de grupo están aisladas por ID de grupo. Los temas de foros añaden `:topic:` para mantener el aislamiento entre temas. -- Los mensajes de MD pueden llevar `message_thread_id`; OpenClaw los enruta con claves de sesión conscientes del hilo y conserva el ID del hilo para las respuestas. -- El sondeo largo usa grammY runner con secuenciación por chat/por hilo. La concurrencia general del receptor de runner usa `agents.defaults.maxConcurrent`. -- Telegram Bot API no admite confirmaciones de lectura (`sendReadReceipts` no se aplica). +- Telegram es gestionado por el proceso de Gateway. +- El enrutamiento es determinista: las respuestas entrantes de Telegram regresan a Telegram (el modelo no elige canales). +- Los mensajes entrantes se normalizan en el sobre compartido del canal con metadatos de respuesta y marcadores de posición de medios. +- Las sesiones de grupo se aíslan por ID de grupo. Los temas del foro añaden `:topic:` para mantener los temas aislados. +- Los mensajes de MD pueden incluir `message_thread_id`; OpenClaw los enruta con claves de sesión compatibles con hilos y preserva el ID del hilo para las respuestas. +- El sondeo largo usa grammY runner con secuenciación por chat/por hilo. La concurrencia total del sink del runner usa `agents.defaults.maxConcurrent`. +- La API de Bot de Telegram no tiene compatibilidad con confirmaciones de lectura (`sendReadReceipts` no se aplica). ## Referencia de funciones - + OpenClaw puede transmitir respuestas parciales en tiempo real: - chats directos: mensaje de vista previa + `editMessageText` @@ -280,54 +280,54 @@ curl "https://api.telegram.org/bot/getUpdates" Requisito: - `channels.telegram.streaming` es `off | partial | block | progress` (predeterminado: `partial`) - - `progress` se asigna a `partial` en Telegram (compatibilidad con nomenclatura entre canales) + - `progress` se asigna a `partial` en Telegram (compatibilidad con la nomenclatura entre canales) - los valores heredados `channels.telegram.streamMode` y booleanos `streaming` se asignan automáticamente Para respuestas solo de texto: - - MD: OpenClaw conserva el mismo mensaje de vista previa y realiza una edición final en el mismo lugar (sin segundo mensaje) - - grupo/tema: OpenClaw conserva el mismo mensaje de vista previa y realiza una edición final en el mismo lugar (sin segundo mensaje) + - MD: OpenClaw mantiene el mismo mensaje de vista previa y realiza una edición final en el mismo lugar (sin segundo mensaje) + - grupo/tema: OpenClaw mantiene el mismo mensaje de vista previa y realiza una edición final en el mismo lugar (sin segundo mensaje) - Para respuestas complejas (por ejemplo, cargas de medios), OpenClaw recurre a la entrega final normal y después limpia el mensaje de vista previa. + Para respuestas complejas (por ejemplo, cargas útiles multimedia), OpenClaw recurre a la entrega final normal y luego limpia el mensaje de vista previa. - La transmisión de vista previa es independiente de la transmisión por bloques. Cuando la transmisión por bloques está habilitada explícitamente para Telegram, OpenClaw omite la transmisión de vista previa para evitar una doble transmisión. + La transmisión de vista previa es independiente de la transmisión por bloques. Cuando la transmisión por bloques está habilitada explícitamente para Telegram, OpenClaw omite la transmisión de vista previa para evitar transmisión duplicada. Si el transporte nativo de borrador no está disponible o es rechazado, OpenClaw recurre automáticamente a `sendMessage` + `editMessageText`. - Transmisión de razonamiento solo para Telegram: + Flujo de razonamiento solo para Telegram: - `/reasoning stream` envía el razonamiento a la vista previa en vivo mientras se genera - - la respuesta final se envía sin el texto del razonamiento + - la respuesta final se envía sin texto de razonamiento - + El texto saliente usa `parse_mode: "HTML"` de Telegram. - El texto tipo Markdown se renderiza como HTML seguro para Telegram. - - El HTML sin procesar del modelo se escapa para reducir los fallos de análisis de Telegram. + - El HTML sin procesar del modelo se escapa para reducir fallos de análisis de Telegram. - Si Telegram rechaza el HTML analizado, OpenClaw reintenta como texto sin formato. Las vistas previas de enlaces están habilitadas de forma predeterminada y pueden deshabilitarse con `channels.telegram.linkPreview: false`. - - El registro del menú de comandos de Telegram se gestiona al inicio con `setMyCommands`. + + El registro del menú de comandos de Telegram se gestiona al iniciar con `setMyCommands`. Valores predeterminados de comandos nativos: - `commands.native: "auto"` habilita comandos nativos para Telegram - Añadir entradas de menú de comandos personalizadas: + Agrega entradas personalizadas al menú de comandos: ```json5 { channels: { telegram: { customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Respaldo de Git" }, + { command: "generate", description: "Crear una imagen" }, ], }, }, @@ -336,45 +336,45 @@ curl "https://api.telegram.org/bot/getUpdates" Reglas: - - los nombres se normalizan (eliminan el `/` inicial, minúsculas) + - los nombres se normalizan (quitar `/` inicial, minúsculas) - patrón válido: `a-z`, `0-9`, `_`, longitud `1..32` - los comandos personalizados no pueden sobrescribir comandos nativos - - los conflictos/duplicados se omiten y se registran + - los conflictos/duplicados se omiten y se registran en el log Notas: - - los comandos personalizados son solo entradas de menú; no implementan el comportamiento automáticamente - - los comandos de plugins/Skills pueden seguir funcionando cuando se escriben incluso si no se muestran en el menú de Telegram + - los comandos personalizados son solo entradas de menú; no implementan comportamiento automáticamente + - los comandos de Plugin/Skills pueden seguir funcionando cuando se escriben incluso si no se muestran en el menú de Telegram - Si los comandos nativos están deshabilitados, los integrados se eliminan. Los comandos personalizados/de plugins aún pueden registrarse si están configurados. + Si los comandos nativos están deshabilitados, los integrados se eliminan. Los comandos personalizados/de Plugin pueden seguir registrándose si están configurados. - Fallos habituales de configuración: + Fallos comunes de configuración: - - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú de Telegram siguió desbordado después de recortarlo; reduce comandos de plugins/Skills/personalizados o deshabilita `channels.telegram.commands.native`. + - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú de Telegram siguió desbordándose después del recorte; reduce los comandos de Plugin/Skills/personalizados o deshabilita `channels.telegram.commands.native`. - `setMyCommands failed` con errores de red/fetch normalmente significa que el DNS/HTTPS saliente hacia `api.telegram.org` está bloqueado. - ### Comandos de pairing de dispositivos (plugin `device-pair`) + ### Comandos de vinculación de dispositivo (Plugin `device-pair`) - Cuando el plugin `device-pair` está instalado: + Cuando el Plugin `device-pair` está instalado: 1. `/pair` genera el código de configuración 2. pega el código en la app de iOS - 3. `/pair pending` lista las solicitudes pendientes (incluidos rol/alcances) + 3. `/pair pending` enumera las solicitudes pendientes (incluidos rol/scopes) 4. aprueba la solicitud: - `/pair approve ` para aprobación explícita - `/pair approve` cuando solo hay una solicitud pendiente - `/pair approve latest` para la más reciente - El código de configuración lleva un token de bootstrap de corta duración. La transferencia integrada de bootstrap mantiene el token de nodo principal en `scopes: []`; cualquier token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` y `operator.write`. Las comprobaciones de alcance de bootstrap usan prefijos por rol, por lo que esa lista de permitidos de operador solo satisface solicitudes de operador; los roles que no son operador siguen necesitando alcances bajo su propio prefijo de rol. + El código de configuración lleva un token de bootstrap de corta duración. La transferencia integrada de bootstrap mantiene el token del Node principal en `scopes: []`; cualquier token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` y `operator.write`. Las comprobaciones de scope de bootstrap tienen prefijo de rol, por lo que esa lista de permitidos de operador solo satisface solicitudes de operador; los roles que no son de operador siguen necesitando scopes bajo su propio prefijo de rol. - Si un dispositivo vuelve a intentarlo con detalles de autenticación modificados (por ejemplo, rol/alcances/clave pública), la solicitud pendiente anterior se reemplaza y la nueva solicitud usa un `requestId` diferente. Vuelve a ejecutar `/pair pending` antes de aprobar. + Si un dispositivo reintenta con detalles de autenticación cambiados (por ejemplo, rol/scopes/clave pública), la solicitud pendiente anterior es reemplazada y la nueva solicitud usa un `requestId` distinto. Vuelve a ejecutar `/pair pending` antes de aprobar. - Más detalles: [Pairing](/channels/pairing#pair-via-telegram-recommended-for-ios). + Más detalles: [Vinculación](/es/channels/pairing#pair-via-telegram-recommended-for-ios). - - Configura el alcance del teclado en línea: + + Configura el alcance del teclado integrado: ```json5 { @@ -388,7 +388,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Anulación por cuenta: + Sobrescritura por cuenta: ```json5 { @@ -439,36 +439,36 @@ curl "https://api.telegram.org/bot/getUpdates" - + Las acciones de herramientas de Telegram incluyen: - - `sendMessage` (`to`, `content`, `mediaUrl`, `replyToMessageId`, `messageThreadId` opcionales) + - `sendMessage` (`to`, `content`, `mediaUrl` opcional, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, `iconColor`, `iconCustomEmojiId` opcionales) + - `createForumTopic` (`chatId`, `name`, `iconColor` opcional, `iconCustomEmojiId`) Las acciones de mensajes del canal exponen alias ergonómicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Controles de activación: + Controles de restricción: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (predeterminado: deshabilitado) - Nota: `edit` y `topic-create` están actualmente habilitados de forma predeterminada y no tienen alternadores separados `channels.telegram.actions.*`. - Los envíos en tiempo de ejecución usan la instantánea activa de configuración/secretos (inicio/recarga), por lo que las rutas de acción no realizan una nueva resolución ad hoc de SecretRef en cada envío. + Nota: `edit` y `topic-create` están habilitados actualmente de forma predeterminada y no tienen alternadores `channels.telegram.actions.*` independientes. + Los envíos en tiempo de ejecución usan la instantánea activa de config/secrets (inicio/recarga), por lo que las rutas de acción no realizan una nueva resolución ad hoc de SecretRef por envío. - Semántica de eliminación de reacciones: [/tools/reactions](/tools/reactions) + Semántica de eliminación de reacciones: [/tools/reactions](/es/tools/reactions) - - Telegram admite etiquetas explícitas de encadenamiento de respuestas en la salida generada: + + Telegram admite etiquetas explícitas de hilos de respuesta en la salida generada: - `[[reply_to_current]]` responde al mensaje que activó la acción - - `[[reply_to:]]` responde a un ID de mensaje específico de Telegram + - `[[reply_to:]]` responde a un ID específico de mensaje de Telegram `channels.telegram.replyToMode` controla el manejo: @@ -476,16 +476,16 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - Nota: `off` deshabilita el encadenamiento implícito de respuestas. Las etiquetas explícitas `[[reply_to_*]]` se siguen respetando. + Nota: `off` deshabilita el enhebrado implícito de respuestas. Las etiquetas explícitas `[[reply_to_*]]` siguen respetándose. - + Supergrupos de foro: - - las claves de sesión de temas añaden `:topic:` - - las respuestas y las acciones de escritura se dirigen al hilo del tema - - ruta de configuración del tema: + - las claves de sesión de tema agregan `:topic:` + - las respuestas y la escritura se dirigen al hilo del tema + - ruta de config del tema: `channels.telegram.groups..topics.` Caso especial de tema general (`threadId=1`): @@ -493,10 +493,10 @@ curl "https://api.telegram.org/bot/getUpdates" - los envíos de mensajes omiten `message_thread_id` (Telegram rechaza `sendMessage(...thread_id=1)`) - las acciones de escritura siguen incluyendo `message_thread_id` - Herencia de temas: las entradas de temas heredan la configuración del grupo salvo que se sobrescriba (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` es exclusivo del tema y no se hereda de los valores predeterminados del grupo. + Herencia de temas: las entradas de tema heredan la configuración del grupo salvo sobrescritura (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` es solo de tema y no se hereda de los valores predeterminados del grupo. - **Enrutamiento de agentes por tema**: cada tema puede enrutar a un agente distinto configurando `agentId` en la configuración del tema. Esto da a cada tema su propio espacio de trabajo, memoria y sesión aislados. Ejemplo: + **Enrutamiento por agente por tema**: cada tema puede enrutar a un agente distinto configurando `agentId` en la config del tema. Esto da a cada tema su propio espacio de trabajo, memoria y sesión aislados. Ejemplo: ```json5 { @@ -505,7 +505,7 @@ curl "https://api.telegram.org/bot/getUpdates" groups: { "-1001234567890": { topics: { - "1": { agentId: "main" }, // Tema general → agente principal + "1": { agentId: "main" }, // Tema general → agente main "3": { agentId: "zu" }, // Tema de desarrollo → agente zu "5": { agentId: "coder" } // Revisión de código → agente coder } @@ -516,9 +516,9 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Cada tema tiene entonces su propia clave de sesión: `agent:zu:telegram:group:-1001234567890:topic:3` + Luego, cada tema tiene su propia clave de sesión: `agent:zu:telegram:group:-1001234567890:topic:3` - **Enlace persistente de temas ACP**: los temas de foros pueden fijar sesiones de arnés ACP mediante enlaces ACP tipados de nivel superior: + **Vinculación persistente de temas de ACP**: los temas de foro pueden fijar sesiones del arnés ACP mediante vinculaciones ACP tipadas de nivel superior: - `bindings[]` con `type: "acp"` y `match.channel: "telegram"` @@ -569,27 +569,27 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Actualmente esto se limita a temas de foros en grupos y supergrupos. + Actualmente, esto está limitado a temas de foro en grupos y supergrupos. - **Creación de ACP vinculado a hilos desde el chat**: + **Generación de ACP vinculada al hilo desde el chat**: - - `/acp spawn --thread here|auto` puede enlazar el tema actual de Telegram a una nueva sesión ACP. - - Los mensajes posteriores del tema se enrutan directamente a la sesión ACP enlazada (no se requiere `/acp steer`). - - OpenClaw fija el mensaje de confirmación de creación dentro del tema después de un enlace correcto. + - `/acp spawn --thread here|auto` puede vincular el tema actual de Telegram a una nueva sesión ACP. + - Los mensajes posteriores en el tema se enrutan directamente a la sesión ACP vinculada (no se requiere `/acp steer`). + - OpenClaw fija el mensaje de confirmación de generación dentro del tema tras una vinculación correcta. - Requiere `channels.telegram.threadBindings.spawnAcpSessions=true`. - El contexto de la plantilla incluye: + El contexto de plantilla incluye: - `MessageThreadId` - `IsForum` Comportamiento de hilos en MD: - - los chats privados con `message_thread_id` mantienen el enrutamiento de MD pero usan claves de sesión y destinos de respuesta conscientes del hilo. + - los chats privados con `message_thread_id` mantienen el enrutamiento de MD pero usan claves de sesión y destinos de respuesta compatibles con hilos. - + ### Mensajes de audio Telegram distingue entre notas de voz y archivos de audio. @@ -609,9 +609,9 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - ### Mensajes de vídeo + ### Mensajes de video - Telegram distingue entre archivos de vídeo y notas de vídeo. + Telegram distingue entre archivos de video y notas de video. Ejemplo de acción de mensaje: @@ -625,15 +625,15 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Las notas de vídeo no admiten subtítulos; el texto del mensaje proporcionado se envía por separado. + Las notas de video no admiten subtítulos; el texto del mensaje proporcionado se envía por separado. ### Stickers Manejo de stickers entrantes: - - WEBP estático: se descarga y procesa (marcador ``) - - TGS animado: se omite - - WEBM de vídeo: se omite + - WEBP estático: descargado y procesado (marcador ``) + - TGS animado: omitido + - WEBM de video: omitido Campos de contexto de stickers: @@ -687,10 +687,10 @@ curl "https://api.telegram.org/bot/getUpdates" - - Las reacciones de Telegram llegan como actualizaciones `message_reaction` (separadas de las cargas de mensajes). + + Las reacciones de Telegram llegan como actualizaciones `message_reaction` (separadas de las cargas útiles de mensajes). - Cuando están habilitadas, OpenClaw pone en cola eventos del sistema como: + Cuando está habilitado, OpenClaw pone en cola eventos del sistema como: - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` @@ -703,15 +703,15 @@ curl "https://api.telegram.org/bot/getUpdates" - `own` significa solo reacciones de usuarios a mensajes enviados por el bot (mejor esfuerzo mediante caché de mensajes enviados). - Los eventos de reacción siguen respetando los controles de acceso de Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); los remitentes no autorizados se descartan. - - Telegram no proporciona ID de hilo en las actualizaciones de reacción. - - los grupos que no son foros se enrutan a la sesión de chat grupal + - Telegram no proporciona IDs de hilo en las actualizaciones de reacciones. + - los grupos que no son de foro se enrutan a la sesión del chat de grupo - los grupos de foro se enrutan a la sesión del tema general del grupo (`:topic:1`), no al tema exacto de origen - `allowed_updates` para sondeo/webhook incluyen `message_reaction` automáticamente. + `allowed_updates` para sondeo/Webhook incluye `message_reaction` automáticamente. - + `ackReaction` envía un emoji de confirmación mientras OpenClaw procesa un mensaje entrante. Orden de resolución: @@ -719,22 +719,22 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - emoji de respaldo de identidad del agente (`agents.list[].identity.emoji`, o bien "👀") + - emoji de identidad del agente como respaldo (`agents.list[].identity.emoji`, o "👀" si no existe) Notas: - - Telegram espera emoji Unicode (por ejemplo, "👀"). + - Telegram espera emoji unicode (por ejemplo, "👀"). - Usa `""` para deshabilitar la reacción para un canal o cuenta. - + Las escrituras de configuración del canal están habilitadas de forma predeterminada (`configWrites !== false`). Las escrituras activadas por Telegram incluyen: - - eventos de migración de grupos (`migrate_to_chat_id`) para actualizar `channels.telegram.groups` - - `/config set` y `/config unset` (requiere habilitación de comandos) + - eventos de migración de grupo (`migrate_to_chat_id`) para actualizar `channels.telegram.groups` + - `/config set` y `/config unset` (requieren habilitación de comandos) Deshabilitar: @@ -750,10 +750,10 @@ curl "https://api.telegram.org/bot/getUpdates" - + Predeterminado: sondeo largo. - Modo webhook: + Modo Webhook: - configura `channels.telegram.webhookUrl` - configura `channels.telegram.webhookSecret` (obligatorio cuando `webhookUrl` está configurado) @@ -761,34 +761,34 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.webhookHost` opcional (predeterminado `127.0.0.1`) - `channels.telegram.webhookPort` opcional (predeterminado `8787`) - El escuchador local predeterminado para el modo webhook se enlaza a `127.0.0.1:8787`. + El listener local predeterminado para el modo Webhook se vincula a `127.0.0.1:8787`. - Si tu endpoint público es distinto, coloca un proxy inverso delante y apunta `webhookUrl` a la URL pública. + Si tu endpoint público es diferente, coloca un proxy inverso delante y apunta `webhookUrl` a la URL pública. Configura `webhookHost` (por ejemplo `0.0.0.0`) cuando necesites intencionalmente ingreso externo. - + - `channels.telegram.textChunkLimit` tiene como valor predeterminado 4000. - - `channels.telegram.chunkMode="newline"` prefiere límites de párrafo (líneas en blanco) antes de dividir por longitud. + - `channels.telegram.chunkMode="newline"` prioriza los límites de párrafo (líneas en blanco) antes de dividir por longitud. - `channels.telegram.mediaMaxMb` (predeterminado 100) limita el tamaño de los medios entrantes y salientes de Telegram. - `channels.telegram.timeoutSeconds` sobrescribe el tiempo de espera del cliente de la API de Telegram (si no se configura, se aplica el valor predeterminado de grammY). - el historial de contexto de grupo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (predeterminado 50); `0` lo deshabilita. - - el contexto suplementario de respuesta/cita/reenvío se pasa actualmente tal como se recibe. - - las listas de permitidos de Telegram controlan principalmente quién puede activar el agente, no son un límite completo de redacción del contexto suplementario. - - controles del historial de MD: + - el contexto suplementario de respuesta/cita/reenvío actualmente se pasa tal como se recibe. + - las listas de permitidos de Telegram controlan principalmente quién puede activar el agente, no un límite completo de redacción del contexto suplementario. + - controles de historial de MD: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - la configuración `channels.telegram.retry` se aplica a los ayudantes de envío de Telegram (CLI/herramientas/acciones) para errores recuperables de API saliente. + - la configuración `channels.telegram.retry` se aplica a los helpers de envío de Telegram (CLI/tools/actions) para errores recuperables de la API saliente. - El destino de envío de CLI puede ser un ID numérico de chat o un nombre de usuario: + El destino de envío por CLI puede ser un ID numérico de chat o un nombre de usuario: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Los sondeos de Telegram usan `openclaw message poll` y admiten temas de foros: + Los sondeos de Telegram usan `openclaw message poll` y admiten temas de foro: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -798,65 +798,65 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Indicadores de sondeo solo de Telegram: + Indicadores de sondeo solo para Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` para temas de foros (o usa un destino `:topic:`) + - `--thread-id` para temas de foro (o usa un destino `:topic:`) - El envío de Telegram también admite: + El envío por Telegram también admite: - - `--buttons` para teclados en línea cuando `channels.telegram.capabilities.inlineButtons` lo permite + - `--buttons` para teclados integrados cuando `channels.telegram.capabilities.inlineButtons` lo permite - `--force-document` para enviar imágenes y GIF salientes como documentos en lugar de cargas comprimidas de foto o medios animados - Control de acciones: + Restricción de acciones: - `channels.telegram.actions.sendMessage=false` deshabilita los mensajes salientes de Telegram, incluidos los sondeos - - `channels.telegram.actions.poll=false` deshabilita la creación de sondeos de Telegram y mantiene habilitados los envíos normales + - `channels.telegram.actions.poll=false` deshabilita la creación de sondeos de Telegram mientras mantiene habilitados los envíos normales - - Telegram admite aprobaciones de ejecución en MD de aprobadores y opcionalmente puede publicar solicitudes de aprobación en el chat o tema de origen. + + Telegram admite aprobaciones de exec en los MD de los aprobadores y, opcionalmente, puede publicar solicitudes de aprobación en el chat o tema de origen. - Ruta de configuración: + Ruta de config: - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers` (opcional; recurre a los ID numéricos de propietario inferidos de `allowFrom` y `defaultTo` directo cuando es posible) + - `channels.telegram.execApprovals.approvers` (opcional; usa como respaldo los ID numéricos de propietarios inferidos desde `allowFrom` y `defaultTo` directo cuando es posible) - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, predeterminado: `dm`) - `agentFilter`, `sessionFilter` - Los aprobadores deben ser ID numéricos de usuario de Telegram. Telegram habilita automáticamente aprobaciones nativas de ejecución cuando `enabled` no está configurado o es `"auto"` y se puede resolver al menos un aprobador, ya sea desde `execApprovals.approvers` o desde la configuración numérica del propietario de la cuenta (`allowFrom` y `defaultTo` de mensaje directo). Configura `enabled: false` para deshabilitar explícitamente Telegram como cliente nativo de aprobación. De lo contrario, las solicitudes de aprobación recurren a otras rutas de aprobación configuradas o a la política de respaldo de aprobación de ejecución. + Los aprobadores deben ser ID numéricos de usuario de Telegram. Telegram habilita automáticamente las aprobaciones nativas de exec cuando `enabled` no está configurado o es `"auto"` y puede resolverse al menos un aprobador, ya sea desde `execApprovals.approvers` o desde la configuración numérica de propietario de la cuenta (`allowFrom` y `defaultTo` de mensaje directo). Configura `enabled: false` para deshabilitar explícitamente Telegram como cliente nativo de aprobación. En caso contrario, las solicitudes de aprobación recurren a otras rutas de aprobación configuradas o a la política de respaldo de aprobación de exec. - Telegram también renderiza los botones de aprobación compartidos usados por otros canales de chat. El adaptador nativo de Telegram añade principalmente el enrutamiento de MD para aprobadores, la difusión a canal/tema y las pistas de escritura antes de la entrega. + Telegram también renderiza los botones de aprobación compartidos usados por otros canales de chat. El adaptador nativo de Telegram agrega principalmente enrutamiento de MD de aprobadores, distribución al canal/tema e indicadores de escritura antes de la entrega. Cuando esos botones están presentes, son la UX principal de aprobación; OpenClaw - solo debería incluir un comando manual `/approve` cuando el resultado de la herramienta diga + solo debe incluir un comando manual `/approve` cuando el resultado de la herramienta indique que las aprobaciones por chat no están disponibles o que la aprobación manual es la única vía. Reglas de entrega: - - `target: "dm"` envía solicitudes de aprobación solo a los MD de aprobadores resueltos + - `target: "dm"` envía solicitudes de aprobación solo a los MD de los aprobadores resueltos - `target: "channel"` envía la solicitud de vuelta al chat/tema de Telegram de origen - - `target: "both"` envía a los MD de aprobadores y al chat/tema de origen + - `target: "both"` envía a los MD de los aprobadores y al chat/tema de origen Solo los aprobadores resueltos pueden aprobar o denegar. Los no aprobadores no pueden usar `/approve` ni los botones de aprobación de Telegram. Comportamiento de resolución de aprobación: - - Los ID con prefijo `plugin:` siempre se resuelven mediante aprobaciones del plugin. - - Otros ID prueban primero `exec.approval.resolve`. - - Si Telegram también está autorizado para aprobaciones del plugin y el gateway dice - que la aprobación de ejecución es desconocida o caducó, Telegram reintenta una vez mediante + - Los ID con prefijo `plugin:` siempre se resuelven mediante aprobaciones del Plugin. + - Otros ID intentan primero `exec.approval.resolve`. + - Si Telegram también está autorizado para aprobaciones del Plugin y Gateway indica + que la aprobación de exec es desconocida o expiró, Telegram reintenta una vez mediante `plugin.approval.resolve`. - - Las denegaciones/errores reales de aprobación de ejecución no pasan silenciosamente a la - resolución de aprobación del plugin. + - Las denegaciones/errores reales de aprobación de exec no recurren silenciosamente a la + resolución de aprobación del Plugin. - La entrega por canal muestra el texto del comando en el chat, así que habilita `channel` o `both` solo en grupos/temas de confianza. Cuando la solicitud llega a un tema de foro, OpenClaw conserva el tema tanto para la solicitud de aprobación como para el seguimiento posterior a la aprobación. Las aprobaciones de ejecución caducan después de 30 minutos de forma predeterminada. + La entrega al canal muestra el texto del comando en el chat, así que habilita `channel` o `both` solo en grupos/temas de confianza. Cuando la solicitud llega a un tema de foro, OpenClaw preserva el tema tanto para la solicitud de aprobación como para el seguimiento posterior a la aprobación. Las aprobaciones de exec expiran después de 30 minutos de forma predeterminada. - Los botones de aprobación en línea también dependen de que `channels.telegram.capabilities.inlineButtons` permita la superficie objetivo (`dm`, `group` o `all`). + Los botones integrados de aprobación también dependen de que `channels.telegram.capabilities.inlineButtons` permita la superficie de destino (`dm`, `group` o `all`). - Documentación relacionada: [Aprobaciones de ejecución](/tools/exec-approvals) + Documentación relacionada: [Aprobaciones de exec](/es/tools/exec-approvals) @@ -865,12 +865,12 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Cuando el agente encuentra un error de entrega o de proveedor, Telegram puede responder con el texto del error o suprimirlo. Dos claves de configuración controlan este comportamiento: -| Key | Values | Default | Description | -| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envía un mensaje de error amigable al chat. `silent` suprime por completo las respuestas de error. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tiempo mínimo entre respuestas de error al mismo chat. Evita spam de errores durante caídas. | +| Clave | Valores | Predeterminado | Descripción | +| ----------------------------------- | ----------------- | -------------- | ---------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envía un mensaje de error amigable al chat. `silent` suprime por completo las respuestas de error. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tiempo mínimo entre respuestas de error al mismo chat. Evita spam de errores durante caídas. | -Se admiten anulaciones por cuenta, por grupo y por tema (la misma herencia que otras claves de configuración de Telegram). +Se admiten sobrescrituras por cuenta, por grupo y por tema (la misma herencia que otras claves de configuración de Telegram). ```json5 { @@ -891,40 +891,40 @@ Se admiten anulaciones por cuenta, por grupo y por tema (la misma herencia que o ## Solución de problemas - + - - Si `requireMention=false`, el modo de privacidad de Telegram debe permitir visibilidad completa. + - Si `requireMention=false`, el modo privacidad de Telegram debe permitir visibilidad completa. - BotFather: `/setprivacy` -> Disable - - luego elimina y vuelve a añadir el bot al grupo - - `openclaw channels status` muestra una advertencia cuando la configuración espera mensajes de grupo sin mención. - - `openclaw channels status --probe` puede comprobar ID numéricos explícitos de grupo; el comodín `"*"` no puede sondearse para membresía. + - luego elimina y vuelve a agregar el bot al grupo + - `openclaw channels status` advierte cuando la configuración espera mensajes de grupo sin mención. + - `openclaw channels status --probe` puede comprobar ID numéricos explícitos de grupo; el comodín `"*"` no puede comprobarse por pertenencia. - prueba rápida de sesión: `/activation always`. - + - cuando existe `channels.telegram.groups`, el grupo debe estar listado (o incluir `"*"`) - - verifica la membresía del bot en el grupo - - revisa los registros: `openclaw logs --follow` para ver motivos de omisión + - verifica la pertenencia del bot al grupo + - revisa los logs: `openclaw logs --follow` para ver los motivos de omisión - + - - autoriza la identidad de tu remitente (pairing y/o `allowFrom` numérico) + - autoriza la identidad de tu remitente (vinculación y/o `allowFrom` numérico) - la autorización de comandos sigue aplicándose incluso cuando la política de grupo es `open` - - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú nativo tiene demasiadas entradas; reduce comandos de plugins/Skills/personalizados o deshabilita los menús nativos + - `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú nativo tiene demasiadas entradas; reduce comandos de Plugin/Skills/personalizados o deshabilita los menús nativos - `setMyCommands failed` con errores de red/fetch normalmente indica problemas de alcance DNS/HTTPS hacia `api.telegram.org` - + - - Node 22+ + fetch/proxy personalizado pueden activar un comportamiento de cancelación inmediata si los tipos de AbortSignal no coinciden. + - Node 22+ + fetch/proxy personalizado puede activar comportamiento de cancelación inmediata si los tipos de AbortSignal no coinciden. - Algunos hosts resuelven `api.telegram.org` primero a IPv6; una salida IPv6 defectuosa puede causar fallos intermitentes de la API de Telegram. - - Si los registros incluyen `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ahora los reintenta como errores de red recuperables. - - En hosts VPS con salida/TLS directa inestable, enruta las llamadas a la API de Telegram mediante `channels.telegram.proxy`: + - Si los logs incluyen `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ahora los reintenta como errores de red recuperables. + - En hosts VPS con salida directa/TLS inestable, enruta las llamadas a la API de Telegram a través de `channels.telegram.proxy`: ```yaml channels: @@ -932,8 +932,8 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ usa de forma predeterminada `autoSelectFamily=true` (excepto WSL2) y `dnsResultOrder=ipv4first`. - - Si tu host es WSL2 o explícitamente funciona mejor con comportamiento solo IPv4, fuerza la selección de familia: + - Node 22+ usa por defecto `autoSelectFamily=true` (excepto WSL2) y `dnsResultOrder=ipv4first`. + - Si tu host es WSL2 o funciona explícitamente mejor con comportamiento solo IPv4, fuerza la selección de familia: ```yaml channels: @@ -942,9 +942,9 @@ channels: autoSelectFamily: false ``` - - Las respuestas del rango de prueba RFC 2544 (`198.18.0.0/15`) ya están permitidas - para descargas de medios de Telegram de forma predeterminada. Si una IP falsa de confianza o un - proxy transparente reescribe `api.telegram.org` a alguna otra + - Las respuestas del rango de referencia RFC 2544 (`198.18.0.0/15`) ya están permitidas + de forma predeterminada para descargas de medios de Telegram. Si una IP falsa de + confianza o un proxy transparente reescribe `api.telegram.org` a alguna otra dirección privada/interna/de uso especial durante las descargas de medios, puedes habilitar la omisión solo para Telegram: @@ -955,20 +955,21 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - La misma opción también está disponible por cuenta en + - La misma habilitación opcional está disponible por cuenta en `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Si tu proxy resuelve hosts de medios de Telegram en `198.18.x.x`, deja primero desactivada la - marca peligrosa. Los medios de Telegram ya permiten por defecto el rango de referencia RFC 2544. + - Si tu proxy resuelve hosts de medios de Telegram a `198.18.x.x`, deja primero + desactivada la marca peligrosa. Los medios de Telegram ya permiten el rango de referencia + RFC 2544 de forma predeterminada. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` debilita las protecciones - SSRF de medios de Telegram. Úsalo solo para entornos de proxy de confianza controlados por el operador - como el enrutamiento con IP falsa de Clash, Mihomo o Surge cuando sintetizan - respuestas privadas o de uso especial fuera del rango de referencia RFC 2544. - Déjalo desactivado para acceso normal de Telegram a través de internet pública. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` debilita las + protecciones SSRF de medios de Telegram. Úsalo solo para entornos de proxy + confiables controlados por el operador, como enrutamiento de IP falsa de Clash, Mihomo o Surge, + cuando sinteticen respuestas privadas o de uso especial fuera del rango de referencia + RFC 2544. Déjalo desactivado para el acceso normal de Telegram por internet pública. - - Anulaciones por entorno (temporales): + - Sobrescrituras de entorno (temporales): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` @@ -982,7 +983,7 @@ dig +short api.telegram.org AAAA -Más ayuda: [Solución de problemas de canales](/channels/troubleshooting). +Más ayuda: [Solución de problemas del canal](/es/channels/troubleshooting). ## Punteros de referencia de configuración de Telegram @@ -992,77 +993,77 @@ Referencia principal: - `channels.telegram.botToken`: token del bot (BotFather). - `channels.telegram.tokenFile`: leer el token desde una ruta de archivo normal. Los enlaces simbólicos se rechazan. - `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (predeterminado: pairing). -- `channels.telegram.allowFrom`: lista de permitidos de MD (ID numéricos de usuario de Telegram). `allowlist` requiere al menos un ID de remitente. `open` requiere `"*"`. `openclaw doctor --fix` puede resolver entradas heredadas `@username` a ID y recuperar entradas de lista de permitidos desde archivos del almacén de pairing en flujos de migración de lista de permitidos. +- `channels.telegram.allowFrom`: lista de permitidos de MD (ID numéricos de usuario de Telegram). `allowlist` requiere al menos un ID de remitente. `open` requiere `"*"`. `openclaw doctor --fix` puede resolver entradas heredadas `@username` a ID y puede recuperar entradas de lista de permitidos desde archivos del almacén de vinculación en flujos de migración de lista de permitidos. - `channels.telegram.actions.poll`: habilitar o deshabilitar la creación de sondeos de Telegram (predeterminado: habilitado; sigue requiriendo `sendMessage`). -- `channels.telegram.defaultTo`: destino predeterminado de Telegram usado por CLI `--deliver` cuando no se proporciona `--reply-to` explícito. +- `channels.telegram.defaultTo`: destino predeterminado de Telegram usado por CLI `--deliver` cuando no se proporciona un `--reply-to` explícito. - `channels.telegram.groupPolicy`: `open | allowlist | disabled` (predeterminado: allowlist). -- `channels.telegram.groupAllowFrom`: lista de permitidos de remitentes de grupo (ID numéricos de usuario de Telegram). `openclaw doctor --fix` puede resolver entradas heredadas `@username` a ID. Las entradas no numéricas se ignoran en el momento de autenticación. La autenticación de grupos no usa el respaldo del almacén de pairing de MD (`2026.2.25+`). +- `channels.telegram.groupAllowFrom`: lista de permitidos de remitentes de grupo (ID numéricos de usuario de Telegram). `openclaw doctor --fix` puede resolver entradas heredadas `@username` a ID. Las entradas no numéricas se ignoran en el momento de la autenticación. La autenticación de grupo no usa el respaldo del almacén de vinculación de MD (`2026.2.25+`). - Precedencia de múltiples cuentas: - - Cuando se configuran dos o más ID de cuenta, configura `channels.telegram.defaultAccount` (o incluye `channels.telegram.accounts.default`) para hacer explícito el enrutamiento predeterminado. - - Si no se configura ninguno, OpenClaw recurre al primer ID de cuenta normalizado y `openclaw doctor` muestra una advertencia. + - Cuando se configuran dos o más ID de cuenta, establece `channels.telegram.defaultAccount` (o incluye `channels.telegram.accounts.default`) para hacer explícito el enrutamiento predeterminado. + - Si no se configura ninguno, OpenClaw usa como respaldo el primer ID de cuenta normalizado y `openclaw doctor` muestra una advertencia. - `channels.telegram.accounts.default.allowFrom` y `channels.telegram.accounts.default.groupAllowFrom` se aplican solo a la cuenta `default`. - Las cuentas con nombre heredan `channels.telegram.allowFrom` y `channels.telegram.groupAllowFrom` cuando los valores a nivel de cuenta no están configurados. - Las cuentas con nombre no heredan `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`. - `channels.telegram.groups`: valores predeterminados por grupo + lista de permitidos (usa `"*"` para valores predeterminados globales). - - `channels.telegram.groups..groupPolicy`: anulación por grupo para `groupPolicy` (`open | allowlist | disabled`). - - `channels.telegram.groups..requireMention`: control predeterminado por mención. + - `channels.telegram.groups..groupPolicy`: sobrescritura por grupo para groupPolicy (`open | allowlist | disabled`). + - `channels.telegram.groups..requireMention`: restricción predeterminada por mención. - `channels.telegram.groups..skills`: filtro de Skills (omitir = todas las Skills, vacío = ninguna). - - `channels.telegram.groups..allowFrom`: anulación por grupo de la lista de permitidos de remitentes. + - `channels.telegram.groups..allowFrom`: sobrescritura de lista de permitidos de remitentes por grupo. - `channels.telegram.groups..systemPrompt`: prompt del sistema adicional para el grupo. - `channels.telegram.groups..enabled`: deshabilita el grupo cuando es `false`. - - `channels.telegram.groups..topics..*`: anulaciones por tema (campos de grupo + `agentId` exclusivo del tema). - - `channels.telegram.groups..topics..agentId`: enrutar este tema a un agente específico (sobrescribe el enrutamiento a nivel de grupo y de binding). -- `channels.telegram.groups..topics..groupPolicy`: anulación por tema para `groupPolicy` (`open | allowlist | disabled`). -- `channels.telegram.groups..topics..requireMention`: anulación por tema del control por mención. -- `bindings[]` de nivel superior con `type: "acp"` e ID canónico de tema `chatId:topic:topicId` en `match.peer.id`: campos de enlace persistente de temas ACP (consulta [Agentes ACP](/tools/acp-agents#channel-specific-settings)). -- `channels.telegram.direct..topics..agentId`: enrutar temas de MD a un agente específico (el mismo comportamiento que los temas de foros). -- `channels.telegram.execApprovals.enabled`: habilitar Telegram como cliente de aprobación de ejecución basado en chat para esta cuenta. -- `channels.telegram.execApprovals.approvers`: ID de usuario de Telegram autorizados para aprobar o denegar solicitudes de ejecución. Opcional cuando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` directo ya identifica al propietario. -- `channels.telegram.execApprovals.target`: `dm | channel | both` (predeterminado: `dm`). `channel` y `both` conservan el tema de Telegram de origen cuando está presente. -- `channels.telegram.execApprovals.agentFilter`: filtro opcional por ID de agente para solicitudes de aprobación reenviadas. -- `channels.telegram.execApprovals.sessionFilter`: filtro opcional por clave de sesión (subcadena o regex) para solicitudes de aprobación reenviadas. -- `channels.telegram.accounts..execApprovals`: anulación por cuenta para el enrutamiento de aprobaciones de ejecución de Telegram y la autorización de aprobadores. + - `channels.telegram.groups..topics..*`: sobrescrituras por tema (campos de grupo + `agentId` exclusivo del tema). + - `channels.telegram.groups..topics..agentId`: enruta este tema a un agente específico (sobrescribe el enrutamiento a nivel de grupo y de bindings). +- `channels.telegram.groups..topics..groupPolicy`: sobrescritura por tema para groupPolicy (`open | allowlist | disabled`). +- `channels.telegram.groups..topics..requireMention`: sobrescritura por tema de la restricción por mención. +- `bindings[]` de nivel superior con `type: "acp"` e ID canónico de tema `chatId:topic:topicId` en `match.peer.id`: campos de vinculación persistente de temas ACP (consulta [Agentes ACP](/es/tools/acp-agents#channel-specific-settings)). +- `channels.telegram.direct..topics..agentId`: enruta temas de MD a un agente específico (mismo comportamiento que los temas de foro). +- `channels.telegram.execApprovals.enabled`: habilita Telegram como cliente de aprobación de exec basado en chat para esta cuenta. +- `channels.telegram.execApprovals.approvers`: ID de usuario de Telegram autorizados para aprobar o denegar solicitudes de exec. Opcional cuando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` directo ya identifica al propietario. +- `channels.telegram.execApprovals.target`: `dm | channel | both` (predeterminado: `dm`). `channel` y `both` preservan el tema de Telegram de origen cuando está presente. +- `channels.telegram.execApprovals.agentFilter`: filtro opcional de ID de agente para solicitudes de aprobación reenviadas. +- `channels.telegram.execApprovals.sessionFilter`: filtro opcional de clave de sesión (subcadena o regex) para solicitudes de aprobación reenviadas. +- `channels.telegram.accounts..execApprovals`: sobrescritura por cuenta para el enrutamiento de aprobación de exec de Telegram y la autorización de aprobadores. - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (predeterminado: allowlist). -- `channels.telegram.accounts..capabilities.inlineButtons`: anulación por cuenta. +- `channels.telegram.accounts..capabilities.inlineButtons`: sobrescritura por cuenta. - `channels.telegram.commands.nativeSkills`: habilitar/deshabilitar comandos nativos de Skills de Telegram. - `channels.telegram.replyToMode`: `off | first | all` (predeterminado: `off`). - `channels.telegram.textChunkLimit`: tamaño de fragmento saliente (caracteres). -- `channels.telegram.chunkMode`: `length` (predeterminado) o `newline` para dividir por líneas en blanco (límites de párrafo) antes de fragmentar por longitud. +- `channels.telegram.chunkMode`: `length` (predeterminado) o `newline` para dividir en líneas en blanco (límites de párrafo) antes de fragmentar por longitud. - `channels.telegram.linkPreview`: alternar vistas previas de enlaces para mensajes salientes (predeterminado: true). - `channels.telegram.streaming`: `off | partial | block | progress` (vista previa de transmisión en vivo; predeterminado: `partial`; `progress` se asigna a `partial`; `block` es compatibilidad heredada del modo de vista previa). La transmisión de vista previa de Telegram usa un único mensaje de vista previa que se edita en el mismo lugar. - `channels.telegram.mediaMaxMb`: límite de medios entrantes/salientes de Telegram (MB, predeterminado: 100). -- `channels.telegram.retry`: política de reintento para los ayudantes de envío de Telegram (CLI/herramientas/acciones) en errores recuperables de API saliente (intentos, `minDelayMs`, `maxDelayMs`, `jitter`). -- `channels.telegram.network.autoSelectFamily`: sobrescribir `autoSelectFamily` de Node (true=habilitar, false=deshabilitar). Predeterminado habilitado en Node 22+, con WSL2 deshabilitado de forma predeterminada. -- `channels.telegram.network.dnsResultOrder`: sobrescribir el orden de resultados DNS (`ipv4first` o `verbatim`). Predeterminado `ipv4first` en Node 22+. -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opción peligrosa para entornos de IP falsa o proxy transparente de confianza donde las descargas de medios de Telegram resuelven `api.telegram.org` a direcciones privadas/internas/de uso especial fuera de la concesión predeterminada del rango de referencia RFC 2544. -- `channels.telegram.proxy`: URL de proxy para llamadas a Bot API (SOCKS/HTTP). -- `channels.telegram.webhookUrl`: habilitar modo webhook (requiere `channels.telegram.webhookSecret`). -- `channels.telegram.webhookSecret`: secreto de webhook (obligatorio cuando `webhookUrl` está configurado). -- `channels.telegram.webhookPath`: ruta local del webhook (predeterminado `/telegram-webhook`). -- `channels.telegram.webhookHost`: host local de enlace del webhook (predeterminado `127.0.0.1`). -- `channels.telegram.webhookPort`: puerto local de enlace del webhook (predeterminado `8787`). -- `channels.telegram.actions.reactions`: controla las reacciones de herramientas de Telegram. -- `channels.telegram.actions.sendMessage`: controla los envíos de mensajes de herramientas de Telegram. -- `channels.telegram.actions.deleteMessage`: controla la eliminación de mensajes de herramientas de Telegram. -- `channels.telegram.actions.sticker`: controla acciones de stickers de Telegram — envío y búsqueda (predeterminado: false). +- `channels.telegram.retry`: política de reintento para helpers de envío de Telegram (CLI/tools/actions) ante errores recuperables de la API saliente (intentos, minDelayMs, maxDelayMs, jitter). +- `channels.telegram.network.autoSelectFamily`: sobrescribe autoSelectFamily de Node (true=habilitar, false=deshabilitar). Está habilitado de forma predeterminada en Node 22+, y WSL2 lo tiene deshabilitado de forma predeterminada. +- `channels.telegram.network.dnsResultOrder`: sobrescribe el orden de resultados DNS (`ipv4first` o `verbatim`). El valor predeterminado es `ipv4first` en Node 22+. +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: habilitación opcional peligrosa para entornos confiables de IP falsa o proxy transparente donde las descargas de medios de Telegram resuelven `api.telegram.org` a direcciones privadas/internas/de uso especial fuera del rango de referencia RFC 2544 permitido de forma predeterminada. +- `channels.telegram.proxy`: URL de proxy para llamadas a la API de Bot (SOCKS/HTTP). +- `channels.telegram.webhookUrl`: habilita el modo Webhook (requiere `channels.telegram.webhookSecret`). +- `channels.telegram.webhookSecret`: secreto de Webhook (obligatorio cuando `webhookUrl` está configurado). +- `channels.telegram.webhookPath`: ruta local de Webhook (predeterminada `/telegram-webhook`). +- `channels.telegram.webhookHost`: host local de enlace de Webhook (predeterminado `127.0.0.1`). +- `channels.telegram.webhookPort`: puerto local de enlace de Webhook (predeterminado `8787`). +- `channels.telegram.actions.reactions`: restringe las reacciones de herramientas de Telegram. +- `channels.telegram.actions.sendMessage`: restringe los envíos de mensajes de herramientas de Telegram. +- `channels.telegram.actions.deleteMessage`: restringe las eliminaciones de mensajes de herramientas de Telegram. +- `channels.telegram.actions.sticker`: restringe las acciones de stickers de Telegram — envío y búsqueda (predeterminado: false). - `channels.telegram.reactionNotifications`: `off | own | all` — controla qué reacciones activan eventos del sistema (predeterminado: `own` cuando no está configurado). - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controla la capacidad de reacción del agente (predeterminado: `minimal` cuando no está configurado). -- `channels.telegram.errorPolicy`: `reply | silent` — controla el comportamiento de respuesta de error (predeterminado: `reply`). Se admiten anulaciones por cuenta/grupo/tema. +- `channels.telegram.errorPolicy`: `reply | silent` — controla el comportamiento de respuesta de error (predeterminado: `reply`). Se admiten sobrescrituras por cuenta/grupo/tema. - `channels.telegram.errorCooldownMs`: ms mínimos entre respuestas de error al mismo chat (predeterminado: `60000`). Evita spam de errores durante caídas. -- [Referencia de configuración - Telegram](/gateway/configuration-reference#telegram) +- [Referencia de configuración - Telegram](/es/gateway/configuration-reference#telegram) Campos específicos de Telegram de alta señal: - inicio/autenticación: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` debe apuntar a un archivo normal; los enlaces simbólicos se rechazan) - control de acceso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nivel superior (`type: "acp"`) -- aprobaciones de ejecución: `execApprovals`, `accounts.*.execApprovals` +- aprobaciones de exec: `execApprovals`, `accounts.*.execApprovals` - comando/menú: `commands.native`, `commands.nativeSkills`, `customCommands` -- encadenamiento/respuestas: `replyToMode` -- streaming: `streaming` (vista previa), `blockStreaming` +- enhebrado/respuestas: `replyToMode` +- transmisión: `streaming` (vista previa), `blockStreaming` - formato/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - medios/red: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - acciones/capacidades: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - reacciones: `reactionNotifications`, `reactionLevel` - errores: `errorPolicy`, `errorCooldownMs` @@ -1070,9 +1071,9 @@ Campos específicos de Telegram de alta señal: ## Relacionado -- [Pairing](/channels/pairing) -- [Grupos](/channels/groups) -- [Seguridad](/gateway/security) -- [Enrutamiento de canales](/channels/channel-routing) -- [Enrutamiento multiagente](/concepts/multi-agent) -- [Solución de problemas](/channels/troubleshooting) +- [Vinculación](/es/channels/pairing) +- [Grupos](/es/channels/groups) +- [Seguridad](/es/gateway/security) +- [Enrutamiento de canales](/es/channels/channel-routing) +- [Enrutamiento de múltiples agentes](/es/concepts/multi-agent) +- [Solución de problemas](/es/channels/troubleshooting) diff --git a/docs/es/concepts/qa-e2e-automation.md b/docs/es/concepts/qa-e2e-automation.md index a70fc2df1..00c10188c 100644 --- a/docs/es/concepts/qa-e2e-automation.md +++ b/docs/es/concepts/qa-e2e-automation.md @@ -1,37 +1,33 @@ --- read_when: - - Ampliar qa-lab o qa-channel - - Agregar escenarios de QA respaldados por el repositorio - - Crear una automatización de QA de mayor realismo en torno al panel de Gateway -summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con seed e informes de protocolo -title: Automatización E2E de QA + - Ampliación de qa-lab o qa-channel + - Agregar escenarios de control de calidad respaldados por el repositorio + - Creación de automatización de control de calidad de mayor realismo en torno al panel de Gateway +summary: Forma de la automatización privada de control de calidad para qa-lab, qa-channel, escenarios con semillas e informes de protocolo +title: Automatización E2E de control de calidad x-i18n: - generated_at: "2026-04-18T04:59:15Z" + generated_at: "2026-04-20T05:21:31Z" model: gpt-5.4 provider: openai - source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 + source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# Automatización E2E de QA +# Automatización E2E de control de calidad -La pila privada de QA está pensada para ejercitar OpenClaw de una manera más realista, -con forma de canal, que la que puede cubrir una sola prueba unitaria. +La pila privada de control de calidad está pensada para ejercitar OpenClaw de una forma más realista y con forma de canal que una sola prueba unitaria. Piezas actuales: -- `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo, - reacción, edición y eliminación. -- `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción, - inyectar mensajes entrantes y exportar un informe en Markdown. -- `qa/`: recursos seed respaldados por el repositorio para la tarea inicial y los - escenarios base de QA. +- `extensions/qa-channel`: canal de mensajes sintético con superficies de DM, canal, hilo, reacción, edición y eliminación. +- `extensions/qa-lab`: interfaz de depuración y bus de control de calidad para observar la transcripción, inyectar mensajes entrantes y exportar un informe en Markdown. +- `qa/`: recursos semilla respaldados por el repositorio para la tarea inicial y los escenarios base de control de calidad. -El flujo actual del operador de QA es un sitio de QA de dos paneles: +El flujo actual del operador de control de calidad es un sitio de control de calidad de dos paneles: - Izquierda: panel de Gateway (Control UI) con el agente. -- Derecha: QA Lab, que muestra la transcripción tipo Slack y el plan del escenario. +- Derecha: QA Lab, que muestra la transcripción estilo Slack y el plan del escenario. Ejecútalo con: @@ -39,13 +35,9 @@ Ejecútalo con: pnpm qa:lab:up ``` -Eso compila el sitio de QA, inicia el carril de Gateway respaldado por Docker y expone la -página de QA Lab, donde un operador o un bucle de automatización puede darle al agente una -misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o -qué siguió bloqueado. +Eso compila el sitio de control de calidad, inicia el carril de Gateway respaldado por Docker y expone la página de QA Lab donde un operador o un bucle de automatización puede darle al agente una misión de control de calidad, observar el comportamiento real del canal y registrar qué funcionó, qué falló o qué siguió bloqueado. -Para una iteración más rápida de la UI de QA Lab sin reconstruir la imagen de Docker cada vez, -inicia la pila con un bundle de QA Lab montado por enlace: +Para una iteración más rápida de la interfaz de QA Lab sin reconstruir la imagen de Docker cada vez, inicia la pila con un bundle de QA Lab montado con bind: ```bash pnpm openclaw qa docker-build-image @@ -54,105 +46,73 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta por enlace -`extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` -recompila ese bundle cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash -de recursos de QA Lab. +`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta con bind `extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` recompila ese bundle cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash de recursos de QA Lab. -Para un carril smoke de Matrix con transporte real, ejecuta: +Para un carril de humo de Matrix con transporte real, ejecuta: ```bash pnpm openclaw qa matrix ``` -Ese carril aprovisiona un homeserver Tuwunel desechable en Docker, registra usuarios temporales -de controlador, SUT y observador, crea una sala privada y luego ejecuta el Plugin real de Matrix dentro -de un proceso hijo de Gateway de QA. El carril de transporte en vivo mantiene la configuración del proceso hijo -limitada al transporte bajo prueba, por lo que Matrix se ejecuta sin `qa-channel` en la configuración -del proceso hijo. Escribe los artefactos de informe estructurado y un registro combinado de stdout/stderr -en el directorio de salida de Matrix QA seleccionado. Para capturar también la salida externa de compilación/lanzamiento -de `scripts/run-node.mjs`, establece `OPENCLAW_RUN_NODE_OUTPUT_LOG=` en un archivo de registro local del repositorio. +Ese carril aprovisiona un homeserver Tuwunel desechable en Docker, registra usuarios temporales de controlador, SUT y observador, crea una sala privada y luego ejecuta el plugin real de Matrix dentro de un proceso hijo de Gateway de control de calidad. El carril de transporte en vivo mantiene la configuración hija acotada al transporte bajo prueba, de modo que Matrix se ejecuta sin `qa-channel` en la configuración hija. Escribe los artefactos de informe estructurado y un registro combinado de stdout/stderr en el directorio de salida de QA de Matrix seleccionado. Para capturar también la salida externa de compilación/lanzamiento de `scripts/run-node.mjs`, establece `OPENCLAW_RUN_NODE_OUTPUT_LOG=` en un archivo de registro local del repositorio. -Para un carril smoke de Telegram con transporte real, ejecuta: +Para un carril de humo de Telegram con transporte real, ejecuta: ```bash pnpm openclaw qa telegram ``` -Ese carril apunta a un grupo privado real de Telegram en lugar de aprovisionar un servidor desechable. -Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, -`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo -grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación bot a bot -funciona mejor cuando ambos bots tienen habilitado el modo de comunicación Bot-to-Bot -en `@BotFather`. +Ese carril apunta a un grupo privado real de Telegram en lugar de aprovisionar un servidor desechable. Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación entre bots funciona mejor cuando ambos bots tienen habilitado el Bot-to-Bot Communication Mode en `@BotFather`. +El comando sale con un código distinto de cero cuando falla cualquier escenario. Usa `--allow-failures` cuando quieras artefactos sin un código de salida fallido. -Los carriles de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada uno invente -su propia forma de lista de escenarios. +Los carriles de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada uno invente su propia forma de lista de escenarios: -`qa-channel` sigue siendo la amplia suite sintética de comportamiento del producto y no forma parte -de la matriz de cobertura de transporte en vivo. +`qa-channel` sigue siendo la suite amplia de comportamiento sintético del producto y no forma parte de la matriz de cobertura de transporte en vivo. -| Carril | Canary | Puerta por mención | Bloqueo por allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando help | -| -------- | ------ | ------------------ | --------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Carril | Canary | Restricción por mención | Bloqueo por lista de permitidos | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda | +| -------- | ------ | ----------------------- | -------------------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Esto mantiene `qa-channel` como la amplia suite de comportamiento del producto, mientras que Matrix, -Telegram y futuros transportes en vivo comparten una lista explícita de comprobación del contrato -de transporte. +Esto mantiene `qa-channel` como la suite amplia de comportamiento del producto, mientras que Matrix, Telegram y futuros transportes en vivo comparten una lista de verificación explícita del contrato de transporte. -Para un carril de VM Linux desechable sin incorporar Docker en la ruta de QA, ejecuta: +Para un carril en VM Linux desechable sin incorporar Docker en la ruta de control de calidad, ejecuta: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Esto inicia un huésped nuevo de Multipass, instala dependencias, compila OpenClaw -dentro del huésped, ejecuta `qa suite` y luego copia el informe y resumen normales de QA de vuelta a -`.artifacts/qa-e2e/...` en el host. +Esto arranca un invitado nuevo de Multipass, instala dependencias, compila OpenClaw dentro del invitado, ejecuta `qa suite` y luego copia el informe y resumen normales de control de calidad de vuelta a `.artifacts/qa-e2e/...` en el host. Reutiliza el mismo comportamiento de selección de escenarios que `qa suite` en el host. -Las ejecuciones del host y de Multipass ejecutan varios escenarios seleccionados en paralelo -con workers de Gateway aislados de forma predeterminada, hasta 64 workers o la cantidad de escenarios -seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o -`--concurrency 1` para ejecución en serie. -Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que son prácticas para el -huésped: claves de proveedor basadas en variables de entorno, la ruta de configuración del proveedor en vivo de QA y -`CODEX_HOME` cuando esté presente. Mantén `--output-dir` bajo la raíz del repositorio para que el huésped -pueda escribir de vuelta a través del espacio de trabajo montado. +Las ejecuciones de suite en host y en Multipass ejecutan varios escenarios seleccionados en paralelo con workers de Gateway aislados por defecto. `qa-channel` usa por defecto una concurrencia de 4, limitada por el número de escenarios seleccionados. Usa `--concurrency ` para ajustar el número de workers, o `--concurrency 1` para ejecución en serie. +El comando sale con un código distinto de cero cuando falla cualquier escenario. Usa `--allow-failures` cuando quieras artefactos sin un código de salida fallido. +Las ejecuciones en vivo reenvían las entradas de autenticación de control de calidad compatibles que son prácticas para el invitado: claves de proveedor basadas en entorno, la ruta de configuración del proveedor en vivo de control de calidad y `CODEX_HOME` cuando está presente. Mantén `--output-dir` bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través del espacio de trabajo montado. -## Seeds respaldados por el repositorio +## Semillas respaldadas por el repositorio -Los recursos seed viven en `qa/`: +Los recursos semilla viven en `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Estos están intencionalmente en git para que el plan de QA sea visible tanto para las personas como para el -agente. +Estos están intencionalmente en git para que el plan de control de calidad sea visible tanto para humanos como para el agente. -`qa-lab` debe seguir siendo un ejecutor genérico de Markdown. Cada archivo Markdown de escenario es -la fuente de verdad para una ejecución de prueba y debe definir: +`qa-lab` debe seguir siendo un ejecutor genérico de Markdown. Cada archivo Markdown de escenario es la fuente de verdad para una ejecución de prueba y debe definir: - metadatos del escenario - metadatos opcionales de categoría, capacidad, carril y riesgo -- referencias de documentación y código -- requisitos opcionales de Plugin +- referencias a documentación y código +- requisitos opcionales de plugin - parche opcional de configuración de Gateway - el `qa-flow` ejecutable -La superficie de ejecución reutilizable que respalda `qa-flow` puede seguir siendo genérica -y transversal. Por ejemplo, los escenarios Markdown pueden combinar ayudantes del lado del transporte -con ayudantes del lado del navegador que controlan la Control UI integrada a través de la -interfaz `browser.request` de Gateway sin agregar un ejecutor de caso especial. +La superficie de tiempo de ejecución reutilizable que respalda `qa-flow` puede seguir siendo genérica y transversal. Por ejemplo, los escenarios Markdown pueden combinar helpers del lado del transporte con helpers del lado del navegador que controlan la Control UI incrustada a través de la superficie `browser.request` de Gateway sin agregar un ejecutor de caso especial. -Los archivos de escenario deben agruparse por capacidad del producto en lugar de por carpeta del árbol -de código fuente. Mantén estables los ID de escenario cuando los archivos se muevan; usa `docsRefs` y `codeRefs` -para la trazabilidad de implementación. +Los archivos de escenario deben agruparse por capacidad del producto en lugar de por carpeta del árbol de código fuente. Mantén estables los IDs de escenario cuando se muevan archivos; usa `docsRefs` y `codeRefs` para la trazabilidad de implementación. -La lista base debe seguir siendo lo suficientemente amplia como para cubrir: +La lista base debe seguir siendo lo bastante amplia como para cubrir: -- chat por MD y canal +- chat por DM y por canal - comportamiento de hilos - ciclo de vida de acciones de mensajes - callbacks de Cron @@ -160,38 +120,31 @@ La lista base debe seguir siendo lo suficientemente amplia como para cubrir: - cambio de modelo - transferencia a subagente - lectura del repositorio y de la documentación -- una pequeña tarea de compilación como Lobster Invaders +- una tarea pequeña de compilación como Lobster Invaders -## Carriles de proveedor simulado +## Carriles de simulación de proveedores -`qa suite` tiene dos carriles locales de proveedor simulado: +`qa suite` tiene dos carriles locales de simulación de proveedores: -- `mock-openai` es el simulador de OpenClaw consciente del escenario. Sigue siendo el - carril simulado determinista predeterminado para QA respaldado por el repositorio y compuertas de paridad. -- `aimock` inicia un servidor de proveedor respaldado por AIMock para cobertura experimental de protocolo, - fixtures, grabación/reproducción y caos. Es complementario y no reemplaza al despachador de escenarios - `mock-openai`. +- `mock-openai` es el simulador de OpenClaw consciente de escenarios. Sigue siendo el carril de simulación determinista predeterminado para el control de calidad respaldado por el repositorio y las compuertas de paridad. +- `aimock` inicia un servidor de proveedor respaldado por AIMock para cobertura experimental de protocolo, fixtures, grabación/reproducción y caos. Es aditivo y no reemplaza el despachador de escenarios de `mock-openai`. La implementación del carril de proveedor vive en `extensions/qa-lab/src/providers/`. -Cada proveedor es dueño de sus valores predeterminados, el arranque del servidor local, la configuración -del modelo de Gateway, las necesidades de preparación del perfil de autenticación y los indicadores de capacidad -live/mock. El código compartido de suite y Gateway debe enrutar a través del registro de proveedores -en lugar de ramificarse según los nombres de proveedor. +Cada proveedor es dueño de sus valores predeterminados, el arranque del servidor local, la configuración del modelo de Gateway, las necesidades de preparación del perfil de autenticación y los indicadores de capacidad de vivo/simulado. El código compartido de suite y Gateway debe enrutar a través del registro de proveedores en lugar de bifurcar según nombres de proveedor. ## Adaptadores de transporte -`qa-lab` es dueño de una interfaz genérica de transporte para escenarios Markdown de QA. -`qa-channel` es el primer adaptador sobre esa interfaz, pero el objetivo de diseño es más amplio: -canales futuros, reales o sintéticos, deberían integrarse en el mismo ejecutor de suite en lugar -de agregar un ejecutor de QA específico para cada transporte. +`qa-lab` es dueño de una superficie genérica de transporte para escenarios de control de calidad en Markdown. +`qa-channel` es el primer adaptador sobre esa superficie, pero el objetivo de diseño es más amplio: +los futuros canales reales o sintéticos deben conectarse al mismo ejecutor de suite en lugar de agregar un ejecutor de control de calidad específico por transporte. A nivel de arquitectura, la división es: -- `qa-lab` es dueño de la ejecución genérica de escenarios, la concurrencia de workers, la escritura de artefactos y los informes. -- el adaptador de transporte es dueño de la configuración de Gateway, la preparación, la observación de entrada y salida, las acciones de transporte y el estado de transporte normalizado. -- los archivos Markdown de escenarios bajo `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de ejecución reutilizable que los ejecuta. +- `qa-lab` es dueño de la ejecución genérica de escenarios, la concurrencia de workers, la escritura de artefactos y la generación de informes. +- el adaptador de transporte es dueño de la configuración de Gateway, la preparación, la observación entrante y saliente, las acciones de transporte y el estado de transporte normalizado. +- los archivos de escenario Markdown en `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de tiempo de ejecución reutilizable que los ejecuta. -La guía de adopción dirigida a mantenedores para nuevos adaptadores de canal se encuentra en +La guía de adopción orientada a mantenedores para nuevos adaptadores de canal vive en [Testing](/es/help/testing#adding-a-channel-to-qa). ## Informes @@ -204,8 +157,7 @@ El informe debe responder: - Qué siguió bloqueado - Qué escenarios de seguimiento vale la pena agregar -Para comprobaciones de carácter y estilo, ejecuta el mismo escenario con múltiples referencias de modelos en vivo -y escribe un informe Markdown evaluado: +Para verificaciones de carácter y estilo, ejecuta el mismo escenario en múltiples refs de modelos en vivo y escribe un informe evaluado en Markdown: ```bash pnpm openclaw qa character-eval \ @@ -224,30 +176,12 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -El comando ejecuta procesos hijo locales de Gateway de QA, no Docker. Los escenarios de evaluación de carácter -deben establecer la personalidad mediante `SOUL.md`, y luego ejecutar turnos de usuario normales -como chat, ayuda del espacio de trabajo y pequeñas tareas con archivos. No se le debe decir al -modelo candidato que está siendo evaluado. El comando conserva cada transcripción completa, -registra estadísticas básicas de ejecución y luego pide a los modelos jueces en modo fast con -razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor. -Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo -cada transcripción y estado de ejecución, pero las referencias candidatas se reemplazan por -etiquetas neutras como `candidate-01`; el informe vuelve a mapear las clasificaciones a las referencias reales -después del análisis. -Las ejecuciones candidatas usan `high` thinking de forma predeterminada, con `xhigh` para los modelos de OpenAI -que lo admiten. Sustituye un candidato específico en línea con -`--model provider/model,thinking=`. `--thinking ` sigue estableciendo una -alternativa global, y la forma antigua `--model-thinking ` se -mantiene por compatibilidad. -Las referencias candidatas de OpenAI usan el modo fast de forma predeterminada para que se use procesamiento prioritario -cuando el proveedor lo admita. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando -un solo candidato o juez necesite una sustitución. Pasa `--fast` solo cuando quieras -forzar el modo fast para todos los modelos candidatos. Las duraciones de candidatos y jueces se -registran en el informe para análisis comparativo, pero los prompts de los jueces indican explícitamente -que no se clasifique por velocidad. -Tanto las ejecuciones de modelos candidatos como las de los jueces usan concurrencia 16 de forma predeterminada. Reduce -`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión del Gateway local -hagan que una ejecución sea demasiado ruidosa. +El comando ejecuta procesos hijo locales de Gateway de control de calidad, no Docker. Los escenarios de evaluación de carácter deben establecer la persona mediante `SOUL.md`, y luego ejecutar turnos ordinarios de usuario como chat, ayuda del espacio de trabajo y pequeñas tareas de archivos. No se le debe decir al modelo candidato que está siendo evaluado. El comando conserva cada transcripción completa, registra estadísticas básicas de ejecución y luego pide a los modelos jueces en modo rápido con razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor. +Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo cada transcripción y estado de ejecución, pero las refs candidatas se reemplazan por etiquetas neutrales como `candidate-01`; el informe vuelve a mapear las clasificaciones a las refs reales después del análisis. +Las ejecuciones candidatas usan por defecto thinking `high`, con `xhigh` para modelos OpenAI que lo admiten. Sustituye un candidato específico en línea con +`--model provider/model,thinking=`. `--thinking ` sigue estableciendo un valor de respaldo global, y la forma anterior `--model-thinking ` se mantiene por compatibilidad. +Las refs candidatas de OpenAI usan por defecto el modo rápido para que se use procesamiento prioritario cuando el proveedor lo admita. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando un solo candidato o juez necesite una sustitución. Pasa `--fast` solo cuando quieras forzar el modo rápido para cada modelo candidato. Las duraciones de candidatos y jueces se registran en el informe para análisis comparativo, pero los prompts de los jueces indican explícitamente que no deben clasificar por velocidad. +Las ejecuciones de modelos candidatos y jueces usan ambas por defecto una concurrencia de 16. Reduce `--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión local sobre Gateway hagan que una ejecución sea demasiado ruidosa. Cuando no se pasa ningún `--model` candidato, la evaluación de carácter usa por defecto `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, @@ -261,4 +195,4 @@ Cuando no se pasa ningún `--judge-model`, los jueces usan por defecto - [Testing](/es/help/testing) - [QA Channel](/es/channels/qa-channel) -- [Dashboard](/web/dashboard) +- [Panel](/web/dashboard) diff --git a/docs/es/gateway/configuration-reference.md b/docs/es/gateway/configuration-reference.md index bedaa9be3..cd1776da0 100644 --- a/docs/es/gateway/configuration-reference.md +++ b/docs/es/gateway/configuration-reference.md @@ -1,34 +1,34 @@ --- read_when: - - Necesitas la semántica exacta de configuración a nivel de campo o los valores predeterminados. - - Estás validando bloques de configuración de canal, modelo, Gateway o herramienta. -summary: Referencia de configuración del Gateway para las claves principales de OpenClaw, los valores predeterminados y enlaces a referencias dedicadas de subsistemas + - Necesita la semántica exacta o los valores predeterminados de la configuración a nivel de campo + - Está validando bloques de configuración de canales, modelos, Gateway o herramientas +summary: Referencia de configuración de Gateway para las claves principales de OpenClaw, los valores predeterminados y enlaces a referencias dedicadas de subsistemas title: Referencia de configuración x-i18n: - generated_at: "2026-04-18T04:59:13Z" + generated_at: "2026-04-20T05:21:26Z" model: gpt-5.4 provider: openai - source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f + source_hash: 22b10f1f133374cd29ef4a5ec4fb9c9938eb51184ad82e1aa2e5f6f7af58585e source_path: gateway/configuration-reference.md workflow: 15 --- # Referencia de configuración -Referencia de configuración principal para `~/.openclaw/openclaw.json`. Para una descripción general orientada a tareas, consulta [Configuración](/es/gateway/configuration). +Referencia de configuración principal para `~/.openclaw/openclaw.json`. Para una visión general orientada a tareas, consulte [Configuration](/es/gateway/configuration). -Esta página cubre las principales superficies de configuración de OpenClaw y enlaza cuando un subsistema tiene su propia referencia más detallada. **No** intenta incluir en línea cada catálogo de comandos propiedad de canales/plugins ni cada ajuste profundo de memoria/QMD en una sola página. +Esta página cubre las principales superficies de configuración de OpenClaw y enlaza a otras referencias cuando un subsistema tiene su propia referencia más profunda. **No** intenta incluir en una sola página cada catálogo de comandos propiedad de canales/plugins ni cada ajuste profundo de memoria/QMD. Fuente de verdad del código: -- `openclaw config schema` imprime el JSON Schema activo usado para validación y la Control UI, con los metadatos de bundled/plugin/channel fusionados cuando están disponibles -- `config.schema.lookup` devuelve un nodo de esquema con alcance a una ruta para herramientas de exploración detallada -- `pnpm config:docs:check` / `pnpm config:docs:gen` validan el hash de referencia base de la documentación de configuración frente a la superficie actual del esquema +- `openclaw config schema` imprime el JSON Schema activo usado para la validación y la Control UI, con los metadatos de bundled/plugin/channel fusionados cuando están disponibles +- `config.schema.lookup` devuelve un nodo del esquema limitado a una ruta para herramientas de exploración detallada +- `pnpm config:docs:check` / `pnpm config:docs:gen` validan el hash de la línea base de la documentación de configuración frente a la superficie actual del esquema -Referencias detalladas dedicadas: +Referencias profundas dedicadas: -- [Referencia de configuración de memoria](/es/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` y la configuración de Dreaming bajo `plugins.entries.memory-core.config.dreaming` -- [Comandos slash](/es/tools/slash-commands) para el catálogo actual de comandos integrados + bundled +- [Referencia de configuración de memoria](/es/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` y la configuración de Dreaming en `plugins.entries.memory-core.config.dreaming` +- [Comandos de barra](/es/tools/slash-commands) para el catálogo actual de comandos integrados + bundled - páginas del canal/plugin propietario para superficies de comandos específicas del canal El formato de configuración es **JSON5** (se permiten comentarios y comas finales). Todos los campos son opcionales: OpenClaw usa valores predeterminados seguros cuando se omiten. @@ -37,34 +37,34 @@ El formato de configuración es **JSON5** (se permiten comentarios y comas final ## Canales -Cada canal se inicia automáticamente cuando existe su sección de configuración (a menos que `enabled: false`). +Cada canal se inicia automáticamente cuando su sección de configuración existe (a menos que `enabled: false`). ### Acceso a MD y grupos Todos los canales admiten políticas de MD y políticas de grupo: -| Política de MD | Comportamiento | -| ------------------- | ------------------------------------------------------------- | +| Política de MD | Comportamiento | +| ------------------- | -------------------------------------------------------------- | | `pairing` (default) | Los remitentes desconocidos reciben un código de vinculación de un solo uso; el propietario debe aprobarlo | -| `allowlist` | Solo remitentes en `allowFrom` (o en el almacén de permitidos emparejados) | -| `open` | Permitir todas las MD entrantes (requiere `allowFrom: ["*"]`) | -| `disabled` | Ignorar todas las MD entrantes | +| `allowlist` | Solo remitentes en `allowFrom` (o en el almacén de permisos vinculados) | +| `open` | Permitir todos los MD entrantes (requiere `allowFrom: ["*"]`) | +| `disabled` | Ignorar todos los MD entrantes | -| Política de grupo | Comportamiento | -| --------------------- | ----------------------------------------------------- | +| Política de grupo | Comportamiento | +| --------------------- | ------------------------------------------------------ | | `allowlist` (default) | Solo grupos que coincidan con la lista de permitidos configurada | -| `open` | Omitir las listas de permitidos de grupos (el requisito de mención sigue aplicándose) | -| `disabled` | Bloquear todos los mensajes de grupo/sala | +| `open` | Omite las listas de permitidos de grupos (la restricción por mención sigue aplicándose) | +| `disabled` | Bloquea todos los mensajes de grupo/sala | `channels.defaults.groupPolicy` establece el valor predeterminado cuando `groupPolicy` de un proveedor no está definido. -Los códigos de vinculación vencen después de 1 hora. Las solicitudes pendientes de vinculación de MD están limitadas a **3 por canal**. -Si falta por completo un bloque de proveedor (`channels.` ausente), la política de grupo en tiempo de ejecución vuelve a `allowlist` (fallo cerrado) con una advertencia al iniciar. +Los códigos de vinculación caducan después de 1 hora. Las solicitudes pendientes de vinculación de MD están limitadas a **3 por canal**. +Si falta por completo un bloque de proveedor (`channels.` ausente), la política de grupo en tiempo de ejecución vuelve a `allowlist` (cerrado por defecto) con una advertencia al inicio. ### Sobrescrituras de modelo por canal -Usa `channels.modelByChannel` para fijar IDs de canal específicos a un modelo. Los valores aceptan `provider/model` o alias de modelo configurados. La asignación de canal se aplica cuando una sesión no tiene ya una sobrescritura de modelo (por ejemplo, establecida mediante `/model`). +Use `channels.modelByChannel` para fijar IDs de canales específicos a un modelo. Los valores aceptan `provider/model` o alias de modelos configurados. La asignación del canal se aplica cuando una sesión no tiene ya una sobrescritura de modelo (por ejemplo, establecida mediante `/model`). ```json5 { @@ -87,7 +87,7 @@ Usa `channels.modelByChannel` para fijar IDs de canal específicos a un modelo. ### Valores predeterminados del canal y Heartbeat -Usa `channels.defaults` para el comportamiento compartido de política de grupo y Heartbeat entre proveedores: +Use `channels.defaults` para el comportamiento compartido de política de grupos y Heartbeat entre proveedores: ```json5 { @@ -106,10 +106,10 @@ Usa `channels.defaults` para el comportamiento compartido de política de grupo ``` - `channels.defaults.groupPolicy`: política de grupo de respaldo cuando `groupPolicy` a nivel de proveedor no está definido. -- `channels.defaults.contextVisibility`: modo predeterminado de visibilidad de contexto suplementario para todos los canales. Valores: `all` (predeterminado, incluir todo el contexto citado/de hilo/de historial), `allowlist` (incluir solo contexto de remitentes en la lista de permitidos), `allowlist_quote` (igual que allowlist pero conserva el contexto explícito de cita/respuesta). Sobrescritura por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: incluir estados de canal saludables en la salida de Heartbeat. +- `channels.defaults.contextVisibility`: modo de visibilidad del contexto suplementario predeterminado para todos los canales. Valores: `all` (predeterminado, incluye todo el contexto citado/de hilo/historial), `allowlist` (solo incluye contexto de remitentes en la lista de permitidos), `allowlist_quote` (igual que allowlist, pero conserva el contexto explícito de cita/respuesta). Sobrescritura por canal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: incluir estados saludables de canales en la salida de Heartbeat. - `channels.defaults.heartbeat.showAlerts`: incluir estados degradados/con error en la salida de Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: mostrar la salida de Heartbeat en estilo compacto con indicador. +- `channels.defaults.heartbeat.useIndicator`: mostrar una salida de Heartbeat compacta con estilo de indicador. ### WhatsApp @@ -146,7 +146,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` - + ```json5 { @@ -164,9 +164,9 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- Los comandos salientes usan de forma predeterminada la cuenta `default` si existe; de lo contrario, el primer id de cuenta configurado (ordenado). -- `channels.whatsapp.defaultAccount` opcional sobrescribe esa selección predeterminada de cuenta de respaldo cuando coincide con un id de cuenta configurado. -- El directorio heredado de autenticación de Baileys para una sola cuenta se migra con `openclaw doctor` a `whatsapp/default`. +- Los comandos salientes usan por defecto la cuenta `default` si está presente; de lo contrario, la primera ID de cuenta configurada (ordenada). +- `channels.whatsapp.defaultAccount` opcional sobrescribe esa selección de cuenta predeterminada de respaldo cuando coincide con una ID de cuenta configurada. +- El directorio de autenticación heredado de Baileys para una sola cuenta es migrado por `openclaw doctor` a `whatsapp/default`. - Sobrescrituras por cuenta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -226,12 +226,12 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia ``` - Token del bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo archivo normal; se rechazan enlaces simbólicos), con `TELEGRAM_BOT_TOKEN` como respaldo para la cuenta predeterminada. -- `channels.telegram.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. -- En configuraciones con múltiples cuentas (2 o más ids de cuenta), establece un valor predeterminado explícito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) para evitar el enrutamiento de respaldo; `openclaw doctor` advierte cuando falta o es inválido. -- `configWrites: false` bloquea escrituras de configuración iniciadas desde Telegram (migraciones de ID de supergrupo, `/config set|unset`). -- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran enlaces ACP persistentes para temas de foro (usa el formato canónico `chatId:topic:topicId` en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). -- Las vistas previas de streaming en Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y grupales). -- Política de reintento: consulta [Política de reintento](/es/concepts/retry). +- `channels.telegram.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- En configuraciones con varias cuentas (2 o más IDs de cuenta), establezca un valor predeterminado explícito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) para evitar el enrutamiento de respaldo; `openclaw doctor` advierte cuando falta o no es válido. +- `configWrites: false` bloquea las escrituras de configuración iniciadas desde Telegram (migraciones de ID de supergrupo, `/config set|unset`). +- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran asociaciones persistentes de ACP para temas de foro (use el formato canónico `chatId:topic:topicId` en `match.peer.id`). La semántica de los campos se comparte en [ACP Agents](/es/tools/acp-agents#channel-specific-settings). +- Las vistas previas de transmisión de Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y grupales). +- Política de reintentos: consulte [Política de reintentos](/es/concepts/retry). ### Discord @@ -334,35 +334,35 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia ``` - Token: `channels.discord.token`, con `DISCORD_BOT_TOKEN` como respaldo para la cuenta predeterminada. -- Las llamadas salientes directas que proporcionan un `token` de Discord explícito usan ese token para la llamada; los ajustes de política/reintento de la cuenta siguen viniendo de la cuenta seleccionada en la instantánea activa del tiempo de ejecución. -- `channels.discord.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. -- Usa `user:` (MD) o `channel:` (canal de guild) para los destinos de entrega; los IDs numéricos sin prefijo se rechazan. -- Los slugs de guild están en minúsculas y con los espacios reemplazados por `-`; las claves de canal usan el nombre convertido a slug (sin `#`). Se prefieren los IDs de guild. -- Los mensajes creados por bots se ignoran de forma predeterminada. `allowBots: true` los habilita; usa `allowBots: "mentions"` para aceptar solo mensajes de bots que mencionen al bot (los mensajes propios siguen filtrándose). -- `channels.discord.guilds..ignoreOtherMentions` (y las sobrescrituras por canal) descarta mensajes que mencionan a otro usuario o rol, pero no al bot (excluyendo @everyone/@here). -- `maxLinesPerMessage` (predeterminado 17) divide mensajes altos incluso cuando están por debajo de 2000 caracteres. -- `channels.discord.threadBindings` controla el enrutamiento vinculado a hilos de Discord: - - `enabled`: sobrescritura de Discord para funciones de sesión vinculadas a hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, y entrega/enrutamiento vinculados) - - `idleHours`: sobrescritura de Discord para auto-unfocus por inactividad en horas (`0` lo desactiva) +- Las llamadas salientes directas que proporcionan un `token` de Discord explícito usan ese token para la llamada; la configuración de reintento/política de la cuenta sigue viniendo de la cuenta seleccionada en la instantánea activa del runtime. +- `channels.discord.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- Use `user:` (MD) o `channel:` (canal del servidor) para los destinos de entrega; las IDs numéricas sin prefijo se rechazan. +- Los slugs de servidores están en minúsculas y los espacios se reemplazan por `-`; las claves de canal usan el nombre con slug (sin `#`). Prefiera las IDs de servidor. +- Los mensajes creados por bots se ignoran de forma predeterminada. `allowBots: true` los habilita; use `allowBots: "mentions"` para aceptar solo mensajes de bots que mencionen al bot (los mensajes propios siguen filtrándose). +- `channels.discord.guilds..ignoreOtherMentions` (y las sobrescrituras por canal) descarta mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here). +- `maxLinesPerMessage` (predeterminado 17) divide mensajes altos incluso cuando tienen menos de 2000 caracteres. +- `channels.discord.threadBindings` controla el enrutamiento asociado a hilos de Discord: + - `enabled`: sobrescritura de Discord para funciones de sesión asociadas a hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` y entrega/enrutamiento asociados) + - `idleHours`: sobrescritura de Discord para el desenfoque automático por inactividad en horas (`0` lo desactiva) - `maxAgeHours`: sobrescritura de Discord para la antigüedad máxima estricta en horas (`0` lo desactiva) - - `spawnSubagentSessions`: interruptor de opt-in para la creación/vinculación automática de hilos con `sessions_spawn({ thread: true })` -- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran enlaces ACP persistentes para canales e hilos (usa el id de canal/hilo en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). + - `spawnSubagentSessions`: interruptor opt-in para la creación/asociación automática de hilos con `sessions_spawn({ thread: true })` +- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran asociaciones persistentes de ACP para canales e hilos (use la id del canal/hilo en `match.peer.id`). La semántica de los campos se comparte en [ACP Agents](/es/tools/acp-agents#channel-specific-settings). - `channels.discord.ui.components.accentColor` establece el color de acento para los contenedores de componentes v2 de Discord. - `channels.discord.voice` habilita conversaciones en canales de voz de Discord y sobrescrituras opcionales de unión automática + TTS. - `channels.discord.voice.daveEncryption` y `channels.discord.voice.decryptionFailureTolerance` se transfieren a las opciones DAVE de `@discordjs/voice` (`true` y `24` de forma predeterminada). -- OpenClaw además intenta recuperar la recepción de voz saliendo y volviendo a unirse a una sesión de voz después de fallas repetidas de descifrado. -- `channels.discord.streaming` es la clave canónica del modo de transmisión. Los valores heredados `streamMode` y `streaming` booleano se migran automáticamente. -- `channels.discord.autoPresence` asigna la disponibilidad del tiempo de ejecución a la presencia del bot (healthy => online, degraded => idle, exhausted => dnd) y permite sobrescrituras opcionales de texto de estado. +- OpenClaw también intenta recuperar la recepción de voz saliendo y volviendo a unirse a una sesión de voz después de fallos repetidos de descifrado. +- `channels.discord.streaming` es la clave canónica del modo de transmisión. Los valores heredados `streamMode` y booleanos `streaming` se migran automáticamente. +- `channels.discord.autoPresence` asigna la disponibilidad del runtime a la presencia del bot (saludable => online, degradado => idle, agotado => dnd) y permite sobrescrituras opcionales del texto de estado. - `channels.discord.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia por nombre/tag mutable (modo de compatibilidad de emergencia). -- `channels.discord.execApprovals`: entrega nativa de aprobaciones de ejecución de Discord y autorización de aprobadores. +- `channels.discord.execApprovals`: entrega de aprobaciones de ejecución nativa de Discord y autorización de aprobadores. - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, las aprobaciones de ejecución se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. - - `approvers`: IDs de usuario de Discord autorizados para aprobar solicitudes de ejecución. Si se omite, usa `commands.ownerAllowFrom` como respaldo. - - `agentFilter`: lista opcional de permitidos de IDs de agente. Omítela para reenviar aprobaciones para todos los agentes. - - `sessionFilter`: patrones opcionales de clave de sesión (subcadena o regex). - - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado) las envía a las MD de los aprobadores, `"channel"` las envía al canal de origen, `"both"` las envía a ambos. Cuando el destino incluye `"channel"`, los botones solo pueden ser usados por aprobadores resueltos. - - `cleanupAfterResolve`: cuando es `true`, elimina las MD de aprobación después de aprobar, denegar o agotar el tiempo de espera. + - `approvers`: IDs de usuario de Discord autorizadas para aprobar solicitudes de ejecución. Usa `commands.ownerAllowFrom` como respaldo cuando se omite. + - `agentFilter`: lista de permitidos opcional de IDs de agentes. Omítala para reenviar aprobaciones de todos los agentes. + - `sessionFilter`: patrones opcionales de claves de sesión (subcadena o regex). + - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado) las envía a los MD de los aprobadores, `"channel"` las envía al canal de origen, `"both"` las envía a ambos. Cuando el destino incluye `"channel"`, los botones solo pueden usarlos los aprobadores resueltos. + - `cleanupAfterResolve`: cuando es `true`, elimina los MD de aprobación después de aprobar, denegar o agotar el tiempo. -**Modos de notificación de reacciones:** `off` (ninguno), `own` (mensajes del bot, predeterminado), `all` (todos los mensajes), `allowlist` (de `guilds..users` en todos los mensajes). +**Modos de notificación de reacciones:** `off` (ninguno), `own` (mensajes del bot, predeterminado), `all` (todos los mensajes), `allowlist` (desde `guilds..users` en todos los mensajes). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- JSON de cuenta de servicio: en línea (`serviceAccount`) o basado en archivo (`serviceAccountFile`). +- JSON de cuenta de servicio: integrado (`serviceAccount`) o basado en archivo (`serviceAccountFile`). - También se admite SecretRef para la cuenta de servicio (`serviceAccountRef`). - Respaldos por variable de entorno: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Usa `spaces/` o `users/` para los destinos de entrega. -- `channels.googlechat.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia mutable de principals de correo electrónico (modo de compatibilidad de emergencia). +- Use `spaces/` o `users/` para los destinos de entrega. +- `channels.googlechat.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia mutable de principal por correo electrónico (modo de compatibilidad de emergencia). ### Slack @@ -464,29 +464,34 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- **Modo socket** requiere tanto `botToken` como `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como respaldo por variable de entorno para la cuenta predeterminada). -- **Modo HTTP** requiere `botToken` más `signingSecret` (en la raíz o por cuenta). -- `botToken`, `appToken`, `signingSecret` y `userToken` aceptan cadenas de texto sin formato u objetos SecretRef. -- Las instantáneas de cuenta de Slack exponen campos por credencial de fuente/estado como `botTokenSource`, `botTokenStatus`, `appTokenStatus` y, en modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que la cuenta está configurada mediante SecretRef, pero la ruta actual de comando/tiempo de ejecución no pudo resolver el valor secreto. -- `configWrites: false` bloquea escrituras de configuración iniciadas desde Slack. -- `channels.slack.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. -- `channels.slack.streaming.mode` es la clave canónica del modo de transmisión de Slack. `channels.slack.streaming.nativeTransport` controla el transporte nativo de transmisión de Slack. Los valores heredados `streamMode`, `streaming` booleano y `nativeStreaming` se migran automáticamente. -- Usa `user:` (MD) o `channel:` para los destinos de entrega. +- **Socket mode** requiere tanto `botToken` como `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como respaldo por entorno para la cuenta predeterminada). +- **HTTP mode** requiere `botToken` más `signingSecret` (en la raíz o por cuenta). +- `botToken`, `appToken`, `signingSecret` y `userToken` aceptan cadenas + de texto sin formato u objetos SecretRef. +- Las instantáneas de cuentas de Slack exponen campos por credencial de origen/estado como + `botTokenSource`, `botTokenStatus`, `appTokenStatus` y, en + HTTP mode, `signingSecretStatus`. `configured_unavailable` significa que la cuenta está + configurada mediante SecretRef, pero la ruta actual de comando/runtime no pudo + resolver el valor del secreto. +- `configWrites: false` bloquea las escrituras de configuración iniciadas desde Slack. +- `channels.slack.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- `channels.slack.streaming.mode` es la clave canónica del modo de transmisión de Slack. `channels.slack.streaming.nativeTransport` controla el transporte de transmisión nativo de Slack. Los valores heredados `streamMode`, booleanos `streaming` y `nativeStreaming` se migran automáticamente. +- Use `user:` (MD) o `channel:` para los destinos de entrega. -**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (de `reactionAllowlist`). +**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). -**Aislamiento de sesión por hilo:** `thread.historyScope` es por hilo (predeterminado) o compartido en todo el canal. `thread.inheritParent` copia la transcripción del canal padre a los hilos nuevos. +**Aislamiento de sesión por hilo:** `thread.historyScope` es por hilo (predeterminado) o compartido en todo el canal. `thread.inheritParent` copia la transcripción del canal principal a los hilos nuevos. -- La transmisión nativa de Slack más el estado de hilo estilo asistente de Slack "is typing..." requieren un destino de hilo de respuesta. Las MD de nivel superior permanecen fuera de hilo de forma predeterminada, así que usan `typingReaction` o entrega normal en lugar de la vista previa estilo hilo. -- `typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras se está ejecutando una respuesta y luego la elimina al completarse. Usa un shortcode de emoji de Slack como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega nativa de aprobaciones de ejecución de Slack y autorización de aprobadores. Mismo esquema que Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuario de Slack), `agentFilter`, `sessionFilter` y `target` (`"dm"`, `"channel"` o `"both"`). +- La transmisión nativa de Slack más el estado de hilo estilo asistente de Slack "is typing..." requieren un destino de hilo de respuesta. Los MD de nivel superior permanecen fuera del hilo de forma predeterminada, por lo que usan `typingReaction` o la entrega normal en lugar de la vista previa estilo hilo. +- `typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras se está generando una respuesta y luego la elimina al completarse. Use un shortcode de emoji de Slack como `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: entrega de aprobaciones de ejecución nativa de Slack y autorización de aprobadores. Mismo esquema que Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuario de Slack), `agentFilter`, `sessionFilter` y `target` (`"dm"`, `"channel"` o `"both"`). -| Grupo de acciones | Predeterminado | Notas | -| ----------------- | -------------- | ------------------------- | +| Grupo de acciones | Predeterminado | Notas | +| ----------------- | -------------- | ------------------------ | | reactions | habilitado | Reaccionar + listar reacciones | | messages | habilitado | Leer/enviar/editar/eliminar | -| pins | habilitado | Fijar/desfijar/listar | -| memberInfo | habilitado | Información de miembro | +| pins | habilitado | Fijar/desfijar/listar | +| memberInfo | habilitado | Información de miembros | | emojiList | habilitado | Lista de emojis personalizados | ### Mattermost @@ -521,18 +526,23 @@ Mattermost se distribuye como un Plugin: `openclaw plugins install @openclaw/mat } ``` -Modos de chat: `oncall` (responder en @mención, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que empiezan con prefijo disparador). +Modos de chat: `oncall` (responde ante una mención con @, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que comienzan con el prefijo de activación). Cuando los comandos nativos de Mattermost están habilitados: -- `commands.callbackPath` debe ser una ruta (por ejemplo, `/api/channels/mattermost/command`), no una URL completa. -- `commands.callbackUrl` debe resolver al endpoint del gateway de OpenClaw y ser accesible desde el servidor de Mattermost. -- Las devoluciones de llamada slash nativas se autentican con los tokens por comando devueltos por Mattermost durante el registro de comandos slash. Si el registro falla o no se activa ningún comando, OpenClaw rechaza las devoluciones de llamada con `Unauthorized: invalid command token.` -- Para hosts de devolución de llamada privados/tailnet/internos, Mattermost puede requerir que `ServiceSettings.AllowedUntrustedInternalConnections` incluya el host/dominio de devolución de llamada. Usa valores de host/dominio, no URLs completas. -- `channels.mattermost.configWrites`: permitir o denegar escrituras de configuración iniciadas desde Mattermost. -- `channels.mattermost.requireMention`: requerir `@mention` antes de responder en canales. -- `channels.mattermost.groups..requireMention`: sobrescritura por canal del requisito de mención (`"*"` como predeterminado). -- `channels.mattermost.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- `commands.callbackPath` debe ser una ruta (por ejemplo `/api/channels/mattermost/command`), no una URL completa. +- `commands.callbackUrl` debe resolverse al endpoint de Gateway de OpenClaw y debe ser accesible desde el servidor de Mattermost. +- Las devoluciones de slash nativas se autentican con los tokens por comando devueltos + por Mattermost durante el registro del slash command. Si el registro falla o no + se activan comandos, OpenClaw rechaza las devoluciones con + `Unauthorized: invalid command token.` +- Para hosts de callback privados/tailnet/internos, Mattermost puede requerir que + `ServiceSettings.AllowedUntrustedInternalConnections` incluya el host/dominio del callback. + Use valores de host/dominio, no URLs completas. +- `channels.mattermost.configWrites`: permite o deniega escrituras de configuración iniciadas desde Mattermost. +- `channels.mattermost.requireMention`: requiere `@mention` antes de responder en canales. +- `channels.mattermost.groups..requireMention`: sobrescritura de la restricción por mención por canal (`"*"` para el valor predeterminado). +- `channels.mattermost.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. ### Signal @@ -553,11 +563,11 @@ Cuando los comandos nativos de Mattermost están habilitados: } ``` -**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (de `reactionAllowlist`). +**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). - `channels.signal.account`: fija el inicio del canal a una identidad de cuenta específica de Signal. - `channels.signal.configWrites`: permite o deniega escrituras de configuración iniciadas desde Signal. -- `channels.signal.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- `channels.signal.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. ### BlueBubbles @@ -577,13 +587,13 @@ BlueBubbles es la ruta recomendada para iMessage (respaldada por Plugin, configu ``` - Rutas de claves principales cubiertas aquí: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. -- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de BlueBubbles a sesiones ACP persistentes. Usa un handle de BlueBubbles o una cadena objetivo (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- `channels.bluebubbles.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de BlueBubbles a sesiones persistentes de ACP. Use un identificador o cadena de destino de BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [ACP Agents](/es/tools/acp-agents#channel-specific-settings). - La configuración completa del canal BlueBubbles está documentada en [BlueBubbles](/es/channels/bluebubbles). ### iMessage -OpenClaw genera `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puerto. +OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puerto. ```json5 { @@ -607,17 +617,17 @@ OpenClaw genera `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puer } ``` -- `channels.imessage.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- `channels.imessage.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. - Requiere acceso completo al disco para la base de datos de Messages. -- Se prefieren destinos `chat_id:`. Usa `imsg chats --limit 20` para listar los chats. -- `cliPath` puede apuntar a un wrapper SSH; establece `remoteHost` (`host` o `user@host`) para la obtención de adjuntos mediante SCP. +- Prefiera destinos `chat_id:`. Use `imsg chats --limit 20` para listar chats. +- `cliPath` puede apuntar a un contenedor SSH; establezca `remoteHost` (`host` o `user@host`) para la obtención de adjuntos por SCP. - `attachmentRoots` y `remoteAttachmentRoots` restringen las rutas de adjuntos entrantes (predeterminado: `/Users/*/Library/Messages/Attachments`). -- SCP usa verificación estricta de clave de host, así que asegúrate de que la clave del host de retransmisión ya exista en `~/.ssh/known_hosts`. +- SCP usa verificación estricta de clave de host, así que asegúrese de que la clave del host de retransmisión ya exista en `~/.ssh/known_hosts`. - `channels.imessage.configWrites`: permite o deniega escrituras de configuración iniciadas desde iMessage. -- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de iMessage a sesiones ACP persistentes. Usa un handle normalizado o un destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de iMessage a sesiones persistentes de ACP. Use un identificador normalizado o un destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [ACP Agents](/es/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -660,19 +670,19 @@ Matrix está respaldado por una extensión y se configura en `channels.matrix`. - La autenticación por token usa `accessToken`; la autenticación por contraseña usa `userId` + `password`. - `channels.matrix.proxy` enruta el tráfico HTTP de Matrix a través de un proxy HTTP(S) explícito. Las cuentas con nombre pueden sobrescribirlo con `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` y esta opción de red son controles independientes. -- `channels.matrix.defaultAccount` selecciona la cuenta preferida en configuraciones con múltiples cuentas. -- `channels.matrix.autoJoin` tiene como valor predeterminado `off`, por lo que las salas invitadas y las invitaciones nuevas estilo MD se ignoran hasta que establezcas `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega nativa de aprobaciones de ejecución de Matrix y autorización de aprobadores. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` y esta activación de red son controles independientes. +- `channels.matrix.defaultAccount` selecciona la cuenta preferida en configuraciones con varias cuentas. +- `channels.matrix.autoJoin` tiene como valor predeterminado `off`, por lo que se ignoran las salas invitadas y las nuevas invitaciones de estilo MD hasta que establezca `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. +- `channels.matrix.execApprovals`: entrega de aprobaciones de ejecución nativa de Matrix y autorización de aprobadores. - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, las aprobaciones de ejecución se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. - - `approvers`: IDs de usuario de Matrix (por ejemplo `@owner:example.org`) autorizados para aprobar solicitudes de ejecución. - - `agentFilter`: lista opcional de permitidos de IDs de agente. Omítela para reenviar aprobaciones para todos los agentes. - - `sessionFilter`: patrones opcionales de clave de sesión (subcadena o regex). + - `approvers`: IDs de usuario de Matrix (por ejemplo `@owner:example.org`) autorizadas para aprobar solicitudes de ejecución. + - `agentFilter`: lista de permitidos opcional de IDs de agentes. Omítala para reenviar aprobaciones de todos los agentes. + - `sessionFilter`: patrones opcionales de claves de sesión (subcadena o regex). - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado), `"channel"` (sala de origen) o `"both"`. - Sobrescrituras por cuenta: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` controla cómo las MD de Matrix se agrupan en sesiones: `per-user` (predeterminado) comparte por par enrutado, mientras que `per-room` aísla cada sala de MD. -- Las sondas de estado de Matrix y las búsquedas del directorio en vivo usan la misma política de proxy que el tráfico en tiempo de ejecución. -- La configuración completa de Matrix, las reglas de direccionamiento y los ejemplos de configuración están documentados en [Matrix](/es/channels/matrix). +- `channels.matrix.dm.sessionScope` controla cómo los MD de Matrix se agrupan en sesiones: `per-user` (predeterminado) comparte por par enrutado, mientras que `per-room` aísla cada sala de MD. +- Las sondas de estado de Matrix y las búsquedas en directorio en vivo usan la misma política de proxy que el tráfico del runtime. +- La configuración completa de Matrix, las reglas de destino y los ejemplos de configuración están documentados en [Matrix](/es/channels/matrix). ### Microsoft Teams @@ -692,7 +702,7 @@ Microsoft Teams está respaldado por una extensión y se configura en `channels. ``` - Rutas de claves principales cubiertas aquí: `channels.msteams`, `channels.msteams.configWrites`. -- La configuración completa de Teams (credenciales, webhook, política de MD/grupo, sobrescrituras por equipo/por canal) está documentada en [Microsoft Teams](/es/channels/msteams). +- La configuración completa de Teams (credenciales, Webhook, política de MD/grupo, sobrescrituras por equipo/por canal) está documentada en [Microsoft Teams](/es/channels/msteams). ### IRC @@ -718,12 +728,12 @@ IRC está respaldado por una extensión y se configura en `channels.irc`. ``` - Rutas de claves principales cubiertas aquí: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. -- La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permitidos/requisito de mención) está documentada en [IRC](/es/channels/irc). +- `channels.irc.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permitidos/restricción por mención) está documentada en [IRC](/es/channels/irc). -### Múltiples cuentas (todos los canales) +### Varias cuentas (todos los canales) -Ejecuta múltiples cuentas por canal (cada una con su propio `accountId`): +Ejecute varias cuentas por canal (cada una con su propio `accountId`): ```json5 { @@ -746,26 +756,26 @@ Ejecuta múltiples cuentas por canal (cada una con su propio `accountId`): - `default` se usa cuando se omite `accountId` (CLI + enrutamiento). - Los tokens de entorno solo se aplican a la cuenta **default**. -- Los ajustes base del canal se aplican a todas las cuentas salvo que se sobrescriban por cuenta. -- Usa `bindings[].match.accountId` para enrutar cada cuenta a un agente distinto. -- Si agregas una cuenta no predeterminada mediante `openclaw channels add` (o la incorporación del canal) mientras aún estás en una configuración de canal de nivel superior de cuenta única, OpenClaw primero promueve los valores de cuenta única de nivel superior con alcance de cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueve a `channels..accounts.default`; Matrix puede conservar en su lugar un destino con nombre/default existente que coincida. -- Los enlaces existentes solo de canal (sin `accountId`) siguen coincidiendo con la cuenta predeterminada; los enlaces con alcance de cuenta siguen siendo opcionales. -- `openclaw doctor --fix` también repara formas mixtas moviendo los valores de cuenta única de nivel superior con alcance de cuenta a la cuenta promovida elegida para ese canal. La mayoría de los canales usan `accounts.default`; Matrix puede conservar en su lugar un destino con nombre/default existente que coincida. +- La configuración base del canal se aplica a todas las cuentas salvo que se sobrescriba por cuenta. +- Use `bindings[].match.accountId` para enrutar cada cuenta a un agente distinto. +- Si agrega una cuenta no predeterminada mediante `openclaw channels add` (o el onboarding del canal) mientras aún está en una configuración de canal de nivel superior de una sola cuenta, OpenClaw primero promueve los valores de una sola cuenta de nivel superior limitados a la cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueve a `channels..accounts.default`; Matrix puede preservar en su lugar un destino con nombre/predeterminado existente que coincida. +- Las asociaciones existentes solo del canal (sin `accountId`) siguen coincidiendo con la cuenta predeterminada; las asociaciones limitadas a la cuenta siguen siendo opcionales. +- `openclaw doctor --fix` también repara formas mixtas moviendo los valores de una sola cuenta de nivel superior limitados a la cuenta a la cuenta promovida elegida para ese canal. La mayoría de los canales usan `accounts.default`; Matrix puede preservar en su lugar un destino con nombre/predeterminado existente que coincida. ### Otros canales de extensión Muchos canales de extensión se configuran como `channels.` y están documentados en sus páginas de canal dedicadas (por ejemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). -Consulta el índice completo de canales: [Canales](/es/channels). +Consulte el índice completo de canales: [Channels](/es/channels). -### Requisito de mención en chats grupales +### Restricción por mención en chats grupales -Los mensajes de grupo requieren mención de forma predeterminada (**require mention**) (mención en metadatos o patrones regex seguros). Se aplica a chats grupales de WhatsApp, Telegram, Discord, Google Chat e iMessage. +Los mensajes de grupo requieren **mención obligatoria** de forma predeterminada (mención en metadatos o patrones regex seguros). Se aplica a los chats grupales de WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipos de mención:** -- **Menciones en metadatos**: @menciones nativas de la plataforma. Se ignoran en el modo de chat propio de WhatsApp. -- **Patrones de texto**: patrones regex seguros en `agents.list[].groupChat.mentionPatterns`. Los patrones inválidos y las repeticiones anidadas no seguras se ignoran. -- El requisito de mención solo se aplica cuando la detección es posible (menciones nativas o al menos un patrón). +- **Menciones en metadatos**: @menciones nativas de la plataforma. Se ignoran en el modo de chat consigo mismo de WhatsApp. +- **Patrones de texto**: patrones regex seguros en `agents.list[].groupChat.mentionPatterns`. Los patrones no válidos y las repeticiones anidadas no seguras se ignoran. +- La restricción por mención solo se aplica cuando la detección es posible (menciones nativas o al menos un patrón). ```json5 { @@ -778,9 +788,9 @@ Los mensajes de grupo requieren mención de forma predeterminada (**require ment } ``` -`messages.groupChat.historyLimit` establece el valor predeterminado global. Los canales pueden sobrescribirlo con `channels..historyLimit` (o por cuenta). Establece `0` para desactivarlo. +`messages.groupChat.historyLimit` establece el valor predeterminado global. Los canales pueden sobrescribirlo con `channels..historyLimit` (o por cuenta). Establezca `0` para desactivarlo. -#### Límites del historial de MD +#### Límites de historial de MD ```json5 { @@ -797,11 +807,11 @@ Los mensajes de grupo requieren mención de forma predeterminada (**require ment Resolución: sobrescritura por MD → valor predeterminado del proveedor → sin límite (se conserva todo). -Compatibles: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Compatible con: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Modo de chat propio +#### Modo de chat consigo mismo -Incluye tu propio número en `allowFrom` para habilitar el modo de chat propio (ignora las @menciones nativas, solo responde a patrones de texto): +Incluya su propio número en `allowFrom` para habilitar el modo de chat consigo mismo (ignora las @menciones nativas, solo responde a patrones de texto): ```json5 { @@ -849,34 +859,34 @@ Incluye tu propio número en `allowFrom` para habilitar el modo de chat propio ( } ``` - + -- Este bloque configura las superficies de comandos. Para el catálogo actual de comandos integrados + bundled, consulta [Comandos slash](/es/tools/slash-commands). -- Esta página es una **referencia de claves de configuración**, no el catálogo completo de comandos. Los comandos propiedad de canales/plugins como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` y Talk `/voice` están documentados en sus páginas de canal/plugin además de en [Comandos slash](/es/tools/slash-commands). -- Los comandos de texto deben ser mensajes **independientes** con `/` inicial. +- Este bloque configura las superficies de comandos. Para el catálogo actual de comandos integrados + bundled, consulte [Slash Commands](/es/tools/slash-commands). +- Esta página es una **referencia de claves de configuración**, no el catálogo completo de comandos. Los comandos propiedad de canales/plugins como `/bot-ping` `/bot-help` `/bot-logs` de QQ Bot, `/card` de LINE, `/pair` de device-pair, `/dreaming` de memory, `/phone` de phone-control y `/voice` de Talk están documentados en sus páginas de canal/plugin y también en [Slash Commands](/es/tools/slash-commands). +- Los comandos de texto deben ser mensajes **independientes** con `/` al inicio. - `native: "auto"` activa los comandos nativos para Discord/Telegram y deja Slack desactivado. - `nativeSkills: "auto"` activa los comandos nativos de Skills para Discord/Telegram y deja Slack desactivado. -- Sobrescritura por canal: `channels.discord.commands.native` (bool o `"auto"`). `false` borra los comandos registrados previamente. -- Sobrescribe el registro nativo de Skills por canal con `channels..commands.nativeSkills`. +- Sobrescritura por canal: `channels.discord.commands.native` (bool o `"auto"`). `false` borra los comandos registrados anteriormente. +- Sobrescriba el registro nativo de Skills por canal con `channels..commands.nativeSkills`. - `channels.telegram.customCommands` agrega entradas adicionales al menú del bot de Telegram. - `bash: true` habilita `! ` para el shell del host. Requiere `tools.elevated.enabled` y que el remitente esté en `tools.elevated.allowFrom.`. -- `config: true` habilita `/config` (lee/escribe `openclaw.json`). Para clientes `chat.send` del gateway, las escrituras persistentes de `/config set|unset` también requieren `operator.admin`; `/config show` de solo lectura sigue disponible para clientes operadores normales con alcance de escritura. +- `config: true` habilita `/config` (lee/escribe `openclaw.json`). Para clientes `chat.send` de gateway, las escrituras persistentes de `/config set|unset` también requieren `operator.admin`; `/config show` de solo lectura sigue estando disponible para clientes operadores normales con alcance de escritura. - `mcp: true` habilita `/mcp` para la configuración del servidor MCP administrado por OpenClaw en `mcp.servers`. -- `plugins: true` habilita `/plugins` para descubrimiento de plugins, instalación y controles de habilitación/deshabilitación. +- `plugins: true` habilita `/plugins` para el descubrimiento, la instalación y los controles de habilitación/deshabilitación de plugins. - `channels..configWrites` controla las mutaciones de configuración por canal (predeterminado: true). -- Para canales con múltiples cuentas, `channels..accounts..configWrites` también controla las escrituras dirigidas a esa cuenta (por ejemplo `/allowlist --config --account ` o `/config set channels..accounts....`). +- Para canales con varias cuentas, `channels..accounts..configWrites` también controla las escrituras dirigidas a esa cuenta (por ejemplo `/allowlist --config --account ` o `/config set channels..accounts....`). - `restart: false` desactiva `/restart` y las acciones de la herramienta de reinicio del gateway. Predeterminado: `true`. -- `ownerAllowFrom` es la lista de permitidos explícita del propietario para comandos/herramientas solo para el propietario. Está separada de `allowFrom`. -- `ownerDisplay: "hash"` aplica hash a los ids del propietario en el prompt del sistema. Establece `ownerDisplaySecret` para controlar el hash. -- `allowFrom` es por proveedor. Cuando está definido, es la **única** fuente de autorización (las listas de permitidos/emparejamiento del canal y `useAccessGroups` se ignoran). -- `useAccessGroups: false` permite que los comandos omitan las políticas de grupos de acceso cuando `allowFrom` no está definido. +- `ownerAllowFrom` es la lista explícita de permitidos del propietario para comandos/herramientas solo para el propietario. Es independiente de `allowFrom`. +- `ownerDisplay: "hash"` aplica hash a los IDs de propietarios en el system prompt. Establezca `ownerDisplaySecret` para controlar el hash. +- `allowFrom` es por proveedor. Cuando se establece, es la **única** fuente de autorización (se ignoran las listas de permitidos/vinculación del canal y `useAccessGroups`). +- `useAccessGroups: false` permite que los comandos omitan las políticas de grupos de acceso cuando `allowFrom` no está establecido. - Mapa de documentación de comandos: - - catálogo integrado + bundled: [Comandos slash](/es/tools/slash-commands) - - superficies de comandos específicas del canal: [Canales](/es/channels) + - catálogo integrado + bundled: [Slash Commands](/es/tools/slash-commands) + - superficies de comandos específicas del canal: [Channels](/es/channels) - comandos de QQ Bot: [QQ Bot](/es/channels/qqbot) - - comandos de vinculación: [Vinculación](/es/channels/pairing) + - comandos de vinculación: [Pairing](/es/channels/pairing) - comando de tarjeta de LINE: [LINE](/es/channels/line) - - memory dreaming: [Dreaming](/es/concepts/dreaming) + - Dreaming de memory: [Dreaming](/es/concepts/dreaming) @@ -896,7 +906,7 @@ Predeterminado: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raíz opcional del repositorio que se muestra en la línea Runtime del prompt del sistema. Si no está definida, OpenClaw la detecta automáticamente recorriendo hacia arriba desde el workspace. +Raíz opcional del repositorio mostrada en la línea Runtime del system prompt. Si no se establece, OpenClaw la detecta automáticamente recorriendo hacia arriba desde el workspace. ```json5 { @@ -906,7 +916,8 @@ Raíz opcional del repositorio que se muestra en la línea Runtime del prompt de ### `agents.defaults.skills` -Lista de permitidos predeterminada opcional de Skills para agentes que no establecen `agents.list[].skills`. +Lista de permitidos predeterminada opcional de Skills para agentes que no establecen +`agents.list[].skills`. ```json5 { @@ -921,10 +932,11 @@ Lista de permitidos predeterminada opcional de Skills para agentes que no establ } ``` -- Omite `agents.defaults.skills` para tener Skills sin restricciones de forma predeterminada. -- Omite `agents.list[].skills` para heredar los valores predeterminados. -- Establece `agents.list[].skills: []` para no tener Skills. -- Una lista no vacía en `agents.list[].skills` es el conjunto final para ese agente; no se fusiona con los valores predeterminados. +- Omita `agents.defaults.skills` para Skills sin restricciones de forma predeterminada. +- Omita `agents.list[].skills` para heredar los valores predeterminados. +- Establezca `agents.list[].skills: []` para no tener Skills. +- Una lista no vacía en `agents.list[].skills` es el conjunto final para ese agente; no + se combina con los valores predeterminados. ### `agents.defaults.skipBootstrap` @@ -938,9 +950,9 @@ Desactiva la creación automática de archivos bootstrap del workspace (`AGENTS. ### `agents.defaults.contextInjection` -Controla cuándo se inyectan los archivos bootstrap del workspace en el prompt del sistema. Predeterminado: `"always"`. +Controla cuándo se insertan los archivos bootstrap del workspace en el system prompt. Predeterminado: `"always"`. -- `"continuation-skip"`: los turnos de continuación seguros (después de una respuesta completada del asistente) omiten la reinyección del bootstrap del workspace, reduciendo el tamaño del prompt. Las ejecuciones de Heartbeat y los reintentos posteriores a la Compaction siguen reconstruyendo el contexto. +- `"continuation-skip"`: los turnos seguros de continuación (después de una respuesta completada del asistente) omiten la reinserción del bootstrap del workspace, lo que reduce el tamaño del prompt. Las ejecuciones de Heartbeat y los reintentos posteriores a la Compaction siguen reconstruyendo el contexto. ```json5 { @@ -960,7 +972,7 @@ Máximo de caracteres por archivo bootstrap del workspace antes del truncamiento ### `agents.defaults.bootstrapTotalMaxChars` -Máximo total de caracteres inyectados entre todos los archivos bootstrap del workspace. Predeterminado: `60000`. +Máximo total de caracteres insertados en todos los archivos bootstrap del workspace. Predeterminado: `60000`. ```json5 { @@ -970,12 +982,12 @@ Máximo total de caracteres inyectados entre todos los archivos bootstrap del wo ### `agents.defaults.bootstrapPromptTruncationWarning` -Controla el texto de advertencia visible para el agente cuando el contexto bootstrap se trunca. +Controla el texto de advertencia visible para el agente cuando se trunca el contexto bootstrap. Predeterminado: `"once"`. -- `"off"`: nunca inyecta texto de advertencia en el prompt del sistema. -- `"once"`: inyecta la advertencia una vez por firma de truncamiento única (recomendado). -- `"always"`: inyecta la advertencia en cada ejecución cuando existe truncamiento. +- `"off"`: nunca inserta texto de advertencia en el system prompt. +- `"once"`: inserta la advertencia una vez por firma de truncamiento única (recomendado). +- `"always"`: inserta la advertencia en cada ejecución cuando existe truncamiento. ```json5 { @@ -985,24 +997,24 @@ Predeterminado: `"once"`. ### Mapa de propiedad del presupuesto de contexto -OpenClaw tiene múltiples presupuestos de prompt/contexto de gran volumen, y están -divididos intencionalmente por subsistema en lugar de pasar todos por una sola -opción genérica. +OpenClaw tiene varios presupuestos de prompt/contexto de alto volumen, y están +divididos intencionalmente por subsistema en lugar de pasar todos por un único +ajuste genérico. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - inyección bootstrap normal del workspace. + inserción bootstrap normal del workspace. - `agents.defaults.startupContext.*`: - preludio de inicio de una sola vez para `/new` y `/reset`, incluidos los - archivos recientes diarios `memory/*.md`. + preludio de inicio de un solo uso para `/new` y `/reset`, incluidos archivos + recientes `memory/*.md` diarios. - `skills.limits.*`: - la lista compacta de Skills inyectada en el prompt del sistema. + la lista compacta de Skills insertada en el system prompt. - `agents.defaults.contextLimits.*`: - extractos limitados en tiempo de ejecución y bloques inyectados propiedad del runtime. + extractos acotados en runtime y bloques insertados propiedad del runtime. - `memory.qmd.limits.*`: - tamaño de fragmentos de búsqueda de memoria indexada e inyección. + tamaños de fragmentos e inserción de búsqueda de memoria indexada. -Usa la sobrescritura por agente correspondiente solo cuando un agente necesite un +Use la sobrescritura correspondiente por agente solo cuando un agente necesite un presupuesto diferente: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1010,7 +1022,7 @@ presupuesto diferente: #### `agents.defaults.startupContext` -Controla el preludio de inicio del primer turno inyectado en ejecuciones simples de `/new` y `/reset`. +Controla el preludio de inicio del primer turno insertado en ejecuciones simples de `/new` y `/reset`. ```json5 { @@ -1031,7 +1043,7 @@ Controla el preludio de inicio del primer turno inyectado en ejecuciones simples #### `agents.defaults.contextLimits` -Valores predeterminados compartidos para superficies de contexto limitadas en tiempo de ejecución. +Valores predeterminados compartidos para superficies de contexto acotadas del runtime. ```json5 { @@ -1048,14 +1060,19 @@ Valores predeterminados compartidos para superficies de contexto limitadas en ti } ``` -- `memoryGetMaxChars`: límite predeterminado del extracto de `memory_get` antes de que se agreguen los metadatos de truncamiento y el aviso de continuación. -- `memoryGetDefaultLines`: ventana de líneas predeterminada de `memory_get` cuando se omite `lines`. -- `toolResultMaxChars`: límite activo de resultados de herramientas usado para resultados persistidos y recuperación por desbordamiento. -- `postCompactionMaxChars`: límite del extracto de AGENTS.md usado durante la inyección de actualización posterior a Compaction. +- `memoryGetMaxChars`: límite predeterminado del extracto de `memory_get` antes de que se agreguen + metadatos de truncamiento y aviso de continuación. +- `memoryGetDefaultLines`: ventana predeterminada de líneas de `memory_get` cuando se omite + `lines`. +- `toolResultMaxChars`: límite activo del resultado de herramientas usado para resultados persistidos y + recuperación por desbordamiento. +- `postCompactionMaxChars`: límite del extracto de AGENTS.md usado durante la inserción de actualización + posterior a la Compaction. #### `agents.list[].contextLimits` -Sobrescritura por agente para las opciones compartidas de `contextLimits`. Los campos omitidos heredan de `agents.defaults.contextLimits`. +Sobrescritura por agente para los ajustes compartidos de `contextLimits`. Los campos omitidos heredan +de `agents.defaults.contextLimits`. ```json5 { @@ -1081,7 +1098,7 @@ Sobrescritura por agente para las opciones compartidas de `contextLimits`. Los c #### `skills.limits.maxSkillsPromptChars` -Límite global para la lista compacta de Skills inyectada en el prompt del sistema. Esto +Límite global para la lista compacta de Skills insertada en el system prompt. Esto no afecta la lectura de archivos `SKILL.md` bajo demanda. ```json5 @@ -1115,11 +1132,11 @@ Sobrescritura por agente para el presupuesto del prompt de Skills. ### `agents.defaults.imageMaxDimensionPx` -Tamaño máximo en píxeles del lado más largo de la imagen en bloques de imagen de transcripción/herramienta antes de las llamadas al proveedor. +Tamaño máximo en píxeles para el lado más largo de la imagen en bloques de imagen de transcript/herramientas antes de las llamadas al proveedor. Predeterminado: `1200`. Los valores más bajos suelen reducir el uso de tokens de visión y el tamaño de la carga útil de la solicitud en ejecuciones con muchas capturas de pantalla. -Los valores más altos preservan más detalle visual. +Los valores más altos conservan más detalle visual. ```json5 { @@ -1129,7 +1146,7 @@ Los valores más altos preservan más detalle visual. ### `agents.defaults.userTimezone` -Zona horaria para el contexto del prompt del sistema (no para las marcas de tiempo de los mensajes). Usa la zona horaria del host como respaldo. +Zona horaria para el contexto del system prompt (no para las marcas de tiempo de los mensajes). Usa como respaldo la zona horaria del host. ```json5 { @@ -1139,7 +1156,7 @@ Zona horaria para el contexto del prompt del sistema (no para las marcas de tiem ### `agents.defaults.timeFormat` -Formato de hora en el prompt del sistema. Predeterminado: `auto` (preferencia del SO). +Formato de hora en el system prompt. Predeterminado: `auto` (preferencia del SO). ```json5 { @@ -1198,47 +1215,47 @@ Formato de hora en el prompt del sistema. Predeterminado: `auto` (preferencia de - `model`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - La forma de cadena establece solo el modelo principal. - - La forma de objeto establece el principal más los modelos de failover ordenados. + - La forma de objeto establece el principal más los modelos de conmutación por error en orden. - `imageModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usa la ruta de la herramienta `image` como configuración de su modelo de visión. + - Lo usa la ruta de la herramienta `image` como su configuración de modelo de visión. - También se usa como enrutamiento de respaldo cuando el modelo seleccionado/predeterminado no puede aceptar entrada de imagen. - `imageGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usa la capacidad compartida de generación de imágenes y cualquier futura superficie de herramienta/plugin que genere imágenes. - - Valores típicos: `google/gemini-3.1-flash-image-preview` para generación de imágenes nativa de Gemini, `fal/fal-ai/flux/dev` para fal, u `openai/gpt-image-1` para OpenAI Images. - - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API del proveedor correspondiente (por ejemplo `GEMINI_API_KEY` o `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). - - Si se omite, `image_generate` aún puede inferir un valor predeterminado de proveedor respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los proveedores restantes de generación de imágenes registrados en orden de id de proveedor. + - Lo usan la capacidad compartida de generación de imágenes y cualquier futura superficie de herramienta/plugin que genere imágenes. + - Valores típicos: `google/gemini-3.1-flash-image-preview` para generación nativa de imágenes con Gemini, `fal/fal-ai/flux/dev` para fal, o `openai/gpt-image-1` para OpenAI Images. + - Si selecciona directamente un proveedor/modelo, configure también la autenticación/clave de API del proveedor correspondiente (por ejemplo `GEMINI_API_KEY` o `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). + - Si se omite, `image_generate` todavía puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y luego los demás proveedores de generación de imágenes registrados en orden de ID de proveedor. - `musicGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usa la capacidad compartida de generación de música y la herramienta integrada `music_generate`. + - Lo usan la capacidad compartida de generación de música y la herramienta integrada `music_generate`. - Valores típicos: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` o `minimax/music-2.5+`. - - Si se omite, `music_generate` aún puede inferir un valor predeterminado de proveedor respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los proveedores restantes de generación de música registrados en orden de id de proveedor. - - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API del proveedor correspondiente. + - Si se omite, `music_generate` todavía puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y luego los demás proveedores de generación de música registrados en orden de ID de proveedor. + - Si selecciona directamente un proveedor/modelo, configure también la autenticación/clave de API del proveedor correspondiente. - `videoGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usa la capacidad compartida de generación de video y la herramienta integrada `video_generate`. + - Lo usan la capacidad compartida de generación de video y la herramienta integrada `video_generate`. - Valores típicos: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` o `qwen/wan2.7-r2v`. - - Si se omite, `video_generate` aún puede inferir un valor predeterminado de proveedor respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los proveedores restantes de generación de video registrados en orden de id de proveedor. - - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API del proveedor correspondiente. + - Si se omite, `video_generate` todavía puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y luego los demás proveedores de generación de video registrados en orden de ID de proveedor. + - Si selecciona directamente un proveedor/modelo, configure también la autenticación/clave de API del proveedor correspondiente. - El proveedor bundled de generación de video Qwen admite hasta 1 video de salida, 1 imagen de entrada, 4 videos de entrada, 10 segundos de duración y opciones a nivel de proveedor `size`, `aspectRatio`, `resolution`, `audio` y `watermark`. - `pdfModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - Lo usa la herramienta `pdf` para el enrutamiento del modelo. - - Si se omite, la herramienta PDF usa `imageModel` como respaldo y luego el modelo resuelto de la sesión/predeterminado. -- `pdfMaxBytesMb`: límite predeterminado de tamaño de PDF para la herramienta `pdf` cuando no se pasa `maxBytesMb` en el momento de la llamada. + - Si se omite, la herramienta PDF recurre a `imageModel` y luego al modelo resuelto de la sesión/predeterminado. +- `pdfMaxBytesMb`: límite predeterminado de tamaño de PDF para la herramienta `pdf` cuando no se pasa `maxBytesMb` en la llamada. - `pdfMaxPages`: máximo predeterminado de páginas consideradas por el modo de respaldo de extracción en la herramienta `pdf`. - `verboseDefault`: nivel verbose predeterminado para agentes. Valores: `"off"`, `"on"`, `"full"`. Predeterminado: `"off"`. - `elevatedDefault`: nivel predeterminado de salida elevada para agentes. Valores: `"off"`, `"on"`, `"ask"`, `"full"`. Predeterminado: `"on"`. -- `model.primary`: formato `provider/model` (por ejemplo `openai/gpt-5.4`). Si omites el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese id de modelo exacto, y solo entonces vuelve al proveedor predeterminado configurado (comportamiento heredado y obsoleto de compatibilidad, así que se prefiere `provider/model` explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. -- `models`: el catálogo de modelos configurado y la lista de permitidos para `/model`. Cada entrada puede incluir `alias` (atajo) y `params` (específicos del proveedor, por ejemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parámetros globales predeterminados del proveedor aplicados a todos los modelos. Se establecen en `agents.defaults.params` (por ejemplo `{ cacheRetention: "long" }`). -- Precedencia de fusión de `params` (config): `agents.defaults.params` (base global) es sobrescrito por `agents.defaults.models["provider/model"].params` (por modelo), y luego `agents.list[].params` (id de agente coincidente) sobrescribe por clave. Consulta [Prompt Caching](/es/reference/prompt-caching) para más detalles. -- `embeddedHarness`: política predeterminada de runtime de agente incrustado de bajo nivel. Usa `runtime: "auto"` para permitir que los harnesses de plugins registrados reclamen modelos compatibles, `runtime: "pi"` para forzar el harness PI integrado, o un id de harness registrado como `runtime: "codex"`. Establece `fallback: "none"` para desactivar el respaldo automático a PI. -- Los escritores de configuración que mutan estos campos (por ejemplo `/models set`, `/models set-image` y comandos de agregar/quitar respaldo) guardan la forma canónica de objeto y preservan las listas de respaldo existentes cuando es posible. +- `model.primary`: formato `provider/model` (por ejemplo `openai/gpt-5.4`). Si omite el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese ID exacto de modelo y solo después recurre al proveedor predeterminado configurado (comportamiento de compatibilidad obsoleto, así que prefiera `provider/model` explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. +- `models`: el catálogo y la lista de permitidos de modelos configurados para `/model`. Cada entrada puede incluir `alias` (atajo) y `params` (específicos del proveedor, por ejemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parámetros predeterminados globales del proveedor aplicados a todos los modelos. Se establecen en `agents.defaults.params` (por ejemplo `{ cacheRetention: "long" }`). +- Precedencia de combinación de `params` (configuración): `agents.defaults.params` (base global) se sobrescribe con `agents.defaults.models["provider/model"].params` (por modelo) y luego `agents.list[].params` (ID de agente coincidente) sobrescribe por clave. Consulte [Prompt Caching](/es/reference/prompt-caching) para más detalles. +- `embeddedHarness`: política predeterminada del runtime de agente integrado de bajo nivel. Use `runtime: "auto"` para permitir que los harnesses de plugins registrados reclamen los modelos compatibles, `runtime: "pi"` para forzar el harness integrado de PI, o un ID de harness registrado, como `runtime: "codex"`. Establezca `fallback: "none"` para desactivar el respaldo automático de PI. +- Los escritores de configuración que modifican estos campos (por ejemplo `/models set`, `/models set-image` y comandos para agregar/quitar respaldos) guardan la forma canónica de objeto y conservan las listas de respaldo existentes cuando es posible. - `maxConcurrent`: máximo de ejecuciones paralelas de agentes entre sesiones (cada sesión sigue serializada). Predeterminado: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` controla qué ejecutor de bajo nivel ejecuta los turnos de agente incrustado. +`embeddedHarness` controla qué ejecutor de bajo nivel ejecuta los turnos de agentes integrados. La mayoría de las implementaciones deberían mantener el valor predeterminado `{ runtime: "auto", fallback: "pi" }`. -Úsalo cuando un plugin de confianza proporcione un harness nativo, como el harness bundled -de servidor de aplicación Codex. +Úselo cuando un plugin de confianza proporcione un harness nativo, como el harness bundled +del servidor de aplicaciones Codex. ```json5 { @@ -1254,13 +1271,13 @@ de servidor de aplicación Codex. } ``` -- `runtime`: `"auto"`, `"pi"` o un id de harness de plugin registrado. El plugin bundled Codex registra `codex`. -- `fallback`: `"pi"` o `"none"`. `"pi"` mantiene el harness PI integrado como respaldo de compatibilidad. `"none"` hace que la selección de un harness de plugin ausente o no compatible falle en lugar de usar PI silenciosamente. -- Sobrescrituras de entorno: `OPENCLAW_AGENT_RUNTIME=` sobrescribe `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desactiva el respaldo a PI para ese proceso. -- Para implementaciones solo de Codex, establece `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` y `embeddedHarness.fallback: "none"`. -- Esto solo controla el harness de chat incrustado. La generación de medios, visión, PDF, música, video y TTS siguen usando su configuración de proveedor/modelo. +- `runtime`: `"auto"`, `"pi"` o un ID de harness de plugin registrado. El plugin bundled Codex registra `codex`. +- `fallback`: `"pi"` o `"none"`. `"pi"` mantiene el harness integrado de PI como respaldo de compatibilidad. `"none"` hace que la selección de un harness de plugin ausente o no compatible falle en lugar de usar PI silenciosamente. +- Sobrescrituras por entorno: `OPENCLAW_AGENT_RUNTIME=` sobrescribe `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desactiva el respaldo de PI para ese proceso. +- Para implementaciones exclusivas de Codex, establezca `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` y `embeddedHarness.fallback: "none"`. +- Esto solo controla el harness de chat integrado. La generación de medios, visión, PDF, música, video y TTS siguen usando sus configuraciones de proveedor/modelo. -**Atajos de alias integrados** (solo se aplican cuando el modelo está en `agents.defaults.models`): +**Abreviaturas de alias integradas** (solo se aplican cuando el modelo está en `agents.defaults.models`): | Alias | Modelo | | ------------------- | -------------------------------------- | @@ -1273,15 +1290,15 @@ de servidor de aplicación Codex. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Tus alias configurados siempre tienen prioridad sobre los predeterminados. +Sus alias configurados siempre tienen prioridad sobre los predeterminados. -Los modelos Z.AI GLM-4.x habilitan automáticamente el modo thinking a menos que establezcas `--thinking off` o definas tú mismo `agents.defaults.models["zai/"].params.thinking`. -Los modelos Z.AI habilitan `tool_stream` de forma predeterminada para el streaming de llamadas a herramientas. Establece `agents.defaults.models["zai/"].params.tool_stream` en `false` para desactivarlo. -Los modelos Anthropic Claude 4.6 usan `adaptive` thinking de forma predeterminada cuando no se establece un nivel explícito de thinking. +Los modelos Z.AI GLM-4.x activan automáticamente el modo thinking a menos que establezca `--thinking off` o defina usted mismo `agents.defaults.models["zai/"].params.thinking`. +Los modelos Z.AI activan `tool_stream` de forma predeterminada para la transmisión de llamadas de herramientas. Establezca `agents.defaults.models["zai/"].params.tool_stream` en `false` para desactivarlo. +Los modelos Anthropic Claude 4.6 usan `adaptive` como valor predeterminado de thinking cuando no se establece un nivel explícito de thinking. ### `agents.defaults.cliBackends` -Backends opcionales de CLI para ejecuciones de respaldo solo de texto (sin llamadas a herramientas). Útiles como respaldo cuando fallan los proveedores de API. +Backends de CLI opcionales para ejecuciones de respaldo solo de texto (sin llamadas a herramientas). Útil como respaldo cuando fallan los proveedores de API. ```json5 { @@ -1309,13 +1326,13 @@ Backends opcionales de CLI para ejecuciones de respaldo solo de texto (sin llama } ``` -- Los backends de CLI son principalmente de texto; las herramientas siempre están desactivadas. -- Las sesiones son compatibles cuando se establece `sessionArg`. -- El paso de imágenes es compatible cuando `imageArg` acepta rutas de archivos. +- Los backends de CLI están centrados en texto; las herramientas siempre están desactivadas. +- Las sesiones se admiten cuando se establece `sessionArg`. +- Se admite el paso de imágenes cuando `imageArg` acepta rutas de archivo. ### `agents.defaults.systemPromptOverride` -Reemplaza todo el prompt del sistema ensamblado por OpenClaw con una cadena fija. Se establece en el nivel predeterminado (`agents.defaults.systemPromptOverride`) o por agente (`agents.list[].systemPromptOverride`). Los valores por agente tienen prioridad; un valor vacío o con solo espacios en blanco se ignora. Útil para experimentos controlados de prompt. +Reemplaza todo el system prompt ensamblado por OpenClaw con una cadena fija. Se establece en el nivel predeterminado (`agents.defaults.systemPromptOverride`) o por agente (`agents.list[].systemPromptOverride`). Los valores por agente tienen prioridad; un valor vacío o compuesto solo por espacios en blanco se ignora. Es útil para experimentos controlados de prompts. ```json5 { @@ -1356,15 +1373,15 @@ Ejecuciones periódicas de Heartbeat. } ``` -- `every`: cadena de duración (ms/s/m/h). Predeterminado: `30m` (autenticación con clave de API) o `1h` (autenticación OAuth). Establece `0m` para desactivar. -- `includeSystemPromptSection`: cuando es false, omite la sección Heartbeat del prompt del sistema y omite la inyección de `HEARTBEAT.md` en el contexto bootstrap. Predeterminado: `true`. +- `every`: cadena de duración (ms/s/m/h). Predeterminado: `30m` (autenticación con clave de API) o `1h` (autenticación OAuth). Establezca `0m` para desactivarlo. +- `includeSystemPromptSection`: cuando es false, omite la sección Heartbeat del system prompt y omite la inserción de `HEARTBEAT.md` en el contexto bootstrap. Predeterminado: `true`. - `suppressToolErrorWarnings`: cuando es true, suprime las cargas útiles de advertencia de error de herramientas durante las ejecuciones de Heartbeat. -- `timeoutSeconds`: tiempo máximo en segundos permitido para un turno de agente de Heartbeat antes de cancelarlo. Déjalo sin definir para usar `agents.defaults.timeoutSeconds`. +- `timeoutSeconds`: tiempo máximo en segundos permitido para un turno de agente de Heartbeat antes de cancelarlo. Déjelo sin establecer para usar `agents.defaults.timeoutSeconds`. - `directPolicy`: política de entrega directa/MD. `allow` (predeterminado) permite la entrega a destino directo. `block` suprime la entrega a destino directo y emite `reason=dm-blocked`. -- `lightContext`: cuando es true, las ejecuciones de Heartbeat usan un contexto bootstrap ligero y conservan solo `HEARTBEAT.md` de los archivos bootstrap del workspace. -- `isolatedSession`: cuando es true, cada Heartbeat se ejecuta en una sesión nueva sin historial de conversación previo. Mismo patrón de aislamiento que Cron `sessionTarget: "isolated"`. Reduce el costo de tokens por Heartbeat de ~100K a ~2-5K tokens. -- Por agente: establece `agents.list[].heartbeat`. Cuando cualquier agente define `heartbeat`, **solo esos agentes** ejecutan Heartbeat. -- Heartbeat ejecuta turnos completos del agente: intervalos más cortos consumen más tokens. +- `lightContext`: cuando es true, las ejecuciones de Heartbeat usan un contexto bootstrap liviano y conservan solo `HEARTBEAT.md` de los archivos bootstrap del workspace. +- `isolatedSession`: cuando es true, cada ejecución de Heartbeat se realiza en una sesión nueva sin historial previo de conversación. Mismo patrón de aislamiento que Cron `sessionTarget: "isolated"`. Reduce el costo por Heartbeat de ~100K a ~2-5K tokens. +- Por agente: establezca `agents.list[].heartbeat`. Cuando cualquier agente define `heartbeat`, **solo esos agentes** ejecutan Heartbeat. +- Los Heartbeats ejecutan turnos completos del agente: intervalos más cortos consumen más tokens. ### `agents.defaults.compaction` @@ -1394,19 +1411,19 @@ Ejecuciones periódicas de Heartbeat. } ``` -- `mode`: `default` o `safeguard` (resumen por fragmentos para historiales largos). Consulta [Compaction](/es/concepts/compaction). -- `provider`: id de un Plugin proveedor de Compaction registrado. Cuando se establece, se llama a `summarize()` del proveedor en lugar del resumen LLM integrado. En caso de fallo, vuelve al integrado. Establecer un proveedor fuerza `mode: "safeguard"`. Consulta [Compaction](/es/concepts/compaction). -- `timeoutSeconds`: máximo de segundos permitidos para una sola operación de Compaction antes de que OpenClaw la cancele. Predeterminado: `900`. -- `identifierPolicy`: `strict` (predeterminado), `off` o `custom`. `strict` antepone instrucciones integradas de conservación de identificadores opacos durante el resumen de Compaction. -- `identifierInstructions`: texto opcional personalizado de conservación de identificadores usado cuando `identifierPolicy=custom`. -- `postCompactionSections`: nombres opcionales de secciones H2/H3 de AGENTS.md para reinyectar después de Compaction. Predeterminado: `["Session Startup", "Red Lines"]`; establece `[]` para desactivar la reinyección. Cuando no está definido o se establece explícitamente en ese par predeterminado, también se aceptan los encabezados heredados `Every Session`/`Safety` como respaldo heredado. -- `model`: sobrescritura opcional `provider/model-id` solo para el resumen de Compaction. Úsalo cuando la sesión principal deba mantener un modelo pero los resúmenes de Compaction deban ejecutarse en otro; cuando no está definido, Compaction usa el modelo principal de la sesión. -- `notifyUser`: cuando es `true`, envía un aviso breve al usuario cuando comienza Compaction (por ejemplo, "Compacting context..."). Está desactivado de forma predeterminada para que Compaction sea silenciosa. -- `memoryFlush`: turno agentivo silencioso antes de la auto-Compaction para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura. +- `mode`: `default` o `safeguard` (resumen por fragmentos para historiales largos). Consulte [Compaction](/es/concepts/compaction). +- `provider`: id de un Plugin proveedor de Compaction registrado. Cuando se establece, se llama a `summarize()` del proveedor en lugar del resumen LLM integrado. En caso de error, vuelve al integrado. Establecer un proveedor fuerza `mode: "safeguard"`. Consulte [Compaction](/es/concepts/compaction). +- `timeoutSeconds`: segundos máximos permitidos para una sola operación de Compaction antes de que OpenClaw la aborte. Predeterminado: `900`. +- `identifierPolicy`: `strict` (predeterminado), `off` o `custom`. `strict` antepone la guía integrada de retención de identificadores opacos durante el resumen de Compaction. +- `identifierInstructions`: texto personalizado opcional de preservación de identificadores usado cuando `identifierPolicy=custom`. +- `postCompactionSections`: nombres opcionales de secciones H2/H3 de AGENTS.md que se volverán a insertar después de la Compaction. Predeterminado: `["Session Startup", "Red Lines"]`; establezca `[]` para desactivar la reinserción. Cuando no se establece o se establece explícitamente en ese par predeterminado, también se aceptan los encabezados heredados `Every Session`/`Safety` como respaldo. +- `model`: sobrescritura opcional `provider/model-id` solo para el resumen de Compaction. Úselo cuando la sesión principal deba mantener un modelo pero los resúmenes de Compaction deban ejecutarse con otro; cuando no se establece, Compaction usa el modelo principal de la sesión. +- `notifyUser`: cuando es `true`, envía un aviso breve al usuario cuando comienza la Compaction (por ejemplo, "Compacting context..."). Está desactivado de forma predeterminada para mantener la Compaction silenciosa. +- `memoryFlush`: turno agéntico silencioso antes de la auto-Compaction para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura. ### `agents.defaults.contextPruning` -Elimina **resultados antiguos de herramientas** del contexto en memoria antes de enviarlo al LLM. **No** modifica el historial de la sesión en disco. +Poda **resultados de herramientas antiguos** del contexto en memoria antes de enviarlo al LLM. **No** modifica el historial de sesión en disco. ```json5 { @@ -1430,25 +1447,25 @@ Elimina **resultados antiguos de herramientas** del contexto en memoria antes de -- `mode: "cache-ttl"` habilita pasadas de poda. -- `ttl` controla con qué frecuencia puede volver a ejecutarse la poda (después del último acceso a la caché). -- La poda primero recorta suavemente los resultados de herramientas sobredimensionados y luego limpia por completo los resultados más antiguos si es necesario. +- `mode: "cache-ttl"` habilita las pasadas de poda. +- `ttl` controla con qué frecuencia la poda puede volver a ejecutarse (después del último acceso a la caché). +- La poda primero recorta suavemente los resultados de herramientas sobredimensionados y luego vacía por completo los resultados de herramientas más antiguos si es necesario. -**Soft-trim** conserva el principio y el final e inserta `...` en el medio. +**Soft-trim** conserva el principio + el final e inserta `...` en el medio. **Hard-clear** reemplaza todo el resultado de la herramienta con el marcador de posición. Notas: -- Los bloques de imagen nunca se recortan ni se limpian. -- Las proporciones se basan en caracteres (aproximadas), no en recuentos exactos de tokens. -- Si existen menos de `keepLastAssistants` mensajes del asistente, la poda se omite. +- Los bloques de imagen nunca se recortan ni se vacían. +- Las proporciones se basan en caracteres (aproximadas), no en conteos exactos de tokens. +- Si existen menos de `keepLastAssistants` mensajes del asistente, se omite la poda. -Consulta [Poda de sesión](/es/concepts/session-pruning) para los detalles del comportamiento. +Consulte [Session Pruning](/es/concepts/session-pruning) para más detalles sobre el comportamiento. -### Streaming por bloques +### Transmisión por bloques ```json5 { @@ -1465,10 +1482,10 @@ Consulta [Poda de sesión](/es/concepts/session-pruning) para los detalles del c ``` - Los canales que no son Telegram requieren `*.blockStreaming: true` explícito para habilitar respuestas por bloques. -- Sobrescrituras por canal: `channels..blockStreamingCoalesce` (y variantes por cuenta). Signal/Slack/Discord/Google Chat tienen como valor predeterminado `minChars: 1500`. -- `humanDelay`: pausa aleatoria entre respuestas por bloques. `natural` = 800–2500 ms. Sobrescritura por agente: `agents.list[].humanDelay`. +- Sobrescrituras por canal: `channels..blockStreamingCoalesce` (y variantes por cuenta). Signal/Slack/Discord/Google Chat usan por defecto `minChars: 1500`. +- `humanDelay`: pausa aleatoria entre respuestas por bloques. `natural` = 800–2500ms. Sobrescritura por agente: `agents.list[].humanDelay`. -Consulta [Streaming](/es/concepts/streaming) para el comportamiento y los detalles de fragmentación. +Consulte [Streaming](/es/concepts/streaming) para obtener detalles sobre el comportamiento y el fragmentado. ### Indicadores de escritura @@ -1483,16 +1500,16 @@ Consulta [Streaming](/es/concepts/streaming) para el comportamiento y los detall } ``` -- Predeterminados: `instant` para chats directos/menciones, `message` para chats grupales sin mención. +- Valores predeterminados: `instant` para chats directos/menciones, `message` para chats grupales sin mención. - Sobrescrituras por sesión: `session.typingMode`, `session.typingIntervalSeconds`. -Consulta [Indicadores de escritura](/es/concepts/typing-indicators). +Consulte [Typing Indicators](/es/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandbox opcional para el agente incrustado. Consulta [Sandboxing](/es/gateway/sandboxing) para la guía completa. +Sandboxing opcional para el agente integrado. Consulte [Sandboxing](/es/gateway/sandboxing) para la guía completa. ```json5 { @@ -1600,35 +1617,35 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del r **Configuración del backend SSH:** -- `target`: destino SSH con formato `user@host[:port]` +- `target`: destino SSH en formato `user@host[:port]` - `command`: comando del cliente SSH (predeterminado: `ssh`) -- `workspaceRoot`: raíz remota absoluta usada para workspaces por alcance +- `workspaceRoot`: raíz remota absoluta usada para workspaces por ámbito - `identityFile` / `certificateFile` / `knownHostsFile`: archivos locales existentes pasados a OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: contenidos en línea o SecretRefs que OpenClaw materializa en archivos temporales en tiempo de ejecución -- `strictHostKeyChecking` / `updateHostKeys`: opciones de política de claves de host de OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: contenido integrado o SecretRefs que OpenClaw materializa en archivos temporales en runtime +- `strictHostKeyChecking` / `updateHostKeys`: ajustes de política de clave de host de OpenSSH **Precedencia de autenticación SSH:** - `identityData` tiene prioridad sobre `identityFile` - `certificateData` tiene prioridad sobre `certificateFile` - `knownHostsData` tiene prioridad sobre `knownHostsFile` -- Los valores `*Data` respaldados por SecretRef se resuelven a partir de la instantánea activa del runtime de secretos antes de que comience la sesión del sandbox +- Los valores `*Data` respaldados por SecretRef se resuelven desde la instantánea activa del runtime de secretos antes de que comience la sesión sandbox **Comportamiento del backend SSH:** - inicializa el workspace remoto una vez después de crear o recrear -- luego mantiene el workspace SSH remoto como canónico -- enruta `exec`, herramientas de archivos y rutas de medios a través de SSH +- luego mantiene el workspace remoto SSH como canónico +- enruta `exec`, herramientas de archivos y rutas de medios por SSH - no sincroniza automáticamente los cambios remotos de vuelta al host - no admite contenedores de navegador del sandbox **Acceso al workspace:** -- `none`: workspace del sandbox por alcance en `~/.openclaw/sandboxes` -- `ro`: workspace del sandbox en `/workspace`, workspace del agente montado como solo lectura en `/agent` +- `none`: workspace sandbox por ámbito en `~/.openclaw/sandboxes` +- `ro`: workspace sandbox en `/workspace`, workspace del agente montado como solo lectura en `/agent` - `rw`: workspace del agente montado con lectura/escritura en `/workspace` -**Alcance:** +**Ámbito:** - `session`: contenedor + workspace por sesión - `agent`: un contenedor + workspace por agente (predeterminado) @@ -1662,30 +1679,30 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del r **Modo OpenShell:** -- `mirror`: inicializa el remoto desde el local antes de `exec`, sincroniza de vuelta después de `exec`; el workspace local sigue siendo el canónico +- `mirror`: inicializa el remoto desde el local antes de `exec`, sincroniza de vuelta después de `exec`; el workspace local sigue siendo canónico - `remote`: inicializa el remoto una vez cuando se crea el sandbox y luego mantiene el workspace remoto como canónico -En modo `remote`, las ediciones locales del host realizadas fuera de OpenClaw no se sincronizan automáticamente con el sandbox después del paso de inicialización. -El transporte es SSH al sandbox de OpenShell, pero el plugin es propietario del ciclo de vida del sandbox y de la sincronización mirror opcional. +En modo `remote`, las ediciones locales del host hechas fuera de OpenClaw no se sincronizan automáticamente en el sandbox después del paso de inicialización. +El transporte es SSH hacia el sandbox de OpenShell, pero el plugin controla el ciclo de vida del sandbox y la sincronización espejo opcional. -**`setupCommand`** se ejecuta una vez después de la creación del contenedor (mediante `sh -lc`). Necesita salida de red, raíz escribible y usuario root. +**`setupCommand`** se ejecuta una vez después de crear el contenedor (mediante `sh -lc`). Necesita salida de red, raíz escribible y usuario root. -**Los contenedores tienen como valor predeterminado `network: "none"`**: establécelo en `"bridge"` (o una red bridge personalizada) si el agente necesita acceso saliente. -`"host"` está bloqueado. `"container:"` está bloqueado de forma predeterminada a menos que establezcas explícitamente -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (modo de emergencia). +**Los contenedores usan `network: "none"` de forma predeterminada**. Establézcalo en `"bridge"` (o una red bridge personalizada) si el agente necesita acceso saliente. +`"host"` está bloqueado. `"container:"` está bloqueado de forma predeterminada a menos que establezca explícitamente +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (emergencia). -**Los adjuntos entrantes** se preparan en `media/inbound/*` en el workspace activo. +**Los adjuntos entrantes** se preparan en `media/inbound/*` dentro del workspace activo. -**`docker.binds`** monta directorios adicionales del host; los binds globales y por agente se fusionan. +**`docker.binds`** monta directorios adicionales del host; los montajes globales y por agente se combinan. -**Navegador en sandbox** (`sandbox.browser.enabled`): Chromium + CDP en un contenedor. La URL de noVNC se inyecta en el prompt del sistema. No requiere `browser.enabled` en `openclaw.json`. -El acceso de observador de noVNC usa autenticación VNC de forma predeterminada y OpenClaw emite una URL con token de corta duración (en lugar de exponer la contraseña en la URL compartida). +**Navegador en sandbox** (`sandbox.browser.enabled`): Chromium + CDP en un contenedor. La URL de noVNC se inserta en el system prompt. No requiere `browser.enabled` en `openclaw.json`. +El acceso de observador noVNC usa autenticación VNC de forma predeterminada y OpenClaw emite una URL con token de corta duración (en lugar de exponer la contraseña en la URL compartida). - `allowHostControl: false` (predeterminado) bloquea que las sesiones en sandbox apunten al navegador del host. -- `network` tiene como valor predeterminado `openclaw-sandbox-browser` (red bridge dedicada). Establécelo en `bridge` solo cuando quieras explícitamente conectividad bridge global. -- `cdpSourceRange` restringe opcionalmente la entrada de CDP en el borde del contenedor a un rango CIDR (por ejemplo `172.21.0.1/32`). +- `network` usa `openclaw-sandbox-browser` de forma predeterminada (red bridge dedicada). Establézcalo en `bridge` solo cuando quiera explícitamente conectividad global de bridge. +- `cdpSourceRange` restringe opcionalmente el ingreso de CDP en el borde del contenedor a un rango CIDR (por ejemplo `172.21.0.1/32`). - `sandbox.browser.binds` monta directorios adicionales del host solo en el contenedor del navegador en sandbox. Cuando se establece (incluido `[]`), reemplaza `docker.binds` para el contenedor del navegador. -- Los valores predeterminados de lanzamiento se definen en `scripts/sandbox-browser-entrypoint.sh` y están ajustados para hosts de contenedores: +- Los valores predeterminados de lanzamiento están definidos en `scripts/sandbox-browser-entrypoint.sh` y ajustados para hosts con contenedores: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1706,23 +1723,24 @@ El acceso de observador de noVNC usa autenticación VNC de forma predeterminada - `--disable-3d-apis`, `--disable-software-rasterizer` y `--disable-gpu` están habilitados de forma predeterminada y pueden desactivarse con `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si el uso de WebGL/3D lo requiere. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` vuelve a habilitar las extensiones si tu flujo de trabajo + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` vuelve a habilitar las extensiones si su flujo de trabajo depende de ellas. - `--renderer-process-limit=2` puede cambiarse con - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; establece `0` para usar el + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; establezca `0` para usar el límite de procesos predeterminado de Chromium. - - además `--no-sandbox` y `--disable-setuid-sandbox` cuando `noSandbox` está habilitado. - - Los valores predeterminados son la línea base de la imagen del contenedor; usa una imagen de navegador personalizada con un entrypoint personalizado para cambiar los valores predeterminados del contenedor. + - además de `--no-sandbox` y `--disable-setuid-sandbox` cuando `noSandbox` está habilitado. + - Los valores predeterminados son la línea base de la imagen del contenedor; use una imagen de navegador personalizada con un + entrypoint personalizado para cambiar los valores predeterminados del contenedor. El sandboxing del navegador y `sandbox.docker.binds` son solo para Docker. -Construir imágenes: +Compilar imágenes: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # imagen principal del sandbox +scripts/sandbox-browser-setup.sh # imagen opcional del navegador ``` ### `agents.list` (sobrescrituras por agente) @@ -1737,13 +1755,13 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // o { primary, fallbacks } + thinkingDefault: "high", // sobrescritura por agente del nivel predeterminado de thinking + reasoningDefault: "on", // sobrescritura por agente de la visibilidad predeterminada del razonamiento + fastModeDefault: false, // sobrescritura por agente del modo rápido predeterminado embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // sobrescribe por clave los params coincidentes de defaults.models + skills: ["docs-search"], // reemplaza agents.defaults.skills cuando se establece identity: { name: "Samantha", theme: "helpful sloth", @@ -1774,27 +1792,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: id estable del agente (obligatorio). +- `id`: ID estable del agente (obligatorio). - `default`: cuando se establecen varios, gana el primero (se registra una advertencia). Si no se establece ninguno, la primera entrada de la lista es la predeterminada. -- `model`: la forma de cadena sobrescribe solo `primary`; la forma de objeto `{ primary, fallbacks }` sobrescribe ambos (`[]` desactiva los respaldos globales). Los trabajos Cron que solo sobrescriben `primary` siguen heredando los respaldos predeterminados a menos que establezcas `fallbacks: []`. -- `params`: parámetros de stream por agente fusionados sobre la entrada de modelo seleccionada en `agents.defaults.models`. Usa esto para sobrescrituras específicas del agente como `cacheRetention`, `temperature` o `maxTokens` sin duplicar todo el catálogo de modelos. -- `skills`: lista de permitidos opcional de Skills por agente. Si se omite, el agente hereda `agents.defaults.skills` cuando está establecido; una lista explícita reemplaza los valores predeterminados en lugar de fusionarlos, y `[]` significa que no hay Skills. -- `thinkingDefault`: sobrescritura opcional por agente para el nivel predeterminado de thinking (`off | minimal | low | medium | high | xhigh | adaptive`). Sobrescribe `agents.defaults.thinkingDefault` para este agente cuando no se establece una sobrescritura por mensaje o sesión. -- `reasoningDefault`: sobrescritura opcional por agente para la visibilidad predeterminada de reasoning (`on | off | stream`). Se aplica cuando no se establece una sobrescritura de reasoning por mensaje o sesión. -- `fastModeDefault`: valor predeterminado opcional por agente para el modo rápido (`true | false`). Se aplica cuando no se establece una sobrescritura por mensaje o sesión. -- `embeddedHarness`: sobrescritura opcional por agente de la política del harness de bajo nivel. Usa `{ runtime: "codex", fallback: "none" }` para hacer que un agente sea solo Codex mientras otros agentes conservan el respaldo predeterminado a PI. -- `runtime`: descriptor de runtime opcional por agente. Usa `type: "acp"` con valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar por defecto sesiones de harness ACP. +- `model`: la forma de cadena sobrescribe solo `primary`; la forma de objeto `{ primary, fallbacks }` sobrescribe ambos (`[]` desactiva los respaldos globales). Los trabajos Cron que solo sobrescriben `primary` siguen heredando los respaldos predeterminados a menos que establezca `fallbacks: []`. +- `params`: params de flujo por agente combinados sobre la entrada del modelo seleccionado en `agents.defaults.models`. Úselo para sobrescrituras específicas del agente como `cacheRetention`, `temperature` o `maxTokens` sin duplicar todo el catálogo de modelos. +- `skills`: lista de permitidos opcional de Skills por agente. Si se omite, el agente hereda `agents.defaults.skills` cuando está establecido; una lista explícita reemplaza los valores predeterminados en lugar de combinarse, y `[]` significa sin Skills. +- `thinkingDefault`: nivel predeterminado opcional de thinking por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Sobrescribe `agents.defaults.thinkingDefault` para este agente cuando no hay una sobrescritura por mensaje o por sesión. +- `reasoningDefault`: visibilidad predeterminada opcional del razonamiento por agente (`on | off | stream`). Se aplica cuando no hay una sobrescritura de razonamiento por mensaje o por sesión. +- `fastModeDefault`: valor predeterminado opcional por agente para el modo rápido (`true | false`). Se aplica cuando no hay una sobrescritura de modo rápido por mensaje o por sesión. +- `embeddedHarness`: sobrescritura opcional por agente de la política de harness de bajo nivel. Use `{ runtime: "codex", fallback: "none" }` para hacer que un agente sea solo Codex mientras otros agentes conservan el respaldo predeterminado de PI. +- `runtime`: descriptor opcional del runtime por agente. Use `type: "acp"` con los valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar por defecto sesiones de harness ACP. - `identity.avatar`: ruta relativa al workspace, URL `http(s)` o URI `data:`. -- `identity` deriva valores predeterminados: `ackReaction` de `emoji`, `mentionPatterns` de `name`/`emoji`. -- `subagents.allowAgents`: lista de permitidos de ids de agente para `sessions_spawn` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- `identity` deriva valores predeterminados: `ackReaction` a partir de `emoji`, `mentionPatterns` a partir de `name`/`emoji`. +- `subagents.allowAgents`: lista de permitidos de IDs de agentes para `sessions_spawn` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). - Protección de herencia del sandbox: si la sesión solicitante está en sandbox, `sessions_spawn` rechaza destinos que se ejecutarían sin sandbox. -- `subagents.requireAgentId`: cuando es true, bloquea las llamadas a `sessions_spawn` que omiten `agentId` (fuerza la selección explícita de perfil; predeterminado: false). +- `subagents.requireAgentId`: cuando es true, bloquea llamadas a `sessions_spawn` que omiten `agentId` (fuerza la selección explícita de perfil; predeterminado: false). --- ## Enrutamiento multiagente -Ejecuta varios agentes aislados dentro de un Gateway. Consulta [Multi-Agent](/es/concepts/multi-agent). +Ejecute varios agentes aislados dentro de un Gateway. Consulte [Multi-Agent](/es/concepts/multi-agent). ```json5 { @@ -1811,16 +1829,16 @@ Ejecuta varios agentes aislados dentro de un Gateway. Consulta [Multi-Agent](/es } ``` -### Campos de coincidencia de enlaces +### Campos de coincidencia de asociaciones -- `type` (opcional): `route` para enrutamiento normal (si falta, type usa route por defecto), `acp` para enlaces persistentes de conversación ACP. +- `type` (opcional): `route` para enrutamiento normal (la ausencia de tipo usa route como predeterminado), `acp` para asociaciones persistentes de conversaciones ACP. - `match.channel` (obligatorio) - `match.accountId` (opcional; `*` = cualquier cuenta; omitido = cuenta predeterminada) - `match.peer` (opcional; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (opcional; específico del canal) - `acp` (opcional; solo para entradas `type: "acp"`): `{ mode, label, cwd, backend }` -**Orden determinista de coincidencia:** +**Orden de coincidencia determinista:** 1. `match.peer` 2. `match.guildId` @@ -1831,7 +1849,7 @@ Ejecuta varios agentes aislados dentro de un Gateway. Consulta [Multi-Agent](/es Dentro de cada nivel, gana la primera entrada coincidente de `bindings`. -Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden de niveles de enlaces de route anterior. +Para las entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden de niveles de asociaciones de ruta anterior. ### Perfiles de acceso por agente @@ -1928,7 +1946,7 @@ Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversac -Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tools) para los detalles de precedencia. +Consulte [Multi-Agent Sandbox & Tools](/es/tools/multi-agent-sandbox-tools) para conocer los detalles de precedencia. --- @@ -1954,22 +1972,22 @@ Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tool }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // omite la bifurcación del hilo principal por encima de este conteo de tokens (0 lo desactiva) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // duración o false + maxDiskBytes: "500mb", // presupuesto máximo opcional estricto + highWaterBytes: "400mb", // objetivo opcional de limpieza }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // desenfoque automático predeterminado por inactividad en horas (`0` lo desactiva) + maxAgeHours: 0, // antigüedad máxima estricta predeterminada en horas (`0` lo desactiva) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // heredado (el runtime siempre usa "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1979,37 +1997,37 @@ Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tool } ``` - + -- **`scope`**: estrategia base de agrupación de sesiones para contextos de chat grupal. - - `per-sender` (predeterminado): cada remitente obtiene una sesión aislada dentro del contexto de un canal. - - `global`: todos los participantes en un contexto de canal comparten una sola sesión (úsalo solo cuando se pretenda contexto compartido). -- **`dmScope`**: cómo se agrupan las MD. - - `main`: todas las MD comparten la sesión principal. - - `per-peer`: aísla por id de remitente entre canales. +- **`scope`**: estrategia base de agrupación de sesiones para contextos de chats grupales. + - `per-sender` (predeterminado): cada remitente obtiene una sesión aislada dentro de un contexto de canal. + - `global`: todos los participantes de un contexto de canal comparten una sola sesión (úselo solo cuando se pretenda un contexto compartido). +- **`dmScope`**: cómo se agrupan los MD. + - `main`: todos los MD comparten la sesión principal. + - `per-peer`: aísla por ID de remitente entre canales. - `per-channel-peer`: aísla por canal + remitente (recomendado para bandejas de entrada multiusuario). - - `per-account-channel-peer`: aísla por cuenta + canal + remitente (recomendado para múltiples cuentas). -- **`identityLinks`**: asigna ids canónicos a peers con prefijo de proveedor para compartir sesiones entre canales. -- **`reset`**: política principal de reinicio. `daily` reinicia a `atHour` en hora local; `idle` reinicia después de `idleMinutes`. Cuando ambos están configurados, gana el que venza primero. -- **`resetByType`**: sobrescrituras por tipo (`direct`, `group`, `thread`). Se acepta el heredado `dm` como alias de `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` permitido de la sesión padre al crear una sesión de hilo bifurcada (predeterminado `100000`). - - Si `totalTokens` del padre está por encima de este valor, OpenClaw inicia una sesión de hilo nueva en lugar de heredar el historial de transcripción del padre. - - Establece `0` para desactivar esta protección y permitir siempre la bifurcación desde el padre. + - `per-account-channel-peer`: aísla por cuenta + canal + remitente (recomendado para varias cuentas). +- **`identityLinks`**: asigna IDs canónicos a peers con prefijo de proveedor para compartir sesiones entre canales. +- **`reset`**: política principal de reinicio. `daily` reinicia a la hora local `atHour`; `idle` reinicia después de `idleMinutes`. Cuando ambos están configurados, gana el que expire primero. +- **`resetByType`**: sobrescrituras por tipo (`direct`, `group`, `thread`). Se acepta `dm` heredado como alias de `direct`. +- **`parentForkMaxTokens`**: máximo de `totalTokens` de la sesión principal permitido al crear una sesión de hilo bifurcada (predeterminado `100000`). + - Si `totalTokens` de la sesión principal está por encima de este valor, OpenClaw inicia una sesión de hilo nueva en lugar de heredar el historial de transcripción de la sesión principal. + - Establezca `0` para desactivar esta protección y permitir siempre la bifurcación desde la sesión principal. - **`mainKey`**: campo heredado. El runtime siempre usa `"main"` para el bucket principal de chat directo. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de respuesta entre agentes durante intercambios agente a agente (entero, rango: `0`–`5`). `0` desactiva la cadena ping-pong. -- **`sendPolicy`**: coincide por `channel`, `chatType` (`direct|group|channel`, con alias heredado `dm`), `keyPrefix` o `rawKeyPrefix`. Gana la primera denegación. +- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de respuesta de ida y vuelta entre agentes durante intercambios entre agentes (entero, rango: `0`–`5`). `0` desactiva el encadenamiento ping-pong. +- **`sendPolicy`**: hace coincidencia por `channel`, `chatType` (`direct|group|channel`, con alias heredado `dm`), `keyPrefix` o `rawKeyPrefix`. Gana la primera denegación. - **`maintenance`**: controles de limpieza + retención del almacén de sesiones. - `mode`: `warn` solo emite advertencias; `enforce` aplica la limpieza. - `pruneAfter`: límite de antigüedad para entradas obsoletas (predeterminado `30d`). - `maxEntries`: número máximo de entradas en `sessions.json` (predeterminado `500`). - `rotateBytes`: rota `sessions.json` cuando supera este tamaño (predeterminado `10mb`). - - `resetArchiveRetention`: retención para archivos de transcripción `*.reset.`. Usa `pruneAfter` por defecto; establece `false` para desactivar. + - `resetArchiveRetention`: retención para archivos de transcripción `*.reset.`. Usa `pruneAfter` de forma predeterminada; establezca `false` para desactivarlo. - `maxDiskBytes`: presupuesto opcional de disco para el directorio de sesiones. En modo `warn` registra advertencias; en modo `enforce` elimina primero los artefactos/sesiones más antiguos. - - `highWaterBytes`: objetivo opcional después de la limpieza por presupuesto. Usa `80%` de `maxDiskBytes` por defecto. -- **`threadBindings`**: valores predeterminados globales para funciones de sesión vinculadas a hilos. + - `highWaterBytes`: objetivo opcional después de la limpieza por presupuesto. De forma predeterminada es el `80%` de `maxDiskBytes`. +- **`threadBindings`**: valores predeterminados globales para funciones de sesión asociadas a hilos. - `enabled`: interruptor maestro predeterminado (los proveedores pueden sobrescribirlo; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: auto-unfocus predeterminado por inactividad en horas (`0` lo desactiva; los proveedores pueden sobrescribirlo) - - `maxAgeHours`: antigüedad máxima estricta predeterminada en horas (`0` lo desactiva; los proveedores pueden sobrescribirlo) + - `idleHours`: desenfoque automático predeterminado por inactividad en horas (`0` lo desactiva; los proveedores pueden sobrescribirlo) + - `maxAgeHours`: antigüedad máxima estricta predeterminada en horas (`0` la desactiva; los proveedores pueden sobrescribirla) @@ -2055,28 +2073,28 @@ Resolución (gana la más específica): cuenta → canal → global. `""` desact | Variable | Descripción | Ejemplo | | ----------------- | ---------------------- | --------------------------- | -| `{model}` | Nombre corto del modelo | `claude-opus-4-6` | +| `{model}` | Nombre corto del modelo | `claude-opus-4-6` | | `{modelFull}` | Identificador completo del modelo | `anthropic/claude-opus-4-6` | | `{provider}` | Nombre del proveedor | `anthropic` | -| `{thinkingLevel}` | Nivel actual de thinking | `high`, `low`, `off` | -| `{identity.name}` | Nombre de identidad del agente | (igual que `"auto"`) | +| `{thinkingLevel}` | Nivel actual de thinking | `high`, `low`, `off` | +| `{identity.name}` | Nombre de identidad del agente | (igual que `"auto"`) | -Las variables no distinguen entre mayúsculas y minúsculas. `{think}` es un alias de `{thinkingLevel}`. +Las variables no distinguen mayúsculas de minúsculas. `{think}` es un alias de `{thinkingLevel}`. -### Reacción de confirmación +### Reacción de acuse -- Usa por defecto `identity.emoji` del agente activo, en caso contrario `"👀"`. Establece `""` para desactivar. +- Usa de forma predeterminada `identity.emoji` del agente activo; en caso contrario `"👀"`. Establezca `""` para desactivarla. - Sobrescrituras por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. - Orden de resolución: cuenta → canal → `messages.ackReaction` → respaldo de identidad. -- Alcance: `group-mentions` (predeterminado), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: elimina la confirmación después de responder en Slack, Discord y Telegram. +- Ámbito: `group-mentions` (predeterminado), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: elimina el acuse después de responder en Slack, Discord y Telegram. - `messages.statusReactions.enabled`: habilita reacciones de estado del ciclo de vida en Slack, Discord y Telegram. - En Slack y Discord, dejarlo sin definir mantiene habilitadas las reacciones de estado cuando las reacciones de confirmación están activas. - En Telegram, establécelo explícitamente en `true` para habilitar las reacciones de estado del ciclo de vida. + En Slack y Discord, si no se establece, las reacciones de estado siguen habilitadas cuando las reacciones de acuse están activas. + En Telegram, establézcalo explícitamente en `true` para habilitar las reacciones de estado del ciclo de vida. -### Debounce entrante +### Debounce de entrada -Agrupa mensajes rápidos solo de texto del mismo remitente en un único turno de agente. Los medios/adjuntos se vacían de inmediato. Los comandos de control omiten el debounce. +Agrupa mensajes rápidos de solo texto del mismo remitente en un único turno del agente. Los medios/adjuntos se vacían de inmediato. Los comandos de control omiten el debounce. ### TTS (texto a voz) @@ -2119,11 +2137,11 @@ Agrupa mensajes rápidos solo de texto del mismo remitente en un único turno de } ``` -- `auto` controla el modo predeterminado de auto-TTS: `off`, `always`, `inbound` o `tagged`. `/tts on|off` puede sobrescribir las preferencias locales y `/tts status` muestra el estado efectivo. +- `auto` controla el modo predeterminado de TTS automático: `off`, `always`, `inbound` o `tagged`. `/tts on|off` puede sobrescribir las preferencias locales, y `/tts status` muestra el estado efectivo. - `summaryModel` sobrescribe `agents.defaults.model.primary` para el resumen automático. -- `modelOverrides` está habilitado de forma predeterminada; `modelOverrides.allowProvider` usa `false` por defecto (opt-in). +- `modelOverrides` está habilitado de forma predeterminada; `modelOverrides.allowProvider` usa `false` como predeterminado (opt-in). - Las claves de API usan como respaldo `ELEVENLABS_API_KEY`/`XI_API_KEY` y `OPENAI_API_KEY`. -- `openai.baseUrl` sobrescribe el endpoint TTS de OpenAI. El orden de resolución es configuración, luego `OPENAI_TTS_BASE_URL` y luego `https://api.openai.com/v1`. +- `openai.baseUrl` sobrescribe el endpoint de TTS de OpenAI. El orden de resolución es configuración, luego `OPENAI_TTS_BASE_URL`, luego `https://api.openai.com/v1`. - Cuando `openai.baseUrl` apunta a un endpoint que no es de OpenAI, OpenClaw lo trata como un servidor TTS compatible con OpenAI y flexibiliza la validación de modelo/voz. --- @@ -2155,12 +2173,12 @@ Valores predeterminados para el modo Talk (macOS/iOS/Android). ``` - `talk.provider` debe coincidir con una clave en `talk.providers` cuando se configuran varios proveedores de Talk. -- Las claves heredadas planas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) son solo de compatibilidad y se migran automáticamente a `talk.providers.`. +- Las claves planas heredadas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) son solo de compatibilidad y se migran automáticamente a `talk.providers.`. - Los IDs de voz usan como respaldo `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. -- `providers.*.apiKey` acepta cadenas de texto sin formato u objetos SecretRef. -- El respaldo `ELEVENLABS_API_KEY` solo se aplica cuando no hay una clave de API de Talk configurada. +- `providers.*.apiKey` acepta cadenas en texto sin formato u objetos SecretRef. +- El respaldo `ELEVENLABS_API_KEY` se aplica solo cuando no hay una clave API de Talk configurada. - `providers.*.voiceAliases` permite que las directivas de Talk usen nombres amigables. -- `silenceTimeoutMs` controla cuánto espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no se define, se mantiene la ventana de pausa predeterminada de la plataforma (`700 ms en macOS y Android, 900 ms en iOS`). +- `silenceTimeoutMs` controla cuánto tiempo espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no se establece, se mantiene la ventana de pausa predeterminada de la plataforma (`700 ms en macOS y Android, 900 ms en iOS`). --- @@ -2170,35 +2188,35 @@ Valores predeterminados para el modo Talk (macOS/iOS/Android). `tools.profile` establece una lista base de permitidos antes de `tools.allow`/`tools.deny`: -La incorporación local configura por defecto los nuevos archivos de configuración locales con `tools.profile: "coding"` cuando no está definido (los perfiles explícitos existentes se conservan). +El onboarding local configura por defecto las nuevas configuraciones locales con `tools.profile: "coding"` cuando no está establecido (se conservan los perfiles explícitos existentes). | Perfil | Incluye | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | solo `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Sin restricción (igual que no definido) | +| `full` | Sin restricción (igual que no establecerlo) | ### Grupos de herramientas -| Grupo | Herramientas | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` se acepta como alias de `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Grupo | Herramientas | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` se acepta como alias de `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Todas las herramientas integradas (excluye plugins de proveedor) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Todas las herramientas integradas (excluye plugins de proveedores) | ### `tools.allow` / `tools.deny` -Política global de permitir/denegar herramientas (denegar tiene prioridad). No distingue entre mayúsculas y minúsculas, admite comodines `*`. Se aplica incluso cuando el sandbox de Docker está desactivado. +Política global de permitir/denegar herramientas (gana deny). No distingue entre mayúsculas y minúsculas, admite comodines `*`. Se aplica incluso cuando el sandbox de Docker está desactivado. ```json5 { @@ -2208,7 +2226,7 @@ Política global de permitir/denegar herramientas (denegar tiene prioridad). No ### `tools.byProvider` -Restringe aún más las herramientas para proveedores o modelos específicos. Orden: perfil base → perfil del proveedor → permitir/denegar. +Restringe aún más las herramientas para proveedores o modelos específicos. Orden: perfil base → perfil del proveedor → allow/deny. ```json5 { @@ -2224,7 +2242,7 @@ Restringe aún más las herramientas para proveedores o modelos específicos. Or ### `tools.elevated` -Controla el acceso elevado de `exec` fuera del sandbox: +Controla el acceso elevado a `exec` fuera del sandbox: ```json5 { @@ -2242,7 +2260,7 @@ Controla el acceso elevado de `exec` fuera del sandbox: - La sobrescritura por agente (`agents.list[].tools.elevated`) solo puede restringir aún más. - `/elevated on|off|ask|full` almacena el estado por sesión; las directivas en línea se aplican a un solo mensaje. -- `exec` elevado omite el sandboxing y usa la ruta de escape configurada (`gateway` de forma predeterminada, o `node` cuando el objetivo de exec es `node`). +- `exec` elevado omite el sandboxing y usa la ruta de escape configurada (`gateway` de forma predeterminada, o `node` cuando el destino de exec es `node`). ### `tools.exec` @@ -2266,7 +2284,7 @@ Controla el acceso elevado de `exec` fuera del sandbox: ### `tools.loopDetection` -Las comprobaciones de seguridad de bucles de herramientas están **desactivadas de forma predeterminada**. Establece `enabled: true` para activar la detección. +Las verificaciones de seguridad de bucles de herramientas están **desactivadas de forma predeterminada**. Establezca `enabled: true` para activar la detección. La configuración puede definirse globalmente en `tools.loopDetection` y sobrescribirse por agente en `agents.list[].tools.loopDetection`. ```json5 @@ -2288,13 +2306,13 @@ La configuración puede definirse globalmente en `tools.loopDetection` y sobresc } ``` -- `historySize`: máximo de historial de llamadas a herramientas conservado para análisis de bucles. +- `historySize`: máximo historial de llamadas a herramientas retenido para el análisis de bucles. - `warningThreshold`: umbral de patrón repetitivo sin progreso para advertencias. - `criticalThreshold`: umbral repetitivo más alto para bloquear bucles críticos. -- `globalCircuitBreakerThreshold`: umbral de parada total para cualquier ejecución sin progreso. +- `globalCircuitBreakerThreshold`: umbral de detención total para cualquier ejecución sin progreso. - `detectors.genericRepeat`: advierte sobre llamadas repetidas a la misma herramienta/con los mismos argumentos. -- `detectors.knownPollNoProgress`: advierte/bloquea en herramientas de sondeo conocidas (`process.poll`, `command_status`, etc.). -- `detectors.pingPong`: advierte/bloquea en patrones alternos de pares sin progreso. +- `detectors.knownPollNoProgress`: advierte/bloquea herramientas de sondeo conocidas (`process.poll`, `command_status`, etc.). +- `detectors.pingPong`: advierte/bloquea patrones alternantes de pares sin progreso. - Si `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la validación falla. ### `tools.web` @@ -2329,7 +2347,7 @@ La configuración puede definirse globalmente en `tools.loopDetection` y sobresc ### `tools.media` -Configura el entendimiento de medios entrantes (imagen/audio/video): +Configura la comprensión de medios entrantes (imagen/audio/video): ```json5 { @@ -2365,8 +2383,8 @@ Configura el entendimiento de medios entrantes (imagen/audio/video): **Entrada de proveedor** (`type: "provider"` u omitido): -- `provider`: id del proveedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) -- `model`: sobrescritura del id del modelo +- `provider`: ID del proveedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) +- `model`: sobrescritura del ID del modelo - `profile` / `preferredProfile`: selección de perfil de `auth-profiles.json` **Entrada de CLI** (`type: "cli"`): @@ -2384,9 +2402,9 @@ La autenticación del proveedor sigue el orden estándar: `auth-profiles.json` **Campos de finalización asíncrona:** -- `asyncCompletion.directSend`: cuando es `true`, las tareas completadas asíncronas `music_generate` +- `asyncCompletion.directSend`: cuando es `true`, las tareas asíncronas completadas de `music_generate` y `video_generate` intentan primero la entrega directa al canal. Predeterminado: `false` - (ruta heredada de activación de sesión del solicitante/entrega de modelo). + (ruta heredada de activación de sesión solicitante/entrega por modelo). @@ -2424,13 +2442,13 @@ Notas: - `self`: solo la clave de la sesión actual. - `tree`: sesión actual + sesiones generadas por la sesión actual (subagentes). -- `agent`: cualquier sesión que pertenezca al id del agente actual (puede incluir otros usuarios si ejecutas sesiones por remitente bajo el mismo id de agente). -- `all`: cualquier sesión. El direccionamiento entre agentes sigue requiriendo `tools.agentToAgent`. -- Restricción del sandbox: cuando la sesión actual está en sandbox y `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilidad se fuerza a `tree` incluso si `tools.sessions.visibility="all"`. +- `agent`: cualquier sesión perteneciente al ID actual del agente (puede incluir otros usuarios si ejecuta sesiones por remitente bajo el mismo ID de agente). +- `all`: cualquier sesión. La selección entre agentes sigue requiriendo `tools.agentToAgent`. +- Limitación por sandbox: cuando la sesión actual está en sandbox y `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilidad se fuerza a `tree` incluso si `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Controla la compatibilidad con adjuntos en línea para `sessions_spawn`. +Controla el soporte de adjuntos en línea para `sessions_spawn`. ```json5 { @@ -2450,16 +2468,16 @@ Controla la compatibilidad con adjuntos en línea para `sessions_spawn`. Notas: -- Los adjuntos solo son compatibles con `runtime: "subagent"`. El runtime ACP los rechaza. +- Los adjuntos solo se admiten para `runtime: "subagent"`. El runtime ACP los rechaza. - Los archivos se materializan en el workspace hijo en `.openclaw/attachments//` con un `.manifest.json`. -- El contenido de los adjuntos se redacta automáticamente de la persistencia de transcripciones. -- Las entradas Base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección de tamaño previa a la decodificación. +- El contenido de los adjuntos se redacta automáticamente de la persistencia de la transcripción. +- Las entradas en base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección previa a la decodificación por tamaño. - Los permisos de archivo son `0700` para directorios y `0600` para archivos. - La limpieza sigue la política `cleanup`: `delete` siempre elimina los adjuntos; `keep` los conserva solo cuando `retainOnSessionKeep: true`. ### `tools.experimental` -Indicadores experimentales de herramientas integradas. Predeterminado desactivado salvo que se aplique una regla de autoactivación estrictamente agentiva de GPT-5. +Indicadores experimentales de herramientas integradas. Desactivados de forma predeterminada salvo que se aplique una regla de activación automática estrictamente agéntica de GPT-5. ```json5 { @@ -2473,9 +2491,9 @@ Indicadores experimentales de herramientas integradas. Predeterminado desactivad Notas: -- `planTool`: habilita la herramienta estructurada experimental `update_plan` para seguimiento de trabajo no trivial de varios pasos. -- Predeterminado: `false` a menos que `agents.defaults.embeddedPi.executionContract` (o una sobrescritura por agente) esté establecido en `"strict-agentic"` para una ejecución de la familia GPT-5 de OpenAI o OpenAI Codex. Establece `true` para forzar la activación fuera de ese ámbito, o `false` para mantenerla desactivada incluso en ejecuciones GPT-5 strict-agentic. -- Cuando está habilitada, el prompt del sistema también agrega orientación de uso para que el modelo solo la use en trabajo sustancial y mantenga como máximo un paso `in_progress`. +- `planTool`: habilita la herramienta estructurada `update_plan` para el seguimiento de trabajo no trivial de varios pasos. +- Predeterminado: `false` salvo que `agents.defaults.embeddedPi.executionContract` (o una sobrescritura por agente) esté establecido en `"strict-agentic"` para una ejecución de OpenAI o OpenAI Codex de la familia GPT-5. Establezca `true` para forzar la herramienta fuera de ese ámbito, o `false` para mantenerla desactivada incluso en ejecuciones estrictamente agénticas de GPT-5. +- Cuando está habilitada, el system prompt también agrega guía de uso para que el modelo solo la use en trabajo sustancial y mantenga como máximo un paso `in_progress`. ### `agents.defaults.subagents` @@ -2496,15 +2514,15 @@ Notas: ``` - `model`: modelo predeterminado para subagentes generados. Si se omite, los subagentes heredan el modelo del llamador. -- `allowAgents`: lista de permitidos predeterminada de ids de agentes de destino para `sessions_spawn` cuando el agente solicitante no establece su propio `subagents.allowAgents` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). -- `runTimeoutSeconds`: tiempo de espera predeterminado (segundos) para `sessions_spawn` cuando la llamada de herramienta omite `runTimeoutSeconds`. `0` significa sin tiempo de espera. +- `allowAgents`: lista de permitidos predeterminada de IDs de agentes de destino para `sessions_spawn` cuando el agente solicitante no establece su propio `subagents.allowAgents` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- `runTimeoutSeconds`: tiempo de espera predeterminado (segundos) para `sessions_spawn` cuando la llamada a la herramienta omite `runTimeoutSeconds`. `0` significa sin tiempo de espera. - Política de herramientas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## Proveedores personalizados y URLs base -OpenClaw usa el catálogo integrado de modelos. Agrega proveedores personalizados mediante `models.providers` en la configuración o `~/.openclaw/agents//agent/models.json`. +OpenClaw usa el catálogo de modelos integrado. Agregue proveedores personalizados mediante `models.providers` en la configuración o `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2533,48 +2551,48 @@ OpenClaw usa el catálogo integrado de modelos. Agrega proveedores personalizado } ``` -- Usa `authHeader: true` + `headers` para necesidades personalizadas de autenticación. -- Sobrescribe la raíz de configuración del agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, un alias heredado de variable de entorno). -- Precedencia de fusión para ids de proveedor coincidentes: - - Los valores no vacíos de `baseUrl` de `models.json` del agente tienen prioridad. - - Los valores no vacíos de `apiKey` del agente tienen prioridad solo cuando ese proveedor no está administrado por SecretRef en el contexto actual de configuración/perfil de autenticación. - - Los valores `apiKey` administrados por SecretRef se actualizan desde marcadores de origen (`ENV_VAR_NAME` para refs de entorno, `secretref-managed` para refs de archivo/exec) en lugar de persistir secretos resueltos. - - Los valores de encabezado de proveedor administrados por SecretRef se actualizan desde marcadores de origen (`secretref-env:ENV_VAR_NAME` para refs de entorno, `secretref-managed` para refs de archivo/exec). - - `apiKey`/`baseUrl` del agente vacíos o ausentes usan como respaldo `models.providers` en la configuración. - - `contextWindow`/`maxTokens` del modelo coincidente usan el valor más alto entre la configuración explícita y los valores implícitos del catálogo. - - `contextTokens` del modelo coincidente conserva un límite explícito del runtime cuando está presente; úsalo para limitar el contexto efectivo sin cambiar los metadatos nativos del modelo. - - Usa `models.mode: "replace"` cuando quieras que la configuración reescriba completamente `models.json`. - - La persistencia de marcadores es autoritativa por origen: los marcadores se escriben desde la instantánea activa de configuración de origen (previa a la resolución), no desde los valores secretos resueltos del runtime. +- Use `authHeader: true` + `headers` para necesidades de autenticación personalizadas. +- Sobrescriba la raíz de configuración del agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, un alias heredado de variable de entorno). +- Precedencia de combinación para IDs de proveedor coincidentes: + - Los valores `baseUrl` no vacíos del `models.json` del agente tienen prioridad. + - Los valores `apiKey` no vacíos del agente tienen prioridad solo cuando ese proveedor no está administrado por SecretRef en el contexto actual de configuración/perfil de autenticación. + - Los valores `apiKey` del proveedor administrados por SecretRef se actualizan desde marcadores de origen (`ENV_VAR_NAME` para referencias de entorno, `secretref-managed` para referencias de archivo/exec) en lugar de persistir secretos resueltos. + - Los valores de encabezado del proveedor administrados por SecretRef se actualizan desde marcadores de origen (`secretref-env:ENV_VAR_NAME` para referencias de entorno, `secretref-managed` para referencias de archivo/exec). + - Los valores `apiKey`/`baseUrl` vacíos o ausentes del agente usan como respaldo `models.providers` en la configuración. + - Los valores `contextWindow`/`maxTokens` de modelos coincidentes usan el valor más alto entre la configuración explícita y los valores implícitos del catálogo. + - Los valores `contextTokens` de modelos coincidentes conservan un límite explícito de runtime cuando está presente; úselo para limitar el contexto efectivo sin cambiar los metadatos nativos del modelo. + - Use `models.mode: "replace"` cuando quiera que la configuración reescriba por completo `models.json`. + - La persistencia de marcadores es autoritativa según la fuente: los marcadores se escriben a partir de la instantánea activa de configuración de origen (previa a la resolución), no a partir de valores secretos resueltos del runtime. ### Detalles de campos del proveedor - `models.mode`: comportamiento del catálogo de proveedores (`merge` o `replace`). -- `models.providers`: mapa de proveedores personalizados indexado por id de proveedor. +- `models.providers`: mapa de proveedores personalizados indexado por ID de proveedor. - `models.providers.*.api`: adaptador de solicitudes (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc.). -- `models.providers.*.apiKey`: credencial del proveedor (se prefiere SecretRef/sustitución por entorno). +- `models.providers.*.apiKey`: credencial del proveedor (prefiera SecretRef/sustitución por variables de entorno). - `models.providers.*.auth`: estrategia de autenticación (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, inyecta `options.num_ctx` en las solicitudes (predeterminado: `true`). -- `models.providers.*.authHeader`: fuerza el transporte de credenciales en el encabezado `Authorization` cuando sea necesario. -- `models.providers.*.baseUrl`: URL base de la API upstream. -- `models.providers.*.headers`: encabezados estáticos extra para enrutamiento de proxy/tenant. +- `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, inserta `options.num_ctx` en las solicitudes (predeterminado: `true`). +- `models.providers.*.authHeader`: fuerza el transporte de la credencial en el encabezado `Authorization` cuando es necesario. +- `models.providers.*.baseUrl`: URL base de la API ascendente. +- `models.providers.*.headers`: encabezados estáticos adicionales para enrutamiento de proxy/tenant. - `models.providers.*.request`: sobrescrituras de transporte para solicitudes HTTP del proveedor de modelos. - - `request.headers`: encabezados extra (fusionados con los valores predeterminados del proveedor). Los valores aceptan SecretRef. - - `request.auth`: sobrescritura de estrategia de autenticación. Modos: `"provider-default"` (usa la autenticación integrada del proveedor), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` opcional). + - `request.headers`: encabezados adicionales (combinados con los valores predeterminados del proveedor). Los valores aceptan SecretRef. + - `request.auth`: sobrescritura de la estrategia de autenticación. Modos: `"provider-default"` (usa la autenticación integrada del proveedor), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` opcional). - `request.proxy`: sobrescritura del proxy HTTP. Modos: `"env-proxy"` (usa las variables de entorno `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Ambos modos aceptan un subobjeto `tls` opcional. - `request.tls`: sobrescritura TLS para conexiones directas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceptan SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: cuando es `true`, permite HTTPS a `baseUrl` cuando DNS se resuelve a rangos privados, CGNAT o similares, mediante la protección SSRF de fetch HTTP del proveedor (opt-in del operador para endpoints OpenAI-compatibles autohospedados de confianza). WebSocket usa el mismo `request` para encabezados/TLS, pero no esa protección SSRF de fetch. Predeterminado `false`. + - `request.allowPrivateNetwork`: cuando es `true`, permite HTTPS a `baseUrl` cuando el DNS se resuelve a rangos privados, CGNAT o similares, mediante la protección SSRF de obtención HTTP del proveedor (opt-in del operador para endpoints confiables autohospedados compatibles con OpenAI). WebSocket usa el mismo `request` para encabezados/TLS, pero no esa protección SSRF de fetch. Predeterminado `false`. - `models.providers.*.models`: entradas explícitas del catálogo de modelos del proveedor. - `models.providers.*.models.*.contextWindow`: metadatos de la ventana de contexto nativa del modelo. -- `models.providers.*.models.*.contextTokens`: límite opcional de contexto en runtime. Úsalo cuando quieras un presupuesto efectivo de contexto menor que `contextWindow` nativo del modelo. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: pista opcional de compatibilidad. Para `api: "openai-completions"` con un `baseUrl` no nativo no vacío (host distinto de `api.openai.com`), OpenClaw fuerza esto a `false` en runtime. Un `baseUrl` vacío u omitido mantiene el comportamiento predeterminado de OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: pista opcional de compatibilidad para endpoints de chat OpenAI-compatibles solo con cadenas. Cuando es `true`, OpenClaw aplana arreglos `messages[].content` de texto puro en cadenas simples antes de enviar la solicitud. +- `models.providers.*.models.*.contextTokens`: límite opcional de contexto en runtime. Úselo cuando quiera un presupuesto de contexto efectivo menor que el `contextWindow` nativo del modelo. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: pista de compatibilidad opcional. Para `api: "openai-completions"` con un `baseUrl` no nativo y no vacío (host distinto de `api.openai.com`), OpenClaw fuerza esto a `false` en runtime. Un `baseUrl` vacío/omitido conserva el comportamiento predeterminado de OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: pista de compatibilidad opcional para endpoints de chat compatibles con OpenAI que solo aceptan cadenas. Cuando es `true`, OpenClaw aplana los arreglos de `messages[].content` de texto puro en cadenas simples antes de enviar la solicitud. - `plugins.entries.amazon-bedrock.config.discovery`: raíz de configuración del descubrimiento automático de Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: activa/desactiva el descubrimiento implícito. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: activa o desactiva el descubrimiento implícito. - `plugins.entries.amazon-bedrock.config.discovery.region`: región de AWS para el descubrimiento. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de id de proveedor para descubrimiento dirigido. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional por ID de proveedor para descubrimiento dirigido. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de sondeo para la actualización del descubrimiento. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: ventana de contexto de respaldo para modelos descubiertos. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: tokens máximos de salida de respaldo para modelos descubiertos. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de salida de respaldo para modelos descubiertos. ### Ejemplos de proveedores @@ -2612,7 +2630,7 @@ OpenClaw usa el catálogo integrado de modelos. Agrega proveedores personalizado } ``` -Usa `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI directo. +Use `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI directo. @@ -2629,7 +2647,7 @@ Usa `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI directo. } ``` -Establece `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa referencias `opencode/...` para el catálogo Zen o referencias `opencode-go/...` para el catálogo Go. Atajo: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. +Establezca `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Use referencias `opencode/...` para el catálogo Zen o referencias `opencode-go/...` para el catálogo Go. Atajo: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. @@ -2646,11 +2664,11 @@ Establece `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa referencias `openco } ``` -Establece `ZAI_API_KEY`. `z.ai/*` y `z-ai/*` se aceptan como alias. Atajo: `openclaw onboard --auth-choice zai-api-key`. +Establezca `ZAI_API_KEY`. `z.ai/*` y `z-ai/*` se aceptan como alias. Atajo: `openclaw onboard --auth-choice zai-api-key`. - Endpoint general: `https://api.z.ai/api/paas/v4` -- Endpoint de coding (predeterminado): `https://api.z.ai/api/coding/paas/v4` -- Para el endpoint general, define un proveedor personalizado con la sobrescritura de URL base. +- Endpoint de codificación (predeterminado): `https://api.z.ai/api/coding/paas/v4` +- Para el endpoint general, defina un proveedor personalizado con la sobrescritura de URL base. @@ -2693,7 +2711,7 @@ Para el endpoint de China: `baseUrl: "https://api.moonshot.cn/v1"` o `openclaw o Los endpoints nativos de Moonshot anuncian compatibilidad de uso de streaming en el transporte compartido `openai-completions`, y OpenClaw se basa en las capacidades del endpoint -en lugar de solo en el id integrado del proveedor. +en lugar de solo en el ID del proveedor integrado. @@ -2750,7 +2768,7 @@ Compatible con Anthropic, proveedor integrado. Atajo: `openclaw onboard --auth-c } ``` -La URL base debe omitir `/v1` (el cliente Anthropic la agrega). Atajo: `openclaw onboard --auth-choice synthetic-api-key`. +La URL base debe omitir `/v1` (el cliente de Anthropic lo agrega). Atajo: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2790,20 +2808,20 @@ La URL base debe omitir `/v1` (el cliente Anthropic la agrega). Atajo: `openclaw } ``` -Establece `MINIMAX_API_KEY`. Atajos: +Establezca `MINIMAX_API_KEY`. Atajos: `openclaw onboard --auth-choice minimax-global-api` o `openclaw onboard --auth-choice minimax-cn-api`. -El catálogo de modelos usa por defecto solo M2.7. -En la ruta de streaming compatible con Anthropic, OpenClaw desactiva thinking de MiniMax -de forma predeterminada a menos que establezcas explícitamente `thinking` tú mismo. `/fast on` o -`params.fastMode: true` reescribe `MiniMax-M2.7` a +El catálogo de modelos usa solo M2.7 de forma predeterminada. +En la ruta de streaming compatible con Anthropic, OpenClaw desactiva el thinking de MiniMax +de forma predeterminada a menos que usted establezca `thinking` explícitamente. `/fast on` o +`params.fastMode: true` reescribe `MiniMax-M2.7` como `MiniMax-M2.7-highspeed`. -Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo local grande mediante la API de Responses de LM Studio en hardware potente; mantén fusionados los modelos alojados para respaldo. +Consulte [Local Models](/es/gateway/local-models). En resumen: ejecute un modelo local grande a través de LM Studio Responses API en hardware potente; mantenga los modelos alojados fusionados para respaldo. @@ -2834,14 +2852,14 @@ Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo } ``` -- `allowBundled`: lista de permitidos opcional solo para Skills bundled (las Skills administradas/de workspace no se ven afectadas). -- `load.extraDirs`: raíces adicionales de Skills compartidas (precedencia más baja). +- `allowBundled`: lista de permitidos opcional solo para Skills bundled (las Skills administradas/del workspace no se ven afectadas). +- `load.extraDirs`: raíces adicionales de Skills compartidas (menor precedencia). - `install.preferBrew`: cuando es true, prefiere instaladores de Homebrew cuando `brew` está - disponible antes de recurrir a otros tipos de instalador. -- `install.nodeManager`: preferencia del instalador Node para especificaciones `metadata.openclaw.install` + disponible antes de pasar a otros tipos de instaladores. +- `install.nodeManager`: preferencia del instalador de Node para especificaciones `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` desactiva una Skill incluso si está bundled/instalada. -- `entries..apiKey`: conveniencia para Skills que declaran una variable de entorno primaria (cadena de texto sin formato u objeto SecretRef). +- `entries..apiKey`: comodidad para Skills que declaran una variable de entorno principal (cadena en texto sin formato u objeto SecretRef). --- @@ -2869,43 +2887,43 @@ Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo } ``` -- Se cargan desde `~/.openclaw/extensions`, `/.openclaw/extensions` y `plugins.load.paths`. -- El descubrimiento acepta plugins nativos de OpenClaw, además de bundles compatibles de Codex y Claude, incluidos bundles de Claude sin manifiesto con el diseño predeterminado. +- Se carga desde `~/.openclaw/extensions`, `/.openclaw/extensions` y `plugins.load.paths`. +- El descubrimiento acepta plugins nativos de OpenClaw más paquetes Codex compatibles y paquetes Claude compatibles, incluidos paquetes Claude sin manifiesto con diseño predeterminado. - **Los cambios de configuración requieren reiniciar el gateway.** - `allow`: lista de permitidos opcional (solo se cargan los plugins listados). `deny` tiene prioridad. - `plugins.entries..apiKey`: campo de conveniencia de clave API a nivel de plugin (cuando el plugin lo admite). -- `plugins.entries..env`: mapa de variables de entorno con alcance del plugin. -- `plugins.entries..hooks.allowPromptInjection`: cuando es `false`, el núcleo bloquea `before_prompt_build` e ignora campos que mutan el prompt de `before_agent_start` heredado, mientras conserva `modelOverride` y `providerOverride` heredados. Se aplica a hooks de plugins nativos y a directorios de hooks compatibles proporcionados por bundles. -- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en que este plugin solicite sobrescrituras por ejecución de `provider` y `model` para ejecuciones de subagentes en segundo plano. -- `plugins.entries..subagent.allowedModels`: lista de permitidos opcional de destinos canónicos `provider/model` para sobrescrituras confiables de subagentes. Usa `"*"` solo cuando realmente quieras permitir cualquier modelo. -- `plugins.entries..config`: objeto de configuración definido por el plugin (validado por el esquema nativo del plugin de OpenClaw cuando está disponible). -- `plugins.entries.firecrawl.config.webFetch`: configuración del proveedor web-fetch de Firecrawl. +- `plugins.entries..env`: mapa de variables de entorno con ámbito del plugin. +- `plugins.entries..hooks.allowPromptInjection`: cuando es `false`, el núcleo bloquea `before_prompt_build` e ignora los campos heredados que mutan el prompt desde `before_agent_start`, al tiempo que conserva `modelOverride` y `providerOverride` heredados. Se aplica a hooks de plugins nativos y a directorios de hooks proporcionados por paquetes compatibles. +- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en este plugin para solicitar sobrescrituras por ejecución de `provider` y `model` para ejecuciones de subagentes en segundo plano. +- `plugins.entries..subagent.allowedModels`: lista de permitidos opcional de destinos canónicos `provider/model` para sobrescrituras confiables de subagentes. Use `"*"` solo cuando realmente quiera permitir cualquier modelo. +- `plugins.entries..config`: objeto de configuración definido por el plugin (validado por el esquema nativo del plugin OpenClaw cuando está disponible). +- `plugins.entries.firecrawl.config.webFetch`: configuración del proveedor de obtención web de Firecrawl. - `apiKey`: clave API de Firecrawl (acepta SecretRef). Usa como respaldo `plugins.entries.firecrawl.config.webSearch.apiKey`, el heredado `tools.web.fetch.firecrawl.apiKey` o la variable de entorno `FIRECRAWL_API_KEY`. - `baseUrl`: URL base de la API de Firecrawl (predeterminada: `https://api.firecrawl.dev`). - `onlyMainContent`: extrae solo el contenido principal de las páginas (predeterminado: `true`). - `maxAgeMs`: antigüedad máxima de caché en milisegundos (predeterminado: `172800000` / 2 días). - - `timeoutSeconds`: tiempo de espera de la solicitud de scrape en segundos (predeterminado: `60`). + - `timeoutSeconds`: tiempo de espera de la solicitud de scraping en segundos (predeterminado: `60`). - `plugins.entries.xai.config.xSearch`: configuración de xAI X Search (búsqueda web de Grok). - `enabled`: habilita el proveedor X Search. - - `model`: modelo Grok que se va a usar para la búsqueda (por ejemplo `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: configuración de memory dreaming. Consulta [Dreaming](/es/concepts/dreaming) para fases y umbrales. - - `enabled`: interruptor principal de dreaming (predeterminado `false`). - - `frequency`: cadencia Cron para cada barrido completo de dreaming (`"0 3 * * *"` por defecto). - - la política de fases y los umbrales son detalles de implementación (no claves de configuración orientadas al usuario). -- La configuración completa de memoria está en [Referencia de configuración de memoria](/es/reference/memory-config): + - `model`: modelo de Grok que se usará para la búsqueda (por ejemplo `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: configuración de dreaming de memoria. Consulte [Dreaming](/es/concepts/dreaming) para las fases y los umbrales. + - `enabled`: interruptor maestro de dreaming (predeterminado `false`). + - `frequency`: cadencia Cron para cada barrido completo de dreaming (predeterminado `"0 3 * * *"`). + - La política de fases y los umbrales son detalles de implementación (no son claves de configuración orientadas al usuario). +- La configuración completa de memoria se encuentra en [Referencia de configuración de memoria](/es/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Los plugins Claude bundle habilitados también pueden aportar valores predeterminados incrustados de Pi desde `settings.json`; OpenClaw los aplica como ajustes de agente saneados, no como parches sin procesar de configuración de OpenClaw. -- `plugins.slots.memory`: elige el id del plugin de memoria activo, o `"none"` para desactivar plugins de memoria. -- `plugins.slots.contextEngine`: elige el id del plugin activo de motor de contexto; el valor predeterminado es `"legacy"` a menos que instales y selecciones otro motor. -- `plugins.installs`: metadatos de instalación administrados por la CLI usados por `openclaw plugins update`. +- Los plugins de paquetes Claude habilitados también pueden aportar valores predeterminados integrados de Pi desde `settings.json`; OpenClaw los aplica como ajustes de agente saneados, no como parches sin procesar de configuración de OpenClaw. +- `plugins.slots.memory`: elija el ID del plugin de memoria activo, o `"none"` para desactivar los plugins de memoria. +- `plugins.slots.contextEngine`: elija el ID del plugin de motor de contexto activo; el valor predeterminado es `"legacy"` a menos que instale y seleccione otro motor. +- `plugins.installs`: metadatos de instalación administrados por CLI y usados por `openclaw plugins update`. - Incluye `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Trata `plugins.installs.*` como estado administrado; prefiere comandos de CLI en lugar de ediciones manuales. + - Trate `plugins.installs.*` como estado administrado; prefiera los comandos de CLI a las ediciones manuales. -Consulta [Plugins](/es/tools/plugin). +Consulte [Plugins](/es/tools/plugin). --- @@ -2946,28 +2964,29 @@ Consulta [Plugins](/es/tools/plugin). ``` - `evaluateEnabled: false` desactiva `act:evaluate` y `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` está desactivado cuando no se define, por lo que la navegación del navegador permanece estricta de forma predeterminada. -- Establece `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo cuando confíes intencionalmente en la navegación del navegador por redes privadas. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` está desactivado cuando no se establece, por lo que la navegación del navegador sigue siendo estricta de forma predeterminada. +- Establezca `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo cuando confíe intencionalmente en la navegación del navegador por red privada. - En modo estricto, los endpoints de perfiles CDP remotos (`profiles.*.cdpUrl`) están sujetos al mismo bloqueo de red privada durante las comprobaciones de alcance/detección. - `ssrfPolicy.allowPrivateNetwork` sigue siendo compatible como alias heredado. -- En modo estricto, usa `ssrfPolicy.hostnameAllowlist` y `ssrfPolicy.allowedHostnames` para excepciones explícitas. -- Los perfiles remotos son solo de conexión (inicio/detención/reinicio desactivados). +- En modo estricto, use `ssrfPolicy.hostnameAllowlist` y `ssrfPolicy.allowedHostnames` para excepciones explícitas. +- Los perfiles remotos son solo de conexión (inicio/detención/restablecimiento desactivados). - `profiles.*.cdpUrl` acepta `http://`, `https://`, `ws://` y `wss://`. - Usa HTTP(S) cuando quieras que OpenClaw detecte `/json/version`; usa WS(S) - cuando tu proveedor te proporcione una URL directa de WebSocket de DevTools. -- Los perfiles `existing-session` son solo para host y usan Chrome MCP en lugar de CDP. -- Los perfiles `existing-session` pueden establecer `userDataDir` para apuntar a un perfil - específico de navegador basado en Chromium como Brave o Edge. -- Los perfiles `existing-session` mantienen los límites actuales de la ruta Chrome MCP: - acciones guiadas por snapshot/ref en lugar de selección por CSS, hooks de carga de un solo archivo, - sin sobrescrituras de tiempo de espera de diálogos, sin `wait --load networkidle`, y sin - `responsebody`, exportación PDF, interceptación de descargas ni acciones por lotes. + Use HTTP(S) cuando quiera que OpenClaw descubra `/json/version`; use WS(S) + cuando su proveedor le dé una URL directa de WebSocket de DevTools. +- Los perfiles `existing-session` usan Chrome MCP en lugar de CDP y pueden conectarse en + el host seleccionado o a través de un Node de navegador conectado. +- Los perfiles `existing-session` pueden establecer `userDataDir` para apuntar a un perfil específico + de navegador basado en Chromium como Brave o Edge. +- Los perfiles `existing-session` conservan los límites actuales de la ruta Chrome MCP: + acciones basadas en instantáneas/referencias en lugar de selección por CSS, + hooks de carga de un solo archivo, sin sobrescrituras del tiempo de espera de cuadros de diálogo, sin + `wait --load networkidle` y sin `responsebody`, exportación PDF, intercepción de descargas ni acciones por lotes. - Los perfiles locales administrados `openclaw` asignan automáticamente `cdpPort` y `cdpUrl`; solo - establece `cdpUrl` explícitamente para CDP remoto. -- Orden de autodetección: navegador predeterminado si está basado en Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. + establezca `cdpUrl` explícitamente para CDP remoto. +- Orden de detección automática: navegador predeterminado si está basado en Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Servicio de control: solo loopback (puerto derivado de `gateway.port`, predeterminado `18791`). -- `extraArgs` agrega flags de lanzamiento extra al inicio local de Chromium (por ejemplo - `--disable-gpu`, tamaño de ventana o flags de depuración). +- `extraArgs` agrega indicadores de lanzamiento adicionales al inicio local de Chromium (por ejemplo + `--disable-gpu`, tamaño de ventana o indicadores de depuración). --- @@ -2985,8 +3004,8 @@ Consulta [Plugins](/es/tools/plugin). } ``` -- `seamColor`: color de acento para el chrome de la UI de la app nativa (tinte de la burbuja del modo Talk, etc.). -- `assistant`: sobrescritura de identidad de la Control UI. Usa como respaldo la identidad activa del agente. +- `seamColor`: color de acento para el cromado de la UI de la aplicación nativa (tono de la burbuja del modo Talk, etc.). +- `assistant`: sobrescritura de identidad de la Control UI. Usa como respaldo la identidad del agente activo. --- @@ -3053,66 +3072,66 @@ Consulta [Plugins](/es/tools/plugin). } ``` - + -- `mode`: `local` (ejecutar gateway) o `remote` (conectarse a un gateway remoto). El Gateway se niega a iniciarse salvo que sea `local`. +- `mode`: `local` (ejecutar gateway) o `remote` (conectarse a un gateway remoto). Gateway se niega a iniciarse salvo que sea `local`. - `port`: puerto multiplexado único para WS + HTTP. Precedencia: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (predeterminado), `lan` (`0.0.0.0`), `tailnet` (solo IP de Tailscale) o `custom`. -- **Alias heredados de bind**: usa valores de modo bind en `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), no alias de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Nota de Docker**: el bind predeterminado `loopback` escucha en `127.0.0.1` dentro del contenedor. Con redes bridge de Docker (`-p 18789:18789`), el tráfico llega por `eth0`, así que el gateway no es accesible. Usa `--network host`, o establece `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) para escuchar en todas las interfaces. -- **Auth**: requerido de forma predeterminada. Los binds no loopback requieren autenticación del gateway. En la práctica eso significa un token/contraseña compartidos o un proxy inverso con reconocimiento de identidad con `gateway.auth.mode: "trusted-proxy"`. El asistente de onboarding genera un token por defecto. -- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados (incluidos SecretRefs), establece `gateway.auth.mode` explícitamente en `token` o `password`. El inicio y los flujos de instalación/reparación del servicio fallan cuando ambos están configurados y `mode` no está definido. -- `gateway.auth.mode: "none"`: modo explícito sin autenticación. Úsalo solo para configuraciones locales de loopback de confianza; intencionalmente no se ofrece en los prompts de onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega la autenticación a un proxy inverso con reconocimiento de identidad y confía en los encabezados de identidad de `gateway.trustedProxies` (consulta [Auth de proxy de confianza](/es/gateway/trusted-proxy-auth)). Este modo espera un origen de proxy **no loopback**; los proxies inversos loopback en el mismo host no cumplen con la autenticación trusted-proxy. -- `gateway.auth.allowTailscale`: cuando es `true`, los encabezados de identidad de Tailscale Serve pueden satisfacer la autenticación de Control UI/WebSocket (verificados mediante `tailscale whois`). Los endpoints de la API HTTP **no** usan esa autenticación por encabezado de Tailscale; siguen el modo normal de autenticación HTTP del gateway. Este flujo sin token asume que el host del gateway es de confianza. Su valor predeterminado es `true` cuando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitador opcional de fallos de autenticación. Se aplica por IP de cliente y por alcance de autenticación (se registran por separado el secreto compartido y el token de dispositivo). Los intentos bloqueados devuelven `429` + `Retry-After`. - - En la ruta asíncrona de Control UI de Tailscale Serve, los intentos fallidos del mismo `{scope, clientIp}` se serializan antes de escribir el fallo. Por lo tanto, intentos incorrectos simultáneos del mismo cliente pueden activar el limitador en la segunda solicitud en lugar de dejar que ambas compitan como simples discrepancias. - - `gateway.auth.rateLimit.exemptLoopback` usa `true` de forma predeterminada; establécelo en `false` cuando quieras intencionalmente limitar también el tráfico localhost (para configuraciones de prueba o implementaciones estrictas con proxy). -- Los intentos de autenticación WS con origen en navegador siempre se limitan con la exención de loopback desactivada (defensa en profundidad contra fuerza bruta de localhost basada en navegador). -- En loopback, esos bloqueos con origen en navegador se aíslan por valor `Origin` - normalizado, de modo que los fallos repetidos desde un origen localhost no - bloqueen automáticamente un origen distinto. +- **Alias heredados de bind**: use valores de modo bind en `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), no alias de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Nota sobre Docker**: el bind predeterminado `loopback` escucha en `127.0.0.1` dentro del contenedor. Con la red bridge de Docker (`-p 18789:18789`), el tráfico llega a `eth0`, por lo que el gateway queda inaccesible. Use `--network host`, o establezca `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) para escuchar en todas las interfaces. +- **Auth**: requerida de forma predeterminada. Los binds que no son loopback requieren autenticación del gateway. En la práctica, eso significa un token/contraseña compartido o un proxy inverso con reconocimiento de identidad con `gateway.auth.mode: "trusted-proxy"`. El asistente de onboarding genera un token de forma predeterminada. +- Si `gateway.auth.token` y `gateway.auth.password` están configurados ambos (incluidos SecretRefs), establezca `gateway.auth.mode` explícitamente como `token` o `password`. Los flujos de inicio e instalación/reparación del servicio fallan cuando ambos están configurados y `mode` no está establecido. +- `gateway.auth.mode: "none"`: modo explícito sin autenticación. Úselo solo para configuraciones confiables de local loopback; intencionalmente no se ofrece en los prompts de onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega la autenticación a un proxy inverso con reconocimiento de identidad y confía en los encabezados de identidad de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/es/gateway/trusted-proxy-auth)). Este modo espera una fuente de proxy **que no sea loopback**; los proxies inversos loopback en el mismo host no cumplen la autenticación trusted-proxy. +- `gateway.auth.allowTailscale`: cuando es `true`, los encabezados de identidad de Tailscale Serve pueden satisfacer la autenticación de Control UI/WebSocket (verificado mediante `tailscale whois`). Los endpoints de la API HTTP **no** usan esa autenticación por encabezado de Tailscale; siguen el modo normal de autenticación HTTP del gateway. Este flujo sin token asume que el host del gateway es confiable. Usa `true` como predeterminado cuando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitador opcional de autenticaciones fallidas. Se aplica por IP de cliente y por ámbito de autenticación (se hace seguimiento por separado de secreto compartido y token de dispositivo). Los intentos bloqueados devuelven `429` + `Retry-After`. + - En la ruta asíncrona de Control UI de Tailscale Serve, los intentos fallidos para el mismo `{scope, clientIp}` se serializan antes de registrar el fallo. Por lo tanto, intentos erróneos concurrentes del mismo cliente pueden activar el limitador en la segunda solicitud en lugar de que ambos pasen compitiendo como simples discrepancias. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` de forma predeterminada; establézcalo en `false` cuando intencionalmente quiera limitar también el tráfico localhost (para entornos de prueba o despliegues estrictos con proxy). +- Los intentos de autenticación WS con origen de navegador siempre se limitan con la exención de loopback desactivada (defensa en profundidad contra fuerza bruta de localhost basada en navegador). +- En loopback, esos bloqueos por origen de navegador se aíslan por valor + `Origin` normalizado, de modo que fallos repetidos desde un origen localhost no + bloquean automáticamente un origen distinto. - `tailscale.mode`: `serve` (solo tailnet, bind loopback) o `funnel` (público, requiere autenticación). -- `controlUi.allowedOrigins`: lista explícita de orígenes de navegador permitidos para conexiones WebSocket del Gateway. Requerida cuando se esperan clientes de navegador desde orígenes no loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo peligroso que habilita el respaldo de origen por encabezado Host para implementaciones que dependen intencionalmente de la política de origen basada en Host. +- `controlUi.allowedOrigins`: lista explícita de orígenes de navegador permitidos para conexiones WebSocket a Gateway. Requerida cuando se esperan clientes de navegador desde orígenes que no son loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo peligroso que habilita el respaldo de origen por encabezado Host para despliegues que dependen intencionalmente de la política de origen basada en Host. - `remote.transport`: `ssh` (predeterminado) o `direct` (ws/wss). Para `direct`, `remote.url` debe ser `ws://` o `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: sobrescritura de emergencia del lado del cliente que permite `ws://` en texto sin cifrar hacia IP de red privada de confianza; el valor predeterminado sigue siendo solo loopback para texto sin cifrar. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: sobrescritura de emergencia del lado del cliente que permite `ws://` en texto plano hacia IP de red privada confiables; el valor predeterminado sigue siendo solo loopback para texto plano. - `gateway.remote.token` / `.password` son campos de credenciales del cliente remoto. No configuran por sí mismos la autenticación del gateway. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para el relay APNs externo usado por las compilaciones oficiales/TestFlight de iOS después de que publiquen registros respaldados por relay en el gateway. Esta URL debe coincidir con la URL del relay compilada en la build de iOS. -- `gateway.push.apns.relay.timeoutMs`: tiempo de espera en milisegundos para envíos del gateway al relay. Predeterminado: `10000`. -- Los registros respaldados por relay se delegan a una identidad específica del gateway. La app iOS emparejada obtiene `gateway.identity.get`, incluye esa identidad en el registro del relay y reenvía al gateway un permiso de envío con alcance del registro. Otro gateway no puede reutilizar ese registro almacenado. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base del relay APNs externo usado por las compilaciones oficiales/TestFlight de iOS después de publicar registros respaldados por relay en el gateway. Esta URL debe coincidir con la URL de relay compilada en la build de iOS. +- `gateway.push.apns.relay.timeoutMs`: tiempo de espera en milisegundos para el envío del gateway al relay. Predeterminado: `10000`. +- Los registros respaldados por relay se delegan a una identidad específica de gateway. La app de iOS vinculada obtiene `gateway.identity.get`, incluye esa identidad en el registro del relay y reenvía un permiso de envío con alcance del registro al gateway. Otro gateway no puede reutilizar ese registro almacenado. - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: sobrescrituras temporales por entorno para la configuración del relay anterior. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo para desarrollo para URLs loopback HTTP del relay. Las URLs de relay de producción deben seguir usando HTTPS. -- `gateway.channelHealthCheckMinutes`: intervalo del monitor de salud de canales en minutos. Establece `0` para desactivar globalmente los reinicios del monitor de salud. Predeterminado: `5`. -- `gateway.channelStaleEventThresholdMinutes`: umbral de socket obsoleto en minutos. Mantén este valor mayor o igual que `gateway.channelHealthCheckMinutes`. Predeterminado: `30`. -- `gateway.channelMaxRestartsPerHour`: máximo de reinicios del monitor de salud por canal/cuenta dentro de una hora móvil. Predeterminado: `10`. -- `channels..healthMonitor.enabled`: opt-out por canal de los reinicios del monitor de salud manteniendo habilitado el monitor global. -- `channels..accounts..healthMonitor.enabled`: sobrescritura por cuenta para canales con múltiples cuentas. Cuando se establece, tiene prioridad sobre la sobrescritura a nivel de canal. -- Las rutas de llamada del gateway local pueden usar `gateway.remote.*` como respaldo solo cuando `gateway.auth.*` no está definido. -- Si `gateway.auth.token` / `gateway.auth.password` están configurados explícitamente mediante SecretRef y no se resuelven, la resolución falla en modo cerrado (sin enmascaramiento por respaldo remoto). -- `trustedProxies`: IP de proxies inversos que terminan TLS o inyectan encabezados de cliente reenviado. Lista solo proxies que controles. Las entradas loopback siguen siendo válidas para configuraciones de detección local/proxy en el mismo host (por ejemplo Tailscale Serve o un proxy inverso local), pero **no** hacen que las solicitudes loopback sean elegibles para `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: cuando es `true`, el gateway acepta `X-Real-IP` si falta `X-Forwarded-For`. Predeterminado `false` para comportamiento de fallo cerrado. -- `gateway.tools.deny`: nombres adicionales de herramientas bloqueados para HTTP `POST /tools/invoke` (amplía la lista predeterminada de denegación). +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape solo para desarrollo para URLs de relay HTTP en loopback. Las URLs de relay de producción deben permanecer en HTTPS. +- `gateway.channelHealthCheckMinutes`: intervalo del monitor de estado del canal en minutos. Establezca `0` para desactivar globalmente los reinicios del monitor de estado. Predeterminado: `5`. +- `gateway.channelStaleEventThresholdMinutes`: umbral de socket obsoleto en minutos. Manténgalo mayor o igual que `gateway.channelHealthCheckMinutes`. Predeterminado: `30`. +- `gateway.channelMaxRestartsPerHour`: máximo de reinicios del monitor de estado por canal/cuenta en una hora móvil. Predeterminado: `10`. +- `channels..healthMonitor.enabled`: exclusión por canal para reinicios del monitor de estado, manteniendo habilitado el monitor global. +- `channels..accounts..healthMonitor.enabled`: sobrescritura por cuenta para canales con varias cuentas. Cuando se establece, tiene prioridad sobre la sobrescritura a nivel de canal. +- Las rutas de llamada del gateway local pueden usar `gateway.remote.*` como respaldo solo cuando `gateway.auth.*` no está establecido. +- Si `gateway.auth.token` / `gateway.auth.password` está configurado explícitamente mediante SecretRef y no se resuelve, la resolución falla de forma cerrada (sin respaldo remoto que oculte el fallo). +- `trustedProxies`: IP de proxies inversos que terminan TLS o insertan encabezados de cliente reenviado. Enumere solo proxies que controle. Las entradas loopback siguen siendo válidas para configuraciones de proxy en el mismo host/detección local (por ejemplo Tailscale Serve o un proxy inverso local), pero **no** hacen que las solicitudes loopback sean aptas para `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: cuando es `true`, el gateway acepta `X-Real-IP` si falta `X-Forwarded-For`. Predeterminado `false` para comportamiento cerrado por defecto. +- `gateway.tools.deny`: nombres adicionales de herramientas bloqueadas para HTTP `POST /tools/invoke` (amplía la lista predeterminada de denegación). - `gateway.tools.allow`: elimina nombres de herramientas de la lista predeterminada de denegación HTTP. ### Endpoints compatibles con OpenAI -- Chat Completions: desactivado de forma predeterminada. Habilítalo con `gateway.http.endpoints.chatCompletions.enabled: true`. -- API de Responses: `gateway.http.endpoints.responses.enabled`. +- Chat Completions: desactivado de forma predeterminada. Habilítelo con `gateway.http.endpoints.chatCompletions.enabled: true`. +- API Responses: `gateway.http.endpoints.responses.enabled`. - Endurecimiento de entrada por URL en Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Las listas de permitidos vacías se tratan como no definidas; usa `gateway.http.endpoints.responses.files.allowUrl=false` + Las listas de permitidos vacías se tratan como no establecidas; use `gateway.http.endpoints.responses.files.allowUrl=false` y/o `gateway.http.endpoints.responses.images.allowUrl=false` para desactivar la obtención por URL. -- Encabezado opcional de endurecimiento de respuesta: - - `gateway.http.securityHeaders.strictTransportSecurity` (establécelo solo para orígenes HTTPS que controles; consulta [Auth de proxy de confianza](/es/gateway/trusted-proxy-auth#tls-termination-and-hsts)) +- Encabezado opcional de endurecimiento de respuestas: + - `gateway.http.securityHeaders.strictTransportSecurity` (establézcalo solo para orígenes HTTPS que controle; consulte [Trusted Proxy Auth](/es/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Aislamiento multiinstancia +### Aislamiento de varias instancias -Ejecuta varios gateways en un mismo host con puertos y directorios de estado únicos: +Ejecute varios gateways en un host con puertos y directorios de estado únicos: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3120,9 +3139,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Flags de conveniencia: `--dev` (usa `~/.openclaw-dev` + puerto `19001`), `--profile ` (usa `~/.openclaw-`). +Indicadores de conveniencia: `--dev` (usa `~/.openclaw-dev` + puerto `19001`), `--profile ` (usa `~/.openclaw-`). -Consulta [Múltiples Gateways](/es/gateway/multiple-gateways). +Consulte [Multiple Gateways](/es/gateway/multiple-gateways). ### `gateway.tls` @@ -3141,10 +3160,10 @@ Consulta [Múltiples Gateways](/es/gateway/multiple-gateways). ``` - `enabled`: habilita la terminación TLS en el listener del gateway (HTTPS/WSS) (predeterminado: `false`). -- `autoGenerate`: genera automáticamente un par local autocertificado de cert/key cuando no hay archivos explícitos configurados; solo para uso local/dev. -- `certPath`: ruta del sistema de archivos al archivo de certificado TLS. -- `keyPath`: ruta del sistema de archivos al archivo de clave privada TLS; mantén permisos restringidos. -- `caPath`: ruta opcional al bundle de CA para verificación de clientes o cadenas de confianza personalizadas. +- `autoGenerate`: genera automáticamente un par local certificado/clave autofirmado cuando no se configuran archivos explícitos; solo para uso local/desarrollo. +- `certPath`: ruta del sistema de archivos al archivo del certificado TLS. +- `keyPath`: ruta del sistema de archivos a la clave privada TLS; manténgala con permisos restringidos. +- `caPath`: ruta opcional al paquete de CA para verificación de clientes o cadenas de confianza personalizadas. ### `gateway.reload` @@ -3160,13 +3179,13 @@ Consulta [Múltiples Gateways](/es/gateway/multiple-gateways). } ``` -- `mode`: controla cómo se aplican las ediciones de configuración en runtime. +- `mode`: controla cómo se aplican en runtime las ediciones de configuración. - `"off"`: ignora las ediciones en vivo; los cambios requieren un reinicio explícito. - - `"restart"`: siempre reinicia el proceso del gateway ante cambios de configuración. - - `"hot"`: aplica los cambios dentro del proceso sin reiniciar. - - `"hybrid"` (predeterminado): primero intenta hot reload; recurre a reinicio si es necesario. + - `"restart"`: siempre reinicia el proceso del gateway cuando cambia la configuración. + - `"hot"`: aplica cambios dentro del proceso sin reiniciar. + - `"hybrid"` (predeterminado): intenta primero una recarga en caliente; recurre al reinicio si es necesario. - `debounceMs`: ventana de debounce en ms antes de aplicar cambios de configuración (entero no negativo). -- `deferralTimeoutMs`: tiempo máximo en ms para esperar operaciones en curso antes de forzar un reinicio (predeterminado: `300000` = 5 minutos). +- `deferralTimeoutMs`: tiempo máximo en ms para esperar a que finalicen operaciones en curso antes de forzar un reinicio (predeterminado: `300000` = 5 minutos). --- @@ -3203,37 +3222,37 @@ Consulta [Múltiples Gateways](/es/gateway/multiple-gateways). } ``` -Auth: `Authorization: Bearer ` o `x-openclaw-token: `. -Los tokens de hooks en query string se rechazan. +Autenticación: `Authorization: Bearer ` o `x-openclaw-token: `. +Los tokens de hooks en la cadena de consulta se rechazan. Notas de validación y seguridad: - `hooks.enabled=true` requiere un `hooks.token` no vacío. -- `hooks.token` debe ser **distinto** de `gateway.auth.token`; se rechaza reutilizar el token del Gateway. -- `hooks.path` no puede ser `/`; usa una subruta dedicada como `/hooks`. -- Si `hooks.allowRequestSessionKey=true`, restringe `hooks.allowedSessionKeyPrefixes` (por ejemplo `["hook:"]`). +- `hooks.token` debe ser **distinto** de `gateway.auth.token`; se rechaza reutilizar el token de Gateway. +- `hooks.path` no puede ser `/`; use una subruta dedicada como `/hooks`. +- Si `hooks.allowRequestSessionKey=true`, restrinja `hooks.allowedSessionKeyPrefixes` (por ejemplo `["hook:"]`). **Endpoints:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` de la carga útil de la solicitud solo se acepta cuando `hooks.allowRequestSessionKey=true` (predeterminado: `false`). -- `POST /hooks/` → se resuelve mediante `hooks.mappings` + - `sessionKey` del cuerpo de la solicitud se acepta solo cuando `hooks.allowRequestSessionKey=true` (predeterminado: `false`). +- `POST /hooks/` → resuelto mediante `hooks.mappings` - + - `match.path` coincide con la subruta después de `/hooks` (por ejemplo `/hooks/gmail` → `gmail`). - `match.source` coincide con un campo de la carga útil para rutas genéricas. - Las plantillas como `{{messages[0].subject}}` leen desde la carga útil. - `transform` puede apuntar a un módulo JS/TS que devuelve una acción de hook. - - `transform.module` debe ser una ruta relativa y permanecer dentro de `hooks.transformsDir` (se rechazan rutas absolutas y recorridos de directorio). -- `agentId` enruta a un agente específico; los IDs desconocidos vuelven al predeterminado. + - `transform.module` debe ser una ruta relativa y permanecer dentro de `hooks.transformsDir` (se rechazan rutas absolutas y recorridos de directorios). +- `agentId` enruta a un agente específico; los IDs desconocidos recurren al predeterminado. - `allowedAgentIds`: restringe el enrutamiento explícito (`*` u omitido = permitir todos, `[]` = denegar todos). -- `defaultSessionKey`: clave de sesión fija opcional para ejecuciones del agente de hooks sin `sessionKey` explícito. +- `defaultSessionKey`: clave de sesión fija opcional para ejecuciones de agente por hook sin `sessionKey` explícito. - `allowRequestSessionKey`: permite que los llamadores de `/hooks/agent` establezcan `sessionKey` (predeterminado: `false`). -- `allowedSessionKeyPrefixes`: lista opcional de prefijos permitidos para valores explícitos de `sessionKey` (solicitud + mapeo), por ejemplo `["hook:"]`. -- `deliver: true` envía la respuesta final a un canal; `channel` usa `last` por defecto. -- `model` sobrescribe el LLM para esta ejecución de hook (debe estar permitido si el catálogo de modelos está configurado). +- `allowedSessionKeyPrefixes`: lista opcional de prefijos permitidos para valores explícitos de `sessionKey` (solicitud + mapping), por ejemplo `["hook:"]`. +- `deliver: true` envía la respuesta final a un canal; `channel` usa `last` como predeterminado. +- `model` sobrescribe el LLM para esta ejecución del hook (debe estar permitido si el catálogo de modelos está configurado). @@ -3260,8 +3279,8 @@ Notas de validación y seguridad: } ``` -- El Gateway inicia automáticamente `gog gmail watch serve` al arrancar cuando está configurado. Establece `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desactivarlo. -- No ejecutes un `gog gmail watch serve` separado junto al Gateway. +- Gateway inicia automáticamente `gog gmail watch serve` al arrancar cuando está configurado. Establezca `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desactivarlo. +- No ejecute un `gog gmail watch serve` separado junto con el Gateway. --- @@ -3277,18 +3296,18 @@ Notas de validación y seguridad: } ``` -- Sirve HTML/CSS/JS editables por el agente y A2UI por HTTP bajo el puerto del Gateway: +- Sirve HTML/CSS/JS editable por el agente y A2UI por HTTP bajo el puerto del Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Solo local: mantén `gateway.bind: "loopback"` (predeterminado). -- En binds no loopback: las rutas de canvas requieren autenticación del Gateway (token/password/trusted-proxy), igual que las demás superficies HTTP del Gateway. -- Los Node WebViews normalmente no envían encabezados de autenticación; después de que un Node se empareja y conecta, el Gateway anuncia URL de capacidad con alcance de nodo para acceso a canvas/A2UI. -- Las URL de capacidad están vinculadas a la sesión WS activa del nodo y caducan rápidamente. No se usa respaldo basado en IP. -- Inyecta el cliente de live reload en el HTML servido. +- Solo local: mantenga `gateway.bind: "loopback"` (predeterminado). +- Binds que no son loopback: las rutas de canvas requieren autenticación de Gateway (token/password/trusted-proxy), igual que otras superficies HTTP de Gateway. +- Los WebViews de Node normalmente no envían encabezados de autenticación; después de que un node se empareja y conecta, Gateway anuncia URLs de capacidad con ámbito del node para acceso a canvas/A2UI. +- Las URLs de capacidad están vinculadas a la sesión WS activa del node y caducan rápidamente. No se usa respaldo basado en IP. +- Inyecta el cliente de recarga en vivo en el HTML servido. - Crea automáticamente un `index.html` inicial cuando está vacío. - También sirve A2UI en `/__openclaw__/a2ui/`. - Los cambios requieren reiniciar el gateway. -- Desactiva live reload para directorios grandes o errores `EMFILE`. +- Desactive la recarga en vivo para directorios grandes o errores `EMFILE`. --- @@ -3308,9 +3327,9 @@ Notas de validación y seguridad: - `minimal` (predeterminado): omite `cliPath` + `sshPort` de los registros TXT. - `full`: incluye `cliPath` + `sshPort`. -- El nombre de host usa `openclaw` por defecto. Sobrescríbelo con `OPENCLAW_MDNS_HOSTNAME`. +- El nombre de host usa `openclaw` como predeterminado. Sobrescríbalo con `OPENCLAW_MDNS_HOSTNAME`. -### Wide-area (DNS-SD) +### Área amplia (DNS-SD) ```json5 { @@ -3320,7 +3339,7 @@ Notas de validación y seguridad: } ``` -Escribe una zona DNS-SD unicast en `~/.openclaw/dns/`. Para descubrimiento entre redes, combínalo con un servidor DNS (se recomienda CoreDNS) + split DNS de Tailscale. +Escribe una zona DNS-SD unicast en `~/.openclaw/dns/`. Para descubrimiento entre redes, combínelo con un servidor DNS (se recomienda CoreDNS) + DNS dividido de Tailscale. Configuración: `openclaw dns setup --apply`. @@ -3328,7 +3347,7 @@ Configuración: `openclaw dns setup --apply`. ## Entorno -### `env` (variables de entorno en línea) +### `env` (variables de entorno integradas) ```json5 { @@ -3345,14 +3364,14 @@ Configuración: `openclaw dns setup --apply`. } ``` -- Las variables de entorno en línea solo se aplican si al entorno del proceso le falta la clave. +- Las variables de entorno integradas solo se aplican si al entorno del proceso le falta la clave. - Archivos `.env`: `.env` del CWD + `~/.openclaw/.env` (ninguno sobrescribe variables existentes). -- `shellEnv`: importa claves esperadas faltantes desde el perfil de tu shell de inicio de sesión. -- Consulta [Entorno](/es/help/environment) para la precedencia completa. +- `shellEnv`: importa claves esperadas faltantes desde el perfil de su shell de inicio de sesión. +- Consulte [Environment](/es/help/environment) para la precedencia completa. ### Sustitución de variables de entorno -Haz referencia a variables de entorno en cualquier cadena de configuración con `${VAR_NAME}`: +Haga referencia a variables de entorno en cualquier cadena de configuración con `${VAR_NAME}`: ```json5 { @@ -3362,20 +3381,20 @@ Haz referencia a variables de entorno en cualquier cadena de configuración con } ``` -- Solo coinciden nombres en mayúsculas: `[A-Z_][A-Z0-9_]*`. +- Solo se reconocen nombres en mayúsculas: `[A-Z_][A-Z0-9_]*`. - Las variables faltantes/vacías generan un error al cargar la configuración. -- Escapa con `$${VAR}` para un `${VAR}` literal. +- Escape con `$${VAR}` para un `${VAR}` literal. - Funciona con `$include`. --- ## Secretos -Las refs secretas son aditivas: los valores en texto sin formato siguen funcionando. +Las referencias a secretos son aditivas: los valores en texto sin formato siguen funcionando. ### `SecretRef` -Usa una única forma de objeto: +Use una sola forma de objeto: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3384,16 +3403,16 @@ Usa una única forma de objeto: Validación: - patrón de `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- patrón de id de `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id: puntero JSON absoluto (por ejemplo `"/providers/openai/apiKey"`) -- patrón de id de `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- Los ids de `source: "exec"` no deben contener segmentos de ruta delimitados por `/` como `.` o `..` (por ejemplo se rechaza `a/../b`) +- patrón de id para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- id para `source: "file"`: puntero JSON absoluto (por ejemplo `"/providers/openai/apiKey"`) +- patrón de id para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- los ids de `source: "exec"` no deben contener segmentos de ruta delimitados por `/` como `.` o `..` (por ejemplo `a/../b` se rechaza) -### Superficie de credenciales compatible +### Superficie de credenciales admitida -- Matriz canónica: [Superficie de credenciales SecretRef](/es/reference/secretref-credential-surface) -- `secrets apply` apunta a rutas de credenciales compatibles de `openclaw.json`. -- Las refs de `auth-profiles.json` se incluyen en la resolución en runtime y en la cobertura de auditoría. +- Matriz canónica: [SecretRef Credential Surface](/es/reference/secretref-credential-surface) +- `secrets apply` apunta a rutas de credenciales compatibles en `openclaw.json`. +- Las referencias de `auth-profiles.json` se incluyen en la resolución en runtime y en la cobertura de auditoría. ### Configuración de proveedores de secretos @@ -3425,13 +3444,13 @@ Validación: Notas: -- El proveedor `file` admite `mode: "json"` y `mode: "singleValue"` (`id` debe ser `"value"` en modo singleValue). +- El proveedor `file` admite `mode: "json"` y `mode: "singleValue"` (en modo singleValue, `id` debe ser `"value"`). - El proveedor `exec` requiere una ruta `command` absoluta y usa cargas útiles de protocolo en stdin/stdout. -- De forma predeterminada, se rechazan rutas de comandos con symlink. Establece `allowSymlinkCommand: true` para permitir rutas con symlink mientras se valida la ruta del destino resuelto. -- Si `trustedDirs` está configurado, la comprobación de directorio de confianza se aplica a la ruta del destino resuelto. -- El entorno hijo de `exec` es mínimo de forma predeterminada; pasa explícitamente las variables necesarias con `passEnv`. -- Las refs secretas se resuelven en el momento de activación en una instantánea en memoria, y luego las rutas de solicitud solo leen esa instantánea. -- El filtrado de superficie activa se aplica durante la activación: las refs no resueltas en superficies habilitadas hacen fallar el inicio/recarga, mientras que las superficies inactivas se omiten con diagnósticos. +- De forma predeterminada, se rechazan rutas de comandos mediante enlaces simbólicos. Establezca `allowSymlinkCommand: true` para permitir rutas de symlink mientras se valida la ruta resuelta de destino. +- Si se configura `trustedDirs`, la comprobación de directorios de confianza se aplica a la ruta resuelta de destino. +- El entorno hijo de `exec` es mínimo de forma predeterminada; pase las variables necesarias explícitamente con `passEnv`. +- Las referencias de secretos se resuelven en el momento de la activación en una instantánea en memoria y luego las rutas de solicitud solo leen esa instantánea. +- El filtrado de superficie activa se aplica durante la activación: las referencias no resueltas en superficies habilitadas hacen fallar el inicio/la recarga, mientras que las superficies inactivas se omiten con diagnósticos. --- @@ -3454,12 +3473,12 @@ Notas: ``` - Los perfiles por agente se almacenan en `/auth-profiles.json`. -- `auth-profiles.json` admite refs a nivel de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credenciales estáticas. +- `auth-profiles.json` admite referencias a nivel de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credenciales estáticas. - Los perfiles en modo OAuth (`auth.profiles..mode = "oauth"`) no admiten credenciales de perfil de autenticación respaldadas por SecretRef. -- Las credenciales estáticas en runtime provienen de instantáneas resueltas en memoria; las entradas heredadas estáticas de `auth.json` se depuran cuando se detectan. -- Importaciones heredadas de OAuth desde `~/.openclaw/credentials/oauth.json`. -- Consulta [OAuth](/es/concepts/oauth). -- Comportamiento del runtime de secretos y herramientas `audit/configure/apply`: [Gestión de secretos](/es/gateway/secrets). +- Las credenciales estáticas de runtime provienen de instantáneas resueltas en memoria; las entradas estáticas heredadas de `auth.json` se depuran cuando se descubren. +- Importaciones OAuth heredadas desde `~/.openclaw/credentials/oauth.json`. +- Consulte [OAuth](/es/concepts/oauth). +- Comportamiento del runtime de secretos y herramientas `audit/configure/apply`: [Secrets Management](/es/gateway/secrets). ### `auth.cooldowns` @@ -3481,20 +3500,21 @@ Notas: } ``` -- `billingBackoffHours`: backoff base en horas cuando un perfil falla debido a errores reales - de facturación/crédito insuficiente (predeterminado: `5`). El texto explícito de facturación - aún puede terminar aquí incluso en respuestas `401`/`403`, pero los matchers de texto - específicos del proveedor siguen limitados al proveedor que les corresponde (por ejemplo OpenRouter - `Key limit exceeded`). Los mensajes reintentables de uso por ventana `402` HTTP o de - límite de gasto de organización/workspace permanecen en la ruta `rate_limit`. -- `billingBackoffHoursByProvider`: sobrescrituras opcionales por proveedor para horas de backoff de facturación. -- `billingMaxHours`: límite en horas para el crecimiento exponencial del backoff de facturación (predeterminado: `24`). -- `authPermanentBackoffMinutes`: backoff base en minutos para fallos `auth_permanent` de alta confianza (predeterminado: `10`). -- `authPermanentMaxMinutes`: límite en minutos para el crecimiento del backoff de `auth_permanent` (predeterminado: `60`). -- `failureWindowHours`: ventana móvil en horas usada para contadores de backoff (predeterminado: `24`). -- `overloadedProfileRotations`: máximo de rotaciones de auth-profile del mismo proveedor para errores de sobrecarga antes de cambiar al modelo de respaldo (predeterminado: `1`). Las formas de proveedor ocupado como `ModelNotReadyException` llegan aquí. +- `billingBackoffHours`: retroceso base en horas cuando un perfil falla por errores reales de + facturación/crédito insuficiente (predeterminado: `5`). El texto explícito de facturación + aún puede llegar aquí incluso en respuestas `401`/`403`, pero los + comparadores de texto específicos del proveedor siguen limitados al proveedor que los posee (por ejemplo OpenRouter + `Key limit exceeded`). Los mensajes reintentables `402` de ventana de uso HTTP o + de límite de gasto de organización/workspace permanecen en la ruta `rate_limit` + en su lugar. +- `billingBackoffHoursByProvider`: sobrescrituras opcionales por proveedor para las horas de retroceso de facturación. +- `billingMaxHours`: límite en horas para el crecimiento exponencial del retroceso de facturación (predeterminado: `24`). +- `authPermanentBackoffMinutes`: retroceso base en minutos para fallos `auth_permanent` de alta confianza (predeterminado: `10`). +- `authPermanentMaxMinutes`: límite en minutos para el crecimiento del retroceso de `auth_permanent` (predeterminado: `60`). +- `failureWindowHours`: ventana móvil en horas usada para contadores de retroceso (predeterminado: `24`). +- `overloadedProfileRotations`: máximo de rotaciones de perfil de autenticación del mismo proveedor para errores por sobrecarga antes de cambiar al modelo de respaldo (predeterminado: `1`). Las formas de proveedor ocupado como `ModelNotReadyException` entran aquí. - `overloadedBackoffMs`: retraso fijo antes de reintentar una rotación de proveedor/perfil sobrecargado (predeterminado: `0`). -- `rateLimitedProfileRotations`: máximo de rotaciones de auth-profile del mismo proveedor para errores de límite de tasa antes de cambiar al modelo de respaldo (predeterminado: `1`). Ese grupo de límites de tasa incluye texto con forma de proveedor como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` y `resource exhausted`. +- `rateLimitedProfileRotations`: máximo de rotaciones de perfil de autenticación del mismo proveedor para errores de límite de velocidad antes de cambiar al modelo de respaldo (predeterminado: `1`). Ese grupo de límite de velocidad incluye texto con forma de proveedor como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` y `resource exhausted`. --- @@ -3514,9 +3534,9 @@ Notas: ``` - Archivo de registro predeterminado: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Establece `logging.file` para una ruta estable. -- `consoleLevel` sube a `debug` con `--verbose`. -- `maxFileBytes`: tamaño máximo del archivo de registro en bytes antes de que se supriman escrituras (entero positivo; predeterminado: `524288000` = 500 MB). Usa rotación de logs externa para implementaciones de producción. +- Establezca `logging.file` para una ruta estable. +- `consoleLevel` sube a `debug` cuando se usa `--verbose`. +- `maxFileBytes`: tamaño máximo del archivo de registro en bytes antes de que se supriman las escrituras (entero positivo; predeterminado: `524288000` = 500 MB). Use rotación de registros externa para despliegues de producción. --- @@ -3554,19 +3574,19 @@ Notas: ``` - `enabled`: interruptor maestro para la salida de instrumentación (predeterminado: `true`). -- `flags`: arreglo de cadenas de flags que habilitan salida de logs dirigida (admite comodines como `"telegram.*"` o `"*"`). +- `flags`: arreglo de cadenas de indicadores que habilitan salida de registro dirigida (admite comodines como `"telegram.*"` o `"*"`). - `stuckSessionWarnMs`: umbral de antigüedad en ms para emitir advertencias de sesión atascada mientras una sesión permanece en estado de procesamiento. - `otel.enabled`: habilita la canalización de exportación de OpenTelemetry (predeterminado: `false`). -- `otel.endpoint`: URL del recolector para exportación OTel. +- `otel.endpoint`: URL del colector para exportación OTel. - `otel.protocol`: `"http/protobuf"` (predeterminado) o `"grpc"`. -- `otel.headers`: encabezados de metadatos HTTP/gRPC extra enviados con las solicitudes de exportación OTel. +- `otel.headers`: encabezados de metadatos HTTP/gRPC adicionales enviados con las solicitudes de exportación OTel. - `otel.serviceName`: nombre del servicio para atributos de recurso. -- `otel.traces` / `otel.metrics` / `otel.logs`: habilitan exportación de trazas, métricas o logs. +- `otel.traces` / `otel.metrics` / `otel.logs`: habilita la exportación de trazas, métricas o registros. - `otel.sampleRate`: tasa de muestreo de trazas `0`–`1`. - `otel.flushIntervalMs`: intervalo periódico de vaciado de telemetría en ms. -- `cacheTrace.enabled`: registra instantáneas de rastreo de caché para ejecuciones incrustadas (predeterminado: `false`). -- `cacheTrace.filePath`: ruta de salida para JSONL de rastreo de caché (predeterminado: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlan qué se incluye en la salida del rastreo de caché (todos usan `true` por defecto). +- `cacheTrace.enabled`: registra instantáneas de rastreo de caché para ejecuciones integradas (predeterminado: `false`). +- `cacheTrace.filePath`: ruta de salida para el JSONL de rastreo de caché (predeterminado: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlan lo que se incluye en la salida del rastreo de caché (todos usan `true` como predeterminado). --- @@ -3588,12 +3608,12 @@ Notas: } ``` -- `channel`: canal de versión para instalaciones npm/git — `"stable"`, `"beta"` o `"dev"`. +- `channel`: canal de lanzamiento para instalaciones npm/git — `"stable"`, `"beta"` o `"dev"`. - `checkOnStart`: comprueba actualizaciones de npm cuando se inicia el gateway (predeterminado: `true`). -- `auto.enabled`: habilita actualización automática en segundo plano para instalaciones de paquetes (predeterminado: `false`). +- `auto.enabled`: habilita la actualización automática en segundo plano para instalaciones de paquetes (predeterminado: `false`). - `auto.stableDelayHours`: retraso mínimo en horas antes de la aplicación automática del canal estable (predeterminado: `6`; máximo: `168`). - `auto.stableJitterHours`: ventana adicional en horas para escalonar el despliegue del canal estable (predeterminado: `12`; máximo: `168`). -- `auto.betaCheckIntervalHours`: frecuencia en horas de las comprobaciones del canal beta (predeterminado: `1`; máximo: `24`). +- `auto.betaCheckIntervalHours`: con qué frecuencia se ejecutan las comprobaciones del canal beta en horas (predeterminado: `1`; máximo: `24`). --- @@ -3626,22 +3646,22 @@ Notas: } ``` -- `enabled`: puerta global de funciones ACP (predeterminado: `false`). -- `dispatch.enabled`: puerta independiente para el despacho de turnos de sesión ACP (predeterminado: `true`). Establécelo en `false` para mantener disponibles los comandos ACP mientras se bloquea la ejecución. -- `backend`: id predeterminado del backend de runtime ACP (debe coincidir con un plugin de runtime ACP registrado). -- `defaultAgent`: id del agente ACP de respaldo cuando los spawns no especifican un destino explícito. -- `allowedAgents`: lista de permitidos de ids de agentes autorizados para sesiones de runtime ACP; vacío significa sin restricción adicional. +- `enabled`: compuerta global de función de ACP (predeterminado: `false`). +- `dispatch.enabled`: compuerta independiente para el despacho de turnos de sesión ACP (predeterminado: `true`). Establézcala en `false` para mantener disponibles los comandos ACP mientras se bloquea la ejecución. +- `backend`: ID predeterminado del backend de runtime ACP (debe coincidir con un plugin de runtime ACP registrado). +- `defaultAgent`: ID del agente objetivo de ACP de respaldo cuando los spawns no especifican un destino explícito. +- `allowedAgents`: lista de permitidos de IDs de agentes autorizados para sesiones de runtime ACP; vacío significa sin restricción adicional. - `maxConcurrentSessions`: máximo de sesiones ACP activas simultáneamente. - `stream.coalesceIdleMs`: ventana de vaciado por inactividad en ms para texto transmitido. -- `stream.maxChunkChars`: tamaño máximo de fragmento antes de dividir la proyección del bloque transmitido. +- `stream.maxChunkChars`: tamaño máximo del fragmento antes de dividir la proyección del bloque transmitido. - `stream.repeatSuppression`: suprime líneas repetidas de estado/herramienta por turno (predeterminado: `true`). -- `stream.deliveryMode`: `"live"` transmite de forma incremental; `"final_only"` almacena en búfer hasta eventos terminales del turno. +- `stream.deliveryMode`: `"live"` transmite de forma incremental; `"final_only"` almacena en búfer hasta los eventos terminales del turno. - `stream.hiddenBoundarySeparator`: separador antes del texto visible después de eventos ocultos de herramientas (predeterminado: `"paragraph"`). - `stream.maxOutputChars`: máximo de caracteres de salida del asistente proyectados por turno ACP. - `stream.maxSessionUpdateChars`: máximo de caracteres para líneas proyectadas de estado/actualización ACP. -- `stream.tagVisibility`: registro de nombres de etiquetas a sobrescrituras booleanas de visibilidad para eventos transmitidos. +- `stream.tagVisibility`: registro de nombres de etiquetas con sobrescrituras de visibilidad booleanas para eventos transmitidos. - `runtime.ttlMinutes`: TTL de inactividad en minutos para workers de sesión ACP antes de ser elegibles para limpieza. -- `runtime.installCommand`: comando opcional de instalación que se ejecuta al inicializar un entorno de runtime ACP. +- `runtime.installCommand`: comando de instalación opcional para ejecutar al inicializar un entorno de runtime ACP. --- @@ -3659,15 +3679,15 @@ Notas: - `cli.banner.taglineMode` controla el estilo del eslogan del banner: - `"random"` (predeterminado): eslóganes rotativos divertidos/de temporada. - - `"default"`: eslogan neutral fijo (`Todos tus chats, un OpenClaw.`). + - `"default"`: eslogan neutral fijo (`All your chats, one OpenClaw.`). - `"off"`: sin texto de eslogan (el título/versión del banner siguen mostrándose). -- Para ocultar todo el banner (no solo los eslóganes), establece la variable de entorno `OPENCLAW_HIDE_BANNER=1`. +- Para ocultar todo el banner (no solo los eslóganes), establezca la variable de entorno `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Metadatos escritos por flujos guiados de configuración de CLI (`onboard`, `configure`, `doctor`): +Metadatos escritos por los flujos de configuración guiada de CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3685,13 +3705,13 @@ Metadatos escritos por flujos guiados de configuración de CLI (`onboard`, `conf ## Identidad -Consulta los campos de identidad de `agents.list` en [Valores predeterminados del agente](#agent-defaults). +Consulte los campos de identidad de `agents.list` en [Valores predeterminados del agente](#agent-defaults). --- ## Bridge (heredado, eliminado) -Las compilaciones actuales ya no incluyen el bridge TCP. Los Nodes se conectan mediante el WebSocket del Gateway. Las claves `bridge.*` ya no forman parte del esquema de configuración (la validación falla hasta que se eliminen; `openclaw doctor --fix` puede quitar claves desconocidas). +Las compilaciones actuales ya no incluyen el bridge TCP. Los nodes se conectan a través del WebSocket de Gateway. Las claves `bridge.*` ya no forman parte del esquema de configuración (la validación falla hasta que se eliminen; `openclaw doctor --fix` puede quitar claves desconocidas). @@ -3731,11 +3751,11 @@ Las compilaciones actuales ya no incluyen el bridge TCP. Los Nodes se conectan m } ``` -- `sessionRetention`: cuánto tiempo conservar las sesiones completadas de ejecuciones Cron aisladas antes de eliminarlas de `sessions.json`. También controla la limpieza de transcripciones Cron eliminadas archivadas. Predeterminado: `24h`; establece `false` para desactivar. -- `runLog.maxBytes`: tamaño máximo por archivo de log de ejecución (`cron/runs/.jsonl`) antes de la poda. Predeterminado: `2_000_000` bytes. -- `runLog.keepLines`: líneas más recientes conservadas cuando se activa la poda del log de ejecución. Predeterminado: `2000`. -- `webhookToken`: token bearer usado para la entrega POST de Webhook de Cron (`delivery.mode = "webhook"`); si se omite no se envía encabezado de autenticación. -- `webhook`: URL heredada obsoleta de respaldo del Webhook (http/https) usada solo para trabajos almacenados que todavía tienen `notify: true`. +- `sessionRetention`: cuánto tiempo conservar las sesiones completadas de ejecuciones aisladas de Cron antes de podarlas de `sessions.json`. También controla la limpieza de las transcripciones archivadas eliminadas de Cron. Predeterminado: `24h`; establezca `false` para desactivarlo. +- `runLog.maxBytes`: tamaño máximo por archivo de registro de ejecución (`cron/runs/.jsonl`) antes de la poda. Predeterminado: `2_000_000` bytes. +- `runLog.keepLines`: líneas más recientes retenidas cuando se activa la poda del registro de ejecución. Predeterminado: `2000`. +- `webhookToken`: token bearer usado para la entrega POST de Webhook de Cron (`delivery.mode = "webhook"`); si se omite, no se envía encabezado de autenticación. +- `webhook`: URL heredada obsoleta de Webhook de respaldo (http/https) usada solo para trabajos almacenados que aún tienen `notify: true`. ### `cron.retry` @@ -3751,11 +3771,11 @@ Las compilaciones actuales ya no incluyen el bridge TCP. Los Nodes se conectan m } ``` -- `maxAttempts`: número máximo de reintentos para trabajos de una sola vez ante errores transitorios (predeterminado: `3`; rango: `0`–`10`). -- `backoffMs`: arreglo de retrasos de backoff en ms para cada intento de reintento (predeterminado: `[30000, 60000, 300000]`; 1–10 entradas). -- `retryOn`: tipos de error que activan reintentos — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omítelo para reintentar todos los tipos transitorios. +- `maxAttempts`: número máximo de reintentos para trabajos de una sola ejecución en errores transitorios (predeterminado: `3`; rango: `0`–`10`). +- `backoffMs`: arreglo de retrasos de retroceso en ms para cada intento de reintento (predeterminado: `[30000, 60000, 300000]`; 1–10 entradas). +- `retryOn`: tipos de error que activan reintentos: `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omítalo para reintentar todos los tipos transitorios. -Se aplica solo a trabajos Cron de una sola vez. Los trabajos recurrentes usan un manejo de fallos independiente. +Se aplica solo a trabajos Cron de una sola ejecución. Los trabajos recurrentes usan un manejo de errores separado. ### `cron.failureAlert` @@ -3774,10 +3794,10 @@ Se aplica solo a trabajos Cron de una sola vez. Los trabajos recurrentes usan un ``` - `enabled`: habilita alertas de fallo para trabajos Cron (predeterminado: `false`). -- `after`: fallos consecutivos antes de que se dispare una alerta (entero positivo, mín.: `1`). +- `after`: fallos consecutivos antes de que se dispare una alerta (entero positivo, mínimo: `1`). - `cooldownMs`: milisegundos mínimos entre alertas repetidas para el mismo trabajo (entero no negativo). -- `mode`: modo de entrega — `"announce"` envía mediante un mensaje de canal; `"webhook"` publica en el Webhook configurado. -- `accountId`: id opcional de cuenta o canal para limitar el alcance de la entrega de alertas. +- `mode`: modo de entrega: `"announce"` envía mediante un mensaje de canal; `"webhook"` publica en el Webhook configurado. +- `accountId`: ID opcional de cuenta o canal para delimitar la entrega de alertas. ### `cron.failureDestination` @@ -3795,15 +3815,15 @@ Se aplica solo a trabajos Cron de una sola vez. Los trabajos recurrentes usan un ``` - Destino predeterminado para notificaciones de fallo de Cron en todos los trabajos. -- `mode`: `"announce"` o `"webhook"`; usa `"announce"` por defecto cuando existen suficientes datos de destino. +- `mode`: `"announce"` o `"webhook"`; usa `"announce"` como predeterminado cuando existen suficientes datos de destino. - `channel`: sobrescritura de canal para entrega `announce`. `"last"` reutiliza el último canal de entrega conocido. -- `to`: destino explícito de `announce` o URL de Webhook. Obligatorio para modo webhook. +- `to`: destino explícito de `announce` o URL de Webhook. Obligatorio para el modo Webhook. - `accountId`: sobrescritura opcional de cuenta para la entrega. - `delivery.failureDestination` por trabajo sobrescribe este valor predeterminado global. -- Cuando no se establece ningún destino de fallo ni global ni por trabajo, los trabajos que ya entregan mediante `announce` vuelven a ese destino principal de `announce` en caso de fallo. -- `delivery.failureDestination` solo es compatible con trabajos `sessionTarget="isolated"` a menos que el `delivery.mode` principal del trabajo sea `"webhook"`. +- Cuando no se establece ni un destino global ni uno por trabajo, los trabajos que ya entregan mediante `announce` recurren a ese destino primario de `announce` en caso de fallo. +- `delivery.failureDestination` solo es compatible con trabajos `sessionTarget="isolated"` salvo que el `delivery.mode` principal del trabajo sea `"webhook"`. -Consulta [Trabajos Cron](/es/automation/cron-jobs). Las ejecuciones Cron aisladas se registran como [tareas en segundo plano](/es/automation/tasks). +Consulte [Cron Jobs](/es/automation/cron-jobs). Las ejecuciones aisladas de Cron se rastrean como [background tasks](/es/automation/tasks). --- @@ -3811,34 +3831,34 @@ Consulta [Trabajos Cron](/es/automation/cron-jobs). Las ejecuciones Cron aislada Marcadores de posición de plantilla expandidos en `tools.media.models[].args`: -| Variable | Descripción | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Cuerpo completo del mensaje entrante | -| `{{RawBody}}` | Cuerpo sin procesar (sin wrappers de historial/remitente) | -| `{{BodyStripped}}` | Cuerpo con menciones de grupo eliminadas | -| `{{From}}` | Identificador del remitente | -| `{{To}}` | Identificador del destino | -| `{{MessageSid}}` | Id del mensaje del canal | -| `{{SessionId}}` | UUID de la sesión actual | -| `{{IsNewSession}}` | `"true"` cuando se crea una sesión nueva | -| `{{MediaUrl}}` | Pseudo-URL del medio entrante | -| `{{MediaPath}}` | Ruta local del medio | -| `{{MediaType}}` | Tipo de medio (image/audio/document/…) | -| `{{Transcript}}` | Transcripción de audio | -| `{{Prompt}}` | Prompt de medios resuelto para entradas CLI | +| Variable | Descripción | +| ------------------ | ------------------------------------------------ | +| `{{Body}}` | Cuerpo completo del mensaje entrante | +| `{{RawBody}}` | Cuerpo sin procesar (sin envoltorios de historial/remitente) | +| `{{BodyStripped}}` | Cuerpo con menciones grupales eliminadas | +| `{{From}}` | Identificador del remitente | +| `{{To}}` | Identificador del destino | +| `{{MessageSid}}` | ID del mensaje del canal | +| `{{SessionId}}` | UUID de la sesión actual | +| `{{IsNewSession}}` | `"true"` cuando se crea una nueva sesión | +| `{{MediaUrl}}` | Pseudo-URL del medio entrante | +| `{{MediaPath}}` | Ruta local del medio | +| `{{MediaType}}` | Tipo de medio (image/audio/document/…) | +| `{{Transcript}}` | Transcripción de audio | +| `{{Prompt}}` | Prompt de medios resuelto para entradas CLI | | `{{MaxChars}}` | Máximo de caracteres de salida resuelto para entradas CLI | -| `{{ChatType}}` | `"direct"` o `"group"` | -| `{{GroupSubject}}` | Asunto del grupo (mejor esfuerzo) | +| `{{ChatType}}` | `"direct"` o `"group"` | +| `{{GroupSubject}}` | Asunto del grupo (mejor esfuerzo) | | `{{GroupMembers}}` | Vista previa de miembros del grupo (mejor esfuerzo) | | `{{SenderName}}` | Nombre para mostrar del remitente (mejor esfuerzo) | | `{{SenderE164}}` | Número de teléfono del remitente (mejor esfuerzo) | -| `{{Provider}}` | Pista del proveedor (whatsapp, telegram, discord, etc.) | +| `{{Provider}}` | Indicación del proveedor (whatsapp, telegram, discord, etc.) | --- ## Inclusiones de configuración (`$include`) -Divide la configuración en varios archivos: +Divida la configuración en varios archivos: ```json5 // ~/.openclaw/openclaw.json @@ -3851,15 +3871,15 @@ Divide la configuración en varios archivos: } ``` -**Comportamiento de fusión:** +**Comportamiento de combinación:** - Archivo único: reemplaza el objeto contenedor. -- Arreglo de archivos: fusión profunda en orden (los posteriores sobrescriben a los anteriores). -- Claves hermanas: se fusionan después de las inclusiones (sobrescriben los valores incluidos). +- Arreglo de archivos: combinación profunda en orden (los posteriores sobrescriben a los anteriores). +- Claves hermanas: se combinan después de las inclusiones (sobrescriben los valores incluidos). - Inclusiones anidadas: hasta 10 niveles de profundidad. -- Rutas: se resuelven en relación con el archivo que incluye, pero deben permanecer dentro del directorio de configuración de nivel superior (`dirname` de `openclaw.json`). Las formas absolutas/`../` se permiten solo cuando siguen resolviéndose dentro de ese límite. +- Rutas: se resuelven en relación con el archivo que incluye, pero deben permanecer dentro del directorio de configuración de nivel superior (`dirname` de `openclaw.json`). Se permiten formas absolutas/`../` solo cuando aun así se resuelven dentro de ese límite. - Errores: mensajes claros para archivos faltantes, errores de análisis e inclusiones circulares. --- -_Relacionado: [Configuración](/es/gateway/configuration) · [Ejemplos de configuración](/es/gateway/configuration-examples) · [Doctor](/es/gateway/doctor)_ +_Relacionado: [Configuration](/es/gateway/configuration) · [Ejemplos de configuración](/es/gateway/configuration-examples) · [Doctor](/es/gateway/doctor)_ diff --git a/docs/es/help/faq.md b/docs/es/help/faq.md index c3849f192..361d36d5a 100644 --- a/docs/es/help/faq.md +++ b/docs/es/help/faq.md @@ -1,23 +1,23 @@ --- read_when: - - Responder preguntas frecuentes de soporte sobre instalación, configuración inicial o tiempo de ejecución - - Clasificar problemas reportados por usuarios antes de una depuración más profunda -summary: Preguntas frecuentes sobre la instalación, la configuración y el uso de OpenClaw + - Responder preguntas comunes de soporte sobre configuración, instalación, incorporación o tiempo de ejecución + - Clasificar los problemas reportados por los usuarios antes de una depuración más profunda +summary: Preguntas frecuentes sobre la configuración, la configuración y el uso de OpenClaw title: Preguntas frecuentes x-i18n: - generated_at: "2026-04-12T23:28:28Z" + generated_at: "2026-04-20T05:21:31Z" model: gpt-5.4 provider: openai - source_hash: d2a78d0fea9596625cc2753e6dc8cc42c2379a3a0c91729265eee0261fe53eaa + source_hash: 6bdb17fc4d8c61a36f3a9fc3ca4a20f723cfa6c9bbbc92f963d6e313181f3451 source_path: help/faq.md workflow: 15 --- # Preguntas frecuentes -Respuestas rápidas más una solución de problemas más profunda para configuraciones del mundo real (desarrollo local, VPS, multi-agent, OAuth/claves de API, failover de modelos). Para diagnósticos de tiempo de ejecución, consulta [Solución de problemas](/es/gateway/troubleshooting). Para la referencia completa de configuración, consulta [Configuración](/es/gateway/configuration). +Respuestas rápidas más una solución de problemas más profunda para configuraciones reales (desarrollo local, VPS, multiagente, OAuth/claves de API, conmutación por error del modelo). Para diagnósticos en tiempo de ejecución, consulta [Solución de problemas](/es/gateway/troubleshooting). Para la referencia completa de configuración, consulta [Configuración](/es/gateway/configuration). -## Los primeros 60 segundos si algo está roto +## Primeros 60 segundos si algo está roto 1. **Estado rápido (primera comprobación)** @@ -25,95 +25,95 @@ Respuestas rápidas más una solución de problemas más profunda para configura openclaw status ``` - Resumen local rápido: SO + actualización, accesibilidad del gateway/servicio, agents/sessions, configuración del proveedor + problemas de tiempo de ejecución (cuando el gateway es accesible). + Resumen local rápido: SO + actualización, accesibilidad del gateway/servicio, agentes/sesiones, configuración del proveedor + problemas en tiempo de ejecución (cuando el gateway es accesible). -2. **Informe listo para compartir (seguro para compartir)** +2. **Informe copiable (seguro para compartir)** ```bash openclaw status --all ``` - Diagnóstico de solo lectura con cola de logs (tokens redactados). + Diagnóstico de solo lectura con cola del registro (tokens redactados). -3. **Estado del daemon + puerto** +3. **Estado del demonio + puerto** ```bash openclaw gateway status ``` - Muestra el tiempo de ejecución del supervisor frente a la accesibilidad RPC, la URL objetivo del probe y qué configuración probablemente usó el servicio. + Muestra el tiempo de ejecución del supervisor frente a la accesibilidad de RPC, la URL de destino de la sonda y qué configuración probablemente usó el servicio. -4. **Probes profundos** +4. **Sondas profundas** ```bash openclaw status --deep ``` - Ejecuta un probe activo del estado del gateway, incluidos probes de canales cuando están soportados + Ejecuta una sonda de estado del gateway en vivo, incluidas las sondas de canal cuando son compatibles (requiere un gateway accesible). Consulta [Health](/es/gateway/health). -5. **Seguir el log más reciente** +5. **Seguir el último registro** ```bash openclaw logs --follow ``` - Si RPC está caído, usa como alternativa: + Si RPC no está disponible, usa esto como alternativa: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Los logs de archivos son independientes de los logs del servicio; consulta [Logging](/es/logging) y [Solución de problemas](/es/gateway/troubleshooting). + Los registros de archivo están separados de los registros del servicio; consulta [Registro](/es/logging) y [Solución de problemas](/es/gateway/troubleshooting). -6. **Ejecutar doctor (reparaciones)** +6. **Ejecutar Doctor (reparaciones)** ```bash openclaw doctor ``` - Repara/migra configuración/estado + ejecuta comprobaciones de salud. Consulta [Doctor](/es/gateway/doctor). + Repara/migra configuración/estado + ejecuta comprobaciones de estado. Consulta [Doctor](/es/gateway/doctor). 7. **Instantánea del Gateway** ```bash openclaw health --json - openclaw health --verbose # muestra la URL objetivo + la ruta de configuración en caso de errores + openclaw health --verbose # muestra la URL de destino + la ruta de configuración en los errores ``` Solicita al gateway en ejecución una instantánea completa (solo WS). Consulta [Health](/es/gateway/health). -## Inicio rápido y configuración de la primera ejecución +## Inicio rápido y configuración inicial - - Usa un agente de IA local que pueda **ver tu máquina**. Eso es mucho más eficaz que preguntar - en Discord, porque la mayoría de los casos de "estoy atascado" son **problemas locales de configuración o de entorno** - que los ayudantes remotos no pueden inspeccionar. + + Usa un agente de IA local que pueda **ver tu máquina**. Eso es mucho más efectivo que preguntar + en Discord, porque la mayoría de los casos de "estoy bloqueado" son **problemas locales de configuración o entorno** que + los ayudantes remotos no pueden inspeccionar. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Estas herramientas pueden leer el repositorio, ejecutar comandos, inspeccionar logs y ayudar a arreglar la - configuración a nivel de máquina (PATH, servicios, permisos, archivos de autenticación). Dales el **checkout completo del código fuente** mediante + Estas herramientas pueden leer el repositorio, ejecutar comandos, inspeccionar registros y ayudar a corregir la configuración + de tu máquina (PATH, servicios, permisos, archivos de autenticación). Dales el **checkout completo del código fuente** mediante la instalación hackable (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Esto instala OpenClaw **desde un checkout de git**, para que el agente pueda leer el código y la documentación y - razonar sobre la versión exacta que estás ejecutando. Siempre puedes volver a la versión estable más adelante + Esto instala OpenClaw **desde un checkout de git**, para que el agente pueda leer el código + la documentación y + razonar sobre la versión exacta que estás ejecutando. Siempre puedes volver a estable más adelante volviendo a ejecutar el instalador sin `--install-method git`. - Consejo: pídele al agente que **planifique y supervise** la solución (paso a paso), y después ejecute solo los + Consejo: pídele al agente que **planifique y supervise** la corrección (paso a paso), y luego ejecute solo los comandos necesarios. Eso mantiene los cambios pequeños y más fáciles de auditar. - Si descubres un error real o una solución, por favor abre una incidencia en GitHub o envía un PR: + Si descubres un error real o una corrección, por favor abre un issue en GitHub o envía un PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - Empieza con estos comandos (comparte las salidas cuando pidas ayuda): + Empieza con estos comandos (comparte las salidas al pedir ayuda): ```bash openclaw status @@ -121,44 +121,45 @@ Respuestas rápidas más una solución de problemas más profunda para configura openclaw doctor ``` - Qué hacen: + Lo que hacen: - - `openclaw status`: instantánea rápida de la salud del gateway/agent + configuración básica. - - `openclaw models status`: comprueba la autenticación del proveedor + disponibilidad del modelo. + - `openclaw status`: instantánea rápida del estado del gateway/agente + configuración básica. + - `openclaw models status`: comprueba la autenticación del proveedor + la disponibilidad del modelo. - `openclaw doctor`: valida y repara problemas comunes de configuración/estado. - Otras comprobaciones útiles de la CLI: `openclaw status --all`, `openclaw logs --follow`, + Otras comprobaciones útiles de CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Bucle rápido de depuración: [Los primeros 60 segundos si algo está roto](#los-primeros-60-segundos-si-algo-está-roto). - Documentación de instalación: [Install](/es/install), [Flags del instalador](/es/install/installer), [Actualización](/es/install/updating). + Bucle de depuración rápida: [Primeros 60 segundos si algo está roto](#primeros-60-segundos-si-algo-está-roto). + Documentación de instalación: [Instalación](/es/install), [Indicadores del instalador](/es/install/installer), [Actualización](/es/install/updating). - - Motivos habituales de omisión de Heartbeat: + + Razones comunes por las que Heartbeat omite ejecuciones: - `quiet-hours`: fuera de la ventana configurada de horas activas - - `empty-heartbeat-file`: `HEARTBEAT.md` existe pero solo contiene estructura vacía o solo encabezados - - `no-tasks-due`: el modo de tareas de `HEARTBEAT.md` está activo pero todavía no vence ninguno de los intervalos de tareas - - `alerts-disabled`: toda la visibilidad de heartbeat está desactivada (`showOk`, `showAlerts` y `useIndicator` están todos desactivados) + - `empty-heartbeat-file`: `HEARTBEAT.md` existe pero solo contiene una estructura en blanco o solo encabezados + - `no-tasks-due`: el modo de tareas de `HEARTBEAT.md` está activo pero ninguno de los intervalos de las tareas vence todavía + - `alerts-disabled`: toda la visibilidad de heartbeat está desactivada (`showOk`, `showAlerts` y `useIndicator` están desactivados) - En el modo de tareas, las marcas de tiempo de vencimiento solo se adelantan después de que se complete - una ejecución real de heartbeat. Las ejecuciones omitidas no marcan las tareas como completadas. + En modo de tareas, las marcas de tiempo de vencimiento solo se adelantan después de que + se completa una ejecución real de heartbeat. + Las ejecuciones omitidas no marcan las tareas como completadas. Documentación: [Heartbeat](/es/gateway/heartbeat), [Automatización y tareas](/es/automation). - El repositorio recomienda ejecutar desde el código fuente y usar la configuración inicial: + El repositorio recomienda ejecutar desde el código fuente y usar el onboarding: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - El asistente también puede compilar automáticamente los recursos de la UI. Después de la configuración inicial, normalmente ejecutas el Gateway en el puerto **18789**. + El asistente también puede compilar automáticamente los recursos de la UI. Después del onboarding, normalmente ejecutas el Gateway en el puerto **18789**. Desde el código fuente (colaboradores/desarrollo): @@ -167,7 +168,7 @@ Respuestas rápidas más una solución de problemas más profunda para configura cd openclaw pnpm install pnpm build - pnpm ui:build # instala automáticamente las dependencias de la UI en la primera ejecución + pnpm ui:build openclaw onboard ``` @@ -175,8 +176,8 @@ Respuestas rápidas más una solución de problemas más profunda para configura - - El asistente abre tu navegador con una URL limpia del panel (sin token) justo después de la configuración inicial y también imprime el enlace en el resumen. Mantén esa pestaña abierta; si no se abrió, copia y pega la URL impresa en la misma máquina. + + El asistente abre tu navegador con una URL limpia del panel (sin token) justo después del onboarding y también imprime el enlace en el resumen. Mantén abierta esa pestaña; si no se abrió, copia y pega la URL impresa en la misma máquina. @@ -190,48 +191,48 @@ Respuestas rápidas más una solución de problemas más profunda para configura **No en localhost:** - - **Tailscale Serve** (recomendado): mantén el bind en loopback, ejecuta `openclaw gateway --tailscale serve`, abre `https:///`. Si `gateway.auth.allowTailscale` es `true`, los encabezados de identidad satisfacen la autenticación de Control UI/WebSocket (sin pegar secreto compartido, asume un host de gateway de confianza); las API HTTP siguen requiriendo autenticación con secreto compartido a menos que uses deliberadamente `none` para private-ingress o autenticación HTTP de trusted-proxy. + - **Tailscale Serve** (recomendado): mantén el enlace en loopback, ejecuta `openclaw gateway --tailscale serve`, abre `https:///`. Si `gateway.auth.allowTailscale` es `true`, los encabezados de identidad satisfacen la autenticación de Control UI/WebSocket (sin pegar un secreto compartido, asume un host de gateway de confianza); las API HTTP siguen requiriendo autenticación con secreto compartido a menos que uses deliberadamente `none` de entrada privada o autenticación HTTP de proxy de confianza. Los intentos concurrentes fallidos de autenticación de Serve desde el mismo cliente se serializan antes de que el limitador de autenticación fallida los registre, por lo que el segundo reintento fallido ya puede mostrar `retry later`. - - **Bind de tailnet**: ejecuta `openclaw gateway --bind tailnet --token ""` (o configura autenticación por contraseña), abre `http://:18789/`, y luego pega el secreto compartido correspondiente en la configuración del panel. - - **Proxy inverso con reconocimiento de identidad**: mantén el Gateway detrás de un trusted proxy no loopback, configura `gateway.auth.mode: "trusted-proxy"`, y luego abre la URL del proxy. - - **Túnel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` y luego abre `http://127.0.0.1:18789/`. La autenticación con secreto compartido sigue aplicándose sobre el túnel; pega el token o la contraseña configurados si se te solicita. + - **Enlace a tailnet**: ejecuta `openclaw gateway --bind tailnet --token ""` (o configura autenticación con contraseña), abre `http://:18789/`, luego pega el secreto compartido correspondiente en la configuración del panel. + - **Proxy inverso con conocimiento de identidad**: mantén el Gateway detrás de un proxy de confianza que no sea loopback, configura `gateway.auth.mode: "trusted-proxy"`, luego abre la URL del proxy. + - **Túnel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` y luego abre `http://127.0.0.1:18789/`. La autenticación con secreto compartido sigue aplicándose a través del túnel; pega el token o la contraseña configurados si se solicita. - Consulta [Dashboard](/web/dashboard) y [Superficies web](/web) para los detalles de modos de bind y autenticación. + Consulta [Panel](/web/dashboard) y [Superficies web](/web) para ver los modos de enlace y los detalles de autenticación. - - Controlan capas distintas: + + Controlan capas diferentes: - `approvals.exec`: reenvía solicitudes de aprobación a destinos de chat - - `channels..execApprovals`: hace que ese canal actúe como cliente nativo de aprobación para aprobaciones exec + - `channels..execApprovals`: hace que ese canal actúe como un cliente nativo de aprobación para aprobaciones de exec - La política exec del host sigue siendo la puerta de aprobación real. La configuración de chat solo controla dónde aparecen - las solicitudes de aprobación y cómo puede responder la gente. + La política de exec 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 la gente puede responderlas. En la mayoría de las configuraciones **no** necesitas ambas: - Si el chat ya admite comandos y respuestas, `/approve` en el mismo chat funciona mediante la ruta compartida. - - Si un canal nativo compatible puede inferir aprobadores de forma segura, OpenClaw ahora habilita automáticamente aprobaciones nativas DM-first cuando `channels..execApprovals.enabled` no está definido o es `"auto"`. - - Cuando hay tarjetas/botones nativos de aprobación disponibles, esa UI nativa es la ruta principal; el agent solo debe incluir un comando manual `/approve` si el resultado de la herramienta dice que las aprobaciones por chat no están disponibles o si la aprobación manual es la única vía. - - Usa `approvals.exec` solo cuando las solicitudes también deban reenviarse a otros chats o salas operativas explícitas. - - Usa `channels..execApprovals.target: "channel"` o `"both"` solo cuando quieras explícitamente que las solicitudes de aprobación se publiquen de vuelta en la sala o el tema de origen. - - Las aprobaciones de plugins son otra cosa aparte: usan `/approve` en el mismo chat por defecto, reenvío opcional con `approvals.plugin`, y solo algunos canales nativos mantienen además el manejo nativo de aprobación de plugins. + - Si un canal nativo compatible puede inferir aprobadores de forma segura, OpenClaw ahora habilita automáticamente aprobaciones nativas priorizando DM cuando `channels..execApprovals.enabled` no está configurado o es `"auto"`. + - Cuando las tarjetas/botones de aprobación nativa están disponibles, esa UI nativa es la ruta principal; el agente solo debe incluir un comando manual `/approve` si el resultado de la herramienta dice que las aprobaciones por chat no están disponibles o si la aprobación manual es la única ruta. + - Usa `approvals.exec` solo cuando las solicitudes también deban reenviarse a otros chats o salas de operaciones explícitas. + - Usa `channels..execApprovals.target: "channel"` o `"both"` solo cuando quieras explícitamente que las solicitudes de aprobación vuelvan a publicarse en la sala/tema de origen. + - Las aprobaciones de Plugin vuelven a estar separadas: usan `/approve` en el mismo chat de forma predeterminada, reenvío opcional con `approvals.plugin`, y solo algunos canales nativos mantienen además el manejo nativo de aprobación de plugins. - Versión corta: el reenvío es para el enrutamiento, la configuración del cliente nativo es para una UX más rica específica del canal. - Consulta [Aprobaciones exec](/es/tools/exec-approvals). + En resumen: el reenvío es para el enrutamiento; la configuración del cliente nativo es para una UX específica del canal más rica. + Consulta [Aprobaciones de exec](/es/tools/exec-approvals). - - Se requiere Node **>= 22**. Se recomienda `pnpm`. Bun **no se recomienda** para el Gateway. + + Se requiere Node **>= 22**. Se recomienda `pnpm`. Bun **no está recomendado** para el Gateway. - Sí. El Gateway es ligero: la documentación indica que **512MB-1GB de RAM**, **1 núcleo** y aproximadamente **500MB** - de disco son suficientes para uso personal, y señala que **Raspberry Pi 4 puede ejecutarlo**. + Sí. El Gateway es ligero: la documentación indica que **512 MB-1 GB de RAM**, **1 núcleo** y aproximadamente **500 MB** + de disco son suficientes para uso personal, y señala que una **Raspberry Pi 4 puede ejecutarlo**. - Si quieres margen adicional (logs, medios, otros servicios), **se recomiendan 2GB**, pero + Si quieres margen adicional (registros, medios, otros servicios), se recomiendan **2 GB**, pero no es un mínimo estricto. Consejo: un Pi/VPS pequeño puede alojar el Gateway, y puedes emparejar **nodes** en tu portátil/teléfono para @@ -240,21 +241,21 @@ Respuestas rápidas más una solución de problemas más profunda para configura - Versión corta: funciona, pero espera ciertas asperezas. + En resumen: funciona, pero espera ciertas asperezas. - Usa un SO de **64 bits** y mantén Node >= 22. - - Prefiere la **instalación hackable (git)** para poder ver logs y actualizar rápidamente. - - Empieza sin canales/Skills, luego añádelos uno por uno. - - Si encuentras problemas extraños con binarios, normalmente es un problema de **compatibilidad ARM**. + - Prefiere la **instalación hackable (git)** para poder ver los registros y actualizar rápidamente. + - Empieza sin channels/Skills, luego añádelos uno por uno. + - Si encuentras problemas binarios extraños, normalmente es un problema de **compatibilidad ARM**. - Documentación: [Linux](/es/platforms/linux), [Install](/es/install). + Documentación: [Linux](/es/platforms/linux), [Instalación](/es/install). - + Esa pantalla depende de que el Gateway sea accesible y esté autenticado. La TUI también envía - "Wake up, my friend!" automáticamente en la primera apertura. Si ves esa línea **sin respuesta** - y los tokens siguen en 0, el agent nunca se ejecutó. + "Wake up, my friend!" automáticamente en la primera activación. Si ves esa línea con **sin respuesta** + y los tokens permanecen en 0, el agente nunca se ejecutó. 1. Reinicia el Gateway: @@ -262,7 +263,7 @@ Respuestas rápidas más una solución de problemas más profunda para configura openclaw gateway restart ``` - 2. Comprueba estado + autenticación: + 2. Comprueba el estado + autenticación: ```bash openclaw status @@ -270,7 +271,7 @@ Respuestas rápidas más una solución de problemas más profunda para configura openclaw logs --follow ``` - 3. Si sigue colgado, ejecuta: + 3. Si sigue bloqueado, ejecuta: ```bash openclaw doctor @@ -281,72 +282,72 @@ Respuestas rápidas más una solución de problemas más profunda para configura - - Sí. Copia el **directorio de estado** y el **espacio de trabajo**, luego ejecuta Doctor una vez. Esto - mantiene tu bot "exactamente igual" (memoria, historial de sesiones, autenticación y estado - del canal) siempre que copies **ambas** ubicaciones: + + Sí. Copia el **directorio de estado** y el **workspace**, luego ejecuta Doctor una vez. Esto + mantiene tu bot "exactamente igual" (memoria, historial de sesión, autenticación y + estado del canal) siempre que copies **ambas** ubicaciones: 1. Instala OpenClaw en la nueva máquina. 2. Copia `$OPENCLAW_STATE_DIR` (predeterminado: `~/.openclaw`) desde la máquina antigua. - 3. Copia tu espacio de trabajo (predeterminado: `~/.openclaw/workspace`). + 3. Copia tu workspace (predeterminado: `~/.openclaw/workspace`). 4. Ejecuta `openclaw doctor` y reinicia el servicio Gateway. - Eso conserva la configuración, los perfiles de autenticación, las credenciales de WhatsApp, las sesiones y la memoria. Si estás en - modo remoto, recuerda que el host del gateway es el propietario del almacenamiento de sesiones y del espacio de trabajo. + Eso preserva la configuración, los perfiles de autenticación, las credenciales de WhatsApp, las sesiones y la memoria. Si estás en + modo remoto, recuerda que el host del gateway es el propietario del almacén de sesiones y del workspace. - **Importante:** si solo haces commit/push de tu espacio de trabajo a GitHub, estás haciendo una copia de seguridad - de **la memoria + archivos de arranque**, pero **no** del historial de sesiones ni de la autenticación. Esos viven + **Importante:** si solo haces commit/push de tu workspace a GitHub, estarás haciendo una copia de seguridad de + **la memoria + los archivos de arranque**, pero **no** del historial de sesiones ni de la autenticación. Esos viven en `~/.openclaw/` (por ejemplo `~/.openclaw/agents//sessions/`). - Relacionado: [Migración](/es/install/migrating), [Dónde están las cosas en disco](#where-things-live-on-disk), - [Espacio de trabajo del agent](/es/concepts/agent-workspace), [Doctor](/es/gateway/doctor), + Relacionado: [Migración](/es/install/migrating), [Dónde viven las cosas en disco](#where-things-live-on-disk), + [Workspace del agente](/es/concepts/agent-workspace), [Doctor](/es/gateway/doctor), [Modo remoto](/es/gateway/remote). - + Consulta el changelog de GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Las entradas más recientes están arriba. Si la sección superior está marcada como **Unreleased**, la siguiente - sección con fecha es la última versión publicada. Las entradas se agrupan en **Highlights**, **Changes** y - **Fixes** (además de secciones de documentación/u otras cuando hace falta). + Las entradas más recientes están arriba. Si la sección superior está marcada como **Unreleased**, la siguiente sección + con fecha es la última versión publicada. Las entradas se agrupan por **Highlights**, **Changes** y + **Fixes** (además de secciones de documentación/u otras cuando es necesario). - + Algunas conexiones de Comcast/Xfinity bloquean incorrectamente `docs.openclaw.ai` mediante Xfinity - Advanced Security. Desactívalo o añade `docs.openclaw.ai` a la allowlist, y vuelve a intentarlo. - Ayúdanos a desbloquearlo informándolo aquí: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Advanced Security. Desactívalo o añade `docs.openclaw.ai` a la lista de permitidos y vuelve a intentarlo. + Ayúdanos a desbloquearlo reportándolo aquí: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Si aún no puedes acceder al sitio, la documentación está replicada en GitHub: + Si todavía no puedes acceder al sitio, la documentación está replicada en GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - - **Stable** y **beta** son **npm dist-tags**, no líneas de código separadas: + + **Estable** y **beta** son **dist-tags de npm**, no líneas de código separadas: - - `latest` = stable + - `latest` = estable - `beta` = compilación temprana para pruebas - Normalmente, una versión stable llega primero a **beta**, y luego un paso explícito - de promoción mueve esa misma versión a `latest`. Los maintainers también pueden - publicar directamente en `latest` cuando hace falta. Por eso beta y stable pueden + Normalmente, una versión estable llega primero a **beta**, y luego un paso explícito + de promoción mueve esa misma versión a `latest`. Los mantenedores también pueden + publicar directamente en `latest` cuando sea necesario. Por eso beta y estable pueden apuntar a la **misma versión** después de la promoción. Consulta qué cambió: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Para comandos de instalación en una sola línea y la diferencia entre beta y dev, consulta el acordeón de abajo. + Para los comandos de instalación en una sola línea y la diferencia entre beta y dev, consulta el acordeón de abajo. - **Beta** es la 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 npm dist-tag `dev`. + **Beta** es el dist-tag `beta` de npm (puede coincidir con `latest` después de la promoción). + **Dev** es la cabecera en movimiento de `main` (git); cuando se publica, usa el dist-tag `dev` de npm. - Comandos en una sola línea (macOS/Linux): + Comandos de una línea (macOS/Linux): ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta @@ -356,15 +357,15 @@ Respuestas rápidas más una solución de problemas más profunda para configura curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Instalador de Windows (PowerShell): + Instalador para Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Más detalles: [Canales de desarrollo](/es/install/development-channels) y [Flags del instalador](/es/install/installer). + Más detalle: [Canales de desarrollo](/es/install/development-channels) e [Indicadores del instalador](/es/install/installer). - Tienes dos opciones: + Dos opciones: 1. **Canal dev (checkout de git):** @@ -380,9 +381,9 @@ Respuestas rápidas más una solución de problemas más profunda para configura curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Eso te da un repositorio local que puedes editar y luego actualizar mediante git. + Eso te da un repositorio local que puedes editar y luego actualizar con git. - Si prefieres hacer manualmente un clon limpio, usa: + Si prefieres un clon limpio manualmente, usa: ```bash git clone https://github.com/openclaw/openclaw.git @@ -391,23 +392,23 @@ Respuestas rápidas más una solución de problemas más profunda para configura pnpm build ``` - Documentación: [Update](/cli/update), [Canales de desarrollo](/es/install/development-channels), - [Install](/es/install). + Documentación: [Actualización](/cli/update), [Canales de desarrollo](/es/install/development-channels), + [Instalación](/es/install). - + Guía aproximada: - **Instalación:** 2-5 minutos - - **Configuración inicial:** 5-15 minutos según cuántos canales/modelos configures + - **Onboarding:** 5-15 minutos según cuántos canales/modelos configures - Si se queda colgado, usa [Instalador atascado](#quick-start-and-first-run-setup) - y el bucle rápido de depuración en [Estoy atascado](#quick-start-and-first-run-setup). + Si se queda bloqueado, usa [Instalador bloqueado](#quick-start-and-first-run-setup) + y el bucle rápido de depuración en [Estoy bloqueado](#quick-start-and-first-run-setup). - + Vuelve a ejecutar el instalador con **salida detallada**: ```bash @@ -429,17 +430,17 @@ Respuestas rápidas más una solución de problemas más profunda para configura Equivalente en Windows (PowerShell): ```powershell - # install.ps1 todavía no tiene un flag -Verbose específico. + # install.ps1 todavía no tiene un indicador -Verbose dedicado. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` - Más opciones: [Flags del instalador](/es/install/installer). + Más opciones: [Indicadores del instalador](/es/install/installer). - + Dos problemas comunes en Windows: **1) error de npm spawn git / git not found** @@ -447,9 +448,9 @@ Respuestas rápidas más una solución de problemas más profunda para configura - Instala **Git for 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** + **2) openclaw is not recognized después de la instalación** - - La carpeta global bin de npm no está en tu PATH. + - Tu carpeta global bin de npm no está en PATH. - Comprueba la ruta: ```powershell @@ -464,15 +465,15 @@ Respuestas rápidas más una solución de problemas más profunda para configura - - Normalmente esto es un desajuste de la página de códigos de la consola en shells nativos de Windows. + + Esto suele deberse a una incompatibilidad de página de códigos de la consola en shells nativos de Windows. Síntomas: - - La salida de `system.run`/`exec` muestra caracteres chinos corruptos + - La salida de `system.run`/`exec` muestra chino como texto ilegible - El mismo comando se ve bien en otro perfil de terminal - Solución temporal rápida en PowerShell: + Solución rápida en PowerShell: ```powershell chcp 65001 @@ -481,32 +482,32 @@ Respuestas rápidas más una solución de problemas más profunda para configura $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - Luego reinicia el Gateway y vuelve a probar tu comando: + Luego reinicia el Gateway y vuelve a probar el comando: ```powershell openclaw gateway restart ``` - Si esto sigue reproduciéndose en la última versión de OpenClaw, haz seguimiento/informa en: + Si todavía puedes reproducir esto en la última versión de OpenClaw, síguelo/repórtalo en: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - Usa la **instalación hackable (git)** para tener localmente todo el código fuente y la documentación, luego pregunta - a tu bot (o a Claude/Codex) _desde esa carpeta_ para que pueda leer el repositorio y responder con precisión. + + Usa la **instalación hackable (git)** para tener el código fuente completo y la documentación localmente, luego pregunta + a tu bot (o Claude/Codex) _desde esa carpeta_ para que pueda leer el repositorio y responder con precisión. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Más detalles: [Install](/es/install) y [Flags del instalador](/es/install/installer). + Más detalle: [Instalación](/es/install) e [Indicadores del instalador](/es/install/installer). - Respuesta corta: sigue la guía de Linux y luego ejecuta la configuración inicial. + Respuesta corta: sigue la guía de Linux y luego ejecuta el onboarding. - Ruta rápida de Linux + instalación del servicio: [Linux](/es/platforms/linux). - Guía completa: [Primeros pasos](/es/start/getting-started). @@ -515,15 +516,15 @@ Respuestas rápidas más una solución de problemas más profunda para configura - Cualquier VPS Linux funciona. Instálalo en el servidor y luego usa SSH/Tailscale para acceder al Gateway. + Cualquier VPS con Linux funciona. Instálalo en el servidor y luego usa SSH/Tailscale para acceder al Gateway. Guías: [exe.dev](/es/install/exe-dev), [Hetzner](/es/install/hetzner), [Fly.io](/es/install/fly). - Acceso remoto: [Gateway remote](/es/gateway/remote). + Acceso remoto: [Gateway remoto](/es/gateway/remote). - Tenemos un **centro de hosting** con los proveedores más habituales. Elige uno y sigue la guía: + Tenemos un **centro de hosting** con los proveedores más comunes. Elige uno y sigue la guía: - [Hosting VPS](/es/vps) (todos los proveedores en un solo lugar) - [Fly.io](/es/install/fly) @@ -531,22 +532,22 @@ Respuestas rápidas más una solución de problemas más profunda para configura - [exe.dev](/es/install/exe-dev) Cómo funciona en la nube: el **Gateway se ejecuta en el servidor**, y accedes a él - desde tu portátil/teléfono mediante la Control UI (o Tailscale/SSH). Tu estado + espacio de trabajo - viven en el servidor, así que trata el host como la fuente de verdad y haz copias de seguridad. + desde tu portátil/teléfono mediante la Control UI (o Tailscale/SSH). Tu estado + workspace + viven en el servidor, así que trata al host como la fuente de verdad y haz copias de seguridad. Puedes emparejar **nodes** (Mac/iOS/Android/headless) con ese Gateway en la nube para acceder a pantalla/cámara/canvas locales o ejecutar comandos en tu portátil mientras mantienes el Gateway en la nube. - Centro: [Plataformas](/es/platforms). Acceso remoto: [Gateway remote](/es/gateway/remote). + Centro: [Plataformas](/es/platforms). Acceso remoto: [Gateway remoto](/es/gateway/remote). Nodes: [Nodes](/es/nodes), [CLI de Nodes](/cli/nodes). Respuesta corta: **es posible, pero no se recomienda**. El flujo de actualización puede reiniciar el - Gateway (lo que corta la sesión activa), puede requerir un checkout de git limpio y - puede pedir confirmación. Más seguro: ejecuta las actualizaciones desde un shell como operador. + Gateway (lo que interrumpe la sesión activa), puede necesitar un checkout de git limpio y + puede pedir confirmación. Es más seguro: ejecutar las actualizaciones desde un shell como operador. Usa la CLI: @@ -558,32 +559,32 @@ Respuestas rápidas más una solución de problemas más profunda para configura openclaw update --no-restart ``` - Si debes automatizarlo desde un agent: + Si debes automatizarlo desde un agente: ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - Documentación: [Update](/cli/update), [Updating](/es/install/updating). + Documentación: [Actualización](/cli/update), [Actualización](/es/install/updating). - + `openclaw onboard` es la ruta de configuración recomendada. En **modo local** te guía por: - **Configuración de modelo/autenticación** (OAuth del proveedor, claves de API, setup-token de Anthropic, además de opciones de modelos locales como LM Studio) - - Ubicación del **espacio de trabajo** + archivos de arranque - - **Configuración del Gateway** (bind/puerto/autenticación/tailscale) - - **Canales** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, además de plugins de canal incluidos como QQ Bot) - - **Instalación del daemon** (LaunchAgent en macOS; unidad de usuario systemd en Linux/WSL2) - - **Comprobaciones de salud** y selección de **Skills** + - Ubicación del **workspace** + archivos de arranque + - **Configuración del Gateway** (bind/port/auth/tailscale) + - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, además de plugins de canal incluidos como QQ Bot) + - **Instalación del demonio** (LaunchAgent en macOS; unidad de usuario systemd en Linux/WSL2) + - **Comprobaciones de estado** y selección de **Skills** También avisa si tu modelo configurado es desconocido o si falta autenticación. - + No. Puedes ejecutar OpenClaw con **claves de API** (Anthropic/OpenAI/otros) 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. @@ -591,49 +592,49 @@ Respuestas rápidas más una solución de problemas más profunda para configura Para Anthropic en OpenClaw, la división práctica es: - **Clave de API de Anthropic**: facturación normal de la API de Anthropic - - **Autenticación con Claude CLI / suscripción de Claude en OpenClaw**: el personal de Anthropic + - **Autenticación de Claude CLI / suscripción de Claude en OpenClaw**: el personal de Anthropic nos dijo que este uso vuelve a estar permitido, y OpenClaw está tratando el uso de `claude -p` como autorizado para esta integración salvo que Anthropic publique una nueva política - Para hosts de gateway de larga duración, las claves de API de Anthropic siguen siendo la configuración - más predecible. OpenAI Codex OAuth está explícitamente soportado para herramientas externas - como OpenClaw. + Para hosts de gateway de larga duración, las claves de API de Anthropic siguen siendo la + configuración más predecible. OpenAI Codex OAuth es compatible explícitamente para herramientas + externas como OpenClaw. - OpenClaw también admite otras opciones alojadas de estilo suscripción, entre ellas + OpenClaw también admite otras opciones alojadas de estilo suscripción, incluidas **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** y **Z.AI / GLM Coding Plan**. Documentación: [Anthropic](/es/providers/anthropic), [OpenAI](/es/providers/openai), [Qwen Cloud](/es/providers/qwen), - [MiniMax](/es/providers/minimax), [GLM Models](/es/providers/glm), - [Modelos locales](/es/gateway/local-models), [Models](/es/concepts/models). + [MiniMax](/es/providers/minimax), [Modelos GLM](/es/providers/glm), + [Modelos locales](/es/gateway/local-models), [Modelos](/es/concepts/models). Sí. - El personal de Anthropic nos dijo que el uso de Claude CLI al estilo de OpenClaw vuelve a estar permitido, así que - OpenClaw trata la autenticación por suscripción de Claude y el uso de `claude -p` como autorizados - para esta integración, salvo que Anthropic publique una nueva política. Si quieres + El personal de Anthropic nos dijo que el uso de Claude CLI al estilo OpenClaw vuelve a estar permitido, así que + OpenClaw trata la autenticación con suscripción de Claude y el uso de `claude -p` como autorizados + para esta integración salvo que Anthropic publique una nueva política. Si quieres la configuración del lado del servidor más predecible, usa en su lugar una clave de API de Anthropic. - + Sí. - El personal de Anthropic nos dijo que este uso vuelve a estar permitido, así que OpenClaw considera + El personal de Anthropic nos dijo que este uso vuelve a estar permitido, por lo que OpenClaw trata la reutilización de Claude CLI y el uso de `claude -p` como autorizados para esta integración salvo que Anthropic publique una nueva política. - El setup-token de Anthropic sigue estando disponible como una ruta de token compatible de OpenClaw, pero OpenClaw ahora prefiere la reutilización de Claude CLI y `claude -p` cuando están disponibles. - Para cargas de trabajo de producción o multi-user, la autenticación con clave de API de Anthropic sigue siendo la + El setup-token de Anthropic sigue estando disponible como una ruta de token compatible en OpenClaw, pero OpenClaw ahora prefiere la reutilización de Claude CLI y `claude -p` cuando están disponibles. + 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 quieres otras opciones alojadas de estilo suscripción en OpenClaw, consulta [OpenAI](/es/providers/openai), [Qwen / Model - Cloud](/es/providers/qwen), [MiniMax](/es/providers/minimax) y [GLM - Models](/es/providers/glm). + Cloud](/es/providers/qwen), [MiniMax](/es/providers/minimax) y [Modelos + GLM](/es/providers/glm). @@ -641,27 +642,27 @@ Respuestas rápidas más una solución de problemas más profunda para configura Eso significa que tu **cuota/límite de tasa de Anthropic** está agotado para la ventana actual. Si usas **Claude CLI**, espera a que la ventana se restablezca o mejora tu plan. Si -usas una **clave de API de Anthropic**, revisa la Consola de Anthropic -para ver uso/facturación y aumenta los límites según sea necesario. +usas una **clave de API de Anthropic**, consulta la consola de Anthropic +para ver el uso/la facturación y aumenta 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 beta de contexto de 1M de Anthropic (`context1m: true`). Eso solo funciona cuando tu + la beta de contexto de 1 M de Anthropic (`context1m: true`). Eso solo funciona cuando tu credencial es apta para la facturación de contexto largo (facturación con clave de API o la - ruta de inicio de sesión de Claude de OpenClaw con Extra Usage habilitado). + ruta de inicio de sesión de Claude de OpenClaw con Uso Extra habilitado). - Consejo: configura un **modelo de fallback** para que OpenClaw pueda seguir respondiendo mientras un proveedor esté limitado por tasa. - Consulta [Models](/cli/models), [OAuth](/es/concepts/oauth) y + Consejo: configura un **modelo de respaldo** para que OpenClaw pueda seguir respondiendo mientras un proveedor tiene límite de tasa. + Consulta [Modelos](/cli/models), [OAuth](/es/concepts/oauth) y [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/es/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - - Sí. OpenClaw tiene un proveedor incluido de **Amazon Bedrock (Converse)**. Con marcadores de entorno de AWS presentes, OpenClaw puede detectar automáticamente el catálogo de Bedrock de streaming/texto y fusionarlo como un proveedor implícito `amazon-bedrock`; de lo contrario puedes habilitar explícitamente `plugins.entries.amazon-bedrock.config.discovery.enabled` o añadir una entrada manual de proveedor. Consulta [Amazon Bedrock](/es/providers/bedrock) y [Proveedores de modelos](/es/providers/models). Si prefieres un flujo gestionado con clave, un proxy compatible con OpenAI delante de Bedrock sigue siendo una opción válida. + + Sí. OpenClaw incluye un proveedor de **Amazon Bedrock (Converse)**. Con los marcadores de entorno de AWS presentes, OpenClaw puede detectar automáticamente el catálogo de Bedrock de streaming/texto y combinarlo como un proveedor implícito `amazon-bedrock`; de lo contrario, puedes habilitar explícitamente `plugins.entries.amazon-bedrock.config.discovery.enabled` o añadir una entrada de proveedor manual. Consulta [Amazon Bedrock](/es/providers/bedrock) y [Proveedores de modelos](/es/providers/models). Si prefieres un flujo de clave administrada, un proxy compatible con OpenAI delante de Bedrock sigue siendo una opción válida. - OpenClaw soporta **OpenAI Code (Codex)** mediante OAuth (inicio de sesión de ChatGPT). La configuración inicial puede ejecutar el flujo OAuth y establecerá el modelo predeterminado en `openai-codex/gpt-5.4` cuando corresponda. Consulta [Proveedores de modelos](/es/concepts/model-providers) y [Configuración inicial (CLI)](/es/start/wizard). + OpenClaw admite **OpenAI Code (Codex)** mediante OAuth (inicio de sesión de ChatGPT). El onboarding puede ejecutar el flujo OAuth y establecerá el modelo predeterminado en `openai-codex/gpt-5.4` cuando corresponda. Consulta [Proveedores de modelos](/es/concepts/model-providers) y [Onboarding (CLI)](/es/start/wizard). @@ -672,34 +673,34 @@ para ver uso/facturación y aumenta los límites según sea necesario. En OpenClaw, el inicio de sesión de ChatGPT/Codex está conectado a la ruta `openai-codex/*`, no a la ruta directa `openai/*`. Si quieres la ruta de API directa en - OpenClaw, establece `OPENAI_API_KEY` (o la configuración equivalente del proveedor OpenAI). - Si quieres el inicio de sesión de ChatGPT/Codex en OpenClaw, usa `openai-codex/*`. + OpenClaw, configura `OPENAI_API_KEY` (o la configuración equivalente del proveedor OpenAI). + Si quieres usar el inicio de sesión de ChatGPT/Codex en OpenClaw, usa `openai-codex/*`. - + `openai-codex/*` usa la ruta OAuth de Codex, y sus ventanas de cuota utilizables son - gestionadas por OpenAI y dependen del plan. En la práctica, esos límites pueden diferir de + administradas por OpenAI y dependen 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 ChatGPT web en acceso directo a la API. Si quieres la ruta directa de facturación/límites de OpenAI Platform, + `openclaw models status`, pero no inventa ni normaliza los derechos de ChatGPT web + en acceso directo a la API. Si quieres la ruta directa de facturación/límites de OpenAI Platform, usa `openai/*` con una clave de API. - - Sí. OpenClaw soporta completamente **OAuth por suscripción de OpenAI Code (Codex)**. - OpenAI permite explícitamente el uso de OAuth por suscripción en herramientas/flujos externos - como OpenClaw. La configuración inicial puede ejecutar el flujo OAuth por ti. + + Sí. OpenClaw admite completamente **OAuth de suscripción de OpenAI Code (Codex)**. + OpenAI permite explícitamente el uso de OAuth de suscripción en herramientas/flujos de trabajo externos + como OpenClaw. El onboarding puede ejecutar el flujo OAuth por ti. - Consulta [OAuth](/es/concepts/oauth), [Proveedores de modelos](/es/concepts/model-providers) y [Configuración inicial (CLI)](/es/start/wizard). + Consulta [OAuth](/es/concepts/oauth), [Proveedores de modelos](/es/concepts/model-providers) y [Onboarding (CLI)](/es/start/wizard). - Gemini CLI usa un **flujo de autenticación de plugin**, no un client id o secret en `openclaw.json`. + Gemini CLI usa un **flujo de autenticación de Plugin**, no un client id o un secret en `openclaw.json`. Pasos: @@ -709,37 +710,37 @@ para ver uso/facturación y aumenta los límites según sea necesario. 2. Habilita el plugin: `openclaw plugins enable google` 3. Inicia 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, establece `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host del gateway + 5. Si las solicitudes fallan, configura `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host del gateway Esto almacena tokens OAuth en perfiles de autenticación en el host del gateway. Detalles: [Proveedores de modelos](/es/concepts/model-providers). - - Normalmente no. OpenClaw necesita contexto amplio + seguridad sólida; las tarjetas pequeñas truncan y filtran. Si es imprescindible, ejecuta localmente la compilación del modelo **más grande** que puedas (LM Studio) y consulta [/gateway/local-models](/es/gateway/local-models). Los modelos más pequeños/cuantizados aumentan el riesgo de prompt injection; consulta [Security](/es/gateway/security). + + Normalmente no. OpenClaw necesita un contexto amplio + seguridad sólida; las tarjetas pequeñas truncan y filtran. Si es imprescindible, ejecuta localmente la compilación del modelo **más grande** que puedas (LM Studio) y consulta [/gateway/local-models](/es/gateway/local-models). Los modelos más pequeños/cuantizados aumentan el riesgo de inyección de prompts; consulta [Seguridad](/es/gateway/security). - - Elige endpoints fijados a una región. OpenRouter expone opciones alojadas en EE. UU. para MiniMax, Kimi y GLM; elige la variante alojada en EE. UU. para mantener los datos en esa región. Aun así puedes listar Anthropic/OpenAI junto con estos usando `models.mode: "merge"` para que los fallbacks sigan disponibles mientras respetas el proveedor regionalizado que selecciones. + + Elige endpoints fijados por región. OpenRouter ofrece opciones alojadas en EE. UU. para MiniMax, Kimi y GLM; elige la variante alojada en EE. UU. para mantener los datos dentro de la región. Aun así, puedes listar Anthropic/OpenAI junto con estos usando `models.mode: "merge"` para que los respaldos sigan disponibles mientras respetas el proveedor regional que seleccionaste. - + No. OpenClaw funciona en macOS o Linux (Windows mediante WSL2). Un Mac mini es opcional; algunas personas - compran uno como host siempre activo, pero también sirve un VPS pequeño, un servidor doméstico o una máquina tipo Raspberry Pi. + compran uno como host siempre activo, pero también sirve un VPS pequeño, un servidor doméstico o un equipo tipo Raspberry Pi. - Solo necesitas un Mac **para herramientas exclusivas de macOS**. Para iMessage, usa [BlueBubbles](/es/channels/bluebubbles) (recomendado): el servidor de BlueBubbles se ejecuta en cualquier Mac, y el Gateway puede ejecutarse en Linux o en otro sitio. Si quieres otras herramientas exclusivas de macOS, ejecuta el Gateway en un Mac o empareja un node de macOS. + Solo necesitas un Mac **para herramientas exclusivas de macOS**. Para iMessage, usa [BlueBubbles](/es/channels/bluebubbles) (recomendado): el servidor BlueBubbles se ejecuta en cualquier Mac, y el Gateway puede ejecutarse en Linux o en otro lugar. Si quieres otras herramientas exclusivas de macOS, ejecuta el Gateway en un Mac o empareja un node de macOS. Documentación: [BlueBubbles](/es/channels/bluebubbles), [Nodes](/es/nodes), [Modo remoto en Mac](/es/platforms/mac/remote). - - Necesitas **algún dispositivo macOS** con sesión iniciada en Messages. **No** tiene que ser un Mac mini: - cualquier Mac sirve. **Usa [BlueBubbles](/es/channels/bluebubbles)** (recomendado) para iMessage: el servidor BlueBubbles se ejecuta en macOS, mientras que el Gateway puede ejecutarse en Linux o en otro lugar. + + Necesitas **algún dispositivo macOS** con sesión iniciada en Mensajes. **No** tiene que ser un Mac mini; + cualquier Mac funciona. **Usa [BlueBubbles](/es/channels/bluebubbles)** (recomendado) para iMessage: el servidor BlueBubbles se ejecuta en macOS, mientras que el Gateway puede ejecutarse en Linux o en otro lugar. Configuraciones habituales: - - Ejecuta el Gateway en Linux/VPS y el servidor BlueBubbles en cualquier Mac con sesión iniciada en Messages. + - Ejecuta el Gateway en Linux/VPS y ejecuta el servidor BlueBubbles en cualquier Mac con sesión iniciada en Mensajes. - Ejecuta todo en el Mac si quieres la configuración más simple en una sola máquina. Documentación: [BlueBubbles](/es/channels/bluebubbles), [Nodes](/es/nodes), @@ -749,8 +750,8 @@ para ver uso/facturación y aumenta los límites según sea necesario. Sí. El **Mac mini puede ejecutar el Gateway**, y tu MacBook Pro puede conectarse como - **node** (dispositivo complementario). Los nodes no ejecutan el Gateway: proporcionan capacidades - adicionales como pantalla/cámara/canvas y `system.run` en ese dispositivo. + **node** (dispositivo complementario). Los nodes no ejecutan el Gateway; proporcionan + capacidades adicionales como pantalla/cámara/canvas y `system.run` en ese dispositivo. Patrón habitual: @@ -763,45 +764,45 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Bun **no se recomienda**. Vemos errores de tiempo de ejecución, especialmente con WhatsApp y Telegram. + Bun **no está recomendado**. Vemos errores en tiempo de ejecución, especialmente con WhatsApp y Telegram. Usa **Node** para gateways estables. - Si aun así quieres experimentar con Bun, hazlo en un gateway no productivo - sin WhatsApp/Telegram. + Si aun así quieres experimentar con Bun, hazlo en un gateway que no sea de producción + y sin WhatsApp/Telegram. `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 inicial acepta entrada `@username` y la resuelve a un ID numérico, pero la autorización de OpenClaw usa solo IDs numéricos. + La configuración solicita solo IDs de usuario numéricos. Si ya tienes entradas heredadas de `@username` en la configuración, `openclaw doctor --fix` puede intentar resolverlas. Más seguro (sin bot de terceros): - - Envía un DM a tu bot, luego ejecuta `openclaw logs --follow` y lee `from.id`. + - Envía un MD a tu bot y luego ejecuta `openclaw logs --follow` y lee `from.id`. API oficial de Bot: - - Envía un DM a tu bot, luego llama a `https://api.telegram.org/bot/getUpdates` y lee `message.from.id`. + - Envía un MD a tu bot y luego llama a `https://api.telegram.org/bot/getUpdates` y lee `message.from.id`. Terceros (menos privado): - - Envía un DM a `@userinfobot` o `@getidsbot`. + - Envía un MD a `@userinfobot` o `@getidsbot`. Consulta [/channels/telegram](/es/channels/telegram#access-control-and-activation). - Sí, mediante **enrutamiento multi-agent**. Vincula el **DM** de WhatsApp de cada remitente (peer `kind: "direct"`, remitente E.164 como `+15551234567`) a un `agentId` distinto, para que cada persona tenga su propio espacio de trabajo y almacenamiento de sesiones. Las respuestas siguen viniendo de la **misma cuenta de WhatsApp**, y el control de acceso de DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) es global por cuenta de WhatsApp. Consulta [Enrutamiento multi-agent](/es/concepts/multi-agent) y [WhatsApp](/es/channels/whatsapp). + Sí, mediante **enrutamiento multiagente**. Vincula el **MD** de WhatsApp de cada remitente (peer `kind: "direct"`, remitente E.164 como `+15551234567`) a un `agentId` distinto, para que cada persona tenga su propio workspace y almacén de sesiones. Las respuestas seguirán saliendo desde la **misma cuenta de WhatsApp**, y el control de acceso de MD (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) es global por cuenta de WhatsApp. Consulta [Enrutamiento multiagente](/es/concepts/multi-agent) y [WhatsApp](/es/channels/whatsapp). - - Sí. Usa enrutamiento multi-agent: da a cada agent su propio modelo predeterminado y luego vincula rutas de entrada (cuenta del proveedor o peers específicos) a cada agent. Hay un ejemplo de configuración en [Enrutamiento multi-agent](/es/concepts/multi-agent). Consulta también [Models](/es/concepts/models) y [Configuration](/es/gateway/configuration). + + Sí. Usa enrutamiento multiagente: da a cada agente su propio modelo predeterminado y luego vincula las rutas entrantes (cuenta del proveedor o peers específicos) a cada agente. Hay un ejemplo de configuración en [Enrutamiento multiagente](/es/concepts/multi-agent). Consulta también [Modelos](/es/concepts/models) y [Configuración](/es/gateway/configuration). - Sí. Homebrew soporta Linux (Linuxbrew). Configuración rápida: + Sí. Homebrew es compatible con Linux (Linuxbrew). Configuración rápida: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -810,25 +811,25 @@ para ver uso/facturación y aumenta los límites según sea necesario. brew install ``` - Si ejecutas OpenClaw mediante 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 sin login. - Las compilaciones recientes también anteponen directorios bin de usuario comunes en servicios Linux systemd (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 definidos. + Si ejecutas OpenClaw mediante 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 sin inicio de sesión. + Las compilaciones recientes también anteponen directorios bin de usuario comunes en 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 definidos. - **Instalación hackable (git):** checkout completo del código fuente, editable, ideal para colaboradores. - Ejecutas las compilaciones localmente y puedes modificar código/documentación. - - **npm install:** instalación global de la CLI, sin repositorio, ideal para "simplemente ejecutarlo". - Las actualizaciones llegan desde las dist-tags de npm. + Ejecutas las compilaciones localmente y puedes corregir código/documentación. + - **npm install:** instalación global de la CLI, sin repositorio, ideal para simplemente ejecutarlo. + Las actualizaciones vienen de los dist-tags de npm. Documentación: [Primeros pasos](/es/start/getting-started), [Actualización](/es/install/updating). - Sí. Instala la otra variante y luego ejecuta Doctor para que el servicio del gateway apunte al nuevo entrypoint. - Esto **no elimina tus datos**: solo cambia la instalación del código de OpenClaw. Tu estado - (`~/.openclaw`) y tu espacio de trabajo (`~/.openclaw/workspace`) permanecen intactos. + Sí. Instala la otra variante y luego ejecuta Doctor para que el servicio del gateway apunte al nuevo punto de entrada. + Esto **no elimina tus datos**; solo cambia la instalación del código de OpenClaw. Tu estado + (`~/.openclaw`) y workspace (`~/.openclaw/workspace`) permanecen intactos. De npm a git: @@ -849,7 +850,7 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw gateway restart ``` - Doctor detecta un desajuste en el entrypoint del servicio del gateway y ofrece reescribir la configuración del servicio para que coincida con la instalación actual (usa `--repair` en automatización). + Doctor detecta una discrepancia en el punto de entrada del servicio Gateway y ofrece reescribir la configuración del servicio para que coincida con la instalación actual (usa `--repair` en automatización). Consejos de copia de seguridad: consulta [Estrategia de copia de seguridad](#where-things-live-on-disk). @@ -857,59 +858,59 @@ para ver uso/facturación y aumenta los límites según sea necesario. Respuesta corta: **si quieres fiabilidad 24/7, usa un VPS**. Si quieres la - menor fricción y te da igual el reposo/los reinicios, ejecútalo localmente. + menor fricción y no te importan las suspensiones/reinicios, ejecútalo localmente. **Portátil (Gateway local)** - - **Ventajas:** sin coste de servidor, acceso directo a archivos locales, ventana del navegador visible en vivo. - - **Desventajas:** reposo/cortes de red = desconexiones, las actualizaciones/reinicios del SO interrumpen, debe permanecer activo. + - **Ventajas:** sin coste de servidor, acceso directo a archivos locales, ventana del navegador visible. + - **Desventajas:** suspensión/cortes de red = desconexiones, las actualizaciones/reinicios del SO interrumpen, debe permanecer encendido. **VPS / nube** - - **Ventajas:** siempre activo, red estable, sin problemas por el reposo del portátil, más fácil de mantener en ejecución. - - **Desventajas:** a menudo funciona en modo headless (usa capturas de pantalla), acceso solo remoto a archivos, debes usar SSH para actualizaciones. + - **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 interfaz (usa capturas de pantalla), acceso solo a archivos remotos, debes usar SSH para las actualizaciones. - **Nota específica de OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord funcionan bien desde un VPS. El único intercambio real es **navegador headless** frente a una ventana visible. Consulta [Browser](/es/tools/browser). + **Nota específica de OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord funcionan perfectamente desde un VPS. La única diferencia real es **navegador sin interfaz** frente a una ventana visible. Consulta [Browser](/es/tools/browser). - **Valor predeterminado recomendado:** VPS si antes tuviste desconexiones del gateway. Lo local es ideal cuando estás usando activamente el Mac y quieres acceso a archivos locales o automatización de UI con un navegador visible. + **Recomendación predeterminada:** VPS si antes tuviste desconexiones del gateway. Lo local es ideal cuando estás usando activamente el Mac y quieres acceso a archivos locales o automatización de UI con un navegador visible. - No es obligatorio, pero **sí recomendable para fiabilidad y aislamiento**. + No es obligatorio, pero **sí recomendable por fiabilidad y aislamiento**. - - **Host dedicado (VPS/Mac mini/Pi):** siempre activo, menos interrupciones por reposo/reinicio, permisos más limpios, más fácil de mantener en ejecución. - - **Portátil/escritorio compartido:** totalmente válido para pruebas y uso activo, pero espera pausas cuando la máquina entre en reposo o se actualice. + - **Host dedicado (VPS/Mac mini/Pi):** siempre activo, menos interrupciones por suspensión/reinicio, permisos más limpios, más fácil de mantener en ejecución. + - **Portátil/escritorio compartido:** totalmente válido para pruebas y uso activo, pero espera pausas cuando la máquina 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 **node** para herramientas locales de pantalla/cámara/exec. Consulta [Nodes](/es/nodes). - Para orientación de seguridad, lee [Security](/es/gateway/security). + Si quieres lo mejor de ambos mundos, mantén el Gateway en un host dedicado y empareja tu portátil como **node** para herramientas locales de pantalla/cámara/exec. Consulta [Nodes](/es/nodes). + Para orientación de seguridad, lee [Seguridad](/es/gateway/security). - + 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 margen (logs, medios, varios canales). Las herramientas de Node y la automatización del navegador pueden consumir bastantes recursos. + - **Mínimo absoluto:** 1 vCPU, 1 GB de RAM, ~500 MB de disco. + - **Recomendado:** 1-2 vCPU, 2 GB de RAM o más para tener margen (registros, medios, múltiples canales). Las herramientas de Node 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 está mejor probada allí. + SO: usa **Ubuntu LTS** (o cualquier Debian/Ubuntu moderno). La ruta de instalación de Linux está mejor probada ahí. Documentación: [Linux](/es/platforms/linux), [Hosting VPS](/es/vps). - Sí. Trata una VM igual que un VPS: debe estar siempre activa, ser accesible y tener suficiente + Sí. Trata una VM igual que un VPS: debe estar siempre encendida, accesible y tener suficiente RAM para el Gateway y cualquier canal que habilites. Guía base: - - **Mínimo absoluto:** 1 vCPU, 1GB de RAM. - - **Recomendado:** 2GB de RAM o más si ejecutas varios canales, automatización del navegador o herramientas multimedia. + - **Mínimo absoluto:** 1 vCPU, 1 GB de RAM. + - **Recomendado:** 2 GB de RAM o más si ejecutas múltiples canales, automatización del navegador o herramientas multimedia. - **SO:** Ubuntu LTS u otro Debian/Ubuntu moderno. - Si estás en Windows, **WSL2 es la configuración tipo VM más sencilla** y la que tiene mejor - compatibilidad de herramientas. Consulta [Windows](/es/platforms/windows), [Hosting VPS](/es/vps). + Si estás en Windows, **WSL2 es la configuración estilo VM más sencilla** y la que tiene la mejor compatibilidad + de herramientas. Consulta [Windows](/es/platforms/windows), [Hosting VPS](/es/vps). Si ejecutas macOS en una VM, consulta [VM de macOS](/es/install/macos-vm). @@ -919,39 +920,39 @@ para ver uso/facturación y aumenta los límites según sea necesario. - OpenClaw es un asistente de IA personal que ejecutas en tus propios dispositivos. Responde en las superficies de mensajería que ya usas (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat y plugins de canal incluidos como QQ Bot) y también puede ofrecer voz + un Canvas en vivo en las plataformas compatibles. El **Gateway** es el plano de control siempre activo; el asistente es el producto. + OpenClaw es un asistente personal de IA que ejecutas en tus propios dispositivos. Responde en las superficies de mensajería que ya usas (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat y plugins de canal incluidos como QQ Bot) y también puede ofrecer voz + un Canvas en vivo en plataformas compatibles. El **Gateway** es el plano de control siempre activo; el asistente es el producto. - OpenClaw no es "simplemente un wrapper de Claude". Es un **plano de control local-first** que te permite ejecutar un + OpenClaw no es "solo un wrapper de Claude". Es un **plano de control local-first** que te permite ejecutar un asistente capaz en **tu propio hardware**, accesible desde las 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. - Puntos destacados: + Aspectos destacados: - **Tus dispositivos, tus datos:** ejecuta el Gateway donde quieras (Mac, Linux, VPS) y mantén el - espacio de trabajo + historial de sesiones en local. - - **Canales reales, no un sandbox web:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc., - además de voz móvil y Canvas en las plataformas compatibles. - - **Agnóstico respecto al modelo:** usa Anthropic, OpenAI, MiniMax, OpenRouter, etc., con enrutamiento - por agent y failover. - - **Opción solo local:** ejecuta modelos locales para que **todos los datos puedan permanecer en tu dispositivo** si así lo deseas. - - **Enrutamiento multi-agent:** agents separados por canal, cuenta o tarea, cada uno con su propio - espacio de trabajo y valores predeterminados. - - **Open source y hackable:** inspecciónalo, extiéndelo y autoalójalo sin dependencia de proveedor. + workspace + historial de sesiones en local. + - **Canales reales, no una sandbox web:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc., + además de voz móvil y Canvas en plataformas compatibles. + - **Independiente del modelo:** usa Anthropic, OpenAI, MiniMax, OpenRouter, etc., con enrutamiento + por agente y conmutación por error. + - **Opción solo local:** ejecuta modelos locales para que **todos los datos puedan permanecer en tu dispositivo** si quieres. + - **Enrutamiento multiagente:** agentes separados por canal, cuenta o tarea, cada uno con su propio + workspace y valores predeterminados. + - **Código abierto y modificable:** inspecciónalo, amplíalo y autohospédalo sin dependencia de un proveedor. - Documentación: [Gateway](/es/gateway), [Channels](/es/channels), [Multi-agent](/es/concepts/multi-agent), - [Memory](/es/concepts/memory). + Documentación: [Gateway](/es/gateway), [Channels](/es/channels), [Multiagente](/es/concepts/multi-agent), + [Memoria](/es/concepts/memory). - + Buenos primeros proyectos: - Crear un sitio web (WordPress, Shopify o un sitio estático sencillo). - - Crear el prototipo de una app móvil (esquema, pantallas, plan de API). - - Organizar archivos y carpetas (limpieza, nombres, etiquetas). + - Prototipar una aplicación móvil (esquema, pantallas, plan de API). + - Organizar archivos y carpetas (limpieza, nombres, etiquetado). - Conectar Gmail y automatizar resúmenes o seguimientos. Puede manejar tareas grandes, pero funciona mejor cuando las divides en fases y @@ -960,42 +961,42 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Las ventajas cotidianas suelen ser: + Los usos cotidianos más útiles suelen verse así: - - **Informes personales:** resúmenes de la bandeja de entrada, el calendario y las noticias que te interesan. + - **Informes personales:** resúmenes de bandeja de entrada, calendario y noticias que te importan. - **Investigación y redacción:** investigación rápida, resúmenes y primeros borradores para correos o documentos. - **Recordatorios y seguimientos:** avisos y listas de verificación impulsados por Cron o Heartbeat. - **Automatización del navegador:** rellenar formularios, recopilar datos y repetir tareas web. - - **Coordinación entre dispositivos:** envía una tarea desde tu teléfono, deja que el Gateway la ejecute en un servidor y recibe el resultado de vuelta en el chat. + - **Coordinación entre dispositivos:** envía una tarea desde tu teléfono, deja que el Gateway la ejecute en un servidor y recibe el resultado en el chat. - - Sí para **investigación, cualificación y redacción**. Puede analizar sitios, crear listas cortas, - resumir prospectos y redactar borradores de outreach o texto publicitario. + + Sí para **investigación, cualificación y redacción**. Puede escanear sitios, crear listas cortas, + resumir prospectos y redactar borradores de mensajes de outreach o anuncios. - Para **outreach o campañas publicitarias**, mantén a una persona en el circuito. Evita el spam, sigue las leyes locales y - las políticas de la plataforma, y revisa todo antes de enviarlo. El patrón más seguro es dejar que + Para **campañas de outreach o anuncios**, mantén a una persona en el circuito. Evita el spam, cumple las leyes locales y + las políticas de la plataforma, y revisa cualquier contenido antes de enviarlo. El patrón más seguro es dejar que OpenClaw redacte y que tú apruebes. - Documentación: [Security](/es/gateway/security). + Documentación: [Seguridad](/es/gateway/security). - OpenClaw es un **asistente personal** y una capa de coordinación, no un sustituto del IDE. Usa - Claude Code o Codex para el bucle de programación directa más rápido dentro de un repositorio. Usa OpenClaw cuando quieras - memoria duradera, acceso entre dispositivos y orquestación de herramientas. + OpenClaw es un **asistente personal** y una capa de coordinación, no un reemplazo del IDE. Usa + Claude Code o Codex para el ciclo de programación directa más rápido dentro de un repositorio. Usa OpenClaw cuando + quieras memoria duradera, acceso entre dispositivos y orquestación de herramientas. Ventajas: - - **Memoria + espacio de trabajo persistentes** entre sesiones + - **Memoria + workspace persistentes** entre sesiones - **Acceso multiplataforma** (WhatsApp, Telegram, TUI, WebChat) - **Orquestación de herramientas** (navegador, archivos, programación, hooks) - **Gateway siempre activo** (ejecútalo en un VPS, interactúa desde cualquier lugar) - **Nodes** para navegador/pantalla/cámara/exec locales - Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) + Demostración: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1004,40 +1005,40 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Usa sobrescrituras administradas en lugar de editar la copia del repositorio. Pon tus cambios en `~/.openclaw/skills//SKILL.md` (o añade una carpeta mediante `skills.load.extraDirs` en `~/.openclaw/openclaw.json`). La precedencia es `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, por lo que las sobrescrituras administradas siguen teniendo prioridad sobre las Skills incluidas sin tocar git. Si necesitas la Skill instalada globalmente pero visible solo para algunos agents, mantén la copia compartida en `~/.openclaw/skills` y controla la visibilidad con `agents.defaults.skills` y `agents.list[].skills`. Solo las ediciones dignas de incorporarse upstream deberían vivir en el repositorio y salir como PRs. + Usa anulaciones gestionadas en lugar de editar la copia del repositorio. Pon tus cambios en `~/.openclaw/skills//SKILL.md` (o añade una carpeta mediante `skills.load.extraDirs` en `~/.openclaw/openclaw.json`). La precedencia es `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → incluidos → `skills.load.extraDirs`, así que las anulaciones gestionadas siguen teniendo prioridad sobre las Skills incluidas sin tocar git. Si necesitas que la skill se instale globalmente pero solo sea visible para algunos agentes, mantén la copia compartida en `~/.openclaw/skills` y controla la visibilidad con `agents.defaults.skills` y `agents.list[].skills`. Solo las ediciones que valga la pena enviar upstream deben vivir en el repositorio y salir como PR. - Sí. Añade directorios adicionales mediante `skills.load.extraDirs` en `~/.openclaw/openclaw.json` (la precedencia más baja). La precedencia predeterminada es `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` instala en `./skills` por defecto, que OpenClaw trata como `/skills` en la siguiente sesión. Si la Skill solo debe ser visible para ciertos agents, combínalo con `agents.defaults.skills` o `agents.list[].skills`. + Sí. Añade directorios adicionales mediante `skills.load.extraDirs` en `~/.openclaw/openclaw.json` (menor precedencia). La precedencia predeterminada es `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → incluidos → `skills.load.extraDirs`. `clawhub` instala en `./skills` de forma predeterminada, que OpenClaw trata como `/skills` en la siguiente sesión. Si la skill solo debe ser visible para determinados agentes, combínalo con `agents.defaults.skills` o `agents.list[].skills`. - - Hoy, los patrones compatibles son: + + Actualmente, los patrones compatibles son: - - **Trabajos Cron**: los trabajos aislados pueden establecer una sobrescritura `model` por trabajo. - - **Subagentes**: enruta tareas a agents separados con distintos modelos predeterminados. + - **Trabajos de Cron**: los trabajos aislados pueden establecer una anulación de `model` por trabajo. + - **Subagentes**: enruta tareas a agentes separados con distintos modelos predeterminados. - **Cambio bajo demanda**: usa `/model` para cambiar el modelo de la sesión actual en cualquier momento. - Consulta [Trabajos Cron](/es/automation/cron-jobs), [Enrutamiento Multi-Agent](/es/concepts/multi-agent) y [Comandos slash](/es/tools/slash-commands). + Consulta [Trabajos de Cron](/es/automation/cron-jobs), [Enrutamiento multiagente](/es/concepts/multi-agent) y [Comandos slash](/es/tools/slash-commands). - + Usa **subagentes** para tareas largas o paralelas. Los subagentes se ejecutan en su propia sesión, - devuelven un resumen y mantienen tu chat principal receptivo. + devuelven un resumen y mantienen tu chat principal con capacidad de respuesta. Pídele a tu bot que "genere un subagente para esta tarea" o usa `/subagents`. - Usa `/status` en el chat para ver qué está haciendo ahora mismo el Gateway (y si está ocupado). + Usa `/status` en el chat para ver qué está haciendo el Gateway ahora mismo (y si está ocupado). - Consejo sobre tokens: tanto las tareas largas como los subagentes consumen tokens. Si el coste es un problema, configura un + Consejo sobre tokens: las tareas largas y los subagentes consumen tokens. Si el coste es una preocupación, configura un modelo más barato para subagentes mediante `agents.defaults.subagents.model`. Documentación: [Subagentes](/es/tools/subagents), [Tareas en segundo plano](/es/automation/tasks). - - Usa vinculaciones de hilos. Puedes vincular un hilo de Discord a un subagente o a un objetivo de sesión para que los mensajes de seguimiento en ese hilo permanezcan en esa sesión vinculada. + + Usa vinculaciones de hilos. Puedes vincular un hilo de Discord a un subagente o a un destino de sesión para que los mensajes de seguimiento en ese hilo permanezcan en esa sesión vinculada. Flujo básico: @@ -1050,22 +1051,22 @@ para ver uso/facturación y aumenta los límites según sea necesario. Configuración necesaria: - Valores predeterminados globales: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Sobrescrituras de Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Vinculación automática al generar: establece `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Anulaciones de Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Vinculación automática al generar: configura `channels.discord.threadBindings.spawnSubagentSessions: true`. Documentación: [Subagentes](/es/tools/subagents), [Discord](/es/channels/discord), [Referencia de configuración](/es/gateway/configuration-reference), [Comandos slash](/es/tools/slash-commands). - + Comprueba primero la ruta del solicitante resuelta: - - La entrega de subagentes en modo finalización prefiere cualquier hilo vinculado o ruta de conversación cuando existe. - - Si el origen de la finalización solo lleva un canal, OpenClaw recurre a la ruta almacenada de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que la entrega directa aún pueda tener éxito. - - Si no existe ni una ruta vinculada ni una ruta almacenada utilizable, la entrega directa puede fallar y el resultado recurre en su lugar a la entrega en cola de la sesión en vez de publicarse inmediatamente en el chat. - - Los destinos no válidos o desactualizados aún pueden forzar el fallback a la cola o el fallo final de la entrega. - - Si la última respuesta visible del asistente del hijo es exactamente el token silencioso `NO_REPLY` / `no_reply`, o exactamente `ANNOUNCE_SKIP`, OpenClaw suprime intencionadamente el anuncio en vez de publicar un progreso anterior obsoleto. - - Si el hijo agotó el tiempo de espera después de solo llamadas a herramientas, el anuncio puede condensarlo en un breve resumen de progreso parcial en vez de reproducir la salida bruta de las herramientas. + - La entrega del subagente en modo finalización prioriza cualquier hilo vinculado o ruta de conversación cuando existe. + - 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 pueda seguir funcionando. + - Si no existe ni una ruta vinculada ni una ruta almacenada utilizable, la entrega directa puede fallar y el resultado vuelve a la entrega en cola de la sesión en lugar de publicarse inmediatamente en el chat. + - Los destinos no válidos o desactualizados pueden seguir forzando la vuelta a la cola o el fallo de la entrega final. + - Si la última respuesta visible del asistente hijo es exactamente el token silencioso `NO_REPLY` / `no_reply`, o exactamente `ANNOUNCE_SKIP`, OpenClaw suprime intencionadamente el anuncio en lugar de publicar un progreso anterior desactualizado. + - Si el hijo agotó el tiempo de espera después de solo llamadas a herramientas, el anuncio puede reducir eso a un breve resumen de progreso parcial en lugar de reproducir la salida sin procesar de las herramientas. Depuración: @@ -1073,18 +1074,18 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw tasks show ``` - Documentación: [Sub-agents](/es/tools/subagents), [Tareas en segundo plano](/es/automation/tasks), [Herramienta de sesión](/es/concepts/session-tool). + Documentación: [Subagentes](/es/tools/subagents), [Tareas en segundo plano](/es/automation/tasks), [Herramientas de sesión](/es/concepts/session-tool). - - Cron se ejecuta dentro del proceso Gateway. Si el Gateway no se está ejecutando continuamente, + + Cron se ejecuta dentro del proceso Gateway. Si el Gateway no se está ejecutando de forma continua, los trabajos programados no se ejecutarán. Lista de comprobación: - - Confirma que Cron está habilitado (`cron.enabled`) y que `OPENCLAW_SKIP_CRON` no está definido. - - Comprueba que el Gateway se está ejecutando 24/7 (sin reposo/reinicios). + - Confirma que Cron está habilitado (`cron.enabled`) y que `OPENCLAW_SKIP_CRON` no está configurado. + - Comprueba que el Gateway se está ejecutando 24/7 (sin suspensión/reinicios). - Verifica la configuración de zona horaria del trabajo (`--tz` frente a la zona horaria del host). Depuración: @@ -1094,21 +1095,21 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw cron runs --id --limit 50 ``` - Documentación: [Trabajos Cron](/es/automation/cron-jobs), [Automatización y tareas](/es/automation). + Documentación: [Trabajos de Cron](/es/automation/cron-jobs), [Automatización y tareas](/es/automation). - + Comprueba primero el modo de entrega: - `--no-deliver` / `delivery.mode: "none"` significa que no se espera ningún mensaje externo. - - La falta de un destino de anuncio (`channel` / `to`) o que sea no válido significa que el ejecutor omitió la entrega saliente. + - Un destino de anuncio faltante o no válido (`channel` / `to`) significa que el ejecutor omitió la entrega saliente. - Los fallos de autenticación del canal (`unauthorized`, `Forbidden`) significan que el ejecutor intentó entregar, pero las credenciales lo bloquearon. - - Un resultado aislado silencioso (`NO_REPLY` / `no_reply` únicamente) se trata como intencionadamente no entregable, por lo que el ejecutor también suprime la entrega de fallback en cola. + - Un resultado aislado silencioso (`NO_REPLY` / `no_reply` solamente) se trata como intencionadamente no entregable, así que el ejecutor también suprime la entrega de respaldo en cola. - Para trabajos Cron aislados, el ejecutor es el responsable de la entrega final. Se espera - que el agent devuelva un resumen en texto plano para que el ejecutor lo envíe. `--no-deliver` mantiene - ese resultado como interno; no permite que el agent envíe directamente con la + Para trabajos Cron aislados, el ejecutor es el responsable de la entrega final. Se espera que el agente + devuelva un resumen en texto plano para que el ejecutor lo envíe. `--no-deliver` mantiene + ese resultado interno; no permite que el agente envíe directamente con la herramienta de mensajes en su lugar. Depuración: @@ -1118,27 +1119,27 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw tasks show ``` - Documentación: [Trabajos Cron](/es/automation/cron-jobs), [Tareas en segundo plano](/es/automation/tasks). + Documentación: [Trabajos de Cron](/es/automation/cron-jobs), [Tareas en segundo plano](/es/automation/tasks). - - Normalmente esa es la ruta activa de cambio de modelo, no una programación duplicada. + + Normalmente esa es la ruta de cambio de modelo en vivo, no una programación duplicada. - Cron aislado puede persistir una cesión 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 sobrescritura del perfil de autenticación, Cron - también la persiste antes de reintentar. + Cron aislado puede conservar una transferencia de modelo en tiempo de ejecución y reintentar cuando la + ejecución activa lanza `LiveSessionModelSwitchError`. El reintento conserva el + proveedor/modelo cambiado, y si el cambio llevaba una nueva anulación de perfil de autenticación, Cron + también la conserva antes de reintentar. Reglas de selección relacionadas: - - La sobrescritura de modelo del hook de Gmail gana primero cuando corresponde. - - Luego `model` por trabajo. - - Luego cualquier sobrescritura de modelo almacenada de la sesión Cron. - - Luego la selección normal de modelo predeterminado/del agent. + - La anulación del modelo del hook de Gmail gana primero cuando corresponde. + - Luego el `model` por trabajo. + - Luego cualquier anulación de modelo almacenada para la sesión de Cron. + - Luego la selección normal del modelo del agente/predeterminado. - El bucle de reintento es limitado. Tras el intento inicial más 2 reintentos por cambio, - Cron se aborta en lugar de entrar en un bucle infinito. + El bucle de reintento es acotado. Después del intento inicial más 2 reintentos por cambio, + Cron aborta en lugar de entrar en un bucle infinito. Depuración: @@ -1147,12 +1148,12 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw tasks show ``` - Documentación: [Trabajos Cron](/es/automation/cron-jobs), [CLI de cron](/cli/cron). + Documentación: [Trabajos de Cron](/es/automation/cron-jobs), [CLI de Cron](/cli/cron). - Usa los comandos nativos `openclaw skills` o coloca Skills en tu espacio de trabajo. La UI de Skills de macOS no está disponible en Linux. + Usa los comandos nativos `openclaw skills` o coloca Skills en tu workspace. La UI de Skills de macOS no está disponible en Linux. Explora Skills en [https://clawhub.ai](https://clawhub.ai). ```bash @@ -1166,39 +1167,39 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw skills check ``` - La instalación nativa con `openclaw skills install` escribe en el directorio `skills/` - del espacio de trabajo activo. Instala la CLI separada `clawhub` solo si quieres publicar o - sincronizar tus propias Skills. Para instalaciones compartidas entre agents, coloca la Skill en + La instalación nativa `openclaw skills install` escribe en el directorio `skills/` + del workspace activo. Instala la CLI `clawhub` por separado solo si quieres publicar o + sincronizar tus propias Skills. Para instalaciones compartidas entre agentes, coloca la skill en `~/.openclaw/skills` y usa `agents.defaults.skills` o - `agents.list[].skills` si quieres limitar qué agents pueden verla. + `agents.list[].skills` si quieres limitar qué agentes pueden verla. - + Sí. Usa el programador del Gateway: - - **Trabajos Cron** para tareas programadas o recurrentes (persisten tras reinicios). + - **Trabajos de Cron** para tareas programadas o recurrentes (persisten entre reinicios). - **Heartbeat** para comprobaciones periódicas de la "sesión principal". - - **Trabajos aislados** para agents autónomos que publican resúmenes o entregan en chats. + - **Trabajos aislados** para agentes autónomos que publican resúmenes o entregan en chats. - Documentación: [Trabajos Cron](/es/automation/cron-jobs), [Automatización y tareas](/es/automation), + Documentación: [Trabajos de Cron](/es/automation/cron-jobs), [Automatización y tareas](/es/automation), [Heartbeat](/es/gateway/heartbeat). - - No directamente. Las Skills de macOS están controladas por `metadata.openclaw.os` más los binarios requeridos, y las Skills solo aparecen en el prompt del sistema cuando son aptas en el **host Gateway**. En Linux, las Skills exclusivas de `darwin` (como `apple-notes`, `apple-reminders`, `things-mac`) no se cargarán a menos que sobrescribas esa restricción. + + No directamente. Las Skills de macOS están controladas por `metadata.openclaw.os` más los binarios requeridos, y las Skills solo aparecen en el prompt del sistema cuando son aptas en el **host del Gateway**. En Linux, las Skills exclusivas de `darwin` (como `apple-notes`, `apple-reminders`, `things-mac`) no se cargarán a menos que anules esa restricción. Tienes tres patrones compatibles: - **Opción A: ejecutar el Gateway en un Mac (lo más sencillo).** - Ejecuta el Gateway donde existan los binarios de macOS y luego conéctate desde Linux en [modo remoto](#gateway-ports-already-running-and-remote-mode) o mediante Tailscale. Las Skills se cargan normalmente porque el host Gateway es macOS. + **Opción A - ejecutar el Gateway en un Mac (lo más simple).** + Ejecuta el Gateway donde existan los binarios de macOS y luego conéctate desde Linux en [modo remoto](#gateway-ports-already-running-and-remote-mode) o mediante Tailscale. Las Skills se cargan normalmente porque el host del Gateway es macOS. - **Opción B: usar un node de macOS (sin SSH).** - Ejecuta el Gateway en Linux, empareja un node de macOS (app de barra de menús) y configura **Node Run Commands** como "Always Ask" o "Always Allow" en el Mac. OpenClaw puede tratar las Skills exclusivas de macOS como aptas cuando los binarios requeridos existen en el node. El agent ejecuta esas Skills mediante la herramienta `nodes`. Si eliges "Always Ask", aprobar "Always Allow" en el prompt añade ese comando a la allowlist. + **Opción B - usar un node de macOS (sin SSH).** + Ejecuta el Gateway en Linux, empareja un node de macOS (app de barra de menús) y configura **Node Run Commands** como "Always Ask" o "Always Allow" en el Mac. OpenClaw puede tratar las Skills exclusivas de macOS como aptas cuando los binarios requeridos existen en el node. El agente ejecuta esas Skills mediante la herramienta `nodes`. Si eliges "Always Ask", aprobar "Always Allow" en el prompt añade ese comando a la lista de permitidos. - **Opción C: usar proxy de binarios de macOS mediante SSH (avanzado).** - Mantén el Gateway en Linux, pero haz que los binarios CLI necesarios resuelvan a wrappers SSH que se ejecuten en un Mac. Luego sobrescribe la Skill para permitir Linux y que siga siendo apta. + **Opción C - usar proxy de binarios de macOS mediante SSH (avanzado).** + Mantén el Gateway en Linux, pero haz que los binarios CLI requeridos se resuelvan a wrappers SSH que se ejecuten en un Mac. Luego anula la skill para permitir Linux y que siga siendo apta. 1. Crea un wrapper SSH para el binario (ejemplo: `memo` para Apple Notes): @@ -1209,12 +1210,12 @@ para ver uso/facturación y aumenta los límites según sea necesario. ``` 2. Coloca el wrapper en `PATH` en el host Linux (por ejemplo `~/bin/memo`). - 3. Sobrescribe los metadatos de la Skill (espacio de trabajo o `~/.openclaw/skills`) para permitir Linux: + 3. Anula los metadatos de la skill (workspace o `~/.openclaw/skills`) para permitir Linux: ```markdown --- name: apple-notes - description: Manage Apple Notes via the memo CLI on macOS. + description: Gestiona Apple Notes mediante la CLI memo en macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` @@ -1224,19 +1225,19 @@ para ver uso/facturación y aumenta los límites según sea necesario. - No incluida de forma nativa hoy. + No incorporada por ahora. Opciones: - - **Skill / Plugin personalizado:** lo mejor para un acceso fiable a la API (tanto Notion como HeyGen tienen API). + - **Skill / Plugin personalizado:** ideal para acceso fiable a la API (Notion y HeyGen tienen API). - **Automatización del navegador:** funciona sin código, pero es más lenta y frágil. Si quieres mantener contexto por cliente (flujos de trabajo de agencia), un patrón sencillo es: - Una página de Notion por cliente (contexto + preferencias + trabajo activo). - - Pedir al agent que recupere esa página al inicio de una sesión. + - Pedir al agente que recupere esa página al comienzo de una sesión. - Si quieres una integración nativa, abre una solicitud de funcionalidad o crea una Skill + Si quieres una integración nativa, abre una solicitud de función o crea una skill orientada a esas API. Instalar Skills: @@ -1246,12 +1247,12 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw skills update --all ``` - Las instalaciones nativas van al directorio `skills/` del espacio de trabajo activo. Para Skills compartidas entre agents, colócalas en `~/.openclaw/skills//SKILL.md`. Si solo algunos agents deben ver una instalación compartida, configura `agents.defaults.skills` o `agents.list[].skills`. Algunas Skills esperan binarios instalados mediante Homebrew; en Linux eso significa Linuxbrew (consulta la entrada de preguntas frecuentes sobre Homebrew en Linux anterior). Consulta [Skills](/es/tools/skills), [Configuración de Skills](/es/tools/skills-config) y [ClawHub](/es/tools/clawhub). + Las instalaciones nativas se colocan en el directorio `skills/` del workspace activo. Para Skills compartidas entre agentes, colócalas en `~/.openclaw/skills//SKILL.md`. Si solo algunos agentes deben ver una instalación compartida, configura `agents.defaults.skills` o `agents.list[].skills`. Algunas Skills esperan binarios instalados mediante Homebrew; en Linux eso significa Linuxbrew (consulta la entrada de preguntas frecuentes sobre Homebrew en Linux más arriba). Consulta [Skills](/es/tools/skills), [Configuración de Skills](/es/tools/skills-config) y [ClawHub](/es/tools/clawhub). - - Usa el perfil de navegador integrado `user`, que se conecta mediante Chrome DevTools MCP: + + Usa el perfil de navegador integrado `user`, que se conecta a través de Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs @@ -1265,13 +1266,13 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw browser --browser-profile chrome-live tabs ``` - Esta ruta es local al host. Si el Gateway se ejecuta en otro lugar, ejecuta un host de node en la máquina del navegador o usa CDP remoto. + Esta ruta puede usar el navegador del host local o un browser node conectado. Si el Gateway se ejecuta en otro lugar, ejecuta un host de node en la máquina del navegador o usa CDP remoto. Límites actuales de `existing-session` / `user`: - - las acciones están guiadas por ref, no por selectores CSS - - las subidas requieren `ref` / `inputRef` y actualmente admiten un archivo cada vez - - `responsebody`, exportación PDF, interceptación de descargas y acciones por lotes siguen necesitando un navegador gestionado o un perfil CDP sin procesar + - las acciones están basadas en refs, no en selectores CSS + - las cargas requieren `ref` / `inputRef` y actualmente admiten un archivo a la vez + - `responsebody`, exportación a PDF, interceptación de descargas y acciones por lotes siguen necesitando un navegador gestionado o un perfil CDP sin procesar @@ -1279,151 +1280,150 @@ para ver uso/facturación y aumenta los límites según sea necesario. ## Sandboxing y memoria - - Sí. Consulta [Sandboxing](/es/gateway/sandboxing). Para la configuración específica de Docker (gateway completo en Docker o imágenes de sandbox), consulta [Docker](/es/install/docker). + + Sí. Consulta [Sandboxing](/es/gateway/sandboxing). Para configuración específica de Docker (Gateway completo en Docker o imágenes de sandbox), consulta [Docker](/es/install/docker). - + La imagen predeterminada prioriza la seguridad y se ejecuta como el usuario `node`, por lo que no incluye paquetes del sistema, Homebrew ni navegadores incluidos. Para una configuración más completa: - - Haz persistente `/home/node` con `OPENCLAW_HOME_VOLUME` para que las cachés sobrevivan. + - Conserva `/home/node` con `OPENCLAW_HOME_VOLUME` para que las cachés sobrevivan. - Incorpora dependencias del sistema en la imagen con `OPENCLAW_DOCKER_APT_PACKAGES`. - - Instala navegadores Playwright mediante la CLI incluida: + - Instala navegadores de Playwright mediante la CLI incluida: `node /app/node_modules/playwright-core/cli.js install chromium` - - Establece `PLAYWRIGHT_BROWSERS_PATH` y asegúrate de que la ruta sea persistente. + - Configura `PLAYWRIGHT_BROWSERS_PATH` y asegúrate de que la ruta sea persistente. Documentación: [Docker](/es/install/docker), [Browser](/es/tools/browser). - - Sí, si tu tráfico privado son **DM** y tu tráfico público son **grupos**. + + Sí, si tu tráfico privado son **MD** y tu tráfico público son **grupos**. - Usa `agents.defaults.sandbox.mode: "non-main"` para que las sesiones de grupo/canal (claves no principales) se ejecuten en Docker, mientras la sesión principal de DM permanece en el host. Luego restringe qué herramientas están disponibles en las sesiones en sandbox mediante `tools.sandbox.tools`. + Usa `agents.defaults.sandbox.mode: "non-main"` para que las sesiones de grupo/canal (claves no principales) se ejecuten en Docker, mientras la sesión principal de MD permanece en el host. Luego restringe qué herramientas están disponibles en las sesiones en sandbox mediante `tools.sandbox.tools`. - Guía de configuración + ejemplo: [Grupos: DM personales + grupos públicos](/es/channels/groups#pattern-personal-dms-public-groups-single-agent) + Guía de configuración + ejemplo de configuración: [Grupos: MD personales + grupos públicos](/es/channels/groups#pattern-personal-dms-public-groups-single-agent) Referencia clave de configuración: [Configuración del Gateway](/es/gateway/configuration-reference#agentsdefaultssandbox) - Establece `agents.defaults.sandbox.docker.binds` en `["host:path:mode"]` (por ejemplo, `"/home/user/src:/src:ro"`). Las vinculaciones globales y por agent se fusionan; las vinculaciones por agent se ignoran cuando `scope: "shared"`. Usa `:ro` para cualquier contenido sensible y recuerda que las vinculaciones omiten las barreras del sistema de archivos del sandbox. + Configura `agents.defaults.sandbox.docker.binds` como `["host:path:mode"]` (por ejemplo `"/home/user/src:/src:ro"`). Los vínculos globales + por agente se combinan; los vínculos por agente se ignoran cuando `scope: "shared"`. Usa `:ro` para cualquier cosa sensible y recuerda que los vínculos evitan las barreras del sistema de archivos del sandbox. - OpenClaw valida los orígenes de bind tanto con la ruta normalizada como con la ruta canónica resuelta a través del ancestro existente más profundo. Eso significa que los escapes mediante un padre con symlink siguen fallando de forma segura incluso cuando el último segmento de la ruta todavía no existe, y las comprobaciones de raíz permitida siguen aplicándose después de la resolución del symlink. + OpenClaw valida los orígenes de bind tanto con la ruta normalizada como con la ruta canónica resuelta a través del ancestro existente más profundo. Eso significa que los escapes mediante padres con symlink siguen fallando de forma cerrada incluso cuando el último segmento de la ruta todavía no existe, y las comprobaciones de raíz permitida siguen aplicándose después de la resolución de symlink. Consulta [Sandboxing](/es/gateway/sandboxing#custom-bind-mounts) y [Sandbox vs Tool Policy vs Elevated](/es/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) para ver ejemplos y notas de seguridad. - La memoria de OpenClaw son simplemente archivos Markdown en el espacio de trabajo del agent: + La memoria de OpenClaw son simplemente archivos Markdown en el workspace del agente: - Notas diarias en `memory/YYYY-MM-DD.md` - - Notas curadas a largo plazo en `MEMORY.md` (solo sesiones principales/privadas) + - Notas seleccionadas a largo plazo en `MEMORY.md` (solo sesiones principales/privadas) - OpenClaw también ejecuta un **vaciado silencioso de memoria previo a la compactación** para recordarle al modelo - que escriba notas duraderas antes de la autocompactación. Esto solo se ejecuta cuando el espacio de trabajo - tiene permisos de escritura (los sandboxes de solo lectura lo omiten). Consulta [Memory](/es/concepts/memory). + OpenClaw también ejecuta un **vaciado silencioso de memoria previo a la Compaction** para recordarle al modelo + que escriba notas duraderas antes de la Compaction automática. Esto solo se ejecuta cuando el workspace + se puede escribir (los sandboxes de solo lectura lo omiten). Consulta [Memoria](/es/concepts/memory). - - Pídele al bot que **escriba el hecho en la memoria**. Las notas a largo plazo van en `MEMORY.md`, - el contexto a corto plazo va en `memory/YYYY-MM-DD.md`. + + Pídele al bot que **escriba el dato en la memoria**. Las notas a largo plazo pertenecen a `MEMORY.md`, + y el contexto a corto plazo va en `memory/YYYY-MM-DD.md`. - Esta sigue siendo un área que estamos mejorando. Ayuda recordarle al modelo que almacene recuerdos; + Esta sigue siendo un área que estamos mejorando. Ayuda recordarle al modelo que almacene memorias; sabrá qué hacer. Si sigue olvidando, verifica que el Gateway esté usando el mismo - espacio de trabajo en cada ejecución. + workspace en cada ejecución. - Documentación: [Memory](/es/concepts/memory), [Espacio de trabajo del agent](/es/concepts/agent-workspace). + Documentación: [Memoria](/es/concepts/memory), [Workspace del agente](/es/concepts/agent-workspace). - Los archivos de memoria viven en disco y persisten hasta que los eliminas. El límite es tu - almacenamiento, no el modelo. El **contexto de sesión** sigue estando limitado por la ventana de contexto - del modelo, así que las conversaciones largas pueden compactarse o truncarse. Por eso - existe la búsqueda en memoria: recupera solo las partes relevantes al contexto. + Los archivos de memoria viven en el disco y persisten hasta que los eliminas. El límite es tu + almacenamiento, no el modelo. El **contexto de la sesión** sigue estando limitado por la ventana de contexto + del modelo, por lo que las conversaciones largas pueden compactarse o truncarse. Por eso + existe la búsqueda en memoria: recupera solo las partes relevantes dentro del contexto. - Documentación: [Memory](/es/concepts/memory), [Context](/es/concepts/context). + Documentación: [Memoria](/es/concepts/memory), [Contexto](/es/concepts/context). Solo si usas **embeddings de OpenAI**. Codex OAuth cubre chat/completions y **no** concede acceso a embeddings, así que **iniciar sesión con Codex (OAuth o el - inicio de sesión de la CLI de Codex)** no ayuda para la búsqueda semántica en memoria. Los embeddings de OpenAI + inicio de sesión de Codex CLI)** no ayuda para la búsqueda semántica en memoria. Los embeddings de OpenAI siguen necesitando una clave de API real (`OPENAI_API_KEY` o `models.providers.openai.apiKey`). - Si no estableces explícitamente un proveedor, OpenClaw selecciona automáticamente uno cuando + Si no configuras un proveedor explícitamente, OpenClaw selecciona automáticamente un proveedor cuando puede resolver una clave de API (perfiles de autenticación, `models.providers.*.apiKey` o variables de entorno). - Prefiere OpenAI si se resuelve una clave de OpenAI; de lo contrario Gemini si se resuelve una clave de Gemini; - luego Voyage y después Mistral. Si no hay ninguna clave remota disponible, la - búsqueda en memoria permanece desactivada hasta que la configures. Si tienes una ruta de modelo local - configurada y presente, OpenClaw - prefiere `local`. Ollama es compatible cuando estableces explícitamente + Prefiere OpenAI si se resuelve una clave de OpenAI; en caso contrario Gemini si se resuelve una clave de Gemini; + luego Voyage; luego Mistral. Si no hay ninguna clave remota disponible, la búsqueda en memoria + permanece deshabilitada hasta que la configures. Si tienes configurada y presente una ruta de modelo local, OpenClaw + prefiere `local`. Ollama es compatible cuando configuras explícitamente `memorySearch.provider = "ollama"`. - Si prefieres seguir en local, establece `memorySearch.provider = "local"` (y opcionalmente - `memorySearch.fallback = "none"`). Si quieres embeddings de Gemini, establece + Si prefieres mantenerlo local, configura `memorySearch.provider = "local"` (y opcionalmente + `memorySearch.fallback = "none"`). Si quieres embeddings de Gemini, configura `memorySearch.provider = "gemini"` y proporciona `GEMINI_API_KEY` (o - `memorySearch.remote.apiKey`). Soportamos modelos de embedding de **OpenAI, Gemini, Voyage, Mistral, Ollama o local**; - consulta [Memory](/es/concepts/memory) para los detalles de configuración. + `memorySearch.remote.apiKey`). Admitimos modelos de embedding de **OpenAI, Gemini, Voyage, Mistral, Ollama o locales**; + consulta [Memoria](/es/concepts/memory) para conocer los detalles de configuración. -## Dónde están las cosas en disco +## Dónde viven las cosas en el disco No: **el estado de OpenClaw es local**, pero **los servicios externos siguen viendo lo que les envías**. - - **Local por defecto:** las sesiones, archivos de memoria, configuración y espacio de trabajo viven en el host Gateway - (`~/.openclaw` + tu directorio de espacio de trabajo). + - **Local por defecto:** las sesiones, archivos de memoria, configuración y workspace viven en el host del Gateway + (`~/.openclaw` + tu directorio de workspace). - **Remoto por necesidad:** los mensajes que envías a proveedores de modelos (Anthropic/OpenAI/etc.) van a - sus API, y las plataformas de chat (WhatsApp/Telegram/Slack/etc.) almacenan los datos de los mensajes en - sus servidores. - - **Tú controlas la huella:** usar modelos locales mantiene los prompts en tu máquina, pero el - tráfico de canales sigue pasando por los servidores del canal. + sus API, y las plataformas de chat (WhatsApp/Telegram/Slack/etc.) almacenan los datos de los mensajes en sus + servidores. + - **Tú controlas la huella:** usar modelos locales mantiene los prompts en tu máquina, pero el tráfico + del canal sigue pasando por los servidores del canal. - Relacionado: [Espacio de trabajo del agent](/es/concepts/agent-workspace), [Memory](/es/concepts/memory). + Relacionado: [Workspace del agente](/es/concepts/agent-workspace), [Memoria](/es/concepts/memory). - Todo vive bajo `$OPENCLAW_STATE_DIR` (valor predeterminado: `~/.openclaw`): + Todo vive bajo `$OPENCLAW_STATE_DIR` (predeterminado: `~/.openclaw`): - | Path | Purpose | + | Path | Propósito | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | Configuración principal (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Importación heredada de OAuth (copiada a perfiles de autenticación en el primer uso) | + | `$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 de API y `keyRef`/`tokenRef` opcionales) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Carga útil opcional de secretos basada en archivos para proveedores `file` de SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Archivo heredado de compatibilidad (entradas estáticas `api_key` depuradas) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Carga útil opcional de secretos respaldada por archivos para proveedores `file` de SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Archivo de compatibilidad heredado (entradas estáticas `api_key` depuradas) | | `$OPENCLAW_STATE_DIR/credentials/` | Estado del proveedor (por ejemplo `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Estado por agent (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Historial y estado de conversaciones (por agent) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadatos de sesión (por agent) | + | `$OPENCLAW_STATE_DIR/agents/` | Estado por agente (agentDir + sesiones) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Historial y estado de conversación (por agente) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadatos de sesión (por agente) | - Ruta heredada de agent único: `~/.openclaw/agent/*` (migrada por `openclaw doctor`). + Ruta heredada de agente único: `~/.openclaw/agent/*` (migrada por `openclaw doctor`). - Tu **espacio de trabajo** (`AGENTS.md`, archivos de memoria, Skills, etc.) es independiente y se configura mediante `agents.defaults.workspace` (predeterminado: `~/.openclaw/workspace`). + Tu **workspace** (`AGENTS.md`, archivos de memoria, Skills, etc.) es independiente y se configura mediante `agents.defaults.workspace` (predeterminado: `~/.openclaw/workspace`). - Estos archivos viven en el **espacio de trabajo del agent**, no en `~/.openclaw`. + Estos archivos viven en el **workspace del agente**, no en `~/.openclaw`. - - **Espacio de trabajo (por agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + - **Workspace (por agente)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md` (o el fallback heredado `memory.md` cuando `MEMORY.md` no existe), `memory/YYYY-MM-DD.md`, `HEARTBEAT.md` opcional. - - **Directorio de estado (`~/.openclaw`)**: configuración, estado de canal/proveedor, perfiles de autenticación, sesiones, logs + - **Directorio de estado (`~/.openclaw`)**: configuración, estado de canal/proveedor, perfiles de autenticación, sesiones, registros, y Skills compartidas (`~/.openclaw/skills`). - El espacio de trabajo predeterminado es `~/.openclaw/workspace`, configurable mediante: + El workspace predeterminado es `~/.openclaw/workspace`, configurable mediante: ```json5 { @@ -1432,41 +1432,41 @@ para ver uso/facturación y aumenta los límites según sea necesario. ``` Si el bot "olvida" después de un reinicio, confirma que el Gateway esté usando el mismo - espacio de trabajo en cada inicio (y recuerda: el modo remoto usa el espacio de trabajo del **host del gateway**, + workspace en cada inicio (y recuerda: el modo remoto usa el workspace del **host del gateway**, no el de tu portátil local). Consejo: si quieres un comportamiento o preferencia duraderos, pídele al bot que **lo escriba en - AGENTS.md o MEMORY.md** en lugar de depender del historial del chat. + AGENTS.md o MEMORY.md** en lugar de confiar en el historial del chat. - Consulta [Espacio de trabajo del agent](/es/concepts/agent-workspace) y [Memory](/es/concepts/memory). + Consulta [Workspace del agente](/es/concepts/agent-workspace) y [Memoria](/es/concepts/memory). - Pon tu **espacio de trabajo del agent** en un repositorio git **privado** y haz una copia de seguridad en algún lugar + Pon tu **workspace del agente** en un repositorio git **privado** y haz una copia de seguridad en algún lugar privado (por ejemplo GitHub privado). Esto captura la memoria + los archivos AGENTS/SOUL/USER - y te permite restaurar más tarde la "mente" del asistente. + y te permite restaurar más adelante la "mente" del asistente. - **No** hagas commit de nada bajo `~/.openclaw` (credenciales, sesiones, tokens o cargas útiles de secretos cifradas). - Si necesitas una restauración completa, haz copias de seguridad tanto del espacio de trabajo como del directorio de estado - por separado (consulta la pregunta sobre migración anterior). + **No** hagas commit de nada bajo `~/.openclaw` (credenciales, sesiones, tokens o cargas útiles de secretos cifrados). + Si necesitas una restauración completa, haz copia de seguridad del workspace y del directorio de estado + por separado (consulta la pregunta de migración anterior). - Documentación: [Espacio de trabajo del agent](/es/concepts/agent-workspace). + Documentación: [Workspace del agente](/es/concepts/agent-workspace). - Consulta la guía específica: [Uninstall](/es/install/uninstall). + Consulta la guía dedicada: [Desinstalación](/es/install/uninstall). - - Sí. El espacio de trabajo es el **cwd predeterminado** y el ancla de memoria, no un sandbox rígido. - Las rutas relativas se resuelven dentro del espacio de trabajo, pero las rutas absolutas pueden acceder a otras + + Sí. El workspace es el **cwd predeterminado** y el ancla de memoria, no un sandbox rígido. + Las rutas relativas se resuelven dentro del workspace, pero las rutas absolutas pueden acceder a otras ubicaciones del host a menos que el sandboxing esté habilitado. Si necesitas aislamiento, usa - [`agents.defaults.sandbox`](/es/gateway/sandboxing) o la configuración de sandbox por agent. Si + [`agents.defaults.sandbox`](/es/gateway/sandboxing) o la configuración de sandbox por agente. Si quieres que un repositorio sea el directorio de trabajo predeterminado, apunta el - `workspace` de ese agent a la raíz del repositorio. El repositorio de OpenClaw es solo código fuente; mantén el - espacio de trabajo separado, salvo que quieras intencionadamente que el agent trabaje dentro de él. + `workspace` de ese agente a la raíz del repositorio. El repositorio de OpenClaw es solo código fuente; mantén el + workspace separado a menos que intencionadamente quieras que el agente trabaje dentro de él. Ejemplo (repositorio como cwd predeterminado): @@ -1482,8 +1482,8 @@ para ver uso/facturación y aumenta los límites según sea necesario. - - El estado de las sesiones pertenece al **host del gateway**. Si estás en modo remoto, el almacenamiento de sesiones que te importa está en la máquina remota, no en tu portátil local. Consulta [Gestión de sesiones](/es/concepts/session). + + El estado de la sesión pertenece al **host del gateway**. Si estás en modo remoto, el almacén de sesiones que te importa está en la máquina remota, no en tu portátil local. Consulta [Gestión de sesiones](/es/concepts/session). @@ -1491,21 +1491,21 @@ para ver uso/facturación y aumenta los límites según sea necesario. - OpenClaw lee una configuración opcional en **JSON5** desde `$OPENCLAW_CONFIG_PATH` (predeterminado: `~/.openclaw/openclaw.json`): + OpenClaw lee una configuración opcional **JSON5** desde `$OPENCLAW_CONFIG_PATH` (predeterminado: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Si el archivo no existe, usa valores predeterminados razonablemente seguros (incluido un espacio de trabajo predeterminado de `~/.openclaw/workspace`). + Si falta el archivo, usa valores predeterminados razonablemente seguros (incluido un workspace predeterminado de `~/.openclaw/workspace`). - - Los bind no loopback **requieren una ruta válida de autenticación del gateway**. En la práctica eso significa: + + Los enlaces que no son loopback **requieren una ruta de autenticación de gateway válida**. En la práctica eso significa: - autenticación con secreto compartido: token o contraseña - - `gateway.auth.mode: "trusted-proxy"` detrás de un proxy inverso con reconocimiento de identidad no loopback configurado correctamente + - `gateway.auth.mode: "trusted-proxy"` detrás de un proxy inverso con reconocimiento de identidad que no sea loopback y esté configurado correctamente ```json5 { @@ -1521,32 +1521,32 @@ para ver uso/facturación y aumenta los límites según sea necesario. Notas: - - `gateway.remote.token` / `.password` **no** habilitan por sí solos la autenticación del gateway local. - - Las rutas de llamada locales pueden usar `gateway.remote.*` como fallback solo cuando `gateway.auth.*` no está configurado. - - Para autenticación por contraseña, establece `gateway.auth.mode: "password"` más `gateway.auth.password` (o `OPENCLAW_GATEWAY_PASSWORD`) en su lugar. - - Si `gateway.auth.token` / `gateway.auth.password` se configuran explícitamente mediante SecretRef y no se resuelven, la resolución falla de forma segura (sin ocultar el problema mediante fallback remoto). - - Las configuraciones de Control UI con secreto compartido se autentican mediante `connect.params.auth.token` o `connect.params.auth.password` (almacenados en la configuración de la app/UI). Los modos con identidad, como Tailscale Serve o `trusted-proxy`, usan en su lugar encabezados de solicitud. Evita poner secretos compartidos en URL. - - Con `gateway.auth.mode: "trusted-proxy"`, los proxies inversos loopback en el mismo host **tampoco** satisfacen la autenticación de trusted-proxy. El trusted proxy debe ser una fuente no loopback configurada. + - `gateway.remote.token` / `.password` por sí solos **no** habilitan la autenticación del gateway local. + - Las rutas de llamada local pueden usar `gateway.remote.*` como respaldo solo cuando `gateway.auth.*` no está configurado. + - Para autenticación con contraseña, configura `gateway.auth.mode: "password"` junto con `gateway.auth.password` (o `OPENCLAW_GATEWAY_PASSWORD`) en su lugar. + - Si `gateway.auth.token` / `gateway.auth.password` está configurado explícitamente mediante SecretRef y no se resuelve, la resolución falla de forma cerrada (sin que el respaldo remoto lo oculte). + - Las configuraciones de Control UI con secreto compartido se autentican mediante `connect.params.auth.token` o `connect.params.auth.password` (almacenados en la configuración de la app/UI). Los modos con identidad, como Tailscale Serve o `trusted-proxy`, usan encabezados de solicitud en su lugar. Evita poner secretos compartidos en las URL. + - Con `gateway.auth.mode: "trusted-proxy"`, los proxies inversos loopback del mismo host siguen **sin** satisfacer la autenticación de trusted-proxy. El proxy de confianza debe ser una fuente no loopback configurada. - OpenClaw aplica autenticación del gateway por defecto, incluido loopback. En la ruta predeterminada normal eso significa autenticación por token: si no hay una ruta de autenticación explícita configurada, el inicio del gateway se resuelve al modo token y genera uno automáticamente, guardándolo en `gateway.auth.token`, por lo que **los clientes WS locales deben autenticarse**. Esto impide que otros procesos locales llamen al Gateway. + OpenClaw aplica autenticación del gateway de forma predeterminada, incluido loopback. En la ruta predeterminada normal eso significa autenticación por token: si no hay ninguna ruta de autenticación explícita configurada, el inicio del gateway se resuelve en modo token y genera uno automáticamente, guardándolo en `gateway.auth.token`, por lo que **los clientes WS locales deben autenticarse**. Esto bloquea que otros procesos locales llamen al Gateway. - Si prefieres otra ruta de autenticación, puedes elegir explícitamente el modo contraseña (o, para proxies inversos no loopback con reconocimiento de identidad, `trusted-proxy`). Si **de verdad** quieres loopback abierto, establece explícitamente `gateway.auth.mode: "none"` en tu configuración. Doctor puede generarte un token en cualquier momento: `openclaw doctor --generate-gateway-token`. + Si prefieres una ruta de autenticación diferente, puedes elegir explícitamente el modo contraseña (o, para proxies inversos con reconocimiento de identidad que no sean loopback, `trusted-proxy`). Si **realmente** quieres loopback abierto, configura `gateway.auth.mode: "none"` explícitamente en tu configuración. Doctor puede generarte un token en cualquier momento: `openclaw doctor --generate-gateway-token`. - El Gateway supervisa la configuración y soporta recarga en caliente: + El Gateway observa la configuración y admite recarga en caliente: - `gateway.reload.mode: "hybrid"` (predeterminado): aplica en caliente los cambios seguros, reinicia para los críticos - - También se soportan `hot`, `restart` y `off` + - También se admiten `hot`, `restart` y `off` - - Establece `cli.banner.taglineMode` en la configuración: + + Configura `cli.banner.taglineMode` en la configuración: ```json5 { @@ -1558,21 +1558,21 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - - `off`: oculta el texto del lema pero mantiene la línea del título/versión del banner. + - `off`: oculta el texto del lema, pero mantiene la línea del título/versión del banner. - `default`: usa `All your chats, one OpenClaw.` siempre. - - `random`: lemas rotativos divertidos/de temporada (comportamiento predeterminado). - - Si no quieres ningún banner, establece la variable de entorno `OPENCLAW_HIDE_BANNER=1`. + - `random`: lemas graciosos/de temporada rotativos (comportamiento predeterminado). + - Si no quieres ningún banner, configura la variable de entorno `OPENCLAW_HIDE_BANNER=1`. - - `web_fetch` funciona sin clave de API. `web_search` depende del - proveedor seleccionado: + + `web_fetch` funciona sin clave de API. `web_search` depende del proveedor + seleccionado: - - Los proveedores respaldados por API, como Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity y Tavily, requieren su configuración normal de clave de API. - - Ollama Web Search no requiere clave, pero usa el host de Ollama configurado y requiere `ollama signin`. - - DuckDuckGo no requiere clave, pero es una integración no oficial basada en HTML. - - SearXNG no requiere clave/puede autoalojarse; configura `SEARXNG_BASE_URL` o `plugins.entries.searxng.config.webSearch.baseUrl`. + - Los proveedores respaldados por API como Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity y Tavily requieren su configuración normal de clave de API. + - Ollama Web Search no necesita clave, pero usa el host de Ollama configurado y requiere `ollama signin`. + - DuckDuckGo no necesita clave, pero es una integración no oficial basada en HTML. + - SearXNG no necesita clave y puede autohospedarse; configura `SEARXNG_BASE_URL` o `plugins.entries.searxng.config.webSearch.baseUrl`. **Recomendado:** ejecuta `openclaw configure --section web` y elige un proveedor. Alternativas mediante variables de entorno: @@ -1617,58 +1617,58 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - La configuración específica del proveedor para la búsqueda web ahora vive en `plugins.entries..config.webSearch.*`. - Las rutas heredadas de proveedor `tools.web.search.*` siguen cargándose temporalmente por compatibilidad, pero no deberían usarse para configuraciones nuevas. - La configuración de fallback de recuperación web de Firecrawl vive en `plugins.entries.firecrawl.config.webFetch.*`. + La configuración específica del proveedor para búsqueda web ahora vive bajo `plugins.entries..config.webSearch.*`. + Las rutas heredadas de proveedor `tools.web.search.*` siguen cargándose temporalmente por compatibilidad, pero no deben usarse para configuraciones nuevas. + La configuración de respaldo de web-fetch de Firecrawl vive bajo `plugins.entries.firecrawl.config.webFetch.*`. Notas: - - Si usas allowlists, añade `web_search`/`web_fetch`/`x_search` o `group:web`. - - `web_fetch` está habilitado por defecto (a menos que se deshabilite explícitamente). - - Si se omite `tools.web.fetch.provider`, OpenClaw detecta automáticamente el primer proveedor de fallback de recuperación listo a partir de las credenciales disponibles. Hoy el proveedor incluido es Firecrawl. - - Los daemons leen variables de entorno desde `~/.openclaw/.env` (o desde el entorno del servicio). + - Si usas listas de permitidos, añade `web_search`/`web_fetch`/`x_search` o `group:web`. + - `web_fetch` está habilitado de forma predeterminada (a menos que se deshabilite explícitamente). + - Si se omite `tools.web.fetch.provider`, OpenClaw detecta automáticamente el primer proveedor de respaldo de fetch listo a partir de las credenciales disponibles. Actualmente el proveedor incluido es Firecrawl. + - Los demonios leen variables de entorno desde `~/.openclaw/.env` (o desde el entorno del servicio). Documentación: [Herramientas web](/es/tools/web). - - `config.apply` sustituye la **configuración completa**. Si envías un objeto parcial, se elimina todo - lo demás. + + `config.apply` reemplaza la **configuración completa**. Si envías un objeto parcial, todo + lo demás se elimina. Recuperación: - Restaura desde una copia de seguridad (git o una copia de `~/.openclaw/openclaw.json`). - - Si no tienes copia de seguridad, vuelve a ejecutar `openclaw doctor` y vuelve a configurar canales/modelos. - - Si esto fue inesperado, abre un bug e incluye tu última configuración conocida o cualquier copia de seguridad. - - Un agente de programación local a menudo puede reconstruir una configuración funcional a partir de logs o del historial. + - Si no tienes copia de seguridad, vuelve a ejecutar `openclaw doctor` y reconfigura canales/modelos. + - Si esto fue inesperado, abre un error e incluye tu última configuración conocida o cualquier copia de seguridad. + - Un agente local de programación a menudo puede reconstruir una configuración funcional a partir de registros o historial. Para evitarlo: - Usa `openclaw config set` para cambios pequeños. - Usa `openclaw configure` para ediciones interactivas. - - Usa `config.schema.lookup` primero cuando no tengas claro una ruta exacta o la forma de un campo; devuelve un nodo de esquema superficial más resúmenes inmediatos de los hijos para profundizar. - - Usa `config.patch` para ediciones RPC parciales; reserva `config.apply` solo para la sustitución completa de la configuración. - - Si estás usando la herramienta exclusiva para propietarios `gateway` desde una ejecución de agent, seguirá rechazando escrituras en `tools.exec.ask` / `tools.exec.security` (incluidos los alias heredados `tools.bash.*` que se normalizan a las mismas rutas exec protegidas). + - Usa primero `config.schema.lookup` cuando no estés seguro de una ruta exacta o de la forma de un campo; devuelve un nodo de esquema superficial más resúmenes inmediatos de nodos hijo para profundizar. + - Usa `config.patch` para ediciones parciales por RPC; reserva `config.apply` solo para reemplazar la configuración completa. + - Si estás usando la herramienta `gateway`, solo para propietarios, desde una ejecución de agente, seguirá rechazando escrituras en `tools.exec.ask` / `tools.exec.security` (incluidos los alias heredados `tools.bash.*` que se normalizan a las mismas rutas protegidas de exec). Documentación: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/es/gateway/doctor). - - El patrón más habitual es **un Gateway** (por ejemplo, Raspberry Pi) más **nodes** y **agents**: + + El patrón habitual es **un Gateway** (por ejemplo, Raspberry Pi) más **nodes** y **agents**: - - **Gateway (central):** posee canales (Signal/WhatsApp), enrutamiento y sesiones. + - **Gateway (central):** es propietario de los canales (Signal/WhatsApp), el enrutamiento y las sesiones. - **Nodes (dispositivos):** Macs/iOS/Android se conectan como periféricos y exponen herramientas locales (`system.run`, `canvas`, `camera`). - - **Agents (workers):** cerebros/espacios de trabajo separados para roles especiales (por ejemplo, "Hetzner ops", "Datos personales"). - - **Subagentes:** generan trabajo en segundo plano desde un agent principal cuando quieres paralelismo. - - **TUI:** conéctate al Gateway y cambia de agents/sessions. + - **Agents (workers):** cerebros/workspaces separados para funciones especializadas (por ejemplo, "operaciones de Hetzner", "datos personales"). + - **Subagentes:** generan trabajo en segundo plano desde un agente principal cuando quieres paralelismo. + - **TUI:** conéctate al Gateway y cambia de agents/sesiones. - Documentación: [Nodes](/es/nodes), [Acceso remoto](/es/gateway/remote), [Enrutamiento Multi-Agent](/es/concepts/multi-agent), [Sub-agents](/es/tools/subagents), [TUI](/web/tui). + Documentación: [Nodes](/es/nodes), [Acceso remoto](/es/gateway/remote), [Enrutamiento multiagente](/es/concepts/multi-agent), [Subagentes](/es/tools/subagents), [TUI](/web/tui). - + Sí. Es una opción de configuración: ```json5 @@ -1682,46 +1682,46 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - El valor predeterminado es `false` (con interfaz). El modo headless tiene más probabilidades de activar comprobaciones anti-bot en algunos sitios. Consulta [Browser](/es/tools/browser). + El valor predeterminado es `false` (con interfaz). El modo sin interfaz tiene más probabilidades de activar comprobaciones antibots en algunos sitios. Consulta [Browser](/es/tools/browser). - El modo headless usa el **mismo motor Chromium** y funciona para la mayoría de automatizaciones (formularios, clics, scraping, inicios de sesión). Las principales diferencias: + El modo sin interfaz usa el **mismo motor Chromium** y funciona para la mayoría de las automatizaciones (formularios, clics, scraping, inicios de sesión). Las principales diferencias son: - No hay ventana visible del navegador (usa capturas de pantalla si necesitas 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 sesiones headless. + - Algunos sitios son más estrictos con la automatización en modo sin interfaz (CAPTCHAs, antibots). + Por ejemplo, X/Twitter suele bloquear sesiones sin interfaz. - Establece `browser.executablePath` en tu binario de Brave (o cualquier navegador basado en Chromium) y reinicia el Gateway. + Configura `browser.executablePath` con tu binario de Brave (o cualquier navegador basado en Chromium) y reinicia el Gateway. Consulta los ejemplos completos de configuración en [Browser](/es/tools/browser#use-brave-or-another-chromium-based-browser). - ## Gateways remotos y nodes +## Gateways remotos y nodes - + - Los mensajes de Telegram los gestiona el **gateway**. El gateway ejecuta el agent y - solo entonces llama a nodes a través del **Gateway WebSocket** cuando se necesita una herramienta de node: + Los mensajes de Telegram son manejados por el **gateway**. El gateway ejecuta el agente y + solo entonces llama a los nodes a través del **Gateway WebSocket** cuando se necesita una herramienta de node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Los nodes no ven tráfico entrante del proveedor; solo reciben llamadas RPC de node. + Los nodes no ven el tráfico entrante del proveedor; solo reciben llamadas RPC de node. - - Respuesta corta: **empareja tu ordenador como un node**. El Gateway se ejecuta en otro lugar, pero puede - llamar a herramientas `node.*` (pantalla, cámara, sistema) en tu máquina local a través del Gateway WebSocket. + + Respuesta corta: **empareja tu equipo como un node**. El Gateway se ejecuta en otro lugar, pero puede + llamar a las herramientas `node.*` (pantalla, cámara, sistema) en tu máquina local a través del Gateway WebSocket. Configuración típica: 1. Ejecuta el Gateway en el host siempre activo (VPS/servidor doméstico). - 2. Pon el host del Gateway y tu ordenador en la misma tailnet. + 2. Pon el host del Gateway y tu equipo en la misma tailnet. 3. Asegúrate de que el WS del Gateway sea accesible (bind de tailnet o túnel SSH). - 4. Abre localmente la app de macOS y conéctate en modo **Remote over SSH** (o tailnet directo) - para que pueda registrarse como un node. + 4. Abre la app de macOS localmente y conéctate en modo **Remote over SSH** (o tailnet directo) + para que pueda registrarse como node. 5. Aprueba el node en el Gateway: ```bash @@ -1729,103 +1729,103 @@ para ver uso/facturación y aumenta los límites según sea necesario. openclaw devices approve ``` - No hace falta ningún puente TCP independiente; los nodes se conectan a través del Gateway WebSocket. + No se requiere ningún puente TCP separado; los nodes se conectan a través del Gateway WebSocket. - Recordatorio de seguridad: emparejar un node de macOS permite `system.run` en esa máquina. Empareja - solo dispositivos de confianza y revisa [Security](/es/gateway/security). + Recordatorio de seguridad: emparejar un node de macOS permite `system.run` en esa máquina. Solo + empareja dispositivos en los que confíes y revisa [Seguridad](/es/gateway/security). - Documentación: [Nodes](/es/nodes), [Protocolo Gateway](/es/gateway/protocol), [Modo remoto de macOS](/es/platforms/mac/remote), [Security](/es/gateway/security). + Documentación: [Nodes](/es/nodes), [Protocolo Gateway](/es/gateway/protocol), [Modo remoto de macOS](/es/platforms/mac/remote), [Seguridad](/es/gateway/security). - + Comprueba lo básico: - El Gateway está en ejecución: `openclaw gateway status` - Estado del Gateway: `openclaw status` - Estado del canal: `openclaw channels status` - Después verifica autenticación y enrutamiento: + Luego verifica la autenticación y el enrutamiento: - Si usas Tailscale Serve, asegúrate de que `gateway.auth.allowTailscale` esté configurado correctamente. - Si te conectas mediante túnel SSH, confirma que el túnel local esté activo y apunte al puerto correcto. - - Confirma que tus allowlists (DM o grupo) incluyen tu cuenta. + - Confirma que tus listas de permitidos (MD o grupo) incluyan tu cuenta. Documentación: [Tailscale](/es/gateway/tailscale), [Acceso remoto](/es/gateway/remote), [Channels](/es/channels). - - Sí. No hay un puente "bot a bot" integrado, pero puedes conectarlo de unas cuantas + + Sí. No hay un puente "bot a bot" integrado, pero puedes conectarlas de varias formas fiables: - **La más sencilla:** 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. + **La más simple:** usa un canal de chat normal al que ambos bots puedan acceder (Telegram/Slack/WhatsApp). + Haz que el Bot A envíe un mensaje al Bot B y luego deja que el Bot B responda como siempre. **Puente de CLI (genérico):** ejecuta un script que llame al otro Gateway con `openclaw agent --message ... --deliver`, apuntando a un chat donde el otro bot - esté escuchando. Si uno de los bots está en un VPS remoto, apunta tu CLI a ese Gateway remoto + escuche. Si uno de los bots está en un VPS remoto, apunta tu CLI a ese Gateway remoto mediante SSH/Tailscale (consulta [Acceso remoto](/es/gateway/remote)). - Patrón de ejemplo (ejecuta desde una máquina que pueda alcanzar el Gateway de destino): + Patrón de ejemplo (ejecútalo desde una máquina que pueda alcanzar el Gateway de destino): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Consejo: añade una barrera para que los dos bots no entren en un bucle infinito (solo menciones, - allowlists de canal o una regla de "no responder a mensajes de bots"). + 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"). - Documentación: [Acceso remoto](/es/gateway/remote), [CLI del agent](/cli/agent), [Envío del agent](/es/tools/agent-send). + Documentación: [Acceso remoto](/es/gateway/remote), [CLI de Agent](/cli/agent), [Envío de Agent](/es/tools/agent-send). - - No. Un Gateway puede alojar varios agents, cada uno con su propio espacio de trabajo, modelos predeterminados - y enrutamiento. Esa es la configuración normal y es mucho más barata y sencilla que ejecutar + + No. Un Gateway puede alojar varios agents, cada uno con su propio workspace, modelos predeterminados + y enrutamiento. Esa es la configuración normal, y es mucho más barata y sencilla que ejecutar un VPS por agent. - Usa VPS separados solo cuando necesites aislamiento estricto (límites de seguridad) o configuraciones - muy distintas que no quieras compartir. En caso contrario, mantén un Gateway y + Usa VPS independientes solo cuando necesites aislamiento fuerte (límites de seguridad) o configuraciones muy + diferentes que no quieras compartir. En caso contrario, mantén un Gateway y usa varios agents o subagentes. - Sí: los nodes son la forma principal de acceder a tu portátil desde un Gateway remoto y - ofrecen más que acceso de shell. El Gateway se ejecuta en macOS/Linux (Windows mediante WSL2) y es - ligero (vale un VPS pequeño o una máquina tipo Raspberry Pi; 4 GB de RAM es de sobra), así que una - configuración habitual es un host siempre activo más tu portátil como node. + Sí: los nodes son la forma de primera clase de llegar a tu portátil desde un Gateway remoto, y + desbloquean más que acceso al shell. El Gateway se ejecuta en macOS/Linux (Windows mediante WSL2) y es + ligero (un VPS pequeño o una máquina tipo Raspberry Pi es suficiente; 4 GB de RAM son más que suficientes), por lo que una configuración + habitual es un host siempre activo más tu portátil como node. - - **No hace falta SSH entrante.** Los nodes se conectan saliendo al Gateway WebSocket y usan emparejamiento de dispositivos. - - **Controles de ejecución más seguros.** `system.run` está controlado por allowlists/aprobaciones de node en ese portátil. + - **No requiere SSH entrante.** Los nodes se conectan hacia fuera al Gateway WebSocket y usan emparejamiento de dispositivos. + - **Controles de ejecución más seguros.** `system.run` está protegido por listas de permitidos/aprobaciones de node en ese portátil. - **Más herramientas de dispositivo.** Los nodes exponen `canvas`, `camera` y `screen` además de `system.run`. - - **Automatización local del navegador.** Mantén el Gateway en un VPS, pero ejecuta Chrome localmente mediante un host de node en el portátil, o conéctate al Chrome local del host mediante Chrome MCP. + - **Automatización local del navegador.** Mantén el Gateway en un VPS, pero ejecuta Chrome localmente a través de un host de node en el portátil, o conéctate a Chrome local en el host mediante Chrome MCP. - SSH está bien para acceso puntual al shell, pero los nodes son más sencillos para flujos de trabajo continuos del agent y - automatización del dispositivo. + SSH está bien para acceso puntual al shell, pero los nodes son más simples para flujos de trabajo continuos de agentes y + automatización de dispositivos. Documentación: [Nodes](/es/nodes), [CLI de Nodes](/cli/nodes), [Browser](/es/tools/browser). - - No. Solo debería ejecutarse **un gateway** por host a menos que ejecutes intencionadamente perfiles aislados (consulta [Multiple gateways](/es/gateway/multiple-gateways)). Los nodes son periféricos que se conectan - al gateway (nodes de iOS/Android o el "modo node" de macOS en la app de barra de menús). Para hosts de node - headless y control por CLI, consulta [Node host CLI](/cli/node). + + No. Solo debe ejecutarse **un gateway** por host, a menos que intencionadamente ejecutes perfiles aislados (consulta [Múltiples gateways](/es/gateway/multiple-gateways)). Los nodes son periféricos que se conectan + al gateway (nodes de iOS/Android o "modo node" de macOS en la app de la barra de menús). Para hosts de node sin interfaz + y control por CLI, consulta [CLI de Node host](/cli/node). Se requiere un reinicio completo para cambios en `gateway`, `discovery` y `canvasHost`. - + Sí. - - `config.schema.lookup`: inspecciona un subárbol de configuración con su nodo de esquema superficial, pista de UI coincidente y resúmenes inmediatos de hijos antes de escribir + - `config.schema.lookup`: inspecciona un subárbol de configuración con su nodo de esquema superficial, la sugerencia de UI coincidente y resúmenes inmediatos de nodos hijo antes de escribir - `config.get`: obtiene 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 necesario + - `config.patch`: actualización parcial segura (preferida para la mayoría de las ediciones RPC); recarga en caliente cuando es posible y reinicia cuando es necesario - `config.apply`: valida + reemplaza la configuración completa; recarga en caliente cuando es posible y reinicia cuando es necesario - - La herramienta de tiempo de ejecución `gateway`, exclusiva para propietarios, sigue negándose a reescribir `tools.exec.ask` / `tools.exec.security`; los alias heredados `tools.bash.*` se normalizan a las mismas rutas exec protegidas + - La herramienta de tiempo de ejecución `gateway`, solo para propietarios, sigue negándose a reescribir `tools.exec.ask` / `tools.exec.security`; los alias heredados `tools.bash.*` se normalizan a las mismas rutas protegidas de exec @@ -1837,7 +1837,7 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - Esto establece tu espacio de trabajo y restringe quién puede activar el bot. + Esto configura tu workspace y restringe quién puede activar el bot. @@ -1870,13 +1870,13 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Serve expone la **Control UI + WS del Gateway**. Los nodes se conectan mediante el mismo endpoint WS del Gateway. + Serve expone la **Control UI + WS del Gateway**. Los nodes se conectan a través del mismo endpoint WS del Gateway. Configuración recomendada: 1. **Asegúrate de que el VPS + Mac estén en la misma tailnet**. - 2. **Usa la app de macOS en modo Remote** (el destino SSH puede ser el hostname de tailnet). - La app tunelizará el puerto del Gateway y se conectará como un node. + 2. **Usa la app de macOS en modo Remoto** (el destino SSH puede ser el hostname de tailnet). + La app tunelizará el puerto del Gateway y se conectará como node. 3. **Aprueba el node** en el gateway: ```bash @@ -1890,12 +1890,12 @@ para ver uso/facturación y aumenta los límites según sea necesario. Si solo necesitas **herramientas locales** (pantalla/cámara/exec) en el segundo portátil, añádelo como - **node**. Eso mantiene un único Gateway y evita configuración duplicada. Las herramientas locales de node son - actualmente exclusivas de macOS, pero planeamos extenderlas a otros SO. + **node**. Eso mantiene un solo Gateway y evita configuración duplicada. Las herramientas locales de node son + actualmente solo para macOS, pero planeamos ampliarlas a otros SO. - Instala un segundo Gateway solo cuando necesites **aislamiento estricto** o dos bots completamente separados. + Instala un segundo Gateway solo cuando necesites **aislamiento fuerte** o dos bots completamente independientes. - Documentación: [Nodes](/es/nodes), [CLI de Nodes](/cli/nodes), [Multiple gateways](/es/gateway/multiple-gateways). + Documentación: [Nodes](/es/nodes), [CLI de Nodes](/cli/nodes), [Múltiples gateways](/es/gateway/multiple-gateways). @@ -1906,12 +1906,12 @@ para ver uso/facturación y aumenta los límites según sea necesario. OpenClaw lee variables de entorno del proceso padre (shell, launchd/systemd, CI, etc.) y además carga: - - `.env` del directorio de trabajo actual - - un `.env` global de fallback desde `~/.openclaw/.env` (también conocido como `$OPENCLAW_STATE_DIR/.env`) + - `.env` desde el directorio de trabajo actual + - un `.env` global de respaldo desde `~/.openclaw/.env` (también conocido como `$OPENCLAW_STATE_DIR/.env`) - Ninguno de los archivos `.env` sobrescribe variables de entorno existentes. + Ninguno de los archivos `.env` reemplaza las variables de entorno existentes. - También puedes definir variables de entorno inline en la configuración (aplicadas solo si faltan en el entorno del proceso): + También puedes definir variables de entorno en línea en la configuración (se aplican solo si faltan en el entorno del proceso): ```json5 { @@ -1922,12 +1922,12 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - Consulta [/environment](/es/help/environment) para ver toda la precedencia y las fuentes. + Consulta [/environment](/es/help/environment) para conocer la precedencia completa y las fuentes. - - Dos soluciones habituales: + + Dos correcciones comunes: 1. Pon las claves que faltan en `~/.openclaw/.env` para que se recojan incluso cuando el servicio no herede el entorno de tu shell. 2. Habilita la importación del shell (comodidad opcional): @@ -1943,18 +1943,18 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - Esto ejecuta tu shell de login e importa solo las claves esperadas que falten (nunca sobrescribe). Equivalentes por variable de entorno: + Esto ejecuta tu shell de inicio de sesión e importa solo las claves esperadas que falten (nunca reemplaza). Equivalentes en variables de entorno: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - - `openclaw models status` informa de si la **importación del entorno del shell** está habilitada. "Shell env: off" + + `openclaw models status` informa si la **importación del entorno del shell** está habilitada. "Shell env: off" **no** significa que falten tus variables de entorno; solo significa que OpenClaw no cargará - automáticamente tu shell de login. + tu shell de inicio de sesión automáticamente. Si el Gateway se ejecuta como servicio (launchd/systemd), no heredará tu - entorno de shell. Arréglalo de una de estas formas: + entorno del shell. Corrígelo haciendo una de estas cosas: 1. Pon el token en `~/.openclaw/.env`: @@ -1963,7 +1963,7 @@ para ver uso/facturación y aumenta los límites según sea necesario. ``` 2. O habilita la importación del shell (`env.shellEnv.enabled: true`). - 3. O añádelo al bloque `env` de tu configuración (solo se aplica si falta). + 3. O añádelo al bloque `env` de tu configuración (se aplica solo si falta). Luego reinicia el gateway y vuelve a comprobar: @@ -1985,9 +1985,9 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Las sesiones pueden caducar después de `session.idleMinutes`, pero esto está **deshabilitado por defecto** (valor predeterminado **0**). - Establécelo en un valor positivo para habilitar la caducidad por inactividad. Cuando está habilitado, el **siguiente** - mensaje después del periodo de inactividad inicia un ID de sesión nuevo para esa clave de chat. + Las sesiones pueden expirar después de `session.idleMinutes`, pero esto está **deshabilitado de forma predeterminada** (valor predeterminado **0**). + Configúralo con un valor positivo para habilitar la expiración por inactividad. Cuando está habilitado, el **siguiente** + mensaje después del período de inactividad inicia un ID de sesión nuevo para esa clave de chat. Esto no elimina las transcripciones; solo inicia una sesión nueva. ```json5 @@ -2000,34 +2000,34 @@ para ver uso/facturación y aumenta los límites según sea necesario. - - Sí, mediante **enrutamiento multi-agent** y **subagentes**. Puedes crear un agent - coordinador y varios agents worker con sus propios espacios de trabajo y modelos. + + Sí, mediante **enrutamiento multiagente** y **subagentes**. Puedes crear un agente + coordinador y varios agentes worker con sus propios workspaces y modelos. Dicho esto, es mejor verlo como un **experimento divertido**. Consume muchos tokens y a menudo - es menos eficiente que usar un solo bot con sesiones separadas. El modelo típico que - imaginamos es un bot con el que hablas, con diferentes sesiones para trabajo en paralelo. Ese - bot también puede generar subagentes cuando haga falta. + es menos eficiente que usar un bot con sesiones separadas. El modelo típico que + imaginamos es un bot con el que hablas, con distintas sesiones para trabajo en paralelo. Ese + bot también puede generar subagentes cuando sea necesario. - Documentación: [Enrutamiento multi-agent](/es/concepts/multi-agent), [Sub-agents](/es/tools/subagents), [CLI de Agents](/cli/agents). + Documentación: [Enrutamiento multiagente](/es/concepts/multi-agent), [Subagentes](/es/tools/subagents), [CLI de Agents](/cli/agents). - El contexto de la sesión está limitado por la ventana del modelo. Los chats largos, las salidas grandes de herramientas o muchos - archivos pueden activar compactación o truncado. + El contexto de la sesión está limitado por la ventana del modelo. Chats largos, salidas grandes de herramientas o muchos + archivos pueden activar Compaction o truncamiento. Qué ayuda: - Pídele al bot que resuma el estado actual y lo escriba en un archivo. - Usa `/compact` antes de tareas largas y `/new` al cambiar de tema. - - Mantén el contexto importante en el espacio de trabajo y pídele al bot que lo vuelva a leer. - - Usa subagentes para trabajo largo o en paralelo para que el chat principal siga siendo más pequeño. - - Elige un modelo con una ventana de contexto mayor si esto ocurre con frecuencia. + - Mantén el contexto importante en el workspace y pídele al bot que lo lea de nuevo. + - Usa subagentes para trabajo largo o en paralelo, para que el chat principal siga siendo más pequeño. + - Elige un modelo con una ventana de contexto más grande si esto ocurre con frecuencia. - + Usa el comando de restablecimiento: ```bash @@ -2048,16 +2048,16 @@ para ver uso/facturación y aumenta los límites según sea necesario. Notas: - - La configuración inicial también ofrece **Reset** si detecta una configuración existente. Consulta [Configuración inicial (CLI)](/es/start/wizard). + - Onboarding también ofrece **Reset** si detecta una configuración existente. Consulta [Onboarding (CLI)](/es/start/wizard). - Si usaste perfiles (`--profile` / `OPENCLAW_PROFILE`), restablece cada directorio de estado (los predeterminados son `~/.openclaw-`). - - Restablecimiento de desarrollo: `openclaw gateway --dev --reset` (solo desarrollo; borra configuración de desarrollo + credenciales + sesiones + espacio de trabajo). + - Restablecimiento de desarrollo: `openclaw gateway --dev --reset` (solo desarrollo; borra configuración de desarrollo + credenciales + sesiones + workspace). - + Usa una de estas opciones: - - **Compactar** (mantiene la conversación pero resume turnos anteriores): + - **Compactar** (mantiene la conversación pero resume los turnos anteriores): ``` /compact @@ -2074,24 +2074,24 @@ para ver uso/facturación y aumenta los límites según sea necesario. Si sigue ocurriendo: - - Habilita o ajusta la **poda de sesión** (`agents.defaults.contextPruning`) para recortar salidas antiguas de herramientas. - - Usa un modelo con una ventana de contexto mayor. + - Habilita o ajusta la **depuración de sesión** (`agents.defaults.contextPruning`) para recortar salidas antiguas de herramientas. + - Usa un modelo con una ventana de contexto más grande. - Documentación: [Compaction](/es/concepts/compaction), [Poda de sesión](/es/concepts/session-pruning), [Gestión de sesiones](/es/concepts/session). + Documentación: [Compaction](/es/concepts/compaction), [Depuración de sesión](/es/concepts/session-pruning), [Gestión de sesiones](/es/concepts/session). - Esto es un error de validación del proveedor: el modelo emitió un bloque `tool_use` sin el - `input` requerido. Normalmente significa que el historial de la sesión está desactualizado o dañado (a menudo después de hilos largos - o de un cambio de herramienta/esquema). + Este es un error de validación del proveedor: el modelo emitió un bloque `tool_use` sin el + `input` requerido. Normalmente significa que el historial de la sesión está obsoleto o dañado (a menudo después de hilos largos + o un cambio de herramienta/esquema). Solución: inicia una sesión nueva con `/new` (mensaje independiente). - Los Heartbeat se ejecutan cada **30m** por defecto (**1h** al usar autenticación OAuth). Ajústalos o desactívalos: + Los Heartbeats se ejecutan cada **30m** de forma predeterminada (**1h** cuando se usa autenticación OAuth). Ajústalos o desactívalos: ```json5 { @@ -2106,16 +2106,16 @@ para ver uso/facturación y aumenta los límites según sea necesario. ``` Si `HEARTBEAT.md` existe pero está efectivamente vacío (solo líneas en blanco y encabezados - markdown como `# Heading`), OpenClaw omite la ejecución del heartbeat para ahorrar llamadas a la API. - Si falta el archivo, el heartbeat sigue ejecutándose y el modelo decide qué hacer. + markdown como `# Heading`), OpenClaw omite la ejecución de heartbeat para ahorrar llamadas a la API. + Si falta el archivo, el heartbeat se sigue ejecutando y el modelo decide qué hacer. - Las sobrescrituras por agent usan `agents.list[].heartbeat`. Documentación: [Heartbeat](/es/gateway/heartbeat). + Las anulaciones por agente usan `agents.list[].heartbeat`. Documentación: [Heartbeat](/es/gateway/heartbeat). - + No. OpenClaw se ejecuta en **tu propia cuenta**, así que si estás en el grupo, OpenClaw puede verlo. - Por defecto, las respuestas en grupos están bloqueadas hasta que permitas remitentes (`groupPolicy: "allowlist"`). + De forma predeterminada, las respuestas en grupos están bloqueadas hasta que permites remitentes (`groupPolicy: "allowlist"`). Si quieres que solo **tú** puedas activar respuestas en grupos: @@ -2133,16 +2133,16 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Opción 1 (la más rápida): sigue los logs y envía un mensaje de prueba en el grupo: + Opción 1 (la más rápida): sigue los registros y envía un mensaje de prueba en el grupo: ```bash openclaw logs --follow --json ``` - Busca `chatId` (o `from`) terminado en `@g.us`, como: + Busca `chatId` (o `from`) terminando en `@g.us`, como: `1234567890-1234567890@g.us`. - Opción 2 (si ya está configurado/en allowlist): lista grupos desde la configuración: + Opción 2 (si ya está configurado/en lista de permitidos): lista grupos desde la configuración: ```bash openclaw directory groups list --channel whatsapp @@ -2155,84 +2155,84 @@ para ver uso/facturación y aumenta los límites según sea necesario. Dos causas comunes: - - La restricción por mención está activada (predeterminada). Debes @mencionar al bot (o coincidir con `mentionPatterns`). - - Configuraste `channels.whatsapp.groups` sin `"*"` y el grupo no está en la allowlist. + - La puerta de menciones está activada (predeterminado). Debes @mencionar al bot (o coincidir con `mentionPatterns`). + - Configuraste `channels.whatsapp.groups` sin `"*"` y el grupo no está en la lista de permitidos. - Consulta [Groups](/es/channels/groups) y [Mensajes de grupo](/es/channels/group-messages). + Consulta [Grupos](/es/channels/groups) y [Mensajes de grupo](/es/channels/group-messages). - - Los chats directos colapsan a la sesión principal por defecto. Los grupos/canales tienen sus propias claves de sesión, y los temas de Telegram / hilos de Discord son sesiones separadas. Consulta [Groups](/es/channels/groups) y [Mensajes de grupo](/es/channels/group-messages). + + Los chats directos se contraen en la sesión principal de forma predeterminada. Los grupos/canales tienen sus propias claves de sesión, y los topics de Telegram / hilos de Discord son sesiones separadas. Consulta [Grupos](/es/channels/groups) y [Mensajes de grupo](/es/channels/group-messages). - - No hay límites estrictos. Decenas (incluso cientos) están bien, pero vigila: + + No hay límites estrictos. Decenas (incluso cientos) están bien, pero ten en cuenta: - - **Crecimiento del disco:** las sesiones + transcripciones viven en `~/.openclaw/agents//sessions/`. + - **Crecimiento del disco:** las sesiones + transcripciones viven bajo `~/.openclaw/agents//sessions/`. - **Coste de tokens:** más agents significa más uso concurrente del modelo. - - **Sobrecarga operativa:** perfiles de autenticación, espacios de trabajo y enrutamiento de canales por agent. + - **Sobrecarga operativa:** perfiles de autenticación, workspaces y enrutamiento de canales por agent. Consejos: - - Mantén un espacio de trabajo **activo** por agent (`agents.defaults.workspace`). - - Poda sesiones antiguas (elimina entradas JSONL o del almacén) si el disco crece. - - Usa `openclaw doctor` para detectar espacios de trabajo perdidos y desajustes de perfiles. + - Mantén un workspace **activo** por agent (`agents.defaults.workspace`). + - Depura sesiones antiguas (elimina entradas JSONL o del almacén) si el disco crece. + - Usa `openclaw doctor` para detectar workspaces errantes y desajustes de perfiles. - Sí. Usa **Enrutamiento Multi-Agent** para ejecutar varios agents aislados y enrutar mensajes entrantes por - canal/cuenta/peer. Slack está soportado como canal y puede vincularse a agents específicos. + Sí. Usa **Enrutamiento multiagente** para ejecutar varios agents aislados y enrutar mensajes entrantes por + canal/cuenta/peer. Slack es compatible como canal y puede vincularse a agents específicos. - El acceso al navegador es potente, pero no significa "hacer cualquier cosa que pueda hacer un humano": anti-bot, CAPTCHA y MFA - todavía pueden bloquear la automatización. Para el control más fiable del navegador, usa Chrome MCP local en el host, + El acceso al navegador es potente, pero no es "hacer cualquier cosa que pueda hacer un humano": antibots, CAPTCHAs y MFA pueden + seguir bloqueando la automatización. Para el control del navegador más fiable, usa Chrome MCP local en el host, o usa CDP en la máquina que realmente ejecuta el navegador. - Configuración recomendada: + Configuración de buenas prácticas: - - Host Gateway siempre activo (VPS/Mac mini). - - Un agent por rol (bindings). + - Host de Gateway siempre activo (VPS/Mac mini). + - Un agent por función (vinculaciones). - Canal(es) de Slack vinculados a esos agents. - - Navegador local mediante Chrome MCP o un node cuando haga falta. + - Navegador local mediante Chrome MCP o un node cuando sea necesario. - Documentación: [Enrutamiento Multi-Agent](/es/concepts/multi-agent), [Slack](/es/channels/slack), + Documentación: [Enrutamiento multiagente](/es/concepts/multi-agent), [Slack](/es/channels/slack), [Browser](/es/tools/browser), [Nodes](/es/nodes). -## Models: valores predeterminados, selección, alias, cambio +## Modelos: predeterminados, selección, alias, cambio - El modelo predeterminado de OpenClaw es el que estableces como: + El modelo predeterminado de OpenClaw es el que configuras como: ``` agents.defaults.model.primary ``` - A los modelos se hace referencia como `provider/model` (ejemplo: `openai/gpt-5.4`). Si omites el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese id de modelo exacto, y solo entonces recurre al proveedor predeterminado configurado como ruta de compatibilidad obsoleta. Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. Aun así, deberías establecer **explícitamente** `provider/model`. + Se hace referencia a los modelos como `provider/model` (ejemplo: `openai/gpt-5.4`). Si omites el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única del proveedor configurado para ese id exacto de modelo y solo después recurre al proveedor predeterminado configurado como ruta de compatibilidad obsoleta. Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. Aun así, deberías configurar **explícitamente** `provider/model`. - **Predeterminado recomendado:** usa el modelo de última generación más potente disponible en tu stack de proveedores. - **Para agents con herramientas habilitadas o entradas no fiables:** prioriza la capacidad del modelo por encima del coste. - **Para chat rutinario/de bajo riesgo:** usa modelos de fallback más baratos y enruta por rol de agent. + **Predeterminado recomendado:** usa el modelo de última generación más potente disponible en tu pila de proveedores. + **Para agents con herramientas habilitadas o entrada no confiable:** prioriza la potencia del modelo sobre el coste. + **Para chat rutinario/de bajo riesgo:** usa modelos de respaldo más baratos y enruta por función del agent. MiniMax tiene su propia documentación: [MiniMax](/es/providers/minimax) y [Modelos locales](/es/gateway/local-models). Regla general: usa el **mejor modelo que puedas permitirte** para trabajo de alto riesgo, y un modelo más barato para chat rutinario o resúmenes. Puedes enrutar modelos por agent y usar subagentes para - paralelizar tareas largas (cada subagente consume tokens). Consulta [Models](/es/concepts/models) y - [Sub-agents](/es/tools/subagents). + paralelizar tareas largas (cada subagente consume tokens). Consulta [Modelos](/es/concepts/models) y + [Subagentes](/es/tools/subagents). - Advertencia importante: los modelos más débiles o excesivamente cuantizados son más vulnerables a prompt - injection y comportamientos inseguros. Consulta [Security](/es/gateway/security). + Advertencia importante: los modelos más débiles o demasiado cuantizados son más vulnerables a la inyección de prompts + y a comportamientos inseguros. Consulta [Seguridad](/es/gateway/security). - Más contexto: [Models](/es/concepts/models). + Más contexto: [Modelos](/es/concepts/models). @@ -2247,21 +2247,21 @@ para ver uso/facturación y aumenta los límites según sea necesario. - edita `agents.defaults.model` en `~/.openclaw/openclaw.json` Evita `config.apply` con un objeto parcial a menos que pretendas reemplazar toda la configuración. - Para ediciones RPC, primero inspecciona con `config.schema.lookup` y prefiere `config.patch`. La carga útil de lookup te da la ruta normalizada, la documentación/restricciones superficiales del esquema y resúmenes inmediatos de hijos. + Para ediciones RPC, inspecciona primero con `config.schema.lookup` y prefiere `config.patch`. La carga útil de lookup te da la ruta normalizada, documentación/restricciones superficiales del esquema y resúmenes inmediatos de nodos hijo. para actualizaciones parciales. Si sobrescribiste la configuración, restaura desde una copia de seguridad o vuelve a ejecutar `openclaw doctor` para repararla. - Documentación: [Models](/es/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/es/gateway/doctor). + Documentación: [Modelos](/es/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/es/gateway/doctor). - - Sí. Ollama es la vía más sencilla para modelos locales. + + Sí. Ollama es la ruta más sencilla para modelos locales. Configuración más rápida: 1. Instala Ollama desde `https://ollama.com/download` - 2. Descarga un modelo local, como `ollama pull gemma4` + 2. Descarga un modelo local como `ollama pull gemma4` 3. Si también quieres modelos en la nube, ejecuta `ollama signin` 4. Ejecuta `openclaw onboard` y elige `Ollama` 5. Elige `Local` o `Cloud + Local` @@ -2269,15 +2269,15 @@ para ver uso/facturación y aumenta los límites según sea necesario. Notas: - `Cloud + Local` te da modelos en la nube más tus modelos locales de Ollama - - los modelos en la nube, como `kimi-k2.5:cloud`, no necesitan una descarga local - - para cambiar manualmente, usa `openclaw models list` y `openclaw models set ollama/` + - los modelos en la nube como `kimi-k2.5:cloud` no necesitan descarga local + - para cambio manual, usa `openclaw models list` y `openclaw models set ollama/` - Nota de seguridad: los modelos más pequeños o muy cuantizados son más vulnerables a prompt - injection. Recomendamos encarecidamente **modelos grandes** para cualquier bot que pueda usar herramientas. - Si aun así quieres modelos pequeños, habilita sandboxing y allowlists estrictas de herramientas. + Nota de seguridad: los modelos más pequeños o muy cuantizados son más vulnerables a la inyección de prompts. + Recomendamos firmemente **modelos grandes** para cualquier bot que pueda usar herramientas. + Si aun así quieres modelos pequeños, habilita sandboxing y listas estrictas de herramientas permitidas. Documentación: [Ollama](/es/providers/ollama), [Modelos locales](/es/gateway/local-models), - [Proveedores de modelos](/es/concepts/model-providers), [Security](/es/gateway/security), + [Proveedores de modelos](/es/concepts/model-providers), [Seguridad](/es/gateway/security), [Sandboxing](/es/gateway/sandboxing). @@ -2305,7 +2305,7 @@ para ver uso/facturación y aumenta los límites según sea necesario. Puedes listar los modelos disponibles con `/model`, `/model list` o `/model status`. - `/model` (y `/model list`) muestra un selector compacto numerado. Selecciona por número: + `/model` (y `/model list`) muestra un selector compacto y numerado. Selecciona por número: ``` /model 3 @@ -2318,10 +2318,10 @@ para ver uso/facturación y aumenta los límites según sea necesario. /model opus@anthropic:work ``` - Consejo: `/model status` muestra qué agent está activo, qué archivo `auth-profiles.json` se está usando y qué perfil de autenticación se intentará a continuación. - También muestra el endpoint configurado del proveedor (`baseUrl`) y el modo de API (`api`) cuando están disponibles. + Consejo: `/model status` muestra qué agent está activo, qué archivo `auth-profiles.json` se está usando y qué perfil de autenticación se probará a continuación. + También muestra el endpoint del proveedor configurado (`baseUrl`) y el modo de API (`api`) cuando están disponibles. - **¿Cómo desanclo un perfil que configuré con @profile?** + **¿Cómo quito la fijación de un perfil que configuré con @profile?** Vuelve a ejecutar `/model` **sin** el sufijo `@profile`: @@ -2335,22 +2335,22 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Sí. Establece uno como predeterminado y cambia según sea necesario: + Sí. Configura uno como predeterminado y cambia según sea necesario: - **Cambio rápido (por sesión):** `/model gpt-5.4` para tareas diarias, `/model openai-codex/gpt-5.4` para programar con Codex OAuth. - - **Predeterminado + cambio:** establece `agents.defaults.model.primary` en `openai/gpt-5.4`, luego cambia a `openai-codex/gpt-5.4` al programar (o al revés). - - **Subagentes:** enruta tareas de programación a subagentes con un modelo predeterminado distinto. + - **Predeterminado + cambio:** configura `agents.defaults.model.primary` en `openai/gpt-5.4`, luego cambia a `openai-codex/gpt-5.4` al programar (o al revés). + - **Subagentes:** enruta las tareas de programación a subagentes con un modelo predeterminado diferente. - Consulta [Models](/es/concepts/models) y [Comandos slash](/es/tools/slash-commands). + Consulta [Modelos](/es/concepts/models) y [Comandos slash](/es/tools/slash-commands). - - Usa una alternancia por sesión o un valor predeterminado en la configuración: + + Usa un cambio por sesión o un valor predeterminado en la configuración: - - **Por sesión:** envía `/fast on` mientras la sesión usa `openclaw/gpt-5.4` o `openai-codex/gpt-5.4`. - - **Predeterminado por modelo:** establece `agents.defaults.models["openai/gpt-5.4"].params.fastMode` en `true`. - - **También Codex OAuth:** si también usas `openai-codex/gpt-5.4`, establece la misma marca allí. + - **Por sesión:** envía `/fast on` mientras la sesión usa `openai/gpt-5.4` o `openai-codex/gpt-5.4`. + - **Predeterminado por modelo:** configura `agents.defaults.models["openai/gpt-5.4"].params.fastMode` en `true`. + - **También Codex OAuth:** si también usas `openai-codex/gpt-5.4`, configura la misma marca ahí. Ejemplo: @@ -2375,40 +2375,40 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - Para OpenAI, el modo fast se asigna a `service_tier = "priority"` en solicitudes nativas de Responses compatibles. Las sobrescrituras de sesión con `/fast` tienen prioridad sobre los valores predeterminados de configuración. + Para OpenAI, el modo rápido se asigna a `service_tier = "priority"` en solicitudes nativas de Responses compatibles. Las anulaciones por sesión con `/fast` tienen prioridad sobre los valores predeterminados de configuración. - Consulta [Thinking y modo fast](/es/tools/thinking) y [Modo fast de OpenAI](/es/providers/openai#openai-fast-mode). + Consulta [Thinking y modo rápido](/es/tools/thinking) y [Modo rápido de OpenAI](/es/providers/openai#openai-fast-mode). - Si `agents.defaults.models` está configurado, se convierte en la **allowlist** para `/model` y cualquier - sobrescritura de sesión. Elegir un modelo que no esté en esa lista devuelve: + Si `agents.defaults.models` está configurado, se convierte en la **lista de permitidos** para `/model` y cualquier + anulación de sesión. Elegir un modelo que no esté en esa lista devuelve: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` Ese error se devuelve **en lugar de** una respuesta normal. Solución: añade el modelo a - `agents.defaults.models`, elimina la allowlist o elige un modelo de `/model list`. + `agents.defaults.models`, elimina la lista de permitidos o elige un modelo de `/model list`. - Esto significa que el **proveedor no está configurado** (no se encontró configuración del proveedor MiniMax ni + Esto significa que el **proveedor no está configurado** (no se encontró ninguna configuración de proveedor MiniMax ni ningún perfil de autenticación), por lo que el modelo no puede resolverse. - Lista de comprobación para solucionarlo: + Lista de comprobación para corregirlo: - 1. Actualiza a una versión actual de OpenClaw (o ejecuta desde `main` del código fuente) y luego reinicia el gateway. + 1. Actualiza a una versión actual de OpenClaw (o ejecuta desde el código fuente `main`) y luego reinicia el gateway. 2. Asegúrate de que MiniMax esté configurado (asistente o JSON), o de que exista autenticación de MiniMax - en el entorno/perfiles de autenticación para que pueda inyectarse el proveedor correspondiente + en env/perfiles de autenticación para que pueda inyectarse el proveedor coincidente (`MINIMAX_API_KEY` para `minimax`, `MINIMAX_OAUTH_TOKEN` o MiniMax OAuth almacenado para `minimax-portal`). - 3. Usa el id de modelo exacto (sensible a mayúsculas y minúsculas) para tu ruta de autenticación: - `minimax/MiniMax-M2.7` o `minimax/MiniMax-M2.7-highspeed` para configuración con clave de API, - o `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` para configuración con OAuth. + 3. Usa el id exacto del modelo (distingue mayúsculas y minúsculas) para tu ruta de autenticación: + `minimax/MiniMax-M2.7` o `minimax/MiniMax-M2.7-highspeed` para configuración + con clave de API, o `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` para configuración OAuth. 4. Ejecuta: ```bash @@ -2417,13 +2417,13 @@ para ver uso/facturación y aumenta los límites según sea necesario. y elige de la lista (o `/model list` en el chat). - Consulta [MiniMax](/es/providers/minimax) y [Models](/es/concepts/models). + Consulta [MiniMax](/es/providers/minimax) y [Modelos](/es/concepts/models). Sí. Usa **MiniMax como predeterminado** y cambia de modelo **por sesión** cuando sea necesario. - Los fallbacks son para **errores**, no para "tareas difíciles", así que usa `/model` o un agent separado. + Los respaldos son para **errores**, no para "tareas difíciles", así que usa `/model` o un agent separado. **Opción A: cambiar por sesión** @@ -2454,11 +2454,11 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Agent B predeterminado: OpenAI - Enruta por agent o usa `/agent` para cambiar - Documentación: [Models](/es/concepts/models), [Enrutamiento Multi-Agent](/es/concepts/multi-agent), [MiniMax](/es/providers/minimax), [OpenAI](/es/providers/openai). + Documentación: [Modelos](/es/concepts/models), [Enrutamiento multiagente](/es/concepts/multi-agent), [MiniMax](/es/providers/minimax), [OpenAI](/es/providers/openai). - + Sí. OpenClaw incluye algunos atajos predeterminados (solo se aplican cuando el modelo existe en `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` @@ -2470,12 +2470,12 @@ para ver uso/facturación y aumenta los límites según sea necesario. - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Si defines tu propio alias con el mismo nombre, prevalece tu valor. + Si configuras tu propio alias con el mismo nombre, prevalece tu valor. - - Los aliases provienen de `agents.defaults.models..alias`. Ejemplo: + + Los aliases vienen de `agents.defaults.models..alias`. Ejemplo: ```json5 { @@ -2492,11 +2492,11 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - Luego `/model sonnet` (o `/` cuando sea compatible) se resuelve a ese id de modelo. + Luego `/model sonnet` (o `/` cuando se admita) se resuelve a ese id de modelo. - + OpenRouter (pago por token; muchos modelos): ```json5 @@ -2525,93 +2525,92 @@ para ver uso/facturación y aumenta los límites según sea necesario. } ``` - Si haces referencia a un proveedor/modelo pero falta la clave requerida del proveedor, obtendrás un error de autenticación en tiempo de ejecución (por ejemplo, `No API key found for provider "zai"`). + Si haces referencia a un proveedor/modelo pero falta la clave requerida del proveedor, obtendrás un error de autenticación en tiempo de ejecución (por ejemplo `No API key found for provider "zai"`). - **No API key found for provider después de añadir un agent nuevo** + **No se encontró ninguna clave de API para el proveedor después de añadir un nuevo agent** - Normalmente esto significa que el **agent nuevo** tiene un almacén de autenticación vacío. La autenticación es por agent y - se guarda en: + Esto normalmente significa que el **nuevo agent** tiene un almacén de autenticación vacío. La autenticación es por agent y + se almacena en: ``` ~/.openclaw/agents//agent/auth-profiles.json ``` - Opciones para solucionarlo: + Opciones para corregirlo: - Ejecuta `openclaw agents add ` y configura la autenticación durante el asistente. - - O copia `auth-profiles.json` desde el `agentDir` del agent principal al `agentDir` del agent nuevo. + - O copia `auth-profiles.json` desde `agentDir` del agent principal al `agentDir` del nuevo agent. **No** reutilices `agentDir` entre agents; provoca colisiones de autenticación/sesión. -## Failover de modelos y "All models failed" +## Conmutación por error de modelos y "All models failed" - - El failover se produce en dos etapas: + + La conmutación por error ocurre en dos fases: 1. **Rotación de perfil de autenticación** dentro del mismo proveedor. - 2. **Fallback de modelo** al siguiente modelo en `agents.defaults.model.fallbacks`. + 2. **Respaldo de modelo** al siguiente modelo en `agents.defaults.model.fallbacks`. - A los perfiles que fallan se les aplican cooldowns (backoff exponencial), por lo que OpenClaw puede seguir respondiendo incluso cuando un proveedor está limitado por tasa o falla temporalmente. + Se aplican enfriamientos a los perfiles que fallan (retroceso exponencial), por lo que OpenClaw puede seguir respondiendo incluso cuando un proveedor tiene límite de tasa o falla temporalmente. El bucket de límite de tasa incluye algo más que respuestas `429` simples. OpenClaw también trata mensajes como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` y límites - periódicos de ventana de uso (`weekly/monthly limit reached`) como - límites de tasa dignos de failover. + periódicos de ventana de uso (`weekly/monthly limit reached`) como límites de tasa + dignos de conmutación por error. - Algunas respuestas con aspecto de facturación no son `402`, y algunas respuestas HTTP `402` + Algunas respuestas que parecen de facturación no son `402`, y algunas respuestas HTTP `402` también permanecen en ese bucket transitorio. Si un proveedor devuelve - texto explícito de facturación en `401` o `403`, OpenClaw puede seguir manteniéndolo en - la vía de facturación, pero los comparadores de texto específicos del proveedor permanecen acotados al - proveedor que los posee (por ejemplo, OpenRouter `Key limit exceeded`). Si un mensaje `402` - en cambio parece un límite reintentable de ventana de uso o - de gasto de organización/espacio de trabajo (`daily limit reached, resets tomorrow`, + texto explícito de facturación en `401` o `403`, OpenClaw aún puede mantener eso en + la vía de facturación, pero los comparadores de texto específicos del proveedor siguen limitados al + proveedor al que pertenecen (por ejemplo OpenRouter `Key limit exceeded`). Si un mensaje `402` + en cambio parece una ventana de uso reintentable o un + límite de gasto de organización/workspace (`daily limit reached, resets tomorrow`, `organization spending limit exceeded`), OpenClaw lo trata como - `rate_limit`, no como una desactivación larga por facturación. + `rate_limit`, no como una deshabilitación prolongada por facturación. Los errores de desbordamiento de contexto son diferentes: firmas como `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` u `ollama error: context length - exceeded` permanecen en la vía de compactación/reintento en lugar de avanzar al - fallback de modelo. + exceeded` permanecen en la ruta de Compaction/reintento en lugar de avanzar el + respaldo de modelo. - El texto genérico de error del servidor es deliberadamente más limitado que "cualquier cosa con - unknown/error". OpenClaw sí trata formas transitorias acotadas al proveedor, - como Anthropic con `An unknown error occurred` sin más, - OpenRouter con `Provider returned error` sin más, - errores de razón de parada como `Unhandled stop reason: + El texto genérico de error del servidor es intencionadamente más estrecho que "cualquier cosa con + unknown/error dentro". OpenClaw sí trata formas transitorias delimitadas por proveedor + como Anthropic bare `An unknown error occurred`, OpenRouter bare + `Provider returned error`, errores de razón de detención como `Unhandled stop reason: error`, cargas JSON `api_error` con texto transitorio de servidor (`internal server error`, `unknown error, 520`, `upstream error`, `backend error`) y errores de proveedor ocupado como `ModelNotReadyException` como - señales de timeout/sobrecarga dignas de failover cuando el contexto del proveedor + señales de tiempo de espera/sobrecarga dignas de conmutación por error cuando el contexto del proveedor coincide. - El texto interno de fallback genérico como `LLM request failed with an unknown - error.` sigue siendo conservador y no activa por sí solo el fallback de modelo. + El texto de respaldo interno genérico como `LLM request failed with an unknown + error.` se mantiene conservador y no activa por sí mismo el respaldo de modelo. Significa que el sistema intentó usar el id de perfil de autenticación `anthropic:default`, pero no pudo encontrar credenciales para él en el almacén de autenticación esperado. - **Lista de comprobación para solucionarlo:** + **Lista de comprobación para corregirlo:** - **Confirma dónde viven los perfiles de autenticación** (rutas nuevas frente a heredadas) - Actual: `~/.openclaw/agents//agent/auth-profiles.json` - Heredada: `~/.openclaw/agent/*` (migrada por `openclaw doctor`) - - **Confirma que la variable de entorno esté cargada por el Gateway** - - Si estableces `ANTHROPIC_API_KEY` en tu shell pero ejecutas el Gateway mediante systemd/launchd, puede que no la herede. Ponla en `~/.openclaw/.env` o habilita `env.shellEnv`. - - **Asegúrate de que estás editando el agent correcto** - - Las configuraciones multi-agent significan que puede haber varios archivos `auth-profiles.json`. - - **Haz una comprobación básica del estado de modelo/autenticación** + - **Confirma que el Gateway cargue tu variable de entorno** + - Si configuras `ANTHROPIC_API_KEY` en tu shell pero ejecutas el Gateway mediante systemd/launchd, puede que no la herede. Ponla en `~/.openclaw/.env` o habilita `env.shellEnv`. + - **Asegúrate de estar editando el agent correcto** + - Las configuraciones multiagente significan que puede haber varios archivos `auth-profiles.json`. + - **Comprueba el estado de modelo/autenticación** - Usa `openclaw models status` para ver los modelos configurados y si los proveedores están autenticados. - **Lista de comprobación para solucionar "No credentials found for profile anthropic"** + **Lista de comprobación para corregir "No credentials found for profile anthropic"** Esto significa que la ejecución está fijada a un perfil de autenticación de Anthropic, pero el Gateway no puede encontrarlo en su almacén de autenticación. @@ -2620,35 +2619,35 @@ para ver uso/facturación y aumenta los límites según sea necesario. - Ejecuta `openclaw models auth login --provider anthropic --method cli --set-default` en el host del gateway. - **Si quieres usar una clave de API en su lugar** - Pon `ANTHROPIC_API_KEY` en `~/.openclaw/.env` en el **host del gateway**. - - Borra cualquier orden fijado que fuerce un perfil inexistente: + - Borra cualquier orden fijado que fuerce un perfil ausente: ```bash openclaw models auth order clear --provider anthropic ``` - - **Confirma que estás ejecutando comandos en el host del gateway** + - **Confirma que estás ejecutando los comandos en el host del gateway** - En modo remoto, los perfiles de autenticación viven en la máquina del gateway, no en tu portátil. - - Si tu configuración de modelo incluye Google Gemini como fallback (o cambiaste a un atajo de Gemini), OpenClaw lo intentará durante el fallback de modelo. Si no has configurado credenciales de Google, verás `No API key found for provider "google"`. + + Si tu configuración de modelo incluye Google Gemini como respaldo (o cambiaste a un atajo de Gemini), OpenClaw lo probará durante el respaldo de modelo. Si no has configurado credenciales de Google, verás `No API key found for provider "google"`. - Solución: proporciona autenticación de Google o elimina/evita modelos de Google en `agents.defaults.model.fallbacks` / aliases para que el fallback no vaya allí. + Solución: proporciona autenticación de Google o elimina/evita los modelos de Google en `agents.defaults.model.fallbacks` / aliases para que el respaldo no se enrute allí. **LLM request rejected: thinking signature required (Google Antigravity)** - Causa: el historial de la sesión contiene **bloques de thinking sin firmas** (a menudo procedentes de - un flujo abortado/parcial). Google Antigravity exige firmas para los bloques de thinking. + Causa: el historial de la sesión contiene **bloques de thinking sin firmas** (a menudo de + un stream abortado/parcial). Google Antigravity requiere firmas para los bloques de thinking. - Solución: OpenClaw ahora elimina los bloques de thinking sin firma para Google Antigravity Claude. Si sigue apareciendo, inicia una **sesión nueva** o establece `/thinking off` para ese agent. + Solución: OpenClaw ahora elimina los bloques de thinking sin firmar para Google Antigravity Claude. Si sigue apareciendo, inicia una **sesión nueva** o configura `/thinking off` para ese agent. ## Perfiles de autenticación: qué son y cómo gestionarlos -Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento de tokens, patrones multi-account) +Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento de tokens, patrones de múltiples cuentas) @@ -2660,37 +2659,37 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento - - OpenClaw usa IDs con prefijo del proveedor, como: + + OpenClaw usa ids con prefijo del proveedor como: - - `anthropic:default` (habitual cuando no existe identidad de correo electrónico) + - `anthropic:default` (común cuando no existe identidad de correo electrónico) - `anthropic:` para identidades OAuth - - IDs personalizados que elijas (por ejemplo `anthropic:work`) + - ids personalizados que elijas (por ejemplo `anthropic:work`) - - Sí. La configuración admite metadatos opcionales para perfiles y un orden por proveedor (`auth.order.`). Esto **no** almacena secretos; asigna IDs a proveedor/modo y establece el orden de rotación. + + Sí. La configuración admite metadatos opcionales para perfiles y un orden por proveedor (`auth.order.`). Esto **no** almacena secretos; asigna ids a proveedor/modo y establece el orden de rotación. - OpenClaw puede omitir temporalmente un perfil si está en un **cooldown** corto (límites de tasa/timeouts/fallos de autenticación) o en un estado **disabled** más largo (facturación/créditos insuficientes). Para inspeccionarlo, ejecuta `openclaw models status --json` y revisa `auth.unusableProfiles`. Ajuste: `auth.cooldowns.billingBackoffHours*`. + OpenClaw puede omitir temporalmente un perfil si está en un **enfriamiento** corto (límites de tasa/tiempos de espera/fallos de autenticación) o en un estado **deshabilitado** más largo (facturación/créditos insuficientes). Para inspeccionarlo, ejecuta `openclaw models status --json` y comprueba `auth.unusableProfiles`. Ajuste: `auth.cooldowns.billingBackoffHours*`. - Los cooldowns por límite de tasa pueden estar acotados al modelo. Un perfil que está en cooldown - para un modelo puede seguir siendo utilizable para un modelo hermano del mismo proveedor, - mientras que las ventanas de facturación/desactivación siguen bloqueando todo el perfil. + Los enfriamientos por límite de tasa pueden estar delimitados por modelo. Un perfil que está en enfriamiento + para un modelo aún puede ser utilizable para un modelo hermano del mismo proveedor, + mientras que las ventanas de facturación/deshabilitación siguen bloqueando todo el perfil. - También puedes establecer una sobrescritura de orden **por agent** (almacenada en `auth-state.json` de ese agent) mediante la CLI: + También puedes establecer una anulación de orden **por agent** (almacenada en `auth-state.json` de ese agent) mediante la CLI: ```bash - # Por defecto, usa el agent predeterminado configurado (omite --agent) + # El valor predeterminado es el agent predeterminado configurado (omite --agent) openclaw models auth order get --provider anthropic - # Bloquear la rotación a un único perfil (probar solo este) + # Bloquea la rotación a un único perfil (solo prueba este) openclaw models auth order set --provider anthropic anthropic:default - # O establecer un orden explícito (fallback dentro del proveedor) + # O establece un orden explícito (respaldo dentro del proveedor) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Borrar la sobrescritura (volver a config auth.order / round-robin) + # Borra la anulación (vuelve a auth.order de config / round-robin) openclaw models auth order clear --provider anthropic ``` @@ -2700,24 +2699,24 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Para verificar qué se intentará realmente, usa: + Para verificar qué se probará realmente, usa: ```bash openclaw models status --probe ``` - Si un perfil almacenado se omite del orden explícito, el probe informa + Si se omite un perfil almacenado del orden explícito, probe informa `excluded_by_auth_order` para ese perfil en lugar de probarlo silenciosamente. - - OpenClaw admite ambas opciones: + + OpenClaw admite ambos: - - **OAuth** a menudo aprovecha el acceso por suscripción (cuando corresponde). - - **Las claves de API** usan facturación por token. + - **OAuth** suele aprovechar acceso por suscripción (cuando corresponde). + - **Claves de API** usan facturación por token. - El asistente soporta explícitamente Anthropic Claude CLI, OpenAI Codex OAuth y claves de API. + El asistente admite explícitamente Anthropic Claude CLI, OpenAI Codex OAuth y claves de API. @@ -2737,18 +2736,18 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento - Porque "running" es la vista del **supervisor** (launchd/systemd/schtasks). El probe RPC es la CLI conectándose realmente al WebSocket del gateway y llamando a `status`. + Porque "running" es la vista del **supervisor** (launchd/systemd/schtasks). La sonda RPC es la CLI conectándose realmente al Gateway WebSocket y llamando a `status`. Usa `openclaw gateway status` y confía en estas líneas: - - `Probe target:` (la URL que el probe usó realmente) + - `Probe target:` (la URL que realmente usó la sonda) - `Listening:` (lo que realmente está vinculado al puerto) - - `Last gateway error:` (causa raíz habitual cuando el proceso está vivo pero el puerto no está escuchando) + - `Last gateway error:` (causa raíz común cuando el proceso está activo pero el puerto no está escuchando) - Estás editando un archivo de configuración mientras el servicio está ejecutando otro (a menudo por un desajuste de `--profile` / `OPENCLAW_STATE_DIR`). + Estás editando un archivo de configuración mientras el servicio está ejecutando otro distinto (a menudo por un desajuste de `--profile` / `OPENCLAW_STATE_DIR`). Solución: @@ -2756,7 +2755,7 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento openclaw gateway install --force ``` - Ejecuta eso desde el mismo `--profile` / entorno que quieres que use el servicio. + Ejecútalo desde el mismo `--profile` / entorno que quieres que use el servicio. @@ -2768,7 +2767,7 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento - Establece `gateway.mode: "remote"` y apunta a una URL WebSocket remota, opcionalmente con credenciales remotas de secreto compartido: + Configura `gateway.mode: "remote"` y apunta a una URL remota de WebSocket, opcionalmente con credenciales remotas de secreto compartido: ```json5 { @@ -2785,43 +2784,43 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento Notas: - - `openclaw gateway` solo se inicia cuando `gateway.mode` es `local` (o si pasas la bandera de sobrescritura). - - La app de macOS supervisa el archivo de configuración y cambia de modo en tiempo real cuando esos valores cambian. - - `gateway.remote.token` / `.password` son solo credenciales remotas del lado del cliente; no habilitan por sí mismas la autenticación del gateway local. + - `openclaw gateway` solo se inicia cuando `gateway.mode` es `local` (o si pasas el indicador de anulación). + - La app de macOS observa el archivo de configuración y cambia de modo en vivo cuando cambian estos valores. + - `gateway.remote.token` / `.password` son solo credenciales remotas del lado del cliente; no habilitan por sí solas la autenticación local del gateway. - Tu ruta de autenticación del gateway y el método de autenticación de la UI no coinciden. + La ruta de autenticación de tu gateway y el método de autenticación de la UI no coinciden. - Datos (según el código): + Hechos (según el código): - - La Control UI guarda el token en `sessionStorage` para la sesión actual de la pestaña del navegador y la URL de gateway seleccionada, por lo que las recargas en la misma pestaña siguen funcionando sin restaurar persistencia de token a largo plazo en localStorage. - - En `AUTH_TOKEN_MISMATCH`, los clientes de confianza pueden intentar un reintento limitado con un token de dispositivo en caché cuando el gateway devuelve pistas de reintento (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Ese reintento con token en caché ahora reutiliza los scopes aprobados en caché almacenados con el token del dispositivo. Los llamadores con `deviceToken` explícito / `scopes` explícitos siguen manteniendo el conjunto de scopes solicitado en lugar de heredar scopes en caché. - - Fuera de esa ruta de reintento, la precedencia de autenticación de conexión es: token/contraseña compartidos explícitos primero, luego `deviceToken` explícito, luego token de dispositivo almacenado y después token de bootstrap. - - Las comprobaciones de alcance del token de bootstrap tienen prefijos por rol. La allowlist integrada del operador de bootstrap solo satisface solicitudes de operador; node u otros roles que no sean de operador siguen necesitando scopes bajo el prefijo de su propio rol. + - La Control UI mantiene el token en `sessionStorage` para la sesión actual de la pestaña del navegador y la URL del gateway seleccionada, de modo que las actualizaciones en la misma pestaña siguen funcionando sin restaurar la persistencia de token de larga duración en localStorage. + - En `AUTH_TOKEN_MISMATCH`, los clientes de confianza pueden intentar un reintento acotado con un token de dispositivo en caché cuando el gateway devuelve sugerencias de reintento (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Ese reintento con token en caché ahora reutiliza los ámbitos aprobados en caché almacenados con el token del dispositivo. Los llamadores explícitos de `deviceToken` / `scopes` explícitos siguen manteniendo su conjunto de ámbitos solicitado en lugar de heredar los ámbitos en caché. + - Fuera de esa ruta de reintento, la precedencia de autenticación de conexión es: token/contraseña compartidos explícitos primero, luego `deviceToken` explícito, luego token de dispositivo almacenado y luego token de bootstrap. + - Las comprobaciones de ámbito de token de bootstrap llevan prefijo de rol. La lista de permitidos del operador de bootstrap integrada solo satisface solicitudes de operador; los roles node u otros roles no operadores siguen necesitando ámbitos con su propio prefijo de rol. Solución: - - La forma más rápida: `openclaw dashboard` (imprime + copia la URL del panel, intenta abrirla; muestra una pista de SSH si está en modo headless). - - Si todavía no tienes un token: `openclaw doctor --generate-gateway-token`. + - La forma más rápida: `openclaw dashboard` (imprime + copia la URL del panel, intenta abrirlo; muestra una sugerencia SSH si está sin interfaz). + - Si aún no tienes token: `openclaw doctor --generate-gateway-token`. - Si es remoto, primero crea un túnel: `ssh -N -L 18789:127.0.0.1:18789 user@host` y luego abre `http://127.0.0.1:18789/`. - - Modo de secreto compartido: establece `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` o `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, y luego pega el secreto correspondiente en la configuración de Control UI. - - Modo Tailscale Serve: asegúrate de que `gateway.auth.allowTailscale` esté habilitado y de que estés abriendo la URL de Serve, no una URL loopback/tailnet sin procesar que omita los encabezados de identidad de Tailscale. - - Modo trusted-proxy: asegúrate de estar accediendo a través del proxy con reconocimiento de identidad no loopback configurado, no de un proxy loopback en el mismo host ni de una URL del gateway sin procesar. - - Si el desajuste persiste después del único reintento, rota/vuelve a aprobar el token del dispositivo emparejado: + - Modo de secreto compartido: configura `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` o `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, y luego pega el secreto correspondiente en la configuración de Control UI. + - Modo Tailscale Serve: asegúrate de que `gateway.auth.allowTailscale` esté habilitado y de que estés abriendo la URL de Serve, no una URL sin procesar de loopback/tailnet que omita los encabezados de identidad de Tailscale. + - Modo trusted-proxy: asegúrate de estar llegando a través del proxy con reconocimiento de identidad no loopback configurado, no a través de un proxy loopback del mismo host ni de una URL sin procesar del gateway. + - Si el desajuste persiste después del único reintento, rota o vuelve 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, comprueba dos cosas: - las sesiones de dispositivos emparejados solo pueden rotar **su propio** dispositivo a menos que también tengan `operator.admin` - - los valores explícitos de `--scope` no pueden exceder los scopes actuales de operador del llamador - - ¿Sigues atascado? Ejecuta `openclaw status --all` y sigue [Troubleshooting](/es/gateway/troubleshooting). Consulta [Dashboard](/web/dashboard) para los detalles de autenticación. + - los valores explícitos de `--scope` no pueden superar los ámbitos actuales de operador del llamador + - ¿Sigues atascado? Ejecuta `openclaw status --all` y sigue [Solución de problemas](/es/gateway/troubleshooting). Consulta [Dashboard](/web/dashboard) para obtener detalles de autenticación. - - El bind `tailnet` elige una IP de Tailscale de tus interfaces de red (100.64.0.0/10). Si la máquina no está en Tailscale (o la interfaz está caída), no hay nada a lo que hacer bind. + + El bind `tailnet` elige una IP de Tailscale de tus interfaces de red (100.64.0.0/10). Si la máquina no está en Tailscale (o la interfaz está caída), no hay nada a lo que vincularse. Solución: @@ -2833,44 +2832,44 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento - Normalmente no: un Gateway puede ejecutar varios canales de mensajería y agents. Usa varios Gateways solo cuando necesites redundancia (por ejemplo, un bot de rescate) o aislamiento estricto. + Normalmente no: un Gateway puede ejecutar múltiples canales de mensajería y agents. Usa varios Gateways solo cuando necesites redundancia (por ejemplo, bot de rescate) o aislamiento fuerte. Sí, pero debes aislar: - `OPENCLAW_CONFIG_PATH` (configuración por instancia) - `OPENCLAW_STATE_DIR` (estado por instancia) - - `agents.defaults.workspace` (aislamiento del espacio de trabajo) + - `agents.defaults.workspace` (aislamiento del workspace) - `gateway.port` (puertos únicos) Configuración rápida (recomendada): - Usa `openclaw --profile ...` por instancia (crea automáticamente `~/.openclaw-`). - - Establece un `gateway.port` único en la configuración de cada perfil (o pasa `--port` para ejecuciones manuales). + - Configura un `gateway.port` único en la configuración de cada perfil (o pasa `--port` para ejecuciones manuales). - Instala un servicio por perfil: `openclaw --profile gateway install`. - Los perfiles también añaden sufijos a los nombres de los servicios (`ai.openclaw.`; heredados `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). - Guía completa: [Multiple gateways](/es/gateway/multiple-gateways). + Los perfiles también añaden sufijos a los nombres de servicio (`ai.openclaw.`; heredados `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Guía completa: [Múltiples gateways](/es/gateway/multiple-gateways). - + El Gateway es un **servidor WebSocket**, y espera que el primer mensaje sea - un frame `connect`. Si recibe cualquier otra cosa, cierra la conexión - con **código 1008** (violación de política). + una trama `connect`. Si recibe cualquier otra cosa, cierra la conexión + con **code 1008** (violación de política). Causas comunes: - - Abriste la URL **HTTP** en un navegador (`http://...`) en lugar de en un cliente WS. + - Abriste la URL **HTTP** en un navegador (`http://...`) en lugar de un cliente WS. - Usaste el puerto o la ruta incorrectos. - - Un proxy o túnel eliminó encabezados de autenticación o envió una solicitud que no era de Gateway. + - Un proxy o túnel eliminó los encabezados de autenticación o envió una solicitud que no era del Gateway. Soluciones rápidas: - 1. Usa la URL WS: `ws://:18789` (o `wss://...` si usas HTTPS). + 1. Usa la URL WS: `ws://:18789` (o `wss://...` si es HTTPS). 2. No abras el puerto WS en una pestaña normal del navegador. - 3. Si la autenticación está activa, incluye el token/contraseña en el frame `connect`. + 3. Si la autenticación está activada, incluye el token/contraseña en la trama `connect`. - Si usas la CLI o la TUI, la URL debería tener este aspecto: + Si estás usando la CLI o la TUI, la URL debería verse así: ``` openclaw tui --url ws://:18789 --token @@ -2881,43 +2880,43 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento -## Logging y depuración +## Registro y depuración - - Logs de archivo (estructurados): + + Registros de archivo (estructurados): ``` /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Puedes establecer una ruta estable mediante `logging.file`. El nivel de log del archivo se controla con `logging.level`. La verbosidad de consola se controla con `--verbose` y `logging.consoleLevel`. + Puedes configurar una ruta estable mediante `logging.file`. El nivel de registro del archivo se controla con `logging.level`. La verbosidad de la consola se controla con `--verbose` y `logging.consoleLevel`. - La forma más rápida de seguir los logs: + La forma más rápida de seguir el registro: ```bash openclaw logs --follow ``` - Logs del servicio/supervisor (cuando el gateway se ejecuta mediante launchd/systemd): + Registros del servicio/supervisor (cuando el gateway se ejecuta mediante launchd/systemd): - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` y `gateway.err.log` (predeterminado: `~/.openclaw/logs/...`; los perfiles usan `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Consulta [Troubleshooting](/es/gateway/troubleshooting) para más información. + Consulta [Solución de problemas](/es/gateway/troubleshooting) para más información. - Usa los helpers de gateway: + Usa los asistentes del gateway: ```bash openclaw gateway status openclaw gateway restart ``` - Si ejecutas el gateway manualmente, `openclaw gateway --force` puede reclamar el puerto. Consulta [Gateway](/es/gateway). + Si ejecutas el gateway manualmente, `openclaw gateway --force` puede recuperar el puerto. Consulta [Gateway](/es/gateway). @@ -2955,12 +2954,12 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento openclaw gateway run ``` - Documentación: [Windows (WSL2)](/es/platforms/windows), [Manual operativo del servicio Gateway](/es/gateway). + Documentación: [Windows (WSL2)](/es/platforms/windows), [Guía operativa del servicio Gateway](/es/gateway). - - Empieza con una comprobación rápida de estado: + + Empieza con una revisión rápida del estado: ```bash openclaw status @@ -2972,36 +2971,36 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento Causas comunes: - La autenticación del modelo no está cargada en el **host del gateway** (comprueba `models status`). - - El emparejamiento/allowlist del canal bloquea respuestas (comprueba la configuración del canal + logs). + - El emparejamiento/lista de permitidos del canal bloquea las respuestas (comprueba la configuración del canal + los registros). - WebChat/Dashboard está abierto sin el token correcto. Si estás en remoto, confirma que la conexión de túnel/Tailscale esté activa y que el - WebSocket del Gateway sea accesible. + Gateway WebSocket sea accesible. - Documentación: [Channels](/es/channels), [Troubleshooting](/es/gateway/troubleshooting), [Acceso remoto](/es/gateway/remote). + Documentación: [Channels](/es/channels), [Solución de problemas](/es/gateway/troubleshooting), [Acceso remoto](/es/gateway/remote). - + Normalmente esto significa que la UI perdió la conexión WebSocket. Comprueba: 1. ¿El Gateway está en ejecución? `openclaw gateway status` 2. ¿El Gateway está bien? `openclaw status` 3. ¿La UI tiene el token correcto? `openclaw dashboard` - 4. Si es remoto, ¿el enlace de túnel/Tailscale está activo? + 4. Si es remoto, ¿está activa la conexión de túnel/Tailscale? - Luego sigue los logs: + Luego sigue los registros: ```bash openclaw logs --follow ``` - Documentación: [Dashboard](/web/dashboard), [Acceso remoto](/es/gateway/remote), [Troubleshooting](/es/gateway/troubleshooting). + Documentación: [Dashboard](/web/dashboard), [Acceso remoto](/es/gateway/remote), [Solución de problemas](/es/gateway/troubleshooting). - - Empieza con logs y estado del canal: + + Empieza con los registros y el estado del canal: ```bash openclaw channels status @@ -3010,16 +3009,16 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento Luego relaciona 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. Reduce comandos de plugins/Skills/personalizados, o deshabilita `channels.telegram.commands.native` si no necesitas el menú. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` o errores de red similares: si estás en un VPS o detrás de un proxy, confirma que HTTPS saliente está permitido y que DNS funciona para `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: el menú de Telegram tiene demasiadas entradas. OpenClaw ya recorta al límite de Telegram y vuelve a intentarlo con menos comandos, pero algunas entradas del menú aún deben eliminarse. Reduce los comandos de plugins/skills/personalizados o desactiva `channels.telegram.commands.native` si no necesitas el menú. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` o errores de red similares: si estás en un VPS o detrás de un proxy, confirma que HTTPS saliente esté permitido y que DNS funcione para `api.telegram.org`. - Si el Gateway es remoto, asegúrate de estar mirando los logs en el host del Gateway. + Si el Gateway es remoto, asegúrate de estar consultando los registros en el host del Gateway. Documentación: [Telegram](/es/channels/telegram), [Solución de problemas de canales](/es/channels/troubleshooting). - + Primero confirma que el Gateway sea accesible y que el agent pueda ejecutarse: ```bash @@ -3028,14 +3027,14 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento openclaw logs --follow ``` - En la TUI, usa `/status` para ver el estado actual. Si esperas respuestas en un - canal de chat, asegúrate de que la entrega esté habilitada (`/deliver on`). + En la TUI, usa `/status` para ver el estado actual. Si esperas respuestas en un canal de chat, + asegúrate de que la entrega esté habilitada (`/deliver on`). Documentación: [TUI](/web/tui), [Comandos slash](/es/tools/slash-commands). - + Si instalaste el servicio: ```bash @@ -3044,7 +3043,7 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento ``` Esto detiene/inicia el **servicio supervisado** (launchd en macOS, systemd en Linux). - Úsalo cuando el Gateway se ejecute en segundo plano como daemon. + Usa esto cuando el Gateway se ejecute en segundo plano como demonio. Si lo estás ejecutando en primer plano, deténlo con Ctrl-C y luego: @@ -3052,7 +3051,7 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento openclaw gateway run ``` - Documentación: [Manual operativo del servicio Gateway](/es/gateway). + Documentación: [Guía operativa del servicio Gateway](/es/gateway). @@ -3066,15 +3065,15 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento - Inicia el Gateway con `--verbose` para obtener más detalle en consola. Luego inspecciona el archivo de log para ver autenticación de canales, enrutamiento de modelos y errores RPC. + Inicia el Gateway con `--verbose` para obtener más detalle en la consola. Luego inspecciona el archivo de registro para ver autenticación de canales, enrutamiento de modelos y errores de RPC. -## Multimedia y archivos adjuntos +## Medios y archivos adjuntos - - Los archivos adjuntos salientes del agent deben incluir una línea `MEDIA:` (en su propia línea). Consulta [Configuración del asistente OpenClaw](/es/start/openclaw) y [Envío del agent](/es/tools/agent-send). + + Los archivos adjuntos salientes del agente deben incluir una línea `MEDIA:` (en su propia línea). Consulta [Configuración del asistente OpenClaw](/es/start/openclaw) y [Envío de Agent](/es/tools/agent-send). Envío por CLI: @@ -3084,10 +3083,10 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento Comprueba también: - - El canal de destino soporta multimedia saliente y no está bloqueado por allowlists. - - El archivo está dentro de los límites de tamaño del proveedor (las imágenes se redimensionan hasta un máximo de 2048 px). - - `tools.fs.workspaceOnly=true` mantiene los envíos de rutas locales limitados al espacio de trabajo, temp/media-store y archivos validados por sandbox. - - `tools.fs.workspaceOnly=false` permite que `MEDIA:` envíe archivos locales del host que el agent ya puede leer, pero solo para multimedia más tipos de documento seguros (imágenes, audio, vídeo, PDF y documentos de Office). El texto sin formato y los archivos con apariencia de secreto siguen bloqueados. + - El canal de destino admite medios salientes y no está bloqueado por listas de permitidos. + - El archivo está dentro de los límites de tamaño del proveedor (las imágenes se redimensionan a un máximo de 2048 px). + - `tools.fs.workspaceOnly=true` mantiene los envíos de rutas locales limitados al workspace, temp/media-store y archivos validados por sandbox. + - `tools.fs.workspaceOnly=false` permite que `MEDIA:` envíe archivos locales del host que el agente ya puede leer, pero solo para medios más tipos de documento seguros (imágenes, audio, video, PDF y documentos de Office). Los archivos de texto sin formato y similares a secretos siguen bloqueados. Consulta [Imágenes](/es/nodes/images). @@ -3097,72 +3096,72 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento ## Seguridad y control de acceso - - Trata los DM entrantes como entrada no fiable. Los valores predeterminados están diseñados para reducir el riesgo: + + Trata los MD entrantes como entrada no confiable. Los valores predeterminados están diseñados para reducir el riesgo: - - El comportamiento predeterminado en canales compatibles con DM es el **emparejamiento**: + - El comportamiento predeterminado en canales compatibles con MD es **emparejamiento**: - Los remitentes desconocidos reciben un código de emparejamiento; el bot no procesa su mensaje. - - Apruébalo con: `openclaw pairing approve --channel [--account ] ` + - Aprueba con: `openclaw pairing approve --channel [--account ] ` - Las solicitudes pendientes están limitadas a **3 por canal**; comprueba `openclaw pairing list --channel [--account ]` si no llegó un código. - - Abrir los DM públicamente requiere una activación explícita (`dmPolicy: "open"` y allowlist `"*"`). + - Abrir los MD públicamente requiere aceptación explícita (`dmPolicy: "open"` y lista de permitidos `"*"`). - Ejecuta `openclaw doctor` para detectar políticas de DM arriesgadas. + Ejecuta `openclaw doctor` para detectar políticas de MD arriesgadas. - - No. La prompt injection tiene que ver con **contenido no fiable**, no solo con quién puede enviar DM al bot. - Si tu asistente lee contenido externo (búsqueda/recuperación web, páginas del navegador, correos, - documentos, archivos adjuntos, logs pegados), ese contenido puede incluir instrucciones que intenten + + No. La inyección de prompts trata sobre **contenido no confiable**, no solo sobre quién puede enviar MD al bot. + Si tu asistente lee contenido externo (búsqueda/captura web, páginas del navegador, correos, + documentos, archivos adjuntos, registros pegados), ese contenido puede incluir instrucciones que intenten secuestrar el modelo. Esto puede ocurrir incluso si **tú eres el único remitente**. - El mayor riesgo aparece cuando hay herramientas habilitadas: se puede engañar al modelo para que - exfiltre contexto o llame herramientas en tu nombre. Reduce el radio de impacto mediante: + El mayor riesgo aparece cuando las herramientas están habilitadas: se puede engañar al modelo para + que exfiltre contexto o llame herramientas en tu nombre. Reduce el alcance del daño: - - usar un agent de "lector" de solo lectura o sin herramientas para resumir contenido no fiable - - mantener `web_search` / `web_fetch` / `browser` desactivados en agents con herramientas habilitadas - - tratar también como no fiable el texto decodificado de archivos/documentos: OpenResponses - `input_file` y la extracción de archivos adjuntos multimedia envuelven ambos el texto extraído en + - usando un agent "lector" de solo lectura o con herramientas deshabilitadas para resumir contenido no confiable + - manteniendo `web_search` / `web_fetch` / `browser` desactivados para agents con herramientas habilitadas + - tratando también como no confiable el texto decodificado de archivos/documentos: OpenResponses + `input_file` y la extracción de archivos adjuntos multimedia envuelven el texto extraído en marcadores explícitos de límite de contenido externo en lugar de pasar el texto bruto del archivo - - sandboxing y allowlists estrictas de herramientas + - usando sandboxing y listas estrictas de herramientas permitidas - Detalles: [Security](/es/gateway/security). + Detalles: [Seguridad](/es/gateway/security). - - Sí, en la mayoría de las configuraciones. Aislar el bot con cuentas y números de teléfono separados - reduce el radio de impacto si algo sale mal. Esto también facilita rotar + + Sí, para la mayoría de las configuraciones. Aislar el bot con cuentas y números de teléfono separados + reduce el alcance del daño si algo sale mal. También facilita rotar credenciales o revocar acceso sin afectar a tus cuentas personales. - Empieza poco a poco. Da acceso solo a las herramientas y cuentas que realmente necesites y amplíalo + Empieza poco a poco. Dale acceso solo a las herramientas y cuentas que realmente necesites, y amplíalo más adelante si hace falta. - Documentación: [Security](/es/gateway/security), [Pairing](/es/channels/pairing). + Documentación: [Seguridad](/es/gateway/security), [Emparejamiento](/es/channels/pairing). **No** recomendamos autonomía total sobre tus mensajes personales. El patrón más seguro es: - - Mantén los DM en **modo pairing** o con una allowlist estricta. - - Usa un **número o cuenta independiente** si quieres que envíe mensajes en tu nombre. - - Deja que redacte y luego **aprueba antes de enviar**. + - Mantener los MD en **modo de emparejamiento** o con una lista de permitidos estricta. + - Usar un **número o cuenta separados** si quieres que envíe mensajes en tu nombre. + - Dejar que redacte y luego **aprobar antes de enviar**. Si quieres experimentar, hazlo con una cuenta dedicada y mantenla aislada. Consulta - [Security](/es/gateway/security). + [Seguridad](/es/gateway/security). - Sí, **siempre que** el agent sea solo de chat y la entrada sea fiable. Los niveles más pequeños son - más susceptibles al secuestro de instrucciones, así que evítalos en agents con herramientas habilitadas - o cuando lean contenido no fiable. Si tienes que usar un modelo más pequeño, restringe - las herramientas y ejecútalo dentro de un sandbox. Consulta [Security](/es/gateway/security). + Sí, **si** el agent es solo de chat y la entrada es confiable. Los niveles más pequeños son + más susceptibles al secuestro por instrucciones, así que evítalos en agents con herramientas habilitadas + o al leer contenido no confiable. Si debes usar un modelo más pequeño, bloquea + las herramientas y ejecútalo dentro de un sandbox. Consulta [Seguridad](/es/gateway/security). - - Los códigos de pairing se envían **solo** cuando un remitente desconocido manda un mensaje al bot y + + 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: @@ -3171,15 +3170,15 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento openclaw pairing list telegram ``` - Si quieres acceso inmediato, añade tu id de remitente a la allowlist o establece `dmPolicy: "open"` + Si quieres acceso inmediato, añade tu id de remitente a la lista de permitidos o configura `dmPolicy: "open"` para esa cuenta. - - No. La política predeterminada de DM de WhatsApp es **pairing**. Los remitentes desconocidos solo reciben un código de pairing y su mensaje **no se procesa**. OpenClaw solo responde a chats que recibe o a envíos explícitos que tú actives. + + No. La política predeterminada de MD 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 envíos explícitos que tú actives. - Aprueba el pairing con: + Aprueba el emparejamiento con: ```bash openclaw pairing approve whatsapp @@ -3191,15 +3190,15 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento openclaw pairing list whatsapp ``` - La solicitud del asistente para el número de teléfono se usa para establecer tu **allowlist/propietario** y permitir tus propios DM. No se usa para envío automático. Si lo ejecutas con tu número personal de WhatsApp, usa ese número y habilita `channels.whatsapp.selfChatMode`. + Aviso del número de teléfono en el asistente: se usa para configurar tu **lista de permitidos/propietario** para que tus propios MD estén permitidos. No se usa para envío automático. Si ejecutas OpenClaw con tu número personal de WhatsApp, usa ese número y habilita `channels.whatsapp.selfChatMode`. -## Comandos de chat, cancelación de tareas y "no se detiene" +## Comandos de chat, abortar tareas y "no se detiene" - + La mayoría de los mensajes internos o de herramientas solo aparecen cuando **verbose**, **trace** o **reasoning** están habilitados para esa sesión. @@ -3211,16 +3210,16 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento /reasoning off ``` - Si sigue habiendo demasiado ruido, comprueba la configuración de la sesión en la Control UI y establece verbose - en **inherit**. Confirma también que no estés usando un perfil de bot con `verboseDefault` establecido + Si sigue habiendo demasiado ruido, comprueba la configuración de la sesión en la Control UI y pon verbose + en **inherit**. Confirma también que no estés usando un perfil de bot con `verboseDefault` configurado en `on` en la configuración. - Documentación: [Thinking y verbose](/es/tools/thinking), [Security](/es/gateway/security#reasoning-verbose-output-in-groups). + Documentación: [Thinking y verbose](/es/tools/thinking), [Seguridad](/es/gateway/security#reasoning-verbose-output-in-groups). - Envía cualquiera de estos **como mensaje independiente** (sin slash): + Envía cualquiera de estas opciones **como mensaje independiente** (sin slash): ``` stop @@ -3244,9 +3243,9 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento interrupt ``` - Estos son disparadores de cancelación (no comandos slash). + Estos son activadores de aborto (no comandos slash). - Para procesos en segundo plano (de la herramienta exec), puedes pedir al agent que ejecute: + Para procesos en segundo plano (de la herramienta exec), puedes pedir al agente que ejecute: ``` process action:kill sessionId:XXX @@ -3254,12 +3253,12 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento Resumen de comandos slash: consulta [Comandos slash](/es/tools/slash-commands). - La mayoría de los comandos deben enviarse como mensaje **independiente** que comience con `/`, pero algunos atajos (como `/status`) también funcionan en línea para remitentes en allowlist. + La mayoría de los comandos deben enviarse como mensaje **independiente** que empiece por `/`, pero algunos atajos (como `/status`) también funcionan en línea para remitentes en lista de permitidos. - OpenClaw bloquea la mensajería **entre proveedores** por defecto. Si una llamada de herramienta está vinculada + OpenClaw bloquea la mensajería **entre proveedores** de forma predeterminada. Si una llamada de herramienta está vinculada a Telegram, no enviará a Discord a menos que lo permitas explícitamente. Habilita la mensajería entre proveedores para el agent: @@ -3281,28 +3280,28 @@ Relacionado: [/concepts/oauth](/es/concepts/oauth) (flujos OAuth, almacenamiento - + El modo de cola controla cómo interactúan los mensajes nuevos con una ejecución en curso. Usa `/queue` para cambiar de modo: - `steer` - los mensajes nuevos redirigen la tarea actual - - `followup` - ejecuta los mensajes de uno en uno - - `collect` - agrupa mensajes y responde una vez (predeterminado) - - `steer-backlog` - redirige ahora y luego procesa la cola pendiente - - `interrupt` - cancela la ejecución actual y empieza de nuevo + - `followup` - ejecuta los mensajes uno a uno + - `collect` - agrupa los mensajes y responde una sola vez (predeterminado) + - `steer-backlog` - redirige ahora y luego procesa la cola acumulada + - `interrupt` - aborta la ejecución actual y empieza de nuevo - Puedes añadir opciones como `debounce:2s cap:25 drop:summarize` para modos followup. + Puedes añadir opciones como `debounce:2s cap:25 drop:summarize` para modos de seguimiento. -## Varios +## Miscelánea - En OpenClaw, las credenciales y la selección de modelo son independientes. Establecer `ANTHROPIC_API_KEY` (o guardar una clave de API de Anthropic en perfiles de autenticación) habilita la autenticación, pero el modelo predeterminado real es el que configures en `agents.defaults.model.primary` (por ejemplo, `anthropic/claude-sonnet-4-6` o `anthropic/claude-opus-4-6`). Si ves `No credentials found for profile "anthropic:default"`, significa que el Gateway no pudo encontrar credenciales de Anthropic en el `auth-profiles.json` esperado para el agent que se está ejecutando. + En OpenClaw, las credenciales y la selección de modelo están separadas. Configurar `ANTHROPIC_API_KEY` (o almacenar una clave de API de Anthropic en perfiles de autenticación) habilita la autenticación, pero el modelo predeterminado real es el que configures en `agents.defaults.model.primary` (por ejemplo, `anthropic/claude-sonnet-4-6` o `anthropic/claude-opus-4-6`). Si ves `No credentials found for profile "anthropic:default"`, significa que el Gateway no pudo encontrar credenciales de Anthropic en el `auth-profiles.json` esperado para el agent en ejecución. --- -¿Sigues atascado? Pregunta en [Discord](https://discord.com/invite/clawd) o abre una [discusión de GitHub](https://github.com/openclaw/openclaw/discussions). +¿Sigues atascado? Pregunta en [Discord](https://discord.com/invite/clawd) o abre una [discusión en GitHub](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/es/help/testing.md b/docs/es/help/testing.md index 6ce364cc2..1e75287f3 100644 --- a/docs/es/help/testing.md +++ b/docs/es/help/testing.md @@ -2,14 +2,14 @@ read_when: - Ejecutar pruebas localmente o en CI - Agregar regresiones para errores de modelo/proveedor - - Depurar el comportamiento de Gateway + agente + - Depurar el comportamiento de Gateway + agent summary: 'Kit de pruebas: suites unitarias/e2e/live, ejecutores de Docker y qué cubre cada prueba' title: Pruebas x-i18n: - generated_at: "2026-04-18T04:59:12Z" + generated_at: "2026-04-20T05:21:30Z" model: gpt-5.4 provider: openai - source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a + source_hash: 88457038e2e2c7940d0348762d0ece187111a8c61fa9bad54b39eade4217ddbc source_path: help/testing.md workflow: 15 --- @@ -22,20 +22,20 @@ Este documento es una guía de “cómo probamos”: - Qué cubre cada suite (y qué _deliberadamente_ no cubre) - Qué comandos ejecutar para flujos de trabajo comunes (local, antes de hacer push, depuración) -- Cómo las pruebas live descubren credenciales y seleccionan modelos/proveedores -- Cómo agregar regresiones para problemas reales de modelo/proveedor +- Cómo las pruebas live detectan credenciales y seleccionan modelos/proveedores +- Cómo agregar regresiones para problemas reales de modelos/proveedores ## Inicio rápido La mayoría de los días: - Puerta completa (esperada antes de hacer push): `pnpm build && pnpm check && pnpm test` -- Ejecución local más rápida de la suite completa en una máquina con buenos recursos: `pnpm test:max` -- Bucle directo de vigilancia de Vitest: `pnpm test:watch` -- El direccionamiento directo a archivos ahora también enruta rutas de extensiones/canales: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Ejecución local más rápida de la suite completa en una máquina con buena capacidad: `pnpm test:max` +- Bucle directo de observación de Vitest: `pnpm test:watch` +- El direccionamiento directo de archivos ahora también enruta rutas de extensiones/canales: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Prefiere primero las ejecuciones dirigidas cuando estés iterando sobre un único fallo. - Sitio de QA respaldado por Docker: `pnpm qa:lab:up` -- Canal de QA respaldado por VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Carril de QA respaldado por VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Cuando tocas pruebas o quieres más confianza: @@ -44,66 +44,65 @@ Cuando tocas pruebas o quieres más confianza: Al depurar proveedores/modelos reales (requiere credenciales reales): -- Suite live (sondeos de modelos + herramientas/imágenes de Gateway): `pnpm test:live` -- Apuntar silenciosamente a un solo archivo live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (sondas de modelos + herramientas/imágenes de Gateway): `pnpm test:live` +- Ejecutar un archivo live silenciosamente: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Consejo: cuando solo necesites un caso fallido, prefiere acotar las pruebas live mediante las variables de entorno de lista permitida descritas abajo. +Consejo: cuando solo necesites un caso fallido, prefiere acotar las pruebas live mediante las variables de entorno de allowlist descritas abajo. ## Ejecutores específicos de QA -Estos comandos están junto a las suites de prueba principales cuando necesitas el realismo de qa-lab: +Estos comandos se usan junto a las suites de prueba principales cuando necesitas el realismo de qa-lab: - `pnpm openclaw qa suite` - - Ejecuta escenarios de QA respaldados por el repositorio directamente en el host. - - Ejecuta en paralelo varios escenarios seleccionados por defecto con workers de Gateway aislados, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para el canal serial anterior. + - Ejecuta directamente en el host escenarios de QA respaldados por el repositorio. + - Ejecuta varios escenarios seleccionados en paralelo de forma predeterminada con workers aislados de Gateway. `qa-channel` usa por defecto concurrencia 4 (limitada por la cantidad de escenarios seleccionados). Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para el carril serial anterior. + - Sale con un código distinto de cero cuando falla cualquier escenario. Usa `--allow-failures` cuando quieras artefactos sin un código de salida fallido. - Admite los modos de proveedor `live-frontier`, `mock-openai` y `aimock`. - `aimock` inicia un servidor de proveedor local respaldado por AIMock para cobertura experimental de fixtures y simulaciones de protocolo sin reemplazar el canal `mock-openai` orientado a escenarios. + `aimock` inicia un servidor local de proveedor respaldado por AIMock para cobertura experimental de fixtures y simulaciones de protocolo, sin reemplazar el carril `mock-openai` orientado a escenarios. - `pnpm openclaw qa suite --runner multipass` - - Ejecuta la misma suite de QA dentro de una VM Linux Multipass desechable. + - Ejecuta la misma suite de QA dentro de una VM Linux desechable de Multipass. - Mantiene el mismo comportamiento de selección de escenarios que `qa suite` en el host. - - Reutiliza las mismas banderas de selección de proveedor/modelo que `qa suite`. + - Reutiliza las mismas opciones de selección de proveedor/modelo que `qa suite`. - Las ejecuciones live reenvían las entradas de autenticación de QA compatibles que son prácticas para el invitado: claves de proveedor basadas en env, la ruta de configuración del proveedor live de QA y `CODEX_HOME` cuando está presente. - Los directorios de salida deben permanecer bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través del espacio de trabajo montado. - - Escribe el informe + resumen normales de QA más los logs de Multipass en - `.artifacts/qa-e2e/...`. + - Escribe el informe y resumen normales de QA, además de los logs de Multipass, en `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia el sitio de QA respaldado por Docker para trabajo de QA estilo operador. + - Inicia el sitio de QA respaldado por Docker para trabajo de QA de estilo operador. - `pnpm openclaw qa aimock` - - Inicia solo el servidor de proveedor local AIMock para pruebas rápidas directas del protocolo. + - Inicia solo el servidor local de proveedor AIMock para pruebas directas de humo del protocolo. - `pnpm openclaw qa matrix` - - Ejecuta el canal de QA live de Matrix contra un homeserver Tuwunel desechable respaldado por Docker. - - Este host de QA hoy es solo para repositorio/desarrollo. Las instalaciones empaquetadas de OpenClaw no incluyen - `qa-lab`, por lo que no exponen `openclaw qa`. - - Los checkouts del repositorio cargan el ejecutor integrado directamente; no se necesita un paso separado de instalación del Plugin. + - Ejecuta el carril live de QA de Matrix contra un homeserver Tuwunel desechable respaldado por Docker. + - Este host de QA hoy es solo para repositorio/desarrollo. Las instalaciones empaquetadas de OpenClaw no incluyen `qa-lab`, por lo que no exponen `openclaw qa`. + - Los checkouts del repositorio cargan directamente el ejecutor integrado; no se necesita un paso separado de instalación de Plugin. - Aprovisiona tres usuarios temporales de Matrix (`driver`, `sut`, `observer`) más una sala privada, y luego inicia un proceso hijo de Gateway de QA con el Plugin real de Matrix como transporte SUT. - - Usa la imagen estable fijada de Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1` por defecto. Sustitúyela con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` cuando necesites probar una imagen diferente. - - Matrix no expone banderas compartidas de origen de credenciales porque el canal aprovisiona usuarios desechables localmente. - - Escribe un informe de QA de Matrix, un resumen, un artefacto de eventos observados y un log combinado de salida estándar/error estándar en `.artifacts/qa-e2e/...`. + - Usa por defecto la imagen estable fijada de Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sobrescribe con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` cuando necesites probar una imagen distinta. + - Matrix no expone opciones compartidas de fuentes de credenciales porque el carril aprovisiona usuarios desechables localmente. + - Escribe un informe de QA de Matrix, resumen, artefacto de eventos observados y un log combinado de stdout/stderr en `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Ejecuta el canal de QA live de Telegram contra un grupo privado real usando los tokens del bot driver y del bot SUT desde env. + - Ejecuta el carril live de QA de Telegram contra un grupo privado real usando los tokens de bot de driver y SUT desde env. - Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. El id del grupo debe ser el id numérico del chat de Telegram. - - Admite `--credential-source convex` para credenciales compartidas en pool. Usa el modo env por defecto, o establece `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por arrendamientos compartidos. + - Admite `--credential-source convex` para credenciales compartidas agrupadas. Usa el modo env de forma predeterminada, o establece `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases agrupados. + - Sale con un código distinto de cero cuando falla cualquier escenario. Usa `--allow-failures` cuando quieras artefactos sin un código de salida fallido. - Requiere dos bots distintos en el mismo grupo privado, con el bot SUT exponiendo un nombre de usuario de Telegram. - - Para una observación estable entre bots, habilita el modo de comunicación Bot-to-Bot en `@BotFather` para ambos bots y asegúrate de que el bot driver pueda observar el tráfico de bots del grupo. - - Escribe un informe de QA de Telegram, un resumen y un artefacto de mensajes observados en `.artifacts/qa-e2e/...`. + - Para una observación estable entre bots, habilita el modo de comunicación bot a bot en `@BotFather` para ambos bots y asegúrate de que el bot driver pueda observar el tráfico de bots del grupo. + - Escribe un informe de QA de Telegram, resumen y artefacto de mensajes observados en `.artifacts/qa-e2e/...`. -Los canales de transporte live comparten un contrato estándar para que los nuevos transportes no diverjan: +Los carriles de transporte live comparten un contrato estándar para que los nuevos transportes no se desvíen: `qa-channel` sigue siendo la suite amplia de QA sintética y no forma parte de la matriz de cobertura de transporte live. -| Canal | Canary | Mención obligatoria | Bloqueo por lista permitida | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando help | -| -------- | ------ | ------------------- | --------------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Carril | Canary | Mención obligatoria | Bloqueo de allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda | +| -------- | ------ | ------------------- | -------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenciales compartidas de Telegram mediante Convex (v1) Cuando `--credential-source convex` (o `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para -`openclaw qa telegram`, qa-lab adquiere un arrendamiento exclusivo de un pool respaldado por Convex, envía Heartbeat -de ese arrendamiento mientras el canal está en ejecución y libera el arrendamiento al cerrarse. +`openclaw qa telegram`, QA lab adquiere un lease exclusivo de un pool respaldado por Convex, envía Heartbeat de ese lease mientras el carril está en ejecución y libera el lease al finalizar. -Andamiaje de referencia del proyecto Convex: +Referencia del andamiaje del proyecto Convex: - `qa/convex-credential-broker/` @@ -115,7 +114,7 @@ Variables de entorno obligatorias: - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` - Selección del rol de credencial: - CLI: `--credential-role maintainer|ci` - - Valor predeterminado en env: `OPENCLAW_QA_CREDENTIAL_ROLE` (por defecto `maintainer`) + - Valor predeterminado en env: `OPENCLAW_QA_CREDENTIAL_ROLE` (usa `ci` por defecto en CI y `maintainer` en cualquier otro caso) Variables de entorno opcionales: @@ -125,14 +124,14 @@ Variables de entorno opcionales: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (predeterminado `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (predeterminado `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreo opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs de Convex `http://` de loopback para desarrollo exclusivamente local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs de Convex con `http://` en loopback para desarrollo únicamente local. -`OPENCLAW_QA_CONVEX_SITE_URL` debe usar `https://` en funcionamiento normal. +`OPENCLAW_QA_CONVEX_SITE_URL` debe usar `https://` en operación normal. -Los comandos administrativos de mantenimiento (agregar/eliminar/listar pool) requieren -específicamente `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Los comandos administrativos de mantenedor (agregar/eliminar/listar del pool) requieren específicamente +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Ayudantes de CLI para mantenedores: +Helpers de CLI para mantenedores: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -146,30 +145,30 @@ Contrato predeterminado del endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-crede - `POST /acquire` - Solicitud: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - - Éxito: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` + - Correcto: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - Agotado/reintentable: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Solicitud: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - Éxito: `{ status: "ok" }` (o `2xx` vacío) + - Correcto: `{ status: "ok" }` (o `2xx` vacío) - `POST /release` - Solicitud: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - - Éxito: `{ status: "ok" }` (o `2xx` vacío) -- `POST /admin/add` (solo con secreto de maintainer) + - Correcto: `{ status: "ok" }` (o `2xx` vacío) +- `POST /admin/add` (solo secreto de maintainer) - Solicitud: `{ kind, actorId, payload, note?, status? }` - - Éxito: `{ status: "ok", credential }` -- `POST /admin/remove` (solo con secreto de maintainer) + - Correcto: `{ status: "ok", credential }` +- `POST /admin/remove` (solo secreto de maintainer) - Solicitud: `{ credentialId, actorId }` - - Éxito: `{ status: "ok", changed, credential }` - - Protección por arrendamiento activo: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (solo con secreto de maintainer) + - Correcto: `{ status: "ok", changed, credential }` + - Protección de lease activo: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (solo secreto de maintainer) - Solicitud: `{ kind?, status?, includePayload?, limit? }` - - Éxito: `{ status: "ok", credentials, count }` + - Correcto: `{ status: "ok", credentials, count }` -Forma de la carga útil para el tipo Telegram: +Forma de payload para el tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` debe ser una cadena con el id numérico del chat de Telegram. -- `admin/add` valida esta forma para `kind: "telegram"` y rechaza cargas útiles mal formadas. +- `admin/add` valida esta forma para `kind: "telegram"` y rechaza payloads mal formados. ### Agregar un canal a QA @@ -178,50 +177,49 @@ Agregar un canal al sistema de QA en Markdown requiere exactamente dos cosas: 1. Un adaptador de transporte para el canal. 2. Un paquete de escenarios que ejercite el contrato del canal. -No agregues una nueva raíz de comandos de QA de nivel superior cuando el host compartido `qa-lab` pueda -controlar el flujo. +No agregues una nueva raíz de comandos de QA de nivel superior cuando el host compartido `qa-lab` pueda encargarse del flujo. -`qa-lab` controla la mecánica compartida del host: +`qa-lab` es responsable de la mecánica compartida del host: - la raíz de comandos `openclaw qa` -- inicio y desmontaje de la suite -- concurrencia de workers -- escritura de artefactos -- generación de informes -- ejecución de escenarios -- alias de compatibilidad para escenarios `qa-channel` antiguos +- el arranque y desmontaje de la suite +- la concurrencia de workers +- la escritura de artefactos +- la generación de informes +- la ejecución de escenarios +- los alias de compatibilidad para escenarios antiguos de `qa-channel` -Los plugins de ejecutor controlan el contrato de transporte: +Los Plugins de ejecutores son responsables del contrato de transporte: - cómo se monta `openclaw qa ` bajo la raíz compartida `qa` - cómo se configura Gateway para ese transporte -- cómo se verifica la preparación +- cómo se comprueba la preparación - cómo se inyectan eventos entrantes - cómo se observan los mensajes salientes - cómo se exponen las transcripciones y el estado de transporte normalizado -- cómo se ejecutan acciones respaldadas por transporte -- cómo se maneja el restablecimiento o la limpieza específicos del transporte +- cómo se ejecutan las acciones respaldadas por transporte +- cómo se maneja el restablecimiento o limpieza específicos del transporte -El requisito mínimo de adopción para un canal nuevo es: +El umbral mínimo de adopción para un nuevo canal es: 1. Mantener `qa-lab` como propietario de la raíz compartida `qa`. -2. Implementar el ejecutor de transporte en la interfaz compartida del host `qa-lab`. -3. Mantener la mecánica específica del transporte dentro del plugin del ejecutor o del arnés del canal. +2. Implementar el ejecutor de transporte sobre la interfaz compartida del host `qa-lab`. +3. Mantener la mecánica específica del transporte dentro del Plugin del ejecutor o del arnés del canal. 4. Montar el ejecutor como `openclaw qa ` en lugar de registrar una raíz de comandos competidora. - Los plugins de ejecutor deben declarar `qaRunners` en `openclaw.plugin.json` y exportar un arreglo `qaRunnerCliRegistrations` coincidente desde `runtime-api.ts`. - Mantén `runtime-api.ts` liviano; la ejecución diferida de CLI y del ejecutor debe permanecer detrás de entrypoints separados. -5. Crear o adaptar escenarios en Markdown bajo los directorios temáticos `qa/scenarios/`. -6. Usar los ayudantes genéricos de escenarios para escenarios nuevos. -7. Mantener funcionando los alias de compatibilidad existentes, a menos que el repositorio esté haciendo una migración intencional. + Los Plugins de ejecutores deben declarar `qaRunners` en `openclaw.plugin.json` y exportar una matriz coincidente `qaRunnerCliRegistrations` desde `runtime-api.ts`. + Mantén `runtime-api.ts` ligero; la ejecución diferida de CLI y del ejecutor debe permanecer detrás de puntos de entrada separados. +5. Crear o adaptar escenarios Markdown bajo los directorios temáticos `qa/scenarios/`. +6. Usar los helpers genéricos de escenarios para los nuevos escenarios. +7. Mantener en funcionamiento los alias de compatibilidad existentes salvo que el repositorio esté realizando una migración intencional. La regla de decisión es estricta: -- Si un comportamiento puede expresarse una sola vez en `qa-lab`, ponlo en `qa-lab`. -- Si un comportamiento depende de un transporte de canal, mantenlo en ese plugin de ejecutor o arnés de plugin. -- Si un escenario necesita una nueva capacidad que más de un canal pueda usar, agrega un ayudante genérico en lugar de una rama específica del canal en `suite.ts`. -- Si un comportamiento solo tiene sentido para un transporte, mantén el escenario específico de ese transporte y hazlo explícito en el contrato del escenario. +- Si el comportamiento puede expresarse una sola vez en `qa-lab`, colócalo en `qa-lab`. +- Si el comportamiento depende de un único transporte de canal, mantenlo en ese Plugin de ejecutor o arnés del Plugin. +- Si un escenario necesita una nueva capacidad que pueda usar más de un canal, agrega un helper genérico en lugar de una rama específica de canal en `suite.ts`. +- Si un comportamiento solo tiene sentido para un transporte, mantén el escenario específico del transporte y hazlo explícito en el contrato del escenario. -Los nombres preferidos de ayudantes genéricos para escenarios nuevos son: +Los nombres preferidos de helpers genéricos para nuevos escenarios son: - `waitForTransportReady` - `waitForChannelReady` @@ -244,102 +242,101 @@ Los alias de compatibilidad siguen disponibles para escenarios existentes, inclu - `formatConversationTranscript` - `resetBus` -El trabajo en canales nuevos debe usar los nombres de ayudantes genéricos. -Los alias de compatibilidad existen para evitar una migración de un solo día, no como modelo para -la creación de escenarios nuevos. +El trabajo en nuevos canales debe usar los nombres genéricos de los helpers. +Los alias de compatibilidad existen para evitar una migración de tipo flag day, no como modelo para redactar escenarios nuevos. -## Suites de prueba (qué se ejecuta dónde) +## Suites de prueba (qué se ejecuta y dónde) -Piense en las suites como “realismo creciente” (y mayor inestabilidad/costo): +Piensa en las suites como de “realismo creciente” (y también de mayor inestabilidad/costo): ### Unitarias / integración (predeterminada) - Comando: `pnpm test` -- Configuración: diez ejecuciones secuenciales por shard (`vitest.full-*.config.ts`) sobre los proyectos de Vitest acotados existentes -- Archivos: inventarios core/unit en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas de nodo de `ui` incluidas en la lista permitida cubiertas por `vitest.unit.config.ts` +- Configuración: diez ejecuciones secuenciales de shards (`vitest.full-*.config.ts`) sobre los proyectos de Vitest acotados existentes +- Archivos: inventarios core/unit en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas de node en `ui` incluidas en allowlist cubiertas por `vitest.unit.config.ts` - Alcance: - Pruebas unitarias puras - - Pruebas de integración en proceso (autenticación de Gateway, enrutamiento, herramientas, parsing, configuración) + - Pruebas de integración en proceso (autenticación de gateway, enrutamiento, herramientas, análisis, configuración) - Regresiones deterministas para errores conocidos - Expectativas: - Se ejecuta en CI - No requiere claves reales - Debe ser rápida y estable - Nota sobre proyectos: - - `pnpm test` sin objetivo ahora ejecuta once configuraciones por shard más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso raíz nativo gigante. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas. - - `pnpm test --watch` sigue usando el grafo de proyectos nativo de `vitest.config.ts`, porque un bucle de watch con múltiples shards no es práctico. - - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` dirigen primero objetivos explícitos de archivo/directorio a través de canales acotados, por lo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo de inicio completo del proyecto raíz. - - `pnpm test:changed` expande las rutas git modificadas a los mismos canales acotados cuando el diff solo toca archivos fuente/de prueba enrutable; las ediciones de configuración/preparación siguen recurriendo a la reejecución amplia del proyecto raíz. - - Las pruebas unitarias livianas en importación de agentes, comandos, plugins, ayudantes de auto-reply, `plugin-sdk` y áreas utilitarias puras similares se dirigen al canal `unit-fast`, que omite `test/setup-openclaw-runtime.ts`; los archivos pesados con estado/runtime permanecen en los canales existentes. - - Algunos archivos fuente auxiliares seleccionados de `plugin-sdk` y `commands` también mapean ejecuciones en modo changed a pruebas hermanas explícitas en esos canales livianos, para que las ediciones en ayudantes eviten volver a ejecutar la suite pesada completa de ese directorio. - - `auto-reply` ahora tiene tres buckets dedicados: ayudantes core de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de respuesta fuera de las pruebas baratas de status/chunk/token. + - `pnpm test` sin objetivos ahora ejecuta once configuraciones de shards más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso gigante del proyecto raíz nativo. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones bloquee suites no relacionadas. + - `pnpm test --watch` sigue usando el grafo de proyectos raíz nativo de `vitest.config.ts`, porque un bucle watch con múltiples shards no es práctico. + - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` enrutan primero los objetivos explícitos de archivo/directorio por carriles acotados, de modo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo completo de arranque del proyecto raíz. + - `pnpm test:changed` expande las rutas git modificadas a esos mismos carriles acotados cuando el diff solo toca archivos de origen/prueba enrutable; las ediciones de configuración/preparación siguen recurriendo a la reejecución amplia del proyecto raíz. + - Las pruebas unitarias ligeras de importación de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` y áreas utilitarias similares se enrutan por el carril `unit-fast`, que omite `test/setup-openclaw-runtime.ts`; los archivos con estado o con runtime más pesado permanecen en los carriles existentes. + - Algunos archivos helper de origen de `plugin-sdk` y `commands` también asignan las ejecuciones en modo changed a pruebas hermanas explícitas en esos carriles ligeros, de modo que editar helpers evita volver a ejecutar la suite pesada completa de ese directorio. + - `auto-reply` ahora tiene tres buckets dedicados: helpers core de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de reply fuera de las pruebas baratas de estado/chunk/token. - Nota sobre el ejecutor integrado: - - Cuando cambies las entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de Compaction, + - Cuando cambies entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de Compaction, mantén ambos niveles de cobertura. - - Agrega regresiones centradas en ayudantes para límites puros de enrutamiento/normalización. - - También mantén sanas las suites de integración del ejecutor integrado: + - Agrega regresiones enfocadas de helpers para límites puros de enrutamiento/normalización. + - Mantén también saludables las suites de integración del ejecutor integrado: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` y `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Estas suites verifican que los ids acotados y el comportamiento de Compaction sigan fluyendo - por las rutas reales `run.ts` / `compact.ts`; las pruebas solo de ayudantes no son un - sustituto suficiente para esas rutas de integración. + - Esas suites verifican que los ids acotados y el comportamiento de Compaction sigan fluyendo + por las rutas reales `run.ts` / `compact.ts`; las pruebas solo de helpers no son un + sustituto suficiente de esas rutas de integración. - Nota sobre el pool: - - La configuración base de Vitest ahora usa `threads` por defecto. + - La configuración base de Vitest ahora usa `threads` de forma predeterminada. - La configuración compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos raíz, e2e y live. - - El canal UI raíz mantiene su configuración y optimizador de `jsdom`, pero ahora también se ejecuta en el ejecutor compartido no aislado. + - El carril raíz de UI mantiene su configuración `jsdom` y su optimizador, pero ahora también se ejecuta en el ejecutor compartido no aislado. - Cada shard de `pnpm test` hereda los mismos valores predeterminados `threads` + `isolate: false` de la configuración compartida de Vitest. - - El lanzador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` por defecto para los procesos Node hijo de Vitest para reducir la agitación de compilación de V8 durante grandes ejecuciones locales. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. + - El iniciador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` de forma predeterminada para los procesos hijo de Node de Vitest para reducir el churn de compilación de V8 durante ejecuciones locales grandes. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas compararlo con el comportamiento estándar de V8. - Nota sobre iteración local rápida: - - `pnpm test:changed` se enruta por canales acotados cuando las rutas modificadas se asignan limpiamente a una suite más pequeña. - - `pnpm test:max` y `pnpm test:changed:max` mantienen el mismo comportamiento de enrutamiento, solo que con un límite mayor de workers. - - El autoescalado local de workers ahora es intencionalmente conservador y también retrocede cuando la carga media del host ya es alta, por lo que múltiples ejecuciones concurrentes de Vitest causan menos daño por defecto. - - La configuración base de Vitest marca los archivos de proyectos/configuración como `forceRerunTriggers` para que las reejecuciones en modo changed sigan siendo correctas cuando cambia el cableado de pruebas. + - `pnpm test:changed` enruta por carriles acotados cuando las rutas modificadas se asignan limpiamente a una suite más pequeña. + - `pnpm test:max` y `pnpm test:changed:max` mantienen el mismo comportamiento de enrutamiento, solo con un límite mayor de workers. + - El autoescalado local de workers ahora es intencionalmente conservador y también reduce intensidad cuando la carga promedio del host ya es alta, de modo que múltiples ejecuciones concurrentes de Vitest hagan menos daño de forma predeterminada. + - La configuración base de Vitest marca los archivos de proyecto/configuración como `forceRerunTriggers` para que las reejecuciones en modo changed sigan siendo correctas cuando cambia el cableado de pruebas. - La configuración mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado en hosts compatibles; establece `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si quieres una ubicación de caché explícita para perfilado directo. - Nota sobre depuración de rendimiento: - - `pnpm test:perf:imports` habilita informes de duración de importación de Vitest más salida de desglose de importaciones. - - `pnpm test:perf:imports:changed` limita la misma vista de perfilado a los archivos modificados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado frente a la ruta nativa del proyecto raíz para ese diff confirmado e imprime tiempo total más RSS máximo de macOS. -- `pnpm test:perf:changed:bench -- --worktree` mide el árbol sucio actual enr utando la lista de archivos modificados a través de `scripts/test-projects.mjs` y la configuración raíz de Vitest. + - `pnpm test:perf:imports` habilita los informes de duración de importación de Vitest más la salida de desglose de importaciones. + - `pnpm test:perf:imports:changed` limita esa misma vista de perfilado a los archivos modificados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado con la ruta nativa del proyecto raíz para ese diff confirmado e imprime tiempo total más RSS máximo de macOS. +- `pnpm test:perf:changed:bench -- --worktree` evalúa el árbol de trabajo actual con cambios, enrutando la lista de archivos modificados a través de `scripts/test-projects.mjs` y la configuración raíz de Vitest. - `pnpm test:perf:profile:main` escribe un perfil de CPU del hilo principal para la sobrecarga de inicio y transformación de Vitest/Vite. - `pnpm test:perf:profile:runner` escribe perfiles de CPU+heap del ejecutor para la suite unitaria con el paralelismo de archivos deshabilitado. -### E2E (prueba rápida de Gateway) +### E2E (prueba de humo de Gateway) - Comando: `pnpm test:e2e` - Configuración: `vitest.e2e.config.ts` - Archivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Valores predeterminados de runtime: - - Usa Vitest `threads` con `isolate: false`, igual que el resto del repositorio. - - Usa workers adaptativos (CI: hasta 2, local: 1 por defecto). - - Se ejecuta en modo silencioso por defecto para reducir la sobrecarga de E/S de consola. -- Overrides útiles: + - Usa `threads` de Vitest con `isolate: false`, igual que el resto del repositorio. + - Usa workers adaptativos (CI: hasta 2, local: 1 de forma predeterminada). + - Se ejecuta en modo silencioso de forma predeterminada para reducir la sobrecarga de E/S de consola. +- Sobrescrituras útiles: - `OPENCLAW_E2E_WORKERS=` para forzar la cantidad de workers (máximo 16). - `OPENCLAW_E2E_VERBOSE=1` para volver a habilitar la salida detallada en consola. - Alcance: - Comportamiento end-to-end de Gateway con múltiples instancias - Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas - Expectativas: - - Se ejecuta en CI (cuando está habilitado en el pipeline) + - Se ejecuta en CI (cuando está habilitado en la canalización) - No requiere claves reales - - Tiene más piezas móviles que las pruebas unitarias (puede ser más lenta) + - Tiene más partes móviles que las pruebas unitarias (puede ser más lento) -### E2E: prueba rápida del backend OpenShell +### E2E: prueba de humo del backend OpenShell - Comando: `pnpm test:e2e:openshell` - Archivo: `test/openshell-sandbox.e2e.test.ts` - Alcance: - Inicia un Gateway OpenShell aislado en el host mediante Docker - - Crea un sandbox desde un Dockerfile local temporal - - Ejercita el backend OpenShell de OpenClaw sobre `sandbox ssh-config` + ejecución SSH reales - - Verifica el comportamiento canónico remoto del sistema de archivos mediante el puente fs del sandbox + - Crea un sandbox a partir de un Dockerfile local temporal + - Ejercita el backend OpenShell de OpenClaw mediante `sandbox ssh-config` + ejecución SSH reales + - Verifica el comportamiento canónico remoto del sistema de archivos a través del puente fs del sandbox - Expectativas: - - Solo opcional; no forma parte de la ejecución predeterminada de `pnpm test:e2e` - - Requiere un CLI `openshell` local más un daemon Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` aislados, luego destruye el Gateway de prueba y el sandbox -- Overrides útiles: + - Solo opt-in; no forma parte de la ejecución predeterminada de `pnpm test:e2e` + - Requiere un CLI local `openshell` y un daemon de Docker funcional + - Usa `HOME` / `XDG_CONFIG_HOME` aislados y luego destruye el Gateway y el sandbox de prueba +- Sobrescrituras útiles: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar la prueba al ejecutar manualmente la suite e2e más amplia - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apuntar a un binario CLI no predeterminado o a un script contenedor + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apuntar a un binario CLI no predeterminado o a un script envoltorio ### Live (proveedores reales + modelos reales) @@ -349,112 +346,112 @@ Piense en las suites como “realismo creciente” (y mayor inestabilidad/costo) - Predeterminado: **habilitado** por `pnpm test:live` (establece `OPENCLAW_LIVE_TEST=1`) - Alcance: - “¿Este proveedor/modelo realmente funciona _hoy_ con credenciales reales?” - - Detectar cambios de formato del proveedor, peculiaridades de llamadas a herramientas, problemas de autenticación y comportamiento de límites de tasa + - Detectar cambios de formato del proveedor, particularidades de llamadas a herramientas, problemas de autenticación y comportamiento de límites de tasa - Expectativas: - - No es estable en CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas) + - Por diseño no es estable en CI (redes reales, políticas reales de proveedores, cuotas, interrupciones) - Cuesta dinero / consume límites de tasa - - Conviene ejecutar subconjuntos acotados en lugar de “todo” -- Las ejecuciones live cargan `~/.profile` para recoger claves API faltantes. -- Por defecto, las ejecuciones live siguen aislando `HOME` y copian el material de configuración/autenticación a un home temporal de prueba para que los fixtures unitarios no puedan modificar tu `~/.openclaw` real. -- Establece `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando intencionalmente necesites que las pruebas live usen tu directorio home real. -- `pnpm test:live` ahora usa por defecto un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero suprime el aviso adicional de `~/.profile` y silencia los logs de arranque de Gateway/el ruido de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los logs completos de inicio. -- Rotación de claves API (específica por proveedor): establece `*_API_KEYS` con formato separado por comas/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o un override por live mediante `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas por límite de tasa. + - Se prefiere ejecutar subconjuntos acotados en lugar de “todo” +- Las ejecuciones live obtienen `~/.profile` para recoger claves de API faltantes. +- De forma predeterminada, las ejecuciones live siguen aislando `HOME` y copiando material de configuración/autenticación a un home temporal de prueba para que los fixtures unitarios no puedan mutar tu `~/.openclaw` real. +- Establece `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando necesites intencionalmente que las pruebas live usen tu directorio home real. +- `pnpm test:live` ahora usa de forma predeterminada un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero suprime el aviso adicional de `~/.profile` y silencia los logs de arranque de Gateway/el ruido de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres volver a ver los logs completos de inicio. +- Rotación de claves de API (específica por proveedor): establece `*_API_KEYS` con formato de comas/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o una sobrescritura por live mediante `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas de límite de tasa. - Salida de progreso/Heartbeat: - - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas a proveedores muestren actividad visible incluso cuando la captura de consola de Vitest está en modo silencioso. - - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso de proveedor/Gateway se transmitan inmediatamente durante las ejecuciones live. + - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas a proveedores sean visiblemente activas incluso cuando la captura de consola de Vitest está en modo silencioso. + - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso del proveedor/Gateway se transmitan de inmediato durante las ejecuciones live. - Ajusta los Heartbeat de modelo directo con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajusta los Heartbeat de Gateway/sondeo con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Ajusta los Heartbeat de Gateway/sonda con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## ¿Qué suite debo ejecutar? +## ¿Qué suite debería ejecutar? Usa esta tabla de decisión: -- Si editas lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste bastante) -- Si tocas redes de Gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` -- Si depuras “mi bot está caído” / fallos específicos del proveedor / llamadas a herramientas: ejecuta un `pnpm test:live` acotado +- Si editas lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste mucho) +- Si tocas redes de Gateway / protocolo WS / emparejamiento: añade `pnpm test:e2e` +- Si depuras “mi bot está caído” / fallos específicos de proveedor / llamadas a herramientas: ejecuta un `pnpm test:live` acotado ## Live: barrido de capacidades de Node Android - Prueba: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **cada comando anunciado actualmente** por un Node Android conectado y comprobar el comportamiento del contrato del comando. +- Objetivo: invocar **cada comando anunciado actualmente** por un Node Android conectado y verificar el comportamiento del contrato del comando. - Alcance: - Configuración previa/manual (la suite no instala/ejecuta/empareja la app). - Validación `node.invoke` de Gateway comando por comando para el Node Android seleccionado. - Configuración previa obligatoria: - - App Android ya conectada y emparejada con Gateway. - - La app debe mantenerse en primer plano. - - Permisos/consentimiento de captura otorgados para las capacidades que esperas que pasen. -- Overrides de objetivo opcionales: + - App Android ya conectada y emparejada con el Gateway. + - App mantenida en primer plano. + - Permisos/consentimiento de captura concedidos para las capacidades que esperas que pasen. +- Sobrescrituras opcionales del objetivo: - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Detalles completos de configuración de Android: [App Android](/es/platforms/android) -## Live: prueba rápida de modelos (claves de perfil) +## Live: prueba de humo de modelos (claves de perfil) Las pruebas live se dividen en dos capas para poder aislar fallos: -- “Modelo directo” nos dice si el proveedor/modelo puede responder con la clave dada. -- “Prueba rápida de Gateway” nos dice si la canalización completa de gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). +- “Modelo directo” nos dice si el proveedor/modelo puede responder en absoluto con la clave dada. +- “Prueba de humo de Gateway” nos dice si la canalización completa gateway+agent funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). -### Capa 1: finalización directa del modelo (sin Gateway) +### Capa 1: finalización directa del modelo (sin gateway) - Prueba: `src/agents/models.profiles.live.test.ts` - Objetivo: - Enumerar los modelos detectados - - Usar `getApiKeyForModel` para seleccionar modelos para los que tienes credenciales + - Usar `getApiKeyForModel` para seleccionar los modelos para los que tienes credenciales - Ejecutar una pequeña finalización por modelo (y regresiones específicas cuando sea necesario) - Cómo habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) -- Establece `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` centrado en la prueba rápida de Gateway +- Establece `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario, se omite para mantener `pnpm test:live` enfocado en la prueba de humo de Gateway - Cómo seleccionar modelos: - - `OPENCLAW_LIVE_MODELS=modern` para ejecutar la lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` es un alias de la lista permitida moderna - - o `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (lista permitida separada por comas) + - `OPENCLAW_LIVE_MODELS=modern` para ejecutar la allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` es un alias de la allowlist moderna + - o `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por comas) - Los barridos modern/all usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor. - Cómo seleccionar proveedores: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (lista permitida separada por comas) -- De dónde vienen las claves: - - Por defecto: almacén de perfiles y respaldos en env + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por comas) +- De dónde provienen las claves: + - De forma predeterminada: almacén de perfiles y alternativas de env - Establece `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **solo el almacén de perfiles** - Por qué existe esto: - - Separa “la API del proveedor está rota / la clave no es válida” de “la canalización del agente de Gateway está rota” - - Contiene regresiones pequeñas y aisladas (ejemplo: reproducción de razonamiento de OpenAI Responses/Codex Responses + flujos de llamada a herramientas) + - Separa “la API del proveedor está rota / la clave no es válida” de “la canalización del agent de gateway está rota” + - Contiene regresiones pequeñas y aisladas (ejemplo: flujos de repetición de razonamiento y llamadas a herramientas de OpenAI Responses/Codex Responses) -### Capa 2: prueba rápida de Gateway + agente de desarrollo (lo que realmente hace "@openclaw") +### Capa 2: prueba de humo de Gateway + agent dev (lo que realmente hace "@openclaw") - Prueba: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - Iniciar un Gateway en proceso - - Crear/parchear una sesión `agent:dev:*` (override de modelo por ejecución) - - Iterar sobre modelos con claves y comprobar: + - Crear/parchear una sesión `agent:dev:*` (sobrescritura de modelo por ejecución) + - Iterar sobre modelos con claves y verificar: - respuesta “significativa” (sin herramientas) - - que una invocación real de herramienta funcione (sondeo de lectura) - - sondeos opcionales adicionales de herramientas (sondeo exec+read) - - que las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) sigan funcionando -- Detalles de los sondeos (para que puedas explicar fallos rápidamente): - - sondeo `read`: la prueba escribe un archivo nonce en el espacio de trabajo y le pide al agente que lo `read` y devuelva el nonce. - - sondeo `exec+read`: la prueba le pide al agente que escriba mediante `exec` un nonce en un archivo temporal y luego lo lea de vuelta con `read`. - - sondeo de imagen: la prueba adjunta un PNG generado (gato + código aleatorio) y espera que el modelo devuelva `cat `. + - que una invocación real de herramienta funcione (sonda de lectura) + - sondas opcionales de herramientas adicionales (sonda exec+read) + - que sigan funcionando las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) +- Detalles de las sondas (para que puedas explicar fallos rápidamente): + - sonda `read`: la prueba escribe un archivo nonce en el workspace y le pide al agent que lo `read` y devuelva el nonce. + - sonda `exec+read`: la prueba le pide al agent que escriba mediante `exec` un nonce en un archivo temporal y luego lo lea de vuelta con `read`. + - sonda de imagen: la prueba adjunta un PNG generado (cat + código aleatorio) y espera que el modelo devuelva `cat `. - Referencia de implementación: `src/gateway/gateway-models.profiles.live.test.ts` y `src/gateway/live-image-probe.ts`. - Cómo habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) - Cómo seleccionar modelos: - - Predeterminado: lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` es un alias de la lista permitida moderna + - Predeterminado: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` es un alias de la allowlist moderna - O establece `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separada por comas) para acotar - - Los barridos de Gateway modern/all usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor. -- Cómo seleccionar proveedores (evitar “todo OpenRouter”): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (lista permitida separada por comas) -- Los sondeos de herramientas + imagen siempre están activados en esta prueba live: - - sondeo `read` + sondeo `exec+read` (estrés de herramientas) - - el sondeo de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen + - Los barridos modern/all de gateway usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor. +- Cómo seleccionar proveedores (evita “OpenRouter para todo”): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por comas) +- Las sondas de herramienta + imagen siempre están activadas en esta prueba live: + - sonda `read` + sonda `exec+read` (estrés de herramientas) + - la sonda de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen - Flujo (alto nivel): - - La prueba genera un pequeño PNG con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) + - La prueba genera un PNG pequeño con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) - Lo envía mediante `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway analiza los adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - El agente integrado reenvía un mensaje de usuario multimodal al modelo - - Comprobación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores) + - El agent integrado reenvía un mensaje de usuario multimodal al modelo + - Verificación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores) Consejo: para ver qué puedes probar en tu máquina (y los ids exactos `provider/model`), ejecuta: @@ -463,26 +460,26 @@ openclaw models list openclaw models list --json ``` -## Live: prueba rápida de backend CLI (Claude, Codex, Gemini u otros CLI locales) +## Live: prueba de humo del backend CLI (Claude, Codex, Gemini u otros CLIs locales) - Prueba: `src/gateway/gateway-cli-backend.live.test.ts` -- Objetivo: validar la canalización de Gateway + agente usando un backend CLI local, sin tocar tu configuración predeterminada. -- Los valores predeterminados de prueba rápida específicos del backend están en la definición `cli-backend.ts` de la extensión propietaria. +- Objetivo: validar la canalización de Gateway + agent usando un backend CLI local, sin tocar tu configuración predeterminada. +- Los valores predeterminados de prueba de humo específicos del backend se encuentran en la definición `cli-backend.ts` de la extensión propietaria. - Habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Predeterminados: +- Valores predeterminados: - Proveedor/modelo predeterminado: `claude-cli/claude-sonnet-4-6` - - El comportamiento de comando/args/imagen proviene de los metadatos del Plugin del backend CLI propietario. -- Overrides opcionales: + - El comportamiento de command/args/image proviene de los metadatos del Plugin propietario del backend CLI. +- Sobrescrituras (opcionales): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar un adjunto de imagen real (las rutas se inyectan en el prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivos de imagen como args de CLI en lugar de inyección en el prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los args de imagen cuando se establece `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivos de imagen como argumentos de CLI en lugar de inyección en el prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los argumentos de imagen cuando `IMAGE_ARG` está establecido. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar un segundo turno y validar el flujo de reanudación. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para deshabilitar el sondeo predeterminado de continuidad en la misma sesión de Claude Sonnet -> Opus (establece `1` para forzarlo cuando el modelo seleccionado admita un destino de cambio). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desactivar la sonda predeterminada de continuidad en la misma sesión de Claude Sonnet -> Opus (establece `1` para forzarla cuando el modelo seleccionado admita un destino de cambio). Ejemplo: @@ -509,38 +506,38 @@ pnpm test:docker:live-cli-backend:gemini Notas: -- El ejecutor de Docker está en `scripts/test-live-cli-backend-docker.sh`. -- Ejecuta la prueba rápida live del backend CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. -- Resuelve los metadatos de la prueba rápida CLI desde la extensión propietaria y luego instala el paquete CLI de Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo grabable en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portátil de suscripción de Claude Code mediante `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primero comprueba `claude -p` directamente en Docker y luego ejecuta dos turnos del backend CLI de Gateway sin conservar las variables de entorno de clave API de Anthropic. Este canal de suscripción deshabilita por defecto los sondeos de herramienta MCP e imagen de Claude porque Claude actualmente enruta el uso de aplicaciones de terceros mediante facturación por uso adicional en lugar de los límites normales del plan de suscripción. -- La prueba rápida live del backend CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen, luego llamada a herramienta MCP `cron` verificada mediante la CLI de Gateway. -- La prueba rápida predeterminada de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada aún recuerde una nota anterior. +- El ejecutor de Docker se encuentra en `scripts/test-live-cli-backend-docker.sh`. +- Ejecuta la prueba de humo live del backend CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. +- Resuelve los metadatos de prueba de humo del CLI desde la extensión propietaria y luego instala el paquete CLI de Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo escribible en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portátil de suscripción de Claude Code mediante `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primero demuestra `claude -p` directo en Docker y luego ejecuta dos turnos del backend CLI de Gateway sin preservar las variables de entorno de clave de API de Anthropic. Este carril de suscripción desactiva por defecto las sondas MCP/tool e imagen de Claude porque actualmente Claude enruta el uso de apps de terceros mediante facturación de uso adicional en lugar de los límites normales del plan de suscripción. +- La prueba de humo live del backend CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada a la herramienta MCP `cron` verificada a través del CLI de gateway. +- La prueba de humo predeterminada de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada siga recordando una nota anterior. -## Live: prueba rápida de enlace ACP (`/acp spawn ... --bind here`) +## Live: prueba de humo de enlace de ACP (`/acp spawn ... --bind here`) - Prueba: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar el flujo real de enlace de conversación de ACP con un agente ACP live: +- Objetivo: validar el flujo real de conversation-bind de ACP con un agent ACP live: - enviar `/acp spawn --bind here` - - enlazar en su lugar una conversación sintética de canal de mensajes + - enlazar in situ una conversación sintética de canal de mensajes - enviar un seguimiento normal en esa misma conversación - - verificar que el seguimiento llegue a la transcripción de la sesión ACP enlazada + - verificar que el seguimiento llegue en la transcripción de la sesión ACP enlazada - Habilitar: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Predeterminados: - - Agentes ACP en Docker: `claude,codex,gemini` - - Agente ACP para `pnpm test:live ...` directo: `claude` +- Valores predeterminados: + - Agents ACP en Docker: `claude,codex,gemini` + - Agent ACP para `pnpm test:live ...` directo: `claude` - Canal sintético: contexto de conversación estilo DM de Slack - Backend ACP: `acpx` -- Overrides: +- Sobrescrituras: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Notas: - - Este canal usa la superficie `chat.send` de Gateway con campos sintéticos de ruta de origen solo para administrador, para que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir entrega externa. - - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro integrado de agentes del Plugin `acpx` incluido para el agente de arnés ACP seleccionado. + - Este carril usa la superficie `chat.send` de gateway con campos sintéticos de ruta de origen solo para administradores para que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir entrega externa. + - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro integrado de agents del Plugin `acpx` para el agent de arnés ACP seleccionado. Ejemplo: @@ -556,7 +553,7 @@ Receta de Docker: pnpm test:docker:live-acp-bind ``` -Recetas de Docker para un solo agente: +Recetas de Docker para un solo agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -566,32 +563,32 @@ pnpm test:docker:live-acp-bind:gemini Notas de Docker: -- El ejecutor de Docker está en `scripts/test-live-acp-bind-docker.sh`. -- Por defecto, ejecuta la prueba rápida de enlace ACP contra todos los agentes CLI live compatibles en secuencia: `claude`, `codex` y luego `gemini`. +- El ejecutor de Docker se encuentra en `scripts/test-live-acp-bind-docker.sh`. +- De forma predeterminada, ejecuta la prueba de humo de enlace ACP contra todos los agents CLI live compatibles en secuencia: `claude`, `codex` y luego `gemini`. - Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para acotar la matriz. -- Carga `~/.profile`, prepara el material de autenticación CLI correspondiente dentro del contenedor, instala `acpx` en un prefijo npm grabable y luego instala la CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. -- Dentro de Docker, el ejecutor establece `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que acpx mantenga disponibles para la CLI hija del arnés las variables de entorno del proveedor procedentes del perfil cargado. +- Obtiene `~/.profile`, prepara el material de autenticación del CLI correspondiente dentro del contenedor, instala `acpx` en un prefijo npm escribible y luego instala el CLI live solicitado (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. +- Dentro de Docker, el ejecutor establece `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que acpx mantenga disponibles para el CLI hijo del arnés las variables de entorno del proveedor obtenidas del perfil. -## Live: prueba rápida del arnés app-server de Codex +## Live: prueba de humo del arnés app-server de Codex -- Objetivo: validar el arnés Codex propiedad del Plugin mediante el método - `agent` normal de Gateway: +- Objetivo: validar el arnés Codex propiedad del Plugin mediante el método normal + `agent` de gateway: - cargar el Plugin integrado `codex` - seleccionar `OPENCLAW_AGENT_RUNTIME=codex` - - enviar un primer turno del agente de Gateway a `codex/gpt-5.4` + - enviar un primer turno de gateway agent a `codex/gpt-5.4` - enviar un segundo turno a la misma sesión de OpenClaw y verificar que el hilo - del app-server pueda reanudarse - - ejecutar `/codex status` y `/codex models` mediante la misma ruta de comando - de Gateway + del app-server puede reanudarse + - ejecutar `/codex status` y `/codex models` mediante la misma ruta de + comandos de gateway - Prueba: `src/gateway/gateway-codex-harness.live.test.ts` - Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modelo predeterminado: `codex/gpt-5.4` -- Sondeo de imagen opcional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sondeo MCP/herramienta opcional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- La prueba rápida establece `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que un - arnés Codex roto no pueda pasar recurriendo silenciosamente a PI. -- Autenticación: `OPENAI_API_KEY` desde el shell/perfil, más copia opcional de - `~/.codex/auth.json` y `~/.codex/config.toml` +- Sonda de imagen opcional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Sonda opcional MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- La prueba de humo establece `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que un arnés Codex roto + no pueda pasar recurriendo silenciosamente a PI. +- Auth: `OPENAI_API_KEY` desde el shell/perfil, más opcionalmente + `~/.codex/auth.json` y `~/.codex/config.toml` copiados Receta local: @@ -613,28 +610,28 @@ pnpm test:docker:live-codex-harness Notas de Docker: -- El ejecutor de Docker está en `scripts/test-live-codex-harness-docker.sh`. -- Carga el `~/.profile` montado, pasa `OPENAI_API_KEY`, copia los archivos de - autenticación de CLI de Codex cuando están presentes, instala `@openai/codex` en un prefijo npm - montado y grabable, prepara el árbol fuente y luego ejecuta solo la prueba live del arnés Codex. -- Docker habilita por defecto los sondeos de imagen y MCP/herramientas. Establece +- El ejecutor de Docker se encuentra en `scripts/test-live-codex-harness-docker.sh`. +- Obtiene el `~/.profile` montado, pasa `OPENAI_API_KEY`, copia los archivos de autenticación + del CLI de Codex cuando están presentes, instala `@openai/codex` en un prefijo npm + montado y escribible, prepara el árbol de código fuente y luego ejecuta solo la prueba live del arnés de Codex. +- Docker habilita por defecto las sondas de imagen y MCP/tool. Establece `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` o `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` cuando necesites una ejecución de depuración más acotada. -- Docker también exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, igual que la configuración de la prueba - live, para que el respaldo a `openai-codex/*` o PI no pueda ocultar una regresión - del arnés Codex. +- Docker también exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, igual que la configuración + de la prueba live, para que el fallback a `openai-codex/*` o PI no pueda ocultar una regresión + del arnés de Codex. ### Recetas live recomendadas -Las listas permitidas acotadas y explícitas son las más rápidas y menos inestables: +Las allowlists acotadas y explícitas son las más rápidas y menos inestables: -- Modelo único, directo (sin Gateway): +- Un solo modelo, directo (sin gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modelo único, prueba rápida de Gateway: +- Un solo modelo, prueba de humo de gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Llamada a herramientas en varios proveedores: +- Llamadas a herramientas en varios proveedores: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Enfoque en Google (clave API de Gemini + Antigravity): @@ -644,32 +641,32 @@ Las listas permitidas acotadas y explícitas son las más rápidas y menos inest Notas: - `google/...` usa la API de Gemini (clave API). -- `google-antigravity/...` usa el puente OAuth de Antigravity (endpoint de agente estilo Cloud Code Assist). -- `google-gemini-cli/...` usa el CLI local de Gemini en tu máquina (autenticación independiente + peculiaridades de herramientas). -- API de Gemini vs CLI de Gemini: - - API: OpenClaw llama a la API alojada de Gemini de Google por HTTP (autenticación con clave API / perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”. - - CLI: OpenClaw ejecuta un binario `gemini` local; tiene su propia autenticación y puede comportarse de forma diferente (streaming/compatibilidad con herramientas/desfase de versión). +- `google-antigravity/...` usa el puente OAuth de Antigravity (endpoint de agent estilo Cloud Code Assist). +- `google-gemini-cli/...` usa el CLI local de Gemini en tu máquina (autenticación separada + particularidades de herramientas). +- API de Gemini frente a CLI de Gemini: + - API: OpenClaw llama por HTTP a la API alojada de Gemini de Google (autenticación por clave API / perfil); esto es lo que la mayoría de los usuarios entiende por “Gemini”. + - CLI: OpenClaw ejecuta un binario local `gemini`; tiene su propia autenticación y puede comportarse de forma diferente (streaming/compatibilidad de herramientas/desfase de versión). ## Live: matriz de modelos (qué cubrimos) -No hay una “lista fija de modelos de CI” (live es opcional), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves. +No hay una “lista fija de modelos de CI” (live es opt-in), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves. -### Conjunto moderno de prueba rápida (llamada a herramientas + imagen) +### Conjunto moderno de prueba de humo (llamadas a herramientas + imagen) Esta es la ejecución de “modelos comunes” que esperamos mantener funcional: - OpenAI (no-Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (o `anthropic/claude-sonnet-4-6`) -- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos antiguos de Gemini 2.x) +- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos Gemini 2.x más antiguos) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` y `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Ejecuta la prueba rápida de Gateway con herramientas + imagen: +Ejecutar prueba de humo de gateway con herramientas + imagen: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Línea base: llamada a herramientas (Read + Exec opcional) +### Línea base: llamadas a herramientas (Read + Exec opcional) Elige al menos uno por familia de proveedores: @@ -679,16 +676,16 @@ Elige al menos uno por familia de proveedores: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Cobertura adicional opcional (bueno tenerla): +Cobertura adicional opcional (deseable): - xAI: `xai/grok-4` (o la última disponible) -- Mistral: `mistral/`… (elige un modelo con capacidad de “tools” que tengas habilitado) +- Mistral: `mistral/`… (elige un modelo con capacidad de herramientas que tengas habilitado) - Cerebras: `cerebras/`… (si tienes acceso) -- LM Studio: `lmstudio/`… (local; la llamada a herramientas depende del modo API) +- LM Studio: `lmstudio/`… (local; las llamadas a herramientas dependen del modo de API) -### Visión: envío de imagen (adjunto → mensaje multimodal) +### Vision: envío de imagen (adjunto → mensaje multimodal) -Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes de OpenAI con visión, etc.) para ejercitar el sondeo de imagen. +Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes de OpenAI con capacidad de visión, etc.) para ejercitar la sonda de imagen. ### Agregadores / gateways alternativos @@ -700,36 +697,36 @@ Si tienes claves habilitadas, también admitimos pruebas mediante: Más proveedores que puedes incluir en la matriz live (si tienes credenciales/configuración): - Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Mediante `models.providers` (endpoints personalizados): `minimax` (nube/API), además de cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) +- Mediante `models.providers` (endpoints personalizados): `minimax` (cloud/API), además de cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) -Consejo: no intentes fijar “todos los modelos” en la documentación. La lista autoritativa es la que devuelva `discoverModels(...)` en tu máquina + las claves disponibles. +Consejo: no intentes codificar de forma rígida “todos los modelos” en la documentación. La lista autorizada es lo que devuelva `discoverModels(...)` en tu máquina + las claves que estén disponibles. -## Credenciales (nunca las confirmes) +## Credenciales (nunca las confirmes en el repositorio) -Las pruebas live descubren credenciales del mismo modo que la CLI. Implicaciones prácticas: +Las pruebas live detectan credenciales del mismo modo que el CLI. Implicaciones prácticas: -- Si la CLI funciona, las pruebas live deberían encontrar las mismas claves. -- Si una prueba live dice “no creds”, depura del mismo modo que depurarías `openclaw models list` / la selección de modelos. +- Si el CLI funciona, las pruebas live deberían encontrar las mismas claves. +- Si una prueba live dice “sin credenciales”, depúralo del mismo modo que depurarías `openclaw models list` / selección de modelo. -- Perfiles de autenticación por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significan las “profile keys” en las pruebas live) +- Perfiles de autenticación por agent: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significa “claves de perfil” en las pruebas live) - Configuración: `~/.openclaw/openclaw.json` (o `OPENCLAW_CONFIG_PATH`) - Directorio de estado heredado: `~/.openclaw/credentials/` (se copia al home live preparado cuando está presente, pero no es el almacén principal de claves de perfil) -- Las ejecuciones live locales copian por defecto la configuración activa, los archivos `auth-profiles.json` por agente, `credentials/` heredado y los directorios de autenticación de CLI externos compatibles a un home temporal de prueba; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan los overrides de ruta `agents.*.workspace` / `agentDir` para que los sondeos no toquen tu espacio de trabajo real del host. +- Las ejecuciones live locales copian por defecto la configuración activa, los archivos `auth-profiles.json` por agent, el directorio heredado `credentials/` y los directorios de autenticación CLI externos compatibles a un home temporal de prueba; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan las sobrescrituras de ruta `agents.*.workspace` / `agentDir` para que las sondas no toquen tu workspace real del host. -Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores de Docker de abajo (pueden montar `~/.profile` dentro del contenedor). +Si quieres depender de claves en env (por ejemplo exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores de Docker de abajo (pueden montar `~/.profile` dentro del contenedor). ## Live de Deepgram (transcripción de audio) - Prueba: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live de plan de codificación de BytePlus +## Live del plan de codificación de BytePlus - Prueba: `src/agents/byteplus.live.test.ts` - Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Override opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Sobrescritura opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live de medios de flujo de trabajo de ComfyUI +## Live de medios del flujo de trabajo de ComfyUI - Prueba: `extensions/comfy/comfy.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` @@ -744,10 +741,10 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Arnés: `pnpm test:live:media image` - Alcance: - - Enumera todos los plugins de proveedor de generación de imágenes registrados - - Carga las variables de entorno de proveedor faltantes desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizable + - Enumera cada Plugin de proveedor de generación de imágenes registrado + - Carga variables de entorno faltantes del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto claves API live/env antes que perfiles de autenticación almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable - Ejecuta las variantes estándar de generación de imágenes mediante la capacidad de runtime compartida: - `google:flash-generate` - `google:pro-generate` @@ -760,8 +757,8 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env +- Comportamiento opcional de autenticación: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar sobrescrituras solo de env ## Live de generación de música @@ -769,23 +766,23 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media music` - Alcance: - - Ejercita la ruta compartida integrada del proveedor de generación de música + - Ejercita la ruta compartida integrada de proveedor de generación de música - Actualmente cubre Google y MiniMax - - Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizable + - Carga variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto claves API live/env antes que perfiles de autenticación almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable - Ejecuta ambos modos de runtime declarados cuando están disponibles: - `generate` con entrada solo de prompt - `edit` cuando el proveedor declara `capabilities.edit.enabled` - - Cobertura actual del canal compartido: + - Cobertura actual del carril compartido: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: archivo live de Comfy separado, no este barrido compartido - Acotación opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env +- Comportamiento opcional de autenticación: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar sobrescrituras solo de env ## Live de generación de video @@ -793,172 +790,172 @@ Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media video` - Alcance: - - Ejercita la ruta compartida integrada del proveedor de generación de video - - Usa por defecto la ruta de prueba rápida segura para lanzamiento: proveedores que no son FAL, una solicitud de texto a video por proveedor, prompt lobster de un segundo y un límite de operación por proveedor desde `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por defecto) - - Omite FAL por defecto porque la latencia de cola del lado del proveedor puede dominar el tiempo de lanzamiento; pasa `--video-providers fal` o `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para ejecutarlo explícitamente + - Ejercita la ruta compartida integrada de proveedor de generación de video + - Usa por defecto la ruta de prueba de humo segura para versiones: proveedores que no son FAL, una solicitud de texto a video por proveedor, prompt lobster de un segundo y un límite de operación por proveedor tomado de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` de forma predeterminada) + - Omite FAL de forma predeterminada porque la latencia de cola del lado del proveedor puede dominar el tiempo de publicación; pasa `--video-providers fal` o `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para ejecutarlo explícitamente - Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizable - - Ejecuta solo `generate` por defecto + - Usa por defecto claves API live/env antes que perfiles de autenticación almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable + - Ejecuta solo `generate` de forma predeterminada - Establece `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para ejecutar también los modos de transformación declarados cuando estén disponibles: - `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por búfer en el barrido compartido - `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local respaldada por búfer en el barrido compartido - Proveedores `imageToVideo` actualmente declarados pero omitidos en el barrido compartido: - - `vydra` porque el `veo3` integrado es solo texto y el `kling` integrado requiere una URL de imagen remota - - Cobertura específica del proveedor Vydra: + - `vydra` porque el `veo3` integrado es solo de texto y el `kling` integrado requiere una URL remota de imagen + - Cobertura específica de proveedor para Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - ese archivo ejecuta `veo3` de texto a video más un canal `kling` que usa por defecto un fixture de URL de imagen remota + - ese archivo ejecuta `veo3` de texto a video más un carril `kling` que usa por defecto un fixture de URL remota de imagen - Cobertura live actual de `videoToVideo`: - solo `runway` cuando el modelo seleccionado es `runway/gen4_aleph` - Proveedores `videoToVideo` actualmente declarados pero omitidos en el barrido compartido: - `alibaba`, `qwen`, `xai` porque esas rutas actualmente requieren URLs de referencia remotas `http(s)` / MP4 - - `google` porque el canal compartido actual de Gemini/Veo usa entrada local respaldada por búfer y esa ruta no se acepta en el barrido compartido - - `openai` porque el canal compartido actual carece de garantías de acceso específicas de la organización para inpaint/remix de video + - `google` porque el carril compartido actual Gemini/Veo usa entrada local respaldada por búfer y esa ruta no se acepta en el barrido compartido + - `openai` porque el carril compartido actual carece de garantías de acceso específicas de la organización para video inpaint/remix - Acotación opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos los proveedores en el barrido predeterminado, incluido FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reducir el límite de operación de cada proveedor en una ejecución agresiva de prueba rápida -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reducir el límite de operación de cada proveedor en una ejecución agresiva de prueba de humo +- Comportamiento opcional de autenticación: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar sobrescrituras solo de env ## Arnés live de medios - Comando: `pnpm test:live:media` - Propósito: - - Ejecuta las suites live compartidas de imagen, música y video mediante un único entrypoint nativo del repositorio - - Carga automáticamente las variables de entorno de proveedor faltantes desde `~/.profile` - - Acota automáticamente cada suite a los proveedores que actualmente tienen autenticación utilizable por defecto - - Reutiliza `scripts/test-live.mjs`, para que el comportamiento de Heartbeat y de modo silencioso siga siendo consistente + - Ejecuta las suites live compartidas de imagen, música y video a través de un único punto de entrada nativo del repositorio + - Carga automáticamente variables de entorno faltantes del proveedor desde `~/.profile` + - Acota automáticamente cada suite a los proveedores que actualmente tienen auth utilizable de forma predeterminada + - Reutiliza `scripts/test-live.mjs`, para que el comportamiento de Heartbeat y modo silencioso siga siendo coherente - Ejemplos: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Ejecutores de Docker (comprobaciones opcionales de "funciona en Linux") +## Ejecutores de Docker (comprobaciones opcionales de “funciona en Linux”) Estos ejecutores de Docker se dividen en dos grupos: -- Ejecutores de modelos live: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio de configuración local y espacio de trabajo (y cargando `~/.profile` si está montado). Los entrypoints locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. -- Los ejecutores live de Docker usan por defecto un límite menor de prueba rápida para que un barrido completo en Docker siga siendo práctico: +- Ejecutores live de modelos: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio de configuración local y workspace (y obteniendo `~/.profile` si está montado). Los puntos de entrada locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. +- Los ejecutores live de Docker usan por defecto un límite de prueba de humo más pequeño para que un barrido completo en Docker siga siendo práctico: `test:docker:live-models` usa por defecto `OPENCLAW_LIVE_MAX_MODELS=12`, y `test:docker:live-gateway` usa por defecto `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` y - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sustituye esas variables de entorno cuando - explícitamente quieras el escaneo exhaustivo más grande. -- `test:docker:all` construye la imagen Docker live una vez mediante `test:docker:live-build`, luego la reutiliza para los dos canales Docker live. -- Los ejecutores de prueba rápida en contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` inician uno o más contenedores reales y verifican rutas de integración de más alto nivel. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sobrescribe esas variables de entorno cuando + quieras explícitamente el barrido exhaustivo más grande. +- `test:docker:all` compila la imagen Docker live una vez mediante `test:docker:live-build` y luego la reutiliza para los dos carriles live de Docker. +- Ejecutores de prueba de humo de contenedores: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` inician uno o más contenedores reales y verifican rutas de integración de nivel superior. -Los ejecutores Docker de modelos live también montan mediante bind solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), luego los copian al home del contenedor antes de la ejecución para que OAuth de CLI externa pueda refrescar tokens sin mutar el almacén de autenticación del host: +Los ejecutores live de modelos de Docker también montan por enlace solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), luego los copian al home del contenedor antes de la ejecución para que OAuth del CLI externo pueda renovar tokens sin mutar el almacén de autenticación del host: - Modelos directos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Prueba rápida de enlace ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) -- Prueba rápida de backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Prueba rápida del arnés app-server de Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + agente de desarrollo: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) -- Prueba rápida live de Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) -- Asistente de onboarding (TTY, andamiaje completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Redes de Gateway (dos contenedores, autenticación WS + estado de salud): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Puente de canal MCP (Gateway inicializado + puente stdio + prueba rápida de tramas de notificación sin procesar de Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (prueba rápida de instalación + alias `/plugin` + semántica de reinicio del paquete Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Prueba de humo de enlace ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Prueba de humo del backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) +- Prueba de humo del arnés app-server de Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + agent dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) +- Prueba de humo live de Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) +- Asistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) +- Redes de Gateway (dos contenedores, autenticación WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Puente de canal MCP (Gateway sembrado + puente stdio + prueba de humo de tramas de notificación Claude sin procesar): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (prueba de humo de instalación + alias `/plugin` + semántica de reinicio del paquete Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -Los ejecutores Docker de modelos live también montan mediante bind el checkout actual en modo de solo lectura y -lo preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la -imagen de runtime liviana y a la vez ejecuta Vitest contra tu código/configuración local exactos. -El paso de preparación omite grandes cachés solo locales y salidas de compilación de app como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios locales de `.build` de app o -salida de Gradle para que las ejecuciones live de Docker no pasen minutos copiando +Los ejecutores live de modelos de Docker también montan por enlace la checkout actual en modo solo lectura y +la preparan en un workdir temporal dentro del contenedor. Esto mantiene la +imagen de runtime ligera y aun así ejecuta Vitest contra tu código fuente/configuración locales exactos. +El paso de preparación omite cachés grandes solo locales y salidas de compilación de apps como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios de salida locales de app `.build` o +Gradle para que las ejecuciones live de Docker no pasen minutos copiando artefactos específicos de la máquina. -También establecen `OPENCLAW_SKIP_CHANNELS=1` para que los sondeos live de Gateway no inicien -workers reales de canales de Telegram/Discord/etc. dentro del contenedor. -`test:docker:live-models` sigue ejecutando `pnpm test:live`, así que transmite también -`OPENCLAW_LIVE_GATEWAY_*` cuando necesites acotar o excluir la cobertura live de Gateway -de ese canal Docker. -`test:docker:openwebui` es una prueba rápida de compatibilidad de nivel superior: inicia un -contenedor Gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, -inicia un contenedor fijado de Open WebUI contra ese Gateway, inicia sesión mediante +También establecen `OPENCLAW_SKIP_CHANNELS=1` para que las sondas live de gateway no inicien +workers reales de canales Telegram/Discord/etc. dentro del contenedor. +`test:docker:live-models` sigue ejecutando `pnpm test:live`, así que deja pasar +`OPENCLAW_LIVE_GATEWAY_*` también cuando necesites acotar o excluir la cobertura +live de gateway de ese carril de Docker. +`test:docker:openwebui` es una prueba de humo de compatibilidad de nivel superior: inicia un +contenedor de Gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, +inicia un contenedor fijado de Open WebUI contra ese gateway, inicia sesión mediante Open WebUI, verifica que `/api/models` exponga `openclaw/default` y luego envía una -solicitud real de chat mediante el proxy `/api/chat/completions` de Open WebUI. +solicitud de chat real a través del proxy `/api/chat/completions` de Open WebUI. La primera ejecución puede ser notablemente más lenta porque Docker puede necesitar descargar la -imagen de Open WebUI y Open WebUI puede necesitar terminar su propia configuración de arranque en frío. -Este canal espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` -(`~/.profile` por defecto) es la forma principal de proporcionarla en ejecuciones con Docker. -Las ejecuciones exitosas imprimen una pequeña carga útil JSON como `{ "ok": true, "model": +imagen de Open WebUI y Open WebUI puede necesitar completar su propia configuración de inicio en frío. +Este carril espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` +(`~/.profile` de forma predeterminada) es la forma principal de proporcionarla en ejecuciones Dockerizadas. +Las ejecuciones correctas imprimen una pequeña carga JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` es intencionalmente determinista y no necesita una -cuenta real de Telegram, Discord o iMessage. Inicia un contenedor Gateway -inicializado, arranca un segundo contenedor que ejecuta `openclaw mcp serve` y luego -verifica descubrimiento de conversaciones enrutadas, lecturas de transcripción, metadatos de adjuntos, -comportamiento de la cola de eventos live, enrutamiento de envío saliente y notificaciones -de canal + permisos estilo Claude sobre el puente MCP stdio real. La comprobación de notificaciones -inspecciona directamente las tramas MCP stdio sin procesar para que la prueba rápida valide lo que el -puente realmente emite, no solo lo que una SDK cliente específica casualmente expone. +cuenta real de Telegram, Discord o iMessage. Inicia un contenedor de Gateway +sembrado, inicia un segundo contenedor que lanza `openclaw mcp serve` y luego +verifica descubrimiento de conversaciones enrutadas, lecturas de transcripciones, metadatos de adjuntos, +comportamiento de cola de eventos live, enrutamiento de envíos salientes y notificaciones de estilo Claude de canal + +permisos a través del puente MCP stdio real. La comprobación de notificaciones +inspecciona directamente las tramas MCP stdio sin procesar, de modo que la prueba de humo valida lo que el +puente realmente emite, no solo lo que una SDK específica del cliente exponga. -Prueba manual ACP de hilo en lenguaje natural (no CI): +Prueba manual ACP de hilos en lenguaje natural (no CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantén este script para flujos de trabajo de regresión/depuración. Puede volver a ser necesario para la validación del enrutamiento de hilos ACP, así que no lo elimines. +- Conserva este script para flujos de trabajo de regresión/depuración. Puede volver a ser necesario para la validación de enrutamiento de hilos ACP, así que no lo elimines. Variables de entorno útiles: - `OPENCLAW_CONFIG_DIR=...` (predeterminado: `~/.openclaw`) montado en `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (predeterminado: `~/.openclaw/workspace`) montado en `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (predeterminado: `~/.profile`) montado en `/home/node/.profile` y cargado antes de ejecutar las pruebas -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar solo variables de entorno cargadas desde `OPENCLAW_PROFILE_FILE`, usando directorios temporales de configuración/espacio de trabajo y sin montajes externos de autenticación CLI +- `OPENCLAW_PROFILE_FILE=...` (predeterminado: `~/.profile`) montado en `/home/node/.profile` y obtenido antes de ejecutar las pruebas +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar solo variables de entorno obtenidas de `OPENCLAW_PROFILE_FILE`, usando directorios temporales de configuración/workspace y sin montajes externos de autenticación CLI - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predeterminado: `~/.cache/openclaw/docker-cli-tools`) montado en `/home/node/.npm-global` para instalaciones CLI en caché dentro de Docker -- Los directorios/archivos de autenticación de CLI externos bajo `$HOME` se montan en modo de solo lectura bajo `/host-auth...`, luego se copian a `/home/node/...` antes de iniciar las pruebas +- Directorios/archivos de autenticación CLI externos bajo `$HOME` se montan en modo solo lectura bajo `/host-auth...`, y luego se copian a `/home/node/...` antes de que comiencen las pruebas - Directorios predeterminados: `.minimax` - Archivos predeterminados: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Las ejecuciones acotadas por proveedor montan solo los directorios/archivos necesarios inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Sustituye manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o una lista separada por comas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Sobrescribe manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o una lista separada por comas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para acotar la ejecución - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar proveedores dentro del contenedor -- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar una imagen existente `openclaw:local-live` en reejecuciones que no necesitan recompilación +- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar una imagen existente `openclaw:local-live` en reejecuciones que no necesiten recompilar - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para asegurar que las credenciales provengan del almacén de perfiles (no de env) -- `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por Gateway para la prueba rápida de Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` para sustituir el prompt de verificación de nonce usado por la prueba rápida de Open WebUI -- `OPENWEBUI_IMAGE=...` para sustituir la etiqueta fijada de imagen de Open WebUI +- `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por el gateway para la prueba de humo de Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` para sobrescribir el prompt de verificación de nonce usado por la prueba de humo de Open WebUI +- `OPENWEBUI_IMAGE=...` para sobrescribir la etiqueta fijada de imagen de Open WebUI -## Verificación de documentación +## Verificación básica de documentación -Ejecuta las comprobaciones de documentación después de editar docs: `pnpm check:docs`. -Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobaciones de encabezados dentro de la página: `pnpm docs:check-links:anchors`. +Ejecuta las comprobaciones de documentación después de editar documentación: `pnpm check:docs`. +Ejecuta la validación completa de anchors de Mintlify cuando también necesites comprobaciones de encabezados en la página: `pnpm docs:check-links:anchors`. -## Regresión offline (segura para CI) +## Regresión sin conexión (segura para CI) Estas son regresiones de “canalización real” sin proveedores reales: -- Llamada a herramientas de Gateway (mock OpenAI, loop real de Gateway + agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Asistente de Gateway (WS `wizard.start`/`wizard.next`, escribe configuración + autenticación exigida): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Llamadas a herramientas de Gateway (OpenAI simulado, gateway real + bucle de agent): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Asistente de Gateway (WS `wizard.start`/`wizard.next`, escribe configuración + auth obligatoria): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evaluaciones de fiabilidad del agente (Skills) +## Evaluaciones de confiabilidad de agent (Skills) -Ya tenemos algunas pruebas seguras para CI que se comportan como “evaluaciones de fiabilidad del agente”: +Ya tenemos algunas pruebas seguras para CI que se comportan como “evaluaciones de confiabilidad de agent”: -- Llamada simulada a herramientas mediante el loop real de Gateway + agente (`src/gateway/gateway.test.ts`). -- Flujos end-to-end del asistente que validan el cableado de la sesión y los efectos de configuración (`src/gateway/gateway.test.ts`). +- Llamadas simuladas a herramientas a través del gateway real + bucle de agent (`src/gateway/gateway.test.ts`). +- Flujos end-to-end del asistente que validan el cableado de sesión y los efectos de configuración (`src/gateway/gateway.test.ts`). -Qué sigue faltando para Skills (ver [Skills](/es/tools/skills)): +Lo que aún falta para Skills (ver [Skills](/es/tools/skills)): -- **Toma de decisiones:** cuando Skills aparecen en el prompt, ¿el agente elige la Skill correcta (o evita las irrelevantes)? -- **Cumplimiento:** ¿el agente lee `SKILL.md` antes de usarla y sigue los pasos/args requeridos? -- **Contratos de flujo de trabajo:** escenarios de varios turnos que comprueban el orden de herramientas, el arrastre del historial de sesión y los límites del sandbox. +- **Decisión:** cuando se enumeran Skills en el prompt, ¿el agent elige la Skill correcta (o evita las irrelevantes)? +- **Cumplimiento:** ¿el agent lee `SKILL.md` antes de usarla y sigue los pasos/args requeridos? +- **Contratos de flujo de trabajo:** escenarios de varios turnos que verifican el orden de herramientas, la persistencia del historial de sesión y los límites del sandbox. -Las evaluaciones futuras deben seguir siendo deterministas primero: +Las futuras evaluaciones deben seguir siendo deterministas primero: -- Un ejecutor de escenarios que use proveedores simulados para comprobar llamadas a herramientas + orden, lecturas de archivos de Skill y cableado de sesión. -- Una pequeña suite de escenarios centrados en Skills (usar vs evitar, puertas, prompt injection). +- Un ejecutor de escenarios que use proveedores simulados para verificar llamadas a herramientas + orden, lecturas de archivos de Skills y cableado de sesión. +- Una pequeña suite de escenarios centrados en Skills (usar vs evitar, compuertas, prompt injection). - Evaluaciones live opcionales (opt-in, controladas por env) solo después de que la suite segura para CI esté implementada. ## Pruebas de contrato (forma de Plugin y canal) -Las pruebas de contrato verifican que cada Plugin y canal registrados cumplan con su -contrato de interfaz. Iteran sobre todos los plugins detectados y ejecutan una suite de -comprobaciones de forma y comportamiento. El canal unitario predeterminado `pnpm test` -omite intencionalmente estos archivos compartidos de interfaz y prueba rápida; ejecuta los comandos de contrato explícitamente -cuando toques superficies compartidas de canal o proveedor. +Las pruebas de contrato verifican que cada Plugin y canal registrado se ajuste a su +contrato de interfaz. Iteran sobre todos los Plugins detectados y ejecutan un conjunto de +verificaciones de forma y comportamiento. El carril unitario predeterminado de `pnpm test` +omite intencionalmente estos archivos compartidos de interfaz y prueba de humo; ejecuta los comandos +de contrato explícitamente cuando toques superficies compartidas de canal o proveedor. ### Comandos @@ -973,19 +970,19 @@ Ubicados en `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Forma básica del Plugin (id, nombre, capacidades) - **setup** - Contrato del asistente de configuración - **session-binding** - Comportamiento de vinculación de sesión -- **outbound-payload** - Estructura de la carga útil del mensaje +- **outbound-payload** - Estructura de la carga de mensaje - **inbound** - Manejo de mensajes entrantes -- **actions** - Manejadores de acciones del canal +- **actions** - Controladores de acciones del canal - **threading** - Manejo de id de hilo - **directory** - API de directorio/lista -- **group-policy** - Aplicación de la política de grupo +- **group-policy** - Aplicación de política de grupo ### Contratos de estado del proveedor Ubicados en `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondeos de estado del canal -- **registry** - Forma del registro de Plugin +- **status** - Sondas de estado del canal +- **registry** - Forma del registro de Plugins ### Contratos de proveedor @@ -994,8 +991,8 @@ Ubicados en `src/plugins/contracts/*.contract.test.ts`: - **auth** - Contrato de flujo de autenticación - **auth-choice** - Elección/selección de autenticación - **catalog** - API del catálogo de modelos -- **discovery** - Descubrimiento de Plugin -- **loader** - Carga de Plugin +- **discovery** - Descubrimiento de Plugins +- **loader** - Carga de Plugins - **runtime** - Runtime del proveedor - **shape** - Forma/interfaz del Plugin - **wizard** - Asistente de configuración @@ -1004,19 +1001,19 @@ Ubicados en `src/plugins/contracts/*.contract.test.ts`: - Después de cambiar exportaciones o subrutas de plugin-sdk - Después de agregar o modificar un Plugin de canal o proveedor -- Después de refactorizar el registro o descubrimiento de plugins +- Después de refactorizar el registro o descubrimiento de Plugins -Las pruebas de contrato se ejecutan en CI y no requieren claves API reales. +Las pruebas de contrato se ejecutan en CI y no requieren claves de API reales. ## Agregar regresiones (guía) Cuando corrijas un problema de proveedor/modelo detectado en live: - Agrega una regresión segura para CI si es posible (proveedor simulado/stub, o captura la transformación exacta de la forma de la solicitud) -- Si es inherentemente solo live (límites de tasa, políticas de autenticación), mantén la prueba live acotada y opt-in mediante variables de entorno +- Si es intrínsecamente solo live (límites de tasa, políticas de autenticación), mantén la prueba live acotada y opt-in mediante variables de entorno - Prefiere apuntar a la capa más pequeña que detecte el error: - - error de conversión/reproducción de solicitud del proveedor → prueba de modelos directos - - error en la canalización de sesión/historial/herramientas de Gateway → prueba rápida live de Gateway o prueba simulada segura para CI de Gateway -- Barandilla de recorrido de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo de muestra por clase de SecretRef a partir de los metadatos del registro (`listSecretTargetRegistryEntries()`), y luego comprueba que se rechacen los ids exec de segmento de recorrido. - - Si agregas una nueva familia de objetivos SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente en ids de objetivo no clasificados para que las clases nuevas no puedan omitirse en silencio. + - error de conversión/repetición de solicitudes del proveedor → prueba de modelos directos + - error en la canalización de sesión/historial/herramientas de gateway → prueba de humo live de gateway o prueba segura para CI con simulación de gateway +- Protección para el recorrido de SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo de muestra por clase de SecretRef a partir de metadatos del registro (`listSecretTargetRegistryEntries()`), y luego verifica que se rechacen ids exec de segmentos de recorrido. + - Si agregas una nueva familia de objetivos SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente con ids de objetivo sin clasificar para que las nuevas clases no puedan omitirse silenciosamente. diff --git a/docs/es/install/index.md b/docs/es/install/index.md index 747eee5c2..d890f5b80 100644 --- a/docs/es/install/index.md +++ b/docs/es/install/index.md @@ -1,24 +1,24 @@ --- read_when: - Necesitas un método de instalación distinto del inicio rápido de Primeros pasos - - Quieres desplegar en una plataforma en la nube + - Quieres implementar en una plataforma en la nube - Necesitas actualizar, migrar o desinstalar -summary: 'Instalar OpenClaw: script de instalación, npm/pnpm/bun, desde el código fuente, Docker y más' -title: Instalación +summary: Instalar OpenClaw — script de instalación, npm/pnpm/bun, desde el código fuente, Docker y más +title: Instalar x-i18n: - generated_at: "2026-04-05T12:45:45Z" + generated_at: "2026-04-20T05:21:26Z" model: gpt-5.4 provider: openai - source_hash: eca17c76a2a66166b3d8cda9dc3144ab920d30ad0ed2a220eb9389d7a383ba5d + source_hash: ad0a5fdbbf13dcaf2fed6840f35aa22b2e9e458509509f98303c8d87c2556a6f source_path: install/index.md workflow: 15 --- -# Instalación +# Instalar ## Recomendado: script de instalación -La forma más rápida de instalar. Detecta tu sistema operativo, instala Node si es necesario, instala OpenClaw e inicia el onboarding. +La forma más rápida de instalar. Detecta tu sistema operativo, instala Node si hace falta, instala OpenClaw e inicia la configuración guiada. @@ -33,7 +33,7 @@ La forma más rápida de instalar. Detecta tu sistema operativo, instala Node si -Para instalar sin ejecutar el onboarding: +Para instalar sin ejecutar la configuración guiada: @@ -48,31 +48,30 @@ Para instalar sin ejecutar el onboarding: -Para ver todos los flags y opciones de CI/automatización, consulta [Elementos internos del instalador](/install/installer). +Para ver todas las banderas y opciones de CI/automatización, consulta [Detalles internos del instalador](/es/install/installer). ## Requisitos del sistema - **Node 24** (recomendado) o Node 22.14+ — el script de instalación se encarga de esto automáticamente -- **macOS, Linux o Windows** — se admiten tanto Windows nativo como WSL2; WSL2 es más estable. Consulta [Windows](/platforms/windows). +- **macOS, Linux o Windows** — se admiten tanto Windows nativo como WSL2; WSL2 es más estable. Consulta [Windows](/es/platforms/windows). - `pnpm` solo es necesario si compilas desde el código fuente ## Métodos de instalación alternativos ### Instalador con prefijo local (`install-cli.sh`) -Úsalo cuando quieras mantener OpenClaw y Node bajo un prefijo local como +Úsalo cuando quieras que OpenClaw y Node se mantengan bajo un prefijo local como `~/.openclaw`, sin depender de una instalación de Node en todo el sistema: ```bash curl -fsSL https://openclaw.ai/install-cli.sh | bash ``` -Admite instalaciones npm de forma predeterminada, además de instalaciones desde checkout git dentro del mismo -flujo con prefijo. Referencia completa: [Elementos internos del instalador](/install/installer#install-clish). +Admite instalaciones con npm de forma predeterminada, además de instalaciones desde una copia de git dentro del mismo flujo de prefijo. Referencia completa: [Detalles internos del instalador](/es/install/installer#install-clish). ### npm, pnpm o bun -Si ya gestionas Node por tu cuenta: +Si ya administras Node por tu cuenta: @@ -117,17 +116,17 @@ SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest ### Desde el código fuente -Para colaboradores o cualquiera que quiera ejecutarlo desde un checkout local: +Para colaboradores o cualquier persona que quiera ejecutar desde una copia local del repositorio: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw -pnpm install && pnpm ui:build && pnpm build +pnpm install && pnpm build && pnpm ui:build pnpm link --global openclaw onboard --install-daemon ``` -O bien omite el enlace y usa `pnpm openclaw ...` desde dentro del repositorio. Consulta [Setup](/start/setup) para ver los flujos completos de desarrollo. +O bien, omite el enlace y usa `pnpm openclaw ...` desde dentro del repositorio. Consulta [Configuración](/es/start/setup) para ver los flujos de desarrollo completos. ### Instalar desde GitHub main @@ -138,64 +137,64 @@ npm install -g github:openclaw/openclaw#main ### Contenedores y gestores de paquetes - - Despliegues en contenedor o headless. + + Implementaciones en contenedores o sin interfaz. - - Alternativa en contenedor rootless a Docker. + + Alternativa de contenedores sin privilegios a Docker. - - Instalación declarativa mediante Nix flake. + + Instalación declarativa mediante flake de Nix. - + Aprovisionamiento automatizado de flotas. - - Uso solo de CLI mediante el runtime de Bun. + + Uso solo de la CLI mediante el runtime de Bun. ## Verificar la instalación ```bash -openclaw --version # confirmar que la CLI está disponible -openclaw doctor # comprobar si hay problemas de configuración -openclaw gateway status # verificar que la Gateway está en ejecución +openclaw --version # confirma que la CLI esté disponible +openclaw doctor # comprueba si hay problemas de configuración +openclaw gateway status # verifica que Gateway esté en ejecución ``` Si quieres inicio administrado después de la instalación: - macOS: LaunchAgent mediante `openclaw onboard --install-daemon` o `openclaw gateway install` - Linux/WSL2: servicio de usuario systemd mediante los mismos comandos -- Windows nativo: primero Scheduled Task, con fallback a un elemento de inicio de sesión por usuario en la carpeta Startup si se deniega la creación de la tarea +- Windows nativo: primero una tarea programada, con un elemento de inicio de sesión en la carpeta de Inicio por usuario como alternativa si se deniega la creación de la tarea -## Alojamiento y despliegue +## Hosting e implementación -Despliega OpenClaw en un servidor en la nube o VPS: +Implementa OpenClaw en un servidor en la nube o VPS: - Cualquier VPS Linux - Pasos compartidos de Docker - K8s - Fly.io - Hetzner - Google Cloud - Azure - Railway - Render - Northflank + Cualquier VPS de Linux + Pasos compartidos de Docker + K8s + Fly.io + Hetzner + Google Cloud + Azure + Railway + Render + Northflank ## Actualizar, migrar o desinstalar - + Mantén OpenClaw actualizado. - - Muévete a una máquina nueva. + + Muévete a una nueva máquina. - + Elimina OpenClaw por completo. @@ -207,13 +206,13 @@ Si la instalación se completó correctamente pero `openclaw` no se encuentra en ```bash node -v # ¿Node está instalado? npm prefix -g # ¿Dónde están los paquetes globales? -echo "$PATH" # ¿Está el directorio global bin en PATH? +echo "$PATH" # ¿El directorio global de binarios está en PATH? ``` -Si `$(npm prefix -g)/bin` no está en tu `$PATH`, añádelo al archivo de inicio de tu shell (`~/.zshrc` o `~/.bashrc`): +Si `$(npm prefix -g)/bin` no está en tu `$PATH`, añádelo a tu archivo de inicio del shell (`~/.zshrc` o `~/.bashrc`): ```bash export PATH="$(npm prefix -g)/bin:$PATH" ``` -Luego abre un terminal nuevo. Consulta [Node setup](/install/node) para más detalles. +Luego abre una terminal nueva. Consulta [Configuración de Node](/es/install/node) para más detalles. diff --git a/docs/es/platforms/windows.md b/docs/es/platforms/windows.md index e27f879b9..b5bb20e18 100644 --- a/docs/es/platforms/windows.md +++ b/docs/es/platforms/windows.md @@ -2,14 +2,14 @@ read_when: - Instalar OpenClaw en Windows - Elegir entre Windows nativo y WSL2 - - Buscar el estado de la app complementaria de Windows -summary: 'Compatibilidad con Windows: rutas de instalación nativa y WSL2, daemon y advertencias actuales' + - Consultar el estado de la aplicación complementaria de Windows +summary: 'Compatibilidad con Windows: rutas de instalación nativas y con WSL2, daemon y limitaciones actuales' title: Windows x-i18n: - generated_at: "2026-04-05T12:49:00Z" + generated_at: "2026-04-20T05:21:27Z" model: gpt-5.4 provider: openai - source_hash: 7d9819206bdd65cf03519c1bc73ed0c7889b0ab842215ea94343262300adfd14 + source_hash: 1e7451c785a1d75c809522ad93e2c44a00b211f77f14c5c489fd0b01840d3fe2 source_path: platforms/windows.md workflow: 15 --- @@ -17,62 +17,62 @@ x-i18n: # Windows OpenClaw es compatible tanto con **Windows nativo** como con **WSL2**. WSL2 es la -ruta más estable y la recomendada para la experiencia completa: la CLI, el Gateway y las -herramientas se ejecutan dentro de Linux con compatibilidad total. Windows nativo funciona para -el uso principal de CLI y Gateway, con algunas advertencias indicadas más abajo. +ruta más estable y la recomendada para la experiencia completa: la CLI, Gateway y +las herramientas se ejecutan dentro de Linux con compatibilidad total. Windows nativo funciona para +el uso básico de la CLI y de Gateway, con algunas limitaciones indicadas más abajo. -Están previstas apps complementarias nativas para Windows. +Las aplicaciones complementarias nativas para Windows están previstas. ## WSL2 (recomendado) - [Primeros pasos](/es/start/getting-started) (úsalo dentro de WSL) -- [Instalación y actualizaciones](/install/updating) +- [Instalación y actualizaciones](/es/install/updating) - Guía oficial de WSL2 (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install) ## Estado de Windows nativo -Los flujos de CLI nativos de Windows están mejorando, pero WSL2 sigue siendo la ruta recomendada. +Los flujos de la CLI nativa en Windows están mejorando, pero WSL2 sigue siendo la ruta recomendada. -Qué funciona bien hoy en Windows nativo: +Lo que funciona bien hoy en Windows nativo: - instalador del sitio web mediante `install.ps1` -- uso local de CLI como `openclaw --version`, `openclaw doctor` y `openclaw plugins list --json` -- prueba smoke integrada de agente/proveedor local como: +- uso local de la CLI como `openclaw --version`, `openclaw doctor` y `openclaw plugins list --json` +- pruebas básicas integradas de agente/proveedor local como: ```powershell openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK." ``` -Advertencias actuales: +Limitaciones actuales: -- `openclaw onboard --non-interactive` todavía espera un gateway local accesible a menos que pases `--skip-health` -- `openclaw onboard --non-interactive --install-daemon` y `openclaw gateway install` intentan primero usar Tareas programadas de Windows -- si se deniega la creación de la tarea programada, OpenClaw recurre a un elemento de inicio de sesión por usuario en la carpeta Startup y arranca el gateway inmediatamente -- si `schtasks` se cuelga o deja de responder, OpenClaw ahora aborta rápidamente esa ruta y recurre al respaldo en lugar de quedarse bloqueado para siempre -- las Tareas programadas siguen siendo la opción preferida cuando están disponibles porque proporcionan mejor estado del supervisor +- `openclaw onboard --non-interactive` sigue esperando un gateway local accesible a menos que pases `--skip-health` +- `openclaw onboard --non-interactive --install-daemon` y `openclaw gateway install` intentan primero usar Windows Scheduled Tasks +- si se deniega la creación de Scheduled Task, OpenClaw recurre a un elemento de inicio de sesión por usuario en la carpeta Startup del usuario y arranca el gateway inmediatamente +- si `schtasks` se bloquea o deja de responder, OpenClaw ahora abandona esa ruta rápidamente y recurre a la alternativa en lugar de quedarse colgado indefinidamente +- Scheduled Tasks siguen siendo la opción preferida cuando están disponibles porque proporcionan un mejor estado del supervisor -Si solo quieres la CLI nativa, sin instalación del servicio gateway, usa una de estas opciones: +Si quieres solo la CLI nativa, sin instalar el servicio de gateway, usa una de estas opciones: ```powershell openclaw onboard --non-interactive --skip-health openclaw gateway run ``` -Si sí quieres un inicio gestionado en Windows nativo: +Si sí quieres inicio administrado en Windows nativo: ```powershell openclaw gateway install openclaw gateway status --json ``` -Si la creación de la tarea programada está bloqueada, el modo de servicio de respaldo seguirá iniciándose automáticamente después del inicio de sesión mediante la carpeta Startup del usuario actual. +Si la creación de Scheduled Task está bloqueada, el modo de servicio alternativo seguirá iniciándose automáticamente después del inicio de sesión mediante la carpeta Startup del usuario actual. ## Gateway -- [Runbook del Gateway](/gateway) -- [Configuración](/gateway/configuration) +- [Guía operativa de Gateway](/es/gateway) +- [Configuración](/es/gateway/configuration) -## Instalación del servicio Gateway (CLI) +## Instalación del servicio de Gateway (CLI) Dentro de WSL2: @@ -92,7 +92,7 @@ O bien: openclaw configure ``` -Selecciona **Gateway service** cuando se te pida. +Selecciona **Servicio de Gateway** cuando se te solicite. Reparar/migrar: @@ -100,12 +100,12 @@ Reparar/migrar: openclaw doctor ``` -## Inicio automático del Gateway antes del inicio de sesión en Windows +## Inicio automático de Gateway antes del inicio de sesión en Windows -Para configuraciones sin interfaz, asegúrate de que toda la cadena de arranque funcione incluso cuando nadie haya iniciado sesión en +Para configuraciones sin interfaz, asegúrate de que toda la cadena de arranque se ejecute incluso cuando nadie inicie sesión en Windows. -### 1) Mantener los servicios de usuario activos sin iniciar sesión +### 1) Mantener los servicios de usuario en ejecución sin iniciar sesión Dentro de WSL: @@ -113,7 +113,7 @@ Dentro de WSL: sudo loginctl enable-linger "$(whoami)" ``` -### 2) Instalar el servicio de usuario del gateway de OpenClaw +### 2) Instalar el servicio de usuario de Gateway de OpenClaw Dentro de WSL: @@ -129,7 +129,7 @@ En PowerShell como administrador: schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM ``` -Sustituye `Ubuntu` por el nombre de tu distribución obtenido con: +Reemplaza `Ubuntu` por el nombre de tu distribución obtenido con: ```powershell wsl --list --verbose @@ -137,19 +137,19 @@ wsl --list --verbose ### Verificar la cadena de inicio -Después de un reinicio (antes de iniciar sesión en Windows), comprueba desde WSL: +Después de reiniciar (antes de iniciar sesión en Windows), comprueba desde WSL: ```bash systemctl --user is-enabled openclaw-gateway.service systemctl --user status openclaw-gateway.service --no-pager ``` -## Avanzado: exponer servicios WSL por LAN (portproxy) +## Avanzado: exponer servicios de WSL por la LAN (portproxy) -WSL tiene su propia red virtual. Si otra máquina necesita llegar a un servicio -que se ejecuta **dentro de WSL** (SSH, un servidor local de TTS o el Gateway), debes -reenviar un puerto de Windows a la IP actual de WSL. La IP de WSL cambia después de reinicios, -por lo que puede que necesites actualizar la regla de reenvío. +WSL tiene su propia red virtual. Si otra máquina necesita acceder a un servicio +que se ejecuta **dentro de WSL** (SSH, un servidor TTS local o Gateway), debes +redirigir un puerto de Windows a la IP actual de WSL. La IP de WSL cambia después de reinicios, +así que es posible que tengas que actualizar la regla de reenvío. Ejemplo (PowerShell **como administrador**): @@ -165,7 +165,7 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor connectaddress=$WslIp connectport=$TargetPort ``` -Permite el puerto en el Firewall de Windows (una sola vez): +Permite el puerto en Windows Firewall (una sola vez): ```powershell New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound ` @@ -182,31 +182,31 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0. Notas: -- El SSH desde otra máquina apunta a la **IP del host de Windows** (ejemplo: `ssh user@windows-host -p 2222`). -- Los nodos remotos deben apuntar a una URL de Gateway **alcanzable** (no `127.0.0.1`); usa +- El acceso SSH desde otra máquina apunta a la **IP del host Windows** (ejemplo: `ssh user@windows-host -p 2222`). +- Los nodos remotos deben apuntar a una URL de Gateway **accesible** (no `127.0.0.1`); usa `openclaw status --all` para confirmarlo. - Usa `listenaddress=0.0.0.0` para acceso por LAN; `127.0.0.1` lo mantiene solo local. -- Si quieres esto automático, registra una Tarea programada para ejecutar el paso de +- Si quieres automatizar esto, registra una Scheduled Task para ejecutar el paso de actualización al iniciar sesión. ## Instalación paso a paso de WSL2 ### 1) Instalar WSL2 + Ubuntu -Abre PowerShell (administrador): +Abre PowerShell (Admin): ```powershell wsl --install -# Or pick a distro explicitly: +# O elige una distribución explícitamente: wsl --list --online wsl --install -d Ubuntu-24.04 ``` Reinicia si Windows lo solicita. -### 2) Habilitar systemd (obligatorio para instalar el gateway) +### 2) Habilitar systemd (obligatorio para instalar Gateway) -En tu terminal WSL: +En tu terminal de WSL: ```bash sudo tee /etc/wsl.conf >/dev/null <<'EOF' @@ -229,20 +229,30 @@ systemctl --user status ### 3) Instalar OpenClaw (dentro de WSL) -Sigue el flujo de Linux de Primeros pasos dentro de WSL: +Para una configuración inicial normal dentro de WSL, sigue el flujo de primeros pasos de Linux: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install -pnpm ui:build # auto-installs UI deps on first run pnpm build -openclaw onboard +pnpm ui:build +pnpm openclaw onboard --install-daemon +``` + +Si estás desarrollando desde el código fuente en lugar de realizar la configuración inicial, usa el +bucle de desarrollo desde [Configuración](/es/start/setup): + +```bash +pnpm install +# Solo la primera ejecución (o después de restablecer la configuración/espacio de trabajo local de OpenClaw) +pnpm openclaw setup +pnpm gateway:watch ``` Guía completa: [Primeros pasos](/es/start/getting-started) -## App complementaria de Windows +## Aplicación complementaria de Windows -Todavía no tenemos una app complementaria para Windows. Las contribuciones son bienvenidas si quieres -hacerla realidad. +Todavía no tenemos una aplicación complementaria para Windows. Las contribuciones son bienvenidas si quieres +contribuir a que esto suceda. diff --git a/docs/es/start/setup.md b/docs/es/start/setup.md index 567bea240..a557079cd 100644 --- a/docs/es/start/setup.md +++ b/docs/es/start/setup.md @@ -1,14 +1,14 @@ --- read_when: - Configurar una máquina nueva - - Quieres “lo último y lo mejor” sin romper tu configuración personal + - Quieres lo último y lo mejor sin romper tu configuración personal summary: Configuración avanzada y flujos de trabajo de desarrollo para OpenClaw title: Configuración x-i18n: - generated_at: "2026-04-05T12:54:29Z" + generated_at: "2026-04-20T05:21:26Z" model: gpt-5.4 provider: openai - source_hash: be4e280dde7f3a224345ca557ef2fb35a9c9db8520454ff63794ac6f8d4e71e7 + source_hash: 773cdbef5f38b069303b5e13fca5fcdc28f082746869f17b8b92aab1610b95a8 source_path: start/setup.md workflow: 15 --- @@ -16,42 +16,42 @@ x-i18n: # Configuración -Si vas a configurarlo por primera vez, empieza con [Primeros pasos](/es/start/getting-started). -Para detalles de onboarding, consulta [Onboarding (CLI)](/es/start/wizard). +Si vas a configurar por primera vez, empieza con [Primeros pasos](/es/start/getting-started). +Para obtener detalles sobre la incorporación, consulta [Incorporación (CLI)](/es/start/wizard). -## En resumen +## Resumen rápido -- **La personalización vive fuera del repositorio:** `~/.openclaw/workspace` (espacio de trabajo) + `~/.openclaw/openclaw.json` (configuración). +- **La personalización vive fuera del repositorio:** `~/.openclaw/workspace` (workspace) + `~/.openclaw/openclaw.json` (configuración). - **Flujo de trabajo estable:** instala la app de macOS; deja que ejecute el Gateway incluido. - **Flujo de trabajo de vanguardia:** ejecuta el Gateway tú mismo mediante `pnpm gateway:watch`, y luego deja que la app de macOS se conecte en modo Local. ## Requisitos previos (desde el código fuente) - Se recomienda Node 24 (Node 22 LTS, actualmente `22.14+`, sigue siendo compatible) -- Se prefiere `pnpm` (o Bun si usas intencionalmente el [flujo de trabajo con Bun](/es/install/bun)) +- Se prefiere `pnpm` (o Bun si usas intencionalmente el [flujo de trabajo de Bun](/es/install/bun)) - Docker (opcional; solo para configuración en contenedores/e2e — consulta [Docker](/es/install/docker)) ## Estrategia de personalización (para que las actualizaciones no perjudiquen) -Si quieres que esté “100 % adaptado a mí” _y_ tener actualizaciones fáciles, mantén tu personalización en: +Si quieres algo “100 % adaptado a mí” _y_ actualizaciones sencillas, mantén tu personalización en: -- **Configuración:** `~/.openclaw/openclaw.json` (similar a JSON/JSON5) -- **Espacio de trabajo:** `~/.openclaw/workspace` (Skills, prompts, memorias; conviértelo en un repositorio git privado) +- **Configuración:** `~/.openclaw/openclaw.json` (tipo JSON/JSON5) +- **Workspace:** `~/.openclaw/workspace` (Skills, prompts, memorias; conviértelo en un repositorio git privado) -Inicialízalo una vez: +Inicializa una vez: ```bash openclaw setup ``` -Desde dentro de este repositorio, usa la entrada local de la CLI: +Desde dentro de este repositorio, usa la entrada de CLI local: ```bash openclaw setup ``` -Si todavía no tienes una instalación global, ejecútalo mediante `pnpm openclaw setup` (o `bun run openclaw setup` si estás usando el flujo de trabajo con Bun). +Si aún no tienes una instalación global, ejecútalo con `pnpm openclaw setup` (o `bun run openclaw setup` si estás usando el flujo de trabajo de Bun). ## Ejecutar el Gateway desde este repositorio @@ -64,116 +64,118 @@ node openclaw.mjs gateway --port 18789 --verbose ## Flujo de trabajo estable (primero la app de macOS) 1. Instala e inicia **OpenClaw.app** (barra de menús). -2. Completa la lista de comprobación de onboarding/permisos (solicitudes TCC). +2. Completa la lista de comprobación de incorporación/permisos (avisos de TCC). 3. Asegúrate de que Gateway esté en **Local** y en ejecución (la app lo gestiona). -4. Vincula superficies (ejemplo: WhatsApp): +4. Vincula las superficies (ejemplo: WhatsApp): ```bash openclaw channels login ``` -5. Verificación rápida: +5. Comprobación rápida: ```bash openclaw health ``` -Si el onboarding no está disponible en tu compilación: +Si la incorporación no está disponible en tu compilación: -- Ejecuta `openclaw setup`, luego `openclaw channels login`, y después inicia el Gateway manualmente (`openclaw gateway`). +- Ejecuta `openclaw setup`, luego `openclaw channels login` y después inicia el Gateway manualmente (`openclaw gateway`). ## Flujo de trabajo de vanguardia (Gateway en una terminal) -Objetivo: trabajar en el Gateway de TypeScript, obtener recarga en caliente y mantener conectada la UI de la app de macOS. +Objetivo: trabajar en el Gateway de TypeScript, obtener recarga en caliente y mantener conectada la interfaz de la app de macOS. -### 0) (Opcional) Ejecutar también la app de macOS desde el código fuente +### 0) (Opcional) Ejecuta también la app de macOS desde el código fuente -Si también quieres que la app de macOS esté en la versión de vanguardia: +Si también quieres la app de macOS en la versión más reciente: ```bash ./scripts/restart-mac.sh ``` -### 1) Iniciar el Gateway de desarrollo +### 1) Inicia el Gateway de desarrollo ```bash pnpm install +# Solo en la primera ejecución (o después de restablecer la configuración/workspace local de OpenClaw) +pnpm openclaw setup pnpm gateway:watch ``` -`gateway:watch` ejecuta el gateway en modo watch y se recarga ante cambios relevantes en el código fuente, -la configuración y los metadatos de plugins incluidos. +`gateway:watch` ejecuta el gateway en modo observación y recarga con cambios relevantes en el código fuente, la configuración y los metadatos de plugins incluidos. +`pnpm openclaw setup` es el paso único de inicialización de la configuración/workspace local para un checkout nuevo. +`pnpm gateway:watch` no recompila `dist/control-ui`, así que vuelve a ejecutar `pnpm ui:build` después de cambios en `ui/` o usa `pnpm ui:dev` mientras desarrollas la Control UI. -Si usas intencionalmente el flujo de trabajo con Bun, los comandos equivalentes son: +Si estás usando intencionalmente el flujo de trabajo de Bun, los comandos equivalentes son: ```bash bun install +# Solo en la primera ejecución (o después de restablecer la configuración/workspace local de OpenClaw) +bun run openclaw setup bun run gateway:watch ``` -### 2) Apuntar la app de macOS a tu Gateway en ejecución +### 2) Apunta la app de macOS a tu Gateway en ejecución En **OpenClaw.app**: - Modo de conexión: **Local** La app se conectará al gateway en ejecución en el puerto configurado. -### 3) Verificar +### 3) Verifica -- El estado del Gateway en la app debería mostrar **“Using existing gateway …”** +- El estado de Gateway en la app debería mostrar **“Using existing gateway …”** - O mediante la CLI: ```bash openclaw health ``` -### Problemas habituales +### Errores comunes -- **Puerto incorrecto:** Gateway WS usa de forma predeterminada `ws://127.0.0.1:18789`; mantén la app y la CLI en el mismo puerto. +- **Puerto incorrecto:** el WS de Gateway usa por defecto `ws://127.0.0.1:18789`; mantén la app y la CLI en el mismo puerto. - **Dónde vive el estado:** - - Estado de canal/proveedor: `~/.openclaw/credentials/` - - Perfiles de autenticación del modelo: `~/.openclaw/agents//agent/auth-profiles.json` + - Estado de canales/proveedores: `~/.openclaw/credentials/` + - Perfiles de autenticación de modelos: `~/.openclaw/agents//agent/auth-profiles.json` - Sesiones: `~/.openclaw/agents//sessions/` - Registros: `/tmp/openclaw/` ## Mapa de almacenamiento de credenciales -Usa esto al depurar autenticación o decidir qué respaldar: +Úsalo al depurar autenticación o decidir qué respaldar: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Token del bot de Telegram**: config/env o `channels.telegram.tokenFile` (solo archivo normal; se rechazan enlaces simbólicos) -- **Token del bot de Discord**: config/env o SecretRef (proveedores env/file/exec) +- **Token de bot de Telegram**: config/env o `channels.telegram.tokenFile` (solo archivo normal; se rechazan los enlaces simbólicos) +- **Token de bot de Discord**: config/env o SecretRef (proveedores env/file/exec) - **Tokens de Slack**: config/env (`channels.slack.*`) - **Listas de permitidos de emparejamiento**: - `~/.openclaw/credentials/-allowFrom.json` (cuenta predeterminada) - `~/.openclaw/credentials/--allowFrom.json` (cuentas no predeterminadas) -- **Perfiles de autenticación del modelo**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Carga útil opcional de secrets respaldados por archivo**: `~/.openclaw/secrets.json` +- **Perfiles de autenticación de modelos**: `~/.openclaw/agents//agent/auth-profiles.json` +- **Carga útil de secretos respaldados por archivo (opcional)**: `~/.openclaw/secrets.json` - **Importación heredada de OAuth**: `~/.openclaw/credentials/oauth.json` Más detalles: [Seguridad](/es/gateway/security#credential-storage-map). ## Actualización (sin destrozar tu configuración) - Mantén `~/.openclaw/workspace` y `~/.openclaw/` como “tus cosas”; no pongas prompts/configuración personales en el repositorio `openclaw`. -- Para actualizar el código fuente: `git pull` + el paso de instalación de tu gestor de paquetes elegido (`pnpm install` de forma predeterminada; `bun install` para el flujo de trabajo con Bun) + sigue usando el comando `gateway:watch` correspondiente. +- Para actualizar el código fuente: `git pull` + el paso de instalación del gestor de paquetes que elijas (`pnpm install` de forma predeterminada; `bun install` para el flujo de trabajo de Bun) + sigue usando el comando `gateway:watch` correspondiente. ## Linux (servicio de usuario systemd) -Las instalaciones de Linux usan un servicio de usuario de systemd. De forma predeterminada, systemd detiene los -servicios de usuario al cerrar sesión o en inactividad, lo que mata el Gateway. Onboarding intenta habilitar -lingering por ti (puede pedir sudo). Si sigue desactivado, ejecuta: +Las instalaciones de Linux usan un servicio de **usuario** de systemd. De forma predeterminada, systemd detiene los servicios de usuario al cerrar sesión o por inactividad, lo que mata el Gateway. La incorporación intenta habilitar el modo persistente por ti (puede pedir sudo). Si sigue desactivado, ejecuta: ```bash sudo loginctl enable-linger $USER ``` -Para servidores siempre activos o multiusuario, considera un servicio de **sistema** en lugar de un -servicio de usuario (no requiere lingering). Consulta [Manual operativo del Gateway](/es/gateway) para ver las notas sobre systemd. +Para servidores siempre activos o multiusuario, considera un servicio de **sistema** en lugar de un servicio de usuario (no hace falta habilitar persistencia). Consulta el [manual operativo de Gateway](/es/gateway) para ver las notas sobre systemd. ## Documentación relacionada -- [Manual operativo del Gateway](/es/gateway) (flags, supervisión, puertos) -- [Configuración del Gateway](/es/gateway/configuration) (esquema de configuración + ejemplos) +- [Manual operativo de Gateway](/es/gateway) (flags, supervisión, puertos) +- [Configuración de Gateway](/es/gateway/configuration) (esquema de configuración + ejemplos) - [Discord](/es/channels/discord) y [Telegram](/es/channels/telegram) (etiquetas de respuesta + ajustes de replyToMode) -- [Configuración del asistente OpenClaw](/start/openclaw) +- [Configuración del asistente OpenClaw](/es/start/openclaw) - [app de macOS](/es/platforms/macos) (ciclo de vida del gateway) diff --git a/docs/es/tools/browser.md b/docs/es/tools/browser.md index 90c5000b8..ef33321ba 100644 --- a/docs/es/tools/browser.md +++ b/docs/es/tools/browser.md @@ -1,28 +1,28 @@ --- read_when: - Agregar automatización del navegador controlada por el agente - - Depuración de por qué openclaw está interfiriendo con tu propio Chrome + - Depurar por qué openclaw está interfiriendo con tu propio Chrome - Implementar la configuración y el ciclo de vida del navegador en la app de macOS summary: Servicio integrado de control del navegador + comandos de acción -title: Navegador (gestionado por OpenClaw) +title: Navegador (administrado por OpenClaw) x-i18n: - generated_at: "2026-04-14T13:04:31Z" + generated_at: "2026-04-20T05:21:57Z" model: gpt-5.4 provider: openai - source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 + source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b source_path: tools/browser.md workflow: 15 --- -# Navegador (gestionado por openclaw) +# Navegador (administrado por openclaw) OpenClaw puede ejecutar un **perfil dedicado de Chrome/Brave/Edge/Chromium** que el agente controla. -Está aislado de tu navegador personal y se gestiona mediante un pequeño -servicio de control local dentro del Gateway (solo loopback). +Está aislado de tu navegador personal y se administra mediante un pequeño servicio local +de control dentro de Gateway (solo loopback). Vista para principiantes: -- Piénsalo como un **navegador separado, solo para el agente**. +- Piensa en esto como un **navegador separado, solo para el agente**. - El perfil `openclaw` **no** toca el perfil de tu navegador personal. - El agente puede **abrir pestañas, leer páginas, hacer clic y escribir** en un entorno seguro. - El perfil integrado `user` se conecta a tu sesión real de Chrome con inicio de sesión mediante Chrome MCP. @@ -31,11 +31,11 @@ Vista para principiantes: - Un perfil de navegador separado llamado **openclaw** (acento naranja de forma predeterminada). - Control determinista de pestañas (listar/abrir/enfocar/cerrar). -- Acciones del agente (clic/escritura/arrastrar/seleccionar), instantáneas, capturas de pantalla y PDF. +- Acciones del agente (clic/escribir/arrastrar/seleccionar), snapshots, capturas de pantalla, PDF. - Compatibilidad opcional con varios perfiles (`openclaw`, `work`, `remote`, ...). -Este navegador **no** es tu navegador de uso diario. Es una superficie segura y aislada para -la automatización y verificación por parte del agente. +Este navegador **no** es tu navegador principal del día a día. Es una superficie +segura y aislada para la automatización y verificación por parte del agente. ## Inicio rápido @@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Si aparece “Browser disabled”, actívalo en la configuración (ver abajo) y reinicia el +Si ves “Browser disabled”, actívalo en la configuración (consulta abajo) y reinicia Gateway. -Si `openclaw browser` falta por completo, o el agente dice que la herramienta de navegador -no está disponible, ve a [Falta el comando o la herramienta de navegador](/es/tools/browser#missing-browser-command-or-tool). +Si `openclaw browser` no aparece en absoluto, o el agente dice que la herramienta de navegador +no está disponible, ve a [Falta el comando o la herramienta del navegador](/es/tools/browser#missing-browser-command-or-tool). ## Control del Plugin -La herramienta `browser` predeterminada ahora es un Plugin integrado que se envía habilitado de -forma predeterminada. Eso significa que puedes desactivarlo o reemplazarlo sin quitar el resto del +La herramienta `browser` predeterminada ahora es un Plugin incluido que se envía activado +de forma predeterminada. Eso significa que puedes desactivarlo o reemplazarlo sin quitar el resto del sistema de plugins de OpenClaw: ```json5 @@ -70,33 +70,33 @@ sistema de plugins de OpenClaw: } ``` -Desactiva el Plugin integrado antes de instalar otro Plugin que proporcione el +Desactiva el Plugin incluido antes de instalar otro plugin que proporcione el mismo nombre de herramienta `browser`. La experiencia predeterminada del navegador necesita ambos: - `plugins.entries.browser.enabled` no desactivado - `browser.enabled=true` -Si desactivas solo el Plugin, el CLI de navegador integrado (`openclaw browser`), -el método del gateway (`browser.request`), la herramienta del agente y el servicio -predeterminado de control del navegador desaparecen juntos. Tu configuración `browser.*` permanece intacta para que un -Plugin de reemplazo la reutilice. +Si desactivas solo el plugin, la CLI de navegador incluida (`openclaw browser`), +el método de gateway (`browser.request`), la herramienta del agente y el servicio predeterminado de control del navegador +desaparecen juntos. Tu configuración `browser.*` permanece intacta para que un +plugin de reemplazo la reutilice. -El Plugin de navegador integrado ahora también es propietario de la implementación del runtime del navegador. -El núcleo conserva solo los helpers compartidos del Plugin SDK más reexportaciones de compatibilidad para -rutas de importación internas antiguas. En la práctica, quitar o reemplazar el paquete del Plugin -de navegador elimina el conjunto de funciones del navegador en lugar de dejar detrás un segundo runtime +El Plugin de navegador incluido ahora también es propietario de la implementación del runtime del navegador. +El núcleo conserva solo helpers compartidos del Plugin SDK, además de reexportaciones de compatibilidad para +rutas de importación internas más antiguas. En la práctica, quitar o reemplazar el paquete del plugin del navegador +elimina el conjunto de funciones del navegador en lugar de dejar detrás un segundo runtime propiedad del núcleo. -Los cambios en la configuración del navegador siguen requiriendo reiniciar el Gateway para que el Plugin integrado +Los cambios en la configuración del navegador siguen requiriendo reiniciar Gateway para que el Plugin incluido pueda volver a registrar su servicio de navegador con la nueva configuración. -## Falta el comando o la herramienta de navegador +## Falta el comando o la herramienta del navegador -Si `openclaw browser` pasa a ser de repente un comando desconocido después de una actualización, o -el agente informa que falta la herramienta de navegador, la causa más común es una lista restrictiva +Si `openclaw browser` de repente pasa a ser un comando desconocido después de una actualización, o +el agente informa de que falta la herramienta del navegador, la causa más común es una lista restrictiva `plugins.allow` que no incluye `browser`. -Ejemplo de configuración incorrecta: +Ejemplo de configuración rota: ```json5 { @@ -106,7 +106,7 @@ Ejemplo de configuración incorrecta: } ``` -Soluciónalo agregando `browser` a la lista de permitidos de plugins: +Corrígelo agregando `browser` a la lista de plugins permitidos: ```json5 { @@ -120,46 +120,46 @@ Notas importantes: - `browser.enabled=true` no es suficiente por sí solo cuando `plugins.allow` está configurado. - `plugins.entries.browser.enabled=true` tampoco es suficiente por sí solo cuando `plugins.allow` está configurado. -- `tools.alsoAllow: ["browser"]` **no** carga el Plugin de navegador integrado. Solo ajusta la política de herramientas después de que el Plugin ya está cargado. -- Si no necesitas una lista restrictiva de plugins permitidos, eliminar `plugins.allow` también restaura el comportamiento predeterminado del navegador integrado. +- `tools.alsoAllow: ["browser"]` **no** carga el Plugin de navegador incluido. Solo ajusta la política de herramientas después de que el plugin ya se haya cargado. +- Si no necesitas una lista restrictiva de plugins permitidos, quitar `plugins.allow` también restaura el comportamiento predeterminado del navegador incluido. Síntomas típicos: - `openclaw browser` es un comando desconocido. -- Falta `browser.request`. -- El agente informa que la herramienta de navegador no está disponible o falta. +- falta `browser.request`. +- El agente informa que la herramienta del navegador no está disponible o falta. ## Perfiles: `openclaw` frente a `user` -- `openclaw`: navegador gestionado y aislado (no requiere extensión). -- `user`: perfil integrado de conexión Chrome MCP para tu sesión **real de Chrome con inicio de sesión**. +- `openclaw`: navegador administrado y aislado (no requiere extensión). +- `user`: perfil integrado de conexión de Chrome MCP para tu sesión **real de Chrome con inicio de sesión**. Para las llamadas de la herramienta de navegador del agente: - Predeterminado: usa el navegador aislado `openclaw`. -- Prefiere `profile="user"` cuando las sesiones existentes con inicio de sesión importan y el usuario - está en la computadora para hacer clic/aprobar cualquier aviso de conexión. +- Prefiere `profile="user"` cuando importen las sesiones existentes con inicio de sesión y el usuario + esté en la computadora para hacer clic o aprobar cualquier aviso de conexión. - `profile` es la anulación explícita cuando quieres un modo de navegador específico. -Establece `browser.defaultProfile: "openclaw"` si quieres el modo gestionado de forma predeterminada. +Configura `browser.defaultProfile: "openclaw"` si quieres el modo administrado de forma predeterminada. ## Configuración -La configuración del navegador vive en `~/.openclaw/openclaw.json`. +La configuración del navegador se encuentra en `~/.openclaw/openclaw.json`. ```json5 { browser: { - enabled: true, // predeterminado: true + enabled: true, // default: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // optar solo para acceso confiable a red privada - // allowPrivateNetwork: true, // alias heredado + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // anulación heredada de un solo perfil - remoteCdpTimeoutMs: 1500, // tiempo de espera HTTP de CDP remoto (ms) - remoteCdpHandshakeTimeoutMs: 3000, // tiempo de espera del handshake WebSocket de CDP remoto (ms) + // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override + remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) + remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -190,30 +190,30 @@ Notas: - El servicio de control del navegador se enlaza a loopback en un puerto derivado de `gateway.port` (predeterminado: `18791`, que es gateway + 2). -- Si anulas el puerto del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), - los puertos derivados del navegador se desplazan para permanecer en la misma “familia”. -- `cdpUrl` usa de forma predeterminada el puerto CDP local gestionado cuando no está establecido. -- `remoteCdpTimeoutMs` se aplica a las comprobaciones de alcance de CDP remoto (no loopback). -- `remoteCdpHandshakeTimeoutMs` se aplica a las comprobaciones de alcance del WebSocket de CDP remoto. -- La navegación del navegador o apertura de pestañas está protegida contra SSRF antes de navegar y se vuelve a comprobar en el mejor esfuerzo en la URL final `http(s)` después de la navegación. -- En el modo estricto de SSRF, también se comprueban el descubrimiento y los sondeos de endpoints CDP remotos (`cdpUrl`, incluidas las búsquedas de `/json/version`). -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` está desactivado de forma predeterminada. Establécelo en `true` solo cuando confíes intencionalmente en el acceso del navegador a redes privadas. +- Si sobrescribes el puerto de Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), + los puertos derivados del navegador cambian para permanecer en la misma “familia”. +- `cdpUrl` usa de forma predeterminada el puerto CDP local administrado cuando no está configurado. +- `remoteCdpTimeoutMs` se aplica a las comprobaciones de accesibilidad de CDP remoto (no loopback). +- `remoteCdpHandshakeTimeoutMs` se aplica a las comprobaciones de accesibilidad del handshake WebSocket de CDP remoto. +- La navegación del navegador y la apertura de pestañas están protegidas contra SSRF antes de la navegación y se vuelven a comprobar en la medida de lo posible en la URL final `http(s)` después de la navegación. +- En el modo SSRF estricto, la detección y las sondas del endpoint CDP remoto (`cdpUrl`, incluidas las búsquedas de `/json/version`) también se comprueban. +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` está desactivado de forma predeterminada. Establécelo en `true` solo cuando confíes intencionalmente en el acceso del navegador a la red privada. - `browser.ssrfPolicy.allowPrivateNetwork` sigue siendo compatible como alias heredado por compatibilidad. -- `attachOnly: true` significa “nunca iniciar un navegador local; solo conectarse si ya se está ejecutando.” -- `color` + `color` por perfil tiñen la interfaz del navegador para que puedas ver qué perfil está activo. -- El perfil predeterminado es `openclaw` (navegador independiente gestionado por OpenClaw). Usa `defaultProfile: "user"` para optar por el navegador del usuario con inicio de sesión. -- Orden de autodetección: navegador predeterminado del sistema si está basado en Chromium; de lo contrario Chrome → Brave → Edge → Chromium → Chrome Canary. -- Los perfiles `openclaw` locales asignan automáticamente `cdpPort`/`cdpUrl`; establécelos solo para CDP remoto. -- `driver: "existing-session"` usa Chrome DevTools MCP en lugar de CDP sin procesar. No - establezcas `cdpUrl` para ese driver. -- Establece `browser.profiles..userDataDir` cuando un perfil de sesión existente +- `attachOnly: true` significa “nunca iniciar un navegador local; solo conectarse si ya está en ejecución”. +- `color` + el `color` por perfil tiñen la IU del navegador para que puedas ver qué perfil está activo. +- El perfil predeterminado es `openclaw` (navegador independiente administrado por OpenClaw). Usa `defaultProfile: "user"` para optar por el navegador del usuario con inicio de sesión. +- Orden de detección automática: navegador predeterminado del sistema si está basado en Chromium; en caso contrario Chrome → Brave → Edge → Chromium → Chrome Canary. +- Los perfiles `openclaw` locales asignan `cdpPort`/`cdpUrl` automáticamente; configúralos solo para CDP remoto. +- `driver: "existing-session"` usa Chrome DevTools MCP en lugar de CDP sin formato. No + configures `cdpUrl` para ese driver. +- Configura `browser.profiles..userDataDir` cuando un perfil existing-session deba conectarse a un perfil de usuario Chromium no predeterminado, como Brave o Edge. ## Usar Brave (u otro navegador basado en Chromium) Si tu navegador **predeterminado del sistema** está basado en Chromium (Chrome/Brave/Edge/etc.), -OpenClaw lo usa automáticamente. Establece `browser.executablePath` para anular la -autodetección: +OpenClaw lo usa automáticamente. Configura `browser.executablePath` para sobrescribir +la detección automática: Ejemplo de CLI: @@ -246,18 +246,18 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Control local frente a remoto -- **Control local (predeterminado):** el Gateway inicia el servicio de control en loopback y puede iniciar un navegador local. -- **Control remoto (host node):** ejecuta un host node en la máquina que tiene el navegador; el Gateway redirige a él las acciones del navegador. -- **CDP remoto:** establece `browser.profiles..cdpUrl` (o `browser.cdpUrl`) para +- **Control local (predeterminado):** Gateway inicia el servicio de control en loopback y puede iniciar un navegador local. +- **Control remoto (host de Node):** ejecuta un host de Node en la máquina que tiene el navegador; Gateway envía mediante proxy las acciones del navegador hacia él. +- **CDP remoto:** configura `browser.profiles..cdpUrl` (o `browser.cdpUrl`) para conectarte a un navegador remoto basado en Chromium. En este caso, OpenClaw no iniciará un navegador local. -El comportamiento de detención difiere según el modo del perfil: +El comportamiento al detenerse difiere según el modo del perfil: -- perfiles locales gestionados: `openclaw browser stop` detiene el proceso del navegador que +- perfiles locales administrados: `openclaw browser stop` detiene el proceso del navegador que OpenClaw inició -- perfiles de solo conexión y CDP remoto: `openclaw browser stop` cierra la sesión de control - activa y libera las anulaciones de emulación de Playwright/CDP (viewport, - esquema de color, configuración regional, zona horaria, modo sin conexión y estado similar), aunque +- perfiles solo de conexión y perfiles CDP remotos: `openclaw browser stop` cierra la sesión de + control activa y libera las anulaciones de emulación de Playwright/CDP (viewport, + combinación de colores, configuración regional, zona horaria, modo sin conexión y estados similares), aunque OpenClaw no haya iniciado ningún proceso de navegador Las URL de CDP remoto pueden incluir autenticación: @@ -271,25 +271,25 @@ tokens en lugar de confirmarlos en archivos de configuración. ## Proxy de navegador de Node (predeterminado sin configuración) -Si ejecutas un **host node** en la máquina que tiene tu navegador, OpenClaw puede -redirigir automáticamente las llamadas de la herramienta de navegador a ese node sin ninguna configuración adicional del navegador. +Si ejecutas un **host de Node** en la máquina que tiene tu navegador, OpenClaw puede +enrutar automáticamente las llamadas a la herramienta del navegador a ese Node sin ninguna configuración adicional del navegador. Esta es la ruta predeterminada para gateways remotos. Notas: -- El host node expone su servidor local de control del navegador mediante un **comando proxy**. -- Los perfiles provienen de la propia configuración `browser.profiles` del node (igual que en local). -- `nodeHost.browserProxy.allowProfiles` es opcional. Déjalo vacío para el comportamiento heredado/predeterminado: todos los perfiles configurados siguen siendo accesibles a través del proxy, incluidas las rutas para crear/eliminar perfiles. -- Si estableces `nodeHost.browserProxy.allowProfiles`, OpenClaw lo trata como un límite de privilegio mínimo: solo se pueden seleccionar los perfiles de la lista permitida, y las rutas persistentes de creación/eliminación de perfiles se bloquean en la superficie del proxy. +- El host de Node expone su servidor local de control del navegador mediante un **comando proxy**. +- Los perfiles provienen de la propia configuración `browser.profiles` del nodo (igual que en local). +- `nodeHost.browserProxy.allowProfiles` es opcional. Déjalo vacío para el comportamiento heredado/predeterminado: todos los perfiles configurados siguen siendo accesibles a través del proxy, incluidas las rutas de creación/eliminación de perfiles. +- Si configuras `nodeHost.browserProxy.allowProfiles`, OpenClaw lo trata como un límite de privilegio mínimo: solo se pueden usar los perfiles permitidos, y las rutas persistentes de creación/eliminación de perfiles se bloquean en la superficie del proxy. - Desactívalo si no lo quieres: - - En el node: `nodeHost.browserProxy.enabled=false` + - En el nodo: `nodeHost.browserProxy.enabled=false` - En el gateway: `gateway.nodes.browser.mode="off"` ## Browserless (CDP remoto alojado) [Browserless](https://browserless.io) es un servicio alojado de Chromium que expone -URL de conexión CDP a través de HTTPS y WebSocket. OpenClaw puede usar cualquiera de las dos formas, pero -para un perfil de navegador remoto la opción más simple es la URL WebSocket directa +URL de conexión CDP mediante HTTPS y WebSocket. OpenClaw puede usar cualquiera de las dos formas, pero +para un perfil de navegador remoto la opción más sencilla es la URL WebSocket directa de la documentación de conexión de Browserless. Ejemplo: @@ -319,23 +319,37 @@ Notas: `wss://` para una conexión CDP directa o conservar la URL HTTPS y dejar que OpenClaw descubra `/json/version`. -## Proveedores de CDP WebSocket directo +## Proveedores CDP directos por WebSocket -Algunos servicios de navegador alojado exponen un endpoint **WebSocket directo** en lugar de -la detección estándar de CDP basada en HTTP (`/json/version`). OpenClaw admite ambos: +Algunos servicios de navegador alojados exponen un endpoint **WebSocket directo** en lugar de +la detección CDP estándar basada en HTTP (`/json/version`). OpenClaw acepta tres +formatos de URL CDP y elige automáticamente la estrategia de conexión correcta: -- **Endpoints HTTP(S)** — OpenClaw llama a `/json/version` para descubrir la - URL del depurador WebSocket y luego se conecta. -- **Endpoints WebSocket** (`ws://` / `wss://`) — OpenClaw se conecta directamente, - omitiendo `/json/version`. Úsalo para servicios como - [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com), o cualquier proveedor que te entregue una - URL WebSocket. +- **Detección HTTP(S)** — `http://host[:port]` o `https://host[:port]`. + OpenClaw llama a `/json/version` para descubrir la URL del depurador WebSocket y luego + se conecta. Sin fallback a WebSocket. +- **Endpoints WebSocket directos** — `ws://host[:port]/devtools//` o + `wss://...` con una ruta `/devtools/browser|page|worker|shared_worker|service_worker/`. + OpenClaw se conecta directamente mediante un handshake WebSocket y omite + por completo `/json/version`. +- **Raíces WebSocket simples** — `ws://host[:port]` o `wss://host[:port]` sin + una ruta `/devtools/...` (por ejemplo, [Browserless](https://browserless.io), + [Browserbase](https://www.browserbase.com)). OpenClaw intenta primero la detección HTTP + de `/json/version` (normalizando el esquema a `http`/`https`); + si la detección devuelve un `webSocketDebuggerUrl`, se usa; en caso contrario, OpenClaw + recurre a un handshake WebSocket directo en la raíz simple. Esto cubre + tanto puertos de depuración remota de estilo Chrome como proveedores solo WebSocket. + +`ws://host:port` / `wss://host:port` simples sin una ruta `/devtools/...` +apuntando a una instancia local de Chrome son compatibles mediante el fallback +que intenta primero la detección: Chrome solo acepta actualizaciones WebSocket en la ruta específica por navegador +o por destino devuelta por `/json/version`, por lo que un handshake solo en la raíz +fallaría. ### Browserbase [Browserbase](https://www.browserbase.com) es una plataforma en la nube para ejecutar -navegadores headless con resolución integrada de CAPTCHA, modo sigiloso y proxies +navegadores sin interfaz con resolución de CAPTCHA integrada, modo sigiloso y proxies residenciales. ```json5 @@ -359,59 +373,59 @@ Notas: - [Regístrate](https://www.browserbase.com/sign-up) y copia tu **API Key** desde el [panel Overview](https://www.browserbase.com/overview). -- Reemplaza `` por tu API key real de Browserbase. -- Browserbase crea automáticamente una sesión de navegador al conectarse por WebSocket, así que - no se necesita ningún paso manual de creación de sesión. +- Reemplaza `` por tu clave de API real de Browserbase. +- Browserbase crea automáticamente una sesión de navegador al conectarse por WebSocket, así que no + hace falta ningún paso manual de creación de sesión. - El nivel gratuito permite una sesión concurrente y una hora de navegador al mes. - Consulta los [precios](https://www.browserbase.com/pricing) para los límites de los planes de pago. -- Consulta la [documentación de Browserbase](https://docs.browserbase.com) para la referencia completa de la API, - las guías del SDK y los ejemplos de integración. + Consulta los [precios](https://www.browserbase.com/pricing) para conocer los límites de los planes de pago. +- Consulta la [documentación de Browserbase](https://docs.browserbase.com) para ver la referencia completa de la API, + guías del SDK y ejemplos de integración. ## Seguridad Ideas clave: -- El control del navegador es solo por loopback; el acceso fluye a través de la autenticación del Gateway o del emparejamiento de node. -- La API HTTP independiente del navegador en loopback usa **solo autenticación de secreto compartido**: - autenticación bearer con token del gateway, `x-openclaw-password`, o autenticación HTTP Basic con la - contraseña de gateway configurada. +- El control del navegador es solo loopback; el acceso fluye a través de la autenticación de Gateway o del emparejamiento de nodos. +- La API HTTP independiente del navegador en loopback usa **solo autenticación con secreto compartido**: + auth bearer con el token de gateway, `x-openclaw-password` o autenticación HTTP Basic con la + contraseña configurada del gateway. - Los encabezados de identidad de Tailscale Serve y `gateway.auth.mode: "trusted-proxy"` **no** - autentican esta API independiente del navegador en loopback. -- Si el control del navegador está habilitado y no hay autenticación de secreto compartido configurada, OpenClaw - genera automáticamente `gateway.auth.token` al iniciar y lo guarda en la configuración. + autentican esta API HTTP independiente del navegador en loopback. +- Si el control del navegador está activado y no se configura ninguna autenticación con secreto compartido, OpenClaw + genera automáticamente `gateway.auth.token` al iniciar y lo persiste en la configuración. - OpenClaw **no** genera automáticamente ese token cuando `gateway.auth.mode` ya es `password`, `none` o `trusted-proxy`. -- Mantén el Gateway y cualquier host node en una red privada (Tailscale); evita la exposición pública. -- Trata las URL/tokens remotos de CDP como secretos; prefiere variables de entorno o un gestor de secretos. +- Mantén Gateway y cualquier host de nodo en una red privada (Tailscale); evita la exposición pública. +- Trata las URL y los tokens de CDP remoto como secretos; prefiere variables de entorno o un gestor de secretos. Consejos para CDP remoto: - Prefiere endpoints cifrados (HTTPS o WSS) y tokens de corta duración cuando sea posible. - Evita incrustar tokens de larga duración directamente en archivos de configuración. -## Perfiles (multi-browser) +## Perfiles (varios navegadores) OpenClaw admite varios perfiles con nombre (configuraciones de enrutamiento). Los perfiles pueden ser: -- **gestionados por openclaw**: una instancia dedicada de navegador basado en Chromium con su propio directorio de datos de usuario + puerto CDP -- **remoto**: una URL de CDP explícita (navegador basado en Chromium ejecutándose en otro lugar) -- **sesión existente**: tu perfil actual de Chrome mediante conexión automática de Chrome DevTools MCP +- **administrados por openclaw**: una instancia dedicada de navegador basado en Chromium con su propio directorio de datos de usuario + puerto CDP +- **remoto**: una URL CDP explícita (navegador basado en Chromium ejecutándose en otro lugar) +- **sesión existente**: tu perfil de Chrome existente mediante conexión automática de Chrome DevTools MCP Valores predeterminados: - El perfil `openclaw` se crea automáticamente si falta. -- El perfil `user` viene integrado para la conexión de sesión existente de Chrome MCP. -- Los perfiles de sesión existente son opcionales más allá de `user`; créalos con `--driver existing-session`. -- Los puertos CDP locales se asignan desde **18800–18899** de forma predeterminada. -- Eliminar un perfil mueve su directorio de datos local a la Papelera. +- El perfil `user` está integrado para la conexión de sesión existente de Chrome MCP. +- Los perfiles de sesión existente son opcionales además de `user`; créalos con `--driver existing-session`. +- Los puertos CDP locales se asignan del rango **18800–18899** de forma predeterminada. +- Al eliminar un perfil, su directorio de datos local se mueve a la papelera. -Todos los endpoints de control aceptan `?profile=`; el CLI usa `--browser-profile`. +Todos los endpoints de control aceptan `?profile=`; la CLI usa `--browser-profile`. ## Sesión existente mediante Chrome DevTools MCP -OpenClaw también puede conectarse a un perfil de navegador basado en Chromium en ejecución mediante el +OpenClaw también puede conectarse a un perfil de navegador basado en Chromium en ejecución a través del servidor oficial Chrome DevTools MCP. Esto reutiliza las pestañas y el estado de inicio de sesión -ya abiertos en ese perfil de navegador. +ya abiertos en ese perfil del navegador. Referencias oficiales de contexto y configuración: @@ -449,8 +463,8 @@ Usa `userDataDir` para Brave, Edge, Chromium o un perfil de Chrome no predetermi Luego, en el navegador correspondiente: -1. Abre la página de inspección de ese navegador para depuración remota. -2. Habilita la depuración remota. +1. Abre la página de inspección de ese navegador para la depuración remota. +2. Activa la depuración remota. 3. Mantén el navegador en ejecución y aprueba el aviso de conexión cuando OpenClaw se conecte. Páginas de inspección comunes: @@ -468,7 +482,7 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Cómo se ve el éxito: +Cómo se ve un resultado correcto: - `status` muestra `driver: existing-session` - `status` muestra `transport: chrome-mcp` @@ -478,62 +492,63 @@ Cómo se ve el éxito: Qué comprobar si la conexión no funciona: -- el navegador de destino basado en Chromium es versión `144+` -- la depuración remota está habilitada en la página de inspección de ese navegador -- el navegador mostró y aceptaste el aviso de consentimiento de conexión +- el navegador basado en Chromium de destino es la versión `144+` +- la depuración remota está activada en la página de inspección de ese navegador +- el navegador mostró el aviso de consentimiento de conexión y lo aceptaste - `openclaw doctor` migra la configuración antigua del navegador basada en extensiones y comprueba que - Chrome está instalado localmente para los perfiles predeterminados de conexión automática, pero no puede - habilitar por ti la depuración remota del lado del navegador + Chrome esté instalado localmente para los perfiles predeterminados con conexión automática, pero no puede + activar por ti la depuración remota del lado del navegador -Uso por el agente: +Uso por parte del agente: - Usa `profile="user"` cuando necesites el estado del navegador del usuario con sesión iniciada. - Si usas un perfil personalizado de sesión existente, pasa ese nombre de perfil explícito. - Elige este modo solo cuando el usuario esté en la computadora para aprobar el aviso de conexión. -- el Gateway o host node puede iniciar `npx chrome-devtools-mcp@latest --autoConnect` +- Gateway o el host del nodo pueden ejecutar `npx chrome-devtools-mcp@latest --autoConnect` Notas: -- Esta ruta tiene mayor riesgo que el perfil aislado `openclaw` porque puede - actuar dentro de tu sesión del navegador con inicio de sesión. -- OpenClaw no inicia el navegador para este driver; se conecta solo a una +- Esta ruta es de mayor riesgo que el perfil aislado `openclaw` porque puede + actuar dentro de tu sesión de navegador con inicio de sesión. +- OpenClaw no inicia el navegador para este driver; solo se conecta a una sesión existente. - OpenClaw usa aquí el flujo oficial `--autoConnect` de Chrome DevTools MCP. Si - `userDataDir` está configurado, OpenClaw lo pasa para apuntar a ese + `userDataDir` está configurado, OpenClaw lo transmite para apuntar a ese directorio de datos de usuario de Chromium explícito. -- Las capturas de pantalla de sesión existente admiten capturas de página y capturas de elementos con `--ref` - desde instantáneas, pero no selectores CSS `--element`. -- Las capturas de pantalla de página de sesión existente funcionan sin Playwright mediante Chrome MCP. +- Las capturas de pantalla de sesión existente admiten capturas de página y capturas de elementos + con `--ref` desde snapshots, pero no selectores CSS `--element`. +- Las capturas de pantalla de páginas de sesión existente funcionan sin Playwright mediante Chrome MCP. Las capturas de elementos basadas en refs (`--ref`) también funcionan allí, pero `--full-page` - no puede combinarse con `--ref` ni con `--element`. + no se puede combinar con `--ref` ni con `--element`. - Las acciones de sesión existente siguen siendo más limitadas que la ruta del navegador - gestionado: + administrado: - `click`, `type`, `hover`, `scrollIntoView`, `drag` y `select` requieren - refs de instantáneas en lugar de selectores CSS - - `click` es solo con botón izquierdo (sin anulaciones de botón ni modificadores) + refs de snapshot en lugar de selectores CSS + - `click` es solo con el botón izquierdo (sin sobrescrituras de botón ni modificadores) - `type` no admite `slowly=true`; usa `fill` o `press` - `press` no admite `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` y `evaluate` no - admiten anulaciones de tiempo de espera por llamada - - `select` actualmente admite solo un valor -- `wait --url` de sesión existente admite patrones exactos, de subcadena y glob - como otros drivers de navegador. `wait --load networkidle` todavía no es compatible. -- Los hooks de carga de archivos de sesión existente requieren `ref` o `inputRef`, admiten un archivo - a la vez y no admiten selección CSS mediante `element`. -- Los hooks de diálogos de sesión existente no admiten anulaciones de tiempo de espera. -- Algunas funciones todavía requieren la ruta del navegador gestionado, incluidas acciones - por lotes, exportación a PDF, interceptación de descargas y `responsebody`. -- La sesión existente es local al host. Si Chrome está en otra máquina o en un - espacio de nombres de red diferente, usa CDP remoto o un host node en su lugar. + admiten sobrescrituras de timeout por llamada + - `select` actualmente admite solo un único valor +- La sesión existente `wait --url` admite patrones exactos, de subcadena y glob + como otros drivers de navegador. `wait --load networkidle` aún no es compatible. +- Los hooks de carga de sesión existente requieren `ref` o `inputRef`, admiten un archivo + a la vez y no admiten direccionamiento CSS mediante `element`. +- Los hooks de diálogos de sesión existente no admiten sobrescrituras de timeout. +- Algunas funciones aún requieren la ruta del navegador administrado, incluidas acciones por lotes, + exportación a PDF, interceptación de descargas y `responsebody`. +- La sesión existente puede conectarse en el host seleccionado o a través de un nodo de navegador conectado. + Si Chrome está en otro lugar y no hay ningún nodo de navegador conectado, usa + CDP remoto o un host de nodo en su lugar. ## Garantías de aislamiento -- **Directorio de datos de usuario dedicado**: nunca toca el perfil de tu navegador personal. -- **Puertos dedicados**: evita `9222` para prevenir conflictos con flujos de trabajo de desarrollo. +- **Directorio dedicado de datos de usuario**: nunca toca el perfil de tu navegador personal. +- **Puertos dedicados**: evita `9222` para prevenir colisiones con flujos de trabajo de desarrollo. - **Control determinista de pestañas**: apunta a las pestañas por `targetId`, no por “última pestaña”. -## Selección del navegador +## Selección de navegador Al iniciar localmente, OpenClaw elige el primero disponible: @@ -543,21 +558,21 @@ Al iniciar localmente, OpenClaw elige el primero disponible: 4. Chromium 5. Chrome Canary -Puedes anularlo con `browser.executablePath`. +Puedes sobrescribirlo con `browser.executablePath`. Plataformas: - macOS: comprueba `/Applications` y `~/Applications`. - Linux: busca `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc. -- Windows: comprueba ubicaciones comunes de instalación. +- Windows: comprueba ubicaciones de instalación comunes. ## API de control (opcional) -Solo para integraciones locales, el Gateway expone una pequeña API HTTP en loopback: +Solo para integraciones locales, Gateway expone una pequeña API HTTP en loopback: - Estado/inicio/detención: `GET /`, `POST /start`, `POST /stop` - Pestañas: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` -- Instantánea/captura de pantalla: `GET /snapshot`, `POST /screenshot` +- Snapshot/captura de pantalla: `GET /snapshot`, `POST /screenshot` - Acciones: `POST /navigate`, `POST /act` - Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog` - Descargas: `POST /download`, `POST /wait/download` @@ -577,15 +592,15 @@ Si la autenticación de gateway con secreto compartido está configurada, las ru Notas: -- Esta API independiente del navegador en loopback **no** consume `trusted-proxy` ni - encabezados de identidad de Tailscale Serve. -- Si `gateway.auth.mode` es `none` o `trusted-proxy`, estas rutas del navegador en loopback - no heredan esos modos basados en identidad; mantenlas solo en loopback. +- Esta API independiente del navegador en loopback **no** consume encabezados de identidad de trusted-proxy ni de + Tailscale Serve. +- Si `gateway.auth.mode` es `none` o `trusted-proxy`, estas rutas de navegador en loopback + no heredan esos modos con identidad; mantenlas solo en loopback. ### Contrato de error de `/act` -`POST /act` usa una respuesta de error estructurada para fallos de validación a nivel de ruta y -de política: +`POST /act` usa una respuesta de error estructurada para fallos de validación y +de política a nivel de ruta: ```json { "error": "", "code": "ACT_*" } @@ -594,13 +609,13 @@ de política: Valores actuales de `code`: - `ACT_KIND_REQUIRED` (HTTP 400): falta `kind` o no se reconoce. -- `ACT_INVALID_REQUEST` (HTTP 400): el payload de la acción falló la normalización o la validación. +- `ACT_INVALID_REQUEST` (HTTP 400): la carga útil de la acción falló en la normalización o validación. - `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): se usó `selector` con un tipo de acción no compatible. -- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (o `wait --fn`) está deshabilitado por configuración. -- `ACT_TARGET_ID_MISMATCH` (HTTP 403): el `targetId` de nivel superior o por lotes entra en conflicto con el destino de la solicitud. +- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (o `wait --fn`) está desactivado por configuración. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` de nivel superior o por lotes entra en conflicto con el destino de la solicitud. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): la acción no es compatible con perfiles de sesión existente. -Otros fallos en tiempo de ejecución aún pueden devolver `{ "error": "" }` sin un +Otros fallos de runtime aún pueden devolver `{ "error": "" }` sin un campo `code`. ### Requisito de Playwright @@ -609,40 +624,40 @@ Algunas funciones (navigate/act/AI snapshot/role snapshot, capturas de pantalla PDF) requieren Playwright. Si Playwright no está instalado, esos endpoints devuelven un error 501 claro. -Lo que sigue funcionando sin Playwright: +Qué sigue funcionando sin Playwright: -- Instantáneas ARIA -- Capturas de pantalla de página para el navegador gestionado `openclaw` cuando hay un WebSocket +- Snapshots ARIA +- Capturas de pantalla de página para el navegador administrado `openclaw` cuando haya un WebSocket CDP por pestaña disponible - Capturas de pantalla de página para perfiles `existing-session` / Chrome MCP -- Capturas de pantalla basadas en refs (`--ref`) de `existing-session` desde la salida de instantáneas +- Capturas de pantalla basadas en refs de `existing-session` (`--ref`) a partir de la salida de snapshot -Lo que todavía necesita Playwright: +Qué sigue necesitando Playwright: - `navigate` - `act` -- Instantáneas AI / instantáneas de rol +- AI snapshots / role snapshots - Capturas de pantalla de elementos con selector CSS (`--element`) - Exportación completa de PDF del navegador Las capturas de pantalla de elementos también rechazan `--full-page`; la ruta devuelve `fullPage is not supported for element screenshots`. -Si ves `Playwright is not available in this gateway build`, instala el paquete completo de -Playwright (no `playwright-core`) y reinicia el gateway, o vuelve a instalar +Si ves `Playwright is not available in this gateway build`, instala el paquete completo +de Playwright (no `playwright-core`) y reinicia el gateway, o reinstala OpenClaw con compatibilidad para navegador. #### Instalación de Playwright en Docker -Si tu Gateway se ejecuta en Docker, evita `npx playwright` (conflictos de anulación de npm). -Usa en su lugar el CLI integrado: +Si tu Gateway se ejecuta en Docker, evita `npx playwright` (conflictos con npm override). +Usa la CLI incluida en su lugar: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -Para conservar las descargas del navegador, establece `PLAYWRIGHT_BROWSERS_PATH` (por ejemplo, +Para conservar las descargas del navegador, configura `PLAYWRIGHT_BROWSERS_PATH` (por ejemplo, `/home/node/.cache/ms-playwright`) y asegúrate de que `/home/node` se conserve mediante `OPENCLAW_HOME_VOLUME` o un bind mount. Consulta [Docker](/es/install/docker). @@ -652,19 +667,19 @@ Flujo de alto nivel: - Un pequeño **servidor de control** acepta solicitudes HTTP. - Se conecta a navegadores basados en Chromium (Chrome/Brave/Edge/Chromium) mediante **CDP**. -- Para acciones avanzadas (clic/escritura/instantánea/PDF), usa **Playwright** sobre +- Para acciones avanzadas (click/type/snapshot/PDF), usa **Playwright** sobre CDP. -- Cuando falta Playwright, solo están disponibles las operaciones que no usan Playwright. +- Cuando falta Playwright, solo están disponibles las operaciones que no dependen de Playwright. -Este diseño mantiene al agente en una interfaz estable y determinista, a la vez que te permite -intercambiar navegadores y perfiles locales/remotos. +Este diseño mantiene al agente en una interfaz estable y determinista, al tiempo que te permite +intercambiar navegadores y perfiles locales o remotos. -## Referencia rápida del CLI +## Referencia rápida de la CLI -Todos los comandos aceptan `--browser-profile ` para apuntar a un perfil específico. -Todos los comandos también aceptan `--json` para salida legible por máquina (payloads estables). +Todos los comandos aceptan `--browser-profile ` para dirigirse a un perfil específico. +Todos los comandos también aceptan `--json` para salida legible por máquina (cargas útiles estables). -Conceptos básicos: +Básicos: - `openclaw browser status` - `openclaw browser start` @@ -695,10 +710,10 @@ Inspección: Nota sobre el ciclo de vida: -- Para perfiles de solo conexión y CDP remoto, `openclaw browser stop` sigue siendo el +- Para perfiles solo de conexión y de CDP remoto, `openclaw browser stop` sigue siendo el comando correcto de limpieza después de las pruebas. Cierra la sesión de control activa y - limpia las anulaciones temporales de emulación en lugar de finalizar el - navegador subyacente. + borra las anulaciones temporales de emulación en lugar de finalizar el navegador + subyacente. - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -749,47 +764,47 @@ Estado: Notas: -- `upload` y `dialog` son llamadas de **preparación**; ejecútalas antes del clic/tecla +- `upload` y `dialog` son llamadas de **preparación**; ejecútalas antes del click/press que activa el selector de archivos o el diálogo. -- Las rutas de salida de descargas y trazas están restringidas a las raíces temporales de OpenClaw: - - trazas: `/tmp/openclaw` (alternativa: `${os.tmpdir()}/openclaw`) - - descargas: `/tmp/openclaw/downloads` (alternativa: `${os.tmpdir()}/openclaw/downloads`) +- Las rutas de salida de descargas y trazas están restringidas a raíces temporales de OpenClaw: + - trazas: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`) + - descargas: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`) - Las rutas de carga están restringidas a una raíz temporal de cargas de OpenClaw: - - cargas: `/tmp/openclaw/uploads` (alternativa: `${os.tmpdir()}/openclaw/uploads`) -- `upload` también puede establecer entradas de archivo directamente mediante `--input-ref` o `--element`. + - cargas: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`) +- `upload` también puede configurar directamente entradas de archivo mediante `--input-ref` o `--element`. - `snapshot`: - - `--format ai` (predeterminado cuando Playwright está instalado): devuelve una instantánea AI con refs numéricos (`aria-ref=""`). + - `--format ai` (predeterminado cuando Playwright está instalado): devuelve un AI snapshot con refs numéricas (`aria-ref=""`). - `--format aria`: devuelve el árbol de accesibilidad (sin refs; solo inspección). - - `--efficient` (o `--mode efficient`): preajuste compacto de instantánea de rol (interactiva + compacta + profundidad + maxChars menor). - - Predeterminado de configuración (solo herramienta/CLI): establece `browser.snapshotDefaults.mode: "efficient"` para usar instantáneas eficientes cuando el llamador no pasa un modo (consulta [Configuración del Gateway](/es/gateway/configuration-reference#browser)). - - Las opciones de instantánea de rol (`--interactive`, `--compact`, `--depth`, `--selector`) fuerzan una instantánea basada en roles con refs como `ref=e12`. - - `--frame "