From 96b4470fb00f82ed6c022b2ceaae03689b20549f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 9 Apr 2026 01:35:03 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/channels/discord.md | 428 +++--- docs/es/channels/matrix.md | 664 +++++----- docs/es/concepts/agent-loop.md | 183 +-- docs/es/concepts/dreaming.md | 129 +- docs/es/concepts/memory.md | 165 ++- docs/es/concepts/model-providers.md | 496 +++---- docs/es/concepts/qa-e2e-automation.md | 93 +- docs/es/gateway/cli-backends.md | 159 +-- docs/es/gateway/configuration-reference.md | 1109 ++++++++-------- docs/es/gateway/doctor.md | 460 ++++--- docs/es/help/testing.md | 606 ++++----- ...refactor-real-plugin-sdk-workspace-plan.md | 584 -------- docs/es/plugins/architecture.md | 1175 +++++++++-------- docs/es/plugins/manifest.md | 311 ++--- docs/es/plugins/sdk-migration.md | 444 +++---- docs/es/plugins/sdk-overview.md | 563 ++++---- docs/es/plugins/sdk-provider-plugins.md | 322 ++--- docs/es/providers/google.md | 89 +- docs/es/providers/inferrs.md | 62 +- docs/es/providers/ollama.md | 84 +- docs/es/providers/qwen.md | 116 +- 21 files changed, 3920 insertions(+), 4322 deletions(-) delete mode 100644 docs/es/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md diff --git a/docs/es/channels/discord.md b/docs/es/channels/discord.md index 374e0dfd7..7e62671d9 100644 --- a/docs/es/channels/discord.md +++ b/docs/es/channels/discord.md @@ -1,26 +1,26 @@ --- read_when: - Trabajando en funciones del canal de Discord -summary: Estado de compatibilidad, capacidades y configuración del bot de Discord +summary: Estado del soporte del bot de Discord, capacidades y configuración title: Discord x-i18n: - generated_at: "2026-04-06T03:08:07Z" + generated_at: "2026-04-09T01:29:29Z" model: gpt-5.4 provider: openai - source_hash: 54af2176a1b4fa1681e3f07494def0c652a2730165058848000e71a59e2a9d08 + source_hash: 3cd2886fad941ae2129e681911309539e9a65a2352b777b538d7f4686a68f73f source_path: channels/discord.md workflow: 15 --- # Discord (API de bot) -Estado: listo para mensajes directos y canales de servidor mediante el gateway oficial de Discord. +Estado: listo para mensajes directos y canales de servidor mediante la gateway oficial de Discord. - - Los mensajes directos de Discord usan el modo de vinculación de forma predeterminada. + + Los mensajes directos de Discord usan el modo de emparejamiento de forma predeterminada. - + Comportamiento nativo de comandos y catálogo de comandos. @@ -30,7 +30,7 @@ Estado: listo para mensajes directos y canales de servidor mediante el gateway o ## Configuración rápida -Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servidor y vincularlo con OpenClaw. Recomendamos añadir tu bot a tu propio servidor privado. Si aún no tienes uno, [crea uno primero](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (elige **Create My Own > For me and my friends**). +Necesitarás crear una aplicación nueva con un bot, añadir el bot a tu servidor y emparejarlo con OpenClaw. Recomendamos añadir tu bot a tu propio servidor privado. Si todavía no tienes uno, [crea uno primero](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (elige **Create My Own > For me and my friends**). @@ -41,16 +41,16 @@ Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servido - Sigue en la página **Bot**, desplázate hacia abajo hasta **Privileged Gateway Intents** y habilita: + Aún en la página **Bot**, desplázate hacia abajo hasta **Privileged Gateway Intents** y habilita: - **Message Content Intent** (obligatorio) - - **Server Members Intent** (recomendado; obligatorio para listas de permitidos basadas en roles y coincidencia de nombre a ID) + - **Server Members Intent** (recomendado; obligatorio para listas de permitidos por rol y coincidencia de nombre a ID) - **Presence Intent** (opcional; solo se necesita para actualizaciones de presencia) - Vuelve a desplazarte hacia arriba en la página **Bot** y haz clic en **Reset Token**. + Vuelve a subir en la página **Bot** y haz clic en **Reset Token**. A pesar del nombre, esto genera tu primer token; no se está "restableciendo" nada. @@ -61,7 +61,7 @@ Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servido - Haz clic en **OAuth2** en la barra lateral. Generarás una URL de invitación con los permisos correctos para añadir el bot a tu servidor. + Haz clic en **OAuth2** en la barra lateral. Generarás una URL de invitación con los permisos adecuados para añadir el bot a tu servidor. Desplázate hacia abajo hasta **OAuth2 URL Generator** y habilita: @@ -81,26 +81,26 @@ Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servido - - De vuelta en la app de Discord, debes habilitar el modo desarrollador para poder copiar los IDs internos. + + De vuelta en la app de Discord, debes habilitar el modo desarrollador para poder copiar IDs internas. 1. Haz clic en **User Settings** (icono de engranaje junto a tu avatar) → **Advanced** → activa **Developer Mode** 2. Haz clic derecho en el **icono de tu servidor** en la barra lateral → **Copy Server ID** - 3. Haz clic derecho en **tu propio avatar** → **Copy User ID** + 3. Haz clic derecho en tu **propio avatar** → **Copy User ID** - Guarda tu **Server ID** y tu **User ID** junto con tu Bot Token; enviarás los tres a OpenClaw en el siguiente paso. + Guarda tu **Server ID** y **User ID** junto con tu Bot Token; enviarás los tres a OpenClaw en el siguiente paso. - Para que la vinculación funcione, Discord debe permitir que tu bot te envíe mensajes directos. Haz clic derecho en el **icono de tu servidor** → **Privacy Settings** → activa **Direct Messages**. + Para que el emparejamiento funcione, Discord debe permitir que tu bot te envíe mensajes directos. Haz clic derecho en el **icono de tu servidor** → **Privacy Settings** → activa **Direct Messages**. - Esto permite que los miembros del servidor (incluidos los bots) te envíen mensajes directos. Mantén esto habilitado si quieres usar mensajes directos de Discord con OpenClaw. Si solo planeas usar canales del servidor, puedes desactivar los mensajes directos después de la vinculación. + Esto permite que los miembros del servidor (incluidos los bots) te envíen mensajes directos. Mantén esto habilitado si quieres usar mensajes directos de Discord con OpenClaw. Si solo planeas usar canales de servidor, puedes desactivar los mensajes directos después del emparejamiento. - - El token de tu bot de Discord es un secreto (como una contraseña). Configúralo en la máquina donde se ejecuta OpenClaw antes de enviar mensajes a tu agente. + + El token de tu bot de Discord es un secreto (como una contraseña). Establécelo en la máquina que ejecuta OpenClaw antes de enviar mensajes a tu agente. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -110,17 +110,17 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - Si OpenClaw ya se está ejecutando como servicio en segundo plano, reinícialo mediante la app de OpenClaw para Mac o deteniendo y reiniciando el proceso `openclaw gateway run`. + Si OpenClaw ya se está ejecutando como servicio en segundo plano, reinícialo mediante la app OpenClaw para Mac o deteniendo y reiniciando el proceso `openclaw gateway run`. - + Chatea con tu agente de OpenClaw en cualquier canal existente (por ejemplo, Telegram) y díselo. Si Discord es tu primer canal, usa en su lugar la pestaña de CLI / config. - > "Ya configuré mi token de bot de Discord en la configuración. Por favor, termina la configuración de Discord con el User ID `` y el Server ID ``." + > "Ya configuré el token de mi bot de Discord en la configuración. Completa la configuración de Discord con User ID `` y Server ID ``." Si prefieres una configuración basada en archivos, establece: @@ -140,27 +140,27 @@ openclaw gateway } ``` - Respaldo de entorno para la cuenta predeterminada: + Respaldo por variable de entorno para la cuenta predeterminada: ```bash DISCORD_BOT_TOKEN=... ``` - Se admiten valores `token` en texto plano. También se admiten valores SecretRef para `channels.discord.token` en proveedores env/file/exec. Consulta [Gestión de secretos](/es/gateway/secrets). + Se admiten valores `token` en texto plano. También se admiten valores SecretRef para `channels.discord.token` en proveedores env/file/exec. Consulta [Secrets Management](/es/gateway/secrets). - - Espera hasta que el gateway esté en ejecución y luego envía un mensaje directo a tu bot en Discord. Responderá con un código de vinculación. + + Espera hasta que la gateway esté en ejecución y luego envía un mensaje directo a tu bot en Discord. Responderá con un código de emparejamiento. - Envía el código de vinculación a tu agente en tu canal existente: + Envía el código de emparejamiento a tu agente en tu canal existente: - > "Aprueba este código de vinculación de Discord: ``" + > "Aprueba este código de emparejamiento de Discord: ``" @@ -172,7 +172,7 @@ openclaw pairing approve discord - Los códigos de vinculación caducan después de 1 hora. + Los códigos de emparejamiento caducan después de 1 hora. Ahora deberías poder chatear con tu agente en Discord mediante mensaje directo. @@ -180,13 +180,13 @@ openclaw pairing approve discord -La resolución del token tiene en cuenta la cuenta. Los valores de token en la configuración prevalecen sobre el respaldo del entorno. `DISCORD_BOT_TOKEN` solo se usa para la cuenta predeterminada. -Para llamadas salientes avanzadas (herramienta de mensajes/acciones de canal), se usa un `token` explícito por llamada para esa llamada. Esto se aplica a acciones de envío y de lectura/sondeo (por ejemplo read/search/fetch/thread/pins/permissions). La política de cuenta y la configuración de reintentos siguen viniendo de la cuenta seleccionada en la instantánea activa del runtime. +La resolución del token tiene en cuenta la cuenta. Los valores del token en la configuración tienen prioridad sobre el respaldo por variable de entorno. `DISCORD_BOT_TOKEN` solo se usa para la cuenta predeterminada. +Para llamadas salientes avanzadas (acciones de canal/herramienta de mensajes), se usa un `token` explícito por llamada para esa llamada. Esto se aplica a acciones de envío y de lectura/sondeo (por ejemplo read/search/fetch/thread/pins/permissions). La política de cuenta y la configuración de reintentos siguen viniendo de la cuenta seleccionada en la instantánea activa del runtime. ## Recomendado: configurar un espacio de trabajo de servidor -Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Discord como un espacio de trabajo completo donde cada canal obtiene su propia sesión de agente con su propio contexto. Esto se recomienda para servidores privados donde solo están tú y tu bot. +Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Discord como un espacio de trabajo completo donde cada canal obtiene su propia sesión de agente con su propio contexto. Esto se recomienda para servidores privados donde solo estáis tú y tu bot. @@ -220,11 +220,11 @@ Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Di - De forma predeterminada, tu agente solo responde en canales del servidor cuando se le menciona con @. En un servidor privado, probablemente quieras que responda a cada mensaje. + De forma predeterminada, tu agente solo responde en canales de servidor cuando se le menciona con @. En un servidor privado, probablemente quieras que responda a todos los mensajes. - > "Permite que mi agente responda en este servidor sin tener que mencionarlo con @" + > "Permite que mi agente responda en este servidor sin necesidad de que se le mencione con @" Establece `requireMention: false` en la configuración de tu servidor: @@ -248,40 +248,40 @@ Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Di - - De forma predeterminada, la memoria a largo plazo (MEMORY.md) solo se carga en sesiones de mensajes directos. Los canales del servidor no cargan automáticamente MEMORY.md. + + De forma predeterminada, la memoria a largo plazo (MEMORY.md) solo se carga en sesiones de mensajes directos. Los canales de servidor no cargan automáticamente MEMORY.md. > "Cuando haga preguntas en canales de Discord, usa memory_search o memory_get si necesitas contexto a largo plazo de MEMORY.md." - Si necesitas contexto compartido en cada canal, coloca las instrucciones estables en `AGENTS.md` o `USER.md` (se inyectan en cada sesión). Mantén las notas a largo plazo en `MEMORY.md` y accede a ellas bajo demanda con las herramientas de memoria. + Si necesitas contexto compartido en cada canal, coloca las instrucciones estables en `AGENTS.md` o `USER.md` (se inyectan en cada sesión). Mantén las notas a largo plazo en `MEMORY.md` y accede a ellas bajo demanda con herramientas de memoria. -Ahora crea algunos canales en tu servidor de Discord y empieza a chatear. Tu agente puede ver el nombre del canal, y cada canal obtiene su propia sesión aislada, así que puedes configurar `#coding`, `#home`, `#research` o lo que mejor se adapte a tu flujo de trabajo. +Ahora crea algunos canales en tu servidor de Discord y empieza a chatear. Tu agente puede ver el nombre del canal, y cada canal obtiene su propia sesión aislada, por lo que puedes configurar `#coding`, `#home`, `#research` o lo que mejor se adapte a tu flujo de trabajo. ## Modelo de runtime -- El gateway gestiona la conexión de Discord. +- La gateway es propietaria de la conexión de Discord. - El enrutamiento de respuestas es determinista: las respuestas entrantes de Discord vuelven a Discord. - De forma predeterminada (`session.dmScope=main`), los chats directos comparten la sesión principal del agente (`agent:main:main`). -- Los canales del servidor usan claves de sesión aisladas (`agent::discord:channel:`). -- Los mensajes directos grupales se ignoran de forma predeterminada (`channels.discord.dm.groupEnabled=false`). -- Los comandos slash nativos se ejecutan en sesiones de comando aisladas (`agent::discord:slash:`), mientras siguen llevando `CommandTargetSessionKey` a la sesión de conversación enrutada. +- Los canales de servidor usan claves de sesión aisladas (`agent::discord:channel:`). +- Los mensajes directos de grupo se ignoran de forma predeterminada (`channels.discord.dm.groupEnabled=false`). +- Los comandos nativos de barra inclinada se ejecutan en sesiones de comando aisladas (`agent::discord:slash:`), mientras siguen llevando `CommandTargetSessionKey` a la sesión de conversación enrutada. ## Canales de foro Los canales de foro y multimedia de Discord solo aceptan publicaciones en hilos. OpenClaw admite dos formas de crearlos: -- Envía un mensaje al foro principal (`channel:`) para crear automáticamente un hilo. El título del hilo usa la primera línea no vacía de tu mensaje. +- Envía un mensaje al padre del foro (`channel:`) para crear automáticamente un hilo. El título del hilo usa la primera línea no vacía de tu mensaje. - Usa `openclaw message thread create` para crear un hilo directamente. No pases `--message-id` para canales de foro. -Ejemplo: enviar al foro principal para crear un hilo +Ejemplo: enviar al padre del foro para crear un hilo ```bash openclaw message send --channel discord --target channel: \ @@ -295,35 +295,35 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Los foros principales no aceptan componentes de Discord. Si necesitas componentes, envía el mensaje al hilo mismo (`channel:`). +Los padres de foro no aceptan componentes de Discord. Si necesitas componentes, envíalos al propio hilo (`channel:`). ## Componentes interactivos -OpenClaw admite contenedores de componentes v2 de Discord para mensajes del agente. Usa la herramienta de mensajes con una carga `components`. Los resultados de interacción se enrutan de vuelta al agente como mensajes entrantes normales y siguen la configuración existente de Discord `replyToMode`. +OpenClaw admite contenedores de componentes v2 de Discord para mensajes del agente. Usa la herramienta de mensajes con una carga útil `components`. Los resultados de interacción se enrutan de vuelta al agente como mensajes entrantes normales y siguen la configuración existente de `replyToMode` de Discord. Bloques compatibles: - `text`, `section`, `separator`, `actions`, `media-gallery`, `file` -- Las filas de acciones permiten hasta 5 botones o un solo menú de selección +- Las filas de acciones permiten hasta 5 botones o un único menú de selección - Tipos de selección: `string`, `user`, `role`, `mentionable`, `channel` -De forma predeterminada, los componentes son de un solo uso. Establece `components.reusable=true` para permitir que botones, selecciones y formularios se usen varias veces hasta que caduquen. +De forma predeterminada, los componentes son de un solo uso. Establece `components.reusable=true` para permitir que botones, selectores y formularios se usen varias veces hasta que caduquen. Para restringir quién puede hacer clic en un botón, establece `allowedUsers` en ese botón (IDs de usuario de Discord, etiquetas o `*`). Cuando está configurado, los usuarios que no coincidan reciben una denegación efímera. -Los comandos slash `/model` y `/models` abren un selector de modelo interactivo con menús desplegables de proveedor y modelo, además de un paso de envío. La respuesta del selector es efímera y solo el usuario que lo invocó puede usarla. +Los comandos de barra inclinada `/model` y `/models` abren un selector interactivo de modelo con menús desplegables de proveedor y modelo, además de un paso Submit. La respuesta del selector es efímera y solo el usuario que lo invocó puede usarla. Archivos adjuntos: - Los bloques `file` deben apuntar a una referencia de adjunto (`attachment://`) - Proporciona el adjunto mediante `media`/`path`/`filePath` (archivo único); usa `media-gallery` para varios archivos -- Usa `filename` para anular el nombre de carga cuando deba coincidir con la referencia del adjunto +- Usa `filename` para reemplazar el nombre de carga cuando deba coincidir con la referencia del adjunto Formularios modales: - Añade `components.modal` con hasta 5 campos - Tipos de campo: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` -- OpenClaw añade automáticamente un botón activador +- OpenClaw añade un botón disparador automáticamente Ejemplo: @@ -383,32 +383,32 @@ Ejemplo: - `channels.discord.dmPolicy` controla el acceso por mensaje directo (heredado: `channels.discord.dm.policy`): + `channels.discord.dmPolicy` controla el acceso a mensajes directos (heredado: `channels.discord.dm.policy`): - `pairing` (predeterminado) - `allowlist` - `open` (requiere que `channels.discord.allowFrom` incluya `"*"`; heredado: `channels.discord.dm.allowFrom`) - `disabled` - Si la política de mensajes directos no es abierta, los usuarios desconocidos se bloquean (o se les pide vinculación en modo `pairing`). + Si la política de mensajes directos no está abierta, los usuarios desconocidos se bloquean (o se les solicita emparejamiento en modo `pairing`). - Precedencia de múltiples cuentas: + Precedencia en múltiples cuentas: - `channels.discord.accounts.default.allowFrom` se aplica solo a la cuenta `default`. - - Las cuentas con nombre heredan `channels.discord.allowFrom` cuando su propio `allowFrom` no está establecido. + - Las cuentas con nombre heredan `channels.discord.allowFrom` cuando su propio `allowFrom` no está definido. - Las cuentas con nombre no heredan `channels.discord.accounts.default.allowFrom`. - Formato de destino de mensaje directo para la entrega: + Formato de destino de mensajes directos para la entrega: - `user:` - mención `<@id>` - Los IDs numéricos sin prefijo son ambiguos y se rechazan a menos que se proporcione un tipo de destino explícito de usuario/canal. + Los ID numéricos sin prefijo son ambiguos y se rechazan a menos que se proporcione un tipo de destino explícito de usuario/canal. - - El manejo de servidores se controla con `channels.discord.groupPolicy`: + + El manejo de servidores está controlado por `channels.discord.groupPolicy`: - `open` - `allowlist` @@ -418,12 +418,12 @@ Ejemplo: Comportamiento de `allowlist`: - - el servidor debe coincidir con `channels.discord.guilds` (`id` preferido, se acepta slug) - - listas de remitentes opcionales: `users` (se recomiendan IDs estables) y `roles` (solo IDs de rol); si se configura cualquiera de las dos, los remitentes se permiten cuando coinciden con `users` O `roles` - - la coincidencia directa por nombre/etiqueta está desactivada de forma predeterminada; habilita `channels.discord.dangerouslyAllowNameMatching: true` solo como modo de compatibilidad de último recurso - - se admiten nombres/etiquetas para `users`, pero los IDs son más seguros; `openclaw security audit` avisa cuando se usan entradas de nombre/etiqueta + - el servidor debe coincidir con `channels.discord.guilds` (`id` preferido, slug aceptado) + - listas de permitidos opcionales para remitentes: `users` (se recomiendan IDs estables) y `roles` (solo IDs de rol); si cualquiera está configurado, los remitentes están permitidos cuando coinciden con `users` O `roles` + - la coincidencia directa por nombre/etiqueta está desactivada de forma predeterminada; habilita `channels.discord.dangerouslyAllowNameMatching: true` solo como modo de compatibilidad de emergencia + - se admiten nombres/etiquetas para `users`, pero los IDs son más seguros; `openclaw security audit` advierte cuando se usan entradas de nombre/etiqueta - si un servidor tiene `channels` configurado, los canales no listados se deniegan - - si un servidor no tiene bloque `channels`, se permiten todos los canales de ese servidor incluido en la lista de permitidos + - si un servidor no tiene bloque `channels`, todos los canales de ese servidor en la lista de permitidos están permitidos Ejemplo: @@ -449,23 +449,23 @@ Ejemplo: } ``` - Si solo estableces `DISCORD_BOT_TOKEN` y no creas un bloque `channels.discord`, el respaldo del runtime será `groupPolicy="allowlist"` (con una advertencia en los registros), incluso si `channels.defaults.groupPolicy` es `open`. + Si solo configuras `DISCORD_BOT_TOKEN` y no creas un bloque `channels.discord`, el respaldo del runtime es `groupPolicy="allowlist"` (con una advertencia en los registros), incluso si `channels.defaults.groupPolicy` es `open`. - - Los mensajes del servidor requieren mención de forma predeterminada. + + Los mensajes de servidor están restringidos por mención de forma predeterminada. La detección de mención incluye: - - mención explícita al bot + - mención explícita del bot - patrones de mención configurados (`agents.list[].groupChat.mentionPatterns`, respaldo `messages.groupChat.mentionPatterns`) - - comportamiento implícito de respuesta al bot en casos compatibles + - comportamiento implícito de respuesta al bot en los casos compatibles `requireMention` se configura por servidor/canal (`channels.discord.guilds...`). - `ignoreOtherMentions` opcionalmente descarta mensajes que mencionen a otro usuario/rol pero no al bot (excluyendo @everyone/@here). + `ignoreOtherMentions` descarta opcionalmente mensajes que mencionan a otro usuario/rol pero no al bot (excepto @everyone/@here). - Mensajes directos grupales: + Mensajes directos de grupo: - predeterminado: ignorados (`dm.groupEnabled=false`) - lista de permitidos opcional mediante `dm.groupChannels` (IDs o slugs de canal) @@ -475,7 +475,7 @@ Ejemplo: ### Enrutamiento de agentes basado en roles -Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a distintos agentes según el ID del rol. Los bindings basados en roles aceptan solo IDs de rol y se evalúan después de los bindings de peer o parent-peer y antes de los bindings solo de servidor. Si un binding también establece otros campos de coincidencia (por ejemplo `peer` + `guildId` + `roles`), todos los campos configurados deben coincidir. +Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a distintos agentes por ID de rol. Las vinculaciones basadas en rol aceptan solo IDs de rol y se evalúan después de las vinculaciones de par o par padre y antes de las vinculaciones solo de servidor. Si una vinculación también establece otros campos de coincidencia (por ejemplo `peer` + `guildId` + `roles`), todos los campos configurados deben coincidir. ```json5 { @@ -499,10 +499,10 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di } ``` -## Configuración del Developer Portal +## Configuración del portal para desarrolladores - + 1. Discord Developer Portal -> **Applications** -> **New Application** 2. **Bot** -> **Add Bot** @@ -516,7 +516,7 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di - Message Content Intent - Server Members Intent (recomendado) - Presence intent es opcional y solo es obligatorio si quieres recibir actualizaciones de presencia. Establecer la presencia del bot (`setPresence`) no requiere habilitar actualizaciones de presencia para miembros. + Presence intent es opcional y solo es obligatorio si quieres recibir actualizaciones de presencia. Configurar la presencia del bot (`setPresence`) no requiere habilitar actualizaciones de presencia para los miembros. @@ -534,12 +534,12 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di - Attach Files - Add Reactions (opcional) - Evita `Administrator` a menos que sea explícitamente necesario. + Evita `Administrator` salvo que sea explícitamente necesario. - Habilita el modo desarrollador de Discord y luego copia: + Habilita Discord Developer Mode y luego copia: - ID del servidor - ID del canal @@ -553,14 +553,14 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di ## Comandos nativos y autenticación de comandos - `commands.native` usa `"auto"` de forma predeterminada y está habilitado para Discord. -- Anulación por canal: `channels.discord.commands.native`. -- `commands.native=false` borra explícitamente los comandos nativos de Discord registrados anteriormente. +- Reemplazo por canal: `channels.discord.commands.native`. +- `commands.native=false` borra explícitamente comandos nativos de Discord registrados anteriormente. - La autenticación de comandos nativos usa las mismas listas de permitidos/políticas de Discord que el manejo normal de mensajes. -- Los comandos pueden seguir siendo visibles en la interfaz de Discord para usuarios no autorizados; la ejecución sigue aplicando la autorización de OpenClaw y devuelve "not authorized". +- Los comandos pueden seguir siendo visibles en la interfaz de Discord para usuarios que no están autorizados; la ejecución sigue aplicando la autenticación de OpenClaw y devuelve "no autorizado". -Consulta [Comandos slash](/es/tools/slash-commands) para ver el catálogo y comportamiento de comandos. +Consulta [Slash commands](/es/tools/slash-commands) para el catálogo y el comportamiento de los comandos. -Configuración predeterminada de comandos slash: +Configuración predeterminada de comandos de barra inclinada: - `ephemeral: true` @@ -581,20 +581,22 @@ Configuración predeterminada de comandos slash: - `batched` Nota: `off` desactiva el encadenamiento implícito de respuestas. Las etiquetas explícitas `[[reply_to_*]]` siguen respetándose. - `first` siempre adjunta la referencia de respuesta nativa implícita a la primera salida de mensaje de Discord del turno. - `batched` solo adjunta la referencia de respuesta nativa implícita de Discord cuando el turno entrante fue un lote con debounce de varios mensajes. Esto es útil - cuando quieres respuestas nativas principalmente para chats ambiguos y con ráfagas, no para cada turno de mensaje único. + `first` siempre adjunta la referencia implícita de respuesta nativa al primer mensaje saliente de Discord del turno. + `batched` solo adjunta la referencia implícita de respuesta nativa de Discord cuando el + turno entrante fue un lote con antirrebote de varios mensajes. Esto es útil + cuando quieres respuestas nativas principalmente para chats ambiguos con ráfagas, no para cada + turno de un solo mensaje. - Los IDs de mensaje se muestran en el contexto/historial para que los agentes puedan dirigirse a mensajes específicos. + Los IDs de mensaje se muestran en el contexto/historial para que los agentes puedan dirigirse a mensajes concretos. - - OpenClaw puede transmitir respuestas preliminares enviando un mensaje temporal y editándolo a medida que llega el texto. + + OpenClaw puede transmitir borradores de respuesta enviando un mensaje temporal y editándolo a medida que llega texto. - - `channels.discord.streaming` controla el streaming de vista previa (`off` | `partial` | `block` | `progress`, predeterminado: `off`). - - El valor predeterminado sigue siendo `off` porque las ediciones de vista previa de Discord pueden alcanzar rápidamente los límites de tasa, especialmente cuando varios bots o gateways comparten la misma cuenta o el tráfico del servidor. - - `progress` se acepta para mantener coherencia entre canales y se asigna a `partial` en Discord. + - `channels.discord.streaming` controla la transmisión de vista previa (`off` | `partial` | `block` | `progress`, predeterminado: `off`). + - El valor predeterminado sigue siendo `off` porque las ediciones de vista previa de Discord pueden alcanzar rápidamente los límites de tasa, especialmente cuando varios bots o gateways comparten la misma cuenta o tráfico de servidor. + - `progress` se acepta por consistencia entre canales y se asigna a `partial` en Discord. - `channels.discord.streamMode` es un alias heredado y se migra automáticamente. - `partial` edita un único mensaje de vista previa a medida que llegan los tokens. - `block` emite fragmentos del tamaño del borrador (usa `draftChunk` para ajustar tamaño y puntos de corte). @@ -611,7 +613,7 @@ Configuración predeterminada de comandos slash: } ``` - Valores predeterminados de fragmentación en modo `block` (limitados por `channels.discord.textChunkLimit`): + Valores predeterminados de fragmentación del modo `block` (limitados a `channels.discord.textChunkLimit`): ```json5 { @@ -628,21 +630,21 @@ Configuración predeterminada de comandos slash: } ``` - La vista previa de streaming es solo de texto; las respuestas multimedia vuelven al envío normal. + La transmisión de vista previa es solo de texto; las respuestas con archivos multimedia vuelven a la entrega normal. - Nota: la vista previa de streaming es independiente del streaming por bloques. Cuando el streaming por bloques está habilitado explícitamente - para Discord, OpenClaw omite la vista previa de streaming para evitar streaming doble. + Nota: la transmisión de vista previa es independiente de la transmisión por bloques. Cuando la transmisión por bloques está explícitamente + habilitada para Discord, OpenClaw omite la vista previa para evitar transmisión doble. - Contexto de historial del servidor: + Contexto del historial de servidores: - `channels.discord.historyLimit` predeterminado `20` - respaldo: `messages.groupChat.historyLimit` - - `0` lo desactiva + - `0` desactiva - Controles de historial de mensajes directos: + Controles del historial de mensajes directos: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` @@ -650,25 +652,25 @@ Configuración predeterminada de comandos slash: Comportamiento de hilos: - los hilos de Discord se enrutan como sesiones de canal - - los metadatos del hilo principal pueden usarse para vincular con la sesión principal - - la configuración del hilo hereda la configuración del canal principal a menos que exista una entrada específica para el hilo + - los metadatos del hilo padre pueden usarse para el enlace de sesión padre + - la configuración del hilo hereda la configuración del canal padre, salvo que exista una entrada específica para el hilo - Los temas del canal se inyectan como contexto **no confiable** (no como prompt del sistema). - El contexto de respuesta y de mensaje citado actualmente se mantiene tal como se recibió. - Las listas de permitidos de Discord bloquean principalmente quién puede activar al agente, no constituyen un límite completo de redacción de contexto suplementario. + Los temas de canal se inyectan como contexto **no confiable** (no como prompt del sistema). + El contexto de respuestas y mensajes citados actualmente permanece tal como se recibe. + Las listas de permitidos de Discord controlan principalmente quién puede activar el agente, no son un límite completo de redacción de contexto suplementario. - Discord puede vincular un hilo a un destino de sesión para que los mensajes posteriores de ese hilo sigan enrutándose a la misma sesión (incluidas sesiones de subagentes). + Discord puede vincular un hilo a un destino de sesión para que los mensajes posteriores en ese hilo sigan enrutándose a la misma sesión (incluidas sesiones de subagentes). Comandos: - `/focus ` vincula el hilo actual/nuevo a un destino de subagente/sesión - - `/unfocus` elimina la vinculación actual del hilo - - `/agents` muestra ejecuciones activas y estado de vinculación - - `/session idle ` inspecciona/actualiza la desvinculación automática por inactividad para bindings enfocados - - `/session max-age ` inspecciona/actualiza la antigüedad máxima estricta para bindings enfocados + - `/unfocus` elimina la vinculación del hilo actual + - `/agents` muestra ejecuciones activas y estado de la vinculación + - `/session idle ` inspecciona/actualiza el desenfoque automático por inactividad para vinculaciones enfocadas + - `/session max-age ` inspecciona/actualiza la antigüedad máxima estricta para vinculaciones enfocadas Configuración: @@ -687,7 +689,7 @@ Configuración predeterminada de comandos slash: enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in + spawnSubagentSessions: false, // activación opcional }, }, }, @@ -697,17 +699,17 @@ Configuración predeterminada de comandos slash: Notas: - `session.threadBindings.*` establece los valores predeterminados globales. - - `channels.discord.threadBindings.*` anula el comportamiento de Discord. - - `spawnSubagentSessions` debe ser true para crear/vincular hilos automáticamente para `sessions_spawn({ thread: true })`. - - `spawnAcpSessions` debe ser true para crear/vincular hilos automáticamente para ACP (`/acp spawn ... --thread ...` o `sessions_spawn({ runtime: "acp", thread: true })`). - - Si los thread bindings están deshabilitados para una cuenta, `/focus` y las operaciones relacionadas con thread binding no están disponibles. + - `channels.discord.threadBindings.*` reemplaza el comportamiento de Discord. + - `spawnSubagentSessions` debe ser true para crear/vincular automáticamente hilos para `sessions_spawn({ thread: true })`. + - `spawnAcpSessions` debe ser true para crear/vincular automáticamente hilos para ACP (`/acp spawn ... --thread ...` o `sessions_spawn({ runtime: "acp", thread: true })`). + - Si las vinculaciones de hilos están deshabilitadas para una cuenta, `/focus` y las operaciones relacionadas no están disponibles. - Consulta [Subagentes](/es/tools/subagents), [Agentes ACP](/es/tools/acp-agents) y [Referencia de configuración](/es/gateway/configuration-reference). + Consulta [Sub-agents](/es/tools/subagents), [ACP Agents](/es/tools/acp-agents) y [Configuration Reference](/es/gateway/configuration-reference). - - Para espacios de trabajo ACP estables "siempre activos", configura bindings ACP tipados de nivel superior dirigidos a conversaciones de Discord. + + Para espacios de trabajo ACP estables "siempre activos", configura vinculaciones ACP tipadas de nivel superior dirigidas a conversaciones de Discord. Ruta de configuración: @@ -763,15 +765,15 @@ Configuración predeterminada de comandos slash: Notas: - - `/acp spawn codex --bind here` vincula el canal o hilo actual de Discord en su lugar y mantiene los mensajes futuros enrutados a la misma sesión ACP. - - Eso aún puede significar "iniciar una sesión ACP nueva de Codex", pero no crea por sí solo un nuevo hilo de Discord. El canal existente sigue siendo la superficie del chat. - - Codex aún puede ejecutarse en su propio `cwd` o espacio de trabajo de backend en disco. Ese espacio de trabajo es estado del runtime, no un hilo de Discord. - - Los mensajes de hilo pueden heredar el binding ACP del canal principal. - - En un canal o hilo vinculado, `/new` y `/reset` reinician la misma sesión ACP en el mismo lugar. - - Los thread bindings temporales siguen funcionando y pueden anular la resolución del destino mientras estén activos. - - `spawnAcpSessions` solo es obligatorio cuando OpenClaw necesita crear/vincular un hilo secundario mediante `--thread auto|here`. No es obligatorio para `/acp spawn ... --bind here` en el canal actual. + - `/acp spawn codex --bind here` vincula el canal o hilo actual de Discord en el lugar y mantiene los mensajes futuros enrutados a la misma sesión ACP. + - Esto todavía puede significar "iniciar una sesión ACP nueva de Codex", pero no crea por sí solo un hilo nuevo de Discord. El canal existente sigue siendo la superficie de chat. + - Codex puede seguir ejecutándose en su propio `cwd` o espacio de trabajo de backend en disco. Ese espacio de trabajo es estado de runtime, no un hilo de Discord. + - Los mensajes del hilo pueden heredar la vinculación ACP del canal padre. + - En un canal o hilo vinculado, `/new` y `/reset` restablecen la misma sesión ACP en el lugar. + - Las vinculaciones temporales de hilos siguen funcionando y pueden reemplazar la resolución de destino mientras estén activas. + - `spawnAcpSessions` solo es obligatorio cuando OpenClaw necesita crear/vincular un hilo hijo mediante `--thread auto|here`. No es obligatorio para `/acp spawn ... --bind here` en el canal actual. - Consulta [Agentes ACP](/es/tools/acp-agents) para ver detalles del comportamiento de los bindings. + Consulta [ACP Agents](/es/tools/acp-agents) para obtener detalles sobre el comportamiento de las vinculaciones. @@ -795,11 +797,11 @@ Configuración predeterminada de comandos slash: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - respaldo del emoji de identidad del agente (`agents.list[].identity.emoji`, si no "👀") + - respaldo al emoji de identidad del agente (`agents.list[].identity.emoji`, o "👀" si no existe) Notas: - - Discord acepta emoji Unicode o nombres de emoji personalizados. + - Discord acepta emoji unicode o nombres de emoji personalizados. - Usa `""` para desactivar la reacción para un canal o cuenta. @@ -807,7 +809,7 @@ Configuración predeterminada de comandos slash: Las escrituras de configuración iniciadas desde el canal están habilitadas de forma predeterminada. - Esto afecta a los flujos `/config set|unset` (cuando las funciones de comando están habilitadas). + Esto afecta a los flujos `/config set|unset` (cuando las funciones de comandos están habilitadas). Desactivar: @@ -823,8 +825,8 @@ Configuración predeterminada de comandos slash: - - Enruta el tráfico WebSocket del gateway de Discord y las búsquedas REST de inicio (ID de aplicación + resolución de lista de permitidos) a través de un proxy HTTP(S) con `channels.discord.proxy`. + + Enruta el tráfico WebSocket de la gateway de Discord y las búsquedas REST de inicio (ID de aplicación + resolución de lista de permitidos) mediante un proxy HTTP(S) con `channels.discord.proxy`. ```json5 { @@ -836,7 +838,7 @@ Configuración predeterminada de comandos slash: } ``` - Anulación por cuenta: + Reemplazo por cuenta: ```json5 { @@ -854,8 +856,8 @@ Configuración predeterminada de comandos slash: - - Habilita la resolución de PluralKit para asignar mensajes proxy a la identidad del miembro del sistema: + + Habilita la resolución de PluralKit para asignar mensajes proxificados a la identidad del miembro del sistema: ```json5 { @@ -873,14 +875,14 @@ Configuración predeterminada de comandos slash: Notas: - las listas de permitidos pueden usar `pk:` - - los nombres de visualización de miembros se comparan por nombre/slug solo cuando `channels.discord.dangerouslyAllowNameMatching: true` - - las búsquedas usan el ID del mensaje original y están limitadas por ventana temporal - - si la búsqueda falla, los mensajes proxy se tratan como mensajes de bot y se descartan a menos que `allowBots=true` + - los nombres visibles de miembro coinciden por nombre/slug solo cuando `channels.discord.dangerouslyAllowNameMatching: true` + - las búsquedas usan el ID del mensaje original y están limitadas por una ventana temporal + - si la búsqueda falla, los mensajes proxificados se tratan como mensajes de bot y se descartan salvo que `allowBots=true` - Las actualizaciones de presencia se aplican cuando estableces un campo de estado o actividad, o cuando habilitas la presencia automática. + Las actualizaciones de presencia se aplican cuando estableces un campo de estado o actividad, o cuando habilitas presencia automática. Ejemplo solo de estado: @@ -894,7 +896,7 @@ Configuración predeterminada de comandos slash: } ``` - Ejemplo de actividad (el tipo de actividad predeterminado es estado personalizado): + Ejemplo de actividad (el estado personalizado es el tipo de actividad predeterminado): ```json5 { @@ -907,7 +909,7 @@ Configuración predeterminada de comandos slash: } ``` - Ejemplo de streaming: + Ejemplo de transmisión: ```json5 { @@ -930,7 +932,7 @@ Configuración predeterminada de comandos slash: - 4: Custom (usa el texto de actividad como estado; el emoji es opcional) - 5: Competing - Ejemplo de presencia automática (señal de estado del runtime): + Ejemplo de presencia automática (señal de estado de salud del runtime): ```json5 { @@ -947,7 +949,7 @@ Configuración predeterminada de comandos slash: } ``` - La presencia automática asigna la disponibilidad del runtime al estado de Discord: saludable => online, degradado o desconocido => idle, agotado o no disponible => dnd. Anulaciones opcionales de texto: + La presencia automática asigna la disponibilidad del runtime al estado de Discord: healthy => online, degraded o unknown => idle, exhausted o unavailable => dnd. Reemplazos de texto opcionales: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -956,43 +958,43 @@ Configuración predeterminada de comandos slash: - Discord admite el manejo de aprobaciones mediante botones en mensajes directos y, opcionalmente, puede publicar solicitudes de aprobación en el canal de origen. + Discord admite manejo de aprobaciones con botones en mensajes directos y puede, de forma opcional, publicar solicitudes de aprobación en el canal de origen. Ruta de configuración: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (opcional; usa como respaldo `commands.ownerAllowFrom` cuando sea posible) + - `channels.discord.execApprovals.approvers` (opcional; usa `commands.ownerAllowFrom` como respaldo cuando es posible) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, predeterminado: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord habilita automáticamente las aprobaciones nativas de ejecución cuando `enabled` no está establecido o es `"auto"` y al menos se puede resolver un aprobador, ya sea desde `execApprovals.approvers` o desde `commands.ownerAllowFrom`. Discord no infiere aprobadores de ejecución desde `allowFrom` del canal, `dm.allowFrom` heredado ni `defaultTo` de mensaje directo. Establece `enabled: false` para desactivar explícitamente Discord como cliente nativo de aprobación. + Discord habilita automáticamente las aprobaciones nativas de ejecución cuando `enabled` no está definido o es `"auto"` y al menos un aprobador puede resolverse, ya sea desde `execApprovals.approvers` o desde `commands.ownerAllowFrom`. Discord no infiere aprobadores de ejecución desde `allowFrom` del canal, `dm.allowFrom` heredado ni `defaultTo` de mensajes directos. Establece `enabled: false` para desactivar Discord explícitamente como cliente de aprobación nativo. - Cuando `target` es `channel` o `both`, la solicitud de aprobación es visible en el canal. Solo los aprobadores resueltos pueden usar los botones; los demás usuarios reciben una denegación efímera. Las solicitudes de aprobación incluyen el texto del comando, así que habilita la entrega en canal solo en canales de confianza. Si el ID del canal no puede derivarse de la clave de sesión, OpenClaw vuelve a la entrega por mensaje directo. + Cuando `target` es `channel` o `both`, la solicitud de aprobación es visible en el canal. Solo los aprobadores resueltos pueden usar los botones; otros usuarios reciben una denegación efímera. Las solicitudes de aprobación incluyen el texto del comando, así que habilita la entrega en canal solo en canales de confianza. Si el ID del canal no puede derivarse de la clave de sesión, OpenClaw vuelve a la entrega por mensaje directo. - Discord también renderiza los botones compartidos de aprobación usados por otros canales de chat. El adaptador nativo de Discord añade principalmente el enrutamiento de mensajes directos a aprobadores y la distribución en canal. - Cuando esos botones están presentes, son la UX principal de aprobación; OpenClaw + Discord también renderiza los botones de aprobación compartidos usados por otros canales de chat. El adaptador nativo de Discord añade principalmente enrutamiento por mensaje directo para aprobadores y difusión al canal. + Cuando esos botones están presentes, son la experiencia principal de aprobación; OpenClaw solo debería 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. - La autenticación del gateway para este controlador usa el mismo contrato compartido de resolución de credenciales que otros clientes del gateway: + La autenticación de gateway para este manejador usa el mismo contrato compartido de resolución de credenciales que otros clientes de Gateway: - - autenticación local con prioridad de entorno (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` y luego `gateway.auth.*`) - - en modo local, `gateway.remote.*` puede usarse como respaldo solo cuando `gateway.auth.*` no está establecido; los SecretRef locales configurados pero no resueltos fallan en modo cerrado - - compatibilidad con modo remoto mediante `gateway.remote.*` cuando corresponda - - las anulaciones de URL son seguras para anulación: las anulaciones de CLI no reutilizan credenciales implícitas, y las anulaciones de entorno usan solo credenciales del entorno + - autenticación local con prioridad a entorno (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` y luego `gateway.auth.*`) + - en modo local, `gateway.remote.*` puede usarse como respaldo solo cuando `gateway.auth.*` no está configurado; los SecretRef locales configurados pero no resueltos fallan en modo cerrado + - soporte de modo remoto mediante `gateway.remote.*` cuando corresponda + - los reemplazos de URL son seguros para reemplazo: los reemplazos de CLI no reutilizan credenciales implícitas, y los reemplazos de entorno usan solo credenciales del entorno Comportamiento de resolución de aprobación: - Los IDs con prefijo `plugin:` se resuelven mediante `plugin.approval.resolve`. - - Los demás IDs se resuelven mediante `exec.approval.resolve`. - - Discord no realiza aquí un salto adicional de respaldo de exec a plugin; el prefijo - del ID decide qué método del gateway llama. + - Otros IDs se resuelven mediante `exec.approval.resolve`. + - Discord no realiza aquí un salto adicional de respaldo de exec a plugin; el + prefijo del ID decide qué método de gateway llama. Las aprobaciones de ejecución caducan después de 30 minutos de forma predeterminada. Si las aprobaciones fallan con - IDs de aprobación desconocidos, verifica la resolución de aprobadores, la habilitación de la función y + IDs de aprobación desconocidos, verifica la resolución de aprobadores, la habilitación de funciones y que el tipo de ID de aprobación entregado coincida con la solicitud pendiente. - Documentación relacionada: [Aprobaciones de ejecución](/es/tools/exec-approvals) + Documentación relacionada: [Exec approvals](/es/tools/exec-approvals) @@ -1008,24 +1010,26 @@ Ejemplos principales: - moderación: `timeout`, `kick`, `ban` - presencia: `setPresence` -Los controles de acciones se encuentran en `channels.discord.actions.*`. +La acción `event-create` acepta un parámetro `image` opcional (URL o ruta de archivo local) para establecer la imagen de portada del evento programado. -Comportamiento predeterminado de controles: +Los controles de acciones están en `channels.discord.actions.*`. -| Grupo de acciones | Predeterminado | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | +Comportamiento predeterminado de los controles: + +| Grupo de acciones | Predeterminado | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | | reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | habilitado | -| roles | deshabilitado | -| moderation | deshabilitado | -| presence | deshabilitado | +| roles | deshabilitado | +| moderation | deshabilitado | +| presence | deshabilitado | -## UI de componentes v2 +## Interfaz Components v2 -OpenClaw usa componentes v2 de Discord para aprobaciones de ejecución y marcadores entre contextos. Las acciones de mensajes de Discord también pueden aceptar `components` para UI personalizada (avanzado; requiere construir una carga de componente mediante la herramienta de Discord), mientras que los `embeds` heredados siguen disponibles pero no se recomiendan. +OpenClaw usa Discord components v2 para aprobaciones de ejecución y marcadores entre contextos. Las acciones de mensajes de Discord también pueden aceptar `components` para una interfaz personalizada (avanzado; requiere construir una carga útil de componentes mediante la herramienta de Discord), mientras que los `embeds` heredados siguen estando disponibles, pero no se recomiendan. - `channels.discord.ui.components.accentColor` establece el color de acento usado por los contenedores de componentes de Discord (hex). - Establécelo por cuenta con `channels.discord.accounts..ui.components.accentColor`. -- `embeds` se ignoran cuando hay componentes v2 presentes. +- `embeds` se ignoran cuando hay components v2 presentes. Ejemplo: @@ -1045,15 +1049,15 @@ Ejemplo: ## Canales de voz -OpenClaw puede unirse a canales de voz de Discord para conversaciones continuas en tiempo real. Esto es independiente de los archivos adjuntos de mensajes de voz. +OpenClaw puede unirse a canales de voz de Discord para conversaciones continuas en tiempo real. Esto es independiente de los adjuntos de mensajes de voz. Requisitos: - Habilita comandos nativos (`commands.native` o `channels.discord.commands.native`). - Configura `channels.discord.voice`. -- El bot necesita permisos de Connect + Speak en el canal de voz de destino. +- El bot necesita permisos Connect + Speak en el canal de voz de destino. -Usa el comando nativo exclusivo de Discord `/vc join|leave|status` para controlar las sesiones. El comando usa el agente predeterminado de la cuenta y sigue las mismas reglas de lista de permitidos y política de grupo que otros comandos de Discord. +Usa el comando nativo exclusivo de Discord `/vc join|leave|status` para controlar sesiones. El comando usa el agente predeterminado de la cuenta y sigue las mismas reglas de lista de permitidos y política de grupo que otros comandos de Discord. Ejemplo de unión automática: @@ -1083,23 +1087,23 @@ Ejemplo de unión automática: Notas: -- `voice.tts` anula `messages.tts` solo para la reproducción de voz. -- Los turnos de transcripción de voz derivan el estado de propietario de `allowFrom` de Discord (o `dm.allowFrom`); los hablantes que no son propietarios no pueden acceder a herramientas exclusivas del propietario (por ejemplo `gateway` y `cron`). -- La voz está habilitada de forma predeterminada; establece `channels.discord.voice.enabled=false` para deshabilitarla. -- `voice.daveEncryption` y `voice.decryptionFailureTolerance` se transfieren a las opciones de unión de `@discordjs/voice`. +- `voice.tts` reemplaza `messages.tts` solo para la reproducción de voz. +- Los turnos de transcripción de voz derivan el estado de propietario desde `allowFrom` de Discord (o `dm.allowFrom`); los hablantes que no son propietarios no pueden acceder a herramientas exclusivas del propietario (por ejemplo `gateway` y `cron`). +- La voz está habilitada de forma predeterminada; establece `channels.discord.voice.enabled=false` para desactivarla. +- `voice.daveEncryption` y `voice.decryptionFailureTolerance` se pasan directamente a las opciones de unión de `@discordjs/voice`. - Los valores predeterminados de `@discordjs/voice` son `daveEncryption=true` y `decryptionFailureTolerance=24` si no se establecen. -- OpenClaw también observa fallos de descifrado en recepción y se recupera automáticamente saliendo y volviendo a unirse al canal de voz después de fallos repetidos en una ventana corta. -- Si los registros de recepción muestran repetidamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, esto puede ser el error ascendente de recepción de `@discordjs/voice` registrado en [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). +- OpenClaw también supervisa los fallos de descifrado de recepción y se recupera automáticamente saliendo y volviendo a unirse al canal de voz después de fallos repetidos en una ventana corta. +- Si los registros de recepción muestran repetidamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, esto puede ser el error upstream de recepción de `@discordjs/voice` rastreado en [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). ## Mensajes de voz -Los mensajes de voz de Discord muestran una vista previa de forma de onda y requieren audio OGG/Opus más metadatos. OpenClaw genera la forma de onda automáticamente, pero necesita `ffmpeg` y `ffprobe` disponibles en el host del gateway para inspeccionar y convertir archivos de audio. +Los mensajes de voz de Discord muestran una vista previa de forma de onda y requieren audio OGG/Opus más metadatos. OpenClaw genera la forma de onda automáticamente, pero necesita que `ffmpeg` y `ffprobe` estén disponibles en el host de la gateway para inspeccionar y convertir archivos de audio. Requisitos y restricciones: -- Proporciona una **ruta de archivo local** (las URL se rechazan). -- Omite el contenido de texto (Discord no permite texto + mensaje de voz en la misma carga). -- Se acepta cualquier formato de audio; OpenClaw lo convierte a OGG/Opus cuando sea necesario. +- Proporciona una **ruta de archivo local** (las URLs se rechazan). +- Omite el contenido de texto (Discord no permite texto + mensaje de voz en la misma carga útil). +- Se acepta cualquier formato de audio; OpenClaw convierte a OGG/Opus cuando es necesario. Ejemplo: @@ -1110,18 +1114,18 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Solución de problemas - + - habilita Message Content Intent - habilita Server Members Intent cuando dependas de la resolución de usuario/miembro - - reinicia el gateway después de cambiar los intents + - reinicia la gateway después de cambiar intents - + - verifica `groupPolicy` - - verifica la lista de permitidos de servidores en `channels.discord.guilds` + - verifica la lista de permitidos del servidor en `channels.discord.guilds` - si existe el mapa `guild.channels`, solo se permiten los canales listados - verifica el comportamiento de `requireMention` y los patrones de mención @@ -1138,13 +1142,13 @@ openclaw logs --follow Causas comunes: - - `groupPolicy="allowlist"` sin una lista de permitidos coincidente de servidor/canal - - `requireMention` configurado en el lugar incorrecto (debe estar en `channels.discord.guilds` o en la entrada del canal) + - `groupPolicy="allowlist"` sin una lista de permitidos de servidor/canal que coincida + - `requireMention` configurado en el lugar equivocado (debe estar en `channels.discord.guilds` o en la entrada del canal) - remitente bloqueado por la lista de permitidos `users` del servidor/canal - + Registros típicos: @@ -1152,16 +1156,16 @@ openclaw logs --follow - `Slow listener detected ...` - `discord inbound worker timed out after ...` - Control de presupuesto del listener: + Ajuste del presupuesto del listener: - cuenta única: `channels.discord.eventQueue.listenerTimeout` - - varias cuentas: `channels.discord.accounts..eventQueue.listenerTimeout` + - múltiples cuentas: `channels.discord.accounts..eventQueue.listenerTimeout` - Control de tiempo de espera de ejecución del worker: + Ajuste del tiempo límite de ejecución del worker: - cuenta única: `channels.discord.inboundWorker.runTimeoutMs` - - varias cuentas: `channels.discord.accounts..inboundWorker.runTimeoutMs` - - predeterminado: `1800000` (30 minutos); establece `0` para deshabilitarlo + - múltiples cuentas: `channels.discord.accounts..inboundWorker.runTimeoutMs` + - predeterminado: `1800000` (30 minutos); establece `0` para desactivar Línea base recomendada: @@ -1185,22 +1189,22 @@ openclaw logs --follow ``` Usa `eventQueue.listenerTimeout` para una configuración lenta del listener y `inboundWorker.runTimeoutMs` - solo si quieres una válvula de seguridad independiente para turnos de agente en cola. + solo si quieres una válvula de seguridad independiente para turnos del agente en cola. - Las comprobaciones de permisos de `channels status --probe` solo funcionan para IDs numéricos de canal. + Las comprobaciones de permisos de `channels status --probe` solo funcionan con IDs numéricos de canal. - Si usas claves slug, la coincidencia en runtime puede seguir funcionando, pero el sondeo no puede verificar completamente los permisos. + Si usas claves slug, la coincidencia en runtime aún puede funcionar, pero el sondeo no puede verificar completamente los permisos. - + - - mensaje directo deshabilitado: `channels.discord.dm.enabled=false` + - mensajes directos deshabilitados: `channels.discord.dm.enabled=false` - política de mensajes directos deshabilitada: `channels.discord.dmPolicy="disabled"` (heredado: `channels.discord.dm.policy`) - - esperando aprobación de vinculación en modo `pairing` + - esperando aprobación de emparejamiento en modo `pairing` @@ -1208,19 +1212,19 @@ openclaw logs --follow De forma predeterminada, los mensajes creados por bots se ignoran. Si estableces `channels.discord.allowBots=true`, usa reglas estrictas de mención y lista de permitidos para evitar comportamientos en bucle. - Prefiere `channels.discord.allowBots="mentions"` para aceptar solo mensajes de bots que mencionen al bot. + Prefiere `channels.discord.allowBots="mentions"` para aceptar solo mensajes de bot que mencionen al bot. - + - mantén OpenClaw actualizado (`openclaw update`) para que esté presente la lógica de recuperación de recepción de voz de Discord - confirma `channels.discord.voice.daveEncryption=true` (predeterminado) - - empieza desde `channels.discord.voice.decryptionFailureTolerance=24` (valor predeterminado ascendente) y ajusta solo si hace falta + - empieza con `channels.discord.voice.decryptionFailureTolerance=24` (valor predeterminado upstream) y ajústalo solo si es necesario - observa los registros para: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - si los fallos continúan después de la reconexión automática, recopila registros y compáralos con [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) + - si los fallos continúan después de volver a unirse automáticamente, recopila registros y compáralos con [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) @@ -1229,20 +1233,20 @@ openclaw logs --follow Referencia principal: -- [Referencia de configuración - Discord](/es/gateway/configuration-reference#discord) +- [Configuration reference - Discord](/es/gateway/configuration-reference#discord) Campos de Discord de alta señal: - inicio/autenticación: `enabled`, `token`, `accounts.*`, `allowBots` - política: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` -- comando: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` +- comandos: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - cola de eventos: `eventQueue.listenerTimeout` (presupuesto del listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` - worker entrante: `inboundWorker.runTimeoutMs` - respuesta/historial: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - entrega: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- streaming: `streaming` (alias heredado: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- transmisión: `streaming` (alias heredado: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` - multimedia/reintentos: `mediaMaxMb`, `retry` - - `mediaMaxMb` limita las cargas salientes a Discord (predeterminado: `100MB`) + - `mediaMaxMb` limita las subidas salientes a Discord (predeterminado: `100MB`) - acciones: `actions.*` - presencia: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` @@ -1250,16 +1254,16 @@ Campos de Discord de alta señal: ## Seguridad y operaciones -- Trata los tokens del bot como secretos (se prefiere `DISCORD_BOT_TOKEN` en entornos supervisados). -- Otorga permisos de Discord con privilegio mínimo. -- Si el despliegue/estado de comandos está obsoleto, reinicia el gateway y vuelve a comprobar con `openclaw channels status --probe`. +- Trata los tokens de bot como secretos (`DISCORD_BOT_TOKEN` es lo preferido en entornos supervisados). +- Otorga permisos de Discord con privilegios mínimos. +- Si el despliegue/estado de comandos está desactualizado, reinicia la gateway y vuelve a comprobar con `openclaw channels status --probe`. ## Relacionado -- [Vinculación](/es/channels/pairing) +- [Emparejamiento](/es/channels/pairing) - [Grupos](/es/channels/groups) - [Enrutamiento de canales](/es/channels/channel-routing) - [Seguridad](/es/gateway/security) -- [Enrutamiento de múltiples agentes](/es/concepts/multi-agent) +- [Enrutamiento multiagente](/es/concepts/multi-agent) - [Solución de problemas](/es/channels/troubleshooting) -- [Comandos slash](/es/tools/slash-commands) +- [Comandos de barra inclinada](/es/tools/slash-commands) diff --git a/docs/es/channels/matrix.md b/docs/es/channels/matrix.md index 3d99455ed..3e5c3ae44 100644 --- a/docs/es/channels/matrix.md +++ b/docs/es/channels/matrix.md @@ -1,30 +1,28 @@ --- read_when: - - Configuración de Matrix en OpenClaw - - Configuración de E2EE y verificación de Matrix + - Configurar Matrix en OpenClaw + - Configurar E2EE y verificación de Matrix summary: Estado de compatibilidad de Matrix, configuración y ejemplos de configuración title: Matrix x-i18n: - generated_at: "2026-04-08T02:16:33Z" + generated_at: "2026-04-09T01:29:53Z" model: gpt-5.4 provider: openai - source_hash: ec926df79a41fa296d63f0ec7219d0f32e075628d76df9ea490e93e4c5030f83 + source_hash: 28fc13c7620c1152200315ae69c94205da6de3180c53c814dd8ce03b5cb1758f source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix es el plugin de canal empaquetado de Matrix para OpenClaw. -Usa el `matrix-js-sdk` oficial y admite MD, salas, hilos, multimedia, reacciones, encuestas, ubicación y E2EE. +Matrix es un plugin de canal incluido con OpenClaw. +Usa el `matrix-js-sdk` oficial y admite mensajes directos, salas, hilos, medios, reacciones, encuestas, ubicación y E2EE. -## Plugin empaquetado +## Plugin incluido -Matrix se incluye como plugin empaquetado en las versiones actuales de OpenClaw, por lo que las -compilaciones empaquetadas normales no necesitan una instalación independiente. +Matrix se incluye como plugin integrado en las versiones actuales de OpenClaw, por lo que las compilaciones empaquetadas normales no necesitan una instalación aparte. -Si estás en una compilación antigua o en una instalación personalizada que excluye Matrix, instálalo -manualmente: +Si usas una compilación anterior o una instalación personalizada que excluye Matrix, instálalo manualmente: Instalar desde npm: @@ -44,13 +42,13 @@ Consulta [Plugins](/es/tools/plugin) para conocer el comportamiento de los plugi 1. Asegúrate de que el plugin de Matrix esté disponible. - Las versiones empaquetadas actuales de OpenClaw ya lo incluyen. - - Las instalaciones antiguas/personalizadas pueden añadirlo manualmente con los comandos anteriores. + - Las instalaciones antiguas o personalizadas pueden añadirlo manualmente con los comandos anteriores. 2. Crea una cuenta de Matrix en tu homeserver. 3. Configura `channels.matrix` con una de estas opciones: - `homeserver` + `accessToken`, o - `homeserver` + `userId` + `password`. -4. Reinicia el gateway. -5. Inicia una MD con el bot o invítalo a una sala. +4. Reinicia la puerta de enlace. +5. Inicia un mensaje directo con el bot o invítalo a una sala. - Las invitaciones nuevas de Matrix solo funcionan cuando `channels.matrix.autoJoin` las permite. Rutas de configuración interactiva: @@ -60,39 +58,35 @@ openclaw channels add openclaw configure --section channels ``` -Lo que realmente pregunta el asistente de Matrix: +El asistente de Matrix solicita: - URL del homeserver - método de autenticación: token de acceso o contraseña -- ID de usuario solo cuando eliges autenticación por contraseña -- nombre del dispositivo opcional +- ID de usuario (solo autenticación con contraseña) +- nombre opcional del dispositivo - si se debe habilitar E2EE -- si se debe configurar ahora el acceso a salas de Matrix -- si se debe configurar ahora la unión automática a invitaciones de Matrix -- cuando la unión automática a invitaciones está habilitada, si debe ser `allowlist`, `always` u `off` +- si se debe configurar el acceso a salas y la unión automática a invitaciones -Comportamiento del asistente que importa: +Comportamientos clave del asistente: -- Si ya existen variables de entorno de autenticación de Matrix para la cuenta seleccionada, y esa cuenta todavía no tiene autenticación guardada en la configuración, el asistente ofrece un atajo de entorno para que la configuración pueda mantener la autenticación en variables de entorno en lugar de copiar secretos a la configuración. -- Cuando añades otra cuenta de Matrix de forma interactiva, el nombre de cuenta introducido se normaliza en el ID de cuenta usado en la configuración y en las variables de entorno. Por ejemplo, `Ops Bot` se convierte en `ops-bot`. -- Los prompts de allowlist para MD aceptan inmediatamente valores completos `@user:server`. Los nombres para mostrar solo funcionan cuando la búsqueda en vivo del directorio encuentra una coincidencia exacta; de lo contrario, el asistente te pide que lo intentes de nuevo con un ID completo de Matrix. -- Los prompts de allowlist para salas aceptan directamente IDs y alias de sala. También pueden resolver en vivo nombres de salas unidas, pero los nombres no resueltos solo se conservan tal como se escribieron durante la configuración y luego se ignoran en la resolución de allowlist en tiempo de ejecución. Prefiere `!room:server` o `#alias:server`. -- El asistente ahora muestra una advertencia explícita antes del paso de unión automática a invitaciones porque `channels.matrix.autoJoin` tiene como valor predeterminado `off`; los agentes no se unirán a salas invitadas ni a invitaciones nuevas de estilo MD a menos que lo configures. -- En el modo allowlist de unión automática a invitaciones, usa solo destinos de invitación estables: `!roomId:server`, `#alias:server` o `*`. Los nombres simples de salas se rechazan. -- La identidad de sala/sesión en tiempo de ejecución usa el ID estable de sala de Matrix. Los alias declarados por la sala solo se usan como entradas de búsqueda, no como clave de sesión a largo plazo ni como identidad estable de grupo. -- Para resolver nombres de salas antes de guardarlos, usa `openclaw channels resolve --channel matrix "Project Room"`. +- Si las variables de entorno de autenticación de Matrix ya existen y esa cuenta aún no tiene autenticación guardada en la configuración, el asistente ofrece un atajo de variables de entorno para mantener la autenticación en variables de entorno. +- Los nombres de cuenta se normalizan al ID de cuenta. Por ejemplo, `Ops Bot` se convierte en `ops-bot`. +- Las entradas de la lista de permitidos para mensajes directos aceptan `@user:server` directamente; los nombres visibles solo funcionan cuando la búsqueda en directorio en vivo encuentra una coincidencia exacta. +- Las entradas de la lista de permitidos para salas aceptan directamente ID y alias de sala. Prefiere `!room:server` o `#alias:server`; los nombres no resueltos se ignoran en tiempo de ejecución durante la resolución de la lista de permitidos. +- En el modo de lista de permitidos de unión automática a invitaciones, usa solo destinos de invitación estables: `!roomId:server`, `#alias:server` o `*`. Los nombres simples de sala se rechazan. +- Para resolver nombres de sala antes de guardar, usa `openclaw channels resolve --channel matrix "Project Room"`. -`channels.matrix.autoJoin` tiene como valor predeterminado `off`. +`channels.matrix.autoJoin` usa `off` de forma predeterminada. -Si lo dejas sin configurar, el bot no se unirá a salas invitadas ni a invitaciones nuevas de estilo MD, por lo que no aparecerá en grupos nuevos ni en MD invitadas a menos que primero te unas manualmente. +Si lo dejas sin configurar, el bot no se unirá a salas invitadas ni a invitaciones nuevas de estilo DM, por lo que no aparecerá en grupos nuevos ni en DMs invitados a menos que primero te unas manualmente. Establece `autoJoin: "allowlist"` junto con `autoJoinAllowlist` para restringir qué invitaciones acepta, o establece `autoJoin: "always"` si quieres que se una a todas las invitaciones. En el modo `allowlist`, `autoJoinAllowlist` solo acepta `!roomId:server`, `#alias:server` o `*`. -Ejemplo de allowlist: +Ejemplo de lista de permitidos: ```json5 { @@ -155,9 +149,9 @@ Configuración basada en contraseña (el token se almacena en caché después de Matrix almacena las credenciales en caché en `~/.openclaw/credentials/matrix/`. La cuenta predeterminada usa `credentials.json`; las cuentas con nombre usan `credentials-.json`. -Cuando existen credenciales en caché ahí, OpenClaw considera Matrix como configurado para la configuración, doctor y el descubrimiento de estado del canal, incluso si la autenticación actual no está definida directamente en la configuración. +Cuando existen credenciales en caché allí, OpenClaw considera Matrix como configurado para configuración inicial, doctor y detección del estado del canal, aunque la autenticación actual no esté establecida directamente en la configuración. -Equivalentes en variables de entorno (se usan cuando la clave de configuración no está definida): +Equivalentes de variables de entorno (se usan cuando la clave de configuración no está establecida): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -166,7 +160,7 @@ Equivalentes en variables de entorno (se usan cuando la clave de configuración - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Para cuentas no predeterminadas, usa variables de entorno con alcance de cuenta: +Para cuentas no predeterminadas, usa variables de entorno limitadas al ámbito de la cuenta: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -185,14 +179,14 @@ Para el ID de cuenta normalizado `ops-bot`, usa: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix escapa la puntuación en los ID de cuenta para mantener las variables de entorno con alcance de cuenta libres de colisiones. -Por ejemplo, `-` se convierte en `_X2D_`, por lo que `ops-prod` se asigna a `MATRIX_OPS_X2D_PROD_*`. +Matrix escapa la puntuación en los ID de cuenta para evitar colisiones en las variables de entorno acotadas al ámbito. +Por ejemplo, `-` se convierte en `_X2D_`, por lo que `ops-prod` se convierte en `MATRIX_OPS_X2D_PROD_*`. El asistente interactivo solo ofrece el atajo de variables de entorno cuando esas variables de autenticación ya están presentes y la cuenta seleccionada aún no tiene autenticación de Matrix guardada en la configuración. ## Ejemplo de configuración -Esta es una configuración base práctica con emparejamiento en MD, allowlist de salas y E2EE habilitado: +Esta es una configuración base práctica con emparejamiento de DM, lista de permitidos de sala y E2EE habilitado: ```json5 { @@ -227,19 +221,13 @@ Esta es una configuración base práctica con emparejamiento en MD, allowlist de } ``` -`autoJoin` se aplica a las invitaciones de Matrix en general, no solo a las invitaciones de sala/grupo. -Eso incluye las invitaciones nuevas de estilo MD. En el momento de la invitación, OpenClaw no sabe de forma fiable si la -sala invitada acabará tratándose como una MD o como un grupo, por lo que todas las invitaciones pasan primero por la misma -decisión de `autoJoin`. `dm.policy` sigue aplicándose después de que el bot se haya unido y la sala se -clasifique como una MD, de modo que `autoJoin` controla el comportamiento de unión mientras que `dm.policy` controla el comportamiento de respuesta/acceso. +`autoJoin` se aplica a todas las invitaciones de Matrix, incluidas las invitaciones de estilo DM. OpenClaw no puede clasificar de forma fiable una sala invitada como DM o grupo en el momento de la invitación, así que todas las invitaciones pasan primero por `autoJoin`. `dm.policy` se aplica después de que el bot se haya unido y la sala se haya clasificado como DM. -## Vistas previas de streaming +## Vistas previas en streaming -El streaming de respuestas de Matrix es opcional. +El streaming de respuestas en Matrix es opcional. -Establece `channels.matrix.streaming` en `"partial"` cuando quieras que OpenClaw envíe una sola vista previa en vivo -de la respuesta, edite esa vista previa en su lugar mientras el modelo genera texto y luego la -finalice cuando la respuesta termine: +Establece `channels.matrix.streaming` en `"partial"` cuando quieras que OpenClaw envíe una única respuesta de vista previa en vivo, edite esa vista previa en el lugar mientras el modelo genera texto y luego la finalice cuando la respuesta esté lista: ```json5 { @@ -252,34 +240,33 @@ finalice cuando la respuesta termine: ``` - `streaming: "off"` es el valor predeterminado. OpenClaw espera la respuesta final y la envía una sola vez. -- `streaming: "partial"` crea un mensaje de vista previa editable para el bloque actual del asistente usando mensajes de texto normales de Matrix. Esto conserva el comportamiento heredado de notificación basado primero en la vista previa de Matrix, por lo que los clientes estándar pueden notificar con el primer texto de vista previa en streaming en lugar del bloque terminado. -- `streaming: "quiet"` crea un aviso de vista previa silencioso editable para el bloque actual del asistente. Usa esto solo cuando también configures reglas push del destinatario para las ediciones finalizadas de la vista previa. -- `blockStreaming: true` habilita mensajes de progreso de Matrix independientes. Con la vista previa en streaming habilitada, Matrix mantiene el borrador en vivo del bloque actual y conserva los bloques completados como mensajes independientes. -- Cuando la vista previa en streaming está activada y `blockStreaming` está desactivado, Matrix edita el borrador en vivo en su lugar y finaliza ese mismo evento cuando el bloque o el turno termina. +- `streaming: "partial"` crea un único mensaje de vista previa editable para el bloque actual del asistente usando mensajes de texto normales de Matrix. Esto conserva el comportamiento heredado de Matrix de notificar primero la vista previa, por lo que los clientes estándar pueden notificar sobre el primer texto de vista previa en streaming en lugar del bloque finalizado. +- `streaming: "quiet"` crea un único aviso silencioso de vista previa editable para el bloque actual del asistente. Úsalo solo cuando también configures reglas push del destinatario para las ediciones de vista previa finalizadas. +- `blockStreaming: true` habilita mensajes de progreso de Matrix separados. Con la vista previa en streaming habilitada, Matrix mantiene el borrador en vivo del bloque actual y conserva los bloques completados como mensajes separados. +- Cuando la vista previa en streaming está activada y `blockStreaming` está desactivado, Matrix edita el borrador en vivo en el lugar y finaliza ese mismo evento cuando termina el bloque o el turno. - Si la vista previa ya no cabe en un solo evento de Matrix, OpenClaw detiene la vista previa en streaming y vuelve a la entrega final normal. -- Las respuestas multimedia siguen enviando archivos adjuntos con normalidad. Si una vista previa obsoleta ya no puede reutilizarse de forma segura, OpenClaw la redacta antes de enviar la respuesta multimedia final. -- Las ediciones de vista previa tienen un costo adicional de llamadas a la API de Matrix. Deja el streaming desactivado si quieres el comportamiento más conservador respecto a los límites de tasa. +- Las respuestas con medios siguen enviando adjuntos normalmente. Si una vista previa obsoleta ya no puede reutilizarse de forma segura, OpenClaw la redacta antes de enviar la respuesta final con medios. +- Las ediciones de vista previa implican llamadas adicionales a la API de Matrix. Deja el streaming desactivado si quieres el comportamiento más conservador respecto a límites de tasa. -`blockStreaming` no habilita por sí solo las vistas previas de borrador. -Usa `streaming: "partial"` o `streaming: "quiet"` para las ediciones de vista previa; luego añade `blockStreaming: true` solo si también quieres que los bloques completados del asistente permanezcan visibles como mensajes de progreso independientes. +`blockStreaming` no habilita por sí solo vistas previas de borrador. +Usa `streaming: "partial"` o `streaming: "quiet"` para las ediciones de vista previa; después añade `blockStreaming: true` solo si además quieres que los bloques completados del asistente sigan siendo visibles como mensajes de progreso separados. Si necesitas notificaciones estándar de Matrix sin reglas push personalizadas, usa `streaming: "partial"` para el comportamiento de vista previa primero o deja `streaming` desactivado para entrega solo final. Con `streaming: "off"`: - `blockStreaming: true` envía cada bloque terminado como un mensaje normal de Matrix con notificación. -- `blockStreaming: false` envía solo la respuesta final completada como un mensaje normal de Matrix con notificación. +- `blockStreaming: false` envía solo la respuesta final completa como un mensaje normal de Matrix con notificación. ### Reglas push autoalojadas para vistas previas silenciosas finalizadas -Si ejecutas tu propia infraestructura de Matrix y quieres que las vistas previas silenciosas notifiquen solo cuando un bloque o la -respuesta final haya terminado, establece `streaming: "quiet"` y añade una regla push por usuario para las ediciones finalizadas de la vista previa. +Si administras tu propia infraestructura de Matrix y quieres que las vistas previas silenciosas notifiquen solo cuando un bloque o la respuesta final haya terminado, establece `streaming: "quiet"` y añade una regla push por usuario para las ediciones de vista previa finalizadas. -Esto normalmente es una configuración del usuario destinatario, no un cambio de configuración global del homeserver: +Normalmente esta es una configuración del usuario destinatario, no un cambio global de configuración del homeserver: -Mapa rápido antes de empezar: +Resumen rápido antes de empezar: - usuario destinatario = la persona que debe recibir la notificación - usuario bot = la cuenta de Matrix de OpenClaw que envía la respuesta -- usa el token de acceso del usuario destinatario para las llamadas a la API de abajo +- usa el token de acceso del usuario destinatario para las llamadas a la API siguientes - haz coincidir `sender` en la regla push con el MXID completo del usuario bot 1. Configura OpenClaw para usar vistas previas silenciosas: @@ -294,11 +281,10 @@ Mapa rápido antes de empezar: } ``` -2. Asegúrate de que la cuenta del destinatario ya recibe notificaciones push normales de Matrix. Las reglas - para vistas previas silenciosas solo funcionan si ese usuario ya tiene pushers/dispositivos operativos. +2. Asegúrate de que la cuenta del destinatario ya reciba notificaciones push normales de Matrix. Las reglas de vista previa silenciosa solo funcionan si ese usuario ya tiene pushers o dispositivos funcionando. 3. Obtén el token de acceso del usuario destinatario. - - Usa el token del usuario que recibe, no el token del bot. + - Usa el token del usuario que recibe, no el del bot. - Reutilizar un token de sesión de cliente existente suele ser lo más sencillo. - Si necesitas emitir un token nuevo, puedes iniciar sesión mediante la API estándar Client-Server de Matrix: @@ -324,8 +310,7 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Si esto no devuelve pushers/dispositivos activos, corrige primero las notificaciones normales de Matrix antes de añadir la -regla de OpenClaw de abajo. +Si esto no devuelve pushers o dispositivos activos, primero corrige las notificaciones normales de Matrix antes de añadir la siguiente regla de OpenClaw. OpenClaw marca las ediciones finalizadas de vista previa solo de texto con: @@ -335,7 +320,7 @@ OpenClaw marca las ediciones finalizadas de vista previa solo de texto con: } ``` -5. Crea una regla push de anulación para cada cuenta destinataria que deba recibir estas notificaciones: +5. Crea una regla push de override para cada cuenta destinataria que deba recibir estas notificaciones: ```bash curl -sS -X PUT \ @@ -374,11 +359,11 @@ Sustituye estos valores antes de ejecutar el comando: Importante para configuraciones con varios bots: -- Las reglas push se indexan por `ruleId`. Volver a ejecutar `PUT` sobre el mismo ID de regla actualiza esa única regla. -- Si un usuario receptor debe recibir notificaciones de varias cuentas bot de Matrix de OpenClaw, crea una regla por bot con un ID de regla único para cada coincidencia de remitente. -- Un patrón simple es `openclaw-finalized-preview-`, como `openclaw-finalized-preview-ops` o `openclaw-finalized-preview-support`. +- Las reglas push se indexan por `ruleId`. Volver a ejecutar `PUT` sobre el mismo ID de regla actualiza esa misma regla. +- Si un usuario receptor debe recibir notificaciones de varias cuentas de bot de Matrix de OpenClaw, crea una regla por bot con un ID de regla único para cada coincidencia de remitente. +- Un patrón sencillo es `openclaw-finalized-preview-`, como `openclaw-finalized-preview-ops` o `openclaw-finalized-preview-support`. -La regla se evalúa frente al remitente del evento: +La regla se evalúa respecto al remitente del evento: - autentícate con el token del usuario receptor - haz coincidir `sender` con el MXID del bot de OpenClaw @@ -391,10 +376,9 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Prueba una respuesta en streaming. En modo silencioso, la sala debería mostrar una vista previa de borrador silenciosa y la edición final - en su lugar debería notificar una vez que el bloque o el turno termine. +7. Prueba una respuesta en streaming. En modo silencioso, la sala debería mostrar una vista previa de borrador silenciosa y la edición final en el lugar debería notificar una vez que termine el bloque o el turno. -Si necesitas eliminar la regla más tarde, borra ese mismo ID de regla con el token del usuario receptor: +Si necesitas eliminar la regla más adelante, borra ese mismo ID de regla con el token del usuario receptor: ```bash curl -sS -X DELETE \ @@ -405,34 +389,30 @@ curl -sS -X DELETE \ Notas: - Crea la regla con el token de acceso del usuario receptor, no con el del bot. -- Las nuevas reglas `override` definidas por el usuario se insertan antes de las reglas de supresión predeterminadas, por lo que no se necesita ningún parámetro adicional de orden. -- Esto solo afecta a las ediciones de vista previa solo de texto que OpenClaw puede finalizar de forma segura en su lugar. Las alternativas para multimedia y las alternativas por vista previa obsoleta siguen usando la entrega normal de Matrix. -- Si `GET /_matrix/client/v3/pushers` no muestra pushers, el usuario todavía no tiene una entrega push de Matrix operativa para esta cuenta/dispositivo. +- Las nuevas reglas `override` definidas por el usuario se insertan antes de las reglas de supresión predeterminadas, así que no hace falta ningún parámetro adicional de orden. +- Esto solo afecta a las ediciones de vista previa solo de texto que OpenClaw puede finalizar en el lugar de forma segura. Los retrocesos de medios y los retrocesos por vista previa obsoleta siguen usando la entrega normal de Matrix. +- Si `GET /_matrix/client/v3/pushers` no muestra pushers, el usuario aún no tiene entrega push de Matrix funcionando para esa cuenta o dispositivo. #### Synapse -Para Synapse, la configuración anterior normalmente es suficiente por sí sola: +Para Synapse, normalmente la configuración anterior es suficiente por sí sola: - No se requiere ningún cambio especial en `homeserver.yaml` para las notificaciones de vista previa finalizada de OpenClaw. -- Si tu despliegue de Synapse ya envía notificaciones push normales de Matrix, el token de usuario + la llamada `pushrules` anterior es el paso principal de configuración. +- Si tu despliegue de Synapse ya envía notificaciones push normales de Matrix, el token de usuario y la llamada `pushrules` de arriba son el paso principal de configuración. - Si ejecutas Synapse detrás de un proxy inverso o workers, asegúrate de que `/_matrix/client/.../pushrules/` llegue correctamente a Synapse. -- Si ejecutas workers de Synapse, asegúrate de que los pushers estén en buen estado. La entrega push la gestiona el proceso principal o `synapse.app.pusher` / workers de pusher configurados. +- Si usas workers de Synapse, asegúrate de que los pushers estén en buen estado. La entrega push la gestiona el proceso principal o `synapse.app.pusher` o los workers pusher configurados. #### Tuwunel -Para Tuwunel, usa el mismo flujo de configuración y la llamada a la API `pushrules` mostrada arriba: +Para Tuwunel, usa el mismo flujo de configuración y la misma llamada a la API `pushrules` mostrada arriba: -- No se requiere ninguna configuración específica de Tuwunel para el marcador de vista previa finalizada en sí. -- Si las notificaciones normales de Matrix ya funcionan para ese usuario, el token de usuario + la llamada `pushrules` anterior es el paso principal de configuración. -- Si parece que las notificaciones desaparecen mientras el usuario está activo en otro dispositivo, comprueba si `suppress_push_when_active` está habilitado. Tuwunel añadió esta opción en Tuwunel 1.4.2 el 12 de septiembre de 2025, y puede suprimir intencionadamente los pushes a otros dispositivos mientras un dispositivo está activo. +- No se requiere ninguna configuración específica de Tuwunel para el propio marcador de vista previa finalizada. +- Si las notificaciones normales de Matrix ya funcionan para ese usuario, el token de usuario y la llamada `pushrules` anterior son el paso principal de configuración. +- Si las notificaciones parecen desaparecer mientras el usuario está activo en otro dispositivo, comprueba si `suppress_push_when_active` está habilitado. Tuwunel añadió esta opción en Tuwunel 1.4.2 el 12 de septiembre de 2025, y puede suprimir intencionadamente los avisos push a otros dispositivos mientras uno está activo. -## Cifrado y verificación +## Salas de bot a bot -En salas cifradas (E2EE), los eventos salientes de imagen usan `thumbnail_file` para que las vistas previas de imagen se cifren junto con el archivo adjunto completo. Las salas sin cifrar siguen usando `thumbnail_url` sin formato. No se necesita ninguna configuración: el plugin detecta automáticamente el estado de E2EE. - -### Salas de bot a bot - -De forma predeterminada, los mensajes de otras cuentas configuradas de Matrix de OpenClaw se ignoran. +De forma predeterminada, se ignoran los mensajes de otras cuentas de Matrix de OpenClaw configuradas. Usa `allowBots` cuando quieras intencionadamente tráfico de Matrix entre agentes: @@ -451,13 +431,17 @@ Usa `allowBots` cuando quieras intencionadamente tráfico de Matrix entre agente } ``` -- `allowBots: true` acepta mensajes de otras cuentas bot configuradas de Matrix en salas y MD permitidas. -- `allowBots: "mentions"` acepta esos mensajes solo cuando mencionan visiblemente a este bot en salas. Las MD siguen estando permitidas. -- `groups..allowBots` reemplaza la configuración a nivel de cuenta para una sala. +- `allowBots: true` acepta mensajes de otras cuentas de bot de Matrix configuradas en salas y DMs permitidos. +- `allowBots: "mentions"` acepta esos mensajes solo cuando mencionan visiblemente a este bot en salas. Los DMs siguen permitidos. +- `groups..allowBots` sobrescribe la configuración a nivel de cuenta para una sala. - OpenClaw sigue ignorando los mensajes del mismo ID de usuario de Matrix para evitar bucles de autorrespuesta. -- Matrix no expone aquí un indicador nativo de bot; OpenClaw considera "creado por bot" como "enviado por otra cuenta de Matrix configurada en este gateway de OpenClaw". +- Matrix no expone aquí una marca nativa de bot; OpenClaw trata "escrito por bot" como "enviado por otra cuenta de Matrix configurada en esta puerta de enlace de OpenClaw". -Usa allowlists estrictas de salas y requisitos de mención al habilitar tráfico bot a bot en salas compartidas. +Usa listas de permitidos estrictas para salas y requisitos de mención cuando habilites tráfico de bot a bot en salas compartidas. + +## Cifrado y verificación + +En las salas cifradas (E2EE), los eventos salientes de imagen usan `thumbnail_file` para que las vistas previas de imagen se cifren junto con el adjunto completo. Las salas no cifradas siguen usando `thumbnail_url` sin cifrar. No se necesita configuración: el plugin detecta automáticamente el estado E2EE. Habilitar cifrado: @@ -493,21 +477,19 @@ Incluir la clave de recuperación almacenada en la salida legible por máquina: openclaw matrix verify status --include-recovery-key --json ``` -Inicializar el estado de cross-signing y verificación: +Inicializar el estado de firma cruzada y verificación: ```bash openclaw matrix verify bootstrap ``` -Compatibilidad con varias cuentas: usa `channels.matrix.accounts` con credenciales por cuenta y `name` opcional. Consulta [Referencia de configuración](/es/gateway/configuration-reference#multi-account-all-channels) para el patrón compartido. - -Diagnóstico detallado de bootstrap: +Diagnóstico detallado del bootstrap: ```bash openclaw matrix verify bootstrap --verbose ``` -Forzar un reinicio nuevo de la identidad de cross-signing antes de hacer bootstrap: +Forzar un reinicio completo de una identidad nueva de firma cruzada antes del bootstrap: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -525,19 +507,19 @@ Detalles detallados de verificación del dispositivo: openclaw matrix verify device "" --verbose ``` -Comprobar el estado del backup de claves de sala: +Comprobar el estado de salud de la copia de seguridad de claves de sala: ```bash openclaw matrix verify backup status ``` -Diagnóstico detallado del estado del backup: +Diagnóstico detallado del estado de la copia de seguridad: ```bash openclaw matrix verify backup status --verbose ``` -Restaurar claves de sala desde el backup del servidor: +Restaurar claves de sala desde la copia de seguridad del servidor: ```bash openclaw matrix verify backup restore @@ -549,19 +531,17 @@ Diagnóstico detallado de restauración: openclaw matrix verify backup restore --verbose ``` -Eliminar el backup actual del servidor y crear una nueva línea base de backup. Si la clave de -backup almacenada no puede cargarse limpiamente, este reinicio también puede recrear el almacenamiento de secretos para que -los futuros arranques en frío puedan cargar la nueva clave de backup: +Eliminar la copia de seguridad actual del servidor y crear una nueva base de copia de seguridad. Si la clave de copia de seguridad almacenada no se puede cargar limpiamente, este restablecimiento también puede recrear el almacenamiento secreto para que futuros inicios en frío puedan cargar la nueva clave de copia de seguridad: ```bash openclaw matrix verify backup reset --yes ``` -Todos los comandos `verify` son concisos de forma predeterminada (incluido el registro interno silencioso del SDK) y solo muestran diagnóstico detallado con `--verbose`. -Usa `--json` para obtener una salida completa legible por máquina al automatizar. +Todos los comandos `verify` son concisos de forma predeterminada (incluido el registro silencioso interno del SDK) y muestran diagnósticos detallados solo con `--verbose`. +Usa `--json` para obtener salida completa legible por máquina en scripts. -En configuraciones con varias cuentas, los comandos de Matrix CLI usan la cuenta predeterminada implícita de Matrix a menos que pases `--account `. -Si configuras varias cuentas con nombre, establece primero `channels.matrix.defaultAccount` o esas operaciones implícitas de CLI se detendrán y te pedirán que elijas una cuenta explícitamente. +En configuraciones de varias cuentas, los comandos CLI de Matrix usan la cuenta predeterminada implícita de Matrix a menos que pases `--account `. +Si configuras varias cuentas con nombre, primero establece `channels.matrix.defaultAccount` o esas operaciones CLI implícitas se detendrán y te pedirán que elijas una cuenta explícitamente. Usa `--account` siempre que quieras que las operaciones de verificación o de dispositivo apunten explícitamente a una cuenta con nombre: ```bash @@ -572,16 +552,16 @@ openclaw matrix devices list --account assistant Cuando el cifrado está deshabilitado o no disponible para una cuenta con nombre, las advertencias de Matrix y los errores de verificación apuntan a la clave de configuración de esa cuenta, por ejemplo `channels.matrix.accounts.assistant.encryption`. -### Qué significa "verified" +### Qué significa "verificado" -OpenClaw trata este dispositivo de Matrix como verificado solo cuando está verificado por tu propia identidad de cross-signing. +OpenClaw trata este dispositivo de Matrix como verificado solo cuando está verificado por tu propia identidad de firma cruzada. En la práctica, `openclaw matrix verify status --verbose` expone tres señales de confianza: -- `Locally trusted`: este dispositivo es de confianza solo para el cliente actual -- `Cross-signing verified`: el SDK informa que el dispositivo está verificado mediante cross-signing -- `Signed by owner`: el dispositivo está firmado por tu propia clave de self-signing +- `Locally trusted`: este dispositivo solo es de confianza para el cliente actual +- `Cross-signing verified`: el SDK informa que el dispositivo está verificado mediante firma cruzada +- `Signed by owner`: el dispositivo está firmado por tu propia clave de autofirma -`Verified by owner` pasa a ser `yes` solo cuando hay verificación por cross-signing o firma del propietario. +`Verified by owner` pasa a ser `yes` solo cuando hay verificación mediante firma cruzada o firma del propietario. La confianza local por sí sola no basta para que OpenClaw trate el dispositivo como totalmente verificado. ### Qué hace bootstrap @@ -589,22 +569,19 @@ La confianza local por sí sola no basta para que OpenClaw trate el dispositivo `openclaw matrix verify bootstrap` es el comando de reparación y configuración para cuentas cifradas de Matrix. Hace todo lo siguiente en este orden: -- inicializa el almacenamiento de secretos, reutilizando una clave de recuperación existente cuando sea posible -- inicializa cross-signing y sube las claves públicas de cross-signing que falten -- intenta marcar y firmar con cross-signing el dispositivo actual -- crea un nuevo backup de claves de sala del lado del servidor si todavía no existe uno +- inicializa el almacenamiento secreto, reutilizando una clave de recuperación existente cuando sea posible +- inicializa la firma cruzada y sube las claves públicas de firma cruzada que falten +- intenta marcar y firmar mediante firma cruzada el dispositivo actual +- crea una nueva copia de seguridad de claves de sala en el servidor si todavía no existe una -Si el homeserver requiere autenticación interactiva para subir claves de cross-signing, OpenClaw intenta la carga primero sin autenticación, luego con `m.login.dummy` y después con `m.login.password` cuando `channels.matrix.password` está configurado. +Si el homeserver requiere autenticación interactiva para subir claves de firma cruzada, OpenClaw intenta primero la subida sin autenticación, luego con `m.login.dummy` y después con `m.login.password` cuando `channels.matrix.password` está configurado. -Usa `--force-reset-cross-signing` solo cuando quieras intencionadamente descartar la identidad actual de cross-signing y crear una nueva. +Usa `--force-reset-cross-signing` solo cuando quieras intencionadamente descartar la identidad actual de firma cruzada y crear una nueva. -Si intencionadamente quieres descartar el backup actual de claves de sala y comenzar una nueva -línea base de backup para futuros mensajes, usa `openclaw matrix verify backup reset --yes`. -Haz esto solo si aceptas que el historial cifrado antiguo irrecuperable seguirá -sin estar disponible y que OpenClaw puede recrear el almacenamiento de secretos si el secreto actual del backup -no puede cargarse de forma segura. +Si quieres descartar intencionadamente la copia de seguridad actual de claves de sala y empezar una nueva base de copia de seguridad para mensajes futuros, usa `openclaw matrix verify backup reset --yes`. +Hazlo solo si aceptas que el historial cifrado antiguo irrecuperable seguirá sin estar disponible y que OpenClaw podría recrear el almacenamiento secreto si el secreto actual de copia de seguridad no puede cargarse de forma segura. -### Nueva línea base de backup +### Nueva base de copia de seguridad Si quieres mantener funcionando los futuros mensajes cifrados y aceptas perder el historial antiguo irrecuperable, ejecuta estos comandos en orden: @@ -616,98 +593,43 @@ openclaw matrix verify status Añade `--account ` a cada comando cuando quieras apuntar explícitamente a una cuenta de Matrix con nombre. -### Comportamiento al iniciar +### Comportamiento al inicio -Cuando `encryption: true`, Matrix establece por defecto `startupVerification` en `"if-unverified"`. -Al iniciar, si este dispositivo sigue sin verificar, Matrix solicitará la autoverificación en otro cliente de Matrix, -omitirá solicitudes duplicadas mientras ya haya una pendiente y aplicará un enfriamiento local antes de reintentar tras reinicios. -Los intentos fallidos de solicitud se reintentan antes que la creación satisfactoria de solicitudes, de forma predeterminada. -Establece `startupVerification: "off"` para deshabilitar las solicitudes automáticas al iniciar, o ajusta `startupVerificationCooldownHours` -si quieres una ventana de reintento más corta o más larga. +Cuando `encryption: true`, Matrix usa `"if-unverified"` como valor predeterminado para `startupVerification`. +Al inicio, si este dispositivo sigue sin verificar, Matrix solicitará una autoverificación en otro cliente de Matrix, omitirá solicitudes duplicadas mientras ya haya una pendiente y aplicará un tiempo de espera local antes de reintentar después de reinicios. +Los intentos de solicitud fallidos se reintentan antes que la creación correcta de solicitudes de forma predeterminada. +Establece `startupVerification: "off"` para desactivar las solicitudes automáticas al inicio, o ajusta `startupVerificationCooldownHours` si quieres una ventana de reintento más corta o más larga. -El inicio también realiza automáticamente una pasada conservadora de bootstrap de crypto. -Esa pasada intenta reutilizar primero el almacenamiento de secretos y la identidad de cross-signing actuales, y evita restablecer cross-signing a menos que ejecutes un flujo explícito de reparación bootstrap. +El inicio también realiza automáticamente un paso conservador de bootstrap criptográfico. +Ese paso intenta primero reutilizar el almacenamiento secreto actual y la identidad actual de firma cruzada, y evita restablecer la firma cruzada a menos que ejecutes un flujo explícito de reparación de bootstrap. -Si el inicio encuentra un estado de bootstrap roto y `channels.matrix.password` está configurado, OpenClaw puede intentar una ruta de reparación más estricta. +Si durante el inicio se detecta un estado de bootstrap dañado y `channels.matrix.password` está configurado, OpenClaw puede intentar una ruta de reparación más estricta. Si el dispositivo actual ya está firmado por el propietario, OpenClaw preserva esa identidad en lugar de restablecerla automáticamente. -Actualización desde el plugin público anterior de Matrix: +Consulta [Migración de Matrix](/es/install/migrating-matrix) para ver el flujo completo de actualización, los límites, los comandos de recuperación y los mensajes de migración comunes. -- OpenClaw reutiliza automáticamente la misma cuenta de Matrix, el token de acceso y la identidad del dispositivo cuando es posible. -- Antes de ejecutar cualquier cambio de migración accionable de Matrix, OpenClaw crea o reutiliza una instantánea de recuperación en `~/Backups/openclaw-migrations/`. -- Si usas varias cuentas de Matrix, establece `channels.matrix.defaultAccount` antes de actualizar desde el diseño plano de almacenamiento antiguo para que OpenClaw sepa qué cuenta debe recibir ese estado heredado compartido. -- Si el plugin anterior almacenó localmente una clave de descifrado del backup de claves de sala de Matrix, el inicio o `openclaw doctor --fix` la importará automáticamente al nuevo flujo de clave de recuperación. -- Si el token de acceso de Matrix cambió después de que se preparó la migración, el inicio ahora examina raíces hermanas de almacenamiento por hash de token en busca de estado heredado pendiente de restauración antes de abandonar la restauración automática del backup. -- Si el token de acceso de Matrix cambia más tarde para la misma cuenta, homeserver y usuario, OpenClaw ahora prefiere reutilizar la raíz de almacenamiento por hash de token existente más completa en lugar de empezar desde un directorio de estado de Matrix vacío. -- En el siguiente inicio del gateway, las claves de sala respaldadas se restauran automáticamente en el nuevo almacén crypto. -- Si el plugin antiguo tenía claves de sala solo locales que nunca se respaldaron, OpenClaw lo advertirá claramente. Esas claves no pueden exportarse automáticamente desde el almacén crypto rust anterior, por lo que parte del historial cifrado antiguo puede seguir sin estar disponible hasta recuperarlo manualmente. -- Consulta [Migración de Matrix](/es/install/migrating-matrix) para ver el flujo completo de actualización, límites, comandos de recuperación y mensajes comunes de migración. +### Avisos de verificación -El estado de ejecución cifrado se organiza bajo raíces por cuenta, usuario y hash de token en -`~/.openclaw/matrix/accounts//__//`. -Ese directorio contiene el almacén de sincronización (`bot-storage.json`), el almacén crypto (`crypto/`), -el archivo de clave de recuperación (`recovery-key.json`), la instantánea de IndexedDB (`crypto-idb-snapshot.json`), -los enlaces de hilos (`thread-bindings.json`) y el estado de verificación al inicio (`startup-verification.json`) -cuando esas funciones están en uso. -Cuando el token cambia pero la identidad de la cuenta sigue siendo la misma, OpenClaw reutiliza la mejor -raíz existente para esa tupla cuenta/homeserver/usuario, de modo que el estado de sincronización previo, el estado crypto, los enlaces de hilos -y el estado de verificación al inicio sigan siendo visibles. - -### Modelo de almacén crypto de Node - -La E2EE de Matrix en este plugin usa la ruta Rust crypto oficial de `matrix-js-sdk` en Node. -Esa ruta espera persistencia respaldada por IndexedDB cuando quieres que el estado crypto sobreviva a los reinicios. - -Actualmente OpenClaw lo proporciona en Node mediante: - -- uso de `fake-indexeddb` como shim de API IndexedDB que espera el SDK -- restauración del contenido de IndexedDB de Rust crypto desde `crypto-idb-snapshot.json` antes de `initRustCrypto` -- persistencia del contenido actualizado de IndexedDB de vuelta en `crypto-idb-snapshot.json` después de la inicialización y durante la ejecución -- serialización de la restauración y persistencia de la instantánea contra `crypto-idb-snapshot.json` con un bloqueo de archivo consultivo para que la persistencia del gateway en ejecución y el mantenimiento desde CLI no compitan por el mismo archivo de instantánea - -Esto es infraestructura de compatibilidad/almacenamiento, no una implementación crypto personalizada. -El archivo de instantánea es un estado sensible en ejecución y se almacena con permisos restrictivos de archivo. -Bajo el modelo de seguridad de OpenClaw, el host del gateway y el directorio de estado local de OpenClaw ya están dentro del límite de confianza del operador, por lo que esto es principalmente una cuestión operativa de durabilidad y no un límite de confianza remoto independiente. - -Mejora planificada: - -- añadir compatibilidad con SecretRef para material persistente de claves de Matrix, de modo que las claves de recuperación y secretos relacionados para cifrado del almacenamiento puedan obtenerse de proveedores de secretos de OpenClaw en lugar de solo desde archivos locales - -## Gestión de perfil - -Actualiza el perfil propio de Matrix para la cuenta seleccionada con: - -```bash -openclaw matrix profile set --name "OpenClaw Assistant" -openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png -``` - -Añade `--account ` cuando quieras apuntar explícitamente a una cuenta de Matrix con nombre. - -Matrix acepta directamente URL de avatar `mxc://`. Cuando pasas una URL de avatar `http://` o `https://`, OpenClaw primero la sube a Matrix y almacena la URL `mxc://` resuelta de vuelta en `channels.matrix.avatarUrl` (o en la anulación de la cuenta seleccionada). - -## Avisos automáticos de verificación - -Matrix ahora publica avisos del ciclo de vida de verificación directamente en la sala estricta de MD de verificación como mensajes `m.notice`. -Eso incluye: +Matrix publica avisos del ciclo de vida de verificación directamente en la sala estricta de DM de verificación como mensajes `m.notice`. +Esto incluye: - avisos de solicitud de verificación -- avisos de verificación lista (con orientación explícita de "Verificar por emoji") -- avisos de inicio y finalización de verificación -- detalles SAS (emoji y decimal) cuando están disponibles +- avisos de verificación lista (con orientación explícita "Verificar por emoji") +- inicio y finalización de verificación +- detalles SAS (emoji y decimal) cuando estén disponibles -Las solicitudes de verificación entrantes de otro cliente de Matrix se rastrean y OpenClaw las acepta automáticamente. -Para flujos de autoverificación, OpenClaw también inicia automáticamente el flujo SAS cuando la verificación por emoji está disponible y confirma su propio lado. -Para solicitudes de verificación de otro usuario/dispositivo de Matrix, OpenClaw acepta automáticamente la solicitud y luego espera a que el flujo SAS continúe normalmente. -Aun así, necesitas comparar el SAS de emoji o decimal en tu cliente de Matrix y confirmar allí "Coinciden" para completar la verificación. +Las solicitudes de verificación entrantes desde otro cliente de Matrix se rastrean y OpenClaw las acepta automáticamente. +Para flujos de autoverificación, OpenClaw también inicia automáticamente el flujo SAS cuando la verificación por emoji pasa a estar disponible y confirma su propio lado. +Para solicitudes de verificación de otro usuario o dispositivo de Matrix, OpenClaw acepta automáticamente la solicitud y luego espera a que el flujo SAS continúe de forma normal. +Aun así, debes comparar el SAS de emoji o decimal en tu cliente de Matrix y confirmar allí "Coinciden" para completar la verificación. -OpenClaw no acepta automáticamente a ciegas flujos duplicados iniciados por sí mismo. Al iniciar se omite la creación de una nueva solicitud cuando ya hay una solicitud de autoverificación pendiente. +OpenClaw no acepta automáticamente a ciegas flujos duplicados iniciados por sí mismo. El inicio omite crear una nueva solicitud cuando ya hay una solicitud de autoverificación pendiente. -Los avisos de verificación de protocolo/sistema no se reenvían al canal de chat del agente, por lo que no producen `NO_REPLY`. +Los avisos del protocolo o sistema de verificación no se reenvían a la canalización de chat del agente, así que no producen `NO_REPLY`. ### Higiene de dispositivos -Los dispositivos antiguos de Matrix gestionados por OpenClaw pueden acumularse en la cuenta y hacer que la confianza en salas cifradas sea más difícil de razonar. +Los dispositivos antiguos de Matrix gestionados por OpenClaw pueden acumularse en la cuenta y dificultar entender la confianza en salas cifradas. Haz una lista con: ```bash @@ -720,67 +642,71 @@ Elimina dispositivos obsoletos gestionados por OpenClaw con: openclaw matrix devices prune-stale ``` -### Reparación directa de sala +### Almacén criptográfico -Si el estado de los mensajes directos se desincroniza, OpenClaw puede acabar con asignaciones `m.direct` obsoletas que apuntan a salas individuales antiguas en lugar de a la MD activa. Inspecciona la asignación actual para un par con: +E2EE de Matrix usa la ruta criptográfica Rust oficial de `matrix-js-sdk` en Node, con `fake-indexeddb` como shim de IndexedDB. El estado criptográfico se conserva en un archivo de instantánea (`crypto-idb-snapshot.json`) y se restaura al inicio. El archivo de instantánea es un estado de ejecución sensible almacenado con permisos de archivo restrictivos. + +El estado cifrado de ejecución vive bajo raíces por cuenta, por usuario y por hash de token en +`~/.openclaw/matrix/accounts//__//`. +Ese directorio contiene el almacén de sincronización (`bot-storage.json`), el almacén criptográfico (`crypto/`), +el archivo de clave de recuperación (`recovery-key.json`), la instantánea de IndexedDB (`crypto-idb-snapshot.json`), +los enlaces de hilos (`thread-bindings.json`) y el estado de verificación al inicio (`startup-verification.json`). +Cuando el token cambia pero la identidad de la cuenta sigue siendo la misma, OpenClaw reutiliza la mejor +raíz existente para esa tupla de cuenta, homeserver y usuario para que el estado de sincronización previo, el estado criptográfico, los enlaces de hilos +y el estado de verificación al inicio sigan estando visibles. + +## Gestión de perfil + +Actualiza el perfil propio de Matrix para la cuenta seleccionada con: ```bash -openclaw matrix direct inspect --user-id @alice:example.org +openclaw matrix profile set --name "OpenClaw Assistant" +openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Repárala con: +Añade `--account ` cuando quieras apuntar explícitamente a una cuenta de Matrix con nombre. -```bash -openclaw matrix direct repair --user-id @alice:example.org -``` - -La reparación mantiene la lógica específica de Matrix dentro del plugin: - -- prefiere una MD estricta 1:1 que ya esté asignada en `m.direct` -- en caso contrario, recurre a cualquier MD estricta 1:1 actualmente unida con ese usuario -- si no existe una MD en buen estado, crea una nueva sala directa y reescribe `m.direct` para que apunte a ella - -El flujo de reparación no elimina automáticamente las salas antiguas. Solo selecciona la MD en buen estado y actualiza la asignación para que los nuevos envíos de Matrix, avisos de verificación y otros flujos de mensajes directos vuelvan a apuntar a la sala correcta. +Matrix acepta directamente URL de avatar `mxc://`. Cuando pasas una URL de avatar `http://` o `https://`, OpenClaw la sube primero a Matrix y almacena la URL `mxc://` resuelta de vuelta en `channels.matrix.avatarUrl` (o en la sobrescritura de la cuenta seleccionada). ## Hilos -Matrix admite hilos nativos de Matrix tanto para respuestas automáticas como para envíos de herramientas de mensajes. +Matrix admite hilos nativos de Matrix tanto para respuestas automáticas como para envíos mediante herramientas de mensajes. -- `dm.sessionScope: "per-user"` (predeterminado) mantiene el enrutamiento de MD de Matrix con alcance por remitente, por lo que varias salas de MD pueden compartir una sesión cuando se resuelven al mismo par. -- `dm.sessionScope: "per-room"` aísla cada sala de MD de Matrix en su propia clave de sesión mientras sigue usando las comprobaciones normales de autenticación y allowlist de MD. -- Los enlaces explícitos de conversación de Matrix siguen teniendo prioridad sobre `dm.sessionScope`, por lo que las salas e hilos vinculados conservan su sesión de destino elegida. -- `threadReplies: "off"` mantiene las respuestas en el nivel superior y mantiene los mensajes entrantes en hilo en la sesión principal. +- `dm.sessionScope: "per-user"` (predeterminado) mantiene el enrutamiento de DM de Matrix acotado al remitente, de modo que varias salas de DM puedan compartir una sesión cuando se resuelven al mismo par. +- `dm.sessionScope: "per-room"` aísla cada sala de DM de Matrix en su propia clave de sesión mientras sigue usando las comprobaciones normales de autenticación y lista de permitidos para DM. +- Los enlaces explícitos de conversación de Matrix siguen teniendo prioridad sobre `dm.sessionScope`, de modo que las salas y los hilos enlazados mantienen su sesión de destino elegida. +- `threadReplies: "off"` mantiene las respuestas en el nivel superior y conserva los mensajes entrantes con hilo en la sesión principal. - `threadReplies: "inbound"` responde dentro de un hilo solo cuando el mensaje entrante ya estaba en ese hilo. -- `threadReplies: "always"` mantiene las respuestas de sala en un hilo enraizado en el mensaje que las activó y enruta esa conversación a través de la sesión con alcance de hilo coincidente desde el primer mensaje desencadenante. -- `dm.threadReplies` reemplaza la configuración de nivel superior solo para MD. Por ejemplo, puedes mantener aislados los hilos de sala mientras mantienes planas las MD. -- Los mensajes entrantes en hilos incluyen el mensaje raíz del hilo como contexto adicional para el agente. -- Los envíos de herramientas de mensajes ahora heredan automáticamente el hilo actual de Matrix cuando el destino es la misma sala, o el mismo destino de usuario de MD, a menos que se proporcione un `threadId` explícito. -- La reutilización del mismo objetivo de usuario de MD de la misma sesión solo se activa cuando los metadatos de la sesión actual prueban el mismo par de MD en la misma cuenta de Matrix; de lo contrario, OpenClaw vuelve al enrutamiento normal con alcance por usuario. -- Cuando OpenClaw detecta que una sala de MD de Matrix colisiona con otra sala de MD en la misma sesión compartida de MD de Matrix, publica un `m.notice` único en esa sala con la vía de escape `/focus` cuando los enlaces de hilos están habilitados y la sugerencia `dm.sessionScope`. -- Los enlaces de hilos en tiempo de ejecución son compatibles con Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` y `/acp spawn` vinculado a hilo ahora funcionan en salas y MD de Matrix. -- `/focus` de sala/MD de Matrix en nivel superior crea un nuevo hilo de Matrix y lo vincula a la sesión de destino cuando `threadBindings.spawnSubagentSessions=true`. -- Ejecutar `/focus` o `/acp spawn --thread here` dentro de un hilo existente de Matrix vincula ese hilo actual en su lugar. +- `threadReplies: "always"` mantiene las respuestas de la sala en un hilo con raíz en el mensaje que las activa y enruta esa conversación por la sesión acotada al hilo correspondiente desde el primer mensaje que la activa. +- `dm.threadReplies` sobrescribe la configuración de nivel superior solo para DMs. Por ejemplo, puedes mantener aislados los hilos de sala mientras mantienes planos los DMs. +- Los mensajes entrantes con hilo incluyen el mensaje raíz del hilo como contexto adicional para el agente. +- Los envíos mediante herramientas de mensajes heredan automáticamente el hilo actual de Matrix cuando el destino es la misma sala, o el mismo destino de usuario de DM, salvo que se proporcione un `threadId` explícito. +- La reutilización del mismo destino de usuario de DM y la misma sesión solo se activa cuando los metadatos de la sesión actual demuestran el mismo par de DM en la misma cuenta de Matrix; en caso contrario, OpenClaw vuelve al enrutamiento normal acotado al usuario. +- Cuando OpenClaw detecta que una sala de DM de Matrix entra en conflicto con otra sala de DM en la misma sesión compartida de DM de Matrix, publica un `m.notice` único en esa sala con la vía de escape `/focus` cuando los enlaces de hilos están habilitados y la pista `dm.sessionScope`. +- Se admiten enlaces de hilos en tiempo de ejecución para Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` y `/acp spawn` enlazado a hilo funcionan en salas y DMs de Matrix. +- `/focus` en una sala o DM de Matrix de nivel superior crea un nuevo hilo de Matrix y lo enlaza a la sesión de destino cuando `threadBindings.spawnSubagentSessions=true`. +- Ejecutar `/focus` o `/acp spawn --thread here` dentro de un hilo de Matrix existente enlaza ese hilo actual en su lugar. ## Enlaces de conversación ACP -Las salas, MD e hilos existentes de Matrix pueden convertirse en espacios de trabajo ACP duraderos sin cambiar la superficie de chat. +Las salas, DMs y hilos existentes de Matrix pueden convertirse en espacios de trabajo ACP duraderos sin cambiar la superficie de chat. Flujo rápido del operador: -- Ejecuta `/acp spawn codex --bind here` dentro de la MD, sala o hilo existente de Matrix que quieras seguir usando. -- En una MD o sala de Matrix de nivel superior, la MD/sala actual sigue siendo la superficie de chat y los mensajes futuros se enrutan a la sesión ACP generada. -- Dentro de un hilo existente de Matrix, `--bind here` vincula ese hilo actual en su lugar. -- `/new` y `/reset` restablecen la misma sesión ACP vinculada en su lugar. -- `/acp close` cierra la sesión ACP y elimina el vínculo. +- Ejecuta `/acp spawn codex --bind here` dentro del DM, la sala o el hilo existente de Matrix que quieras seguir usando. +- En un DM o sala de Matrix de nivel superior, el DM o la sala actual siguen siendo la superficie de chat y los mensajes futuros se enrutan a la sesión ACP creada. +- Dentro de un hilo existente de Matrix, `--bind here` enlaza ese hilo actual en su lugar. +- `/new` y `/reset` restablecen la misma sesión ACP enlazada en su lugar. +- `/acp close` cierra la sesión ACP y elimina el enlace. Notas: - `--bind here` no crea un hilo hijo de Matrix. -- `threadBindings.spawnAcpSessions` solo es necesario para `/acp spawn --thread auto|here`, donde OpenClaw necesita crear o vincular un hilo hijo de Matrix. +- `threadBindings.spawnAcpSessions` solo es necesario para `/acp spawn --thread auto|here`, donde OpenClaw necesita crear o enlazar un hilo hijo de Matrix. -### Configuración de enlaces de hilos +### Configuración de enlace de hilos -Matrix hereda los valores predeterminados globales de `session.threadBindings` y también admite anulaciones por canal: +Matrix hereda los valores predeterminados globales de `session.threadBindings`, y también admite sobrescrituras por canal: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -788,29 +714,29 @@ Matrix hereda los valores predeterminados globales de `session.threadBindings` y - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Las marcas de generación vinculadas a hilos de Matrix son opcionales: +Las marcas de creación enlazada a hilo de Matrix son opcionales: -- Establece `threadBindings.spawnSubagentSessions: true` para permitir que `/focus` de nivel superior cree y vincule nuevos hilos de Matrix. -- Establece `threadBindings.spawnAcpSessions: true` para permitir que `/acp spawn --thread auto|here` vincule sesiones ACP a hilos de Matrix. +- Establece `threadBindings.spawnSubagentSessions: true` para permitir que `/focus` de nivel superior cree y enlace nuevos hilos de Matrix. +- Establece `threadBindings.spawnAcpSessions: true` para permitir que `/acp spawn --thread auto|here` enlace sesiones ACP a hilos de Matrix. ## Reacciones -Matrix admite acciones de reacción salientes, notificaciones de reacción entrantes y reacciones de confirmación entrantes. +Matrix admite acciones salientes de reacciones, notificaciones entrantes de reacciones y reacciones entrantes de acuse. -- Las herramientas de reacción saliente están controladas por `channels["matrix"].actions.reactions`. +- Las herramientas salientes de reacción están controladas por `channels["matrix"].actions.reactions`. - `react` añade una reacción a un evento específico de Matrix. -- `reactions` enumera el resumen actual de reacciones para un evento específico de Matrix. -- `emoji=""` elimina las propias reacciones de la cuenta del bot en ese evento. +- `reactions` muestra el resumen actual de reacciones para un evento específico de Matrix. +- `emoji=""` elimina las reacciones propias de la cuenta del bot en ese evento. - `remove: true` elimina solo la reacción del emoji especificado de la cuenta del bot. -El alcance de las reacciones de confirmación se resuelve en este orden estándar de OpenClaw: +El ámbito de las reacciones de acuse se resuelve en este orden: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- emoji de respaldo de la identidad del agente +- alternativa del emoji de identidad del agente -El alcance de `ackReaction` se resuelve en este orden: +El alcance de la reacción de acuse se resuelve en este orden: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -822,33 +748,32 @@ El modo de notificación de reacciones se resuelve en este orden: - `channels["matrix"].reactionNotifications` - predeterminado: `own` -Comportamiento actual: +Comportamiento: -- `reactionNotifications: "own"` reenvía eventos `m.reaction` añadidos cuando apuntan a mensajes de Matrix creados por el bot. -- `reactionNotifications: "off"` deshabilita los eventos de sistema de reacciones. -- Las eliminaciones de reacciones todavía no se sintetizan en eventos de sistema porque Matrix las expone como redacciones, no como eliminaciones independientes de `m.reaction`. +- `reactionNotifications: "own"` reenvía eventos añadidos de `m.reaction` cuando apuntan a mensajes de Matrix escritos por el bot. +- `reactionNotifications: "off"` desactiva los eventos del sistema de reacciones. +- La eliminación de reacciones no se sintetiza en eventos del sistema porque Matrix los muestra como redacciones, no como eliminaciones independientes de `m.reaction`. ## Contexto del historial -- `channels.matrix.historyLimit` controla cuántos mensajes recientes de la sala se incluyen como `InboundHistory` cuando un mensaje de sala de Matrix activa al agente. -- Recurre a `messages.groupChat.historyLimit`. Si ambos no están configurados, el valor predeterminado efectivo es `0`, por lo que los mensajes de sala controlados por mención no se almacenan en búfer. Establece `0` para deshabilitarlo. -- El historial de salas de Matrix es solo de sala. Las MD siguen usando el historial normal de sesión. -- El historial de salas de Matrix es solo pendiente: OpenClaw almacena en búfer los mensajes de sala que todavía no activaron una respuesta y luego captura esa ventana cuando llega una mención u otro activador. +- `channels.matrix.historyLimit` controla cuántos mensajes recientes de la sala se incluyen como `InboundHistory` cuando un mensaje de una sala de Matrix activa al agente. Recurre a `messages.groupChat.historyLimit`; si ambos no están configurados, el valor efectivo predeterminado es `0`. Establece `0` para desactivar. +- El historial de salas de Matrix es solo de sala. Los DMs siguen usando el historial normal de sesión. +- El historial de salas de Matrix es solo pendiente: OpenClaw almacena en búfer los mensajes de sala que aún no han activado una respuesta, y luego toma una instantánea de esa ventana cuando llega una mención u otro activador. - El mensaje activador actual no se incluye en `InboundHistory`; permanece en el cuerpo principal entrante de ese turno. -- Los reintentos del mismo evento de Matrix reutilizan la instantánea original del historial en lugar de desviarse hacia mensajes más nuevos de la sala. +- Los reintentos del mismo evento de Matrix reutilizan la instantánea original del historial en lugar de avanzar con mensajes más nuevos de la sala. ## Visibilidad del contexto -Matrix admite el control compartido `contextVisibility` para contexto suplementario de sala, como texto de respuesta obtenido, raíces de hilo e historial pendiente. +Matrix admite el control compartido `contextVisibility` para contexto suplementario de la sala, como texto de respuesta recuperado, raíces de hilo e historial pendiente. -- `contextVisibility: "all"` es el valor predeterminado. El contexto suplementario se conserva tal como se recibió. -- `contextVisibility: "allowlist"` filtra el contexto suplementario a remitentes permitidos por las comprobaciones activas de allowlist de sala/usuario. +- `contextVisibility: "all"` es el valor predeterminado. El contexto suplementario se mantiene tal como se recibió. +- `contextVisibility: "allowlist"` filtra el contexto suplementario a remitentes permitidos por las comprobaciones activas de lista de permitidos de sala o usuario. - `contextVisibility: "allowlist_quote"` se comporta como `allowlist`, pero sigue conservando una respuesta citada explícita. -Esta configuración afecta la visibilidad del contexto suplementario, no si el propio mensaje entrante puede activar una respuesta. -La autorización del activador sigue viniendo de `groupPolicy`, `groups`, `groupAllowFrom` y la configuración de políticas de MD. +Esta configuración afecta a la visibilidad del contexto suplementario, no a si el mensaje entrante en sí puede activar una respuesta. +La autorización del activador sigue viniendo de `groupPolicy`, `groups`, `groupAllowFrom` y la configuración de la política de DM. -## Ejemplo de política de MD y sala +## Política de DM y sala ```json5 { @@ -871,64 +796,84 @@ La autorización del activador sigue viniendo de `groupPolicy`, `groups`, `group } ``` -Consulta [Grupos](/es/channels/groups) para el comportamiento de control por mención y allowlist. +Consulta [Groups](/es/channels/groups) para conocer el comportamiento de las menciones obligatorias y la lista de permitidos. -Ejemplo de emparejamiento para MD de Matrix: +Ejemplo de emparejamiento para DMs de Matrix: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Si un usuario de Matrix no aprobado sigue enviándote mensajes antes de la aprobación, OpenClaw reutiliza el mismo código de emparejamiento pendiente y puede volver a enviar una respuesta de recordatorio tras un breve enfriamiento en lugar de emitir un código nuevo. +Si un usuario de Matrix no aprobado sigue enviándote mensajes antes de la aprobación, OpenClaw reutiliza el mismo código pendiente de emparejamiento y puede enviar de nuevo una respuesta recordatoria tras un breve tiempo de espera en lugar de generar un código nuevo. -Consulta [Emparejamiento](/es/channels/pairing) para el flujo compartido de emparejamiento de MD y el diseño de almacenamiento. +Consulta [Pairing](/es/channels/pairing) para ver el flujo compartido de emparejamiento de DM y la distribución del almacenamiento. + +## Reparación directa de sala + +Si el estado de los mensajes directos se desincroniza, OpenClaw puede acabar con asignaciones `m.direct` obsoletas que apuntan a salas antiguas individuales en lugar del DM activo. Inspecciona la asignación actual para un par con: + +```bash +openclaw matrix direct inspect --user-id @alice:example.org +``` + +Repárala con: + +```bash +openclaw matrix direct repair --user-id @alice:example.org +``` + +El flujo de reparación: + +- prefiere un DM estricto 1:1 que ya esté asignado en `m.direct` +- recurre a cualquier DM estricto 1:1 actualmente unido con ese usuario +- crea una nueva sala directa y reescribe `m.direct` si no existe ningún DM saludable + +El flujo de reparación no elimina automáticamente las salas antiguas. Solo elige el DM saludable y actualiza la asignación para que los nuevos envíos de Matrix, los avisos de verificación y otros flujos de mensajes directos vuelvan a apuntar a la sala correcta. ## Aprobaciones de exec -Matrix puede actuar como cliente nativo de aprobación para una cuenta de Matrix. Los -controles nativos de enrutamiento de MD/canal siguen estando en la configuración de aprobación de exec: +Matrix puede actuar como cliente nativo de aprobación para una cuenta de Matrix. Los controles nativos +de enrutamiento de DM/canal siguen estando bajo la configuración de aprobación de exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (opcional; recurre a `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (opcional; usa `channels.matrix.dm.allowFrom` como alternativa) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, predeterminado: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Los aprobadores deben ser ID de usuario de Matrix, como `@owner:example.org`. Matrix habilita automáticamente las aprobaciones nativas cuando `enabled` no está configurado o es `"auto"` y se puede resolver al menos un aprobador. Las aprobaciones de exec usan primero `execApprovals.approvers` y pueden recurrir a `channels.matrix.dm.allowFrom`. Las aprobaciones de plugins autorizan a través de `channels.matrix.dm.allowFrom`. Establece `enabled: false` para deshabilitar explícitamente Matrix 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. +Los aprobadores deben ser ID de usuario de Matrix como `@owner:example.org`. Matrix habilita automáticamente las aprobaciones nativas cuando `enabled` no está configurado o es `"auto"` y se puede resolver al menos un aprobador. Las aprobaciones de exec usan primero `execApprovals.approvers` y pueden recurrir a `channels.matrix.dm.allowFrom`. Las aprobaciones de plugins autorizan mediante `channels.matrix.dm.allowFrom`. Establece `enabled: false` para desactivar explícitamente Matrix 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 alternativa de aprobación. -El enrutamiento nativo de Matrix ahora admite ambos tipos de aprobación: +El enrutamiento nativo de Matrix admite ambos tipos de aprobación: -- `channels.matrix.execApprovals.*` controla el modo nativo de distribución en MD/canal para los prompts de aprobación de Matrix. +- `channels.matrix.execApprovals.*` controla el modo nativo de distribución en DM/canal para los avisos de aprobación de Matrix. - Las aprobaciones de exec usan el conjunto de aprobadores de exec de `execApprovals.approvers` o `channels.matrix.dm.allowFrom`. -- Las aprobaciones de plugins usan la allowlist de MD de Matrix de `channels.matrix.dm.allowFrom`. -- Los atajos por reacción y las actualizaciones de mensajes de Matrix se aplican tanto a las aprobaciones de exec como a las de plugins. +- Las aprobaciones de plugins usan la lista de permitidos de DM de Matrix de `channels.matrix.dm.allowFrom`. +- Los atajos por reacción de Matrix y las actualizaciones de mensajes se aplican tanto a las aprobaciones de exec como a las de plugins. Reglas de entrega: -- `target: "dm"` envía los prompts de aprobación a las MD de los aprobadores -- `target: "channel"` envía el prompt de vuelta a la sala o MD de Matrix de origen -- `target: "both"` envía el prompt a las MD de los aprobadores y a la sala o MD de Matrix de origen +- `target: "dm"` envía avisos de aprobación a los DMs de los aprobadores +- `target: "channel"` envía el aviso de vuelta a la sala o DM original de Matrix +- `target: "both"` envía a los DMs de los aprobadores y a la sala o DM original de Matrix -Los prompts de aprobación de Matrix siembran atajos de reacción en el mensaje principal de aprobación: +Los avisos de aprobación de Matrix siembran atajos de reacción en el mensaje principal de aprobación: - `✅` = permitir una vez - `❌` = denegar -- `♾️` = permitir siempre cuando esa decisión está permitida por la política efectiva de exec +- `♾️` = permitir siempre cuando esa decisión esté permitida por la política efectiva de exec -Los aprobadores pueden reaccionar en ese mensaje o usar los comandos slash de respaldo: `/approve allow-once`, `/approve allow-always` o `/approve deny`. +Los aprobadores pueden reaccionar sobre ese mensaje o usar los comandos slash alternativos: `/approve allow-once`, `/approve allow-always`, o `/approve deny`. -Solo los aprobadores resueltos pueden aprobar o denegar. Para las aprobaciones de exec, la entrega por canal incluye el texto del comando, así que solo habilita `channel` o `both` en salas de confianza. +Solo los aprobadores resueltos pueden aprobar o denegar. Para aprobaciones de exec, la entrega por canal incluye el texto del comando, así que activa `channel` o `both` solo en salas de confianza. -Los prompts de aprobación de Matrix reutilizan el planificador compartido principal de aprobaciones. La superficie nativa específica de Matrix gestiona el enrutamiento de sala/MD, las reacciones y el comportamiento de envío/actualización/eliminación de mensajes tanto para las aprobaciones de exec como para las de plugins. - -Anulación por cuenta: +Sobrescritura por cuenta: - `channels.matrix.accounts..execApprovals` Documentación relacionada: [Aprobaciones de exec](/es/tools/exec-approvals) -## Ejemplo de varias cuentas +## Varias cuentas ```json5 { @@ -958,18 +903,20 @@ Documentación relacionada: [Aprobaciones de exec](/es/tools/exec-approvals) } ``` -Los valores de nivel superior `channels.matrix` actúan como predeterminados para las cuentas con nombre, a menos que una cuenta los reemplace. -Puedes limitar las entradas de sala heredadas a una cuenta de Matrix con `groups..account` (o el heredado `rooms..account`). -Las entradas sin `account` permanecen compartidas entre todas las cuentas de Matrix, y las entradas con `account: "default"` siguen funcionando cuando la cuenta predeterminada está configurada directamente en el nivel superior `channels.matrix.*`. -Los valores predeterminados parciales de autenticación compartida no crean por sí solos una cuenta predeterminada implícita independiente. OpenClaw solo sintetiza la cuenta `default` de nivel superior cuando esa cuenta predeterminada tiene autenticación nueva (`homeserver` más `accessToken`, o `homeserver` más `userId` y `password`); las cuentas con nombre pueden seguir siendo detectables a partir de `homeserver` más `userId` cuando las credenciales en caché satisfacen la autenticación más adelante. -Si Matrix ya tiene exactamente una cuenta con nombre, o `defaultAccount` apunta a una clave existente de cuenta con nombre, la promoción de reparación/configuración de una sola cuenta a varias cuentas conserva esa cuenta en lugar de crear una nueva entrada `accounts.default`. Solo las claves de autenticación/bootstrap de Matrix se mueven a esa cuenta promovida; las claves compartidas de política de entrega permanecen en el nivel superior. -Establece `defaultAccount` cuando quieras que OpenClaw prefiera una cuenta de Matrix con nombre para el enrutamiento implícito, sondeos y operaciones de CLI. -Si configuras varias cuentas con nombre, establece `defaultAccount` o pasa `--account ` para los comandos de CLI que dependan de la selección implícita de cuenta. -Pasa `--account ` a `openclaw matrix verify ...` y `openclaw matrix devices ...` cuando quieras anular esa selección implícita para un comando. +Los valores de nivel superior en `channels.matrix` actúan como valores predeterminados para las cuentas con nombre, a menos que una cuenta los sobrescriba. +Puedes acotar entradas de sala heredadas a una cuenta de Matrix con `groups..account`. +Las entradas sin `account` siguen compartidas entre todas las cuentas de Matrix, y las entradas con `account: "default"` siguen funcionando cuando la cuenta predeterminada se configura directamente en `channels.matrix.*` de nivel superior. +Los valores predeterminados parciales compartidos de autenticación no crean por sí mismos una cuenta predeterminada implícita aparte. OpenClaw solo sintetiza la cuenta `default` de nivel superior cuando ese valor predeterminado tiene autenticación reciente (`homeserver` más `accessToken`, o `homeserver` más `userId` y `password`); las cuentas con nombre pueden seguir siendo detectables a partir de `homeserver` más `userId` cuando las credenciales en caché satisfacen la autenticación más adelante. +Si Matrix ya tiene exactamente una cuenta con nombre, o `defaultAccount` apunta a una clave existente de cuenta con nombre, la reparación o promoción de configuración de una sola cuenta a varias cuentas conserva esa cuenta en lugar de crear una entrada nueva `accounts.default`. Solo las claves de autenticación o bootstrap de Matrix se mueven a esa cuenta promovida; las claves compartidas de política de entrega permanecen en el nivel superior. +Establece `defaultAccount` cuando quieras que OpenClaw prefiera una cuenta de Matrix con nombre para enrutamiento implícito, sondeos y operaciones de CLI. +Si configuras varias cuentas con nombre, establece `defaultAccount` o pasa `--account ` para los comandos CLI que dependen de la selección implícita de cuenta. +Pasa `--account ` a `openclaw matrix verify ...` y `openclaw matrix devices ...` cuando quieras sobrescribir esa selección implícita en un comando. + +Consulta [Referencia de configuración](/es/gateway/configuration-reference#multi-account-all-channels) para ver el patrón compartido de varias cuentas. ## Homeservers privados/LAN -De forma predeterminada, OpenClaw bloquea los homeservers de Matrix privados/internos por protección SSRF a menos que +De forma predeterminada, OpenClaw bloquea homeservers privados o internos de Matrix para protección SSRF, a menos que optes explícitamente por permitirlos por cuenta. Si tu homeserver se ejecuta en localhost, una IP LAN/Tailscale o un nombre de host interno, habilita @@ -989,7 +936,7 @@ Si tu homeserver se ejecuta en localhost, una IP LAN/Tailscale o un nombre de ho } ``` -Ejemplo de configuración por CLI: +Ejemplo de configuración desde CLI: ```bash openclaw matrix account add \ @@ -999,10 +946,10 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Esta aceptación explícita solo permite objetivos privados/internos de confianza. Los homeservers públicos en texto claro, como -`http://matrix.example.org:8008`, siguen bloqueados. Prefiere `https://` siempre que sea posible. +Esta aceptación explícita solo permite destinos privados o internos de confianza. Los homeservers públicos en texto claro como +`http://matrix.example.org:8008` siguen bloqueados. Prefiere `https://` siempre que sea posible. -## Uso de proxy para tráfico de Matrix +## Uso de proxy para el tráfico de Matrix Si tu despliegue de Matrix necesita un proxy HTTP(S) saliente explícito, establece `channels.matrix.proxy`: @@ -1018,78 +965,77 @@ Si tu despliegue de Matrix necesita un proxy HTTP(S) saliente explícito, establ } ``` -Las cuentas con nombre pueden anular el valor predeterminado de nivel superior con `channels.matrix.accounts..proxy`. -OpenClaw usa la misma configuración de proxy para el tráfico de Matrix en ejecución y para los sondeos de estado de la cuenta. +Las cuentas con nombre pueden sobrescribir el valor predeterminado de nivel superior con `channels.matrix.accounts..proxy`. +OpenClaw usa la misma configuración de proxy para el tráfico de Matrix en tiempo de ejecución y para los sondeos de estado de la cuenta. -## Resolución de objetivos +## Resolución de destinos -Matrix acepta estas formas de destino en cualquier lugar donde OpenClaw te pida un destino de sala o usuario: +Matrix acepta estos formatos de destino en cualquier lugar donde OpenClaw te pida un objetivo de sala o usuario: -- Usuarios: `@user:server`, `user:@user:server` o `matrix:user:@user:server` -- Salas: `!room:server`, `room:!room:server` o `matrix:room:!room:server` -- Alias: `#alias:server`, `channel:#alias:server` o `matrix:channel:#alias:server` +- Usuarios: `@user:server`, `user:@user:server`, o `matrix:user:@user:server` +- Salas: `!room:server`, `room:!room:server`, o `matrix:room:!room:server` +- Alias: `#alias:server`, `channel:#alias:server`, o `matrix:channel:#alias:server` -La búsqueda en vivo del directorio usa la cuenta de Matrix con sesión iniciada: +La búsqueda en directorio en vivo usa la cuenta de Matrix que ha iniciado sesión: -- Las búsquedas de usuarios consultan el directorio de usuarios de Matrix en ese homeserver. -- Las búsquedas de salas aceptan directamente IDs y alias de sala explícitos y luego recurren a la búsqueda de nombres de salas unidas para esa cuenta. -- La búsqueda por nombre de sala unida es de mejor esfuerzo. Si el nombre de una sala no puede resolverse a un ID o alias, se ignora en la resolución de allowlist en tiempo de ejecución. +- Las búsquedas de usuario consultan el directorio de usuarios de Matrix en ese homeserver. +- Las búsquedas de sala aceptan directamente ID y alias de sala explícitos, y después recurren a buscar nombres de salas unidas para esa cuenta. +- La búsqueda de nombres de salas unidas es de mejor esfuerzo. Si un nombre de sala no puede resolverse a un ID o alias, se ignora en la resolución de la lista de permitidos en tiempo de ejecución. ## Referencia de configuración - `enabled`: habilita o deshabilita el canal. - `name`: etiqueta opcional para la cuenta. -- `defaultAccount`: ID de cuenta preferido cuando hay varias cuentas de Matrix configuradas. +- `defaultAccount`: ID de cuenta preferido cuando se configuran varias cuentas de Matrix. - `homeserver`: URL del homeserver, por ejemplo `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: permite que esta cuenta de Matrix se conecte a homeservers privados/internos. Habilítalo cuando el homeserver se resuelva a `localhost`, una IP LAN/Tailscale o un host interno como `matrix-synapse`. -- `proxy`: URL opcional de proxy HTTP(S) para tráfico de Matrix. Las cuentas con nombre pueden reemplazar el valor predeterminado de nivel superior con su propio `proxy`. +- `network.dangerouslyAllowPrivateNetwork`: permite que esta cuenta de Matrix se conecte a homeservers privados o internos. Habilítalo cuando el homeserver se resuelva a `localhost`, una IP LAN/Tailscale o un host interno como `matrix-synapse`. +- `proxy`: URL opcional de proxy HTTP(S) para el tráfico de Matrix. Las cuentas con nombre pueden sobrescribir el valor predeterminado de nivel superior con su propio `proxy`. - `userId`: ID completo de usuario de Matrix, por ejemplo `@bot:example.org`. - `accessToken`: token de acceso para autenticación basada en token. Se admiten valores en texto plano y valores SecretRef para `channels.matrix.accessToken` y `channels.matrix.accounts..accessToken` en proveedores env/file/exec. Consulta [Gestión de secretos](/es/gateway/secrets). - `password`: contraseña para inicio de sesión basado en contraseña. Se admiten valores en texto plano y valores SecretRef. - `deviceId`: ID explícito del dispositivo de Matrix. -- `deviceName`: nombre para mostrar del dispositivo para inicio de sesión con contraseña. -- `avatarUrl`: URL almacenada del avatar propio para sincronización de perfil y actualizaciones `set-profile`. -- `initialSyncLimit`: límite de eventos de sincronización al iniciar. +- `deviceName`: nombre para mostrar del dispositivo en inicio de sesión con contraseña. +- `avatarUrl`: URL del avatar propio almacenada para sincronización de perfil y actualizaciones de `profile set`. +- `initialSyncLimit`: número máximo de eventos obtenidos durante la sincronización de inicio. - `encryption`: habilita E2EE. -- `allowlistOnly`: fuerza comportamiento solo con allowlist para MD y salas. -- `allowBots`: permite mensajes de otras cuentas configuradas de Matrix de OpenClaw (`true` o `"mentions"`). +- `allowlistOnly`: cuando es `true`, actualiza la política de sala `open` a `allowlist` y obliga a que todas las políticas DM activas excepto `disabled` (incluidas `pairing` y `open`) pasen a `allowlist`. No afecta a las políticas `disabled`. +- `allowBots`: permite mensajes de otras cuentas de Matrix de OpenClaw configuradas (`true` o `"mentions"`). - `groupPolicy`: `open`, `allowlist` o `disabled`. - `contextVisibility`: modo de visibilidad de contexto suplementario de sala (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: allowlist de ID de usuario para tráfico de sala. -- Las entradas de `groupAllowFrom` deben ser ID completos de usuario de Matrix. Los nombres no resueltos se ignoran en tiempo de ejecución. -- `historyLimit`: cantidad máxima de mensajes de sala que se incluirán como contexto de historial de grupo. Recurre a `messages.groupChat.historyLimit`; si ambos no están configurados, el valor predeterminado efectivo es `0`. Establece `0` para deshabilitarlo. -- `replyToMode`: `off`, `first`, `all` o `batched`. +- `groupAllowFrom`: lista de permitidos de ID de usuario para tráfico de sala. Las entradas deben ser ID completos de usuario de Matrix; los nombres no resueltos se ignoran en tiempo de ejecución. +- `historyLimit`: número máximo de mensajes de sala que se incluirán como contexto del historial de grupo. Recurre a `messages.groupChat.historyLimit`; si ambos no están configurados, el valor efectivo predeterminado es `0`. Establece `0` para desactivar. +- `replyToMode`: `off`, `first`, `all`, o `batched`. - `markdown`: configuración opcional de renderizado Markdown para texto saliente de Matrix. -- `streaming`: `off` (predeterminado), `partial`, `quiet`, `true` o `false`. `partial` y `true` habilitan actualizaciones de borrador basadas primero en vista previa con mensajes de texto normales de Matrix. `quiet` usa avisos de vista previa sin notificación para configuraciones autoalojadas de reglas push. -- `blockStreaming`: `true` habilita mensajes de progreso independientes para bloques completados del asistente mientras la vista previa en streaming del borrador está activa. -- `threadReplies`: `off`, `inbound` o `always`. -- `threadBindings`: anulaciones por canal para enrutamiento y ciclo de vida de sesiones vinculadas a hilos. -- `startupVerification`: modo automático de solicitud de autoverificación al iniciar (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: enfriamiento antes de reintentar solicitudes automáticas de verificación al iniciar. -- `textChunkLimit`: tamaño de fragmento de mensaje saliente. -- `chunkMode`: `length` o `newline`. -- `responsePrefix`: prefijo opcional de mensaje para respuestas salientes. -- `ackReaction`: anulación opcional de reacción de confirmación para este canal/cuenta. -- `ackReactionScope`: anulación opcional del alcance de reacción de confirmación (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). -- `reactionNotifications`: modo de notificación de reacciones entrantes (`own`, `off`). -- `mediaMaxMb`: límite de tamaño multimedia en MB para el manejo multimedia de Matrix. Se aplica a envíos salientes y al procesamiento multimedia entrante. -- `autoJoin`: política de unión automática a invitaciones (`always`, `allowlist`, `off`). Predeterminado: `off`. Esto se aplica a las invitaciones de Matrix en general, incluidas las invitaciones de estilo MD, no solo a las invitaciones de sala/grupo. OpenClaw toma esta decisión en el momento de la invitación, antes de poder clasificar con fiabilidad la sala unida como MD o grupo. -- `autoJoinAllowlist`: salas/alias permitidos cuando `autoJoin` es `allowlist`. Las entradas de alias se resuelven a IDs de sala durante el manejo de la invitación; OpenClaw no confía en el estado del alias afirmado por la sala invitada. -- `dm`: bloque de política de MD (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: controla el acceso a MD después de que OpenClaw se haya unido a la sala y la haya clasificado como MD. No cambia si una invitación se une automáticamente. -- Las entradas de `dm.allowFrom` deben ser ID completos de usuario de Matrix, a menos que ya las hayas resuelto mediante búsqueda en vivo del directorio. -- `dm.sessionScope`: `per-user` (predeterminado) o `per-room`. Usa `per-room` cuando quieras que cada sala de MD de Matrix mantenga contexto independiente incluso si el par es el mismo. -- `dm.threadReplies`: anulación de política de hilos solo para MD (`off`, `inbound`, `always`). Reemplaza la configuración de nivel superior `threadReplies` tanto para la ubicación de la respuesta como para el aislamiento de sesiones en MD. -- `execApprovals`: entrega nativa de aprobaciones de exec en Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `streaming`: `off` (predeterminado), `"partial"`, `"quiet"`, `true`, o `false`. `"partial"` y `true` habilitan actualizaciones de borrador con vista previa primero usando mensajes de texto normales de Matrix. `"quiet"` usa avisos de vista previa sin notificación para configuraciones autoalojadas con reglas push. `false` equivale a `"off"`. +- `blockStreaming`: `true` habilita mensajes de progreso separados para bloques completados del asistente mientras la vista previa de borrador en streaming está activa. +- `threadReplies`: `off`, `inbound`, o `always`. +- `threadBindings`: sobrescrituras por canal para enrutamiento y ciclo de vida de sesiones enlazadas a hilos. +- `startupVerification`: modo automático de solicitud de autoverificación al inicio (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: tiempo de espera antes de reintentar solicitudes automáticas de verificación al inicio. +- `textChunkLimit`: tamaño en caracteres de los fragmentos de mensajes salientes (se aplica cuando `chunkMode` es `length`). +- `chunkMode`: `length` divide mensajes por cantidad de caracteres; `newline` divide en límites de línea. +- `responsePrefix`: cadena opcional añadida al principio de todas las respuestas salientes de este canal. +- `ackReaction`: sobrescritura opcional de reacción de acuse para este canal o cuenta. +- `ackReactionScope`: sobrescritura opcional del alcance de la reacción de acuse (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `reactionNotifications`: modo de notificación entrante de reacciones (`own`, `off`). +- `mediaMaxMb`: límite de tamaño de medios en MB para envíos salientes y procesamiento de medios entrantes. +- `autoJoin`: política de unión automática a invitaciones (`always`, `allowlist`, `off`). Predeterminado: `off`. Se aplica a todas las invitaciones de Matrix, incluidas las invitaciones de estilo DM. +- `autoJoinAllowlist`: salas o alias permitidos cuando `autoJoin` es `allowlist`. Las entradas de alias se resuelven a ID de sala durante el manejo de la invitación; OpenClaw no confía en el estado del alias afirmado por la sala invitada. +- `dm`: bloque de política de DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). +- `dm.policy`: controla el acceso a DM después de que OpenClaw se haya unido a la sala y la haya clasificado como DM. No cambia si una invitación se une automáticamente o no. +- `dm.allowFrom`: las entradas deben ser ID completos de usuario de Matrix a menos que ya las hayas resuelto mediante búsqueda de directorio en vivo. +- `dm.sessionScope`: `per-user` (predeterminado) o `per-room`. Usa `per-room` cuando quieras que cada sala de DM de Matrix mantenga contexto separado aunque el par sea el mismo. +- `dm.threadReplies`: sobrescritura de política de hilos solo para DMs (`off`, `inbound`, `always`). Sobrescribe la configuración de nivel superior `threadReplies` tanto para la colocación de respuestas como para el aislamiento de sesión en DMs. +- `execApprovals`: entrega nativa de aprobaciones de exec de Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). - `execApprovals.approvers`: ID de usuario de Matrix autorizados para aprobar solicitudes de exec. Opcional cuando `dm.allowFrom` ya identifica a los aprobadores. - `execApprovals.target`: `dm | channel | both` (predeterminado: `dm`). -- `accounts`: anulaciones con nombre por cuenta. Los valores de nivel superior `channels.matrix` actúan como predeterminados para estas entradas. -- `groups`: mapa de políticas por sala. Prefiere IDs o alias de sala; los nombres de sala no resueltos se ignoran en tiempo de ejecución. La identidad de sesión/grupo usa el ID estable de sala después de la resolución, mientras que las etiquetas legibles por humanos siguen viniendo de los nombres de sala. -- `groups..account`: restringe una entrada heredada de sala a una cuenta específica de Matrix en configuraciones con varias cuentas. -- `groups..allowBots`: anulación a nivel de sala para remitentes de bots configurados (`true` o `"mentions"`). -- `groups..users`: allowlist de remitentes por sala. -- `groups..tools`: anulaciones por sala para permitir/denegar herramientas. -- `groups..autoReply`: anulación a nivel de sala para control por mención. `true` deshabilita los requisitos de mención para esa sala; `false` los vuelve a forzar. +- `accounts`: sobrescrituras con nombre por cuenta. Los valores de nivel superior en `channels.matrix` actúan como predeterminados para estas entradas. +- `groups`: mapa de políticas por sala. Prefiere ID o alias de sala; los nombres de sala no resueltos se ignoran en tiempo de ejecución. La identidad de sesión o grupo usa el ID de sala estable después de la resolución. +- `groups..account`: restringe una entrada de sala heredada a una cuenta de Matrix específica en configuraciones de varias cuentas. +- `groups..allowBots`: sobrescritura a nivel de sala para remitentes bot configurados (`true` o `"mentions"`). +- `groups..users`: lista de permitidos por remitente a nivel de sala. +- `groups..tools`: sobrescrituras por sala para permitir o denegar herramientas. +- `groups..autoReply`: sobrescritura a nivel de sala para el requisito de menciones. `true` desactiva los requisitos de mención para esa sala; `false` los vuelve a forzar. - `groups..skills`: filtro opcional de Skills a nivel de sala. - `groups..systemPrompt`: fragmento opcional de system prompt a nivel de sala. - `rooms`: alias heredado para `groups`. @@ -1098,7 +1044,7 @@ La búsqueda en vivo del directorio usa la cuenta de Matrix con sesión iniciada ## Relacionado - [Resumen de canales](/es/channels) — todos los canales compatibles -- [Emparejamiento](/es/channels/pairing) — autenticación de MD y flujo de emparejamiento -- [Grupos](/es/channels/groups) — comportamiento del chat grupal y control por mención +- [Pairing](/es/channels/pairing) — autenticación DM y flujo de emparejamiento +- [Groups](/es/channels/groups) — comportamiento de chat grupal y requisito de menciones - [Enrutamiento de canales](/es/channels/channel-routing) — enrutamiento de sesión para mensajes -- [Seguridad](/es/gateway/security) — modelo de acceso y refuerzo +- [Security](/es/gateway/security) — modelo de acceso y refuerzo diff --git a/docs/es/concepts/agent-loop.md b/docs/es/concepts/agent-loop.md index 73680b0c2..5d8bc399f 100644 --- a/docs/es/concepts/agent-loop.md +++ b/docs/es/concepts/agent-loop.md @@ -1,175 +1,176 @@ --- read_when: - - Necesitas un recorrido exacto del bucle del agente o de los eventos del ciclo de vida -summary: Ciclo de vida del bucle del agente, streams y semántica de espera + - Necesitas una guía exacta del bucle del agente o de los eventos del ciclo de vida +summary: Ciclo de vida del bucle del agente, flujos y semántica de espera title: Bucle del agente x-i18n: - generated_at: "2026-04-05T12:39:34Z" + generated_at: "2026-04-09T01:27:48Z" model: gpt-5.4 provider: openai - source_hash: 8e562e63c494881e9c345efcb93c5f972d69aaec61445afc3d4ad026b2d26883 + source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1 source_path: concepts/agent-loop.md workflow: 15 --- # Bucle del agente (OpenClaw) -Un bucle agéntico es la ejecución completa y “real” de un agente: entrada → ensamblaje de contexto → inferencia del modelo → +Un bucle agéntico es la ejecución “real” completa de un agente: entrada → ensamblaje de contexto → inferencia del modelo → ejecución de herramientas → respuestas en streaming → persistencia. Es la ruta autoritativa que convierte un mensaje en acciones y una respuesta final, mientras mantiene coherente el estado de la sesión. -En OpenClaw, un bucle es una única ejecución serializada por sesión que emite eventos de ciclo de vida y de stream -mientras el modelo piensa, llama herramientas y transmite salida. Este documento explica cómo está -conectado de extremo a extremo ese bucle auténtico. +En OpenClaw, un bucle es una sola ejecución serializada por sesión que emite eventos de ciclo de vida y de flujo +mientras el modelo piensa, llama herramientas y transmite la salida. Este documento explica cómo se conecta ese bucle auténtico de extremo a extremo. ## Puntos de entrada -- RPC del Gateway: `agent` y `agent.wait`. +- RPC del gateway: `agent` y `agent.wait`. - CLI: comando `agent`. -## Cómo funciona (alto nivel) +## Cómo funciona (visión general) -1. El RPC `agent` valida parámetros, resuelve la sesión (`sessionKey`/`sessionId`), conserva los metadatos de la sesión y devuelve `{ runId, acceptedAt }` de inmediato. +1. El RPC `agent` valida los parámetros, resuelve la sesión (sessionKey/sessionId), persiste los metadatos de la sesión y devuelve `{ runId, acceptedAt }` de inmediato. 2. `agentCommand` ejecuta el agente: - - resuelve el modelo y los valores predeterminados de thinking/verbose + - resuelve los valores predeterminados de modelo + thinking/verbose - carga la instantánea de Skills - - llama a `runEmbeddedPiAgent` (tiempo de ejecución de pi-agent-core) + - llama a `runEmbeddedPiAgent` (runtime de pi-agent-core) - emite **lifecycle end/error** si el bucle integrado no emite uno 3. `runEmbeddedPiAgent`: - - serializa ejecuciones mediante colas por sesión y una cola global - - resuelve el perfil de modelo y autenticación y construye la sesión de pi - - se suscribe a eventos de pi y transmite deltas del asistente y de herramientas + - serializa las ejecuciones mediante colas por sesión y una cola global + - resuelve el perfil de modelo + autenticación y construye la sesión de Pi + - se suscribe a los eventos de Pi y transmite los deltas del asistente/herramientas - aplica el tiempo de espera -> aborta la ejecución si se supera - - devuelve cargas útiles y metadatos de uso -4. `subscribeEmbeddedPiSession` conecta los eventos de pi-agent-core al stream `agent` de OpenClaw: - - eventos de herramienta => `stream: "tool"` + - devuelve payloads + metadatos de uso +4. `subscribeEmbeddedPiSession` conecta los eventos de pi-agent-core con el flujo `agent` de OpenClaw: + - eventos de herramientas => `stream: "tool"` - deltas del asistente => `stream: "assistant"` - eventos de ciclo de vida => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` usa `waitForAgentRun`: - espera **lifecycle end/error** para `runId` - devuelve `{ status: ok|error|timeout, startedAt, endedAt, error? }` -## Colas y concurrencia +## Cola + concurrencia -- Las ejecuciones se serializan por clave de sesión (carril de sesión) y, opcionalmente, mediante un carril global. -- Esto evita condiciones de carrera de herramientas o sesiones y mantiene coherente el historial de la sesión. +- Las ejecuciones se serializan por clave de sesión (carril de sesión) y, opcionalmente, a través de un carril global. +- Esto evita condiciones de carrera de herramientas/sesión y mantiene coherente el historial de la sesión. - Los canales de mensajería pueden elegir modos de cola (collect/steer/followup) que alimentan este sistema de carriles. - Consulta [Command Queue](/concepts/queue). + Consulta [Cola de comandos](/es/concepts/queue). -## Preparación de sesión y espacio de trabajo +## Preparación de sesión + espacio de trabajo -- El espacio de trabajo se resuelve y se crea; las ejecuciones en sandbox pueden redirigirse a una raíz de espacio de trabajo aislada. -- Se cargan Skills (o se reutilizan desde una instantánea) y se inyectan en el entorno y en el prompt. -- Los archivos de bootstrap/contexto se resuelven y se inyectan en el informe del prompt del sistema. +- El espacio de trabajo se resuelve y se crea; las ejecuciones en sandbox pueden redirigirse a una raíz de espacio de trabajo en sandbox. +- Las Skills se cargan (o se reutilizan desde una instantánea) y se inyectan en el entorno y en el prompt. +- Los archivos de bootstrap/contexto se resuelven y se inyectan en el informe del system prompt. - Se adquiere un bloqueo de escritura de sesión; `SessionManager` se abre y se prepara antes del streaming. -## Ensamblaje del prompt y prompt del sistema +## Ensamblaje del prompt + system prompt -- El prompt del sistema se construye a partir del prompt base de OpenClaw, el prompt de Skills, el contexto de bootstrap y las anulaciones por ejecución. -- Se aplican límites específicos del modelo y reservas de tokens para compactación. -- Consulta [System prompt](/concepts/system-prompt) para ver lo que ve el modelo. +- El system prompt se construye a partir del prompt base de OpenClaw, el prompt de Skills, el contexto de bootstrap y las anulaciones por ejecución. +- Se aplican los límites específicos del modelo y los tokens reservados para compactación. +- Consulta [System prompt](/es/concepts/system-prompt) para ver lo que ve el modelo. ## Puntos de hook (donde puedes interceptar) OpenClaw tiene dos sistemas de hooks: -- **Hooks internos** (hooks del Gateway): scripts controlados por eventos para comandos y eventos del ciclo de vida. -- **Hooks de plugin**: puntos de extensión dentro del ciclo de vida del agente o herramienta y de la canalización del gateway. +- **Hooks internos** (hooks del gateway): scripts impulsados por eventos para comandos y eventos del ciclo de vida. +- **Hooks de plugin**: puntos de extensión dentro del ciclo de vida del agente/herramientas y del pipeline del gateway. -### Hooks internos (hooks del Gateway) +### Hooks internos (hooks del gateway) -- **`agent:bootstrap`**: se ejecuta mientras se construyen archivos de bootstrap antes de que el prompt del sistema se finalice. - Úsalo para añadir o eliminar archivos de contexto de bootstrap. -- **Hooks de comandos**: `/new`, `/reset`, `/stop` y otros eventos de comandos (consulta la documentación de Hooks). +- **`agent:bootstrap`**: se ejecuta mientras se construyen los archivos de bootstrap antes de que se finalice el system prompt. + Úsalo para agregar o eliminar archivos de contexto de bootstrap. +- **Hooks de comandos**: `/new`, `/reset`, `/stop` y otros eventos de comandos (consulta el documento de Hooks). -Consulta [Hooks](/automation/hooks) para ver configuración y ejemplos. +Consulta [Hooks](/es/automation/hooks) para la configuración y ejemplos. -### Hooks de plugin (ciclo de vida del agente y del gateway) +### Hooks de plugin (ciclo de vida del agente + gateway) -Se ejecutan dentro del bucle del agente o de la canalización del gateway: +Estos se ejecutan dentro del bucle del agente o del pipeline del gateway: -- **`before_model_resolve`**: se ejecuta antes de la sesión (sin `messages`) para anular de forma determinista el proveedor o modelo antes de la resolución del modelo. -- **`before_prompt_build`**: se ejecuta después de cargar la sesión (con `messages`) para inyectar `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` antes del envío del prompt. Usa `prependContext` para texto dinámico por turno y campos de contexto del sistema para guía estable que deba situarse en el espacio del prompt del sistema. -- **`before_agent_start`**: hook heredado de compatibilidad que puede ejecutarse en cualquiera de las fases; prefiere los hooks explícitos anteriores. -- **`before_agent_reply`**: se ejecuta después de las acciones en línea y antes de la llamada al LLM, permitiendo que un plugin reclame el turno y devuelva una respuesta sintética o silencie completamente el turno. -- **`agent_end`**: inspecciona la lista final de mensajes y los metadatos de la ejecución tras completarse. -- **`before_compaction` / `after_compaction`**: observan o anotan ciclos de compactación. -- **`before_tool_call` / `after_tool_call`**: interceptan parámetros y resultados de herramientas. -- **`before_install`**: inspecciona hallazgos del análisis integrado y, opcionalmente, bloquea instalaciones de Skills o plugins. -- **`tool_result_persist`**: transforma sincrónicamente resultados de herramientas antes de que se escriban en la transcripción de la sesión. -- **`message_received` / `message_sending` / `message_sent`**: hooks de mensajes entrantes y salientes. +- **`before_model_resolve`**: se ejecuta antes de la sesión (sin `messages`) para anular de forma determinista el proveedor/modelo antes de la resolución del modelo. +- **`before_prompt_build`**: se ejecuta después de cargar la sesión (con `messages`) para inyectar `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` antes de enviar el prompt. Usa `prependContext` para texto dinámico por turno y los campos de contexto del sistema para guía estable que deba ubicarse en el espacio del system prompt. +- **`before_agent_start`**: hook heredado de compatibilidad que puede ejecutarse en cualquiera de las dos fases; prefiere los hooks explícitos anteriores. +- **`before_agent_reply`**: se ejecuta después de las acciones en línea y antes de la llamada al LLM, permitiendo que un plugin reclame el turno y devuelva una respuesta sintética o silencie el turno por completo. +- **`agent_end`**: inspecciona la lista final de mensajes y los metadatos de ejecución tras completarse. +- **`before_compaction` / `after_compaction`**: observan o anotan los ciclos de compactación. +- **`before_tool_call` / `after_tool_call`**: interceptan los parámetros/resultados de las herramientas. +- **`before_install`**: inspecciona los resultados del análisis integrado y, opcionalmente, bloquea instalaciones de Skills o plugins. +- **`tool_result_persist`**: transforma de forma síncrona los resultados de herramientas antes de que se escriban en la transcripción de la sesión. +- **`message_received` / `message_sending` / `message_sent`**: hooks de mensajes entrantes + salientes. - **`session_start` / `session_end`**: límites del ciclo de vida de la sesión. - **`gateway_start` / `gateway_stop`**: eventos del ciclo de vida del gateway. -Reglas de decisión de hooks para controles de salida y herramientas: +Reglas de decisión de hooks para guardas de salida/herramientas: -- `before_tool_call`: `{ block: true }` es terminal y detiene controladores de menor prioridad. -- `before_tool_call`: `{ block: false }` es una operación nula y no elimina un bloqueo previo. -- `before_install`: `{ block: true }` es terminal y detiene controladores de menor prioridad. -- `before_install`: `{ block: false }` es una operación nula y no elimina un bloqueo previo. -- `message_sending`: `{ cancel: true }` es terminal y detiene controladores de menor prioridad. -- `message_sending`: `{ cancel: false }` es una operación nula y no elimina una cancelación previa. +- `before_tool_call`: `{ block: true }` es terminal y detiene los manejadores de menor prioridad. +- `before_tool_call`: `{ block: false }` no hace nada y no elimina un bloqueo previo. +- `before_install`: `{ block: true }` es terminal y detiene los manejadores de menor prioridad. +- `before_install`: `{ block: false }` no hace nada y no elimina un bloqueo previo. +- `message_sending`: `{ cancel: true }` es terminal y detiene los manejadores de menor prioridad. +- `message_sending`: `{ cancel: false }` no hace nada y no elimina una cancelación previa. -Consulta [Plugin hooks](/plugins/architecture#provider-runtime-hooks) para ver la API de hooks y los detalles de registro. +Consulta [Hooks de plugin](/es/plugins/architecture#provider-runtime-hooks) para la API de hooks y los detalles de registro. -## Streaming y respuestas parciales +## Streaming + respuestas parciales - Los deltas del asistente se transmiten desde pi-agent-core y se emiten como eventos `assistant`. -- El streaming por bloques puede emitir respuestas parciales en `text_end` o `message_end`. -- El streaming de razonamiento puede emitirse como un stream separado o como respuestas por bloques. -- Consulta [Streaming](/concepts/streaming) para ver el comportamiento de fragmentación y respuestas por bloques. +- El streaming por bloques puede emitir respuestas parciales en `text_end` o en `message_end`. +- El streaming de razonamiento puede emitirse como un flujo independiente o como respuestas por bloques. +- Consulta [Streaming](/es/concepts/streaming) para el comportamiento de fragmentación y respuestas por bloques. -## Ejecución de herramientas y herramientas de mensajería +## Ejecución de herramientas + herramientas de mensajería -- Los eventos de inicio, actualización y fin de herramientas se emiten en el stream `tool`. -- Los resultados de herramientas se sanean en cuanto a tamaño y cargas útiles de imágenes antes de registrarse o emitirse. +- Los eventos de inicio/actualización/fin de herramientas se emiten en el flujo `tool`. +- Los resultados de herramientas se sanean por tamaño y payloads de imagen antes de registrarlos/emitirlos. - Los envíos de herramientas de mensajería se rastrean para suprimir confirmaciones duplicadas del asistente. -## Modelado de la respuesta y supresión +## Modelado de respuestas + supresión -- Las cargas útiles finales se ensamblan a partir de: +- Los payloads finales se ensamblan a partir de: - texto del asistente (y razonamiento opcional) - - resúmenes de herramientas en línea (cuando verbose + allowed) - - texto de error del asistente cuando el modelo falla -- El token silencioso exacto `NO_REPLY` / `no_reply` se filtra de las - cargas útiles salientes. -- Los duplicados de herramientas de mensajería se eliminan de la lista final de cargas útiles. -- Si no quedan cargas útiles representables y una herramienta falló, se emite - una respuesta alternativa de error de herramienta (a menos que una herramienta de mensajería ya haya enviado una respuesta visible para el usuario). + - resúmenes de herramientas en línea (cuando verbose + permitido) + - texto de error del asistente cuando falla el modelo +- El token silencioso exacto `NO_REPLY` / `no_reply` se filtra de los + payloads salientes. +- Los duplicados de herramientas de mensajería se eliminan de la lista final de payloads. +- Si no quedan payloads renderizables y una herramienta falló, se emite + una respuesta de error de herramienta de respaldo + (a menos que una herramienta de mensajería ya haya enviado una respuesta visible para el usuario). -## Compactación y reintentos +## Compactación + reintentos -- La compactación automática emite eventos de stream `compaction` y puede activar un reintento. -- En el reintento, se restablecen los búferes en memoria y los resúmenes de herramientas para evitar salida duplicada. -- Consulta [Compaction](/concepts/compaction) para ver la canalización de compactación. +- La compactación automática emite eventos de flujo `compaction` y puede activar un reintento. +- En un reintento, los búferes en memoria y los resúmenes de herramientas se restablecen para evitar salida duplicada. +- Consulta [Compactación](/es/concepts/compaction) para el pipeline de compactación. -## Streams de eventos (actualmente) +## Flujos de eventos (hoy) - `lifecycle`: emitido por `subscribeEmbeddedPiSession` (y como respaldo por `agentCommand`) -- `assistant`: deltas transmitidos desde pi-agent-core -- `tool`: eventos de herramientas transmitidos desde pi-agent-core +- `assistant`: deltas en streaming desde pi-agent-core +- `tool`: eventos de herramientas en streaming desde pi-agent-core ## Manejo del canal de chat - Los deltas del asistente se almacenan en búfer en mensajes `delta` del chat. -- Se emite un `final` del chat en **lifecycle end/error**. +- Se emite un `final` de chat en **lifecycle end/error**. ## Tiempos de espera -- Predeterminado de `agent.wait`: 30 s (solo la espera). El parámetro `timeoutMs` lo sustituye. -- Tiempo de ejecución del agente: valor predeterminado de `agents.defaults.timeoutSeconds` 172800 s (48 horas); se aplica en el temporizador de aborto de `runEmbeddedPiAgent`. +- Valor predeterminado de `agent.wait`: 30 s (solo la espera). El parámetro `timeoutMs` lo reemplaza. +- Runtime del agente: `agents.defaults.timeoutSeconds`, valor predeterminado 172800 s (48 horas); se aplica en el temporizador de aborto de `runEmbeddedPiAgent`. +- Tiempo de espera inactivo del LLM: `agents.defaults.llm.idleTimeoutSeconds` aborta una solicitud al modelo cuando no llegan fragmentos de respuesta antes de la ventana de inactividad. Establécelo explícitamente para modelos locales lentos o proveedores de razonamiento/llamadas a herramientas; establécelo en 0 para desactivarlo. Si no se establece, OpenClaw usa `agents.defaults.timeoutSeconds` cuando está configurado; de lo contrario, 60 s. Las ejecuciones activadas por cron sin tiempo de espera explícito del LLM o del agente desactivan el watchdog de inactividad y dependen del tiempo de espera externo del cron. -## Dónde puede terminar antes de tiempo +## Dónde las cosas pueden terminar antes de tiempo - Tiempo de espera del agente (aborto) - AbortSignal (cancelación) - Desconexión del gateway o tiempo de espera de RPC -- Tiempo de espera de `agent.wait` (solo espera, no detiene al agente) +- Tiempo de espera de `agent.wait` (solo de espera, no detiene al agente) ## Relacionado -- [Tools](/tools) — herramientas disponibles del agente -- [Hooks](/automation/hooks) — scripts controlados por eventos activados por eventos del ciclo de vida del agente -- [Compaction](/concepts/compaction) — cómo se resumen las conversaciones largas -- [Exec Approvals](/tools/exec-approvals) — puertas de aprobación para comandos de shell -- [Thinking](/tools/thinking) — configuración del nivel de thinking/razonamiento +- [Herramientas](/es/tools) — herramientas disponibles del agente +- [Hooks](/es/automation/hooks) — scripts impulsados por eventos activados por eventos del ciclo de vida del agente +- [Compactación](/es/concepts/compaction) — cómo se resumen las conversaciones largas +- [Aprobaciones de Exec](/es/tools/exec-approvals) — puertas de aprobación para comandos de shell +- [Thinking](/es/tools/thinking) — configuración del nivel de thinking/razonamiento diff --git a/docs/es/concepts/dreaming.md b/docs/es/concepts/dreaming.md index 877d86443..fbf314396 100644 --- a/docs/es/concepts/dreaming.md +++ b/docs/es/concepts/dreaming.md @@ -2,32 +2,32 @@ read_when: - Quieres que la promoción de memoria se ejecute automáticamente - Quieres entender qué hace cada fase de dreaming - - Quieres ajustar la consolidación sin contaminar MEMORY.md + - Quieres ajustar la consolidación sin contaminar `MEMORY.md` summary: Consolidación de memoria en segundo plano con fases ligera, profunda y REM, además de un Diario de Sueños title: Dreaming (experimental) x-i18n: - generated_at: "2026-04-06T05:12:22Z" + generated_at: "2026-04-09T01:27:48Z" model: gpt-5.4 provider: openai - source_hash: 36c4b1e70801d662090dc8ce20608c2f141c23cd7ce53c54e3dcf332c801fd4e + source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef source_path: concepts/dreaming.md workflow: 15 --- # Dreaming (experimental) -Dreaming es el sistema de consolidación de memoria en segundo plano de `memory-core`. -Ayuda a OpenClaw a mover señales fuertes de corto plazo a memoria duradera, mientras +Dreaming es el sistema de consolidación de memoria en segundo plano en `memory-core`. +Ayuda a OpenClaw a mover señales sólidas de corto plazo a memoria duradera mientras mantiene el proceso explicable y revisable. -Dreaming es **optativo** y está desactivado de forma predeterminada. +Dreaming es **optativo** y está deshabilitado de forma predeterminada. ## Qué escribe dreaming Dreaming mantiene dos tipos de salida: -- **Estado de máquina** en `memory/.dreams/` (almacén de recuperación, señales de fase, puntos de control de ingestión, bloqueos). -- **Salida legible por humanos** en `DREAMS.md` (o `dreams.md` existente) y archivos opcionales de informes de fase en `memory/dreaming//YYYY-MM-DD.md`. +- **Estado de máquina** en `memory/.dreams/` (almacén de recuperación, señales de fase, puntos de control de ingesta, bloqueos). +- **Salida legible por humanos** en `DREAMS.md` (o `dreams.md` existente) y archivos opcionales de informe de fase en `memory/dreaming//YYYY-MM-DD.md`. La promoción a largo plazo sigue escribiendo solo en `MEMORY.md`. @@ -35,33 +35,33 @@ La promoción a largo plazo sigue escribiendo solo en `MEMORY.md`. Dreaming usa tres fases cooperativas: -| Fase | Propósito | Escritura duradera | -| ----- | --------- | ------------------ | -| Ligera | Ordenar y preparar material reciente de corto plazo | No | -| Profunda | Puntuar y promover candidatos duraderos | Sí (`MEMORY.md`) | -| REM | Reflexionar sobre temas e ideas recurrentes | No | +| Fase | Propósito | Escritura duradera | +| ----- | ----------------------------------------- | ------------------ | +| Light | Ordenar y preparar material reciente de corto plazo | No | +| Deep | Puntuar y promover candidatos duraderos | Sí (`MEMORY.md`) | +| REM | Reflexionar sobre temas e ideas recurrentes | No | Estas fases son detalles internos de implementación, no "modos" -separados configurados por el usuario. +configurables por el usuario por separado. -### Fase ligera +### Fase Light -La fase ligera ingiere señales recientes de memoria diaria y rastros de recuperación, los deduplica +La fase Light ingiere señales recientes de memoria diaria y rastros de recuperación, los deduplica y prepara líneas candidatas. -- Lee del estado de recuperación a corto plazo y de archivos recientes de memoria diaria. +- Lee del estado de recuperación de corto plazo, archivos recientes de memoria diaria y transcripciones de sesión redactadas cuando están disponibles. - Escribe un bloque administrado `## Light Sleep` cuando el almacenamiento incluye salida en línea. - Registra señales de refuerzo para una clasificación profunda posterior. - Nunca escribe en `MEMORY.md`. -### Fase profunda +### Fase Deep -La fase profunda decide qué se convierte en memoria a largo plazo. +La fase Deep decide qué pasa a convertirse en memoria a largo plazo. -- Clasifica candidatos usando puntuación ponderada y umbrales de acceso. +- Clasifica los candidatos usando puntuación ponderada y umbrales de validación. - Requiere que `minScore`, `minRecallCount` y `minUniqueQueries` se cumplan. - Rehidrata fragmentos desde archivos diarios activos antes de escribir, por lo que se omiten los fragmentos obsoletos o eliminados. -- Agrega entradas promovidas a `MEMORY.md`. +- Agrega las entradas promovidas a `MEMORY.md`. - Escribe un resumen `## Deep Sleep` en `DREAMS.md` y, opcionalmente, escribe `memory/dreaming/deep/YYYY-MM-DD.md`. ### Fase REM @@ -73,40 +73,62 @@ La fase REM extrae patrones y señales reflexivas. - Registra señales de refuerzo REM usadas por la clasificación profunda. - Nunca escribe en `MEMORY.md`. +## Ingesta de transcripciones de sesión + +Dreaming puede ingerir transcripciones de sesión redactadas en el corpus de dreaming. Cuando +las transcripciones están disponibles, se incorporan en la fase Light junto con señales de +memoria diaria y rastros de recuperación. El contenido personal y sensible se redacta +antes de la ingesta. + ## Diario de Sueños Dreaming también mantiene un **Diario de Sueños** narrativo en `DREAMS.md`. Después de que cada fase tiene suficiente material, `memory-core` ejecuta un turno -de subagente en segundo plano de mejor esfuerzo (usando el modelo de runtime predeterminado) y agrega una entrada breve al diario. +de subagente en segundo plano de mejor esfuerzo (usando el modelo de runtime predeterminado) +y agrega una entrada breve del diario. -Este diario es para lectura humana en la UI de Dreams, no una fuente de promoción. +Este diario es para lectura humana en la IU de Dreams, no una fuente de promoción. + +También existe una vía de relleno histórico fundamentado para trabajo de revisión y recuperación: + +- `memory rem-harness --path ... --grounded` previsualiza la salida del diario fundamentado a partir de notas históricas `YYYY-MM-DD.md`. +- `memory rem-backfill --path ...` escribe entradas fundamentadas reversibles del diario en `DREAMS.md`. +- `memory rem-backfill --path ... --stage-short-term` prepara candidatos duraderos fundamentados en el mismo almacén de evidencias de corto plazo que la fase Deep normal ya usa. +- `memory rem-backfill --rollback` y `--rollback-short-term` eliminan esos artefactos de relleno preparados sin tocar las entradas normales del diario ni la recuperación activa de corto plazo. + +La IU de Control expone el mismo flujo de relleno/restablecimiento del diario para que puedas inspeccionar +los resultados en la escena de Dreams antes de decidir si los candidatos fundamentados +merecen promoción. La escena también muestra una vía fundamentada distinta para que puedas ver +qué entradas preparadas de corto plazo provinieron de la reproducción histórica, qué elementos promovidos +fueron impulsados por la vía fundamentada, y borrar solo las entradas preparadas exclusivamente fundamentadas sin +tocar el estado normal activo de corto plazo. ## Señales de clasificación profunda La clasificación profunda usa seis señales base ponderadas más refuerzo de fase: -| Señal | Peso | Descripción | -| ------ | ---- | ----------- | -| Frecuencia | 0.24 | Cuántas señales de corto plazo acumuló la entrada | -| Relevancia | 0.30 | Calidad media de recuperación de la entrada | +| Señal | Peso | Descripción | +| ------------------- | ---- | ------------------------------------------------- | +| Frecuencia | 0.24 | Cuántas señales de corto plazo acumuló la entrada | +| Relevancia | 0.30 | Calidad media de recuperación de la entrada | | Diversidad de consultas | 0.15 | Contextos distintos de consulta/día en que apareció | -| Recencia | 0.15 | Puntuación de frescura con decaimiento temporal | -| Consolidación | 0.10 | Fuerza de recurrencia en varios días | -| Riqueza conceptual | 0.06 | Densidad de etiquetas conceptuales del fragmento/ruta | +| Recencia | 0.15 | Puntuación de frescura con decaimiento temporal | +| Consolidación | 0.10 | Fuerza de recurrencia en varios días | +| Riqueza conceptual | 0.06 | Densidad de etiquetas conceptuales del fragmento/ruta | -Los aciertos de las fases ligera y REM añaden un pequeño refuerzo con decaimiento por recencia desde +Los aciertos de las fases Light y REM agregan un pequeño impulso con decaimiento por recencia desde `memory/.dreams/phase-signals.json`. ## Programación -Cuando está habilitado, `memory-core` administra automáticamente una tarea cron para un barrido -completo de dreaming. Cada barrido ejecuta las fases en orden: ligera -> REM -> profunda. +Cuando está habilitado, `memory-core` administra automáticamente un trabajo cron para un barrido +completo de dreaming. Cada barrido ejecuta las fases en orden: light -> REM -> deep. Comportamiento predeterminado de la cadencia: -| Configuración | Predeterminado | -| ------------- | -------------- | -| `dreaming.frequency` | `0 3 * * *` | +| Ajuste | Predeterminado | +| -------------------- | -------------- | +| `dreaming.frequency` | `0 3 * * *` | ## Inicio rápido @@ -148,7 +170,7 @@ Habilitar dreaming con una cadencia de barrido personalizada: } ``` -## Comando de barra +## Comando de barra inclinada ``` /dreaming status @@ -159,7 +181,7 @@ Habilitar dreaming con una cadencia de barrido personalizada: ## Flujo de trabajo de la CLI -Usa la promoción de la CLI para vista previa o aplicación manual: +Usa la promoción de la CLI para previsualizar o aplicar manualmente: ```bash openclaw memory promote @@ -168,8 +190,8 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -La ejecución manual de `memory promote` usa los umbrales de la fase profunda de forma predeterminada, salvo que se sobrescriban -con flags de la CLI. +`memory promote` manual usa umbrales de la fase Deep de forma predeterminada, a menos que se reemplacen +con banderas de la CLI. Explica por qué un candidato específico se promovería o no: @@ -178,7 +200,7 @@ openclaw memory promote-explain "router vlan" openclaw memory promote-explain "router vlan" --json ``` -Obtén una vista previa de reflexiones REM, verdades candidatas y salida de promoción profunda sin +Previsualiza reflexiones REM, verdades candidatas y salida de promoción profunda sin escribir nada: ```bash @@ -188,28 +210,29 @@ openclaw memory rem-harness --json ## Valores predeterminados clave -Todas las configuraciones viven en `plugins.entries.memory-core.config.dreaming`. +Todos los ajustes están en `plugins.entries.memory-core.config.dreaming`. -| Clave | Predeterminado | -| ----- | -------------- | -| `enabled` | `false` | -| `frequency` | `0 3 * * *` | +| Clave | Predeterminado | +| ----------- | -------------- | +| `enabled` | `false` | +| `frequency` | `0 3 * * *` | La política de fases, los umbrales y el comportamiento de almacenamiento son detalles internos de implementación -(no son configuración orientada al usuario). +(no configuración orientada al usuario). Consulta la [referencia de configuración de Memory](/es/reference/memory-config#dreaming-experimental) para ver la lista completa de claves. -## UI de Dreams +## IU de Dreams -Cuando está habilitada, la pestaña **Dreams** del Gateway muestra: +Cuando está habilitada, la pestaña **Dreams** de Gateway muestra: -- estado actual de habilitación de dreaming +- estado actual de dreaming habilitado - estado a nivel de fase y presencia de barrido administrado -- recuentos de corto plazo, largo plazo y promovidos hoy -- hora de la siguiente ejecución programada -- un lector expandible del Diario de Sueños respaldado por `doctor.memory.dreamDiary` +- recuentos de corto plazo, fundamentados, de señales y promovidos hoy +- hora de la próxima ejecución programada +- una vía de escena fundamentada distinta para entradas preparadas de reproducción histórica +- un lector expandible de Diario de Sueños respaldado por `doctor.memory.dreamDiary` ## Relacionado diff --git a/docs/es/concepts/memory.md b/docs/es/concepts/memory.md index 1ad008141..cd65c0e12 100644 --- a/docs/es/concepts/memory.md +++ b/docs/es/concepts/memory.md @@ -5,10 +5,10 @@ read_when: summary: Cómo OpenClaw recuerda cosas entre sesiones title: Descripción general de la memoria x-i18n: - generated_at: "2026-04-08T05:03:03Z" + generated_at: "2026-04-09T01:27:44Z" model: gpt-5.4 provider: openai - source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af + source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059 source_path: concepts/memory.md workflow: 15 --- @@ -28,76 +28,80 @@ Tu agente tiene tres archivos relacionados con la memoria: - **`memory/YYYY-MM-DD.md`** -- notas diarias. Contexto y observaciones en curso. Las notas de hoy y de ayer se cargan automáticamente. - **`DREAMS.md`** (experimental, opcional) -- Diario de sueños y resúmenes de - barridos de sueño para revisión humana. + barridos de sueño para revisión humana, incluidas entradas de relleno + histórico fundamentado. Estos archivos viven en el espacio de trabajo del agente (predeterminado `~/.openclaw/workspace`). Si quieres que tu agente recuerde algo, solo pídeselo: "Recuerda que prefiero -TypeScript." Lo escribirá en el archivo adecuado. +TypeScript". Lo escribirá en el archivo adecuado. ## Herramientas de memoria El agente tiene dos herramientas para trabajar con la memoria: -- **`memory_search`** -- encuentra notas relevantes mediante búsqueda - semántica, incluso cuando la redacción difiere de la original. -- **`memory_get`** -- lee un archivo de memoria específico o un intervalo de - líneas. +- **`memory_search`** -- encuentra notas relevantes usando búsqueda semántica, + incluso cuando la redacción difiere del original. +- **`memory_get`** -- lee un archivo de memoria específico o un rango de líneas. -Ambas herramientas las proporciona el plugin de memoria activo (predeterminado: `memory-core`). +Ambas herramientas las proporciona el plugin de memoria activo +(predeterminado: `memory-core`). -## Plugin complementario Memory Wiki +## Plugin complementario de Wiki de memoria -Si quieres que la memoria duradera se comporte más como una base de conocimiento mantenida que -como simples notas sin procesar, usa el plugin integrado `memory-wiki`. +Si quieres que la memoria duradera se comporte más como una base de +conocimiento mantenida que como simples notas sin procesar, usa el plugin +incluido `memory-wiki`. `memory-wiki` compila el conocimiento duradero en una bóveda wiki con: - estructura de páginas determinista -- afirmaciones y evidencia estructuradas -- seguimiento de contradicciones y vigencia +- afirmaciones y evidencias estructuradas +- seguimiento de contradicciones y actualidad - paneles generados -- resúmenes compilados para consumidores del agente/runtime +- resúmenes compilados para consumidores de agente/runtime - herramientas nativas de wiki como `wiki_search`, `wiki_get`, `wiki_apply` y `wiki_lint` No reemplaza al plugin de memoria activo. El plugin de memoria activo sigue -encargándose de la recuperación, la promoción y el sueño. `memory-wiki` añade una -capa de conocimiento rica en procedencia a su lado. +siendo responsable de la recuperación, la promoción y el sueño. `memory-wiki` +añade una capa de conocimiento rica en procedencia junto a él. Consulta [Memory Wiki](/es/plugins/memory-wiki). -## Búsqueda en memoria +## Búsqueda de memoria -Cuando hay configurado un proveedor de embeddings, `memory_search` usa -**búsqueda híbrida** -- combinando similitud vectorial (significado semántico) con coincidencia por palabras clave -(términos exactos como ID y símbolos de código). Esto funciona de inmediato en cuanto tengas -una clave de API para cualquier proveedor compatible. +Cuando se configura un proveedor de embeddings, `memory_search` usa **búsqueda +híbrida**: combina similitud vectorial (significado semántico) con coincidencia +por palabras clave (términos exactos como identificadores y símbolos de código). +Esto funciona de inmediato en cuanto tengas una clave de API para cualquier +proveedor compatible. -OpenClaw detecta automáticamente tu proveedor de embeddings a partir de las claves de API disponibles. Si -tienes configurada una clave de OpenAI, Gemini, Voyage o Mistral, la búsqueda en memoria se -habilita automáticamente. +OpenClaw detecta automáticamente tu proveedor de embeddings a partir de las +claves de API disponibles. Si tienes configurada una clave de OpenAI, Gemini, +Voyage o Mistral, la búsqueda de memoria se habilita automáticamente. -Para obtener detalles sobre cómo funciona la búsqueda, las opciones de ajuste y la configuración del proveedor, consulta +Para obtener detalles sobre cómo funciona la búsqueda, las opciones de ajuste y +la configuración del proveedor, consulta [Memory Search](/es/concepts/memory-search). ## Backends de memoria -Basado en SQLite. Funciona de inmediato con búsqueda por palabras clave, similitud vectorial y -búsqueda híbrida. Sin dependencias adicionales. +Basado en SQLite. Funciona de inmediato con búsqueda por palabras clave, +similitud vectorial y búsqueda híbrida. Sin dependencias adicionales. -Sidecar local-first con reranking, expansión de consultas y la capacidad de indexar -directorios fuera del espacio de trabajo. +Sidecar local-first con reranking, expansión de consultas y la capacidad de +indexar directorios fuera del espacio de trabajo. -Memoria entre sesiones nativa para IA con modelado de usuario, búsqueda semántica y -conocimiento de múltiples agentes. Instalación mediante plugin. +Memoria nativa de IA entre sesiones con modelado de usuario, búsqueda semántica +y conocimiento multiagente. Requiere instalación del plugin. @@ -105,59 +109,100 @@ conocimiento de múltiples agentes. Instalación mediante plugin. -Compila la memoria duradera en una bóveda wiki rica en procedencia con afirmaciones, -paneles, modo puente y flujos de trabajo compatibles con Obsidian. +Compila la memoria duradera en una bóveda wiki rica en procedencia con +afirmaciones, paneles, modo puente y flujos de trabajo compatibles con Obsidian. ## Vaciado automático de memoria -Antes de que la [compactación](/es/concepts/compaction) resuma tu conversación, OpenClaw -ejecuta un turno silencioso que recuerda al agente que guarde el contexto importante en archivos -de memoria. Esto está activado de forma predeterminada; no necesitas configurar nada. +Antes de que la [compactación](/es/concepts/compaction) resuma tu conversación, +OpenClaw ejecuta un turno silencioso que recuerda al agente que guarde el +contexto importante en archivos de memoria. Esto está activado de forma +predeterminada; no necesitas configurar nada. -El vaciado de memoria evita la pérdida de contexto durante la compactación. Si tu agente tiene -hechos importantes en la conversación que todavía no se han escrito en un archivo, -se guardarán automáticamente antes de que ocurra el resumen. +El vaciado de memoria evita la pérdida de contexto durante la compactación. Si +tu agente tiene hechos importantes en la conversación que todavía no están +escritos en un archivo, se guardarán automáticamente antes de que ocurra el +resumen. ## Sueño (experimental) -El sueño es un proceso opcional de consolidación en segundo plano para la memoria. Recopila -señales a corto plazo, puntúa candidatos y promueve solo los elementos que cumplen los requisitos a la -memoria a largo plazo (`MEMORY.md`). +El sueño es un proceso opcional de consolidación de memoria en segundo plano. +Recopila señales a corto plazo, puntúa candidatos y promueve solo los elementos +que cumplen los requisitos a la memoria a largo plazo (`MEMORY.md`). -Está diseñado para mantener alta la relación señal-ruido de la memoria a largo plazo: +Está diseñado para mantener la memoria a largo plazo con alta señal: -- **Optativo**: desactivado de forma predeterminada. -- **Programado**: cuando está activado, `memory-core` gestiona automáticamente un trabajo cron recurrente - para un barrido completo de sueño. -- **Con umbrales**: las promociones deben superar filtros de puntuación, frecuencia de recuperación y - diversidad de consultas. -- **Revisable**: los resúmenes de fase y las entradas del diario se escriben en `DREAMS.md` - para revisión humana. +- **Participación voluntaria**: desactivado de forma predeterminada. +- **Programado**: cuando está activado, `memory-core` gestiona automáticamente + un trabajo cron recurrente para un barrido completo de sueño. +- **Con umbrales**: las promociones deben superar filtros de puntuación, + frecuencia de recuperación y diversidad de consultas. +- **Revisable**: los resúmenes de fase y las entradas del diario se escriben en + `DREAMS.md` para revisión humana. -Para conocer el comportamiento por fases, las señales de puntuación y los detalles del Diario de sueños, consulta -[Sueño (experimental)](/es/concepts/dreaming). +Para el comportamiento de las fases, las señales de puntuación y los detalles +del Diario de sueños, consulta [Dreaming (experimental)](/es/concepts/dreaming). + +## Relleno fundamentado y promoción en vivo + +El sistema de sueño ahora tiene dos vías de revisión estrechamente +relacionadas: + +- **Sueño en vivo** funciona a partir del almacén de sueño a corto plazo en + `memory/.dreams/` y es lo que usa la fase profunda normal al decidir qué + puede graduarse a `MEMORY.md`. +- **Relleno fundamentado** lee notas históricas `memory/YYYY-MM-DD.md` como + archivos de día independientes y escribe una salida de revisión estructurada + en `DREAMS.md`. + +El relleno fundamentado es útil cuando quieres volver a procesar notas antiguas +e inspeccionar lo que el sistema considera duradero sin editar manualmente +`MEMORY.md`. + +Cuando usas: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +los candidatos duraderos fundamentados no se promueven directamente. Se preparan +en el mismo almacén de sueño a corto plazo que la fase profunda normal ya usa. +Eso significa que: + +- `DREAMS.md` sigue siendo la superficie de revisión humana. +- el almacén a corto plazo sigue siendo la superficie de clasificación orientada a máquinas. +- `MEMORY.md` sigue siendo escrito solo por la promoción profunda. + +Si decides que la repetición no fue útil, puedes eliminar los artefactos +preparados sin tocar las entradas normales del diario ni el estado normal de +recuperación: + +```bash +openclaw memory rem-backfill --rollback +openclaw memory rem-backfill --rollback-short-term +``` ## CLI ```bash -openclaw memory status # Check index status and provider -openclaw memory search "query" # Search from the command line -openclaw memory index --force # Rebuild the index +openclaw memory status # Comprobar el estado del índice y el proveedor +openclaw memory search "query" # Buscar desde la línea de comandos +openclaw memory index --force # Reconstruir el índice ``` -## Más información +## Lecturas adicionales -- [Builtin Memory Engine](/es/concepts/memory-builtin) -- backend SQLite predeterminado +- [Builtin Memory Engine](/es/concepts/memory-builtin) -- backend predeterminado de SQLite - [QMD Memory Engine](/es/concepts/memory-qmd) -- sidecar local-first avanzado -- [Honcho Memory](/es/concepts/memory-honcho) -- memoria entre sesiones nativa para IA +- [Honcho Memory](/es/concepts/memory-honcho) -- memoria nativa de IA entre sesiones - [Memory Wiki](/es/plugins/memory-wiki) -- bóveda de conocimiento compilada y herramientas nativas de wiki - [Memory Search](/es/concepts/memory-search) -- canalización de búsqueda, proveedores y ajuste - [Dreaming (experimental)](/es/concepts/dreaming) -- promoción en segundo plano - de la recuperación a corto plazo a la memoria a largo plazo + desde la recuperación a corto plazo hasta la memoria a largo plazo - [Memory configuration reference](/es/reference/memory-config) -- todas las opciones de configuración - [Compaction](/es/concepts/compaction) -- cómo interactúa la compactación con la memoria diff --git a/docs/es/concepts/model-providers.md b/docs/es/concepts/model-providers.md index 190e002ba..b68b33b05 100644 --- a/docs/es/concepts/model-providers.md +++ b/docs/es/concepts/model-providers.md @@ -1,14 +1,14 @@ --- read_when: - Necesitas una referencia de configuración de modelos proveedor por proveedor - - Quieres configuraciones de ejemplo o comandos de incorporación de la CLI para proveedores de modelos -summary: Descripción general de los proveedores de modelos con configuraciones de ejemplo + flujos de la CLI + - Quieres configuraciones de ejemplo o comandos de incorporación por CLI para proveedores de modelos +summary: Resumen de proveedores de modelos con configuraciones de ejemplo + flujos de CLI title: Proveedores de modelos x-i18n: - generated_at: "2026-04-08T05:04:33Z" + generated_at: "2026-04-09T01:29:09Z" model: gpt-5.4 provider: openai - source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9 + source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b source_path: concepts/model-providers.md workflow: 15 --- @@ -20,21 +20,22 @@ Para las reglas de selección de modelos, consulta [/concepts/models](/es/concep ## Reglas rápidas -- Las referencias de modelo usan `provider/model` (ejemplo: `opencode/claude-opus-4-6`). -- Si configuras `agents.defaults.models`, se convierte en la lista permitida. -- Ayudantes de la CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Las reglas de runtime de fallback, las sondas de enfriamiento y la persistencia de las anulaciones de sesión - se documentan en [/concepts/model-failover](/es/concepts/model-failover). +- Las referencias de modelos usan `provider/model` (ejemplo: `opencode/claude-opus-4-6`). +- Si configuras `agents.defaults.models`, se convierte en la lista de permitidos. +- Ayudantes de CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. +- Las reglas de tiempo de ejecución de respaldo, las sondas de enfriamiento y la persistencia de anulaciones por sesión + están documentadas en [/concepts/model-failover](/es/concepts/model-failover). - `models.providers.*.models[].contextWindow` son metadatos nativos del modelo; - `models.providers.*.models[].contextTokens` es el límite efectivo del runtime. -- Los plugins de proveedor pueden inyectar catálogos de modelos mediante `registerProvider({ catalog })`; + `models.providers.*.models[].contextTokens` es el límite efectivo en tiempo de ejecución. +- Los plugins de proveedores pueden inyectar catálogos de modelos mediante `registerProvider({ catalog })`; OpenClaw fusiona esa salida en `models.providers` antes de escribir `models.json`. -- Los manifiestos de proveedor pueden declarar `providerAuthEnvVars` para que las - sondas genéricas de autenticación basadas en variables de entorno no necesiten cargar el runtime del plugin. El mapa restante de variables de entorno del núcleo - ahora es solo para proveedores no plugin/del núcleo y algunos casos de precedencia genérica - como la incorporación de Anthropic priorizando la API key. -- Los plugins de proveedor también pueden encargarse del comportamiento de runtime del proveedor mediante +- Los manifiestos de proveedores pueden declarar `providerAuthEnvVars` y + `providerAuthAliases` para que las sondas genéricas de autenticación basadas en variables de entorno y las variantes de proveedores + no necesiten cargar el tiempo de ejecución del plugin. El mapa restante de variables de entorno del núcleo ahora + es solo para proveedores no basados en plugins/del núcleo y unos pocos casos de precedencia genérica + como la incorporación con prioridad de clave API de Anthropic. +- Los plugins de proveedores también pueden encargarse del comportamiento en tiempo de ejecución del proveedor mediante `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -50,200 +51,200 @@ Para las reglas de selección de modelos, consulta [/concepts/models](/es/concep `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, y + `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and `onModelSelected`. -- Nota: `capabilities` del runtime del proveedor son metadatos compartidos del ejecutor (familia del proveedor, - peculiaridades de transcripción/herramientas, sugerencias de transporte/caché). No es lo - mismo que el [modelo de capacidades público](/es/plugins/architecture#public-capability-model) +- Nota: `capabilities` del tiempo de ejecución del proveedor son metadatos compartidos del ejecutor (familia del proveedor, + particularidades de transcripción/herramientas, pistas de transporte/caché). No es lo + mismo que el [modelo público de capacidades](/es/plugins/architecture#public-capability-model) que describe lo que registra un plugin (inferencia de texto, voz, etc.). -## Comportamiento de proveedor controlado por plugins +## Comportamiento del proveedor propiedad del plugin -Los plugins de proveedor ahora pueden encargarse de la mayor parte de la lógica específica de cada proveedor mientras OpenClaw mantiene -el bucle de inferencia genérico. +Los plugins de proveedores ahora pueden encargarse de la mayor parte de la lógica específica del proveedor mientras OpenClaw mantiene +el bucle genérico de inferencia. División típica: - `auth[].run` / `auth[].runNonInteractive`: el proveedor se encarga de los flujos de incorporación/inicio de sesión para `openclaw onboard`, `openclaw models auth` y la configuración sin interfaz - `wizard.setup` / `wizard.modelPicker`: el proveedor se encarga de las etiquetas de elección de autenticación, - alias heredados, sugerencias de listas permitidas para incorporación y entradas de configuración en los selectores de incorporación/modelo + alias heredados, pistas de lista de permitidos para incorporación y entradas de configuración en los selectores de incorporación/modelos - `catalog`: el proveedor aparece en `models.providers` -- `normalizeModelId`: el proveedor normaliza ids de modelo heredados/de vista previa antes de - la búsqueda o canonicalización -- `normalizeTransport`: el proveedor normaliza `api` / `baseUrl` de la familia de transporte +- `normalizeModelId`: el proveedor normaliza identificadores de modelos heredados/de vista previa antes de + la búsqueda o la canonicalización +- `normalizeTransport`: el proveedor normaliza la familia de transporte `api` / `baseUrl` antes del ensamblaje genérico del modelo; OpenClaw comprueba primero el proveedor coincidente, - luego otros plugins de proveedor con capacidad de hook hasta que uno cambie realmente el + luego otros plugins de proveedores con capacidad de hook hasta que uno realmente cambie el transporte -- `normalizeConfig`: el proveedor normaliza la configuración `models.providers.` antes de - que el runtime la use; OpenClaw comprueba primero el proveedor coincidente, luego otros - plugins de proveedor con capacidad de hook hasta que uno cambie realmente la configuración. Si ningún - hook de proveedor reescribe la configuración, los ayudantes agrupados de la familia Google siguen - normalizando las entradas de proveedor Google compatibles. +- `normalizeConfig`: el proveedor normaliza la configuración `models.providers.` antes de que + el tiempo de ejecución la use; OpenClaw comprueba primero el proveedor coincidente, luego otros + plugins de proveedores con capacidad de hook hasta que uno realmente cambie la configuración. Si ningún + hook de proveedor reescribe la configuración, los ayudantes integrados de la familia Google siguen + normalizando las entradas de proveedores Google admitidas. - `applyNativeStreamingUsageCompat`: el proveedor aplica reescrituras de compatibilidad de uso de streaming nativo impulsadas por el endpoint para proveedores configurados -- `resolveConfigApiKey`: el proveedor resuelve la autenticación con marcador de entorno para proveedores configurados - sin forzar la carga completa de la autenticación del runtime. `amazon-bedrock` también tiene un - resolvedor integrado de marcador de entorno de AWS aquí, aunque la autenticación de runtime de Bedrock usa +- `resolveConfigApiKey`: el proveedor resuelve la autenticación de marcadores de variables de entorno para proveedores configurados + sin forzar la carga completa de la autenticación en tiempo de ejecución. `amazon-bedrock` también tiene aquí un + resolvedor integrado de marcadores de variables de entorno de AWS, aunque la autenticación en tiempo de ejecución de Bedrock usa la cadena predeterminada del SDK de AWS. -- `resolveSyntheticAuth`: el proveedor puede exponer disponibilidad de autenticación local/alojada por uno mismo u otra - autenticación basada en configuración sin persistir secretos en texto sin formato +- `resolveSyntheticAuth`: el proveedor puede exponer disponibilidad de autenticación + local/alojada por el usuario u otra basada en configuración sin persistir secretos en texto plano - `shouldDeferSyntheticProfileAuth`: el proveedor puede marcar marcadores de posición de perfiles sintéticos almacenados - como de menor precedencia que la autenticación basada en entorno/configuración -- `resolveDynamicModel`: el proveedor acepta ids de modelo que todavía no están presentes en el + con menor precedencia que la autenticación basada en variables de entorno/configuración +- `resolveDynamicModel`: el proveedor acepta identificadores de modelos que aún no están presentes en el catálogo estático local -- `prepareDynamicModel`: el proveedor necesita una actualización de metadatos antes de volver a intentar +- `prepareDynamicModel`: el proveedor necesita una actualización de metadatos antes de reintentar la resolución dinámica - `normalizeResolvedModel`: el proveedor necesita reescrituras de transporte o URL base - `contributeResolvedModelCompat`: el proveedor aporta banderas de compatibilidad para sus - modelos del proveedor incluso cuando llegan mediante otro transporte compatible -- `capabilities`: el proveedor publica peculiaridades de transcripción/herramientas/familia de proveedor + modelos del proveedor incluso cuando llegan a través de otro transporte compatible +- `capabilities`: el proveedor publica particularidades de transcripción/herramientas/familia de proveedor - `normalizeToolSchemas`: el proveedor limpia los esquemas de herramientas antes de que el ejecutor integrado los vea -- `inspectToolSchemas`: el proveedor expone advertencias de esquemas específicas del transporte +- `inspectToolSchemas`: el proveedor muestra advertencias de esquemas específicas del transporte después de la normalización -- `resolveReasoningOutputMode`: el proveedor elige contratos de salida de razonamiento - nativos frente a etiquetados -- `prepareExtraParams`: el proveedor establece valores predeterminados o normaliza parámetros de solicitud por modelo -- `createStreamFn`: el proveedor reemplaza la ruta normal de streaming por un - transporte totalmente personalizado -- `wrapStreamFn`: el proveedor aplica envoltorios de compatibilidad de encabezados/cuerpo/modelo de solicitud -- `resolveTransportTurnState`: el proveedor suministra encabezados nativos o metadatos - por turno para el transporte -- `resolveWebSocketSessionPolicy`: el proveedor suministra encabezados de sesión WebSocket nativos - o política de enfriamiento de sesión -- `createEmbeddingProvider`: el proveedor se encarga del comportamiento de embedding de memoria cuando - corresponde al plugin del proveedor en lugar del selector central de embeddings -- `formatApiKey`: el proveedor formatea perfiles de autenticación almacenados en la cadena - `apiKey` de runtime esperada por el transporte -- `refreshOAuth`: el proveedor se encarga de la actualización de OAuth cuando los actualizadores compartidos de `pi-ai` - no son suficientes -- `buildAuthDoctorHint`: el proveedor agrega orientación de reparación cuando falla la - actualización de OAuth +- `resolveReasoningOutputMode`: el proveedor elige contratos nativos o etiquetados + para la salida de razonamiento +- `prepareExtraParams`: el proveedor aplica valores predeterminados o normaliza parámetros de solicitud por modelo +- `createStreamFn`: el proveedor reemplaza la ruta normal de stream por un transporte + completamente personalizado +- `wrapStreamFn`: el proveedor aplica envoltorios de compatibilidad para encabezados/cuerpo/modelo de la solicitud +- `resolveTransportTurnState`: el proveedor suministra encabezados o metadatos + nativos de transporte por turno +- `resolveWebSocketSessionPolicy`: el proveedor suministra encabezados nativos de sesión WebSocket + o una política de enfriamiento de sesión +- `createEmbeddingProvider`: el proveedor se encarga del comportamiento de embeddings de memoria cuando + corresponde al plugin del proveedor en lugar del conmutador central de embeddings +- `formatApiKey`: el proveedor formatea los perfiles de autenticación almacenados en la cadena + `apiKey` esperada por el transporte en tiempo de ejecución +- `refreshOAuth`: el proveedor se encarga de la actualización de OAuth cuando los + actualizadores compartidos `pi-ai` no son suficientes +- `buildAuthDoctorHint`: el proveedor agrega orientación de reparación cuando falla la actualización de OAuth - `matchesContextOverflowError`: el proveedor reconoce errores específicos del proveedor - de desbordamiento de ventana de contexto que las heurísticas genéricas pasarían por alto -- `classifyFailoverReason`: el proveedor asigna errores sin procesar específicos del proveedor del transporte/API - a motivos de failover como límite de tasa o sobrecarga -- `isCacheTtlEligible`: el proveedor decide qué ids de modelo del upstream admiten TTL de caché de prompt + por desbordamiento de ventana de contexto que las heurísticas genéricas no detectarían +- `classifyFailoverReason`: el proveedor asigna errores sin procesar específicos del proveedor de transporte/API + a motivos de failover como límite de velocidad o sobrecarga +- `isCacheTtlEligible`: el proveedor decide qué identificadores de modelos ascendentes admiten TTL de caché de prompt - `buildMissingAuthMessage`: el proveedor reemplaza el error genérico del almacén de autenticación - por una sugerencia de recuperación específica del proveedor -- `suppressBuiltInModel`: el proveedor oculta filas obsoletas del upstream y puede devolver un - error controlado por el proveedor para fallos de resolución directa -- `augmentModelCatalog`: el proveedor agrega filas sintéticas/finales al catálogo después de - la detección y fusión de configuración -- `isBinaryThinking`: el proveedor se encarga de la UX de razonamiento binario activado/desactivado -- `supportsXHighThinking`: el proveedor habilita `xhigh` para los modelos seleccionados + por una pista de recuperación específica del proveedor +- `suppressBuiltInModel`: el proveedor oculta filas ascendentes obsoletas y puede devolver un + error propiedad del proveedor para fallos de resolución directa +- `augmentModelCatalog`: el proveedor agrega filas sintéticas/finales del catálogo después del + descubrimiento y la fusión de configuración +- `isBinaryThinking`: el proveedor se encarga de la UX binaria de activado/desactivado para thinking +- `supportsXHighThinking`: el proveedor habilita `xhigh` para modelos seleccionados - `resolveDefaultThinkingLevel`: el proveedor se encarga de la política predeterminada de `/think` para una familia de modelos -- `applyConfigDefaults`: el proveedor aplica valores globales predeterminados específicos del proveedor - durante la materialización de la configuración según el modo de autenticación, el entorno o la familia del modelo -- `isModernModelRef`: el proveedor se encarga de la coincidencia de modelos preferidos en vivo/smoke -- `prepareRuntimeAuth`: el proveedor convierte una credencial configurada en un token de runtime - de corta duración +- `applyConfigDefaults`: el proveedor aplica valores predeterminados globales específicos del proveedor + durante la materialización de la configuración según el modo de autenticación, el entorno o la familia de modelos +- `isModernModelRef`: el proveedor se encarga de la coincidencia de modelos preferidos para live/smoke +- `prepareRuntimeAuth`: el proveedor convierte una credencial configurada en un token + de tiempo de ejecución de corta duración - `resolveUsageAuth`: el proveedor resuelve credenciales de uso/cuota para `/usage` y superficies relacionadas de estado/informes -- `fetchUsageSnapshot`: el proveedor se encarga de obtener/analizar el endpoint de uso mientras - el núcleo sigue encargándose de la estructura del resumen y el formato +- `fetchUsageSnapshot`: el proveedor se encarga de la obtención/análisis del endpoint de uso mientras + el núcleo sigue encargándose de la carcasa de resumen y el formato - `onModelSelected`: el proveedor ejecuta efectos secundarios posteriores a la selección, como - telemetría o gestión de sesión controlada por el proveedor + telemetría o mantenimiento de sesión propiedad del proveedor -Ejemplos agrupados actuales: +Ejemplos integrados actuales: - `anthropic`: fallback de compatibilidad futura de Claude 4.6, sugerencias de reparación de autenticación, obtención de endpoint - de uso, metadatos de TTL de caché/familia de proveedor y valores globales predeterminados de configuración - conscientes de la autenticación -- `amazon-bedrock`: coincidencia de desbordamiento de contexto controlada por el proveedor y clasificación - de motivos de failover para errores específicos de Bedrock de limitación/no listo, además - de la familia compartida de repetición `anthropic-by-model` para protecciones de política de repetición exclusivas de Claude + de uso, metadatos de TTL de caché/familia de proveedor, y valores predeterminados globales + de configuración conscientes de la autenticación +- `amazon-bedrock`: coincidencia de desbordamiento de contexto propiedad del proveedor y clasificación de motivos + de failover para errores de Bedrock específicos de limitación/no listo, además de + la familia compartida de reproducción `anthropic-by-model` para protecciones de política de reproducción solo de Claude en tráfico de Anthropic -- `anthropic-vertex`: protecciones de política de repetición exclusivas de Claude en tráfico - de mensajes de Anthropic -- `openrouter`: ids de modelo pass-through, envoltorios de solicitud, sugerencias de capacidades - del proveedor, saneamiento de firmas de pensamiento de Gemini en tráfico Gemini por proxy, - inyección de razonamiento de proxy mediante la familia de stream `openrouter-thinking`, - reenvío de metadatos de enrutamiento y política de TTL de caché -- `github-copilot`: incorporación/inicio de sesión del dispositivo, fallback de modelo de compatibilidad futura, - sugerencias de transcripción de razonamiento de Claude, intercambio de token de runtime y obtención de endpoint - de uso -- `openai`: fallback de compatibilidad futura de GPT-5.4, normalización directa del transporte de OpenAI, - sugerencias de autenticación faltante adaptadas a Codex, supresión de Spark, filas sintéticas - de catálogo OpenAI/Codex, política de razonamiento/modelos en vivo, normalización de alias - de token de uso (`input` / `output` y familias `prompt` / `completion`), la - familia compartida de stream `openai-responses-defaults` para envoltorios nativos de OpenAI/Codex, - metadatos de familia de proveedor, registro agrupado de proveedor de generación de imágenes - para `gpt-image-1` y registro agrupado de proveedor de generación de video +- `anthropic-vertex`: protecciones de política de reproducción solo de Claude en tráfico + de mensajes Anthropic +- `openrouter`: identificadores de modelo pass-through, envoltorios de solicitudes, sugerencias de capacidades + del proveedor, saneamiento de firmas de pensamiento Gemini en tráfico proxy Gemini, + inyección de razonamiento por proxy a través de la familia de stream `openrouter-thinking`, reenvío de metadatos + de enrutamiento y política de TTL de caché +- `github-copilot`: incorporación/inicio de sesión del dispositivo, fallback de compatibilidad futura de modelos, + sugerencias de transcripción de thinking de Claude, intercambio de tokens en tiempo de ejecución y obtención + de endpoint de uso +- `openai`: fallback de compatibilidad futura de GPT-5.4, normalización de transporte + directo de OpenAI, sugerencias de autenticación faltante conscientes de Codex, supresión de Spark, filas + sintéticas del catálogo OpenAI/Codex, política de thinking/modelos live, normalización de alias de tokens + de uso (`input` / `output` y familias `prompt` / `completion`), la familia compartida de stream + `openai-responses-defaults` para envoltorios nativos de OpenAI/Codex, + metadatos de familia del proveedor, registro integrado del proveedor de generación de imágenes + para `gpt-image-1`, y registro integrado del proveedor de generación de video para `sora-2` - `google` y `google-gemini-cli`: fallback de compatibilidad futura de Gemini 3.1, - validación nativa de repetición de Gemini, saneamiento de repetición de bootstrap, modo - de salida de razonamiento etiquetado, coincidencia de modelos modernos, registro agrupado de proveedor de generación de imágenes - para modelos Gemini image-preview y registro agrupado - de proveedor de generación de video para modelos Veo; Gemini CLI OAuth también - se encarga del formato de token de perfiles de autenticación, del análisis de token de uso y de la obtención - de endpoint de cuota para superficies de uso -- `moonshot`: transporte compartido, normalización de payload de razonamiento controlada por plugin -- `kilocode`: transporte compartido, encabezados de solicitud controlados por plugin, normalización del payload de razonamiento, - saneamiento de firmas de pensamiento de Gemini por proxy y política de TTL de caché + validación nativa de reproducción de Gemini, saneamiento de reproducción en bootstrap, modo etiquetado + de salida de razonamiento, coincidencia de modelos modernos, registro integrado del proveedor de generación de imágenes + para modelos Gemini image-preview, y registro integrado + del proveedor de generación de video para modelos Veo; Gemini CLI OAuth también + se encarga del formateo de tokens de perfiles de autenticación, análisis de tokens de uso y + obtención del endpoint de cuota para superficies de uso +- `moonshot`: transporte compartido, normalización de payload de thinking propiedad del plugin +- `kilocode`: transporte compartido, encabezados de solicitud propiedad del plugin, normalización de payload + de razonamiento, saneamiento de firmas de pensamiento de Gemini por proxy y política + de TTL de caché - `zai`: fallback de compatibilidad futura de GLM-5, valores predeterminados de `tool_stream`, política de TTL de caché, - política de razonamiento binario/modelos en vivo y autenticación de uso + obtención de cuota; - ids desconocidos `glm-5*` se sintetizan a partir de la plantilla agrupada `glm-4.7` + política binaria de thinking/modelos live, y autenticación de uso + obtención de cuota; + los identificadores desconocidos `glm-5*` se sintetizan a partir de la plantilla integrada `glm-4.7` - `xai`: normalización nativa del transporte Responses, reescrituras de alias `/fast` para - variantes rápidas de Grok, valor predeterminado de `tool_stream`, limpieza de esquemas de herramientas / - payload de razonamiento específica de xAI y registro agrupado de proveedor de generación de video + variantes rápidas de Grok, `tool_stream` predeterminado, limpieza específica de xAI de esquemas de herramientas / + payload de razonamiento, y registro integrado del proveedor de generación de video para `grok-imagine-video` -- `mistral`: metadatos de capacidades controlados por plugin -- `opencode` y `opencode-go`: metadatos de capacidades controlados por plugin más - saneamiento de firmas de pensamiento de Gemini por proxy -- `alibaba`: catálogo de generación de video controlado por plugin para referencias directas a modelos Wan +- `mistral`: metadatos de capacidades propiedad del plugin +- `opencode` y `opencode-go`: metadatos de capacidades propiedad del plugin más saneamiento + de firmas de pensamiento Gemini por proxy +- `alibaba`: catálogo de generación de video propiedad del plugin para referencias directas de modelos Wan como `alibaba/wan2.6-t2v` -- `byteplus`: catálogos controlados por plugin más registro agrupado de proveedor de generación de video +- `byteplus`: catálogos propiedad del plugin más registro integrado del proveedor de generación de video para modelos Seedance de texto a video/imagen a video -- `fal`: registro agrupado de proveedor de generación de video para terceros alojados - registro agrupado de proveedor de generación de imágenes para modelos de imagen FLUX más registro agrupado - de proveedor de generación de video para modelos de video de terceros alojados +- `fal`: registro integrado del proveedor de generación de video para proveedores de terceros alojados y + registro del proveedor de generación de imágenes para modelos de imagen FLUX, además de registro integrado + del proveedor de generación de video para modelos de video de terceros alojados - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, - `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` y `volcengine`: - solo catálogos controlados por plugin -- `qwen`: catálogos controlados por plugin para modelos de texto más registros compartidos + `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, y `volcengine`: + solo catálogos propiedad del plugin +- `qwen`: catálogos propiedad del plugin para modelos de texto más registros compartidos de proveedores de comprensión multimedia y generación de video para sus - superficies multimodales; la generación de video de Qwen usa los endpoints de video DashScope Standard - con modelos Wan agrupados como `wan2.6-t2v` y `wan2.7-r2v` -- `runway`: registro de proveedor de generación de video controlado por plugin para modelos nativos - basados en tareas de Runway como `gen4.5` -- `minimax`: catálogos controlados por plugin, registro agrupado de proveedor de generación de video - para modelos de video Hailuo, registro agrupado de proveedor de generación de imágenes - para `image-01`, selección híbrida de política de repetición Anthropic/OpenAI - y lógica de autenticación/instantánea de uso -- `together`: catálogos controlados por plugin más registro agrupado de proveedor de generación de video + superficies multimodales; la generación de video de Qwen usa los endpoints de video Standard DashScope + con modelos Wan integrados como `wan2.6-t2v` y `wan2.7-r2v` +- `runway`: registro de proveedor de generación de video propiedad del plugin para modelos + nativos de Runway basados en tareas como `gen4.5` +- `minimax`: catálogos propiedad del plugin, registro integrado del proveedor de generación de video + para modelos de video Hailuo, registro integrado del proveedor de generación de imágenes + para `image-01`, selección híbrida de política de reproducción Anthropic/OpenAI, + y lógica de autenticación/snapshot de uso +- `together`: catálogos propiedad del plugin más registro integrado del proveedor de generación de video para modelos de video Wan -- `xiaomi`: catálogos controlados por plugin más lógica de autenticación/instantánea de uso +- `xiaomi`: catálogos propiedad del plugin más lógica de autenticación/snapshot de uso -El plugin agrupado `openai` ahora se encarga de ambos ids de proveedor: `openai` y +El plugin integrado `openai` ahora se encarga de ambos identificadores de proveedor: `openai` y `openai-codex`. -Eso cubre los proveedores que aún encajan en los transportes normales de OpenClaw. Un proveedor -que necesita un ejecutor de solicitudes totalmente personalizado es una superficie de extensión +Eso cubre los proveedores que todavía encajan en los transportes normales de OpenClaw. Un proveedor +que necesita un ejecutor de solicitudes completamente personalizado es una superficie de extensión separada y más profunda. -## Rotación de API keys +## Rotación de claves API -- Admite rotación genérica del proveedor para proveedores seleccionados. +- Admite rotación genérica de proveedores para proveedores seleccionados. - Configura varias claves mediante: - - `OPENCLAW_LIVE__KEY` (anulación única en vivo, máxima prioridad) + - `OPENCLAW_LIVE__KEY` (anulación única live, máxima prioridad) - `_API_KEYS` (lista separada por comas o punto y coma) - `_API_KEY` (clave principal) - - `_API_KEY_*` (lista numerada, por ejemplo `_API_KEY_1`) + - `_API_KEY_*` (lista numerada, p. ej. `_API_KEY_1`) - Para los proveedores de Google, `GOOGLE_API_KEY` también se incluye como fallback. - El orden de selección de claves preserva la prioridad y elimina duplicados. -- Las solicitudes se reintentan con la siguiente clave solo en respuestas de límite de tasa (por +- Las solicitudes se reintentan con la siguiente clave solo ante respuestas de límite de velocidad (por ejemplo `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` o mensajes periódicos de límite de uso). -- Los fallos que no son de límite de tasa fallan inmediatamente; no se intenta rotación de claves. -- Cuando fallan todas las claves candidatas, se devuelve el error final del último intento. + `workers_ai ... quota limit exceeded`, o mensajes periódicos de límite de uso). +- Los fallos que no son de límite de velocidad fallan inmediatamente; no se intenta rotación de claves. +- Cuando todas las claves candidatas fallan, se devuelve el error final del último intento. ## Proveedores integrados (catálogo pi-ai) -OpenClaw incluye el catálogo pi‑ai. Estos proveedores no requieren -configuración `models.providers`; solo configura la autenticación y elige un modelo. +OpenClaw incluye el catálogo pi‑ai. Estos proveedores no requieren configuración de +`models.providers`; solo configura la autenticación y elige un modelo. ### OpenAI @@ -252,18 +253,18 @@ configuración `models.providers`; solo configura la autenticación y elige un m - Rotación opcional: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, además de `OPENCLAW_LIVE_OPENAI_KEY` (anulación única) - Modelos de ejemplo: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- El transporte predeterminado es `auto` (primero WebSocket, fallback a SSE) -- Anulación por modelo mediante `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) -- El precalentamiento de WebSocket de OpenAI Responses está habilitado de forma predeterminada mediante `params.openaiWsWarmup` (`true`/`false`) +- El transporte predeterminado es `auto` (WebSocket primero, fallback a SSE) +- Anula por modelo mediante `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, o `"auto"`) +- El calentamiento de WebSocket de OpenAI Responses está habilitado de forma predeterminada mediante `params.openaiWsWarmup` (`true`/`false`) - El procesamiento prioritario de OpenAI puede habilitarse mediante `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` y `params.fastMode` asignan solicitudes directas de Responses `openai/*` a `service_tier=priority` en `api.openai.com` -- Usa `params.serviceTier` cuando quieras un nivel explícito en lugar del selector compartido `/fast` +- `/fast` y `params.fastMode` asignan las solicitudes directas de Responses `openai/*` a `service_tier=priority` en `api.openai.com` +- Usa `params.serviceTier` cuando quieras un nivel explícito en lugar del conmutador compartido `/fast` - Los encabezados de atribución ocultos de OpenClaw (`originator`, `version`, `User-Agent`) se aplican solo en tráfico nativo de OpenAI hacia `api.openai.com`, no en proxies genéricos compatibles con OpenAI - Las rutas nativas de OpenAI también mantienen `store` de Responses, sugerencias de caché de prompt y - conformación de payload de compatibilidad de razonamiento de OpenAI; las rutas por proxy no -- `openai/gpt-5.3-codex-spark` está intencionalmente suprimido en OpenClaw porque la API en vivo de OpenAI lo rechaza; Spark se trata solo como Codex + modelado de payload de compatibilidad de razonamiento de OpenAI; las rutas proxy no +- `openai/gpt-5.3-codex-spark` se suprime intencionalmente en OpenClaw porque la API live de OpenAI lo rechaza; Spark se trata solo como Codex ```json5 { @@ -278,9 +279,9 @@ configuración `models.providers`; solo configura la autenticación y elige un m - Rotación opcional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, además de `OPENCLAW_LIVE_ANTHROPIC_KEY` (anulación única) - Modelo de ejemplo: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Las solicitudes públicas directas de Anthropic admiten el selector compartido `/fast` y `params.fastMode`, incluido el tráfico autenticado con API key y OAuth enviado a `api.anthropic.com`; OpenClaw lo asigna a Anthropic `service_tier` (`auto` frente a `standard_only`) -- Nota sobre Anthropic: el personal de Anthropic nos dijo que el uso estilo Claude CLI de OpenClaw vuelve a estar permitido, por lo que OpenClaw considera autorizados para esta integración tanto la reutilización de Claude CLI como el uso de `claude -p`, salvo que Anthropic publique una nueva política. -- El token de configuración de Anthropic sigue disponible como ruta de token compatible con OpenClaw, pero OpenClaw ahora prefiere la reutilización de Claude CLI y `claude -p` cuando están disponibles. +- Las solicitudes directas a Anthropic público admiten el conmutador compartido `/fast` y `params.fastMode`, incluido el tráfico autenticado con clave API y OAuth enviado a `api.anthropic.com`; OpenClaw lo asigna a Anthropic `service_tier` (`auto` vs `standard_only`) +- Nota de Anthropic: el personal de Anthropic nos dijo que el uso al estilo Claude CLI de OpenClaw 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, a menos que Anthropic publique una política nueva. +- El token de configuración de Anthropic sigue disponible como ruta de token admitida por OpenClaw, pero OpenClaw ahora prefiere reutilizar Claude CLI y `claude -p` cuando están disponibles. ```json5 { @@ -294,16 +295,16 @@ configuración `models.providers`; solo configura la autenticación y elige un m - Autenticación: OAuth (ChatGPT) - Modelo de ejemplo: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` o `openclaw models auth login --provider openai-codex` -- El transporte predeterminado es `auto` (primero WebSocket, fallback a SSE) -- Anulación por modelo mediante `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) +- El transporte predeterminado es `auto` (WebSocket primero, fallback a SSE) +- Anula por modelo mediante `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"`, o `"auto"`) - `params.serviceTier` también se reenvía en solicitudes nativas de Codex Responses (`chatgpt.com/backend-api`) - Los encabezados de atribución ocultos de OpenClaw (`originator`, `version`, `User-Agent`) solo se adjuntan en tráfico nativo de Codex hacia `chatgpt.com/backend-api`, no en proxies genéricos compatibles con OpenAI -- Comparte el mismo selector `/fast` y la misma configuración `params.fastMode` que `openai/*` directo; OpenClaw lo asigna a `service_tier=priority` +- Comparte el mismo conmutador `/fast` y la misma configuración `params.fastMode` que `openai/*` directo; OpenClaw lo asigna a `service_tier=priority` - `openai-codex/gpt-5.3-codex-spark` sigue disponible cuando el catálogo OAuth de Codex lo expone; depende de la autorización -- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo y un `contextTokens = 272000` de runtime predeterminado; anula el límite de runtime con `models.providers.openai-codex.models[].contextTokens` -- Nota de política: OpenAI Codex OAuth es compatible explícitamente para herramientas/flujos de trabajo externos como OpenClaw. +- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo y un `contextTokens = 272000` de tiempo de ejecución predeterminado; anula el límite de tiempo de ejecución con `models.providers.openai-codex.models[].contextTokens` +- Nota de política: OpenAI Codex OAuth es compatible explícitamente con herramientas/flujos de trabajo externos como OpenClaw. ```json5 { @@ -326,14 +327,14 @@ configuración `models.providers`; solo configura la autenticación y elige un m ### Otras opciones alojadas de estilo suscripción - [Qwen Cloud](/es/providers/qwen): superficie del proveedor Qwen Cloud más asignación de endpoints de Alibaba DashScope y Coding Plan -- [MiniMax](/es/providers/minimax): acceso por OAuth o API key a MiniMax Coding Plan -- [GLM Models](/es/providers/glm): endpoints de Z.AI Coding Plan o API general +- [MiniMax](/es/providers/minimax): acceso por OAuth o clave API de MiniMax Coding Plan +- [GLM Models](/es/providers/glm): Z.AI Coding Plan o endpoints generales de API ### OpenCode - Autenticación: `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`) -- Proveedor de runtime Zen: `opencode` -- Proveedor de runtime Go: `opencode-go` +- Proveedor de tiempo de ejecución Zen: `opencode` +- Proveedor de tiempo de ejecución Go: `opencode-go` - Modelos de ejemplo: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go` @@ -343,35 +344,35 @@ configuración `models.providers`; solo configura la autenticación y elige un m } ``` -### Google Gemini (API key) +### Google Gemini (clave API) - Proveedor: `google` - Autenticación: `GEMINI_API_KEY` -- Rotación opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` y `OPENCLAW_LIVE_GEMINI_KEY` (anulación única) +- Rotación opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback a `GOOGLE_API_KEY`, y `OPENCLAW_LIVE_GEMINI_KEY` (anulación única) - Modelos de ejemplo: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Compatibilidad: la configuración heredada de OpenClaw que usa `google/gemini-3.1-flash-preview` se normaliza a `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Las ejecuciones directas de Gemini también aceptan `agents.defaults.models["google/"].params.cachedContent` (o el heredado `cached_content`) para reenviar un identificador nativo del proveedor - `cachedContents/...`; los aciertos de caché de Gemini se muestran como `cacheRead` de OpenClaw + `cachedContents/...`; los aciertos de caché de Gemini aparecen como `cacheRead` de OpenClaw ### Google Vertex y Gemini CLI - Proveedores: `google-vertex`, `google-gemini-cli` - Autenticación: Vertex usa gcloud ADC; Gemini CLI usa su flujo OAuth -- Precaución: Gemini CLI OAuth en OpenClaw es una integración no oficial. Algunos usuarios han informado restricciones en cuentas de Google después de usar clientes de terceros. Revisa las condiciones de Google y usa una cuenta no crítica si decides continuar. -- Gemini CLI OAuth se distribuye como parte del plugin agrupado `google`. - - Instala Gemini CLI primero: +- Precaución: Gemini CLI OAuth en OpenClaw es una integración no oficial. Algunos usuarios han informado de restricciones en sus cuentas de Google después de usar clientes de terceros. Revisa las condiciones de Google y usa una cuenta no crítica si decides continuar. +- Gemini CLI OAuth se distribuye como parte del plugin integrado `google`. + - Instala primero Gemini CLI: - `brew install gemini-cli` - o `npm install -g @google/gemini-cli` - Habilita: `openclaw plugins enable google` - Inicia sesión: `openclaw models auth login --provider google-gemini-cli --set-default` - Modelo predeterminado: `google-gemini-cli/gemini-3-flash-preview` - - Nota: **no** pegues un client id ni un secret en `openclaw.json`. El flujo de inicio de sesión de la CLI almacena + - Nota: **no** pegas un client id ni un secreto en `openclaw.json`. El flujo de inicio de sesión de CLI almacena tokens en perfiles de autenticación en el host de la gateway. - Si las solicitudes fallan después de iniciar sesión, configura `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host de la gateway. - Las respuestas JSON de Gemini CLI se analizan desde `response`; el uso recurre a - `stats`, con `stats.cached` normalizado a `cacheRead` de OpenClaw. + `stats`, con `stats.cached` normalizado en `cacheRead` de OpenClaw. ### Z.AI (GLM) @@ -380,7 +381,7 @@ configuración `models.providers`; solo configura la autenticación y elige un m - Modelo de ejemplo: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Alias: `z.ai/*` y `z-ai/*` se normalizan a `zai/*` - - `zai-api-key` detecta automáticamente el endpoint de Z.AI coincidente; `zai-coding-global`, `zai-coding-cn`, `zai-global` y `zai-cn` fuerzan una superficie específica + - `zai-api-key` detecta automáticamente el endpoint Z.AI coincidente; `zai-coding-global`, `zai-coding-cn`, `zai-global` y `zai-cn` fuerzan una superficie específica ### Vercel AI Gateway @@ -396,44 +397,45 @@ configuración `models.providers`; solo configura la autenticación y elige un m - Modelo de ejemplo: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - URL base: `https://api.kilo.ai/api/gateway/` -- El catálogo estático de fallback incluye `kilocode/kilo/auto`; el descubrimiento en vivo en +- El catálogo estático de fallback incluye `kilocode/kilo/auto`; el descubrimiento live en `https://api.kilo.ai/api/gateway/models` puede ampliar aún más el catálogo - de runtime. -- El enrutamiento exacto del upstream detrás de `kilocode/kilo/auto` es responsabilidad de Kilo Gateway, - no está codificado de forma rígida en OpenClaw. + en tiempo de ejecución. +- El enrutamiento ascendente exacto detrás de `kilocode/kilo/auto` es propiedad de Kilo Gateway, + no está codificado de forma fija en OpenClaw. -Consulta [/providers/kilocode](/es/providers/kilocode) para los detalles de configuración. +Consulta [/providers/kilocode](/es/providers/kilocode) para obtener detalles de configuración. -### Otros plugins de proveedor agrupados +### Otros plugins integrados de proveedores - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Modelo de ejemplo: `openrouter/auto` -- OpenClaw aplica los encabezados documentados de atribución de aplicación de OpenRouter solo cuando +- OpenClaw aplica los encabezados de atribución de aplicación documentados por OpenRouter solo cuando la solicitud realmente apunta a `openrouter.ai` -- Los marcadores `cache_control` específicos de Anthropic para OpenRouter también están restringidos a - rutas OpenRouter verificadas, no a URLs arbitrarias de proxy -- OpenRouter permanece en la ruta de estilo proxy compatible con OpenAI, por lo que la conformación de solicitudes solo nativa de OpenAI (`serviceTier`, `store` de Responses, +- Los marcadores `cache_control` específicos de Anthropic de OpenRouter también están restringidos a + rutas OpenRouter verificadas, no a URL proxy arbitrarias +- OpenRouter sigue en la ruta de estilo proxy compatible con OpenAI, por lo que el modelado nativo + de solicitudes exclusivo de OpenAI (`serviceTier`, `store` de Responses, sugerencias de caché de prompt, payloads de compatibilidad de razonamiento de OpenAI) no se reenvía -- Las referencias de OpenRouter respaldadas por Gemini solo mantienen el saneamiento de firmas de pensamiento de Gemini por proxy; - la validación nativa de repetición de Gemini y las reescrituras de bootstrap permanecen desactivadas +- Las referencias OpenRouter respaldadas por Gemini mantienen solo el saneamiento de firmas de pensamiento Gemini por proxy; + la validación nativa de reproducción de Gemini y las reescrituras de bootstrap siguen desactivadas - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Modelo de ejemplo: `kilocode/kilo/auto` - Las referencias de Kilo respaldadas por Gemini mantienen la misma ruta de saneamiento - de firmas de pensamiento de Gemini por proxy; `kilocode/kilo/auto` y otras sugerencias - de razonamiento por proxy no compatible omiten la inyección de razonamiento por proxy -- MiniMax: `minimax` (API key) y `minimax-portal` (OAuth) + de firmas de pensamiento Gemini por proxy; `kilocode/kilo/auto` y otras + sugerencias no admitidas de razonamiento por proxy omiten la inyección de razonamiento por proxy +- MiniMax: `minimax` (clave API) y `minimax-portal` (OAuth) - Autenticación: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` para `minimax-portal` - Modelo de ejemplo: `minimax/MiniMax-M2.7` o `minimax-portal/MiniMax-M2.7` -- La incorporación/configuración con API key de MiniMax escribe definiciones explícitas del modelo M2.7 con - `input: ["text", "image"]`; el catálogo agrupado del proveedor mantiene las referencias de chat - solo texto hasta que se materializa la configuración de ese proveedor +- La incorporación/configuración con clave API de MiniMax escribe definiciones explícitas del modelo M2.7 con + `input: ["text", "image"]`; el catálogo integrado del proveedor mantiene las referencias de chat + solo de texto hasta que se materializa esa configuración del proveedor - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Modelo de ejemplo: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` o `KIMICODE_API_KEY`) - Modelo de ejemplo: `kimi/kimi-code` - Qianfan: `qianfan` (`QIANFAN_API_KEY`) - Modelo de ejemplo: `qianfan/deepseek-v3.2` -- Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY` o `DASHSCOPE_API_KEY`) +- Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, o `DASHSCOPE_API_KEY`) - Modelo de ejemplo: `qwen/qwen3.5-plus` - NVIDIA: `nvidia` (`NVIDIA_API_KEY`) - Modelo de ejemplo: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` @@ -452,9 +454,9 @@ Consulta [/providers/kilocode](/es/providers/kilocode) para los detalles de conf - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) - Modelo de ejemplo: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - - Las solicitudes nativas agrupadas de xAI usan la ruta xAI Responses + - Las solicitudes xAI nativas integradas usan la ruta xAI Responses - `/fast` o `params.fastMode: true` reescriben `grok-3`, `grok-3-mini`, - `grok-4` y `grok-4-0709` a sus variantes `*-fast` + `grok-4`, y `grok-4-0709` a sus variantes `*-fast` - `tool_stream` está activado de forma predeterminada; configura `agents.defaults.models["xai/"].params.tool_stream` en `false` para desactivarlo @@ -463,24 +465,24 @@ Consulta [/providers/kilocode](/es/providers/kilocode) para los detalles de conf - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Los modelos GLM en Cerebras usan los ids `zai-glm-4.7` y `zai-glm-4.6`. + - Los modelos GLM en Cerebras usan los identificadores `zai-glm-4.7` y `zai-glm-4.6`. - URL base compatible con OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Modelo de ejemplo de Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Consulta [Hugging Face (Inference)](/es/providers/huggingface). -## Proveedores mediante `models.providers` (personalizado/URL base) +## Proveedores mediante `models.providers` (personalizados/URL base) Usa `models.providers` (o `models.json`) para agregar proveedores **personalizados** o proxies compatibles con OpenAI/Anthropic. -Muchos de los plugins de proveedor agrupados a continuación ya publican un catálogo predeterminado. -Usa entradas explícitas `models.providers.` solo cuando quieras anular la +Muchos de los plugins integrados de proveedores a continuación ya publican un catálogo predeterminado. +Usa entradas explícitas de `models.providers.` solo cuando quieras anular la URL base, los encabezados o la lista de modelos predeterminados. ### Moonshot AI (Kimi) -Moonshot se incluye como plugin de proveedor agrupado. Usa el proveedor integrado de -forma predeterminada y agrega una entrada explícita `models.providers.moonshot` solo cuando +Moonshot se distribuye como un plugin integrado de proveedor. Usa el proveedor integrado de forma +predeterminada y agrega una entrada explícita `models.providers.moonshot` solo cuando necesites anular la URL base o los metadatos del modelo: - Proveedor: `moonshot` @@ -488,7 +490,7 @@ necesites anular la URL base o los metadatos del modelo: - Modelo de ejemplo: `moonshot/kimi-k2.5` - CLI: `openclaw onboard --auth-choice moonshot-api-key` o `openclaw onboard --auth-choice moonshot-api-key-cn` -Ids de modelo Kimi K2: +Identificadores de modelo Kimi K2: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -535,7 +537,7 @@ Kimi Coding usa el endpoint compatible con Anthropic de Moonshot AI: } ``` -El heredado `kimi/k2p5` sigue aceptándose como id de modelo de compatibilidad. +El heredado `kimi/k2p5` sigue aceptándose como identificador de modelo de compatibilidad. ### Volcano Engine (Doubao) @@ -554,13 +556,13 @@ Volcano Engine (火山引擎) proporciona acceso a Doubao y otros modelos en Chi } ``` -La incorporación usa de forma predeterminada la superficie de coding, pero el catálogo general `volcengine/*` +La incorporación usa por defecto la superficie de coding, pero el catálogo general `volcengine/*` se registra al mismo tiempo. -En los selectores de modelos de incorporación/configuración, la opción de autenticación de Volcengine prefiere tanto las filas -`volcengine/*` como `volcengine-plan/*`. Si esos modelos aún no se han cargado, +En los selectores de incorporación/configuración de modelos, la opción de autenticación de Volcengine prefiere tanto +las filas `volcengine/*` como `volcengine-plan/*`. Si esos modelos aún no se han cargado, OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector -vacío limitado al proveedor. +de ámbito de proveedor vacío. Modelos disponibles: @@ -578,7 +580,7 @@ Modelos de coding (`volcengine-plan`): - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (Internacional) +### BytePlus (internacional) BytePlus ARK proporciona acceso a los mismos modelos que Volcano Engine para usuarios internacionales. @@ -595,13 +597,13 @@ BytePlus ARK proporciona acceso a los mismos modelos que Volcano Engine para usu } ``` -La incorporación usa de forma predeterminada la superficie de coding, pero el catálogo general `byteplus/*` +La incorporación usa por defecto la superficie de coding, pero el catálogo general `byteplus/*` se registra al mismo tiempo. -En los selectores de modelos de incorporación/configuración, la opción de autenticación de BytePlus prefiere tanto las filas -`byteplus/*` como `byteplus-plan/*`. Si esos modelos aún no se han cargado, +En los selectores de incorporación/configuración de modelos, la opción de autenticación de BytePlus prefiere tanto +las filas `byteplus/*` como `byteplus-plan/*`. Si esos modelos aún no se han cargado, OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector -vacío limitado al proveedor. +de ámbito de proveedor vacío. Modelos disponibles: @@ -649,29 +651,29 @@ Synthetic proporciona modelos compatibles con Anthropic detrás del proveedor `s MiniMax se configura mediante `models.providers` porque usa endpoints personalizados: -- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API key (Global): `--auth-choice minimax-global-api` -- MiniMax API key (CN): `--auth-choice minimax-cn-api` +- Clave API de MiniMax (global): `--auth-choice minimax-global-api` +- Clave API de MiniMax (CN): `--auth-choice minimax-cn-api` - Autenticación: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` para `minimax-portal` -Consulta [/providers/minimax](/es/providers/minimax) para detalles de configuración, opciones de modelo y fragmentos de configuración. +Consulta [/providers/minimax](/es/providers/minimax) para obtener detalles de configuración, opciones de modelo y fragmentos de configuración. -En la ruta de streaming compatible con Anthropic de MiniMax, OpenClaw desactiva el razonamiento de -forma predeterminada a menos que lo configures explícitamente, y `/fast on` reescribe +En la ruta de streaming compatible con Anthropic de MiniMax, OpenClaw desactiva thinking de forma +predeterminada a menos que lo configures explícitamente, y `/fast on` reescribe `MiniMax-M2.7` a `MiniMax-M2.7-highspeed`. -División de capacidades controlada por plugins: +División de capacidades propiedad del plugin: -- Los valores predeterminados de texto/chat permanecen en `minimax/MiniMax-M2.7` +- Los valores predeterminados de texto/chat siguen en `minimax/MiniMax-M2.7` - La generación de imágenes es `minimax/image-01` o `minimax-portal/image-01` -- La comprensión de imágenes es `MiniMax-VL-01` controlado por plugin en ambas rutas de autenticación de MiniMax -- La búsqueda web permanece en el id de proveedor `minimax` +- La comprensión de imágenes es `MiniMax-VL-01` propiedad del plugin en ambas rutas de autenticación de MiniMax +- La búsqueda web permanece en el identificador de proveedor `minimax` ### Ollama -Ollama se incluye como plugin de proveedor agrupado y usa la API nativa de Ollama: +Ollama se distribuye como un plugin integrado de proveedor y usa la API nativa de Ollama: - Proveedor: `ollama` - Autenticación: no se requiere (servidor local) @@ -691,27 +693,27 @@ ollama pull llama3.3 } ``` -Ollama se detecta localmente en `http://127.0.0.1:11434` cuando activas la opción con -`OLLAMA_API_KEY`, y el plugin de proveedor agrupado añade Ollama directamente a +Ollama se detecta localmente en `http://127.0.0.1:11434` cuando participas mediante +`OLLAMA_API_KEY`, y el plugin integrado del proveedor agrega Ollama directamente a `openclaw onboard` y al selector de modelos. Consulta [/providers/ollama](/es/providers/ollama) -para la incorporación, el modo en la nube/local y la configuración personalizada. +para incorporación, modo local/en la nube y configuración personalizada. ### vLLM -vLLM se incluye como plugin de proveedor agrupado para servidores -compatibles con OpenAI locales/alojados por uno mismo: +vLLM se distribuye como un plugin integrado de proveedor para servidores +compatibles con OpenAI locales/alojados por el usuario: - Proveedor: `vllm` - Autenticación: opcional (depende de tu servidor) - URL base predeterminada: `http://127.0.0.1:8000/v1` -Para activar la detección automática localmente (cualquier valor sirve si tu servidor no exige autenticación): +Para participar en el descubrimiento automático localmente (cualquier valor funciona si tu servidor no exige autenticación): ```bash export VLLM_API_KEY="vllm-local" ``` -Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `/v1/models`): +Luego configura un modelo (sustitúyelo por uno de los identificadores devueltos por `/v1/models`): ```json5 { @@ -725,21 +727,21 @@ Consulta [/providers/vllm](/es/providers/vllm) para más detalles. ### SGLang -SGLang se incluye como plugin de proveedor agrupado para servidores -compatibles con OpenAI autoalojados de alto rendimiento: +SGLang se distribuye como un plugin integrado de proveedor para servidores +compatibles con OpenAI autohospedados y rápidos: - Proveedor: `sglang` - Autenticación: opcional (depende de tu servidor) - URL base predeterminada: `http://127.0.0.1:30000/v1` -Para activar la detección automática localmente (cualquier valor sirve si tu servidor no +Para participar en el descubrimiento automático localmente (cualquier valor funciona si tu servidor no exige autenticación): ```bash export SGLANG_API_KEY="sglang-local" ``` -Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `/v1/models`): +Luego configura un modelo (sustitúyelo por uno de los identificadores devueltos por `/v1/models`): ```json5 { @@ -788,7 +790,7 @@ Ejemplo (compatible con OpenAI): Notas: -- Para proveedores personalizados, `reasoning`, `input`, `cost`, `contextWindow` y `maxTokens` son opcionales. +- Para proveedores personalizados, `reasoning`, `input`, `cost`, `contextWindow`, y `maxTokens` son opcionales. Cuando se omiten, OpenClaw usa estos valores predeterminados: - `reasoning: false` - `input: ["text"]` @@ -797,14 +799,14 @@ Notas: - `maxTokens: 8192` - Recomendado: configura valores explícitos que coincidan con los límites de tu proxy/modelo. - Para `api: "openai-completions"` en endpoints no nativos (cualquier `baseUrl` no vacío cuyo host no sea `api.openai.com`), OpenClaw fuerza `compat.supportsDeveloperRole: false` para evitar errores 400 del proveedor por roles `developer` no compatibles. -- Las rutas de estilo proxy compatibles con OpenAI también omiten la conformación de solicitudes solo nativa de OpenAI: - no `service_tier`, no `store` de Responses, no sugerencias de caché de prompt, no - conformación de payload de compatibilidad de razonamiento de OpenAI y no encabezados - ocultos de atribución de OpenClaw. -- Si `baseUrl` está vacío o se omite, OpenClaw mantiene el comportamiento predeterminado de OpenAI (que resuelve a `api.openai.com`). -- Por seguridad, un `compat.supportsDeveloperRole: true` explícito sigue siendo reemplazado en endpoints no nativos de `openai-completions`. +- Las rutas proxy de estilo compatible con OpenAI también omiten el modelado nativo de solicitudes exclusivo de OpenAI: + no hay `service_tier`, no hay `store` de Responses, no hay sugerencias de caché de prompt, no hay + modelado de payload de compatibilidad de razonamiento de OpenAI y no hay encabezados ocultos + de atribución de OpenClaw. +- Si `baseUrl` está vacío/se omite, OpenClaw mantiene el comportamiento predeterminado de OpenAI (que se resuelve en `api.openai.com`). +- Por seguridad, una opción explícita `compat.supportsDeveloperRole: true` sigue siendo anulada en endpoints no nativos `openai-completions`. -## Ejemplos de la CLI +## Ejemplos de CLI ```bash openclaw onboard --auth-choice opencode-zen @@ -812,7 +814,7 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Consulta también: [/gateway/configuration](/es/gateway/configuration) para ejemplos completos de configuración. +Consulta también: [/gateway/configuration](/es/gateway/configuration) para ver ejemplos completos de configuración. ## Relacionado diff --git a/docs/es/concepts/qa-e2e-automation.md b/docs/es/concepts/qa-e2e-automation.md index 10aefe3b1..cc38146a1 100644 --- a/docs/es/concepts/qa-e2e-automation.md +++ b/docs/es/concepts/qa-e2e-automation.md @@ -2,50 +2,50 @@ read_when: - Ampliar qa-lab o qa-channel - Agregar escenarios de QA respaldados por el repositorio - - Crear una automatización de QA con mayor realismo alrededor del panel del Gateway + - Crear automatización de QA de mayor realismo alrededor del panel del Gateway summary: Estructura de automatización de QA privada para qa-lab, qa-channel, escenarios sembrados e informes de protocolo title: Automatización E2E de QA x-i18n: - generated_at: "2026-04-08T05:02:50Z" + generated_at: "2026-04-09T01:27:42Z" model: gpt-5.4 provider: openai - source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99 + source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automatización E2E de QA -La pila de QA privada está pensada para ejercitar OpenClaw de una forma más realista, +La pila de QA privada está pensada para ejercitar OpenClaw de una manera más realista, con forma de canal, de lo que puede hacerlo una sola prueba unitaria. Partes actuales: -- `extensions/qa-channel`: canal de mensajes sintético con superficies de DM, canal, hilo, +- `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 semilla respaldados por el repositorio para la tarea inicial y los - escenarios de QA de referencia. + escenarios base de QA. El flujo actual del operador de QA es un sitio de QA de dos paneles: - Izquierda: panel del Gateway (Control UI) con el agente. - Derecha: QA Lab, que muestra la transcripción tipo Slack y el plan del escenario. -Ejecútalo con: +Ejecuta esto con: ```bash pnpm qa:lab:up ``` -Eso compila el sitio de QA, inicia la vía del gateway respaldada por Docker y expone la -página de QA Lab donde un operador o un bucle de automatización puede darle al agente una +Eso compila el sitio de QA, inicia la ruta del gateway respaldada por Docker y expone la +página de QA Lab donde un operador o un bucle de automatización puede dar al agente una misión de QA, 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 interfaz de QA Lab sin reconstruir la imagen de Docker cada vez, -inicia la pila con un paquete de QA Lab montado mediante bind mount: +Para iterar más rápido en la UI de QA Lab sin reconstruir la imagen de Docker cada vez, +inicia la pila con un paquete de QA Lab montado mediante bind: ```bash pnpm openclaw qa docker-build-image @@ -54,7 +54,7 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta mediante bind mount +`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta mediante bind `extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` recompila ese paquete cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash de recursos de QA Lab. @@ -67,21 +67,21 @@ Los recursos semilla viven en `qa/`: - `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. La lista de referencia debe seguir siendo lo bastante amplia como para cubrir: +agente. La lista base debe seguir siendo lo bastante amplia como para cubrir: -- chat de DM y de canal +- chat por MD y por canal - comportamiento de hilos -- ciclo de vida de las acciones de mensajes +- ciclo de vida de acciones de mensajes - callbacks de cron - recuperación de memoria - cambio de modelo -- transferencia a subagentes +- transferencia a subagente - lectura del repositorio y de la documentación - una pequeña tarea de compilación como Lobster Invaders ## Informes -`qa-lab` exporta un informe de protocolo en Markdown a partir de la línea temporal del bus observado. +`qa-lab` exporta un informe de protocolo en Markdown a partir de la línea de tiempo observada del bus. El informe debe responder: - Qué funcionó @@ -89,8 +89,61 @@ 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 en múltiples refs de modelos en vivo +y escribe un informe en Markdown evaluado: + +```bash +pnpm openclaw qa character-eval \ + --model openai/gpt-5.4,thinking=xhigh \ + --model openai/gpt-5.2,thinking=xhigh \ + --model openai/gpt-5,thinking=xhigh \ + --model anthropic/claude-opus-4-6,thinking=high \ + --model anthropic/claude-sonnet-4-6,thinking=high \ + --model zai/glm-5.1,thinking=high \ + --model moonshot/kimi-k2.5,thinking=high \ + --model google/gemini-3.1-pro-preview,thinking=high \ + --judge-model openai/gpt-5.4,thinking=xhigh,fast \ + --judge-model anthropic/claude-opus-4-6,thinking=high \ + --blind-judge-models \ + --concurrency 16 \ + --judge-concurrency 16 +``` + +El comando ejecuta procesos hijo locales del gateway de QA, no Docker. Los escenarios de evaluación de carácter +deben establecer la persona mediante `SOUL.md`, y luego ejecutar turnos de usuario normales +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 juez 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 refs candidatas se sustituyen por +etiquetas neutras como `candidate-01`; el informe vuelve a asignar las clasificaciones a las refs reales después +del análisis. +Las ejecuciones candidatas usan de forma predeterminada pensamiento `high`, 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 un +respaldo global, y la forma anterior `--model-thinking ` se +mantiene por compatibilidad. +Las refs candidatas de OpenAI usan de forma predeterminada el modo fast para que se use el procesamiento prioritario allí +donde 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 el análisis comparativo, pero los prompts de los jueces dicen explícitamente que +no clasifiquen por velocidad. +Tanto las ejecuciones de modelos candidatos como las de jueces usan por defecto una concurrencia de 16. 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. +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`, +`moonshot/kimi-k2.5` y +`google/gemini-3.1-pro-preview` cuando no se pasa `--model`. +Cuando no se pasa `--judge-model`, los jueces usan por defecto +`openai/gpt-5.4,thinking=xhigh,fast` y +`anthropic/claude-opus-4-6,thinking=high`. + ## Documentación relacionada -- [Pruebas](/es/help/testing) -- [Canal de QA](/es/channels/qa-channel) -- [Panel](/web/dashboard) +- [Testing](/es/help/testing) +- [QA Channel](/es/channels/qa-channel) +- [Dashboard](/web/dashboard) diff --git a/docs/es/gateway/cli-backends.md b/docs/es/gateway/cli-backends.md index 7dab12b83..f523dd35c 100644 --- a/docs/es/gateway/cli-backends.md +++ b/docs/es/gateway/cli-backends.md @@ -1,34 +1,34 @@ --- read_when: - - Quieres una alternativa confiable cuando fallen los proveedores de API - - Estás ejecutando Codex CLI u otros CLI de IA locales y quieres reutilizarlos - - Quieres entender el puente loopback de MCP para el acceso a herramientas del backend de CLI -summary: 'Backends de CLI: alternativa local de CLI de IA con puente de herramientas MCP opcional' + - Quieres un respaldo confiable cuando fallen los proveedores de API + - Estás ejecutando Codex CLI u otras CLI de IA locales y quieres reutilizarlas + - Quieres comprender el puente loopback de MCP para el acceso a herramientas del backend de CLI +summary: 'Backends de CLI: respaldo con CLI de IA local con puente de herramientas MCP opcional' title: Backends de CLI x-i18n: - generated_at: "2026-04-08T02:14:38Z" + generated_at: "2026-04-09T01:27:53Z" model: gpt-5.4 provider: openai - source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414 + source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20 source_path: gateway/cli-backends.md workflow: 15 --- -# Backends de CLI (runtime alternativo) +# Backends de CLI (entorno de ejecución de respaldo) -OpenClaw puede ejecutar **CLI de IA locales** como una **alternativa solo de texto** cuando los proveedores de API no están disponibles, -están limitados por tasa o se comportan mal temporalmente. Esto es intencionalmente conservador: +OpenClaw puede ejecutar **CLI de IA locales** como **respaldo solo de texto** cuando los proveedores de API no están disponibles, +tienen límite de tasa o presentan un comportamiento incorrecto temporal. Esto es intencionalmente conservador: - **Las herramientas de OpenClaw no se inyectan directamente**, pero los backends con `bundleMcp: true` - pueden recibir herramientas del gateway mediante un puente MCP loopback. -- **Streaming JSONL** para los CLI que lo admiten. -- **Se admiten sesiones** (para que los turnos de seguimiento sigan siendo coherentes). -- **Las imágenes pueden pasarse** si el CLI acepta rutas de imágenes. + pueden recibir herramientas del gateway mediante un puente loopback de MCP. +- **Streaming JSONL** para las CLI que lo admiten. +- **Se admiten sesiones** (para que los turnos de seguimiento mantengan la coherencia). +- **Las imágenes pueden pasarse** si la CLI acepta rutas de imágenes. -Esto está diseñado como una **red de seguridad** más que como una ruta principal. Úsalo cuando -quieras respuestas de texto de “siempre funciona” sin depender de API externas. +Esto está diseñado como una **red de seguridad** en lugar de una ruta principal. Úsalo cuando +quieras respuestas de texto que “siempre funcionen” sin depender de APIs externas. -Si quieres un runtime de arnés completo con controles de sesión ACP, tareas en segundo plano, +Si quieres un entorno de ejecución completo con controles de sesión ACP, tareas en segundo plano, vinculación de hilo/conversación y sesiones externas de programación persistentes, usa [ACP Agents](/es/tools/acp-agents) en su lugar. Los backends de CLI no son ACP. @@ -58,16 +58,16 @@ ruta del comando: } ``` -Eso es todo. No se necesitan claves ni configuración de autenticación adicional más allá del propio CLI. +Eso es todo. No se necesitan claves ni configuración de autenticación extra más allá de la propia CLI. Si usas un backend de CLI incluido como **proveedor principal de mensajes** en un host de gateway, OpenClaw ahora carga automáticamente el plugin incluido propietario cuando tu configuración hace referencia explícita a ese backend en una referencia de modelo o en `agents.defaults.cliBackends`. -## Uso como alternativa +## Uso como respaldo -Agrega un backend de CLI a tu lista de alternativas para que solo se ejecute cuando fallen los modelos principales: +Agrega un backend de CLI a tu lista de respaldo para que solo se ejecute cuando fallen los modelos principales: ```json5 { @@ -88,9 +88,9 @@ Agrega un backend de CLI a tu lista de alternativas para que solo se ejecute cua Notas: -- Si usas `agents.defaults.models` (lista permitida), también debes incluir ahí los modelos de tu backend de CLI. +- Si usas `agents.defaults.models` (lista de permitidos), también debes incluir allí los modelos de tu backend de CLI. - Si falla el proveedor principal (autenticación, límites de tasa, tiempos de espera), OpenClaw - probará después el backend de CLI. + probará luego el backend de CLI. ## Resumen de configuración @@ -100,8 +100,8 @@ Todos los backends de CLI viven en: agents.defaults.cliBackends ``` -Cada entrada se identifica con un **id de proveedor** (por ejemplo, `codex-cli`, `my-cli`). -El id del proveedor se convierte en la parte izquierda de tu referencia de modelo: +Cada entrada está indexada por un **id de proveedor** (por ejemplo, `codex-cli`, `my-cli`). +El id de proveedor pasa a ser el lado izquierdo de tu referencia de modelo: ``` / @@ -131,6 +131,9 @@ El id del proveedor se convierte en la parte izquierda de tu referencia de model sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", + // Las CLI de estilo Codex pueden apuntar a un archivo de prompt en su lugar: + // systemPromptFileConfigArg: "-c", + // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -145,65 +148,71 @@ El id del proveedor se convierte en la parte izquierda de tu referencia de model ## Cómo funciona 1. **Selecciona un backend** según el prefijo del proveedor (`codex-cli/...`). -2. **Construye un prompt del sistema** usando el mismo prompt de OpenClaw + contexto del espacio de trabajo. -3. **Ejecuta el CLI** con un id de sesión (si se admite) para que el historial siga siendo consistente. -4. **Analiza la salida** (JSON o texto sin formato) y devuelve el texto final. -5. **Persiste los id de sesión** por backend, para que los seguimientos reutilicen la misma sesión del CLI. +2. **Construye un prompt de sistema** usando el mismo prompt de OpenClaw + contexto del espacio de trabajo. +3. **Ejecuta la CLI** con un id de sesión (si se admite) para que el historial se mantenga consistente. +4. **Analiza la salida** (JSON o texto plano) y devuelve el texto final. +5. **Persiste los id de sesión** por backend, para que los seguimientos reutilicen la misma sesión de la CLI. -El backend incluido `claude-cli` de Anthropic vuelve a ser compatible. El personal de Anthropic -nos dijo que el uso de Claude CLI al estilo de OpenClaw vuelve a estar permitido, por lo que OpenClaw trata +El backend `claude-cli` incluido de Anthropic vuelve a ser compatible. El personal de Anthropic +nos dijo que el uso de Claude CLI al estilo OpenClaw vuelve a estar permitido, por lo que OpenClaw trata el uso de `claude -p` como autorizado para esta integración, a menos que Anthropic publique una nueva política. +El backend `codex-cli` incluido de OpenAI pasa el prompt de sistema de OpenClaw a través de +la anulación de configuración `model_instructions_file` de Codex (`-c +model_instructions_file="..."`). Codex no expone una bandera de estilo Claude +`--append-system-prompt`, por lo que OpenClaw escribe el prompt ensamblado en un +archivo temporal para cada sesión nueva de Codex CLI. + ## Sesiones -- Si el CLI admite sesiones, configura `sessionArg` (por ejemplo, `--session-id`) o +- Si la CLI admite sesiones, establece `sessionArg` (por ejemplo, `--session-id`) o `sessionArgs` (marcador `{sessionId}`) cuando el ID deba insertarse en varias banderas. -- Si el CLI usa un **subcomando de reanudación** con banderas diferentes, configura - `resumeArgs` (reemplaza `args` al reanudar) y, opcionalmente, `resumeOutput` - (para reanudaciones no JSON). +- Si la CLI usa un **subcomando de reanudación** con banderas diferentes, establece + `resumeArgs` (reemplaza `args` al reanudar) y opcionalmente `resumeOutput` + (para reanudaciones que no son JSON). - `sessionMode`: - - `always`: siempre envía un id de sesión (un UUID nuevo si no hay ninguno almacenado). - - `existing`: solo envía un id de sesión si ya se había almacenado antes. - - `none`: nunca envía un id de sesión. + - `always`: envía siempre un id de sesión (UUID nuevo si no hay ninguno almacenado). + - `existing`: envía un id de sesión solo si ya había uno almacenado. + - `none`: no envía nunca un id de sesión. Notas sobre serialización: -- `serialize: true` mantiene ordenadas las ejecuciones del mismo carril. -- La mayoría de los CLI serializan en un carril de proveedor. -- OpenClaw descarta la reutilización de sesiones de CLI almacenadas cuando cambia el estado de autenticación del backend, incluido relogin, rotación de tokens o un cambio en las credenciales del perfil de autenticación. +- `serialize: true` mantiene ordenadas las ejecuciones en la misma vía. +- La mayoría de las CLI serializan en una vía de proveedor. +- OpenClaw descarta la reutilización de sesión almacenada de la CLI cuando cambia el estado de autenticación del backend, lo que incluye volver a iniciar sesión, rotación de tokens o un cambio en la credencial del perfil de autenticación. ## Imágenes (paso directo) -Si tu CLI acepta rutas de imágenes, configura `imageArg`: +Si tu CLI acepta rutas de imágenes, establece `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw escribirá las imágenes base64 en archivos temporales. Si `imageArg` está configurado, esas -rutas se pasan como argumentos del CLI. Si falta `imageArg`, OpenClaw agrega las -rutas de archivo al prompt (inyección de ruta), lo que es suficiente para los CLI que cargan automáticamente -archivos locales a partir de rutas simples. +OpenClaw escribirá las imágenes base64 en archivos temporales. Si `imageArg` está establecido, esas +rutas se pasan como argumentos de CLI. Si falta `imageArg`, OpenClaw agrega las +rutas de archivo al prompt (inyección de ruta), lo cual es suficiente para las CLI que cargan +automáticamente archivos locales desde rutas simples. ## Entradas / salidas - `output: "json"` (predeterminado) intenta analizar JSON y extraer texto + id de sesión. -- Para la salida JSON de Gemini CLI, OpenClaw lee el texto de respuesta de `response` y - el uso de `stats` cuando falta `usage` o está vacío. -- `output: "jsonl"` analiza streams JSONL (por ejemplo Codex CLI `--json`) y extrae el mensaje final del agente, además de los identificadores de sesión - cuando están presentes. +- Para la salida JSON de Gemini CLI, OpenClaw lee el texto de respuesta desde `response` y + el uso desde `stats` cuando falta `usage` o está vacío. +- `output: "jsonl"` analiza flujos JSONL (por ejemplo Codex CLI `--json`) y extrae el mensaje final del agente más los identificadores + de sesión cuando están presentes. - `output: "text"` trata stdout como la respuesta final. Modos de entrada: -- `input: "arg"` (predeterminado) pasa el prompt como el último argumento del CLI. -- `input: "stdin"` envía el prompt mediante stdin. -- Si el prompt es muy largo y `maxPromptArgChars` está configurado, se usa stdin. +- `input: "arg"` (predeterminado) pasa el prompt como el último argumento de CLI. +- `input: "stdin"` envía el prompt por stdin. +- Si el prompt es muy largo y se establece `maxPromptArgChars`, se usa stdin. ## Valores predeterminados (propiedad del plugin) @@ -229,31 +238,31 @@ El plugin Google incluido también registra un valor predeterminado para `google - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -Requisito previo: el Gemini CLI local debe estar instalado y disponible como +Requisito previo: la Gemini CLI local debe estar instalada y disponible como `gemini` en `PATH` (`brew install gemini-cli` o `npm install -g @google/gemini-cli`). Notas sobre JSON de Gemini CLI: - El texto de respuesta se lee del campo JSON `response`. -- El uso recurre a `stats` cuando `usage` está ausente o vacío. -- `stats.cached` se normaliza en OpenClaw como `cacheRead`. -- Si falta `stats.input`, OpenClaw deriva los tokens de entrada de +- El uso recurre a `stats` cuando `usage` no está presente o está vacío. +- `stats.cached` se normaliza como `cacheRead` en OpenClaw. +- Si falta `stats.input`, OpenClaw deriva los tokens de entrada a partir de `stats.input_tokens - stats.cached`. -Sobrescribe esto solo si es necesario (lo más común: ruta absoluta de `command`). +Anúlalo solo si es necesario (algo común: ruta `command` absoluta). ## Valores predeterminados propiedad del plugin -Los valores predeterminados de los backends de CLI ahora forman parte de la superficie del plugin: +Los valores predeterminados del backend de CLI ahora forman parte de la superficie del plugin: - Los plugins los registran con `api.registerCliBackend(...)`. -- El `id` del backend se convierte en el prefijo del proveedor en las referencias de modelo. -- La configuración de usuario en `agents.defaults.cliBackends.` sigue sobrescribiendo el valor predeterminado del plugin. +- El `id` del backend pasa a ser el prefijo de proveedor en las referencias de modelo. +- La configuración del usuario en `agents.defaults.cliBackends.` sigue anulando el valor predeterminado del plugin. - La limpieza de configuración específica del backend sigue siendo propiedad del plugin mediante el hook opcional `normalizeConfig`. -## Superposiciones Bundle MCP +## Superposiciones de MCP incluidas Los backends de CLI **no** reciben llamadas de herramientas de OpenClaw directamente, pero un backend puede optar por una superposición de configuración MCP generada con `bundleMcp: true`. @@ -261,37 +270,37 @@ optar por una superposición de configuración MCP generada con `bundleMcp: true Comportamiento incluido actual: - `claude-cli`: archivo de configuración MCP estricto generado -- `codex-cli`: sobrescrituras de configuración en línea para `mcp_servers` +- `codex-cli`: anulaciones de configuración en línea para `mcp_servers` - `google-gemini-cli`: archivo de configuración del sistema Gemini generado -Cuando Bundle MCP está habilitado, OpenClaw: +Cuando bundle MCP está habilitado, OpenClaw: -- genera un servidor HTTP MCP loopback que expone herramientas del gateway al proceso del CLI +- inicia un servidor HTTP MCP loopback que expone herramientas del gateway al proceso de CLI - autentica el puente con un token por sesión (`OPENCLAW_MCP_TOKEN`) -- limita el acceso a herramientas a la sesión, cuenta y contexto de canal actuales +- limita el acceso a herramientas a la sesión, cuenta y contexto del canal actuales - carga los servidores bundle-MCP habilitados para el espacio de trabajo actual -- los combina con cualquier forma existente de configuración/ajustes MCP del backend +- los fusiona con cualquier forma existente de configuración/ajustes MCP del backend - reescribe la configuración de inicio usando el modo de integración propiedad del backend desde la extensión propietaria -Si no hay servidores MCP habilitados, OpenClaw sigue inyectando una configuración estricta cuando un -backend opta por Bundle MCP para que las ejecuciones en segundo plano permanezcan aisladas. +Si no hay servidores MCP habilitados, OpenClaw igualmente inyecta una configuración estricta cuando un +backend opta por bundle MCP para que las ejecuciones en segundo plano sigan aisladas. ## Limitaciones - **No hay llamadas directas a herramientas de OpenClaw.** OpenClaw no inyecta llamadas de herramientas en el protocolo del backend de CLI. Los backends solo ven herramientas del gateway cuando optan por `bundleMcp: true`. -- **El streaming es específico del backend.** Algunos backends transmiten JSONL; otros almacenan - en búfer hasta la salida. -- **Las salidas estructuradas** dependen del formato JSON del CLI. -- **Las sesiones de Codex CLI** se reanudan mediante salida de texto (sin JSONL), lo que está menos +- **El streaming es específico del backend.** Algunos backends transmiten JSONL; otros almacenan en búfer + hasta salir. +- **Las salidas estructuradas** dependen del formato JSON de la CLI. +- **Las sesiones de Codex CLI** se reanudan mediante salida de texto (sin JSONL), lo que es menos estructurado que la ejecución inicial con `--json`. Las sesiones de OpenClaw siguen funcionando normalmente. ## Solución de problemas -- **CLI no encontrado**: configura `command` con una ruta completa. -- **Nombre de modelo incorrecto**: usa `modelAliases` para mapear `provider/model` → modelo del CLI. -- **Sin continuidad de sesión**: asegúrate de que `sessionArg` esté configurado y que `sessionMode` no sea +- **CLI no encontrada**: establece `command` en una ruta completa. +- **Nombre de modelo incorrecto**: usa `modelAliases` para asignar `provider/model` → modelo de CLI. +- **Sin continuidad de sesión**: asegúrate de que `sessionArg` esté establecido y de que `sessionMode` no sea `none` (actualmente Codex CLI no puede reanudarse con salida JSON). -- **Imágenes ignoradas**: configura `imageArg` (y verifica que el CLI admita rutas de archivo). +- **Imágenes ignoradas**: establece `imageArg` (y verifica que la CLI admita rutas de archivo). diff --git a/docs/es/gateway/configuration-reference.md b/docs/es/gateway/configuration-reference.md index cf645c096..30a28cd43 100644 --- a/docs/es/gateway/configuration-reference.md +++ b/docs/es/gateway/configuration-reference.md @@ -1,37 +1,37 @@ --- read_when: - - Necesitas la semántica exacta o los valores predeterminados de configuración a nivel de campo + - Necesitas la semántica exacta o los valores predeterminados de la configuración a nivel de campo - Estás validando bloques de configuración de canales, modelos, gateway o herramientas -summary: Referencia de configuración del gateway para claves principales de OpenClaw, valores predeterminados y enlaces a referencias dedicadas de subsistemas +summary: Referencia de configuración del 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-08T05:08:30Z" + generated_at: "2026-04-09T01:35:02Z" model: gpt-5.4 provider: openai - source_hash: 2f9ab34fb56897a77cb038d95bea21e8530d8f0402b66d1ee97c73822a1e8fd4 + source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c 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 [Configuration](/es/gateway/configuration). +Referencia de configuración principal para `~/.openclaw/openclaw.json`. Para una visión general orientada a tareas, consulta [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 canal/plugin 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 páginas cuando un subsistema tiene su propia referencia más profunda. **No** intenta incluir en una sola página cada catálogo de comandos propio de canales/plugins ni cada ajuste profundo de memoria/QMD. Fuente de verdad del código: -- `openclaw config schema` imprime el JSON Schema en vivo 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 de ruta para herramientas de exploración detallada -- `pnpm config:docs:check` / `pnpm config:docs:gen` validan el hash base de documentación de configuración frente a la superficie actual del esquema +- `openclaw config schema` imprime el JSON Schema activo usado para validación y Control UI, con los metadatos fusionados de bundles/plugins/canales 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 base de la documentación de configuración frente a la superficie actual del esquema Referencias profundas dedicadas: - [Memory configuration reference](/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` -- [Slash Commands](/es/tools/slash-commands) para el catálogo actual de comandos integrados + bundled +- [Slash Commands](/es/tools/slash-commands) para el catálogo actual de comandos integrados + agrupados - 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. +El formato de configuración es **JSON5** (se permiten comentarios + comas finales). Todos los campos son opcionales: OpenClaw usa valores predeterminados seguros cuando se omiten. --- @@ -39,32 +39,32 @@ El formato de configuración es **JSON5** (se permiten comentarios y comas final Cada canal se inicia automáticamente cuando existe su sección de configuración (a menos que `enabled: false`). -### Acceso a DM y grupos +### Acceso a mensajes directos y grupos -Todos los canales admiten políticas de DM y políticas de grupo: +Todos los canales admiten políticas de MD y políticas de grupo: -| Política de DM | Comportamiento | -| ------------------- | -------------------------------------------------------------- | -| `pairing` (default) | Los remitentes desconocidos reciben un código de pairing único; el propietario debe aprobar | -| `allowlist` | Solo remitentes en `allowFrom` (o almacén de permitidos emparejados) | -| `open` | Permitir todos los DM entrantes (requiere `allowFrom: ["*"]`) | -| `disabled` | Ignorar todos los DM entrantes | +| Política de MD | Comportamiento | +| ------------------ | --------------------------------------------------------------- | +| `pairing` (predeterminada) | Los remitentes desconocidos reciben un código de emparejamiento de un solo uso; el propietario debe aprobarlo | +| `allowlist` | Solo remitentes en `allowFrom` (o en el almacén de permisos emparejado) | +| `open` | Permitir todos los MD entrantes (requiere `allowFrom: ["*"]`) | +| `disabled` | Ignorar todos los MD entrantes | -| Política de grupo | Comportamiento | -| --------------------- | ------------------------------------------------------- | -| `allowlist` (default) | Solo grupos que coincidan con la lista de permitidos configurada | -| `open` | Omite las listas de permitidos de grupos (la exigencia de mención sigue aplicándose) | -| `disabled` | Bloquea todos los mensajes de grupo/sala | +| Política de grupo | Comportamiento | +| -------------------- | ------------------------------------------------------ | +| `allowlist` (predeterminada) | Solo grupos que coinciden con la lista de permisos configurada | +| `open` | Omite las listas de permisos de grupo (la exigencia de 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 pairing vencen después de 1 hora. Las solicitudes pendientes de pairing por DM 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` (fail-closed) con una advertencia al iniciar. +`channels.defaults.groupPolicy` establece el valor predeterminado cuando `groupPolicy` de un proveedor no está configurado. +Los códigos de emparejamiento caducan después de 1 hora. Las solicitudes pendientes de emparejamiento 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` (cierre por defecto) con una advertencia al inicio. -### Sobrescrituras de modelo por canal +### Sustituciones 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 modelos configurados. La asignación del canal se aplica cuando una sesión aún no tiene una sobrescritura de modelo (por ejemplo, establecida mediante `/model`). +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 del canal se aplica cuando una sesión no tiene ya una sustitución 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 de canal y heartbeat -Usa `channels.defaults` para el comportamiento compartido de política de grupo y heartbeat entre proveedores: +Usa `channels.defaults` para compartir el comportamiento de política de grupo y heartbeat entre proveedores: ```json5 { @@ -105,11 +105,11 @@ 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, incluye todo el contexto citado/de hilo/historial), `allowlist` (solo incluye contexto de remitentes 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.groupPolicy`: política de grupo de respaldo cuando no se configura un `groupPolicy` a nivel de proveedor. +- `channels.defaults.contextVisibility`: modo predeterminado de visibilidad de contexto suplementario para todos los canales. Valores: `all` (predeterminado, incluir todo el contexto citado/de hilo/historial), `allowlist` (incluir solo contexto de remitentes permitidos), `allowlist_quote` (igual que allowlist pero conservando el contexto explícito de cita/respuesta). Sustitución por canal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: incluir estados de canal saludables en la salida de heartbeat. - `channels.defaults.heartbeat.showAlerts`: incluir estados degradados/con error en la salida de heartbeat. -- `channels.defaults.heartbeat.useIndicator`: representar una salida de heartbeat compacta con estilo de indicador. +- `channels.defaults.heartbeat.useIndicator`: mostrar una salida de heartbeat compacta con estilo de indicador. ### WhatsApp @@ -124,7 +124,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // doble check azul (false en modo self-chat) groups: { "*": { requireMention: true }, }, @@ -146,7 +146,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` - + ```json5 { @@ -164,10 +164,10 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- Los comandos salientes usan por defecto la cuenta `default` si está presente; de lo contrario, el primer id de cuenta configurado (ordenado). -- `channels.whatsapp.defaultAccount` opcional sobrescribe esa selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. -- El directorio de autenticación heredado de Baileys de 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`. +- Los comandos salientes usan la cuenta `default` por defecto si está presente; de lo contrario, usan el primer ID de cuenta configurado (ordenado). +- `channels.whatsapp.defaultAccount` opcional sustituye esa selección de cuenta predeterminada de respaldo cuando coincide con un ID de cuenta configurado. +- El directorio heredado de autenticación Baileys de una sola cuenta es migrado por `openclaw doctor` a `whatsapp/default`. +- Sustituciones por cuenta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -226,11 +226,11 @@ 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 regular; se rechazan symlinks), 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 varias 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 por respaldo; `openclaw doctor` advierte cuando falta o no es válido. -- `configWrites: false` bloquea escrituras de configuración iniciadas desde Telegram (migraciones de ID de supergrupo, `/config set|unset`). -- Las entradas de nivel superior `bindings[]` 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 [ACP Agents](/es/tools/acp-agents#channel-specific-settings). -- Las vistas previas de streaming de Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y de grupo). +- `channels.telegram.defaultAccount` opcional sustituye la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. +- En configuraciones de múltiples cuentas (2+ IDs de cuenta), establece una cuenta predeterminada explícita (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) para evitar el enrutamiento por respaldo; `openclaw doctor` advierte cuando esto falta o es inválido. +- `configWrites: false` bloquea las escrituras de configuración iniciadas por 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 [ACP Agents](/es/tools/acp-agents#channel-specific-settings). +- Las vistas previas de stream de Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y de grupo). - Política de reintento: consulta [Retry policy](/es/concepts/retry). ### Discord @@ -334,33 +334,33 @@ 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; las opciones de reintento/política de la cuenta siguen viniendo de la cuenta seleccionada en la instantánea activa en 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:` (DM) o `channel:` (canal de guild) para los destinos de entrega; se rechazan los IDs numéricos sin prefijo. -- Los slugs de guild están en minúsculas con espacios reemplazados por `-`; las claves de canal usan el nombre convertido a slug (sin `#`). Prefiere IDs de guild. +- Las llamadas salientes directas que proporcionan un `token` explícito de Discord usan ese token para la llamada; la configuración de reintento/política de cuenta sigue viniendo de la cuenta seleccionada en la instantánea activa en tiempo de ejecución. +- `channels.discord.defaultAccount` opcional sustituye la selección de cuenta predeterminada 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 van en minúsculas y con espacios reemplazados por `-`; las claves de canal usan el nombre convertido en slug (sin `#`). Prefiere 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 filtrados). -- `channels.discord.guilds..ignoreOtherMentions` (y las sobrescrituras de canal) descarta mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here). +- `channels.discord.guilds..ignoreOtherMentions` (y las sustituciones por canal) descarta mensajes que mencionan a otro usuario o rol, pero no al bot (excepto @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 desenfoque automático por inactividad en horas (`0` lo desactiva) - - `maxAgeHours`: sobrescritura de Discord para antigüedad máxima estricta en horas (`0` lo desactiva) - - `spawnSubagentSessions`: interruptor opt-in para la creación/vinculación automática de hilos con `sessions_spawn({ thread: true })` -- Las entradas de nivel superior `bindings[]` 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 [ACP Agents](/es/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` establece el color de acento para contenedores de componentes v2 de Discord. -- `channels.discord.voice` habilita conversaciones en canales de voz de Discord y sobrescrituras opcionales de auto-unión + 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 entrar en una sesión de voz tras fallos repetidos de descifrado. -- `channels.discord.streaming` es la clave canónica para el modo de streaming. Los valores heredados `streamMode` y booleanos `streaming` se migran automáticamente. -- `channels.discord.autoPresence` asigna la disponibilidad de tiempo de ejecución a la presencia del bot (healthy => online, degraded => idle, exhausted => dnd) y permite sobrescrituras opcionales del texto de estado. -- `channels.discord.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia por nombre/tag mutable (modo de compatibilidad break-glass). -- `channels.discord.execApprovals`: entrega nativa de aprobaciones de exec de Discord y autorización de aprobadores. - - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo auto, las aprobaciones de exec se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. - - `approvers`: IDs de usuario de Discord autorizados para aprobar solicitudes de exec. Usa `commands.ownerAllowFrom` como respaldo cuando se omite. - - `agentFilter`: lista de permitidos opcional de IDs de agente. Omítela para reenviar aprobaciones de todos los agentes. +- `channels.discord.threadBindings` controla el enrutamiento ligado a hilos de Discord: + - `enabled`: sustitución de Discord para las funciones de sesión ligadas a hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` y entrega/enrutamiento ligados) + - `idleHours`: sustitución de Discord para el auto-unfocus por inactividad en horas (`0` desactiva) + - `maxAgeHours`: sustitución de Discord para la antigüedad máxima estricta en horas (`0` desactiva) + - `spawnSubagentSessions`: interruptor opt-in para creación/enlace automático 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 [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 sustituciones opcionales de auto-join + TTS. +- `channels.discord.voice.daveEncryption` y `channels.discord.voice.decryptionFailureTolerance` se pasan a las opciones DAVE de `@discordjs/voice` (`true` y `24` por defecto). +- OpenClaw además 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 stream. Los valores heredados `streamMode` y booleanos `streaming` se migran automáticamente. +- `channels.discord.autoPresence` asigna la disponibilidad en tiempo de ejecución a la presencia del bot (saludable => online, degradado => idle, agotado => dnd) y permite sustituciones opcionales del texto de estado. +- `channels.discord.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia con nombres/tags mutables (modo de compatibilidad de emergencia). +- `channels.discord.execApprovals`: entrega de aprobaciones exec nativa de Discord y autorización de aprobadores. + - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo auto, las aprobaciones exec se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. + - `approvers`: IDs de usuario de Discord autorizados para aprobar solicitudes exec. Usa `commands.ownerAllowFrom` como respaldo si se omite. + - `agentFilter`: lista opcional de IDs de agente permitidos. Omítela para reenviar aprobaciones para todos los agentes. - `sessionFilter`: patrones opcionales de claves de sesión (subcadena o regex). - - `target`: dónde enviar los avisos de aprobación. `"dm"` (predeterminado) los envía a los DMs de los aprobadores, `"channel"` los envía al canal de origen, `"both"` los envía a ambos. Cuando el destino incluye `"channel"`, los botones solo pueden usarlos los aprobadores resueltos. - - `cleanupAfterResolve`: cuando es `true`, elimina los DMs de aprobación tras aprobación, denegación o timeout. + - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado) las envía a los MD del aprobador, `"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 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). @@ -395,9 +395,9 @@ 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`). - 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`. +- Respaldos por 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 por principal de email mutable (modo de compatibilidad break-glass). +- `channels.googlechat.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia con principal de correo mutable (modo de compatibilidad de emergencia). ### Slack @@ -464,39 +464,39 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- El **modo socket** requiere tanto `botToken` como `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para el respaldo por entorno de la cuenta predeterminada). -- El **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 origen/estado como +- **Modo socket** requiere tanto `botToken` como `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como respaldo 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 en texto plano u objetos SecretRef. +- Las instantáneas de cuentas de Slack exponen campos por credencial de origen/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 + configurada mediante SecretRef pero la ruta actual de comando/tiempo de ejecución no pudo resolver el valor del 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 para el modo de streaming de Slack. `channels.slack.streaming.nativeTransport` controla el transporte nativo de streaming de Slack. Los valores heredados `streamMode`, booleanos `streaming` y `nativeStreaming` se migran automáticamente. -- Usa `user:` (DM) o `channel:` para los destinos de entrega. +- `configWrites: false` bloquea las escrituras de configuración iniciadas por Slack. +- `channels.slack.defaultAccount` opcional sustituye la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. +- `channels.slack.streaming.mode` es la clave canónica del modo de stream de Slack. `channels.slack.streaming.nativeTransport` controla el transporte de streaming nativo de Slack. Los valores heredados `streamMode`, booleanos `streaming` y `nativeStreaming` se migran automáticamente. +- Usa `user:` (MD) o `channel:` para los destinos de entrega. **Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (de `reactionAllowlist`). -**Aislamiento de sesión por hilo:** `thread.historyScope` es por hilo (predeterminado) o compartido en el canal. `thread.inheritParent` copia la transcripción del canal padre a hilos nuevos. +**Aislamiento de sesión de hilos:** `thread.historyScope` es por hilo (predeterminado) o compartido por canal. `thread.inheritParent` copia la transcripción del canal padre a los nuevos hilos. -- El streaming nativo de Slack más el estado de hilo estilo asistente de Slack "is typing..." requieren un destino de respuesta en hilo. Los DM 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` añade una reacción temporal al mensaje entrante de Slack mientras se está generando 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 exec 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"`). +- El streaming nativo de Slack más el estado de hilo estilo “is typing...” del asistente de Slack requieren un destino de respuesta en hilo. Los MD de nivel superior permanecen fuera de hilo por defecto, por lo que usan `typingReaction` o entrega normal en lugar de la vista previa de estilo hilo. +- `typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras se está ejecutando una respuesta, y luego la elimina al finalizar. Usa un shortcode de emoji de Slack como `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: entrega de aprobaciones exec 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 | -| ----------------- | -------------- | ------------------------- | -| reactions | enabled | Reaccionar + listar reacciones | -| messages | enabled | Leer/enviar/editar/eliminar | -| pins | enabled | Fijar/desfijar/listar | -| memberInfo | enabled | Información de miembros | -| emojiList | enabled | Lista de emojis personalizados | +| 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 miembros | +| emojiList | habilitado | Lista de emoji personalizados | ### Mattermost -Mattermost se distribuye como un plugin: `openclaw plugins install @openclaw/mattermost`. +Mattermost se distribuye como plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -516,7 +516,7 @@ Mattermost se distribuye como un plugin: `openclaw plugins install @openclaw/mat native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // URL explícita opcional para despliegues públicos/con proxy inverso callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,9 +526,9 @@ Mattermost se distribuye como un plugin: `openclaw plugins install @openclaw/mat } ``` -Modos de chat: `oncall` (responder ante mención con @, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que comienzan con un prefijo disparador). +Modos de chat: `oncall` (responder con mención @, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que empiezan con el prefijo disparador). -Cuando los comandos nativos de Mattermost están habilitados: +Cuando están habilitados los comandos nativos de Mattermost: - `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. @@ -539,10 +539,10 @@ Cuando los comandos nativos de Mattermost están habilitados: - Para hosts de callback privados/tailnet/internos, Mattermost puede requerir que `ServiceSettings.AllowedUntrustedInternalConnections` incluya el host/dominio del callback. Usa valores de host/dominio, no URLs completas. -- `channels.mattermost.configWrites`: permitir o denegar escrituras de configuración iniciadas desde Mattermost. +- `channels.mattermost.configWrites`: permitir o denegar escrituras de configuración iniciadas por Mattermost. - `channels.mattermost.requireMention`: requerir `@mention` antes de responder en canales. -- `channels.mattermost.groups..requireMention`: sobrescritura por canal para exigencia de mención (`"*"` para el valor predeterminado). -- `channels.mattermost.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- `channels.mattermost.groups..requireMention`: sustitución por canal para la exigencia de mención (`"*"` para predeterminado). +- `channels.mattermost.defaultAccount` opcional sustituye la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. ### Signal @@ -551,7 +551,7 @@ Cuando los comandos nativos de Mattermost están habilitados: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // vinculación de cuenta opcional dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -565,9 +565,9 @@ Cuando los comandos nativos de Mattermost están habilitados: **Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (de `reactionAllowlist`). -- `channels.signal.account`: fija el inicio del canal a una identidad de cuenta de Signal específica. -- `channels.signal.configWrites`: permitir o denegar 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.account`: fija el inicio del canal a una identidad específica de cuenta de Signal. +- `channels.signal.configWrites`: permitir o denegar escrituras de configuración iniciadas por Signal. +- `channels.signal.defaultAccount` opcional sustituye la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. ### BlueBubbles @@ -579,21 +579,21 @@ BlueBubbles es la ruta recomendada para iMessage (respaldada por plugin, configu bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl, password, webhookPath, controles de grupo y acciones avanzadas: + // consulta /channels/bluebubbles }, }, } ``` -- Rutas de clave 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 de nivel superior `bindings[]` con `type: "acp"` pueden vincular conversaciones de BlueBubbles a sesiones ACP persistentes. Usa 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). +- Rutas clave principales cubiertas aquí: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- `channels.bluebubbles.defaultAccount` opcional sustituye la selección de cuenta predeterminada 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 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 requiere daemon ni puerto. ```json5 { @@ -617,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 sustituye la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. - Requiere Full Disk Access a la base de datos de Messages. - Prefiere destinos `chat_id:`. Usa `imsg chats --limit 20` para listar chats. -- `cliPath` puede apuntar a un envoltorio SSH; establece `remoteHost` (`host` o `user@host`) para obtener adjuntos mediante SCP. +- `cliPath` puede apuntar a un wrapper SSH; configura `remoteHost` (`host` o `user@host`) para obtener 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 relevo ya exista en `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: permitir o denegar escrituras de configuración iniciadas desde iMessage. -- Las entradas de nivel superior `bindings[]` con `type: "acp"` pueden vincular conversaciones de iMessage a sesiones ACP persistentes. Usa 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). +- SCP usa verificación estricta de claves de host, así que asegúrate de que la clave del host de retransmisión ya exista en `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: permitir o denegar escrituras de configuración iniciadas por iMessage. +- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de iMessage a sesiones ACP persistentes. Usa un identificador normalizado o un destino explícito de chat (`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 @@ -668,21 +668,21 @@ Matrix está respaldado por 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 nombradas pueden sobrescribirlo con `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` y esta aceptació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 las salas invitadas y las invitaciones nuevas estilo DM se ignoran hasta que configures `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega nativa de aprobaciones de exec de Matrix y autorización de aprobadores. - - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo auto, las aprobaciones de exec se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. - - `approvers`: IDs de usuario de Matrix (p. ej. `@owner:example.org`) autorizados para aprobar solicitudes de exec. - - `agentFilter`: lista de permitidos opcional de IDs de agente. Omítela para reenviar aprobaciones de todos los agentes. +- La autenticación con token usa `accessToken`; la autenticación con 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 nombradas pueden sustituirlo con `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` y esta habilitación de red son controles independientes. +- `channels.matrix.defaultAccount` selecciona la cuenta preferida en configuraciones de múltiples cuentas. +- `channels.matrix.autoJoin` usa por defecto `off`, así que las salas invitadas y las nuevas invitaciones tipo MD se ignoran hasta que configures `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. +- `channels.matrix.execApprovals`: entrega de aprobaciones exec nativa de Matrix y autorización de aprobadores. + - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo auto, las aprobaciones exec se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. + - `approvers`: IDs de usuario de Matrix (p. ej. `@owner:example.org`) autorizados para aprobar solicitudes exec. + - `agentFilter`: lista opcional de IDs de agente permitidos. Omítela para reenviar aprobaciones para todos los agentes. - `sessionFilter`: patrones opcionales de claves de sesión (subcadena o regex). - - `target`: dónde enviar los avisos 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 se agrupan los DM de Matrix en sesiones: `per-user` (predeterminado) comparte por par enrutado, mientras que `per-room` aísla cada sala DM. -- Las sondas de estado y búsquedas de directorio en vivo de Matrix 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 destino y los ejemplos de configuración están documentados en [Matrix](/es/channels/matrix). + - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado), `"channel"` (sala de origen) o `"both"`. + - Sustituciones por cuenta: `channels.matrix.accounts..execApprovals`. +- `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 en tiempo de ejecución. +- La configuración completa de Matrix, reglas de destino y ejemplos de configuración están documentados en [Matrix](/es/channels/matrix). ### Microsoft Teams @@ -694,15 +694,15 @@ Microsoft Teams está respaldado por extensión y se configura en `channels.mste msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId, appPassword, tenantId, webhook, políticas de equipo/canal: + // consulta /channels/msteams }, }, } ``` -- Rutas de clave principales cubiertas aquí: `channels.msteams`, `channels.msteams.configWrites`. -- La configuración completa de Teams (credenciales, webhook, política DM/grupo, sobrescrituras por equipo/canal) está documentada en [Microsoft Teams](/es/channels/msteams). +- Rutas clave principales cubiertas aquí: `channels.msteams`, `channels.msteams.configWrites`. +- La configuración completa de Teams (credenciales, webhook, política de MD/grupo, sustituciones por equipo/canal) está documentada en [Microsoft Teams](/es/channels/msteams). ### IRC @@ -727,11 +727,11 @@ IRC está respaldado por extensión y se configura en `channels.irc`. } ``` -- Rutas de clave 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/exigencia de mención) está documentada en [IRC](/es/channels/irc). +- Rutas clave principales cubiertas aquí: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- `channels.irc.defaultAccount` opcional sustituye la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. +- La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permisos/exigencia de mención) está documentada en [IRC](/es/channels/irc). -### Varias cuentas (todos los canales) +### Múltiples cuentas (todos los canales) Ejecuta varias cuentas por canal (cada una con su propio `accountId`): @@ -756,25 +756,25 @@ Ejecuta varias 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**. -- La configuración base del canal se aplica a todas las cuentas salvo sobrescritura por cuenta. +- Los ajustes base del canal se aplican a todas las cuentas salvo que se sustituyan 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 onboarding de canal) mientras sigues 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 con alcance de cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los trasladan a `channels..accounts.default`; Matrix puede conservar en su lugar un destino nombrado/predeterminado existente que coincida. +- Si agregas una cuenta no predeterminada mediante `openclaw channels add` (o el onboarding del canal) mientras aún estás en una configuración de canal de una sola cuenta a nivel superior, OpenClaw promueve primero los valores de una sola cuenta 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 nombrado/default coincidente existente. - 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 una sola cuenta 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 nombrado/predeterminado existente que coincida. +- `openclaw doctor --fix` también repara formas mixtas moviendo los valores de una sola cuenta de nivel superior con alcance de cuenta a la cuenta promovida elegida para ese canal. La mayoría de los canales usa `accounts.default`; Matrix puede conservar un destino nombrado/default coincidente existente. ### Otros canales de extensión -Muchos canales de extensión se configuran como `channels.` y están documentados en sus páginas dedicadas de canal (por ejemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). +Muchos canales de extensión se configuran como `channels.` y se documentan en sus páginas dedicadas de canal (por ejemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). Consulta el índice completo de canales: [Channels](/es/channels). ### Exigencia de mención en chats grupales -Los mensajes de grupo requieren **mención** de forma predeterminada (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 usan por defecto **require mention** (mención en metadatos o patrones regex seguros). Se aplica a 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 self-chat de WhatsApp. -- **Patrones de texto**: patrones regex seguros en `agents.list[].groupChat.mentionPatterns`. Los patrones no válidos y la repetición anidada insegura se ignoran. +- **Menciones en metadatos**: menciones @ nativas de la plataforma. Se ignoran en el modo self-chat de WhatsApp. +- **Patrones de texto**: patrones regex seguros en `agents.list[].groupChat.mentionPatterns`. Los patrones inválidos y la repetición anidada insegura se ignoran. - La exigencia de mención solo se aplica cuando la detección es posible (menciones nativas o al menos un patrón). ```json5 @@ -788,9 +788,9 @@ Los mensajes de grupo requieren **mención** de forma predeterminada (mención e } ``` -`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 sustituirlo con `channels..historyLimit` (o por cuenta). Establece `0` para desactivarlo. -#### Límites de historial de DM +#### Límites de historial de MD ```json5 { @@ -805,13 +805,13 @@ Los mensajes de grupo requieren **mención** de forma predeterminada (mención e } ``` -Resolución: sobrescritura por DM → valor predeterminado del proveedor → sin límite (se conserva todo). +Resolución: sustitución por MD → predeterminado del proveedor → sin límite (se conserva todo). -Compatibles con: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Compatibles: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Modo self-chat -Incluye tu propio número en `allowFrom` para habilitar el modo self-chat (ignora menciones @ nativas, solo responde a patrones de texto): +Incluye tu propio número en `allowFrom` para habilitar el modo self-chat (ignora las menciones @ nativas, responde solo a patrones de texto): ```json5 { @@ -837,16 +837,16 @@ Incluye tu propio número en `allowFrom` para habilitar el modo self-chat (ignor ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // registrar comandos nativos cuando se admitan + nativeSkills: "auto", // registrar comandos nativos de Skills cuando se admitan + text: true, // analizar /commands en mensajes de chat + bash: false, // permitir ! (alias: /bash) bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // permitir /config + mcp: false, // permitir /mcp + plugins: false, // permitir /plugins + debug: false, // permitir /debug + restart: true, // permitir /restart + herramienta de reinicio del gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -859,33 +859,33 @@ Incluye tu propio número en `allowFrom` para habilitar el modo self-chat (ignor } ``` - + -- Este bloque configura las superficies de comandos. Para el catálogo actual de comandos integrados + bundled, consulta [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 canal/plugin 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 junto con [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. -- Sobrescribe por canal con `channels.discord.commands.native` (bool o `"auto"`). `false` borra los comandos registrados previamente. -- Sobrescribe el registro de Skills nativas por canal con `channels..commands.nativeSkills`. -- `channels.telegram.customCommands` añade entradas adicionales al menú del bot de Telegram. -- `bash: true` habilita `! ` para el shell del host. Requiere `tools.elevated.enabled` y remitente en `tools.elevated.allowFrom.`. -- `config: true` habilita `/config` (lee/escribe `openclaw.json`). Para clientes de gateway `chat.send`, las escrituras persistentes con `/config set|unset` también requieren `operator.admin`; el modo de solo lectura `/config show` sigue disponible para clientes normales con alcance de escritura. -- `mcp: true` habilita `/mcp` para la configuración del servidor MCP administrada por OpenClaw en `mcp.servers`. -- `plugins: true` habilita `/plugins` para descubrimiento de plugins, instalación y controles de habilitación/deshabilitación. -- `channels..configWrites` controla las mutaciones de configuración por canal (predeterminado: true). -- Para canales con varias cuentas, `channels..accounts..configWrites` también controla las escrituras que apuntan a esa cuenta (por ejemplo `/allowlist --config --account ` o `/config set channels..accounts....`). +- Este bloque configura las superficies de comandos. Para el catálogo actual de comandos integrados + agrupados, consulta [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 propios de canal/plugin 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 más [Slash Commands](/es/tools/slash-commands). +- Los comandos de texto deben ser mensajes **independientes** con `/` inicial. +- `native: "auto"` activa comandos nativos para Discord/Telegram y deja Slack desactivado. +- `nativeSkills: "auto"` activa comandos nativos de Skills para Discord/Telegram y deja Slack desactivado. +- Sustitución por canal: `channels.discord.commands.native` (bool o `"auto"`). `false` borra comandos registrados previamente. +- Sustituye el registro nativo de Skills por canal con `channels..commands.nativeSkills`. +- `channels.telegram.customCommands` agrega entradas extra al menú del bot de Telegram. +- `bash: true` habilita `! ` para la shell del host. Requiere `tools.elevated.enabled` y remitente 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 permiso de escritura. +- `mcp: true` habilita `/mcp` para la configuración de servidores MCP administrados por OpenClaw bajo `mcp.servers`. +- `plugins: true` habilita `/plugins` para descubrimiento, instalación y controles de habilitación/deshabilitación de plugins. +- `channels..configWrites` controla mutaciones de configuración por canal (predeterminado: true). +- Para canales de múltiples cuentas, `channels..accounts..configWrites` también controla las escrituras que apuntan a esa cuenta (por ejemplo `/allowlist --config --account ` o `/config set channels..accounts....`). - `restart: false` desactiva `/restart` y las acciones de herramienta de reinicio del gateway. Predeterminado: `true`. -- `ownerAllowFrom` es la lista explícita de permitidos para propietario de comandos/herramientas solo para propietario. Está separada de `allowFrom`. -- `ownerDisplay: "hash"` aplica hash a los ids del propietario en el system prompt. Establece `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/pairing del canal y `useAccessGroups`). -- `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 propietarios permitidos para comandos/herramientas solo de propietario. Está separada de `allowFrom`. +- `ownerDisplay: "hash"` aplica hash a los IDs de propietario en el system prompt. Establece `ownerDisplaySecret` para controlar el hash. +- `allowFrom` es por proveedor. Cuando está configurado, es la **única** fuente de autorización (se ignoran las listas de permisos/emparejamiento del canal y `useAccessGroups`). +- `useAccessGroups: false` permite que los comandos omitan las políticas de grupos de acceso cuando `allowFrom` no está configurado. - Mapa de documentación de comandos: - - catálogo integrado + bundled: [Slash Commands](/es/tools/slash-commands) - - superficies de comandos específicas del canal: [Channels](/es/channels) + - catálogo integrado + agrupado: [Slash Commands](/es/tools/slash-commands) + - superficies de comandos específicas de canal: [Channels](/es/channels) - comandos de QQ Bot: [QQ Bot](/es/channels/qqbot) - - comandos de pairing: [Pairing](/es/channels/pairing) - - comando card de LINE: [LINE](/es/channels/line) + - comandos de emparejamiento: [Pairing](/es/channels/pairing) + - comando de tarjeta de LINE: [LINE](/es/channels/line) - memory dreaming: [Dreaming](/es/concepts/dreaming) @@ -906,7 +906,7 @@ Predeterminado: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raíz opcional del repositorio mostrada en la línea Runtime del system prompt. 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 está configurada, OpenClaw la detecta automáticamente subiendo desde el workspace. ```json5 { @@ -916,7 +916,7 @@ Raíz opcional del repositorio mostrada en la línea Runtime del system prompt. ### `agents.defaults.skills` -Lista de permitidos predeterminada opcional de Skills para agentes que no establecen +Lista de permisos predeterminada opcional de Skills para agentes que no configuran `agents.list[].skills`. ```json5 @@ -924,19 +924,19 @@ Lista de permitidos predeterminada opcional de Skills para agentes que no establ agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // hereda github, weather + { id: "docs", skills: ["docs-search"] }, // reemplaza los predeterminados + { id: "locked-down", skills: [] }, // sin Skills ], }, } ``` -- Omite `agents.defaults.skills` para Skills sin restricciones de forma predeterminada. -- Omite `agents.list[].skills` para heredar los valores predeterminados. +- Omite `agents.defaults.skills` para Skills sin restricción de forma predeterminada. +- Omite `agents.list[].skills` para heredar los 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. + no se fusiona con los predeterminados. ### `agents.defaults.skipBootstrap` @@ -950,9 +950,9 @@ Desactiva la creación automática de archivos bootstrap del workspace (`AGENTS. ### `agents.defaults.contextInjection` -Controla cuándo se inyectan archivos bootstrap del workspace en el system prompt. Predeterminado: `"always"`. +Controla cuándo se inyectan los archivos bootstrap del workspace en el system prompt. Predeterminado: `"always"`. -- `"continuation-skip"`: los turnos de continuación segura (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 compaction siguen reconstruyendo el contexto. +- `"continuation-skip"`: los turnos seguros de continuación (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 compactación siguen reconstruyendo el contexto. ```json5 { @@ -962,7 +962,7 @@ Controla cuándo se inyectan archivos bootstrap del workspace en el system promp ### `agents.defaults.bootstrapMaxChars` -Máximo de caracteres por archivo bootstrap del workspace antes de truncarlo. Predeterminado: `20000`. +Máximo de caracteres por archivo bootstrap del workspace antes de truncar. Predeterminado: `20000`. ```json5 { @@ -972,7 +972,7 @@ Máximo de caracteres por archivo bootstrap del workspace antes de truncarlo. Pr ### `agents.defaults.bootstrapTotalMaxChars` -Máximo total de caracteres inyectados en todos los archivos bootstrap del workspace. Predeterminado: `150000`. +Máximo total de caracteres inyectados entre todos los archivos bootstrap del workspace. Predeterminado: `150000`. ```json5 { @@ -982,7 +982,7 @@ Máximo total de caracteres inyectados en todos los archivos bootstrap del works ### `agents.defaults.bootstrapPromptTruncationWarning` -Controla el texto de advertencia visible para el agente cuando se trunca el contexto bootstrap. +Controla el texto de advertencia visible para el agente cuando el contexto bootstrap se trunca. Predeterminado: `"once"`. - `"off"`: nunca inyecta texto de advertencia en el system prompt. @@ -997,11 +997,11 @@ Predeterminado: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Tamaño máximo en píxeles del lado más largo de una imagen en bloques de imagen de transcripción/herramienta antes de las llamadas al proveedor. +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. Predeterminado: `1200`. -Los valores más bajos suelen reducir el uso de vision tokens y el tamaño de la carga útil de la solicitud en ejecuciones con muchas capturas. -Los valores más altos conservan más detalle visual. +Valores más bajos suelen reducir el uso de vision tokens y el tamaño de la carga útil de la solicitud en ejecuciones con muchas capturas de pantalla. +Valores más altos conservan más detalle visual. ```json5 { @@ -1011,7 +1011,7 @@ Los valores más altos conservan más detalle visual. ### `agents.defaults.userTimezone` -Zona horaria para el contexto del system prompt (no para las marcas de tiempo de 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 la zona horaria del host como respaldo. ```json5 { @@ -1059,7 +1059,7 @@ Formato de hora en el system prompt. Predeterminado: `auto` (preferencia del SO) primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // parámetros globales predeterminados del proveedor pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1075,40 +1075,40 @@ Formato de hora en el system prompt. Predeterminado: `auto` (preferencia del SO) ``` - `model`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - La forma de cadena establece solo el modelo primario. - - La forma de objeto establece el modelo primario más los modelos de failover ordenados. + - La forma de cadena establece solo el modelo principal. + - La forma de objeto establece el principal más los modelos de failover ordenados. - `imageModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usa la ruta de 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 nativa de imágenes de Gemini, `fal/fal-ai/flux/dev` para fal, o `openai/gpt-image-1` para OpenAI Images. - - Si seleccionas directamente un provider/model, configura también la autenticación/API key correspondiente del proveedor (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 con autenticación. Primero intenta el proveedor predeterminado actual y luego los demás proveedores registrados de generación de imágenes en orden por id de proveedor. + - Si seleccionas directamente un provider/model, configura también la autenticación/API key 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 valor predeterminado de proveedor con autenticación. Primero prueba el proveedor predeterminado actual, luego los demás proveedores registrados de generación de imágenes 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`. - 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 con autenticación. Primero intenta el proveedor predeterminado actual y luego los demás proveedores registrados de generación de música en orden por id de proveedor. + - Si se omite, `music_generate` todavía puede inferir un valor predeterminado de proveedor con autenticación. Primero prueba el proveedor predeterminado actual, luego los demás proveedores registrados de generación de música en orden de ID de proveedor. - Si seleccionas directamente un provider/model, configura también la autenticación/API key correspondiente del proveedor. - `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`. - 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 con autenticación. Primero intenta el proveedor predeterminado actual y luego los demás proveedores registrados de generación de video en orden por id de proveedor. + - Si se omite, `video_generate` todavía puede inferir un valor predeterminado de proveedor con autenticación. Primero prueba el proveedor predeterminado actual, luego los demás proveedores registrados de generación de video en orden de ID de proveedor. - Si seleccionas directamente un provider/model, configura también la autenticación/API key correspondiente del proveedor. - - El proveedor bundled de generación de video Qwen admite actualmente 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`. + - El proveedor agrupado 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 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 `maxBytesMb` no se pasa en el momento de la llamada. -- `pdfMaxPages`: máximo predeterminado de páginas consideradas por el modo de extracción de respaldo en la herramienta `pdf`. -- `verboseDefault`: nivel detallado predeterminado para agentes. Valores: `"off"`, `"on"`, `"full"`. Predeterminado: `"off"`. + - Lo usa la herramienta `pdf` para el enrutamiento de modelos. + - Si se omite, la herramienta PDF usa como respaldo `imageModel` y luego el modelo resuelto de la sesión/predeterminado. +- `pdfMaxBytesMb`: límite predeterminado de tamaño del PDF para la herramienta `pdf` cuando no se pasa `maxBytesMb` en el momento de la llamada. +- `pdfMaxPages`: páginas máximas predeterminadas 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 exacto de modelo y solo después recurre al proveedor predeterminado configurado (comportamiento de compatibilidad obsoleto; por eso 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 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 globales predeterminados del proveedor aplicados a todos los modelos. Se establecen en `agents.defaults.params` (p. ej. `{ cacheRetention: "long" }`). -- Precedencia de fusión de `params` (configuración): `agents.defaults.params` (base global) es sobrescrito por `agents.defaults.models["provider/model"].params` (por modelo), luego `agents.list[].params` (id de agente coincidente) sobrescribe por clave. Consulta [Prompt Caching](/es/reference/prompt-caching) para más detalles. -- Los escritores de configuración que modifican estos campos (por ejemplo `/models set`, `/models set-image` y comandos de agregar/quitar fallback) guardan la forma de objeto canónica y conservan las listas de fallback existentes cuando es posible. -- `maxConcurrent`: máximo de ejecuciones paralelas de agentes entre sesiones (cada sesión sigue serializada). Predeterminado: 4. +- `model.primary`: formato `provider/model` (p. ej. `openai/gpt-5.4`). Si omites el proveedor, OpenClaw intenta primero un alias, luego una coincidencia única de proveedor configurado para ese ID de modelo exacto, y solo después vuelve al proveedor predeterminado configurado (comportamiento heredado de compatibilidad, así que prefiere `provider/model` explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw vuelve al primer provider/model configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. +- `models`: el catálogo y la lista de modelos permitidos configurados 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 definen en `agents.defaults.params` (p. ej. `{ cacheRetention: "long" }`). +- Precedencia de fusión de `params` (configuración): `agents.defaults.params` (base global) es sustituido por `agents.defaults.models["provider/model"].params` (por modelo), luego `agents.list[].params` (ID de agente coincidente) sustituye por clave. Consulta [Prompt Caching](/es/reference/prompt-caching) para más detalles. +- Los escritores de configuración que mutan estos campos (por ejemplo `/models set`, `/models set-image` y los comandos de agregar/eliminar fallback) guardan la forma canónica de objeto y conservan las listas fallback existentes cuando es posible. +- `maxConcurrent`: máximo de ejecuciones de agentes en paralelo entre sesiones (cada sesión sigue serializada). Predeterminado: 4. **Alias abreviados integrados** (solo se aplican cuando el modelo está en `agents.defaults.models`): @@ -1123,15 +1123,15 @@ Formato de hora en el system prompt. Predeterminado: `auto` (preferencia del SO) | `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. +Tus alias configurados siempre prevalecen sobre los predeterminados. -Los modelos Z.AI GLM-4.x habilitan automáticamente el modo thinking salvo que establezcas `--thinking off` o definas `agents.defaults.models["zai/"].params.thinking` por tu cuenta. -Los modelos Z.AI habilitan `tool_stream` de forma predeterminada para 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 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` por defecto 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 por defecto cuando no se establece un nivel explícito de thinking. ### `agents.defaults.cliBackends` -Backends CLI opcionales para ejecuciones de respaldo de solo texto (sin llamadas a herramientas). Útil como copia de seguridad cuando fallan los proveedores API. +Backends CLI opcionales para ejecuciones de respaldo solo de texto (sin llamadas a herramientas). Útiles como respaldo cuando fallan los proveedores de API. ```json5 { @@ -1159,9 +1159,23 @@ Backends CLI opcionales para ejecuciones de respaldo de solo texto (sin llamadas } ``` -- Los backends CLI son text-first; las herramientas siempre están desactivadas. -- Se admiten sesiones cuando `sessionArg` está definido. -- Se admite paso de imágenes cuando `imageArg` acepta rutas de archivo. +- Los backends CLI son principalmente de texto; las herramientas siempre están desactivadas. +- Sesiones compatibles cuando se establece `sessionArg`. +- Paso de imágenes compatible cuando `imageArg` acepta rutas de archivo. + +### `agents.defaults.systemPromptOverride` + +Reemplaza todo el system prompt ensamblado por OpenClaw con una cadena fija. Defínelo en el nivel predeterminado (`agents.defaults.systemPromptOverride`) o por agente (`agents.list[].systemPromptOverride`). Los valores por agente tienen prioridad; un valor vacío o solo con espacios se ignora. Útil para experimentos controlados de prompts. + +```json5 +{ + agents: { + defaults: { + systemPromptOverride: "You are a helpful assistant.", + }, + }, +} +``` ### `agents.defaults.heartbeat` @@ -1172,15 +1186,16 @@ Ejecuciones periódicas de heartbeat. agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m desactiva model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // predeterminado: true; false omite la sección Heartbeat del system prompt + lightContext: false, // predeterminado: false; true conserva solo HEARTBEAT.md de los archivos bootstrap del workspace + isolatedSession: false, // predeterminado: false; true ejecuta cada heartbeat en una sesión nueva (sin historial de conversación) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (predeterminado) | block + target: "none", // predeterminado: none | opciones: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1190,13 +1205,14 @@ Ejecuciones periódicas de heartbeat. } ``` -- `every`: cadena de duración (ms/s/m/h). Predeterminado: `30m` (autenticación con API key) o `1h` (autenticación OAuth). Establece `0m` para desactivarlo. -- `suppressToolErrorWarnings`: cuando es true, suprime las cargas útiles de advertencia de error de herramienta durante las ejecuciones de heartbeat. -- `directPolicy`: política de entrega directa/DM. `allow` (predeterminado) permite 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 contexto bootstrap ligero 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 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 heartbeats. -- Los heartbeats ejecutan turnos completos del agente; intervalos más cortos consumen más tokens. +- `every`: cadena de duración (ms/s/m/h). Predeterminado: `30m` (autenticación con API key) o `1h` (autenticación OAuth). Establece `0m` para desactivar. +- `includeSystemPromptSection`: cuando es false, omite la sección Heartbeat del system prompt y omite la inyección de `HEARTBEAT.md` en el contexto bootstrap. Predeterminado: `true`. +- `suppressToolErrorWarnings`: cuando es true, suprime las cargas de advertencia por errores de herramientas durante las ejecuciones de heartbeat. +- `directPolicy`: política de entrega directa/MD. `allow` (predeterminado) permite la entrega a destinos directos. `block` la suprime 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 previo de conversación. Mismo patrón de aislamiento que cron `sessionTarget: "isolated"`. Reduce el coste por heartbeat de ~100K a ~2-5K tokens. +- Por agente: configura `agents.list[].heartbeat`. Cuando cualquier agente define `heartbeat`, **solo esos agentes** ejecutan heartbeats. +- Los heartbeats ejecutan turnos completos del agente: intervalos más cortos consumen más tokens. ### `agents.defaults.compaction` @@ -1206,14 +1222,14 @@ Ejecuciones periódicas de heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // id de un plugin proveedor de compactación registrado (opcional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send a brief notice when compaction starts (default: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // usado cuando identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] desactiva la reinyección + model: "openrouter/anthropic/claude-sonnet-4-6", // sustitución opcional de modelo solo para compactación + notifyUser: true, // envía un aviso breve cuando comienza la compactación (predeterminado: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1226,19 +1242,19 @@ Ejecuciones periódicas de heartbeat. } ``` -- `mode`: `default` o `safeguard` (resumen por bloques 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. Recurre al integrado si falla. Establecer un proveedor fuerza `mode: "safeguard"`. Consulta [Compaction](/es/concepts/compaction). -- `timeoutSeconds`: número máximo de segundos permitidos para una única operación de compaction antes de que OpenClaw la aborte. Predeterminado: `900`. -- `identifierPolicy`: `strict` (predeterminado), `off` o `custom`. `strict` antepone orientación integrada de conservació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 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, los encabezados antiguos `Every Session`/`Safety` también se aceptan como respaldo heredado. -- `model`: sobrescritura opcional `provider/model-id` solo para el resumen de compaction. Úsala cuando la sesión principal deba mantener un modelo pero los resúmenes de compaction deban ejecutarse con otro; cuando no se define, compaction usa el modelo primario 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 mantener compaction en silencio. -- `memoryFlush`: turno silencioso y agéntico antes de la compaction automática para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura. +- `mode`: `default` o `safeguard` (resumen por fragmentos para historiales largos). Consulta [Compaction](/es/concepts/compaction). +- `provider`: id de un plugin proveedor de compactación registrado. Cuando está configurado, se llama a `summarize()` del proveedor en lugar del resumen LLM integrado. Si falla, vuelve al integrado. Configurar un proveedor fuerza `mode: "safeguard"`. Consulta [Compaction](/es/concepts/compaction). +- `timeoutSeconds`: segundos máximos permitidos para una sola operación de compactación antes de que OpenClaw la aborte. Predeterminado: `900`. +- `identifierPolicy`: `strict` (predeterminado), `off` o `custom`. `strict` antepone la guía integrada de conservación de identificadores opacos durante el resumen de compactación. +- `identifierInstructions`: texto opcional personalizado de conservación de identificadores usado cuando `identifierPolicy=custom`. +- `postCompactionSections`: nombres opcionales de secciones H2/H3 de AGENTS.md que se reinyectan después de la compactación. Predeterminado: `["Session Startup", "Red Lines"]`; establece `[]` para desactivar la reinyección. Cuando no está configurado o se establece explícitamente en ese par predeterminado, también se aceptan los encabezados heredados `Every Session`/`Safety` como respaldo. +- `model`: sustitución opcional `provider/model-id` solo para el resumen de compactación. Úsalo cuando la sesión principal deba mantener un modelo pero los resúmenes de compactación deban ejecutarse con otro; cuando no está configurado, la compactación usa el modelo principal de la sesión. +- `notifyUser`: cuando es `true`, envía un aviso breve al usuario al comenzar la compactación (por ejemplo, "Compacting context..."). Está desactivado por defecto para que la compactación sea silenciosa. +- `memoryFlush`: turno agentic silencioso antes de la auto-compactación para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura. ### `agents.defaults.contextPruning` -Poda **resultados antiguos de herramientas** del contexto en memoria antes de enviarlo al LLM. **No** modifica el historial de sesión en disco. +Recorta **resultados antiguos de herramientas** del contexto en memoria antes de enviarlo al LLM. **No** modifica el historial de la sesión en disco. ```json5 { @@ -1246,7 +1262,7 @@ Poda **resultados antiguos de herramientas** del contexto en memoria antes de en defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // duración (ms/s/m/h), unidad predeterminada: minutos keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1262,25 +1278,25 @@ Poda **resultados antiguos de herramientas** del contexto en memoria antes de en -- `mode: "cache-ttl"` habilita los pases de poda. -- `ttl` controla con qué frecuencia puede volver a ejecutarse la poda (después del último toque de caché). -- La poda primero recorta suavemente los resultados de herramientas sobredimensionados y luego limpia por completo resultados más antiguos si es necesario. +- `mode: "cache-ttl"` habilita las pasadas de recorte. +- `ttl` controla con qué frecuencia puede volver a ejecutarse el recorte (después del último acceso a la caché). +- El recorte primero aplica soft-trim a los resultados sobredimensionados de herramientas, y luego hard-clear a resultados antiguos de herramientas si es necesario. -**Soft-trim** conserva el comienzo + el final e inserta `...` en 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. +**Hard-clear** reemplaza todo el resultado de la herramienta con el placeholder. Notas: -- Los bloques de imagen nunca se recortan ni se limpian. -- 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. +- Los bloques de imagen nunca se recortan ni limpian. +- Las proporciones se basan en caracteres (aproximadas), no en recuentos exactos de tokens. +- Si existen menos de `keepLastAssistants` mensajes del asistente, se omite el recorte. Consulta [Session Pruning](/es/concepts/session-pruning) para detalles del comportamiento. -### Streaming por bloques +### Block streaming ```json5 { @@ -1290,17 +1306,17 @@ Consulta [Session Pruning](/es/concepts/session-pruning) para detalles del compo blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (usa minMs/maxMs) }, }, } ``` -- 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 usan por defecto `minChars: 1500`. -- `humanDelay`: pausa aleatoria entre respuestas por bloques. `natural` = 800–2500ms. Sobrescritura por agente: `agents.list[].humanDelay`. +- Los canales no Telegram requieren `*.blockStreaming: true` explícito para habilitar respuestas por bloques. +- Sustituciones 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. Sustitución por agente: `agents.list[].humanDelay`. -Consulta [Streaming](/es/concepts/streaming) para el comportamiento y los detalles del fragmentado. +Consulta [Streaming](/es/concepts/streaming) para comportamiento + detalles de fragmentación. ### Indicadores de escritura @@ -1316,7 +1332,7 @@ Consulta [Streaming](/es/concepts/streaming) para el comportamiento y los detall ``` - Predeterminados: `instant` para chats directos/menciones, `message` para chats grupales sin mención. -- Sobrescrituras por sesión: `session.typingMode`, `session.typingIntervalSeconds`. +- Sustituciones por sesión: `session.typingMode`, `session.typingIntervalSeconds`. Consulta [Typing Indicators](/es/concepts/typing-indicators). @@ -1370,7 +1386,7 @@ Sandboxing opcional para el agente integrado. Consulta [Sandboxing](/es/gateway/ identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // También se admiten SecretRefs / contenidos en línea: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1419,45 +1435,45 @@ Sandboxing opcional para el agente integrado. Consulta [Sandboxing](/es/gateway/ } ``` - + **Backend:** -- `docker`: entorno Docker local (predeterminado) -- `ssh`: entorno remoto genérico respaldado por SSH -- `openshell`: entorno OpenShell +- `docker`: runtime local de Docker (predeterminado) +- `ssh`: runtime remoto genérico respaldado por SSH +- `openshell`: runtime de OpenShell -Cuando se selecciona `backend: "openshell"`, la configuración específica del entorno se mueve a +Cuando se selecciona `backend: "openshell"`, los ajustes específicos del runtime se mueven a `plugins.entries.openshell.config`. **Configuración del backend SSH:** -- `target`: destino SSH en formato `user@host[:port]` +- `target`: destino SSH con formato `user@host[:port]` - `command`: comando del cliente SSH (predeterminado: `ssh`) - `workspaceRoot`: raíz remota absoluta usada para workspaces por alcance - `identityFile` / `certificateFile` / `knownHostsFile`: archivos locales existentes pasados a OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: contenido en línea o SecretRefs que OpenClaw materializa en archivos temporales durante el tiempo de ejecución -- `strictHostKeyChecking` / `updateHostKeys`: opciones de política de clave de host de OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: contenidos en línea o SecretRefs que OpenClaw materializa en archivos temporales en tiempo de ejecución +- `strictHostKeyChecking` / `updateHostKeys`: ajustes de política de claves 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 desde la instantánea activa del entorno de secretos antes de que comience la sesión sandbox +- `identityData` prevalece sobre `identityFile` +- `certificateData` prevalece sobre `certificateFile` +- `knownHostsData` prevalece 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 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 archivo y rutas de medios por SSH -- no sincroniza automáticamente los cambios remotos de vuelta al host +- siembra el workspace remoto una vez después de crear o recrear +- luego conserva como canónico el workspace SSH remoto +- enruta `exec`, herramientas de archivos y rutas de medios por SSH +- no sincroniza automáticamente al host los cambios remotos - no admite contenedores de navegador sandbox **Acceso al workspace:** -- `none`: workspace sandbox por alcance en `~/.openclaw/sandboxes` -- `ro`: workspace sandbox en `/workspace`, workspace del agente montado en solo lectura en `/agent` +- `none`: workspace sandbox por alcance bajo `~/.openclaw/sandboxes` +- `ro`: workspace sandbox en `/workspace`, workspace del agente montado como solo lectura en `/agent` - `rw`: workspace del agente montado en lectura/escritura en `/workspace` **Alcance:** @@ -1479,10 +1495,10 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del e from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // opcional + gatewayEndpoint: "https://lab.example", // opcional + policy: "strict", // id de política de OpenShell opcional + providers: ["openai"], // opcional autoProviders: true, timeoutSeconds: 120, }, @@ -1494,30 +1510,30 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del e **Modo OpenShell:** -- `mirror`: inicializa el remoto desde lo local antes de exec, sincroniza de vuelta después de exec; el workspace local sigue siendo el canónico -- `remote`: inicializa el remoto una vez cuando se crea el sandbox y luego mantiene el workspace remoto como canónico +- `mirror`: siembra el remoto desde local antes de exec, sincroniza de vuelta después de exec; el workspace local sigue siendo el canónico +- `remote`: siembra el remoto una vez cuando se crea el sandbox, luego conserva como canónico el workspace remoto -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 el modo `remote`, las ediciones locales del host hechas fuera de OpenClaw no se sincronizan automáticamente al sandbox después del paso inicial de siembra. +El transporte es SSH al sandbox de OpenShell, pero el plugin es dueño del ciclo de vida del sandbox y de la sincronización espejo opcional. **`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 usan por defecto `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` (break-glass). +**Los contenedores usan por defecto `network: "none"`**; configúralo en `"bridge"` (o una red bridge personalizada) si el agente necesita acceso saliente. +`"host"` está bloqueado. `"container:"` está bloqueado por defecto a menos que establezcas explícitamente +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (emergencia). -**Los adjuntos entrantes** se colocan temporalmente en `media/inbound/*` dentro del workspace activo. +**Los adjuntos entrantes** se almacenan temporalmente en `media/inbound/*` en el workspace activo. **`docker.binds`** monta directorios adicionales del host; los binds globales y por agente se fusionan. -**Navegador sandbox** (`sandbox.browser.enabled`): Chromium + CDP en un contenedor. La URL de noVNC se inyecta 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). +**Navegador en sandbox** (`sandbox.browser.enabled`): Chromium + CDP en un contenedor. La URL de noVNC se inyecta en el system prompt. No requiere `browser.enabled` en `openclaw.json`. +El acceso de observador noVNC usa autenticación VNC por defecto 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 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 global de bridge. -- `cdpSourceRange` restringe opcionalmente el ingreso 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 de navegador sandbox. Cuando se establece (incluido `[]`), reemplaza `docker.binds` para el contenedor del navegador. -- Los valores predeterminados de lanzamiento están definidos en `scripts/sandbox-browser-entrypoint.sh` y ajustados para hosts de contenedor: +- `network` usa por defecto `openclaw-sandbox-browser` (red bridge dedicada). Configúralo en `bridge` solo cuando quieras explícitamente conectividad global del bridge. +- `cdpSourceRange` restringe opcionalmente la entrada 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 sandbox. Cuando está configurado (incluido `[]`), reemplaza `docker.binds` para el contenedor del navegador. +- Los valores de inicio predeterminados 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` @@ -1534,30 +1550,31 @@ El acceso de observador noVNC usa autenticación VNC de forma predeterminada y O - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (habilitado de forma predeterminada) + - `--disable-extensions` (habilitado por defecto) - `--disable-3d-apis`, `--disable-software-rasterizer` y `--disable-gpu` están - habilitados de forma predeterminada y pueden desactivarse con + habilitados por defecto 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 extensiones si tu flujo de trabajo depende de ellas. - `--renderer-process-limit=2` puede cambiarse con - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; establece `0` para usar el - límite de procesos predeterminado de Chromium. + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; establece `0` para usar + el límite predeterminado de procesos de Chromium. - además de `--no-sandbox` y `--disable-setuid-sandbox` cuando `noSandbox` está habilitado. - - Los valores predeterminados son la base de la imagen del contenedor; usa una imagen de navegador personalizada con un entrypoint personalizado para cambiar los valores predeterminados del contenedor. + - 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. -El sandboxing de navegador y `sandbox.docker.binds` actualmente son solo para Docker. +El sandboxing del navegador y `sandbox.docker.binds` solo son compatibles con Docker. -Construir imágenes: +Compilar imágenes: ```bash scripts/sandbox-setup.sh # imagen principal de sandbox -scripts/sandbox-browser-setup.sh # imagen opcional de navegador +scripts/sandbox-browser-setup.sh # imagen opcional del navegador ``` -### `agents.list` (sobrescrituras por agente) +### `agents.list` (sustituciones por agente) ```json5 { @@ -1569,12 +1586,12 @@ scripts/sandbox-browser-setup.sh # imagen opcional de navegador 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 - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + model: "anthropic/claude-opus-4-6", // o { primary, fallbacks } + thinkingDefault: "high", // sustitución del nivel thinking por agente + reasoningDefault: "on", // sustitución de visibilidad de reasoning por agente + fastModeDefault: false, // sustitución de modo fast por agente + params: { cacheRetention: "none" }, // sustituye por clave los params coincidentes de defaults.models + skills: ["docs-search"], // reemplaza agents.defaults.skills cuando se establece identity: { name: "Samantha", theme: "helpful sloth", @@ -1605,26 +1622,26 @@ scripts/sandbox-browser-setup.sh # imagen opcional de navegador } ``` -- `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 fallbacks globales). Los trabajos cron que solo sobrescriben `primary` siguen heredando los fallbacks predeterminados salvo que establezcas `fallbacks: []`. -- `params`: parámetros de flujo por agente fusionados sobre la entrada del modelo seleccionado en `agents.defaults.models`. Úsalo 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á definido; una lista explícita reemplaza los valores predeterminados en lugar de fusionarse, y `[]` significa que no hay Skills. -- `thinkingDefault`: nivel thinking predeterminado opcional por agente (`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`: visibilidad de reasoning predeterminada opcional por agente (`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 fast mode (`true | false`). Se aplica cuando no se establece una sobrescritura por mensaje o sesión. -- `runtime`: descriptor de runtime opcional por agente. Usa `type: "acp"` con los valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar por defecto sesiones del arnés ACP. +- `id`: ID estable del agente (obligatorio). +- `default`: cuando se establecen varios, gana el primero (se registra una advertencia). Si ninguno está establecido, la primera entrada de la lista es la predeterminada. +- `model`: la forma de cadena sustituye solo `primary`; la forma de objeto `{ primary, fallbacks }` sustituye ambos (`[]` desactiva los fallbacks globales). Los cron jobs que solo sustituyen `primary` siguen heredando los fallbacks predeterminados salvo que establezcas `fallbacks: []`. +- `params`: parámetros de stream por agente fusionados sobre la entrada del modelo seleccionado en `agents.defaults.models`. Úsalo para sustituciones específicas del agente como `cacheRetention`, `temperature` o `maxTokens` sin duplicar todo el catálogo de modelos. +- `skills`: lista opcional de Skills permitidas por agente. Si se omite, el agente hereda `agents.defaults.skills` cuando está configurado; una lista explícita reemplaza los predeterminados en lugar de fusionarse, y `[]` significa sin Skills. +- `thinkingDefault`: nivel predeterminado opcional de thinking por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Sustituye `agents.defaults.thinkingDefault` para este agente cuando no hay sustitución por mensaje o sesión. +- `reasoningDefault`: visibilidad predeterminada opcional de reasoning por agente (`on | off | stream`). Se aplica cuando no hay sustitución de reasoning por mensaje o sesión. +- `fastModeDefault`: valor predeterminado opcional por agente para modo fast (`true | false`). Se aplica cuando no hay sustitución de modo fast por mensaje o sesión. +- `runtime`: descriptor opcional de runtime por agente. Usa `type: "acp"` con los valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar sesiones del arnés ACP por defecto. - `identity.avatar`: ruta relativa al workspace, URL `http(s)` o URI `data:`. -- `identity` deriva valores predeterminados: `ackReaction` desde `emoji`, `mentionPatterns` desde `name`/`emoji`. -- `subagents.allowAgents`: lista de permitidos de ids de agente para `sessions_spawn` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). -- Protección de herencia 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 llamadas a `sessions_spawn` que omiten `agentId` (obliga a una selección de perfil explícita; predeterminado: false). +- `identity` deriva predeterminados: `ackReaction` desde `emoji`, `mentionPatterns` desde `name`/`emoji`. +- `subagents.allowAgents`: lista permitida de IDs de agente para `sessions_spawn` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- Protección de herencia de sandbox: si la sesión solicitante está en sandbox, `sessions_spawn` rechaza objetivos que se ejecutarían sin sandbox. +- `subagents.requireAgentId`: cuando es true, bloquea llamadas `sessions_spawn` que omiten `agentId` (fuerza selección explícita de perfil; predeterminado: false). --- -## Enrutamiento de múltiples agentes +## Enrutamiento multiagente -Ejecuta varios agentes aislados dentro de un mismo Gateway. Consulta [Multi-Agent](/es/concepts/multi-agent). +Ejecuta varios agentes aislados dentro de un solo Gateway. Consulta [Multi-Agent](/es/concepts/multi-agent). ```json5 { @@ -1641,27 +1658,27 @@ Ejecuta varios agentes aislados dentro de un mismo Gateway. Consulta [Multi-Agen } ``` -### Campos de coincidencia de binding +### Campos de coincidencia del enlace -- `type` (opcional): `route` para enrutamiento normal (si falta el tipo, por defecto es route), `acp` para enlaces persistentes de conversación ACP. +- `type` (opcional): `route` para enrutamiento normal (si falta, route es el predeterminado), `acp` para enlaces persistentes de conversación 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 `type: "acp"`): `{ mode, label, cwd, backend }` +- `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` 3. `match.teamId` 4. `match.accountId` (exacto, sin peer/guild/team) -5. `match.accountId: "*"` (canal completo) +5. `match.accountId: "*"` (en todo el canal) 6. Agente predeterminado Dentro de cada nivel, gana la primera entrada coincidente de `bindings`. -Para entradas de `type: "acp"`, OpenClaw resuelve por identidad exacta de conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden de niveles de route binding anterior. +Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden por niveles de route binding anterior. ### Perfiles de acceso por agente @@ -1784,22 +1801,22 @@ Consulta [Multi-Agent Sandbox & Tools](/es/tools/multi-agent-sandbox-tools) para }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // omitir fork del hilo padre por encima de este recuento de tokens (0 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", // opcional presupuesto 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, // auto-unfocus predeterminado por inactividad en horas (`0` desactiva) + maxAgeHours: 0, // antigüedad máxima estricta predeterminada en horas (`0` 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" } }], @@ -1811,35 +1828,35 @@ Consulta [Multi-Agent Sandbox & Tools](/es/tools/multi-agent-sandbox-tools) para -- **`scope`**: estrategia base de agrupación de sesiones para contextos de chat grupal. +- **`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 (úsalo solo cuando se pretende un contexto compartido). -- **`dmScope`**: cómo se agrupan los DM. - - `main`: todos los DM comparten la sesión principal. - - `per-peer`: aísla por id de remitente entre canales. + - `global`: todos los participantes en un contexto de canal comparten una sola sesión (úsalo solo cuando se quiera contexto compartido). +- **`dmScope`**: cómo se agrupan los MD. + - `main`: todos los MD comparten la sesión principal. + - `per-peer`: aísla por ID del 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 varias cuentas). -- **`identityLinks`**: asigna ids canónicos a peers con prefijo de proveedor para compartir sesión entre canales. -- **`reset`**: política principal de restablecimiento. `daily` restablece a la `atHour` local; `idle` restablece tras `idleMinutes`. Cuando ambos están configurados, gana el que venza 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 padre permitido 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 del padre. -- **`mainKey`**: campo heredado. El entorno de ejecución ahora siempre usa `"main"` para el bucket principal de chat directo. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de respuesta entre agentes durante intercambios agent-to-agent (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`. La primera denegación gana. -- **`maintenance`**: controles de limpieza y retención del almacén de sesiones. + - `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 tras `idleMinutes`. Cuando ambos están configurados, gana el que venza antes. +- **`resetByType`**: sustituciones por tipo (`direct`, `group`, `thread`). Se acepta `dm` heredado como alias de `direct`. +- **`parentForkMaxTokens`**: `totalTokens` máximo permitido en la sesión padre al crear una sesión de hilo derivada (predeterminado `100000`). + - Si `totalTokens` del padre supera este valor, OpenClaw inicia una nueva sesión de hilo en lugar de heredar el historial de transcripción del padre. + - Establece `0` para desactivar esta protección y permitir siempre el fork del padre. +- **`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 de ida y vuelta 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 el primer deny. +- **`maintenance`**: limpieza + controles de 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.`. Predeterminado igual a `pruneAfter`; establece `false` para desactivarlo. + - `resetArchiveRetention`: retención para archivos de transcripción `*.reset.`. Usa `pruneAfter` como predeterminado; establece `false` para desactivar. - `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 tras la limpieza por presupuesto. Predeterminado: `80%` de `maxDiskBytes`. -- **`threadBindings`**: valores predeterminados globales para funciones de sesión vinculadas a hilos. - - `enabled`: interruptor maestro predeterminado (los proveedores pueden sobrescribirlo; Discord usa `channels.discord.threadBindings.enabled`) - - `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` lo desactiva; los proveedores pueden sobrescribirlo) + - `highWaterBytes`: objetivo opcional después de la limpieza por presupuesto. Predeterminado: `80%` de `maxDiskBytes`. +- **`threadBindings`**: valores predeterminados globales para funciones de sesión ligadas a hilos. + - `enabled`: interruptor maestro predeterminado (los proveedores pueden sustituirlo; Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: auto-unfocus predeterminado por inactividad en horas (`0` desactiva; los proveedores pueden sustituir) + - `maxAgeHours`: antigüedad máxima estricta predeterminada en horas (`0` desactiva; los proveedores pueden sustituir) @@ -1850,7 +1867,7 @@ Consulta [Multi-Agent Sandbox & Tools](/es/tools/multi-agent-sandbox-tools) para ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // o "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1865,7 +1882,7 @@ Consulta [Multi-Agent Sandbox & Tools](/es/tools/multi-agent-sandbox-tools) para }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 desactiva byChannel: { whatsapp: 5000, slack: 1500, @@ -1877,36 +1894,36 @@ Consulta [Multi-Agent Sandbox & Tools](/es/tools/multi-agent-sandbox-tools) para ### Prefijo de respuesta -Sobrescrituras por canal/cuenta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Sustituciones por canal/cuenta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. Resolución (gana la más específica): cuenta → canal → global. `""` desactiva y detiene la cascada. `"auto"` deriva `[{identity.name}]`. **Variables de plantilla:** -| Variable | Descripción | Ejemplo | -| ----------------- | ----------------------- | --------------------------- | +| Variable | Descripción | Ejemplo | +| ----------------- | ---------------------- | --------------------------- | | `{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"`) | +| `{provider}` | Nombre del proveedor | `anthropic` | +| `{thinkingLevel}` | Nivel actual de thinking | `high`, `low`, `off` | +| `{identity.name}` | Nombre de identidad del agente | (igual que `"auto"`) | -Las variables no distinguen 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 acuse -- Por defecto usa `identity.emoji` del agente activo y, si no existe, `"👀"`. Establece `""` para desactivarla. -- Sobrescrituras por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Usa por defecto `identity.emoji` del agente activo; en otro caso `"👀"`. Establece `""` para desactivar. +- Sustituciones 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 el acuse tras responder en Slack, Discord y Telegram. -- `messages.statusReactions.enabled`: habilita reacciones de estado de ciclo de vida en Slack, Discord y Telegram. - En Slack y Discord, si no se establece, las reacciones de estado permanecen habilitadas cuando las reacciones de acuse están activas. - En Telegram, establécelo explícitamente en `true` para habilitar reacciones de estado de ciclo de vida. +- `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, si no está configurado, mantiene activadas las reacciones de estado cuando las reacciones de acuse están activas. + En Telegram, configúralo explícitamente en `true` para habilitar reacciones de estado del ciclo de vida. -### Antirrebote de entrada +### Debounce de entrada -Agrupa mensajes rápidos de solo texto del mismo remitente en un único turno del agente. Los medios/adjuntos vacían la cola de inmediato. Los comandos de control omiten el antirrebote. +Agrupa mensajes rápidos solo de texto del mismo remitente en un único turno del agente. Los medios/adjuntos se vacían inmediatamente. Los comandos de control omiten el debounce. ### TTS (text-to-speech) @@ -1949,18 +1966,18 @@ Agrupa mensajes rápidos de solo 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. -- `summaryModel` sobrescribe `agents.defaults.model.primary` para el resumen automático. -- `modelOverrides` está habilitado de forma predeterminada; `modelOverrides.allowProvider` tiene como valor predeterminado `false` (opt-in). -- Las API keys recurren a `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`, 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. +- `auto` controla el modo predeterminado de auto-TTS: `off`, `always`, `inbound` o `tagged`. `/tts on|off` puede sustituir las preferencias locales, y `/tts status` muestra el estado efectivo. +- `summaryModel` sustituye `agents.defaults.model.primary` para el auto-resumen. +- `modelOverrides` está habilitado por defecto; `modelOverrides.allowProvider` usa `false` por defecto (opt-in). +- Las API keys usan como respaldo `ELEVENLABS_API_KEY`/`XI_API_KEY` y `OPENAI_API_KEY`. +- `openai.baseUrl` sustituye el endpoint TTS de OpenAI. Orden de resolución: 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 relaja la validación de modelo/voz. --- ## Talk -Valores predeterminados para el modo Talk (macOS/iOS/Android). +Predeterminados para el modo Talk (macOS/iOS/Android). ```json5 { @@ -1984,13 +2001,13 @@ Valores predeterminados para el modo Talk (macOS/iOS/Android). } ``` -- `talk.provider` debe coincidir con una clave en `talk.providers` cuando se configuran varios proveedores Talk. -- 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.`. +- `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.`. - 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 API key de Talk configurada. +- `providers.*.apiKey` acepta cadenas en texto plano u objetos SecretRef. +- El respaldo `ELEVENLABS_API_KEY` solo se aplica cuando no se configura una API key de Talk. - `providers.*.voiceAliases` permite que las directivas de Talk usen nombres amigables. -- `silenceTimeoutMs` controla cuánto espera el modo Talk tras el 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`). +- `silenceTimeoutMs` controla cuánto espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no está configurado, se conserva la ventana de pausa predeterminada de la plataforma (`700 ms en macOS y Android, 900 ms en iOS`). --- @@ -1998,16 +2015,16 @@ Valores predeterminados para el modo Talk (macOS/iOS/Android). ### Perfiles de herramientas -`tools.profile` establece una lista de permitidos base antes de `tools.allow`/`tools.deny`: +`tools.profile` establece una lista base de permisos antes de `tools.allow`/`tools.deny`: -El onboarding local establece de forma predeterminada `tools.profile: "coding"` en nuevas configuraciones locales cuando no está definido (los perfiles explícitos existentes se conservan). +El onboarding local establece por defecto en nuevas configuraciones locales `tools.profile: "coding"` cuando no está configurado (los perfiles explícitos existentes se conservan). | 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 restricciones (igual que no definirlo) | +| `full` | Sin restricción (igual que no configurado) | ### Grupos de herramientas @@ -2028,7 +2045,7 @@ El onboarding local establece de forma predeterminada `tools.profile: "coding"` ### `tools.allow` / `tools.deny` -Política global de permitir/denegar herramientas (la denegación gana). No distingue mayúsculas y minúsculas, admite comodines `*`. Se aplica incluso cuando el sandbox Docker está desactivado. +Política global de permitir/denegar herramientas (deny prevalece). No distingue mayúsculas de minúsculas y admite comodines `*`. Se aplica incluso cuando el sandbox de Docker está desactivado. ```json5 { @@ -2038,7 +2055,7 @@ Política global de permitir/denegar herramientas (la denegación gana). No dist ### `tools.byProvider` -Restringe aún más las herramientas para proveedores o modelos específicos. Orden: perfil base → perfil de proveedor → allow/deny. +Restringe aún más las herramientas para proveedores o modelos específicos. Orden: perfil base → perfil del proveedor → allow/deny. ```json5 { @@ -2070,9 +2087,9 @@ Controla el acceso exec elevado 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 destino de exec es `node`). +- La sustitución por agente (`agents.list[].tools.elevated`) solo puede restringir aún más. +- `/elevated on|off|ask|full` guarda 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` por defecto, o `node` cuando el destino exec es `node`). ### `tools.exec` @@ -2096,8 +2113,8 @@ Controla el acceso exec elevado 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. -La configuración puede definirse globalmente en `tools.loopDetection` y sobrescribirse por agente en `agents.list[].tools.loopDetection`. +Las verificaciones de seguridad de bucles de herramientas están **desactivadas por defecto**. Establece `enabled: true` para activar la detección. +Los ajustes pueden definirse globalmente en `tools.loopDetection` y sustituirse por agente en `agents.list[].tools.loopDetection`. ```json5 { @@ -2118,13 +2135,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. -- `warningThreshold`: umbral de patrón repetitivo sin progreso para advertencias. -- `criticalThreshold`: umbral repetitivo superior para bloquear bucles críticos. -- `globalCircuitBreakerThreshold`: umbral de parada 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 por pares sin progreso. +- `historySize`: historial máximo de llamadas a herramientas conservado para análisis de bucles. +- `warningThreshold`: umbral de patrones repetidos sin progreso para advertencias. +- `criticalThreshold`: umbral repetido más alto para bloquear bucles críticos. +- `globalCircuitBreakerThreshold`: umbral de parada estricta para cualquier ejecución sin progreso. +- `detectors.genericRepeat`: advierte sobre llamadas repetidas a la misma herramienta/con los mismos args. +- `detectors.knownPollNoProgress`: advierte/bloquea herramientas conocidas de sondeo (`process.poll`, `command_status`, etc.). +- `detectors.pingPong`: advierte/bloquea patrones alternos de pares sin progreso. - Si `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la validación falla. ### `tools.web` @@ -2135,14 +2152,14 @@ La configuración puede definirse globalmente en `tools.loopDetection` y sobresc web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // o entorno BRAVE_API_KEY maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // opcional; omitir para autodetección maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2167,7 +2184,7 @@ Configura la comprensión de medios entrantes (imagen/audio/video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // opt-in: enviar música/video asíncronos finalizados directamente al canal }, audio: { enabled: true, @@ -2195,26 +2212,26 @@ Configura la comprensión de medios entrantes (imagen/audio/video): **Entrada de proveedor** (`type: "provider"` u omitido): -- `provider`: id del proveedor API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) -- `model`: sobrescritura del id de modelo -- `profile` / `preferredProfile`: selección de perfil de `auth-profiles.json` +- `provider`: id del proveedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) +- `model`: sustitución del ID de modelo +- `profile` / `preferredProfile`: selección del perfil de `auth-profiles.json` **Entrada CLI** (`type: "cli"`): -- `command`: ejecutable a ejecutar -- `args`: argumentos con plantilla (admite `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) +- `command`: ejecutable que se va a ejecutar +- `args`: args con plantilla (admite `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) **Campos comunes:** - `capabilities`: lista opcional (`image`, `audio`, `video`). Predeterminados: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: sobrescrituras por entrada. -- Los fallos recurren a la siguiente entrada. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: sustituciones por entrada. +- Los fallos pasan a la siguiente entrada. La autenticación del proveedor sigue el orden estándar: `auth-profiles.json` → variables de entorno → `models.providers.*.apiKey`. **Campos de finalización asíncrona:** -- `asyncCompletion.directSend`: cuando es `true`, las tareas completadas de +- `asyncCompletion.directSend`: cuando es `true`, las tareas completadas `music_generate` y `video_generate` intentan primero la entrega directa al canal. Predeterminado: `false` (ruta heredada de activación de sesión solicitante/entrega por modelo). @@ -2237,7 +2254,7 @@ La autenticación del proveedor sigue el orden estándar: `auth-profiles.json` Controla a qué sesiones pueden dirigirse las herramientas de sesión (`sessions_list`, `sessions_history`, `sessions_send`). -Predeterminado: `tree` (sesión actual + sesiones generadas por ella, como subagents). +Predeterminado: `tree` (sesión actual + sesiones generadas por ella, como subagentes). ```json5 { @@ -2253,25 +2270,25 @@ Predeterminado: `tree` (sesión actual + sesiones generadas por ella, como subag Notas: - `self`: solo la clave de la sesión actual. -- `tree`: sesión actual + sesiones generadas por la sesión actual (subagents). -- `agent`: cualquier sesión perteneciente al id de agente actual (puede incluir otros usuarios si ejecutas sesiones per-sender bajo el mismo id de agente). +- `tree`: sesión actual + sesiones generadas por la sesión actual (subagentes). +- `agent`: cualquier sesión perteneciente al ID del agente actual (puede incluir otros usuarios si ejecutas sesiones per-sender bajo el mismo ID de agente). - `all`: cualquier sesión. El direccionamiento entre agentes sigue requiriendo `tools.agentToAgent`. - Restricció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 el soporte de adjuntos en línea para `sessions_spawn`. +Controla la compatibilidad con adjuntos en línea para `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // opt-in: establece true para permitir adjuntos de archivo en línea + maxTotalBytes: 5242880, // 5 MB totales entre todos los archivos maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 1 MB por archivo + retainOnSessionKeep: false, // conservar adjuntos cuando cleanup="keep" }, }, }, @@ -2280,22 +2297,22 @@ Controla el soporte de adjuntos en línea para `sessions_spawn`. Notas: -- Los adjuntos solo son compatibles con `runtime: "subagent"`. El entorno ACP los rechaza. +- Los adjuntos solo son compatibles con `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 transcripción. -- Las entradas base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección previa de tamaño antes de la decodificación. -- Los permisos de archivos son `0700` para directorios y `0600` para archivos. +- El contenido de los adjuntos se redacta automáticamente de la persistencia de la transcripción. +- Las entradas base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección de tamaño antes de decodificar. +- 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` solo los conserva cuando `retainOnSessionKeep: true`. ### `tools.experimental` -Indicadores de herramientas integradas experimentales. Predeterminado desactivado a menos que se aplique una regla de autoactivación específica del entorno. +Flags experimentales de herramientas integradas. Desactivado por defecto salvo que se aplique una regla de auto-enable específica del runtime. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // habilitar update_plan experimental }, }, } @@ -2303,9 +2320,9 @@ Indicadores de herramientas integradas experimentales. Predeterminado desactivad Notas: -- `planTool`: habilita la herramienta estructurada experimental `update_plan` para el seguimiento de trabajo no trivial de varios pasos. -- Predeterminado: `false` para proveedores que no son OpenAI. Las ejecuciones de OpenAI y OpenAI Codex la habilitan automáticamente cuando no está definida; establece `false` para desactivar esa autoactivación. -- Cuando está habilitada, el system prompt también añade orientación de uso para que el modelo la use solo para trabajo sustancial y mantenga como máximo un paso en `in_progress`. +- `planTool`: habilita la herramienta estructurada `update_plan` para seguimiento de trabajo no trivial de varios pasos. +- Predeterminado: `false` para proveedores no OpenAI. Las ejecuciones de OpenAI y OpenAI Codex la habilitan automáticamente cuando no está configurada; establece `false` para desactivar ese auto-enable. +- Cuando está habilitada, el system prompt también agrega una guía de uso para que el modelo solo la use en trabajo sustancial y conserve como máximo un paso `in_progress`. ### `agents.defaults.subagents` @@ -2325,10 +2342,10 @@ Notas: } ``` -- `model`: modelo predeterminado para subagents generados. Si se omite, los subagents heredan el modelo del solicitante. -- `allowAgents`: lista de permitidos predeterminada de ids de agente de destino para `sessions_spawn` cuando el agente solicitante no establece su propio `subagents.allowAgents` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- `model`: modelo predeterminado para subagentes generados. Si se omite, los subagentes heredan el modelo del llamador. +- `allowAgents`: lista predeterminada de IDs de agente objetivo para `sessions_spawn` cuando el agente solicitante no establece su propio `subagents.allowAgents` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). - `runTimeoutSeconds`: timeout predeterminado (segundos) para `sessions_spawn` cuando la llamada a la herramienta omite `runTimeoutSeconds`. `0` significa sin timeout. -- Política de herramientas por subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Política de herramientas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -2339,7 +2356,7 @@ OpenClaw usa el catálogo de modelos integrado. Agrega proveedores personalizado ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (predeterminado) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2364,44 +2381,44 @@ OpenClaw usa el catálogo de modelos integrado. 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). +- Sustituye la raíz de configuración del agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, alias heredado de variable de entorno). - Precedencia de fusión para IDs de proveedor coincidentes: - - Los valores no vacíos de `baseUrl` en `models.json` del agente tienen prioridad. - - Los valores no vacíos de `apiKey` del agente solo tienen prioridad cuando ese proveedor no está administrado por SecretRef en el contexto actual de configuración/perfil de autenticación. - - Los valores `apiKey` de proveedor administrados por SecretRef se actualizan desde marcadores de origen (`ENV_VAR_NAME` para referencias env, `secretref-managed` para referencias file/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 referencias env, `secretref-managed` para referencias file/exec). - - Los valores vacíos o ausentes de `apiKey`/`baseUrl` del agente recurren a `models.providers` en la configuración. - - Los valores coincidentes de modelo `contextWindow`/`maxTokens` usan el valor más alto entre la configuración explícita y los valores implícitos del catálogo. - - Los valores coincidentes de modelo `contextTokens` conservan un límite explícito de tiempo de ejecución 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 por completo `models.json`. - - La persistencia de marcadores es autoritativa respecto del origen: los marcadores se escriben desde la instantánea activa de configuración de origen (previa a la resolución), no desde valores secretos resueltos en tiempo de ejecución. + - Los valores `baseUrl` no vacíos de `models.json` del agente prevalecen. + - Los valores `apiKey` no vacíos del agente prevalecen solo cuando ese proveedor no está administrado por SecretRef en el contexto actual de configuración/perfil de autenticación. + - Los valores `apiKey` de proveedor gestionados 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 gestionados 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` vacíos o ausentes en el agente usan como respaldo `models.providers` en la configuración. + - Los `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 de 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 respecto al origen: los marcadores se escriben desde la instantánea activa de configuración del origen (antes de la resolución), no desde los valores secretos resueltos en 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.*.api`: adaptador de solicitud (`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`: 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 (prefiere SecretRef/sustitución 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 se requiere. -- `models.providers.*.baseUrl`: URL base de la API upstream. -- `models.providers.*.headers`: encabezados estáticos adicionales para enrutamiento de proxy/inquilino. -- `models.providers.*.request`: sobrescrituras de transporte para solicitudes HTTP de model-provider. +- `models.providers.*.authHeader`: fuerza el transporte de credenciales en el encabezado `Authorization` cuando sea necesario. +- `models.providers.*.baseUrl`: base URL de la API upstream. +- `models.providers.*.headers`: encabezados estáticos extra para enrutamiento proxy/inquilino. +- `models.providers.*.request`: sustituciones de transporte para solicitudes HTTP del proveedor de modelos. - `request.headers`: encabezados extra (fusionados con los 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.proxy`: sobrescritura de proxy HTTP. Modos: `"env-proxy"` (usa las variables de entorno `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Ambos modos aceptan un subobjeto opcional `tls`. - - `request.tls`: sobrescritura TLS para conexiones directas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceptan SecretRef), `serverName`, `insecureSkipVerify`. + - `request.auth`: sustitución 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.proxy`: sustitución de proxy HTTP. Modos: `"env-proxy"` (usa variables de entorno `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Ambos modos aceptan un subobjeto `tls` opcional. + - `request.tls`: sustitución TLS para conexiones directas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceptan SecretRef), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: entradas explícitas del catálogo de modelos del proveedor. -- `models.providers.*.models.*.contextWindow`: metadatos nativos de ventana de contexto del modelo. -- `models.providers.*.models.*.contextTokens`: límite opcional de contexto en tiempo de ejecución. Úsalo cuando quieras un presupuesto efectivo de contexto menor que el `contextWindow` nativo del modelo. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: pista de compatibilidad opcional. Para `api: "openai-completions"` con un `baseUrl` no vacío y no nativo (host distinto de `api.openai.com`), OpenClaw lo fuerza a `false` en tiempo de ejecución. Un `baseUrl` vacío/omitido conserva el comportamiento predeterminado de OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: pista de compatibilidad opcional para endpoints chat compatibles con OpenAI que solo admiten cadenas. Cuando es `true`, OpenClaw aplana arreglos de `messages[].content` de solo texto 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.region`: región 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.refreshInterval`: intervalo de sondeo para actualización del descubrimiento. +- `models.providers.*.models.*.contextWindow`: metadatos nativos de la ventana de contexto del modelo. +- `models.providers.*.models.*.contextTokens`: límite opcional de contexto en runtime. Úsalo cuando quieras un presupuesto de contexto efectivo menor que el `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 lo fuerza a `false` en runtime. Un `baseUrl` vacío/omitido conserva el comportamiento predeterminado de OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: pista opcional de compatibilidad para endpoints de chat compatibles con OpenAI que solo aceptan cadenas. Cuando es `true`, OpenClaw aplana arreglos `messages[].content` de solo texto en cadenas simples antes de enviar la solicitud. +- `plugins.entries.amazon-bedrock.config.discovery`: raíz de ajustes de auto-descubrimiento de Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: activar/desactivar 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.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. @@ -2458,7 +2475,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`. +Configura `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`. @@ -2475,11 +2492,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`. +Configura `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 base URL. +- Endpoint de programación (predeterminado): `https://api.z.ai/api/coding/paas/v4` +- Para el endpoint general, define un proveedor personalizado con la sustitución de base URL. @@ -2518,11 +2535,11 @@ Establece `ZAI_API_KEY`. `z.ai/*` y `z-ai/*` se aceptan como alias. Atajo: `open } ``` -Para el endpoint de China: `baseUrl: "https://api.moonshot.cn/v1"` u `openclaw onboard --auth-choice moonshot-api-key-cn`. +Para el endpoint de China: `baseUrl: "https://api.moonshot.cn/v1"` o `openclaw onboard --auth-choice moonshot-api-key-cn`. -Los endpoints nativos de Moonshot anuncian compatibilidad de uso de streaming en el -transporte compartido `openai-completions`, y OpenClaw ahora determina eso según las -capacidades del endpoint en lugar de hacerlo solo por el id integrado del proveedor. +Los endpoints nativos de Moonshot anuncian compatibilidad de uso de streaming en el transporte compartido +`openai-completions`, y OpenClaw basa ese comportamiento en las capacidades del endpoint +en lugar de hacerlo solo en el ID del proveedor integrado. @@ -2619,12 +2636,12 @@ La base URL debe omitir `/v1` (el cliente de Anthropic lo agrega). Atajo: `openc } ``` -Establece `MINIMAX_API_KEY`. Atajos: +Configura `MINIMAX_API_KEY`. Atajos: `openclaw onboard --auth-choice minimax-global-api` o `openclaw onboard --auth-choice minimax-cn-api`. -El catálogo de modelos ahora usa M2.7 solo como predeterminado. -En la ruta de streaming compatible con Anthropic, OpenClaw desactiva MiniMax thinking -de forma predeterminada a menos que establezcas `thinking` por tu cuenta. `/fast on` o +El catálogo de modelos usa por defecto solo M2.7. +En la ruta de streaming compatible con Anthropic, OpenClaw desactiva el thinking de MiniMax +por defecto salvo que configures `thinking` explícitamente. `/fast on` o `params.fastMode: true` reescribe `MiniMax-M2.7` como `MiniMax-M2.7-highspeed`. @@ -2632,7 +2649,7 @@ de forma predeterminada a menos que establezcas `thinking` por tu cuenta. `/fast -Consulta [Local Models](/es/gateway/local-models). Resumen: ejecuta un gran modelo local mediante la API Responses de LM Studio en hardware serio; mantén los modelos alojados fusionados como respaldo. +Consulta [Local Models](/es/gateway/local-models). En resumen: ejecuta un modelo local grande a través de la API Responses de LM Studio en hardware serio; mantén los modelos alojados fusionados como respaldo. @@ -2653,7 +2670,7 @@ Consulta [Local Models](/es/gateway/local-models). Resumen: ejecuta un gran mode }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // o cadena en texto plano env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2663,14 +2680,14 @@ Consulta [Local Models](/es/gateway/local-models). Resumen: ejecuta un gran mode } ``` -- `allowBundled`: lista de permitidos opcional solo para Skills bundled (las Skills administradas/del workspace no se ven afectadas). -- `load.extraDirs`: raíces adicionales compartidas de Skills (precedencia más baja). +- `allowBundled`: lista opcional de Skills agrupadas únicamente (no afecta a Skills administradas/del workspace). +- `load.extraDirs`: raíces extra de Skills compartidas (menor precedencia). - `install.preferBrew`: cuando es true, prefiere instaladores Homebrew cuando `brew` está - disponible antes de recurrir a otros tipos de instalador. -- `install.nodeManager`: preferencia del instalador de node para especificaciones + disponible antes de volver a otros tipos de instalador. +- `install.nodeManager`: preferencia del instalador Node para especificaciones `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` desactiva una Skill aunque esté bundled/instalada. -- `entries..apiKey`: campo de conveniencia de API key a nivel de Skill (cuando lo admite la Skill). +- `entries..enabled: false` desactiva una Skill incluso si está agrupada/instalada. +- `entries..apiKey`: campo práctico de API key para Skills que declaran una variable de entorno principal (cadena en texto plano u objeto SecretRef). --- @@ -2699,38 +2716,38 @@ Consulta [Local Models](/es/gateway/local-models). Resumen: ejecuta un gran mode ``` - Se cargan desde `~/.openclaw/extensions`, `/.openclaw/extensions` y `plugins.load.paths`. -- El descubrimiento acepta plugins nativos de OpenClaw más paquetes compatibles de Codex y Claude, incluidos paquetes Claude sin manifiesto con diseño predeterminado. +- El descubrimiento acepta plugins nativos de OpenClaw y bundles compatibles de Codex y Claude, incluidos bundles de Claude sin manifiesto y 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 API key a nivel de plugin (cuando lo admite el plugin). +- `allow`: lista opcional de permisos (solo se cargan los plugins listados). `deny` prevalece. +- `plugins.entries..apiKey`: campo práctico de API key a nivel de plugin (cuando el plugin lo admite). - `plugins.entries..env`: mapa de variables de entorno con alcance de plugin. -- `plugins.entries..hooks.allowPromptInjection`: cuando es `false`, el núcleo bloquea `before_prompt_build` e ignora campos mutadores del prompt de `before_agent_start` heredado, conservando `modelOverride` y `providerOverride` heredados. Se aplica a hooks de plugins nativos y a directorios de hooks suministrados por bundles compatibles. -- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en este plugin para solicitar sobrescrituras de `provider` y `model` por ejecución para ejecuciones de subagent en segundo plano. -- `plugins.entries..subagent.allowedModels`: lista de permitidos opcional de destinos canónicos `provider/model` para sobrescrituras confiables de subagent. Usa `"*"` solo cuando quieras permitir intencionalmente cualquier modelo. +- `plugins.entries..hooks.allowPromptInjection`: cuando es `false`, el núcleo bloquea `before_prompt_build` e ignora campos heredados que mutan el prompt desde `before_agent_start`, mientras conserva `modelOverride` y `providerOverride` heredados. Se aplica a hooks de plugins nativos y a directorios de hooks proporcionados por bundles compatibles. +- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en este plugin para solicitar sustituciones por ejecución de `provider` y `model` para ejecuciones en segundo plano de subagentes. +- `plugins.entries..subagent.allowedModels`: lista opcional de objetivos canónicos `provider/model` permitidos para sustituciones de subagente confiables. Usa `"*"` solo cuando quieras permitir intencionalmente cualquier modelo. - `plugins.entries..config`: objeto de configuración definido por el plugin (validado por el esquema del plugin nativo de OpenClaw cuando está disponible). -- `plugins.entries.firecrawl.config.webFetch`: configuración del proveedor de web-fetch de Firecrawl. - - `apiKey`: API key de Firecrawl (acepta SecretRef). Recurre a `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` heredado o la variable de entorno `FIRECRAWL_API_KEY`. +- `plugins.entries.firecrawl.config.webFetch`: ajustes del proveedor web-fetch de Firecrawl. + - `apiKey`: API key de Firecrawl (acepta SecretRef). Usa como respaldo `plugins.entries.firecrawl.config.webSearch.apiKey`, el valor heredado `tools.web.fetch.firecrawl.apiKey` o la variable de entorno `FIRECRAWL_API_KEY`. - `baseUrl`: base URL de la API de Firecrawl (predeterminado: `https://api.firecrawl.dev`). - - `onlyMainContent`: extrae solo el contenido principal de las páginas (predeterminado: `true`). + - `onlyMainContent`: extraer 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`: timeout de la solicitud de scrape en segundos (predeterminado: `60`). -- `plugins.entries.xai.config.xSearch`: configuración de xAI X Search (búsqueda web de Grok). +- `plugins.entries.xai.config.xSearch`: ajustes de xAI X Search (búsqueda web de Grok). - `enabled`: habilita el proveedor X Search. - - `model`: modelo Grok a usar para búsqueda (por ejemplo `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: configuración de memory dreaming (experimental). Consulta [Dreaming](/es/concepts/dreaming) para fases y umbrales. + - `model`: modelo Grok que se usará para la búsqueda (p. ej. `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: ajustes de memory dreaming (experimental). Consulta [Dreaming](/es/concepts/dreaming) para fases y umbrales. - `enabled`: interruptor maestro de dreaming (predeterminado `false`). - - `frequency`: cadencia cron para cada barrido completo de dreaming (`"0 3 * * *"` de forma predeterminada). + - `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 memory está en [Memory configuration reference](/es/reference/memory-config): +- La configuración completa de memoria se encuentra en [Memory configuration reference](/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 Pi integrados desde `settings.json`; OpenClaw los aplica como configuración saneada del agente, no como parches crudos de configuración de OpenClaw. -- `plugins.slots.memory`: elige el id activo del plugin de memory o `"none"` para desactivar los plugins de memory. -- `plugins.slots.contextEngine`: elige el id activo del plugin de motor de contexto; su 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 bundle Claude habilitados también pueden aportar valores predeterminados Pi integrados desde `settings.json`; OpenClaw los aplica como ajustes saneados del agente, no como parches de configuración sin procesar de OpenClaw. +- `plugins.slots.memory`: elige el ID del plugin de memoria activo, o `"none"` para desactivar los plugins de memoria. +- `plugins.slots.contextEngine`: elige el ID del plugin de motor de contexto activo; usa por defecto `"legacy"` salvo que instales y selecciones otro motor. +- `plugins.installs`: metadatos de instalación administrados por CLI 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 CLI sobre ediciones manuales. @@ -2738,7 +2755,7 @@ Consulta [Plugins](/es/tools/plugin). --- -## Browser +## Navegador ```json5 { @@ -2747,8 +2764,8 @@ Consulta [Plugins](/es/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // default trusted-network mode - // allowPrivateNetwork: true, // legacy alias + dangerouslyAllowPrivateNetwork: true, // modo predeterminado de red de confianza + // allowPrivateNetwork: true, // alias heredado // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2775,27 +2792,27 @@ Consulta [Plugins](/es/tools/plugin). ``` - `evaluateEnabled: false` desactiva `act:evaluate` y `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` usa `true` como valor predeterminado cuando no se establece (modelo de red confiable). -- Establece `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` para navegación estricta del browser solo en red pública. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` usa `true` por defecto cuando no está configurado (modelo de red de confianza). +- Establece `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` para una navegación estricta del navegador solo en redes públicas. - En modo estricto, los endpoints remotos de perfil CDP (`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 (start/stop/reset desactivados). +- Los perfiles remotos son solo de adjunción (start/stop/reset desactivados). - `profiles.*.cdpUrl` acepta `http://`, `https://`, `ws://` y `wss://`. Usa HTTP(S) cuando quieras que OpenClaw descubra `/json/version`; usa WS(S) - cuando tu proveedor te dé una URL directa de WebSocket 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 rutas de Chrome MCP: - acciones basadas en snapshot/ref en lugar de selectores CSS, hooks de subida de un solo archivo, - sin sobrescrituras de timeout de diálogo, sin `wait --load networkidle` y sin - `responsebody`, exportación PDF, interceptación de descargas ni acciones por lotes. -- Los perfiles locales gestionados `openclaw` asignan automáticamente `cdpPort` y `cdpUrl`; solo - establece `cdpUrl` explícitamente para CDP remoto. + cuando tu proveedor te dé una URL WebSocket directa de DevTools. +- Los perfiles `existing-session` son solo del 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` conservan los límites actuales de ruta de Chrome MCP: + acciones basadas en snapshot/ref en lugar de direccionamiento por selector CSS, hooks de carga + de un solo archivo, sin sustituciones de timeout de diálogos, sin `wait --load networkidle`, + y sin `responsebody`, exportación PDF, interceptación de descargas o acciones por lotes. +- Los perfiles locales administrados `openclaw` asignan automáticamente `cdpPort` y `cdpUrl`; solo + configura `cdpUrl` explícitamente para CDP remoto. - Orden de autodetección: navegador predeterminado si es Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary. - Servicio de control: solo loopback (puerto derivado de `gateway.port`, predeterminado `18791`). -- `extraArgs` añade flags adicionales de inicio a Chromium local (por ejemplo +- `extraArgs` agrega flags extra de inicio al Chromium local (por ejemplo `--disable-gpu`, tamaño de ventana o flags de depuración). --- @@ -2808,14 +2825,14 @@ Consulta [Plugins](/es/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji, texto corto, URL de imagen o URI de datos }, }, } ``` -- `seamColor`: color de acento para la interfaz nativa de la aplicación (tinte de burbuja de Talk Mode, etc.). -- `assistant`: sobrescritura de identidad de la Control UI. Usa como respaldo la identidad del agente activo. +- `seamColor`: color de acento para la UI nativa de la app (tono de la burbuja del modo Talk, etc.). +- `assistant`: sustitución de identidad para Control UI. Usa como respaldo la identidad del agente activo. --- @@ -2830,8 +2847,8 @@ Consulta [Plugins](/es/tools/plugin). auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // o OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // para mode=trusted-proxy; consulta /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2848,8 +2865,8 @@ Consulta [Plugins](/es/tools/plugin). enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowedOrigins: ["https://control.example.com"], // obligatorio para Control UI no loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // modo peligroso de respaldo de origen por encabezado Host // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2860,12 +2877,12 @@ Consulta [Plugins](/es/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // Opcional. Predeterminado false. allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // Denegaciones HTTP adicionales de /tools/invoke deny: ["browser"], - // Remove tools from the default HTTP deny list + // Eliminar herramientas de la lista predeterminada de denegación HTTP allow: ["gateway"], }, push: { @@ -2882,9 +2899,7 @@ Consulta [Plugins](/es/tools/plugin). -- `mode`: `local` (ejecutar gateway) o `remote` (conectarse a gateway remoto). El gateway se niega a iniciar salvo en `local`. +- `mode`: `local` (ejecuta gateway) o `remote` (conectarse a un gateway remoto). El 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`. -- **Aliases heredados de bind**: usa valores de modo bind en `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), no aliases 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 redes bridge de Docker (`-p 18789:18789`), el tráfico llega por `eth0`, por lo que el gateway queda inaccesible. Usa `--network host`, o establece `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) para escuchar en todas las interfaces. -- **Auth**: requerida 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 reverse proxy con \ No newline at end of file +- **Alias heredados de bind**: usa valores de modo bind en `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), no alias de host (` \ No newline at end of file diff --git a/docs/es/gateway/doctor.md b/docs/es/gateway/doctor.md index a8699decf..be3fbf934 100644 --- a/docs/es/gateway/doctor.md +++ b/docs/es/gateway/doctor.md @@ -1,22 +1,23 @@ --- read_when: - - Agregar o modificar migraciones de Doctor - - Introducir cambios de configuración incompatibles + - Agregar o modificar migraciones de doctor + - Introducir cambios incompatibles de configuración summary: 'Comando Doctor: comprobaciones de estado, migraciones de configuración y pasos de reparación' title: Doctor x-i18n: - generated_at: "2026-04-08T02:15:35Z" + generated_at: "2026-04-09T01:29:12Z" model: gpt-5.4 provider: openai - source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6 + source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce source_path: gateway/doctor.md workflow: 15 --- # Doctor -`openclaw doctor` es la herramienta de reparación y migración de OpenClaw. Corrige -configuración/estado obsoletos, comprueba el estado y proporciona pasos de reparación accionables. +`openclaw doctor` es la herramienta de reparación + migración de OpenClaw. Corrige +configuración/estado obsoletos, comprueba el estado y proporciona pasos de +reparación accionables. ## Inicio rápido @@ -24,19 +25,19 @@ configuración/estado obsoletos, comprueba el estado y proporciona pasos de repa openclaw doctor ``` -### Sin interfaz / automatización +### Modo sin interfaz / automatización ```bash openclaw doctor --yes ``` -Acepta los valores predeterminados sin solicitar confirmación (incluidos los pasos de reparación de reinicio/servicio/sandbox cuando corresponda). +Acepta los valores predeterminados sin preguntar (incluidos los pasos de reparación de reinicio/servicio/sandbox cuando corresponda). ```bash openclaw doctor --repair ``` -Aplica las reparaciones recomendadas sin solicitar confirmación (reparaciones + reinicios cuando sea seguro). +Aplica las reparaciones recomendadas sin preguntar (reparaciones + reinicios cuando sea seguro). ```bash openclaw doctor --repair --force @@ -48,7 +49,7 @@ Aplica también reparaciones agresivas (sobrescribe configuraciones personalizad openclaw doctor --non-interactive ``` -Se ejecuta sin solicitudes y solo aplica migraciones seguras (normalización de configuración + movimientos de estado en disco). Omite acciones de reinicio/servicio/sandbox que requieren confirmación humana. +Se ejecuta sin preguntas y solo aplica migraciones seguras (normalización de configuración + movimientos de estado en disco). Omite acciones de reinicio/servicio/sandbox que requieren confirmación humana. Las migraciones de estado heredado se ejecutan automáticamente cuando se detectan. ```bash @@ -57,7 +58,7 @@ openclaw doctor --deep Analiza los servicios del sistema para detectar instalaciones adicionales del gateway (launchd/systemd/schtasks). -Si quiere revisar los cambios antes de escribirlos, abra primero el archivo de configuración: +Si quieres revisar los cambios antes de escribir, abre primero el archivo de configuración: ```bash cat ~/.openclaw/openclaw.json @@ -66,61 +67,95 @@ cat ~/.openclaw/openclaw.json ## Qué hace (resumen) - Actualización previa opcional para instalaciones de git (solo interactivo). -- Comprobación de actualización del protocolo de la UI (reconstruye Control UI cuando el esquema del protocolo es más reciente). -- Comprobación de estado + solicitud de reinicio. -- Resumen del estado de Skills (aptas/faltantes/bloqueadas) y estado de plugins. +- Comprobación de vigencia del protocolo de IU (reconstruye la Control UI cuando el esquema del protocolo es más reciente). +- Comprobación de estado + aviso para reiniciar. +- Resumen del estado de Skills (aptas/faltantes/bloqueadas) y estado de los plugins. - Normalización de configuración para valores heredados. -- Migración de la configuración de Talk desde los campos planos heredados `talk.*` a `talk.provider` + `talk.providers.`. +- Migración de configuración de Talk desde campos planos heredados `talk.*` hacia `talk.provider` + `talk.providers.`. - Comprobaciones de migración del navegador para configuraciones heredadas de la extensión de Chrome y preparación de Chrome MCP. -- Advertencias de sobrescritura del proveedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Advertencias de enmascaramiento de OAuth de Codex (`models.providers.openai-codex`). -- Comprobación de requisitos previos de TLS para perfiles OAuth de OpenAI Codex. -- Migración de estado heredado en disco (sesiones/directorio de agente/autenticación de WhatsApp). -- Migración de claves de contrato heredadas del manifiesto de plugins (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Migración del almacén cron heredado (`jobId`, `schedule.cron`, campos de entrega/carga útil de nivel superior, `provider` en la carga útil, trabajos de respaldo webhook simples con `notify: true`). +- Advertencias de anulaciones del proveedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). +- Advertencias de sombreado de OAuth de Codex (`models.providers.openai-codex`). +- Comprobación de requisitos previos de TLS de OAuth para perfiles de OAuth de OpenAI Codex. +- Migración heredada de estado en disco (sesiones/directorio del agente/autenticación de WhatsApp). +- Migración heredada de claves de contrato en manifiestos de plugins (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Migración heredada del almacén cron (`jobId`, `schedule.cron`, campos de entrega/carga útil de nivel superior, `provider` en la carga útil, trabajos simples de respaldo webhook con `notify: true`). - Inspección de archivos de bloqueo de sesión y limpieza de bloqueos obsoletos. - Comprobaciones de integridad y permisos del estado (sesiones, transcripciones, directorio de estado). - Comprobaciones de permisos del archivo de configuración (`chmod 600`) cuando se ejecuta localmente. -- Estado de autenticación de modelos: comprueba el vencimiento de OAuth, puede renovar tokens próximos a vencer y reporta estados de enfriamiento/deshabilitación de perfiles de autenticación. +- Estado de autenticación del modelo: comprueba vencimiento de OAuth, puede actualizar tokens próximos a vencer e informa de estados de enfriamiento/desactivación del perfil de autenticación. - Detección de directorio de espacio de trabajo adicional (`~/openclaw`). -- Reparación de imagen de sandbox cuando el aislamiento está habilitado. -- Migración de servicios heredados y detección de gateways adicionales. -- Migración de estado heredado del canal Matrix (en modo `--fix` / `--repair`). -- Comprobaciones del tiempo de ejecución del gateway (servicio instalado pero no en ejecución; etiqueta launchd en caché). +- Reparación de imagen de sandbox cuando el sandbox está habilitado. +- Migración de servicio heredado y detección de gateways adicionales. +- Migración heredada del estado del canal Matrix (en modo `--fix` / `--repair`). +- Comprobaciones del runtime del gateway (servicio instalado pero no en ejecución; etiqueta launchd en caché). - Advertencias de estado de canales (sondeadas desde el gateway en ejecución). - Auditoría de configuración del supervisor (launchd/systemd/schtasks) con reparación opcional. -- Comprobaciones de buenas prácticas del tiempo de ejecución del gateway (Node frente a Bun, rutas de gestores de versiones). -- Diagnóstico de colisiones de puerto del gateway (predeterminado `18789`). -- Advertencias de seguridad para políticas de DM abiertas. -- Comprobaciones de autenticación del gateway para el modo de token local (ofrece generar un token cuando no existe una fuente de token; no sobrescribe configuraciones de token con SecretRef). -- Comprobación de linger de systemd en Linux. -- Comprobación del tamaño de archivos de arranque del espacio de trabajo (advertencias de truncamiento o cercanía al límite para archivos de contexto). -- Comprobación del estado del autocompletado del shell e instalación/actualización automática. +- Comprobaciones de buenas prácticas del runtime del gateway (Node frente a Bun, rutas de gestores de versiones). +- Diagnósticos de colisión de puertos del gateway (predeterminado `18789`). +- Advertencias de seguridad para políticas de MD abiertas. +- Comprobaciones de autenticación del gateway para modo de token local (ofrece generar un token cuando no existe una fuente de token; no sobrescribe configuraciones de token SecretRef). +- Comprobación de systemd linger en Linux. +- Comprobación del tamaño de archivos bootstrap del espacio de trabajo (advertencias por truncamiento/cercanía al límite para archivos de contexto). +- Comprobación del estado de autocompletado del shell e instalación/actualización automática. - Comprobación de preparación del proveedor de embeddings para búsqueda en memoria (modelo local, clave de API remota o binario QMD). -- Comprobaciones de instalación desde código fuente (desajuste del espacio de trabajo pnpm, recursos de UI faltantes, binario tsx faltante). +- Comprobaciones de instalación desde código fuente (desajuste de espacio de trabajo pnpm, recursos de IU faltantes, binario tsx faltante). - Escribe la configuración actualizada + metadatos del asistente. -## Comportamiento detallado y fundamento +## Backfill y restablecimiento de la IU de Dreams + +La escena Dreams de la Control UI incluye acciones de **Backfill**, **Reset** y **Clear Grounded** +para el flujo de trabajo de sueños fundamentados. Estas acciones usan métodos RPC +de estilo doctor del gateway, pero **no** forman parte de la reparación/migración +de la CLI `openclaw doctor`. + +Qué hacen: + +- **Backfill** analiza archivos históricos `memory/YYYY-MM-DD.md` en el espacio + de trabajo activo, ejecuta el proceso fundamentado del diario REM y escribe + entradas reversibles de backfill en `DREAMS.md`. +- **Reset** elimina solo esas entradas del diario de backfill marcadas de `DREAMS.md`. +- **Clear Grounded** elimina solo las entradas preparadas a corto plazo de tipo + grounded-only que provinieron de una reproducción histórica y que aún no han + acumulado recuperación en vivo ni soporte diario. + +Qué **no** hacen por sí solas: + +- no editan `MEMORY.md` +- no ejecutan migraciones completas de doctor +- no preparan automáticamente candidatos fundamentados en el almacén de promoción + activa a corto plazo a menos que ejecutes explícitamente primero la ruta de la CLI preparada + +Si quieres que la reproducción histórica fundamentada influya en la vía normal +de promoción profunda, usa en su lugar el flujo de CLI: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +Eso prepara candidatos duraderos fundamentados en el almacén de sueños a corto plazo, +manteniendo `DREAMS.md` como la superficie de revisión. + +## Comportamiento detallado y justificación ### 0) Actualización opcional (instalaciones de git) -Si esto es una extracción de git y doctor se está ejecutando de forma interactiva, ofrece +Si esto es un checkout de git y doctor se ejecuta de forma interactiva, ofrece actualizar (fetch/rebase/build) antes de ejecutar doctor. ### 1) Normalización de configuración -Si la configuración contiene formas de valores heredados (por ejemplo `messages.ackReaction` -sin una sobrescritura específica del canal), doctor los normaliza al esquema actual. +Si la configuración contiene formas heredadas de valores (por ejemplo `messages.ackReaction` +sin una anulación específica por canal), doctor las normaliza al esquema actual. -Eso incluye los campos planos heredados de Talk. La configuración pública actual de Talk es +Eso incluye campos planos heredados de Talk. La configuración pública actual de Talk es `talk.provider` + `talk.providers.`. Doctor reescribe las formas antiguas `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` en el mapa de proveedores. +`talk.apiKey` en el mapa del proveedor. -### 2) Migraciones de claves de configuración heredadas +### 2) Migraciones de claves heredadas de configuración -Cuando la configuración contiene claves obsoletas, otros comandos se niegan a ejecutarse y piden -que ejecute `openclaw doctor`. +Cuando la configuración contiene claves obsoletas, otros comandos se niegan a ejecutarse y te piden +que ejecutes `openclaw doctor`. Doctor hará lo siguiente: @@ -128,8 +163,8 @@ Doctor hará lo siguiente: - Mostrar la migración que aplicó. - Reescribir `~/.openclaw/openclaw.json` con el esquema actualizado. -El Gateway también ejecuta automáticamente las migraciones de doctor al iniciarse cuando detecta un -formato de configuración heredado, por lo que las configuraciones obsoletas se reparan sin intervención manual. +El Gateway también ejecuta automáticamente las migraciones de doctor al iniciarse cuando detecta +un formato heredado de configuración, de modo que las configuraciones obsoletas se reparan sin intervención manual. Las migraciones del almacén de trabajos cron se gestionan con `openclaw doctor --fix`. Migraciones actuales: @@ -141,7 +176,7 @@ Migraciones actuales: - `routing.queue` → `messages.queue` - `routing.bindings` → `bindings` de nivel superior - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` -- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` heredados → `talk.provider` + `talk.providers.` +- heredado `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` @@ -154,7 +189,7 @@ Migraciones actuales: - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Para canales con `accounts` con nombre pero con valores de canal de cuenta única aún presentes en el nivel superior, mover esos valores con alcance de cuenta a la cuenta promovida elegida para ese canal (`accounts.default` para la mayoría de los canales; Matrix puede conservar un destino coincidente con nombre/predeterminado existente) +- Para canales con `accounts` con nombre pero con valores persistentes de canal de cuenta única en el nivel superior, mover esos valores con alcance de cuenta a la cuenta promovida elegida para ese canal (`accounts.default` para la mayoría de los canales; Matrix puede conservar un destino con nombre/predeterminado coincidente ya existente) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` @@ -163,74 +198,75 @@ Migraciones actuales: - `browser.profiles.*.driver: "extension"` → `"existing-session"` - eliminar `browser.relayBindHost` (configuración heredada del relay de la extensión) -Las advertencias de Doctor también incluyen orientación sobre cuentas predeterminadas para canales con varias cuentas: +Las advertencias de doctor también incluyen orientación sobre cuentas predeterminadas para canales con varias cuentas: -- Si se configuran dos o más entradas `channels..accounts` sin `channels..defaultAccount` o `accounts.default`, doctor advierte que el enrutamiento de respaldo puede elegir una cuenta inesperada. -- Si `channels..defaultAccount` está configurado con un ID de cuenta desconocido, doctor advierte y enumera los ID de cuenta configurados. +- Si se configuran dos o más entradas `channels..accounts` sin `channels..defaultAccount` ni `accounts.default`, doctor advierte que el enrutamiento de respaldo puede elegir una cuenta inesperada. +- Si `channels..defaultAccount` está establecido en un ID de cuenta desconocido, doctor advierte y enumera los ID de cuenta configurados. -### 2b) Sobrescrituras del proveedor OpenCode +### 2b) Anulaciones del proveedor OpenCode -Si agregó manualmente `models.providers.opencode`, `opencode-zen` u `opencode-go`, -sobrescribe el catálogo integrado de OpenCode de `@mariozechner/pi-ai`. -Eso puede forzar modelos a la API incorrecta o dejar los costos en cero. Doctor advierte para que -pueda eliminar la sobrescritura y restaurar el enrutamiento por modelo + costos. +Si agregaste manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, +eso sobrescribe el catálogo integrado de OpenCode de `@mariozechner/pi-ai`. +Eso puede forzar modelos a la API equivocada o poner los costos a cero. Doctor advierte +para que puedas eliminar la anulación y restaurar el enrutamiento por modelo + costos. ### 2c) Migración del navegador y preparación de Chrome MCP -Si su configuración del navegador aún apunta a la ruta eliminada de la extensión de Chrome, doctor -la normaliza al modelo actual de conexión de Chrome MCP local al host: +Si tu configuración del navegador aún apunta a la ruta eliminada de la extensión de Chrome, doctor +la normaliza al modelo actual de conexión host-local de Chrome MCP: - `browser.profiles.*.driver: "extension"` pasa a ser `"existing-session"` - se elimina `browser.relayBindHost` -Doctor también audita la ruta de Chrome MCP local al host cuando usa `defaultProfile: +Doctor también audita la ruta host-local de Chrome MCP cuando usas `defaultProfile: "user"` o un perfil `existing-session` configurado: -- comprueba si Google Chrome está instalado en el mismo host para perfiles predeterminados - de conexión automática +- comprueba si Google Chrome está instalado en el mismo host para perfiles de + conexión automática predeterminados - comprueba la versión detectada de Chrome y advierte cuando es inferior a Chrome 144 - recuerda habilitar la depuración remota en la página de inspección del navegador (por ejemplo `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, o `edge://inspect/#remote-debugging`) -Doctor no puede habilitar la configuración del lado de Chrome por usted. El Chrome MCP -local al host aún requiere: +Doctor no puede habilitar la configuración del lado de Chrome por ti. Chrome MCP host-local +todavía requiere: -- un navegador basado en Chromium 144+ en el host gateway/nodo +- un navegador basado en Chromium 144+ en el host del gateway/nodo - el navegador ejecutándose localmente - depuración remota habilitada en ese navegador -- aprobar la primera solicitud de consentimiento de conexión en el navegador +- aprobar el primer aviso de consentimiento de conexión en el navegador -La preparación aquí solo se refiere a los requisitos previos de conexión local. Existing-session mantiene -los límites de ruta actuales de Chrome MCP; las rutas avanzadas como `responsebody`, exportación PDF, -intercepción de descargas y acciones por lotes siguen requiriendo un navegador gestionado -o un perfil CDP sin procesar. +La preparación aquí se refiere solo a los requisitos previos de conexión local. Existing-session mantiene +los límites actuales de rutas de Chrome MCP; rutas avanzadas como `responsebody`, exportación +a PDF, interceptación de descargas y acciones por lotes siguen requiriendo un +navegador gestionado o un perfil CDP sin procesar. -Esta comprobación **no** se aplica a Docker, sandbox, remote-browser ni a otros +Esta comprobación **no** se aplica a Docker, sandbox, remote-browser ni otros flujos sin interfaz. Esos siguen usando CDP sin procesar. ### 2d) Requisitos previos de TLS para OAuth -Cuando se configura un perfil OAuth de OpenAI Codex, doctor sondea el endpoint de autorización de OpenAI -para verificar que la pila TLS local de Node/OpenSSL pueda validar la cadena de certificados. Si el sondeo falla con un error de certificado (por +Cuando se configura un perfil de OAuth de OpenAI Codex, doctor sondea el endpoint de autorización de OpenAI +para verificar que la pila TLS local de Node/OpenSSL pueda validar la cadena de certificados. +Si el sondeo falla con un error de certificado (por ejemplo `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado vencido o certificado autofirmado), -doctor muestra orientación de corrección específica para cada plataforma. En macOS con Node de Homebrew, la +doctor imprime orientación de corrección específica de la plataforma. En macOS con un Node de Homebrew, la corrección suele ser `brew postinstall ca-certificates`. Con `--deep`, el sondeo se ejecuta incluso si el gateway está en buen estado. -### 2c) Sobrescrituras del proveedor OAuth de Codex +### 2c) Anulaciones del proveedor OAuth de Codex -Si anteriormente agregó configuraciones heredadas de transporte OpenAI en -`models.providers.openai-codex`, pueden enmascarar la ruta integrada del -proveedor OAuth de Codex que las versiones más recientes usan automáticamente. Doctor advierte cuando ve -esas configuraciones antiguas de transporte junto con OAuth de Codex para que pueda eliminar o reescribir -la sobrescritura de transporte obsoleta y recuperar el comportamiento integrado de enrutamiento/respaldo. -Los proxies personalizados y las sobrescrituras solo de encabezados siguen siendo compatibles y no -activan esta advertencia. +Si anteriormente agregaste configuraciones heredadas de transporte de OpenAI en +`models.providers.openai-codex`, estas pueden ocultar la ruta integrada del +proveedor OAuth de Codex que las versiones más recientes usan automáticamente. Doctor +advierte cuando ve esas configuraciones antiguas de transporte junto con OAuth de Codex +para que puedas eliminar o reescribir la anulación obsoleta de transporte y recuperar +el comportamiento integrado de enrutamiento/respaldo. Los proxies personalizados y las anulaciones +solo de encabezados siguen siendo compatibles y no activan esta advertencia. -### 3) Migraciones de estado heredado (diseño en disco) +### 3) Migraciones heredadas de estado (disposición en disco) -Doctor puede migrar diseños antiguos en disco a la estructura actual: +Doctor puede migrar disposiciones antiguas en disco a la estructura actual: - Almacén de sesiones + transcripciones: - de `~/.openclaw/sessions/` a `~/.openclaw/agents//sessions/` @@ -238,34 +274,34 @@ Doctor puede migrar diseños antiguos en disco a la estructura actual: - de `~/.openclaw/agent/` a `~/.openclaw/agents//agent/` - Estado de autenticación de WhatsApp (Baileys): - desde `~/.openclaw/credentials/*.json` heredado (excepto `oauth.json`) - - hacia `~/.openclaw/credentials/whatsapp//...` (id de cuenta predeterminada: `default`) + - a `~/.openclaw/credentials/whatsapp//...` (ID de cuenta predeterminado: `default`) -Estas migraciones son de mejor esfuerzo e idempotentes; doctor emitirá advertencias cuando +Estas migraciones son por mejor esfuerzo e idempotentes; doctor emitirá advertencias cuando deje carpetas heredadas como copias de seguridad. El Gateway/CLI también migra automáticamente -las sesiones heredadas + el directorio del agente al iniciarse, de modo que el historial/autenticación/modelos -terminen en la ruta por agente sin ejecutar doctor manualmente. La autenticación de WhatsApp se migra intencionalmente solo -mediante `openclaw doctor`. La normalización del proveedor/mapa de proveedores de Talk ahora -compara por igualdad estructural, por lo que las diferencias solo en el orden de las claves ya no activan -cambios repetidos de `doctor --fix` sin efecto. +las sesiones heredadas + el directorio del agente al iniciarse, para que el historial/autenticación/modelos +terminen en la ruta por agente sin una ejecución manual de doctor. La autenticación de WhatsApp se migra +intencionalmente solo mediante `openclaw doctor`. La normalización de proveedor/mapa de proveedores de Talk ahora +compara por igualdad estructural, por lo que las diferencias solo en el orden de claves ya no provocan +cambios repetidos sin efecto de `doctor --fix`. -### 3a) Migraciones heredadas del manifiesto de plugins +### 3a) Migraciones heredadas de manifiestos de plugins -Doctor analiza todos los manifiestos de plugins instalados para detectar claves obsoletas de capacidades -de nivel superior (`speechProviders`, `realtimeTranscriptionProviders`, +Doctor analiza todos los manifiestos de plugins instalados en busca de claves +obsoletas de capacidades de nivel superior (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Cuando las encuentra, ofrece moverlas al objeto `contracts` -y reescribir el archivo de manifiesto in situ. Esta migración es idempotente; +y reescribir el archivo del manifiesto in situ. Esta migración es idempotente; si la clave `contracts` ya tiene los mismos valores, la clave heredada se elimina sin duplicar los datos. ### 3b) Migraciones heredadas del almacén cron Doctor también comprueba el almacén de trabajos cron (`~/.openclaw/cron/jobs.json` de forma predeterminada, -o `cron.store` cuando se sobrescribe) para detectar formas antiguas de trabajos que el planificador aún +o `cron.store` si se ha sobrescrito) en busca de formas antiguas de trabajos que el planificador aún acepta por compatibilidad. -Las limpiezas cron actuales incluyen: +Las limpiezas actuales de cron incluyen: - `jobId` → `id` - `schedule.cron` → `schedule.expr` @@ -275,130 +311,133 @@ Las limpiezas cron actuales incluyen: - trabajos heredados simples de respaldo webhook con `notify: true` → `delivery.mode="webhook"` explícito con `delivery.to=cron.webhook` Doctor solo migra automáticamente trabajos `notify: true` cuando puede hacerlo sin -cambiar el comportamiento. Si un trabajo combina el respaldo heredado de notify con un modo de entrega -existente no webhook, doctor advierte y deja ese trabajo para revisión manual. +cambiar el comportamiento. Si un trabajo combina un respaldo notify heredado con un modo de +entrega existente no webhook, doctor advierte y deja ese trabajo para revisión manual. ### 3c) Limpieza de bloqueos de sesión -Doctor analiza cada directorio de sesión de agente para detectar archivos de bloqueo de escritura obsoletos: -archivos que quedaron atrás cuando una sesión salió de forma anómala. Para cada archivo de bloqueo encontrado informa: +Doctor analiza cada directorio de sesiones de agente en busca de archivos obsoletos de bloqueo de escritura: +archivos que quedan cuando una sesión salió de forma anómala. Para cada archivo de bloqueo encontrado informa: la ruta, el PID, si el PID sigue activo, la antigüedad del bloqueo y si se -considera obsoleto (PID muerto o más de 30 minutos). En modo `--fix` / `--repair` -elimina automáticamente los archivos de bloqueo obsoletos; en caso contrario, muestra una nota y -le indica volver a ejecutar con `--fix`. +considera obsoleto (PID muerto o con más de 30 minutos). En modo `--fix` / `--repair` +elimina automáticamente los archivos de bloqueo obsoletos; de lo contrario imprime una nota e +indica que lo vuelvas a ejecutar con `--fix`. ### 4) Comprobaciones de integridad del estado (persistencia de sesión, enrutamiento y seguridad) -El directorio de estado es el tronco encefálico operativo. Si desaparece, pierde -sesiones, credenciales, registros y configuración (a menos que tenga copias de seguridad en otro lugar). +El directorio de estado es el tronco operativo principal. Si desaparece, pierdes +sesiones, credenciales, registros y configuración (a menos que tengas copias de seguridad en otro lugar). Doctor comprueba: -- **Falta el directorio de estado**: advierte sobre una pérdida catastrófica del estado, solicita volver a crear - el directorio y recuerda que no puede recuperar los datos faltantes. -- **Permisos del directorio de estado**: verifica que se pueda escribir; ofrece reparar permisos - (y emite una sugerencia de `chown` cuando detecta discrepancia de propietario/grupo). -- **Directorio de estado sincronizado en la nube de macOS**: advierte cuando el estado se resuelve bajo iCloud Drive +- **Falta el directorio de estado**: advierte sobre pérdida catastrófica de estado, ofrece recrear + el directorio y recuerda que no puede recuperar datos faltantes. +- **Permisos del directorio de estado**: verifica que sea escribible; ofrece reparar permisos + (y emite una sugerencia de `chown` cuando detecta desajuste de propietario/grupo). +- **Directorio de estado sincronizado en la nube en macOS**: advierte cuando el estado se resuelve bajo iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o `~/Library/CloudStorage/...` porque las rutas respaldadas por sincronización pueden causar E/S más lentas y condiciones de carrera de bloqueo/sincronización. -- **Directorio de estado en SD o eMMC de Linux**: advierte cuando el estado se resuelve a una fuente de montaje `mmcblk*`, - porque la E/S aleatoria respaldada por SD o eMMC puede ser más lenta y desgastarse - más rápido con las escrituras de sesión y credenciales. +- **Directorio de estado en SD o eMMC en Linux**: advierte cuando el estado se resuelve a un origen de montaje `mmcblk*`, + porque la E/S aleatoria respaldada por SD o eMMC puede ser más lenta y desgastarse más rápido con escrituras de sesiones y credenciales. - **Faltan directorios de sesión**: `sessions/` y el directorio del almacén de sesiones son - necesarios para persistir el historial y evitar fallos `ENOENT`. -- **Desajuste de transcripción**: advierte cuando las entradas recientes de sesión tienen - archivos de transcripción faltantes. -- **Sesión principal con “JSONL de 1 línea”**: marca cuando la transcripción principal solo tiene una + necesarios para conservar el historial y evitar fallos `ENOENT`. +- **Desajuste de transcripciones**: advierte cuando entradas recientes de sesión tienen archivos + de transcripción faltantes. +- **Sesión principal “JSONL de 1 línea”**: marca cuando la transcripción principal tiene solo una línea (el historial no se está acumulando). - **Varios directorios de estado**: advierte cuando existen varias carpetas `~/.openclaw` entre - directorios de inicio o cuando `OPENCLAW_STATE_DIR` apunta a otro lugar (el historial puede - dividirse entre instalaciones). + directorios personales o cuando `OPENCLAW_STATE_DIR` apunta a otro sitio (el historial puede dividirse entre instalaciones). - **Recordatorio de modo remoto**: si `gateway.mode=remote`, doctor recuerda ejecutarlo en el host remoto (el estado vive allí). - **Permisos del archivo de configuración**: advierte si `~/.openclaw/openclaw.json` es legible por grupo/mundo y ofrece restringirlo a `600`. -### 5) Estado de autenticación de modelos (vencimiento de OAuth) +### 5) Estado de autenticación del modelo (vencimiento de OAuth) -Doctor inspecciona los perfiles OAuth en el almacén de autenticación, advierte cuando los tokens están -próximos a vencer o vencidos, y puede renovarlos cuando es seguro. Si el perfil OAuth/token -de Anthropic está obsoleto, sugiere una clave de API de Anthropic o la -ruta de token de configuración de Anthropic. -Las solicitudes de renovación solo aparecen cuando se ejecuta de forma interactiva (TTY); `--non-interactive` -omite los intentos de renovación. +Doctor inspecciona perfiles OAuth en el almacén de autenticación, advierte cuando los tokens +están por vencer o vencidos, y puede actualizarlos cuando sea seguro. Si el perfil +de OAuth/token de Anthropic está obsoleto, sugiere una clave de API de Anthropic o la +ruta de setup-token de Anthropic. +Los avisos de actualización solo aparecen cuando se ejecuta de forma interactiva (TTY); `--non-interactive` +omite los intentos de actualización. -Doctor también informa perfiles de autenticación que están temporalmente inutilizables debido a: +Cuando una actualización de OAuth falla de forma permanente (por ejemplo `refresh_token_reused`, +`invalid_grant` o un proveedor te indica que vuelvas a iniciar sesión), doctor informa +que se requiere reautenticación e imprime el comando exacto `openclaw models auth login --provider ...` +que debes ejecutar. -- enfriamientos breves (límites de velocidad/tiempos de espera/fallos de autenticación) -- deshabilitaciones más largas (fallos de facturación/crédito) +Doctor también informa de perfiles de autenticación temporalmente inutilizables debido a: -### 6) Validación del modelo de hooks +- enfriamientos cortos (límites de tasa/tiempos de espera/fallos de autenticación) +- desactivaciones más largas (fallos de facturación/crédito) -Si `hooks.gmail.model` está configurado, doctor valida la referencia del modelo con el +### 6) Validación del modelo de Hooks + +Si `hooks.gmail.model` está configurado, doctor valida la referencia del modelo frente al catálogo y la lista de permitidos y advierte cuando no se resolverá o no está permitido. ### 7) Reparación de imagen de sandbox -Cuando el aislamiento está habilitado, doctor comprueba las imágenes de Docker y ofrece compilar o +Cuando el sandbox está habilitado, doctor comprueba las imágenes de Docker y ofrece compilar o cambiar a nombres heredados si falta la imagen actual. -### 7b) Dependencias de tiempo de ejecución de plugins integrados +### 7b) Dependencias de runtime de plugins incluidos -Doctor verifica que las dependencias de tiempo de ejecución de plugins integrados (por ejemplo, los -paquetes de tiempo de ejecución del plugin de Discord) estén presentes en la raíz de instalación de OpenClaw. -Si falta alguna, doctor informa los paquetes y los instala en -modo `openclaw doctor --fix` / `openclaw doctor --repair`. +Doctor verifica que las dependencias de runtime de los plugins incluidos (por ejemplo los +paquetes de runtime del plugin de Discord) estén presentes en la raíz de instalación de OpenClaw. +Si falta alguna, doctor informa de los paquetes y los instala en modo +`openclaw doctor --fix` / `openclaw doctor --repair`. ### 8) Migraciones de servicios del gateway y sugerencias de limpieza Doctor detecta servicios heredados del gateway (launchd/systemd/schtasks) y ofrece eliminarlos e instalar el servicio de OpenClaw usando el puerto actual del gateway. -También puede buscar servicios adicionales similares al gateway y mostrar sugerencias de limpieza. -Los servicios de gateway de OpenClaw con nombre de perfil se consideran de primera clase y no -se marcan como “adicionales”. +También puede buscar servicios adicionales similares al gateway e imprimir sugerencias de limpieza. +Los servicios de gateway de OpenClaw con nombre de perfil se consideran de primera clase y no se +marcan como "adicionales". -### 8b) Migración de Matrix al inicio +### 8b) Migración de Matrix al iniciar -Cuando una cuenta del canal Matrix tiene una migración de estado heredado pendiente o procesable, +Cuando una cuenta del canal Matrix tiene una migración heredada de estado pendiente o aplicable, doctor (en modo `--fix` / `--repair`) crea una instantánea previa a la migración y luego -ejecuta los pasos de migración de mejor esfuerzo: migración del estado heredado de Matrix y preparación -del estado cifrado heredado. Ambos pasos no son fatales; los errores se registran y el -inicio continúa. En modo de solo lectura (`openclaw doctor` sin `--fix`) esta comprobación +ejecuta los pasos de migración por mejor esfuerzo: migración heredada del estado de Matrix +y preparación heredada del estado cifrado. Ambos pasos no son fatales; los errores se registran y +el inicio continúa. En modo de solo lectura (`openclaw doctor` sin `--fix`) esta comprobación se omite por completo. ### 9) Advertencias de seguridad -Doctor emite advertencias cuando un proveedor está abierto a DM sin una lista de permitidos, o +Doctor emite advertencias cuando un proveedor está abierto a MD sin lista de permitidos, o cuando una política está configurada de forma peligrosa. -### 10) Linger de systemd (Linux) +### 10) systemd linger (Linux) -Si se ejecuta como servicio de usuario de systemd, doctor asegura que linger esté habilitado para que el -gateway siga activo después de cerrar sesión. +Si se ejecuta como servicio de usuario systemd, doctor se asegura de que lingering esté habilitado para que el +gateway siga activo después del cierre de sesión. ### 11) Estado del espacio de trabajo (Skills, plugins y directorios heredados) -Doctor muestra un resumen del estado del espacio de trabajo para el agente predeterminado: +Doctor imprime un resumen del estado del espacio de trabajo para el agente predeterminado: -- **Estado de Skills**: cuenta las Skills aptas, con requisitos faltantes y bloqueadas por lista de permitidos. -- **Directorios heredados del espacio de trabajo**: advierte cuando `~/openclaw` u otros directorios heredados del espacio de trabajo - existen junto al espacio de trabajo actual. -- **Estado de plugins**: cuenta plugins cargados/deshabilitados/con error; enumera los ID de plugins con - errores; informa las capacidades de plugins integrados. +- **Estado de Skills**: cuenta Skills aptas, con requisitos faltantes y bloqueadas por la lista de permitidos. +- **Directorios heredados del espacio de trabajo**: advierte cuando existen `~/openclaw` u otros directorios heredados del espacio de trabajo + junto al espacio de trabajo actual. +- **Estado de plugins**: cuenta plugins cargados/deshabilitados/con errores; enumera los ID de plugin para cualquier + error; informa de las capacidades de los plugins del bundle. - **Advertencias de compatibilidad de plugins**: marca plugins que tienen problemas de compatibilidad con - el tiempo de ejecución actual. -- **Diagnóstico de plugins**: muestra cualquier advertencia o error en tiempo de carga emitido por el + el runtime actual. +- **Diagnósticos de plugins**: muestra cualquier advertencia o error de carga emitido por el registro de plugins. -### 11b) Tamaño del archivo de arranque +### 11b) Tamaño del archivo bootstrap -Doctor comprueba si los archivos de arranque del espacio de trabajo (por ejemplo `AGENTS.md`, -`CLAUDE.md` u otros archivos de contexto inyectados) están cerca o por encima del presupuesto de -caracteres configurado. Informa por archivo los recuentos de caracteres sin procesar frente a inyectados, el -porcentaje de truncamiento, la causa del truncamiento (`max/file` o `max/total`) y el total de caracteres inyectados -como fracción del presupuesto total. Cuando los archivos están truncados o cerca -del límite, doctor muestra consejos para ajustar `agents.defaults.bootstrapMaxChars` +Doctor comprueba si los archivos bootstrap del espacio de trabajo (por ejemplo `AGENTS.md`, +`CLAUDE.md` u otros archivos de contexto inyectados) están cerca o por encima del presupuesto +configurado de caracteres. Informa por archivo del recuento de caracteres sin procesar frente al inyectado, el porcentaje +de truncamiento, la causa del truncamiento (`max/file` o `max/total`) y el total de caracteres +inyectados como fracción del presupuesto total. Cuando los archivos están truncados o cerca +del límite, doctor imprime sugerencias para ajustar `agents.defaults.bootstrapMaxChars` y `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Autocompletado del shell @@ -408,103 +447,102 @@ Doctor comprueba si el autocompletado con tabulador está instalado para el shel - Si el perfil del shell usa un patrón lento de autocompletado dinámico (`source <(openclaw completion ...)`), doctor lo actualiza a la variante más rápida - de archivo en caché. + con archivo en caché. - Si el autocompletado está configurado en el perfil pero falta el archivo de caché, - doctor regenera automáticamente la caché. -- Si no hay ningún autocompletado configurado, doctor solicita instalarlo + doctor regenera la caché automáticamente. +- Si no hay ningún autocompletado configurado, doctor ofrece instalarlo (solo en modo interactivo; se omite con `--non-interactive`). -Ejecute `openclaw completion --write-state` para regenerar manualmente la caché. +Ejecuta `openclaw completion --write-state` para regenerar la caché manualmente. ### 12) Comprobaciones de autenticación del gateway (token local) -Doctor comprueba la preparación de la autenticación por token del gateway local. +Doctor comprueba la preparación de autenticación por token del gateway local. -- Si el modo de token necesita un token y no existe una fuente de token, doctor ofrece generar uno. -- Si `gateway.auth.token` está gestionado por SecretRef pero no está disponible, doctor advierte y no lo sobrescribe con texto sin formato. -- `openclaw doctor --generate-gateway-token` fuerza la generación solo cuando no hay ningún token SecretRef configurado. +- Si el modo token necesita un token y no existe una fuente de token, doctor ofrece generar uno. +- Si `gateway.auth.token` está gestionado por SecretRef pero no disponible, doctor advierte y no lo sobrescribe con texto sin formato. +- `openclaw doctor --generate-gateway-token` fuerza la generación solo cuando no hay un token SecretRef configurado. -### 12b) Reparaciones de solo lectura con reconocimiento de SecretRef +### 12b) Reparaciones de solo lectura compatibles con SecretRef -Algunos flujos de reparación necesitan inspeccionar las credenciales configuradas sin debilitar el comportamiento de fallo rápido del tiempo de ejecución. +Algunos flujos de reparación necesitan inspeccionar credenciales configuradas sin debilitar el comportamiento fail-fast del runtime. -- `openclaw doctor --fix` ahora usa el mismo modelo resumido de SecretRef de solo lectura que la familia de comandos de estado para reparaciones de configuración específicas. -- Ejemplo: la reparación de `@username` en Telegram para `allowFrom` / `groupAllowFrom` intenta usar credenciales del bot configuradas cuando están disponibles. -- Si el token del bot de Telegram está configurado mediante SecretRef pero no está disponible en la ruta actual del comando, doctor informa que la credencial está configurada-pero-no-disponible y omite la resolución automática en lugar de fallar o informar erróneamente que falta el token. +- `openclaw doctor --fix` ahora usa el mismo modelo resumido de SecretRef de solo lectura que los comandos de la familia status para reparaciones específicas de configuración. +- Ejemplo: la reparación de Telegram `allowFrom` / `groupAllowFrom` con `@username` intenta usar credenciales configuradas del bot cuando están disponibles. +- Si el token del bot de Telegram está configurado mediante SecretRef pero no está disponible en la ruta actual del comando, doctor informa que la credencial está configurada pero no disponible y omite la resolución automática en lugar de fallar o informar incorrectamente que falta el token. ### 13) Comprobación de estado del gateway + reinicio Doctor ejecuta una comprobación de estado y ofrece reiniciar el gateway cuando parece no estar en buen estado. -### 13b) Preparación de búsqueda en memoria +### 13b) Preparación de la búsqueda en memoria -Doctor comprueba si el proveedor de embeddings configurado para búsqueda en memoria está preparado +Doctor comprueba si el proveedor de embeddings configurado para búsqueda en memoria está listo para el agente predeterminado. El comportamiento depende del backend y del proveedor configurados: - **Backend QMD**: sondea si el binario `qmd` está disponible y puede iniciarse. - Si no, muestra orientación de corrección, incluido el paquete npm y una opción manual de ruta binaria. -- **Proveedor local explícito**: comprueba si existe un archivo de modelo local o una URL - reconocida de modelo remoto/descargable. Si falta, sugiere cambiar a un proveedor remoto. + Si no, imprime orientación para corregirlo, incluido el paquete npm y una opción manual de ruta al binario. +- **Proveedor local explícito**: comprueba si hay un archivo de modelo local o una URL de modelo remota/descargable reconocida. Si falta, sugiere cambiar a un proveedor remoto. - **Proveedor remoto explícito** (`openai`, `voyage`, etc.): verifica que haya una clave de API - presente en el entorno o en el almacén de autenticación. Muestra sugerencias de corrección accionables si falta. -- **Proveedor automático**: comprueba primero la disponibilidad de modelos locales y luego prueba cada proveedor remoto - en el orden de selección automática. + presente en el entorno o en el almacén de autenticación. Imprime sugerencias de corrección accionables si falta. +- **Proveedor automático**: comprueba primero la disponibilidad del modelo local y luego prueba cada + proveedor remoto en orden de selección automática. -Cuando hay disponible un resultado de sondeo del gateway (el gateway estaba en buen estado en el momento de la -comprobación), doctor cruza ese resultado con la configuración visible desde la CLI y señala +Cuando hay disponible un resultado del sondeo del gateway (el gateway estaba en buen estado en el momento de la +comprobación), doctor lo cruza con la configuración visible desde la CLI y señala cualquier discrepancia. -Use `openclaw memory status --deep` para verificar la preparación de embeddings en tiempo de ejecución. +Usa `openclaw memory status --deep` para verificar en runtime la preparación de embeddings. -### 14) Advertencias de estado de canales +### 14) Advertencias de estado de los canales -Si el gateway está en buen estado, doctor ejecuta un sondeo de estado de los canales e informa +Si el gateway está en buen estado, doctor ejecuta un sondeo de estado de canales e informa advertencias con correcciones sugeridas. ### 15) Auditoría + reparación de configuración del supervisor -Doctor comprueba si la configuración del supervisor instalado (launchd/systemd/schtasks) tiene -valores predeterminados faltantes u obsoletos (por ejemplo, dependencias de systemd network-online y +Doctor comprueba la configuración instalada del supervisor (launchd/systemd/schtasks) en busca de +valores predeterminados ausentes o desactualizados (p. ej., dependencias de systemd network-online y retraso de reinicio). Cuando encuentra una discrepancia, recomienda una actualización y puede reescribir el archivo de servicio/tarea a los valores predeterminados actuales. Notas: -- `openclaw doctor` solicita confirmación antes de reescribir la configuración del supervisor. -- `openclaw doctor --yes` acepta las solicitudes de reparación predeterminadas. -- `openclaw doctor --repair` aplica las correcciones recomendadas sin solicitudes. +- `openclaw doctor` pregunta antes de reescribir la configuración del supervisor. +- `openclaw doctor --yes` acepta los avisos de reparación predeterminados. +- `openclaw doctor --repair` aplica las correcciones recomendadas sin preguntas. - `openclaw doctor --repair --force` sobrescribe configuraciones personalizadas del supervisor. -- Si la autenticación por token requiere un token y `gateway.auth.token` está gestionado por SecretRef, la instalación/reparación del servicio de doctor valida el SecretRef, pero no persiste valores resueltos de token en texto sin formato en los metadatos de entorno del servicio supervisor. +- Si la autenticación por token requiere un token y `gateway.auth.token` está gestionado por SecretRef, la instalación/reparación del servicio valida el SecretRef pero no conserva valores de token resueltos en texto sin formato en los metadatos del entorno del servicio del supervisor. - Si la autenticación por token requiere un token y el token SecretRef configurado no está resuelto, doctor bloquea la ruta de instalación/reparación con orientación accionable. -- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados y `gateway.auth.mode` no está definido, doctor bloquea la instalación/reparación hasta que el modo se establezca explícitamente. -- Para unidades user-systemd de Linux, las comprobaciones de deriva de token de doctor ahora incluyen tanto fuentes `Environment=` como `EnvironmentFile=` al comparar metadatos de autenticación del servicio. -- Siempre puede forzar una reescritura completa mediante `openclaw gateway install --force`. +- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados y `gateway.auth.mode` no está establecido, doctor bloquea la instalación/reparación hasta que el modo se configure explícitamente. +- Para unidades user-systemd en Linux, las comprobaciones de divergencia del token de doctor ahora incluyen tanto las fuentes `Environment=` como `EnvironmentFile=` al comparar metadatos de autenticación del servicio. +- Siempre puedes forzar una reescritura completa mediante `openclaw gateway install --force`. -### 16) Diagnóstico del tiempo de ejecución del gateway + puerto +### 16) Diagnósticos del runtime del gateway + puerto -Doctor inspecciona el tiempo de ejecución del servicio (PID, último estado de salida) y advierte cuando el +Doctor inspecciona el runtime del servicio (PID, último estado de salida) y advierte cuando el servicio está instalado pero en realidad no se está ejecutando. También comprueba colisiones -de puerto en el puerto del gateway (predeterminado `18789`) e informa causas probables (gateway ya +de puertos en el puerto del gateway (predeterminado `18789`) e informa causas probables (gateway ya en ejecución, túnel SSH). -### 17) Buenas prácticas del tiempo de ejecución del gateway +### 17) Buenas prácticas del runtime del gateway -Doctor advierte cuando el servicio del gateway se ejecuta con Bun o con una ruta de Node gestionada por versiones +Doctor advierte cuando el servicio del gateway se ejecuta con Bun o una ruta de Node gestionada por versiones (`nvm`, `fnm`, `volta`, `asdf`, etc.). Los canales de WhatsApp + Telegram requieren Node, y las rutas de gestores de versiones pueden fallar después de actualizaciones porque el servicio no -carga la inicialización de su shell. Doctor ofrece migrar a una instalación de Node del sistema cuando +carga la inicialización de tu shell. Doctor ofrece migrar a una instalación de Node del sistema cuando está disponible (Homebrew/apt/choco). ### 18) Escritura de configuración + metadatos del asistente -Doctor conserva cualquier cambio de configuración y marca metadatos del asistente para registrar la -ejecución de doctor. +Doctor guarda cualquier cambio de configuración y registra metadatos del asistente para anotar la ejecución +de doctor. -### 19) Consejos del espacio de trabajo (copia de seguridad + sistema de memoria) +### 19) Sugerencias del espacio de trabajo (copia de seguridad + sistema de memoria) -Doctor sugiere un sistema de memoria del espacio de trabajo cuando falta y muestra un consejo de copia de seguridad -si el espacio de trabajo todavía no está bajo git. +Doctor sugiere un sistema de memoria para el espacio de trabajo cuando falta y muestra una sugerencia de copia de seguridad +si el espacio de trabajo aún no está bajo git. -Consulte [/concepts/agent-workspace](/es/concepts/agent-workspace) para ver una guía completa sobre -la estructura del espacio de trabajo y la copia de seguridad con git (se recomienda GitHub o GitLab privados). +Consulta [/concepts/agent-workspace](/es/concepts/agent-workspace) para obtener una guía completa sobre la +estructura del espacio de trabajo y la copia de seguridad con git (se recomienda GitHub o GitLab privados). diff --git a/docs/es/help/testing.md b/docs/es/help/testing.md index c611f9245..cfb9c34e0 100644 --- a/docs/es/help/testing.md +++ b/docs/es/help/testing.md @@ -2,25 +2,25 @@ read_when: - Ejecutar pruebas localmente o en CI - Agregar regresiones para errores de modelo/proveedor - - Depurar el comportamiento de gateway + agente -summary: 'Kit de pruebas: suites unitarias/e2e/live, ejecutores de Docker y qué cubre cada prueba' + - Depurar el comportamiento del gateway + agente +summary: 'Kit de pruebas: suites unit/e2e/live, ejecutores de Docker y qué cubre cada prueba' title: Pruebas x-i18n: - generated_at: "2026-04-08T02:17:59Z" + generated_at: "2026-04-09T01:30:09Z" model: gpt-5.4 provider: openai - source_hash: ace2c19bfc350780475f4348264a4b55be2b4ccbb26f0d33b4a6af34510943b5 + source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b source_path: help/testing.md workflow: 15 --- # Pruebas -OpenClaw tiene tres suites de Vitest (unitaria/integración, e2e, live) y un pequeño conjunto de ejecutores de Docker. +OpenClaw tiene tres suites de Vitest (unit/integration, e2e, live) y un pequeño conjunto de ejecutores de Docker. -Este documento es una guía de “cómo hacemos pruebas”: +Este documento es una guía de “cómo probamos”: -- Qué cubre cada suite (y qué _deliberadamente no_ cubre) +- 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 modelos/proveedores @@ -29,97 +29,97 @@ Este documento es una guía de “cómo hacemos pruebas”: La mayoría de los días: -- Puerta completa (se espera 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 holgada: `pnpm test:max` -- Bucle directo de watch 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` -- Sitio QA con Docker: `pnpm qa:lab:up` +- Gate completo (esperado 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 suficientes recursos: `pnpm test:max` +- Bucle de vigilancia directo 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` +- Sitio de QA con respaldo en Docker: `pnpm qa:lab:up` -Cuando tocas pruebas o quieres más confianza: +Cuando toques pruebas o quieras más confianza: -- Puerta de cobertura: `pnpm test:coverage` +- Gate de cobertura: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` -Cuando depuras proveedores/modelos reales (requiere credenciales reales): +Al depurar proveedores/modelos reales (requiere credenciales reales): -- Suite live (sondeos de modelos + gateway herramientas/imágenes): `pnpm test:live` -- Apuntar a un archivo live concreto en silencio: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (modelos + sondeos de herramientas/imágenes del gateway): `pnpm test:live` +- Apuntar a un archivo live en silencio: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Consejo: cuando solo necesitas un caso que falla, es preferible acotar las pruebas live mediante las variables de entorno de lista permitida descritas abajo. +Consejo: cuando solo necesites un caso fallido, prefiere limitar las pruebas live mediante las variables de entorno de allowlist descritas abajo. -## Suites de pruebas (qué se ejecuta dónde) +## Suites de prueba (qué se ejecuta dónde) -Piensa en las suites como de “realismo creciente” (y también de mayor inestabilidad/costo): +Piensa en las suites como “realismo creciente” (y mayor inestabilidad/costo): -### Unitaria / integración (predeterminada) +### Unit / integration (predeterminado) - Comando: `pnpm test` -- Configuración: diez ejecuciones secuenciales de shards (`vitest.full-*.config.ts`) sobre los proyectos de Vitest ya acotados -- Archivos: inventarios principales/unitarios en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas node de `ui` en lista permitida cubiertas por `vitest.unit.config.ts` +- Configuración: diez ejecuciones de shards secuenciales (`vitest.full-*.config.ts`) sobre los proyectos de Vitest con alcance existente +- Archivos: inventarios core/unit en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas node permitidas de `ui` cubiertas por `vitest.unit.config.ts` - Alcance: - - Pruebas puramente unitarias - - Pruebas de integración en proceso (autenticación de gateway, routing, herramientas, parsing, configuración) + - Pruebas unitarias puras + - Pruebas de integración en proceso (autenticación del gateway, routing, 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 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 raíz gigantesco. 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 raíz `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` 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 en los mismos carriles acotados cuando el diff solo toca archivos fuente/prueba enroutables; las ediciones de configuración/setup siguen recurriendo a una nueva ejecución amplia del proyecto raíz. - - Algunas pruebas seleccionadas de `plugin-sdk` y `commands` también se enrutan por carriles ligeros dedicados que omiten `test/setup-openclaw-runtime.ts`; los archivos con estado o mucho runtime se quedan en los carriles existentes. - - Algunos archivos fuente auxiliares de `plugin-sdk` y `commands` también asignan las ejecuciones en modo changed a pruebas hermanas explícitas en esos carriles ligeros, para que las ediciones auxiliares eviten volver a ejecutar la suite pesada completa de ese directorio. - - `auto-reply` ahora tiene tres buckets dedicados: helpers principales 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 respuestas fuera de las pruebas baratas de estado/chunk/token. -- Nota sobre el ejecutor embebido: + - `pnpm test` sin objetivo 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 nativo gigante del proyecto raíz. 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` en la raíz, porque un bucle de 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 archivos/directorios a través de carriles con alcance, por lo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo completo de inicio del proyecto raíz. + - `pnpm test:changed` expande las rutas modificadas de git en esos mismos carriles con alcance 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. + - Algunas pruebas seleccionadas de `plugin-sdk` y `commands` también se enrutan por carriles ligeros dedicados que omiten `test/setup-openclaw-runtime.ts`; los archivos con mucho estado/runtime permanecen en los carriles existentes. + - Algunos archivos auxiliares seleccionados de `plugin-sdk` y `commands` también mapean las ejecuciones de modo changed a pruebas hermanas explícitas en esos carriles ligeros, para que las ediciones de helpers eviten reejecutar 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 entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de compactación, - mantén ambos niveles de cobertura. - - Agrega regresiones enfocadas de helper para límites puros de routing/normalización. - - También mantén sanas las suites de integración del ejecutor embebido: + conserva ambos niveles de cobertura. + - Agrega regresiones enfocadas de helpers para límites puros de routing/normalización. + - También manté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.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 compactación sigan fluyendo - por las rutas reales `run.ts` / `compact.ts`; las pruebas solo de helper no son un - sustituto suficiente para esas rutas de integración. + - Esas suites verifican que los id con alcance y el comportamiento de compactación sigan fluyendo + por las rutas reales de `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 compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos raíz, configuraciones e2e y live. - - El carril UI raíz mantiene su configuración y optimizador de `jsdom`, pero ahora también se ejecuta con el ejecutor compartido no aislado. + - 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 carril raíz de UI mantiene su configuración y optimizador `jsdom`, 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 child Node de Vitest, para reducir el churn de compilación V8 durante ejecuciones locales grandes. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas compararlo con el comportamiento estándar de V8. + - El lanzador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` de forma predeterminada para los procesos Node hijo de Vitest, para reducir el churn de compilación de V8 durante ejecuciones locales grandes. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. - Nota sobre iteración local rápida: - - `pnpm test:changed` se 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 routing, solo con un límite de workers más alto. - - El autoescalado local de workers ahora es intencionalmente conservador y también reduce ritmo cuando la carga media del host ya es alta, para que varias ejecuciones simultáneas de Vitest hagan menos daño por defecto. - - La configuración base de Vitest marca los proyectos/archivos de configuración como `forceRerunTriggers` para que las nuevas ejecuciones en modo changed sigan siendo correctas cuando cambia el cableado de pruebas. + - `pnpm test:changed` enruta a través de carriles con alcance 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 routing, solo que con un límite de workers más alto. + - El autoescalado local de workers ahora es intencionalmente conservador y también reduce el ritmo cuando la carga promedio del host ya es alta, para que múltiples ejecuciones concurrentes de Vitest hagan menos daño de forma predeterminada. + - 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 cambie 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 archivos modificados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara el `test:changed` enroutado 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` toma métricas del árbol sucio actual enroutando la lista de archivos modificados mediante `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 arranque 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 desactivado. +- Nota de depuración de rendimiento: + - `pnpm test:perf:imports` habilita el informe de duración de importaciones de Vitest más la salida de desglose de importaciones. + - `pnpm test:perf:imports:changed` limita esa misma vista de perfilado a archivos modificados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado contra la ruta nativa del proyecto raíz para ese diff confirmado e imprime el tiempo total más el RSS máximo en 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 (smoke de gateway) +### E2E (smoke del 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 `threads` de Vitest 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. + - 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. - Anulaciones útiles: - - `OPENCLAW_E2E_WORKERS=` para forzar el número de workers (limitado a 16). - - `OPENCLAW_E2E_VERBOSE=1` para reactivar la salida detallada por consola. + - `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 + - Comportamiento end-to-end del gateway en múltiples instancias - Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas - Expectativas: - - Se ejecuta en CI (cuando está habilitado en la canalización) + - Se ejecuta en CI (cuando está habilitado en el pipeline) - No requiere claves reales - Tiene más piezas móviles que las pruebas unitarias (puede ser más lenta) @@ -129,16 +129,16 @@ Piensa en las suites como de “realismo creciente” (y también de mayor inest - 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` + exec 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 opt-in; no forma parte de la ejecución predeterminada de `pnpm test:e2e` - Requiere una CLI `openshell` local más un daemon de Docker funcional - Usa `HOME` / `XDG_CONFIG_HOME` aislados y luego destruye el gateway y el sandbox de prueba - Anulaciones útiles: - - `OPENCLAW_E2E_OPENSHELL=1` para habilitar la prueba cuando ejecutes 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 wrapper script + - `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 o script contenedor no predeterminado ### Live (proveedores reales + modelos reales) @@ -148,138 +148,140 @@ Piensa en las suites como de “realismo creciente” (y también de mayor inest - 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 de proveedor, rarezas en llamadas a herramientas, problemas de autenticación y comportamiento de límites de tasa + - Detectar cambios de formato de proveedor, particularidades de llamadas a herramientas, problemas de autenticación y comportamiento con límites de tasa - Expectativas: - - No es estable para CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas) + - No es estable en CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas) - Cuesta dinero / usa límites de tasa - - Es preferible 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 material de config/auth a un home temporal de prueba para que los fixtures unitarios no muten tu `~/.openclaw` real. -- Establece `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando quieras intencionalmente 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 extra de `~/.profile` y silencia logs de arranque del gateway/cháchara de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los logs completos de arranque. -- Rotación de claves API (específica por proveedor): establece `*_API_KEYS` con formato de coma/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o una anulación por live mediante `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas de límite de tasa. + - Es preferible ejecutar subconjuntos limitados 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 copian el material de configuración/autenticación a un home de prueba temporal para que los fixtures unitarios no puedan mutar 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 del gateway y el ruido de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los logs completos de inicio. +- Rotación de claves de API (específica del proveedor): establece `*_API_KEYS` con formato de comas/puntos y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o una anulación 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 silencio. - - `vitest.live.config.ts` desactiva la interceptación de consola de Vitest para que las líneas de progreso de proveedor/gateway fluyan inmediatamente durante las ejecuciones live. + - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas a proveedores se vean activas incluso cuando la captura de consola de Vitest está en silencio. + - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso de proveedor/gateway se transmitan de inmediato durante las ejecuciones live. - Ajusta los heartbeats de modelo directo con `OPENCLAW_LIVE_HEARTBEAT_MS`. - Ajusta los heartbeats de gateway/sondeo con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## ¿Qué suite debería ejecutar? +## ¿Qué suite debo ejecutar? Usa esta tabla de decisión: - Editar lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste mucho) -- Tocar redes de gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` -- Depurar “mi bot está caído” / fallos específicos de proveedor / llamadas a herramientas: ejecuta un `pnpm test:live` acotado +- Tocar redes del gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` +- Depurar “mi bot está caído” / fallos específicos del proveedor / llamadas a herramientas: ejecuta un `pnpm test:live` limitado -## Live: barrido de capacidades de nodo Android +## Live: barrido de capacidades del nodo Android - Prueba: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **cada comando anunciado actualmente** por un nodo Android conectado y afirmar el comportamiento contractual del comando. +- Objetivo: invocar **cada comando anunciado actualmente** por un nodo Android conectado y comprobar el comportamiento del contrato del comando. - Alcance: - Configuración previa/manual (la suite no instala/ejecuta/empareja la app). - - Validación comando por comando de `node.invoke` de gateway para el nodo Android seleccionado. + - Validación `node.invoke` del gateway comando por comando para el nodo Android seleccionado. - Configuración previa obligatoria: - - App Android ya conectada y emparejada con el gateway. - - App mantenida en primer plano. + - La app de Android ya está conectada y emparejada con el gateway. + - La app se mantiene en primer plano. - Permisos/consentimiento de captura concedidos para las capacidades que esperas que pasen. - Anulaciones opcionales de 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) +- Detalles completos de la configuración de Android: [App de Android](/es/platforms/android) ## Live: smoke 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 en absoluto con la clave dada. -- “Smoke de gateway” nos dice si la canalización completa gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). +- “Smoke del gateway” nos dice si funciona el pipeline completo de gateway+agente para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). -### Capa 1: completado directo de modelo (sin gateway) +### Capa 1: finalización directa del modelo (sin gateway) - Prueba: `src/agents/models.profiles.live.test.ts` - Objetivo: - - Enumerar modelos descubiertos - - Usar `getApiKeyForModel` para seleccionar modelos para los que tienes credenciales - - Ejecutar una pequeña finalización por modelo (y regresiones dirigidas cuando haga falta) + - Enumerar los modelos descubiertos + - 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 que `pnpm test:live` se centre en el smoke 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` centrado en el smoke del 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 para 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 de forma predeterminada 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 más pequeño. - Cómo seleccionar proveedores: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (lista permitida separada por comas) -- De dónde salen las claves: - - Por defecto: almacén de perfiles y entornos de respaldo + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por comas) +- De dónde provienen las claves: + - Por defecto: almacén de perfiles y respaldos de entorno - Establece `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **solo el almacén de perfiles** - Por qué existe: - - Separa “la API del proveedor está rota / la clave no es válida” de “la canalización gateway agente está rota” - - Contiene regresiones pequeñas y aisladas (ejemplo: replay 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 “el pipeline del agente del gateway está roto” + - Contiene regresiones pequeñas y aisladas (ejemplo: flujos de repetición de razonamiento y llamadas a herramientas de OpenAI Responses/Codex Responses) -### Capa 2: smoke de gateway + agente dev (lo que realmente hace "@openclaw") +### Capa 2: smoke del gateway + agente dev (lo que realmente hace "@openclaw") - Prueba: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - Levantar un gateway en proceso - - Crear/aplicar patch a una sesión `agent:dev:*` (anulación de modelo por ejecución) - - Iterar modelos-con-claves y afirmar: + - Crear/parchear una sesión `agent:dev:*` (anulación del modelo por ejecución) + - Iterar los modelos con claves y comprobar: - respuesta “significativa” (sin herramientas) - - que una invocación de herramienta real funcione (sondeo de lectura) - - sondeos opcionales de herramientas extra (sondeo exec+read) + - que funciona una invocación real de herramienta (sondeo de lectura) + - sondeos opcionales de herramientas adicionales (sondeo exec+read) - que las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) sigan funcionando -- Detalles del sondeo (para que puedas explicar los 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 vuelva a `read`. - - sondeo de imagen: la prueba adjunta un PNG generado (gato + código aleatorio) y espera que el modelo devuelva `cat `. +- Detalles del sondeo (para que puedas explicar fallos rápidamente): + - Sondeo `read`: la prueba escribe un archivo nonce en el espacio de trabajo y pide al agente que lo `read` y devuelva el nonce. + - Sondeo `exec+read`: la prueba pide al agente que escriba un nonce en un archivo temporal mediante `exec` y luego lo vuelva a `read`. + - Sondeo de imagen: la prueba adjunta un PNG generado (gato + código aleatorizado) 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 para la lista permitida moderna - - O establece `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o lista separada por comas) para acotar -- Cómo seleccionar proveedores (evita “todo OpenRouter”): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (lista permitida separada por comas) + - 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 lista separada por comas) para limitar + - Los barridos de gateway modern/all usan de forma predeterminada 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 más pequeño. +- Cómo seleccionar proveedores (evitar “todo OpenRouter”): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist 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 soporte para entrada de imagen + - el sondeo 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 embebido reenvía un mensaje multimodal del usuario al modelo - - Afirmación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores) + - El 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 + - Verificación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten pequeños errores) -Consejo: para ver qué puedes probar en tu máquina (y los ids exactos `provider/model`), ejecuta: +Consejo: para ver lo que puedes probar en tu máquina (y los ids exactos `provider/model`), ejecuta: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke de backend CLI (Claude, Codex, Gemini u otras CLI locales) +## Live: smoke del backend de CLI (Claude, Codex, Gemini u otras CLI 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 smoke específicos del backend viven con la definición `cli-backend.ts` de la extensión propietaria. +- Objetivo: validar el pipeline de Gateway + agente usando un backend de CLI local, sin tocar tu configuración predeterminada. +- Los valores predeterminados de smoke específicos del backend están junto a 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` -- Valores predeterminados: +- Predeterminados: - Proveedor/modelo predeterminado: `claude-cli/claude-sonnet-4-6` - - El comportamiento de comando/args/imagen proviene de los metadatos del plugin propietario del backend CLI. -- Anulaciones opcionales: + - El comportamiento de comando/args/imagen proviene de los metadatos del plugin propietario del backend de CLI. +- Anulaciones (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 `IMAGE_ARG` está configurado. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivos de imagen como args de CLI en lugar de inyectarlas en el prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los args 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 Claude Sonnet -> Opus (establece `1` para forzarlo cuando el modelo seleccionado admita un objetivo de cambio). + - `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 objetivo de cambio). Ejemplo: @@ -295,7 +297,7 @@ Receta de Docker: pnpm test:docker:live-cli-backend ``` -Recetas Docker de un solo proveedor: +Recetas de Docker para un solo proveedor: ```bash pnpm test:docker:live-cli-backend:claude @@ -305,27 +307,27 @@ pnpm test:docker:live-cli-backend:gemini Notas: -- El ejecutor Docker está en `scripts/test-live-cli-backend-docker.sh`. -- Ejecuta el smoke live del backend CLI dentro de la imagen Docker del repositorio como usuario no root `node`. -- Resuelve los metadatos del smoke CLI desde la extensión propietaria y luego instala el paquete CLI 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`). -- El smoke 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 mediante la CLI de gateway. -- El smoke predeterminado de Claude también aplica patch a la sesión de Sonnet a Opus y verifica que la sesión reanudada siga recordando una nota anterior. +- El ejecutor de Docker está en `scripts/test-live-cli-backend-docker.sh`. +- Ejecuta el smoke live del backend de CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. +- Resuelve los metadatos del smoke de CLI desde la extensión propietaria y luego instala el paquete de 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`). +- El smoke live del backend de 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 mediante la CLI del gateway. +- El smoke predeterminado 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: smoke de enlace ACP (`/acp spawn ... --bind here`) +## Live: smoke de ACP bind (`/acp spawn ... --bind here`) - Prueba: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar el flujo real de enlace de conversación ACP con un agente ACP live: +- Objetivo: validar el flujo real de bind de conversación ACP con un agente ACP live: - enviar `/acp spawn --bind here` - - enlazar en su lugar una conversación sintética de canal de mensajes - - enviar un seguimiento normal sobre esa misma conversación - - verificar que el seguimiento llega a la transcripción de la sesión ACP enlazada + - enlazar una conversación sintética de canal de mensajes en su lugar + - enviar un seguimiento normal en esa misma conversación + - verificar que el seguimiento llegue a 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` -- Valores predeterminados: +- Predeterminados: - Agentes ACP en Docker: `claude,codex,gemini` - Agente ACP para `pnpm test:live ...` directo: `claude` - - Canal sintético: contexto de conversación estilo DM de Slack + - Canal sintético: contexto de conversación tipo DM de Slack - Backend ACP: `acpx` - Anulaciones: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -334,8 +336,8 @@ Notas: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Notas: - - Este carril usa la superficie `chat.send` del gateway con campos de ruta de origen sintéticos solo para admin, de modo que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir entrega externa. - - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está definido, la prueba usa el registro incorporado de agentes del plugin embebido `acpx` para el agente de arnés ACP seleccionado. + - Este carril usa la superficie `chat.send` del gateway con campos sintéticos de ruta de origen solo para administradores, para que las pruebas puedan adjuntar contexto de canal de mensajes sin simular una entrega externa. + - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro integrado de agentes del plugin `acpx` embebido para el agente de arnés ACP seleccionado. Ejemplo: @@ -351,7 +353,7 @@ Receta de Docker: pnpm test:docker:live-acp-bind ``` -Recetas Docker de un solo agente: +Recetas de Docker para un solo agente: ```bash pnpm test:docker:live-acp-bind:claude @@ -361,58 +363,58 @@ pnpm test:docker:live-acp-bind:gemini Notas de Docker: -- El ejecutor Docker está en `scripts/test-live-acp-bind-docker.sh`. -- Por defecto, ejecuta el smoke de enlace ACP contra todos los agentes 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 provenientes del profile cargado. +- El ejecutor de Docker está en `scripts/test-live-acp-bind-docker.sh`. +- De forma predeterminada, ejecuta el smoke de ACP bind contra todos los agentes 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 limitar la matriz. +- Obtiene `~/.profile`, prepara el material de autenticación CLI correspondiente dentro del contenedor, instala `acpx` en un prefijo npm escribible 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 obtenidas desde el profile cargado. ### Recetas live recomendadas -Las listas permitidas explícitas y acotadas son las más rápidas y menos inestables: +Las allowlists explícitas y limitadas son las más rápidas y menos inestables: - Un solo modelo, directo (sin gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Un solo modelo, smoke de gateway: +- Un solo modelo, smoke del gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Llamada a herramientas a través de 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` -- Foco Google (clave API de Gemini + Antigravity): - - Gemini (clave API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Foco en Google (clave de API de Gemini + Antigravity): + - Gemini (clave de API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Notas: -- `google/...` usa la API de Gemini (clave API). +- `google/...` usa la API de Gemini (clave de API). - `google-antigravity/...` usa el puente OAuth de Antigravity (endpoint de agente estilo Cloud Code Assist). -- `google-gemini-cli/...` usa la CLI local de Gemini en tu máquina (autenticación aparte + peculiaridades de herramientas). -- Gemini API frente a Gemini CLI: - - API: OpenClaw llama a la API alojada de Gemini de Google sobre HTTP (autenticación por clave API / perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”. - - CLI: OpenClaw ejecuta una binaria local `gemini`; tiene su propia autenticación y puede comportarse de forma distinta (streaming/soporte de herramientas/desfase de versión). +- `google-gemini-cli/...` usa la CLI local de Gemini en tu máquina (autenticación independiente + particularidades de herramientas). +- API de Gemini vs CLI de Gemini: + - API: OpenClaw llama a la API alojada de Gemini de Google mediante HTTP (clave de API / autenticación de perfil); esto es lo que la mayoría de los usuarios quieren decir con “Gemini”. + - CLI: OpenClaw ejecuta un binario `gemini` local; tiene su propia autenticación y puede comportarse de manera diferente (streaming/compatibilidad de herramientas/desfase de versión). ## Live: matriz de modelos (qué cubrimos) -No hay una “lista fija de modelos en CI” (live es opt-in), 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 smoke moderno (llamada a herramientas + imagen) +### Conjunto smoke moderno (llamadas a herramientas + imagen) Esta es la ejecución de “modelos comunes” que esperamos mantener funcionando: - 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 Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos antiguos Gemini 2.x) +- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos antiguos Gemini 2.x) - 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 smoke de gateway con herramientas + imagen: +Ejecuta smoke del 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` -### Base: llamada a herramientas (Read + Exec opcional) +### Base: llamadas a herramientas (Read + Exec opcional) Elige al menos uno por familia de proveedor: @@ -422,16 +424,16 @@ Elige al menos uno por familia de proveedor: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Cobertura adicional opcional (buena de tener): +Cobertura adicional opcional (sería bueno tenerla): - xAI: `xai/grok-4` (o la última disponible) -- Mistral: `mistral/`… (elige uno con capacidad de “tools” que tengas habilitado) +- Mistral: `mistral/`… (elige un modelo con capacidad de “tools” 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) -Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI con capacidad de 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 el sondeo de imagen. ### Agregadores / gateways alternativos @@ -443,43 +445,43 @@ 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` (cloud/API), más 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 codificar “todos los modelos” en la documentación. La lista autorizada es lo 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 autoritativa es lo que devuelva `discoverModels(...)` en tu máquina + las claves disponibles. -## Credenciales (nunca las confirmes en git) +## Credenciales (nunca las confirmes en el repositorio) -Las pruebas live descubren credenciales de la misma forma que la CLI. Implicaciones prácticas: +Las pruebas live descubren credenciales de la misma manera que la CLI. Implicaciones prácticas: - Si la CLI funciona, las pruebas live deberían encontrar las mismas claves. -- Si una prueba live dice “sin credenciales”, depúralo igual que depurarías `openclaw models list` / selección de modelo. +- Si una prueba live dice “no creds”, depúrala igual que depurarías `openclaw models list` / selección de modelo. -- Perfiles de autenticación por agente: `~/.openclaw/agents//agent/auth-profiles.json` (a esto se refieren las pruebas live con “claves de perfil”) +- Perfiles de autenticación por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significa “profile keys” 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 existe, 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 CLI externos compatibles a un home temporal de prueba; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan las anulaciones de ruta `agents.*.workspace` / `agentDir` para que los sondeos no toquen tu espacio de trabajo real del host. +- 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 la configuración activa, los archivos `auth-profiles.json` por agente, el `credentials/` heredado y los directorios de autenticación CLI externos compatibles a un home de prueba temporal de forma predeterminada; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan las anulaciones de ruta `agents.*.workspace` / `agentDir` para que los sondeos no toquen tu espacio de trabajo real del host. -Si quieres depender de claves del entorno (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores Docker de abajo (pueden montar `~/.profile` en el contenedor). +Si quieres depender de claves de entorno (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` en el 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 BytePlus +## Live del plan de coding 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` -- Anulación opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Anulación opcional del modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## Live de medios de workflow 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` - Alcance: - - Ejercita las rutas integradas de imagen, video y `music_generate` de comfy - - Omite cada capacidad a menos que `models.providers.comfy.` esté configurado - - Es útil después de cambiar el envío de workflows de comfy, el sondeo, las descargas o el registro del plugin + - Ejercita las rutas empaquetadas de comfy para imagen, video y `music_generate` + - Omite cada capacidad salvo que `models.providers.comfy.` esté configurado + - Útil tras cambiar el envío de workflows de comfy, el polling, las descargas o el registro del plugin ## Live de generación de imágenes @@ -487,24 +489,24 @@ Si quieres depender de claves del entorno (por ejemplo, exportadas en tu `~/.pro - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Arnés: `pnpm test:live:media image` - Alcance: - - Enumera cada plugin proveedor de generación de imágenes registrado - - Carga variables de entorno de proveedor faltantes desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/del entorno 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 compartida de runtime: + - Enumera cada plugin de proveedor de generación de imágenes registrado + - Carga las variables de entorno de proveedor faltantes desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto las claves de API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin autenticación/perfil/modelo utilizable + - Ejecuta las variantes estándar de generación de imágenes a través de la capacidad compartida de runtime: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Proveedores integrados cubiertos actualmente: +- Proveedores empaquetados actuales cubiertos: - `openai` - `google` -- Acotación opcional: +- Limitación opcional: - `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 auth del almacén de perfiles e ignorar anulaciones solo del entorno + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación desde el almacén de perfiles e ignorar anulaciones solo de entorno ## Live de generación de música @@ -512,23 +514,23 @@ Si quieres depender de claves del entorno (por ejemplo, exportadas en tu `~/.pro - 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 de proveedor de generación de música + - Ejercita la ruta compartida empaquetada del proveedor de generación de música - Actualmente cubre Google y MiniMax - - Carga variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/del entorno 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 + - Carga las variables de entorno de proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto las claves de API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin autenticación/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 carril compartido: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: archivo live de Comfy separado, no este barrido compartido -- Acotación opcional: + - `comfy`: archivo live de Comfy independiente, no este barrido compartido +- Limitació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 auth del almacén de perfiles e ignorar anulaciones solo del entorno + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación desde el almacén de perfiles e ignorar anulaciones solo de entorno ## Live de generación de video @@ -536,200 +538,200 @@ Si quieres depender de claves del entorno (por ejemplo, exportadas en tu `~/.pro - 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 de proveedor de generación de video - - Carga variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves API live/del entorno 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 + - Ejercita la ruta compartida empaquetada del proveedor de generación de video + - Carga las variables de entorno de proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto las claves de API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin autenticación/perfil/modelo utilizable - Ejecuta ambos modos de runtime declarados cuando están disponibles: - `generate` con entrada solo de prompt - - `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local basada en buffer en el barrido compartido - - `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local basada en buffer 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 remota de imagen - - Cobertura específica de proveedor Vydra: + - `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 actualmente declarados pero omitidos de `imageToVideo` en el barrido compartido: + - `vydra` porque el `veo3` empaquetado es solo texto y el `kling` empaquetado requiere una URL de imagen remota + - Cobertura específica del proveedor Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - ese archivo ejecuta `veo3` texto a video más un carril `kling` que usa por defecto un fixture de URL remota de imagen + - ese archivo ejecuta `veo3` de texto a video más un carril `kling` que usa por defecto un fixture de URL de imagen remota - Cobertura live actual de `videoToVideo`: - `runway` solo cuando el modelo seleccionado es `runway/gen4_aleph` - - Proveedores `videoToVideo` actualmente declarados pero omitidos en el barrido compartido: + - Proveedores actualmente declarados pero omitidos de `videoToVideo` en el barrido compartido: - `alibaba`, `qwen`, `xai` porque esas rutas actualmente requieren URLs de referencia remotas `http(s)` / MP4 - - `google` porque el carril compartido actual de Gemini/Veo usa entrada local basada en buffer y esa ruta no se acepta en el barrido compartido - - `openai` porque el carril compartido actual no tiene garantías de acceso específicas de organización para inpaint/remix de video -- Acotación opcional: + - `google` porque el carril 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 carril compartido actual carece de garantías de acceso específicas de organización para video inpaint/remix +- Limitació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"` - Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar auth del almacén de perfiles e ignorar anulaciones solo del entorno + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación desde el almacén de perfiles e ignorar anulaciones solo de entorno ## 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 punto de entrada nativo del repositorio + - Ejecuta las suites live compartidas de imagen, música y video mediante un único entrypoint nativo del repositorio - Carga automáticamente variables de entorno de proveedor faltantes desde `~/.profile` - - Acota automáticamente cada suite a proveedores que actualmente tienen auth utilizable por defecto - - Reutiliza `scripts/test-live.mjs`, para que el comportamiento de heartbeat y modo silencioso siga siendo coherente + - Limita automáticamente cada suite a proveedores que actualmente tienen autenticación utilizable de forma predeterminada + - Reutiliza `scripts/test-live.mjs`, para que el comportamiento de heartbeat y modo silencioso siga siendo consistente - 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 Docker (comprobaciones opcionales de “funciona en Linux”) +## Ejecutores de Docker (comprobaciones opcionales de "funciona en Linux") -Estos ejecutores Docker se dividen en dos grupos: +Estos ejecutores de Docker se dividen en dos grupos: -- Ejecutores live de modelos: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live correspondiente de claves de perfil 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 local de configuración y espacio de trabajo (y cargando `~/.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 smoke más pequeño para que un barrido Docker completo 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 local de configuración y el espacio de trabajo (y obteniendo `~/.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 smoke 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_STEP_TIMEOUT_MS=45000`, y `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Anula esas variables de entorno cuando - explícitamente quieras el barrido exhaustivo más amplio. -- `test:docker:all` construye una vez la imagen live de Docker mediante `test:docker:live-build` y luego la reutiliza para los dos carriles live de Docker. -- Ejecutores smoke de contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` levantan uno o más contenedores reales y verifican rutas de integración de nivel superior. + quieras explícitamente el escaneo exhaustivo más grande. +- `test:docker:all` construye una vez la imagen Docker live mediante `test:docker:live-build`, y luego la reutiliza para los dos carriles live de Docker. +- Ejecutores smoke de contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` levantan uno o más contenedores reales y verifican rutas de integración de mayor nivel. -Los ejecutores Docker live de modelos también montan por bind solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), y 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 auth del host: +Los ejecutores Docker live de modelos también montan con bind solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está limitada), y luego los copian al home del contenedor antes de la ejecución para que OAuth de CLI externa pueda actualizar 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`) -- Smoke de enlace ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) -- Smoke de backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) +- Smoke de ACP bind: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Smoke del backend de CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) - Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke 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`) -- Red 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 precargado + puente stdio + smoke sin procesar de marcos de notificación de Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke de instalación + alias `/plugin` + semántica de reinicio del bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Redes del gateway (dos contenedores, autenticación WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Puente de canal MCP (Gateway inicializado + puente stdio + smoke sin procesar de marcos de notificación de Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke 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 live de modelos también montan por bind el checkout actual en solo lectura y -lo preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la imagen de runtime -ligera y aun así ejecuta Vitest contra tu código/configuración local exactos. -El paso de preparación omite grandes cachés solo locales y salidas de build de apps como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios locales de salida `.build` o -Gradle, para que las ejecuciones live de Docker no pasen minutos copiando +Los ejecutores Docker live de modelos también montan con bind la copia de trabajo actual en modo solo lectura y +la preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la +imagen de runtime ligera, al tiempo que sigue ejecutando Vitest contra tu código/configuración local exactos. +El paso de preparación omite cachés grandes solo locales y salidas de build de apps como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios de salida locales de app `.build` o +Gradle, para que las ejecuciones Docker live 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 Telegram/Discord/etc. dentro del contenedor. -`test:docker:live-models` sigue ejecutando `pnpm test:live`, así que propaga -también `OPENCLAW_LIVE_GATEWAY_*` cuando necesites acotar o excluir la cobertura -live de gateway de ese carril Docker. +También establecen `OPENCLAW_SKIP_CHANNELS=1` para que los sondeos live del 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 pasa también +`OPENCLAW_LIVE_GATEWAY_*` cuando necesites limitar o excluir cobertura live +del gateway de ese carril Docker. `test:docker:openwebui` es un smoke de compatibilidad de nivel superior: inicia un -contenedor de gateway OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, -inicia un contenedor de Open WebUI fijado contra ese gateway, inicia sesión a través de +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` expone `openclaw/default`, y luego envía una -petición 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 completar su propia configuración de arranque en frío. +solicitud real de chat a través del proxy `/api/chat/completions` de Open WebUI. +La primera ejecución puede ser notablemente más lenta porque Docker podría necesitar descargar la +imagen de Open WebUI y Open WebUI podría necesitar completar su propia configuración de arranque en frío. Este carril espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` -(`~/.profile` por defecto) es la forma principal de proporcionarla en ejecuciones Dockerizadas. +(`~/.profile` de forma predeterminada) es la forma principal de proporcionarla en ejecuciones con Docker. Las ejecuciones exitosas 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. Levanta un Gateway -precargado en un contenedor, inicia un segundo contenedor que ejecuta `openclaw mcp serve`, luego -verifica descubrimiento de conversaciones enroutadas, lecturas de transcripción, metadatos de adjuntos, -comportamiento de cola de eventos live, routing de envío saliente y notificaciones estilo Claude de canal + -permisos a través del puente MCP stdio real. La comprobación de notificaciones +cuenta real de Telegram, Discord o iMessage. Inicia un contenedor de Gateway +inicializado, arranca un segundo contenedor que ejecuta `openclaw mcp serve`, luego +verifica el descubrimiento de conversaciones enrutadas, lecturas de transcripciones, metadatos de adjuntos, +comportamiento de cola de eventos live, routing de envíos salientes y notificaciones de estilo Claude de canal + +permisos sobre el puente MCP stdio real. La comprobación de notificaciones inspecciona directamente los marcos MCP stdio sin procesar, de modo que el smoke valida lo que el -puente realmente emite, no solo lo que una SDK cliente concreta casualmente expone. +puente realmente emite, no solo lo que un SDK cliente específico exponga por casualidad. -Smoke manual ACP de hilo en lenguaje natural (no CI): +Smoke manual de hilo ACP en lenguaje natural (no CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Conserva este script para flujos de trabajo de regresión/depuración. Puede volver a ser necesario para validación de routing de hilos ACP, así que no lo elimines. +- Mantén este script para flujos de trabajo de regresión/depuración. Puede ser necesario de nuevo para validar el routing 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 pruebas +- `OPENCLAW_PROFILE_FILE=...` (predeterminado: `~/.profile`) montado en `/home/node/.profile` y obtenido antes de ejecutar las pruebas - `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 externos de auth CLI bajo `$HOME` se montan en solo lectura bajo `/host-auth...` y luego se copian a `/home/node/...` antes de empezar las pruebas +- Los directorios/archivos de autenticación CLI externa 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` - - Anula 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 + - Las ejecuciones limitadas por proveedor montan solo los directorios/archivos necesarios inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Anúlalo 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 limitar la ejecución - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar proveedores dentro del contenedor - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para asegurar que las credenciales provengan del almacén de perfiles (no del entorno) - `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por el gateway para el smoke de Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` para anular el prompt de comprobación nonce usado por el smoke de Open WebUI -- `OPENWEBUI_IMAGE=...` para anular el tag fijado de imagen de Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` para anular el prompt de verificación con nonce usado por el smoke de Open WebUI +- `OPENWEBUI_IMAGE=...` para anular la etiqueta fijada de la imagen de Open WebUI -## Verificación básica de docs +## Verificación básica de documentación -Ejecuta comprobaciones de documentación después de editar docs: `pnpm check:docs`. -Ejecuta la validación completa de anchors de Mintlify cuando también necesites comprobaciones de encabezados en página: `pnpm docs:check-links:anchors`. +Ejecuta las comprobaciones de docs después de editar documentación: `pnpm check:docs`. +Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobar encabezados dentro de la página: `pnpm docs:check-links:anchors`. ## Regresión offline (segura para CI) -Estas son regresiones de “canalización real” sin proveedores reales: +Estas son regresiones de “pipeline real” sin proveedores reales: -- Llamada a herramientas de gateway (OpenAI simulado, gateway real + bucle de 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 config + auth exigidos): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Llamadas a herramientas del gateway (OpenAI simulado, gateway real + bucle de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Asistente del gateway (WS `wizard.start`/`wizard.next`, escritura de config + auth obligatoria): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evaluaciones de fiabilidad del agente (Skills) +## Evals de confiabilidad del agente (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 “evals de confiabilidad del agente”: -- Llamada simulada a herramientas mediante el gateway real + bucle de agente (`src/gateway/gateway.test.ts`). +- Llamadas a herramientas simuladas a través del gateway real + bucle de agente (`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`). Lo que aún falta para Skills (consulta [Skills](/es/tools/skills)): -- **Toma de decisiones:** cuando se listan Skills en el prompt, ¿elige el agente la Skill correcta (o evita las irrelevantes)? -- **Cumplimiento:** ¿lee el agente `SKILL.md` antes de usarla y sigue los pasos/args requeridos? -- **Contratos de flujo de trabajo:** escenarios de varios turnos que afirmen orden de herramientas, persistencia del historial de sesión y límites de sandbox. +- **Toma de decisiones:** cuando las Skills se enumeran 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 verifiquen orden de herramientas, arrastre del historial de la sesión y límites del sandbox. -Las evaluaciones futuras deberían seguir siendo deterministas primero: +Las evals futuras deberían seguir siendo deterministas primero: -- Un ejecutor de escenarios usando proveedores simulados para afirmar llamadas a herramientas + orden, lecturas de archivos de Skill y cableado de sesión. -- Un pequeño conjunto de escenarios centrados en Skills (usar vs evitar, restricciones, inyección en el prompt). -- Evaluaciones live opcionales (opt-in, controladas por entorno) solo después de que la suite segura para CI esté implementada. +- Un ejecutor de escenarios que use proveedores simulados para comprobar llamadas a herramientas + orden, lecturas de archivos de Skills y cableado de sesiones. +- Un pequeño conjunto de escenarios centrados en Skills (usar vs evitar, gating, inyección de prompts). +- Evals live opcionales (opt-in, controladas por env) solo después de que la suite segura para CI esté implementada. -## Pruebas de contrato (forma de plugins y canales) +## Pruebas de contrato (forma de plugin y canal) Las pruebas de contrato verifican que cada plugin y canal registrado se ajuste a su contrato de interfaz. Iteran sobre todos los plugins descubiertos y ejecutan un conjunto de -afirmaciones de forma y comportamiento. El carril unitario predeterminado `pnpm test` +comprobaciones de forma y comportamiento. El carril unitario predeterminado de `pnpm test` omite intencionalmente estos archivos compartidos de seams y smoke; ejecuta los comandos de contrato explícitamente -cuando toques superficies compartidas de canales o proveedores. +cuando toques superficies compartidas de canal o proveedor. ### Comandos - Todos los contratos: `pnpm test:contracts` -- Solo contratos de canales: `pnpm test:contracts:channels` -- Solo contratos de proveedores: `pnpm test:contracts:plugins` +- Solo contratos de canal: `pnpm test:contracts:channels` +- Solo contratos de proveedor: `pnpm test:contracts:plugins` -### Contratos de canales +### Contratos de canal 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 enlace de sesión -- **outbound-payload** - Estructura de la carga del mensaje +- **outbound-payload** - Estructura del payload del mensaje - **inbound** - Manejo de mensajes entrantes -- **actions** - Handlers de acciones del canal -- **threading** - Manejo del id de hilo -- **directory** - API de directorio/lista -- **group-policy** - Aplicación de política de grupo +- **actions** - Manejadores de acciones del canal +- **threading** - Manejo de id de hilo +- **directory** - API de directorio/listado +- **group-policy** - Aplicación de políticas de grupo -### Contratos de estado de proveedores +### Contratos de estado del proveedor Ubicados en `src/plugins/contracts/*.contract.test.ts`. - **status** - Sondeos de estado del canal - **registry** - Forma del registro de plugins -### Contratos de proveedores +### Contratos de proveedor Ubicados en `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato de flujo de autenticación +- **auth** - Contrato del flujo de autenticación - **auth-choice** - Elección/selección de autenticación -- **catalog** - API de catálogo de modelos +- **catalog** - API del catálogo de modelos - **discovery** - Descubrimiento de plugins - **loader** - Carga de plugins - **runtime** - Runtime del proveedor @@ -740,19 +742,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 el 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 descubierto 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 petición) -- 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 +- 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 limitada y opt-in mediante variables de entorno - Prefiere apuntar a la capa más pequeña que detecte el error: - - error de conversión/replay de petición del proveedor → prueba de modelos directos - - error de canalización gateway sesión/historial/herramienta → smoke live de gateway o prueba simulada de gateway segura para CI -- Barrera de protección 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 metadatos del registro (`listSecretTargetRegistryEntries()`), y luego afirma que los ids exec de segmentos de recorrido son rechazados. - - 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 no clasificados para que nuevas clases no puedan omitirse en silencio. + - error de conversión/repetición de solicitud del proveedor → prueba directa de modelos + - error del pipeline del gateway de sesión/historial/herramientas → smoke live del gateway o prueba segura para CI del gateway simulado +- Barandilla de recorrido SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo muestreado por clase de SecretRef desde los metadatos del registro (`listSecretTargetRegistryEntries()`), y luego comprueba que se rechacen los id de 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 ante ids de objetivo sin clasificar para que las nuevas clases no puedan omitirse silenciosamente. diff --git a/docs/es/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md b/docs/es/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md deleted file mode 100644 index ec418b288..000000000 --- a/docs/es/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md +++ /dev/null @@ -1,584 +0,0 @@ ---- -date: 2026-04-05T00:00:00Z -status: active -title: 'refactor: Convertir plugin-sdk en un paquete real del workspace de forma incremental' -type: refactor -x-i18n: - generated_at: "2026-04-07T05:04:02Z" - model: gpt-5.4 - provider: openai - source_hash: ea1ca41846363c506a0db6dbca746e840d7c71ca82bbfc5277af9e2ae7f6b070 - source_path: plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md - workflow: 15 ---- - -# refactor: Convertir plugin-sdk en un paquete real del workspace de forma incremental - -## Descripción general - -Este plan introduce un paquete real del workspace para el SDK de plugins en -`packages/plugin-sdk` y lo usa para incorporar una pequeña primera ola de extensiones a -límites de paquetes aplicados por el compilador. El objetivo es hacer que las -importaciones relativas no permitidas fallen bajo `tsc` normal para un conjunto seleccionado de extensiones -de proveedor empaquetadas, sin forzar una migración en todo el repositorio ni una enorme -superficie de conflictos de fusión. - -El movimiento incremental clave es ejecutar dos modos en paralelo durante un tiempo: - -| Modo legado | Forma de importación | Quién lo usa | Aplicación | -| ----------- | -------------------------- | ------------------------------------ | --------------------------------------------- | -| Modo legado | `openclaw/plugin-sdk/*` | todas las extensiones existentes no incorporadas | se mantiene el comportamiento permisivo actual | -| Modo opt-in | `@openclaw/plugin-sdk/*` | solo las extensiones de la primera ola | `rootDir` local al paquete + referencias de proyecto | - -## Planteamiento del problema - -El repositorio actual exporta una gran superficie pública del SDK de plugins, pero no es un -paquete real del workspace. En su lugar: - -- el `tsconfig.json` raíz asigna `openclaw/plugin-sdk/*` directamente a - `src/plugin-sdk/*.ts` -- las extensiones que no se incorporaron al experimento anterior siguen compartiendo ese - comportamiento global de alias de origen -- agregar `rootDir` solo funciona cuando las importaciones permitidas del SDK dejan de resolverse hacia código fuente - sin procesar del repositorio - -Eso significa que el repositorio puede describir la política de límites deseada, pero TypeScript -no la aplica limpiamente para la mayoría de las extensiones. - -Quieres una ruta incremental que: - -- convierta `plugin-sdk` en algo real -- mueva el SDK hacia un paquete del workspace llamado `@openclaw/plugin-sdk` -- cambie solo alrededor de 10 extensiones en el primer PR -- deje el resto del árbol de extensiones en el esquema antiguo hasta una limpieza posterior -- evite el flujo de trabajo `tsconfig.plugin-sdk.dts.json` + declaraciones generadas en postinstall - como mecanismo principal para el despliegue de la primera ola - -## Trazabilidad de requisitos - -- R1. Crear un paquete real del workspace para el SDK bajo `packages/`. -- R2. Nombrar el nuevo paquete `@openclaw/plugin-sdk`. -- R3. Dar al nuevo paquete SDK su propio `package.json` y `tsconfig.json`. -- R4. Mantener las importaciones heredadas `openclaw/plugin-sdk/*` funcionando para las extensiones - no incorporadas durante la ventana de migración. -- R5. Incorporar solo una pequeña primera ola de extensiones en el primer PR. -- R6. Las extensiones de la primera ola deben fallar de forma cerrada para las importaciones relativas que salgan - de la raíz de su paquete. -- R7. Las extensiones de la primera ola deben consumir el SDK mediante una - dependencia de paquete y una referencia de proyecto de TS, no mediante alias `paths` de la raíz. -- R8. El plan debe evitar un paso obligatorio de generación en postinstall para todo el repositorio - para la corrección en el editor. -- R9. El despliegue de la primera ola debe ser revisable e integrable como un PR moderado, - no como una refactorización de más de 300 archivos en todo el repositorio. - -## Límites del alcance - -- No migrar completamente todas las extensiones empaquetadas en el primer PR. -- No es necesario eliminar `src/plugin-sdk` en el primer PR. -- No es necesario reconfigurar inmediatamente cada ruta de compilación o prueba raíz para usar el nuevo paquete. -- No se intenta forzar errores visuales de VS Code para todas las extensiones no incorporadas. -- No hay limpieza amplia de lint para el resto del árbol de extensiones. -- No hay cambios grandes en el comportamiento en tiempo de ejecución más allá de la resolución de importaciones, la - propiedad del paquete y la aplicación de límites para las extensiones incorporadas. - -## Contexto e investigación - -### Código y patrones relevantes - -- `pnpm-workspace.yaml` ya incluye `packages/*` y `extensions/*`, por lo que un - nuevo paquete del workspace bajo `packages/plugin-sdk` encaja en el diseño existente del - repositorio. -- Los paquetes existentes del workspace, como `packages/memory-host-sdk/package.json` - y `packages/plugin-package-contract/package.json`, ya usan mapas `exports` locales al paquete - enraizados en `src/*.ts`. -- El `package.json` raíz actualmente publica la superficie del SDK mediante `./plugin-sdk` - y `./plugin-sdk/*` exports respaldados por `dist/plugin-sdk/*.js` y - `dist/plugin-sdk/*.d.ts`. -- `src/plugin-sdk/entrypoints.ts` y `scripts/lib/plugin-sdk-entrypoints.json` - ya actúan como el inventario canónico de entrypoints para la superficie del SDK. -- El `tsconfig.json` raíz actualmente asigna: - - `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts` - - `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts` -- El experimento anterior de límites mostró que `rootDir` local al paquete funciona para - importaciones relativas no permitidas solo después de que las importaciones permitidas del SDK dejan de resolverse hacia código fuente - sin procesar fuera del paquete de extensión. - -### Conjunto de extensiones de la primera ola - -Este plan asume que la primera ola es el conjunto con muchos proveedores que tiene menos probabilidades -de arrastrar casos límite complejos del tiempo de ejecución de canales: - -- `extensions/anthropic` -- `extensions/exa` -- `extensions/firecrawl` -- `extensions/groq` -- `extensions/mistral` -- `extensions/openai` -- `extensions/perplexity` -- `extensions/tavily` -- `extensions/together` -- `extensions/xai` - -### Inventario de superficie del SDK de la primera ola - -Las extensiones de la primera ola actualmente importan un subconjunto manejable de subrutas del SDK. -El paquete inicial `@openclaw/plugin-sdk` solo necesita cubrir estas: - -- `agent-runtime` -- `cli-runtime` -- `config-runtime` -- `core` -- `image-generation` -- `media-runtime` -- `media-understanding` -- `plugin-entry` -- `plugin-runtime` -- `provider-auth` -- `provider-auth-api-key` -- `provider-auth-login` -- `provider-auth-runtime` -- `provider-catalog-shared` -- `provider-entry` -- `provider-http` -- `provider-model-shared` -- `provider-onboard` -- `provider-stream-family` -- `provider-stream-shared` -- `provider-tools` -- `provider-usage` -- `provider-web-fetch` -- `provider-web-search` -- `realtime-transcription` -- `realtime-voice` -- `runtime-env` -- `secret-input` -- `security-runtime` -- `speech` -- `testing` - -### Aprendizajes institucionales - -- No había entradas relevantes en `docs/solutions/` en este árbol de trabajo. - -### Referencias externas - -- No fue necesaria investigación externa para este plan. El repositorio ya contiene los - patrones relevantes de paquete del workspace y exportación del SDK. - -## Decisiones técnicas clave - -- Introducir `@openclaw/plugin-sdk` como un nuevo paquete del workspace mientras se mantiene activa la - superficie heredada raíz `openclaw/plugin-sdk/*` durante la migración. - Justificación: esto permite que un conjunto de extensiones de la primera ola pase a una resolución real de paquetes - sin forzar que todas las extensiones y todas las rutas de compilación raíz cambien - de una sola vez. - -- Usar una configuración base dedicada de límites opt-in, como - `extensions/tsconfig.package-boundary.base.json`, en lugar de reemplazar la - base existente de extensiones para todos. - Justificación: el repositorio necesita admitir simultáneamente tanto el modo heredado como el opt-in para extensiones - durante la migración. - -- Usar referencias de proyecto de TS desde las extensiones de la primera ola hacia - `packages/plugin-sdk/tsconfig.json` y establecer - `disableSourceOfProjectReferenceRedirect` para el modo opt-in de límites. - Justificación: esto da a `tsc` un grafo real de paquetes mientras desalienta al editor y - al compilador de recurrir al recorrido del código fuente sin procesar. - -- Mantener `@openclaw/plugin-sdk` como privado en la primera ola. - Justificación: el objetivo inmediato es la aplicación interna de límites y la seguridad de migración, - no publicar un segundo contrato externo del SDK antes de que la superficie sea - estable. - -- Mover solo las subrutas del SDK de la primera ola en el primer corte de implementación, y - mantener puentes de compatibilidad para el resto. - Justificación: mover físicamente los 315 archivos `src/plugin-sdk/*.ts` en un solo PR es - exactamente la superficie de conflicto de fusión que este plan intenta evitar. - -- No depender de `scripts/postinstall-bundled-plugins.mjs` para construir - declaraciones del SDK para la primera ola. - Justificación: los flujos explícitos de compilación/referencia son más fáciles de razonar y mantienen - el comportamiento del repositorio más predecible. - -## Preguntas abiertas - -### Resueltas durante la planificación - -- ¿Qué extensiones deben estar en la primera ola? - Usar las 10 extensiones de proveedor/búsqueda web enumeradas arriba porque están más - aisladas estructuralmente que los paquetes de canal más pesados. - -- ¿Debe el primer PR reemplazar todo el árbol de extensiones? - No. El primer PR debe admitir dos modos en paralelo e incorporar solo la - primera ola. - -- ¿Debe la primera ola requerir una compilación de declaraciones en postinstall? - No. El grafo de paquete/referencia debe ser explícito, y CI debe ejecutar - intencionalmente la verificación de tipos local al paquete correspondiente. - -### Aplazadas para la implementación - -- Si el paquete de la primera ola puede apuntar directamente a `src/*.ts` local al paquete - solo mediante referencias de proyecto, o si aún se requiere un pequeño paso de emisión de declaraciones - para el paquete `@openclaw/plugin-sdk`. - Esta es una cuestión de validación del grafo de TS propia de la implementación. - -- Si el paquete raíz `openclaw` debe redirigir inmediatamente las subrutas del SDK de la primera ola a - las salidas de `packages/plugin-sdk` o seguir usando shims de compatibilidad generados bajo `src/plugin-sdk`. - Este es un detalle de compatibilidad y forma de compilación que depende de la - ruta mínima de implementación que mantenga CI en verde. - -## Diseño técnico de alto nivel - -> Esto ilustra el enfoque previsto y sirve como guía direccional para la revisión, no como especificación de implementación. El agente encargado de implementar debe tratarlo como contexto, no como código para reproducir. - -```mermaid -flowchart TB - subgraph Legacy["Extensiones heredadas (sin cambios)"] - L1["extensions/*\nopenclaw/plugin-sdk/*"] - L2["root tsconfig paths"] - L1 --> L2 - L2 --> L3["src/plugin-sdk/*"] - end - - subgraph OptIn["Extensiones de la primera ola"] - O1["10 extensiones incorporadas"] - O2["extensions/tsconfig.package-boundary.base.json"] - O3["rootDir = '.'\nproject reference"] - O4["@openclaw/plugin-sdk"] - O1 --> O2 - O2 --> O3 - O3 --> O4 - end - - subgraph SDK["Nuevo paquete del workspace"] - P1["packages/plugin-sdk/package.json"] - P2["packages/plugin-sdk/tsconfig.json"] - P3["packages/plugin-sdk/src/.ts"] - P1 --> P2 - P2 --> P3 - end - - O4 --> SDK -``` - -## Unidades de implementación - -- [ ] **Unidad 1: Introducir el paquete real del workspace `@openclaw/plugin-sdk`** - -**Objetivo:** Crear un paquete real del workspace para el SDK que pueda ser propietario de la -superficie de subrutas de la primera ola sin forzar una migración en todo el repositorio. - -**Requisitos:** R1, R2, R3, R8, R9 - -**Dependencias:** Ninguna - -**Archivos:** - -- Crear: `packages/plugin-sdk/package.json` -- Crear: `packages/plugin-sdk/tsconfig.json` -- Crear: `packages/plugin-sdk/src/index.ts` -- Crear: `packages/plugin-sdk/src/*.ts` para las subrutas del SDK de la primera ola -- Modificar: `pnpm-workspace.yaml` solo si se necesitan ajustes en los globs de paquetes -- Modificar: `package.json` -- Modificar: `src/plugin-sdk/entrypoints.ts` -- Modificar: `scripts/lib/plugin-sdk-entrypoints.json` -- Probar: `src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts` - -**Enfoque:** - -- Agregar un nuevo paquete del workspace llamado `@openclaw/plugin-sdk`. -- Comenzar solo con las subrutas del SDK de la primera ola, no con todo el árbol de 315 archivos. -- Si mover directamente un entrypoint de la primera ola creara un diff demasiado grande, el - primer PR puede introducir primero esa subruta en `packages/plugin-sdk/src` como un wrapper - delgado del paquete y luego cambiar la fuente de verdad al paquete en un PR de seguimiento - para ese grupo de subrutas. -- Reutilizar la maquinaria existente de inventario de entrypoints para que la superficie del paquete de la primera ola - se declare en un único lugar canónico. -- Mantener activas las exportaciones del paquete raíz para los usuarios heredados mientras el paquete del workspace - se convierte en el nuevo contrato opt-in. - -**Patrones a seguir:** - -- `packages/memory-host-sdk/package.json` -- `packages/plugin-package-contract/package.json` -- `src/plugin-sdk/entrypoints.ts` - -**Escenarios de prueba:** - -- Caso satisfactorio: el paquete del workspace exporta cada subruta de la primera ola enumerada - en el plan y no falta ninguna exportación requerida de la primera ola. -- Caso límite: los metadatos de exportación del paquete permanecen estables cuando la lista de entradas de la primera ola - se vuelve a generar o se compara con el inventario canónico. -- Integración: las exportaciones heredadas del SDK en el paquete raíz siguen presentes tras introducir - el nuevo paquete del workspace. - -**Verificación:** - -- El repositorio contiene un paquete válido del workspace `@openclaw/plugin-sdk` con un - mapa estable de exportaciones de la primera ola y sin regresión de exportaciones heredadas en el - `package.json` raíz. - -- [ ] **Unidad 2: Agregar un modo opt-in de límites de TS para extensiones con aplicación por paquete** - -**Objetivo:** Definir el modo de configuración de TS que usarán las extensiones incorporadas, -mientras se deja sin cambios el comportamiento existente de TS para extensiones del resto. - -**Requisitos:** R4, R6, R7, R8, R9 - -**Dependencias:** Unidad 1 - -**Archivos:** - -- Crear: `extensions/tsconfig.package-boundary.base.json` -- Crear: `tsconfig.boundary-optin.json` -- Modificar: `extensions/xai/tsconfig.json` -- Modificar: `extensions/openai/tsconfig.json` -- Modificar: `extensions/anthropic/tsconfig.json` -- Modificar: `extensions/mistral/tsconfig.json` -- Modificar: `extensions/groq/tsconfig.json` -- Modificar: `extensions/together/tsconfig.json` -- Modificar: `extensions/perplexity/tsconfig.json` -- Modificar: `extensions/tavily/tsconfig.json` -- Modificar: `extensions/exa/tsconfig.json` -- Modificar: `extensions/firecrawl/tsconfig.json` -- Probar: `src/plugins/contracts/extension-package-project-boundaries.test.ts` -- Probar: `test/extension-package-tsc-boundary.test.ts` - -**Enfoque:** - -- Dejar `extensions/tsconfig.base.json` en su lugar para las extensiones heredadas. -- Agregar una nueva configuración base opt-in que: - - establezca `rootDir: "."` - - haga referencia a `packages/plugin-sdk` - - habilite `composite` - - deshabilite la redirección de fuente de referencia de proyecto cuando sea necesario -- Agregar una configuración de solución dedicada para el grafo de typecheck de la primera ola en lugar de - reformar el proyecto TS raíz del repositorio en el mismo PR. - -**Nota de ejecución:** comenzar con una comprobación canaria fallida de typecheck local al paquete para una -extensión incorporada antes de aplicar el patrón a las 10. - -**Patrones a seguir:** - -- Patrón existente de `tsconfig.json` local a extensiones del trabajo anterior - de límites -- Patrón de paquete del workspace de `packages/memory-host-sdk` - -**Escenarios de prueba:** - -- Caso satisfactorio: cada extensión incorporada supera correctamente el typecheck mediante la - configuración TS de límites de paquete. -- Ruta de error: una importación relativa canaria desde `../../src/cli/acp-cli.ts` falla - con `TS6059` para una extensión incorporada. -- Integración: las extensiones no incorporadas permanecen intactas y no necesitan - participar todavía en la nueva configuración de solución. - -**Verificación:** - -- Existe un grafo de typecheck dedicado para las 10 extensiones incorporadas, y las - malas importaciones relativas desde una de ellas fallan mediante `tsc` normal. - -- [ ] **Unidad 3: Migrar las extensiones de la primera ola a `@openclaw/plugin-sdk`** - -**Objetivo:** Cambiar las extensiones de la primera ola para que consuman el paquete real del SDK -mediante metadatos de dependencia, referencias de proyecto e importaciones por nombre de paquete. - -**Requisitos:** R5, R6, R7, R9 - -**Dependencias:** Unidad 2 - -**Archivos:** - -- Modificar: `extensions/anthropic/package.json` -- Modificar: `extensions/exa/package.json` -- Modificar: `extensions/firecrawl/package.json` -- Modificar: `extensions/groq/package.json` -- Modificar: `extensions/mistral/package.json` -- Modificar: `extensions/openai/package.json` -- Modificar: `extensions/perplexity/package.json` -- Modificar: `extensions/tavily/package.json` -- Modificar: `extensions/together/package.json` -- Modificar: `extensions/xai/package.json` -- Modificar: las importaciones de producción y prueba bajo cada una de las 10 raíces de extensión que - actualmente hacen referencia a `openclaw/plugin-sdk/*` - -**Enfoque:** - -- Agregar `@openclaw/plugin-sdk: workspace:*` a `devDependencies` de las extensiones - de la primera ola. -- Reemplazar las importaciones `openclaw/plugin-sdk/*` en esos paquetes por - `@openclaw/plugin-sdk/*`. -- Mantener las importaciones internas locales de la extensión en barriles locales como `./api.ts` y - `./runtime-api.ts`. -- No cambiar las extensiones no incorporadas en este PR. - -**Patrones a seguir:** - -- Barriles existentes de importación local de extensiones (`api.ts`, `runtime-api.ts`) -- Forma de dependencia de paquete usada por otros paquetes del workspace `@openclaw/*` - -**Escenarios de prueba:** - -- Caso satisfactorio: cada extensión migrada sigue registrándose/cargándose mediante sus pruebas - existentes del plugin después de la reescritura de importaciones. -- Caso límite: las importaciones del SDK solo para pruebas en el conjunto de extensiones incorporadas siguen resolviéndose - correctamente mediante el nuevo paquete. -- Integración: las extensiones migradas no requieren alias raíz `openclaw/plugin-sdk/*` - para el typechecking. - -**Verificación:** - -- Las extensiones de la primera ola compilan y se prueban contra `@openclaw/plugin-sdk` - sin necesitar la ruta heredada de alias del SDK en la raíz. - -- [ ] **Unidad 4: Preservar la compatibilidad heredada mientras la migración es parcial** - -**Objetivo:** Mantener el resto del repositorio funcionando mientras el SDK existe tanto en forma heredada -como en forma de nuevo paquete durante la migración. - -**Requisitos:** R4, R8, R9 - -**Dependencias:** Unidades 1-3 - -**Archivos:** - -- Modificar: `src/plugin-sdk/*.ts` para shims de compatibilidad de la primera ola según sea necesario -- Modificar: `package.json` -- Modificar: la infraestructura de compilación o exportación que ensambla los artefactos del SDK -- Probar: `src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts` -- Probar: `src/plugins/contracts/plugin-sdk-index.bundle.test.ts` - -**Enfoque:** - -- Mantener `openclaw/plugin-sdk/*` en la raíz como superficie de compatibilidad para las - extensiones heredadas y para consumidores externos que aún no se están moviendo. -- Usar ya sea shims generados o cableado de proxy de exportación raíz para las subrutas - de la primera ola que se hayan movido a `packages/plugin-sdk`. -- No intentar retirar la superficie del SDK en la raíz en esta fase. - -**Patrones a seguir:** - -- Generación existente de exportaciones del SDK raíz mediante `src/plugin-sdk/entrypoints.ts` -- Compatibilidad existente de exportación de paquetes en el `package.json` raíz - -**Escenarios de prueba:** - -- Caso satisfactorio: una importación heredada del SDK raíz sigue resolviéndose para una extensión - no incorporada después de que exista el nuevo paquete. -- Caso límite: una subruta de la primera ola funciona tanto mediante la superficie heredada raíz como - mediante la nueva superficie del paquete durante la ventana de migración. -- Integración: las pruebas de contrato del índice/bundle de plugin-sdk siguen viendo una - superficie pública coherente. - -**Verificación:** - -- El repositorio admite tanto modos heredados como modos opt-in de consumo del SDK sin - romper las extensiones no modificadas. - -- [ ] **Unidad 5: Agregar aplicación acotada y documentar el contrato de migración** - -**Objetivo:** Incorporar CI y una guía para contribuidores que apliquen el nuevo comportamiento para la -primera ola sin fingir que todo el árbol de extensiones ya está migrado. - -**Requisitos:** R5, R6, R8, R9 - -**Dependencias:** Unidades 1-4 - -**Archivos:** - -- Modificar: `package.json` -- Modificar: los archivos de workflow de CI que deben ejecutar el typecheck opt-in de límites -- Modificar: `AGENTS.md` -- Modificar: `docs/plugins/sdk-overview.md` -- Modificar: `docs/plugins/sdk-entrypoints.md` -- Modificar: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` - -**Enfoque:** - -- Agregar una compuerta explícita para la primera ola, como una ejecución dedicada de `tsc -b` para - `packages/plugin-sdk` más las 10 extensiones incorporadas. -- Documentar que el repositorio ahora admite tanto modos heredados como modos opt-in de extensiones, - y que el nuevo trabajo de límites de extensiones debe preferir la nueva ruta de paquete. -- Registrar la regla de migración de la siguiente ola para que PR posteriores puedan agregar más extensiones - sin volver a debatir la arquitectura. - -**Patrones a seguir:** - -- Pruebas de contrato existentes bajo `src/plugins/contracts/` -- Actualizaciones existentes de documentación que explican migraciones por etapas - -**Escenarios de prueba:** - -- Caso satisfactorio: la nueva compuerta de typecheck de la primera ola pasa para el paquete del workspace - y las extensiones incorporadas. -- Ruta de error: introducir una nueva importación relativa no permitida en una - extensión incorporada hace fallar la compuerta de typecheck acotada. -- Integración: CI aún no exige que las extensiones no incorporadas satisfagan el nuevo - modo de límites de paquete. - -**Verificación:** - -- La ruta de aplicación de la primera ola está documentada, probada y se puede ejecutar sin - obligar a migrar todo el árbol de extensiones. - -## Impacto en todo el sistema - -- **Grafo de interacción:** este trabajo toca la fuente de verdad del SDK, las - exportaciones del paquete raíz, los metadatos de paquetes de extensiones, el diseño del grafo de TS y la verificación en CI. -- **Propagación de errores:** el modo principal de fallo previsto pasa a ser errores de TS en tiempo de compilación - (`TS6059`) en extensiones incorporadas en lugar de fallos solo de scripts personalizados. -- **Riesgos del ciclo de vida del estado:** la migración de doble superficie introduce riesgo de divergencia entre - las exportaciones de compatibilidad raíz y el nuevo paquete del workspace. -- **Paridad de superficie de API:** las subrutas de la primera ola deben seguir siendo semánticamente idénticas - tanto a través de `openclaw/plugin-sdk/*` como de `@openclaw/plugin-sdk/*` durante la - transición. -- **Cobertura de integración:** las pruebas unitarias no son suficientes; se requieren typechecks - acotados del grafo de paquetes para demostrar el límite. -- **Invariantes sin cambios:** las extensiones no incorporadas mantienen su comportamiento actual - en el PR 1. Este plan no afirma una aplicación de límites de importación en todo el repositorio. - -## Riesgos y dependencias - -| Riesgo | Mitigación | -| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| El paquete de la primera ola sigue resolviéndose hacia código fuente sin procesar y `rootDir` en realidad no falla de forma cerrada | Hacer que el primer paso de implementación sea un canario de referencia de paquete sobre una extensión incorporada antes de ampliarlo al conjunto completo | -| Mover demasiado código fuente del SDK de una vez recrea el problema original de conflictos de fusión | Mover solo las subrutas de la primera ola en el primer PR y mantener puentes de compatibilidad en la raíz | -| Las superficies heredadas y nuevas del SDK divergen semánticamente | Mantener un único inventario de entrypoints, agregar pruebas de contrato de compatibilidad y hacer explícita la paridad de doble superficie | -| Las rutas de compilación/prueba del repositorio raíz empiezan accidentalmente a depender del nuevo paquete de formas no controladas | Usar una configuración de solución opt-in dedicada y mantener fuera del primer PR los cambios de topología TS para todo el repositorio | - -## Entrega por fases - -### Fase 1 - -- Introducir `@openclaw/plugin-sdk` -- Definir la superficie de subrutas de la primera ola -- Demostrar que una extensión incorporada puede fallar de forma cerrada mediante `rootDir` - -### Fase 2 - -- Incorporar las 10 extensiones de la primera ola -- Mantener activa la compatibilidad en la raíz para todos los demás - -### Fase 3 - -- Agregar más extensiones en PR posteriores -- Mover más subrutas del SDK al paquete del workspace -- Retirar la compatibilidad en la raíz solo después de que desaparezca el conjunto heredado de extensiones - -## Notas operativas / de documentación - -- El primer PR debe describirse explícitamente como una migración de modo dual, no como la - finalización de la aplicación en todo el repositorio. -- La guía de migración debe facilitar que PR posteriores agreguen más extensiones - siguiendo el mismo patrón de paquete/dependencia/referencia. - -## Fuentes y referencias - -- Plan previo: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` -- Configuración del workspace: `pnpm-workspace.yaml` -- Inventario existente de entrypoints del SDK: `src/plugin-sdk/entrypoints.ts` -- Exportaciones existentes del SDK raíz: `package.json` -- Patrones existentes de paquetes del workspace: - - `packages/memory-host-sdk/package.json` - - `packages/plugin-package-contract/package.json` diff --git a/docs/es/plugins/architecture.md b/docs/es/plugins/architecture.md index a41371d44..17af6c511 100644 --- a/docs/es/plugins/architecture.md +++ b/docs/es/plugins/architecture.md @@ -1,52 +1,52 @@ --- read_when: - - Crear o depurar plugins nativos de OpenClaw - - Entender el modelo de capacidades de los plugins o los límites de propiedad - - Trabajar en la canalización de carga o el registro de plugins - - Implementar hooks de runtime de proveedores o plugins de canal + - Estás creando o depurando plugins nativos de OpenClaw + - Quieres entender el modelo de capacidades de plugins o los límites de propiedad + - Estás trabajando en la canalización de carga o el registro de plugins + - Estás implementando hooks de runtime de proveedores o plugins de canal sidebarTitle: Internals -summary: 'Aspectos internos de los plugins: modelo de capacidades, propiedad, contratos, canalización de carga y helpers de runtime' -title: Aspectos internos de los plugins +summary: 'Aspectos internos de plugins: modelo de capacidades, propiedad, contratos, canalización de carga y utilidades de runtime' +title: Aspectos internos de plugins x-i18n: - generated_at: "2026-04-08T02:20:35Z" + generated_at: "2026-04-09T01:31:56Z" model: gpt-5.4 provider: openai - source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 + source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 source_path: plugins/architecture.md workflow: 15 --- -# Aspectos internos de los plugins +# Aspectos internos de plugins - Esta es la **referencia de arquitectura detallada**. Para guías prácticas, consulta: - - [Install and use plugins](/es/tools/plugin) — guía del usuario - - [Getting Started](/es/plugins/building-plugins) — primer tutorial de plugins - - [Channel Plugins](/es/plugins/sdk-channel-plugins) — crea un canal de mensajería - - [Provider Plugins](/es/plugins/sdk-provider-plugins) — crea un proveedor de modelos - - [SDK Overview](/es/plugins/sdk-overview) — mapa de importaciones y API de registro + Esta es la **referencia de arquitectura profunda**. Para guías prácticas, consulta: + - [Instalar y usar plugins](/es/tools/plugin) — guía del usuario + - [Primeros pasos](/es/plugins/building-plugins) — primer tutorial de plugins + - [Plugins de canal](/es/plugins/sdk-channel-plugins) — crea un canal de mensajería + - [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — crea un proveedor de modelos + - [Descripción general del SDK](/es/plugins/sdk-overview) — mapa de importación y API de registro Esta página cubre la arquitectura interna del sistema de plugins de OpenClaw. ## Modelo público de capacidades -Las capacidades son el modelo público de **plugin nativo** dentro de OpenClaw. Cada +Las capacidades son el modelo público de **plugins nativos** dentro de OpenClaw. Cada plugin nativo de OpenClaw se registra en uno o más tipos de capacidad: -| Capability | Registration method | Example plugins | -| ---------------------- | ------------------------------------------------ | ------------------------------------ | -| Inferencia de texto | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend de inferencia CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Voz | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Transcripción en tiempo real | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Voz en tiempo real | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Comprensión multimedia | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Generación de imágenes | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Generación de música | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Generación de video | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Recuperación web | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Búsqueda web | `api.registerWebSearchProvider(...)` | `google` | +| Capacidad | Método de registro | Plugins de ejemplo | +| --------------------- | ------------------------------------------------ | ------------------------------------ | +| Inferencia de texto | `api.registerProvider(...)` | `openai`, `anthropic` | +| Backend de inferencia de CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Voz | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Transcripción en tiempo real | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Voz en tiempo real | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Comprensión de medios | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Generación de imágenes | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Generación de música | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Generación de video | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Recuperación web | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Búsqueda web | `api.registerWebSearchProvider(...)` | `google` | | Canal / mensajería | `api.registerChannel(...)` | `msteams`, `matrix` | Un plugin que registra cero capacidades pero proporciona hooks, herramientas o @@ -54,36 +54,36 @@ servicios es un plugin **heredado solo de hooks**. Ese patrón sigue siendo tota ### Postura de compatibilidad externa -El modelo de capacidades ya está implementado en el núcleo y hoy lo usan los plugins -incluidos/nativos, pero la compatibilidad de plugins externos aún necesita una barra más alta que “está -exportado, por lo tanto está congelado”. +El modelo de capacidades ya está implementado en el núcleo y lo usan hoy los plugins +nativos/integrados, pero la compatibilidad de plugins externos todavía necesita un criterio +más estricto que "está exportado, por lo tanto está congelado". Guía actual: - **plugins externos existentes:** mantén funcionando las integraciones basadas en hooks; trátalo - como la base de compatibilidad -- **nuevos plugins incluidos/nativos:** prefiere el registro explícito de capacidades en lugar de + como la línea base de compatibilidad +- **nuevos plugins nativos/integrados:** prefiere el registro explícito de capacidades en lugar de accesos específicos de proveedor o nuevos diseños solo con hooks -- **plugins externos que adopten el registro de capacidades:** permitido, pero trata las - superficies helper específicas de capacidades como evolutivas salvo que la documentación marque explícitamente un contrato como estable +- **plugins externos que adopten registro de capacidades:** permitido, pero trata las superficies de utilidades + específicas de capacidad como evolutivas, a menos que la documentación marque explícitamente un contrato como estable Regla práctica: - las API de registro de capacidades son la dirección prevista -- los hooks heredados siguen siendo la ruta más segura para evitar rupturas en plugins externos durante +- los hooks heredados siguen siendo la vía más segura y sin rupturas para plugins externos durante la transición -- no todas las subrutas helper exportadas son iguales; prefiere el contrato documentado y limitado, - no exportaciones helper incidentales +- no todas las subrutas de utilidades exportadas son iguales; prefiere el contrato estrecho documentado, + no las exportaciones auxiliares incidentales -### Formas de plugins +### Formas de plugin -OpenClaw clasifica cada plugin cargado en una forma según su comportamiento real -de registro (no solo según los metadatos estáticos): +OpenClaw clasifica cada plugin cargado según su comportamiento real de registro +(no solo por metadatos estáticos): - **plain-capability** -- registra exactamente un tipo de capacidad (por ejemplo, un plugin solo de proveedor como `mistral`) -- **hybrid-capability** -- registra varios tipos de capacidad (por ejemplo, - `openai` posee inferencia de texto, voz, comprensión multimedia y generación +- **hybrid-capability** -- registra múltiples tipos de capacidad (por ejemplo, + `openai` posee inferencia de texto, voz, comprensión de medios y generación de imágenes) - **hook-only** -- registra solo hooks (tipados o personalizados), sin capacidades, herramientas, comandos ni servicios @@ -91,95 +91,95 @@ de registro (no solo según los metadatos estáticos): capacidades Usa `openclaw plugins inspect ` para ver la forma de un plugin y el desglose -de capacidades. Consulta [CLI reference](/cli/plugins#inspect) para más detalles. +de capacidades. Consulta la [referencia de CLI](/cli/plugins#inspect) para más detalles. ### Hooks heredados El hook `before_agent_start` sigue siendo compatible como vía de compatibilidad para -plugins solo de hooks. Los plugins heredados reales siguen dependiendo de él. +plugins solo con hooks. Los plugins heredados del mundo real aún dependen de él. Dirección: - mantenerlo funcionando - documentarlo como heredado -- preferir `before_model_resolve` para el trabajo de sobrescritura de modelo/proveedor -- preferir `before_prompt_build` para la mutación de prompts -- eliminarlo solo cuando baje el uso real y la cobertura de fixtures demuestre la seguridad de la migración +- preferir `before_model_resolve` para trabajo de anulación de modelo/proveedor +- preferir `before_prompt_build` para trabajo de mutación de prompts +- eliminarlo solo cuando baje el uso real y la cobertura de fixtures demuestre seguridad de migración ### Señales de compatibilidad -Cuando ejecutes `openclaw doctor` o `openclaw plugins inspect `, puedes ver +Cuando ejecutas `openclaw doctor` o `openclaw plugins inspect `, puedes ver una de estas etiquetas: -| Signal | Meaning | +| Señal | Significado | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | La configuración se analiza correctamente y los plugins se resuelven | -| **compatibility advisory** | El plugin usa un patrón compatible pero antiguo (por ejemplo, `hook-only`) | +| **config valid** | La configuración se analiza correctamente y los plugins se resuelven | +| **compatibility advisory** | El plugin usa un patrón compatible pero antiguo (p. ej., `hook-only`) | | **legacy warning** | El plugin usa `before_agent_start`, que está obsoleto | -| **hard error** | La configuración no es válida o el plugin no se pudo cargar | +| **hard error** | La configuración es inválida o el plugin no se pudo cargar | Ni `hook-only` ni `before_agent_start` romperán tu plugin hoy -- -`hook-only` es informativo, y `before_agent_start` solo activa una advertencia. Estas +`hook-only` es solo informativo, y `before_agent_start` solo genera una advertencia. Estas señales también aparecen en `openclaw status --all` y `openclaw plugins doctor`. -## Resumen de arquitectura +## Descripción general de la arquitectura El sistema de plugins de OpenClaw tiene cuatro capas: -1. **Manifest + discovery** - OpenClaw encuentra plugins candidatos a partir de rutas configuradas, raíces del espacio de trabajo, - raíces globales de extensiones y extensiones incluidas. El descubrimiento lee primero - los manifests nativos `openclaw.plugin.json` y los manifests de paquetes compatibles. -2. **Enablement + validation** +1. **Manifiesto + descubrimiento** + OpenClaw encuentra plugins candidatos desde rutas configuradas, raíces de workspace, + raíces globales de extensiones y extensiones integradas. El descubrimiento primero lee + manifiestos nativos `openclaw.plugin.json` y luego manifiestos de paquetes compatibles. +2. **Habilitación + validación** El núcleo decide si un plugin descubierto está habilitado, deshabilitado, bloqueado o - seleccionado para una ranura exclusiva como memoria. -3. **Runtime loading** - Los plugins nativos de OpenClaw se cargan dentro del proceso mediante jiti y registran + seleccionado para una ranura exclusiva, como memoria. +3. **Carga en runtime** + Los plugins nativos de OpenClaw se cargan en proceso mediante jiti y registran capacidades en un registro central. Los paquetes compatibles se normalizan en - registros del registro sin importar código de runtime. -4. **Surface consumption** + registros del sistema sin importar código de runtime. +4. **Consumo de superficie** El resto de OpenClaw lee el registro para exponer herramientas, canales, configuración - de proveedores, hooks, rutas HTTP, comandos CLI y servicios. + de proveedores, hooks, rutas HTTP, comandos de CLI y servicios. -En el caso específico del CLI de plugins, el descubrimiento de comandos raíz se divide en dos fases: +Para la CLI de plugins específicamente, el descubrimiento del comando raíz se divide en dos fases: -- los metadatos en tiempo de análisis provienen de `registerCli(..., { descriptors: [...] })` -- el módulo CLI real del plugin puede seguir siendo perezoso y registrarse en la primera invocación +- los metadatos en tiempo de análisis vienen de `registerCli(..., { descriptors: [...] })` +- el módulo real de CLI del plugin puede seguir siendo perezoso y registrarse en la primera invocación -Eso mantiene el código del CLI propiedad del plugin dentro del propio plugin y aun así permite que OpenClaw -reserve nombres de comandos raíz antes del análisis. +Eso mantiene el código de CLI propiedad del plugin dentro del plugin, al tiempo que permite a OpenClaw +reservar nombres de comandos raíz antes del análisis. El límite de diseño importante: -- el descubrimiento y la validación de configuración deben funcionar a partir de **metadatos de manifest/esquema** +- el descubrimiento + la validación de configuración deben funcionar a partir de **metadatos de manifiesto/esquema** sin ejecutar código del plugin -- el comportamiento nativo de runtime proviene de la ruta `register(api)` del módulo del plugin +- el comportamiento nativo en runtime proviene de la ruta `register(api)` del módulo del plugin -Esa separación permite a OpenClaw validar configuración, explicar plugins faltantes/deshabilitados y -crear pistas para la UI/esquema antes de que el runtime completo esté activo. +Esa separación permite a OpenClaw validar la configuración, explicar plugins ausentes/deshabilitados, y +crear sugerencias de IU/esquema antes de que el runtime completo esté activo. ### Plugins de canal y la herramienta compartida de mensajes -Los plugins de canal no necesitan registrar una herramienta independiente para enviar/editar/reaccionar en +Los plugins de canal no necesitan registrar una herramienta separada de enviar/editar/reaccionar para acciones normales de chat. OpenClaw mantiene una única herramienta compartida `message` en el núcleo, y los plugins de canal poseen el descubrimiento y la ejecución específicos del canal detrás de ella. El límite actual es: -- el núcleo posee el host de la herramienta compartida `message`, la integración con prompts, la +- el núcleo posee el host compartido de la herramienta `message`, el cableado del prompt, la contabilidad de sesión/hilo y el despacho de ejecución - los plugins de canal poseen el descubrimiento de acciones con alcance, el descubrimiento de capacidades y cualquier fragmento de esquema específico del canal - los plugins de canal poseen la gramática de conversación de sesión específica del proveedor, como - cómo los ids de conversación codifican ids de hilo o heredan de conversaciones padre + cómo los id de conversación codifican los id de hilo o se heredan de conversaciones principales - los plugins de canal ejecutan la acción final a través de su adaptador de acciones -Para los plugins de canal, la superficie del SDK es +Para plugins de canal, la superficie del SDK es `ChannelMessageActionAdapter.describeMessageTool(...)`. Esa llamada unificada de descubrimiento -permite que un plugin devuelva sus acciones visibles, capacidades y contribuciones de esquema -juntas para que esas piezas no se desincronicen. +permite que un plugin devuelva juntas sus acciones visibles, capacidades y contribuciones de esquema +para que esas piezas no se desalineen. -El núcleo pasa el alcance de runtime a ese paso de descubrimiento. Los campos importantes incluyen: +El núcleo pasa el alcance de runtime a ese paso de descubrimiento. Entre los campos importantes están: - `accountId` - `currentChannelId` @@ -190,40 +190,41 @@ El núcleo pasa el alcance de runtime a ese paso de descubrimiento. Los campos i - `agentId` - `requesterSenderId` entrante de confianza -Eso importa para los plugins sensibles al contexto. Un canal puede ocultar o exponer -acciones de mensajes según la cuenta activa, la sala/hilo/mensaje actual o la identidad -confiable del solicitante, sin codificar ramas específicas del canal en la herramienta -`message` del núcleo. +Esto importa para plugins sensibles al contexto. Un canal puede ocultar o exponer +acciones de mensajes según la cuenta activa, la sala/hilo/mensaje actual, o +la identidad confiable del solicitante, sin codificar ramas específicas del canal en la +herramienta central `message`. -Por eso los cambios de enrutamiento del ejecutor incrustado siguen siendo trabajo del plugin: el ejecutor -es responsable de reenviar la identidad actual del chat/sesión al límite de descubrimiento del plugin -para que la herramienta compartida `message` exponga la superficie propiedad del canal correcta para el turno actual. +Por eso los cambios de enrutamiento del embedded-runner siguen siendo trabajo del plugin: el runner es +responsable de reenviar la identidad actual de chat/sesión al límite de descubrimiento del plugin +para que la herramienta compartida `message` exponga la superficie correcta propiedad del canal +para el turno actual. -Para los helpers de ejecución propiedad del canal, los plugins incluidos deben mantener el runtime de ejecución -dentro de sus propios módulos de extensión. El núcleo ya no posee los runtimes de acciones de mensajes -de Discord, Slack, Telegram o WhatsApp en `src/agents/tools`. -No publicamos subrutas `plugin-sdk/*-action-runtime` separadas, y los plugins incluidos +Para utilidades de ejecución propiedad del canal, los plugins integrados deben mantener el runtime +de ejecución dentro de sus propios módulos de extensión. El núcleo ya no posee los +runtimes de acción de mensajes de Discord, Slack, Telegram o WhatsApp en `src/agents/tools`. +No publicamos subrutas separadas `plugin-sdk/*-action-runtime`, y los plugins integrados deben importar directamente su propio código de runtime local desde sus -módulos propiedad de la extensión. +módulos propios de extensión. -El mismo límite se aplica a las uniones del SDK con nombre de proveedor en general: el núcleo -no debe importar barriles de conveniencia específicos de canal para Slack, Discord, Signal, +El mismo límite se aplica a las uniones del SDK con nombre de proveedor en general: el núcleo no +debe importar barriles de conveniencia específicos de canal para Slack, Discord, Signal, WhatsApp o extensiones similares. Si el núcleo necesita un comportamiento, debe -consumir el barril propio `api.ts` / `runtime-api.ts` del plugin incluido o promover la necesidad -a una capacidad genérica y estrecha en el SDK compartido. +consumir el propio barril `api.ts` / `runtime-api.ts` del plugin integrado o elevar la necesidad +a una capacidad genérica estrecha en el SDK compartido. -En el caso específico de las encuestas, hay dos rutas de ejecución: +Para encuestas específicamente, hay dos rutas de ejecución: -- `outbound.sendPoll` es la base compartida para canales que encajan en el modelo - común de encuestas -- `actions.handleAction("poll")` es la ruta preferida para semánticas de encuestas específicas del canal - o parámetros adicionales de encuestas +- `outbound.sendPoll` es la base compartida para canales que se ajustan al modelo común + de encuestas +- `actions.handleAction("poll")` es la ruta preferida para semánticas de encuestas + específicas del canal o parámetros adicionales de encuesta El núcleo ahora difiere el análisis compartido de encuestas hasta después de que el despacho de encuestas del plugin -rechace la acción, para que los controladores de encuestas propiedad del plugin puedan aceptar -campos específicos del canal sin quedar bloqueados primero por el analizador genérico de encuestas. +rechaza la acción, para que los manejadores de encuestas propiedad del plugin puedan aceptar campos +de encuesta específicos del canal sin quedar bloqueados primero por el analizador genérico de encuestas. -Consulta [Load pipeline](#load-pipeline) para la secuencia completa de inicio. +Consulta [Canalización de carga](#load-pipeline) para ver la secuencia completa de inicio. ## Modelo de propiedad de capacidades @@ -232,32 +233,30 @@ OpenClaw trata un plugin nativo como el límite de propiedad de una **empresa** Eso significa: -- un plugin de empresa normalmente debe poseer todas las superficies de OpenClaw orientadas a esa empresa +- un plugin de empresa normalmente debe poseer todas las superficies de OpenClaw de esa empresa - un plugin de función normalmente debe poseer toda la superficie de la función que introduce - los canales deben consumir capacidades compartidas del núcleo en lugar de reimplementar comportamiento de proveedores de forma ad hoc Ejemplos: -- el plugin incluido `openai` posee el comportamiento de proveedor de modelos de OpenAI y el comportamiento de OpenAI - en voz + voz en tiempo real + comprensión multimedia + generación de imágenes -- el plugin incluido `elevenlabs` posee el comportamiento de voz de ElevenLabs -- el plugin incluido `microsoft` posee el comportamiento de voz de Microsoft -- el plugin incluido `google` posee el comportamiento de proveedor de modelos de Google además de Google - en comprensión multimedia + generación de imágenes + búsqueda web -- el plugin incluido `firecrawl` posee el comportamiento de recuperación web de Firecrawl -- los plugins incluidos `minimax`, `mistral`, `moonshot` y `zai` poseen sus - backends de comprensión multimedia -- el plugin incluido `qwen` posee el comportamiento de proveedor de texto de Qwen más - comprensión multimedia y generación de video +- el plugin integrado `openai` posee el comportamiento de proveedor de modelos de OpenAI y el comportamiento + de OpenAI para voz + voz en tiempo real + comprensión de medios + generación de imágenes +- el plugin integrado `elevenlabs` posee el comportamiento de voz de ElevenLabs +- el plugin integrado `microsoft` posee el comportamiento de voz de Microsoft +- el plugin integrado `google` posee el comportamiento de proveedor de modelos de Google más + comportamiento de Google para comprensión de medios + generación de imágenes + búsqueda web +- el plugin integrado `firecrawl` posee el comportamiento de recuperación web de Firecrawl +- los plugins integrados `minimax`, `mistral`, `moonshot` y `zai` poseen sus + backends de comprensión de medios - el plugin `voice-call` es un plugin de función: posee transporte de llamadas, herramientas, - CLI, rutas y puente de flujo multimedia de Twilio, pero consume voz compartida - más capacidades de transcripción en tiempo real y voz en tiempo real en lugar de - importar directamente plugins de proveedores + CLI, rutas y el puente de flujos de medios de Twilio, pero consume capacidades compartidas de voz + más transcripción en tiempo real y voz en tiempo real en lugar de + importar plugins de proveedor directamente -El estado final deseado es: +El estado final previsto es: -- OpenAI vive en un único plugin aunque abarque modelos de texto, voz, imágenes y +- OpenAI vive en un solo plugin incluso si abarca modelos de texto, voz, imágenes y video futuro - otro proveedor puede hacer lo mismo para su propia superficie - a los canales no les importa qué plugin de proveedor posee el proveedor; consumen el @@ -268,44 +267,44 @@ Esta es la distinción clave: - **plugin** = límite de propiedad - **capacidad** = contrato del núcleo que varios plugins pueden implementar o consumir -Así, si OpenClaw agrega un nuevo dominio como video, la primera pregunta no es -“¿qué proveedor debe codificar el manejo de video?”. La primera pregunta es “¿cuál es -el contrato central de capacidad de video?”. Una vez que ese contrato exista, los plugins de proveedores -pueden registrarse contra él y los plugins de canal/función pueden consumirlo. +Así que si OpenClaw agrega un nuevo dominio como video, la primera pregunta no es +"¿qué proveedor debe codificar de forma rígida el manejo de video?" La primera pregunta es "¿cuál es +el contrato de capacidad central de video?" Una vez que ese contrato existe, los plugins de proveedor +pueden registrarse en él y los plugins de canal/función pueden consumirlo. -Si la capacidad todavía no existe, el movimiento correcto normalmente es: +Si la capacidad aún no existe, el movimiento correcto suele ser: 1. definir la capacidad faltante en el núcleo 2. exponerla a través de la API/runtime del plugin de forma tipada 3. conectar canales/funciones a esa capacidad -4. dejar que los plugins de proveedores registren implementaciones +4. dejar que los plugins de proveedor registren implementaciones -Esto mantiene la propiedad explícita y evita al mismo tiempo un comportamiento del núcleo que dependa -de un único proveedor o de una ruta de código específica para un plugin puntual. +Esto mantiene la propiedad explícita y evita al mismo tiempo un comportamiento central que depende de un +solo proveedor o de una ruta de código específica para un único plugin. -### Estratificación de capacidades +### Capas de capacidades Usa este modelo mental al decidir dónde debe ir el código: -- **capa de capacidad del núcleo**: orquestación compartida, política, fallback, configuración - reglas de fusión, semántica de entrega y contratos tipados -- **capa de plugin de proveedor**: API específicas del proveedor, autenticación, catálogos de modelos, - síntesis de voz, generación de imágenes, futuros backends de video, endpoints de uso -- **capa de plugin de canal/función**: integración de Slack/Discord/voice-call/etc. - que consume capacidades del núcleo y las presenta en una superficie +- **capa central de capacidad**: orquestación compartida, políticas, fallback, reglas de + fusión de configuración, semántica de entrega y contratos tipados +- **capa de plugin de proveedor**: API específicas del proveedor, autenticación, catálogos de modelos, síntesis + de voz, generación de imágenes, futuros backends de video, endpoints de uso +- **capa de plugin de canal/función**: integración con Slack/Discord/voice-call/etc. + que consume capacidades centrales y las presenta en una superficie Por ejemplo, TTS sigue esta forma: -- el núcleo posee la política de TTS en tiempo de respuesta, el orden de fallback, las preferencias y la entrega por canal +- el núcleo posee la política TTS en tiempo de respuesta, el orden de fallback, las preferencias y la entrega por canal - `openai`, `elevenlabs` y `microsoft` poseen las implementaciones de síntesis -- `voice-call` consume el helper de runtime de TTS para telefonía +- `voice-call` consume la utilidad de runtime TTS de telefonía Ese mismo patrón debe preferirse para capacidades futuras. -### Ejemplo de plugin de empresa con varias capacidades +### Ejemplo de plugin de empresa con múltiples capacidades Un plugin de empresa debe sentirse cohesivo desde fuera. Si OpenClaw tiene contratos compartidos -para modelos, voz, transcripción en tiempo real, voz en tiempo real, comprensión multimedia, +para modelos, voz, transcripción en tiempo real, voz en tiempo real, comprensión de medios, generación de imágenes, generación de video, recuperación web y búsqueda web, un proveedor puede poseer todas sus superficies en un solo lugar: @@ -322,12 +321,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // hooks de autenticación/catálogo de modelos/runtime + // auth/model catalog/runtime hooks }); api.registerSpeechProvider({ id: "exampleai", - // configuración de voz del proveedor — implementa directamente la interfaz SpeechProviderPlugin + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -352,7 +351,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // lógica de credenciales + fetch + // credential + fetch logic }), ); }, @@ -361,65 +360,65 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Lo importante no son los nombres exactos de los helpers. Lo importante es la forma: +Lo importante no son los nombres exactos de las utilidades. Lo importante es la forma: -- un plugin posee la superficie del proveedor +- un solo plugin posee la superficie del proveedor - el núcleo sigue poseyendo los contratos de capacidad -- los canales y plugins de funciones consumen helpers `api.runtime.*`, no código del proveedor +- los canales y plugins de funciones consumen utilidades `api.runtime.*`, no código del proveedor - las pruebas de contrato pueden afirmar que el plugin registró las capacidades que - dice poseer + afirma poseer ### Ejemplo de capacidad: comprensión de video -OpenClaw ya trata la comprensión de imagen/audio/video como una única -capacidad compartida. Aquí se aplica el mismo modelo de propiedad: +OpenClaw ya trata la comprensión de imagen/audio/video como una sola +capacidad compartida. El mismo modelo de propiedad se aplica aquí: -1. el núcleo define el contrato de comprensión multimedia -2. los plugins de proveedores registran `describeImage`, `transcribeAudio` y +1. el núcleo define el contrato de comprensión de medios +2. los plugins de proveedor registran `describeImage`, `transcribeAudio` y `describeVideo` según corresponda -3. los plugins de canal y funciones consumen el comportamiento compartido del núcleo en lugar de - conectarse directamente a código del proveedor +3. los plugins de canal y de funciones consumen el comportamiento compartido del núcleo en lugar de + conectarse directamente al código del proveedor -Eso evita incorporar al núcleo las suposiciones de video de un único proveedor. El plugin posee +Eso evita incorporar al núcleo las suposiciones de video de un solo proveedor. El plugin posee la superficie del proveedor; el núcleo posee el contrato de capacidad y el comportamiento de fallback. -La generación de video ya usa esa misma secuencia: el núcleo posee el -contrato tipado de capacidad y el helper de runtime, y los plugins de proveedores registran -implementaciones `api.registerVideoGenerationProvider(...)` contra él. +La generación de video ya usa esa misma secuencia: el núcleo posee el contrato tipado +de capacidad y la utilidad de runtime, y los plugins de proveedor registran +implementaciones `api.registerVideoGenerationProvider(...)` en él. -¿Necesitas una lista concreta de despliegue? Consulta -[Capability Cookbook](/es/plugins/architecture). +¿Necesitas una lista concreta para el despliegue? Consulta el +[Recetario de capacidades](/es/plugins/architecture). -## Contratos y aplicación +## Contratos y cumplimiento -La superficie de la API de plugins es intencionalmente tipada y está centralizada en +La superficie de la API de plugins es intencionalmente tipada y centralizada en `OpenClawPluginApi`. Ese contrato define los puntos de registro compatibles y -los helpers de runtime de los que un plugin puede depender. +las utilidades de runtime en las que un plugin puede apoyarse. -Por qué esto importa: +Por qué importa: -- los autores de plugins obtienen un único estándar interno estable +- los autores de plugins obtienen un estándar interno estable - el núcleo puede rechazar propiedad duplicada, como dos plugins que registren el mismo id de proveedor -- el inicio puede mostrar diagnósticos accionables para registros mal formados -- las pruebas de contrato pueden aplicar la propiedad de plugins incluidos y evitar una deriva silenciosa +- el inicio puede mostrar diagnósticos accionables para registros malformados +- las pruebas de contrato pueden hacer cumplir la propiedad de plugins integrados y evitar desviaciones silenciosas -Hay dos capas de aplicación: +Hay dos capas de cumplimiento: -1. **aplicación del registro en runtime** +1. **cumplimiento de registro en runtime** El registro de plugins valida los registros a medida que se cargan los plugins. Ejemplos: ids de proveedor duplicados, ids de proveedor de voz duplicados y registros - mal formados producen diagnósticos del plugin en lugar de un comportamiento indefinido. + malformados producen diagnósticos de plugin en lugar de comportamiento indefinido. 2. **pruebas de contrato** - Los plugins incluidos se capturan en registros de contrato durante las ejecuciones de prueba para que - OpenClaw pueda afirmar explícitamente la propiedad. Hoy esto se usa para proveedores de modelos, - proveedores de voz, proveedores de búsqueda web y propiedad de registros incluidos. + Los plugins integrados se capturan en registros de contrato durante las ejecuciones de prueba para que + OpenClaw pueda afirmar explícitamente la propiedad. Hoy esto se usa para + proveedores de modelos, proveedores de voz, proveedores de búsqueda web y propiedad de registro integrada. -El efecto práctico es que OpenClaw sabe, por adelantado, qué plugin posee qué -superficie. Eso permite que el núcleo y los canales compongan sin fricciones porque la propiedad está -declarada, tipada y es comprobable en lugar de implícita. +El efecto práctico es que OpenClaw sabe, de antemano, qué plugin posee qué +superficie. Eso permite que el núcleo y los canales se compongan sin fricciones porque la propiedad está +declarada, tipada y es verificable en pruebas, en lugar de ser implícita. -### Qué pertenece a un contrato +### Qué debe pertenecer a un contrato Los buenos contratos de plugins son: @@ -427,15 +426,15 @@ Los buenos contratos de plugins son: - pequeños - específicos de capacidad - propiedad del núcleo -- reutilizables por varios plugins +- reutilizables por múltiples plugins - consumibles por canales/funciones sin conocimiento del proveedor Los malos contratos de plugins son: -- política específica del proveedor oculta en el núcleo +- políticas específicas del proveedor ocultas en el núcleo - vías de escape puntuales para plugins que eluden el registro - código de canal que accede directamente a una implementación de proveedor -- objetos de runtime ad hoc que no forman parte de `OpenClawPluginApi` o +- objetos de runtime ad hoc que no forman parte de `OpenClawPluginApi` ni de `api.runtime` En caso de duda, eleva el nivel de abstracción: define primero la capacidad y luego @@ -443,103 +442,103 @@ deja que los plugins se conecten a ella. ## Modelo de ejecución -Los plugins nativos de OpenClaw se ejecutan **dentro del proceso** con el Gateway. No están +Los plugins nativos de OpenClaw se ejecutan **en proceso** con el Gateway. No están aislados. Un plugin nativo cargado tiene el mismo límite de confianza a nivel de proceso que el código del núcleo. Implicaciones: - un plugin nativo puede registrar herramientas, manejadores de red, hooks y servicios -- un error en un plugin nativo puede hacer caer o desestabilizar el gateway +- un error en un plugin nativo puede bloquear o desestabilizar el gateway - un plugin nativo malicioso equivale a ejecución arbitraria de código dentro del proceso de OpenClaw -Los paquetes compatibles son más seguros por defecto porque OpenClaw actualmente los trata -como paquetes de metadatos/contenido. En las versiones actuales, eso significa sobre todo -Skills incluidos. +Los paquetes compatibles son más seguros de forma predeterminada porque OpenClaw actualmente los trata +como paquetes de metadatos/contenido. En las versiones actuales, eso significa principalmente +Skills integradas. -Usa listas permitidas y rutas explícitas de instalación/carga para plugins no incluidos. -Trata los plugins del espacio de trabajo como código de desarrollo, no como valores predeterminados de producción. +Usa listas de permitidos y rutas explícitas de instalación/carga para plugins no integrados. Trata +los plugins de workspace como código de desarrollo, no como valores predeterminados de producción. -Para los nombres de paquetes del espacio de trabajo incluidos, mantén el id del plugin anclado en el +Para nombres de paquetes de workspace integrados, mantén el id del plugin anclado en el nombre npm: `@openclaw/` de forma predeterminada, o un sufijo tipado aprobado como `-provider`, `-plugin`, `-speech`, `-sandbox` o `-media-understanding` cuando -el paquete exponga intencionalmente un rol de plugin más limitado. +el paquete expone intencionalmente un rol de plugin más estrecho. Nota importante de confianza: -- `plugins.allow` confía en **ids de plugin**, no en la procedencia de la fuente. -- Un plugin del espacio de trabajo con el mismo id que un plugin incluido - sombrea intencionalmente la copia incluida cuando ese plugin del espacio de trabajo está habilitado/en lista permitida. +- `plugins.allow` confía en **ids de plugin**, no en la procedencia del origen. +- Un plugin de workspace con el mismo id que un plugin integrado sombrea intencionalmente + la copia integrada cuando ese plugin de workspace está habilitado/en la lista de permitidos. - Esto es normal y útil para desarrollo local, pruebas de parches y hotfixes. ## Límite de exportación -OpenClaw exporta capacidades, no comodidades de implementación. +OpenClaw exporta capacidades, no conveniencias de implementación. -Mantén público el registro de capacidades. Recorta las exportaciones helper no contractuales: +Mantén público el registro de capacidades. Reduce las exportaciones de utilidades que no son contratos: -- subrutas específicas de plugins incluidos +- subrutas auxiliares específicas de plugins integrados - subrutas de infraestructura de runtime no destinadas a ser API pública -- helpers de conveniencia específicos del proveedor -- helpers de configuración/onboarding que son detalles de implementación +- utilidades de conveniencia específicas del proveedor +- utilidades de configuración/incorporación que son detalles de implementación -Algunas subrutas helper de plugins incluidos todavía permanecen en el mapa de exportación del SDK -generado por compatibilidad y mantenimiento de plugins incluidos. Algunos ejemplos actuales son +Algunas subrutas auxiliares de plugins integrados aún permanecen en el mapa generado de exportaciones del SDK +por compatibilidad y mantenimiento de plugins integrados. Ejemplos actuales incluyen `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` y varias uniones `plugin-sdk/matrix*`. Trátalas como -exportaciones reservadas de detalle de implementación, no como el patrón recomendado del SDK para +exportaciones reservadas de detalle de implementación, no como el patrón de SDK recomendado para nuevos plugins de terceros. ## Canalización de carga -En el inicio, OpenClaw hace aproximadamente esto: +Al inicio, OpenClaw hace aproximadamente esto: -1. descubrir raíces candidatas de plugins -2. leer manifests nativos o compatibles y metadatos de paquetes -3. rechazar candidatos inseguros -4. normalizar la configuración de plugins (`plugins.enabled`, `allow`, `deny`, `entries`, +1. descubre raíces candidatas de plugins +2. lee manifiestos nativos o de paquetes compatibles y metadatos de paquete +3. rechaza candidatos inseguros +4. normaliza la configuración del plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. decidir la habilitación para cada candidato -6. cargar módulos nativos habilitados mediante jiti -7. llamar a los hooks nativos `register(api)` (o `activate(api)` — un alias heredado) y recopilar registros en el registro de plugins -8. exponer el registro a comandos/superficies de runtime +5. decide la habilitación de cada candidato +6. carga módulos nativos habilitados mediante jiti +7. llama a los hooks nativos `register(api)` (o `activate(api)` — un alias heredado) y recopila registros en el registro de plugins +8. expone el registro a las superficies de comandos/runtime -`activate` es un alias heredado de `register`: el cargador resuelve el que esté presente (`def.register ?? def.activate`) y lo llama en el mismo punto. Todos los plugins incluidos usan `register`; prefiere `register` para los plugins nuevos. +`activate` es un alias heredado de `register` — el cargador resuelve el que esté presente (`def.register ?? def.activate`) y lo llama en el mismo punto. Todos los plugins integrados usan `register`; para plugins nuevos, prefiere `register`. -Las compuertas de seguridad ocurren **antes** de la ejecución del runtime. Los candidatos se bloquean -cuando la entrada escapa de la raíz del plugin, la ruta tiene permisos de escritura globales o la -propiedad de la ruta parece sospechosa en plugins no incluidos. +Las puertas de seguridad ocurren **antes** de la ejecución en runtime. Los candidatos se bloquean +cuando la entrada escapa de la raíz del plugin, la ruta tiene permiso de escritura global, o la +propiedad de la ruta parece sospechosa para plugins no integrados. -### Comportamiento manifest-first +### Comportamiento centrado en el manifiesto -El manifest es la fuente de verdad del plano de control. OpenClaw lo usa para: +El manifiesto es la fuente de verdad del plano de control. OpenClaw lo usa para: - identificar el plugin -- descubrir canales/Skills/esquema de configuración declarados o capacidades del paquete +- descubrir canales/habilidades/esquema de configuración declarados o capacidades del paquete - validar `plugins.entries..config` -- ampliar etiquetas/placeholders de Control UI +- ampliar etiquetas/placeholders de la IU de Control - mostrar metadatos de instalación/catálogo -Para los plugins nativos, el módulo de runtime es la parte del plano de datos. Registra -el comportamiento real, como hooks, herramientas, comandos o flujos de proveedores. +Para plugins nativos, el módulo de runtime es la parte del plano de datos. Registra +comportamiento real como hooks, herramientas, comandos o flujos de proveedor. -### Qué almacena en caché el cargador +### Lo que almacena en caché el cargador -OpenClaw mantiene cachés cortas dentro del proceso para: +OpenClaw mantiene cachés breves en proceso para: - resultados de descubrimiento -- datos del registro de manifests +- datos del registro de manifiestos - registros de plugins cargados -Estas cachés reducen el inicio brusco y la sobrecarga de comandos repetidos. Es seguro +Estas cachés reducen inicios intensivos y la sobrecarga de comandos repetidos. Es seguro pensar en ellas como cachés de rendimiento de corta duración, no como persistencia. Nota de rendimiento: -- Configura `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` o +- Establece `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` o `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` para desactivar estas cachés. - Ajusta las ventanas de caché con `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` y `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. @@ -551,32 +550,32 @@ registro central de plugins. El registro rastrea: -- registros de plugins (identidad, origen, procedencia, estado, diagnósticos) +- registros de plugin (identidad, origen, procedencia, estado, diagnósticos) - herramientas - hooks heredados y hooks tipados - canales - proveedores - manejadores RPC del gateway - rutas HTTP -- registradores CLI +- registradores de CLI - servicios en segundo plano - comandos propiedad del plugin -Las funciones del núcleo luego leen de ese registro en lugar de hablar directamente con los módulos -del plugin. Esto mantiene la carga en una sola dirección: +Las funciones del núcleo leen luego de ese registro en lugar de hablar directamente con +los módulos del plugin. Esto mantiene la carga en un solo sentido: -- módulo de plugin -> registro en el registro +- módulo del plugin -> registro en el registro - runtime del núcleo -> consumo del registro Esa separación importa para la mantenibilidad. Significa que la mayoría de las superficies del núcleo solo -necesitan un punto de integración: “leer el registro”, no “hacer casos especiales para cada módulo -de plugin”. +necesitan un punto de integración: "leer el registro", no "tratar cada módulo de plugin +como un caso especial". -## Callbacks de vinculación de conversaciones +## Callbacks de vinculación de conversación Los plugins que vinculan una conversación pueden reaccionar cuando se resuelve una aprobación. -Usa `api.onConversationBindingResolved(...)` para recibir un callback después de que una solicitud de vinculación sea aprobada o denegada: +Usa `api.onConversationBindingResolved(...)` para recibir un callback después de que una solicitud de vinculación es aprobada o denegada: ```ts export default { @@ -584,38 +583,39 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Ahora existe una vinculación para este plugin + conversación. + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // La solicitud fue denegada; limpia cualquier estado local pendiente. + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, }; ``` -Campos de la carga útil del callback: +Campos de la carga del callback: - `status`: `"approved"` o `"denied"` - `decision`: `"allow-once"`, `"allow-always"` o `"deny"` - `binding`: la vinculación resuelta para solicitudes aprobadas -- `request`: el resumen de la solicitud original, indicación de desvinculación, id del remitente y +- `request`: el resumen de la solicitud original, sugerencia de desvinculación, id del remitente y metadatos de conversación -Este callback es solo de notificación. No cambia quién puede vincular una -conversación y se ejecuta después de que finalice el manejo de aprobación del núcleo. +Este callback es solo de notificación. No cambia quién tiene permitido vincular una +conversación, y se ejecuta después de que termina el manejo de aprobación del núcleo. -## Hooks de runtime del proveedor +## Hooks de runtime de proveedores -Los plugins de proveedores ahora tienen dos capas: +Los plugins de proveedor ahora tienen dos capas: -- metadatos del manifest: `providerAuthEnvVars` para una búsqueda económica de autenticación de proveedor basada en variables de entorno - antes de cargar el runtime, `channelEnvVars` para una búsqueda económica de canal/env/configuración - antes de cargar el runtime, además de `providerAuthChoices` para etiquetas económicas - de onboarding/elección de autenticación y metadatos de banderas CLI antes de cargar el runtime -- hooks en tiempo de configuración: `catalog` / heredado `discovery` más `applyConfigDefaults` +- metadatos del manifiesto: `providerAuthEnvVars` para búsqueda barata de autenticación de proveedor por entorno + antes de la carga del runtime, `providerAuthAliases` para variantes de proveedor que comparten + autenticación, `channelEnvVars` para búsqueda barata de entorno/configuración del canal antes de la carga del runtime, + además de `providerAuthChoices` para etiquetas baratas de incorporación/elección de autenticación y + metadatos de banderas de CLI antes de la carga del runtime +- hooks en tiempo de configuración: `catalog` / `discovery` heredado más `applyConfigDefaults` - hooks de runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -636,86 +636,88 @@ Los plugins de proveedores ahora tienen dos capas: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw sigue poseyendo el bucle genérico del agente, el failover, el manejo de transcripciones y la -política de herramientas. Estos hooks son la superficie de extensión para el comportamiento específico del proveedor sin -necesitar un transporte de inferencia totalmente personalizado. +OpenClaw sigue poseyendo el ciclo genérico del agente, el failover, el manejo de transcripciones y la +política de herramientas. Estos hooks son la superficie de extensión para comportamiento específico del proveedor sin +necesitar un transporte de inferencia personalizado completo. -Usa el manifest `providerAuthEnvVars` cuando el proveedor tenga credenciales basadas en variables de entorno +Usa el `providerAuthEnvVars` del manifiesto cuando el proveedor tenga credenciales basadas en entorno que las rutas genéricas de autenticación/estado/selector de modelos deban ver sin cargar el runtime del plugin. -Usa el manifest `providerAuthChoices` cuando las superficies CLI de onboarding/elección de autenticación -deban conocer el id de elección del proveedor, las etiquetas de grupo y la integración simple -de autenticación con una sola bandera sin cargar el runtime del proveedor. Mantén `envVars` en el runtime del proveedor -para pistas orientadas al operador, como etiquetas de onboarding o variables de -configuración de client-id/client-secret de OAuth. +Usa `providerAuthAliases` del manifiesto cuando un id de proveedor deba reutilizar +las variables de entorno, perfiles de autenticación, autenticación basada en configuración y opción de incorporación +con API key de otro id de proveedor. Usa `providerAuthChoices` del manifiesto cuando las +superficies de CLI de incorporación/elección de autenticación deban conocer el id de opción del proveedor, las +etiquetas de grupo y el cableado simple de autenticación con una sola bandera sin cargar el runtime del proveedor. +Mantén `envVars` del runtime del proveedor para sugerencias orientadas al operador, como etiquetas +de incorporación o variables de configuración de client-id/client-secret de OAuth. -Usa el manifest `channelEnvVars` cuando un canal tenga autenticación o configuración impulsadas por entorno que -las rutas genéricas de fallback de shell-env, comprobaciones de config/estado o prompts de configuración deban ver -sin cargar el runtime del canal. +Usa `channelEnvVars` del manifiesto cuando un canal tenga autenticación o configuración impulsada por entorno +que la recuperación genérica desde el entorno del shell, las comprobaciones de configuración/estado o los prompts de configuración +deban ver sin cargar el runtime del canal. -### Orden de hooks y uso +### Orden y uso de hooks -Para plugins de modelos/proveedores, OpenClaw llama a los hooks en este orden aproximado. -La columna “When to use” es la guía rápida de decisión. +Para plugins de modelo/proveedor, OpenClaw llama a los hooks en este orden aproximado. +La columna "Cuándo usarlo" es la guía rápida de decisión. -| # | Hook | What it does | When to use | +| # | Hook | Qué hace | Cuándo usarlo | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Publica la configuración del proveedor en `models.providers` durante la generación de `models.json` | El proveedor posee un catálogo o valores predeterminados de URL base | -| 2 | `applyConfigDefaults` | Aplica valores predeterminados globales del proveedor durante la materialización de configuración | Los valores predeterminados dependen del modo de autenticación, del entorno o de la semántica de la familia de modelos del proveedor | -| -- | _(built-in model lookup)_ | OpenClaw prueba primero la ruta normal de registro/catálogo | _(no es un hook de plugin)_ | -| 3 | `normalizeModelId` | Normaliza alias heredados o de vista previa de ids de modelo antes de la búsqueda | El proveedor posee la limpieza de alias antes de la resolución canónica del modelo | -| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` de una familia de proveedores antes del ensamblado genérico del modelo | El proveedor posee la limpieza de transporte para ids de proveedor personalizados en la misma familia de transporte | -| 5 | `normalizeConfig` | Normaliza `models.providers.` antes de la resolución de runtime/proveedor | El proveedor necesita limpieza de configuración que debe vivir con el plugin; los helpers incluidos de la familia Google también respaldan entradas de configuración compatibles | -| 6 | `applyNativeStreamingUsageCompat` | Aplica reescrituras de compatibilidad de uso de streaming nativo a proveedores de configuración | El proveedor necesita correcciones de metadatos de uso de streaming nativo impulsadas por el endpoint | -| 7 | `resolveConfigApiKey` | Resuelve autenticación de marcador de entorno para proveedores de configuración antes de cargar la autenticación del runtime | El proveedor tiene resolución de API key por marcador de entorno propiedad del proveedor; `amazon-bedrock` también tiene aquí un resolvedor incorporado de marcadores de entorno de AWS | -| 8 | `resolveSyntheticAuth` | Expone autenticación local/alojada por uno mismo o respaldada por configuración sin persistir texto plano | El proveedor puede operar con un marcador de credencial sintética/local | -| 9 | `resolveExternalAuthProfiles` | Superpone perfiles de autenticación externa propiedad del proveedor; `persistence` predeterminado es `runtime-only` para credenciales propiedad de CLI/app | El proveedor reutiliza credenciales de autenticación externa sin persistir tokens de actualización copiados | -| 10 | `shouldDeferSyntheticProfileAuth` | Rebaja placeholders de perfiles sintéticos almacenados detrás de autenticación respaldada por env/config | El proveedor almacena perfiles placeholder sintéticos que no deberían ganar precedencia | -| 11 | `resolveDynamicModel` | Fallback síncrono para ids de modelo propiedad del proveedor que aún no están en el registro local | El proveedor acepta ids de modelo arbitrarios del upstream | -| 12 | `prepareDynamicModel` | Calentamiento asíncrono, luego `resolveDynamicModel` se ejecuta otra vez | El proveedor necesita metadatos de red antes de resolver ids desconocidos | -| 13 | `normalizeResolvedModel` | Reescritura final antes de que el ejecutor incrustado use el modelo resuelto | El proveedor necesita reescrituras de transporte pero sigue usando un transporte del núcleo | -| 14 | `contributeResolvedModelCompat` | Aporta banderas de compatibilidad para modelos de proveedor detrás de otro transporte compatible | El proveedor reconoce sus propios modelos en transportes proxy sin asumir el control del proveedor | -| 15 | `capabilities` | Metadatos de transcripción/herramientas propiedad del proveedor usados por la lógica compartida del núcleo | El proveedor necesita particularidades de transcripción/familia de proveedor | -| 16 | `normalizeToolSchemas` | Normaliza esquemas de herramientas antes de que el ejecutor incrustado los vea | El proveedor necesita limpieza de esquemas de la familia de transporte | -| 17 | `inspectToolSchemas` | Expone diagnósticos de esquemas propiedad del proveedor después de la normalización | El proveedor quiere advertencias de keywords sin enseñar al núcleo reglas específicas del proveedor | -| 18 | `resolveReasoningOutputMode` | Selecciona contrato nativo frente a etiquetado de salida de razonamiento | El proveedor necesita salida de razonamiento/final etiquetada en lugar de campos nativos | -| 19 | `prepareExtraParams` | Normalización de parámetros de solicitud antes de los wrappers genéricos de opciones de stream | El proveedor necesita parámetros de solicitud predeterminados o limpieza de parámetros por proveedor | -| 20 | `createStreamFn` | Sustituye por completo la ruta normal de stream con un transporte personalizado | El proveedor necesita un protocolo de red personalizado, no solo un wrapper | -| 21 | `wrapStreamFn` | Wrapper de stream después de aplicar los wrappers genéricos | El proveedor necesita wrappers de compatibilidad de encabezados/cuerpo/modelo de solicitud sin un transporte personalizado | -| 22 | `resolveTransportTurnState` | Adjunta encabezados nativos por turno o metadatos de transporte | El proveedor quiere que transportes genéricos envíen identidad de turno nativa del proveedor | -| 23 | `resolveWebSocketSessionPolicy` | Adjunta encabezados nativos de WebSocket o política de enfriamiento de sesión | El proveedor quiere que transportes genéricos WS ajusten encabezados de sesión o política de fallback | -| 24 | `formatApiKey` | Formateador de perfil de autenticación: el perfil almacenado se convierte en la cadena `apiKey` del runtime | El proveedor almacena metadatos de autenticación adicionales y necesita una forma de token de runtime personalizada | -| 25 | `refreshOAuth` | Sobrescritura de actualización de OAuth para endpoints de actualización personalizados o política de fallos de actualización | El proveedor no encaja en los actualizadores compartidos de `pi-ai` | -| 26 | `buildAuthDoctorHint` | Pista de reparación añadida cuando falla la actualización de OAuth | El proveedor necesita una guía de reparación de autenticación propiedad del proveedor tras un fallo de actualización | -| 27 | `matchesContextOverflowError` | Comparador de desbordamiento de ventana de contexto propiedad del proveedor | El proveedor tiene errores de desbordamiento en bruto que las heurísticas genéricas pasarían por alto | -| 28 | `classifyFailoverReason` | Clasificación de motivo de failover propiedad del proveedor | El proveedor puede mapear errores brutos de API/transporte a rate-limit/sobrecarga/etc. | -| 29 | `isCacheTtlEligible` | Política de caché de prompts para proveedores proxy/backhaul | El proveedor necesita control específico de TTL de caché para proxies | -| 30 | `buildMissingAuthMessage` | Sustitución del mensaje genérico de recuperación por falta de autenticación | El proveedor necesita una pista de recuperación específica del proveedor por falta de autenticación | -| 31 | `suppressBuiltInModel` | Supresión de modelos upstream obsoletos más una pista opcional de error orientada al usuario | El proveedor necesita ocultar filas upstream obsoletas o sustituirlas por una pista del proveedor | -| 32 | `augmentModelCatalog` | Filas sintéticas/finales de catálogo añadidas después del descubrimiento | El proveedor necesita filas sintéticas de compatibilidad futura en `models list` y selectores | -| 33 | `isBinaryThinking` | Conmutador de razonamiento on/off para proveedores de razonamiento binario | El proveedor expone solo razonamiento binario activado/desactivado | -| 34 | `supportsXHighThinking` | Compatibilidad con razonamiento `xhigh` para modelos seleccionados | El proveedor quiere `xhigh` solo en un subconjunto de modelos | -| 35 | `resolveDefaultThinkingLevel` | Nivel `/think` predeterminado para una familia de modelos específica | El proveedor posee la política predeterminada de `/think` para una familia de modelos | -| 36 | `isModernModelRef` | Comparador de modelos modernos para filtros de perfiles en vivo y selección de smoke | El proveedor posee la coincidencia de modelos preferidos en vivo/smoke | -| 37 | `prepareRuntimeAuth` | Intercambia una credencial configurada por el token/clave real de runtime justo antes de la inferencia | El proveedor necesita un intercambio de token o una credencial de solicitud de corta duración | -| 38 | `resolveUsageAuth` | Resuelve credenciales de uso/facturación para `/usage` y superficies de estado relacionadas | El proveedor necesita análisis personalizado de token de uso/cuota o una credencial de uso diferente | -| 39 | `fetchUsageSnapshot` | Obtiene y normaliza snapshots de uso/cuota específicos del proveedor después de resolver la autenticación | El proveedor necesita un endpoint de uso específico del proveedor o un analizador de carga | -| 40 | `createEmbeddingProvider` | Crea un adaptador de embeddings propiedad del proveedor para memoria/búsqueda | El comportamiento de embeddings de memoria debe vivir con el plugin del proveedor | -| 41 | `buildReplayPolicy` | Devuelve una política de replay que controla el manejo de transcripciones para el proveedor | El proveedor necesita una política personalizada de transcripción (por ejemplo, eliminación de bloques de pensamiento) | -| 42 | `sanitizeReplayHistory` | Reescribe el historial de replay después de la limpieza genérica de transcripciones | El proveedor necesita reescrituras de replay específicas del proveedor más allá de los helpers compartidos de compactación | -| 43 | `validateReplayTurns` | Validación o remodelado final de turnos de replay antes del ejecutor incrustado | El transporte del proveedor necesita validación más estricta de turnos después de la limpieza genérica | -| 44 | `onModelSelected` | Ejecuta efectos secundarios propiedad del proveedor después de la selección | El proveedor necesita telemetría o estado propiedad del proveedor cuando un modelo se vuelve activo | +| 1 | `catalog` | Publica la configuración del proveedor en `models.providers` durante la generación de `models.json` | El proveedor posee un catálogo o valores predeterminados de base URL | +| 2 | `applyConfigDefaults` | Aplica valores predeterminados globales propiedad del proveedor durante la materialización de la configuración | Los valores predeterminados dependen del modo de autenticación, del entorno o de semánticas de familia de modelos del proveedor | +| -- | _(built-in model lookup)_ | OpenClaw prueba primero la ruta normal de registro/catálogo | _(no es un hook de plugin)_ | +| 3 | `normalizeModelId` | Normaliza alias heredados o de vista previa de id de modelo antes de la búsqueda | El proveedor posee limpieza de alias antes de la resolución canónica del modelo | +| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` de familia de proveedor antes del ensamblaje genérico del modelo | El proveedor posee limpieza de transporte para ids de proveedor personalizados de la misma familia de transporte | +| 5 | `normalizeConfig` | Normaliza `models.providers.` antes de la resolución en runtime/del proveedor | El proveedor necesita limpieza de configuración que debe vivir con el plugin; las utilidades integradas de familia Google también respaldan entradas de configuración Google compatibles | +| 6 | `applyNativeStreamingUsageCompat` | Aplica reescrituras de compatibilidad de uso de streaming nativo a proveedores configurados | El proveedor necesita correcciones de metadatos de uso de streaming nativo impulsadas por endpoints | +| 7 | `resolveConfigApiKey` | Resuelve autenticación con marcador de entorno para proveedores configurados antes de cargar autenticación en runtime | El proveedor tiene resolución de API key con marcador de entorno propiedad del proveedor; `amazon-bedrock` también tiene aquí un resolvedor integrado de marcadores de entorno de AWS | +| 8 | `resolveSyntheticAuth` | Expone autenticación local/alojada por uno mismo o respaldada por configuración sin persistir texto sin formato | El proveedor puede operar con un marcador de credencial sintética/local | +| 9 | `resolveExternalAuthProfiles` | Superpone perfiles externos de autenticación propiedad del proveedor; `persistence` predeterminado es `runtime-only` para credenciales propiedad de CLI/app | El proveedor reutiliza credenciales de autenticación externas sin persistir tokens de actualización copiados | +| 10 | `shouldDeferSyntheticProfileAuth` | Da menor prioridad a placeholders sintéticos almacenados detrás de autenticación respaldada por entorno/configuración | El proveedor almacena perfiles placeholder sintéticos que no deberían ganar precedencia | +| 11 | `resolveDynamicModel` | Fallback síncrono para ids de modelo propiedad del proveedor que aún no están en el registro local | El proveedor acepta ids de modelo arbitrarios del upstream | +| 12 | `prepareDynamicModel` | Calentamiento asíncrono, luego `resolveDynamicModel` se ejecuta de nuevo | El proveedor necesita metadatos de red antes de resolver ids desconocidos | +| 13 | `normalizeResolvedModel` | Reescritura final antes de que el embedded runner use el modelo resuelto | El proveedor necesita reescrituras de transporte pero sigue usando un transporte central | +| 14 | `contributeResolvedModelCompat` | Aporta banderas de compatibilidad para modelos del proveedor detrás de otro transporte compatible | El proveedor reconoce sus propios modelos en transportes proxy sin asumir el control del proveedor | +| 15 | `capabilities` | Metadatos de transcripción/herramientas propiedad del proveedor usados por lógica central compartida | El proveedor necesita particularidades de transcripción/familia de proveedor | +| 16 | `normalizeToolSchemas` | Normaliza esquemas de herramientas antes de que el embedded runner los vea | El proveedor necesita limpieza de esquemas para una familia de transporte | +| 17 | `inspectToolSchemas` | Expone diagnósticos de esquemas propiedad del proveedor después de la normalización | El proveedor quiere advertencias de palabras clave sin enseñar al núcleo reglas específicas del proveedor | +| 18 | `resolveReasoningOutputMode` | Selecciona contrato de salida de razonamiento nativo o etiquetado | El proveedor necesita salida de razonamiento/final etiquetada en lugar de campos nativos | +| 19 | `prepareExtraParams` | Normalización de parámetros de solicitud antes de wrappers genéricos de opciones de stream | El proveedor necesita parámetros de solicitud predeterminados o limpieza de parámetros por proveedor | +| 20 | `createStreamFn` | Reemplaza por completo la ruta normal de stream con un transporte personalizado | El proveedor necesita un protocolo de cableado personalizado, no solo un wrapper | +| 21 | `wrapStreamFn` | Wrapper de stream después de aplicar wrappers genéricos | El proveedor necesita wrappers de compatibilidad de encabezados/cuerpo/modelo de solicitud sin un transporte personalizado | +| 22 | `resolveTransportTurnState` | Adjunta encabezados o metadatos nativos por turno del transporte | El proveedor quiere que transportes genéricos envíen identidad de turno nativa del proveedor | +| 23 | `resolveWebSocketSessionPolicy` | Adjunta encabezados nativos de WebSocket o política de enfriamiento de sesión | El proveedor quiere que transportes genéricos WS ajusten encabezados de sesión o política de fallback | +| 24 | `formatApiKey` | Formateador de perfil de autenticación: el perfil almacenado se convierte en la cadena `apiKey` de runtime | El proveedor almacena metadatos de autenticación adicionales y necesita una forma de token de runtime personalizada | +| 25 | `refreshOAuth` | Reemplazo del refresco de OAuth para endpoints de refresco personalizados o política de fallo de refresco | El proveedor no encaja en los refrescadores compartidos de `pi-ai` | +| 26 | `buildAuthDoctorHint` | Sugerencia de reparación agregada cuando falla el refresco de OAuth | El proveedor necesita una guía de reparación de autenticación propiedad del proveedor tras un fallo de refresco | +| 27 | `matchesContextOverflowError` | Comparador propiedad del proveedor para desbordamiento de ventana de contexto | El proveedor tiene errores de desbordamiento crudos que las heurísticas genéricas no detectarían | +| 28 | `classifyFailoverReason` | Clasificación propiedad del proveedor del motivo de failover | El proveedor puede mapear errores crudos de API/transporte a límite de tasa/sobrecarga/etc. | +| 29 | `isCacheTtlEligible` | Política de caché de prompts para proveedores proxy/backhaul | El proveedor necesita control específico del proxy para TTL de caché | +| 30 | `buildMissingAuthMessage` | Reemplazo del mensaje genérico de recuperación por falta de autenticación | El proveedor necesita una sugerencia de recuperación específica del proveedor por falta de autenticación | +| 31 | `suppressBuiltInModel` | Supresión de modelos upstream obsoletos más sugerencia opcional de error orientada al usuario | El proveedor necesita ocultar filas upstream obsoletas o reemplazarlas con una sugerencia del proveedor | +| 32 | `augmentModelCatalog` | Filas de catálogo sintéticas/finales añadidas después del descubrimiento | El proveedor necesita filas sintéticas de compatibilidad futura en `models list` y selectores | +| 33 | `isBinaryThinking` | Alternancia on/off de razonamiento para proveedores de pensamiento binario | El proveedor expone solo pensamiento binario activado/desactivado | +| 34 | `supportsXHighThinking` | Compatibilidad con razonamiento `xhigh` para modelos seleccionados | El proveedor quiere `xhigh` solo en un subconjunto de modelos | +| 35 | `resolveDefaultThinkingLevel` | Nivel predeterminado de `/think` para una familia específica de modelos | El proveedor posee la política predeterminada de `/think` para una familia de modelos | +| 36 | `isModernModelRef` | Comparador de modelo moderno para filtros de perfiles activos y selección smoke | El proveedor posee la coincidencia de modelo preferido en pruebas live/smoke | +| 37 | `prepareRuntimeAuth` | Intercambia una credencial configurada por el token/clave real de runtime justo antes de la inferencia | El proveedor necesita un intercambio de tokens o una credencial de solicitud de corta duración | +| 38 | `resolveUsageAuth` | Resuelve credenciales de uso/facturación para `/usage` y superficies de estado relacionadas | El proveedor necesita análisis personalizado de token de uso/cuota o una credencial de uso diferente | +| 39 | `fetchUsageSnapshot` | Recupera y normaliza instantáneas de uso/cuota específicas del proveedor después de resolver la autenticación | El proveedor necesita un endpoint de uso específico del proveedor o un analizador de carga útil | +| 40 | `createEmbeddingProvider` | Construye un adaptador de embeddings propiedad del proveedor para memoria/búsqueda | El comportamiento de embeddings de memoria debe pertenecer al plugin del proveedor | +| 41 | `buildReplayPolicy` | Devuelve una política de replay que controla el manejo de transcripciones para el proveedor | El proveedor necesita una política de transcripción personalizada (por ejemplo, eliminar bloques de pensamiento) | +| 42 | `sanitizeReplayHistory` | Reescribe el historial de replay después de la limpieza genérica de transcripciones | El proveedor necesita reescrituras de replay específicas del proveedor más allá de utilidades compartidas de compactación | +| 43 | `validateReplayTurns` | Validación o remodelado final de turnos de replay antes del embedded runner | El transporte del proveedor necesita validación más estricta de turnos tras el saneamiento genérico | +| 44 | `onModelSelected` | Ejecuta efectos secundarios propiedad del proveedor después de seleccionar el modelo | El proveedor necesita telemetría o estado propio del proveedor cuando un modelo pasa a estar activo | -`normalizeModelId`, `normalizeTransport` y `normalizeConfig` primero comprueban el -plugin de proveedor coincidente, y luego recorren otros plugins de proveedor con capacidad de hook -hasta que uno realmente cambia el id del modelo o el transporte/configuración. Eso mantiene -funcionando los shims de alias/compatibilidad de proveedores sin exigir que quien llama sepa qué -plugin incluido posee la reescritura. Si ningún hook de proveedor reescribe una entrada compatible -de configuración de la familia Google, el normalizador de configuración incluido de Google sigue aplicando +`normalizeModelId`, `normalizeTransport` y `normalizeConfig` primero verifican el +plugin de proveedor coincidente y luego recorren otros plugins de proveedor con capacidad de hook +hasta que uno realmente cambie el id del modelo o el transporte/configuración. Eso mantiene +funcionando los adaptadores shim de alias/compatibilidad de proveedores sin requerir que el llamador sepa qué +plugin integrado posee la reescritura. Si ningún hook de proveedor reescribe una entrada de configuración +compatible de familia Google, el normalizador de configuración integrado de Google sigue aplicando esa limpieza de compatibilidad. -Si el proveedor necesita un protocolo de red totalmente personalizado o un ejecutor de solicitudes personalizado, +Si el proveedor necesita un protocolo de cableado totalmente personalizado o un ejecutor de solicitudes personalizado, esa es otra clase de extensión. Estos hooks son para comportamiento del proveedor -que sigue ejecutándose en el bucle normal de inferencia de OpenClaw. +que todavía se ejecuta sobre el ciclo normal de inferencia de OpenClaw. ### Ejemplo de proveedor @@ -777,106 +779,113 @@ api.registerProvider({ `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, y `wrapStreamFn` porque posee la compatibilidad futura de Claude 4.6, - pistas de familia de proveedor, guía de reparación de autenticación, integración - con endpoint de uso, elegibilidad de caché de prompts, valores predeterminados de configuración con reconocimiento de autenticación, política - predeterminada/adaptativa de pensamiento de Claude y modelado de stream específico de Anthropic para - encabezados beta, `/fast` / `serviceTier` y `context1m`. -- Los helpers de stream específicos de Claude de Anthropic permanecen por ahora en la - propia unión pública `api.ts` / `contract-api.ts` del plugin incluido. Esa superficie de paquete + sugerencias de familia de proveedor, guía de reparación de autenticación, integración + del endpoint de uso, elegibilidad de caché de prompts, valores predeterminados de configuración sensibles a autenticación, + política predeterminada/adaptativa de pensamiento de Claude y conformado de stream + específico de Anthropic para encabezados beta, `/fast` / `serviceTier` y `context1m`. +- Las utilidades de stream específicas de Claude de Anthropic permanecen por ahora en la + propia unión pública `api.ts` / `contract-api.ts` del plugin integrado. Esa superficie del paquete exporta `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` y los generadores - de wrappers de Anthropic de nivel inferior en lugar de ampliar el SDK genérico alrededor de las reglas + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` y los constructores de wrappers + de Anthropic de nivel inferior, en lugar de ampliar el SDK genérico alrededor de las reglas de encabezados beta de un solo proveedor. - OpenAI usa `resolveDynamicModel`, `normalizeResolvedModel` y - `capabilities` más `buildMissingAuthMessage`, `suppressBuiltInModel`, + `capabilities` además de `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef` - porque posee la compatibilidad futura de GPT-5.4, la normalización directa - de OpenAI `openai-completions` -> `openai-responses`, pistas de autenticación - con reconocimiento de Codex, supresión de Spark, filas sintéticas de lista de OpenAI y la política - de pensamiento / modelos en vivo de GPT-5; la familia de streams `openai-responses-defaults` posee los - wrappers compartidos nativos de OpenAI Responses para encabezados de atribución, + porque posee la compatibilidad futura de GPT-5.4, la normalización directa de OpenAI + `openai-completions` -> `openai-responses`, sugerencias de autenticación compatibles con Codex, + supresión de Spark, filas sintéticas de lista de OpenAI y la política de pensamiento / modelos activos + de GPT-5; la familia de streams `openai-responses-defaults` posee los wrappers compartidos de OpenAI Responses + para encabezados de atribución, `/fast`/`serviceTier`, verbosidad de texto, búsqueda web nativa de Codex, - modelado de carga de compatibilidad de razonamiento y gestión de contexto de Responses. -- OpenRouter usa `catalog` más `resolveDynamicModel` y + conformado de cargas de compatibilidad de razonamiento y gestión de contexto de Responses. +- OpenRouter usa `catalog` además de `resolveDynamicModel` y `prepareDynamicModel` porque el proveedor es pass-through y puede exponer nuevos ids de modelo antes de que se actualice el catálogo estático de OpenClaw; también usa `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` para mantener - encabezados de solicitud específicos del proveedor, metadatos de enrutamiento, parches de razonamiento y - política de caché de prompts fuera del núcleo. Su política de replay proviene de la + fuera del núcleo los encabezados de solicitud específicos del proveedor, metadatos de enrutamiento, parches de razonamiento + y la política de caché de prompts. Su política de replay proviene de la familia `passthrough-gemini`, mientras que la familia de streams `openrouter-thinking` - posee la inyección de razonamiento proxy y los saltos de modelo no compatible / `auto`. + posee la inyección de razonamiento proxy y las omisiones de modelo no compatible / `auto`. - GitHub Copilot usa `catalog`, `auth`, `resolveDynamicModel` y - `capabilities` más `prepareRuntimeAuth` y `fetchUsageSnapshot` porque - necesita inicio de sesión de dispositivo propiedad del proveedor, comportamiento de fallback de modelos, particularidades - de transcripción de Claude, un intercambio de token de GitHub -> token de Copilot y un endpoint - de uso propiedad del proveedor. + `capabilities` además de `prepareRuntimeAuth` y `fetchUsageSnapshot` porque + necesita inicio de sesión por dispositivo propiedad del proveedor, comportamiento de fallback de modelo, + particularidades de transcripción de Claude, un intercambio de token de GitHub a token de Copilot + y un endpoint de uso propiedad del proveedor. - OpenAI Codex usa `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` y `augmentModelCatalog` más + `normalizeResolvedModel`, `refreshOAuth` y `augmentModelCatalog` además de `prepareExtraParams`, `resolveUsageAuth` y `fetchUsageSnapshot` porque - aún se ejecuta sobre los transportes centrales de OpenAI pero posee su normalización - de transporte/URL base, política de fallback para actualización de OAuth, elección predeterminada de transporte, - filas sintéticas de catálogo de Codex e integración con el endpoint de uso de ChatGPT; comparte la misma familia de streams `openai-responses-defaults` que OpenAI directo. + todavía se ejecuta sobre transportes centrales de OpenAI, pero posee su + normalización de transporte/base URL, política de fallback de refresco OAuth, elección + predeterminada de transporte, filas sintéticas de catálogo de Codex e integración + del endpoint de uso de ChatGPT; comparte la misma familia de streams `openai-responses-defaults` + que OpenAI directo. - Google AI Studio y Gemini CLI OAuth usan `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` e `isModernModelRef` porque la familia de replay `google-gemini` posee el fallback de compatibilidad futura de Gemini 3.1, - la validación nativa de replay de Gemini, la sanitización de replay de bootstrap, el modo - etiquetado de salida de razonamiento y la coincidencia de modelos modernos, mientras que la - familia de streams `google-thinking` posee la normalización de cargas de pensamiento de Gemini; + la validación nativa de replay de Gemini, el saneamiento de replay de arranque, el modo + etiquetado de salida de razonamiento y la coincidencia de modelo moderno, mientras que la + familia de streams `google-thinking` posee la normalización de carga útil de pensamiento de Gemini; Gemini CLI OAuth también usa `formatApiKey`, `resolveUsageAuth` y - `fetchUsageSnapshot` para formateo de tokens, análisis de tokens e integración - con el endpoint de cuota. + `fetchUsageSnapshot` para formato de tokens, análisis de tokens y cableado + del endpoint de cuota. - Anthropic Vertex usa `buildReplayPolicy` a través de la - familia de replay `anthropic-by-model` para que la limpieza de replay específica de Claude quede - limitada a ids de Claude en lugar de a todo transporte `anthropic-messages`. + familia de replay `anthropic-by-model` para que la limpieza de replay específica de Claude permanezca + limitada a ids de Claude en lugar de a todos los transportes `anthropic-messages`. - Amazon Bedrock usa `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` y `resolveDefaultThinkingLevel` porque posee la clasificación específica de Bedrock para errores de limitación, no-listo y desbordamiento de contexto - en tráfico de Anthropic sobre Bedrock; su política de replay sigue compartiendo la misma + `classifyFailoverReason` y `resolveDefaultThinkingLevel` porque posee la clasificación + específica de Bedrock de errores de límite/not-ready/desbordamiento de contexto + para tráfico Anthropic-on-Bedrock; su política de replay sigue compartiendo la misma protección `anthropic-by-model` solo para Claude. - OpenRouter, Kilocode, Opencode y Opencode Go usan `buildReplayPolicy` a través de la familia de replay `passthrough-gemini` porque hacen proxy de modelos Gemini - a través de transportes compatibles con OpenAI y necesitan la sanitización de firmas de pensamiento de Gemini sin validación nativa de replay de Gemini ni reescrituras - de bootstrap. + mediante transportes compatibles con OpenAI y necesitan saneamiento de firma de pensamiento de Gemini + sin validación nativa de replay de Gemini ni reescrituras de arranque. - MiniMax usa `buildReplayPolicy` a través de la - familia `hybrid-anthropic-openai` porque un proveedor posee tanto semántica de mensajes - de Anthropic como compatible con OpenAI; mantiene la eliminación de bloques de pensamiento solo de Claude en el lado - Anthropic mientras sobrescribe el modo de salida de razonamiento de vuelta a nativo, y la familia de streams `minimax-fast-mode` posee las reescrituras de modelos de modo rápido en la ruta compartida de stream. -- Moonshot usa `catalog` más `wrapStreamFn` porque todavía usa el transporte - compartido de OpenAI pero necesita normalización de cargas de pensamiento propiedad del proveedor; la - familia de streams `moonshot-thinking` asigna la configuración más el estado `/think` a su - carga nativa binaria de pensamiento. + familia de replay `hybrid-anthropic-openai` porque un proveedor posee tanto semánticas + de mensajes Anthropic como compatibilidad con OpenAI; mantiene la eliminación + de bloques de pensamiento solo de Claude del lado Anthropic mientras sobrescribe el modo + de salida de razonamiento de vuelta a nativo, y la familia de streams `minimax-fast-mode` + posee las reescrituras de modelos fast-mode en la ruta compartida de stream. +- Moonshot usa `catalog` además de `wrapStreamFn` porque todavía usa el transporte + compartido de OpenAI, pero necesita normalización de carga útil de pensamiento propiedad del proveedor; la + familia de streams `moonshot-thinking` mapea configuración y estado de `/think` sobre su + carga útil nativa de pensamiento binario. - Kilocode usa `catalog`, `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` porque necesita encabezados de solicitud propiedad del proveedor, - normalización de cargas de razonamiento, pistas de transcripción de Gemini y control - de TTL de caché de Anthropic; la familia de streams `kilocode-thinking` mantiene la inyección de pensamiento de Kilo en la ruta compartida de stream proxy mientras omite `kilo/auto` y + normalización de carga útil de razonamiento, sugerencias de transcripción Gemini y control + de TTL de caché de Anthropic; la familia de streams `kilocode-thinking` mantiene la inyección + del pensamiento Kilo en la ruta compartida de stream proxy, omitiendo `kilo/auto` y otros ids de modelo proxy que no admiten cargas explícitas de razonamiento. - Z.AI usa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, `resolveUsageAuth` y `fetchUsageSnapshot` porque posee el fallback de GLM-5, - valores predeterminados de `tool_stream`, UX de pensamiento binario, coincidencia de modelos modernos y tanto autenticación de uso como obtención de cuota; la familia de streams `tool-stream-default-on` mantiene el wrapper predeterminado activado de `tool_stream` fuera del pegamento escrito a mano por proveedor. + valores predeterminados de `tool_stream`, UX de pensamiento binario, coincidencia de modelo moderno + y tanto autenticación de uso como recuperación de cuota; la familia de streams `tool-stream-default-on` + mantiene el wrapper predeterminado de `tool_stream` fuera del pegamento escrito a mano por proveedor. - xAI usa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef` - porque posee la normalización nativa de transporte xAI Responses, reescrituras de alias - de modo rápido de Grok, `tool_stream` predeterminado, limpieza estricta de herramientas/cargas de razonamiento, - reutilización de autenticación de fallback para herramientas propiedad del plugin, resolución de modelos Grok - con compatibilidad futura y parches de compatibilidad propiedad del proveedor como el perfil - de esquema de herramientas de xAI, keywords de esquema no compatibles, `web_search` nativo y decodificación - de entidades HTML en argumentos de llamadas de herramientas. + porque posee la normalización nativa del transporte xAI Responses, las reescrituras de alias fast-mode de Grok, `tool_stream` predeterminado, limpieza estricta de herramientas / cargas de razonamiento, + reutilización de autenticación fallback para herramientas propiedad del plugin, resolución + de modelos Grok con compatibilidad futura y parches de compatibilidad propiedad del proveedor como el perfil + de esquema de herramientas de xAI, palabras clave de esquema no compatibles, `web_search` nativo y + decodificación de argumentos de llamadas a herramientas con entidades HTML. - Mistral, OpenCode Zen y OpenCode Go usan solo `capabilities` para mantener fuera del núcleo las particularidades de transcripción/herramientas. -- Los proveedores incluidos solo de catálogo como `byteplus`, `cloudflare-ai-gateway`, +- Proveedores integrados solo de catálogo como `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` y `volcengine` usan solo `catalog`. -- Qwen usa `catalog` para su proveedor de texto más registros compartidos de comprensión multimedia y - generación de video para sus superficies multimodales. -- MiniMax y Xiaomi usan `catalog` más hooks de uso porque su comportamiento de `/usage` - es propiedad del plugin aunque la inferencia siga ejecutándose a través de los transportes compartidos. +- Qwen usa `catalog` para su proveedor de texto más registros compartidos de comprensión de medios + y generación de video para sus superficies multimodales. +- MiniMax y Xiaomi usan `catalog` más hooks de uso porque su comportamiento `/usage` + pertenece al plugin aunque la inferencia siga ejecutándose a través de los transportes compartidos. -## Helpers de runtime +## Utilidades de runtime -Los plugins pueden acceder a helpers seleccionados del núcleo a través de `api.runtime`. Para TTS: +Los plugins pueden acceder a utilidades centrales seleccionadas mediante `api.runtime`. Para TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -897,11 +906,11 @@ const voices = await api.runtime.tts.listVoices({ Notas: -- `textToSpeech` devuelve la carga normal de salida de TTS del núcleo para superficies de archivo/nota de voz. +- `textToSpeech` devuelve la carga útil normal central de TTS para superficies de archivo/nota de voz. - Usa la configuración central `messages.tts` y la selección de proveedor. -- Devuelve un buffer de audio PCM + frecuencia de muestreo. Los plugins deben remuestrear/codificar para los proveedores. +- Devuelve buffer de audio PCM + frecuencia de muestreo. Los plugins deben remuestrear/codificar para proveedores. - `listVoices` es opcional por proveedor. Úsalo para selectores de voz o flujos de configuración propiedad del proveedor. -- Los listados de voces pueden incluir metadatos más ricos como locale, género y etiquetas de personalidad para selectores con conocimiento del proveedor. +- Los listados de voces pueden incluir metadatos más ricos como configuración regional, género y etiquetas de personalidad para selectores conscientes del proveedor. - OpenAI y ElevenLabs admiten telefonía hoy. Microsoft no. Los plugins también pueden registrar proveedores de voz mediante `api.registerSpeechProvider(...)`. @@ -924,15 +933,15 @@ api.registerSpeechProvider({ Notas: -- Mantén la política de TTS, el fallback y la entrega de respuestas en el núcleo. +- Mantén la política TTS, el fallback y la entrega de respuestas en el núcleo. - Usa proveedores de voz para comportamiento de síntesis propiedad del proveedor. - La entrada heredada `edge` de Microsoft se normaliza al id de proveedor `microsoft`. - El modelo de propiedad preferido está orientado a la empresa: un plugin de proveedor puede poseer - texto, voz, imagen y futuros proveedores multimedia a medida que OpenClaw agregue esos + texto, voz, imagen y futuros proveedores de medios a medida que OpenClaw agrega esos contratos de capacidad. Para comprensión de imagen/audio/video, los plugins registran un proveedor tipado -de comprensión multimedia en lugar de una bolsa genérica de clave/valor: +de comprensión de medios en lugar de una bolsa genérica de clave/valor: ```ts api.registerMediaUnderstandingProvider({ @@ -946,15 +955,16 @@ api.registerMediaUnderstandingProvider({ Notas: -- Mantén la orquestación, el fallback, la configuración y la integración con canales en el núcleo. +- Mantén la orquestación, el fallback, la configuración y el cableado del canal en el núcleo. - Mantén el comportamiento del proveedor en el plugin del proveedor. -- La expansión aditiva debe seguir siendo tipada: nuevos métodos opcionales, nuevos campos de resultado opcionales, nuevas capacidades opcionales. +- La expansión aditiva debe seguir siendo tipada: nuevos métodos opcionales, nuevos campos + opcionales de resultado, nuevas capacidades opcionales. - La generación de video ya sigue el mismo patrón: - - el núcleo posee el contrato de capacidad y el helper de runtime - - los plugins de proveedores registran `api.registerVideoGenerationProvider(...)` + - el núcleo posee el contrato de capacidad y la utilidad de runtime + - los plugins de proveedor registran `api.registerVideoGenerationProvider(...)` - los plugins de función/canal consumen `api.runtime.videoGeneration.*` -Para los helpers de runtime de comprensión multimedia, los plugins pueden llamar a: +Para utilidades de runtime de comprensión de medios, los plugins pueden llamar a: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -969,14 +979,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Para transcripción de audio, los plugins pueden usar el runtime de comprensión multimedia -o el alias antiguo STT: +Para transcripción de audio, los plugins pueden usar el runtime de comprensión de medios +o el alias heredado de STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Opcional cuando el MIME no puede inferirse de forma fiable: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` @@ -985,11 +995,11 @@ Notas: - `api.runtime.mediaUnderstanding.*` es la superficie compartida preferida para comprensión de imagen/audio/video. -- Usa la configuración central de audio de comprensión multimedia (`tools.media.audio`) y el orden de fallback de proveedores. +- Usa la configuración central de audio de comprensión de medios (`tools.media.audio`) y el orden de fallback de proveedores. - Devuelve `{ text: undefined }` cuando no se produce salida de transcripción (por ejemplo, entrada omitida/no compatible). -- `api.runtime.stt.transcribeAudioFile(...)` permanece como alias de compatibilidad. +- `api.runtime.stt.transcribeAudioFile(...)` sigue existiendo como alias de compatibilidad. -Los plugins también pueden lanzar ejecuciones de subagentes en segundo plano mediante `api.runtime.subagent`: +Los plugins también pueden iniciar ejecuciones de subagentes en segundo plano mediante `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1003,14 +1013,14 @@ const result = await api.runtime.subagent.run({ Notas: -- `provider` y `model` son sobrescrituras opcionales por ejecución, no cambios persistentes de sesión. -- OpenClaw solo respeta esos campos de sobrescritura para llamadores de confianza. -- Para ejecuciones de fallback propiedad del plugin, los operadores deben habilitarlo expresamente con `plugins.entries..subagent.allowModelOverride: true`. +- `provider` y `model` son reemplazos opcionales por ejecución, no cambios persistentes de sesión. +- OpenClaw solo respeta esos campos de reemplazo para llamadores de confianza. +- Para ejecuciones fallback propiedad del plugin, los operadores deben habilitarlo explícitamente con `plugins.entries..subagent.allowModelOverride: true`. - Usa `plugins.entries..subagent.allowedModels` para restringir plugins de confianza a objetivos canónicos específicos `provider/model`, o `"*"` para permitir explícitamente cualquier objetivo. -- Las ejecuciones de subagentes de plugins no confiables siguen funcionando, pero las solicitudes de sobrescritura se rechazan en lugar de usar silencio como fallback. +- Las ejecuciones de subagente de plugins no confiables siguen funcionando, pero las solicitudes de reemplazo se rechazan en lugar de caer silenciosamente en fallback. -Para búsqueda web, los plugins pueden consumir el helper compartido de runtime en lugar de -acceder directamente a la integración de herramientas del agente: +Para búsqueda web, los plugins pueden consumir la utilidad compartida de runtime en lugar de +acceder directamente al cableado de herramientas del agente: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1031,9 +1041,9 @@ Los plugins también pueden registrar proveedores de búsqueda web mediante Notas: -- Mantén la selección de proveedor, la resolución de credenciales y la semántica compartida de solicitudes en el núcleo. +- Mantén en el núcleo la selección de proveedores, la resolución de credenciales y la semántica compartida de solicitudes. - Usa proveedores de búsqueda web para transportes de búsqueda específicos del proveedor. -- `api.runtime.webSearch.*` es la superficie compartida preferida para plugins de función/canal que necesiten comportamiento de búsqueda sin depender del wrapper de herramienta del agente. +- `api.runtime.webSearch.*` es la superficie compartida preferida para plugins de función/canal que necesitan comportamiento de búsqueda sin depender del wrapper de herramientas del agente. ### `api.runtime.imageGeneration` @@ -1049,7 +1059,7 @@ const providers = api.runtime.imageGeneration.listProviders({ ``` - `generate(...)`: genera una imagen usando la cadena configurada de proveedores de generación de imágenes. -- `listProviders(...)`: lista los proveedores disponibles de generación de imágenes y sus capacidades. +- `listProviders(...)`: lista los proveedores de generación de imágenes disponibles y sus capacidades. ## Rutas HTTP del Gateway @@ -1071,31 +1081,31 @@ api.registerHttpRoute({ Campos de la ruta: - `path`: ruta bajo el servidor HTTP del gateway. -- `auth`: obligatorio. Usa `"gateway"` para requerir autenticación normal del gateway, o `"plugin"` para autenticación/validación de webhook gestionadas por el plugin. +- `auth`: obligatorio. Usa `"gateway"` para requerir autenticación normal del gateway, o `"plugin"` para autenticación/validación de webhook gestionada por el plugin. - `match`: opcional. `"exact"` (predeterminado) o `"prefix"`. - `replaceExisting`: opcional. Permite que el mismo plugin reemplace su propio registro de ruta existente. - `handler`: devuelve `true` cuando la ruta manejó la solicitud. Notas: -- `api.registerHttpHandler(...)` fue eliminado y causará un error de carga del plugin. Usa `api.registerHttpRoute(...)` en su lugar. +- `api.registerHttpHandler(...)` fue eliminado y causará un error de carga del plugin. Usa `api.registerHttpRoute(...)`. - Las rutas de plugins deben declarar `auth` explícitamente. -- Los conflictos exactos de `path + match` se rechazan salvo que `replaceExisting: true`, y un plugin no puede reemplazar la ruta de otro plugin. -- Las rutas superpuestas con distintos niveles de `auth` se rechazan. Mantén cadenas de paso `exact`/`prefix` solo en el mismo nivel de autenticación. -- Las rutas `auth: "plugin"` **no** reciben automáticamente scopes de runtime del operador. Son para webhooks/validación de firmas gestionados por el plugin, no para llamadas privilegiadas a helpers del Gateway. -- Las rutas `auth: "gateway"` se ejecutan dentro de un scope de runtime de solicitud del Gateway, pero ese scope es intencionalmente conservador: - - la autenticación bearer por secreto compartido (`gateway.auth.mode = "token"` / `"password"`) mantiene los scopes de runtime de rutas de plugin fijados en `operator.write`, incluso si quien llama envía `x-openclaw-scopes` - - los modos HTTP de confianza con identidad (por ejemplo `trusted-proxy` o `gateway.auth.mode = "none"` en un ingreso privado) respetan `x-openclaw-scopes` solo cuando la cabecera está presente de forma explícita - - si `x-openclaw-scopes` está ausente en esas solicitudes de rutas de plugin con identidad, el scope de runtime vuelve a `operator.write` -- Regla práctica: no asumas que una ruta de plugin autenticada por gateway es implícitamente una superficie de administración. Si tu ruta necesita comportamiento exclusivo de admin, exige un modo de autenticación con identidad y documenta el contrato explícito de la cabecera `x-openclaw-scopes`. +- Los conflictos exactos de `path + match` se rechazan a menos que `replaceExisting: true`, y un plugin no puede reemplazar la ruta de otro plugin. +- Las rutas superpuestas con distintos niveles de `auth` se rechazan. Mantén las cadenas de fallthrough `exact`/`prefix` solo en el mismo nivel de autenticación. +- Las rutas `auth: "plugin"` **no** reciben automáticamente alcances de runtime del operador. Son para webhooks/verificación de firmas gestionados por el plugin, no para llamadas privilegiadas a utilidades del Gateway. +- Las rutas `auth: "gateway"` se ejecutan dentro de un alcance de runtime de solicitud del Gateway, pero ese alcance es intencionalmente conservador: + - la autenticación bearer por secreto compartido (`gateway.auth.mode = "token"` / `"password"`) mantiene los alcances de runtime de rutas de plugin fijados en `operator.write`, incluso si el llamador envía `x-openclaw-scopes` + - los modos HTTP confiables con identidad (por ejemplo `trusted-proxy` o `gateway.auth.mode = "none"` en una entrada privada) respetan `x-openclaw-scopes` solo cuando el encabezado está explícitamente presente + - si `x-openclaw-scopes` está ausente en esas solicitudes de rutas de plugin con identidad, el alcance de runtime vuelve a `operator.write` +- Regla práctica: no asumas que una ruta de plugin autenticada por gateway es implícitamente una superficie de administración. Si tu ruta necesita comportamiento exclusivo de administrador, exige un modo de autenticación con identidad y documenta el contrato explícito del encabezado `x-openclaw-scopes`. -## Rutas de importación del Plugin SDK +## Rutas de importación del SDK de plugins Usa subrutas del SDK en lugar de la importación monolítica `openclaw/plugin-sdk` al crear plugins: - `openclaw/plugin-sdk/plugin-entry` para primitivas de registro de plugins. -- `openclaw/plugin-sdk/core` para el contrato genérico compartido orientado a plugins. +- `openclaw/plugin-sdk/core` para el contrato compartido genérico orientado a plugins. - `openclaw/plugin-sdk/config-schema` para la exportación del esquema Zod raíz de `openclaw.json` (`OpenClawSchema`). - Primitivas estables de canal como `openclaw/plugin-sdk/channel-setup`, @@ -1110,15 +1120,15 @@ crear plugins: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` y - `openclaw/plugin-sdk/webhook-ingress` para la integración compartida de - configuración/autenticación/respuesta/webhook. `channel-inbound` es la superficie compartida para debounce, coincidencia de menciones, - helpers de política de menciones entrantes, formato de envelopes y helpers de - contexto de envelopes entrantes. - `channel-setup` es la unión estrecha de configuración opcional durante la instalación. - `setup-runtime` es la superficie de configuración segura en runtime usada por `setupEntry` / - inicio diferido, incluidos los adaptadores de parches de configuración seguros para importación. - `setup-adapter-runtime` es la unión del adaptador de configuración de cuentas consciente del entorno. - `setup-tools` es la pequeña unión helper para CLI/archivo/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` para cableado compartido de configuración/autenticación/respuesta/webhook. + `channel-inbound` es el hogar compartido para debounce, coincidencia de menciones, + utilidades de política de menciones entrantes, formateo de sobres y utilidades + de contexto de sobres entrantes. + `channel-setup` es la unión estrecha de configuración de instalación opcional. + `setup-runtime` es la superficie de configuración segura para runtime usada por `setupEntry` / + inicio diferido, incluidos los adaptadores de parche de configuración seguros para importación. + `setup-adapter-runtime` es la unión de adaptador de configuración de cuenta consciente del entorno. + `setup-tools` es la pequeña unión de utilidades de CLI/archivo/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Subrutas de dominio como `openclaw/plugin-sdk/channel-config-helpers`, @@ -1139,141 +1149,147 @@ crear plugins: `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` y - `openclaw/plugin-sdk/directory-runtime` para helpers compartidos de runtime/configuración. - `telegram-command-config` es la unión pública estrecha para normalización/validación de comandos personalizados de Telegram y sigue disponible incluso si la superficie de contrato incluida de Telegram no está disponible temporalmente. + `openclaw/plugin-sdk/directory-runtime` para utilidades compartidas de runtime/configuración. + `telegram-command-config` es la unión pública estrecha para normalización/validación de comandos personalizados de Telegram y sigue disponible incluso si la superficie de contrato integrada de Telegram no está disponible temporalmente. `text-runtime` es la unión compartida de texto/markdown/logging, incluida - la eliminación de texto visible para el asistente, helpers de renderizado/segmentación de markdown, helpers de redacción, - helpers de etiquetas directivas y utilidades de texto seguro. -- Las uniones de canal específicas de aprobación deben preferir un único contrato `approvalCapability` en el plugin. El núcleo - luego lee autenticación de aprobación, entrega, renderizado, enrutamiento nativo y comportamiento perezoso del manejador nativo a través de esa única capacidad + la eliminación de texto visible para el asistente, utilidades de renderizado/fragmentación markdown, utilidades de redacción, utilidades de etiquetas de directivas y utilidades de texto seguro. +- Las uniones de canal específicas de aprobación deben preferir un solo contrato `approvalCapability` + en el plugin. Luego, el núcleo lee autenticación de aprobación, entrega, renderizado, + enrutamiento nativo y comportamiento de manejador nativo perezoso a través de esa única capacidad en lugar de mezclar el comportamiento de aprobación en campos no relacionados del plugin. -- `openclaw/plugin-sdk/channel-runtime` está obsoleto y permanece solo como shim de compatibilidad para plugins antiguos. El código nuevo debe importar - las primitivas genéricas más estrechas, y el código del repositorio no debe agregar nuevas importaciones del shim. -- Los aspectos internos de extensiones incluidas siguen siendo privados. Los plugins externos deben usar solo subrutas `openclaw/plugin-sdk/*`. El código/pruebas del núcleo de OpenClaw puede usar los puntos de entrada públicos del repositorio bajo la raíz de un paquete de plugin como `index.js`, `api.js`, +- `openclaw/plugin-sdk/channel-runtime` está obsoleto y permanece solo como una + capa de compatibilidad para plugins antiguos. El código nuevo debe importar en su lugar las primitivas + genéricas más estrechas, y el código del repositorio no debe agregar nuevas importaciones de esta capa. +- Los aspectos internos de extensiones integradas siguen siendo privados. Los plugins externos deben usar solo + subrutas `openclaw/plugin-sdk/*`. El código/pruebas del núcleo de OpenClaw puede usar los + puntos de entrada públicos del repositorio bajo la raíz de paquete de un plugin como `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js` y archivos de alcance estrecho como - `login-qr-api.js`. Nunca importes `src/*` de un paquete de plugin desde el núcleo o desde otra extensión. + `login-qr-api.js`. Nunca importes `src/*` de un paquete de plugin desde el núcleo o desde + otra extensión. - División del punto de entrada del repositorio: - `/api.js` es el barril de helpers/tipos, + `/api.js` es el barril de utilidades/tipos, `/runtime-api.js` es el barril solo de runtime, - `/index.js` es la entrada del plugin incluido + `/index.js` es la entrada del plugin integrado, y `/setup-entry.js` es la entrada del plugin de configuración. -- Ejemplos actuales de proveedores incluidos: - - Anthropic usa `api.js` / `contract-api.js` para helpers de stream de Claude como - `wrapAnthropicProviderStream`, helpers de encabezados beta y análisis de `service_tier`. - - OpenAI usa `api.js` para constructores de proveedores, helpers de modelos predeterminados y constructores de proveedores en tiempo real. - - OpenRouter usa `api.js` para su constructor de proveedor más helpers de onboarding/configuración, - mientras que `register.runtime.js` todavía puede reexportar helpers genéricos +- Ejemplos actuales de proveedores integrados: + - Anthropic usa `api.js` / `contract-api.js` para utilidades de stream de Claude como + `wrapAnthropicProviderStream`, utilidades de encabezados beta y análisis de `service_tier`. + - OpenAI usa `api.js` para constructores de proveedores, utilidades de modelo predeterminado y + constructores de proveedores en tiempo real. + - OpenRouter usa `api.js` para su constructor de proveedor más utilidades de incorporación/configuración, + mientras que `register.runtime.js` aún puede reexportar utilidades genéricas `plugin-sdk/provider-stream` para uso local del repositorio. -- Los puntos de entrada públicos cargados mediante fachadas prefieren la instantánea activa de configuración de runtime - cuando existe una, y luego recurren al archivo de configuración resuelto en disco cuando +- Los puntos de entrada públicos cargados mediante fachada prefieren la instantánea activa de configuración de runtime + cuando existe, y en caso contrario recurren al archivo de configuración resuelto en disco cuando OpenClaw aún no está sirviendo una instantánea de runtime. -- Las primitivas genéricas compartidas siguen siendo el contrato público preferido del SDK. Aún existe - un pequeño conjunto reservado de compatibilidad de uniones helper con marca de canal incluidas. Trátalas - como uniones de compatibilidad/mantenimiento de los incluidos, no como nuevos objetivos de importación para terceros; los nuevos contratos entre canales deben seguir llegando a subrutas genéricas `plugin-sdk/*` o a los barriles locales `api.js` / - `runtime-api.js` del plugin. +- Las primitivas compartidas genéricas siguen siendo el contrato público preferido del SDK. Aún existe un pequeño conjunto reservado de uniones auxiliares de compatibilidad con marca de canal integrado. Trátalas como uniones de mantenimiento/compatibilidad integradas, no como nuevos objetivos de importación de terceros; los nuevos contratos entre canales deben seguir llegando a subrutas genéricas `plugin-sdk/*` o a los barriles locales `api.js` / `runtime-api.js` del plugin. Nota de compatibilidad: -- Evita el barril raíz `openclaw/plugin-sdk` en código nuevo. -- Prefiere primero las primitivas estables y estrechas. Las nuevas subrutas de configuración/emparejamiento/respuesta/ - feedback/contrato/inbound/threading/comando/secret-input/webhook/infra/ - allowlist/status/message-tool son el contrato previsto para trabajo nuevo - de plugins incluidos y externos. - El análisis/coincidencia de objetivos pertenece a `openclaw/plugin-sdk/channel-targets`. - Las compuertas de acciones de mensajes y los helpers de id de mensaje de reacciones pertenecen a +- Evita el barril raíz `openclaw/plugin-sdk` para código nuevo. +- Prefiere primero las primitivas estables y estrechas. Las subrutas más recientes de configuración/emparejamiento/respuesta/ + feedback/contrato/entrada/hilos/comando/secret-input/webhook/infra/ + allowlist/status/message-tool son el contrato previsto para nuevo trabajo de plugins + integrados y externos. + El análisis/coincidencia de destinos pertenece a `openclaw/plugin-sdk/channel-targets`. + Las puertas de acciones de mensajes y las utilidades de id de mensaje para reacciones pertenecen a `openclaw/plugin-sdk/channel-actions`. -- Los barriles helper específicos de extensiones incluidas no son estables por defecto. Si un - helper solo lo necesita una extensión incluida, mantenlo detrás de la unión local - `api.js` o `runtime-api.js` de la extensión en lugar de promocionarlo a +- Los barriles auxiliares específicos de extensiones integradas no son estables por defecto. Si una + utilidad solo la necesita una extensión integrada, mantenla detrás de la unión local + `api.js` o `runtime-api.js` de la extensión en lugar de promoverla a `openclaw/plugin-sdk/`. -- Las nuevas uniones helper compartidas deben ser genéricas, no con marca de canal. El análisis compartido - de objetivos pertenece a `openclaw/plugin-sdk/channel-targets`; los aspectos internos específicos del canal - permanecen detrás de la unión local `api.js` o `runtime-api.js` del plugin propietario. -- Existen subrutas específicas de capacidad como `image-generation`, - `media-understanding` y `speech` porque los plugins incluidos/nativos las usan hoy. - Su presencia no significa por sí sola que cada helper exportado sea un +- Las nuevas uniones de utilidades compartidas deben ser genéricas, no de marca de canal. El análisis + compartido de destinos pertenece a `openclaw/plugin-sdk/channel-targets`; los aspectos internos + específicos del canal deben permanecer detrás de la unión local `api.js` o `runtime-api.js` + del plugin propietario. +- Subrutas específicas de capacidad como `image-generation`, + `media-understanding` y `speech` existen porque los plugins nativos/integrados las usan hoy. Su presencia no significa por sí sola que toda utilidad exportada sea un contrato externo congelado a largo plazo. ## Esquemas de la herramienta de mensajes -Los plugins deben poseer las contribuciones de esquema específicas del canal de `describeMessageTool(...)`. +Los plugins deben poseer las contribuciones de esquema específicas del canal para `describeMessageTool(...)`. Mantén los campos específicos del proveedor en el plugin, no en el núcleo compartido. -Para fragmentos compartidos de esquema portable, reutiliza los helpers genéricos exportados a través de +Para fragmentos de esquema portables compartidos, reutiliza las utilidades genéricas exportadas a través de `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` para cargas útiles tipo cuadrícula de botones -- `createMessageToolCardSchema()` para cargas útiles estructuradas de tarjetas +- `createMessageToolButtonsSchema()` para cargas de estilo cuadrícula de botones +- `createMessageToolCardSchema()` para cargas de tarjeta estructurada Si una forma de esquema solo tiene sentido para un proveedor, defínela en el -código fuente de ese plugin en lugar de promoverla al SDK compartido. +propio código fuente de ese plugin en lugar de promoverla al SDK compartido. -## Resolución de objetivos de canal +## Resolución de destinos de canal -Los plugins de canal deben poseer la semántica de objetivos específica del canal. Mantén el host -genérico compartido de salida y usa la superficie del adaptador de mensajería para las reglas del proveedor: +Los plugins de canal deben poseer la semántica de destinos específica del canal. Mantén genérico el +host compartido de salida y usa la superficie del adaptador de mensajería para reglas del proveedor: -- `messaging.inferTargetChatType({ to })` decide si un objetivo normalizado - debe tratarse como `direct`, `group` o `channel` antes de buscar en el directorio. +- `messaging.inferTargetChatType({ to })` decide si un destino normalizado + debe tratarse como `direct`, `group` o `channel` antes de la búsqueda en directorio. - `messaging.targetResolver.looksLikeId(raw, normalized)` indica al núcleo si una entrada debe pasar directamente a resolución tipo id en lugar de búsqueda en directorio. - `messaging.targetResolver.resolveTarget(...)` es el fallback del plugin cuando - el núcleo necesita una resolución final propiedad del proveedor tras la normalización o tras un fallo de directorio. -- `messaging.resolveOutboundSessionRoute(...)` posee la construcción de rutas de sesión específicas del proveedor una vez que se resuelve un objetivo. + el núcleo necesita una resolución final propiedad del proveedor después de la normalización o tras un + fallo del directorio. +- `messaging.resolveOutboundSessionRoute(...)` posee la construcción específica del proveedor + de ruta de sesión saliente una vez resuelto un destino. División recomendada: -- Usa `inferTargetChatType` para decisiones de categoría que deban ocurrir antes - de buscar en peers/grupos. -- Usa `looksLikeId` para comprobaciones de “tratar esto como un id de objetivo explícito/nativo”. +- Usa `inferTargetChatType` para decisiones de categoría que deben ocurrir antes de + buscar pares/grupos. +- Usa `looksLikeId` para comprobaciones de "tratar esto como un id de destino explícito/nativo". - Usa `resolveTarget` para fallback de normalización específico del proveedor, no para búsqueda amplia en directorio. -- Mantén ids nativos del proveedor como ids de chat, ids de hilo, JIDs, handles e ids de sala dentro de valores `target` o parámetros específicos del proveedor, no en campos genéricos del SDK. +- Mantén ids nativos del proveedor como ids de chat, ids de hilo, JID, handles e ids de sala + dentro de valores `target` o parámetros específicos del proveedor, no en campos genéricos del SDK. ## Directorios respaldados por configuración Los plugins que derivan entradas de directorio a partir de la configuración deben mantener esa lógica en el -plugin y reutilizar los helpers compartidos de +plugin y reutilizar las utilidades compartidas de `openclaw/plugin-sdk/directory-runtime`. -Usa esto cuando un canal necesite peers/grupos respaldados por configuración como: +Usa esto cuando un canal necesita pares/grupos respaldados por configuración como: -- peers de MD impulsados por allowlist -- mapas configurados de canales/grupos -- fallbacks de directorio estáticos con alcance por cuenta +- pares de DM impulsados por allowlist +- mapas configurados de canal/grupo +- fallbacks estáticos de directorio con alcance por cuenta -Los helpers compartidos en `directory-runtime` solo manejan operaciones genéricas: +Las utilidades compartidas de `directory-runtime` solo manejan operaciones genéricas: - filtrado de consultas - aplicación de límites -- helpers de deduplicación/normalización -- creación de `ChannelDirectoryEntry[]` +- utilidades de deduplicación/normalización +- construcción de `ChannelDirectoryEntry[]` -La inspección de cuentas y la normalización de ids específicas del canal deben seguir en la implementación del plugin. +La inspección de cuentas y normalización de ids específicas del canal deben permanecer en la +implementación del plugin. ## Catálogos de proveedores -Los plugins de proveedores pueden definir catálogos de modelos para inferencia con +Los plugins de proveedor pueden definir catálogos de modelos para inferencia con `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` devuelve la misma forma que OpenClaw escribe en `models.providers`: - `{ provider }` para una entrada de proveedor -- `{ providers }` para varias entradas de proveedor +- `{ providers }` para múltiples entradas de proveedor -Usa `catalog` cuando el plugin posea ids de modelos específicos del proveedor, valores -predeterminados de URL base o metadatos de modelos limitados por autenticación. +Usa `catalog` cuando el plugin posee ids de modelo específicos del proveedor, valores predeterminados +de base URL o metadatos de modelo condicionados por autenticación. -`catalog.order` controla cuándo se fusiona el catálogo de un plugin respecto de los +`catalog.order` controla cuándo se fusiona el catálogo de un plugin en relación con los proveedores implícitos integrados de OpenClaw: -- `simple`: proveedores sencillos impulsados por API key o entorno +- `simple`: proveedores sencillos por API key o entorno - `profile`: proveedores que aparecen cuando existen perfiles de autenticación -- `paired`: proveedores que sintetizan varias entradas de proveedor relacionadas +- `paired`: proveedores que sintetizan múltiples entradas de proveedor relacionadas - `late`: última pasada, después de otros proveedores implícitos -Los proveedores posteriores ganan en colisión de claves, por lo que los plugins pueden +Los proveedores posteriores ganan en caso de colisión de claves, por lo que los plugins pueden sobrescribir intencionalmente una entrada de proveedor integrada con el mismo id de proveedor. Compatibilidad: @@ -1281,34 +1297,34 @@ Compatibilidad: - `discovery` sigue funcionando como alias heredado - si se registran tanto `catalog` como `discovery`, OpenClaw usa `catalog` -## Inspección de canal en solo lectura +## Inspección de canal de solo lectura Si tu plugin registra un canal, prefiere implementar `plugin.config.inspectAccount(cfg, accountId)` junto con `resolveAccount(...)`. Por qué: -- `resolveAccount(...)` es la ruta de runtime. Se le permite asumir que las credenciales - están totalmente materializadas y puede fallar rápido cuando faltan secretos obligatorios. +- `resolveAccount(...)` es la ruta de runtime. Puede asumir que las credenciales + están totalmente materializadas y puede fallar rápido cuando faltan secretos requeridos. - Las rutas de comandos de solo lectura como `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` y los flujos de doctor/configuración - de reparación no deberían necesitar materializar credenciales de runtime solo para + `openclaw channels status`, `openclaw channels resolve` y los flujos doctor/reparación + de configuración no deberían necesitar materializar credenciales de runtime solo para describir la configuración. -Comportamiento recomendado para `inspectAccount(...)`: +Comportamiento recomendado de `inspectAccount(...)`: -- Devuelve solo el estado descriptivo de la cuenta. +- Devuelve solo estado descriptivo de la cuenta. - Conserva `enabled` y `configured`. -- Incluye campos de origen/estado de credenciales cuando corresponda, como: +- Incluye campos de fuente/estado de credenciales cuando sean relevantes, como: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- No necesitas devolver valores brutos de tokens solo para informar disponibilidad en solo lectura. Devolver `tokenStatus: "available"` (y el campo de origen correspondiente) es suficiente para comandos tipo status. -- Usa `configured_unavailable` cuando una credencial esté configurada mediante SecretRef pero no esté disponible en la ruta de comando actual. +- No necesitas devolver valores brutos de tokens solo para informar disponibilidad de solo lectura. Devolver `tokenStatus: "available"` (y el campo de fuente correspondiente) es suficiente para comandos de estilo estado. +- Usa `configured_unavailable` cuando una credencial está configurada mediante SecretRef pero + no está disponible en la ruta de comando actual. -Esto permite que los comandos de solo lectura informen “configurado pero no disponible en esta ruta de comando” -en lugar de fallar o informar erróneamente que la cuenta no está configurada. +Esto permite que los comandos de solo lectura informen "configurado pero no disponible en esta ruta de comando" en lugar de bloquearse o informar incorrectamente que la cuenta no está configurada. ## Paquetes pack @@ -1324,18 +1340,18 @@ Un directorio de plugin puede incluir un `package.json` con `openclaw.extensions } ``` -Cada entrada se convierte en un plugin. Si el pack lista varias extensiones, el id del plugin +Cada entrada se convierte en un plugin. Si el pack enumera múltiples extensiones, el id del plugin pasa a ser `name/`. Si tu plugin importa dependencias npm, instálalas en ese directorio para que `node_modules` esté disponible (`npm install` / `pnpm install`). -Barrera de seguridad: cada entrada `openclaw.extensions` debe permanecer dentro del directorio del plugin -después de resolver symlinks. Las entradas que escapen del directorio del paquete son -rechazadas. +Protección de seguridad: cada entrada `openclaw.extensions` debe permanecer dentro del directorio del plugin +después de resolver symlinks. Las entradas que escapan del directorio del paquete se +rechazan. Nota de seguridad: `openclaw plugins install` instala dependencias de plugins con -`npm install --omit=dev --ignore-scripts` (sin scripts de ciclo de vida, sin dependencias de desarrollo en runtime). Mantén los árboles de dependencias de plugins como "JS/TS puro" y evita paquetes que requieran compilaciones en `postinstall`. +`npm install --omit=dev --ignore-scripts` (sin scripts de ciclo de vida, sin dependencias de desarrollo en runtime). Mantén los árboles de dependencias de plugins como "JS/TS puro" y evita paquetes que requieran compilaciones `postinstall`. Opcional: `openclaw.setupEntry` puede apuntar a un módulo ligero solo de configuración. Cuando OpenClaw necesita superficies de configuración para un plugin de canal deshabilitado, o @@ -1344,40 +1360,43 @@ en lugar de la entrada completa del plugin. Esto mantiene el inicio y la configu cuando la entrada principal del plugin también conecta herramientas, hooks u otro código solo de runtime. Opcional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -puede hacer que un plugin de canal use la misma ruta `setupEntry` durante la -fase de inicio previa a listen del gateway, incluso cuando el canal ya está configurado. +puede optar por que un plugin de canal use la misma ruta `setupEntry` durante la fase de inicio +previa a escuchar del gateway, incluso cuando el canal ya está configurado. -Usa esto solo cuando `setupEntry` cubra completamente la superficie de inicio que debe existir +Úsalo solo cuando `setupEntry` cubra por completo la superficie de inicio que debe existir antes de que el gateway empiece a escuchar. En la práctica, eso significa que la entrada de configuración debe registrar toda capacidad propiedad del canal de la que dependa el inicio, como: - el propio registro del canal - cualquier ruta HTTP que deba estar disponible antes de que el gateway empiece a escuchar -- cualquier método del gateway, herramienta o servicio que deba existir durante esa misma ventana +- cualquier método, herramienta o servicio del gateway que deba existir durante esa misma ventana -Si tu entrada completa sigue poseyendo alguna capacidad de inicio requerida, no habilites -esta bandera. Mantén el comportamiento predeterminado del plugin y deja que OpenClaw cargue la +Si tu entrada completa aún posee alguna capacidad de inicio requerida, no habilites +esta bandera. Mantén el plugin con el comportamiento predeterminado y deja que OpenClaw cargue la entrada completa durante el inicio. -Los canales incluidos también pueden publicar helpers de superficie contractual solo de configuración que el núcleo -puede consultar antes de que se cargue el runtime completo del canal. La superficie actual de promoción de configuración es: +Los canales integrados también pueden publicar utilidades de superficie de contrato solo de configuración que el núcleo +puede consultar antes de cargar el runtime completo del canal. La superficie actual de promoción de configuración es: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -El núcleo usa esa superficie cuando necesita promover una configuración heredada de canal de una sola cuenta a -`channels..accounts.*` sin cargar la entrada completa del plugin. -Matrix es el ejemplo incluido actual: mueve solo claves de autenticación/bootstrap a una cuenta promovida con nombre cuando ya existen cuentas con nombre, y puede preservar una clave configurada no canónica de cuenta predeterminada en lugar de crear siempre +El núcleo usa esa superficie cuando necesita promover una configuración de canal heredada de cuenta única +a `channels..accounts.*` sin cargar la entrada completa del plugin. +Matrix es el ejemplo integrado actual: mueve solo claves de autenticación/bootstrap a una +cuenta promovida con nombre cuando ya existen cuentas con nombre, y puede preservar una +clave configurada de cuenta predeterminada no canónica en lugar de crear siempre `accounts.default`. -Esos adaptadores de parches de configuración mantienen perezoso el descubrimiento de superficies contractuales incluidas. El tiempo de importación sigue siendo ligero; la superficie de promoción se carga -solo en el primer uso en lugar de reingresar al inicio del canal incluido al importar el módulo. +Esos adaptadores de parche de configuración mantienen perezoso el descubrimiento de la superficie de contrato integrada. +El tiempo de importación sigue siendo ligero; la superficie de promoción se carga solo en el primer uso +en lugar de volver a entrar en el inicio del canal integrado durante la importación del módulo. -Cuando esas superficies de inicio incluyan métodos RPC del gateway, mantenlas en un -prefijo específico del plugin. Los espacios de nombres de administración del núcleo (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) siguen reservados y siempre se resuelven -a `operator.admin`, incluso si un plugin solicita un scope más estrecho. +Cuando esas superficies de inicio incluyen métodos RPC del gateway, mantenlas en un +prefijo específico del plugin. Los espacios de nombres administrativos centrales (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) permanecen reservados y siempre se resuelven +a `operator.admin`, incluso si un plugin solicita un alcance más estrecho. Ejemplo: @@ -1397,7 +1416,7 @@ Ejemplo: ### Metadatos de catálogo de canal Los plugins de canal pueden anunciar metadatos de configuración/descubrimiento mediante `openclaw.channel` y -pistas de instalación mediante `openclaw.install`. Esto mantiene los datos de catálogo libres de núcleo. +sugerencias de instalación mediante `openclaw.install`. Esto mantiene libres de datos los catálogos del núcleo. Ejemplo: @@ -1425,22 +1444,22 @@ Ejemplo: } ``` -Campos útiles de `openclaw.channel` más allá del ejemplo mínimo: +Campos útiles de `openclaw.channel` además del ejemplo mínimo: -- `detailLabel`: etiqueta secundaria para superficies más ricas de catálogo/status -- `docsLabel`: sobrescribe el texto del enlace a la documentación -- `preferOver`: ids de plugin/canal de menor prioridad a los que esta entrada de catálogo debe superar -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controles de texto para superficies de selección +- `detailLabel`: etiqueta secundaria para superficies más ricas de catálogo/estado +- `docsLabel`: reemplaza el texto del enlace a la documentación +- `preferOver`: ids de plugin/canal de menor prioridad a los que esta entrada del catálogo debe superar +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controles de texto para la superficie de selección - `markdownCapable`: marca el canal como compatible con markdown para decisiones de formato saliente -- `exposure.configured`: oculta el canal de las superficies de listado de canales configurados cuando se establece en `false` -- `exposure.setup`: oculta el canal de los selectores interactivos de configuración cuando se establece en `false` +- `exposure.configured`: oculta el canal de superficies de lista de canales configurados cuando se establece en `false` +- `exposure.setup`: oculta el canal de selectores interactivos de configuración cuando se establece en `false` - `exposure.docs`: marca el canal como interno/privado para superficies de navegación de documentación - `showConfigured` / `showInSetup`: alias heredados aún aceptados por compatibilidad; prefiere `exposure` - `quickstartAllowFrom`: hace que el canal participe en el flujo estándar de inicio rápido `allowFrom` - `forceAccountBinding`: requiere vinculación explícita de cuenta incluso cuando solo existe una cuenta -- `preferSessionLookupForAnnounceTarget`: prefiere la búsqueda de sesión al resolver objetivos de anuncios +- `preferSessionLookupForAnnounceTarget`: prefiere búsqueda por sesión al resolver destinos de anuncio -OpenClaw también puede fusionar **catálogos externos de canales** (por ejemplo, una +OpenClaw también puede fusionar **catálogos de canales externos** (por ejemplo, una exportación de registro MPM). Coloca un archivo JSON en una de estas rutas: - `~/.openclaw/mpm/plugins.json` @@ -1448,17 +1467,17 @@ exportación de registro MPM). Coloca un archivo JSON en una de estas rutas: - `~/.openclaw/plugins/catalog.json` O apunta `OPENCLAW_PLUGIN_CATALOG_PATHS` (o `OPENCLAW_MPM_CATALOG_PATHS`) a -uno o más archivos JSON (delimitados por coma/punto y coma/`PATH`). Cada archivo debe +uno o más archivos JSON (delimitados por comas/punto y coma/`PATH`). Cada archivo debe contener `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. El analizador también acepta `"packages"` o `"plugins"` como alias heredados de la clave `"entries"`. -## Plugins de motor de contexto +## Plugins del motor de contexto -Los plugins de motor de contexto poseen la orquestación del contexto de sesión para ingesta, -ensamblaje y compactación. Regístralos desde tu plugin con -`api.registerContextEngine(id, factory)`, y luego selecciona el motor activo con +Los plugins del motor de contexto poseen la orquestación del contexto de sesión para ingesta, ensamblaje +y compactación. Regístralos desde tu plugin con +`api.registerContextEngine(id, factory)`, luego selecciona el motor activo con `plugins.slots.contextEngine`. -Usa esto cuando tu plugin necesite reemplazar o ampliar la canalización predeterminada de contexto +Usa esto cuando tu plugin necesite reemplazar o extender la canalización de contexto predeterminada en lugar de simplemente agregar búsqueda de memoria o hooks. ```ts @@ -1525,59 +1544,59 @@ export default function (api) { ## Agregar una nueva capacidad -Cuando un plugin necesite un comportamiento que no encaje en la API actual, no eludas -el sistema de plugins con un acceso privado. Agrega la capacidad faltante. +Cuando un plugin necesita comportamiento que no encaja en la API actual, no eludas +el sistema de plugins con un acceso privado. Agrega la capacidad que falta. Secuencia recomendada: -1. definir el contrato del núcleo - Decide qué comportamiento compartido debe poseer el núcleo: política, fallback, configuración - de fusión, ciclo de vida, semántica orientada al canal y forma del helper de runtime. -2. agregar superficies tipadas de registro/runtime de plugins - Extiende `OpenClawPluginApi` y/o `api.runtime` con la superficie de capacidad tipada más pequeña y útil. -3. conectar consumidores del núcleo + canal/función +1. define el contrato central + Decide qué comportamiento compartido debe poseer el núcleo: política, fallback, fusión de configuración, + ciclo de vida, semántica orientada a canales y forma de la utilidad de runtime. +2. agrega superficies tipadas de registro/runtime para plugins + Amplía `OpenClawPluginApi` y/o `api.runtime` con la superficie tipada de capacidad más pequeña útil. +3. conecta consumidores del núcleo y de canal/función Los canales y plugins de funciones deben consumir la nueva capacidad a través del núcleo, no importando directamente una implementación de proveedor. -4. registrar implementaciones de proveedores - Los plugins de proveedores registran entonces sus backends contra la capacidad. -5. agregar cobertura contractual +4. registra implementaciones de proveedores + Luego, los plugins de proveedor registran sus backends respecto de la capacidad. +5. agrega cobertura de contrato Agrega pruebas para que la propiedad y la forma del registro sigan siendo explícitas con el tiempo. -Así es como OpenClaw se mantiene con criterio sin quedar codificado de forma rígida a la visión del mundo -de un solo proveedor. Consulta [Capability Cookbook](/es/plugins/architecture) -para una lista concreta de archivos y un ejemplo trabajado. +Así es como OpenClaw se mantiene con criterio sin volverse rígido al punto de ajustarse a la +visión del mundo de un solo proveedor. Consulta el [Recetario de capacidades](/es/plugins/architecture) +para una lista concreta de archivos y un ejemplo práctico. ### Lista de verificación de capacidad -Cuando agregues una nueva capacidad, la implementación normalmente debe tocar estas -superficies a la vez: +Cuando agregas una nueva capacidad, la implementación normalmente debe tocar estas +superficies en conjunto: -- tipos de contrato del núcleo en `src//types.ts` -- ejecutor/helper de runtime del núcleo en `src//runtime.ts` -- superficie de registro de la API de plugins en `src/plugins/types.ts` -- integración del registro de plugins en `src/plugins/registry.ts` -- exposición de runtime de plugins en `src/plugins/runtime/*` cuando plugins de función/canal - necesiten consumirla -- helpers de captura/prueba en `src/test-utils/plugin-registration.ts` +- tipos del contrato central en `src//types.ts` +- runner/utilidad de runtime central en `src//runtime.ts` +- superficie de registro de API de plugins en `src/plugins/types.ts` +- cableado del registro de plugins en `src/plugins/registry.ts` +- exposición del runtime de plugins en `src/plugins/runtime/*` cuando los plugins de función/canal + necesitan consumirla +- utilidades de captura/prueba en `src/test-utils/plugin-registration.ts` - afirmaciones de propiedad/contrato en `src/plugins/contracts/registry.ts` - documentación para operadores/plugins en `docs/` -Si falta una de esas superficies, normalmente es una señal de que la capacidad todavía -no está totalmente integrada. +Si falta alguna de esas superficies, normalmente es una señal de que la capacidad +todavía no está totalmente integrada. ### Plantilla de capacidad Patrón mínimo: ```ts -// contrato del núcleo +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API del plugin +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1586,7 +1605,7 @@ api.registerVideoGenerationProvider({ }, }); -// helper compartido de runtime para plugins de función/canal +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1602,6 +1621,6 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Eso mantiene la regla simple: - el núcleo posee el contrato de capacidad + la orquestación -- los plugins de proveedores poseen las implementaciones del proveedor -- los plugins de función/canal consumen helpers de runtime +- los plugins de proveedor poseen las implementaciones del proveedor +- los plugins de función/canal consumen utilidades de runtime - las pruebas de contrato mantienen explícita la propiedad diff --git a/docs/es/plugins/manifest.md b/docs/es/plugins/manifest.md index ae5cba28b..1ed5af2ce 100644 --- a/docs/es/plugins/manifest.md +++ b/docs/es/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - Estás creando un plugin de OpenClaw - - Necesitas distribuir un esquema de configuración del plugin o depurar errores de validación del plugin + - Necesitas distribuir un esquema de configuración de plugin o depurar errores de validación de plugins summary: Manifiesto del plugin + requisitos del esquema JSON (validación estricta de configuración) title: Manifiesto del plugin x-i18n: - generated_at: "2026-04-07T05:04:40Z" + generated_at: "2026-04-09T01:28:54Z" model: gpt-5.4 provider: openai - source_hash: 22d41b9f8748b1b1b066ee856be4a8f41e88b9a8bc073d74fc79d2bb0982f01a + source_hash: 9a7ee4b621a801d2a8f32f8976b0e1d9433c7810eb360aca466031fc0ffb286a source_path: plugins/manifest.md workflow: 15 --- @@ -19,7 +19,7 @@ Esta página es solo para el **manifiesto nativo de plugins de OpenClaw**. Para diseños de paquetes compatibles, consulta [Paquetes de plugins](/es/plugins/bundles). -Los formatos de paquetes compatibles usan archivos de manifiesto distintos: +Los formatos de paquetes compatibles usan archivos de manifiesto diferentes: - Paquete Codex: `.codex-plugin/plugin.json` - Paquete Claude: `.claude-plugin/plugin.json` o el diseño predeterminado de componentes de Claude @@ -27,20 +27,20 @@ Los formatos de paquetes compatibles usan archivos de manifiesto distintos: - Paquete Cursor: `.cursor-plugin/plugin.json` OpenClaw también detecta automáticamente esos diseños de paquetes, pero no se validan -contra el esquema `openclaw.plugin.json` descrito aquí. +con el esquema `openclaw.plugin.json` descrito aquí. -Para los paquetes compatibles, OpenClaw actualmente lee los metadatos del paquete más las raíces de -Skills declaradas, las raíces de comandos de Claude, los valores predeterminados de `settings.json` del paquete Claude, -los valores predeterminados de LSP del paquete Claude y los paquetes de hooks compatibles cuando el diseño coincide -con las expectativas de ejecución de OpenClaw. +Para los paquetes compatibles, OpenClaw actualmente lee los metadatos del paquete más las +raíces de Skills declaradas, las raíces de comandos de Claude, los valores predeterminados de `settings.json` del paquete Claude, +los valores predeterminados de LSP del paquete Claude y los paquetes de hooks compatibles cuando el diseño coincide con +las expectativas del entorno de ejecución de OpenClaw. Todo plugin nativo de OpenClaw **debe** incluir un archivo `openclaw.plugin.json` en la **raíz del plugin**. OpenClaw usa este manifiesto para validar la configuración -**sin ejecutar código del plugin**. Los manifiestos ausentes o no válidos se tratan como -errores del plugin y bloquean la validación de la configuración. +**sin ejecutar el código del plugin**. Los manifiestos faltantes o no válidos se tratan como +errores del plugin y bloquean la validación de configuración. Consulta la guía completa del sistema de plugins: [Plugins](/es/tools/plugin). -Para el modelo de capacidades nativas y la guía actual de compatibilidad externa: +Para el modelo nativo de capacidades y la guía actual de compatibilidad externa: [Modelo de capacidades](/es/plugins/architecture#public-capability-model). ## Qué hace este archivo @@ -52,24 +52,24 @@ código de tu plugin. - identidad del plugin - validación de configuración -- metadatos de autenticación e incorporación que deban estar disponibles sin iniciar el - tiempo de ejecución del plugin -- metadatos de alias y activación automática que deban resolverse antes de que se cargue el tiempo de ejecución del plugin -- metadatos abreviados de propiedad de familias de modelos que deban activar automáticamente el - plugin antes de que se cargue el tiempo de ejecución -- instantáneas estáticas de propiedad de capacidades usadas para el cableado de compatibilidad integrado y +- metadatos de autenticación e incorporación que deben estar disponibles sin iniciar el + entorno de ejecución del plugin +- metadatos de alias y autoactivación que deben resolverse antes de que se cargue el entorno de ejecución del plugin +- metadatos abreviados de pertenencia de familias de modelos que deben activar automáticamente el + plugin antes de que se cargue el entorno de ejecución +- instantáneas estáticas de pertenencia de capacidades usadas para el cableado de compatibilidad incluido y la cobertura de contratos -- metadatos de configuración específicos del canal que deban fusionarse en las superficies - de catálogo y validación sin cargar el tiempo de ejecución -- pistas de UI de configuración +- metadatos de configuración específicos del canal que deben fusionarse en el catálogo y las superficies de validación + sin cargar el entorno de ejecución +- sugerencias de UI de configuración No lo uses para: - registrar comportamiento en tiempo de ejecución -- declarar entrypoints de código -- metadatos de instalación npm +- declarar puntos de entrada de código +- metadatos de instalación de npm -Eso corresponde al código de tu plugin y a `package.json`. +Eso pertenece al código de tu plugin y a `package.json`. ## Ejemplo mínimo @@ -90,7 +90,7 @@ Eso corresponde al código de tu plugin y a `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin de proveedor de OpenRouter", + "description": "Plugin de proveedor OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -100,6 +100,9 @@ Eso corresponde al código de tu plugin y a `package.json`. "providerAuthEnvVars": { "openrouter": ["OPENROUTER_API_KEY"] }, + "providerAuthAliases": { + "openrouter-coding": "openrouter" + }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, @@ -108,19 +111,19 @@ Eso corresponde al código de tu plugin y a `package.json`. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "Clave de API de OpenRouter", + "choiceLabel": "Clave API de OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "Clave de API de OpenRouter", + "cliDescription": "Clave API de OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "Clave de API", + "label": "Clave API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -141,61 +144,62 @@ Eso corresponde al código de tu plugin y a `package.json`. | Field | Required | Type | What it means | | ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Sí | `string` | ID canónico del plugin. Este es el ID usado en `plugins.entries.`. | +| `id` | Sí | `string` | Id canónico del plugin. Este es el id usado en `plugins.entries.`. | | `configSchema` | Sí | `object` | JSON Schema en línea para la configuración de este plugin. | -| `enabledByDefault` | No | `true` | Marca un plugin integrado como habilitado de forma predeterminada. Omítelo, o establece cualquier valor distinto de `true`, para dejar el plugin deshabilitado de forma predeterminada. | -| `legacyPluginIds` | No | `string[]` | IDs heredados que se normalizan a este ID canónico del plugin. | -| `autoEnableWhenConfiguredProviders` | No | `string[]` | IDs de proveedor que deberían habilitar automáticamente este plugin cuando la autenticación, la configuración o las referencias de modelo los mencionen. | -| `kind` | No | `"memory"` \| `"context-engine"` | Declara un tipo exclusivo de plugin usado por `plugins.slots.*`. | -| `channels` | No | `string[]` | IDs de canal controlados por este plugin. Se usan para descubrimiento y validación de configuración. | -| `providers` | No | `string[]` | IDs de proveedor controlados por este plugin. | -| `modelSupport` | No | `object` | Metadatos abreviados de familia de modelos controlados por el manifiesto usados para cargar automáticamente el plugin antes del tiempo de ejecución. | -| `cliBackends` | No | `string[]` | IDs de backend de inferencia de CLI controlados por este plugin. Se usan para la activación automática al inicio a partir de referencias explícitas de configuración. | -| `providerAuthEnvVars` | No | `Record` | Metadatos ligeros de autenticación de proveedor en variables de entorno que OpenClaw puede inspeccionar sin cargar el código del plugin. | -| `channelEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno del canal que OpenClaw puede inspeccionar sin cargar el código del plugin. Usa esto para superficies de configuración o autenticación de canal basadas en entorno que los ayudantes genéricos de inicio/configuración deberían ver. | -| `providerAuthChoices` | No | `object[]` | Metadatos ligeros de opciones de autenticación para selectores de incorporación, resolución de proveedor preferido y cableado simple de flags de CLI. | -| `contracts` | No | `object` | Instantánea estática de capacidades integradas para voz, transcripción en tiempo real, voz en tiempo real, comprensión multimedia, generación de imágenes, generación de música, generación de video, web-fetch, búsqueda web y propiedad de herramientas. | -| `channelConfigs` | No | `Record` | Metadatos de configuración de canal controlados por el manifiesto que se fusionan en las superficies de descubrimiento y validación antes de que se cargue el tiempo de ejecución. | -| `skills` | No | `string[]` | Directorios de Skills que se deben cargar, relativos a la raíz del plugin. | -| `name` | No | `string` | Nombre legible del plugin. | -| `description` | No | `string` | Resumen breve mostrado en las superficies del plugin. | -| `version` | No | `string` | Versión informativa del plugin. | -| `uiHints` | No | `Record` | Etiquetas de UI, placeholders y pistas de sensibilidad para campos de configuración. | +| `enabledByDefault` | No | `true` | Marca un plugin incluido como habilitado de forma predeterminada. Omítelo, o establece cualquier valor distinto de `true`, para dejar el plugin deshabilitado de forma predeterminada. | +| `legacyPluginIds` | No | `string[]` | Id heredados que se normalizan a este id canónico de plugin. | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | Id de proveedores que deben autohabilitar este plugin cuando la autenticación, la configuración o las referencias de modelos los mencionan. | +| `kind` | No | `"memory"` \| `"context-engine"` | Declara un tipo exclusivo de plugin usado por `plugins.slots.*`. | +| `channels` | No | `string[]` | Id de canales propiedad de este plugin. Se usan para descubrimiento y validación de configuración. | +| `providers` | No | `string[]` | Id de proveedores propiedad de este plugin. | +| `modelSupport` | No | `object` | Metadatos abreviados de familias de modelos propiedad del manifiesto usados para cargar automáticamente el plugin antes del entorno de ejecución. | +| `cliBackends` | No | `string[]` | Id de backends de inferencia por CLI propiedad de este plugin. Se usan para la autoactivación al inicio a partir de referencias explícitas en la configuración. | +| `providerAuthEnvVars` | No | `Record` | Metadatos ligeros de autenticación del proveedor mediante variables de entorno que OpenClaw puede inspeccionar sin cargar el código del plugin. | +| `providerAuthAliases` | No | `Record` | Id de proveedores que deben reutilizar otro id de proveedor para la búsqueda de autenticación, por ejemplo un proveedor de programación que comparte la clave API y los perfiles de autenticación del proveedor base. | +| `channelEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno del canal que OpenClaw puede inspeccionar sin cargar el código del plugin. Usa esto para configuraciones de canal guiadas por entorno o superficies de autenticación que los ayudantes genéricos de inicio/configuración deberían ver. | +| `providerAuthChoices` | No | `object[]` | Metadatos ligeros de opciones de autenticación para selectores de incorporación, resolución de proveedores preferidos y cableado sencillo de banderas CLI. | +| `contracts` | No | `object` | Instantánea estática de capacidades incluidas para voz, transcripción en tiempo real, voz en tiempo real, comprensión de medios, generación de imágenes, generación musical, generación de video, web-fetch, búsqueda web y propiedad de herramientas. | +| `channelConfigs` | No | `Record` | Metadatos de configuración de canal propiedad del manifiesto fusionados en las superficies de descubrimiento y validación antes de que se cargue el entorno de ejecución. | +| `skills` | No | `string[]` | Directorios de Skills que se cargarán, relativos a la raíz del plugin. | +| `name` | No | `string` | Nombre legible del plugin. | +| `description` | No | `string` | Resumen corto mostrado en superficies del plugin. | +| `version` | No | `string` | Versión informativa del plugin. | +| `uiHints` | No | `Record` | Etiquetas de UI, marcadores de posición y sugerencias de sensibilidad para campos de configuración. | ## Referencia de `providerAuthChoices` Cada entrada de `providerAuthChoices` describe una opción de incorporación o autenticación. -OpenClaw la lee antes de que se cargue el tiempo de ejecución del proveedor. +OpenClaw la lee antes de que se cargue el entorno de ejecución del proveedor. | Field | Required | Type | What it means | | --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Sí | `string` | ID del proveedor al que pertenece esta opción. | -| `method` | Sí | `string` | ID del método de autenticación al que se enviará. | -| `choiceId` | Sí | `string` | ID estable de opción de autenticación usado por los flujos de incorporación y CLI. | -| `choiceLabel` | No | `string` | Etiqueta visible para el usuario. Si se omite, OpenClaw usa `choiceId` como respaldo. | -| `choiceHint` | No | `string` | Texto de ayuda breve para el selector. | -| `assistantPriority` | No | `number` | Los valores más bajos se ordenan antes en los selectores interactivos guiados por el asistente. | -| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción en los selectores del asistente, pero sigue permitiendo la selección manual por CLI. | -| `deprecatedChoiceIds` | No | `string[]` | IDs heredados de opciones que deberían redirigir a los usuarios a esta opción de reemplazo. | -| `groupId` | No | `string` | ID de grupo opcional para agrupar opciones relacionadas. | +| `provider` | Sí | `string` | Id del proveedor al que pertenece esta opción. | +| `method` | Sí | `string` | Id del método de autenticación al que se enviará. | +| `choiceId` | Sí | `string` | Id estable de opción de autenticación usado por los flujos de incorporación y CLI. | +| `choiceLabel` | No | `string` | Etiqueta visible para el usuario. Si se omite, OpenClaw usa `choiceId` como valor alternativo. | +| `choiceHint` | No | `string` | Texto de ayuda corto para el selector. | +| `assistantPriority` | No | `number` | Los valores más bajos se ordenan antes en los selectores interactivos controlados por el asistente. | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción de los selectores del asistente, pero sigue permitiendo la selección manual por CLI. | +| `deprecatedChoiceIds` | No | `string[]` | Id heredados de opciones que deben redirigir a los usuarios a esta opción de reemplazo. | +| `groupId` | No | `string` | Id de grupo opcional para agrupar opciones relacionadas. | | `groupLabel` | No | `string` | Etiqueta visible para el usuario de ese grupo. | -| `groupHint` | No | `string` | Texto de ayuda breve para el grupo. | -| `optionKey` | No | `string` | Clave de opción interna para flujos simples de autenticación con un solo flag. | -| `cliFlag` | No | `string` | Nombre del flag de CLI, como `--openrouter-api-key`. | -| `cliOption` | No | `string` | Forma completa de la opción de CLI, como `--openrouter-api-key `. | -| `cliDescription` | No | `string` | Descripción usada en la ayuda de CLI. | +| `groupHint` | No | `string` | Texto de ayuda corto para el grupo. | +| `optionKey` | No | `string` | Clave interna de opción para flujos de autenticación simples de una sola bandera. | +| `cliFlag` | No | `string` | Nombre de la bandera CLI, como `--openrouter-api-key`. | +| `cliOption` | No | `string` | Forma completa de la opción CLI, como `--openrouter-api-key `. | +| `cliDescription` | No | `string` | Descripción usada en la ayuda de la CLI. | | `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | En qué superficies de incorporación debe aparecer esta opción. Si se omite, el valor predeterminado es `["text-inference"]`. | ## Referencia de `uiHints` -`uiHints` es un mapa de nombres de campos de configuración a pequeñas pistas de renderizado. +`uiHints` es un mapa de nombres de campos de configuración a pequeñas sugerencias de representación. ```json { "uiHints": { "apiKey": { - "label": "Clave de API", - "help": "Se usa para solicitudes de OpenRouter", + "label": "Clave API", + "help": "Se usa para solicitudes a OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -203,21 +207,21 @@ OpenClaw la lee antes de que se cargue el tiempo de ejecución del proveedor. } ``` -Cada pista de campo puede incluir: +Cada sugerencia de campo puede incluir: | Field | Type | What it means | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | Etiqueta del campo visible para el usuario. | -| `help` | `string` | Texto de ayuda breve. | +| `help` | `string` | Texto de ayuda corto. | | `tags` | `string[]` | Etiquetas opcionales de UI. | | `advanced` | `boolean` | Marca el campo como avanzado. | | `sensitive` | `boolean` | Marca el campo como secreto o sensible. | -| `placeholder` | `string` | Texto de placeholder para entradas de formularios. | +| `placeholder` | `string` | Texto de marcador de posición para entradas de formulario. | ## Referencia de `contracts` -Usa `contracts` solo para metadatos estáticos de propiedad de capacidades que OpenClaw pueda -leer sin importar el tiempo de ejecución del plugin. +Usa `contracts` solo para metadatos estáticos de propiedad de capacidades que OpenClaw puede +leer sin importar el entorno de ejecución del plugin. ```json { @@ -239,20 +243,20 @@ Cada lista es opcional: | Field | Type | What it means | | -------------------------------- | ---------- | -------------------------------------------------------------- | -| `speechProviders` | `string[]` | IDs de proveedor de voz que controla este plugin. | -| `realtimeTranscriptionProviders` | `string[]` | IDs de proveedor de transcripción en tiempo real que controla este plugin. | -| `realtimeVoiceProviders` | `string[]` | IDs de proveedor de voz en tiempo real que controla este plugin. | -| `mediaUnderstandingProviders` | `string[]` | IDs de proveedor de comprensión multimedia que controla este plugin. | -| `imageGenerationProviders` | `string[]` | IDs de proveedor de generación de imágenes que controla este plugin. | -| `videoGenerationProviders` | `string[]` | IDs de proveedor de generación de video que controla este plugin. | -| `webFetchProviders` | `string[]` | IDs de proveedor de web-fetch que controla este plugin. | -| `webSearchProviders` | `string[]` | IDs de proveedor de búsqueda web que controla este plugin. | -| `tools` | `string[]` | Nombres de herramientas del agente que controla este plugin para comprobaciones integradas de contratos. | +| `speechProviders` | `string[]` | Id de proveedores de voz propiedad de este plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Id de proveedores de transcripción en tiempo real propiedad de este plugin. | +| `realtimeVoiceProviders` | `string[]` | Id de proveedores de voz en tiempo real propiedad de este plugin. | +| `mediaUnderstandingProviders` | `string[]` | Id de proveedores de comprensión de medios propiedad de este plugin. | +| `imageGenerationProviders` | `string[]` | Id de proveedores de generación de imágenes propiedad de este plugin. | +| `videoGenerationProviders` | `string[]` | Id de proveedores de generación de video propiedad de este plugin. | +| `webFetchProviders` | `string[]` | Id de proveedores de web-fetch propiedad de este plugin. | +| `webSearchProviders` | `string[]` | Id de proveedores de búsqueda web propiedad de este plugin. | +| `tools` | `string[]` | Nombres de herramientas del agente propiedad de este plugin para verificaciones de contratos incluidos. | ## Referencia de `channelConfigs` -Usa `channelConfigs` cuando un plugin de canal necesite metadatos de configuración ligeros antes de que -se cargue el tiempo de ejecución. +Usa `channelConfigs` cuando un plugin de canal necesita metadatos ligeros de configuración antes de que +se cargue el entorno de ejecución. ```json { @@ -283,16 +287,16 @@ Cada entrada de canal puede incluir: | Field | Type | What it means | | ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema para `channels.`. Obligatorio para cada entrada de configuración de canal declarada. | -| `uiHints` | `Record` | Etiquetas/placeholders/pistas de sensibilidad de UI opcionales para esa sección de configuración del canal. | -| `label` | `string` | Etiqueta del canal fusionada en superficies de selector e inspección cuando los metadatos de tiempo de ejecución no están listos. | -| `description` | `string` | Descripción breve del canal para superficies de inspección y catálogo. | -| `preferOver` | `string[]` | IDs heredados o de menor prioridad de plugins que este canal debe superar en las superficies de selección. | +| `schema` | `object` | JSON Schema para `channels.`. Obligatorio para cada entrada declarada de configuración de canal. | +| `uiHints` | `Record` | Etiquetas/placeholders/sugerencias de sensibilidad opcionales de UI para esa sección de configuración del canal. | +| `label` | `string` | Etiqueta del canal fusionada en las superficies de selector e inspección cuando los metadatos del entorno de ejecución no están listos. | +| `description` | `string` | Descripción corta del canal para las superficies de inspección y catálogo. | +| `preferOver` | `string[]` | Id de plugins heredados o de menor prioridad que este canal debe superar en las superficies de selección. | ## Referencia de `modelSupport` Usa `modelSupport` cuando OpenClaw deba inferir tu plugin de proveedor a partir de -IDs abreviados de modelo como `gpt-5.4` o `claude-sonnet-4.6` antes de que se cargue el tiempo de ejecución del plugin. +id abreviados de modelos como `gpt-5.4` o `claude-sonnet-4.6` antes de que se cargue el entorno de ejecución del plugin. ```json { @@ -305,73 +309,74 @@ IDs abreviados de modelo como `gpt-5.4` o `claude-sonnet-4.6` antes de que se ca OpenClaw aplica esta precedencia: -- las referencias explícitas `provider/model` usan los metadatos de manifiesto `providers` del propietario +- las referencias explícitas `provider/model` usan los metadatos del manifiesto `providers` propietario - `modelPatterns` tienen prioridad sobre `modelPrefixes` -- si coinciden un plugin no integrado y uno integrado, gana el plugin no integrado -- la ambigüedad restante se ignora hasta que el usuario o la configuración especifiquen un proveedor +- si coinciden un plugin no incluido y un plugin incluido, el plugin no incluido + gana +- la ambigüedad restante se ignora hasta que el usuario o la configuración especifique un proveedor Campos: | Field | Type | What it means | | --------------- | ---------- | ------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Prefijos comparados con `startsWith` frente a IDs abreviados de modelo. | -| `modelPatterns` | `string[]` | Fuentes regex comparadas con IDs abreviados de modelo después de eliminar el sufijo del perfil. | +| `modelPrefixes` | `string[]` | Prefijos comparados con `startsWith` frente a id abreviados de modelos. | +| `modelPatterns` | `string[]` | Fuentes regex comparadas con id abreviados de modelos tras eliminar el sufijo del perfil. | Las claves heredadas de capacidades de nivel superior están obsoletas. Usa `openclaw doctor --fix` para mover `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` y `webSearchProviders` bajo `contracts`; la carga normal -del manifiesto ya no trata esos campos de nivel superior como propiedad -de capacidades. +del manifiesto ya no trata esos campos de nivel superior como +propiedad de capacidades. ## Manifiesto frente a package.json -Los dos archivos tienen funciones distintas: +Los dos archivos cumplen funciones distintas: | File | Use it for | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Descubrimiento, validación de configuración, metadatos de opciones de autenticación y pistas de UI que deben existir antes de que se ejecute el código del plugin | -| `package.json` | Metadatos npm, instalación de dependencias y el bloque `openclaw` usado para entrypoints, control de instalación, configuración o metadatos de catálogo | +| `openclaw.plugin.json` | Descubrimiento, validación de configuración, metadatos de opciones de autenticación y sugerencias de UI que deben existir antes de que se ejecute el código del plugin | +| `package.json` | Metadatos de npm, instalación de dependencias y el bloque `openclaw` usado para puntos de entrada, control de instalación, configuración o metadatos de catálogo | -Si no tienes claro dónde debe ir un dato, usa esta regla: +Si no estás seguro de dónde debe ir un dato, usa esta regla: -- si OpenClaw debe conocerlo antes de cargar el código del plugin, colócalo en `openclaw.plugin.json` -- si trata sobre empaquetado, archivos de entrada o comportamiento de instalación npm, colócalo en `package.json` +- si OpenClaw debe conocerlo antes de cargar el código del plugin, ponlo en `openclaw.plugin.json` +- si trata sobre empaquetado, archivos de entrada o comportamiento de instalación de npm, ponlo en `package.json` ### Campos de package.json que afectan al descubrimiento -Algunos metadatos del plugin previos al tiempo de ejecución viven intencionadamente en `package.json` dentro del +Algunos metadatos del plugin previos al entorno de ejecución viven intencionalmente en `package.json` bajo el bloque `openclaw` en lugar de `openclaw.plugin.json`. Ejemplos importantes: | Field | What it means | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Declara entrypoints nativos del plugin. | -| `openclaw.setupEntry` | Entrypoint ligero solo de configuración usado durante la incorporación y el inicio diferido de canales. | +| `openclaw.extensions` | Declara puntos de entrada nativos del plugin. | +| `openclaw.setupEntry` | Punto de entrada ligero solo para configuración usado durante la incorporación y el arranque diferido del canal. | | `openclaw.channel` | Metadatos ligeros del catálogo de canales, como etiquetas, rutas de documentación, alias y texto de selección. | -| `openclaw.channel.configuredState` | Metadatos ligeros del comprobador de estado configurado que pueden responder a "¿ya existe una configuración solo con entorno?" sin cargar el tiempo de ejecución completo del canal. | -| `openclaw.channel.persistedAuthState` | Metadatos ligeros del comprobador de autenticación persistida que pueden responder a "¿ya hay algo con sesión iniciada?" sin cargar el tiempo de ejecución completo del canal. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Pistas de instalación/actualización para plugins integrados y publicados externamente. | -| `openclaw.install.defaultChoice` | Ruta de instalación preferida cuando hay varias fuentes de instalación disponibles. | -| `openclaw.install.minHostVersion` | Versión mínima compatible del host de OpenClaw, usando un piso semver como `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Permite una ruta de recuperación de reinstalación limitada para plugins integrados cuando la configuración no es válida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies del canal solo de configuración se carguen antes del plugin completo del canal durante el inicio. | +| `openclaw.channel.configuredState` | Metadatos ligeros del verificador de estado configurado que pueden responder “¿ya existe una configuración solo por entorno?” sin cargar el entorno de ejecución completo del canal. | +| `openclaw.channel.persistedAuthState` | Metadatos ligeros del verificador de autenticación persistida que pueden responder “¿ya hay algo con sesión iniciada?” sin cargar el entorno de ejecución completo del canal. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Sugerencias de instalación/actualización para plugins incluidos y publicados externamente. | +| `openclaw.install.defaultChoice` | Ruta de instalación preferida cuando hay varias fuentes de instalación disponibles. | +| `openclaw.install.minHostVersion` | Versión mínima compatible del host de OpenClaw, usando un umbral semver como `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Permite una ruta limitada de recuperación por reinstalación de plugins incluidos cuando la configuración no es válida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies de canal solo de configuración se carguen antes que el plugin de canal completo durante el arranque. | -`openclaw.install.minHostVersion` se aplica durante la instalación y la carga del registro -del manifiesto. Los valores no válidos se rechazan; los valores válidos pero más recientes omiten el +`openclaw.install.minHostVersion` se aplica durante la instalación y la carga del +registro de manifiestos. Los valores no válidos se rechazan; los valores válidos pero más recientes omiten el plugin en hosts más antiguos. -`openclaw.install.allowInvalidConfigRecovery` es intencionadamente limitado. No -hace instalables configuraciones rotas arbitrarias. Hoy solo permite que los flujos de instalación -se recuperen de fallos concretos de actualización de plugins integrados obsoletos, como una -ruta faltante del plugin integrado o una entrada obsoleta `channels.` para ese mismo -plugin integrado. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores +`openclaw.install.allowInvalidConfigRecovery` es intencionalmente limitado. No +permite instalar configuraciones arbitrariamente rotas. Actualmente solo permite que los flujos de instalación +se recuperen de errores concretos de actualización obsoleta de plugins incluidos, como una +ruta faltante del plugin incluido o una entrada obsoleta `channels.` para ese mismo +plugin incluido. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores a `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` es un metadato de paquete para un módulo -comprobador diminuto: +`openclaw.channel.persistedAuthState` son metadatos de paquete para un módulo +verificador diminuto: ```json { @@ -387,13 +392,13 @@ comprobador diminuto: } ``` -Úsalo cuando los flujos de configuración, doctor o estado configurado necesiten una sonda de autenticación -ligera de sí/no antes de que se cargue el plugin completo del canal. La exportación de destino debe ser una -función pequeña que lea solo el estado persistido; no la encamines a través del barrel completo -de tiempo de ejecución del canal. +Úsalo cuando los flujos de configuración, doctor o estado configurado necesiten una sonda barata de autenticación sí/no +antes de que se cargue el plugin completo del canal. La exportación de destino debe ser una función pequeña +que lea solo el estado persistido; no la enrutes a través del barrel completo del entorno de ejecución +del canal. -`openclaw.channel.configuredState` sigue la misma forma para comprobaciones ligeras -de estado configurado solo con entorno: +`openclaw.channel.configuredState` sigue la misma forma para verificaciones ligeras +de estado configurado solo por entorno: ```json { @@ -409,10 +414,9 @@ de estado configurado solo con entorno: } ``` -Úsalo cuando un canal pueda responder al estado configurado desde el entorno u otras entradas -mínimas no relacionadas con el tiempo de ejecución. Si la comprobación necesita resolución completa de configuración o el -tiempo de ejecución real del canal, mantén esa lógica en el hook `config.hasConfiguredState` -del plugin. +Úsalo cuando un canal pueda responder el estado configurado desde el entorno u otras +entradas mínimas ajenas al entorno de ejecución. Si la verificación necesita la resolución completa de configuración o el +entorno de ejecución real del canal, deja esa lógica en el hook del plugin `config.hasConfiguredState`. ## Requisitos de JSON Schema @@ -422,49 +426,52 @@ del plugin. ## Comportamiento de validación -- Las claves desconocidas `channels.*` son **errores**, salvo que el ID del canal esté declarado por +- Las claves desconocidas `channels.*` son **errores**, a menos que el id del canal esté declarado por un manifiesto de plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` y `plugins.slots.*` - deben hacer referencia a IDs de plugin **detectables**. Los IDs desconocidos son **errores**. -- Si un plugin está instalado pero tiene un manifiesto o esquema roto o ausente, + deben hacer referencia a id de plugins **detectables**. Los id desconocidos son **errores**. +- Si un plugin está instalado pero tiene un manifiesto o esquema roto o faltante, la validación falla y Doctor informa del error del plugin. - Si existe configuración del plugin pero el plugin está **deshabilitado**, la configuración se conserva y - se muestra una **advertencia** en Doctor + los registros. + se muestra una **advertencia** en Doctor + registros. Consulta [Referencia de configuración](/es/gateway/configuration) para ver el esquema completo de `plugins.*`. ## Notas - El manifiesto es **obligatorio para los plugins nativos de OpenClaw**, incluidas las cargas desde el sistema de archivos local. -- El tiempo de ejecución sigue cargando el módulo del plugin por separado; el manifiesto es solo para +- El entorno de ejecución sigue cargando el módulo del plugin por separado; el manifiesto es solo para descubrimiento + validación. - Los manifiestos nativos se analizan con JSON5, por lo que se aceptan comentarios, comas finales y claves sin comillas siempre que el valor final siga siendo un objeto. -- El cargador de manifiestos solo lee los campos de manifiesto documentados. Evita añadir +- El cargador de manifiestos solo lee los campos documentados del manifiesto. Evita agregar aquí claves personalizadas de nivel superior. -- `providerAuthEnvVars` es la ruta ligera de metadatos para sondas de autenticación, validación - de marcadores de entorno y superficies similares de autenticación de proveedor que no deberían iniciar el - tiempo de ejecución del plugin solo para inspeccionar nombres de variables de entorno. -- `channelEnvVars` es la ruta ligera de metadatos para respaldo de variables de entorno del shell, prompts - de configuración y superficies similares de canal que no deberían iniciar el tiempo de ejecución del plugin - solo para inspeccionar nombres de variables de entorno. -- `providerAuthChoices` es la ruta ligera de metadatos para selectores de opciones de autenticación, - resolución de `--auth-choice`, asignación de proveedor preferido y registro simple - de flags de CLI de incorporación antes de que se cargue el tiempo de ejecución del proveedor. Para metadatos - del asistente en tiempo de ejecución que requieran código del proveedor, consulta - [Hooks de tiempo de ejecución del proveedor](/es/plugins/architecture#provider-runtime-hooks). -- Los tipos exclusivos de plugins se seleccionan mediante `plugins.slots.*`. +- `providerAuthEnvVars` es la ruta de metadatos ligera para sondeos de autenticación, validación + de marcadores de entorno y superficies similares de autenticación del proveedor que no deberían iniciar el entorno de ejecución del plugin + solo para inspeccionar nombres de entorno. +- `providerAuthAliases` permite que variantes de proveedores reutilicen la autenticación + por variables de entorno, perfiles de autenticación, autenticación respaldada por configuración y la opción de incorporación + por clave API de otro proveedor sin codificar esa relación en el núcleo. +- `channelEnvVars` es la ruta de metadatos ligera para fallback de entorno de shell, prompts + de configuración y superficies de canal similares que no deberían iniciar el entorno de ejecución del plugin + solo para inspeccionar nombres de entorno. +- `providerAuthChoices` es la ruta de metadatos ligera para selectores de opciones de autenticación, + resolución de `--auth-choice`, mapeo de proveedores preferidos y registro simple + de banderas CLI de incorporación antes de que se cargue el entorno de ejecución del proveedor. Para metadatos de asistente en tiempo de ejecución + que requieren código del proveedor, consulta + [Hooks de runtime del proveedor](/es/plugins/architecture#provider-runtime-hooks). +- Los tipos exclusivos de plugin se seleccionan mediante `plugins.slots.*`. - `kind: "memory"` se selecciona mediante `plugins.slots.memory`. - `kind: "context-engine"` se selecciona mediante `plugins.slots.contextEngine` (predeterminado: `legacy` integrado). - `channels`, `providers`, `cliBackends` y `skills` pueden omitirse cuando un - plugin no los necesite. + plugin no los necesita. - Si tu plugin depende de módulos nativos, documenta los pasos de compilación y cualquier - requisito de lista permitida del gestor de paquetes (por ejemplo, pnpm `allow-build-scripts` + requisito de lista de permitidos del administrador de paquetes (por ejemplo, pnpm `allow-build-scripts` - `pnpm rebuild `). ## Relacionado -- [Building Plugins](/es/plugins/building-plugins) — primeros pasos con plugins -- [Plugin Architecture](/es/plugins/architecture) — arquitectura interna -- [SDK Overview](/es/plugins/sdk-overview) — referencia del SDK de plugins +- [Creación de plugins](/es/plugins/building-plugins) — introducción a los plugins +- [Arquitectura de plugins](/es/plugins/architecture) — arquitectura interna +- [Resumen del SDK](/es/plugins/sdk-overview) — referencia del SDK de plugins diff --git a/docs/es/plugins/sdk-migration.md b/docs/es/plugins/sdk-migration.md index d93892d0e..9718076b8 100644 --- a/docs/es/plugins/sdk-migration.md +++ b/docs/es/plugins/sdk-migration.md @@ -5,40 +5,40 @@ read_when: - Estás actualizando un plugin a la arquitectura moderna de plugins - Mantienes un plugin externo de OpenClaw sidebarTitle: Migrate to SDK -summary: Migra desde la capa heredada de compatibilidad hacia atrás al moderno plugin SDK -title: Migración del Plugin SDK +summary: Migra desde la capa heredada de compatibilidad retroactiva al SDK de plugins moderno +title: Migración del SDK de plugins x-i18n: - generated_at: "2026-04-08T02:17:07Z" + generated_at: "2026-04-09T01:30:19Z" model: gpt-5.4 provider: openai - source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad + source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07 source_path: plugins/sdk-migration.md workflow: 15 --- -# Migración del Plugin SDK +# Migración del SDK de plugins -OpenClaw ha pasado de una amplia capa de compatibilidad hacia atrás a una arquitectura -moderna de plugins con importaciones enfocadas y documentadas. Si tu plugin se creó antes -de la nueva arquitectura, esta guía te ayuda a migrarlo. +OpenClaw ha pasado de una capa amplia de compatibilidad retroactiva a una arquitectura moderna de plugins +con importaciones específicas y documentadas. Si tu plugin se creó antes de +la nueva arquitectura, esta guía te ayudará a migrarlo. ## Qué está cambiando El sistema anterior de plugins proporcionaba dos superficies muy abiertas que permitían a los plugins importar -cualquier cosa que necesitaran desde un único punto de entrada: +todo lo que necesitaran desde un único punto de entrada: - **`openclaw/plugin-sdk/compat`** — una sola importación que reexportaba decenas de - helpers. Se introdujo para mantener en funcionamiento plugins más antiguos basados en hooks mientras se + ayudantes. Se introdujo para mantener funcionando los plugins basados en hooks más antiguos mientras se construía la nueva arquitectura de plugins. - **`openclaw/extension-api`** — un puente que daba a los plugins acceso directo a - helpers del lado del host, como el ejecutor de agente embebido. + ayudantes del lado del host, como el ejecutor de agentes integrado. -Ambas superficies ahora están **obsoletas**. Siguen funcionando en tiempo de ejecución, pero los -plugins nuevos no deben usarlas, y los plugins existentes deberían migrar antes de que la próxima +Ambas superficies ahora están **obsoletas**. Siguen funcionando en tiempo de ejecución, pero los plugins +nuevos no deben usarlas, y los plugins existentes deberían migrar antes de que la próxima versión principal las elimine. - La capa de compatibilidad hacia atrás se eliminará en una futura versión principal. + La capa de compatibilidad retroactiva se eliminará en una futura versión principal. Los plugins que sigan importando desde estas superficies dejarán de funcionar cuando eso ocurra. @@ -46,64 +46,63 @@ versión principal las elimine. El enfoque anterior causaba problemas: -- **Inicio lento** — importar un helper cargaba decenas de módulos no relacionados +- **Inicio lento** — importar un ayudante cargaba decenas de módulos no relacionados - **Dependencias circulares** — las reexportaciones amplias facilitaban la creación de ciclos de importación -- **Superficie API poco clara** — no había forma de saber qué exportaciones eran estables y cuáles eran internas +- **Superficie de API poco clara** — no había forma de saber qué exportaciones eran estables y cuáles eran internas -El moderno plugin SDK soluciona esto: cada ruta de importación (`openclaw/plugin-sdk/\`) -es un módulo pequeño, autocontenido, con un propósito claro y un contrato documentado. +El SDK de plugins moderno corrige esto: cada ruta de importación (`openclaw/plugin-sdk/\`) +es un módulo pequeño, autónomo, con un propósito claro y un contrato documentado. -Las superficies heredadas de conveniencia para proveedores de canales empaquetados también han desaparecido. Las importaciones +Las uniones heredadas de conveniencia para proveedores de canales incluidos también han desaparecido. Importaciones como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -las superficies helper con marca de canal y +las uniones de ayudantes con marca de canal y `openclaw/plugin-sdk/telegram-core` eran atajos privados del monorepo, no -contratos estables para plugins. Usa en su lugar subrutas genéricas y específicas del SDK. Dentro del -espacio de trabajo de plugins empaquetados, mantén los helpers propiedad del proveedor en el propio +contratos estables de plugins. Usa en su lugar subrutas genéricas y estrechas del SDK. Dentro del +espacio de trabajo de plugins incluidos, conserva los ayudantes propios del proveedor en el `api.ts` o `runtime-api.ts` de ese plugin. -Ejemplos actuales de proveedores empaquetados: +Ejemplos actuales de proveedores incluidos: -- Anthropic mantiene helpers de flujo específicos de Claude en su propia superficie `api.ts` / +- Anthropic mantiene los ayudantes de streaming específicos de Claude en su propia unión `api.ts` / `contract-api.ts` -- OpenAI mantiene constructores de proveedores, helpers de modelos predeterminados y constructores de proveedores - realtime en su propio `api.ts` -- OpenRouter mantiene el constructor del proveedor y los helpers de onboarding/configuración en su propio +- OpenAI mantiene los constructores de proveedores, los ayudantes de modelos predeterminados y los constructores + de proveedores en tiempo real en su propio `api.ts` +- OpenRouter mantiene el constructor del proveedor y los ayudantes de incorporación/configuración en su propio `api.ts` ## Cómo migrar - + Los plugins de canal con capacidad de aprobación ahora exponen el comportamiento nativo de aprobación mediante - `approvalCapability.nativeRuntime` más el registro compartido de contexto de runtime. + `approvalCapability.nativeRuntime` más el registro compartido de contexto de ejecución. - Cambios clave: + Cambios principales: - Reemplaza `approvalCapability.handler.loadRuntime(...)` por `approvalCapability.nativeRuntime` - - Mueve la autenticación/entrega específica de aprobación fuera del cableado heredado `plugin.auth` / - `plugin.approvals` y colócalo en `approvalCapability` - - `ChannelPlugin.approvals` se ha eliminado del contrato público - de plugins de canal; mueve los campos delivery/native/render a `approvalCapability` - - `plugin.auth` se mantiene solo para flujos de login/logout del canal; los hooks de autenticación - de aprobación allí ya no son leídos por el núcleo - - Registra objetos de runtime propiedad del canal, como clientes, tokens o apps Bolt, - mediante `openclaw/plugin-sdk/channel-runtime-context` - - No envíes avisos de redirección propiedad del plugin desde handlers nativos de aprobación; - el núcleo ahora se encarga de los avisos de enrutado a otro lugar a partir de resultados reales de entrega + - Mueve la autenticación/entrega específica de aprobaciones fuera del cableado heredado `plugin.auth` / + `plugin.approvals` y hacia `approvalCapability` + - `ChannelPlugin.approvals` se eliminó del contrato público de + plugin de canal; mueve los campos delivery/native/render a `approvalCapability` + - `plugin.auth` permanece solo para los flujos de inicio/cierre de sesión del canal; los hooks + de autenticación de aprobación ahí ya no son leídos por el núcleo + - Registra objetos de entorno de ejecución propiedad del canal, como clientes, tokens o aplicaciones + Bolt, mediante `openclaw/plugin-sdk/channel-runtime-context` + - No envíes avisos de redirección propiedad del plugin desde controladores nativos de aprobación; + el núcleo ahora es propietario de los avisos de “enrutado a otro lugar” a partir de los resultados reales de entrega - Al pasar `channelRuntime` a `createChannelManager(...)`, proporciona una - superficie real `createPluginRuntime().channel`. Los stubs parciales se rechazan. + superficie real de `createPluginRuntime().channel`. Los stubs parciales se rechazan. - Consulta `/plugins/sdk-channel-plugins` para ver el diseño actual de - capacidades de aprobación. + Consulta `/plugins/sdk-channel-plugins` para ver el diseño actual + de la capacidad de aprobación. - - Si tu plugin usa `openclaw/plugin-sdk/windows-spawn`, los wrappers `.cmd`/`.bat` - no resueltos de Windows ahora fallan en modo cerrado, a menos que pases explícitamente - `allowShellFallback: true`. + + Si tu plugin usa `openclaw/plugin-sdk/windows-spawn`, los wrappers `.cmd`/`.bat` de Windows no resueltos ahora fallan de forma cerrada a menos que pases + explícitamente `allowShellFallback: true`. ```typescript // Antes @@ -112,19 +111,19 @@ Ejemplos actuales de proveedores empaquetados: // Después const program = applyWindowsSpawnProgramPolicy({ candidate, - // Establece esto solo para llamantes de compatibilidad de confianza que - // aceptan intencionalmente el respaldo mediado por shell. + // Establece esto solo para llamadores de compatibilidad de confianza que + // aceptan intencionalmente el fallback mediado por shell. allowShellFallback: true, }); ``` - Si tu llamante no depende intencionalmente del respaldo por shell, no establezcas - `allowShellFallback` y maneja el error lanzado en su lugar. + Si tu llamador no depende intencionalmente del fallback de shell, no establezcas + `allowShellFallback` y maneja en su lugar el error lanzado. - - Busca en tu plugin importaciones desde cualquiera de estas dos superficies obsoletas: + + Busca en tu plugin importaciones desde cualquiera de las dos superficies obsoletas: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -133,24 +132,24 @@ Ejemplos actuales de proveedores empaquetados: - - Cada exportación de la superficie antigua se corresponde con una ruta de importación moderna específica: + + Cada exportación de la superficie anterior se asigna a una ruta de importación moderna específica: ```typescript - // Antes (capa obsoleta de compatibilidad hacia atrás) + // Antes (capa obsoleta de compatibilidad retroactiva) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // Después (importaciones modernas y enfocadas) + // Después (importaciones modernas específicas) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Para helpers del lado del host, usa el runtime de plugin inyectado en lugar de importar + Para los ayudantes del lado del host, usa el entorno de ejecución del plugin inyectado en lugar de importar directamente: ```typescript @@ -158,11 +157,11 @@ Ejemplos actuales de proveedores empaquetados: import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // Después (runtime inyectado) + // Después (entorno de ejecución inyectado) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - El mismo patrón se aplica a otros helpers heredados del puente: + El mismo patrón se aplica a otros ayudantes heredados del puente: | Importación antigua | Equivalente moderno | | --- | --- | @@ -172,7 +171,7 @@ Ejemplos actuales de proveedores empaquetados: | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | helpers del almacén de sesiones | `api.runtime.agent.session.*` | + | ayudantes de almacén de sesiones | `api.runtime.agent.session.*` | @@ -189,178 +188,181 @@ Ejemplos actuales de proveedores empaquetados: | Ruta de importación | Propósito | Exportaciones clave | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Helper canónico de entrada de plugin | `definePluginEntry` | + | `plugin-sdk/plugin-entry` | Ayudante canónico de entrada de plugin | `definePluginEntry` | | `plugin-sdk/core` | Reexportación paraguas heredada para definiciones/constructores de entrada de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Exportación del esquema raíz de configuración | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper de entrada de proveedor único | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Definiciones y constructores enfocados de entrada de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Helpers compartidos del asistente de configuración | Prompts de listas de permitidos, constructores de estado de configuración | - | `plugin-sdk/setup-runtime` | Helpers de runtime en tiempo de configuración | Adaptadores de parches de configuración seguros para importación, helpers de notas de búsqueda, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies delegados de configuración | - | `plugin-sdk/setup-adapter-runtime` | Helpers del adaptador de configuración | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Helpers de herramientas de configuración | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpers de múltiples cuentas | Helpers de lista/configuración/compuertas de acciones de cuenta | - | `plugin-sdk/account-id` | Helpers de id de cuenta | `DEFAULT_ACCOUNT_ID`, normalización de id de cuenta | - | `plugin-sdk/account-resolution` | Helpers de búsqueda de cuenta | Helpers de búsqueda de cuenta + respaldo predeterminado | - | `plugin-sdk/account-helpers` | Helpers de cuenta específicos | Helpers de lista de cuentas/acción de cuenta | + | `plugin-sdk/config-schema` | Exportación del esquema de configuración raíz | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Ayudante de entrada de proveedor único | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Definiciones y constructores específicos de entrada de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Ayudantes compartidos del asistente de configuración | Prompts de lista de permitidos, constructores de estado de configuración | + | `plugin-sdk/setup-runtime` | Ayudantes de entorno de ejecución en tiempo de configuración | Adaptadores de parcheo de configuración seguros para importación, ayudantes de notas de búsqueda, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuración delegados | + | `plugin-sdk/setup-adapter-runtime` | Ayudantes del adaptador de configuración | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Ayudantes de herramientas de configuración | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Ayudantes de múltiples cuentas | Ayudantes de lista/configuración/puerta de acciones de cuenta | + | `plugin-sdk/account-id` | Ayudantes de id de cuenta | `DEFAULT_ACCOUNT_ID`, normalización de id de cuenta | + | `plugin-sdk/account-resolution` | Ayudantes de búsqueda de cuentas | Ayudantes de búsqueda de cuentas + fallback predeterminado | + | `plugin-sdk/account-helpers` | Ayudantes de cuenta específicos | Ayudantes de lista de cuentas/acciones de cuenta | | `plugin-sdk/channel-setup` | Adaptadores del asistente de configuración | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, además de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Primitivas de emparejamiento de DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Cableado de prefijo de respuesta + escritura | `createChannelReplyPipeline` | + | `plugin-sdk/channel-pairing` | Primitivas de emparejamiento DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Cableado de prefijo de respuesta + indicador de escritura | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Fábricas de adaptadores de configuración | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Constructores de esquema de configuración | Tipos de esquema de configuración de canal | - | `plugin-sdk/telegram-command-config` | Helpers de configuración de comandos de Telegram | Normalización de nombres de comando, recorte de descripciones, validación de duplicados/conflictos | + | `plugin-sdk/channel-config-schema` | Constructores de esquemas de configuración | Tipos de esquema de configuración de canal | + | `plugin-sdk/telegram-command-config` | Ayudantes de configuración de comandos de Telegram | Normalización de nombres de comandos, recorte de descripciones, validación de duplicados/conflictos | | `plugin-sdk/channel-policy` | Resolución de políticas de grupo/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Seguimiento del estado de cuenta | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpers de envoltorio entrante | Helpers compartidos de ruta + construcción de envoltorio | - | `plugin-sdk/inbound-reply-dispatch` | Helpers de respuesta entrante | Helpers compartidos de registro y despacho | - | `plugin-sdk/messaging-targets` | Análisis de objetivos de mensajería | Helpers de análisis/coincidencia de objetivos | - | `plugin-sdk/outbound-media` | Helpers de medios salientes | Carga compartida de medios salientes | - | `plugin-sdk/outbound-runtime` | Helpers de runtime saliente | Helpers delegados de identidad/envío saliente | - | `plugin-sdk/thread-bindings-runtime` | Helpers de bindings de hilo | Ciclo de vida de bindings de hilo y helpers de adaptador | - | `plugin-sdk/agent-media-payload` | Helpers heredados de carga útil de medios | Constructor de carga útil de medios de agente para diseños heredados de campos | - | `plugin-sdk/channel-runtime` | Shim obsoleto de compatibilidad | Solo utilidades heredadas de runtime de canal | + | `plugin-sdk/channel-lifecycle` | Seguimiento de estado de cuenta | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Ayudantes de envelope de entrada | Ayudantes compartidos de enrutamiento + construcción de envelope | + | `plugin-sdk/inbound-reply-dispatch` | Ayudantes de respuesta entrante | Ayudantes compartidos de registro y despacho | + | `plugin-sdk/messaging-targets` | Análisis de destinos de mensajería | Ayudantes de análisis/coincidencia de destinos | + | `plugin-sdk/outbound-media` | Ayudantes de medios salientes | Carga compartida de medios salientes | + | `plugin-sdk/outbound-runtime` | Ayudantes de entorno de ejecución saliente | Ayudantes de identidad saliente/delegados de envío | + | `plugin-sdk/thread-bindings-runtime` | Ayudantes de asociación de hilos | Ciclo de vida y ayudantes de adaptadores de asociación de hilos | + | `plugin-sdk/agent-media-payload` | Ayudantes heredados de payload de medios | Constructor de payload de medios del agente para diseños heredados de campos | + | `plugin-sdk/channel-runtime` | Shim de compatibilidad obsoleto | Solo utilidades heredadas de entorno de ejecución de canal | | `plugin-sdk/channel-send-result` | Tipos de resultado de envío | Tipos de resultado de respuesta | - | `plugin-sdk/runtime-store` | Almacenamiento persistente del plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Helpers amplios de runtime | Helpers de runtime/logging/backup/instalación de plugins | - | `plugin-sdk/runtime-env` | Helpers específicos de entorno de runtime | Logger/entorno de runtime, timeout, retry y helpers de backoff | - | `plugin-sdk/plugin-runtime` | Helpers compartidos de runtime de plugin | Helpers de comandos/hooks/http/interactivos de plugin | - | `plugin-sdk/hook-runtime` | Helpers de pipeline de hooks | Helpers compartidos del pipeline de hooks webhook/internos | - | `plugin-sdk/lazy-runtime` | Helpers de runtime diferido | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpers de proceso | Helpers compartidos de exec | - | `plugin-sdk/cli-runtime` | Helpers de runtime de CLI | Formato de comandos, esperas, helpers de versión | - | `plugin-sdk/gateway-runtime` | Helpers del Gateway | Cliente Gateway y helpers de parcheo de estado de canal | - | `plugin-sdk/config-runtime` | Helpers de configuración | Helpers de carga/escritura de configuración | - | `plugin-sdk/telegram-command-config` | Helpers de comandos de Telegram | Helpers de validación de comandos de Telegram estables como respaldo cuando la superficie de contrato empaquetada de Telegram no está disponible | - | `plugin-sdk/approval-runtime` | Helpers de prompts de aprobación | Carga útil de aprobación de exec/plugin, helpers de capacidad/perfil de aprobación, helpers nativos de routing/runtime de aprobación | - | `plugin-sdk/approval-auth-runtime` | Helpers de auth de aprobación | Resolución del aprobador, auth de acción en el mismo chat | - | `plugin-sdk/approval-client-runtime` | Helpers de cliente de aprobación | Helpers de perfil/filtro nativos de aprobación de exec | - | `plugin-sdk/approval-delivery-runtime` | Helpers de entrega de aprobación | Adaptadores nativos de capacidad/entrega de aprobación | - | `plugin-sdk/approval-gateway-runtime` | Helpers de Gateway de aprobación | Helper compartido de resolución de gateway de aprobación | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpers de adaptador de aprobación | Helpers ligeros de carga de adaptadores nativos de aprobación para puntos de entrada de canal activos | - | `plugin-sdk/approval-handler-runtime` | Helpers de handler de aprobación | Helpers más amplios de runtime de handlers de aprobación; prefiere las superficies más específicas de adaptador/gateway cuando sean suficientes | - | `plugin-sdk/approval-native-runtime` | Helpers de objetivos de aprobación | Helpers nativos de binding de objetivo/cuenta de aprobación | - | `plugin-sdk/approval-reply-runtime` | Helpers de respuesta de aprobación | Helpers de carga útil de respuesta de aprobación de exec/plugin | - | `plugin-sdk/channel-runtime-context` | Helpers de contexto de runtime de canal | Helpers genéricos de registro/obtención/observación del contexto de runtime de canal | - | `plugin-sdk/security-runtime` | Helpers de seguridad | Helpers compartidos de confianza, restricción de DM, contenido externo y recopilación de secretos | - | `plugin-sdk/ssrf-policy` | Helpers de política SSRF | Helpers de lista de permitidos de hosts y política de red privada | - | `plugin-sdk/ssrf-runtime` | Helpers de runtime SSRF | Helpers de dispatcher fijado, fetch protegido y política SSRF | - | `plugin-sdk/collection-runtime` | Helpers de caché limitada | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helpers de restricción diagnóstica | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Helpers de formato de errores | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de grafo de errores | - | `plugin-sdk/fetch-runtime` | Helpers envueltos de fetch/proxy | `resolveFetch`, helpers de proxy | - | `plugin-sdk/host-runtime` | Helpers de normalización del host | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Helpers de retry | `RetryConfig`, `retryAsync`, ejecutores de políticas | - | `plugin-sdk/allow-from` | Formateo de lista de permitidos | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Mapeo de entradas de lista de permitidos | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Restricción de comandos y helpers de superficie de comandos | `resolveControlCommandGate`, helpers de autorización de remitente, helpers de registro de comandos | - | `plugin-sdk/secret-input` | Análisis de entrada secreta | Helpers de entrada secreta | - | `plugin-sdk/webhook-ingress` | Helpers de solicitud webhook | Utilidades de objetivo webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de guardas de cuerpo webhook | Helpers de lectura/límite del cuerpo de solicitud | - | `plugin-sdk/reply-runtime` | Runtime compartido de respuesta | Despacho entrante, heartbeat, planificador de respuesta, fragmentación | - | `plugin-sdk/reply-dispatch-runtime` | Helpers específicos de despacho de respuesta | Helpers de finalización + despacho de proveedor | - | `plugin-sdk/reply-history` | Helpers de historial de respuesta | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/runtime-store` | Almacenamiento persistente de plugins | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Ayudantes amplios de entorno de ejecución | Ayudantes de entorno de ejecución/logs/backup/instalación de plugins | + | `plugin-sdk/runtime-env` | Ayudantes específicos de entorno de ejecución | Logger/entorno de ejecución, tiempo de espera, reintentos y ayudantes de backoff | + | `plugin-sdk/plugin-runtime` | Ayudantes compartidos de entorno de ejecución de plugins | Ayudantes de comandos/hooks/http/interactividad de plugins | + | `plugin-sdk/hook-runtime` | Ayudantes de canalización de hooks | Ayudantes compartidos de canalización de webhooks/hooks internos | + | `plugin-sdk/lazy-runtime` | Ayudantes de entorno de ejecución perezoso | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Ayudantes de procesos | Ayudantes compartidos de exec | + | `plugin-sdk/cli-runtime` | Ayudantes de entorno de ejecución de CLI | Formateo de comandos, esperas, ayudantes de versión | + | `plugin-sdk/gateway-runtime` | Ayudantes de gateway | Cliente de gateway y ayudantes de parcheo de estado de canal | + | `plugin-sdk/config-runtime` | Ayudantes de configuración | Ayudantes de carga/escritura de configuración | + | `plugin-sdk/telegram-command-config` | Ayudantes de comandos de Telegram | Ayudantes de validación de comandos de Telegram con fallback estable cuando la superficie contractual incluida de Telegram no está disponible | + | `plugin-sdk/approval-runtime` | Ayudantes de prompts de aprobación | Payload de aprobación de exec/plugin, ayudantes de capacidad/perfil de aprobación, ayudantes nativos de enrutamiento/entorno de ejecución de aprobaciones | + | `plugin-sdk/approval-auth-runtime` | Ayudantes de autenticación de aprobación | Resolución de aprobadores, autenticación de acciones en el mismo chat | + | `plugin-sdk/approval-client-runtime` | Ayudantes de cliente de aprobación | Ayudantes nativos de perfil/filtro de aprobación de exec | + | `plugin-sdk/approval-delivery-runtime` | Ayudantes de entrega de aprobación | Adaptadores nativos de capacidad/entrega de aprobación | + | `plugin-sdk/approval-gateway-runtime` | Ayudantes de gateway de aprobación | Ayudante compartido de resolución de gateway de aprobación | + | `plugin-sdk/approval-handler-adapter-runtime` | Ayudantes de adaptador de aprobación | Ayudantes ligeros de carga de adaptadores nativos de aprobación para puntos de entrada de canal activos | + | `plugin-sdk/approval-handler-runtime` | Ayudantes de controlador de aprobación | Ayudantes más amplios del entorno de ejecución del controlador de aprobación; prefiere las uniones más específicas de adaptador/gateway cuando sean suficientes | + | `plugin-sdk/approval-native-runtime` | Ayudantes de destino de aprobación | Ayudantes nativos de asociación de destino/cuenta de aprobación | + | `plugin-sdk/approval-reply-runtime` | Ayudantes de respuesta de aprobación | Ayudantes de payload de respuesta de aprobación de exec/plugin | + | `plugin-sdk/channel-runtime-context` | Ayudantes de contexto de entorno de ejecución de canal | Ayudantes genéricos de registro/obtención/observación de contexto de entorno de ejecución de canal | + | `plugin-sdk/security-runtime` | Ayudantes de seguridad | Ayudantes compartidos de confianza, control DM, contenido externo y recopilación de secretos | + | `plugin-sdk/ssrf-policy` | Ayudantes de políticas SSRF | Ayudantes de lista de permitidos de hosts y políticas de red privada | + | `plugin-sdk/ssrf-runtime` | Ayudantes de entorno de ejecución SSRF | Dispatcher fijado, fetch protegido, ayudantes de políticas SSRF | + | `plugin-sdk/collection-runtime` | Ayudantes de caché acotada | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Ayudantes de control de diagnósticos | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Ayudantes de formato de errores | `formatUncaughtError`, `isApprovalNotFoundError`, ayudantes de grafo de errores | + | `plugin-sdk/fetch-runtime` | Ayudantes de fetch/proxy envueltos | `resolveFetch`, ayudantes de proxy | + | `plugin-sdk/host-runtime` | Ayudantes de normalización del host | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Ayudantes de reintento | `RetryConfig`, `retryAsync`, ejecutores de políticas | + | `plugin-sdk/allow-from` | Formateo de listas de permitidos | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Mapeo de entrada de listas de permitidos | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Control de comandos y ayudantes de superficie de comandos | `resolveControlCommandGate`, ayudantes de autorización de remitente, ayudantes de registro de comandos | + | `plugin-sdk/command-status` | Renderizadores de estado/ayuda de comandos | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Análisis de entrada de secretos | Ayudantes de entrada de secretos | + | `plugin-sdk/webhook-ingress` | Ayudantes de solicitudes webhook | Utilidades de destino webhook | + | `plugin-sdk/webhook-request-guards` | Ayudantes de protección de solicitudes webhook | Ayudantes de lectura/límite de cuerpo de solicitud | + | `plugin-sdk/reply-runtime` | Entorno de ejecución compartido de respuestas | Despacho entrante, heartbeat, planificador de respuestas, fragmentación | + | `plugin-sdk/reply-dispatch-runtime` | Ayudantes específicos de despacho de respuestas | Ayudantes de finalización + despacho de proveedor | + | `plugin-sdk/reply-history` | Ayudantes de historial de respuestas | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | Planificación de referencias de respuesta | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpers de fragmentación de respuesta | Helpers de fragmentación de texto/markdown | - | `plugin-sdk/session-store-runtime` | Helpers de almacén de sesiones | Ruta del almacén + helpers de updated-at | - | `plugin-sdk/state-paths` | Helpers de rutas de estado | Helpers de directorios de estado y OAuth | - | `plugin-sdk/routing` | Helpers de routing/clave de sesión | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalización de clave de sesión | - | `plugin-sdk/status-helpers` | Helpers de estado de canal | Constructores de resúmenes de estado de canal/cuenta, valores predeterminados de estado de runtime, helpers de metadatos de incidencias | - | `plugin-sdk/target-resolver-runtime` | Helpers de resolución de objetivos | Helpers compartidos de resolución de objetivos | - | `plugin-sdk/string-normalization-runtime` | Helpers de normalización de cadenas | Helpers de normalización de slug/cadenas | - | `plugin-sdk/request-url` | Helpers de URL de solicitud | Extrae URLs de cadena de entradas similares a solicitudes | - | `plugin-sdk/run-command` | Helpers de comandos temporizados | Ejecutor de comandos temporizados con stdout/stderr normalizados | + | `plugin-sdk/reply-chunking` | Ayudantes de fragmentación de respuestas | Ayudantes de fragmentación de texto/Markdown | + | `plugin-sdk/session-store-runtime` | Ayudantes de almacén de sesiones | Ayudantes de ruta de almacén + updated-at | + | `plugin-sdk/state-paths` | Ayudantes de rutas de estado | Ayudantes de directorios de estado y OAuth | + | `plugin-sdk/routing` | Ayudantes de enrutamiento/clave de sesión | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, ayudantes de normalización de claves de sesión | + | `plugin-sdk/status-helpers` | Ayudantes de estado de canal | Constructores de resúmenes de estado de canal/cuenta, valores predeterminados de estado de entorno de ejecución, ayudantes de metadatos de incidencias | + | `plugin-sdk/target-resolver-runtime` | Ayudantes de resolución de destino | Ayudantes compartidos de resolución de destino | + | `plugin-sdk/string-normalization-runtime` | Ayudantes de normalización de cadenas | Ayudantes de normalización de slug/cadenas | + | `plugin-sdk/request-url` | Ayudantes de URL de solicitud | Extrae URL de cadena de entradas tipo solicitud | + | `plugin-sdk/run-command` | Ayudantes de comandos temporizados | Ejecutor de comandos temporizados con stdout/stderr normalizados | | `plugin-sdk/param-readers` | Lectores de parámetros | Lectores comunes de parámetros de herramientas/CLI | - | `plugin-sdk/tool-send` | Extracción de envío de herramientas | Extrae campos canónicos de objetivo de envío desde argumentos de herramientas | - | `plugin-sdk/temp-path` | Helpers de ruta temporal | Helpers compartidos de ruta temporal de descarga | - | `plugin-sdk/logging-core` | Helpers de logging | Logger de subsistema y helpers de redacción | - | `plugin-sdk/markdown-table-runtime` | Helpers de tablas Markdown | Helpers de modo de tabla Markdown | - | `plugin-sdk/reply-payload` | Tipos de respuesta de mensaje | Tipos de carga útil de respuesta | - | `plugin-sdk/provider-setup` | Helpers seleccionados de configuración de proveedores locales/autohospedados | Helpers de descubrimiento/configuración de proveedores autohospedados | - | `plugin-sdk/self-hosted-provider-setup` | Helpers enfocados de configuración de proveedores autohospedados compatibles con OpenAI | Los mismos helpers de descubrimiento/configuración de proveedores autohospedados | - | `plugin-sdk/provider-auth-runtime` | Helpers de auth de runtime del proveedor | Helpers de resolución de API key en runtime | - | `plugin-sdk/provider-auth-api-key` | Helpers de configuración de API key del proveedor | Helpers de onboarding/escritura de perfil de API key | - | `plugin-sdk/provider-auth-result` | Helpers de resultado de auth del proveedor | Constructor estándar de resultado de auth OAuth | - | `plugin-sdk/provider-auth-login` | Helpers de login interactivo del proveedor | Helpers compartidos de login interactivo | - | `plugin-sdk/provider-env-vars` | Helpers de variables de entorno del proveedor | Helpers de búsqueda de variables de entorno de auth del proveedor | - | `plugin-sdk/provider-model-shared` | Helpers compartidos de modelo/repetición del proveedor | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, helpers de endpoints del proveedor y helpers de normalización de id de modelo | - | `plugin-sdk/provider-catalog-shared` | Helpers compartidos de catálogo del proveedor | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Parches de onboarding del proveedor | Helpers de configuración de onboarding | - | `plugin-sdk/provider-http` | Helpers HTTP del proveedor | Helpers genéricos de HTTP/capacidades de endpoint del proveedor | - | `plugin-sdk/provider-web-fetch` | Helpers de web-fetch del proveedor | Helpers de registro/caché del proveedor web-fetch | - | `plugin-sdk/provider-web-search-contract` | Helpers de contrato de búsqueda web del proveedor | Helpers específicos de contrato de configuración/credenciales de búsqueda web como `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance | - | `plugin-sdk/provider-web-search` | Helpers de búsqueda web del proveedor | Helpers de registro/caché/runtime del proveedor de búsqueda web | - | `plugin-sdk/provider-tools` | Helpers de compatibilidad de herramientas/esquema del proveedor | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquema Gemini y helpers de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Helpers de uso del proveedor | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` y otros helpers de uso del proveedor | - | `plugin-sdk/provider-stream` | Helpers de wrapper de flujo del proveedor | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de flujo y helpers compartidos de wrappers Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | Cola async ordenada | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Helpers compartidos de medios | Helpers de obtención/transformación/almacenamiento de medios más constructores de carga útil de medios | - | `plugin-sdk/media-generation-runtime` | Helpers compartidos de generación de medios | Helpers compartidos de failover, selección de candidatos y mensajes de modelo ausente para generación de imagen/video/música | - | `plugin-sdk/media-understanding` | Helpers de comprensión de medios | Tipos de proveedor de comprensión de medios más exportaciones de helpers de imagen/audio orientados al proveedor | - | `plugin-sdk/text-runtime` | Helpers compartidos de texto | Eliminación de texto visible para el asistente, helpers de renderizado/fragmentación/tablas Markdown, helpers de redacción, helpers de etiquetas de directiva, utilidades de texto seguro y helpers relacionados de texto/logging | - | `plugin-sdk/text-chunking` | Helpers de fragmentación de texto | Helper de fragmentación de texto saliente | - | `plugin-sdk/speech` | Helpers de voz | Tipos de proveedor de voz más helpers orientados al proveedor para directivas, registro y validación | - | `plugin-sdk/speech-core` | Núcleo compartido de voz | Tipos de proveedor de voz, registro, directivas, normalización | - | `plugin-sdk/realtime-transcription` | Helpers de transcripción en tiempo real | Tipos de proveedor y helpers de registro | - | `plugin-sdk/realtime-voice` | Helpers de voz en tiempo real | Tipos de proveedor y helpers de registro | - | `plugin-sdk/image-generation-core` | Núcleo compartido de generación de imágenes | Tipos de generación de imágenes, failover, auth y helpers de registro | - | `plugin-sdk/music-generation` | Helpers de generación musical | Tipos de proveedor/solicitud/resultado de generación musical | - | `plugin-sdk/music-generation-core` | Núcleo compartido de generación musical | Tipos de generación musical, helpers de failover, búsqueda de proveedor y análisis de model-ref | - | `plugin-sdk/video-generation` | Helpers de generación de video | Tipos de proveedor/solicitud/resultado de generación de video | - | `plugin-sdk/video-generation-core` | Núcleo compartido de generación de video | Tipos de generación de video, helpers de failover, búsqueda de proveedor y análisis de model-ref | - | `plugin-sdk/interactive-runtime` | Helpers de respuesta interactiva | Normalización/reducción de carga útil de respuesta interactiva | + | `plugin-sdk/tool-payload` | Extracción de payload de herramientas | Extrae payloads normalizados de objetos de resultado de herramientas | + | `plugin-sdk/tool-send` | Extracción de envío de herramientas | Extrae campos canónicos de destino de envío desde argumentos de herramientas | + | `plugin-sdk/temp-path` | Ayudantes de rutas temporales | Ayudantes compartidos de rutas temporales de descarga | + | `plugin-sdk/logging-core` | Ayudantes de logging | Logger de subsistema y ayudantes de redacción | + | `plugin-sdk/markdown-table-runtime` | Ayudantes de tablas Markdown | Ayudantes de modo de tabla Markdown | + | `plugin-sdk/reply-payload` | Tipos de respuesta de mensajes | Tipos de payload de respuesta | + | `plugin-sdk/provider-setup` | Ayudantes curados de configuración de proveedores locales/autohospedados | Ayudantes de detección/configuración de proveedores autohospedados | + | `plugin-sdk/self-hosted-provider-setup` | Ayudantes específicos de configuración de proveedores autohospedados compatibles con OpenAI | Los mismos ayudantes de detección/configuración de proveedores autohospedados | + | `plugin-sdk/provider-auth-runtime` | Ayudantes de autenticación de proveedores en tiempo de ejecución | Ayudantes de resolución de claves API en tiempo de ejecución | + | `plugin-sdk/provider-auth-api-key` | Ayudantes de configuración de claves API de proveedores | Ayudantes de incorporación/escritura de perfil de clave API | + | `plugin-sdk/provider-auth-result` | Ayudantes de resultado de autenticación de proveedores | Constructor estándar de resultado de autenticación OAuth | + | `plugin-sdk/provider-auth-login` | Ayudantes de inicio de sesión interactivo de proveedores | Ayudantes compartidos de inicio de sesión interactivo | + | `plugin-sdk/provider-env-vars` | Ayudantes de variables de entorno de proveedores | Ayudantes de búsqueda de variables de entorno de autenticación del proveedor | + | `plugin-sdk/provider-model-shared` | Ayudantes compartidos de modelos/replay de proveedores | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de replay, ayudantes de endpoints de proveedores y ayudantes de normalización de id de modelos | + | `plugin-sdk/provider-catalog-shared` | Ayudantes compartidos de catálogo de proveedores | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Parches de incorporación de proveedores | Ayudantes de configuración de incorporación | + | `plugin-sdk/provider-http` | Ayudantes HTTP de proveedores | Ayudantes genéricos de HTTP/capacidades de endpoints de proveedores | + | `plugin-sdk/provider-web-fetch` | Ayudantes de web-fetch de proveedores | Ayudantes de registro/caché de proveedores web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Ayudantes de configuración de búsqueda web de proveedores | Ayudantes específicos de configuración/credenciales de búsqueda web para proveedores que no necesitan cableado de habilitación del plugin | + | `plugin-sdk/provider-web-search-contract` | Ayudantes contractuales de búsqueda web de proveedores | Ayudantes contractuales específicos de configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance | + | `plugin-sdk/provider-web-search` | Ayudantes de búsqueda web de proveedores | Ayudantes de registro/caché/entorno de ejecución de proveedores de búsqueda web | + | `plugin-sdk/provider-tools` | Ayudantes de compatibilidad de herramientas/esquemas de proveedores | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquemas Gemini y ayudantes de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Ayudantes de uso de proveedores | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` y otros ayudantes de uso de proveedores | + | `plugin-sdk/provider-stream` | Ayudantes de envoltorio de streams de proveedores | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorios de streams y ayudantes compartidos de envoltorios Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/keyed-async-queue` | Cola asíncrona ordenada | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Ayudantes compartidos de medios | Ayudantes de fetch/transformación/almacenamiento de medios más constructores de payload de medios | + | `plugin-sdk/media-generation-runtime` | Ayudantes compartidos de generación de medios | Ayudantes compartidos de failover, selección de candidatos y mensajes de modelo faltante para generación de imágenes/video/música | + | `plugin-sdk/media-understanding` | Ayudantes de comprensión de medios | Tipos de proveedores de comprensión de medios más exportaciones de ayudantes de imagen/audio orientados a proveedores | + | `plugin-sdk/text-runtime` | Ayudantes compartidos de texto | Eliminación de texto visible para el asistente, renderizado/fragmentación/tablas Markdown, ayudantes de redacción, ayudantes de etiquetas de directivas, utilidades de texto seguro y ayudantes relacionados de texto/logging | + | `plugin-sdk/text-chunking` | Ayudantes de fragmentación de texto | Ayudante de fragmentación de texto saliente | + | `plugin-sdk/speech` | Ayudantes de voz | Tipos de proveedores de voz más exportaciones orientadas a proveedores de directivas, registro y validación | + | `plugin-sdk/speech-core` | Núcleo compartido de voz | Tipos de proveedores de voz, registro, directivas, normalización | + | `plugin-sdk/realtime-transcription` | Ayudantes de transcripción en tiempo real | Tipos de proveedores y ayudantes de registro | + | `plugin-sdk/realtime-voice` | Ayudantes de voz en tiempo real | Tipos de proveedores y ayudantes de registro | + | `plugin-sdk/image-generation-core` | Núcleo compartido de generación de imágenes | Tipos de generación de imágenes, failover, autenticación y ayudantes de registro | + | `plugin-sdk/music-generation` | Ayudantes de generación musical | Tipos de proveedor/solicitud/resultado de generación musical | + | `plugin-sdk/music-generation-core` | Núcleo compartido de generación musical | Tipos de generación musical, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos | + | `plugin-sdk/video-generation` | Ayudantes de generación de video | Tipos de proveedor/solicitud/resultado de generación de video | + | `plugin-sdk/video-generation-core` | Núcleo compartido de generación de video | Tipos de generación de video, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos | + | `plugin-sdk/interactive-runtime` | Ayudantes de respuestas interactivas | Normalización/reducción de payload de respuestas interactivas | | `plugin-sdk/channel-config-primitives` | Primitivas de configuración de canal | Primitivas específicas de esquema de configuración de canal | - | `plugin-sdk/channel-config-writes` | Helpers de escritura de configuración de canal | Helpers de autorización de escritura de configuración de canal | - | `plugin-sdk/channel-plugin-common` | Preludio compartido de canal | Exportaciones compartidas del preludio de plugin de canal | - | `plugin-sdk/channel-status` | Helpers de estado de canal | Helpers compartidos de instantánea/resumen de estado de canal | - | `plugin-sdk/allowlist-config-edit` | Helpers de configuración de lista de permitidos | Helpers de edición/lectura de configuración de lista de permitidos | - | `plugin-sdk/group-access` | Helpers de acceso a grupos | Helpers compartidos de decisión de acceso a grupos | - | `plugin-sdk/direct-dm` | Helpers de DM directo | Helpers compartidos de auth/protección para DM directo | - | `plugin-sdk/extension-shared` | Helpers compartidos de extensiones | Primitivas de canal pasivo/estado y helper de proxy ambiental | - | `plugin-sdk/webhook-targets` | Helpers de objetivos webhook | Registro de objetivos webhook y helpers de instalación de rutas | - | `plugin-sdk/webhook-path` | Helpers de ruta webhook | Helpers de normalización de ruta webhook | - | `plugin-sdk/web-media` | Helpers compartidos de medios web | Helpers de carga de medios remotos/locales | - | `plugin-sdk/zod` | Reexportación de Zod | `zod` reexportado para consumidores del plugin SDK | - | `plugin-sdk/memory-core` | Helpers empaquetados de memory-core | Superficie helper de administrador/configuración/archivo/CLI de memoria | - | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime del motor de memoria | Fachada de runtime de índice/búsqueda de memoria | + | `plugin-sdk/channel-config-writes` | Ayudantes de escritura de configuración de canal | Ayudantes de autorización de escritura de configuración de canal | + | `plugin-sdk/channel-plugin-common` | Preludio compartido de canal | Exportaciones compartidas de preludio de plugin de canal | + | `plugin-sdk/channel-status` | Ayudantes de estado de canal | Ayudantes compartidos de instantáneas/resúmenes de estado de canal | + | `plugin-sdk/allowlist-config-edit` | Ayudantes de configuración de lista de permitidos | Ayudantes de edición/lectura de lista de permitidos | + | `plugin-sdk/group-access` | Ayudantes de acceso a grupos | Ayudantes compartidos de decisiones de acceso a grupos | + | `plugin-sdk/direct-dm` | Ayudantes de DM directo | Ayudantes compartidos de autenticación/protección de DM directo | + | `plugin-sdk/extension-shared` | Ayudantes compartidos de extensiones | Primitivas de canal/estado pasivo y ayudantes de proxy ambiental | + | `plugin-sdk/webhook-targets` | Ayudantes de destino webhook | Registro de destinos webhook y ayudantes de instalación de rutas | + | `plugin-sdk/webhook-path` | Ayudantes de ruta webhook | Ayudantes de normalización de rutas webhook | + | `plugin-sdk/web-media` | Ayudantes compartidos de medios web | Ayudantes de carga de medios remotos/locales | + | `plugin-sdk/zod` | Reexportación de Zod | Reexportación de `zod` para consumidores del SDK de plugins | + | `plugin-sdk/memory-core` | Ayudantes incluidos de memory-core | Superficie de ayudantes de gestor/configuración/archivo/CLI de memoria | + | `plugin-sdk/memory-core-engine-runtime` | Fachada de entorno de ejecución del motor de memoria | Fachada de entorno de ejecución de índice/búsqueda de memoria | | `plugin-sdk/memory-core-host-engine-foundation` | Motor base del host de memoria | Exportaciones del motor base del host de memoria | | `plugin-sdk/memory-core-host-engine-embeddings` | Motor de embeddings del host de memoria | Exportaciones del motor de embeddings del host de memoria | | `plugin-sdk/memory-core-host-engine-qmd` | Motor QMD del host de memoria | Exportaciones del motor QMD del host de memoria | | `plugin-sdk/memory-core-host-engine-storage` | Motor de almacenamiento del host de memoria | Exportaciones del motor de almacenamiento del host de memoria | - | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodales del host de memoria | Helpers multimodales del host de memoria | - | `plugin-sdk/memory-core-host-query` | Helpers de consultas del host de memoria | Helpers de consultas del host de memoria | - | `plugin-sdk/memory-core-host-secret` | Helpers de secretos del host de memoria | Helpers de secretos del host de memoria | - | `plugin-sdk/memory-core-host-events` | Helpers de diario de eventos del host de memoria | Helpers de diario de eventos del host de memoria | - | `plugin-sdk/memory-core-host-status` | Helpers de estado del host de memoria | Helpers de estado del host de memoria | - | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI del host de memoria | Helpers de runtime CLI del host de memoria | - | `plugin-sdk/memory-core-host-runtime-core` | Runtime principal del host de memoria | Helpers de runtime principal del host de memoria | - | `plugin-sdk/memory-core-host-runtime-files` | Helpers de archivos/runtime del host de memoria | Helpers de archivos/runtime del host de memoria | - | `plugin-sdk/memory-host-core` | Alias de runtime principal del host de memoria | Alias neutral de proveedor para helpers del runtime principal del host de memoria | - | `plugin-sdk/memory-host-events` | Alias del diario de eventos del host de memoria | Alias neutral de proveedor para helpers del diario de eventos del host de memoria | - | `plugin-sdk/memory-host-files` | Alias de archivos/runtime del host de memoria | Alias neutral de proveedor para helpers de archivos/runtime del host de memoria | - | `plugin-sdk/memory-host-markdown` | Helpers de markdown gestionado | Helpers compartidos de markdown gestionado para plugins adyacentes a memoria | - | `plugin-sdk/memory-host-search` | Fachada activa de búsqueda en memoria | Fachada lazy del runtime del administrador de búsqueda de memoria activa | - | `plugin-sdk/memory-host-status` | Alias de estado del host de memoria | Alias neutral de proveedor para helpers de estado del host de memoria | - | `plugin-sdk/memory-lancedb` | Helpers empaquetados de memory-lancedb | Superficie helper de memory-lancedb | - | `plugin-sdk/testing` | Utilidades de prueba | Helpers y mocks de prueba | + | `plugin-sdk/memory-core-host-multimodal` | Ayudantes multimodales del host de memoria | Ayudantes multimodales del host de memoria | + | `plugin-sdk/memory-core-host-query` | Ayudantes de consultas del host de memoria | Ayudantes de consultas del host de memoria | + | `plugin-sdk/memory-core-host-secret` | Ayudantes de secretos del host de memoria | Ayudantes de secretos del host de memoria | + | `plugin-sdk/memory-core-host-events` | Ayudantes de registro de eventos del host de memoria | Ayudantes de registro de eventos del host de memoria | + | `plugin-sdk/memory-core-host-status` | Ayudantes de estado del host de memoria | Ayudantes de estado del host de memoria | + | `plugin-sdk/memory-core-host-runtime-cli` | Entorno de ejecución CLI del host de memoria | Ayudantes de entorno de ejecución CLI del host de memoria | + | `plugin-sdk/memory-core-host-runtime-core` | Entorno de ejecución central del host de memoria | Ayudantes del entorno de ejecución central del host de memoria | + | `plugin-sdk/memory-core-host-runtime-files` | Ayudantes de archivos/entorno de ejecución del host de memoria | Ayudantes de archivos/entorno de ejecución del host de memoria | + | `plugin-sdk/memory-host-core` | Alias de entorno de ejecución central del host de memoria | Alias neutral respecto al proveedor para ayudantes del entorno de ejecución central del host de memoria | + | `plugin-sdk/memory-host-events` | Alias de registro de eventos del host de memoria | Alias neutral respecto al proveedor para ayudantes del registro de eventos del host de memoria | + | `plugin-sdk/memory-host-files` | Alias de archivos/entorno de ejecución del host de memoria | Alias neutral respecto al proveedor para ayudantes de archivos/entorno de ejecución del host de memoria | + | `plugin-sdk/memory-host-markdown` | Ayudantes de Markdown gestionado | Ayudantes compartidos de Markdown gestionado para plugins cercanos a la memoria | + | `plugin-sdk/memory-host-search` | Fachada de búsqueda activa de memoria | Fachada perezosa del entorno de ejecución del gestor de búsqueda de memoria activa | + | `plugin-sdk/memory-host-status` | Alias de estado del host de memoria | Alias neutral respecto al proveedor para ayudantes de estado del host de memoria | + | `plugin-sdk/memory-lancedb` | Ayudantes incluidos de memory-lancedb | Superficie de ayudantes de memory-lancedb | + | `plugin-sdk/testing` | Utilidades de prueba | Ayudantes y mocks de prueba | -Esta tabla es intencionalmente el subconjunto común de migración, no toda la -superficie del SDK. La lista completa de más de 200 puntos de entrada está en +Esta tabla es intencionalmente el subconjunto común de migración, no la superficie completa del SDK. +La lista completa de más de 200 puntos de entrada se encuentra en `scripts/lib/plugin-sdk-entrypoints.json`. -Esa lista todavía incluye algunas superficies helper de plugins empaquetados como +Esa lista sigue incluyendo algunas uniones de ayudantes de plugins incluidos como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` y `plugin-sdk/matrix*`. Siguen exportándose para -mantenimiento y compatibilidad de plugins empaquetados, pero se omiten intencionalmente +mantenimiento y compatibilidad de plugins incluidos, pero se omiten intencionalmente de la tabla común de migración y no son el objetivo recomendado para código nuevo de plugins. -La misma regla se aplica a otras familias de helpers empaquetados como: +La misma regla se aplica a otras familias de ayudantes incluidos como: -- helpers de compatibilidad con navegador: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- ayudantes de soporte de navegador: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- superficies de helpers/plugins empaquetados como `plugin-sdk/googlechat`, +- superficies de ayudantes/plugins incluidos como `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -369,39 +371,39 @@ La misma regla se aplica a otras familias de helpers empaquetados como: `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` y `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` expone actualmente la superficie específica de helpers de token +`plugin-sdk/github-copilot-token` actualmente expone la superficie específica de ayudantes de token `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken`. -Usa la importación más específica que se ajuste a la tarea. Si no encuentras una exportación, -consulta el código fuente en `src/plugin-sdk/` o pregunta en Discord. +Usa la importación más específica que se ajuste al trabajo. Si no puedes encontrar una exportación, +revisa el código fuente en `src/plugin-sdk/` o pregunta en Discord. ## Cronograma de eliminación -| Cuándo | Qué ocurre | -| -------------------- | --------------------------------------------------------------------- | -| **Ahora** | Las superficies obsoletas emiten advertencias en tiempo de ejecución | +| Cuándo | Qué ocurre | +| ---------------------- | ----------------------------------------------------------------------- | +| **Ahora** | Las superficies obsoletas emiten advertencias en tiempo de ejecución | | **Próxima versión principal** | Las superficies obsoletas se eliminarán; los plugins que sigan usándolas fallarán | Todos los plugins principales ya se han migrado. Los plugins externos deberían migrar antes de la próxima versión principal. -## Suprimir temporalmente las advertencias +## Cómo suprimir temporalmente las advertencias -Configura estas variables de entorno mientras trabajas en la migración: +Establece estas variables de entorno mientras trabajas en la migración: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Esto es una vía de escape temporal, no una solución permanente. +Esta es una vía de escape temporal, no una solución permanente. ## Relacionado - [Primeros pasos](/es/plugins/building-plugins) — crea tu primer plugin -- [Resumen del SDK](/es/plugins/sdk-overview) — referencia completa de importación por subrutas -- [Plugins de canal](/es/plugins/sdk-channel-plugins) — crear plugins de canal -- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — crear plugins de proveedor -- [Internals de plugins](/es/plugins/architecture) — análisis profundo de la arquitectura +- [Resumen del SDK](/es/plugins/sdk-overview) — referencia completa de importaciones por subruta +- [Plugins de canal](/es/plugins/sdk-channel-plugins) — creación de plugins de canal +- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — creación de plugins de proveedor +- [Aspectos internos de plugins](/es/plugins/architecture) — análisis detallado de la arquitectura - [Manifiesto del plugin](/es/plugins/manifest) — referencia del esquema del manifiesto diff --git a/docs/es/plugins/sdk-overview.md b/docs/es/plugins/sdk-overview.md index f3c49586e..1292ea370 100644 --- a/docs/es/plugins/sdk-overview.md +++ b/docs/es/plugins/sdk-overview.md @@ -1,35 +1,35 @@ --- read_when: - - Necesita saber desde qué subruta del SDK importar - - Quiere una referencia de todos los métodos de registro en OpenClawPluginApi - - Está buscando una exportación específica del SDK + - Necesitas saber desde qué subruta del SDK importar + - Quieres una referencia de todos los métodos de registro en OpenClawPluginApi + - Estás buscando una exportación específica del SDK sidebarTitle: SDK Overview -summary: Mapa de importaciones, referencia de la API de registro y arquitectura del SDK -title: Descripción general del Plugin SDK +summary: Mapa de importación, referencia de la API de registro y arquitectura del SDK +title: Resumen del Plugin SDK x-i18n: - generated_at: "2026-04-08T02:18:05Z" + generated_at: "2026-04-09T01:30:49Z" model: gpt-5.4 provider: openai - source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30 + source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381 source_path: plugins/sdk-overview.md workflow: 15 --- -# Descripción general del Plugin SDK +# Resumen del Plugin SDK -El Plugin SDK es el contrato tipado entre los plugins y el núcleo. Esta página es la -referencia de **qué importar** y **qué se puede registrar**. +El plugin SDK es el contrato tipado entre los plugins y el núcleo. Esta página es la +referencia para **qué importar** y **qué puedes registrar**. - **¿Busca una guía práctica?** - - ¿Su primer plugin? Empiece con [Primeros pasos](/es/plugins/building-plugins) - - ¿Plugin de canal? Vea [Plugins de canal](/es/plugins/sdk-channel-plugins) - - ¿Plugin de proveedor? Vea [Plugins de proveedor](/es/plugins/sdk-provider-plugins) + **¿Buscas una guía práctica?** + - ¿Tu primer plugin? Empieza con [Getting Started](/es/plugins/building-plugins) + - ¿Plugin de canal? Consulta [Channel Plugins](/es/plugins/sdk-channel-plugins) + - ¿Plugin de proveedor? Consulta [Provider Plugins](/es/plugins/sdk-provider-plugins) ## Convención de importación -Importe siempre desde una subruta específica: +Importa siempre desde una subruta específica: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -37,35 +37,36 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Cada subruta es un módulo pequeño y autocontenido. Esto mantiene un inicio rápido y -evita problemas de dependencias circulares. Para los auxiliares específicos de entrada/compilación de canales, -prefiera `openclaw/plugin-sdk/channel-core`; reserve `openclaw/plugin-sdk/core` para -la superficie paraguas más amplia y auxiliares compartidos como +evita problemas de dependencias circulares. Para ayudantes de entrada/construcción específicos de canal, +prefiere `openclaw/plugin-sdk/channel-core`; conserva `openclaw/plugin-sdk/core` para +la superficie paraguas más amplia y ayudantes compartidos como `buildChannelConfigSchema`. -No agregue ni dependa de capas de conveniencia con nombre de proveedor como +No agregues ni dependas de puntos de acceso de conveniencia con nombre de proveedor como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de -capas auxiliares con marca de canal. Los plugins integrados deben componer subrutas -genéricas del SDK dentro de sus propios archivos barril `api.ts` o `runtime-api.ts`, y el núcleo -debe usar esos barriles locales del plugin o agregar un contrato del SDK genérico y acotado -cuando la necesidad sea realmente transversal a varios canales. +puntos de acceso auxiliares con marca de canal. Los plugins integrados deben componer subrutas +genéricas del SDK dentro de sus propios barrels `api.ts` o `runtime-api.ts`, y el núcleo +debe usar esos barrels locales del plugin o agregar un contrato genérico y acotado del SDK +cuando la necesidad sea realmente entre canales. -El mapa de exportaciones generado aún contiene un pequeño conjunto de -capas auxiliares para plugins integrados como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, -`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` y `plugin-sdk/matrix*`. Esas +El mapa de exportación generado todavía contiene un pequeño conjunto de puntos de acceso auxiliares +de plugins integrados como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, y `plugin-sdk/matrix*`. Esas subrutas existen solo para mantenimiento y compatibilidad de plugins integrados; se -omiten intencionalmente de la tabla común a continuación y no son la ruta de importación recomendada para plugins nuevos de terceros. +omiten intencionalmente de la tabla común a continuación y no son la ruta de +importación recomendada para nuevos plugins de terceros. ## Referencia de subrutas -Las subrutas de uso más común, agrupadas por propósito. La lista completa generada de +Las subrutas más utilizadas, agrupadas por propósito. La lista completa generada de más de 200 subrutas está en `scripts/lib/plugin-sdk-entrypoints.json`. Las subrutas auxiliares reservadas para plugins integrados siguen apareciendo en esa lista generada. -Trátelas como detalles de implementación o superficies de compatibilidad, a menos que una página de documentación +Trátalas como superficies de detalle de implementación/compatibilidad a menos que una página de documentación promocione explícitamente una como pública. -### Entrada de plugin +### Entrada del plugin | Subruta | Exportaciones clave | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | @@ -81,226 +82,229 @@ promocione explícitamente una como pública. | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Exportación del esquema Zod raíz de `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, además de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Auxiliares compartidos para el asistente de configuración, prompts de lista de permitidos y constructores de estado de configuración | + | `plugin-sdk/setup` | Ayudantes compartidos del asistente de configuración, prompts de lista de permitidos, constructores de estado de configuración | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Auxiliares de configuración/múltiples cuentas/bloqueo de acciones, y auxiliares de respaldo para cuenta predeterminada | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, auxiliares de normalización de id de cuenta | - | `plugin-sdk/account-resolution` | Búsqueda de cuentas + auxiliares de respaldo predeterminado | - | `plugin-sdk/account-helpers` | Auxiliares acotados para lista de cuentas/acciones de cuenta | + | `plugin-sdk/account-core` | Ayudantes de configuración de múltiples cuentas/puerta de acciones, ayudantes de fallback de cuenta predeterminada | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, ayudantes de normalización de id de cuenta | + | `plugin-sdk/account-resolution` | Búsqueda de cuentas + ayudantes de fallback predeterminado | + | `plugin-sdk/account-helpers` | Ayudantes acotados para lista de cuentas/acciones de cuenta | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Tipos de esquema de configuración de canal | - | `plugin-sdk/telegram-command-config` | Auxiliares de normalización/validación de comandos personalizados de Telegram con respaldo de contrato integrado | + | `plugin-sdk/telegram-command-config` | Ayudantes de normalización/validación de comandos personalizados de Telegram con fallback de contrato integrado | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Auxiliares compartidos para rutas entrantes y construcción de sobres | - | `plugin-sdk/inbound-reply-dispatch` | Auxiliares compartidos para registrar y despachar entradas | - | `plugin-sdk/messaging-targets` | Auxiliares de análisis/coincidencia de destinos | - | `plugin-sdk/outbound-media` | Auxiliares compartidos para carga de medios salientes | - | `plugin-sdk/outbound-runtime` | Auxiliares de identidad saliente y delegado de envío | - | `plugin-sdk/thread-bindings-runtime` | Auxiliares de ciclo de vida y adaptadores para enlaces de hilos | - | `plugin-sdk/agent-media-payload` | Constructor heredado de carga útil multimedia del agente | - | `plugin-sdk/conversation-runtime` | Auxiliares de enlaces de conversación/hilo, pairing y enlaces configurados | - | `plugin-sdk/runtime-config-snapshot` | Auxiliar de instantánea de configuración en tiempo de ejecución | - | `plugin-sdk/runtime-group-policy` | Auxiliares de resolución de políticas de grupo en tiempo de ejecución | - | `plugin-sdk/channel-status` | Auxiliares compartidos para instantáneas/resúmenes de estado del canal | + | `plugin-sdk/inbound-envelope` | Ayudantes compartidos de ruta entrante + construcción de sobre | + | `plugin-sdk/inbound-reply-dispatch` | Ayudantes compartidos de registro y despacho entrante | + | `plugin-sdk/messaging-targets` | Ayudantes de análisis/coincidencia de destinos | + | `plugin-sdk/outbound-media` | Ayudantes compartidos de carga de medios salientes | + | `plugin-sdk/outbound-runtime` | Ayudantes de identidad saliente/delegado de envío | + | `plugin-sdk/thread-bindings-runtime` | Ayudantes de ciclo de vida y adaptador de vinculaciones de hilo | + | `plugin-sdk/agent-media-payload` | Constructor heredado de payload de medios del agente | + | `plugin-sdk/conversation-runtime` | Ayudantes de vinculación de conversación/hilo, emparejamiento y vinculación configurada | + | `plugin-sdk/runtime-config-snapshot` | Ayudante de snapshot de configuración en tiempo de ejecución | + | `plugin-sdk/runtime-group-policy` | Ayudantes de resolución de políticas de grupo en tiempo de ejecución | + | `plugin-sdk/channel-status` | Ayudantes compartidos de snapshot/resumen del estado del canal | | `plugin-sdk/channel-config-primitives` | Primitivas acotadas de esquema de configuración de canal | - | `plugin-sdk/channel-config-writes` | Auxiliares de autorización para escritura de configuración de canal | - | `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas para plugins de canal | - | `plugin-sdk/allowlist-config-edit` | Auxiliares para leer/editar configuración de listas de permitidos | - | `plugin-sdk/group-access` | Auxiliares compartidos para decisiones de acceso a grupos | - | `plugin-sdk/direct-dm` | Auxiliares compartidos de autenticación/protección de DM directos | - | `plugin-sdk/interactive-runtime` | Auxiliares de normalización/reducción de cargas útiles de respuestas interactivas | - | `plugin-sdk/channel-inbound` | Auxiliares para debounce de entrada, coincidencia de menciones, políticas de mención y sobres | - | `plugin-sdk/channel-send-result` | Tipos de resultados de respuesta | + | `plugin-sdk/channel-config-writes` | Ayudantes de autorización para escrituras de configuración de canal | + | `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas de plugins de canal | + | `plugin-sdk/allowlist-config-edit` | Ayudantes de edición/lectura de configuración de lista de permitidos | + | `plugin-sdk/group-access` | Ayudantes compartidos de decisión de acceso a grupos | + | `plugin-sdk/direct-dm` | Ayudantes compartidos de autenticación/protección de DM directa | + | `plugin-sdk/interactive-runtime` | Ayudantes de normalización/reducción de payload de respuesta interactiva | + | `plugin-sdk/channel-inbound` | Ayudantes de debounce entrante, coincidencia de menciones, política de menciones y sobres | + | `plugin-sdk/channel-send-result` | Tipos de resultado de respuesta | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Auxiliares de análisis/coincidencia de destinos | - | `plugin-sdk/channel-contract` | Tipos de contratos de canal | + | `plugin-sdk/channel-targets` | Ayudantes de análisis/coincidencia de destinos | + | `plugin-sdk/channel-contract` | Tipos de contrato de canal | | `plugin-sdk/channel-feedback` | Cableado de feedback/reacciones | - | `plugin-sdk/channel-secret-runtime` | Auxiliares acotados de contrato de secretos como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` y tipos de destino de secretos | + | `plugin-sdk/channel-secret-runtime` | Ayudantes acotados de contrato de secretos como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, y tipos de destino de secretos | | Subruta | Exportaciones clave | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Auxiliares seleccionados para configurar proveedores locales/autohospedados | - | `plugin-sdk/self-hosted-provider-setup` | Auxiliares centrados en la configuración de proveedores autohospedados compatibles con OpenAI | - | `plugin-sdk/cli-backend` | Valores predeterminados del backend de CLI + constantes de watchdog | - | `plugin-sdk/provider-auth-runtime` | Auxiliares de resolución de claves de API en tiempo de ejecución para plugins de proveedor | - | `plugin-sdk/provider-auth-api-key` | Auxiliares de incorporación/escritura de perfiles de claves de API como `upsertApiKeyProfile` | + | `plugin-sdk/provider-setup` | Ayudantes curados de configuración de proveedores locales/autohospedados | + | `plugin-sdk/self-hosted-provider-setup` | Ayudantes centrados en la configuración de proveedores autohospedados compatibles con OpenAI | + | `plugin-sdk/cli-backend` | Valores predeterminados del backend CLI + constantes watchdog | + | `plugin-sdk/provider-auth-runtime` | Ayudantes de resolución de claves API en tiempo de ejecución para plugins de proveedores | + | `plugin-sdk/provider-auth-api-key` | Ayudantes de incorporación/escritura de perfiles para claves API como `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | Constructor estándar de resultados de autenticación OAuth | - | `plugin-sdk/provider-auth-login` | Auxiliares interactivos compartidos de inicio de sesión para plugins de proveedor | - | `plugin-sdk/provider-env-vars` | Auxiliares de búsqueda de variables de entorno para autenticación de proveedor | + | `plugin-sdk/provider-auth-login` | Ayudantes compartidos de inicio de sesión interactivo para plugins de proveedores | + | `plugin-sdk/provider-env-vars` | Ayudantes de búsqueda de variables de entorno de autenticación de proveedor | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, auxiliares de endpoint de proveedor y normalización de id de modelo como `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de política de reproducción, ayudantes de endpoints de proveedor, y ayudantes de normalización de identificadores de modelo como `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Auxiliares genéricos de HTTP/capacidades de endpoint para proveedores | - | `plugin-sdk/provider-web-fetch-contract` | Auxiliares acotados para contratos de configuración/selección de web fetch como `enablePluginInConfig` y `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Auxiliares de registro/caché de proveedores de web fetch | - | `plugin-sdk/provider-web-search-contract` | Auxiliares acotados para contratos de configuración/credenciales de búsqueda web como `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance | - | `plugin-sdk/provider-web-search` | Auxiliares de registro/caché/tiempo de ejecución para proveedores de búsqueda web | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquemas Gemini y auxiliares de compatibilidad de xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Ayudantes genéricos de capacidades HTTP/endpoint para proveedores | + | `plugin-sdk/provider-web-fetch-contract` | Ayudantes acotados de contrato para configuración/selección de web-fetch como `enablePluginInConfig` y `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Ayudantes de registro/caché de proveedores web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Ayudantes acotados de configuración/credenciales de búsqueda web para proveedores que no necesitan cableado de habilitación del plugin | + | `plugin-sdk/provider-web-search-contract` | Ayudantes acotados de contrato para configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, y setters/getters de credenciales con ámbito | + | `plugin-sdk/provider-web-search` | Ayudantes de registro/caché/tiempo de ejecución de proveedores de búsqueda web | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquemas Gemini, y ayudantes de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` y similares | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorios de streaming y auxiliares compartidos de envoltorios para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Auxiliares de parches de configuración para onboarding | - | `plugin-sdk/global-singleton` | Auxiliares de singleton/mapa/caché locales al proceso | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorios de stream, y ayudantes compartidos de envoltorios para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Ayudantes de parcheo de configuración para onboarding | + | `plugin-sdk/global-singleton` | Ayudantes de singleton/mapa/caché locales al proceso | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, auxiliares de registro de comandos, auxiliares de autorización de remitentes | - | `plugin-sdk/approval-auth-runtime` | Resolución de aprobadores y auxiliares de autenticación de acciones en el mismo chat | - | `plugin-sdk/approval-client-runtime` | Auxiliares nativos de perfiles/filtros de aprobación de exec | - | `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidad/entrega de aprobaciones | - | `plugin-sdk/approval-gateway-runtime` | Auxiliar compartido de resolución del gateway de aprobaciones | - | `plugin-sdk/approval-handler-adapter-runtime` | Auxiliares ligeros de carga de adaptadores nativos de aprobación para puntos de entrada de canales de acceso frecuente | - | `plugin-sdk/approval-handler-runtime` | Auxiliares más amplios de tiempo de ejecución para controladores de aprobación; prefiera las capas más acotadas de adaptador/gateway cuando sean suficientes | - | `plugin-sdk/approval-native-runtime` | Auxiliares nativos de destino de aprobación y enlace de cuentas | - | `plugin-sdk/approval-reply-runtime` | Auxiliares de cargas útiles de respuesta para aprobaciones de exec/plugin | - | `plugin-sdk/command-auth-native` | Autenticación nativa de comandos + auxiliares nativos de destino de sesión | - | `plugin-sdk/command-detection` | Auxiliares compartidos de detección de comandos | - | `plugin-sdk/command-surface` | Auxiliares de normalización del cuerpo del comando y de superficie de comandos | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, ayudantes de registro de comandos, ayudantes de autorización del remitente | + | `plugin-sdk/command-status` | Constructores de mensajes de comando/ayuda como `buildCommandsMessagePaginated` y `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Resolución de aprobadores y ayudantes de autenticación de acciones en el mismo chat | + | `plugin-sdk/approval-client-runtime` | Ayudantes de perfiles/filtros de aprobación nativa de ejecución | + | `plugin-sdk/approval-delivery-runtime` | Adaptadores compartidos de capacidad/entrega de aprobación nativa | + | `plugin-sdk/approval-gateway-runtime` | Ayudante compartido de resolución de gateway de aprobación | + | `plugin-sdk/approval-handler-adapter-runtime` | Ayudantes ligeros de carga de adaptadores de aprobación nativa para entrypoints rápidos de canal | + | `plugin-sdk/approval-handler-runtime` | Ayudantes más amplios del tiempo de ejecución del manejador de aprobación; prefiere los puntos de acceso más acotados de adaptador/gateway cuando sean suficientes | + | `plugin-sdk/approval-native-runtime` | Ayudantes de destino de aprobación nativa + vinculación de cuenta | + | `plugin-sdk/approval-reply-runtime` | Ayudantes de payload de respuesta de aprobación de exec/plugin | + | `plugin-sdk/command-auth-native` | Ayudantes de autenticación de comandos nativos + destinos de sesión nativa | + | `plugin-sdk/command-detection` | Ayudantes compartidos de detección de comandos | + | `plugin-sdk/command-surface` | Ayudantes de normalización del cuerpo de comandos y superficie de comandos | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Auxiliares acotados de recopilación de contratos de secretos para superficies de secretos de canales/plugins | - | `plugin-sdk/secret-ref-runtime` | Auxiliares acotados `coerceSecretRef` y de tipado de SecretRef para análisis de contratos/configuración de secretos | - | `plugin-sdk/security-runtime` | Auxiliares compartidos de confianza, control de DM, contenido externo y recopilación de secretos | - | `plugin-sdk/ssrf-policy` | Auxiliares de lista de permitidos de hosts y política SSRF de red privada | - | `plugin-sdk/ssrf-runtime` | Dispatcher fijado, fetch protegido por SSRF y auxiliares de política SSRF | - | `plugin-sdk/secret-input` | Auxiliares de análisis de entradas secretas | - | `plugin-sdk/webhook-ingress` | Auxiliares para solicitudes/destinos de webhook | - | `plugin-sdk/webhook-request-guards` | Auxiliares para tamaño de cuerpo/tiempo de espera de solicitudes | + | `plugin-sdk/channel-secret-runtime` | Ayudantes acotados de recopilación de contratos de secretos para superficies secretas de canal/plugin | + | `plugin-sdk/secret-ref-runtime` | Ayudantes acotados `coerceSecretRef` y de tipado SecretRef para análisis de contratos/configuración de secretos | + | `plugin-sdk/security-runtime` | Ayudantes compartidos de confianza, protección de DM, contenido externo y recopilación de secretos | + | `plugin-sdk/ssrf-policy` | Ayudantes de lista de permitidos de hosts y política SSRF de red privada | + | `plugin-sdk/ssrf-runtime` | Ayudantes de dispatcher fijado, fetch protegido con SSRF y política SSRF | + | `plugin-sdk/secret-input` | Ayudantes de análisis de entradas secretas | + | `plugin-sdk/webhook-ingress` | Ayudantes de solicitudes/destinos de webhook | + | `plugin-sdk/webhook-request-guards` | Ayudantes de tamaño del cuerpo de la solicitud/timeout | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/runtime` | Auxiliares amplios de tiempo de ejecución/registro/copias de seguridad/instalación de plugins | - | `plugin-sdk/runtime-env` | Auxiliares acotados de entorno de ejecución, logger, timeout, retry y backoff | - | `plugin-sdk/channel-runtime-context` | Auxiliares genéricos de registro y búsqueda de contexto de tiempo de ejecución del canal | + | `plugin-sdk/runtime` | Ayudantes amplios de tiempo de ejecución/logging/copias de seguridad/instalación de plugins | + | `plugin-sdk/runtime-env` | Ayudantes acotados de entorno de ejecución, logger, timeout, reintento y backoff | + | `plugin-sdk/channel-runtime-context` | Ayudantes genéricos de registro y búsqueda de contexto de tiempo de ejecución de canal | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Auxiliares compartidos para comandos/hooks/http/elementos interactivos del plugin | - | `plugin-sdk/hook-runtime` | Auxiliares compartidos del flujo de webhook/hooks internos | - | `plugin-sdk/lazy-runtime` | Auxiliares de importación/vinculación diferida del tiempo de ejecución como `createLazyRuntimeModule`, `createLazyRuntimeMethod` y `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Auxiliares para ejecución de procesos | - | `plugin-sdk/cli-runtime` | Auxiliares de formato, espera y versión para CLI | - | `plugin-sdk/gateway-runtime` | Cliente del gateway y auxiliares de parches para estado de canales | - | `plugin-sdk/config-runtime` | Auxiliares para cargar/escribir configuración | - | `plugin-sdk/telegram-command-config` | Normalización de nombre/descripción de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato integrada de Telegram no está disponible | - | `plugin-sdk/approval-runtime` | Auxiliares de aprobación de exec/plugin, constructores de capacidades de aprobación, auxiliares de autenticación/perfiles y auxiliares nativos de enrutamiento/tiempo de ejecución | - | `plugin-sdk/reply-runtime` | Auxiliares compartidos para entradas/respuestas en tiempo de ejecución, fragmentación, despacho, heartbeat y planificador de respuestas | - | `plugin-sdk/reply-dispatch-runtime` | Auxiliares acotados para despacho/finalización de respuestas | - | `plugin-sdk/reply-history` | Auxiliares compartidos para historial de respuestas en ventanas cortas como `buildHistoryContext`, `recordPendingHistoryEntry` y `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Ayudantes compartidos de comandos/hooks/http/interacción de plugins | + | `plugin-sdk/hook-runtime` | Ayudantes compartidos de pipeline de hooks webhook/internos | + | `plugin-sdk/lazy-runtime` | Ayudantes de importación/vinculación lazy en tiempo de ejecución como `createLazyRuntimeModule`, `createLazyRuntimeMethod`, y `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Ayudantes de ejecución de procesos | + | `plugin-sdk/cli-runtime` | Ayudantes de formato CLI, espera y versión | + | `plugin-sdk/gateway-runtime` | Ayudantes de cliente de gateway y parcheo de estado de canal | + | `plugin-sdk/config-runtime` | Ayudantes de carga/escritura de configuración | + | `plugin-sdk/telegram-command-config` | Normalización de nombres/descripciones de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato integrada de Telegram no está disponible | + | `plugin-sdk/approval-runtime` | Ayudantes de aprobación de exec/plugin, constructores de capacidad de aprobación, ayudantes de autenticación/perfiles, y ayudantes nativos de enrutamiento/tiempo de ejecución | + | `plugin-sdk/reply-runtime` | Ayudantes compartidos de tiempo de ejecución para entrada/respuesta, fragmentación, despacho, heartbeat, planificador de respuestas | + | `plugin-sdk/reply-dispatch-runtime` | Ayudantes acotados para despacho/finalización de respuestas | + | `plugin-sdk/reply-history` | Ayudantes compartidos de historial de respuestas de ventana corta como `buildHistoryContext`, `recordPendingHistoryEntry`, y `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Auxiliares acotados de fragmentación de texto/Markdown | - | `plugin-sdk/session-store-runtime` | Auxiliares de rutas del almacén de sesiones + `updated-at` | - | `plugin-sdk/state-paths` | Auxiliares de rutas de directorios de estado/OAuth | - | `plugin-sdk/routing` | Auxiliares de ruta/clave de sesión/enlace de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Auxiliares compartidos para resúmenes de estado de canal/cuenta, valores predeterminados del estado de ejecución y auxiliares de metadatos de incidencias | - | `plugin-sdk/target-resolver-runtime` | Auxiliares compartidos de resolución de destinos | - | `plugin-sdk/string-normalization-runtime` | Auxiliares de normalización de slug/cadenas | - | `plugin-sdk/request-url` | Extrae URL en cadena de entradas tipo fetch/request | - | `plugin-sdk/run-command` | Ejecutor de comandos temporizado con resultados normalizados de stdout/stderr | - | `plugin-sdk/param-readers` | Lectores comunes de parámetros de herramientas/CLI | - | `plugin-sdk/tool-send` | Extrae campos canónicos de destino de envío a partir de argumentos de herramientas | - | `plugin-sdk/temp-path` | Auxiliares compartidos para rutas temporales de descarga | - | `plugin-sdk/logging-core` | Logger de subsistema y auxiliares de redacción | - | `plugin-sdk/markdown-table-runtime` | Auxiliares del modo de tablas Markdown | - | `plugin-sdk/json-store` | Auxiliares pequeños para leer/escribir estado JSON | - | `plugin-sdk/file-lock` | Auxiliares reentrantes de bloqueo de archivos | - | `plugin-sdk/persistent-dedupe` | Auxiliares de caché de deduplicación respaldada por disco | - | `plugin-sdk/acp-runtime` | Auxiliares de tiempo de ejecución/sesión ACP y despacho de respuestas | + | `plugin-sdk/reply-chunking` | Ayudantes acotados de fragmentación de texto/markdown | + | `plugin-sdk/session-store-runtime` | Ayudantes de ruta de almacén de sesiones + `updated-at` | + | `plugin-sdk/state-paths` | Ayudantes de rutas de directorios de estado/OAuth | + | `plugin-sdk/routing` | Ayudantes de vinculación de rutas/claves de sesión/cuentas como `resolveAgentRoute`, `buildAgentSessionKey`, y `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Ayudantes compartidos de resumen de estado de canal/cuenta, valores predeterminados de estado de tiempo de ejecución y ayudantes de metadatos de incidencias | + | `plugin-sdk/target-resolver-runtime` | Ayudantes compartidos de resolución de destinos | + | `plugin-sdk/string-normalization-runtime` | Ayudantes de normalización de slug/cadenas | + | `plugin-sdk/request-url` | Extrae URL de cadena desde entradas tipo fetch/request | + | `plugin-sdk/run-command` | Ejecutor de comandos temporizado con resultados stdout/stderr normalizados | + | `plugin-sdk/param-readers` | Lectores comunes de parámetros para herramientas/CLI | + | `plugin-sdk/tool-payload` | Extrae payloads normalizados desde objetos de resultado de herramientas | + | `plugin-sdk/tool-send` | Extrae campos de destino de envío canónicos desde argumentos de herramientas | + | `plugin-sdk/temp-path` | Ayudantes compartidos de rutas temporales de descarga | + | `plugin-sdk/logging-core` | Logger de subsistema y ayudantes de redacción | + | `plugin-sdk/markdown-table-runtime` | Ayudantes de modo de tabla Markdown | + | `plugin-sdk/json-store` | Pequeños ayudantes de lectura/escritura de estado JSON | + | `plugin-sdk/file-lock` | Ayudantes reentrantes de bloqueo de archivos | + | `plugin-sdk/persistent-dedupe` | Ayudantes de caché de deduplicación persistente en disco | + | `plugin-sdk/acp-runtime` | Ayudantes de tiempo de ejecución/sesión ACP y de despacho de respuestas | | `plugin-sdk/agent-config-primitives` | Primitivas acotadas de esquema de configuración de tiempo de ejecución del agente | | `plugin-sdk/boolean-param` | Lector flexible de parámetros booleanos | - | `plugin-sdk/dangerous-name-runtime` | Auxiliares de resolución para coincidencias de nombres peligrosos | - | `plugin-sdk/device-bootstrap` | Auxiliares de arranque de dispositivos y tokens de pairing | - | `plugin-sdk/extension-shared` | Primitivas auxiliares compartidas para canales pasivos, estado y proxy ambiental | - | `plugin-sdk/models-provider-runtime` | Auxiliares de comandos `/models` y respuestas de proveedor | - | `plugin-sdk/skill-commands-runtime` | Auxiliares para listados de comandos de Skills | - | `plugin-sdk/native-command-registry` | Auxiliares nativos de registro/construcción/serialización de comandos | - | `plugin-sdk/provider-zai-endpoint` | Auxiliares de detección de endpoints de Z.AI | - | `plugin-sdk/infra-runtime` | Auxiliares de eventos del sistema/heartbeat | - | `plugin-sdk/collection-runtime` | Auxiliares pequeños de caché acotada | - | `plugin-sdk/diagnostic-runtime` | Auxiliares de indicadores y eventos de diagnóstico | - | `plugin-sdk/error-runtime` | Grafo de errores, formato, auxiliares compartidos de clasificación de errores, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Fetch envuelto, proxy y auxiliares de búsqueda fijada | - | `plugin-sdk/host-runtime` | Auxiliares de normalización de hostname y host SCP | - | `plugin-sdk/retry-runtime` | Auxiliares de configuración y ejecución de retry | - | `plugin-sdk/agent-runtime` | Auxiliares de directorio/identidad/espacio de trabajo del agente | - | `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorios respaldadas por configuración | + | `plugin-sdk/dangerous-name-runtime` | Ayudantes de resolución para coincidencia de nombres peligrosos | + | `plugin-sdk/device-bootstrap` | Ayudantes de bootstrap del dispositivo y tokens de emparejamiento | + | `plugin-sdk/extension-shared` | Primitivas auxiliares compartidas para canal pasivo, estado y proxy ambiental | + | `plugin-sdk/models-provider-runtime` | Ayudantes del comando `/models` y de respuesta de proveedores | + | `plugin-sdk/skill-commands-runtime` | Ayudantes de listado de comandos de Skills | + | `plugin-sdk/native-command-registry` | Ayudantes de registro/construcción/serialización de comandos nativos | + | `plugin-sdk/provider-zai-endpoint` | Ayudantes de detección de endpoints de Z.AI | + | `plugin-sdk/infra-runtime` | Ayudantes de eventos del sistema/heartbeat | + | `plugin-sdk/collection-runtime` | Pequeños ayudantes de caché acotada | + | `plugin-sdk/diagnostic-runtime` | Ayudantes de indicadores y eventos de diagnóstico | + | `plugin-sdk/error-runtime` | Grafo de errores, formato, ayudantes compartidos de clasificación de errores, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Ayudantes de fetch envuelto, proxy y búsquedas fijadas | + | `plugin-sdk/host-runtime` | Ayudantes de normalización de hostname y host SCP | + | `plugin-sdk/retry-runtime` | Ayudantes de configuración y ejecución de reintentos | + | `plugin-sdk/agent-runtime` | Ayudantes de directorio/identidad/workspace del agente | + | `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorios respaldada por configuración | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/media-runtime` | Auxiliares compartidos para obtener/transformar/almacenar medios, además de constructores de cargas útiles multimedia | - | `plugin-sdk/media-generation-runtime` | Auxiliares compartidos para failover de generación multimedia, selección de candidatos y mensajes de falta de modelo | - | `plugin-sdk/media-understanding` | Tipos de proveedores de comprensión multimedia más exportaciones orientadas a proveedores para auxiliares de imagen/audio | - | `plugin-sdk/text-runtime` | Auxiliares compartidos para texto/Markdown/registro como eliminación de texto visible para el asistente, renderizado/fragmentación/tablas Markdown, auxiliares de redacción, auxiliares de etiquetas de directivas y utilidades de texto seguro | - | `plugin-sdk/text-chunking` | Auxiliar de fragmentación de texto saliente | - | `plugin-sdk/speech` | Tipos de proveedores de voz más auxiliares orientados a proveedores para directivas, registro y validación | - | `plugin-sdk/speech-core` | Tipos compartidos de proveedores de voz, registro, directivas y auxiliares de normalización | - | `plugin-sdk/realtime-transcription` | Tipos de proveedores de transcripción en tiempo real y auxiliares de registro | - | `plugin-sdk/realtime-voice` | Tipos de proveedores de voz en tiempo real y auxiliares de registro | - | `plugin-sdk/image-generation` | Tipos de proveedores de generación de imágenes | - | `plugin-sdk/image-generation-core` | Tipos compartidos de generación de imágenes, failover, autenticación y auxiliares de registro | - | `plugin-sdk/music-generation` | Tipos de proveedores/solicitudes/resultados de generación musical | - | `plugin-sdk/music-generation-core` | Tipos compartidos de generación musical, auxiliares de failover, búsqueda de proveedores y análisis de referencias de modelos | - | `plugin-sdk/video-generation` | Tipos de proveedores/solicitudes/resultados de generación de video | - | `plugin-sdk/video-generation-core` | Tipos compartidos de generación de video, auxiliares de failover, búsqueda de proveedores y análisis de referencias de modelos | - | `plugin-sdk/webhook-targets` | Registro de destinos de webhook y auxiliares de instalación de rutas | - | `plugin-sdk/webhook-path` | Auxiliares de normalización de rutas de webhook | - | `plugin-sdk/web-media` | Auxiliares compartidos para carga de medios remotos/locales | - | `plugin-sdk/zod` | Reexportación de `zod` para consumidores del Plugin SDK | + | `plugin-sdk/media-runtime` | Ayudantes compartidos de obtención/transformación/almacenamiento de medios más constructores de payload de medios | + | `plugin-sdk/media-generation-runtime` | Ayudantes compartidos de failover en generación de medios, selección de candidatos y mensajes de modelo ausente | + | `plugin-sdk/media-understanding` | Tipos de proveedor de comprensión de medios más exportaciones auxiliares de imagen/audio para proveedores | + | `plugin-sdk/text-runtime` | Ayudantes compartidos de texto/markdown/logging como eliminación de texto visible para el asistente, renderizado/fragmentación/tablas de markdown, ayudantes de redacción, ayudantes de etiquetas de directivas y utilidades de texto seguro | + | `plugin-sdk/text-chunking` | Ayudante de fragmentación de texto saliente | + | `plugin-sdk/speech` | Tipos de proveedor de voz más exportaciones auxiliares de directivas, registro y validación para proveedores | + | `plugin-sdk/speech-core` | Tipos compartidos de proveedor de voz, registro, directivas y ayudantes de normalización | + | `plugin-sdk/realtime-transcription` | Tipos de proveedor de transcripción en tiempo real y ayudantes de registro | + | `plugin-sdk/realtime-voice` | Tipos de proveedor de voz en tiempo real y ayudantes de registro | + | `plugin-sdk/image-generation` | Tipos de proveedor de generación de imágenes | + | `plugin-sdk/image-generation-core` | Tipos compartidos de generación de imágenes, failover, autenticación y ayudantes de registro | + | `plugin-sdk/music-generation` | Tipos de proveedor/solicitud/resultado de generación musical | + | `plugin-sdk/music-generation-core` | Tipos compartidos de generación musical, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos | + | `plugin-sdk/video-generation` | Tipos de proveedor/solicitud/resultado de generación de video | + | `plugin-sdk/video-generation-core` | Tipos compartidos de generación de video, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos | + | `plugin-sdk/webhook-targets` | Registro de destinos webhook y ayudantes de instalación de rutas | + | `plugin-sdk/webhook-path` | Ayudantes de normalización de rutas webhook | + | `plugin-sdk/web-media` | Ayudantes compartidos de carga de medios remotos/locales | + | `plugin-sdk/zod` | `zod` reexportado para consumidores del plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/memory-core` | Superficie auxiliar integrada de memory-core para auxiliares de administrador/configuración/archivos/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Fachada de tiempo de ejecución para indexación/búsqueda en memoria | + | `plugin-sdk/memory-core` | Superficie auxiliar integrada memory-core para ayudantes de manager/config/archivos/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Fachada de tiempo de ejecución para índice/búsqueda de memoria | | `plugin-sdk/memory-core-host-engine-foundation` | Exportaciones del motor base del host de memoria | | `plugin-sdk/memory-core-host-engine-embeddings` | Exportaciones del motor de embeddings del host de memoria | | `plugin-sdk/memory-core-host-engine-qmd` | Exportaciones del motor QMD del host de memoria | | `plugin-sdk/memory-core-host-engine-storage` | Exportaciones del motor de almacenamiento del host de memoria | - | `plugin-sdk/memory-core-host-multimodal` | Auxiliares multimodales del host de memoria | - | `plugin-sdk/memory-core-host-query` | Auxiliares de consulta del host de memoria | - | `plugin-sdk/memory-core-host-secret` | Auxiliares de secretos del host de memoria | - | `plugin-sdk/memory-core-host-events` | Auxiliares del diario de eventos del host de memoria | - | `plugin-sdk/memory-core-host-status` | Auxiliares de estado del host de memoria | - | `plugin-sdk/memory-core-host-runtime-cli` | Auxiliares de tiempo de ejecución CLI del host de memoria | - | `plugin-sdk/memory-core-host-runtime-core` | Auxiliares principales de tiempo de ejecución del host de memoria | - | `plugin-sdk/memory-core-host-runtime-files` | Auxiliares de archivos/tiempo de ejecución del host de memoria | - | `plugin-sdk/memory-host-core` | Alias neutral respecto al proveedor para auxiliares principales de tiempo de ejecución del host de memoria | - | `plugin-sdk/memory-host-events` | Alias neutral respecto al proveedor para auxiliares del diario de eventos del host de memoria | - | `plugin-sdk/memory-host-files` | Alias neutral respecto al proveedor para auxiliares de archivos/tiempo de ejecución del host de memoria | - | `plugin-sdk/memory-host-markdown` | Auxiliares compartidos de Markdown administrado para plugins adyacentes a memoria | - | `plugin-sdk/memory-host-search` | Fachada de tiempo de ejecución activa de memoria para acceso al administrador de búsqueda | - | `plugin-sdk/memory-host-status` | Alias neutral respecto al proveedor para auxiliares de estado del host de memoria | - | `plugin-sdk/memory-lancedb` | Superficie auxiliar integrada de memory-lancedb | + | `plugin-sdk/memory-core-host-multimodal` | Ayudantes multimodales del host de memoria | + | `plugin-sdk/memory-core-host-query` | Ayudantes de consulta del host de memoria | + | `plugin-sdk/memory-core-host-secret` | Ayudantes de secretos del host de memoria | + | `plugin-sdk/memory-core-host-events` | Ayudantes del diario de eventos del host de memoria | + | `plugin-sdk/memory-core-host-status` | Ayudantes de estado del host de memoria | + | `plugin-sdk/memory-core-host-runtime-cli` | Ayudantes de tiempo de ejecución CLI del host de memoria | + | `plugin-sdk/memory-core-host-runtime-core` | Ayudantes centrales de tiempo de ejecución del host de memoria | + | `plugin-sdk/memory-core-host-runtime-files` | Ayudantes de archivos/tiempo de ejecución del host de memoria | + | `plugin-sdk/memory-host-core` | Alias neutral respecto al proveedor para los ayudantes centrales de tiempo de ejecución del host de memoria | + | `plugin-sdk/memory-host-events` | Alias neutral respecto al proveedor para los ayudantes del diario de eventos del host de memoria | + | `plugin-sdk/memory-host-files` | Alias neutral respecto al proveedor para los ayudantes de archivos/tiempo de ejecución del host de memoria | + | `plugin-sdk/memory-host-markdown` | Ayudantes compartidos de markdown administrado para plugins adyacentes a memoria | + | `plugin-sdk/memory-host-search` | Fachada activa de tiempo de ejecución de memoria para acceso al gestor de búsquedas | + | `plugin-sdk/memory-host-status` | Alias neutral respecto al proveedor para los ayudantes de estado del host de memoria | + | `plugin-sdk/memory-lancedb` | Superficie auxiliar integrada memory-lancedb | - + | Familia | Subrutas actuales | Uso previsto | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Auxiliares de soporte del plugin Browser integrado (`browser-support` sigue siendo el barril de compatibilidad) | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Ayudantes de soporte para el plugin integrado de navegador (`browser-support` sigue siendo el barrel de compatibilidad) | | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie auxiliar/de tiempo de ejecución integrada de Matrix | | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie auxiliar/de tiempo de ejecución integrada de LINE | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie auxiliar integrada de IRC | - | Auxiliares específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Capas auxiliares/de compatibilidad para canales integrados | - | Auxiliares específicos de autenticación/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Capas auxiliares para funciones/plugins integrados; `plugin-sdk/github-copilot-token` actualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` | + | Ayudantes específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Puntos de acceso de compatibilidad/ayuda para canales integrados | + | Ayudantes específicos de auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Puntos de acceso auxiliares de funciones/plugins integrados; `plugin-sdk/github-copilot-token` exporta actualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, y `resolveCopilotApiToken` | ## API de registro -La devolución de llamada `register(api)` recibe un objeto `OpenClawPluginApi` con estos +El callback `register(api)` recibe un objeto `OpenClawPluginApi` con estos métodos: ### Registro de capacidades @@ -308,42 +312,42 @@ métodos: | Método | Qué registra | | ------------------------------------------------ | ------------------------------- | | `api.registerProvider(...)` | Inferencia de texto (LLM) | -| `api.registerCliBackend(...)` | Backend de inferencia CLI local | +| `api.registerCliBackend(...)` | Backend local de inferencia CLI | | `api.registerChannel(...)` | Canal de mensajería | | `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real por streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex | +| `api.registerRealtimeVoiceProvider(...)` | Sesiones dúplex de voz en tiempo real | | `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video | | `api.registerImageGenerationProvider(...)` | Generación de imágenes | -| `api.registerMusicGenerationProvider(...)` | Generación musical | +| `api.registerMusicGenerationProvider(...)` | Generación de música | | `api.registerVideoGenerationProvider(...)` | Generación de video | -| `api.registerWebFetchProvider(...)` | Proveedor de obtención / scraping web | +| `api.registerWebFetchProvider(...)` | Proveedor de obtención/scraping web | | `api.registerWebSearchProvider(...)` | Búsqueda web | ### Herramientas y comandos -| Método | Qué registra | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Herramienta del agente (obligatoria o `{ optional: true }`) | -| `api.registerCommand(def)` | Comando personalizado (omite el LLM) | +| Método | Qué registra | +| ------------------------------- | -------------------------------------------- | +| `api.registerTool(tool, opts?)` | Herramienta del agente (requerida o `{ optional: true }`) | +| `api.registerCommand(def)` | Comando personalizado (omite el LLM) | ### Infraestructura | Método | Qué registra | | ---------------------------------------------- | -------------------------------------- | | `api.registerHook(events, handler, opts?)` | Hook de eventos | -| `api.registerHttpRoute(params)` | Endpoint HTTP del gateway | -| `api.registerGatewayMethod(name, handler)` | Método RPC del gateway | -| `api.registerCli(registrar, opts?)` | Subcomando CLI | +| `api.registerHttpRoute(params)` | Endpoint HTTP de la gateway | +| `api.registerGatewayMethod(name, handler)` | Método RPC de la gateway | +| `api.registerCli(registrar, opts?)` | Subcomando de CLI | | `api.registerService(service)` | Servicio en segundo plano | -| `api.registerInteractiveHandler(registration)` | Controlador interactivo | -| `api.registerMemoryPromptSupplement(builder)` | Sección aditiva del prompt adyacente a memoria | -| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de lectura/búsqueda de memoria | +| `api.registerInteractiveHandler(registration)` | Manejador interactivo | +| `api.registerMemoryPromptSupplement(builder)` | Sección de prompt aditiva adyacente a memoria | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de búsqueda/lectura de memoria | Los espacios de nombres administrativos reservados del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) siempre permanecen como `operator.admin`, incluso si un plugin intenta asignar -un alcance más restringido a un método del gateway. Prefiera prefijos específicos del plugin para -los métodos propiedad del plugin. +`update.*`) siempre permanecen como `operator.admin`, incluso si un plugin intenta asignar un +ámbito más restringido a un método de gateway. Prefiere prefijos específicos del plugin para +métodos propiedad del plugin. ### Metadatos de registro de CLI @@ -351,10 +355,10 @@ los métodos propiedad del plugin. - `commands`: raíces de comandos explícitas propiedad del registrador - `descriptors`: descriptores de comandos en tiempo de análisis usados para la ayuda del CLI raíz, - el enrutamiento y el registro diferido del CLI del plugin + enrutamiento y registro lazy del CLI del plugin -Si quiere que un comando del plugin siga cargándose de forma diferida en la ruta normal del CLI raíz, -proporcione `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese +Si quieres que un comando de plugin permanezca con lazy-loading en la ruta normal del CLI raíz, +proporciona `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese registrador. ```typescript @@ -367,7 +371,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Administrar cuentas, verificación, dispositivos y estado de perfil de Matrix", + description: "Administra cuentas, verificación, dispositivos y estado de perfil de Matrix", hasSubcommands: true, }, ], @@ -375,88 +379,87 @@ api.registerCli( ); ``` -Use `commands` por sí solo únicamente cuando no necesite registro diferido en el CLI raíz. -Esa ruta de compatibilidad ansiosa sigue siendo compatible, pero no instala -marcadores respaldados por descriptores para la carga diferida en tiempo de análisis. +Usa `commands` por sí solo solo cuando no necesites registro lazy del CLI raíz. +Esa ruta de compatibilidad eager sigue siendo compatible, pero no instala +marcadores de posición respaldados por descriptores para lazy loading en tiempo de análisis. -### Registro de backends de CLI +### Registro de backend CLI -`api.registerCliBackend(...)` permite que un plugin posea la configuración predeterminada de un -backend de CLI de IA local como `codex-cli`. +`api.registerCliBackend(...)` permite que un plugin se encargue de la configuración predeterminada de un +backend CLI local de IA como `codex-cli`. -- El `id` del backend se convierte en el prefijo del proveedor en referencias de modelo como `codex-cli/gpt-5`. +- El `id` del backend se convierte en el prefijo del proveedor en referencias de modelos como `codex-cli/gpt-5`. - La `config` del backend usa la misma forma que `agents.defaults.cliBackends.`. -- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.` sobre el - valor predeterminado del plugin antes de ejecutar la CLI. -- Use `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión +- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.` sobre la + predeterminada del plugin antes de ejecutar el CLI. +- Usa `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión (por ejemplo, normalizar formas antiguas de flags). ### Ranuras exclusivas -| Método | Qué registra | -| ------------------------------------------ | -------------------------------------- | -| `api.registerContextEngine(id, factory)` | Motor de contexto (uno activo a la vez) | -| `api.registerMemoryCapability(capability)` | Capacidad de memoria unificada | -| `api.registerMemoryPromptSection(builder)` | Constructor de secciones de prompts de memoria | -| `api.registerMemoryFlushPlan(resolver)` | Resolutor del plan de vaciado de memoria | -| `api.registerMemoryRuntime(runtime)` | Adaptador de tiempo de ejecución de memoria | +| Método | Qué registra | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Motor de contexto (solo uno activo a la vez). El callback `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar las adiciones al prompt. | +| `api.registerMemoryCapability(capability)` | Capacidad unificada de memoria | +| `api.registerMemoryPromptSection(builder)` | Constructor de sección de prompt de memoria | +| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plan de vaciado de memoria | +| `api.registerMemoryRuntime(runtime)` | Adaptador de tiempo de ejecución de memoria | ### Adaptadores de embeddings de memoria -| Método | Qué registra | -| ---------------------------------------------- | ------------------------------------------------ | +| Método | Qué registra | +| ---------------------------------------------- | ---------------------------------------------- | | `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embeddings de memoria para el plugin activo | -- `registerMemoryCapability` es la API exclusiva preferida para plugins de memoria. +- `registerMemoryCapability` es la API exclusiva de plugin de memoria preferida. - `registerMemoryCapability` también puede exponer `publicArtifacts.listArtifacts(...)` - para que plugins complementarios consuman artefactos de memoria exportados a través de - `openclaw/plugin-sdk/memory-host-core` en lugar de acceder al diseño privado - de un plugin de memoria específico. -- `registerMemoryPromptSection`, `registerMemoryFlushPlan` y - `registerMemoryRuntime` son API exclusivas de plugins de memoria compatibles con versiones heredadas. + para que los plugins complementarios consuman artefactos de memoria exportados mediante + `openclaw/plugin-sdk/memory-host-core` en lugar de acceder al diseño privado de un + plugin de memoria específico. +- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, y + `registerMemoryRuntime` son API exclusivas de plugin de memoria compatibles con el legado. - `registerMemoryEmbeddingProvider` permite que el plugin de memoria activo registre uno - o más id de adaptadores de embeddings (por ejemplo `openai`, `gemini` o un id - personalizado definido por el plugin). + o más ids de adaptadores de embeddings (por ejemplo `openai`, `gemini`, o un id personalizado definido por el plugin). - La configuración del usuario, como `agents.defaults.memorySearch.provider` y - `agents.defaults.memorySearch.fallback`, se resuelve contra esos id de adaptadores registrados. + `agents.defaults.memorySearch.fallback`, se resuelve contra esos ids de adaptadores registrados. ### Eventos y ciclo de vida -| Método | Qué hace | -| -------------------------------------------- | ---------------------------- | -| `api.on(hookName, handler, opts?)` | Hook tipado del ciclo de vida | -| `api.onConversationBindingResolved(handler)` | Devolución de llamada de enlace de conversación | +| Método | Qué hace | +| -------------------------------------------- | --------------------------- | +| `api.on(hookName, handler, opts?)` | Hook de ciclo de vida tipado | +| `api.onConversationBindingResolved(handler)` | Callback de vinculación de conversación | ### Semántica de decisión de hooks -- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad. -- `before_tool_call`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación. -- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad. -- `before_install`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación. -- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier controlador reclama el despacho, se omiten los controladores de menor prioridad y la ruta predeterminada de despacho del modelo. -- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad. -- `message_sending`: devolver `{ cancel: false }` se trata como ausencia de decisión (igual que omitir `cancel`), no como una anulación. +- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad. +- `before_tool_call`: devolver `{ block: false }` se trata como sin decisión (igual que omitir `block`), no como una anulación. +- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad. +- `before_install`: devolver `{ block: false }` se trata como sin decisión (igual que omitir `block`), no como una anulación. +- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier manejador reclama el despacho, se omiten los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo. +- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad. +- `message_sending`: devolver `{ cancel: false }` se trata como sin decisión (igual que omitir `cancel`), no como una anulación. ### Campos del objeto API -| Campo | Tipo | Descripción | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | -| `api.id` | `string` | Id del plugin | -| `api.name` | `string` | Nombre visible | -| `api.version` | `string?` | Versión del plugin (opcional) | -| `api.description` | `string?` | Descripción del plugin (opcional) | -| `api.source` | `string` | Ruta de origen del plugin | -| `api.rootDir` | `string?` | Directorio raíz del plugin (opcional) | -| `api.config` | `OpenClawConfig` | Instantánea actual de configuración (instantánea activa en memoria del tiempo de ejecución cuando está disponible) | -| `api.pluginConfig` | `Record` | Configuración específica del plugin desde `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Auxiliares de tiempo de ejecución](/es/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger con alcance (`debug`, `info`, `warn`, `error`) | +| Campo | Tipo | Descripción | +| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Id del plugin | +| `api.name` | `string` | Nombre para mostrar | +| `api.version` | `string?` | Versión del plugin (opcional) | +| `api.description` | `string?` | Descripción del plugin (opcional) | +| `api.source` | `string` | Ruta de origen del plugin | +| `api.rootDir` | `string?` | Directorio raíz del plugin (opcional) | +| `api.config` | `OpenClawConfig` | Snapshot actual de configuración (snapshot activo en memoria del tiempo de ejecución cuando está disponible) | +| `api.pluginConfig` | `Record` | Configuración específica del plugin desde `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Ayudantes de tiempo de ejecución](/es/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger con ámbito (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Modo de carga actual; `"setup-runtime"` es la ventana ligera de inicio/configuración previa a la entrada completa | -| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin | +| `api.resolvePath(input)` | `(string) => string` | Resuelve la ruta relativa a la raíz del plugin | ## Convención de módulos internos -Dentro de su plugin, use archivos barril locales para las importaciones internas: +Dentro de tu plugin, usa archivos barrel locales para las importaciones internas: ``` my-plugin/ @@ -467,36 +470,42 @@ my-plugin/ ``` - Nunca importe su propio plugin mediante `openclaw/plugin-sdk/` - desde código de producción. Encamine las importaciones internas mediante `./api.ts` o + Nunca importes tu propio plugin mediante `openclaw/plugin-sdk/` + desde código de producción. Dirige las importaciones internas a través de `./api.ts` o `./runtime-api.ts`. La ruta del SDK es solo el contrato externo. -Las superficies públicas cargadas mediante fachada de plugins integrados (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` y archivos de entrada pública similares) ahora prefieren la -instantánea de configuración activa del tiempo de ejecución cuando OpenClaw ya está en ejecución. Si todavía no existe una instantánea de tiempo de ejecución, recurren al archivo de configuración resuelto en disco. +Las superficies públicas de plugins integrados cargadas por fachada (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts`, y archivos de entrada pública similares) ahora prefieren el +snapshot activo de configuración en tiempo de ejecución cuando OpenClaw ya se está ejecutando. Si todavía +no existe un snapshot en tiempo de ejecución, recurren al archivo de configuración resuelto en disco. -Los plugins de proveedor también pueden exponer un barril de contrato local del plugin y de alcance limitado cuando un auxiliar es intencionalmente específico del proveedor y aún no pertenece a una subruta genérica del SDK. Ejemplo integrado actual: el proveedor Anthropic mantiene sus auxiliares de streaming de Claude en su propia capa pública `api.ts` / `contract-api.ts` en lugar de promover la lógica del encabezado beta de Anthropic y `service_tier` a un contrato genérico `plugin-sdk/*`. +Los plugins de proveedores también pueden exponer un barrel local del plugin con un contrato acotado cuando un +ayudante es intencionalmente específico del proveedor y aún no pertenece a una subruta genérica +del SDK. Ejemplo integrado actual: el proveedor Anthropic conserva sus +ayudantes de stream Claude en su propio punto de acceso público `api.ts` / `contract-api.ts` en lugar de +promover la lógica de encabezado beta de Anthropic y `service_tier` a un contrato genérico +`plugin-sdk/*`. Otros ejemplos integrados actuales: - `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedores, - auxiliares de modelos predeterminados y constructores de proveedores en tiempo real + ayudantes de modelo predeterminado y constructores de proveedores realtime - `@openclaw/openrouter-provider`: `api.ts` exporta el constructor del proveedor más - auxiliares de onboarding/configuración + ayudantes de onboarding/configuración - El código de producción de extensiones también debe evitar importaciones desde `openclaw/plugin-sdk/`. - Si un auxiliar se comparte realmente, promuévalo a una subruta neutral del SDK - como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` u otra - superficie orientada a capacidades, en lugar de acoplar dos plugins entre sí. + El código de producción de extensiones también debe evitar las importaciones + `openclaw/plugin-sdk/`. Si un ayudante es realmente compartido, promuévelo a una subruta neutra del SDK + como `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, u otra + superficie orientada a capacidades en lugar de acoplar dos plugins entre sí. ## Relacionado -- [Puntos de entrada](/es/plugins/sdk-entrypoints) — opciones de `definePluginEntry` y `defineChannelPluginEntry` -- [Auxiliares de tiempo de ejecución](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime` -- [Configuración y config](/es/plugins/sdk-setup) — empaquetado, manifiestos y esquemas de configuración -- [Pruebas](/es/plugins/sdk-testing) — utilidades de prueba y reglas de lint -- [Migración del SDK](/es/plugins/sdk-migration) — migración desde superficies obsoletas -- [Internos de plugins](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades +- [Entry Points](/es/plugins/sdk-entrypoints) — opciones de `definePluginEntry` y `defineChannelPluginEntry` +- [Runtime Helpers](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime` +- [Setup and Config](/es/plugins/sdk-setup) — empaquetado, manifiestos, esquemas de configuración +- [Testing](/es/plugins/sdk-testing) — utilidades de prueba y reglas de lint +- [SDK Migration](/es/plugins/sdk-migration) — migración desde superficies obsoletas +- [Plugin Internals](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades diff --git a/docs/es/plugins/sdk-provider-plugins.md b/docs/es/plugins/sdk-provider-plugins.md index 4baa1d335..0be9ed332 100644 --- a/docs/es/plugins/sdk-provider-plugins.md +++ b/docs/es/plugins/sdk-provider-plugins.md @@ -1,30 +1,30 @@ --- read_when: - Estás creando un nuevo plugin de proveedor de modelos - - Quieres añadir un proxy compatible con OpenAI o un LLM personalizado a OpenClaw - - Necesitas entender la autenticación del proveedor, los catálogos y los hooks de tiempo de ejecución + - Quieres añadir a OpenClaw un proxy compatible con OpenAI o un LLM personalizado + - Necesitas entender la autenticación del proveedor, los catálogos y los hooks de runtime sidebarTitle: Provider Plugins summary: Guía paso a paso para crear un plugin de proveedor de modelos para OpenClaw -title: Creación de plugins de proveedor +title: Crear plugins de proveedor x-i18n: - generated_at: "2026-04-07T05:06:01Z" + generated_at: "2026-04-09T01:30:35Z" model: gpt-5.4 provider: openai - source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990 + source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- -# Creación de plugins de proveedor +# Crear plugins de proveedor -Esta guía explica cómo crear un plugin de proveedor que añada un proveedor de modelos +Esta guía explica cómo crear un plugin de proveedor que añade un proveedor de modelos (LLM) a OpenClaw. Al final tendrás un proveedor con un catálogo de modelos, -autenticación por clave de API y resolución dinámica de modelos. +autenticación mediante clave de API y resolución dinámica de modelos. - Si todavía no has creado ningún plugin de OpenClaw, lee primero - [Primeros pasos](/es/plugins/building-plugins) para ver la estructura básica del - paquete y la configuración del manifiesto. + Si aún no has creado ningún plugin de OpenClaw, lee primero + [Getting Started](/es/plugins/building-plugins) para conocer la estructura básica + del paquete y la configuración del manifiesto. ## Tutorial @@ -57,7 +57,7 @@ autenticación por clave de API y resolución dinámica de modelos. { "id": "acme-ai", "name": "Acme AI", - "description": "Proveedor de modelos Acme AI", + "description": "Acme AI model provider", "providers": ["acme-ai"], "modelSupport": { "modelPrefixes": ["acme-"] @@ -65,17 +65,20 @@ autenticación por clave de API y resolución dinámica de modelos. "providerAuthEnvVars": { "acme-ai": ["ACME_AI_API_KEY"] }, + "providerAuthAliases": { + "acme-ai-coding": "acme-ai" + }, "providerAuthChoices": [ { "provider": "acme-ai", "method": "api-key", "choiceId": "acme-ai-api-key", - "choiceLabel": "Clave de API de Acme AI", + "choiceLabel": "Acme AI API key", "groupId": "acme-ai", "groupLabel": "Acme AI", "cliFlag": "--acme-ai-api-key", "cliOption": "--acme-ai-api-key ", - "cliDescription": "Clave de API de Acme AI" + "cliDescription": "Acme AI API key" } ], "configSchema": { @@ -87,16 +90,17 @@ autenticación por clave de API y resolución dinámica de modelos. El manifiesto declara `providerAuthEnvVars` para que OpenClaw pueda detectar - credenciales sin cargar el tiempo de ejecución de tu plugin. `modelSupport` es opcional - y permite que OpenClaw cargue automáticamente tu plugin de proveedor a partir de IDs abreviados de modelo - como `acme-large` antes de que existan hooks de tiempo de ejecución. Si publicas el + credenciales sin cargar el runtime de tu plugin. Añade `providerAuthAliases` + cuando una variante del proveedor deba reutilizar la autenticación de otro id de proveedor. `modelSupport` + es opcional y permite que OpenClaw cargue automáticamente tu plugin de proveedor a partir de ids + abreviados de modelo como `acme-large` antes de que existan hooks de runtime. Si publicas el proveedor en ClawHub, esos campos `openclaw.compat` y `openclaw.build` son obligatorios en `package.json`. - Un proveedor mínimo necesita `id`, `label`, `auth` y `catalog`: + Un proveedor mínimo necesita un `id`, `label`, `auth` y `catalog`: ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -167,13 +171,14 @@ autenticación por clave de API y resolución dinámica de modelos. }); ``` - Ese es un proveedor funcional. Los usuarios ahora pueden ejecutar - `openclaw onboard --acme-ai-api-key ` y seleccionar - `acme-ai/acme-large` como modelo. + Ese es un proveedor funcional. Ahora los usuarios pueden + ejecutar `openclaw onboard --acme-ai-api-key ` y seleccionar + `acme-ai/acme-large` como su modelo. - Para proveedores integrados que solo registran un proveedor de texto con - autenticación por clave de API más un único tiempo de ejecución respaldado por catálogo, prefiere el helper - más específico `defineSingleProviderPluginEntry(...)`: + Para proveedores incluidos que solo registran un proveedor de texto con + autenticación por clave de API más un único runtime respaldado por catálogo, es preferible + usar el helper más específico + `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -208,25 +213,25 @@ autenticación por clave de API y resolución dinámica de modelos. }); ``` - Si tu flujo de autenticación también necesita modificar `models.providers.*`, alias y - el modelo predeterminado del agente durante la incorporación, usa los helpers predefinidos de + Si tu flujo de autenticación también necesita aplicar parches a `models.providers.*`, alias y + al modelo predeterminado del agente durante la incorporación, usa los helpers predefinidos de `openclaw/plugin-sdk/provider-onboard`. Los helpers más específicos son `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` y `createModelCatalogPresetAppliers(...)`. Cuando el endpoint nativo de un proveedor admite bloques de uso en streaming en el - transporte normal `openai-completions`, prefiere los helpers compartidos de catálogo en + transporte normal `openai-completions`, es preferible usar los helpers compartidos de catálogo en `openclaw/plugin-sdk/provider-catalog-shared` en lugar de codificar comprobaciones - de ID de proveedor. `supportsNativeStreamingUsageCompat(...)` y - `applyProviderNativeStreamingUsageCompat(...)` detectan la compatibilidad a partir del mapa - de capacidades del endpoint, por lo que los endpoints nativos de estilo Moonshot/DashScope siguen - pudiendo activarse incluso cuando un plugin usa un ID de proveedor personalizado. + del id del proveedor. `supportsNativeStreamingUsageCompat(...)` y + `applyProviderNativeStreamingUsageCompat(...)` detectan la compatibilidad a partir del mapa de capacidades + del endpoint, de modo que los endpoints nativos tipo Moonshot/DashScope sigan + activándose incluso cuando un plugin esté usando un id de proveedor personalizado. - Si tu proveedor acepta IDs arbitrarios de modelo (como un proxy o router), + Si tu proveedor acepta ids de modelo arbitrarios (como un proxy o router), añade `resolveDynamicModel`: ```typescript @@ -249,17 +254,17 @@ autenticación por clave de API y resolución dinámica de modelos. ``` Si la resolución requiere una llamada de red, usa `prepareDynamicModel` para el - calentamiento asíncrono: `resolveDynamicModel` se vuelve a ejecutar después de que se complete. + calentamiento asíncrono; `resolveDynamicModel` se ejecuta de nuevo cuando se completa. - + La mayoría de los proveedores solo necesitan `catalog` + `resolveDynamicModel`. Añade hooks - de forma incremental a medida que tu proveedor los necesite. + de forma incremental según lo requiera tu proveedor. - Los constructores de helpers compartidos ahora cubren las familias más comunes de - compatibilidad de repetición/herramientas, por lo que normalmente los plugins no necesitan conectar - manualmente cada hook uno por uno: + Los generadores de helpers compartidos ahora cubren las familias más habituales de + reproducción/compatibilidad con herramientas, así que normalmente los plugins no necesitan + conectar manualmente cada hook uno por uno: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -279,17 +284,17 @@ autenticación por clave de API y resolución dinámica de modelos. }); ``` - Familias de repetición disponibles actualmente: + Familias de reproducción disponibles actualmente: | Family | What it wires in | | --- | --- | - | `openai-compatible` | Política compartida de repetición estilo OpenAI para transportes compatibles con OpenAI, incluido el saneamiento de IDs de llamadas a herramientas, correcciones del orden con el asistente primero y validación genérica de turnos Gemini cuando el transporte lo necesita | - | `anthropic-by-model` | Política de repetición compatible con Claude elegida por `modelId`, para que los transportes `anthropic-message` solo apliquen limpieza de bloques de pensamiento específica de Claude cuando el modelo resuelto sea realmente un ID de Claude | - | `google-gemini` | Política nativa de repetición de Gemini más saneamiento de repetición de arranque y modo de salida de razonamiento etiquetado | - | `passthrough-gemini` | Saneamiento de firmas de pensamiento de Gemini para modelos Gemini que se ejecutan a través de transportes proxy compatibles con OpenAI; no habilita la validación nativa de repetición de Gemini ni las reescrituras de arranque | - | `hybrid-anthropic-openai` | Política híbrida para proveedores que mezclan superficies de modelo `anthropic-message` y compatibles con OpenAI en un solo plugin; la eliminación opcional de bloques de pensamiento solo para Claude sigue limitada al lado Anthropic | + | `openai-compatible` | Política compartida de reproducción de estilo OpenAI para transportes compatibles con OpenAI, incluida la limpieza de `tool-call-id`, correcciones de orden con el asistente primero y validación genérica de turnos de Gemini cuando el transporte lo necesita | + | `anthropic-by-model` | Política de reproducción compatible con Claude elegida por `modelId`, de modo que los transportes `anthropic-message` solo reciban limpieza de bloques de razonamiento específica de Claude cuando el modelo resuelto sea realmente un id de Claude | + | `google-gemini` | Política nativa de reproducción de Gemini más saneamiento de reproducción bootstrap y modo etiquetado de salida de razonamiento | + | `passthrough-gemini` | Saneamiento de firmas de pensamiento de Gemini para modelos Gemini que se ejecutan mediante transportes proxy compatibles con OpenAI; no habilita validación nativa de reproducción de Gemini ni reescrituras de bootstrap | + | `hybrid-anthropic-openai` | Política híbrida para proveedores que mezclan superficies de modelos `anthropic-message` y compatibles con OpenAI en un solo plugin; la eliminación opcional de bloques de razonamiento solo para Claude permanece limitada al lado Anthropic | - Ejemplos integrados reales: + Ejemplos reales incluidos: - `google` y `google-gemini-cli`: `google-gemini` - `openrouter`, `kilocode`, `opencode` y `opencode-go`: `passthrough-gemini` @@ -297,19 +302,19 @@ autenticación por clave de API y resolución dinámica de modelos. - `minimax`: `hybrid-anthropic-openai` - `moonshot`, `ollama`, `xai` y `zai`: `openai-compatible` - Familias de streaming disponibles actualmente: + Familias de stream disponibles actualmente: | Family | What it wires in | | --- | --- | - | `google-thinking` | Normalización de la carga útil de pensamiento de Gemini en la ruta de streaming compartida | - | `kilocode-thinking` | Envoltorio de razonamiento de Kilo en la ruta de streaming proxy compartida, con `kilo/auto` e IDs de razonamiento proxy no compatibles omitiendo el pensamiento inyectado | - | `moonshot-thinking` | Asignación de carga útil de pensamiento nativo binario de Moonshot a partir de la configuración + nivel de `/think` | - | `minimax-fast-mode` | Reescritura de modelo de modo rápido de MiniMax en la ruta de streaming compartida | - | `openai-responses-defaults` | Envoltorios compartidos de Responses nativas de OpenAI/Codex: encabezados de atribución, `/fast`/`serviceTier`, verbosidad del texto, búsqueda web nativa de Codex, conformación de carga útil de compatibilidad de razonamiento y gestión del contexto de Responses | - | `openrouter-thinking` | Envoltorio de razonamiento de OpenRouter para rutas proxy, con los saltos de modelo no compatible/`auto` gestionados de forma centralizada | + | `google-thinking` | Normalización de carga útil de pensamiento de Gemini en la ruta de stream compartida | + | `kilocode-thinking` | Envoltorio de razonamiento de Kilo en la ruta de stream proxy compartida, con `kilo/auto` e ids de razonamiento proxy no compatibles omitiendo el pensamiento inyectado | + | `moonshot-thinking` | Asignación de carga útil binaria nativa de pensamiento de Moonshot a partir de la configuración y del nivel `/think` | + | `minimax-fast-mode` | Reescritura de modelos de modo rápido de MiniMax en la ruta de stream compartida | + | `openai-responses-defaults` | Envoltorios compartidos de Responses nativas de OpenAI/Codex: encabezados de atribución, `/fast`/`serviceTier`, verbosidad del texto, búsqueda web nativa de Codex, ajuste de carga útil compatible con razonamiento y gestión de contexto de Responses | + | `openrouter-thinking` | Envoltorio de razonamiento de OpenRouter para rutas proxy, con omisiones para modelos no compatibles/`auto` gestionadas de forma centralizada | | `tool-stream-default-on` | Envoltorio `tool_stream` activado por defecto para proveedores como Z.AI que quieren streaming de herramientas salvo que se desactive explícitamente | - Ejemplos integrados reales: + Ejemplos reales incluidos: - `google` y `google-gemini-cli`: `google-thinking` - `kilocode`: `kilocode-thinking` @@ -319,25 +324,25 @@ autenticación por clave de API y resolución dinámica de modelos. - `openrouter`: `openrouter-thinking` - `zai`: `tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` también exporta el enum de familia - de repetición más los helpers compartidos sobre los que se construyen esas familias. Las - exportaciones públicas más comunes incluyen: + `openclaw/plugin-sdk/provider-model-shared` también exporta el enum de familias de reproducción + junto con los helpers compartidos sobre los que se construyen esas familias. Las + exportaciones públicas habituales incluyen: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - constructores compartidos de repetición como `buildOpenAICompatibleReplayPolicy(...)`, + - generadores compartidos de reproducción como `buildOpenAICompatibleReplayPolicy(...)`, `buildAnthropicReplayPolicyForModel(...)`, `buildGoogleGeminiReplayPolicy(...)` y `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - helpers de repetición de Gemini como `sanitizeGoogleGeminiReplayHistory(...)` + - helpers de reproducción de Gemini como `sanitizeGoogleGeminiReplayHistory(...)` y `resolveTaggedReasoningOutputMode()` - helpers de endpoint/modelo como `resolveProviderEndpoint(...)`, `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` y `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` expone tanto el constructor de familias como - los helpers públicos de envoltorio que esas familias reutilizan. Las exportaciones públicas - más comunes incluyen: + `openclaw/plugin-sdk/provider-stream` expone tanto el generador de familias como + los helpers públicos de envoltorio que reutilizan esas familias. Las + exportaciones públicas habituales incluyen: - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` @@ -351,44 +356,44 @@ autenticación por clave de API y resolución dinámica de modelos. - envoltorios compartidos de proxy/proveedor como `createOpenRouterWrapper(...)`, `createToolStreamWrapper(...)` y `createMinimaxFastModeWrapper(...)` - Algunos helpers de streaming permanecen intencionadamente locales al proveedor. Ejemplo - integrado actual: `@openclaw/anthropic-provider` exporta + Algunos helpers de stream se mantienen locales al proveedor de forma intencionada. Ejemplo + actual incluido: `@openclaw/anthropic-provider` exporta `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` y los - constructores de envoltorios Anthropic de nivel inferior desde su interfaz pública `api.ts` / + generadores de envoltorio Anthropic de nivel inferior desde su punto de unión público `api.ts` / `contract-api.ts`. Esos helpers siguen siendo específicos de Anthropic porque - también codifican el manejo de betas de Claude OAuth y la restricción de `context1m`. + también codifican el manejo beta de OAuth de Claude y el control de `context1m`. - Otros proveedores integrados también mantienen locales los envoltorios específicos del transporte cuando + Otros proveedores incluidos también mantienen envoltorios específicos de transporte como locales cuando el comportamiento no se comparte limpiamente entre familias. Ejemplo actual: el - plugin integrado de xAI mantiene en su propio - `wrapStreamFn` la conformación nativa de xAI Responses, incluidas las reescrituras de alias `/fast`, el valor predeterminado de `tool_stream`, - la limpieza de herramientas estrictas no compatibles y la eliminación - de carga útil de razonamiento específica de xAI. + plugin xAI incluido mantiene el ajuste nativo de Responses de xAI en su propio + `wrapStreamFn`, incluyendo reescrituras de alias `/fast`, `tool_stream` predeterminado, + limpieza estricta de herramientas no compatibles y eliminación de carga útil + de razonamiento específica de xAI. `openclaw/plugin-sdk/provider-tools` actualmente expone una familia compartida de esquemas de herramientas más helpers compartidos de esquema/compatibilidad: - - `ProviderToolCompatFamily` documenta el inventario actual de familias compartidas. - - `buildProviderToolCompatFamilyHooks("gemini")` conecta la - limpieza + diagnóstico de esquemas de Gemini para proveedores que necesitan esquemas de herramientas seguros para Gemini. - - `normalizeGeminiToolSchemas(...)` e `inspectGeminiToolSchemas(...)` - son los helpers públicos subyacentes del esquema Gemini. - - `resolveXaiModelCompatPatch()` devuelve el parche de compatibilidad integrado de xAI: - `toolSchemaProfile: "xai"`, palabras clave de esquema no compatibles, compatibilidad - nativa con `web_search` y decodificación de argumentos de llamadas a herramientas con entidades HTML. - - `applyXaiModelCompat(model)` aplica ese mismo parche de compatibilidad de xAI a un + - `ProviderToolCompatFamily` documenta hoy el inventario de familias compartidas. + - `buildProviderToolCompatFamilyHooks("gemini")` conecta limpieza de esquemas Gemini + + diagnósticos para proveedores que necesitan esquemas de herramientas seguros para Gemini. + - `normalizeGeminiToolSchemas(...)` y `inspectGeminiToolSchemas(...)` + son los helpers públicos subyacentes para esquemas Gemini. + - `resolveXaiModelCompatPatch()` devuelve el parche de compatibilidad xAI incluido: + `toolSchemaProfile: "xai"`, palabras clave de esquema no compatibles, compatibilidad nativa con + `web_search` y decodificación de argumentos de llamadas a herramientas con entidades HTML. + - `applyXaiModelCompat(model)` aplica ese mismo parche de compatibilidad xAI a un modelo resuelto antes de que llegue al ejecutor. - Ejemplo integrado real: el plugin de xAI usa `normalizeResolvedModel` más - `contributeResolvedModelCompat` para que esos metadatos de compatibilidad sigan siendo propiedad del - proveedor en lugar de codificar reglas de xAI en el núcleo. + Ejemplo real incluido: el plugin xAI usa `normalizeResolvedModel` más + `contributeResolvedModelCompat` para mantener esos metadatos de compatibilidad bajo + propiedad del proveedor en lugar de codificar reglas xAI en el núcleo. - El mismo patrón de raíz de paquete también sustenta otros proveedores integrados: + El mismo patrón de raíz de paquete también respalda otros proveedores incluidos: - - `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedor, - helpers de modelos predeterminados y constructores de proveedores en tiempo real - - `@openclaw/openrouter-provider`: `api.ts` exporta el constructor de proveedor + - `@openclaw/openai-provider`: `api.ts` exporta generadores de proveedor, + helpers de modelo predeterminado y generadores de proveedores realtime + - `@openclaw/openrouter-provider`: `api.ts` exporta el generador de proveedor más helpers de incorporación/configuración @@ -424,7 +429,7 @@ autenticación por clave de API y resolución dinámica de modelos. }, ``` - + Para proveedores que necesitan encabezados o metadatos nativos de solicitud/sesión en transportes HTTP o WebSocket genéricos: @@ -462,73 +467,72 @@ autenticación por clave de API y resolución dinámica de modelos. - OpenClaw llama a los hooks en este orden. La mayoría de los proveedores solo usan 2-3: + OpenClaw llama a los hooks en este orden. La mayoría de los proveedores solo usan 2 o 3: | # | Hook | Cuándo usarlo | | --- | --- | --- | - | 1 | `catalog` | Catálogo de modelos o valores predeterminados de URL base | - | 2 | `applyConfigDefaults` | Valores globales predeterminados controlados por el proveedor durante la materialización de la configuración | - | 3 | `normalizeModelId` | Limpieza de alias de IDs de modelo heredados/de vista previa antes de la búsqueda | - | 4 | `normalizeTransport` | Limpieza de `api` / `baseUrl` de la familia de proveedor antes del ensamblado genérico del modelo | - | 5 | `normalizeConfig` | Normalizar la configuración `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Reescrituras de compatibilidad de uso de streaming nativo para proveedores configurados | - | 7 | `resolveConfigApiKey` | Resolución de autenticación de marcador de entorno controlada por el proveedor | + | 1 | `catalog` | Catálogo de modelos o valores predeterminados de `baseUrl` | + | 2 | `applyConfigDefaults` | Valores predeterminados globales propiedad del proveedor durante la materialización de la configuración | + | 3 | `normalizeModelId` | Limpieza de alias heredados/de vista previa de ids de modelo antes de la búsqueda | + | 4 | `normalizeTransport` | Limpieza de familia del proveedor `api` / `baseUrl` antes del ensamblado genérico del modelo | + | 5 | `normalizeConfig` | Normalizar configuración `models.providers.` | + | 6 | `applyNativeStreamingUsageCompat` | Reescrituras de compatibilidad de uso nativo en streaming para proveedores de configuración | + | 7 | `resolveConfigApiKey` | Resolución de autenticación de marcadores de entorno propiedad del proveedor | | 8 | `resolveSyntheticAuth` | Autenticación sintética local/autohospedada o basada en configuración | - | 9 | `shouldDeferSyntheticProfileAuth` | Colocar marcadores de posición sintéticos de perfiles almacenados por detrás de la autenticación de entorno/configuración | - | 10 | `resolveDynamicModel` | Aceptar IDs arbitrarios de modelo ascendente | + | 9 | `shouldDeferSyntheticProfileAuth` | Rebajar placeholders sintéticos de perfiles almacenados por detrás de autenticación env/config | + | 10 | `resolveDynamicModel` | Aceptar ids de modelo arbitrarios del upstream | | 11 | `prepareDynamicModel` | Obtención asíncrona de metadatos antes de resolver | | 12 | `normalizeResolvedModel` | Reescrituras de transporte antes del ejecutor | - Notas sobre el comportamiento de respaldo en tiempo de ejecución: + Notas sobre el fallback en runtime: - - `normalizeConfig` comprueba primero el proveedor coincidente y después otros - plugins de proveedor con capacidad de hook hasta que uno cambie realmente la configuración. - Si ningún hook de proveedor reescribe una entrada de configuración compatible de la familia Google, - se sigue aplicando el normalizador integrado de configuración de Google. - - `resolveConfigApiKey` usa el hook del proveedor cuando está expuesto. La ruta integrada - `amazon-bedrock` también tiene aquí un resolvedor integrado de marcadores - de entorno de AWS, aunque la autenticación en tiempo de ejecución de Bedrock siga usando la - cadena predeterminada del SDK de AWS. - | 13 | `contributeResolvedModelCompat` | Banderas de compatibilidad para modelos del proveedor detrás de otro transporte compatible | - | 14 | `capabilities` | Bolsa heredada de capacidades estáticas; solo para compatibilidad | - | 15 | `normalizeToolSchemas` | Limpieza de esquemas de herramientas controlada por el proveedor antes del registro | - | 16 | `inspectToolSchemas` | Diagnóstico de esquemas de herramientas controlado por el proveedor | + - `normalizeConfig` primero comprueba el proveedor coincidente y después otros + plugins de proveedor con capacidad de hooks hasta que uno realmente cambie la configuración. + Si ningún hook de proveedor reescribe una entrada de configuración compatible de la familia Google, + se sigue aplicando el normalizador de configuración de Google incluido. + - `resolveConfigApiKey` usa el hook del proveedor cuando se expone. La ruta incluida + de `amazon-bedrock` también tiene aquí un resolvedor integrado de marcadores de entorno AWS, + aunque la autenticación de runtime de Bedrock siga usando la cadena predeterminada del SDK de AWS. + | 13 | `contributeResolvedModelCompat` | Indicadores de compatibilidad para modelos de proveedor detrás de otro transporte compatible | + | 14 | `capabilities` | Bolsa estática heredada de capacidades; solo compatibilidad | + | 15 | `normalizeToolSchemas` | Limpieza de esquemas de herramientas propiedad del proveedor antes del registro | + | 16 | `inspectToolSchemas` | Diagnósticos de esquemas de herramientas propiedad del proveedor | | 17 | `resolveReasoningOutputMode` | Contrato de salida de razonamiento etiquetado frente a nativo | - | 18 | `prepareExtraParams` | Parámetros de solicitud predeterminados | - | 19 | `createStreamFn` | Transporte `StreamFn` totalmente personalizado | - | 20 | `wrapStreamFn` | Envoltorios personalizados de encabezados/cuerpo en la ruta normal de streaming | + | 18 | `prepareExtraParams` | Parámetros predeterminados de la solicitud | + | 19 | `createStreamFn` | Transporte `StreamFn` completamente personalizado | + | 20 | `wrapStreamFn` | Envoltorios personalizados de encabezados/cuerpo en la ruta de stream normal | | 21 | `resolveTransportTurnState` | Encabezados/metadatos nativos por turno | - | 22 | `resolveWebSocketSessionPolicy` | Encabezados nativos de sesión WS/enfriamiento | - | 23 | `formatApiKey` | Forma personalizada del token en tiempo de ejecución | - | 24 | `refreshOAuth` | Actualización personalizada de OAuth | - | 25 | `buildAuthDoctorHint` | Orientación para reparar autenticación | - | 26 | `matchesContextOverflowError` | Detección de desbordamiento controlada por el proveedor | - | 27 | `classifyFailoverReason` | Clasificación de límite de velocidad/sobrecarga controlada por el proveedor | - | 28 | `isCacheTtlEligible` | Control de TTL de la caché de prompts | - | 29 | `buildMissingAuthMessage` | Pista personalizada para autenticación faltante | - | 30 | `suppressBuiltInModel` | Ocultar filas ascendentes obsoletas | - | 31 | `augmentModelCatalog` | Filas sintéticas de compatibilidad anticipada | + | 22 | `resolveWebSocketSessionPolicy` | Encabezados/enfriamiento de sesión WS nativos | + | 23 | `formatApiKey` | Forma personalizada del token de runtime | + | 24 | `refreshOAuth` | Actualización OAuth personalizada | + | 25 | `buildAuthDoctorHint` | Orientación de reparación de autenticación | + | 26 | `matchesContextOverflowError` | Detección de desbordamiento propiedad del proveedor | + | 27 | `classifyFailoverReason` | Clasificación propiedad del proveedor de límite de tasa/sobrecarga | + | 28 | `isCacheTtlEligible` | Control TTL de la caché de prompts | + | 29 | `buildMissingAuthMessage` | Sugerencia personalizada de autenticación faltante | + | 30 | `suppressBuiltInModel` | Ocultar filas upstream obsoletas | + | 31 | `augmentModelCatalog` | Filas sintéticas de compatibilidad futura | | 32 | `isBinaryThinking` | Pensamiento binario activado/desactivado | - | 33 | `supportsXHighThinking` | Compatibilidad de razonamiento `xhigh` | + | 33 | `supportsXHighThinking` | Compatibilidad con razonamiento `xhigh` | | 34 | `resolveDefaultThinkingLevel` | Política predeterminada de `/think` | | 35 | `isModernModelRef` | Coincidencia de modelos live/smoke | | 36 | `prepareRuntimeAuth` | Intercambio de tokens antes de la inferencia | | 37 | `resolveUsageAuth` | Análisis personalizado de credenciales de uso | - | 38 | `fetchUsageSnapshot` | Endpoint de uso personalizado | - | 39 | `createEmbeddingProvider` | Adaptador de embeddings controlado por el proveedor para memoria/búsqueda | - | 40 | `buildReplayPolicy` | Política personalizada de repetición/compactación de transcripciones | - | 41 | `sanitizeReplayHistory` | Reescrituras de repetición específicas del proveedor después de la limpieza genérica | - | 42 | `validateReplayTurns` | Validación estricta de turnos de repetición antes del ejecutor integrado | - | 43 | `onModelSelected` | Callback posterior a la selección (por ejemplo, telemetría) | + | 38 | `fetchUsageSnapshot` | Endpoint personalizado de uso | + | 39 | `createEmbeddingProvider` | Adaptador de embeddings propiedad del proveedor para memoria/búsqueda | + | 40 | `buildReplayPolicy` | Política personalizada de reproducción/compactación de transcripciones | + | 41 | `sanitizeReplayHistory` | Reescrituras de reproducción específicas del proveedor tras la limpieza genérica | + | 42 | `validateReplayTurns` | Validación estricta de turnos de reproducción antes del ejecutor embebido | + | 43 | `onModelSelected` | Callback posterior a la selección (p. ej., telemetría) | Nota sobre ajuste de prompts: - `resolveSystemPromptContribution` permite que un proveedor inyecte - orientación de system prompt consciente de la caché para una familia de modelos. Prefiérelo frente a - `before_prompt_build` cuando el comportamiento pertenezca a un proveedor/familia de modelos - y deba preservar la división estable/dinámica de la caché. + orientación de system prompt consciente de la caché para una familia de modelos. Es preferible usarlo en lugar de + `before_prompt_build` cuando el comportamiento pertenece a una familia de proveedor/modelo + y debe conservar la división estable/dinámica de la caché. - Para descripciones detalladas y ejemplos reales, consulta + Para descripciones detalladas y ejemplos del mundo real, consulta [Internals: Provider Runtime Hooks](/es/plugins/architecture#provider-runtime-hooks). @@ -536,9 +540,9 @@ autenticación por clave de API y resolución dinámica de modelos. - Un plugin de proveedor puede registrar voz, transcripción en tiempo real, voz - en tiempo real, comprensión multimedia, generación de imágenes, generación de video, web fetch - y búsqueda web junto con inferencia de texto: + Un plugin de proveedor puede registrar speech, transcripción realtime, voz + realtime, comprensión multimedia, generación de imágenes, generación de video, web fetch + y búsqueda web junto con la inferencia de texto: ```typescript register(api) { @@ -650,16 +654,16 @@ autenticación por clave de API y resolución dinámica de modelos. patrón recomendado para plugins de empresa (un plugin por proveedor). Consulta [Internals: Capability Ownership](/es/plugins/architecture#capability-ownership-model). - Para la generación de video, prefiere la forma de capacidades consciente del modo que se muestra arriba: + Para la generación de video, es preferible usar la forma de capacidades con reconocimiento de modo que se muestra arriba: `generate`, `imageToVideo` y `videoToVideo`. Los campos agregados planos como - `maxInputImages`, `maxInputVideos` y `maxDurationSeconds` no - bastan para anunciar claramente compatibilidad con modos de transformación o modos deshabilitados. + `maxInputImages`, `maxInputVideos` y `maxDurationSeconds` no son + suficientes para anunciar limpiamente compatibilidad con modo de transformación o modos deshabilitados. - Los proveedores de generación musical deben seguir el mismo patrón: - `generate` para generación solo con prompt y `edit` para generación basada en imagen - de referencia. Los campos agregados planos como `maxInputImages`, - `supportsLyrics` y `supportsFormat` no bastan para anunciar compatibilidad - con edición; los bloques explícitos `generate` / `edit` son el contrato esperado. + Los proveedores de generación de música deben seguir el mismo patrón: + `generate` para generación solo a partir de prompt y `edit` para generación + basada en imagen de referencia. Los campos agregados planos como `maxInputImages`, + `supportsLyrics` y `supportsFormat` no son suficientes para anunciar compatibilidad + con edición; el contrato esperado son bloques explícitos `generate` / `edit`. @@ -714,29 +718,29 @@ No uses aquí el alias heredado de publicación solo para Skills; los paquetes d ``` /acme-ai/ -├── package.json # openclaw.providers metadata -├── openclaw.plugin.json # Manifest with providerAuthEnvVars +├── package.json # metadatos de openclaw.providers +├── openclaw.plugin.json # manifiesto con metadatos de autenticación del proveedor ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Tests - └── usage.ts # Usage endpoint (optional) + ├── provider.test.ts # pruebas + └── usage.ts # endpoint de uso (opcional) ``` ## Referencia del orden del catálogo -`catalog.order` controla cuándo se fusiona tu catálogo respecto a los proveedores -integrados: +`catalog.order` controla cuándo se fusiona tu catálogo en relación con los +proveedores integrados: | Order | When | Use case | | --------- | ------------- | ----------------------------------------------- | -| `simple` | Primera pasada | Proveedores simples con clave de API | -| `profile` | Después de simple | Proveedores condicionados por perfiles de autenticación | -| `paired` | Después de profile | Sintetizar varias entradas relacionadas | -| `late` | Última pasada | Sobrescribir proveedores existentes (gana en caso de colisión) | +| `simple` | Primer paso | Proveedores sencillos con clave de API | +| `profile` | Después de simple | Proveedores condicionados a perfiles de autenticación | +| `paired` | Después de profile | Sintetizar varias entradas relacionadas | +| `late` | Último paso | Sobrescribir proveedores existentes (gana en colisión) | -## Siguientes pasos +## Próximos pasos -- [Plugins de canal](/es/plugins/sdk-channel-plugins) — si tu plugin también proporciona un canal -- [SDK Runtime](/es/plugins/sdk-runtime) — helpers de `api.runtime` (TTS, búsqueda, subagente) +- [Channel Plugins](/es/plugins/sdk-channel-plugins) — si tu plugin también proporciona un canal +- [SDK Runtime](/es/plugins/sdk-runtime) — helpers `api.runtime` (TTS, búsqueda, subagent) - [SDK Overview](/es/plugins/sdk-overview) — referencia completa de importaciones por subruta -- [Plugin Internals](/es/plugins/architecture#provider-runtime-hooks) — detalles de hooks y ejemplos integrados +- [Plugin Internals](/es/plugins/architecture#provider-runtime-hooks) — detalles de hooks y ejemplos incluidos diff --git a/docs/es/providers/google.md b/docs/es/providers/google.md index bb5d172ad..e7fee87b3 100644 --- a/docs/es/providers/google.md +++ b/docs/es/providers/google.md @@ -1,14 +1,14 @@ --- read_when: - Quieres usar modelos Google Gemini con OpenClaw - - Necesitas el flujo de autenticación con clave API u OAuth -summary: Configuración de Google Gemini (clave API + OAuth, generación de imágenes, comprensión de medios, búsqueda web) + - Necesitas el flujo de autenticación con clave de API u OAuth +summary: Configuración de Google Gemini (clave de API + OAuth, generación de imágenes, comprensión de medios, búsqueda web) title: Google (Gemini) x-i18n: - generated_at: "2026-04-08T02:17:24Z" + generated_at: "2026-04-09T01:29:49Z" model: gpt-5.4 provider: openai - source_hash: e9e558f5ce35c853e0240350be9a1890460c5f7f7fd30b05813a656497dee516 + source_hash: fad2ff68987301bd86145fa6e10de8c7b38d5bd5dbcd13db9c883f7f5b9a4e01 source_path: providers/google.md workflow: 15 --- @@ -26,13 +26,13 @@ Gemini Grounding. ## Inicio rápido -1. Define la clave API: +1. Establece la clave de API: ```bash openclaw onboard --auth-choice gemini-api-key ``` -2. Define un modelo predeterminado: +2. Establece un modelo predeterminado: ```json5 { @@ -55,13 +55,13 @@ openclaw onboard --non-interactive \ ## OAuth (Gemini CLI) -Un proveedor alternativo `google-gemini-cli` usa OAuth PKCE en lugar de una -clave API. Esta es una integración no oficial; algunos usuarios informan -restricciones en la cuenta. Úsala bajo tu propia responsabilidad. +Un proveedor alternativo `google-gemini-cli` usa OAuth con PKCE en lugar de una clave de +API. Esta es una integración no oficial; algunos usuarios informan +restricciones de cuenta. Úsalo bajo tu propia responsabilidad. - Modelo predeterminado: `google-gemini-cli/gemini-3-flash-preview` - Alias: `gemini-cli` -- Requisito de instalación: Gemini CLI local disponible como `gemini` +- Requisito previo de instalación: Gemini CLI local disponible como `gemini` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` - Inicio de sesión: @@ -77,46 +77,49 @@ Variables de entorno: (O las variantes `GEMINI_CLI_*`). -Si las solicitudes de OAuth de Gemini CLI fallan después de iniciar sesión, define -`GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host de la gateway e -inténtalo de nuevo. +Si las solicitudes OAuth de Gemini CLI fallan después del inicio de sesión, establece +`GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host de la gateway y +vuelve a intentarlo. Si el inicio de sesión falla antes de que comience el flujo del navegador, asegúrate de que el comando local `gemini` -esté instalado y disponible en `PATH`. OpenClaw admite tanto instalaciones con Homebrew -como instalaciones globales de npm, incluidos diseños comunes de Windows/npm. +esté instalado y en `PATH`. OpenClaw admite tanto instalaciones con Homebrew +como instalaciones globales con npm, incluidos diseños comunes de Windows/npm. -Notas de uso JSON de Gemini CLI: +Notas sobre el uso de JSON de Gemini CLI: -- El texto de la respuesta proviene del campo JSON `response` de CLI. -- El uso recurre a `stats` cuando CLI deja `usage` vacío. -- `stats.cached` se normaliza a `cacheRead` de OpenClaw. -- Si falta `stats.input`, OpenClaw deriva los tokens de entrada de +- El texto de respuesta proviene del campo `response` del JSON de CLI. +- El uso vuelve a `stats` cuando la CLI deja `usage` vacío. +- `stats.cached` se normaliza en `cacheRead` de OpenClaw. +- Si falta `stats.input`, OpenClaw deriva los tokens de entrada a partir de `stats.input_tokens - stats.cached`. ## Capacidades | Capacidad | Compatible | | ---------------------- | ----------------- | -| Finalizaciones de chat | Sí | +| Finalización de chat | Sí | | Generación de imágenes | Sí | | Generación de música | Sí | -| Comprensión de imagen | Sí | +| Comprensión de imágenes| Sí | | Transcripción de audio | Sí | | Comprensión de video | Sí | | Búsqueda web (Grounding) | Sí | -| Pensamiento/razonamiento | Sí (Gemini 3.1+) | +| Thinking/reasoning | Sí (Gemini 3.1+) | +| Modelos Gemma 4 | Sí | + +Los modelos Gemma 4 (por ejemplo `gemma-4-26b-a4b-it`) admiten el modo thinking. OpenClaw reescribe `thinkingBudget` a un `thinkingLevel` de Google compatible para Gemma 4. Establecer thinking en `off` mantiene thinking desactivado en lugar de asignarlo a `MINIMAL`. ## Reutilización directa de caché de Gemini -Para ejecuciones directas de la API de Gemini (`api: "google-generative-ai"`), OpenClaw ahora -pasa un identificador configurado `cachedContent` a las solicitudes de Gemini. +Para ejecuciones directas con la API de Gemini (`api: "google-generative-ai"`), OpenClaw ahora +pasa un identificador `cachedContent` configurado a las solicitudes de Gemini. - Configura parámetros por modelo o globales con `cachedContent` o el heredado `cached_content` - Si ambos están presentes, `cachedContent` tiene prioridad - Valor de ejemplo: `cachedContents/prebuilt-context` -- El uso por acierto de caché de Gemini se normaliza a `cacheRead` en OpenClaw a partir de - `cachedContentTokenCount` ascendente +- El uso con aciertos de caché de Gemini se normaliza en `cacheRead` de OpenClaw a partir de + `cachedContentTokenCount` upstream Ejemplo: @@ -138,17 +141,17 @@ Ejemplo: ## Generación de imágenes -El proveedor integrado de generación de imágenes `google` usa de forma predeterminada +El proveedor empaquetado de generación de imágenes `google` usa de forma predeterminada `google/gemini-3.1-flash-image-preview`. - También admite `google/gemini-3-pro-image-preview` - Generación: hasta 4 imágenes por solicitud -- Modo de edición: habilitado, hasta 5 imágenes de entrada +- Modo edición: habilitado, hasta 5 imágenes de entrada - Controles de geometría: `size`, `aspectRatio` y `resolution` -El proveedor `google-gemini-cli`, solo con OAuth, es una superficie separada -de inferencia de texto. La generación de imágenes, la comprensión de medios y Gemini Grounding permanecen en -el identificador de proveedor `google`. +El proveedor `google-gemini-cli`, solo con OAuth, es una superficie independiente +de inferencia de texto. La generación de imágenes, la comprensión de medios y Gemini Grounding siguen en +el ID de proveedor `google`. Para usar Google como proveedor de imágenes predeterminado: @@ -164,18 +167,18 @@ Para usar Google como proveedor de imágenes predeterminado: } ``` -Consulta [Image Generation](/es/tools/image-generation) para conocer los -parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de failover. +Consulta [Image Generation](/es/tools/image-generation) para ver los parámetros +compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error. ## Generación de video -El plugin integrado `google` también registra generación de video mediante la herramienta compartida +El plugin empaquetado `google` también registra la generación de video mediante la herramienta compartida `video_generate`. - Modelo de video predeterminado: `google/veo-3.1-fast-generate-preview` - Modos: texto a video, imagen a video y flujos de referencia de un solo video - Admite `aspectRatio`, `resolution` y `audio` -- Límite actual de duración: **4 a 8 segundos** +- Límite actual de duración: **de 4 a 8 segundos** Para usar Google como proveedor de video predeterminado: @@ -191,17 +194,17 @@ Para usar Google como proveedor de video predeterminado: } ``` -Consulta [Video Generation](/es/tools/video-generation) para conocer los -parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de failover. +Consulta [Video Generation](/es/tools/video-generation) para ver los parámetros +compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error. ## Generación de música -El plugin integrado `google` también registra generación de música mediante la herramienta compartida +El plugin empaquetado `google` también registra la generación de música mediante la herramienta compartida `music_generate`. - Modelo de música predeterminado: `google/lyria-3-clip-preview` - También admite `google/lyria-3-pro-preview` -- Controles de prompt: `lyrics` e `instrumental` +- Controles del prompt: `lyrics` e `instrumental` - Formato de salida: `mp3` de forma predeterminada, además de `wav` en `google/lyria-3-pro-preview` - Entradas de referencia: hasta 10 imágenes - Las ejecuciones respaldadas por sesión se desacoplan mediante el flujo compartido de tarea/estado, incluido `action: "status"` @@ -220,11 +223,11 @@ Para usar Google como proveedor de música predeterminado: } ``` -Consulta [Music Generation](/es/tools/music-generation) para conocer los -parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de failover. +Consulta [Music Generation](/es/tools/music-generation) para ver los parámetros +compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error. ## Nota sobre el entorno -Si la gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `GEMINI_API_KEY` +Si la Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `GEMINI_API_KEY` esté disponible para ese proceso (por ejemplo, en `~/.openclaw/.env` o mediante `env.shellEnv`). diff --git a/docs/es/providers/inferrs.md b/docs/es/providers/inferrs.md index 43c380e57..faeb20d27 100644 --- a/docs/es/providers/inferrs.md +++ b/docs/es/providers/inferrs.md @@ -6,10 +6,10 @@ read_when: summary: Ejecuta OpenClaw mediante inferrs (servidor local compatible con OpenAI) title: inferrs x-i18n: - generated_at: "2026-04-08T02:17:25Z" + generated_at: "2026-04-09T01:30:07Z" model: gpt-5.4 provider: openai - source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6 + source_hash: 03b9d5a9935c75fd369068bacb7807a5308cd0bd74303b664227fb664c3a2098 source_path: providers/inferrs.md workflow: 15 --- @@ -17,11 +17,11 @@ x-i18n: # inferrs [inferrs](https://github.com/ericcurtin/inferrs) puede servir modelos locales detrás de una -API `/v1` compatible con OpenAI. OpenClaw funciona con `inferrs` mediante la ruta genérica +API `/v1` compatible con OpenAI. OpenClaw funciona con `inferrs` a través de la ruta genérica `openai-completions`. -Actualmente, lo mejor es tratar `inferrs` como un backend personalizado autoalojado -compatible con OpenAI, no como un plugin de proveedor dedicado de OpenClaw. +Actualmente, lo mejor es tratar `inferrs` como un backend personalizado autohospedado compatible con OpenAI, +no como un plugin de proveedor dedicado de OpenClaw. ## Inicio rápido @@ -30,20 +30,20 @@ compatible con OpenAI, no como un plugin de proveedor dedicado de OpenClaw. Ejemplo: ```bash -inferrs serve gg-hf-gg/gemma-4-E2B-it \ +inferrs serve google/gemma-4-E2B-it \ --host 127.0.0.1 \ --port 8080 \ --device metal ``` -2. Verifica que se pueda acceder al servidor. +2. Verifica que el servidor sea accesible. ```bash curl http://127.0.0.1:8080/health curl http://127.0.0.1:8080/v1/models ``` -3. Añade una entrada explícita de proveedor de OpenClaw y apunta tu modelo predeterminado a ella. +3. Añade una entrada de proveedor explícita de OpenClaw y apunta tu modelo predeterminado a ella. ## Ejemplo completo de configuración @@ -53,9 +53,9 @@ Este ejemplo usa Gemma 4 en un servidor local de `inferrs`. { agents: { defaults: { - model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" }, + model: { primary: "inferrs/google/gemma-4-E2B-it" }, models: { - "inferrs/gg-hf-gg/gemma-4-E2B-it": { + "inferrs/google/gemma-4-E2B-it": { alias: "Gemma 4 (inferrs)", }, }, @@ -70,7 +70,7 @@ Este ejemplo usa Gemma 4 en un servidor local de `inferrs`. api: "openai-completions", models: [ { - id: "gg-hf-gg/gemma-4-E2B-it", + id: "google/gemma-4-E2B-it", name: "Gemma 4 E2B (inferrs)", reasoning: false, input: ["text"], @@ -88,12 +88,12 @@ Este ejemplo usa Gemma 4 en un servidor local de `inferrs`. } ``` -## Por qué importa `requiresStringContent` +## Por qué `requiresStringContent` es importante -Algunas rutas Chat Completions de `inferrs` aceptan solo -`messages[].content` de tipo cadena, no matrices estructuradas de partes de contenido. +Algunas rutas de Chat Completions de `inferrs` aceptan solo +`messages[].content` como cadena, no matrices estructuradas de partes de contenido. -Si las ejecuciones de OpenClaw fallan con un error como: +Si las ejecuciones de OpenClaw fallan con un error como este: ```text messages[1].content: invalid type: sequence, expected a string @@ -112,8 +112,8 @@ la solicitud. ## Advertencia sobre Gemma y el esquema de herramientas -Algunas combinaciones actuales de `inferrs` + Gemma aceptan solicitudes directas pequeñas a -`/v1/chat/completions`, pero aun así fallan en turnos completos del entorno de ejecución de agentes de OpenClaw. +Algunas combinaciones actuales de `inferrs` + Gemma aceptan solicitudes pequeñas directas a +`/v1/chat/completions`, pero aun así fallan en turnos completos del runtime de agente de OpenClaw. Si eso ocurre, prueba primero esto: @@ -124,30 +124,30 @@ compat: { } ``` -Eso desactiva la superficie de esquema de herramientas de OpenClaw para el modelo y puede reducir la +Eso desactiva la superficie del esquema de herramientas de OpenClaw para el modelo y puede reducir la presión del prompt en backends locales más estrictos. -Si las solicitudes directas pequeñas siguen funcionando, pero los turnos normales de agentes de OpenClaw continúan -fallando dentro de `inferrs`, el problema restante suele estar en el comportamiento ascendente del modelo/servidor -y no en la capa de transporte de OpenClaw. +Si las solicitudes directas pequeñas siguen funcionando pero los turnos normales del agente de OpenClaw continúan +fallando dentro de `inferrs`, el problema restante suele ser un comportamiento upstream del modelo/servidor +más que de la capa de transporte de OpenClaw. -## Prueba manual rápida +## Prueba manual básica Una vez configurado, prueba ambas capas: ```bash curl http://127.0.0.1:8080/v1/chat/completions \ -H 'content-type: application/json' \ - -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' + -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' openclaw infer model run \ - --model inferrs/gg-hf-gg/gemma-4-E2B-it \ + --model inferrs/google/gemma-4-E2B-it \ --prompt "What is 2 + 2? Reply with one short sentence." \ --json ``` Si el primer comando funciona pero el segundo falla, usa las notas de solución de problemas -de abajo. +que aparecen a continuación. ## Solución de problemas @@ -158,22 +158,22 @@ de abajo. - Las llamadas directas pequeñas a `/v1/chat/completions` funcionan, pero `openclaw infer model run` falla: prueba `compat.supportsTools: false`. - OpenClaw ya no recibe errores de esquema, pero `inferrs` sigue fallando en turnos de - agentes más grandes: trátalo como una limitación ascendente de `inferrs` o del modelo y reduce la + agente más grandes: trátalo como una limitación upstream de `inferrs` o del modelo, y reduce la presión del prompt o cambia de backend/modelo local. -## Comportamiento de estilo proxy +## Comportamiento de tipo proxy -`inferrs` se trata como un backend `/v1` compatible con OpenAI de estilo proxy, no como un +`inferrs` se trata como un backend `/v1` compatible con OpenAI de tipo proxy, no como un endpoint nativo de OpenAI. - aquí no se aplica el modelado de solicitudes exclusivo de OpenAI nativo -- no hay `service_tier`, ni `store` de Responses, ni sugerencias de caché de prompts, ni - modelado de payload de compatibilidad de razonamiento de OpenAI +- no hay `service_tier`, no hay `store` de Responses, no hay sugerencias de caché de prompt ni + modelado de carga útil de compatibilidad de reasoning de OpenAI - los encabezados ocultos de atribución de OpenClaw (`originator`, `version`, `User-Agent`) no se inyectan en URLs base personalizadas de `inferrs` ## Ver también - [Modelos locales](/es/gateway/local-models) -- [Solución de problemas del gateway](/es/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) +- [Solución de problemas de Gateway](/es/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) - [Proveedores de modelos](/es/concepts/model-providers) diff --git a/docs/es/providers/ollama.md b/docs/es/providers/ollama.md index 2443b9332..e0c9ca034 100644 --- a/docs/es/providers/ollama.md +++ b/docs/es/providers/ollama.md @@ -1,39 +1,39 @@ --- read_when: - Quieres ejecutar OpenClaw con modelos en la nube o locales mediante Ollama - - Necesitas orientación de configuración y puesta en marcha de Ollama + - Necesitas orientación para la configuración y puesta en marcha de Ollama summary: Ejecuta OpenClaw con Ollama (modelos en la nube y locales) title: Ollama x-i18n: - generated_at: "2026-04-08T02:18:01Z" + generated_at: "2026-04-09T01:30:28Z" model: gpt-5.4 provider: openai - source_hash: 222ec68f7d4bb29cc7796559ddef1d5059f5159e7a51e2baa3a271ddb3abb716 + source_hash: d3295a7c879d3636a2ffdec05aea6e670e54a990ef52bd9b0cae253bc24aa3f7 source_path: providers/ollama.md workflow: 15 --- # Ollama -Ollama es un runtime de LLM local que facilita ejecutar modelos de código abierto en tu equipo. OpenClaw se integra con la API nativa de Ollama (`/api/chat`), admite streaming y llamadas a herramientas, y puede detectar automáticamente modelos locales de Ollama cuando optas por usar `OLLAMA_API_KEY` (o un perfil de autenticación) y no defines una entrada explícita `models.providers.ollama`. +Ollama es un entorno de ejecución local de LLM que facilita ejecutar modelos de código abierto en tu equipo. OpenClaw se integra con la API nativa de Ollama (`/api/chat`), admite streaming y tool calling, y puede detectar automáticamente modelos locales de Ollama cuando lo habilitas con `OLLAMA_API_KEY` (o un perfil de autenticación) y no defines una entrada explícita `models.providers.ollama`. -**Usuarios de Ollama remoto**: No uses la URL compatible con OpenAI `/v1` (`http://host:11434/v1`) con OpenClaw. Esto rompe las llamadas a herramientas y los modelos pueden generar JSON de herramientas sin procesar como texto plano. Usa en su lugar la URL de la API nativa de Ollama: `baseUrl: "http://host:11434"` (sin `/v1`). +**Usuarios de Ollama remoto**: No uses la URL compatible con OpenAI `/v1` (`http://host:11434/v1`) con OpenClaw. Esto rompe el tool calling y los modelos pueden producir JSON de herramientas sin procesar como texto sin formato. Usa en su lugar la URL de la API nativa de Ollama: `baseUrl: "http://host:11434"` (sin `/v1`). ## Inicio rápido -### Onboarding (recomendado) +### Incorporación guiada (recomendado) -La forma más rápida de configurar Ollama es mediante el onboarding: +La forma más rápida de configurar Ollama es mediante la incorporación guiada: ```bash openclaw onboard ``` -Selecciona **Ollama** en la lista de proveedores. El onboarding hará lo siguiente: +Selecciona **Ollama** en la lista de proveedores. La incorporación guiada hará lo siguiente: -1. Pedirá la URL base de Ollama donde se puede acceder a tu instancia (valor predeterminado `http://127.0.0.1:11434`). +1. Te pedirá la URL base de Ollama en la que se puede acceder a tu instancia (predeterminada: `http://127.0.0.1:11434`). 2. Te permitirá elegir **Cloud + Local** (modelos en la nube y modelos locales) o **Local** (solo modelos locales). 3. Abrirá un flujo de inicio de sesión en el navegador si eliges **Cloud + Local** y no has iniciado sesión en ollama.com. 4. Detectará los modelos disponibles y sugerirá valores predeterminados. @@ -77,7 +77,7 @@ ollama pull llama3.3 ollama signin ``` -4. Ejecuta el onboarding y elige `Ollama`: +4. Ejecuta la incorporación guiada y elige `Ollama`: ```bash openclaw onboard @@ -92,7 +92,7 @@ OpenClaw sugiere actualmente: - valor predeterminado local: `gemma4` - valores predeterminados en la nube: `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud` -5. Si prefieres una configuración manual, habilita Ollama para OpenClaw directamente (cualquier valor funciona; Ollama no requiere una clave real): +5. Si prefieres la configuración manual, habilita Ollama directamente para OpenClaw (cualquier valor funciona; Ollama no requiere una clave real): ```bash # Establecer variable de entorno @@ -123,11 +123,12 @@ openclaw models set ollama/gemma4 ## Detección de modelos (proveedor implícito) -Cuando estableces `OLLAMA_API_KEY` (o un perfil de autenticación) y **no** defines `models.providers.ollama`, OpenClaw detecta modelos de la instancia local de Ollama en `http://127.0.0.1:11434`: +Cuando estableces `OLLAMA_API_KEY` (o un perfil de autenticación) y **no** defines `models.providers.ollama`, OpenClaw detecta modelos desde la instancia local de Ollama en `http://127.0.0.1:11434`: - Consulta `/api/tags` -- Usa búsquedas `/api/show` en modo best-effort para leer `contextWindow` cuando está disponible -- Marca `reasoning` con una heurística basada en el nombre del modelo (`r1`, `reasoning`, `think`) +- Usa búsquedas de `/api/show` con mejor esfuerzo para leer `contextWindow` y detectar capacidades (incluida visión) cuando estén disponibles +- Los modelos con una capacidad `vision` informada por `/api/show` se marcan como compatibles con imágenes (`input: ["text", "image"]`), por lo que OpenClaw inyecta automáticamente imágenes en el prompt para esos modelos +- Marca `reasoning` mediante una heurística por nombre de modelo (`r1`, `reasoning`, `think`) - Establece `maxTokens` en el límite máximo predeterminado de tokens de Ollama usado por OpenClaw - Establece todos los costos en `0` @@ -146,9 +147,9 @@ Para añadir un modelo nuevo, simplemente haz `pull` con Ollama: ollama pull mistral ``` -El nuevo modelo se detectará automáticamente y estará disponible para usar. +El modelo nuevo se detectará automáticamente y estará disponible para usarse. -Si configuras `models.providers.ollama` explícitamente, la detección automática se omite y debes definir los modelos manualmente (ver más abajo). +Si defines `models.providers.ollama` de forma explícita, se omite la detección automática y debes definir los modelos manualmente (ver más abajo). ## Configuración @@ -164,9 +165,9 @@ export OLLAMA_API_KEY="ollama-local" Usa configuración explícita cuando: -- Ollama se ejecuta en otro host/puerto. +- Ollama se ejecuta en otro host o puerto. - Quieres forzar ventanas de contexto o listas de modelos específicas. -- Quieres definiciones de modelos completamente manuales. +- Quieres definiciones de modelos totalmente manuales. ```json5 { @@ -193,11 +194,11 @@ Usa configuración explícita cuando: } ``` -Si `OLLAMA_API_KEY` está establecido, puedes omitir `apiKey` en la entrada del proveedor y OpenClaw lo completará para las comprobaciones de disponibilidad. +Si `OLLAMA_API_KEY` está configurada, puedes omitir `apiKey` en la entrada del proveedor y OpenClaw la completará para las comprobaciones de disponibilidad. ### URL base personalizada (configuración explícita) -Si Ollama se está ejecutando en un host o puerto diferente (la configuración explícita desactiva la detección automática, así que define los modelos manualmente): +Si Ollama se está ejecutando en un host o puerto distintos (la configuración explícita desactiva la detección automática, por lo que debes definir los modelos manualmente): ```json5 { @@ -205,8 +206,8 @@ Si Ollama se está ejecutando en un host o puerto diferente (la configuración e providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // Sin /v1: usa la URL nativa de la API de Ollama - api: "ollama", // Establécelo explícitamente para garantizar el comportamiento nativo de llamadas a herramientas + baseUrl: "http://ollama-host:11434", // Sin /v1: usa la URL de la API nativa de Ollama + api: "ollama", // Establécelo explícitamente para garantizar el comportamiento nativo de tool calling }, }, }, @@ -214,10 +215,10 @@ Si Ollama se está ejecutando en un host o puerto diferente (la configuración e ``` -No añadas `/v1` a la URL. La ruta `/v1` usa el modo compatible con OpenAI, donde las llamadas a herramientas no son fiables. Usa la URL base de Ollama sin un sufijo de ruta. +No añadas `/v1` a la URL. La ruta `/v1` usa el modo compatible con OpenAI, donde el tool calling no es fiable. Usa la URL base de Ollama sin sufijo de ruta. -### Selección de modelos +### Selección de modelo Una vez configurado, todos tus modelos de Ollama estarán disponibles: @@ -238,22 +239,19 @@ Una vez configurado, todos tus modelos de Ollama estarán disponibles: Los modelos en la nube te permiten ejecutar modelos alojados en la nube (por ejemplo, `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`) junto con tus modelos locales. -Para usar modelos en la nube, selecciona el modo **Cloud + Local** durante la configuración. El asistente comprueba si has iniciado sesión y abre un flujo de inicio de sesión en el navegador cuando es necesario. Si no se puede verificar la autenticación, el asistente vuelve a los valores predeterminados de modelos locales. +Para usar modelos en la nube, selecciona el modo **Cloud + Local** durante la configuración. El asistente comprueba si has iniciado sesión y abre un flujo de inicio de sesión en el navegador cuando es necesario. Si no se puede verificar la autenticación, el asistente recurre a los valores predeterminados de modelos locales. También puedes iniciar sesión directamente en [ollama.com/signin](https://ollama.com/signin). -## Búsqueda web de Ollama +## Ollama Web Search -OpenClaw también es compatible con **Ollama Web Search** como proveedor -empaquetado de `web_search`. +OpenClaw también admite **Ollama Web Search** como proveedor integrado de `web_search`. -- Usa tu host de Ollama configurado (`models.providers.ollama.baseUrl` cuando - está configurado; de lo contrario `http://127.0.0.1:11434`). +- Usa tu host de Ollama configurado (`models.providers.ollama.baseUrl` cuando está definido; de lo contrario, `http://127.0.0.1:11434`). - No requiere clave. - Requiere que Ollama esté en ejecución y que hayas iniciado sesión con `ollama signin`. -Elige **Ollama Web Search** durante `openclaw onboard` o -`openclaw configure --section web`, o configura: +Elige **Ollama Web Search** durante `openclaw onboard` o `openclaw configure --section web`, o establece: ```json5 { @@ -267,30 +265,30 @@ Elige **Ollama Web Search** durante `openclaw onboard` o } ``` -Para ver la configuración completa y los detalles del comportamiento, consulta [Ollama Web Search](/es/tools/ollama-search). +Para conocer todos los detalles de configuración y comportamiento, consulta [Ollama Web Search](/es/tools/ollama-search). ## Avanzado ### Modelos de razonamiento -OpenClaw trata de forma predeterminada los modelos con nombres como `deepseek-r1`, `reasoning` o `think` como modelos con capacidad de razonamiento: +OpenClaw trata de forma predeterminada como compatibles con razonamiento a los modelos con nombres como `deepseek-r1`, `reasoning` o `think`: ```bash ollama pull deepseek-r1:32b ``` -### Costos de modelos +### Costos del modelo -Ollama es gratuito y se ejecuta localmente, por lo que todos los costos de los modelos se establecen en $0. +Ollama es gratuito y se ejecuta localmente, por lo que todos los costos de modelo se establecen en $0. ### Configuración de streaming -La integración de Ollama en OpenClaw usa la **API nativa de Ollama** (`/api/chat`) de forma predeterminada, que admite completamente streaming y llamadas a herramientas al mismo tiempo. No se necesita ninguna configuración especial. +La integración de Ollama en OpenClaw usa de forma predeterminada la **API nativa de Ollama** (`/api/chat`), que admite completamente streaming y tool calling al mismo tiempo. No se necesita ninguna configuración especial. #### Modo heredado compatible con OpenAI -**Las llamadas a herramientas no son fiables en el modo compatible con OpenAI.** Usa este modo solo si necesitas el formato de OpenAI para un proxy y no dependes del comportamiento nativo de llamadas a herramientas. +**El tool calling no es fiable en el modo compatible con OpenAI.** Usa este modo solo si necesitas el formato OpenAI para un proxy y no dependes del comportamiento nativo de tool calling. Si necesitas usar en su lugar el endpoint compatible con OpenAI (por ejemplo, detrás de un proxy que solo admite formato OpenAI), establece `api: "openai-completions"` explícitamente: @@ -311,9 +309,9 @@ Si necesitas usar en su lugar el endpoint compatible con OpenAI (por ejemplo, de } ``` -Es posible que este modo no admita streaming + llamadas a herramientas simultáneamente. Puede que necesites desactivar el streaming con `params: { streaming: false }` en la configuración del modelo. +Es posible que este modo no admita streaming + tool calling simultáneamente. Puede que necesites desactivar el streaming con `params: { streaming: false }` en la configuración del modelo. -Cuando se usa `api: "openai-completions"` con Ollama, OpenClaw inyecta `options.num_ctx` de forma predeterminada para que Ollama no vuelva silenciosamente a una ventana de contexto de 4096. Si tu proxy/upstream rechaza campos `options` desconocidos, desactiva este comportamiento: +Cuando se usa `api: "openai-completions"` con Ollama, OpenClaw inyecta `options.num_ctx` de forma predeterminada para que Ollama no vuelva silenciosamente a una ventana de contexto de 4096. Si tu proxy o servicio ascendente rechaza campos `options` desconocidos, desactiva este comportamiento: ```json5 { @@ -337,15 +335,15 @@ Para los modelos detectados automáticamente, OpenClaw usa la ventana de context ## Solución de problemas -### No se detecta Ollama +### Ollama no se detecta -Asegúrate de que Ollama se está ejecutando, de que estableciste `OLLAMA_API_KEY` (o un perfil de autenticación) y de que **no** definiste una entrada explícita `models.providers.ollama`: +Asegúrate de que Ollama esté en ejecución, de que hayas configurado `OLLAMA_API_KEY` (o un perfil de autenticación) y de que **no** hayas definido una entrada explícita `models.providers.ollama`: ```bash ollama serve ``` -Y de que la API sea accesible: +Y de que se pueda acceder a la API: ```bash curl http://localhost:11434/api/tags diff --git a/docs/es/providers/qwen.md b/docs/es/providers/qwen.md index 34ee8d367..4a239aaaa 100644 --- a/docs/es/providers/qwen.md +++ b/docs/es/providers/qwen.md @@ -1,14 +1,14 @@ --- read_when: - Quieres usar Qwen con OpenClaw - - Antes usabas OAuth de Qwen -summary: Usa Qwen Cloud mediante el proveedor `qwen` empaquetado de OpenClaw + - Antes usabas Qwen OAuth +summary: Usa Qwen Cloud mediante el proveedor qwen empaquetado de OpenClaw title: Qwen x-i18n: - generated_at: "2026-04-06T03:11:04Z" + generated_at: "2026-04-09T01:30:31Z" model: gpt-5.4 provider: openai - source_hash: f175793693ab6a4c3f1f4d42040e673c15faf7603a500757423e9e06977c989d + source_hash: 4786df2cb6ec1ab29d191d012c61dcb0e5468bf0f8561fbbb50eed741efad325 source_path: providers/qwen.md workflow: 15 --- @@ -17,7 +17,7 @@ x-i18n: -**Se eliminó OAuth de Qwen.** La integración OAuth del nivel gratuito +**Qwen OAuth ha sido eliminado.** La integración OAuth de nivel gratuito (`qwen-portal`) que usaba endpoints de `portal.qwen.ai` ya no está disponible. Consulta [Issue #49557](https://github.com/openclaw/openclaw/issues/49557) para obtener contexto. @@ -26,10 +26,10 @@ obtener contexto. ## Recomendado: Qwen Cloud -OpenClaw ahora trata a Qwen como un proveedor empaquetado de primera clase con el id canónico +OpenClaw ahora trata Qwen como un proveedor empaquetado de primera clase con el id canónico `qwen`. El proveedor empaquetado apunta a los endpoints de Qwen Cloud / Alibaba DashScope y -Coding Plan, y mantiene los id heredados `modelstudio` funcionando como alias -de compatibilidad. +Coding Plan, y mantiene los ids heredados `modelstudio` funcionando como alias de +compatibilidad. - Proveedor: `qwen` - Variable de entorno preferida: `QWEN_API_KEY` @@ -43,21 +43,21 @@ La compatibilidad con Coding Plan puede ir por detrás del catálogo público. # Endpoint global de Coding Plan openclaw onboard --auth-choice qwen-api-key -# Endpoint de Coding Plan para China +# Endpoint de Coding Plan en China openclaw onboard --auth-choice qwen-api-key-cn # Endpoint global Standard (pay-as-you-go) openclaw onboard --auth-choice qwen-standard-api-key -# Endpoint para China Standard (pay-as-you-go) +# Endpoint Standard (pay-as-you-go) en China openclaw onboard --auth-choice qwen-standard-api-key-cn ``` -Los id heredados de `auth-choice` `modelstudio-*` y las referencias de modelo `modelstudio/...` todavía -funcionan como alias de compatibilidad, pero los nuevos flujos de configuración deben preferir los id canónicos -de `auth-choice` `qwen-*` y las referencias de modelo `qwen/...`. +Los ids heredados `modelstudio-*` para `auth-choice` y las referencias de modelo `modelstudio/...` siguen +funcionando como alias de compatibilidad, pero los nuevos flujos de configuración deberían preferir los ids canónicos +`qwen-*` para `auth-choice` y las referencias de modelo `qwen/...`. -Después del onboarding, establece un modelo predeterminado: +Después de la configuración inicial, establece un modelo predeterminado: ```json5 { @@ -79,12 +79,12 @@ Después del onboarding, establece un modelo predeterminado: | Coding Plan (subscription) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | El proveedor selecciona automáticamente el endpoint según tu `auth choice`. Las opciones canónicas -usan la familia `qwen-*`; `modelstudio-*` sigue siendo solo de compatibilidad. -Puedes sobrescribirlo con un `baseUrl` personalizado en la configuración. +usan la familia `qwen-*`; `modelstudio-*` queda solo para compatibilidad. +Puedes reemplazarlo con un `baseUrl` personalizado en la configuración. Los endpoints nativos de Model Studio anuncian compatibilidad de uso de streaming en el -transporte compartido `openai-completions`. OpenClaw ahora basa esto en las capacidades del endpoint, -por lo que los id personalizados de proveedores compatibles con DashScope que apunten a los +transporte compartido `openai-completions`. OpenClaw ahora basa eso en las capacidades del endpoint, +por lo que los ids de proveedor personalizados compatibles con DashScope que apunten a los mismos hosts nativos heredan el mismo comportamiento de uso de streaming en lugar de requerir específicamente el id del proveedor integrado `qwen`. @@ -95,25 +95,27 @@ requerir específicamente el id del proveedor integrado `qwen`. ## Catálogo integrado -OpenClaw actualmente incluye este catálogo empaquetado de Qwen: +Actualmente, OpenClaw incluye este catálogo Qwen empaquetado. El catálogo configurado +tiene en cuenta el endpoint: las configuraciones de Coding Plan omiten modelos que solo se sabe que funcionan en +el endpoint Standard. -| Referencia de modelo | Entrada | Contexto | Notas | -| --------------------------- | ----------- | --------- | -------------------------------------------------- | -| `qwen/qwen3.5-plus` | texto, imagen | 1,000,000 | Modelo predeterminado | -| `qwen/qwen3.6-plus` | texto, imagen | 1,000,000 | Prefiere endpoints Standard cuando necesites este modelo | -| `qwen/qwen3-max-2026-01-23` | texto | 262,144 | Línea Qwen Max | -| `qwen/qwen3-coder-next` | texto | 262,144 | Código | -| `qwen/qwen3-coder-plus` | texto | 1,000,000 | Código | -| `qwen/MiniMax-M2.5` | texto | 1,000,000 | Razonamiento habilitado | -| `qwen/glm-5` | texto | 202,752 | GLM | -| `qwen/glm-4.7` | texto | 202,752 | GLM | -| `qwen/kimi-k2.5` | texto, imagen | 262,144 | Moonshot AI a través de Alibaba | +| Referencia de modelo | Entrada | Contexto | Notas | +| -------------------------- | ----------- | --------- | -------------------------------------------------- | +| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Modelo predeterminado | +| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Prefiere endpoints Standard cuando necesites este modelo | +| `qwen/qwen3-max-2026-01-23`| text | 262,144 | Línea Qwen Max | +| `qwen/qwen3-coder-next` | text | 262,144 | Coding | +| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding | +| `qwen/MiniMax-M2.5` | text | 1,000,000 | Reasoning habilitado | +| `qwen/glm-5` | text | 202,752 | GLM | +| `qwen/glm-4.7` | text | 202,752 | GLM | +| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI mediante Alibaba | -La disponibilidad aún puede variar según el endpoint y el plan de facturación incluso cuando un modelo -está presente en el catálogo empaquetado. +La disponibilidad puede seguir variando según el endpoint y el plan de facturación, incluso cuando un modelo +esté presente en el catálogo empaquetado. -La compatibilidad de uso de streaming nativo se aplica tanto a los hosts de Coding Plan como a -los hosts Standard compatibles con DashScope: +La compatibilidad de uso de streaming nativo se aplica tanto a los hosts de Coding Plan como a los +hosts Standard compatibles con DashScope: - `https://coding.dashscope.aliyuncs.com/v1` - `https://coding-intl.dashscope.aliyuncs.com/v1` @@ -122,7 +124,7 @@ los hosts Standard compatibles con DashScope: ## Disponibilidad de Qwen 3.6 Plus -`qwen3.6-plus` está disponible en los endpoints de Model Studio Standard (pay-as-you-go): +`qwen3.6-plus` está disponible en los endpoints Model Studio Standard (pay-as-you-go): - China: `dashscope.aliyuncs.com/compatible-mode/v1` - Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1` @@ -133,16 +135,16 @@ endpoint/clave de Coding Plan. ## Plan de capacidades -La extensión `qwen` se está posicionando como el hogar del proveedor para toda la superficie de Qwen -Cloud, no solo para modelos de código/texto. +La extensión `qwen` se está posicionando como la base del proveedor para toda la superficie de Qwen +Cloud, no solo para modelos de coding/texto. -- Modelos de texto/chat: ya incluidos -- Llamada de herramientas, salida estructurada, thinking: heredados del transporte compatible con OpenAI -- Generación de imágenes: planificada en la capa de plugins de proveedor -- Comprensión de imágenes/video: ya incluida en el endpoint Standard -- Voz/audio: planificada en la capa de plugins de proveedor -- Embeddings/reranking de memoria: planificados a través de la superficie del adaptador de embeddings -- Generación de video: ya incluida mediante la capacidad compartida de generación de video +- Modelos de texto/chat: empaquetados ahora +- Llamadas a herramientas, salida estructurada, thinking: heredados del transporte compatible con OpenAI +- Generación de imágenes: planificada en la capa del plugin de proveedor +- Comprensión de imagen/video: empaquetada ahora en el endpoint Standard +- Voz/audio: planificada en la capa del plugin de proveedor +- Embeddings/reranking de memoria: planificados mediante la superficie del adaptador de embeddings +- Generación de video: empaquetada ahora mediante la capacidad compartida de generación de video ## Complementos multimodales @@ -159,17 +161,17 @@ La extensión `qwen` ahora también expone: Estas superficies multimodales usan los endpoints DashScope **Standard**, no los endpoints de Coding Plan. -- URL base de Standard global/intl: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` -- URL base de Standard China: `https://dashscope.aliyuncs.com/compatible-mode/v1` +- URL base Standard global/internacional: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` +- URL base Standard de China: `https://dashscope.aliyuncs.com/compatible-mode/v1` -Para la generación de video, OpenClaw asigna la región de Qwen configurada al host -AIGC de DashScope correspondiente antes de enviar el trabajo: +Para la generación de video, OpenClaw asigna la región de Qwen configurada al host AIGC de +DashScope correspondiente antes de enviar el trabajo: -- Global/Intl: `https://dashscope-intl.aliyuncs.com` +- Global/internacional: `https://dashscope-intl.aliyuncs.com` - China: `https://dashscope.aliyuncs.com` Eso significa que un `models.providers.qwen.baseUrl` normal que apunte a cualquiera de los -hosts de Qwen de Coding Plan o Standard sigue manteniendo la generación de video en el endpoint +hosts Qwen de Coding Plan o Standard sigue manteniendo la generación de video en el endpoint regional correcto de video de DashScope. Para la generación de video, establece explícitamente un modelo predeterminado: @@ -184,22 +186,22 @@ Para la generación de video, establece explícitamente un modelo predeterminado } ``` -Límites actuales de generación de video del Qwen empaquetado: +Límites actuales empaquetados de generación de video de Qwen: - Hasta **1** video de salida por solicitud - Hasta **1** imagen de entrada - Hasta **4** videos de entrada - Hasta **10 segundos** de duración - Admite `size`, `aspectRatio`, `resolution`, `audio` y `watermark` -- El modo de imagen/video de referencia actualmente requiere **URLs remotas http(s)**. Las - rutas de archivos locales se rechazan de entrada porque el endpoint de video de DashScope no - acepta buffers locales subidos para esas referencias. +- El modo de imagen/video de referencia actualmente requiere **URLs http(s) remotas**. Las + rutas de archivo locales se rechazan de entrada porque el endpoint de video de DashScope no + acepta buffers locales cargados para esas referencias. -Consulta [Generación de video](/tools/video-generation) para ver los parámetros -compartidos de la herramienta, la selección de proveedor y el comportamiento de failover. +Consulta [Video Generation](/es/tools/video-generation) para ver los parámetros +compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error. ## Nota sobre el entorno -Si el Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `QWEN_API_KEY` esté +Si la Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `QWEN_API_KEY` esté disponible para ese proceso (por ejemplo, en `~/.openclaw/.env` o mediante `env.shellEnv`).