From 473154dd77e9febcb2084352eece4bfd0e4034c4 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 6 Apr 2026 05:17:44 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/channels/matrix.md | 560 ++++----- docs/es/concepts/dreaming.md | 123 +- docs/es/gateway/configuration-reference.md | 1200 ++++++++++---------- docs/es/plugins/sdk-migration.md | 382 ++++--- docs/es/plugins/sdk-overview.md | 520 ++++----- docs/es/tools/image-generation.md | 84 +- docs/es/tools/video-generation.md | 140 +-- 7 files changed, 1529 insertions(+), 1480 deletions(-) diff --git a/docs/es/channels/matrix.md b/docs/es/channels/matrix.md index 3f11528ec..129b31445 100644 --- a/docs/es/channels/matrix.md +++ b/docs/es/channels/matrix.md @@ -1,30 +1,28 @@ --- read_when: - Configurar Matrix en OpenClaw - - Configurar Matrix E2EE y la verificación + - 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-06T03:07:56Z" + generated_at: "2026-04-06T05:14:34Z" model: gpt-5.4 provider: openai - source_hash: 3e2d84c08d7d5b96db14b914e54f08d25334401cdd92eb890bc8dfb37b0ca2dc + source_hash: 06f833bf0ede81bad69f140994c32e8cc5d1635764f95fc5db4fc5dc25f2b85e 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, medios, reacciones, encuestas, ubicación y E2EE. +Matrix es el plugin de canal integrado de Matrix para OpenClaw. +Usa el `matrix-js-sdk` oficial y admite MD, salas, hilos, multimedia, reacciones, encuestas, ubicación y E2EE. -## Plugin empaquetado +## Plugin integrado -Matrix se incluye como plugin empaquetado en las versiones actuales de OpenClaw, por lo que las -compilaciones empaquetadas normales no necesitan una instalación separada. +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 anterior o una instalación personalizada que excluye Matrix, instálalo -manualmente: +Si usas una compilación antigua o una instalación personalizada que excluye Matrix, instálalo manualmente: Instalar desde npm: @@ -38,19 +36,19 @@ Instalar desde una copia local: openclaw plugins install ./path/to/local/matrix-plugin ``` -Consulta [Plugins](/es/tools/plugin) para conocer el comportamiento del plugin y las reglas de instalación. +Consulta [Plugins](/es/tools/plugin) para ver el comportamiento de los plugins y las reglas de instalación. ## Configuración 1. Asegúrate de que el plugin de Matrix esté disponible. - Las versiones empaquetadas actuales de OpenClaw ya lo incluyen. - - Las instalaciones anteriores/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 la gateway. -5. Inicia una MD con el bot o invítalo a una sala. +4. Reinicia el gateway. +5. Inicia un MD con el bot o invítalo a una sala. Rutas de configuración interactiva: @@ -63,18 +61,18 @@ Lo que realmente pregunta el asistente de Matrix: - URL del homeserver - método de autenticación: token de acceso o contraseña -- ID de usuario solo cuando eliges autenticación con contraseña -- nombre de dispositivo opcional +- ID de usuario solo cuando eliges autenticación por contraseña +- nombre opcional del dispositivo - si se debe habilitar E2EE - si se debe configurar ahora el acceso a salas de Matrix Comportamiento del asistente que importa: -- Si las variables de entorno de autenticación de Matrix ya existen 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 y solo escribe `enabled: true` para esa cuenta. +- Si las variables de entorno de autenticación de Matrix ya existen para la cuenta seleccionada, y esa cuenta todavía no tiene autenticación guardada en la configuración, el asistente ofrece un atajo por variable de entorno y solo escribe `enabled: true` para esa cuenta. - 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`. -- Las indicaciones de lista de permitidos de MD aceptan valores completos `@user:server` de inmediato. Los nombres para mostrar solo funcionan cuando la búsqueda activa en el directorio encuentra una coincidencia exacta; de lo contrario, el asistente te pide que vuelvas a intentarlo con un ID completo de Matrix. -- Las indicaciones de lista de permitidos de salas aceptan IDs y alias de sala directamente. 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 después se ignoran en la resolución de lista de permitidos en tiempo de ejecución. Prefiere `!room:server` o `#alias:server`. -- La identidad de sala/sesión en tiempo de ejecución usa el ID estable de sala de Matrix. Los alias declarados en la sala solo se usan como entradas de búsqueda, no como clave de sesión a largo plazo ni como identidad estable del grupo. +- Las solicitudes de lista de permitidos para MD aceptan inmediatamente valores completos `@user:server`. Los nombres para mostrar solo funcionan cuando la búsqueda en el directorio en vivo encuentra una coincidencia exacta; en caso contrario, el asistente te pide que vuelvas a intentarlo con un ID completo de Matrix. +- Las solicitudes de lista de permitidos de salas aceptan directamente IDs y alias de sala. También pueden resolver en vivo nombres de salas unidas, pero los nombres sin resolver solo se conservan tal como se escribieron durante la configuración y luego se ignoran en la resolución de lista de permitidos en tiempo de ejecución. Usa preferiblemente `!room:server` o `#alias:server`. +- La identidad de sala/sesión en tiempo de ejecución usa el ID estable de la 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"`. Configuración mínima basada en token: @@ -92,7 +90,7 @@ Configuración mínima basada en token: } ``` -Configuración basada en contraseña (el token se almacena en caché después del inicio de sesión): +Configuración basada en contraseña (el token se almacena en caché después de iniciar sesión): ```json5 { @@ -110,9 +108,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é allí, OpenClaw trata Matrix como configurado para configuración, doctor y detección del estado del canal, incluso si la autenticación actual no está establecida directamente en la configuración. +Cuando allí existen credenciales en caché, OpenClaw trata 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 (usados cuando la clave de configuración no está establecida): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -121,7 +119,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 con ámbito de cuenta: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -140,10 +138,10 @@ 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 IDs de cuenta para evitar colisiones en las variables de entorno con alcance. +Matrix escapa la puntuación en los IDs de cuenta para evitar colisiones en las variables de entorno con ámbito. Por ejemplo, `-` se convierte en `_X2D_`, por lo que `ops-prod` se asigna a `MATRIX_OPS_X2D_PROD_*`. -El asistente interactivo solo ofrece el atajo de variable de entorno cuando esas variables de autenticación ya están presentes y la cuenta seleccionada todavía no tiene autenticación de Matrix guardada en la configuración. +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 todavía no tiene autenticación de Matrix guardada en la configuración. ## Ejemplo de configuración @@ -182,13 +180,20 @@ Esta es una configuración base práctica con emparejamiento de MD, lista de per } ``` -## Vistas previas en streaming +`autoJoin` se aplica a las invitaciones de Matrix en general, no solo a invitaciones de salas o grupos. +Eso incluye invitaciones nuevas de estilo MD. En el momento de la invitación, OpenClaw no sabe de forma fiable si la +sala invitada terminará tratándose como un MD o como un grupo, así 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 MD, por lo que `autoJoin` controla el comportamiento de unión mientras que `dm.policy` controla el comportamiento +de respuesta y acceso. + +## Vistas previas de streaming El streaming de respuestas de Matrix es opcional. -Establece `channels.matrix.streaming` en `"partial"` cuando quieras que OpenClaw envíe una sola vista previa -en vivo, 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 vista previa en vivo +de la respuesta, edite esa vista previa en el mismo lugar mientras el modelo genera texto y luego la finalice cuando la +respuesta haya terminado: ```json5 { @@ -201,16 +206,16 @@ 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 preserva el comportamiento heredado de Matrix de notificación primero por vista previa, por lo que los clientes estándar pueden notificar sobre el primer texto transmitido en streaming en lugar del bloque terminado. -- `streaming: "quiet"` crea un 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 finalizadas de la vista previa. -- `blockStreaming: true` habilita mensajes de progreso de Matrix separados. Con la vista previa por streaming habilitada, Matrix mantiene el borrador en vivo para el bloque actual y conserva los bloques completados como mensajes separados. -- Cuando la vista previa por streaming está activada y `blockStreaming` está desactivado, Matrix edita el borrador en vivo en su 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 por streaming y vuelve a la entrega final normal. -- Las respuestas con medios siguen enviando los 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 generan llamadas adicionales a la API de Matrix. Deja el streaming desactivado si quieres el comportamiento más conservador respecto a límites de tasa. +- `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 Matrix de notificar primero por vista previa, por lo que los clientes estándar pueden notificar con el primer texto de vista previa transmitido en lugar del bloque terminado. +- `streaming: "quiet"` crea un aviso de vista previa silencioso y editable para el bloque actual del asistente. Úsalo 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 separados. Con el streaming de vista previa habilitado, Matrix conserva el borrador en vivo del bloque actual y mantiene los bloques completados como mensajes separados. +- Cuando la vista previa está activada y `blockStreaming` está desactivado, Matrix edita el borrador en vivo en el mismo lugar y finaliza ese mismo evento cuando termina el bloque o el turno. +- Si la vista previa deja de caber en un solo evento de Matrix, OpenClaw detiene el streaming de vista previa y vuelve a la entrega final normal. +- Las respuestas con multimedia siguen enviando adjuntos normalmente. 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 cuestan 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 sigan visibles como mensajes de progreso separados. +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 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"`: @@ -219,10 +224,10 @@ Si necesitas notificaciones estándar de Matrix sin reglas push personalizadas, ### 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 estén terminados, establece `streaming: "quiet"` y añade una regla push por usuario para las ediciones finalizadas de la vista previa. +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. -Normalmente esto se configura por usuario destinatario, no como un cambio global del homeserver: +Normalmente esto es una configuración del usuario destinatario, no un cambio global de configuración del homeserver: Mapa rápido antes de empezar: @@ -243,12 +248,12 @@ Mapa rápido antes de empezar: } ``` -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/dispositivos funcionando. +2. Asegúrate de que la cuenta destinataria ya reciba notificaciones push normales de Matrix. Las reglas de vista previa silenciosa + solo funcionan si ese usuario ya tiene pushers/dispositivos funcionando. 3. Obtén el token de acceso del usuario destinatario. - - Usa el token del usuario receptor, no el del bot. - - Reutilizar un token de una sesión de cliente existente suele ser lo más sencillo. + - Usa el token del usuario que recibe, no el token del bot. + - Reutilizar un token de una sesión existente del cliente suele ser lo más fácil. - Si necesitas emitir un token nuevo, puedes iniciar sesión mediante la API estándar Client-Server de Matrix: ```bash @@ -265,7 +270,7 @@ curl -sS -X POST \ }' ``` -4. Verifica que la cuenta del destinatario ya tenga pushers: +4. Verifica que la cuenta destinataria ya tenga pushers: ```bash curl -sS \ @@ -273,7 +278,7 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Si esto no devuelve pushers/dispositivos activos, primero corrige las notificaciones normales de Matrix antes de añadir la +Si esto no devuelve pushers/dispositivos activos, corrige primero las notificaciones normales de Matrix antes de añadir la regla de OpenClaw de abajo. OpenClaw marca las ediciones finalizadas de vista previa de solo texto con: @@ -323,7 +328,7 @@ 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` con el mismo ID de regla actualiza esa regla. +- Las reglas push se indexan por `ruleId`. Volver a ejecutar `PUT` contra 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`. @@ -332,7 +337,7 @@ La regla se evalúa contra el remitente del evento: - autentícate con el token del usuario receptor - haz coincidir `sender` con el MXID del bot de OpenClaw -6. Verifica que la regla existe: +6. Verifica que la regla exista: ```bash curl -sS \ @@ -340,10 +345,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Prueba una respuesta transmitida por streaming. En modo silencioso, la sala debe mostrar una vista previa silenciosa de borrador y la - edición final en su lugar debe notificar una vez que termine el bloque o el turno. +7. Prueba una respuesta transmitida. En modo silencioso, la sala debería mostrar una vista previa de borrador silenciosa y la + edición final en el mismo lugar debería notificar una vez que el bloque o el turno haya terminado. -Si necesitas eliminar la regla más adelante, borra ese mismo ID de regla con el token del usuario receptor: +Si necesitas eliminar la regla después, elimina ese mismo ID de regla con el token del usuario receptor: ```bash curl -sS -X DELETE \ @@ -354,36 +359,36 @@ 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 predeterminadas de supresión, por lo que no se necesita ningún parámetro adicional de orden. -- Esto solo afecta a las ediciones de vista previa de solo texto que OpenClaw puede finalizar de forma segura en su lugar. Los reemplazos para medios y las recuperaciones por vista previa obsoleta siguen usando la entrega normal de Matrix. -- Si `GET /_matrix/client/v3/pushers` no muestra pushers, ese usuario todavía no tiene entrega push de Matrix funcionando 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 se necesita ningún parámetro adicional de orden. +- Esto solo afecta a las ediciones de vista previa de solo texto que OpenClaw puede finalizar de forma segura en el mismo lugar. Las rutas alternativas de multimedia y de 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 funcional para esta cuenta o dispositivo. #### Synapse -Para Synapse, la configuración anterior normalmente es suficiente por sí sola: +Para Synapse, la configuración anterior suele ser 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 del usuario + la llamada `pushrules` anterior es 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 a Synapse correctamente. +- Si tu implementación de Synapse ya envía notificaciones push normales de Matrix, el token de usuario + la llamada a `pushrules` anterior es 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` / los workers de pusher configurados. #### Tuwunel -Para Tuwunel, usa el mismo flujo de configuración y la misma llamada a la API `pushrules` mostrada arriba: +Para Tuwunel, usa el mismo flujo de configuración y la misma llamada a la API `push-rule` mostrados arriba: -- 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 del 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 las notificaciones push hacia otros dispositivos mientras uno está activo. +- No se requiere ninguna configuración específica de Tuwunel para el marcador de vista previa finalizada. +- Si las notificaciones normales de Matrix ya funcionan para ese usuario, el token de usuario + la llamada a `pushrules` anterior es 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 push hacia otros dispositivos mientras uno de ellos está activo. ## 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 ninguna configuración: el plugin detecta automáticamente el estado de E2EE. +En 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 ninguna configuración: el plugin detecta automáticamente el estado de E2EE. -### Salas bot a bot +### Salas de bot a bot -De forma predeterminada, los mensajes de otras cuentas configuradas de Matrix de OpenClaw se ignoran. +De forma predeterminada, los mensajes de otras cuentas configuradas de OpenClaw Matrix se ignoran. -Usa `allowBots` cuando quieras intencionadamente tráfico de Matrix entre agentes: +Usa `allowBots` cuando quieras intencionadamente tráfico Matrix entre agentes: ```json5 { @@ -400,15 +405,15 @@ Usa `allowBots` cuando quieras intencionadamente tráfico de Matrix entre agente } ``` -- `allowBots: true` acepta mensajes de otras cuentas de bot de Matrix configuradas en salas permitidas y MD. -- `allowBots: "mentions"` acepta esos mensajes solo cuando mencionan visiblemente a este bot en salas. Las MD siguen estando permitidas. -- `groups..allowBots` sustituye la configuración a nivel de cuenta para una sala. +- `allowBots: true` acepta mensajes de otras cuentas configuradas de bot de Matrix en salas permitidas y en MD. +- `allowBots: "mentions"` acepta esos mensajes solo cuando mencionan visiblemente a este bot en salas. Los MD siguen permitidos. +- `groups..allowBots` reemplaza 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í una marca nativa de bot; OpenClaw trata “creado por bot” como “enviado por otra cuenta de Matrix configurada en esta gateway de OpenClaw”. +- Matrix no expone aquí una marca nativa de bot; OpenClaw trata "escrito por bot" como "enviado por otra cuenta configurada de Matrix en este gateway de OpenClaw". -Usa listas de permitidos estrictas de salas y requisitos de mención cuando habilites tráfico bot a bot en salas compartidas. +Usa listas de permitidos estrictas de sala y requisitos de mención cuando habilites tráfico bot a bot en salas compartidas. -Habilitar el cifrado: +Habilitar cifrado: ```json5 { @@ -430,7 +435,7 @@ Comprobar el estado de verificación: openclaw matrix verify status ``` -Estado detallado (diagnóstico completo): +Estado detallado (diagnósticos completos): ```bash openclaw matrix verify status --verbose @@ -448,15 +453,15 @@ Inicializar el estado de cross-signing y verificación: openclaw matrix verify bootstrap ``` -Compatibilidad con múltiples 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. +Compatibilidad con varias cuentas: usa `channels.matrix.accounts` con credenciales por cuenta y `name` opcional. Consulta [Configuration reference](/es/gateway/configuration-reference#multi-account-all-channels) para el patrón compartido. -Diagnóstico detallado del bootstrap: +Diagnósticos detallados de bootstrap: ```bash openclaw matrix verify bootstrap --verbose ``` -Forzar un restablecimiento nuevo de identidad de cross-signing antes del bootstrap: +Forzar un restablecimiento completo de la identidad de cross-signing antes de la inicialización: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -474,43 +479,43 @@ Detalles detallados de verificación del dispositivo: openclaw matrix verify device "" --verbose ``` -Comprobar el estado de salud de la copia de seguridad de claves de sala: +Comprobar el estado del respaldo de claves de sala: ```bash openclaw matrix verify backup status ``` -Diagnóstico detallado del estado de la copia de seguridad: +Diagnósticos detallados del estado del respaldo: ```bash openclaw matrix verify backup status --verbose ``` -Restaurar claves de sala desde la copia de seguridad del servidor: +Restaurar claves de sala desde el respaldo del servidor: ```bash openclaw matrix verify backup restore ``` -Diagnóstico detallado de la restauración: +Diagnósticos detallados de restauración: ```bash openclaw matrix verify backup restore --verbose ``` -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 puede cargarse limpiamente, este restablecimiento también puede recrear el almacenamiento secreto para que -los futuros arranques en frío puedan cargar la nueva clave de copia de seguridad: +Eliminar el respaldo actual del servidor y crear una base nueva de respaldo. Si la +clave de respaldo almacenada no puede cargarse limpiamente, este restablecimiento también puede recrear el almacenamiento de secretos para que +los futuros arranques en frío puedan cargar la nueva clave de respaldo: ```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ósticos detallados con `--verbose`. -Usa `--json` para una salida completa legible por máquina al crear scripts. +Usa `--json` para obtener la salida completa legible por máquina al automatizar scripts. -En configuraciones de múltiples cuentas, los comandos CLI de Matrix usan la cuenta predeterminada implícita de Matrix salvo 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 de Matrix CLI 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 implícitas de CLI 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 @@ -519,7 +524,7 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -Cuando el cifrado está deshabilitado o no disponible para una cuenta con nombre, las advertencias y errores de verificación de Matrix apuntan a la clave de configuración de esa cuenta, por ejemplo `channels.matrix.accounts.assistant.encryption`. +Cuando el cifrado está deshabilitado o no está 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" @@ -528,32 +533,32 @@ En la práctica, `openclaw matrix verify status --verbose` expone tres señales - `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 autofirma +- `Signed by owner`: el dispositivo está firmado por tu propia clave self-signing `Verified by owner` pasa a ser `yes` solo cuando existe verificación por cross-signing o firma del propietario. -La confianza local por sí sola no es suficiente para que OpenClaw trate el dispositivo como completamente verificado. +La confianza local por sí sola no basta para que OpenClaw trate el dispositivo como totalmente verificado. ### Qué hace bootstrap `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 secreto, reutilizando una clave de recuperación existente cuando sea posible -- inicializa el cross-signing y sube las claves públicas de cross-signing que falten -- intenta marcar y firmar con cross-signing el dispositivo actual -- crea una nueva copia de seguridad de claves de sala en el servidor si todavía no existe +- inicializa el almacenamiento de secretos, reutilizando una clave de recuperación existente cuando es posible +- inicializa cross-signing y sube las claves públicas de cross-signing que falten +- intenta marcar y firmar mediante cross-signing el dispositivo actual +- crea un nuevo respaldo del lado del servidor para claves de sala si todavía no existe uno -Si el homeserver requiere autenticación interactiva para subir claves de cross-signing, 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. +Si el homeserver requiere autenticación interactiva para subir claves de cross-signing, OpenClaw intenta la subida primero 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 realmente quieras descartar la identidad actual de cross-signing y crear una nueva. +Usa `--force-reset-cross-signing` solo cuando quieras descartar intencionadamente la identidad actual de cross-signing y crear una nueva. -Si intencionadamente quieres descartar 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`. +Si intencionadamente quieres descartar el respaldo actual de claves de sala y empezar una nueva +base de respaldo 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 puede recrear el almacenamiento secreto si el secreto actual de copia de seguridad +sin estar disponible y que OpenClaw puede recrear el almacenamiento de secretos si el secreto de respaldo actual no puede cargarse de forma segura. -### Nueva base de copia de seguridad +### Base nueva de respaldo Si quieres mantener funcionando los futuros mensajes cifrados y aceptas perder el historial antiguo irrecuperable, ejecuta estos comandos en orden: @@ -565,64 +570,64 @@ openclaw matrix verify status Añade `--account ` a cada comando cuando quieras apuntar explícitamente a una cuenta de Matrix con nombre. -### Comportamiento al inicio +### Comportamiento al iniciar -Cuando `encryption: true`, Matrix establece `startupVerification` de forma predeterminada en `"if-unverified"`. -Al iniciarse, si este dispositivo sigue sin verificarse, 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 volver a intentarlo tras reinicios. -Los intentos fallidos de solicitud vuelven a intentarse antes que la creación exitosa de solicitudes, de forma predeterminada. -Establece `startupVerification: "off"` para deshabilitar las solicitudes automáticas al inicio, o ajusta `startupVerificationCooldownHours` +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 tiempo de espera local antes de reintentar tras reinicios. +Los intentos fallidos de solicitud se reintentan antes que la creación exitosa de solicitudes, de forma predeterminada. +Establece `startupVerification: "off"` para desactivar las solicitudes automáticas al iniciar, 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 criptográfico. -Esa pasada intenta reutilizar primero el almacenamiento secreto actual y la identidad actual de cross-signing, y evita restablecer el cross-signing salvo que ejecutes un flujo explícito de reparación de bootstrap. +Esa pasada intenta primero reutilizar el almacenamiento de secretos y la identidad actual de cross-signing, y evita restablecer cross-signing salvo que ejecutes un flujo explícito de reparación de bootstrap. -Si durante el inicio se detecta un estado de bootstrap roto 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. +Si al iniciar se detecta un estado roto de bootstrap 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 conserva esa identidad en lugar de restablecerla automáticamente. -Actualización desde el plugin público anterior de Matrix: +Actualizar desde el plugin público anterior de Matrix: -- OpenClaw reutiliza automáticamente la misma cuenta de Matrix, token de acceso e identidad de dispositivo cuando es posible. +- 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 de Matrix que requiera acción, 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 anterior de almacenamiento plano para que OpenClaw sepa qué cuenta debe recibir ese estado heredado compartido. -- Si el plugin anterior almacenaba localmente una clave de descifrado de copia de seguridad de claves de sala de Matrix, el inicio o `openclaw doctor --fix` la importarán automáticamente al nuevo flujo de clave de recuperación. -- Si el token de acceso de Matrix cambió después de preparar la migración, el inicio ahora explora raíces de almacenamiento hermanas por hash de token en busca de estado heredado pendiente de restauración antes de abandonar la restauración automática de la copia de seguridad. -- Si el token de acceso de Matrix cambia más adelante 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 de la gateway, las claves de sala respaldadas se restauran automáticamente en el nuevo almacén criptográfico. -- Si el plugin anterior tenía claves de sala solo locales que nunca se respaldaron, OpenClaw mostrará una advertencia clara. Esas claves no se pueden exportar automáticamente desde el almacén criptográfico Rust anterior, por lo que parte del historial cifrado antiguo puede seguir sin estar disponible hasta recuperarse 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. +- Si usas varias cuentas de Matrix, establece `channels.matrix.defaultAccount` antes de actualizar desde el antiguo diseño de almacenamiento plano para que OpenClaw sepa qué cuenta debe recibir ese estado heredado compartido. +- Si el plugin anterior almacenaba localmente una clave de descifrado del respaldo de claves de sala de Matrix, el inicio o `openclaw doctor --fix` la importarán automáticamente al nuevo flujo de clave de recuperación. +- Si el token de acceso de Matrix cambió después de preparar la migración, ahora el inicio busca raíces vecinas de almacenamiento por hash de token en busca de estado heredado pendiente de restauración antes de abandonar la restauración automática del respaldo. +- 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 existente por hash de token más completa en lugar de empezar desde un directorio vacío de estado de Matrix. +- En el siguiente arranque del gateway, las claves de sala respaldadas se restauran automáticamente en el nuevo almacén criptográfico. +- 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 criptográfico anterior de Rust, por lo que parte del historial cifrado antiguo puede seguir sin estar disponible hasta recuperarse manualmente. +- Consulta [Matrix migration](/es/install/migrating-matrix) para ver el flujo completo de actualización, límites, comandos de recuperación y mensajes comunes de migración. -El estado cifrado en tiempo de ejecución se organiza bajo raíces por cuenta, usuario y hash de token en +El estado cifrado en tiempo de ejecución se organiza en 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 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`) +las vinculaciones de hilos (`thread-bindings.json`) y el estado de verificación al iniciar (`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 previo de sincronización, estado criptográfico, enlaces de hilos -y estado de verificación al inicio sigan visibles. +raíz existente para esa tupla de cuenta/homeserver/usuario, de modo que el estado previo de sincronización, estado criptográfico, vinculaciones de hilos +y estado de verificación al iniciar sigan siendo visibles. ### Modelo de almacén criptográfico de Node -Matrix E2EE en este plugin usa la ruta oficial de criptografía Rust de `matrix-js-sdk` en Node. +La E2EE de Matrix en este plugin usa la ruta criptográfica Rust oficial de `matrix-js-sdk` en Node. Esa ruta espera persistencia basada en IndexedDB cuando quieres que el estado criptográfico sobreviva a los reinicios. -OpenClaw actualmente lo proporciona en Node mediante: +Actualmente OpenClaw la proporciona en Node de esta forma: -- usar `fake-indexeddb` como la capa de API IndexedDB esperada por el SDK -- restaurar el contenido de IndexedDB del cifrado Rust desde `crypto-idb-snapshot.json` antes de `initRustCrypto` -- persistir el contenido actualizado de IndexedDB de nuevo en `crypto-idb-snapshot.json` después de la inicialización y durante la ejecución -- serializar la restauración y persistencia de la instantánea frente a `crypto-idb-snapshot.json` con un bloqueo de archivo consultivo para que la persistencia en tiempo de ejecución de la gateway y el mantenimiento de CLI no compitan sobre el mismo archivo de instantánea +- usa `fake-indexeddb` como el shim de API de IndexedDB que espera el SDK +- restaura el contenido de IndexedDB criptográfico de Rust desde `crypto-idb-snapshot.json` antes de `initRustCrypto` +- persiste el contenido actualizado de IndexedDB de vuelta en `crypto-idb-snapshot.json` después de la inicialización y durante la ejecución +- serializa la restauración y persistencia de instantáneas frente a `crypto-idb-snapshot.json` con un bloqueo de archivo consultivo para que la persistencia del gateway en tiempo de ejecución y el mantenimiento por CLI no compitan por el mismo archivo de instantánea -Esto es compatibilidad/infraestructura de almacenamiento, no una implementación criptográfica personalizada. +Esto es compatibilidad y plomería de almacenamiento, no una implementación criptográfica personalizada. El archivo de instantánea es estado sensible en tiempo de ejecución y se almacena con permisos de archivo restrictivos. -Según el modelo de seguridad de OpenClaw, el host de la 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 separado. +Según el modelo de seguridad de OpenClaw, el host del gateway y el directorio local de estado de OpenClaw ya están dentro del límite de confianza del operador, así que esto es principalmente una cuestión de durabilidad operativa más que un límite de confianza remoto separado. 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 de cifrado del almacén puedan obtenerse de proveedores de secretos de OpenClaw en lugar de solo de archivos locales +- añadir compatibilidad con SecretRef para el material persistente de claves de Matrix, de modo que las claves de recuperación y los secretos relacionados de cifrado del almacén puedan obtenerse de proveedores de secretos de OpenClaw en lugar de solo de archivos locales -## Gestión del perfil +## Gestión de perfil Actualiza el perfil propio de Matrix para la cuenta seleccionada con: @@ -633,45 +638,45 @@ 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 la sube primero a Matrix y almacena la URL `mxc://` resuelta de nuevo en `channels.matrix.avatarUrl` (o en la sustitución de la cuenta seleccionada). +Matrix acepta directamente URLs 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 anulación de la cuenta seleccionada). ## Avisos automáticos de verificación -Ahora Matrix publica avisos del ciclo de vida de verificación directamente en la sala estricta de MD de verificación como mensajes `m.notice`. +Matrix ahora publica avisos del ciclo de vida de la verificación directamente en la sala estricta de MD de verificación como mensajes `m.notice`. Eso incluye: - avisos de solicitud de verificación -- avisos de verificación lista (con guía explícita de "Verify by emoji") +- avisos de verificación lista (con indicació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 +- detalles SAS (emoji y decimal) cuando están disponibles -Las solicitudes de verificación entrantes desde otro cliente de Matrix se rastrean y OpenClaw las acepta automáticamente. -Para los 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 desde otro usuario/dispositivo de Matrix, OpenClaw acepta automáticamente la solicitud y luego espera a que el flujo SAS continúe con normalidad. -Aun así, necesitas comparar el SAS de emoji o decimal en tu cliente de Matrix y confirmar allí "They match" para completar la verificación. +Las solicitudes entrantes de verificación 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 está 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 normalmente. +Aun así, debes comparar el SAS de emoji o decimal en tu cliente de Matrix y confirmar allí "They match" para completar la verificación. -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. +OpenClaw no acepta automáticamente a ciegas flujos duplicados iniciados por él mismo. Al iniciar se omite crear una nueva solicitud cuando ya hay una solicitud de autoverificación pendiente. -Los avisos de protocolo/sistema de verificación no se reenvían a la canalización de chat del agente, por lo que no producen `NO_REPLY`. +Los avisos de verificación de protocolo/sistema no se reenvían al flujo de chat del agente, por lo que no producen `NO_REPLY`. ### Higiene de dispositivos -Los dispositivos antiguos de Matrix gestionados por OpenClaw pueden acumularse en la cuenta y dificultar el razonamiento sobre la confianza en salas cifradas. -Haz una lista con: +Los dispositivos antiguos de Matrix gestionados por OpenClaw pueden acumularse en la cuenta y dificultar la comprensión de la confianza en salas cifradas. +Enuméralos con: ```bash openclaw matrix devices list ``` -Elimina dispositivos obsoletos gestionados por OpenClaw con: +Elimina los dispositivos obsoletos gestionados por OpenClaw con: ```bash openclaw matrix devices prune-stale ``` -### Reparación de sala directa +### Reparación directa de salas -Si el estado del mensaje directo se desincroniza, OpenClaw puede terminar con asignaciones `m.direct` obsoletas que apuntan a salas individuales antiguas en lugar de a la MD activa. Inspecciona la asignación actual de un par con: +Si el estado de mensajes directos se desincroniza, OpenClaw puede terminar con asignaciones `m.direct` obsoletas que apuntan a salas individuales antiguas en lugar del MD activo. Inspecciona la asignación actual para un par con: ```bash openclaw matrix direct inspect --user-id @alice:example.org @@ -685,51 +690,51 @@ 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` -- de lo 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 +- prefiere un MD estricto 1:1 que ya esté asignado en `m.direct` +- en caso contrario, recurre a cualquier MD estricto 1:1 actualmente unido con ese usuario +- si no existe un MD sano, 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 elige 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 mensaje directo vuelvan a apuntar a la sala correcta. +El flujo de reparación no elimina automáticamente las salas antiguas. Solo elige el MD correcto 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. ## 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 con la herramienta de mensajes. -- `dm.sessionScope: "per-user"` (predeterminado) mantiene el enrutamiento de MD de Matrix con ámbito del 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 comprobaciones normales de autenticación de MD y lista de permitidos. -- Los enlaces explícitos de conversación de Matrix siguen teniendo prioridad sobre `dm.sessionScope`, por lo que las salas e hilos enlazados conservan su sesión de destino elegida. -- `threadReplies: "off"` mantiene las respuestas al nivel superior y conserva los mensajes entrantes en hilo en la sesión padre. +- `dm.sessionScope: "per-user"` (predeterminado) mantiene el enrutamiento de MD de Matrix con alcance al remitente, de modo que varias salas de MD puedan 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 sin dejar de usar las comprobaciones normales de autenticación y lista de permitidos de MD. +- Las vinculaciones explícitas 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. - `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 activador y enruta esa conversación a través de la sesión con ámbito de hilo correspondiente desde el primer mensaje activador. -- `dm.threadReplies` sustituye la configuración de nivel superior solo para las MD. Por ejemplo, puedes mantener aislados los hilos de sala mientras mantienes planas las MD. -- Los mensajes entrantes en hilo incluyen el mensaje raíz del hilo como contexto adicional del 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, salvo que se proporcione un `threadId` explícito. -- La reutilización del destino de usuario de MD de la misma sesión solo se activa cuando los metadatos de la sesión actual demuestran el mismo par de MD en la misma cuenta de Matrix; en caso contrario, OpenClaw vuelve al enrutamiento normal con ámbito de 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 único `m.notice` en esa sala con la vía de escape `/focus` cuando los enlaces de hilos están habilitados y con 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` enlazado a hilo ahora funcionan en salas y MD de Matrix. -- `/focus` de sala/MD de Matrix al nivel superior crea un nuevo hilo de Matrix y lo enlaza con 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. +- `threadReplies: "always"` mantiene las respuestas de sala en un hilo con raíz en el mensaje desencadenante y enruta esa conversación mediante la sesión con alcance de hilo correspondiente 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 los MD planos. +- Los mensajes entrantes en hilo incluyen el mensaje raíz del hilo como contexto adicional para el agente. +- Los envíos de la herramienta de mensajes ahora heredan automáticamente el hilo actual de Matrix cuando el destino es la misma sala o el mismo objetivo de usuario de MD, a menos que se proporcione un `threadId` explícito. +- La reutilización de objetivo de usuario de MD de misma sesión solo se activa cuando los metadatos de la sesión actual demuestran el mismo par de MD en la misma cuenta de Matrix; en caso contrario, OpenClaw vuelve al enrutamiento normal con alcance de usuario. +- Cuando OpenClaw ve que una sala de MD de Matrix entra en conflicto con otra sala de MD en la misma sesión compartida de MD de Matrix, publica un `m.notice` de una sola vez en esa sala con la vía de escape `/focus` cuando las vinculaciones de hilos están habilitadas y la pista `dm.sessionScope`. +- Las vinculaciones 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 de 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 de Matrix existente vincula ese hilo actual en su lugar. -## Enlaces de conversación ACP +## Vinculaciones 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, los MD y los hilos existentes de Matrix pueden convertirse en espacios de trabajo ACP duraderos sin cambiar la superficie del chat. -Flujo rápido para operadores: +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 permanece como superficie de chat y los mensajes futuros se enrutan a la sesión ACP generada. -- 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. +- Ejecuta `/acp spawn codex --bind here` dentro del MD, la sala o el hilo existente de Matrix que quieras seguir usando. +- En un MD o sala de Matrix de nivel superior, el MD o la sala actuales siguen siendo la superficie del chat y los mensajes futuros se enrutan a la sesión ACP creada. +- Dentro de un hilo existente de Matrix, `--bind here` vincula ese hilo actual en el mismo lugar. +- `/new` y `/reset` restablecen la misma sesión ACP vinculada en el mismo lugar. +- `/acp close` cierra la sesión ACP y elimina la vinculación. Notas: - `--bind here` no crea un hilo hijo de Matrix. -- `threadBindings.spawnAcpSessions` solo se requiere para `/acp spawn --thread auto|here`, donde OpenClaw necesita crear o enlazar 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. -### Configuración de enlace de hilos +### Configuración de vinculación de hilos -Matrix hereda valores globales predeterminados de `session.threadBindings`, y también admite sustituciones por canal: +Matrix hereda los valores predeterminados globales de `session.threadBindings` y también admite reemplazos por canal: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -737,27 +742,27 @@ Matrix hereda valores globales predeterminados de `session.threadBindings`, y ta - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Las marcas de generación enlazada a hilos de Matrix son opcionales: +Las banderas de creación vinculada a hilos de Matrix son opcionales: -- 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. +- 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. ## Reacciones Matrix admite acciones de reacción salientes, notificaciones de reacción entrantes y reacciones de confirmación entrantes. -- Las herramientas de reacción saliente están controladas por `channels["matrix"].actions.reactions`. +- La herramienta de reacciones salientes está controlada 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 de un evento específico de Matrix. -- `emoji=""` elimina las propias reacciones de la cuenta del bot sobre ese evento. -- `remove: true` elimina solo la reacción de emoji especificada de la cuenta del bot. +- `reactions` enumera el resumen actual de reacciones para un evento específico de Matrix. +- `emoji=""` elimina las reacciones de la propia cuenta del bot en ese evento. +- `remove: true` elimina solo la reacción con el emoji especificado de la cuenta del bot. -El alcance de las reacciones de confirmación se resuelve en este orden estándar de OpenClaw: +Las reacciones de confirmación usan el orden estándar de resolución de OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- alternativa con emoji de identidad del agente +- emoji de reserva de identidad del agente El alcance de la reacción de confirmación se resuelve en este orden: @@ -773,31 +778,31 @@ El modo de notificación de reacciones se resuelve en este orden: Comportamiento actual: -- `reactionNotifications: "own"` reenvía eventos `m.reaction` añadidos cuando apuntan a mensajes de Matrix creados por el bot. -- `reactionNotifications: "off"` deshabilita los eventos del sistema de reacciones. -- Las eliminaciones de reacciones todavía no se sintetizan en eventos del sistema porque Matrix las presenta como redacciones, no como eliminaciones independientes de `m.reaction`. +- `reactionNotifications: "own"` reenvía eventos `m.reaction` añadidos cuando apuntan a mensajes de Matrix escritos por el bot. +- `reactionNotifications: "off"` desactiva los eventos del sistema de reacciones. +- Las eliminaciones de reacciones todavía no se sintetizan en eventos del sistema porque Matrix las expone como redacciones, no como eliminaciones independientes de `m.reaction`. ## Contexto del historial -- `channels.matrix.historyLimit` controla cuántos mensajes recientes de sala se incluyen como `InboundHistory` cuando un mensaje de sala de Matrix activa al agente. -- Recurre a `messages.groupChat.historyLimit`. Establece `0` para deshabilitarlo. -- El historial de salas de Matrix es solo de sala. Las MD siguen usando el historial normal de sesión. +- `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 establecidos, el valor predeterminado efectivo es `0`, por lo que los mensajes de sala con requisito de mención no se almacenan en búfer. Establece `0` para desactivar. +- El historial de salas de Matrix es solo de sala. Los 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 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 para 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 hacia 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 recuperado, raíces de hilo e historial pendiente. +Matrix admite el control compartido `contextVisibility` para el contexto suplementario de 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: "all"` es el valor predeterminado. El contexto suplementario se conserva tal como se recibe. - `contextVisibility: "allowlist"` filtra el contexto suplementario a remitentes permitidos por las comprobaciones activas de lista de permitidos de sala/usuario. - `contextVisibility: "allowlist_quote"` se comporta como `allowlist`, pero sigue conservando una respuesta citada explícita. -Esta configuración afecta a la visibilidad del contexto suplementario, no a si el propio mensaje entrante puede activar una respuesta. -La autorización del activador sigue proviniendo de `groupPolicy`, `groups`, `groupAllowFrom` y de la configuración de la política de MD. +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ítica de MD. -## Ejemplo de política de MD y salas +## Ejemplo de política de MD y sala ```json5 { @@ -820,7 +825,7 @@ La autorización del activador sigue proviniendo de `groupPolicy`, `groups`, `gr } ``` -Consulta [Groups](/es/channels/groups) para el comportamiento de mención obligatoria y lista de permitidos. +Consulta [Groups](/es/channels/groups) para conocer el comportamiento de requisito de mención y lista de permitidos. Ejemplo de emparejamiento para MD de Matrix: @@ -829,13 +834,13 @@ 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 generar 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 de emparejamiento pendiente y puede volver a enviar una respuesta de recordatorio tras un breve tiempo de espera en lugar de generar un código nuevo. -Consulta [Pairing](/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 MD y el diseño de almacenamiento. -## Aprobaciones de exec +## Aprobaciones de ejecución -Matrix puede actuar como cliente de aprobación de exec para una cuenta de Matrix. +Matrix puede actuar como cliente de aprobación de ejecución para una cuenta de Matrix. - `channels.matrix.execApprovals.enabled` - `channels.matrix.execApprovals.approvers` (opcional; recurre a `channels.matrix.dm.allowFrom`) @@ -843,39 +848,39 @@ Matrix puede actuar como cliente de aprobación de exec para una cuenta de Matri - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Los aprobadores deben ser IDs de usuario de Matrix como `@owner:example.org`. Matrix habilita automáticamente las aprobaciones nativas de exec cuando `enabled` no está definido o es `"auto"` y al menos puede resolverse un aprobador, ya sea desde `execApprovals.approvers` o desde `channels.matrix.dm.allowFrom`. Establece `enabled: false` para deshabilitar 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 de respaldo de aprobación de exec. +Los aprobadores deben ser IDs de usuario de Matrix como `@owner:example.org`. Matrix habilita automáticamente las aprobaciones nativas de ejecución cuando `enabled` no está establecido o es `"auto"` y al menos puede resolverse un aprobador, ya sea desde `execApprovals.approvers` o desde `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 de reserva de aprobación de ejecución. -Actualmente, el enrutamiento nativo de Matrix es solo para exec: +El enrutamiento nativo de Matrix hoy es solo para ejecución: -- `channels.matrix.execApprovals.*` controla el enrutamiento nativo de MD/canal solo para aprobaciones de exec. -- Las aprobaciones del plugin siguen usando `/approve` compartido en el mismo chat más cualquier reenvío configurado en `approvals.plugin`. -- Matrix todavía puede reutilizar `channels.matrix.dm.allowFrom` para la autorización de aprobaciones del plugin cuando puede inferir aprobadores de forma segura, pero no expone una ruta nativa separada de distribución por MD/canal para aprobaciones del plugin. +- `channels.matrix.execApprovals.*` controla el enrutamiento nativo de MD/canal para aprobaciones de ejecución únicamente. +- Las aprobaciones de plugin siguen usando `/approve` en el mismo chat compartido más cualquier reenvío configurado de `approvals.plugin`. +- Matrix todavía puede reutilizar `channels.matrix.dm.allowFrom` para la autorización de aprobación de plugins cuando puede inferir aprobadores de forma segura, pero no expone una ruta nativa separada de distribución en MD/canal para aprobación de plugins. Reglas de entrega: -- `target: "dm"` envía solicitudes de aprobación a las MD de los aprobadores +- `target: "dm"` envía solicitudes de aprobación a los MD de los aprobadores - `target: "channel"` envía la solicitud de vuelta a la sala o MD de Matrix de origen -- `target: "both"` envía a las MD de los aprobadores y a la sala o MD de Matrix de origen +- `target: "both"` envía a los MD de los aprobadores y a la sala o MD de Matrix de origen -Las solicitudes de aprobación de Matrix siembran atajos de reacción en el mensaje principal de aprobación: +Las solicitudes de aprobación de Matrix generan 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 de ejecución efectiva -Los aprobadores pueden reaccionar a ese mensaje o usar los comandos slash alternativos: `/approve allow-once`, `/approve allow-always` o `/approve deny`. +Los aprobadores pueden reaccionar en ese mensaje o usar los comandos slash de reserva: `/approve allow-once`, `/approve allow-always` o `/approve deny`. -Solo los aprobadores resueltos pueden aprobar o denegar. 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. La entrega por canal incluye el texto del comando, así que habilita `channel` o `both` solo en salas de confianza. -Las solicitudes de aprobación de Matrix reutilizan el planificador compartido de aprobaciones del núcleo. La superficie nativa específica de Matrix es solo de transporte para aprobaciones de exec: enrutamiento de sala/MD y comportamiento de envío/actualización/eliminación de mensajes. +Las solicitudes de aprobación de Matrix reutilizan el planificador compartido principal de aprobaciones. La superficie nativa específica de Matrix es solo el transporte para aprobaciones de ejecución: enrutamiento de sala/MD y comportamiento de envío/actualización/eliminación de mensajes. -Sustitución por cuenta: +Reemplazo por cuenta: - `channels.matrix.accounts..execApprovals` -Documentación relacionada: [Aprobaciones de exec](/es/tools/exec-approvals) +Documentación relacionada: [Exec approvals](/es/tools/exec-approvals) -## Ejemplo de múltiples cuentas +## Ejemplo de varias cuentas ```json5 { @@ -905,19 +910,19 @@ Documentación relacionada: [Aprobaciones de exec](/es/tools/exec-approvals) } ``` -Los valores de nivel superior de `channels.matrix` actúan como valores predeterminados para las cuentas con nombre salvo que una cuenta los sustituya. -Puedes aplicar 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 `channels.matrix.*` de nivel superior. -Los valores predeterminados compartidos de autenticación parcial no crean por sí solos una cuenta predeterminada implícita separada. OpenClaw solo sintetiza la cuenta `default` de nivel superior cuando ese valor predeterminado tiene autenticación nueva (`homeserver` más `accessToken`, o `homeserver` más `userId` y `password`); las cuentas con nombre pueden seguir siendo detectables desde `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 de cuenta con nombre existente, la promoción de reparación/configuración de cuenta única a múltiples cuentas preserva 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 promocionada; 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, sondeo y operaciones de CLI. -Si configuras varias cuentas con nombre, establece `defaultAccount` o pasa `--account ` para comandos de CLI que dependen de la selección implícita de cuenta. -Pasa `--account ` a `openclaw matrix verify ...` y `openclaw matrix devices ...` cuando quieras sustituir esa selección implícita para un solo comando. +Los valores de nivel superior `channels.matrix` actúan como valores predeterminados para las cuentas con nombre, salvo que una cuenta los reemplace. +Puedes limitar una entrada de sala heredada 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 se configura directamente en `channels.matrix.*` de nivel superior. +Los valores predeterminados parciales de autenticación compartida no crean por sí solos una cuenta predeterminada implícita separada. OpenClaw solo sintetiza la cuenta `default` de nivel superior cuando ese valor predeterminado 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é satisfagan 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 de política de entrega compartida permanecen en el nivel superior. +Establece `defaultAccount` cuando quieras que OpenClaw prefiera una cuenta de Matrix con nombre para el enrutamiento implícito, sondeo y operaciones de CLI. +Si configuras varias cuentas con nombre, establece `defaultAccount` o pasa `--account ` para los comandos de CLI que dependen de la selección implícita de cuenta. +Pasa `--account ` a `openclaw matrix verify ...` y `openclaw matrix devices ...` cuando quieras reemplazar esa selección implícita para un comando. ## Homeservers privados/LAN -De forma predeterminada, OpenClaw bloquea los homeservers privados/internos de Matrix para proteger contra SSRF salvo que -los habilites explícitamente por cuenta. +De forma predeterminada, OpenClaw bloquea los homeservers privados o internos de Matrix para protección SSRF, salvo que +aceptes explícitamente por cuenta. Si tu homeserver se ejecuta en localhost, una IP de LAN/Tailscale o un nombre de host interno, habilita `allowPrivateNetwork` para esa cuenta de Matrix: @@ -934,7 +939,7 @@ Si tu homeserver se ejecuta en localhost, una IP de LAN/Tailscale o un nombre de } ``` -Ejemplo de configuración por CLI: +Ejemplo de configuración mediante CLI: ```bash openclaw matrix account add \ @@ -944,12 +949,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Esta habilitación explícita solo permite destinos 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 solo permite destinos privados o internos de confianza. Los homeservers públicos en texto plano, como +`http://matrix.example.org:8008`, siguen bloqueados. Usa `https://` siempre que sea posible. -## Uso de proxy para tráfico de Matrix +## Proxy para tráfico de Matrix -Si tu despliegue de Matrix necesita un proxy HTTP(S) saliente explícito, establece `channels.matrix.proxy`: +Si tu implementación de Matrix necesita un proxy HTTP(S) saliente explícito, establece `channels.matrix.proxy`: ```json5 { @@ -963,7 +968,7 @@ Si tu despliegue de Matrix necesita un proxy HTTP(S) saliente explícito, establ } ``` -Las cuentas con nombre pueden sustituir el valor predeterminado de nivel superior con `channels.matrix.accounts..proxy`. +Las cuentas con nombre pueden reemplazar 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 cuenta. ## Resolución de destino @@ -974,75 +979,76 @@ Matrix acepta estas formas de destino en cualquier lugar donde OpenClaw te pida - 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 activa en directorio usa la cuenta de Matrix que ha iniciado sesión: +La búsqueda en directorio en vivo usa la cuenta de Matrix con sesión iniciada: -- Las búsquedas de usuario consultan el directorio de usuarios de Matrix en ese homeserver. -- Las búsquedas de sala aceptan directamente IDs y alias explícitos de sala, y luego recurren a buscar nombres de salas unidas para esa cuenta. -- La búsqueda por nombre de sala unida es de mejor esfuerzo. Si un nombre de sala no puede resolverse a un ID o alias, se ignora en la resolución de lista de permitidos en tiempo de ejecució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 explícitos de sala, y luego 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 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`. -- `allowPrivateNetwork`: permite que esta cuenta de Matrix se conecte a homeservers privados/internos. Habilítalo cuando el homeserver se resuelva a `localhost`, una IP de 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 sustituir el valor predeterminado de nivel superior con su propio `proxy`. +- `allowPrivateNetwork`: permite que esta cuenta de Matrix se conecte a homeservers privados o internos. Habilítalo cuando el homeserver resuelva a `localhost`, una IP de 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`. - `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 sin formato 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 sin formato y valores SecretRef. -- `deviceId`: ID explícito de 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 de `set-profile`. -- `initialSyncLimit`: límite de eventos de sincronización al inicio. +- `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 [Secrets Management](/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 por 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. - `encryption`: habilita E2EE. -- `allowlistOnly`: fuerza el comportamiento solo de lista de permitidos para MD y salas. -- `allowBots`: permite mensajes de otras cuentas configuradas de Matrix de OpenClaw (`true` o `"mentions"`). +- `allowlistOnly`: fuerza comportamiento de solo lista de permitidos para MD y salas. +- `allowBots`: permite mensajes de otras cuentas configuradas de OpenClaw Matrix (`true` o `"mentions"`). - `groupPolicy`: `open`, `allowlist` o `disabled`. - `contextVisibility`: modo de visibilidad del contexto suplementario de sala (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: lista de permitidos de IDs de usuario para tráfico de salas. -- Las entradas de `groupAllowFrom` deben ser IDs completos de usuario de Matrix. Los nombres no resueltos se ignoran en tiempo de ejecución. -- `historyLimit`: máximo de mensajes de sala que se incluirán como contexto de historial de grupo. Recurre a `messages.groupChat.historyLimit`. Establece `0` para deshabilitarlo. +- `groupAllowFrom`: lista de permitidos de IDs de usuario para tráfico de sala. +- Las entradas de `groupAllowFrom` deben ser IDs completos de usuario de Matrix. Los nombres sin resolver se ignoran en tiempo de ejecución. +- `historyLimit`: máximo de mensajes de sala que se incluirán como contexto de historial de grupo. Recurre a `messages.groupChat.historyLimit`; si ambos no están establecidos, el valor predeterminado efectivo es `0`. Establece `0` para desactivar. - `replyToMode`: `off`, `first` o `all`. - `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 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. -- `blockStreaming`: `true` habilita mensajes de progreso separados para bloques completados del asistente mientras está activo el streaming de vista previa de borrador. +- `streaming`: `off` (predeterminado), `partial`, `quiet`, `true` o `false`. `partial` y `true` habilitan actualizaciones de borrador de vista previa primero con mensajes normales de texto de Matrix. `quiet` usa avisos de vista previa sin notificación para configuraciones autoalojadas con reglas push. +- `blockStreaming`: `true` habilita mensajes de progreso separados para bloques completados del asistente mientras el streaming de borrador de vista previa está activo. - `threadReplies`: `off`, `inbound` o `always`. -- `threadBindings`: sustituciones por canal para enrutamiento y ciclo de vida de sesión enlazada a hilos. -- `startupVerification`: modo de solicitud automática de autoverificación al inicio (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: enfriamiento antes de volver a intentar solicitudes automáticas de verificación al inicio. +- `threadBindings`: reemplazos por canal para el enrutamiento y ciclo de vida de sesiones vinculadas a hilos. +- `startupVerification`: modo de solicitud automática de autoverificación al iniciar (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: tiempo de espera 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`: sustitución opcional de reacción de confirmación para este canal/cuenta. -- `ackReactionScope`: sustitución opcional del alcance de reacción de confirmación (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `ackReaction`: reemplazo opcional de reacción de confirmación para este canal o cuenta. +- `ackReactionScope`: reemplazo opcional del alcance de la reacción de confirmación (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: modo de notificación de reacción entrante (`own`, `off`). -- `mediaMaxMb`: límite de tamaño de medios en MB para el manejo de medios de Matrix. Se aplica a envíos salientes y al procesamiento de medios entrantes. -- `autoJoin`: política de unión automática por invitación (`always`, `allowlist`, `off`). Predeterminado: `off`. -- `autoJoinAllowlist`: salas/alias permitidos cuando `autoJoin` es `allowlist`. Las entradas de alias se resuelven a IDs de sala durante el manejo de invitaciones; OpenClaw no confía en el estado de alias declarado por la sala invitante. +- `mediaMaxMb`: límite de tamaño de multimedia en MB para el manejo multimedia de Matrix. Se aplica a los envíos salientes y al procesamiento multimedia entrante. +- `autoJoin`: política de autoaceptación de 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 invitaciones de salas o grupos. OpenClaw toma esta decisión en el momento de la invitación, antes de poder clasificar de forma fiable la sala unida como MD o grupo. +- `autoJoinAllowlist`: salas o alias permitidos cuando `autoJoin` es `allowlist`. Las entradas de alias se resuelven a IDs de sala durante el manejo de invitaciones; OpenClaw no confía en el estado de alias declarado por la sala invitada. - `dm`: bloque de política de MD (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- Las entradas `dm.allowFrom` deben ser IDs completos de usuario de Matrix salvo que ya las hayas resuelto mediante búsqueda activa en el directorio. -- `dm.sessionScope`: `per-user` (predeterminado) o `per-room`. Usa `per-room` cuando quieras que cada sala de MD de Matrix mantenga contexto separado aunque el par sea el mismo. -- `dm.threadReplies`: sustitución de política de hilos solo para MD (`off`, `inbound`, `always`). Sustituye la configuración `threadReplies` de nivel superior tanto para la colocación de respuestas como para el aislamiento de sesión en MD. -- `execApprovals`: entrega nativa de aprobaciones de exec de Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: IDs de usuario de Matrix autorizados para aprobar solicitudes de exec. Es opcional cuando `dm.allowFrom` ya identifica a los aprobadores. +- `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 autoacepta. +- Las entradas de `dm.allowFrom` deben ser IDs completos de usuario de Matrix, salvo que ya las hayas resuelto mediante búsqueda en directorio en vivo. +- `dm.sessionScope`: `per-user` (predeterminado) o `per-room`. Usa `per-room` cuando quieras que cada sala de MD de Matrix conserve un contexto separado aunque el par sea el mismo. +- `dm.threadReplies`: reemplazo de política de hilos solo para MD (`off`, `inbound`, `always`). Reemplaza la configuración de nivel superior `threadReplies` tanto para la colocación de respuestas como para el aislamiento de sesión en MD. +- `execApprovals`: entrega nativa de aprobación de ejecución de Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: IDs de usuario de Matrix autorizados para aprobar solicitudes de ejecución. Opcional cuando `dm.allowFrom` ya identifica a los aprobadores. - `execApprovals.target`: `dm | channel | both` (predeterminado: `dm`). -- `accounts`: sustituciones con nombre por cuenta. Los valores de nivel superior de `channels.matrix` actúan como valores 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 tras la resolución, mientras que las etiquetas legibles para humanos siguen viniendo de los nombres de sala. -- `groups..account`: restringe una entrada de sala heredada a una cuenta específica de Matrix en configuraciones de múltiples cuentas. -- `groups..allowBots`: sustitución a nivel de sala para remitentes bot configurados (`true` o `"mentions"`). +- `accounts`: reemplazos con nombre por cuenta. Los valores de nivel superior `channels.matrix` actúan como predeterminados para estas entradas. +- `groups`: mapa de política por sala. Usa preferiblemente IDs o alias de sala; los nombres de sala sin resolver se ignoran en tiempo de ejecución. La identidad de sesión o grupo usa el ID estable de sala después de la resolución, mientras que las etiquetas legibles siguen viniendo de los nombres de sala. +- `groups..account`: restringe una entrada heredada de sala a una cuenta específica de Matrix en configuraciones de varias cuentas. +- `groups..allowBots`: reemplazo a nivel de sala para remitentes bot configurados (`true` o `"mentions"`). - `groups..users`: lista de permitidos de remitentes por sala. -- `groups..tools`: sustituciones por sala de permitir/denegar herramientas. -- `groups..autoReply`: sustitución a nivel de sala para obligatoriedad de mención. `true` deshabilita el requisito de mención para esa sala; `false` lo vuelve a forzar. +- `groups..tools`: reemplazos por sala para permitir o denegar herramientas. +- `groups..autoReply`: reemplazo a nivel de sala del requisito de mención. `true` desactiva el requisito de mención para esa sala; `false` vuelve a activarlo. - `groups..skills`: filtro opcional de Skills a nivel de sala. -- `groups..systemPrompt`: fragmento opcional de system prompt a nivel de sala. +- `groups..systemPrompt`: fragmento opcional de prompt del sistema a nivel de sala. - `rooms`: alias heredado de `groups`. - `actions`: control por acción de herramientas (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Relacionado -- [Resumen de canales](/es/channels) — todos los canales compatibles -- [Pairing](/es/channels/pairing) — autenticación de MD y flujo de emparejamiento -- [Groups](/es/channels/groups) — comportamiento del chat grupal y obligatoriedad de mención -- [Enrutamiento de canales](/es/channels/channel-routing) — enrutamiento de sesiones para mensajes -- [Seguridad](/es/gateway/security) — modelo de acceso y endurecimiento +- [Channels Overview](/es/channels) — todos los canales compatibles +- [Pairing](/es/channels/pairing) — autenticación MD y flujo de emparejamiento +- [Groups](/es/channels/groups) — comportamiento del chat de grupo y requisito de mención +- [Channel Routing](/es/channels/channel-routing) — enrutamiento de sesión para mensajes +- [Security](/es/gateway/security) — modelo de acceso y endurecimiento diff --git a/docs/es/concepts/dreaming.md b/docs/es/concepts/dreaming.md index eeb970ef8..877d86443 100644 --- a/docs/es/concepts/dreaming.md +++ b/docs/es/concepts/dreaming.md @@ -1,52 +1,52 @@ --- read_when: - Quieres que la promoción de memoria se ejecute automáticamente - - Quieres entender qué hace cada fase de sueño - - Quieres ajustar la consolidación sin contaminar `MEMORY.md` + - Quieres entender qué hace cada fase de dreaming + - 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: Sueños (experimental) +title: Dreaming (experimental) x-i18n: - generated_at: "2026-04-06T03:06:09Z" + generated_at: "2026-04-06T05:12:22Z" model: gpt-5.4 provider: openai - source_hash: f27da718176bebf59fe8a80fddd4fb5b6d814ac5647f6c1e8344bcfb328db9de + source_hash: 36c4b1e70801d662090dc8ce20608c2f141c23cd7ce53c54e3dcf332c801fd4e source_path: concepts/dreaming.md workflow: 15 --- -# Sueños (experimental) +# Dreaming (experimental) -Sueños es el sistema de consolidación de memoria en segundo plano de `memory-core`. -Ayuda a OpenClaw a mover señales sólidas de corto plazo hacia memoria duradera mientras +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 mantiene el proceso explicable y revisable. -Sueños es **optativo** y está deshabilitado de forma predeterminada. +Dreaming es **optativo** y está desactivado de forma predeterminada. -## Qué escribe Sueños +## Qué escribe dreaming -Sueños mantiene dos tipos de salida: +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 para humanos** en `DREAMS.md` (o `dreams.md` existente) y archivos opcionales de informes de fase en `memory/dreaming//YYYY-MM-DD.md`. +- **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`. La promoción a largo plazo sigue escribiendo solo en `MEMORY.md`. ## Modelo de fases -Sueños usa tres fases cooperativas: +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 | +| ----- | --------- | ------------------ | +| 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 | Estas fases son detalles internos de implementación, no "modos" separados configurados por el usuario. ### Fase ligera -La fase ligera ingiere señales recientes de memoria diaria y trazas de recuperación, las desduplica +La fase ligera 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. @@ -58,59 +58,59 @@ y prepara líneas candidatas. La fase profunda decide qué se convierte en memoria a largo plazo. -- Clasifica candidatos usando puntuación ponderada y umbrales de control. +- Clasifica candidatos usando puntuación ponderada y umbrales de acceso. - Requiere que `minScore`, `minRecallCount` y `minUniqueQueries` se cumplan. -- Rehidrata fragmentos desde archivos diarios activos antes de escribir, por lo que se omiten fragmentos obsoletos o eliminados. +- 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`. -- Escribe un resumen `## Deep Sleep` en `DREAMS.md` y opcionalmente escribe `memory/dreaming/deep/YYYY-MM-DD.md`. +- Escribe un resumen `## Deep Sleep` en `DREAMS.md` y, opcionalmente, escribe `memory/dreaming/deep/YYYY-MM-DD.md`. ### Fase REM La fase REM extrae patrones y señales reflexivas. -- Construye resúmenes de temas y reflexiones a partir de trazas recientes de corto plazo. +- Construye resúmenes de temas y reflexiones a partir de rastros recientes de corto plazo. - Escribe un bloque administrado `## REM Sleep` cuando el almacenamiento incluye salida en línea. - Registra señales de refuerzo REM usadas por la clasificación profunda. - Nunca escribe en `MEMORY.md`. ## Diario de Sueños -Sueños también mantiene un **Diario de Sueños** narrativo en `DREAMS.md`. -Después de que cada fase tiene suficiente material, `memory-core` ejecuta en segundo plano, con el mejor esfuerzo, -un turno de subagente (usando el modelo de runtime predeterminado) y agrega una breve entrada de diario. +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. -Este diario es para lectura humana en la interfaz de Sueños, no una fuente de promoción. +Este diario es para lectura humana en la UI de Dreams, no una fuente de promoción. ## Señales de clasificación profunda -La clasificación profunda usa seis señales base ponderadas más refuerzo por fase: +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 promedio de recuperación de la entrada | -| Diversidad de consultas | 0.15 | Contextos distintos de consulta/día en los 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 | +| 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 | -Los aciertos de las fases ligera y REM agregan un pequeño impulso con decaimiento temporal desde +Los aciertos de las fases ligera y REM añaden un pequeño refuerzo 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 sueños. Cada barrido ejecuta las fases en orden: ligera -> REM -> profunda. +completo de dreaming. Cada barrido ejecuta las fases en orden: ligera -> REM -> profunda. Comportamiento predeterminado de la cadencia: -| Configuración | Predeterminado | -| -------------------- | ----------- | +| Configuración | Predeterminado | +| ------------- | -------------- | | `dreaming.frequency` | `0 3 * * *` | ## Inicio rápido -Habilitar Sueños: +Habilitar dreaming: ```json { @@ -128,7 +128,7 @@ Habilitar Sueños: } ``` -Habilitar Sueños con una cadencia de barrido personalizada: +Habilitar dreaming con una cadencia de barrido personalizada: ```json { @@ -168,31 +168,46 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -`memory promote` manual usa los umbrales de la fase profunda de forma predeterminada, a menos que se reemplacen -con indicadores de la CLI. +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. + +Explica por qué un candidato específico se promovería o no: + +```bash +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 +escribir nada: + +```bash +openclaw memory rem-harness +openclaw memory rem-harness --json +``` ## Valores predeterminados clave -Toda la configuración se encuentra en `plugins.entries.memory-core.config.dreaming`. +Todas las configuraciones viven en `plugins.entries.memory-core.config.dreaming`. -| Clave | Predeterminado | -| ----------- | ----------- | -| `enabled` | `false` | +| 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 visible para el usuario). +(no son 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. -## Interfaz de Sueños +## UI de Dreams Cuando está habilitada, la pestaña **Dreams** del Gateway muestra: -- estado actual de habilitación de Sueños -- estado por fase y presencia del barrido administrado -- recuentos de corto plazo, largo plazo y promociones de hoy +- estado actual de habilitación de dreaming +- 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` @@ -200,5 +215,5 @@ Cuando está habilitada, la pestaña **Dreams** del Gateway muestra: - [Memory](/es/concepts/memory) - [Memory Search](/es/concepts/memory-search) -- [memory CLI](/cli/memory) +- [CLI de memory](/cli/memory) - [referencia de configuración de Memory](/es/reference/memory-config) diff --git a/docs/es/gateway/configuration-reference.md b/docs/es/gateway/configuration-reference.md index e0f7bcb49..95bfaede1 100644 --- a/docs/es/gateway/configuration-reference.md +++ b/docs/es/gateway/configuration-reference.md @@ -1,23 +1,23 @@ --- read_when: - - Necesitas la semántica exacta o los valores predeterminados 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 completa de cada clave de configuración de OpenClaw, valores predeterminados y ajustes de canales title: Referencia de configuración x-i18n: - generated_at: "2026-04-06T03:13:10Z" + generated_at: "2026-04-06T05:17:44Z" model: gpt-5.4 provider: openai - source_hash: 6aa6b24b593f6f07118817afabea4cc7842aca6b7c5602b45f479b40c1685230 + source_hash: 6ae6c19666f65433361e1c8b100ae710448c8aa055a60c140241a8aea09b98a5 source_path: gateway/configuration-reference.md workflow: 15 --- # Referencia de configuración -Cada campo disponible en `~/.openclaw/openclaw.json`. Para una descripción general orientada a tareas, consulta [Configuración](/es/gateway/configuration). +Cada campo disponible en `~/.openclaw/openclaw.json`. Para una visión general orientada a tareas, consulta [Configuración](/es/gateway/configuration). -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. +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. --- @@ -27,30 +27,30 @@ Cada canal se inicia automáticamente cuando existe su sección de configuració ### Acceso a mensajes directos y grupos -Todos los canales admiten políticas de mensajes directos y políticas de grupo: +Todos los canales admiten políticas de MD y políticas de grupo: -| Política de mensaje directo | Comportamiento | -| --------------------------- | ------------------------------------------------------------- | -| `pairing` (predeterminada) | Los remitentes desconocidos reciben un código de vinculación de un solo uso; el propietario debe aprobarlo | -| `allowlist` | Solo remitentes en `allowFrom` (o en el almacén de permitidos vinculado) | -| `open` | Permitir todos los mensajes directos entrantes (requiere `allowFrom: ["*"]`) | -| `disabled` | Ignorar todos los mensajes directos entrantes | +| Política de MD | Comportamiento | +| ------------------- | ------------------------------------------------------------- | +| `pairing` (predeterminada) | Los remitentes desconocidos reciben un código de vinculación de un solo uso; el propietario debe aprobar | +| `allowlist` | Solo remitentes en `allowFrom` (o en el almacén de permitidos emparejados) | +| `open` | Permitir todos los MD entrantes (requiere `allowFrom: ["*"]`) | +| `disabled` | Ignorar todos los MD entrantes | -| Política de grupo | Comportamiento | -| ----------------------- | ------------------------------------------------------ | -| `allowlist` (predeterminada) | Solo grupos que coincidan con la lista de permitidos configurada | -| `open` | Omite las listas de permitidos de grupo (la restricción por mención sigue aplicándose) | -| `disabled` | Bloquea todos los mensajes de grupo/sala | +| Política de grupo | Comportamiento | +| --------------------- | ------------------------------------------------------ | +| `allowlist` (predeterminada) | Solo grupos que coincidan con la allowlist configurada | +| `open` | Omitir las allowlists de grupo (la exigencia de mención sigue aplicándose) | +| `disabled` | Bloquear todos los mensajes de grupo/sala | -`channels.defaults.groupPolicy` establece el valor predeterminado cuando `groupPolicy` de un proveedor no está definido. -Los códigos de vinculación caducan después de 1 hora. Las solicitudes pendientes de vinculación para mensajes directos 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 recurre 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 vinculación expiran después de 1 hora. Las solicitudes pendientes de vinculación de MD están limitadas a **3 por canal**. +Si falta por completo un bloque de proveedor (`channels.` ausente), la política de grupo en tiempo de ejecución vuelve a `allowlist` (fallo cerrado) con una advertencia al iniciar. -### Anulaciones de modelo por canal +### Sobrescrituras de modelo por canal -Usa `channels.modelByChannel` para fijar IDs de canal específicos a un modelo. Los valores aceptan `provider/model` o alias de modelo configurados. La asignación de canal se aplica cuando una sesión aún no tiene una anulación 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 sobrescritura de modelo (por ejemplo, establecida mediante `/model`). ```json5 { @@ -71,7 +71,7 @@ Usa `channels.modelByChannel` para fijar IDs de canal específicos a un modelo. } ``` -### Valores predeterminados de canales y heartbeat +### Valores predeterminados de canal y heartbeat Usa `channels.defaults` para compartir el comportamiento de política de grupo y heartbeat entre proveedores: @@ -91,11 +91,11 @@ Usa `channels.defaults` para compartir el comportamiento de política de grupo y } ``` -- `channels.defaults.groupPolicy`: política de grupo de reserva 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 de citas/hilos/historial), `allowlist` (solo incluye contexto de remitentes permitidos), `allowlist_quote` (igual que allowlist, pero conserva el contexto explícito de cita/respuesta). Anulación por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: incluye estados de canal saludables en la salida de heartbeat. -- `channels.defaults.heartbeat.showAlerts`: incluye estados degradados/con error en la salida de heartbeat. -- `channels.defaults.heartbeat.useIndicator`: representa la salida de heartbeat en estilo de indicador compacto. +- `channels.defaults.groupPolicy`: política de grupo de respaldo cuando `groupPolicy` a nivel de proveedor no está configurado. +- `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 en allowlist), `allowlist_quote` (igual que allowlist pero manteniendo el contexto explícito de cita/respuesta). Sobrescritura por canal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: incluir estados de canales saludables en la salida de heartbeat. +- `channels.defaults.heartbeat.showAlerts`: incluir estados degradados/con error en la salida de heartbeat. +- `channels.defaults.heartbeat.useIndicator`: mostrar salida de heartbeat compacta con estilo de indicador. ### WhatsApp @@ -110,7 +110,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, // marcas azules (false en modo self-chat) + sendReadReceipts: true, // doble marca azul (false en modo self-chat) groups: { "*": { requireMention: true }, }, @@ -132,7 +132,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` - + ```json5 { @@ -150,10 +150,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 anula esa selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. -- El directorio de autenticación heredado de una sola cuenta de Baileys se migra con `openclaw doctor` a `whatsapp/default`. -- Anulaciones por cuenta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Los comandos salientes usan por defecto la cuenta `default` si existe; en caso contrario, la primera ID de cuenta configurada (ordenada). +- `channels.whatsapp.defaultAccount` opcional sobrescribe esa selección predeterminada de cuenta si coincide con una ID de cuenta configurada. +- El directorio heredado de autenticación Baileys de una sola cuenta se migra mediante `openclaw doctor` a `whatsapp/default`. +- Sobrescrituras por cuenta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -171,24 +171,24 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Keep answers brief.", + systemPrompt: "Mantén las respuestas breves.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Stay on topic.", + systemPrompt: "Mantente en el tema.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Respaldo de Git" }, + { command: "generate", description: "Crear una imagen" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (predeterminado: off; actívalo explícitamente para evitar límites de frecuencia de edición de vista previa) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -211,13 +211,13 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- Token del bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo archivo normal; se rechazan symlinks), con `TELEGRAM_BOT_TOKEN` como reserva para la cuenta predeterminada. -- `channels.telegram.defaultAccount` opcional anula la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. -- En configuraciones de múltiples cuentas (2 o más IDs de cuenta), establece un valor predeterminado explícito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) para evitar el enrutamiento de reserva; `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 vínculos ACP persistentes para temas de foros (usa el formato canónico `chatId:topic:topicId` en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). -- Las vistas previas de stream de Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y de grupo). -- Política de reintentos: consulta [Política de reintentos](/es/concepts/retry). +- 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 de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- 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 es inválido. +- `configWrites: false` bloquea escrituras de configuración iniciadas desde Telegram (migraciones de ID de supergrupo, `/config set|unset`). +- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran enlaces ACP persistentes para temas de foros (usa el formato canónico `chatId:topic:topicId` en `match.peer.id`). La semántica de campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- Las vistas previas de streaming de Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y de grupo). +- Política de reintento: consulta [Política de reintento](/es/concepts/retry). ### Discord @@ -264,7 +264,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Solo respuestas breves.", }, }, }, @@ -272,7 +272,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (progress se mapea a partial en Discord) maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // activación opcional para sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -319,36 +319,36 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- Token: `channels.discord.token`, con `DISCORD_BOT_TOKEN` como reserva para la cuenta predeterminada. -- Las llamadas salientes directas que proporcionan un `token` explícito de Discord usan ese token para la llamada; la configuración de reintentos/política de cuenta sigue viniendo de la cuenta seleccionada en la snapshot activa del entorno de ejecución. -- `channels.discord.defaultAccount` opcional anula la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. -- Usa `user:` (MD) o `channel:` (canal del servidor) para destinos de entrega; se rechazan los IDs numéricos sin prefijo. -- Los slugs de los servidores están en minúsculas y reemplazan los espacios por `-`; las claves de canal usan el nombre con slug (sin `#`). Prefiere los IDs de servidor. -- Los mensajes creados por bots se ignoran por defecto. `allowBots: true` los habilita; usa `allowBots: "mentions"` para aceptar solo mensajes de bots que mencionen al bot (los mensajes propios siguen filtrándose). -- `channels.discord.guilds..ignoreOtherMentions` (y las anulaciones por canal) descarta mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here). -- `maxLinesPerMessage` (predeterminado 17) divide mensajes altos incluso cuando tienen menos de 2000 caracteres. -- `channels.discord.threadBindings` controla el enrutamiento vinculado a hilos de Discord: - - `enabled`: anulación de Discord para funciones de sesión vinculadas a hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` y entrega/enrutamiento vinculados) - - `idleHours`: anulación de Discord para desenfoque automático por inactividad en horas (`0` desactiva) - - `maxAgeHours`: anulación de Discord para edad máxima estricta en horas (`0` desactiva) - - `spawnSubagentSessions`: interruptor opt-in para la creación/vinculación automática de hilos de `sessions_spawn({ thread: true })` -- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran vínculos ACP persistentes para canales e hilos (usa el ID del canal/hilo en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` establece el color de acento para los contenedores v2 de componentes de Discord. -- `channels.discord.voice` habilita conversaciones en canales de voz de Discord y anulaciones opcionales de auto-unión + TTS. +- Token: `channels.discord.token`, con `DISCORD_BOT_TOKEN` como respaldo para la cuenta predeterminada. +- Las llamadas salientes directas que proporcionan un `token` explícito de Discord usan ese token para la llamada; los ajustes de reintento/política de cuenta siguen viniendo de la cuenta seleccionada en la instantánea activa de tiempo de ejecución. +- `channels.discord.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- Usa `user:` (MD) 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 en slug (sin `#`). Prefiere IDs de guild. +- Los mensajes escritos por bots se ignoran de forma predeterminada. `allowBots: true` los habilita; usa `allowBots: "mentions"` para aceptar solo mensajes de bots que mencionen al bot (los mensajes propios siguen filtrándose). +- `channels.discord.guilds..ignoreOtherMentions` (y sus sobrescrituras de canal) descarta mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here). +- `maxLinesPerMessage` (predeterminado 17) divide mensajes altos incluso si tienen menos de 2000 caracteres. +- `channels.discord.threadBindings` controla el enrutamiento ligado a hilos de Discord: + - `enabled`: sobrescritura de Discord para funciones de sesión ligadas 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 opcional 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 campos se comparte en [Agentes ACP](/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 autoentrada + 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 también intenta recuperación de recepción de voz saliendo y volviendo a entrar en una sesión de voz después de repetidos fallos 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 (healthy => online, degraded => idle, exhausted => dnd) y permite anulaciones opcionales del texto de estado. -- `channels.discord.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia por nombre/tag mutable (modo de compatibilidad de emergencia). -- `channels.discord.execApprovals`: entrega nativa de aprobaciones de exec en Discord y autorización de aprobadores. - - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, 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. Recurre a `commands.ownerAllowFrom` cuando se omite. - - `agentFilter`: lista de permitidos opcional de IDs de agente. Omítela para reenviar aprobaciones para todos los agentes. +- OpenClaw además intenta recuperar la recepción de voz saliendo y volviendo a entrar en una sesión de voz tras repetidos fallos 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 del tiempo de ejecución al estado del bot (healthy => online, degraded => idle, exhausted => dnd) y permite sobrescrituras opcionales de 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 exec en Discord y autorización de aprobadores. + - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo auto, las aprobaciones exec se activan cuando se pueden resolver aprobadores 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`: allowlist opcional de IDs de agente. Omítelo para reenviar aprobaciones para todos los agentes. - `sessionFilter`: patrones opcionales de clave de sesión (subcadena o regex). - - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado) envía a MD de los aprobadores, `"channel"` envía al canal de origen, `"both"` envía a ambos. Cuando el destino incluye `"channel"`, los botones solo pueden usarlos aprobadores resueltos. - - `cleanupAfterResolve`: cuando es `true`, elimina los MD de aprobación tras aprobación, denegación o tiempo de espera. + - `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 usarlos los aprobadores resueltos. + - `cleanupAfterResolve`: cuando es `true`, elimina los MD de aprobación después de aprobar, rechazar o agotar el tiempo. -**Modos de notificación de reacción:** `off` (ninguna), `own` (mensajes del bot, predeterminado), `all` (todos los mensajes), `allowlist` (desde `guilds..users` en todos los mensajes). +**Modos de notificación de reacciones:** `off` (ninguno), `own` (mensajes del bot, predeterminado), `all` (todos los mensajes), `allowlist` (desde `guilds..users` en todos los mensajes). ### Google Chat @@ -380,10 +380,10 @@ 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`). -- Reservas por entorno: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- También se admite SecretRef para cuenta de servicio (`serviceAccountRef`). +- Variables de entorno de respaldo: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Usa `spaces/` o `users/` para destinos de entrega. -- `channels.googlechat.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia mutable de principal de correo electrónico (modo de compatibilidad de emergencia). +- `channels.googlechat.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia mutable de principal de correo electrónico (modo de compatibilidad break-glass). ### Slack @@ -405,7 +405,7 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Solo respuestas breves.", }, }, historyLimit: 50, @@ -433,8 +433,8 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) - nativeStreaming: true, // use Slack native streaming API when streaming=partial + streaming: "partial", // off | partial | block | progress (modo de vista previa) + nativeStreaming: true, // usar la API nativa de streaming de Slack cuando streaming=partial mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,34 +448,34 @@ WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia } ``` -- **Modo socket** requiere `botToken` y `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como reserva de entorno para la cuenta predeterminada). -- **Modo HTTP** requiere `botToken` más `signingSecret` (en la raíz o por cuenta). -- `botToken`, `appToken`, `signingSecret` y `userToken` aceptan cadenas de - texto sin formato u objetos SecretRef. -- Las snapshots de cuenta de Slack exponen campos de fuente/estado por credencial como +- 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 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/entorno 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 las escrituras de configuración iniciadas por Slack. -- `channels.slack.defaultAccount` opcional anula la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. -- `channels.slack.streaming` es la clave canónica del modo de stream. Los valores heredados `streamMode` y booleanos `streaming` se migran automáticamente. +- `configWrites: false` bloquea escrituras de configuración iniciadas desde Slack. +- `channels.slack.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- `channels.slack.streaming` es la clave canónica para el modo de streaming. Los valores heredados `streamMode` y booleanos `streaming` se migran automáticamente. - Usa `user:` (MD) o `channel:` para destinos de entrega. -**Modos de notificación de reacción:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). +**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). -**Aislamiento de sesión por hilo:** `thread.historyScope` es por hilo (predeterminado) o compartido en todo el canal. `thread.inheritParent` copia la transcripción del canal principal a hilos nuevos. +**Aislamiento de sesión por hilo:** `thread.historyScope` es por hilo (predeterminado) o compartido en todo el canal. `thread.inheritParent` copia la transcripción del canal padre a los nuevos hilos. -- `typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras se está ejecutando una respuesta, y luego la elimina al completarse. Usa un shortcode de emoji de Slack como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega nativa de aprobaciones de exec en 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"`). +- `typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras se ejecuta 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 exec en 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 miembro | +| emojiList | habilitado | Lista de emojis personalizados | ### Mattermost @@ -496,10 +496,10 @@ Mattermost se distribuye como plugin: `openclaw plugins install @openclaw/matter "team-channel-id": { requireMention: false }, }, commands: { - native: true, // opt-in + native: true, // activación opcional nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // URL explícita opcional para despliegues detrás de proxy inverso/públicos callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -509,23 +509,23 @@ Mattermost se distribuye como plugin: `openclaw plugins install @openclaw/matter } ``` -Modos de chat: `oncall` (responder con mención @, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que comienzan con el prefijo disparador). +Modos de chat: `oncall` (responder con mención @, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que empiezan con prefijo disparador). Cuando los comandos nativos de Mattermost están habilitados: - `commands.callbackPath` debe ser una ruta (por ejemplo `/api/channels/mattermost/command`), no una URL completa. -- `commands.callbackUrl` debe resolver al endpoint del gateway de OpenClaw y ser accesible desde el servidor de Mattermost. -- Los callbacks slash nativos se autentican con los tokens por comando devueltos - por Mattermost durante el registro del comando slash. Si el registro falla o no - se activa ningún comando, OpenClaw rechaza los callbacks con +- `commands.callbackUrl` debe resolverse al endpoint del gateway de OpenClaw y ser accesible desde el servidor de Mattermost. +- Los callbacks nativos de slash se autentican con los tokens por comando devueltos + por Mattermost durante el registro del slash command. Si el registro falla o no + se activan comandos, OpenClaw rechaza los callbacks con `Unauthorized: invalid command token.` - 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 URL completas. -- `channels.mattermost.configWrites`: permite o deniega escrituras de configuración iniciadas por Mattermost. -- `channels.mattermost.requireMention`: requiere `@mention` antes de responder en canales. -- `channels.mattermost.groups..requireMention`: anulación por canal de la restricción por mención (`"*"` para predeterminado). -- `channels.mattermost.defaultAccount` opcional anula la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. + Usa valores de host/dominio, no URLs completas. +- `channels.mattermost.configWrites`: permitir o denegar escrituras de configuración iniciadas desde Mattermost. +- `channels.mattermost.requireMention`: requerir `@mention` antes de responder en canales. +- `channels.mattermost.groups..requireMention`: sobrescritura por canal para exigencia de mención (`"*"` para el valor predeterminado). +- `channels.mattermost.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. ### Signal @@ -534,7 +534,7 @@ Cuando los comandos nativos de Mattermost están habilitados: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // enlace de cuenta opcional dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -546,11 +546,11 @@ Cuando los comandos nativos de Mattermost están habilitados: } ``` -**Modos de notificación de reacción:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). +**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). - `channels.signal.account`: fija el inicio del canal a una identidad de cuenta de Signal específica. -- `channels.signal.configWrites`: permite o deniega escrituras de configuración iniciadas por Signal. -- `channels.signal.defaultAccount` opcional anula la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. +- `channels.signal.configWrites`: permitir o denegar escrituras de configuración iniciadas desde Signal. +- `channels.signal.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. ### BlueBubbles @@ -562,21 +562,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 claves principales cubiertas aquí: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opcional anula 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 handle de BlueBubbles o una cadena de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- `channels.bluebubbles.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de BlueBubbles a sesiones ACP persistentes. Usa un handle o cadena de destino de BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). - La configuración completa del canal BlueBubbles está documentada en [BlueBubbles](/es/channels/bluebubbles). ### iMessage -OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puerto. +OpenClaw ejecuta `imsg rpc` (JSON-RPC sobre stdio). No requiere daemon ni puerto. ```json5 { @@ -600,17 +600,17 @@ OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puer } ``` -- `channels.imessage.defaultAccount` opcional anula la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado. +- `channels.imessage.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. -- Requiere Full Disk Access a la base de datos de Messages. +- Requiere acceso completo al disco para la base de datos de Mensajes. - Prefiere destinos `chat_id:`. Usa `imsg chats --limit 20` para listar chats. -- `cliPath` puede apuntar a un contenedor SSH; establece `remoteHost` (`host` o `user@host`) para obtener adjuntos por 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 de host del relay ya exista en `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: permite o deniega 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 handle normalizado o un destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- SCP usa verificación estricta de clave de host, así que asegúrate de que la clave del host de retransmisión ya exista en `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: permitir o denegar escrituras de configuración iniciadas desde iMessage. +- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de iMessage a sesiones ACP persistentes. Usa un handle normalizado o un destino explícito de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -621,7 +621,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix está respaldado por una extensión y se configura en `channels.matrix`. +Matrix está respaldado por extensiones y se configura en `channels.matrix`. ```json5 { @@ -652,23 +652,23 @@ Matrix está respaldado por una extensión y se configura en `channels.matrix`. ``` - La autenticación por token usa `accessToken`; la autenticación por contraseña usa `userId` + `password`. -- `channels.matrix.proxy` enruta el tráfico HTTP de Matrix a través de un proxy HTTP(S) explícito. Las cuentas con nombre pueden anularlo con `channels.matrix.accounts..proxy`. +- `channels.matrix.proxy` enruta el tráfico HTTP de Matrix a través de un proxy HTTP(S) explícito. Las cuentas con nombre pueden sobrescribirlo con `channels.matrix.accounts..proxy`. - `channels.matrix.allowPrivateNetwork` permite homeservers privados/internos. `proxy` y `allowPrivateNetwork` son controles independientes. -- `channels.matrix.defaultAccount` selecciona la cuenta preferida en configuraciones de múltiples cuentas. -- `channels.matrix.execApprovals`: entrega nativa de aprobaciones de exec en Matrix y autorización de aprobadores. - - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, las aprobaciones de exec se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. - - `approvers`: IDs de usuario de Matrix (por ejemplo `@owner:example.org`) autorizados para aprobar solicitudes de exec. - - `agentFilter`: lista de permitidos opcional de IDs de agente. Omítela para reenviar aprobaciones para todos los agentes. +- `channels.matrix.defaultAccount` selecciona la cuenta preferida en configuraciones de varias cuentas. +- `channels.matrix.execApprovals`: entrega nativa de aprobaciones exec en Matrix y autorización de aprobadores. + - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo auto, las aprobaciones exec se activan cuando se pueden resolver aprobadores desde `approvers` o `commands.ownerAllowFrom`. + - `approvers`: IDs de usuario de Matrix (por ejemplo `@owner:example.org`) autorizados para aprobar solicitudes exec. + - `agentFilter`: allowlist opcional de IDs de agente. Omítelo para reenviar aprobaciones para todos los agentes. - `sessionFilter`: patrones opcionales de clave de sesión (subcadena o regex). - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado), `"channel"` (sala de origen) o `"both"`. - - Anulaciones por cuenta: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` controla cómo se agrupan los MD de Matrix en sesiones: `per-user` (predeterminado) comparte por peer enrutado, mientras que `per-room` aísla cada sala de MD. -- Los sondeos de estado de Matrix y las búsquedas en directorios en vivo usan la misma política de proxy que el tráfico en tiempo de ejecución. -- La configuración completa de Matrix, las reglas de destino y los ejemplos de configuración están documentados en [Matrix](/es/channels/matrix). + - Sobrescrituras por cuenta: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` controla cómo se agrupan los MD de Matrix 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 activas en el directorio 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 instalación están documentados en [Matrix](/es/channels/matrix). ### Microsoft Teams -Microsoft Teams está respaldado por una extensión y se configura en `channels.msteams`. +Microsoft Teams está respaldado por extensiones y se configura en `channels.msteams`. ```json5 { @@ -676,19 +676,19 @@ Microsoft Teams está respaldado por una extensión y se configura en `channels. 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 claves principales cubiertas aquí: `channels.msteams`, `channels.msteams.configWrites`. -- La configuración completa de Teams (credenciales, webhook, política de MD/grupo, anulaciones por equipo/canal) está documentada en [Microsoft Teams](/es/channels/msteams). +- La configuración completa de Teams (credenciales, webhook, política de MD/grupo, sobrescrituras por equipo/canal) está documentada en [Microsoft Teams](/es/channels/msteams). ### IRC -IRC está respaldado por una extensión y se configura en `channels.irc`. +IRC está respaldado por extensiones y se configura en `channels.irc`. ```json5 { @@ -710,12 +710,12 @@ IRC está respaldado por una extensión y se configura en `channels.irc`. ``` - Rutas de claves principales cubiertas aquí: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opcional anula 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 permitidos/restricción por mención) está documentada en [IRC](/es/channels/irc). +- `channels.irc.defaultAccount` opcional sobrescribe la selección de cuenta predeterminada cuando coincide con una ID de cuenta configurada. +- La configuración completa del canal IRC (host/puerto/TLS/canales/allowlists/exigencia de mención) está documentada en [IRC](/es/channels/irc). -### Múltiples cuentas (todos los canales) +### Varias cuentas (todos los canales) -Ejecuta múltiples cuentas por canal (cada una con su propio `accountId`): +Ejecuta varias cuentas por canal (cada una con su propio `accountId`): ```json5 { @@ -723,11 +723,11 @@ Ejecuta múltiples cuentas por canal (cada una con su propio `accountId`): telegram: { accounts: { default: { - name: "Primary bot", + name: "Bot principal", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "Bot de alertas", botToken: "987654:XYZ...", }, }, @@ -737,27 +737,27 @@ Ejecuta múltiples cuentas por canal (cada una con su propio `accountId`): ``` - `default` se usa cuando se omite `accountId` (CLI + enrutamiento). -- Los tokens de entorno solo se aplican a la cuenta **default**. -- La configuración base del canal se aplica a todas las cuentas salvo que se anule por cuenta. -- Usa `bindings[].match.accountId` para enrutar cada cuenta a un agente diferente. -- Si agregas una cuenta no predeterminada mediante `openclaw channels add` (o durante la incorporación del canal) mientras aún estás en una configuración de canal de nivel superior de una sola cuenta, OpenClaw primero promociona los valores de una sola cuenta de nivel superior con ámbito de cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueven a `channels..accounts.default`; Matrix puede conservar un destino con nombre/predeterminado coincidente existente. -- Los vínculos existentes solo de canal (sin `accountId`) siguen coincidiendo con la cuenta predeterminada; los vínculos con ámbito de cuenta siguen siendo opcionales. -- `openclaw doctor --fix` también repara formas mixtas moviendo los valores de una sola cuenta de nivel superior con ámbito de cuenta a la cuenta promocionada elegida para ese canal. La mayoría de los canales usan `accounts.default`; Matrix puede conservar un destino con nombre/predeterminado coincidente existente. +- Los tokens por entorno solo se aplican a la cuenta **predeterminada**. +- Los ajustes base del canal se aplican a todas las cuentas salvo sobrescritura por cuenta. +- Usa `bindings[].match.accountId` para enrutar cada cuenta a un agente distinto. +- Si agregas una cuenta no predeterminada mediante `openclaw channels add` (o la incorporación del canal) cuando todavía usas una configuración de canal de una sola cuenta en nivel superior, OpenClaw primero promociona los valores de una sola cuenta con ámbito de cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueven a `channels..accounts.default`; Matrix puede conservar en cambio un destino nombrado/predeterminado existente que coincida. +- Los enlaces existentes solo de canal (sin `accountId`) siguen coincidiendo con la cuenta predeterminada; los enlaces con ámbito de cuenta siguen siendo opcionales. +- `openclaw doctor --fix` también repara formas mixtas moviendo valores de una sola cuenta con ámbito de cuenta de nivel superior a la cuenta promocionada elegida para ese canal. La mayoría de los canales usan `accounts.default`; Matrix puede conservar en cambio un destino nombrado/predeterminado existente que coincida. ### Otros canales de extensiones -Muchos canales de extensiones se configuran como `channels.` y se documentan en sus páginas dedicadas (por ejemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). +Muchos canales de extensiones se configuran como `channels.` y están documentados en sus páginas de canal dedicadas (por ejemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). Consulta el índice completo de canales: [Canales](/es/channels). -### Restricción por mención en chats grupales +### Exigencia de mención en chats grupales -Los mensajes de grupo requieren por defecto **mención obligatoria** (mención en metadatos o patrones regex seguros). Se aplica a chats grupales de WhatsApp, Telegram, Discord, Google Chat e iMessage. +Los mensajes de grupo requieren **mención** de forma predeterminada (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 self-chat de WhatsApp. +- **Menciones en metadatos**: @menciones nativas de la plataforma. Se ignoran en 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 restricción por mención se aplica solo cuando la detección es posible (menciones nativas o al menos un patrón). +- La exigencia de mención solo se aplica cuando la detección es posible (menciones nativas o al menos un patrón). ```json5 { @@ -770,9 +770,9 @@ Los mensajes de grupo requieren por defecto **mención obligatoria** (mención e } ``` -`messages.groupChat.historyLimit` establece el valor predeterminado global. Los canales pueden anularlo con `channels..historyLimit` (o por cuenta). Establece `0` para desactivarlo. +`messages.groupChat.historyLimit` establece el valor predeterminado global. Los canales pueden sobrescribirlo con `channels..historyLimit` (o por cuenta). Establece `0` para desactivarlo. -#### Límites de historial de mensajes directos +#### Límites de historial de MD ```json5 { @@ -787,13 +787,13 @@ Los mensajes de grupo requieren por defecto **mención obligatoria** (mención e } ``` -Resolución: anulación por MD → valor predeterminado del proveedor → sin límite (se conserva todo). +Resolución: sobrescritura por MD → predeterminado del proveedor → sin límite (se conserva todo). -Compatible 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 las 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, solo responde a patrones de texto): ```json5 { @@ -814,18 +814,18 @@ Incluye tu propio número en `allowFrom` para habilitar el modo self-chat (ignor } ``` -### Comandos (manejo de comandos en chat) +### Comandos (manejo de comandos de chat) ```json5 { commands: { - native: "auto", // register native commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // registrar comandos nativos cuando sea compatible + text: true, // analizar /commands en mensajes de chat + bash: false, // permitir ! (alias: /bash) bashForegroundMs: 2000, - config: false, // allow /config - debug: false, // allow /debug - restart: false, // allow /restart + gateway restart tool + config: false, // permitir /config + debug: false, // permitir /debug + restart: false, // permitir /restart + herramienta de reinicio del gateway allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -835,24 +835,24 @@ Incluye tu propio número en `allowFrom` para habilitar el modo self-chat (ignor } ``` - + - Los comandos de texto deben ser mensajes **independientes** con `/` inicial. -- `native: "auto"` activa los comandos nativos para Discord/Telegram y deja Slack desactivado. -- Anulación por canal: `channels.discord.commands.native` (bool o `"auto"`). `false` borra comandos registrados previamente. -- `channels.telegram.customCommands` agrega entradas adicionales al menú del bot de Telegram. +- `native: "auto"` activa comandos nativos para Discord/Telegram y deja Slack desactivado. +- Sobrescribir por canal: `channels.discord.commands.native` (bool o `"auto"`). `false` borra comandos registrados anteriormente. +- `channels.telegram.customCommands` agrega entradas extra al menú del bot de Telegram. - `bash: true` habilita `! ` para el shell del host. Requiere `tools.elevated.enabled` y que el remitente esté en `tools.elevated.allowFrom.`. -- `config: true` habilita `/config` (lee/escribe `openclaw.json`). Para clientes `chat.send` del gateway, las escrituras persistentes de `/config set|unset` también requieren `operator.admin`; `/config show` de solo lectura sigue disponible para clientes operadores normales con alcance de escritura. +- `config: true` habilita `/config` (lee/escribe `openclaw.json`). Para clientes `chat.send` del gateway, las escrituras persistentes `/config set|unset` también requieren `operator.admin`; el modo solo lectura `/config show` sigue disponible para clientes normales con permisos de escritura. - `channels..configWrites` controla las mutaciones de configuración por canal (predeterminado: true). -- Para canales de múltiples cuentas, `channels..accounts..configWrites` también controla las escrituras dirigidas a esa cuenta (por ejemplo `/allowlist --config --account ` o `/config set channels..accounts....`). -- `allowFrom` es por proveedor. Cuando se establece, es la **única** fuente de autorización (las listas de permitidos/vinculación del canal y `useAccessGroups` se ignoran). -- `useAccessGroups: false` permite que los comandos omitan las políticas de grupos de acceso cuando `allowFrom` no está definido. +- 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....`). +- `allowFrom` es por proveedor. Cuando se establece, es la **única** fuente de autorización (se ignoran las allowlists/emparejamiento del canal y `useAccessGroups`). +- `useAccessGroups: false` permite que los comandos omitan las políticas de grupos de acceso cuando `allowFrom` no está configurado. --- -## Valores predeterminados de agente +## Valores predeterminados del agente ### `agents.defaults.workspace` @@ -866,7 +866,7 @@ Predeterminado: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raíz opcional del repositorio mostrada en la línea Runtime del prompt del sistema. Si no se define, OpenClaw la detecta automáticamente recorriendo hacia arriba desde el espacio de trabajo. +Raíz opcional del repositorio mostrada en la línea Runtime del system prompt. Si no se establece, OpenClaw la detecta automáticamente subiendo desde el workspace. ```json5 { @@ -876,7 +876,7 @@ Raíz opcional del repositorio mostrada en la línea Runtime del prompt del sist ### `agents.defaults.skills` -Lista de permitidos predeterminada opcional de Skills para agentes que no establecen +Allowlist predeterminada opcional de Skills para agentes que no establecen `agents.list[].skills`. ```json5 @@ -884,23 +884,23 @@ 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 valores predeterminados + { id: "locked-down", skills: [] }, // sin Skills ], }, } ``` -- Omite `agents.defaults.skills` para Skills sin restricciones de forma predeterminada. +- Omite `agents.defaults.skills` para permitir Skills sin restricciones de forma predeterminada. - Omite `agents.list[].skills` para heredar los valores predeterminados. - Establece `agents.list[].skills: []` para no tener Skills. - Una lista no vacía en `agents.list[].skills` es el conjunto final para ese agente; - no se combina con los valores predeterminados. + no se fusiona con los valores predeterminados. ### `agents.defaults.skipBootstrap` -Desactiva la creación automática de archivos bootstrap del espacio de trabajo (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Desactiva la creación automática de archivos bootstrap del workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -908,9 +908,21 @@ Desactiva la creación automática de archivos bootstrap del espacio de trabajo } ``` +### `agents.defaults.contextInjection` + +Controla cuándo se inyectan los archivos bootstrap del workspace en el system prompt. Predeterminado: `"always"`. + +- `"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 +{ + agents: { defaults: { contextInjection: "continuation-skip" } }, +} +``` + ### `agents.defaults.bootstrapMaxChars` -Máximo de caracteres por archivo bootstrap del espacio de trabajo antes del truncamiento. Predeterminado: `20000`. +Máximo de caracteres por archivo bootstrap del workspace antes del truncamiento. Predeterminado: `20000`. ```json5 { @@ -920,7 +932,7 @@ Máximo de caracteres por archivo bootstrap del espacio de trabajo antes del tru ### `agents.defaults.bootstrapTotalMaxChars` -Máximo total de caracteres inyectados entre todos los archivos bootstrap del espacio de trabajo. Predeterminado: `150000`. +Máximo total de caracteres inyectados entre todos los archivos bootstrap del workspace. Predeterminado: `150000`. ```json5 { @@ -930,12 +942,12 @@ Máximo total de caracteres inyectados entre todos los archivos bootstrap del es ### `agents.defaults.bootstrapPromptTruncationWarning` -Controla el texto de advertencia visible para el agente cuando el contexto bootstrap se trunca. +Controla el texto de advertencia visible para el agente cuando se trunca el contexto bootstrap. Predeterminado: `"once"`. -- `"off"`: nunca inyecta texto de advertencia en el prompt del sistema. -- `"once"`: inyecta la advertencia una vez por firma de truncamiento única (recomendado). -- `"always"`: inyecta la advertencia en cada ejecución cuando existe truncamiento. +- `"off"`: nunca inyectar texto de advertencia en el system prompt. +- `"once"`: inyectar la advertencia una vez por firma única de truncamiento (recomendado). +- `"always"`: inyectar la advertencia en cada ejecución cuando exista truncamiento. ```json5 { @@ -945,10 +957,10 @@ Predeterminado: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Tamaño máximo en píxeles para el lado más largo de la imagen en bloques de imagen de transcripción/herramienta antes de las llamadas al proveedor. +Tamaño máximo en píxeles para el lado más largo de la imagen en bloques de imagen de transcript/tool antes de llamar 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 de pantalla. +Los valores más bajos suelen reducir el uso de tokens de visión y el tamaño de la carga útil de la solicitud. Los valores más altos conservan más detalle visual. ```json5 @@ -959,7 +971,7 @@ Los valores más altos conservan más detalle visual. ### `agents.defaults.userTimezone` -Zona horaria para el contexto del prompt del sistema (no para las marcas de tiempo de los mensajes). Recurre a la zona horaria del host. +Zona horaria para el contexto del system prompt (no para marcas de tiempo de mensajes). Usa la zona horaria del host como respaldo. ```json5 { @@ -969,7 +981,7 @@ Zona horaria para el contexto del prompt del sistema (no para las marcas de tiem ### `agents.defaults.timeFormat` -Formato de hora en el prompt del sistema. Predeterminado: `auto` (preferencia del SO). +Formato horario en el system prompt. Predeterminado: `auto` (preferencia del SO). ```json5 { @@ -1007,7 +1019,7 @@ Formato de hora en el prompt del sistema. Predeterminado: `auto` (preferencia de 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", @@ -1023,42 +1035,42 @@ Formato de hora en el prompt del sistema. Predeterminado: `auto` (preferencia de ``` - `model`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - La forma de cadena establece solo el modelo primario. - - La forma de objeto establece el 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 en orden. - `imageModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - La usa la ruta de la herramienta `image` como su configuración de modelo de visión. - - También se usa como enrutamiento de reserva cuando el modelo seleccionado/predeterminado no puede aceptar entrada de imagen. + - 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 }`). - - Se usa en la capacidad compartida de generación de imágenes y en cualquier futura superficie de herramienta/plugin que genere imágenes. - - Valores típicos: `google/gemini-3.1-flash-image-preview` para generación nativa de imágenes con Gemini, `fal/fal-ai/flux/dev` para fal o `openai/gpt-image-1` para OpenAI Images. - - Si seleccionas directamente un proveedor/modelo, 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 del proveedor respaldado por autenticación. Intenta primero con el proveedor predeterminado actual y luego con los demás proveedores de generación de imágenes registrados en orden de ID de proveedor. + - 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 con 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 o clave API 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` todavía puede inferir un valor predeterminado del proveedor respaldado por autenticación. Primero prueba el proveedor predeterminado actual, luego los proveedores de generación de imágenes registrados restantes en orden de ID de proveedor. - `musicGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Se usa en la capacidad compartida de generación de música y en la herramienta integrada `music_generate`. + - Lo usa la capacidad compartida de generación musical y la herramienta incorporada `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 del proveedor respaldado por autenticación. Intenta primero con el proveedor predeterminado actual y luego con los demás proveedores de generación de música registrados en orden de ID de proveedor. - - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/API key correspondiente del proveedor. + - Si se omite, `music_generate` todavía puede inferir un valor predeterminado del proveedor respaldado por autenticación. Primero prueba el proveedor predeterminado actual, luego los proveedores de generación musical registrados restantes en orden de ID de proveedor. + - Si seleccionas directamente un provider/model, configura también la autenticación o clave API correspondiente del proveedor. - `videoGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Se usa en la capacidad compartida de generación de video y en la herramienta integrada `video_generate`. + - Lo usa la capacidad compartida de generación de video y la herramienta incorporada `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 del proveedor respaldado por autenticación. Intenta primero con el proveedor predeterminado actual y luego con los demás proveedores de generación de video registrados en orden de ID de proveedor. - - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/API key correspondiente del proveedor. - - El proveedor integrado de generación de video Qwen actualmente 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`. + - Si se omite, `video_generate` todavía puede inferir un valor predeterminado del proveedor respaldado por autenticación. Primero prueba el proveedor predeterminado actual, luego los proveedores de generación de video registrados restantes en orden de ID de proveedor. + - Si seleccionas directamente un provider/model, configura también la autenticación o clave API correspondiente del proveedor. + - El proveedor agrupado de generación de video Qwen actualmente admite hasta 1 video de salida, 1 imagen de entrada, 4 videos de entrada, duración de 10 segundos y opciones a nivel de proveedor `size`, `aspectRatio`, `resolution`, `audio` y `watermark`. - `pdfModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Se usa para el enrutamiento del modelo de la herramienta `pdf`. - - Si se omite, la herramienta PDF recurre a `imageModel` y luego al modelo resuelto de la sesión/predeterminado. -- `pdfMaxBytesMb`: límite de tamaño PDF predeterminado para la herramienta `pdf` cuando no se pasa `maxBytesMb` en el momento de la llamada. -- `pdfMaxPages`: máximo de páginas considerado por defecto por el modo de extracción de reserva en la herramienta `pdf`. + - Lo usa la herramienta `pdf` para el enrutamiento del modelo. + - Si se omite, la herramienta PDF vuelve a `imageModel` y luego al modelo resuelto de sesión/predeterminado. +- `pdfMaxBytesMb`: límite predeterminado de tamaño PDF para la herramienta `pdf` cuando `maxBytesMb` no se pasa en la llamada. +- `pdfMaxPages`: número máximo predeterminado de páginas consideradas por el modo de respaldo de extracción en la herramienta `pdf`. - `verboseDefault`: nivel verbose predeterminado para agentes. Valores: `"off"`, `"on"`, `"full"`. Predeterminado: `"off"`. - `elevatedDefault`: nivel predeterminado de salida elevada para agentes. Valores: `"off"`, `"on"`, `"ask"`, `"full"`. Predeterminado: `"on"`. -- `model.primary`: formato `provider/model` (por ejemplo `openai/gpt-5.4`). Si omites el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese ID exacto de modelo y solo después recurre al proveedor predeterminado configurado (comportamiento heredado por compatibilidad, así que prefiere `provider/model` explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en vez de mostrar un valor predeterminado obsoleto de un proveedor eliminado. -- `models`: catálogo de modelos configurado y lista de permitidos para `/model`. Cada entrada puede incluir `alias` (atajo) y `params` (específicos del proveedor, por ejemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parámetros globales predeterminados del proveedor aplicados a todos los modelos. Se establece en `agents.defaults.params` (por ejemplo `{ cacheRetention: "long" }`). -- Precedencia de combinación de `params` (config): `agents.defaults.params` (base global) es anulada por `agents.defaults.models["provider/model"].params` (por modelo) y luego `agents.list[].params` (ID de agente coincidente) anula por clave. Consulta [Caché de prompts](/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 failbacks) guardan la forma canónica de objeto y conservan las listas de failbacks existentes cuando es posible. -- `maxConcurrent`: máximo de ejecuciones de agente en paralelo 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 exacto de modelo y solo entonces recurre al proveedor predeterminado configurado (comportamiento de compatibilidad obsoleto, así que prefiere `provider/model` explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw vuelve al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. +- `models`: el catálogo y allowlist configurados de modelos 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), y 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 mutan estos campos (por ejemplo `/models set`, `/models set-image` y comandos para agregar/quitar fallbacks) guardan la forma canónica de objeto 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. -**Alias abreviados integrados** (solo se aplican cuando el modelo está en `agents.defaults.models`): +**Atajos de alias incorporados** (solo se aplican cuando el modelo está en `agents.defaults.models`): | Alias | Modelo | | ------------------- | -------------------------------------- | @@ -1074,11 +1086,11 @@ Formato de hora en el prompt del sistema. Predeterminado: `auto` (preferencia de Tus alias configurados siempre tienen prioridad sobre los predeterminados. Los modelos Z.AI GLM-4.x habilitan automáticamente el modo thinking a menos que establezcas `--thinking off` o definas tú mismo `agents.defaults.models["zai/"].params.thinking`. -Los modelos Z.AI habilitan `tool_stream` de forma predeterminada para el streaming de llamadas a herramientas. Establece `agents.defaults.models["zai/"].params.tool_stream` en `false` para desactivarlo. -Los modelos Anthropic Claude 4.6 usan `adaptive` thinking por defecto cuando no se establece un nivel explícito de thinking. +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` por defecto para thinking cuando no se establece un nivel explícito de thinking. -- Se admiten sesiones cuando `sessionArg` está definido. -- Se admite pass-through de imágenes cuando `imageArg` acepta rutas de archivo. +- Se admiten sesiones cuando `sessionArg` está configurado. +- Se admite el paso directo de imágenes cuando `imageArg` acepta rutas de archivo. ### `agents.defaults.heartbeat` @@ -1089,16 +1101,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) + 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 | ... - prompt: "Read HEARTBEAT.md if it exists...", + directPolicy: "allow", // allow (predeterminado) | block + target: "none", // predeterminado: none | opciones: last | whatsapp | telegram | discord | ... + prompt: "Lee HEARTBEAT.md si existe...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1107,11 +1119,11 @@ 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 ejecuciones de heartbeat. -- `directPolicy`: política de entrega directa/MD. `allow` (predeterminado) permite la entrega a destino directo. `block` suprime la entrega a destino directo y emite `reason=dm-blocked`. -- `lightContext`: cuando es true, las ejecuciones de heartbeat usan un contexto bootstrap ligero y conservan solo `HEARTBEAT.md` de los archivos bootstrap del espacio de trabajo. -- `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. +- `every`: cadena de duración (ms/s/m/h). Predeterminado: `30m` (autenticación por clave API) o `1h` (autenticación OAuth). Establece `0m` para desactivar. +- `suppressToolErrorWarnings`: cuando es true, suprime las cargas de advertencia de errores de herramientas durante ejecuciones de heartbeat. +- `directPolicy`: política de entrega directa/MD. `allow` (predeterminada) permite entrega a destino directo. `block` la suprime 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 hace en una sesión nueva sin historial previo de conversación. Mismo patrón de aislamiento que cron `sessionTarget: "isolated"`. Reduce el costo por heartbeat de ~100K a ~2-5K tokens. - Por agente: 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. @@ -1126,15 +1138,15 @@ Ejecuciones periódicas de heartbeat. 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: "Conserva exactamente los ID de despliegue, ID de tickets y pares host:port.", // usado cuando identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] desactiva la reinyección + model: "openrouter/anthropic/claude-sonnet-4-6", // sobrescritura opcional del modelo solo para compactación + notifyUser: true, // enviar un aviso breve cuando comienza la compactación (predeterminado: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "La sesión se acerca a la compactación. Almacena ahora memorias duraderas.", + prompt: "Escribe cualquier nota duradera en memory/YYYY-MM-DD.md; responde con el token silencioso exacto NO_REPLY si no hay nada que guardar.", }, }, }, @@ -1143,13 +1155,13 @@ Ejecuciones periódicas de heartbeat. ``` - `mode`: `default` o `safeguard` (resumen por fragmentos para historiales largos). Consulta [Compactación](/es/concepts/compaction). -- `timeoutSeconds`: máximo de segundos 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 para volver a inyectar después de la compactación. Predeterminado: `["Session Startup", "Red Lines"]`; establece `[]` para desactivar la reinyección. Cuando no se define o se define explícitamente con ese par predeterminado, también se aceptan como reserva heredada los encabezados antiguos `Every Session`/`Safety`. -- `model`: anulación opcional de `provider/model-id` solo para el resumen de compactación. Úsala cuando la sesión principal deba mantener un modelo, pero los resúmenes de compactación deban ejecutarse con otro; cuando no se define, la compactación usa el modelo primario de la sesión. -- `notifyUser`: cuando es `true`, envía una breve notificación al usuario cuando comienza la compactación (por ejemplo, "Compacting context..."). Desactivado de forma predeterminada para mantener la compactación silenciosa. -- `memoryFlush`: turno agéntico silencioso antes de la auto-compactación para almacenar memorias duraderas. Se omite cuando el espacio de trabajo es de solo lectura. +- `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 orientación incorporada para conservar identificadores opacos durante el resumen de compactación. +- `identifierInstructions`: texto opcional personalizado de preservación de identificadores usado cuando `identifierPolicy=custom`. +- `postCompactionSections`: nombres opcionales de secciones H2/H3 de AGENTS.md para reinyectar 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 como respaldo heredado los encabezados antiguos `Every Session`/`Safety`. +- `model`: sobrescritura opcional `provider/model-id` solo para el resumen de compactación. Úsala 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 al usuario un aviso breve cuando comienza la compactación (por ejemplo, "Compacting context..."). Está desactivado de forma predeterminada para mantener la compactación silenciosa. +- `memoryFlush`: turno agéntico silencioso antes de la autocompactación para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura. ### `agents.defaults.contextPruning` @@ -1161,13 +1173,13 @@ 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, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Contenido antiguo del resultado de herramienta eliminado]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1177,25 +1189,25 @@ Poda **resultados antiguos de herramientas** del contexto en memoria antes de en -- `mode: "cache-ttl"` habilita los pasos 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 sobredimensionados de herramientas y luego borra por completo los resultados más antiguos si es necesario. +- `mode: "cache-ttl"` habilita pasadas de poda. +- `ttl` controla cada cuánto puede volver a ejecutarse la poda (después del último toque de caché). +- La poda primero recorta de forma suave los resultados sobredimensionados de herramientas y luego elimina por completo los resultados más antiguos si es necesario. -**Soft-trim** conserva el principio + el final e inserta `...` en el medio. +**Soft-trim** conserva el comienzo + el final e inserta `...` en medio. -**Hard-clear** reemplaza el resultado completo de la herramienta con el placeholder. +**Hard-clear** reemplaza todo el resultado de la herramienta con el marcador. Notas: -- Los bloques de imagen nunca se recortan ni se borran. +- Los bloques de imagen nunca se recortan ni se eliminan. - Las proporciones se basan en caracteres (aproximadas), no en recuentos exactos de tokens. - Si existen menos de `keepLastAssistants` mensajes del asistente, la poda se omite. -Consulta [Poda de sesión](/es/concepts/session-pruning) para detalles del comportamiento. +Consulta [Poda de sesión](/es/concepts/session-pruning) para detalles de comportamiento. -### Block streaming +### Streaming por bloques ```json5 { @@ -1205,17 +1217,17 @@ Consulta [Poda de sesión](/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. -- Anulaciones 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–2500 ms. Anulación por agente: `agents.list[].humanDelay`. +- Sobrescrituras por canal: `channels..blockStreamingCoalesce` (y variantes por cuenta). Signal/Slack/Discord/Google Chat usan por defecto `minChars: 1500`. +- `humanDelay`: pausa aleatoria entre respuestas por bloques. `natural` = 800–2500ms. Sobrescritura por agente: `agents.list[].humanDelay`. -Consulta [Streaming](/es/concepts/streaming) para ver el comportamiento + detalles de fragmentación. +Consulta [Streaming](/es/concepts/streaming) para detalles de comportamiento y fragmentación. ### Indicadores de escritura @@ -1230,8 +1242,8 @@ Consulta [Streaming](/es/concepts/streaming) para ver el comportamiento + detall } ``` -- Predeterminado: `instant` para chats directos/menciones, `message` para grupos sin mención. -- Anulaciones por sesión: `session.typingMode`, `session.typingIntervalSeconds`. +- Valores predeterminados: `instant` para chats directos/menciones, `message` para grupos sin mención. +- Sobrescrituras por sesión: `session.typingMode`, `session.typingIntervalSeconds`. Consulta [Indicadores de escritura](/es/concepts/typing-indicators). @@ -1239,7 +1251,7 @@ Consulta [Indicadores de escritura](/es/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing opcional para el agente embebido. Consulta [Sandboxing](/es/gateway/sandboxing) para la guía completa. +Sandboxing opcional para el agente integrado. Consulta [Sandboxing](/es/gateway/sandboxing) para la guía completa. ```json5 { @@ -1285,7 +1297,7 @@ Sandboxing opcional para el agente embebido. Consulta [Sandboxing](/es/gateway/s 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" }, @@ -1334,22 +1346,22 @@ Sandboxing opcional para el agente embebido. Consulta [Sandboxing](/es/gateway/s } ``` - + **Backend:** -- `docker`: entorno Docker local (predeterminado) -- `ssh`: entorno remoto genérico respaldado por SSH -- `openshell`: entorno OpenShell +- `docker`: tiempo de ejecución local de Docker (predeterminado) +- `ssh`: tiempo de ejecución remoto genérico respaldado por SSH +- `openshell`: tiempo de ejecución 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 tiempo de ejecución pasan a `plugins.entries.openshell.config`. **Configuración del backend SSH:** -- `target`: destino SSH con formato `user@host[:port]` +- `target`: destino SSH en formato `user@host[:port]` - `command`: comando del cliente SSH (predeterminado: `ssh`) -- `workspaceRoot`: raíz remota absoluta usada para espacios de trabajo por ámbito +- `workspaceRoot`: raíz remota absoluta usada para workspaces por ámbito - `identityFile` / `certificateFile` / `knownHostsFile`: archivos locales existentes pasados a OpenSSH - `identityData` / `certificateData` / `knownHostsData`: contenidos en línea o SecretRefs que OpenClaw materializa en archivos temporales en tiempo de ejecución - `strictHostKeyChecking` / `updateHostKeys`: controles de política de clave de host de OpenSSH @@ -1359,27 +1371,27 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del e - `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 snapshot activa del entorno de secretos antes de que comience la sesión sandbox +- Los valores `*Data` respaldados por SecretRef se resuelven desde la instantánea activa del tiempo de ejecución de secretos antes de que comience la sesión sandbox **Comportamiento del backend SSH:** -- inicializa el espacio de trabajo remoto una vez después de crearlo o recrearlo -- luego mantiene el espacio de trabajo SSH remoto como canónico -- enruta `exec`, herramientas de archivo y rutas de medios sobre SSH -- no sincroniza automáticamente los cambios remotos de vuelta al host +- inicializa el workspace remoto una vez después de crear o recrear +- luego mantiene como canónico el workspace SSH remoto +- enruta `exec`, las herramientas de archivos y las rutas de medios por SSH +- no sincroniza automáticamente de vuelta al host los cambios remotos - no admite contenedores de navegador sandbox -**Acceso al espacio de trabajo:** +**Acceso al workspace:** -- `none`: espacio de trabajo sandbox por ámbito en `~/.openclaw/sandboxes` -- `ro`: espacio de trabajo sandbox en `/workspace`, espacio de trabajo del agente montado en solo lectura en `/agent` -- `rw`: espacio de trabajo del agente montado en lectura/escritura en `/workspace` +- `none`: workspace sandbox por ámbito bajo `~/.openclaw/sandboxes` +- `ro`: workspace sandbox en `/workspace`, workspace del agente montado de solo lectura en `/agent` +- `rw`: workspace del agente montado en lectura/escritura en `/workspace` **Ámbito:** -- `session`: contenedor + espacio de trabajo por sesión -- `agent`: un contenedor + espacio de trabajo por agente (predeterminado) -- `shared`: contenedor y espacio de trabajo compartidos (sin aislamiento entre sesiones) +- `session`: contenedor + workspace por sesión +- `agent`: un contenedor + workspace por agente (predeterminado) +- `shared`: contenedor y workspace compartidos (sin aislamiento entre sesiones) **Configuración del plugin OpenShell:** @@ -1394,10 +1406,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 opcional de política OpenShell + providers: ["openai"], // opcional autoProviders: true, timeoutSeconds: 120, }, @@ -1409,30 +1421,30 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del e **Modo OpenShell:** -- `mirror`: inicializa el remoto desde el local antes de exec y sincroniza de vuelta después de exec; el espacio de trabajo local sigue siendo canónico -- `remote`: inicializa el remoto una vez cuando se crea el sandbox y luego mantiene el espacio de trabajo remoto como canónico +- `mirror`: inicializa el remoto desde el local antes de exec, sincroniza de vuelta después de exec; el workspace local sigue siendo canónico +- `remote`: inicializa el remoto una vez cuando se crea el sandbox y luego mantiene el workspace remoto como canónico -En modo `remote`, las ediciones locales del host realizadas fuera de OpenClaw no se sincronizan automáticamente en el sandbox después del paso de inicialización. -El transporte es SSH hacia el sandbox de OpenShell, pero el plugin controla el ciclo de vida del sandbox y la sincronización espejo opcional. +En modo `remote`, las ediciones locales del host hechas fuera de OpenClaw no se sincronizan automáticamente al sandbox después del paso inicial. +El transporte es SSH hacia el sandbox OpenShell, pero el plugin es responsable 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 por defecto a menos que establezcas -explícitamente `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (emergencia). +**Los contenedores usan por defecto `network: "none"`**: cámbialo a `"bridge"` (o una red bridge personalizada) si el agente necesita acceso saliente. +`"host"` está bloqueado. `"container:"` está bloqueado de forma predeterminada salvo que establezcas explícitamente +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Los adjuntos entrantes** se preparan en `media/inbound/*` dentro del espacio de trabajo activo. +**Los adjuntos entrantes** se preparan en `media/inbound/*` dentro del workspace activo. -**`docker.binds`** monta directorios adicionales del host; los mounts globales y por agente se combinan. +**`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 prompt del sistema. No requiere `browser.enabled` en `openclaw.json`. -El acceso de observador de 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). +**Navegador sandbox** (`sandbox.browser.enabled`): Chromium + CDP en un contenedor. Se inyecta la URL de noVNC 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` usa por defecto `openclaw-sandbox-browser` (red bridge dedicada). Establécelo en `bridge` solo cuando explícitamente quieras conectividad global bridge. -- `cdpSourceRange` opcionalmente restringe 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 del navegador sandbox. Cuando se establece (incluido `[]`), reemplaza `docker.binds` para el contenedor del navegador. -- Los valores predeterminados de inicio se definen en `scripts/sandbox-browser-entrypoint.sh` y están ajustados para hosts con contenedores: +- `network` usa por defecto `openclaw-sandbox-browser` (red bridge dedicada). Establécelo en `bridge` solo cuando quieras explícitamente conectividad global del 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 dentro del contenedor del navegador sandbox. Cuando se configura (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 con contenedores: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1451,28 +1463,29 @@ El acceso de observador de noVNC usa autenticación VNC por defecto y OpenClaw e - `--metrics-recording-only` - `--disable-extensions` (habilitado por defecto) - `--disable-3d-apis`, `--disable-software-rasterizer` y `--disable-gpu` están - habilitados por defecto y pueden desactivarse con + habilitados de forma predeterminada y pueden desactivarse con `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si el uso de WebGL/3D lo requiere. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` vuelve a habilitar 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. - - además de `--no-sandbox` y `--disable-setuid-sandbox` cuando `noSandbox` está habilitado. - - Los valores predeterminados son la línea base de la imagen del contenedor; usa una imagen de navegador personalizada con un entrypoint personalizado para cambiar los valores predeterminados del contenedor. + - más `--no-sandbox` y `--disable-setuid-sandbox` cuando `noSandbox` está habilitado. + - Los valores predeterminados son la línea base de la imagen del contenedor; usa una imagen de navegador personalizada con un + entrypoint personalizado para cambiar los valores predeterminados del contenedor. -El sandboxing del navegador y `sandbox.docker.binds` actualmente son solo para Docker. +El sandboxing del navegador y `sandbox.docker.binds` actualmente solo están disponibles para Docker. Construir imágenes: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # imagen principal del sandbox +scripts/sandbox-browser-setup.sh # imagen opcional del navegador ``` -### `agents.list` (anulaciones por agente) +### `agents.list` (sobrescrituras por agente) ```json5 { @@ -1481,18 +1494,18 @@ scripts/sandbox-browser-setup.sh # optional browser image { id: "main", default: true, - name: "Main Agent", + name: "Agente principal", 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", // sobrescritura por agente del nivel de thinking + reasoningDefault: "on", // sobrescritura por agente de la visibilidad de reasoning + fastModeDefault: false, // sobrescritura por agente del modo rápido + params: { cacheRetention: "none" }, // sobrescribe por clave los params de defaults.models coincidentes + skills: ["docs-search"], // reemplaza agents.defaults.skills cuando está configurado identity: { name: "Samantha", - theme: "helpful sloth", + theme: "perezoso servicial", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1520,24 +1533,24 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: ID de agente estable (obligatorio). -- `default`: cuando se establecen varios, gana el primero (se registra una advertencia). Si no hay ninguno, la primera entrada de la lista es la predeterminada. -- `model`: la forma de cadena anula solo `primary`; la forma de objeto `{ primary, fallbacks }` anula ambos (`[]` desactiva los fallbacks globales). Los trabajos cron que solo anulan `primary` aún heredan los fallbacks predeterminados a menos que establezcas `fallbacks: []`. -- `params`: parámetros de stream por agente combinados sobre la entrada del modelo seleccionado en `agents.defaults.models`. Úsalo para anulaciones 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 combinarse, y `[]` significa sin Skills. -- `thinkingDefault`: nivel thinking predeterminado opcional por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Anula `agents.defaults.thinkingDefault` para este agente cuando no se establece una anulación por mensaje o por sesión. -- `reasoningDefault`: visibilidad reasoning predeterminada opcional por agente (`on | off | stream`). Se aplica cuando no se establece una anulación reasoning por mensaje o por sesión. -- `fastModeDefault`: valor predeterminado opcional por agente para el modo rápido (`true | false`). Se aplica cuando no se establece una anulación de modo rápido por mensaje o por sesión. -- `runtime`: descriptor opcional del entorno por agente. Usa `type: "acp"` con valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar por defecto sesiones de arnés ACP. -- `identity.avatar`: ruta relativa al espacio de trabajo, 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 de 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` (fuerza selección explícita de perfil; predeterminado: false). +- `id`: ID estable de agente (obligatorio). +- `default`: cuando hay varios, gana el primero (se registra una advertencia). Si no hay 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 stream por agente fusionados sobre la entrada de modelo seleccionada 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`: allowlist opcional de Skills por agente. Si se omite, el agente hereda `agents.defaults.skills` cuando está configurado; una lista explícita reemplaza los valores predeterminados en lugar de fusionarse, y `[]` significa sin Skills. +- `thinkingDefault`: nivel predeterminado opcional de thinking por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Sobrescribe `agents.defaults.thinkingDefault` para este agente cuando no hay sobrescritura por mensaje o sesión. +- `reasoningDefault`: visibilidad predeterminada opcional de reasoning por agente (`on | off | stream`). Se aplica cuando no hay sobrescritura de reasoning por mensaje o sesión. +- `fastModeDefault`: valor predeterminado opcional por agente para el modo rápido (`true | false`). Se aplica cuando no hay sobrescritura del modo rápido por mensaje o sesión. +- `runtime`: descriptor opcional del tiempo de ejecución por agente. Usa `type: "acp"` con valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar por defecto sesiones del arnés ACP. +- `identity.avatar`: ruta relativa al workspace, URL `http(s)` o URI `data:`. +- `identity` deriva valores predeterminados: `ackReaction` a partir de `emoji`, `mentionPatterns` a partir de `name`/`emoji`. +- `subagents.allowAgents`: allowlist de IDs de agente para `sessions_spawn` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- Guardia 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 a `sessions_spawn` que omiten `agentId` (obliga a una selección explícita del perfil; predeterminado: false). --- -## Enrutamiento multiagente +## Enrutamiento multagente Ejecuta varios agentes aislados dentro de un mismo Gateway. Consulta [Multi-Agent](/es/concepts/multi-agent). @@ -1558,25 +1571,25 @@ Ejecuta varios agentes aislados dentro de un mismo Gateway. Consulta [Multi-Agen ### Campos de coincidencia de bindings -- `type` (opcional): `route` para enrutamiento normal (si falta, type usa route), `acp` para vínculos persistentes de conversación ACP. +- `type` (opcional): `route` para enrutamiento normal (si falta el tipo, el valor predeterminado es route), `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íficos del canal) +- `match.guildId` / `match.teamId` (opcional; específico del canal) - `acp` (opcional; solo para entradas `type: "acp"`): `{ mode, label, cwd, backend }` -**Orden de coincidencia determinista:** +**Orden determinista de coincidencia:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (exacta, sin peer/guild/team) -5. `match.accountId: "*"` (en todo el canal) +4. `match.accountId` (exacto, sin peer/guild/team) +5. `match.accountId: "*"` (para todo el canal) 6. Agente predeterminado Dentro de cada nivel, gana la primera entrada coincidente de `bindings`. -Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden de niveles de route binding anterior. +Para las entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden de niveles de route binding anterior. ### Perfiles de acceso por agente @@ -1598,7 +1611,7 @@ Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversac - + ```json5 { @@ -1673,7 +1686,7 @@ Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversac -Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tools) para ver detalles de precedencia. +Consulta [Sandbox y herramientas multagente](/es/tools/multi-agent-sandbox-tools) para detalles de precedencia. --- @@ -1699,22 +1712,22 @@ Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tool }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // omitir la bifurcación 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", // presupuesto rígido opcional + highWaterBytes: "400mb", // objetivo opcional de limpieza }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // desenfoque automático predeterminado por inactividad en horas (`0` lo desactiva) + maxAgeHours: 0, // antigüedad máxima estricta predeterminada en horas (`0` la desactiva) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // heredado (el tiempo de ejecución siempre usa "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1724,37 +1737,37 @@ Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tool } ``` - + -- **`scope`**: estrategia base de agrupación de sesión para contextos de chat grupal. - - `per-sender` (predeterminado): cada remitente obtiene una sesión aislada dentro del contexto del canal. - - `global`: todos los participantes en un contexto de canal comparten una sola sesión (úsalo solo cuando se pretende compartir contexto). +- **`scope`**: estrategia base de agrupación de sesiones para contextos de chat grupal. + - `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 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 de remitente entre canales. - - `per-channel-peer`: aísla por canal + remitente (recomendado para bandejas de entrada multiusuario). - - `per-account-channel-peer`: aísla por cuenta + canal + remitente (recomendado para múltiples cuentas). -- **`identityLinks`**: asigna IDs canónicos a peers con prefijo de proveedor para compartir sesión entre canales. -- **`reset`**: política principal de reinicio. `daily` reinicia a la hora local `atHour`; `idle` reinicia tras `idleMinutes`. Cuando ambos están configurados, gana el que expire primero. -- **`resetByType`**: anulaciones por tipo (`direct`, `group`, `thread`). Se acepta `dm` heredado como alias de `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` de la sesión principal permitido al crear una sesión de hilo bifurcada (predeterminado `100000`). + - `per-peer`: aislar por ID de remitente entre canales. + - `per-channel-peer`: aislar por canal + remitente (recomendado para bandejas de entrada multiusuario). + - `per-account-channel-peer`: aislar por cuenta + canal + remitente (recomendado para varias cuentas). +- **`identityLinks`**: asigna IDs canónicos a peers con prefijo de proveedor para compartir sesiones entre canales. +- **`reset`**: política principal de reinicio. `daily` reinicia a la hora local `atHour`; `idle` reinicia después de `idleMinutes`. Cuando ambos están configurados, gana el que expire primero. +- **`resetByType`**: sobrescrituras por tipo (`direct`, `group`, `thread`). Se acepta `dm` heredado como alias de `direct`. +- **`parentForkMaxTokens`**: máximo de `totalTokens` de la sesión padre permitido al crear una sesión de hilo bifurcado (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 ahora siempre usa `"main"` para el bucket principal de chat directo. -- **`agentToAgent.maxPingPongTurns`**: máximo de turnos de respuesta entre agentes durante intercambios agente a agente (entero, rango: `0`–`5`). `0` desactiva el encadenamiento ping-pong. -- **`sendPolicy`**: coincide por `channel`, `chatType` (`direct|group|channel`, con alias heredado `dm`), `keyPrefix` o `rawKeyPrefix`. La primera denegación gana. + - Establece `0` para desactivar esta protección y permitir siempre la bifurcación desde el padre. +- **`mainKey`**: campo heredado. El tiempo de ejecución ahora siempre usa `"main"` para el bucket principal de chat directo. +- **`agentToAgent.maxPingPongTurns`**: máximo de turnos de respuesta entre agentes durante intercambios agente a agente (entero, rango: `0`–`5`). `0` desactiva la cadena ping-pong. +- **`sendPolicy`**: coincide por `channel`, `chatType` (`direct|group|channel`, con alias heredado `dm`), `keyPrefix` o `rawKeyPrefix`. Gana la primera denegación. - **`maintenance`**: controles de limpieza + retención del almacén de sesiones. - `mode`: `warn` solo emite advertencias; `enforce` aplica la limpieza. - - `pruneAfter`: límite de antigüedad para entradas obsoletas (predeterminado `30d`). + - `pruneAfter`: corte 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.`. Por defecto usa `pruneAfter`; establece `false` para desactivarlo. - - `maxDiskBytes`: presupuesto opcional estricto de disco para el directorio de sesiones. En modo `warn` registra advertencias; en modo `enforce` elimina primero los artefactos/sesiones más antiguos. + - `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 después de 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 anularlo; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: desenfoque automático por inactividad predeterminado en horas (`0` desactiva; los proveedores pueden anularlo) - - `maxAgeHours`: edad máxima estricta predeterminada en horas (`0` desactiva; los proveedores pueden anularlo) +- **`threadBindings`**: valores predeterminados globales para funciones de sesión ligadas 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` la desactiva; los proveedores pueden sobrescribirla) @@ -1765,7 +1778,7 @@ Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tool ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // o "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1780,7 +1793,7 @@ Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tool }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 desactiva byChannel: { whatsapp: 5000, slack: 1500, @@ -1792,9 +1805,9 @@ Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tool ### Prefijo de respuesta -Anulaciones por canal/cuenta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Sobrescrituras 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}]`. +Resolución (gana el más específico): cuenta → canal → global. `""` lo desactiva y detiene la cascada. `"auto"` deriva `[{identity.name}]`. **Variables de plantilla:** @@ -1804,24 +1817,24 @@ Resolución (gana la más específica): cuenta → canal → global. `""` desact | `{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"`) | +| `{identity.name}` | Nombre de la identidad del agente | (igual que `"auto"`) | -Las variables no distinguen entre mayúsculas y minúsculas. `{think}` es un alias de `{thinkingLevel}`. +Las variables no distinguen mayúsculas y minúsculas. `{think}` es un alias de `{thinkingLevel}`. ### Reacción de acuse -- Por defecto usa `identity.emoji` del agente activo, o `"👀"` en su defecto. Establece `""` para desactivarla. -- Anulaciones por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Orden de resolución: cuenta → canal → `messages.ackReaction` → reserva de identidad. +- Usa por defecto `identity.emoji` del agente activo, o `"👀"` en su defecto. Establece `""` para desactivarla. +- Sobrescrituras por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Orden de resolución: cuenta → canal → `messages.ackReaction` → respaldo de identidad. - Ámbito: `group-mentions` (predeterminado), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: elimina el acuse después de responder en Slack, Discord y Telegram. +- `removeAckAfterReply`: elimina el acuse tras 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 se establece, mantiene las reacciones de estado habilitadas cuando las reacciones de acuse están activas. - En Telegram, establécelo explícitamente en `true` para habilitar las reacciones de estado del ciclo de vida. + En Slack y Discord, si no se configura explícitamente, las reacciones de estado siguen habilitadas cuando las reacciones de acuse están activas. + En Telegram, establécelo explícitamente en `true` para habilitar reacciones de estado del ciclo de vida. ### Debounce de entrada -Agrupa mensajes rápidos de solo texto del mismo remitente en un solo turno del agente. Los medios/adjuntos se vacían inmediatamente. Los comandos de control omiten el debounce. +Agrupa mensajes rápidos de solo texto del mismo remitente en un único turno del agente. Los medios/adjuntos fuerzan vaciado inmediato. Los comandos de control omiten el debounce. ### TTS (texto a voz) @@ -1864,18 +1877,18 @@ Agrupa mensajes rápidos de solo texto del mismo remitente en un solo turno del } ``` -- `auto` controla el auto-TTS. `/tts off|always|inbound|tagged` anula por sesión. -- `summaryModel` anula `agents.defaults.model.primary` para el resumen automático. -- `modelOverrides` está habilitado por defecto; `modelOverrides.allowProvider` usa por defecto `false` (opt-in). -- Las API keys recurren a `ELEVENLABS_API_KEY`/`XI_API_KEY` y `OPENAI_API_KEY`. -- `openai.baseUrl` anula el endpoint TTS de OpenAI. El orden de resolución es config, luego `OPENAI_TTS_BASE_URL` y luego `https://api.openai.com/v1`. -- Cuando `openai.baseUrl` apunta a un endpoint distinto de OpenAI, OpenClaw lo trata como un servidor TTS compatible con OpenAI y flexibiliza la validación de modelo/voz. +- `auto` controla el TTS automático. `/tts off|always|inbound|tagged` sobrescribe por sesión. +- `summaryModel` sobrescribe `agents.defaults.model.primary` para el resumen automático. +- `modelOverrides` está habilitado de forma predeterminada; `modelOverrides.allowProvider` usa `false` por defecto (activación opcional). +- Las claves API usan `ELEVENLABS_API_KEY`/`XI_API_KEY` y `OPENAI_API_KEY` como respaldo. +- `openai.baseUrl` sobrescribe el endpoint TTS de OpenAI. El orden de resolución es configuración, luego `OPENAI_TTS_BASE_URL` y luego `https://api.openai.com/v1`. +- 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 del modo Talk (macOS/iOS/Android). +Valores predeterminados para el modo Talk (macOS/iOS/Android). ```json5 { @@ -1899,13 +1912,13 @@ Valores predeterminados del modo Talk (macOS/iOS/Android). } ``` -- `talk.provider` debe coincidir con una clave en `talk.providers` cuando se configuran varios proveedores de Talk. +- `talk.provider` debe coincidir con una clave de `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.`. -- Los IDs de voz recurren a `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. -- `providers.*.apiKey` acepta cadenas de texto sin formato u objetos SecretRef. -- La reserva `ELEVENLABS_API_KEY` se aplica solo cuando no hay ninguna API key de Talk configurada. -- `providers.*.voiceAliases` permite que las directivas de Talk usen nombres amigables. -- `silenceTimeoutMs` controla cuánto espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no se establece, conserva la ventana de pausa predeterminada de la plataforma (`700 ms en macOS y Android, 900 ms en iOS`). +- Los IDs de voz usan `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID` como respaldo. +- `providers.*.apiKey` acepta cadenas de texto plano u objetos SecretRef. +- El respaldo `ELEVENLABS_API_KEY` solo se aplica cuando no hay ninguna clave API Talk configurada. +- `providers.*.voiceAliases` permite que las directivas Talk usen nombres amigables. +- `silenceTimeoutMs` controla cuánto espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no se configura, se mantiene la ventana de pausa predeterminada de la plataforma (`700 ms en macOS y Android, 900 ms en iOS`). --- @@ -1913,37 +1926,37 @@ Valores predeterminados del modo Talk (macOS/iOS/Android). ### Perfiles de herramientas -`tools.profile` establece una lista base de permitidos antes de `tools.allow`/`tools.deny`: +`tools.profile` establece una allowlist base antes de `tools.allow`/`tools.deny`: -La incorporación local configura por defecto las nuevas configuraciones locales con `tools.profile: "coding"` cuando no está definido (se conservan los perfiles explícitos existentes). +La incorporación local configura por defecto nuevas configuraciones locales con `tools.profile: "coding"` cuando no está establecido (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 restricción (igual que no definido) | +| `full` | Sin restricción (igual que sin configurar) | ### Grupos de herramientas | Grupo | Herramientas | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` se acepta como alias de `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Todas las herramientas integradas (excluye plugins de proveedor) | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` se acepta como alias de `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Todas las herramientas incorporadas (excluye plugins de proveedor) | ### `tools.allow` / `tools.deny` -Política global de permitir/denegar herramientas (deny gana). No distingue mayúsculas/minúsculas y admite comodines `*`. Se aplica incluso cuando el sandbox de Docker está desactivado. +Política global de permitir/denegar herramientas (deny gana). No distingue mayúsculas y minúsculas, admite comodines `*`. Se aplica incluso cuando el sandbox Docker está desactivado. ```json5 { @@ -1953,7 +1966,7 @@ Política global de permitir/denegar herramientas (deny gana). No distingue may ### `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 por proveedor → allow/deny. ```json5 { @@ -1969,7 +1982,7 @@ Restringe aún más las herramientas para proveedores o modelos específicos. Or ### `tools.elevated` -Controla el acceso elevado a exec fuera del sandbox: +Controla el acceso exec elevado fuera del sandbox: ```json5 { @@ -1985,9 +1998,9 @@ Controla el acceso elevado a exec fuera del sandbox: } ``` -- La anulación por agente (`agents.list[].tools.elevated`) solo puede restringir aún más. -- `/elevated on|off|ask|full` almacena estado por sesión; las directivas inline se aplican a un solo mensaje. -- El `exec` elevado omite el sandboxing y usa la ruta de escape configurada (`gateway` por defecto, o `node` cuando el destino de exec es `node`). +- La sobrescritura por agente (`agents.list[].tools.elevated`) solo puede restringir 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 sandbox y usa la ruta de escape configurada (`gateway` por defecto, o `node` cuando el objetivo exec es `node`). ### `tools.exec` @@ -2011,8 +2024,8 @@ Controla el acceso elevado a exec fuera del sandbox: ### `tools.loopDetection` -Las comprobaciones de seguridad de bucles de herramientas están **desactivadas de forma predeterminada**. Establece `enabled: true` para activar la detección. -La configuración puede definirse globalmente en `tools.loopDetection` y anularse por agente en `agents.list[].tools.loopDetection`. +Las verificaciones de seguridad de bucle de herramientas están **desactivadas de forma predeterminada**. Establece `enabled: true` para activar la detección. +Los ajustes pueden definirse globalmente en `tools.loopDetection` y sobrescribirse por agente en `agents.list[].tools.loopDetection`. ```json5 { @@ -2033,13 +2046,13 @@ La configuración puede definirse globalmente en `tools.loopDetection` y anulars } ``` -- `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 más alto de repetición para bloquear bucles críticos. -- `globalCircuitBreakerThreshold`: umbral de detención total para cualquier ejecución sin progreso. -- `detectors.genericRepeat`: advierte sobre llamadas repetidas con la misma herramienta/los mismos argumentos. -- `detectors.knownPollNoProgress`: advierte/bloquea herramientas de sondeo conocidas (`process.poll`, `command_status`, etc.). -- `detectors.pingPong`: advierte/bloquea patrones alternos en parejas sin progreso. +- `historySize`: máximo historial de llamadas de herramientas retenido para análisis de bucles. +- `warningThreshold`: umbral para advertencias de patrones repetitivos sin progreso. +- `criticalThreshold`: umbral superior para bloquear bucles críticos. +- `globalCircuitBreakerThreshold`: umbral de parada dura para cualquier ejecución sin progreso. +- `detectors.genericRepeat`: advierte sobre llamadas repetidas a la misma herramienta con los mismos argumentos. +- `detectors.knownPollNoProgress`: advierte/bloquea sobre herramientas de sondeo conocidas (`process.poll`, `command_status`, etc.). +- `detectors.pingPong`: advierte/bloquea sobre patrones alternados por pares sin progreso. - Si `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la validación falla. ### `tools.web` @@ -2050,14 +2063,14 @@ La configuración puede definirse globalmente en `tools.loopDetection` y anulars web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // o BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // opcional; omitir para detección automática maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2074,7 +2087,7 @@ La configuración puede definirse globalmente en `tools.loopDetection` y anulars ### `tools.media` -Configura la comprensión de medios entrantes (imagen/audio/video): +Configura el entendimiento de medios entrantes (imagen/audio/video): ```json5 { @@ -2082,7 +2095,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, // activación opcional: enviar música/video asíncronos terminados directamente al canal }, audio: { enabled: true, @@ -2111,27 +2124,27 @@ Configura la comprensión de medios entrantes (imagen/audio/video): **Entrada de proveedor** (`type: "provider"` u omitido): - `provider`: ID del proveedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) -- `model`: anulación del ID del modelo -- `profile` / `preferredProfile`: selección de perfil en `auth-profiles.json` +- `model`: sobrescritura del ID del modelo +- `profile` / `preferredProfile`: selección de perfil de `auth-profiles.json` -**Entrada de CLI** (`type: "cli"`): +**Entrada CLI** (`type: "cli"`): - `command`: ejecutable a ejecutar -- `args`: argumentos con plantilla (admite `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) +- `args`: argumentos con plantillas (admite `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) **Campos comunes:** - `capabilities`: lista opcional (`image`, `audio`, `video`). Valores predeterminados: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: anulaciones por entrada. -- Los fallos recurren a la siguiente entrada. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: sobrescrituras por entrada. +- Los fallos pasan a la siguiente entrada. -La autenticación del proveedor sigue el orden estándar: `auth-profiles.json` → vars de entorno → `models.providers.*.apiKey`. +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 asíncronas completadas de `music_generate` - y `video_generate` intentan primero la entrega directa al canal. Predeterminado: `false` - (ruta heredada de activación de sesión del solicitante/entrega del modelo). +- `asyncCompletion.directSend`: cuando es `true`, las tareas completadas de + `music_generate` y `video_generate` intentan primero la entrega directa al canal. Predeterminado: `false` + (ruta heredada de despertar sesión solicitante/entrega por modelo). @@ -2150,7 +2163,7 @@ La autenticación del proveedor sigue el orden estándar: `auth-profiles.json` ### `tools.sessions` -Controla a qué sesiones pueden dirigirse las herramientas de sesión (`sessions_list`, `sessions_history`, `sessions_send`). +Controla qué sesiones pueden ser objetivo de las herramientas de sesión (`sessions_list`, `sessions_history`, `sessions_send`). Predeterminado: `tree` (sesión actual + sesiones generadas por ella, como subagentes). @@ -2169,24 +2182,24 @@ Notas: - `self`: solo la clave de sesión actual. - `tree`: sesión actual + sesiones generadas por la sesión actual (subagentes). -- `agent`: cualquier sesión que pertenezca al ID del agente actual (puede incluir otros usuarios si ejecutas sesiones por remitente bajo el mismo ID de agente). -- `all`: cualquier sesión. El direccionamiento entre agentes aún requiere `tools.agentToAgent`. +- `agent`: cualquier sesión perteneciente al ID del agente actual (puede incluir otros usuarios si ejecutas sesiones por remitente bajo el mismo ID de agente). +- `all`: cualquier sesión. El direccionamiento entre agentes sigue requiriendo `tools.agentToAgent`. - Restricción 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 inline 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, // activación opcional: establece true para permitir adjuntos de archivo en línea + maxTotalBytes: 5242880, // 5 MB total 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" }, }, }, @@ -2195,22 +2208,22 @@ Controla el soporte de adjuntos inline para `sessions_spawn`. Notas: -- Los adjuntos solo son compatibles con `runtime: "subagent"`. El entorno ACP los rechaza. -- Los archivos se materializan en el espacio de trabajo hijo en `.openclaw/attachments//` con un `.manifest.json`. +- Los adjuntos solo son compatibles con `runtime: "subagent"`. El tiempo de ejecución 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 la transcripción. -- Las entradas base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección de tamaño previa a la decodificación. -- Los permisos de archivos son `0700` para directorios y `0600` para archivos. -- La limpieza sigue la política `cleanup`: `delete` siempre elimina adjuntos; `keep` los conserva solo cuando `retainOnSessionKeep: true`. +- Las entradas base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección de tamaño antes de descodificar. +- Los permisos de archivo son `0700` para directorios y `0600` para archivos. +- La limpieza sigue la política `cleanup`: `delete` siempre elimina los adjuntos; `keep` los conserva solo cuando `retainOnSessionKeep: true`. ### `tools.experimental` -Indicadores de herramientas integradas experimentales. Desactivados por defecto a menos que se aplique una regla de autoactivación específica del entorno. +Indicadores experimentales para herramientas incorporadas. Desactivado por defecto salvo que se aplique una regla automática específica del tiempo de ejecución. ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // habilitar update_plan experimental }, }, } @@ -2218,9 +2231,9 @@ Indicadores de herramientas integradas experimentales. Desactivados por defecto Notas: -- `planTool`: habilita la herramienta estructurada `update_plan` para el seguimiento de trabajos no triviales de varios pasos. -- Predeterminado: `false` para proveedores que no son OpenAI. Las ejecuciones de OpenAI y OpenAI Codex la habilitan automáticamente. -- Cuando está habilitada, el prompt del sistema también agrega guía de uso para que el modelo solo la use en trabajos sustanciales y mantenga como máximo un paso `in_progress`. +- `planTool`: habilita la herramienta estructurada `update_plan` para seguimiento de trabajo no trivial de varios pasos. +- Predeterminado: `false` para proveedores que no sean OpenAI. Las ejecuciones de OpenAI y OpenAI Codex la habilitan automáticamente. +- Cuando está habilitada, el system prompt también agrega orientación de uso para que el modelo solo la use en trabajos sustanciales y mantenga como máximo un paso `in_progress`. ### `agents.defaults.subagents` @@ -2241,20 +2254,20 @@ Notas: ``` - `model`: modelo predeterminado para subagentes generados. Si se omite, los subagentes heredan el modelo del llamador. -- `allowAgents`: lista de permitidos predeterminada de IDs de agente de destino para `sessions_spawn` cuando el agente solicitante no establece su propio `subagents.allowAgents` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- `allowAgents`: allowlist 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`: tiempo de espera predeterminado (segundos) para `sessions_spawn` cuando la llamada a la herramienta omite `runTimeoutSeconds`. `0` significa sin tiempo de espera. - Política de herramientas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Proveedores personalizados y base URLs +## Proveedores personalizados y URLs base -OpenClaw usa el catálogo de modelos integrado. Agrega proveedores personalizados mediante `models.providers` en la configuración o `~/.openclaw/agents//agent/models.json`. +OpenClaw usa el catálogo incorporado de modelos. Agrega proveedores personalizados mediante `models.providers` en la configuración o `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge (predeterminado) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2279,45 +2292,45 @@ OpenClaw usa el catálogo de modelos integrado. Agrega proveedores personalizado ``` - Usa `authHeader: true` + `headers` para necesidades de autenticación personalizadas. -- Anula 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 combinación para IDs de proveedor coincidentes: +- Sobrescribe 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 tienen prioridad solo cuando ese proveedor no está administrado por SecretRef en el contexto actual de config/auth-profile. - - Los valores `apiKey` del proveedor administrados por SecretRef se actualizan desde marcadores de origen (`ENV_VAR_NAME` para refs de entorno, `secretref-managed` para refs de archivo/exec) en lugar de persistir secretos resueltos. - - Los valores de encabezado del proveedor administrados por SecretRef se actualizan desde marcadores de origen (`secretref-env:ENV_VAR_NAME` para refs de entorno, `secretref-managed` para refs de archivo/exec). - - `apiKey`/`baseUrl` vacíos o ausentes 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 entorno 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 por origen: los marcadores se escriben desde la snapshot de configuración del origen activo (antes de la resolución), no desde valores secretos resueltos en tiempo de ejecución. + - Los valores no vacíos de `apiKey` del agente tienen prioridad solo cuando ese proveedor no está gestionado por SecretRef en el contexto actual de configuración/perfil de autenticación. + - Los valores `apiKey` de proveedores 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 cabecera 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` de la configuración. + - `contextWindow`/`maxTokens` del modelo coincidente usan el valor más alto entre la configuración explícita y los valores implícitos del catálogo. + - `contextTokens` del modelo coincidente conserva un límite explícito 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 completamente `models.json`. + - La persistencia de marcadores es autoritativa según la fuente: 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. ### Detalles de campos del proveedor -- `models.mode`: comportamiento del catálogo de proveedores (`merge` o `replace`). +- `models.mode`: comportamiento del catálogo del proveedor (`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 (prefiere SecretRef/sustitución por entorno). +- `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 sea necesario. -- `models.providers.*.baseUrl`: URL base de la API upstream. -- `models.providers.*.headers`: encabezados estáticos extra para enrutamiento proxy/inquilino. -- `models.providers.*.request`: anulaciones de transporte para solicitudes HTTP del proveedor de modelos. - - `request.headers`: encabezados adicionales (combinados con los valores predeterminados del proveedor). Los valores aceptan SecretRef. - - `request.auth`: anulación de estrategia de autenticación. Modos: `"provider-default"` (usar la autenticación integrada del proveedor), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` opcional). - - `request.proxy`: anulación de proxy HTTP. Modos: `"env-proxy"` (usar variables de entorno `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Ambos modos aceptan un subobjeto `tls` opcional. - - `request.tls`: anulación TLS para conexiones directas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceptan SecretRef), `serverName`, `insecureSkipVerify`. +- `models.providers.*.authHeader`: fuerza el transporte de credenciales en la cabecera `Authorization` cuando sea necesario. +- `models.providers.*.baseUrl`: URL base de la API ascendente. +- `models.providers.*.headers`: cabeceras estáticas extra para enrutamiento por proxy/inquilino. +- `models.providers.*.request`: sobrescrituras de transporte para solicitudes HTTP del proveedor de modelos. + - `request.headers`: cabeceras extra (fusionadas con las predeterminadas del proveedor). Los valores aceptan SecretRef. + - `request.auth`: sobrescritura de estrategia de autenticación. Modos: `"provider-default"` (usar la autenticación incorporada del proveedor), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, opcional `prefix`). + - `request.proxy`: sobrescritura de proxy HTTP. Modos: `"env-proxy"` (usar 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`. - `models.providers.*.models`: entradas explícitas del catálogo de modelos del proveedor. -- `models.providers.*.models.*.contextWindow`: metadatos nativos de la ventana de contexto del modelo. -- `models.providers.*.models.*.contextTokens`: límite opcional de contexto en tiempo de ejecución. Úsalo cuando quieras un presupuesto de contexto efectivo menor que el `contextWindow` nativo del modelo. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: sugerencia de compatibilidad opcional. Para `api: "openai-completions"` con `baseUrl` no nativa y no vacía (host distinto de `api.openai.com`), OpenClaw fuerza este valor a `false` en tiempo de ejecución. Una `baseUrl` vacía/omitida conserva el comportamiento predeterminado de OpenAI. -- `plugins.entries.amazon-bedrock.config.discovery`: raíz de configuración de auto-descubrimiento 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 refrescar el descubrimiento. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: ventana de contexto de reserva para modelos descubiertos. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de salida de reserva para modelos descubiertos. +- `models.providers.*.models.*.contextWindow`: metadatos de ventana de contexto nativa 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 opcional de compatibilidad. Para `api: "openai-completions"` con `baseUrl` no vacío y no nativo (host distinto de `api.openai.com`), OpenClaw fuerza esto a `false` en tiempo de ejecución. Un `baseUrl` vacío/omitido mantiene el comportamiento predeterminado de OpenAI. +- `plugins.entries.amazon-bedrock.config.discovery`: raíz de ajustes de autodetección de Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: activar/desactivar la detección implícita. +- `plugins.entries.amazon-bedrock.config.discovery.region`: región AWS para la detección. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional por ID de proveedor para detección dirigida. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de sondeo para la actualización de detección. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: ventana de contexto de respaldo para modelos detectados. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de salida de respaldo para modelos detectados. ### Ejemplos de proveedores @@ -2372,7 +2385,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`. +Establece `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa referencias `opencode/...` para el catálogo Zen o `opencode-go/...` para el catálogo Go. Atajo: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. @@ -2392,8 +2405,8 @@ 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`. - 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 anulación de base URL. +- Endpoint de código (predeterminado): `https://api.z.ai/api/coding/paas/v4` +- Para el endpoint general, define un proveedor personalizado con la sobrescritura de URL base. @@ -2435,8 +2448,8 @@ 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"` 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 basa eso en las capacidades del endpoint -en lugar de solo en el ID del proveedor integrado. +`openai-completions`, y OpenClaw ahora lo decide según las +capacidades del endpoint en lugar de solo por el ID integrado del proveedor. @@ -2493,7 +2506,7 @@ Compatible con Anthropic, proveedor integrado. Atajo: `openclaw onboard --auth-c } ``` -La base URL debe omitir `/v1` (el cliente Anthropic la añade). Atajo: `openclaw onboard --auth-choice synthetic-api-key`. +La URL base debe omitir `/v1` (el cliente Anthropic lo añade). Atajo: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2536,17 +2549,17 @@ La base URL debe omitir `/v1` (el cliente Anthropic la añade). Atajo: `openclaw Establece `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 de forma predeterminada. +El catálogo de modelos ahora usa por defecto solo M2.7. En la ruta de streaming compatible con Anthropic, OpenClaw desactiva el thinking de MiniMax -por defecto a menos que establezcas `thinking` explícitamente. `/fast on` o -`params.fastMode: true` reescribe `MiniMax-M2.7` a +de forma predeterminada a menos que establezcas tú mismo `thinking`. +`/fast on` o `params.fastMode: true` reescribe `MiniMax-M2.7` a `MiniMax-M2.7-highspeed`. -Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo local grande mediante la API Responses de LM Studio en hardware potente; mantén los modelos alojados combinados para failover. +Consulta [Modelos locales](/es/gateway/local-models). En resumen: ejecuta un modelo local grande mediante la API Responses de LM Studio en hardware serio; conserva los modelos alojados fusionados como respaldo. @@ -2567,7 +2580,7 @@ Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo }, 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 de texto plano env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2577,14 +2590,14 @@ Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo } ``` -- `allowBundled`: lista de permitidos opcional solo para Skills integradas (las Skills administradas/del espacio de trabajo no se ven afectadas). -- `load.extraDirs`: raíces compartidas extra de Skills (menor precedencia). +- `allowBundled`: allowlist opcional solo para Skills agrupadas (las Skills administradas/del workspace no se ven afectadas). +- `load.extraDirs`: raíces extra de Skills compartidas (precedencia más baja). - `install.preferBrew`: cuando es true, prefiere instaladores Homebrew cuando `brew` está disponible antes de recurrir a otros tipos de instalador. -- `install.nodeManager`: preferencia de instalador node para especificaciones `metadata.openclaw.install` +- `install.nodeManager`: preferencia del instalador de Node para especificaciones `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` desactiva una Skill incluso si está integrada/instalada. -- `entries..apiKey`: campo práctico de API key a nivel de Skill (cuando la Skill lo admite) para Skills que declaran una variable de entorno principal. +- `entries..enabled: false` desactiva una Skill incluso si está agrupada/instalada. +- `entries..apiKey`: campo de conveniencia para Skills que declaran una variable de entorno principal (cadena de texto plano u objeto SecretRef). --- @@ -2613,40 +2626,40 @@ Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo ``` - Se cargan desde `~/.openclaw/extensions`, `/.openclaw/extensions`, más `plugins.load.paths`. -- El descubrimiento acepta plugins nativos de OpenClaw más bundles compatibles de Codex y Claude, incluidos bundles Claude sin manifest con el diseño predeterminado. +- La detección acepta plugins nativos de OpenClaw más paquetes compatibles de Codex y Claude, incluidos paquetes Claude sin manifest y con disposición predeterminada. - **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 práctico de API key a nivel de plugin (cuando el plugin lo admite). +- `allow`: allowlist opcional (solo se cargan los plugins listados). `deny` tiene prioridad. +- `plugins.entries..apiKey`: campo de conveniencia de clave API a nivel de plugin (cuando el plugin lo admite). - `plugins.entries..env`: mapa de variables de entorno con ámbito de plugin. -- `plugins.entries..hooks.allowPromptInjection`: cuando es `false`, el núcleo bloquea `before_prompt_build` e ignora los campos que mutan el prompt de `before_agent_start` heredado, mientras conserva `modelOverride` y `providerOverride` heredados. Se aplica a hooks de plugins nativos y a directorios de hooks proporcionados por bundles compatibles. -- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en este plugin para solicitar anulaciones por ejecución de `provider` y `model` para ejecuciones de subagentes en segundo plano. -- `plugins.entries..subagent.allowedModels`: lista de permitidos opcional de destinos canónicos `provider/model` para anulaciones de subagente confiables. 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 que mutan prompts desde `before_agent_start` heredado, mientras preserva `modelOverride` y `providerOverride` heredados. Se aplica a hooks nativos de plugins y a directorios de hooks proporcionados por paquetes compatibles. +- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en este plugin para solicitar sobrescrituras de `provider` y `model` por ejecución para ejecuciones en segundo plano de subagentes. +- `plugins.entries..subagent.allowedModels`: allowlist opcional de destinos canónicos `provider/model` para sobrescrituras confiables de subagentes. Usa `"*"` solo si intencionalmente quieres permitir 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 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`. - - `baseUrl`: URL base de la API de Firecrawl (predeterminado: `https://api.firecrawl.dev`). - - `onlyMainContent`: extrae solo el contenido principal de las páginas (predeterminado: `true`). +- `plugins.entries.firecrawl.config.webFetch`: ajustes del proveedor de obtención web Firecrawl. + - `apiKey`: clave API de Firecrawl (acepta SecretRef). Usa como respaldo `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` heredado o la variable de entorno `FIRECRAWL_API_KEY`. + - `baseUrl`: URL base de la API Firecrawl (predeterminado: `https://api.firecrawl.dev`). + - `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`: tiempo de espera de la solicitud de scraping en segundos (predeterminado: `60`). -- `plugins.entries.xai.config.xSearch`: configuración de xAI X Search (búsqueda web de Grok). - - `enabled`: habilita el proveedor X Search. - - `model`: modelo Grok a usar para búsqueda (por ejemplo `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: configuración de dreaming de memoria (experimental). Consulta [Dreaming](/concepts/dreaming) para fases y umbrales. +- `plugins.entries.xai.config.xSearch`: ajustes de xAI X Search (búsqueda web de Grok). + - `enabled`: habilitar el proveedor X Search. + - `model`: modelo Grok que se usará para la búsqueda (p. ej. `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: ajustes de dreaming de memoria (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). - - la política de fases y los umbrales son detalles de implementación (no son claves de configuración orientadas al usuario). -- Los plugins habilitados del bundle Claude también pueden aportar valores predeterminados Pi integrados desde `settings.json`; OpenClaw los aplica como configuraciones sanitizadas del agente, no como parches de configuración OpenClaw sin procesar. -- `plugins.slots.memory`: elige el ID del plugin de memoria activo o `"none"` para desactivar plugins de memoria. -- `plugins.slots.contextEngine`: elige el ID del plugin de motor de contexto activo; el valor predeterminado es `"legacy"` a menos que instales y selecciones otro motor. + - la política de fases y los umbrales son detalles de implementación (no claves de configuración orientadas al usuario). +- Los plugins habilitados de paquetes Claude también pueden aportar valores predeterminados Pi integrados desde `settings.json`; OpenClaw los aplica como ajustes saneados del agente, no como parches directos de configuración de OpenClaw. +- `plugins.slots.memory`: elige el ID del plugin de memoria activo, o `"none"` para desactivar plugins de memoria. +- `plugins.slots.contextEngine`: elige el ID del plugin de motor de contexto activo; el predeterminado es `"legacy"` salvo que instales y selecciones otro motor. - `plugins.installs`: metadatos de instalación administrados por la 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 de la CLI antes que ediciones manuales. + - Trata `plugins.installs.*` como estado administrado; prefiere comandos CLI antes que ediciones manuales. Consulta [Plugins](/es/tools/plugin). --- -## Browser +## Navegador ```json5 { @@ -2655,8 +2668,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"], }, @@ -2683,9 +2696,9 @@ Consulta [Plugins](/es/tools/plugin). ``` - `evaluateEnabled: false` desactiva `act:evaluate` y `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` usa por defecto `true` cuando no está definido (modelo de red confiable). -- Establece `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` para una navegación estricta del navegador solo pública. -- En modo estricto, los endpoints de perfiles CDP remotos (`profiles.*.cdpUrl`) están sujetos al mismo bloqueo de red privada durante las comprobaciones de accesibilidad/descubrimiento. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` usa `true` por defecto cuando no está configurado (modelo de red de confianza). +- Establece `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` para navegación estricta del navegador solo a redes públicas. +- En modo estricto, los endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) están sujetos al mismo bloqueo de red privada durante 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). @@ -2695,13 +2708,15 @@ Consulta [Plugins](/es/tools/plugin). - 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` mantienen los límites actuales de la ruta Chrome MCP: - acciones basadas en snapshot/ref en lugar de selección por CSS, hooks de carga de un solo archivo, sin anulaciones de tiempo de espera de diálogo, sin `wait --load networkidle` y sin `responsebody`, exportación PDF, interceptación de descargas ni acciones por lotes. -- Los perfiles locales administrados `openclaw` asignan automáticamente `cdpPort` y `cdpUrl`; solo +- 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 subida + de un solo archivo, sin sobrescrituras de tiempo de espera para diálogos, sin `wait --load networkidle`, + ni `responsebody`, exportación PDF, interceptación de descargas o acciones por lotes. +- Los perfiles locales administrados `openclaw` autoasignan `cdpPort` y `cdpUrl`; solo establece `cdpUrl` explícitamente para CDP remoto. -- Orden de auto-detección: navegador predeterminado si es Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Orden de autodetección: navegador predeterminado si está basado en Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Servicio de control: solo loopback (puerto derivado de `gateway.port`, predeterminado `18791`). -- `extraArgs` agrega flags extra de inicio a Chromium local (por ejemplo +- `extraArgs` agrega flags extra de lanzamiento al inicio local de Chromium (por ejemplo `--disable-gpu`, tamaño de ventana o flags de depuración). --- @@ -2714,14 +2729,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 data }, }, } ``` -- `seamColor`: color de acento para la interfaz nativa de la app (tinte de la burbuja de Talk Mode, etc.). -- `assistant`: anulación de identidad para la Control UI. Recurre a la identidad del agente activo. +- `seamColor`: color de acento para el chrome de la UI de la app nativa (tono de la burbuja de Talk Mode, etc.). +- `assistant`: sobrescritura de identidad de la Control UI. Usa como respaldo la identidad del agente activo. --- @@ -2736,8 +2751,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, @@ -2754,8 +2769,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"], // requerido para Control UI no loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // modo peligroso de respaldo de origen por cabecera Host // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2766,12 +2781,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 para /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: { @@ -2786,43 +2801,36 @@ Consulta [Plugins](/es/tools/plugin). } ``` - + -- `mode`: `local` (ejecutar gateway) o `remote` (conectarse a un gateway remoto). El gateway se niega a iniciar salvo que sea `local`. -- `port`: único puerto multiplexado para WS + HTTP. Precedencia: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local` (ejecutar gateway) o `remote` (conectarse a un gateway remoto). Gateway se niega a iniciarse salvo que sea `local`. +- `port`: puerto multiplexado único para WS + HTTP. Precedencia: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (predeterminado), `lan` (`0.0.0.0`), `tailnet` (solo IP de Tailscale) o `custom`. -- **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`, así que el gateway es 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 por defecto. Los binds no loopback requieren autenticación del gateway. En la práctica eso significa un token/contraseña compartidos o un proxy inverso con reconocimiento de identidad usando `gateway.auth.mode: "trusted-proxy"`. El asistente de incorporación genera un token por defecto. -- Si se configuran tanto `gateway.auth.token` como `gateway.auth.password` (incluidos SecretRefs), establece `gateway.auth.mode` explícitamente en `token` o `password`. El inicio y los flujos de instalación/reparación del servicio fallan cuando ambos están configurados y el modo no está definido. -- `gateway.auth.mode: "none"`: modo explícito sin autenticación. Úsalo solo para configuraciones confiables locales con local loopback; esto intencionalmente no se ofrece en los prompts de incorporación. -- `gateway.auth.mode: "trusted-proxy"`: delega la autenticación a un proxy inverso con reconocimiento de identidad y confía en encabezados de identidad desde `gateway.trustedProxies` (consulta [Autenticación con proxy confiable](/es/gateway/trusted-proxy-auth)). Este modo espera una fuente de proxy **no loopback**; los proxies inversos loopback del mismo host no satisfacen la autenticación de trusted-proxy. -- `gateway.auth.allowTailscale`: cuando es `true`, los encabezados de identidad de Tailscale Serve pueden satisfacer la autenticación de Control UI/WebSocket (verificado mediante `tailscale whois`). Los endpoints de la API HTTP **no** usan esa autenticación por encabezado de Tailscale; siguen el modo normal de autenticación HTTP del gateway. Este flujo sin token asume que el host del gateway es confiable. Usa `true` por defecto cuando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitador opcional para autenticaciones fallidas. Se aplica por IP de cliente y por ámbito de autenticación (shared-secret y device-token se rastrean por separado). Los intentos bloqueados devuelven `429` + `Retry-After`. - - En la ruta asíncrona de Control UI por Tailscale Serve, los intentos fallidos para el mismo `{scope, clientIp}` se serializan antes de registrar el fallo. Por tanto, los intentos simultáneos incorrectos del mismo cliente pueden activar el limitador en la segunda solicitud en lugar de que ambas pasen como simples discrepancias. - - `gateway.auth.rateLimit.exemptLoopback` usa por defecto `true`; establece `false` cuando intencionalmente quieras limitar también el tráfico localhost (para configuraciones de prueba o despliegues proxy estrictos). -- Los intentos de autenticación WS desde origen de navegador siempre se limitan con la exención loopback desactivada (defensa en profundidad contra fuerza bruta localhost basada en navegador). -- En loopback, esos bloqueos desde origen de navegador se aíslan por valor `Origin` - normalizado, de modo que los fallos repetidos desde un origen localhost no bloquean automáticamente - otro origen diferente. +- **Alias heredados de bind**: usa valores de modo bind en `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), no alias de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Nota 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`, así 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 que no son loopback requieren autenticación del gateway. En la práctica, eso significa un token/contraseña compartidos o un proxy inverso con identidad gestionada con `gateway.auth.mode: "trusted-proxy"`. El asistente de incorporación genera un token por defecto. +- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados (incluidos SecretRefs), establece `gateway.auth.mode` explícitamente en `token` o `password`. El inicio y los flujos de instalación/reparación del servicio fallan cuando ambos están configurados y no hay modo definido. +- `gateway.auth.mode: "none"`: modo explícito sin autenticación. Úsalo solo para configuraciones locales loopback de confianza; esto intencionalmente no se ofrece en los prompts de incorporación. +- `gateway.auth.mode: "trusted-proxy"`: delega la autenticación a un proxy inverso con identidad gestionada y confía en cabeceras de identidad desde `gateway.trustedProxies` (consulta [Trusted Proxy Auth](/es/gateway/trusted-proxy-auth)). Este modo espera una fuente de proxy **que no sea loopback**; los proxies inversos loopback en el mismo host no satisfacen la autenticación trusted-proxy. +- `gateway.auth.allowTailscale`: cuando es `true`, las cabeceras de identidad de Tailscale Serve pueden satisfacer la autenticación de Control UI/WebSocket (verificada mediante `tailscale whois`). Los endpoints HTTP API **no** usan esa autenticación por cabecera de Tailscale; siguen el modo normal de autenticación HTTP del gateway. Este flujo sin token asume que el host del gateway es de confianza. Usa `true` por defecto cuando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitador opcional de autenticaciones fallidas. Se aplica por IP cliente y por ámbito de autenticación (los secretos compartidos y los tokens de dispositivo se rastrean por separado). Los intentos bloqueados devuelven `429` + `Retry-After`. + - En la ruta asíncrona de Tailscale Serve Control UI, los intentos fallidos del mismo `{scope, clientIp}` se serializan antes de escribir el fallo. Por tanto, intentos incorrectos concurrentes del mismo cliente pueden activar el limitador en la segunda solicitud en vez de dejar pasar ambas como simples discrepancias. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` por defecto; establece `false` cuando intencionalmente quieras limitar también el tráfico localhost (para entornos de prueba o despliegues estrictos con proxy). +- Los intentos de autenticación WS originados en navegador siempre se limitan con la exención de loopback desactivada (defensa en profundidad frente a ataques de fuerza bruta de localhost desde navegador). +- En loopback, esos bloqueos por origen de localhost se aíslan por valor `Origin` + normalizado, de modo que fallos repetidos de un origen localhost no bloqueen automáticamente + a otro origen distinto. - `tailscale.mode`: `serve` (solo tailnet, bind loopback) o `funnel` (público, requiere auth). -- `controlUi.allowedOrigins`: lista explícita de orígenes de navegador permitidos para conexiones WebSocket del Gateway. Es obligatoria cuando se esperan clientes de navegador desde orígenes no loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo peligroso que habilita el fallback de origen basado en encabezado Host para despliegues que dependen intencionalmente de esa política. +- `controlUi.allowedOrigins`: allowlist explícita de origen de navegador para conexiones WebSocket del Gateway. Requerida cuando se esperan clientes de navegador desde orígenes que no sean loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo peligroso que habilita el respaldo de origen por cabecera Host para despliegues que dependen intencionalmente de esa política. - `remote.transport`: `ssh` (predeterminado) o `direct` (ws/wss). Para `direct`, `remote.url` debe ser `ws://` o `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: anulación de emergencia del lado del cliente que permite `ws://` en texto claro hacia IPs confiables de red privada; el valor predeterminado sigue siendo solo loopback para texto claro. -- `gateway.remote.token` / `.password` son campos de credenciales del cliente remoto. No configuran por sí mismos la autenticación del gateway. -- `gateway.push.apns.relay.baseUrl`: URL base HTTPS para el relay APNs externo usado por compilaciones oficiales/TestFlight de iOS después de publicar registros respaldados por relay en el gateway. Esta URL debe coincidir con la URL del relay compilada en la build de iOS. -- `gateway.push.apns.relay.timeoutMs`: tiempo de espera en milisegundos para envíos gateway→relay. Predeterminado: `10000`. -- Los registros respaldados por relay se delegan a una identidad específica del gateway. La app iOS vinculada obtiene `gateway.identity.get`, incluye esa identidad en el registro del relay y reenvía al gateway una concesión de envío con ámbito de registro. Otro gateway no puede reutilizar ese registro almacenado. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: anulaciones temporales por entorno para la configuración del relay anterior. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: vía de escape solo para desarrollo para URLs HTTP loopback del relay. Las URLs de relay de producción deben seguir usando HTTPS. -- `gateway.channelHealthCheckMinutes`: intervalo del monitor de salud de canales en minutos. Establece `0` para desactivar globalmente los reinicios del monitor de salud. Predeterminado: `5`. -- `gateway.channelStaleEventThresholdMinutes`: umbral de socket obsoleto en minutos. Debe ser mayor o igual que `gateway.channelHealthCheckMinutes`. Predeterminado: `30`. -- `gateway.channelMaxRestartsPerHour`: máximo de reinicios del monitor de salud por canal/cuenta en una hora móvil. Predeterminado: `10`. -- `channels..healthMonitor.enabled`: exclusión opcional por canal de reinicios del monitor de salud manteniendo habilitado el monitor global. -- `channels..accounts..healthMonitor.enabled`: anulación por cuenta para canales de múltiples cuentas. Cuando se define, tiene prioridad sobre la anulación a nivel de canal. -- Las rutas de llamada del gateway local pueden usar `gateway.remote.*` como reserva solo cuando `gateway.auth.*` no está definido. -- Si `gateway.auth.token` / `gateway.auth.password` está configurado explícitamente mediante SecretRef y no se resuelve, la resolución falla cerrada (sin fallback remoto que lo oculte). -- `trustedProxies`: IPs de proxies inversos que terminan TLS o inyectan encabezados reenviados de cliente. Lista solo proxies que controles. Las entradas loopback siguen siendo válidas para configuraciones de detección local/proxy en el mismo host (por ejemplo Tailscale Serve o un proxy inverso local), pero **no** hacen que las solicitudes loopback sean elegibles para `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: cuando es `true`, el gateway acepta `X-Real-IP` si falta `X-Forwarded-For`. Predeterminado `false` para comportamiento fail-closed. -- `gateway.tools.deny`: nombres extra de herramientas bloqueados para HTTP `POST /tools/invoke` \ No newline at end of file +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: sobrescritura break-glass del lado cliente que permite `ws://` en texto plano hacia IP privadas de confianza; el valor predeterminado sigue siendo permitir texto plano solo en loopback. +- `gateway.remote.token` / `.password` son campos de credencial del cliente remoto. No configuran por sí mismos la autenticación del gateway. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base del relay APNs externo usado por compilaciones oficiales/TestFlight de iOS después de que publiquen registros respaldados por relay al gateway. Esta URL debe coincidir con la URL del relay compilada en la app iOS. +- `gateway.push.apns.relay.timeoutMs`: tiempo de espera en milisegundos para los envíos gateway→relay. Predeterminado: `10000`. +- Los registros respaldados por relay se delegan a una identidad específica del gateway. La app iOS emparejada obtiene `gateway.identity.get`, incluye esa identidad en el registro del relay y reenvía un permiso de envío con ámbito de registro al gateway. Otro gateway no puede reutilizar ese registro almacenado. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: sobrescrituras temporales por entorno para la configuración del relay anterior. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo para desarrollo para URLs de relay HTTP en loopback. Las URLs de relay de producción deberían seguir usando HTTPS. +- `gateway.channelHealthCheckMinutes`: intervalo en minutos del monitor de salud de canales. Establece `0` para desactivar globalmente los reinicios del monitor de salud. Predeterminado: `5`. +- `gateway.channelStaleEventThresholdMinutes`: umbral en minutos para sockets obsoletos. Mantenlo mayor o igual que `gateway.channelHealthCheckMinutes`. Predeterminado: `30`. +- `gateway.channelMaxRestartsPerHour`: máximo de reinicios por canal/cuenta en una hora móvil. Pred \ No newline at end of file diff --git a/docs/es/plugins/sdk-migration.md b/docs/es/plugins/sdk-migration.md index cef014825..a37a3a543 100644 --- a/docs/es/plugins/sdk-migration.md +++ b/docs/es/plugins/sdk-migration.md @@ -2,43 +2,43 @@ read_when: - Ves la advertencia OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ves la advertencia OPENCLAW_EXTENSION_API_DEPRECATED - - Estás actualizando un plugin a la arquitectura moderna de plugins de OpenClaw + - 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 Plugin SDK moderno -title: Migración del Plugin SDK +summary: Migra de la capa heredada de compatibilidad con versiones anteriores al moderno plugin SDK +title: Migración de Plugin SDK x-i18n: - generated_at: "2026-04-06T03:09:50Z" + generated_at: "2026-04-06T05:13:27Z" model: gpt-5.4 provider: openai - source_hash: b71ce69b30c3bb02da1b263b1d11dc3214deae5f6fc708515e23b5a1c7bb7c8f + source_hash: 94f12d1376edd8184714cc4dbea4a88fa8ed652f65e9365ede6176f3bf441b33 source_path: plugins/sdk-migration.md workflow: 15 --- -# Migración del Plugin SDK +# Migración de Plugin SDK -OpenClaw ha pasado de una amplia capa de compatibilidad hacia atrás 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 ayuda a migrarlo. +OpenClaw ha pasado de una amplia capa de compatibilidad con versiones anteriores 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 antiguo de plugins proporcionaba dos superficies muy abiertas que permitían a los plugins importar +El sistema de plugins anterior proporcionaba dos superficies muy abiertas que permitían a los plugins importar todo lo que necesitaban desde un único punto de entrada: - **`openclaw/plugin-sdk/compat`** — una sola importación que reexportaba decenas de - helpers. Se introdujo para mantener funcionando los plugins antiguos basados en hooks mientras se + utilidades. Se introdujo para mantener en funcionamiento los plugins antiguos basados en hooks 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 agentes integrados. + utilidades del lado del host, como el ejecutor de agentes embebido. -Ambas superficies ahora están **obsoletas**. Siguen funcionando en runtime, pero los nuevos -plugins 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 con versiones anteriores se eliminará en una futura versión principal. Los plugins que sigan importando desde estas superficies dejarán de funcionar cuando eso ocurra. @@ -46,37 +46,37 @@ versión principal las elimine. El enfoque anterior causaba problemas: -- **Inicio lento** — importar un helper cargaba docenas de módulos no relacionados -- **Dependencias circulares** — las reexportaciones amplias facilitaban crear ciclos de importación +- **Inicio lento** — importar una utilidad cargaba docenas de módulos no relacionados +- **Dependencias circulares** — las reexportaciones amplias hacían fácil crear ciclos de importación - **Superficie de API poco clara** — no había forma de saber qué exportaciones eran estables y cuáles eran internas -El Plugin SDK moderno corrige esto: cada ruta de importación (`openclaw/plugin-sdk/\`) -es un módulo pequeño y autocontenido con un propósito claro y un contrato documentado. +El moderno plugin SDK corrige esto: cada ruta de importación (`openclaw/plugin-sdk/\`) +es un módulo pequeño y autónomo con un propósito claro y un contrato documentado. -Las interfaces heredadas de conveniencia de proveedores para canales empaquetados también han desaparecido. Las importaciones +Las interfaces heredadas de conveniencia para providers de canales integrados también han desaparecido. Importaciones como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -las interfaces helper con marca de canal y -`openclaw/plugin-sdk/telegram-core` eran atajos privados del monorepo, no +interfaces de utilidades con marca de canal, y +`openclaw/plugin-sdk/telegram-core` eran atajos privados del mono-repo, no contratos estables para plugins. Usa en su lugar subrutas genéricas y específicas del SDK. Dentro del -workspace de plugins empaquetados, mantén los helpers propiedad del proveedor en el propio +espacio de trabajo de plugins integrados, mantén las utilidades propias del provider en el propio `api.ts` o `runtime-api.ts` de ese plugin. -Ejemplos actuales de proveedores empaquetados: +Ejemplos actuales de providers integrados: -- Anthropic mantiene los helpers de stream específicos de Claude en su propia interfaz `api.ts` / +- Anthropic mantiene las utilidades de flujo específicas de Claude en su propia interfaz `api.ts` / `contract-api.ts` -- OpenAI mantiene constructores de proveedores, helpers de modelo predeterminado y constructores de proveedores - en tiempo real en su propio `api.ts` -- OpenRouter mantiene el constructor de proveedor y los helpers de onboarding/configuración en su propio +- OpenAI mantiene los builders de provider, las utilidades de modelo predeterminado y los builders del provider + realtime en su propio `api.ts` +- OpenRouter mantiene el builder del provider y las utilidades de onboarding/configuración en su propio `api.ts` ## Cómo migrar - - Si tu plugin usa `openclaw/plugin-sdk/windows-spawn`, los wrappers de Windows - `.cmd`/`.bat` no resueltos ahora fallan de forma cerrada a menos que pases explícitamente + + Si tu plugin usa `openclaw/plugin-sdk/windows-spawn`, los wrappers no resueltos de Windows + `.cmd`/`.bat` ahora fallan de forma cerrada a menos que pases explícitamente `allowShellFallback: true`. ```typescript @@ -86,19 +86,19 @@ Ejemplos actuales de proveedores empaquetados: // Después const program = applyWindowsSpawnProgramPolicy({ candidate, - // Establece esto solo para llamadas de compatibilidad de confianza que - // aceptan intencionalmente el fallback mediado por shell. + // Establece esto solo para llamadores de compatibilidad confiables que + // aceptan intencionalmente la reserva mediada por shell. allowShellFallback: true, }); ``` - Si tu llamada no depende intencionalmente del fallback de shell, no establezcas - `allowShellFallback` y gestiona en su lugar el error lanzado. + Si tu llamador no depende intencionalmente de la reserva por shell, no establezcas + `allowShellFallback` y maneja en su lugar el error lanzado. - - Busca en tu plugin importaciones de cualquiera de las dos superficies obsoletas: + + Busca en tu plugin las importaciones desde cualquiera de las dos superficies obsoletas: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -107,11 +107,11 @@ Ejemplos actuales de proveedores empaquetados: - - Cada exportación de la superficie antigua se asigna a una ruta de importación moderna específica: + + Cada exportación de la superficie anterior corresponde a una ruta de importación moderna específica: ```typescript - // Antes (capa obsoleta de compatibilidad hacia atrás) + // Antes (capa obsoleta de compatibilidad con versiones anteriores) import { createChannelReplyPipeline, createPluginRuntimeStore, @@ -124,7 +124,7 @@ Ejemplos actuales de proveedores empaquetados: import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Para los helpers del lado del host, usa el runtime de plugin inyectado en lugar de importar + Para las utilidades del lado del host, usa el runtime del plugin inyectado en lugar de importar directamente: ```typescript @@ -136,9 +136,9 @@ Ejemplos actuales de proveedores empaquetados: 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 otras utilidades heredadas del puente: - | Importación antigua | Equivalente moderno | + | Importación anterior | Equivalente moderno | | --- | --- | | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` | | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` | @@ -146,11 +146,11 @@ 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.*` | + | utilidades del almacén de sesiones | `api.runtime.agent.session.*` | - + ```bash pnpm build pnpm test -- my-plugin/ @@ -160,168 +160,176 @@ Ejemplos actuales de proveedores empaquetados: ## Referencia de rutas de importación - + | Ruta de importación | Propósito | Exportaciones clave | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Helper canónico del punto de entrada del plugin | `definePluginEntry` | - | `plugin-sdk/core` | Reexportación heredada general para definiciones/constructores de entrada de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Utilidad canónica de entrada de plugin | `definePluginEntry` | + | `plugin-sdk/core` | Reexportación general heredada para definiciones/builders de entradas de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Exportación del esquema de configuración raíz | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper de punto 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` | Helpers compartidos del asistente de configuración | Prompts de lista permitida, constructores de estado de configuración | - | `plugin-sdk/setup-runtime` | Helpers de runtime para configuración | Adaptadores de parche de configuración seguros para importación, helpers de notas de búsqueda, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuración delegados | - | `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/puerta 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 cuentas | Helpers de búsqueda de cuenta + fallback predeterminado | - | `plugin-sdk/account-helpers` | Helpers específicos de cuenta | Helpers de lista de cuentas/acciones de cuenta | + | `plugin-sdk/provider-entry` | Utilidad de entrada para un solo provider | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Definiciones y builders específicos para entradas de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Utilidades compartidas del asistente de configuración | Prompts de lista de permitidos, builders de estado de configuración | + | `plugin-sdk/setup-runtime` | Utilidades de runtime para el tiempo de configuración | Adaptadores de parche de configuración seguros para importación, utilidades lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuración delegada | + | `plugin-sdk/setup-adapter-runtime` | Utilidades de adaptador de configuración | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Utilidades de herramientas de configuración | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Utilidades para múltiples cuentas | Utilidades de lista/configuración/puerta de acciones de cuenta | + | `plugin-sdk/account-id` | Utilidades de ID de cuenta | `DEFAULT_ACCOUNT_ID`, normalización de ID de cuenta | + | `plugin-sdk/account-resolution` | Utilidades de búsqueda de cuentas | Utilidades de búsqueda de cuentas + reserva predeterminada | + | `plugin-sdk/account-helpers` | Utilidades específicas de cuenta | Utilidades de lista de cuentas/acción 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 + typing | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | Cableado de prefijo de respuesta + 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 comandos, recorte de descripciones, validación de duplicados/conflictos | + | `plugin-sdk/channel-config-schema` | Builders de esquemas de configuración | Tipos de esquema de configuración de canal | + | `plugin-sdk/telegram-command-config` | Utilidades de configuración de comandos de Telegram | Normalización de nombres de comando, 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 cuentas | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpers de sobre entrante | Helpers compartidos de ruta + constructor de sobre | - | `plugin-sdk/inbound-reply-dispatch` | Helpers de respuesta entrante | Helpers compartidos de registrar y despachar | - | `plugin-sdk/messaging-targets` | Análisis de destinos de mensajería | Helpers de análisis/coincidencia de destinos | - | `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 salientes | - | `plugin-sdk/thread-bindings-runtime` | Helpers de enlaces de hilo | Ciclo de vida de enlaces de hilo y helpers de adaptador | - | `plugin-sdk/agent-media-payload` | Helpers heredados de payload de medios | Constructor de payload de medios de agente para estructuras heredadas de campos | + | `plugin-sdk/channel-lifecycle` | Seguimiento de estado de cuenta | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Utilidades de envoltura de entrada | Utilidades compartidas de ruta + builder de envoltura | + | `plugin-sdk/inbound-reply-dispatch` | Utilidades de respuesta entrante | Utilidades compartidas de registrar y despachar | + | `plugin-sdk/messaging-targets` | Análisis de destinos de mensajería | Utilidades de análisis/coincidencia de destinos | + | `plugin-sdk/outbound-media` | Utilidades de medios salientes | Carga compartida de medios salientes | + | `plugin-sdk/outbound-runtime` | Utilidades de runtime saliente | Utilidades de identidad saliente/delegado de envío | + | `plugin-sdk/thread-bindings-runtime` | Utilidades de vinculación de hilos | Utilidades de ciclo de vida y adaptador de vinculación de hilos | + | `plugin-sdk/agent-media-payload` | Utilidades heredadas de payload de medios | Builder de payload de medios de agente para diseños heredados de campos | | `plugin-sdk/channel-runtime` | Shim de compatibilidad obsoleto | Solo utilidades heredadas de runtime 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/copias de seguridad/instalación de plugins | - | `plugin-sdk/runtime-env` | Helpers específicos del entorno de runtime | Logger/entorno de runtime, helpers de timeout, reintento y backoff | - | `plugin-sdk/plugin-runtime` | Helpers compartidos de runtime de plugin | Helpers de plugin para comandos/hooks/http/interactivo | - | `plugin-sdk/hook-runtime` | Helpers del 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 procesos | 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 de gateway | Cliente del gateway y helpers de parche 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 ante fallback cuando la superficie de contrato empaquetada de Telegram no está disponible | - | `plugin-sdk/approval-runtime` | Helpers de prompts de aprobación | Payload de aprobación de exec/plugin, helpers de capacidad/perfil de aprobación, helpers de enrutamiento/runtime de aprobación nativa | - | `plugin-sdk/approval-auth-runtime` | Helpers de autenticación de aprobación | Resolución de aprobadores, autenticación de acciones del mismo chat | - | `plugin-sdk/approval-client-runtime` | Helpers de cliente de aprobación | Helpers de perfil/filtro de aprobación nativa de exec | - | `plugin-sdk/approval-delivery-runtime` | Helpers de entrega de aprobación | Adaptadores de capacidad/entrega de aprobación nativa | - | `plugin-sdk/approval-native-runtime` | Helpers de destino de aprobación | Helpers de destino/vinculación de cuenta de aprobación nativa | - | `plugin-sdk/approval-reply-runtime` | Helpers de respuesta de aprobación | Helpers de payload de respuesta de aprobación de exec/plugin | - | `plugin-sdk/security-runtime` | Helpers de seguridad | Helpers compartidos de confianza, bloqueo de DM, contenido externo y recopilación de secretos | - | `plugin-sdk/ssrf-policy` | Helpers de política SSRF | Helpers de lista permitida 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é acotada | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helpers de bloqueo de diagnóstico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Helpers de formato de errores | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de grafo de errores | - | `plugin-sdk/fetch-runtime` | Helpers de fetch/proxy envueltos | `resolveFetch`, helpers de proxy | - | `plugin-sdk/host-runtime` | Helpers de normalización de host | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Helpers de reintento | `RetryConfig`, `retryAsync`, ejecutores de política | - | `plugin-sdk/allow-from` | Formato de lista permitida | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Asignación de entradas de lista permitida | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Bloqueo de comandos y helpers de superficie de comandos | `resolveControlCommandGate`, helpers de autorización del remitente, helpers del registro de comandos | - | `plugin-sdk/secret-input` | Análisis de entradas secretas | Helpers de entrada secreta | - | `plugin-sdk/webhook-ingress` | Helpers de solicitudes webhook | Utilidades de destino de webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de protección del cuerpo de webhook | Helpers de lectura/límite del cuerpo de la solicitud | + | `plugin-sdk/runtime-store` | Almacenamiento persistente de plugins | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Utilidades amplias de runtime | Utilidades de runtime/logging/respaldo/instalación de plugins | + | `plugin-sdk/runtime-env` | Utilidades específicas de entorno de runtime | Entorno logger/runtime, utilidades de timeout, retry y backoff | + | `plugin-sdk/plugin-runtime` | Utilidades compartidas de runtime de plugins | Utilidades de comandos/hooks/http/interacción de plugins | + | `plugin-sdk/hook-runtime` | Utilidades de pipeline de hooks | Utilidades compartidas de pipeline de webhook/hook interno | + | `plugin-sdk/lazy-runtime` | Utilidades de runtime diferido | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Utilidades de procesos | Utilidades compartidas de ejecución | + | `plugin-sdk/cli-runtime` | Utilidades de runtime de CLI | Formato de comandos, esperas, utilidades de versión | + | `plugin-sdk/gateway-runtime` | Utilidades de gateway | Cliente de gateway y utilidades de parche de estado de canal | + | `plugin-sdk/config-runtime` | Utilidades de configuración | Utilidades de carga/escritura de configuración | + | `plugin-sdk/telegram-command-config` | Utilidades de comandos de Telegram | Utilidades de validación de comandos de Telegram con reserva estable cuando la superficie de contrato integrada de Telegram no está disponible | + | `plugin-sdk/approval-runtime` | Utilidades de prompts de aprobación | Payload de aprobación de ejecución/plugin, utilidades de capacidad/perfil de aprobación, utilidades nativas de enrutamiento/runtime de aprobación | + | `plugin-sdk/approval-auth-runtime` | Utilidades de autenticación de aprobación | Resolución de aprobador, autenticación de acciones en el mismo chat | + | `plugin-sdk/approval-client-runtime` | Utilidades de cliente de aprobación | Utilidades nativas de perfil/filtro de aprobación de ejecución | + | `plugin-sdk/approval-delivery-runtime` | Utilidades de entrega de aprobación | Adaptadores nativos de capacidad/entrega de aprobación | + | `plugin-sdk/approval-native-runtime` | Utilidades de destino de aprobación | Utilidades nativas de vinculación de destino/cuenta de aprobación | + | `plugin-sdk/approval-reply-runtime` | Utilidades de respuesta de aprobación | Utilidades de payload de respuesta de aprobación de ejecución/plugin | + | `plugin-sdk/security-runtime` | Utilidades de seguridad | Utilidades compartidas de confianza, control de DM, contenido externo y recolección de secretos | + | `plugin-sdk/ssrf-policy` | Utilidades de política SSRF | Utilidades de lista de permitidos de hosts y política de red privada | + | `plugin-sdk/ssrf-runtime` | Utilidades de runtime SSRF | Dispatcher fijado, fetch protegido, utilidades de política SSRF | + | `plugin-sdk/collection-runtime` | Utilidades de caché acotada | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Utilidades de control de diagnósticos | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Utilidades de formateo de errores | `formatUncaughtError`, `isApprovalNotFoundError`, utilidades de grafo de errores | + | `plugin-sdk/fetch-runtime` | Utilidades de fetch/proxy envuelto | `resolveFetch`, utilidades de proxy | + | `plugin-sdk/host-runtime` | Utilidades de normalización del host | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Utilidades de retry | `RetryConfig`, `retryAsync`, ejecutores de políticas | + | `plugin-sdk/allow-from` | Formato de lista de permitidos | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Mapeo de entradas de lista de permitidos | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Control de comandos y utilidades de superficie de comandos | `resolveControlCommandGate`, utilidades de autorización del remitente, utilidades de registro de comandos | + | `plugin-sdk/secret-input` | Análisis de entrada secreta | Utilidades de entrada secreta | + | `plugin-sdk/webhook-ingress` | Utilidades de solicitudes webhook | Utilidades de destino de webhook | + | `plugin-sdk/webhook-request-guards` | Utilidades de guardas del cuerpo webhook | Utilidades de lectura/límite del cuerpo de la 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 del proveedor | - | `plugin-sdk/reply-history` | Helpers del historial de respuestas | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-dispatch-runtime` | Utilidades específicas de despacho de respuesta | Utilidades de finalización + despacho de provider | + | `plugin-sdk/reply-history` | Utilidades 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 respuestas | Helpers de fragmentación de texto/markdown | - | `plugin-sdk/session-store-runtime` | Helpers del almacén de sesiones | Helpers de ruta del almacén + updated-at | - | `plugin-sdk/state-paths` | Helpers de rutas de estado | Helpers de directorio de estado y OAuth | - | `plugin-sdk/routing` | Helpers de enrutamiento/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 resumen de estado de canal/cuenta, valores predeterminados del estado de runtime, helpers de metadatos de incidencias | - | `plugin-sdk/target-resolver-runtime` | Helpers de resolución de destinos | Helpers compartidos de resolución de destinos | - | `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 tipo request | - | `plugin-sdk/run-command` | Helpers de comandos temporizados | Ejecutor de comandos temporizados con stdout/stderr normalizados | + | `plugin-sdk/reply-chunking` | Utilidades de fragmentación de respuestas | Utilidades de fragmentación de texto/markdown | + | `plugin-sdk/session-store-runtime` | Utilidades de almacén de sesiones | Utilidades de ruta del almacén + fecha de actualización | + | `plugin-sdk/state-paths` | Utilidades de rutas de estado | Utilidades de directorios de estado y OAuth | + | `plugin-sdk/routing` | Utilidades de enrutamiento/clave de sesión | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, utilidades de normalización de clave de sesión | + | `plugin-sdk/status-helpers` | Utilidades de estado de canal | Builders de resumen de estado de canal/cuenta, valores predeterminados de estado de runtime, utilidades de metadatos de incidencias | + | `plugin-sdk/target-resolver-runtime` | Utilidades de resolución de destinos | Utilidades compartidas de resolución de destinos | + | `plugin-sdk/string-normalization-runtime` | Utilidades de normalización de cadenas | Utilidades de normalización de slug/cadenas | + | `plugin-sdk/request-url` | Utilidades de URL de solicitud | Extraer URL de cadena de entradas similares a solicitudes | + | `plugin-sdk/run-command` | Utilidades 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 herramienta/CLI | - | `plugin-sdk/tool-send` | Extracción de envío de herramientas | Extrae campos canónicos de destino de envío de argumentos de herramienta | - | `plugin-sdk/temp-path` | Helpers de rutas temporales | Helpers compartidos de rutas temporales para descargas | - | `plugin-sdk/logging-core` | Helpers de logging | Logger del subsistema y helpers de redacción | - | `plugin-sdk/markdown-table-runtime` | Helpers de tablas Markdown | Helpers de modo de tabla Markdown | + | `plugin-sdk/tool-send` | Extracción de envío de herramientas | Extraer campos canónicos de destino de envío de argumentos de herramientas | + | `plugin-sdk/temp-path` | Utilidades de rutas temporales | Utilidades compartidas de rutas temporales de descarga | + | `plugin-sdk/logging-core` | Utilidades de logging | Logger de subsistema y utilidades de redacción | + | `plugin-sdk/markdown-table-runtime` | Utilidades de tablas Markdown | Utilidades de modo de tabla Markdown | | `plugin-sdk/reply-payload` | Tipos de respuesta de mensajes | Tipos de payload 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 específicos 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 autenticación de proveedores en runtime | Helpers de resolución de claves de API en runtime | - | `plugin-sdk/provider-auth-api-key` | Helpers de configuración de claves de API de proveedores | Helpers de onboarding/escritura de perfiles para claves de API | - | `plugin-sdk/provider-auth-result` | Helpers de resultados de autenticación de proveedores | Constructor estándar de resultados de autenticación OAuth | - | `plugin-sdk/provider-auth-login` | Helpers de inicio de sesión interactivo de proveedores | Helpers compartidos de inicio de sesión interactivo | - | `plugin-sdk/provider-env-vars` | Helpers de variables de entorno de proveedores | Helpers de búsqueda de variables de entorno de autenticación de proveedores | - | `plugin-sdk/provider-model-shared` | Helpers compartidos de modelos/replay de proveedores | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de replay, helpers de endpoint del proveedor y helpers de normalización de ID de modelo | - | `plugin-sdk/provider-catalog-shared` | Helpers compartidos de catálogo de proveedores | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Parches de onboarding de proveedores | Helpers de configuración de onboarding | - | `plugin-sdk/provider-http` | Helpers HTTP de proveedores | Helpers genéricos de HTTP/capacidades de endpoint de proveedores | - | `plugin-sdk/provider-web-fetch` | Helpers de proveedores de obtención web | Helpers de registro/caché de proveedores de obtención web | - | `plugin-sdk/provider-web-search` | Helpers de proveedores de búsqueda web | Helpers de registro/caché/configuración de proveedores de búsqueda web | - | `plugin-sdk/provider-tools` | Helpers de compatibilidad de herramientas/esquema de proveedores | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquemas Gemini y helpers de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Helpers de uso de proveedores | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` y otros helpers de uso de proveedores | - | `plugin-sdk/provider-stream` | Helpers de envoltorios de stream de proveedores | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorio de stream y helpers compartidos de envoltorio para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-setup` | Utilidades seleccionadas de configuración de provider local/autohospedado | Utilidades de detección/configuración de provider autohospedado | + | `plugin-sdk/self-hosted-provider-setup` | Utilidades específicas de configuración de provider autohospedado compatible con OpenAI | Las mismas utilidades de detección/configuración de provider autohospedado | + | `plugin-sdk/provider-auth-runtime` | Utilidades de autenticación de runtime de provider | Utilidades de resolución de API key en runtime | + | `plugin-sdk/provider-auth-api-key` | Utilidades de configuración de API key de provider | Utilidades de onboarding/escritura de perfil de API key | + | `plugin-sdk/provider-auth-result` | Utilidades de resultado de autenticación de provider | Builder estándar de resultado de autenticación OAuth | + | `plugin-sdk/provider-auth-login` | Utilidades de inicio de sesión interactivo de provider | Utilidades compartidas de inicio de sesión interactivo | + | `plugin-sdk/provider-env-vars` | Utilidades de variables de entorno de provider | Utilidades de búsqueda de variables de entorno de autenticación de provider | + | `plugin-sdk/provider-model-shared` | Utilidades compartidas de modelo/replay de provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders compartidos de política de replay, utilidades de endpoint de provider y utilidades de normalización de ID de modelo | + | `plugin-sdk/provider-catalog-shared` | Utilidades compartidas de catálogo de provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Parches de onboarding de provider | Utilidades de configuración de onboarding | + | `plugin-sdk/provider-http` | Utilidades HTTP de provider | Utilidades genéricas HTTP/capacidad de endpoint de provider | + | `plugin-sdk/provider-web-fetch` | Utilidades web-fetch de provider | Utilidades de registro/caché de provider web-fetch | + | `plugin-sdk/provider-web-search` | Utilidades web-search de provider | Utilidades de registro/caché/configuración de provider web-search | + | `plugin-sdk/provider-tools` | Utilidades de compatibilidad de herramientas/esquemas de provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza de esquemas Gemini + diagnósticos, y utilidades de compatibilidad de xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Utilidades de uso de provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` y otras utilidades de uso de provider | + | `plugin-sdk/provider-stream` | Utilidades wrapper de streams de provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream y utilidades wrapper compartidas de 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` | Helpers compartidos de medios | Helpers de fetch/transformación/almacenamiento de medios más constructores de payload de medios | - | `plugin-sdk/media-understanding` | Helpers de comprensión de medios | Tipos de proveedores de comprensión de medios más exportaciones helper orientadas al proveedor para imagen/audio | - | `plugin-sdk/text-runtime` | Helpers compartidos de texto | Eliminación de texto visible para el asistente, helpers de renderizado/fragmentación/tabla 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 proveedores 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 proveedores de voz, registro, directivas, normalización | - | `plugin-sdk/realtime-transcription` | Helpers de transcripción en tiempo real | Tipos de proveedores y helpers de registro | - | `plugin-sdk/realtime-voice` | Helpers de voz en tiempo real | Tipos de proveedores y helpers de registro | - | `plugin-sdk/image-generation-core` | Núcleo compartido de generación de imágenes | Tipos, failover, autenticación y helpers de registro de generación de imágenes | - | `plugin-sdk/music-generation` | Helpers de generación de música | Tipos de proveedor/solicitud/resultado de generación de música | - | `plugin-sdk/music-generation-core` | Núcleo compartido de generación de música | Tipos de generación de música, helpers de failover, búsqueda de proveedor y análisis de referencias de modelo | - | `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 referencias de modelo | - | `plugin-sdk/interactive-runtime` | Helpers 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 para escritura de configuración de canal | + | `plugin-sdk/media-runtime` | Utilidades compartidas de medios | Utilidades de fetch/transformación/almacenamiento de medios además de builders de payload de medios | + | `plugin-sdk/media-generation-runtime` | Utilidades compartidas de generación de medios | Utilidades compartidas de failover, selección de candidatos y mensajes de modelo faltante para generación de imagen/video/música | + | `plugin-sdk/media-understanding` | Utilidades de comprensión de medios | Tipos de provider de comprensión de medios además de exportaciones de utilidades de imagen/audio orientadas al provider | + | `plugin-sdk/text-runtime` | Utilidades compartidas de texto | Eliminación de texto visible para el asistente, utilidades de renderizado/fragmentación/tablas Markdown, utilidades de redacción, utilidades de etiquetas de directivas, utilidades de texto seguro y utilidades relacionadas de texto/logging | + | `plugin-sdk/text-chunking` | Utilidades de fragmentación de texto | Utilidad de fragmentación de texto saliente | + | `plugin-sdk/speech` | Utilidades de voz | Tipos de provider de voz además de utilidades de directivas, registro y validación orientadas al provider | + | `plugin-sdk/speech-core` | Núcleo compartido de voz | Tipos de provider de voz, registro, directivas, normalización | + | `plugin-sdk/realtime-transcription` | Utilidades de transcripción en tiempo real | Tipos de provider y utilidades de registro | + | `plugin-sdk/realtime-voice` | Utilidades de voz en tiempo real | Tipos de provider y utilidades 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 utilidades de registro | + | `plugin-sdk/music-generation` | Utilidades de generación de música | Tipos de provider/solicitud/resultado para generación de música | + | `plugin-sdk/music-generation-core` | Núcleo compartido de generación de música | Tipos de generación de música, utilidades de failover, búsqueda de provider y análisis de model-ref | + | `plugin-sdk/video-generation` | Utilidades de generación de video | Tipos de provider/solicitud/resultado para generación de video | + | `plugin-sdk/video-generation-core` | Núcleo compartido de generación de video | Tipos de generación de video, utilidades de failover, búsqueda de provider y análisis de model-ref | + | `plugin-sdk/interactive-runtime` | Utilidades de respuestas interactivas | Normalización/reducción de payload de respuesta interactiva | + | `plugin-sdk/channel-config-primitives` | Primitivas de configuración de canal | Primitivas específicas de config-schema de canal | + | `plugin-sdk/channel-config-writes` | Utilidades de escritura de configuración de canal | Utilidades de autorización para 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` | 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 permitida | Helpers de edición/lectura de configuración de lista permitida | - | `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 autenticación/protección de DM directo | - | `plugin-sdk/extension-shared` | Helpers compartidos de extensión | Primitivas helper de canal/estado pasivo | - | `plugin-sdk/webhook-targets` | Helpers de destinos webhook | Registro de destinos webhook y helpers de instalación de rutas | - | `plugin-sdk/webhook-path` | Helpers de rutas webhook | Helpers de normalización de rutas 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 gestor/configuración/archivo/CLI de memoria | + | `plugin-sdk/channel-status` | Utilidades de estado de canal | Utilidades compartidas de instantánea/resumen de estado de canal | + | `plugin-sdk/allowlist-config-edit` | Utilidades de configuración de lista de permitidos | Utilidades de edición/lectura de configuración de lista de permitidos | + | `plugin-sdk/group-access` | Utilidades de acceso a grupos | Utilidades compartidas de decisión de acceso a grupos | + | `plugin-sdk/direct-dm` | Utilidades de DM directo | Utilidades compartidas de autenticación/protección de DM directo | + | `plugin-sdk/extension-shared` | Utilidades compartidas de extensiones | Primitivas auxiliares de canal/estado pasivo | + | `plugin-sdk/webhook-targets` | Utilidades de destinos webhook | Registro de destinos webhook y utilidades de instalación de rutas | + | `plugin-sdk/webhook-path` | Utilidades de rutas webhook | Utilidades de normalización de rutas webhook | + | `plugin-sdk/web-media` | Utilidades compartidas de medios web | Utilidades de carga de medios remotos/locales | + | `plugin-sdk/zod` | Reexportación de Zod | `zod` reexportado para consumidores de plugin SDK | + | `plugin-sdk/memory-core` | Utilidades integradas de memory-core | Superficie de utilidades 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/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 consulta del host de memoria | Helpers de consulta 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-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 central del host de memoria | Helpers de runtime central 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-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` | Utilidades multimodales del host de memoria | Utilidades multimodales del host de memoria | + | `plugin-sdk/memory-core-host-query` | Utilidades de consulta del host de memoria | Utilidades de consulta del host de memoria | + | `plugin-sdk/memory-core-host-secret` | Utilidades de secretos del host de memoria | Utilidades de secretos del host de memoria | + | `plugin-sdk/memory-core-host-events` | Utilidades de diario de eventos del host de memoria | Utilidades de diario de eventos del host de memoria | + | `plugin-sdk/memory-core-host-status` | Utilidades de estado del host de memoria | Utilidades de estado del host de memoria | + | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI del host de memoria | Utilidades de runtime CLI del host de memoria | + | `plugin-sdk/memory-core-host-runtime-core` | Runtime principal del host de memoria | Utilidades de runtime principal del host de memoria | + | `plugin-sdk/memory-core-host-runtime-files` | Utilidades de archivos/runtime del host de memoria | Utilidades de archivos/runtime del host de memoria | + | `plugin-sdk/memory-host-core` | Alias de runtime principal del host de memoria | Alias neutral respecto al proveedor para utilidades de runtime principal del host de memoria | + | `plugin-sdk/memory-host-events` | Alias de diario de eventos del host de memoria | Alias neutral respecto al proveedor para utilidades de diario de eventos del host de memoria | + | `plugin-sdk/memory-host-files` | Alias de archivos/runtime del host de memoria | Alias neutral respecto al proveedor para utilidades de archivos/runtime del host de memoria | + | `plugin-sdk/memory-host-markdown` | Utilidades de markdown administrado | Utilidades compartidas de markdown administrado para plugins adyacentes a memoria | + | `plugin-sdk/memory-host-search` | Fachada de búsqueda de memoria activa | Fachada de runtime diferido del administrador de búsqueda de memoria activa | + | `plugin-sdk/memory-host-status` | Alias de estado del host de memoria | Alias neutral respecto al proveedor para utilidades de estado del host de memoria | + | `plugin-sdk/memory-lancedb` | Utilidades integradas de memory-lancedb | Superficie de utilidades de memory-lancedb | + | `plugin-sdk/testing` | Utilidades de prueba | Utilidades 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 se encuentra 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 aún incluye algunas interfaces helper de plugins empaquetados como +Esa lista todavía incluye algunas interfaces de utilidades de plugins integrados 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 intencionadamente -de la tabla común de migración y no son el objetivo recomendado para +`plugin-sdk/zalo-setup` y `plugin-sdk/matrix*`. Estas siguen exportándose para +mantenimiento y compatibilidad de plugins integrados, pero se omiten intencionalmente +de la tabla común de migración y no son el destino 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 utilidades integradas como: -- helpers 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` +- utilidades de compatibilidad con 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` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- superficies de helpers/plugins empaquetados como `plugin-sdk/googlechat`, +- superficies de utilidades/plugins integrados 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`, @@ -330,21 +338,21 @@ 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` actualmente expone la superficie específica de helpers de token +`plugin-sdk/github-copilot-token` actualmente expone la superficie específica de utilidades de token `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken`. Usa la importación más específica que coincida con la tarea. Si no encuentras una exportación, -consulta el código fuente en `src/plugin-sdk/` o pregunta en Discord. +revisa la fuente en `src/plugin-sdk/` o pregunta en Discord. ## Cronograma de eliminación -| Cuándo | Qué sucede | -| ---------------------- | ----------------------------------------------------------------------- | -| **Ahora** | Las superficies obsoletas emiten advertencias en runtime | +| Cuándo | Qué sucede | +| ---------------------- | ---------------------------------------------------------------------- | +| **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 aún las usen fallarán | -Todos los plugins principales ya se han migrado. Los plugins externos deberían migrar +Todos los plugins principales ya se migraron. Los plugins externos deberían migrar antes de la próxima versión principal. ## Suprimir temporalmente las advertencias @@ -356,13 +364,13 @@ 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 importaciones por subruta +- [Descripción general 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 -- [Internals de plugins](/es/plugins/architecture) — análisis profundo de la arquitectura -- [Manifiesto del plugin](/es/plugins/manifest) — referencia del esquema del manifiesto +- [Plugins de provider](/es/plugins/sdk-provider-plugins) — creación de plugins de provider +- [Aspectos internos de plugins](/es/plugins/architecture) — análisis profundo de la arquitectura +- [Manifiesto de 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 37fc4a596..d957cce8c 100644 --- a/docs/es/plugins/sdk-overview.md +++ b/docs/es/plugins/sdk-overview.md @@ -1,30 +1,30 @@ --- read_when: - Necesitas saber desde qué subruta del SDK importar - - Quieres una referencia de todos los métodos de registro en OpenClawPluginApi - - Estás consultando una exportación específica del SDK + - Quieres una referencia para 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: Resumen del Plugin SDK +summary: Mapa de importación, referencia de la API de registro y arquitectura del SDK +title: Descripción general del SDK de plugins x-i18n: - generated_at: "2026-04-06T03:10:46Z" + generated_at: "2026-04-06T05:13:36Z" model: gpt-5.4 provider: openai - source_hash: d801641f26f39dc21490d2a69a337ff1affb147141360916b8b58a267e9f822a + source_hash: acd2887ef52c66b2f234858d812bb04197ecd0bfb3e4f7bf3622f8fdc765acad source_path: plugins/sdk-overview.md workflow: 15 --- -# Resumen del Plugin SDK +# Descripción general del SDK de plugins -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**. +El SDK de plugins es el contrato tipado entre los plugins y el núcleo. Esta página es la +referencia de **qué importar** y **qué puedes registrar**. **¿Buscas una guía práctica?** - - ¿Primer plugin? Empieza con [Primeros pasos](/es/plugins/building-plugins) - - ¿Plugin de canal? Consulta [Plugins de canal](/es/plugins/sdk-channel-plugins) - - ¿Plugin de proveedor? Consulta [Plugins de proveedor](/es/plugins/sdk-provider-plugins) + - ¿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 @@ -37,247 +37,255 @@ 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 helpers de entrada/construcción específicos -de canal, prefiere `openclaw/plugin-sdk/channel-core`; deja `openclaw/plugin-sdk/core` para -la superficie paraguas más amplia y helpers compartidos como +evita problemas de dependencias circulares. Para los ayudantes de entrada/construcción específicos de canal, +prefiere `openclaw/plugin-sdk/channel-core`; deja `openclaw/plugin-sdk/core` para +la superficie paraguas más amplia y los ayudantes compartidos como `buildChannelConfigSchema`. -No añadas ni dependas de accesos convenientes con nombre de proveedor como +No agregues ni dependas de interfaces de conveniencia con nombre de proveedor como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni -accesos helper con marca de canal. Los plugins empaquetados 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 añadir un contrato genérico y estrecho del SDK -cuando la necesidad sea realmente entre canales. +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de +interfaces auxiliares con marca de canal. Los plugins incluidos 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 reducido del SDK +cuando la necesidad sea realmente transversal a varios canales. -El mapa de exportaciones generado todavía contiene un pequeño conjunto de accesos helper -de plugins empaquetados como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +El mapa de exportaciones generado todavía contiene un pequeño conjunto de +interfaces auxiliares para plugins incluidos 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 empaquetados; se -omiten intencionalmente de la tabla común siguiente y no son la ruta de importación +subrutas existen solo para mantenimiento y compatibilidad de plugins incluidos; se +omiten intencionalmente de la tabla común de abajo y no son la ruta de importación recomendada para nuevos plugins de terceros. ## Referencia de subrutas -Las subrutas más usadas, agrupadas por propósito. La lista completa generada de +Las subrutas más usadas con frecuencia, agrupadas por propósito. La lista completa generada de más de 200 subrutas está en `scripts/lib/plugin-sdk-entrypoints.json`. -Las subrutas helper reservadas para plugins empaquetados siguen apareciendo en esa lista generada. -Trátalas como una superficie de implementación/compatibilidad a menos que una página de documentación -promocione explícitamente una como pública. +Las subrutas auxiliares reservadas para plugins incluidos siguen apareciendo en esa lista generada. +Trátalas como superficies de detalle de implementación/compatibilidad salvo que una página de documentación +promueva explícitamente alguna como pública. -### Entrada de plugin +### Entrada del plugin -| Subruta | Exportaciones clave | -| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | -| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| Subruta | Exportaciones clave | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | Subruta | Exportaciones clave | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Exportación del esquema Zod raíz `openclaw.json` (`OpenClawSchema`) | + | `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` | Helpers compartidos de asistente de configuración, prompts de lista de permitidos, generadores de estado de configuración | + | `plugin-sdk/setup` | Ayudantes compartidos del asistente de configuración, indicaciones de allowlist, 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` | Helpers de configuración/controles de acciones multi-cuenta y helpers de fallback de cuenta predeterminada | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalización de ID de cuenta | - | `plugin-sdk/account-resolution` | Helpers de búsqueda de cuenta y fallback predeterminado | - | `plugin-sdk/account-helpers` | Helpers concretos de lista de cuentas/acciones de cuenta | + | `plugin-sdk/account-core` | Ayudantes de configuración/puerta de acción para varias cuentas, ayudantes de respaldo 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 respaldo predeterminado | + | `plugin-sdk/account-helpers` | Ayudantes específicos 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` | Helpers de normalización/validación de comandos personalizados de Telegram con fallback de contrato empaquetado | + | `plugin-sdk/telegram-command-config` | Ayudantes de normalización/validación de comandos personalizados de Telegram con respaldo del contrato incluido | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpers compartidos de ruta entrante y construcción de sobre | - | `plugin-sdk/inbound-reply-dispatch` | Helpers compartidos para registrar y despachar entradas | - | `plugin-sdk/messaging-targets` | Helpers de análisis/coincidencia de destino | - | `plugin-sdk/outbound-media` | Helpers compartidos de carga de multimedia saliente | - | `plugin-sdk/outbound-runtime` | Helpers de identidad saliente y delegado de envío | - | `plugin-sdk/thread-bindings-runtime` | Helpers de ciclo de vida y adaptador de vinculaciones de hilo | - | `plugin-sdk/agent-media-payload` | Constructor heredado de carga multimedia del agente | - | `plugin-sdk/conversation-runtime` | Helpers de conversación/vinculación de hilo, vinculación y binding configurado | - | `plugin-sdk/runtime-config-snapshot` | Helper de snapshot de configuración de runtime | - | `plugin-sdk/runtime-group-policy` | Helpers de resolución de política de grupo en runtime | - | `plugin-sdk/channel-status` | Helpers compartidos de snapshot/resumen de estado de canal | - | `plugin-sdk/channel-config-primitives` | Primitivas concretas de esquema de configuración de canal | - | `plugin-sdk/channel-config-writes` | Helpers de autorización para escrituras de configuración de canal | + | `plugin-sdk/inbound-envelope` | Ayudantes compartidos para rutas de entrada + creación de sobres | + | `plugin-sdk/inbound-reply-dispatch` | Ayudantes compartidos para registrar y despachar entradas | + | `plugin-sdk/messaging-targets` | Ayudantes para analizar/emparejar destinos | + | `plugin-sdk/outbound-media` | Ayudantes compartidos para cargar medios salientes | + | `plugin-sdk/outbound-runtime` | Ayudantes de identidad saliente/del delegado de envío | + | `plugin-sdk/thread-bindings-runtime` | Ciclo de vida de vinculaciones de hilos y ayudantes de adaptador | + | `plugin-sdk/agent-media-payload` | Constructor heredado de carga útil 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 instantánea 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 para instantáneas/resúmenes de estado de canal | + | `plugin-sdk/channel-config-primitives` | Primitivas específicas del esquema de configuración de canal | + | `plugin-sdk/channel-config-writes` | Ayudantes de autorización de escritura de configuración de canal | | `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas para plugins de canal | - | `plugin-sdk/allowlist-config-edit` | Helpers de edición/lectura de configuración de lista de permitidos | - | `plugin-sdk/group-access` | Helpers compartidos de decisión de acceso a grupos | - | `plugin-sdk/direct-dm` | Helpers compartidos de autenticación/protección para DM directo | - | `plugin-sdk/interactive-runtime` | Helpers de normalización/reducción de carga de respuesta interactiva | - | `plugin-sdk/channel-inbound` | Helpers de debounce, coincidencia de mención y sobre | + | `plugin-sdk/allowlist-config-edit` | Ayudantes para editar/leer configuración de allowlist | + | `plugin-sdk/group-access` | Ayudantes compartidos para decisiones de acceso a grupos | + | `plugin-sdk/direct-dm` | Ayudantes compartidos para autenticación/protección de mensajes directos | + | `plugin-sdk/interactive-runtime` | Ayudantes para normalización/reducción de cargas útiles de respuestas interactivas | + | `plugin-sdk/channel-inbound` | Debounce, coincidencia de menciones, ayudantes de sobres | | `plugin-sdk/channel-send-result` | Tipos de resultado de respuesta | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Helpers de análisis/coincidencia de destino | + | `plugin-sdk/channel-targets` | Ayudantes para analizar/emparejar destinos | | `plugin-sdk/channel-contract` | Tipos de contrato de canal | - | `plugin-sdk/channel-feedback` | Cableado de feedback/reacciones | + | `plugin-sdk/channel-feedback` | Integración de comentarios/reacciones | | Subruta | Exportaciones clave | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helpers seleccionados de configuración de proveedores locales/autohospedados | - | `plugin-sdk/self-hosted-provider-setup` | Helpers enfocados para configuración de proveedores autohospedados compatibles con OpenAI | - | `plugin-sdk/provider-auth-runtime` | Helpers de resolución de claves API en runtime para plugins de proveedor | - | `plugin-sdk/provider-auth-api-key` | Helpers de onboarding/escritura de perfil de clave API | + | `plugin-sdk/provider-setup` | Ayudantes seleccionados de configuración para proveedores locales/autohospedados | + | `plugin-sdk/self-hosted-provider-setup` | Ayudantes enfocados de configuración para proveedores autohospedados compatibles con OpenAI | + | `plugin-sdk/provider-auth-runtime` | Ayudantes de resolución de claves API en tiempo de ejecución para plugins de proveedor | + | `plugin-sdk/provider-auth-api-key` | Ayudantes de incorporación/escritura de perfil de clave API | | `plugin-sdk/provider-auth-result` | Constructor estándar de resultado de autenticación OAuth | - | `plugin-sdk/provider-auth-login` | Helpers compartidos de inicio de sesión interactivo para plugins de proveedor | - | `plugin-sdk/provider-env-vars` | Helpers de búsqueda de variables de entorno de autenticación de proveedor | + | `plugin-sdk/provider-auth-login` | Ayudantes compartidos de inicio de sesión interactivo para plugins de proveedor | + | `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` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de política de replay, helpers de endpoint de proveedor y helpers de normalización de ID de modelo como `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, ayudantes de endpoints de proveedor y ayudantes de normalización de ID de modelo como `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helpers genéricos de capacidades HTTP/endpoint de proveedor | - | `plugin-sdk/provider-web-fetch` | Helpers de registro/caché de proveedores web-fetch | - | `plugin-sdk/provider-web-search` | Helpers de registro/caché/configuración de proveedores web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza de esquemas Gemini + diagnósticos, y helpers de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Ayudantes genéricos de capacidades HTTP/endpoint de proveedor | + | `plugin-sdk/provider-web-fetch` | Ayudantes de registro/caché para proveedores de captura web | + | `plugin-sdk/provider-web-search` | Ayudantes de registro/caché/configuración para proveedores de búsqueda web | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza de esquemas Gemini + diagnósticos y ayudantes de compatibilidad de xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` y similares | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltura de stream y helpers compartidos de envoltura para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Helpers de parche de configuración de onboarding | - | `plugin-sdk/global-singleton` | Helpers de singleton/mapa/caché locales al proceso | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorios de flujo 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 de incorporación | + | `plugin-sdk/global-singleton` | Ayudantes de singleton/mapa/caché local al proceso | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registro de comandos, helpers de autorización de remitente | - | `plugin-sdk/approval-auth-runtime` | Helpers de resolución de aprobadores y autenticación de acciones en el mismo chat | - | `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprobaciones nativas de ejecución | - | `plugin-sdk/approval-delivery-runtime` | Adaptadores de capacidad/entrega de aprobación nativa | - | `plugin-sdk/approval-native-runtime` | Helpers de destino de aprobación nativa y vinculación de cuenta | - | `plugin-sdk/approval-reply-runtime` | Helpers de carga de respuesta para aprobación exec/plugin | - | `plugin-sdk/command-auth-native` | Helpers de autenticación de comandos nativos y destino de sesión nativa | - | `plugin-sdk/command-detection` | Helpers compartidos de detección de comandos | - | `plugin-sdk/command-surface` | Helpers de normalización del cuerpo de comando y superficie de comando | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, ayudantes del registro de comandos, ayudantes de autorización del remitente | + | `plugin-sdk/approval-auth-runtime` | Ayudantes para resolución de aprobadores y autenticación de acciones en el mismo chat | + | `plugin-sdk/approval-client-runtime` | Ayudantes de perfil/filtro de aprobación de ejecución nativa | + | `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidad/entrega de aprobación | + | `plugin-sdk/approval-native-runtime` | Ayudantes nativos de destino de aprobación + vinculación de cuenta | + | `plugin-sdk/approval-reply-runtime` | Ayudantes de carga útil de respuesta para aprobación de ejecución/plugin | + | `plugin-sdk/command-auth-native` | Autenticación de comandos nativos + ayudantes nativos de destino de sesión | + | `plugin-sdk/command-detection` | Ayudantes compartidos de detección de comandos | + | `plugin-sdk/command-surface` | Normalización del cuerpo de comandos y ayudantes de superficie de comandos | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/security-runtime` | Helpers compartidos de confianza, control de DM, contenido externo y recopilación de secretos | - | `plugin-sdk/ssrf-policy` | Helpers de allowlist de hosts y política SSRF de red privada | - | `plugin-sdk/ssrf-runtime` | Helpers de pinned-dispatcher, fetch protegido por SSRF y política SSRF | - | `plugin-sdk/secret-input` | Helpers de análisis de entrada secreta | - | `plugin-sdk/webhook-ingress` | Helpers de solicitud/destino de webhook | - | `plugin-sdk/webhook-request-guards` | Helpers de tamaño de cuerpo/tiempo de espera de solicitud | + | `plugin-sdk/security-runtime` | Ayudantes compartidos para confianza, bloqueo de mensajes directos, contenido externo y recolección de secretos | + | `plugin-sdk/ssrf-policy` | Ayudantes de allowlist de hosts y política SSRF de red privada | + | `plugin-sdk/ssrf-runtime` | Ayudantes de dispatcher fijado, fetch con protección SSRF y política SSRF | + | `plugin-sdk/secret-input` | Ayudantes de análisis de entrada secreta | + | `plugin-sdk/webhook-ingress` | Ayudantes de solicitud/destino de webhook | + | `plugin-sdk/webhook-request-guards` | Ayudantes de tamaño de cuerpo/tiempo de espera de solicitud | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/runtime` | Helpers amplios de runtime/logging/copia de seguridad/instalación de plugins | - | `plugin-sdk/runtime-env` | Helpers concretos de entorno de runtime, logger, timeout, retry y backoff | + | `plugin-sdk/runtime` | Ayudantes amplios de runtime, registro, copias de seguridad e instalación de plugins | + | `plugin-sdk/runtime-env` | Ayudantes específicos de entorno de runtime, logger, tiempo de espera, reintento y retroceso | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Helpers compartidos de plugin para comandos/hooks/http/interactivo | - | `plugin-sdk/hook-runtime` | Helpers compartidos del pipeline de hooks webhook/internos | - | `plugin-sdk/lazy-runtime` | Helpers de importación/vinculación perezosa de runtime como `createLazyRuntimeModule`, `createLazyRuntimeMethod` y `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helpers de ejecución de procesos | - | `plugin-sdk/cli-runtime` | Helpers de formato CLI, espera y versión | - | `plugin-sdk/gateway-runtime` | Helpers de cliente gateway y parche de estado de canal | - | `plugin-sdk/config-runtime` | Helpers de carga/escritura de configuración | - | `plugin-sdk/telegram-command-config` | Normalización de nombre/descripción de comando de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato de Telegram empaquetada no está disponible | - | `plugin-sdk/approval-runtime` | Helpers de aprobación exec/plugin, constructores de capacidad de aprobación, helpers de auth/perfil, helpers nativos de routing/runtime | - | `plugin-sdk/reply-runtime` | Helpers compartidos de runtime para entrada/respuesta, fragmentación, despacho, heartbeat, planificador de respuesta | - | `plugin-sdk/reply-dispatch-runtime` | Helpers concretos de despacho/finalización de respuesta | - | `plugin-sdk/reply-history` | Helpers compartidos de historial de respuesta de ventana corta como `buildHistoryContext`, `recordPendingHistoryEntry` y `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Ayudantes compartidos para comandos, hooks, HTTP e interacciones de plugins | + | `plugin-sdk/hook-runtime` | Ayudantes compartidos del flujo de hooks webhook/internos | + | `plugin-sdk/lazy-runtime` | Ayudantes de importación/vinculación perezosa 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, espera y versión para CLI | + | `plugin-sdk/gateway-runtime` | Ayudantes de cliente de gateway y parcheo de estado de canal | + | `plugin-sdk/config-runtime` | Ayudantes 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 del contrato incluido de Telegram no está disponible | + | `plugin-sdk/approval-runtime` | Ayudantes de aprobación de ejecución/plugin, constructores de capacidad de aprobación, ayudantes de autenticación/perfil, ayudantes nativos de enrutamiento/runtime | + | `plugin-sdk/reply-runtime` | Ayudantes compartidos de runtime de entrada/respuesta, fragmentación, despacho, latido, planificador de respuestas | + | `plugin-sdk/reply-dispatch-runtime` | Ayudantes específicos 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` | Helpers concretos de fragmentación de texto/Markdown | - | `plugin-sdk/session-store-runtime` | Helpers de ruta del almacén de sesiones y updated-at | - | `plugin-sdk/state-paths` | Helpers de rutas de directorios de estado/OAuth | - | `plugin-sdk/routing` | Helpers de ruta/clave de sesión/vinculación de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helpers compartidos de resumen de estado de canal/cuenta, valores predeterminados de estado de runtime y helpers de metadatos de incidencias | - | `plugin-sdk/target-resolver-runtime` | Helpers compartidos de resolución de destino | - | `plugin-sdk/string-normalization-runtime` | Helpers de normalización de slug/cadenas | - | `plugin-sdk/request-url` | Extraer URLs de cadena de entradas tipo fetch/request | - | `plugin-sdk/run-command` | Ejecutor de comandos con tiempo medido y resultados stdout/stderr normalizados | - | `plugin-sdk/param-readers` | Lectores comunes de parámetros de herramienta/CLI | - | `plugin-sdk/tool-send` | Extraer campos de destino de envío canónicos de argumentos de herramienta | - | `plugin-sdk/temp-path` | Helpers compartidos de rutas temporales de descarga | - | `plugin-sdk/logging-core` | Logger de subsistema y helpers de redacción | - | `plugin-sdk/markdown-table-runtime` | Helpers de modo de tabla Markdown | - | `plugin-sdk/json-store` | Helpers pequeños de lectura/escritura de estado JSON | - | `plugin-sdk/file-lock` | Helpers de bloqueo de archivo reentrante | - | `plugin-sdk/persistent-dedupe` | Helpers de caché de deduplicación persistente en disco | - | `plugin-sdk/acp-runtime` | Helpers de runtime/sesión ACP y despacho de respuesta | - | `plugin-sdk/agent-config-primitives` | Primitivas concretas de esquema de configuración de runtime del agente | + | `plugin-sdk/reply-chunking` | Ayudantes específicos para fragmentación de texto/markdown | + | `plugin-sdk/session-store-runtime` | Ayudantes de ruta de almacén de sesión + `updated-at` | + | `plugin-sdk/state-paths` | Ayudantes de rutas de directorios de estado/OAuth | + | `plugin-sdk/routing` | Ayudantes de ruta/clave de sesión/vinculación de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Ayudantes compartidos para resúmenes de estado de canal/cuenta, valores predeterminados de estado de runtime 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` | Extraer URL en formato 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 para herramientas/CLI | + | `plugin-sdk/tool-send` | Extraer campos canónicos del destino de envío 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` | Ayudantes pequeños para leer/escribir estado JSON | + | `plugin-sdk/file-lock` | Ayudantes de bloqueo de archivos reentrantes | + | `plugin-sdk/persistent-dedupe` | Ayudantes de caché de deduplicación respaldada en disco | + | `plugin-sdk/acp-runtime` | Ayudantes de runtime/sesión ACP y despacho de respuestas | + | `plugin-sdk/agent-config-primitives` | Primitivas específicas del esquema de configuración de runtime de agentes | | `plugin-sdk/boolean-param` | Lector flexible de parámetros booleanos | - | `plugin-sdk/dangerous-name-runtime` | Helpers de resolución de coincidencia de nombre peligrosa | - | `plugin-sdk/device-bootstrap` | Helpers de arranque de dispositivo y token de vinculación | - | `plugin-sdk/extension-shared` | Primitivas helper compartidas para canales pasivos y estado | - | `plugin-sdk/models-provider-runtime` | Helpers de respuesta para comando `/models`/proveedor | - | `plugin-sdk/skill-commands-runtime` | Helpers de listado de comandos de Skills | - | `plugin-sdk/native-command-registry` | Helpers de registro/construcción/serialización de comandos nativos | - | `plugin-sdk/provider-zai-endpoint` | Helpers de detección de endpoint Z.AI | - | `plugin-sdk/infra-runtime` | Helpers de evento del sistema/heartbeat | - | `plugin-sdk/collection-runtime` | Helpers pequeños de caché acotada | - | `plugin-sdk/diagnostic-runtime` | Helpers de marca y evento de diagnóstico | - | `plugin-sdk/error-runtime` | Grafo de errores, formato, helpers compartidos de clasificación de errores, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helpers de fetch envuelto, proxy y búsqueda fijada | - | `plugin-sdk/host-runtime` | Helpers de normalización de hostname y host SCP | - | `plugin-sdk/retry-runtime` | Helpers de configuración de retry y ejecutor de retry | - | `plugin-sdk/agent-runtime` | Helpers de directorio/identidad/workspace de agente | - | `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorios basada en configuración | + | `plugin-sdk/dangerous-name-runtime` | Ayudantes de resolución de coincidencias de nombres peligrosos | + | `plugin-sdk/device-bootstrap` | Ayudantes de inicialización de dispositivos y tokens de emparejamiento | + | `plugin-sdk/extension-shared` | Primitivas compartidas para canales pasivos y ayudantes de estado | + | `plugin-sdk/models-provider-runtime` | Ayudantes de respuesta para el comando `/models` y proveedores | + | `plugin-sdk/skill-commands-runtime` | Ayudantes de listado de comandos de Skills | + | `plugin-sdk/native-command-registry` | Ayudantes para registrar/construir/serializar comandos nativos | + | `plugin-sdk/provider-zai-endpoint` | Ayudantes de detección de endpoint Z.AI | + | `plugin-sdk/infra-runtime` | Ayudantes de eventos del sistema/latido | + | `plugin-sdk/collection-runtime` | Ayudantes de caché acotada pequeña | + | `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úsqueda fijada | + | `plugin-sdk/host-runtime` | Ayudantes de normalización de nombre de host y host SCP | + | `plugin-sdk/retry-runtime` | Ayudantes de configuración y ejecución de reintentos | + | `plugin-sdk/agent-runtime` | Ayudantes de directorio/identidad/espacio de trabajo del agente | + | `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorios respaldados por configuración | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/media-runtime` | Helpers compartidos de obtención/transformación/almacenamiento de multimedia más constructores de carga multimedia | - | `plugin-sdk/media-understanding` | Tipos de proveedor de comprensión multimedia más exportaciones de helpers de imagen/audio para proveedores | - | `plugin-sdk/text-runtime` | Helpers compartidos de texto/Markdown/logging como eliminación de texto visible para el asistente, renderizado/fragmentación/tablas Markdown, redacción, etiquetas de directivas y utilidades de texto seguro | - | `plugin-sdk/text-chunking` | Helper de fragmentación de texto saliente | - | `plugin-sdk/speech` | Tipos de proveedor de voz más helpers orientados al proveedor para directivas, registro y validación | - | `plugin-sdk/speech-core` | Tipos compartidos de proveedor de voz, registro, directiva y helpers de normalización | - | `plugin-sdk/realtime-transcription` | Tipos de proveedor de transcripción en tiempo real y helpers de registro | - | `plugin-sdk/realtime-voice` | Tipos de proveedor de voz en tiempo real y helpers de registro | + | `plugin-sdk/media-runtime` | Ayudantes compartidos para obtener/transformar/almacenar medios, además de constructores de cargas útiles de medios | + | `plugin-sdk/media-generation-runtime` | Ayudantes compartidos para failover de generación de medios, selección de candidatos y mensajes de modelo faltante | + | `plugin-sdk/media-understanding` | Tipos de proveedor para comprensión de medios más exportaciones de ayudantes de imagen/audio orientadas a proveedores | + | `plugin-sdk/text-runtime` | Ayudantes compartidos de texto/markdown/logging como eliminación de texto visible para el asistente, ayudantes de 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 ayudantes orientados a proveedores para directivas, registro y validación | + | `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 helpers de registro | + | `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, helpers de failover, búsqueda de proveedor y análisis de model-ref | + | `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, helpers de failover, búsqueda de proveedor y análisis de model-ref | - | `plugin-sdk/webhook-targets` | Registro de destinos webhook y helpers de instalación de rutas | - | `plugin-sdk/webhook-path` | Helpers de normalización de ruta de webhook | - | `plugin-sdk/web-media` | Helpers compartidos de carga multimedia remota/local | - | `plugin-sdk/zod` | `zod` reexportado para consumidores del plugin SDK | + | `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 de webhook y ayudantes de instalación de rutas | + | `plugin-sdk/webhook-path` | Ayudantes de normalización de rutas de webhook | + | `plugin-sdk/web-media` | Ayudantes compartidos para carga de medios remotos/locales | + | `plugin-sdk/zod` | `zod` reexportado para consumidores del SDK de plugins | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/memory-core` | Superficie helper empaquetada memory-core para helpers de gestor/configuración/archivo/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime de índice/búsqueda de memoria | + | `plugin-sdk/memory-core` | Superficie auxiliar `memory-core` incluida para ayudantes de administrador/configuración/archivo/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime para indexación/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` | Helpers multimodales del host de memoria | - | `plugin-sdk/memory-core-host-query` | Helpers de consulta del host de memoria | - | `plugin-sdk/memory-core-host-secret` | Helpers de secretos del host de memoria | - | `plugin-sdk/memory-core-host-status` | Helpers de estado del host de memoria | - | `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime CLI del host de memoria | - | `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime central del host de memoria | - | `plugin-sdk/memory-core-host-runtime-files` | Helpers de archivos/runtime del host de memoria | - | `plugin-sdk/memory-lancedb` | Superficie helper empaquetada 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 de 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 runtime CLI del host de memoria | + | `plugin-sdk/memory-core-host-runtime-core` | Ayudantes de runtime central del host de memoria | + | `plugin-sdk/memory-core-host-runtime-files` | Ayudantes de archivos/runtime del host de memoria | + | `plugin-sdk/memory-host-core` | Alias neutral al proveedor para ayudantes de runtime central del host de memoria | + | `plugin-sdk/memory-host-events` | Alias neutral al proveedor para ayudantes del diario de eventos del host de memoria | + | `plugin-sdk/memory-host-files` | Alias neutral al proveedor para ayudantes de archivos/runtime del host de memoria | + | `plugin-sdk/memory-host-markdown` | Ayudantes compartidos de markdown gestionado para plugins adyacentes a memoria | + | `plugin-sdk/memory-host-search` | Fachada de runtime de memoria activa para acceso al administrador de búsqueda | + | `plugin-sdk/memory-host-status` | Alias neutral al proveedor para ayudantes de estado del host de memoria | + | `plugin-sdk/memory-lancedb` | Superficie auxiliar `memory-lancedb` incluida | - + | 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` | Helpers de soporte del plugin Browser empaquetado (`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 helper/runtime empaquetada de Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime empaquetada de LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper empaquetada de IRC | - | Helpers 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` | Accesos de compatibilidad/helper para canales empaquetados | - | Helpers 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` | Accesos helper para funciones/plugins empaquetados; `plugin-sdk/github-copilot-token` exporta actualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` | + | 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 Browser incluido (`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 runtime de Matrix incluida | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie auxiliar/de runtime de LINE incluida | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie auxiliar de IRC incluida | + | 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` | Interfaces auxiliares/de compatibilidad de canales incluidos | + | Ayudantes 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` | Interfaces auxiliares de funciones/plugins incluidos; `plugin-sdk/github-copilot-token` exporta actualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` | @@ -288,19 +296,19 @@ métodos: ### Registro de capacidades -| Método | Qué registra | -| ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | Inferencia de texto (LLM) | -| `api.registerChannel(...)` | Canal de mensajería | -| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT | +| Método | Qué registra | +| ------------------------------------------------ | ------------------------------- | +| `api.registerProvider(...)` | Inferencia de texto (LLM) | +| `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 bidireccionales en tiempo real | -| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video | -| `api.registerImageGenerationProvider(...)` | Generación de imágenes | -| `api.registerMusicGenerationProvider(...)` | Generación musical | -| `api.registerVideoGenerationProvider(...)` | Generación de video | -| `api.registerWebFetchProvider(...)` | Proveedor de web fetch / scraping | -| `api.registerWebSearchProvider(...)` | Búsqueda web | +| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz dúplex en tiempo real | +| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video | +| `api.registerImageGenerationProvider(...)` | Generación de imágenes | +| `api.registerMusicGenerationProvider(...)` | Generación de música | +| `api.registerVideoGenerationProvider(...)` | Generación de video | +| `api.registerWebFetchProvider(...)` | Proveedor de captura / scraping web | +| `api.registerWebSearchProvider(...)` | Búsqueda web | ### Herramientas y comandos @@ -311,29 +319,31 @@ métodos: ### Infraestructura -| Método | Qué registra | -| ---------------------------------------------- | -------------------- | -| `api.registerHook(events, handler, opts?)` | Hook de evento | -| `api.registerHttpRoute(params)` | Endpoint HTTP del gateway | -| `api.registerGatewayMethod(name, handler)` | Método RPC del gateway | -| `api.registerCli(registrar, opts?)` | Subcomando de CLI | -| `api.registerService(service)` | Servicio en segundo plano | -| `api.registerInteractiveHandler(registration)` | Controlador interactivo | +| 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 de CLI | +| `api.registerService(service)` | Servicio en segundo plano | +| `api.registerInteractiveHandler(registration)` | Manejador interactivo | +| `api.registerMemoryPromptSupplement(builder)` | Sección adicional del prompt adyacente a memoria | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus adicional de búsqueda/lectura de memoria | -Los espacios de nombres de administración reservados del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, +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 -ámbito más estrecho a un método del gateway. Prefiere prefijos específicos del plugin para -métodos propiedad del plugin. +alcance más limitado al método del gateway. Prefiere prefijos específicos del plugin para +métodos propios del plugin. -### Metadatos de registro CLI +### Metadatos de registro de CLI `api.registerCli(registrar, opts?)` acepta dos tipos de metadatos de nivel superior: -- `commands`: raíces de comando explícitas propiedad del registrador -- `descriptors`: descriptores de comandos en tiempo de análisis usados para la ayuda de la CLI raíz, - el enrutamiento y el registro perezoso de CLI de plugins +- `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, + enrutamiento y registro perezoso del CLI del plugin -Si quieres que un comando de plugin siga cargándose de forma perezosa en la ruta normal de la CLI raíz, +Si quieres que un comando del plugin permanezca con carga perezosa en la ruta normal del CLI raíz, proporciona `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese registrador. @@ -347,7 +357,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Administrar cuentas de Matrix, verificación, dispositivos y estado del perfil", + description: "Manage Matrix accounts, verification, devices, and profile state", hasSubcommands: true, }, ], @@ -355,7 +365,7 @@ api.registerCli( ); ``` -Usa `commands` por sí solo únicamente cuando no necesites registro perezoso en la CLI raíz. +Usa `commands` por sí solo solo cuando no necesites registro perezoso en el CLI raíz. Esa ruta de compatibilidad ansiosa sigue siendo compatible, pero no instala marcadores respaldados por descriptores para carga perezosa en tiempo de análisis. @@ -370,52 +380,52 @@ marcadores respaldados por descriptores para carga perezosa en tiempo de anális ### 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 | - `registerMemoryPromptSection`, `registerMemoryFlushPlan` y - `registerMemoryRuntime` son exclusivos de los plugins de memoria. -- `registerMemoryEmbeddingProvider` permite al plugin de memoria activo registrar - uno o más IDs de adaptador de embeddings (por ejemplo `openai`, `gemini` o un ID personalizado + `registerMemoryRuntime` son exclusivos para plugins de memoria. +- `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). -- La configuración de usuario, como `agents.defaults.memorySearch.provider` y - `agents.defaults.memorySearch.fallback`, se resuelve contra esos IDs de adaptador +- La configuración del usuario como `agents.defaults.memorySearch.provider` y + `agents.defaults.memorySearch.fallback` se resuelve contra esos ID de adaptadores registrados. ### Eventos y ciclo de vida -| Método | Qué hace | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida | -| `api.onConversationBindingResolved(handler)` | Callback de resolución de vinculación de conversación | +| Método | Qué hace | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Hook tipado del ciclo de vida | +| `api.onConversationBindingResolved(handler)` | Devolución de llamada de vinculación de conversación | -### Semántica de decisiones de hook +### 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 prioridad inferior. +- `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 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 prioridad inferior. +- `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 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 prioridad inferior 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 prioridad inferior. +- `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 ausencia de 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` | Snapshot actual de configuración (snapshot activo en memoria del runtime cuando está disponible) | -| `api.pluginConfig` | `Record` | Configuración específica del plugin desde `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/es/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger con ámbito (`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` | Instantánea de configuración actual (instantánea activa en memoria en tiempo de ejecución cuando está disponible) | +| `api.pluginConfig` | `Record` | Configuración específica del plugin de `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Ayudantes de runtime](/es/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger con alcance (`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` | Resolver ruta relativa a la raíz del plugin | +| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin | ## Convención de módulos internos @@ -424,7 +434,7 @@ Dentro de tu plugin, usa archivos barrel locales para las importaciones internas ``` my-plugin/ api.ts # Exportaciones públicas para consumidores externos - runtime-api.ts # Exportaciones internas de runtime + runtime-api.ts # Exportaciones internas solo para runtime index.ts # Punto de entrada del plugin setup-entry.ts # Entrada ligera solo para configuración (opcional) ``` @@ -435,37 +445,37 @@ my-plugin/ `./runtime-api.ts`. La ruta del SDK es solo el contrato externo. -Las superficies públicas de plugins empaquetados cargadas mediante 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 del runtime cuando OpenClaw ya está en ejecución. Si todavía no existe -un snapshot de runtime, usan como fallback el archivo de configuración resuelto en disco. +Las superficies públicas de plugins incluidos cargadas mediante fachada (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` y archivos de entrada públicos similares) ahora prefieren la +instantánea activa de configuración en tiempo de ejecución cuando OpenClaw ya está en ejecución. Si todavía +no existe una instantánea de runtime, recurren al archivo de configuración resuelto en disco. -Los plugins de proveedor también pueden exponer un barrel de contrato local y concreto cuando un -helper es intencionalmente específico del proveedor y todavía no pertenece a una subruta genérica -del SDK. Ejemplo empaquetado actual: el proveedor Anthropic mantiene sus helpers de stream Claude -en su propio acceso público `api.ts` / `contract-api.ts` en lugar de promocionar la lógica de -encabezados beta de Anthropic y `service_tier` a un contrato genérico +Los plugins de proveedor también pueden exponer un barrel de contrato local y específico del plugin cuando un +ayudante es intencionalmente específico del proveedor y todavía no pertenece a una subruta genérica del SDK. +Ejemplo incluido actual: el proveedor Anthropic mantiene sus ayudantes de flujo Claude +en su propia interfaz pública `api.ts` / `contract-api.ts` en lugar de +promover la lógica de encabezados beta de Anthropic y `service_tier` a un contrato genérico `plugin-sdk/*`. -Otros ejemplos empaquetados actuales: +Otros ejemplos incluidos actuales: -- `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedores, - helpers de modelo predeterminado y constructores de proveedores en tiempo real +- `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedor, + ayudantes de modelo predeterminado y constructores de proveedor en tiempo real - `@openclaw/openrouter-provider`: `api.ts` exporta el constructor del proveedor más - helpers de onboarding/configuración + ayudantes de incorporación/configuración - El código de producción de extensiones también debe evitar importaciones `openclaw/plugin-sdk/`. - Si un helper es realmente compartido, promuévelo a una subruta neutral del SDK + El código de producción de extensiones también debe evitar importaciones de `openclaw/plugin-sdk/`. + Si un ayudante es realmente compartido, promuévelo 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í. + 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` -- [Helpers de runtime](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime` -- [Configuración y config](/es/plugins/sdk-setup) — empaquetado, manifiestos, 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 del plugin](/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/tools/image-generation.md b/docs/es/tools/image-generation.md index 3d8a83a69..fbdd97ebb 100644 --- a/docs/es/tools/image-generation.md +++ b/docs/es/tools/image-generation.md @@ -1,30 +1,30 @@ --- read_when: - - Generar imágenes a través del agente + - Generar imágenes mediante el agente - Configurar proveedores y modelos de generación de imágenes - Comprender los parámetros de la herramienta image_generate -summary: Generar y editar imágenes usando proveedores configurados (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra) +summary: Genera y edita imágenes usando proveedores configurados (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra) title: Generación de imágenes x-i18n: - generated_at: "2026-04-06T03:12:15Z" + generated_at: "2026-04-06T05:12:27Z" model: gpt-5.4 provider: openai - source_hash: dde416dd1441a06605db85b5813cf61ccfc525813d6db430b7b7dfa53d6a3134 + source_hash: 903cc522c283a8da2cbd449ae3e25f349a74d00ecfdaf0f323fd8aa3f2107aea source_path: tools/image-generation.md workflow: 15 --- # Generación de imágenes -La herramienta `image_generate` permite al agente crear y editar imágenes usando tus proveedores configurados. Las imágenes generadas se entregan automáticamente como adjuntos multimedia en la respuesta del agente. +La herramienta `image_generate` permite que el agente cree y edite imágenes usando tus proveedores configurados. Las imágenes generadas se entregan automáticamente como archivos multimedia adjuntos en la respuesta del agente. -La herramienta solo aparece cuando al menos un proveedor de generación de imágenes está disponible. Si no ves `image_generate` en las herramientas de tu agente, configura `agents.defaults.imageGenerationModel` o establece una clave de API del proveedor. +La herramienta solo aparece cuando hay al menos un proveedor de generación de imágenes disponible. Si no ves `image_generate` en las herramientas de tu agente, configura `agents.defaults.imageGenerationModel` o establece una clave de API de un proveedor. ## Inicio rápido -1. Establece una clave de API para al menos un proveedor (por ejemplo `OPENAI_API_KEY` o `GEMINI_API_KEY`). +1. Establece una clave de API para al menos un proveedor (por ejemplo, `OPENAI_API_KEY` o `GEMINI_API_KEY`). 2. Opcionalmente, establece tu modelo preferido: ```json5 @@ -41,18 +41,18 @@ La herramienta solo aparece cuando al menos un proveedor de generación de imág 3. Pídele al agente: _"Genera una imagen de una mascota langosta amistosa."_ -El agente llama a `image_generate` automáticamente. No hace falta una lista de permitidos de herramientas: está habilitada de forma predeterminada cuando hay un proveedor disponible. +El agente llama a `image_generate` automáticamente. No se necesita ninguna lista de permitidos de herramientas; está habilitada de forma predeterminada cuando hay un proveedor disponible. ## Proveedores compatibles -| Provider | Modelo predeterminado | Compatibilidad de edición | Clave de API | -| -------- | -------------------------------- | ---------------------------------- | ------------------------------------------------------- | -| OpenAI | `gpt-image-1` | Sí (hasta 5 imágenes) | `OPENAI_API_KEY` | -| Google | `gemini-3.1-flash-image-preview` | Sí | `GEMINI_API_KEY` o `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | Sí | `FAL_KEY` | -| MiniMax | `image-01` | Sí (referencia de sujeto) | `MINIMAX_API_KEY` o OAuth de MiniMax (`minimax-portal`) | -| ComfyUI | `workflow` | Sí (1 imagen, configurada por workflow) | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` para cloud | -| Vydra | `grok-imagine` | No | `VYDRA_API_KEY` | +| Proveedor | Modelo predeterminado | Compatibilidad con edición | Clave de API | +| --------- | -------------------------------- | ---------------------------------- | ------------------------------------------------------- | +| OpenAI | `gpt-image-1` | Sí (hasta 5 imágenes) | `OPENAI_API_KEY` | +| Google | `gemini-3.1-flash-image-preview` | Sí | `GEMINI_API_KEY` o `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | Sí | `FAL_KEY` | +| MiniMax | `image-01` | Sí (referencia de sujeto) | `MINIMAX_API_KEY` o OAuth de MiniMax (`minimax-portal`) | +| ComfyUI | `workflow` | Sí (1 imagen, configurada por flujo de trabajo) | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` para la nube | +| Vydra | `grok-imagine` | No | `VYDRA_API_KEY` | Usa `action: "list"` para inspeccionar los proveedores y modelos disponibles en tiempo de ejecución: @@ -62,20 +62,20 @@ Usa `action: "list"` para inspeccionar los proveedores y modelos disponibles en ## Parámetros de la herramienta -| Parameter | Type | Descripción | +| Parámetro | Tipo | Descripción | | ------------- | -------- | ------------------------------------------------------------------------------------ | | `prompt` | string | Prompt de generación de imágenes (obligatorio para `action: "generate"`) | | `action` | string | `"generate"` (predeterminado) o `"list"` para inspeccionar proveedores | | `model` | string | Anulación de proveedor/modelo, por ejemplo `openai/gpt-image-1` | -| `image` | string | Ruta o URL de una sola imagen de referencia para el modo edición | -| `images` | string[] | Varias imágenes de referencia para el modo edición (hasta 5) | +| `image` | string | Ruta o URL de una sola imagen de referencia para el modo de edición | +| `images` | string[] | Varias imágenes de referencia para el modo de edición (hasta 5) | | `size` | string | Sugerencia de tamaño: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024` | | `aspectRatio` | string | Relación de aspecto: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | | `resolution` | string | Sugerencia de resolución: `1K`, `2K` o `4K` | -| `count` | number | Número de imágenes a generar (1–4) | +| `count` | number | Número de imágenes que se van a generar (1–4) | | `filename` | string | Sugerencia de nombre de archivo de salida | -No todos los proveedores admiten todos los parámetros. La herramienta pasa lo que cada proveedor admite, ignora el resto e informa de las anulaciones descartadas en el resultado de la herramienta. +No todos los proveedores admiten todos los parámetros. La herramienta pasa lo que cada proveedor admite, ignora el resto e informa las anulaciones descartadas en el resultado de la herramienta. ## Configuración @@ -98,23 +98,25 @@ No todos los proveedores admiten todos los parámetros. La herramienta pasa lo q Al generar una imagen, OpenClaw prueba los proveedores en este orden: -1. **Parámetro `model`** de la llamada a la herramienta (si el agente especifica uno) +1. El parámetro **`model`** de la llamada a la herramienta (si el agente especifica uno) 2. **`imageGenerationModel.primary`** de la configuración 3. **`imageGenerationModel.fallbacks`** en orden 4. **Detección automática** — usa solo valores predeterminados de proveedores respaldados por autenticación: - primero el proveedor predeterminado actual - - luego los proveedores restantes de generación de imágenes registrados, en orden de id de proveedor + - luego los proveedores de generación de imágenes registrados restantes en orden de ID de proveedor -Si un proveedor falla (error de autenticación, límite de tasa, etc.), se prueba automáticamente el siguiente candidato. Si todos fallan, el error incluye detalles de cada intento. +Si un proveedor falla (error de autenticación, límite de velocidad, etc.), se prueba automáticamente el siguiente candidato. Si todos fallan, el error incluye detalles de cada intento. Notas: -- La detección automática es consciente de la autenticación. Un valor predeterminado de proveedor solo entra en la lista de candidatos cuando OpenClaw puede autenticar realmente ese proveedor. -- Usa `action: "list"` para inspeccionar los proveedores actualmente registrados, sus modelos predeterminados y las sugerencias de variables de entorno de autenticación. +- La detección automática tiene en cuenta la autenticación. Un valor predeterminado de proveedor solo entra en la lista de candidatos + cuando OpenClaw realmente puede autenticar ese proveedor. +- Usa `action: "list"` para inspeccionar los proveedores registrados actualmente, sus + modelos predeterminados y las sugerencias de variables de entorno para autenticación. ### Edición de imágenes -OpenAI, Google, fal, MiniMax y ComfyUI admiten edición de imágenes de referencia. Pasa una ruta o URL de imagen de referencia: +OpenAI, Google, fal, MiniMax y ComfyUI admiten la edición de imágenes de referencia. Pasa una ruta o URL de imagen de referencia: ``` "Genera una versión en acuarela de esta foto" + image: "/path/to/photo.jpg" @@ -122,29 +124,29 @@ OpenAI, Google, fal, MiniMax y ComfyUI admiten edición de imágenes de referenc OpenAI y Google admiten hasta 5 imágenes de referencia mediante el parámetro `images`. fal, MiniMax y ComfyUI admiten 1. -La generación de imágenes de MiniMax está disponible a través de ambas rutas integradas de autenticación de MiniMax: +La generación de imágenes de MiniMax está disponible a través de ambas rutas de autenticación MiniMax incluidas: - `minimax/image-01` para configuraciones con clave de API - `minimax-portal/image-01` para configuraciones con OAuth ## Capacidades del proveedor -| Capability | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | -| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ----- | -| Generar | Sí (hasta 4) | Sí (hasta 4) | Sí (hasta 4) | Sí (hasta 9) | Sí (salidas definidas por workflow) | Sí (1) | -| Edición/referencia | Sí (hasta 5 imágenes) | Sí (hasta 5 imágenes) | Sí (1 imagen) | Sí (1 imagen, ref. de sujeto) | Sí (1 imagen, configurada por workflow) | No | -| Control de tamaño | Sí | Sí | Sí | No | No | No | -| Relación de aspecto | No | Sí | Sí (solo generar) | Sí | No | No | -| Resolución (1K/2K/4K) | No | Sí | Sí | No | No | No | +| Capacidad | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | +| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | +| Generar | Sí (hasta 4) | Sí (hasta 4) | Sí (hasta 4) | Sí (hasta 9) | Sí (salidas definidas por el flujo de trabajo) | Sí (1) | +| Edición/referencia | Sí (hasta 5 imágenes) | Sí (hasta 5 imágenes) | Sí (1 imagen) | Sí (1 imagen, ref. de sujeto) | Sí (1 imagen, configurada por flujo de trabajo) | No | +| Control de tamaño | Sí | Sí | Sí | No | No | No | +| Relación de aspecto | No | Sí | Sí (solo generación) | Sí | No | No | +| Resolución (1K/2K/4K) | No | Sí | Sí | No | No | No | ## Relacionado -- [Resumen de herramientas](/es/tools) — todas las herramientas de agente disponibles -- [fal](/providers/fal) — configuración del proveedor de imágenes y video de fal -- [ComfyUI](/providers/comfy) — configuración de workflows de ComfyUI local y Comfy Cloud +- [Resumen de herramientas](/es/tools) — todas las herramientas del agente disponibles +- [fal](/es/providers/fal) — configuración del proveedor de imágenes y video de fal +- [ComfyUI](/es/providers/comfy) — configuración de flujos de trabajo locales de ComfyUI y Comfy Cloud - [Google (Gemini)](/es/providers/google) — configuración del proveedor de imágenes Gemini - [MiniMax](/es/providers/minimax) — configuración del proveedor de imágenes MiniMax - [OpenAI](/es/providers/openai) — configuración del proveedor OpenAI Images -- [Vydra](/providers/vydra) — configuración de imágenes, video y voz de Vydra -- [Referencia de configuración](/es/gateway/configuration-reference#agent-defaults) — configuración `imageGenerationModel` -- [Models](/es/concepts/models) — configuración de modelos y failover +- [Vydra](/es/providers/vydra) — configuración de imágenes, video y voz de Vydra +- [Referencia de configuración](/es/gateway/configuration-reference#agent-defaults) — configuración de `imageGenerationModel` +- [Modelos](/es/concepts/models) — configuración de modelos y conmutación por error diff --git a/docs/es/tools/video-generation.md b/docs/es/tools/video-generation.md index ca820529a..2f4bf6a9a 100644 --- a/docs/es/tools/video-generation.md +++ b/docs/es/tools/video-generation.md @@ -2,29 +2,29 @@ read_when: - Generar videos mediante el agente - Configurar proveedores y modelos de generación de video - - Comprender los parámetros de la herramienta video_generate -summary: Generar videos a partir de texto, imágenes o videos existentes usando 12 backends de proveedor + - Comprender los parámetros de la herramienta `video_generate` +summary: Genera videos a partir de texto, imágenes o videos existentes mediante 12 backends de proveedores title: Generación de video x-i18n: - generated_at: "2026-04-06T03:13:12Z" + generated_at: "2026-04-06T05:12:32Z" model: gpt-5.4 provider: openai - source_hash: 4afec87368232221db1aa5a3980254093d6a961b17271b2dcbf724e6bd455b16 + source_hash: 90d8a392b35adbd899232b02c55c10895b9d7ffc9858d6ca448f2e4e4a57f12f source_path: tools/video-generation.md workflow: 15 --- # Generación de video -Los agentes de OpenClaw pueden generar videos a partir de prompts de texto, imágenes de referencia o videos existentes. Se admiten doce backends de proveedor, cada uno con distintas opciones de modelo, modos de entrada y conjuntos de funciones. El agente elige automáticamente el proveedor adecuado según tu configuración y las claves de API disponibles. +Los agentes de OpenClaw pueden generar videos a partir de indicaciones de texto, imágenes de referencia o videos existentes. Se admiten doce backends de proveedores, cada uno con distintas opciones de modelo, modos de entrada y conjuntos de funciones. El agente elige automáticamente el proveedor adecuado según tu configuración y las claves de API disponibles. -La herramienta `video_generate` solo aparece cuando al menos un proveedor de generación de video está disponible. Si no la ves en las herramientas de tu agente, establece una clave de API del proveedor o configura `agents.defaults.videoGenerationModel`. +La herramienta `video_generate` solo aparece cuando hay al menos un proveedor de generación de video disponible. Si no la ves en las herramientas de tu agente, configura una clave de API del proveedor o establece `agents.defaults.videoGenerationModel`. ## Inicio rápido -1. Establece una clave de API para cualquier proveedor compatible: +1. Configura una clave de API para cualquier proveedor compatible: ```bash export GEMINI_API_KEY="your-key" @@ -36,13 +36,13 @@ export GEMINI_API_KEY="your-key" openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` -3. Pídele al agente: +3. Pídeselo al agente: -> Genera un video cinematográfico de 5 segundos de una langosta amigable surfeando al atardecer. +> Genera un video cinematográfico de 5 segundos de una langosta amistosa surfeando al atardecer. -El agente llama a `video_generate` automáticamente. No se necesita lista de permitidos para herramientas. +El agente llama a `video_generate` automáticamente. No se necesita ninguna lista de herramientas permitidas. -## Qué ocurre cuando generas un video +## Qué sucede cuando generas un video La generación de video es asíncrona. Cuando el agente llama a `video_generate` en una sesión: @@ -51,28 +51,28 @@ La generación de video es asíncrona. Cuando el agente llama a `video_generate` 3. Cuando el video está listo, OpenClaw reactiva la misma sesión con un evento interno de finalización. 4. El agente publica el video terminado de vuelta en la conversación original. -Mientras un trabajo está en curso, las llamadas duplicadas a `video_generate` en la misma sesión devuelven el estado actual de la tarea en lugar de iniciar otra generación. Usa `openclaw tasks list` o `openclaw tasks show ` para comprobar el progreso desde la CLI. +Mientras una tarea está en curso, las llamadas duplicadas a `video_generate` en la misma sesión devuelven el estado actual de la tarea en lugar de iniciar otra generación. Usa `openclaw tasks list` o `openclaw tasks show ` para comprobar el progreso desde la CLI. -Fuera de las ejecuciones de agente respaldadas por sesión (por ejemplo, invocaciones directas de herramientas), la herramienta recurre a la generación en línea y devuelve la ruta final del medio en el mismo turno. +Fuera de las ejecuciones del agente respaldadas por sesión (por ejemplo, invocaciones directas de herramientas), la herramienta recurre a la generación en línea y devuelve la ruta del medio final en el mismo turno. ## Proveedores compatibles -| Provider | Modelo predeterminado | Texto | Ref. de imagen | Ref. de video | Clave de API | -| -------- | ------------------------------- | ----- | ----------------- | ----------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | Sí | Sí (URL remota) | Sí (URL remota) | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | Sí | 1 imagen | No | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Sí | 1 imagen | No | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Sí | 1 imagen | No | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | Sí | 1 imagen | 1 video | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Sí | 1 imagen | No | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | Sí | 1 imagen | 1 video | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Sí | Sí (URL remota) | Sí (URL remota) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Sí | 1 imagen | 1 video | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sí | 1 imagen | No | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Sí | 1 imagen (`kling`) | No | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Sí | 1 imagen | 1 video | `XAI_API_KEY` | +| Proveedor | Modelo predeterminado | Texto | Imagen de ref. | Video de ref. | Clave de API | +| --------- | ------------------------------- | ----- | ----------------- | ---------------- | ----------------------------------------- | +| Alibaba | `wan2.6-t2v` | Sí | Sí (URL remota) | Sí (URL remota) | `MODELSTUDIO_API_KEY` | +| BytePlus | `seedance-1-0-lite-t2v-250428` | Sí | 1 imagen | No | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Sí | 1 imagen | No | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Sí | 1 imagen | No | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Sí | 1 imagen | 1 video | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Sí | 1 imagen | No | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Sí | 1 imagen | 1 video | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Sí | Sí (URL remota) | Sí (URL remota) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Sí | 1 imagen | 1 video | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sí | 1 imagen | No | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Sí | 1 imagen (`kling`) | No | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Sí | 1 imagen | 1 video | `XAI_API_KEY` | -Algunos proveedores aceptan variables de entorno adicionales o alternativas para la clave de API. Consulta las páginas individuales de [proveedores](#related) para más detalles. +Algunos proveedores aceptan variables de entorno de clave de API adicionales o alternativas. Consulta las [páginas de proveedores](#related) individuales para obtener más detalles. Ejecuta `video_generate action=list` para inspeccionar los proveedores y modelos disponibles en tiempo de ejecución. @@ -80,13 +80,13 @@ Ejecuta `video_generate action=list` para inspeccionar los proveedores y modelos ### Obligatorios -| Parameter | Type | Descripción | -| --------- | ------ | ------------------------------------------------------------------------------- | -| `prompt` | string | Descripción en texto del video que se va a generar (obligatorio para `action: "generate"`) | +| Parámetro | Tipo | Descripción | +| --------- | ------ | ---------------------------------------------------------------------------- | +| `prompt` | string | Descripción de texto del video que se va a generar (obligatoria para `action: "generate"`) | ### Entradas de contenido -| Parameter | Type | Descripción | +| Parámetro | Tipo | Descripción | | --------- | -------- | ---------------------------------------- | | `image` | string | Una sola imagen de referencia (ruta o URL) | | `images` | string[] | Varias imágenes de referencia (hasta 5) | @@ -95,28 +95,28 @@ Ejecuta `video_generate action=list` para inspeccionar los proveedores y modelos ### Controles de estilo -| Parameter | Type | Descripción | -| ----------------- | ------- | ----------------------------------------------------------------------- | -| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | `480P`, `720P` o `1080P` | -| `durationSeconds` | number | Duración objetivo en segundos (redondeada al valor compatible más cercano del proveedor) | -| `size` | string | Sugerencia de tamaño cuando el proveedor lo admite | -| `audio` | boolean | Habilita audio generado cuando se admite | -| `watermark` | boolean | Activa o desactiva la marca de agua del proveedor cuando se admite | +| Parámetro | Tipo | Descripción | +| ---------------- | ------- | ----------------------------------------------------------------------- | +| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | +| `resolution` | string | `480P`, `720P` o `1080P` | +| `durationSeconds` | number | Duración objetivo en segundos (redondeada al valor compatible más cercano del proveedor) | +| `size` | string | Indicación de tamaño cuando el proveedor lo admite | +| `audio` | boolean | Habilita el audio generado cuando se admite | +| `watermark` | boolean | Activa o desactiva la marca de agua del proveedor cuando se admite | ### Avanzados -| Parameter | Type | Descripción | -| ---------- | ------ | ---------------------------------------------- | -| `action` | string | `"generate"` (predeterminado), `"status"` o `"list"` | -| `model` | string | Anulación de proveedor/modelo (por ejemplo `runway/gen4.5`) | -| `filename` | string | Sugerencia de nombre de archivo de salida | +| Parámetro | Tipo | Descripción | +| --------- | ------ | ---------------------------------------------- | +| `action` | string | `"generate"` (predeterminado), `"status"` o `"list"` | +| `model` | string | Anulación de proveedor/modelo (por ejemplo, `runway/gen4.5`) | +| `filename` | string | Sugerencia de nombre de archivo de salida | -No todos los proveedores admiten todos los parámetros. Las anulaciones no compatibles se ignoran en base a best-effort y se informan como advertencias en el resultado de la herramienta. Los límites estrictos de capacidad (como demasiadas entradas de referencia) fallan antes del envío. +No todos los proveedores admiten todos los parámetros. Las anulaciones no compatibles se ignoran según el mejor esfuerzo y se informan como advertencias en el resultado de la herramienta. Los límites estrictos de capacidad (como demasiadas entradas de referencia) fallan antes del envío. ## Acciones -- **generate** (predeterminada) -- crea un video a partir del prompt dado y entradas de referencia opcionales. +- **generate** (predeterminada) -- crea un video a partir de la indicación dada y entradas de referencia opcionales. - **status** -- comprueba el estado de la tarea de video en curso para la sesión actual sin iniciar otra generación. - **list** -- muestra los proveedores, modelos y sus capacidades disponibles. @@ -127,7 +127,7 @@ Al generar un video, OpenClaw resuelve el modelo en este orden: 1. **Parámetro de herramienta `model`** -- si el agente especifica uno en la llamada. 2. **`videoGenerationModel.primary`** -- desde la configuración. 3. **`videoGenerationModel.fallbacks`** -- se prueban en orden. -4. **Detección automática** -- usa proveedores que tienen autenticación válida, empezando por el proveedor predeterminado actual y luego los proveedores restantes en orden alfabético. +4. **Detección automática** -- usa los proveedores que tienen autenticación válida, comenzando por el proveedor predeterminado actual y luego los proveedores restantes en orden alfabético. Si un proveedor falla, se prueba automáticamente el siguiente candidato. Si todos los candidatos fallan, el error incluye detalles de cada intento. @@ -146,20 +146,20 @@ Si un proveedor falla, se prueba automáticamente el siguiente candidato. Si tod ## Notas sobre proveedores -| Provider | Notas | -| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Usa el endpoint asíncrono de DashScope/Model Studio. Las imágenes y videos de referencia deben ser URL remotas `http(s)`. | -| BytePlus | Solo una imagen de referencia. | -| ComfyUI | Ejecución local o cloud impulsada por workflows. Admite texto a video e imagen a video mediante el grafo configurado. | -| fal | Usa un flujo respaldado por cola para trabajos de larga duración. Solo una imagen de referencia. | -| Google | Usa Gemini/Veo. Admite una imagen o un video de referencia. | -| MiniMax | Solo una imagen de referencia. | -| OpenAI | Solo se reenvía la anulación `size`. Otras anulaciones de estilo (`aspectRatio`, `resolution`, `audio`, `watermark`) se ignoran con advertencia. | -| Qwen | Mismo backend DashScope que Alibaba. Las entradas de referencia deben ser URL remotas `http(s)`; los archivos locales se rechazan de entrada. | -| Runway | Admite archivos locales mediante URI de datos. Video a video requiere `runway/gen4_aleph`. Las ejecuciones de solo texto exponen relaciones de aspecto `16:9` y `9:16`. | -| Together | Solo una imagen de referencia. | -| Vydra | Usa `https://www.vydra.ai/api/v1` directamente para evitar redirecciones que eliminan la autenticación. `veo3` está integrado solo como texto a video; `kling` requiere una URL de imagen remota. | -| xAI | Admite flujos de texto a video, imagen a video y edición/extensión de video remoto. | +| Proveedor | Notas | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Alibaba | Usa el endpoint asíncrono de DashScope/Model Studio. Las imágenes y videos de referencia deben ser URL `http(s)` remotas. | +| BytePlus | Solo admite una imagen de referencia. | +| ComfyUI | Ejecución local o en la nube basada en flujos de trabajo. Admite texto a video e imagen a video mediante el grafo configurado. | +| fal | Usa un flujo respaldado por cola para trabajos de larga duración. Solo admite una imagen de referencia. | +| Google | Usa Gemini/Veo. Admite una imagen o un video de referencia. | +| MiniMax | Solo admite una imagen de referencia. | +| OpenAI | Solo se reenvía la anulación `size`. Las demás anulaciones de estilo (`aspectRatio`, `resolution`, `audio`, `watermark`) se ignoran con una advertencia. | +| Qwen | El mismo backend de DashScope que Alibaba. Las entradas de referencia deben ser URL `http(s)` remotas; los archivos locales se rechazan por adelantado. | +| Runway | Admite archivos locales mediante URI de datos. Video a video requiere `runway/gen4_aleph`. Las ejecuciones solo con texto exponen las relaciones de aspecto `16:9` y `9:16`. | +| Together | Solo admite una imagen de referencia. | +| Vydra | Usa `https://www.vydra.ai/api/v1` directamente para evitar redirecciones que eliminan la autenticación. `veo3` se incluye solo como texto a video; `kling` requiere una URL de imagen remota. | +| xAI | Admite flujos de texto a video, imagen a video y edición/extensión de video remoto. | ## Configuración @@ -187,18 +187,18 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Relacionado - [Resumen de herramientas](/es/tools) -- [Tareas en segundo plano](/es/automation/tasks) -- seguimiento de tareas para generación de video asíncrona -- [Alibaba Model Studio](/providers/alibaba) -- [BytePlus](/providers/byteplus) -- [ComfyUI](/providers/comfy) -- [fal](/providers/fal) +- [Tareas en segundo plano](/es/automation/tasks) -- seguimiento de tareas para la generación asíncrona de video +- [Alibaba Model Studio](/es/providers/alibaba) +- [BytePlus](/es/concepts/model-providers#byteplus-international) +- [ComfyUI](/es/providers/comfy) +- [fal](/es/providers/fal) - [Google (Gemini)](/es/providers/google) - [MiniMax](/es/providers/minimax) - [OpenAI](/es/providers/openai) - [Qwen](/es/providers/qwen) -- [Runway](/providers/runway) +- [Runway](/es/providers/runway) - [Together AI](/es/providers/together) -- [Vydra](/providers/vydra) +- [Vydra](/es/providers/vydra) - [xAI](/es/providers/xai) - [Referencia de configuración](/es/gateway/configuration-reference#agent-defaults) -- [Models](/es/concepts/models) +- [Modelos](/es/concepts/models)