diff --git a/docs/es/channels/qqbot.md b/docs/es/channels/qqbot.md index c89cd5799..65898aa64 100644 --- a/docs/es/channels/qqbot.md +++ b/docs/es/channels/qqbot.md @@ -1,24 +1,24 @@ --- read_when: - Quieres conectar OpenClaw con QQ - - Debe configurar las credenciales de QQ Bot - - Quieres soporte para chats grupales o privados de QQ Bot -summary: Instalación, configuración y uso de QQ Bot + - Necesitas configurar las credenciales de QQ Bot + - Quieres compatibilidad con chats grupales o privados de QQ Bot +summary: Configuración, ajustes y uso de QQ Bot title: bot de QQ x-i18n: - generated_at: "2026-04-30T05:30:21Z" + generated_at: "2026-04-30T09:34:47Z" model: gpt-5.5 provider: openai - source_hash: aefece6b05bb16d5c4f588bf7af4fd710b5f98aab0dbed8221490c46bf3f379c + source_hash: 964a92021acc534b7ec2749670fedd0e8caa47d5edf67ced80f0a8fb3eda7600 source_path: channels/qqbot.md workflow: 16 --- QQ Bot se conecta a OpenClaw mediante la API oficial de QQ Bot (Gateway WebSocket). El -Plugin admite chat privado C2C, @mensajes de grupo y mensajes de canal de gremio con +Plugin admite chat privado C2C, @mensajes de grupo y mensajes de canales de gremio con medios enriquecidos (imágenes, voz, video, archivos). -Estado: Plugin incluido. Se admiten mensajes directos, chats grupales, canales de gremio y +Estado: Plugin incluido. Se admiten mensajes directos, chats de grupo, canales de gremio y medios. No se admiten reacciones ni hilos. ## Plugin incluido @@ -26,17 +26,17 @@ medios. No se admiten reacciones ni hilos. Las versiones actuales de OpenClaw incluyen QQ Bot, por lo que las compilaciones empaquetadas normales no necesitan un paso separado de `openclaw plugins install`. -## Configuración inicial +## Configuración 1. Ve a [QQ Open Platform](https://q.qq.com/) y escanea el código QR con tu QQ del teléfono para registrarte / iniciar sesión. -2. Haz clic en **Create Bot** para crear un nuevo bot de QQ. +2. Haz clic en **Crear bot** para crear un nuevo bot de QQ. 3. Busca **AppID** y **AppSecret** en la página de configuración del bot y cópialos. > AppSecret no se almacena en texto sin formato; si sales de la página sin guardarlo, > tendrás que regenerar uno nuevo. -4. Añade el canal: +4. Agrega el canal: ```bash openclaw channels add --channel qqbot --token "AppID:AppSecret" @@ -88,12 +88,12 @@ AppSecret respaldado por archivo: Notas: -- La reserva por entorno se aplica solo a la cuenta predeterminada de QQ Bot. +- La reserva de entorno se aplica solo a la cuenta predeterminada de QQ Bot. - `openclaw channels add --channel qqbot --token-file ...` proporciona solo el - AppSecret; el AppID ya debe estar definido en la configuración o en `QQBOT_APP_ID`. -- `clientSecret` también acepta entrada SecretRef, no solo una cadena en texto sin formato. + AppSecret; el AppID ya debe estar establecido en la configuración o en `QQBOT_APP_ID`. +- `clientSecret` también acepta entrada SecretRef, no solo una cadena de texto sin formato. -### Configuración de múltiples cuentas +### Configuración de varias cuentas Ejecuta varios bots de QQ en una sola instancia de OpenClaw: @@ -119,16 +119,16 @@ Ejecuta varios bots de QQ en una sola instancia de OpenClaw: Cada cuenta inicia su propia conexión WebSocket y mantiene una caché de tokens independiente (aislada por `appId`). -Añade un segundo bot mediante CLI: +Agrega un segundo bot mediante la CLI: ```bash openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" ``` -### Chats grupales +### Chats de grupo -La compatibilidad de QQ Bot con chats grupales usa OpenIDs de grupos de QQ, no nombres visibles. Añade el bot -a un grupo y luego menciónalo o configura el grupo para que se ejecute sin mención. +La compatibilidad de QQ Bot con chats de grupo usa OpenIDs de grupos de QQ, no nombres para mostrar. Agrega el bot +a un grupo y luego menciónalo o configura el grupo para ejecutarse sin mención. ```json5 { @@ -155,30 +155,30 @@ a un grupo y luego menciónalo o configura el grupo para que se ejecute sin menc } ``` -`groups["*"]` define los valores predeterminados para cada grupo, y una entrada concreta -`groups.GROUP_OPENID` anula esos valores para un grupo. La configuración de grupo +`groups["*"]` establece valores predeterminados para cada grupo, y una entrada concreta +`groups.GROUP_OPENID` anula esos valores predeterminados para un grupo. La configuración de grupo incluye: - `requireMention`: requiere una @mención antes de que el bot responda. Predeterminado: `true`. -- `ignoreOtherMentions`: descarta mensajes que mencionen a otra persona pero no al bot. -- `historyLimit`: conserva mensajes grupales recientes sin mención como contexto para el siguiente turno mencionado. Establece `0` para desactivar. +- `ignoreOtherMentions`: descarta mensajes que mencionan a otra persona pero no al bot. +- `historyLimit`: conserva los mensajes recientes de grupo sin mención como contexto para el siguiente turno mencionado. Establece `0` para desactivarlo. - `toolPolicy`: `full`, `restricted` o `none` para herramientas con alcance de grupo. -- `name`: etiqueta legible usada en registros y contexto de grupo. -- `prompt`: indicación de comportamiento por grupo añadida al contexto del agente. +- `name`: etiqueta descriptiva usada en registros y contexto de grupo. +- `prompt`: indicación de comportamiento por grupo agregada al contexto del agente. Los modos de activación son `mention` y `always`. `requireMention: true` se asigna a `mention`; `requireMention: false` se asigna a `always`. Una anulación de activación a nivel de sesión, -cuando está presente, prevalece sobre la configuración. +cuando existe, prevalece sobre la configuración. -La cola entrante es por par. Los pares de grupo tienen un límite de cola mayor, mantienen los mensajes -humanos por delante de la conversación generada por el bot cuando está llena, y fusionan ráfagas de mensajes -grupales normales en un solo turno atribuido. Los comandos de barra siguen ejecutándose uno por uno. +La cola entrante es por par. Los pares de grupo tienen un límite de cola mayor, mantienen los +mensajes humanos por delante de la conversación generada por bots cuando está llena, y fusionan ráfagas de mensajes normales +de grupo en un turno atribuido. Los comandos de barra siguen ejecutándose uno por uno. ### Voz (STT / TTS) -La compatibilidad con STT y TTS usa configuración de dos niveles con reserva por prioridad: +La compatibilidad con STT y TTS admite configuración de dos niveles con reserva por prioridad: -| Ajuste | Específico del Plugin | Reserva del framework | +| Configuración | Específica del Plugin | Reserva del framework | | ------- | -------------------------------------------------------- | ----------------------------- | | STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | | TTS | `channels.qqbot.tts`, `channels.qqbot.accounts..tts` | `messages.tts` | @@ -210,12 +210,12 @@ La compatibilidad con STT y TTS usa configuración de dos niveles con reserva po } ``` -Establece `enabled: false` en cualquiera de los dos para desactivar. +Establece `enabled: false` en cualquiera de los dos para desactivarlo. Las anulaciones de TTS a nivel de cuenta usan la misma forma que `messages.tts` y se fusionan en profundidad -sobre la configuración TTS del canal/global. +sobre la configuración de TTS del canal/global. -Los adjuntos de voz entrantes de QQ se exponen a los agentes como metadatos de medios de audio, mientras -mantienen los archivos de voz sin procesar fuera de los `MediaPaths` genéricos. Las respuestas de texto sin formato +Los archivos adjuntos de voz entrantes de QQ se exponen a los agentes como metadatos de medios de audio mientras +se mantienen los archivos de voz sin procesar fuera de los `MediaPaths` genéricos. Las respuestas de texto sin formato `[[audio_as_voice]]` sintetizan TTS y envían un mensaje de voz nativo de QQ cuando TTS está configurado. @@ -231,61 +231,64 @@ El comportamiento de carga/transcodificación de audio saliente también se pued | Formato | Descripción | | -------------------------- | ------------------ | | `qqbot:c2c:OPENID` | Chat privado (C2C) | -| `qqbot:group:GROUP_OPENID` | Chat grupal | +| `qqbot:group:GROUP_OPENID` | Chat de grupo | | `qqbot:channel:CHANNEL_ID` | Canal de gremio | -> Cada bot tiene su propio conjunto de OpenIDs de usuario. Un OpenID recibido por el Bot A **no puede** -> usarse para enviar mensajes mediante el Bot B. +> Cada bot tiene su propio conjunto de OpenIDs de usuario. Un OpenID recibido por el bot A **no puede** +> usarse para enviar mensajes mediante el bot B. ## Comandos de barra Comandos integrados interceptados antes de la cola de IA: -| Comando | Descripción | -| -------------- | -------------------------------------------------------------------------------------------------------------- | -| `/bot-ping` | Prueba de latencia | -| `/bot-version` | Muestra la versión del framework de OpenClaw | -| `/bot-help` | Enumera todos los comandos | -| `/bot-upgrade` | Muestra el enlace a la guía de actualización de QQBot | -| `/bot-logs` | Exporta registros recientes del Gateway como archivo | +| Comando | Descripción | +| -------------- | -------------------------------------------------------------------------------------------------------- | +| `/bot-ping` | Prueba de latencia | +| `/bot-version` | Muestra la versión del framework de OpenClaw | +| `/bot-help` | Lista todos los comandos | +| `/bot-me` | Muestra el ID de usuario de QQ del remitente (openid) para configurar `allowFrom`/`groupAllowFrom` | +| `/bot-upgrade` | Muestra el enlace de la guía de actualización de QQBot | +| `/bot-logs` | Exporta los registros recientes del gateway como archivo | | `/bot-approve` | Aprueba una acción pendiente de QQ Bot (por ejemplo, confirmar una carga C2C o de grupo) mediante el flujo nativo. | -Añade `?` a cualquier comando para obtener ayuda de uso (por ejemplo, `/bot-upgrade ?`). +Agrega `?` a cualquier comando para obtener ayuda de uso (por ejemplo `/bot-upgrade ?`). + +Los comandos de administrador (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) son solo para mensajes directos y requieren que el openid del remitente esté en una lista `allowFrom` explícita y sin comodines. Un comodín `allowFrom: ["*"]` permite chatear, pero no concede acceso a comandos de administrador. Los mensajes de grupo se comparan primero con `groupAllowFrom` y recurren a `allowFrom`. Ejecutar un comando de administrador en un grupo devuelve una sugerencia en lugar de descartarlo silenciosamente. ## Arquitectura del motor -QQ Bot se distribuye como un motor autocontenido dentro del Plugin: +QQ Bot se distribuye como un motor autónomo dentro del Plugin: -- Cada cuenta posee una pila de recursos aislada (conexión WebSocket, cliente de API, caché de tokens, raíz de almacenamiento de medios) con clave por `appId`. Las cuentas nunca comparten estado entrante/saliente. -- El registrador de múltiples cuentas etiqueta las líneas de registro con la cuenta propietaria para que los diagnósticos sigan siendo separables cuando ejecutas varios bots bajo un Gateway. -- Las rutas de entrada, salida y puente del Gateway comparten una única raíz de carga útil de medios bajo `~/.openclaw/media`, de modo que las cargas, descargas y cachés de transcodificación se ubican bajo un directorio protegido en lugar de un árbol por subsistema. -- La entrega de medios enriquecidos pasa por una única ruta `sendMedia` para destinos C2C y de grupo. Los archivos locales y búferes por encima del umbral de archivos grandes usan los endpoints de carga por fragmentos de QQ, mientras que las cargas útiles más pequeñas usan la API de medios de una sola operación. -- Las credenciales pueden incluirse en copias de seguridad y restaurarse como parte de las instantáneas estándar de credenciales de OpenClaw; el motor vuelve a adjuntar la pila de recursos de cada cuenta al restaurar sin requerir un nuevo par por código QR. +- Cada cuenta posee una pila de recursos aislada (conexión WebSocket, cliente de API, caché de tokens, raíz de almacenamiento de medios) identificada por `appId`. Las cuentas nunca comparten estado entrante/saliente. +- El registrador de varias cuentas etiqueta las líneas de registro con la cuenta propietaria para que los diagnósticos sigan siendo separables cuando ejecutas varios bots bajo un Gateway. +- Las rutas entrantes, salientes y del puente del Gateway comparten una sola raíz de carga útil de medios bajo `~/.openclaw/media`, por lo que cargas, descargas y cachés de transcodificación quedan bajo un directorio protegido en lugar de un árbol por subsistema. +- La entrega de medios enriquecidos pasa por una sola ruta `sendMedia` para destinos C2C y de grupo. Los archivos locales y búferes por encima del umbral de archivos grandes usan los endpoints de carga fragmentada de QQ, mientras que las cargas útiles más pequeñas usan la API de medios de una sola operación. +- Las credenciales pueden respaldarse y restaurarse como parte de las instantáneas estándar de credenciales de OpenClaw; el motor vuelve a adjuntar la pila de recursos de cada cuenta al restaurar sin requerir un nuevo emparejamiento por código QR. -## Vinculación con código QR +## Incorporación con código QR -Como alternativa a pegar `AppID:AppSecret` manualmente, el motor admite un flujo de vinculación con código QR para conectar un QQ Bot a OpenClaw: +Como alternativa a pegar `AppID:AppSecret` manualmente, el motor admite un flujo de incorporación con código QR para vincular un QQ Bot a OpenClaw: 1. Ejecuta la ruta de configuración de QQ Bot (por ejemplo `openclaw channels add --channel qqbot`) y elige el flujo de código QR cuando se te solicite. -2. Escanea el código QR generado con la app del teléfono asociada al QQ Bot de destino. +2. Escanea el código QR generado con la app del teléfono vinculada al QQ Bot de destino. 3. Aprueba el emparejamiento en el teléfono. OpenClaw conserva las credenciales devueltas en `credentials/` bajo el alcance de cuenta correcto. -Las solicitudes de aprobación generadas por el propio bot (por ejemplo, flujos de "¿permitir esta acción?" expuestos por la API de QQ Bot) aparecen como solicitudes nativas de OpenClaw que puedes aceptar con `/bot-approve` en lugar de responder mediante el cliente QQ sin procesar. +Las solicitudes de aprobación generadas por el propio bot (por ejemplo, flujos de "¿permitir esta acción?" expuestos por la API de QQ Bot) aparecen como solicitudes nativas de OpenClaw que puedes aceptar con `/bot-approve` en lugar de responder mediante el cliente sin procesar de QQ. ## Solución de problemas -- **El bot responde "se fue a Marte":** las credenciales no están configuradas o el Gateway no se inició. +- **El bot responde "gone to Mars":** credenciales no configuradas o Gateway no iniciado. - **No hay mensajes entrantes:** verifica que `appId` y `clientSecret` sean correctos, y que el - bot esté activado en QQ Open Platform. -- **Autorespuestas repetidas:** OpenClaw registra los índices de referencia salientes de QQ como - generados por el bot e ignora los eventos entrantes cuyo `msgIdx` actual coincide con esa - misma cuenta de bot. Esto evita bucles de eco de la plataforma y permite a la vez que los usuarios - citen o respondan a mensajes anteriores del bot. -- **La configuración con `--token-file` sigue mostrándose como sin configurar:** `--token-file` solo define + bot esté habilitado en QQ Open Platform. +- **Autorrespuestas repetidas:** OpenClaw registra los índices de referencia salientes de QQ como + generados por bot e ignora eventos entrantes cuyo `msgIdx` actual coincida con esa + misma cuenta de bot. Esto evita bucles de eco de la plataforma y aun así permite a los usuarios + citar o responder a mensajes anteriores del bot. +- **La configuración con `--token-file` sigue mostrándose sin configurar:** `--token-file` solo establece el AppSecret. Aún necesitas `appId` en la configuración o `QQBOT_APP_ID`. -- **Los mensajes proactivos no llegan:** QQ puede interceptar mensajes iniciados por el bot si +- **No llegan mensajes proactivos:** QQ puede interceptar mensajes iniciados por el bot si el usuario no ha interactuado recientemente. -- **La voz no se transcribe:** asegúrate de que STT esté configurado y de que el proveedor esté accesible. +- **La voz no se transcribe:** asegúrate de que STT esté configurado y de que el proveedor sea accesible. ## Relacionado diff --git a/docs/es/ci.md b/docs/es/ci.md index 1d3ed0e1e..6f951cda4 100644 --- a/docs/es/ci.md +++ b/docs/es/ci.md @@ -1,75 +1,75 @@ --- read_when: - - Necesitas entender por qué un trabajo de CI se ejecutó o no se ejecutó + - Debe entender por qué un trabajo de CI se ejecutó o no - Estás depurando una comprobación fallida de GitHub Actions - - Está coordinando una ejecución o repetición de validación de lanzamiento + - Está coordinando una ejecución o reejecución de validación de lanzamiento summary: Grafo de trabajos de CI, puertas de alcance, paraguas de lanzamiento y equivalentes de comandos locales title: Canalización de CI x-i18n: - generated_at: "2026-04-30T05:32:10Z" + generated_at: "2026-04-30T09:34:48Z" model: gpt-5.5 provider: openai - source_hash: 80e0edd99f9832bed0c50d2f66b56163e32859e627090e6bf6b9ad7aa5f63d43 + source_hash: a9c18f0801864ca1030aac9ea81117b011bd7936388984a1809ce3ae6e906e62 source_path: ci.md workflow: 16 --- -La CI de OpenClaw se ejecuta en cada push a `main` y en cada pull request. El job `preflight` clasifica el diff y desactiva los carriles costosos cuando solo cambiaron áreas no relacionadas. Las ejecuciones manuales de `workflow_dispatch` omiten intencionalmente el alcance inteligente y despliegan todo el grafo para candidatos de lanzamiento y validación amplia. Los carriles de Android siguen siendo opt-in mediante `include_android`. La cobertura de plugins solo de lanzamiento vive en el flujo de trabajo separado [`Prelanzamiento de Plugin`](#plugin-prerelease) y solo se ejecuta desde [`Validación completa de lanzamiento`](#full-release-validation) o desde un despacho manual explícito. +OpenClaw CI se ejecuta en cada push a `main` y en cada pull request. El trabajo `preflight` clasifica el diff y desactiva las lanes costosas cuando solo cambiaron áreas no relacionadas. Las ejecuciones manuales de `workflow_dispatch` omiten intencionalmente el alcance inteligente y despliegan todo el grafo para release candidates y validación amplia. Las lanes de Android siguen siendo opt-in mediante `include_android`. La cobertura de plugins solo para lanzamientos vive en el flujo de trabajo independiente [`Prelanzamiento de Plugin`](#plugin-prerelease) y solo se ejecuta desde [`Validación completa de la versión`](#full-release-validation) o una ejecución manual explícita. ## Resumen del pipeline -| Job | Propósito | Cuándo se ejecuta | -| -------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------- | -| `preflight` | Detectar cambios solo de docs, alcances cambiados, extensiones cambiadas y construir el manifiesto de CI | Siempre en pushes y PRs que no sean borrador | -| `security-scm-fast` | Detección de claves privadas y auditoría de flujos de trabajo mediante `zizmor` | Siempre en pushes y PRs que no sean borrador | -| `security-dependency-audit` | Auditoría sin dependencias del lockfile de producción contra avisos de npm | Siempre en pushes y PRs que no sean borrador | -| `security-fast` | Agregado requerido para los jobs rápidos de seguridad | Siempre en pushes y PRs que no sean borrador | -| `check-dependencies` | Pasada de Knip solo para dependencias de producción más la guarda de la lista permitida de archivos sin usar | Cambios relevantes para Node | -| `build-artifacts` | Construir `dist/`, la IU de control, verificaciones de artefactos construidos y artefactos reutilizables para consumidores posteriores | Cambios relevantes para Node | -| `checks-fast-core` | Carriles rápidos de corrección en Linux, como verificaciones de paquetes incluidos/contratos de plugins/protocolo | Cambios relevantes para Node | -| `checks-fast-contracts-channels` | Verificaciones fragmentadas de contratos de canales con un resultado de verificación agregado estable | Cambios relevantes para Node | -| `checks-node-core-test` | Fragmentos de pruebas de Node del núcleo, excluyendo carriles de canales, paquetes incluidos, contratos y extensiones | Cambios relevantes para Node | -| `check` | Equivalente fragmentado de la puerta local principal: tipos de producción, lint, guardas, tipos de pruebas y smoke estricto | Cambios relevantes para Node | -| `check-additional` | Fragmentos de arquitectura, límites, guardas de superficie de extensiones, límite de paquetes y observación del Gateway | Cambios relevantes para Node | -| `build-smoke` | Pruebas smoke de la CLI construida y smoke de memoria de arranque | Cambios relevantes para Node | -| `checks` | Verificador para pruebas de canales con artefactos construidos | Cambios relevantes para Node | -| `checks-node-compat-node22` | Carril de build y smoke de compatibilidad con Node 22 | Despacho manual de CI para lanzamientos | -| `check-docs` | Formato, lint y verificaciones de enlaces rotos de docs | Docs cambiados | +| Trabajo | Propósito | Cuándo se ejecuta | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | +| `preflight` | Detectar cambios solo de docs, ámbitos modificados, extensiones modificadas y crear el manifiesto de CI | Siempre en pushes y PRs que no sean borrador | +| `security-scm-fast` | Detección de claves privadas y auditoría de workflows mediante `zizmor` | Siempre en pushes y PRs que no sean borrador | +| `security-dependency-audit` | Auditoría del lockfile de producción sin dependencias contra avisos de npm | Siempre en pushes y PRs que no sean borrador | +| `security-fast` | Agregado requerido para los trabajos rápidos de seguridad | Siempre en pushes y PRs que no sean borrador | +| `check-dependencies` | Paso de Knip solo para dependencias de producción más el guard de la lista de permitidos de archivos no usados | Cambios relevantes para Node | +| `build-artifacts` | Compilar `dist/`, Control UI, comprobaciones de artefactos compilados y artefactos reutilizables para trabajos descendentes | Cambios relevantes para Node | +| `checks-fast-core` | Lanes rápidas de corrección en Linux, como comprobaciones de bundled/plugin-contract/protocol | Cambios relevantes para Node | +| `checks-fast-contracts-channels` | Comprobaciones de contratos de canal fragmentadas con un resultado de comprobación agregado estable | Cambios relevantes para Node | +| `checks-node-core-test` | Fragmentos de tests de Node del núcleo, excluidas las lanes de canal, bundled, contrato y extensión | Cambios relevantes para Node | +| `check` | Equivalente fragmentado de la gate local principal: tipos de producción, lint, guards, tipos de tests y smoke estricto | Cambios relevantes para Node | +| `check-additional` | Fragmentos de arquitectura, límites, guards de superficie de extensión, package-boundary y gateway-watch | Cambios relevantes para Node | +| `build-smoke` | Tests smoke de la CLI compilada y smoke de memoria de arranque | Cambios relevantes para Node | +| `checks` | Verificador para tests de canales con artefactos compilados | Cambios relevantes para Node | +| `checks-node-compat-node22` | Lane de compilación y smoke de compatibilidad con Node 22 | Ejecución manual de CI para lanzamientos | +| `check-docs` | Formateo, lint y comprobaciones de enlaces rotos de la documentación | Cambios en docs | | `skills-python` | Ruff + pytest para Skills respaldadas por Python | Cambios relevantes para Skills de Python | -| `checks-windows` | Pruebas específicas de procesos/rutas de Windows más regresiones compartidas de especificadores de importación en tiempo de ejecución | Cambios relevantes para Windows | -| `macos-node` | Carril de pruebas de TypeScript en macOS usando los artefactos construidos compartidos | Cambios relevantes para macOS | -| `macos-swift` | Lint, build y pruebas de Swift para la app de macOS | Cambios relevantes para macOS | -| `android` | Pruebas unitarias de Android para ambos sabores más una build de APK de depuración | Cambios relevantes para Android | -| `test-performance-agent` | Optimización diaria de pruebas lentas de Codex después de actividad confiable | Éxito de CI principal o despacho manual | +| `checks-windows` | Tests específicos de Windows de procesos/rutas más regresiones compartidas de especificadores de importación en runtime | Cambios relevantes para Windows | +| `macos-node` | Lane de tests TypeScript en macOS usando los artefactos compilados compartidos | Cambios relevantes para macOS | +| `macos-swift` | Lint, compilación y tests de Swift para la app de macOS | Cambios relevantes para macOS | +| `android` | Tests unitarios de Android para ambos sabores más una compilación de APK de depuración | Cambios relevantes para Android | +| `test-performance-agent` | Optimización diaria de tests lentos de Codex después de actividad confiable | Éxito de CI en main o ejecución manual | -## Orden de fallo rápido +## Orden fail-fast -1. `preflight` decide qué carriles existen realmente. La lógica de `docs-scope` y `changed-scope` son pasos dentro de este job, no jobs independientes. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` y `skills-python` fallan rápido sin esperar a los jobs más pesados de artefactos y matriz de plataformas. -3. `build-artifacts` se solapa con los carriles rápidos de Linux para que los consumidores posteriores puedan empezar en cuanto la build compartida esté lista. -4. Los carriles más pesados de plataforma y tiempo de ejecución se despliegan después: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` y `android`. +1. `preflight` decide qué lanes existen. La lógica de `docs-scope` y `changed-scope` son pasos dentro de este trabajo, no trabajos independientes. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` y `skills-python` fallan rápidamente sin esperar a los trabajos más pesados de artefactos y matriz de plataformas. +3. `build-artifacts` se solapa con las lanes rápidas de Linux para que los consumidores descendentes puedan empezar en cuanto la compilación compartida esté lista. +4. Las lanes más pesadas de plataforma y runtime se despliegan después: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` y `android`. -GitHub puede marcar jobs reemplazados como `cancelled` cuando llega un push más nuevo al mismo PR o ref de `main`. Trátalo como ruido de CI a menos que la ejecución más nueva para el mismo ref también esté fallando. Las verificaciones agregadas de fragmentos usan `!cancelled() && always()` para que sigan informando fallos normales de fragmentos, pero no se encolen después de que todo el flujo de trabajo ya haya sido reemplazado. La clave automática de concurrencia de CI está versionada (`CI-v7-*`) para que un zombi del lado de GitHub en un grupo de cola antiguo no pueda bloquear indefinidamente ejecuciones principales más nuevas. Las ejecuciones manuales de la suite completa usan `CI-manual-v1-*` y no cancelan ejecuciones en curso. +GitHub puede marcar trabajos reemplazados como `cancelled` cuando llega un push más nuevo al mismo PR o ref de `main`. Trátalo como ruido de CI salvo que la ejecución más reciente para el mismo ref también esté fallando. Las comprobaciones agregadas de fragmentos usan `!cancelled() && always()` para seguir informando fallos normales de fragmentos, pero no se ponen en cola después de que todo el workflow ya haya sido reemplazado. La clave de concurrencia automática de CI está versionada (`CI-v7-*`), de modo que un zombi del lado de GitHub en un grupo de cola antiguo no pueda bloquear indefinidamente ejecuciones nuevas de main. Las ejecuciones manuales de suite completa usan `CI-manual-v1-*` y no cancelan ejecuciones en curso. ## Alcance y enrutamiento -La lógica de alcance vive en `scripts/ci-changed-scope.mjs` y está cubierta por pruebas unitarias en `src/scripts/ci-changed-scope.test.ts`. El despacho manual omite la detección de alcance cambiado y hace que el manifiesto de preflight actúe como si todas las áreas con alcance hubieran cambiado. +La lógica de alcance vive en `scripts/ci-changed-scope.mjs` y está cubierta por tests unitarios en `src/scripts/ci-changed-scope.test.ts`. La ejecución manual omite la detección de changed-scope y hace que el manifiesto de preflight actúe como si cada área con alcance hubiera cambiado. -- **Las ediciones del flujo de trabajo de CI** validan el grafo de CI de Node más el linting del flujo de trabajo, pero no fuerzan por sí solas builds nativas de Windows, Android o macOS; esos carriles de plataforma siguen limitados a cambios en el código fuente de plataforma. -- **Las ediciones solo de enrutamiento de CI, ediciones seleccionadas de fixtures baratas de pruebas del núcleo y ediciones estrechas de helpers/enrutamiento de pruebas de contratos de plugins** usan una ruta rápida de manifiesto solo de Node: `preflight`, seguridad y una única tarea `checks-fast-core`. Esa ruta omite artefactos de build, compatibilidad con Node 22, contratos de canales, fragmentos completos del núcleo, fragmentos de plugins incluidos y matrices adicionales de guardas cuando el cambio está limitado a las superficies de enrutamiento o helpers que la tarea rápida ejercita directamente. -- **Las verificaciones de Node en Windows** se limitan a wrappers de procesos/rutas específicos de Windows, helpers de runner de npm/pnpm/IU, configuración del gestor de paquetes y las superficies del flujo de trabajo de CI que ejecutan ese carril; los cambios no relacionados de código fuente, plugins, install-smoke y solo pruebas permanecen en los carriles de Node en Linux. +- **Las ediciones del workflow de CI** validan el grafo de CI de Node más el linting de workflows, pero no fuerzan por sí mismas compilaciones nativas de Windows, Android o macOS; esas lanes de plataforma siguen estando acotadas a cambios de código fuente de plataforma. +- **Las ediciones solo de enrutamiento de CI, ediciones seleccionadas baratas de fixtures de core-test y ediciones estrechas de helper/enrutamiento de tests de contratos de plugins** usan una ruta rápida de manifiesto solo de Node: `preflight`, seguridad y una sola tarea `checks-fast-core`. Esa ruta omite artefactos de compilación, compatibilidad con Node 22, contratos de canal, fragmentos completos del núcleo, fragmentos de plugins bundled y matrices adicionales de guards cuando el cambio se limita a las superficies de enrutamiento o helpers que la tarea rápida ejercita directamente. +- **Las comprobaciones de Node en Windows** están acotadas a wrappers de procesos/rutas específicos de Windows, helpers de runners de npm/pnpm/UI, configuración del gestor de paquetes y las superficies del workflow de CI que ejecutan esa lane; los cambios no relacionados de código fuente, plugins, install-smoke y solo de tests permanecen en las lanes de Node en Linux. -Las familias de pruebas de Node más lentas se dividen o equilibran para que cada job se mantenga pequeño sin reservar en exceso los runners: los contratos de canales se ejecutan como tres fragmentos ponderados, los carriles unitarios pequeños del núcleo se emparejan, auto-reply se ejecuta como cuatro workers equilibrados (con el subárbol de reply dividido en fragmentos de agent-runner, dispatch y commands/state-routing), y las configuraciones agentic de Gateway/plugins se distribuyen entre los jobs de Node agentic existentes solo de código fuente en lugar de esperar a los artefactos construidos. Las pruebas amplias de navegador, QA, medios y plugins misceláneos usan sus configuraciones dedicadas de Vitest en lugar del catch-all compartido de plugins. Los fragmentos con patrones de inclusión registran entradas de tiempo usando el nombre del fragmento de CI, de modo que `.artifacts/vitest-shard-timings.json` pueda distinguir una configuración completa de un fragmento filtrado. `check-additional` mantiene juntas las tareas de compilación/canary de límites de paquetes y separa la arquitectura de topología de tiempo de ejecución de la cobertura de observación del Gateway; el fragmento de guarda de límites ejecuta sus pequeñas guardas independientes de forma concurrente dentro de un job. La observación del Gateway, las pruebas de canales y el fragmento de límites de soporte del núcleo se ejecutan de forma concurrente dentro de `build-artifacts` después de que `dist/` y `dist-runtime/` ya estén construidos. +Las familias de tests de Node más lentas se dividen o equilibran para que cada trabajo siga siendo pequeño sin reservar runners en exceso: los contratos de canal se ejecutan como tres fragmentos ponderados, las lanes pequeñas de unidades del núcleo se emparejan, auto-reply se ejecuta como cuatro workers equilibrados (con el subárbol de reply dividido en fragmentos de agent-runner, dispatch y commands/state-routing), y las configuraciones agénticas de gateway/plugins se distribuyen entre los trabajos agénticos de Node solo de código fuente existentes en lugar de esperar a artefactos compilados. Los tests amplios de navegador, QA, medios y plugins varios usan sus configuraciones dedicadas de Vitest en lugar del catch-all compartido de plugins. Los fragmentos con patrones de inclusión registran entradas de tiempo usando el nombre del fragmento de CI, de modo que `.artifacts/vitest-shard-timings.json` pueda distinguir una configuración completa de un fragmento filtrado. `check-additional` mantiene juntos el trabajo de compilación/canary de package-boundary y separa la arquitectura de topología de runtime de la cobertura de gateway watch; el fragmento de boundary guard ejecuta sus pequeños guards independientes de forma concurrente dentro de un solo trabajo. Gateway watch, los tests de canales y el fragmento de support-boundary del núcleo se ejecutan de forma concurrente dentro de `build-artifacts` después de que `dist/` y `dist-runtime/` ya estén compilados. -La CI de Android ejecuta tanto `testPlayDebugUnitTest` como `testThirdPartyDebugUnitTest` y luego construye el APK de depuración Play. El sabor de terceros no tiene un source set ni manifiesto separados; su carril de pruebas unitarias sigue compilando el sabor con las flags de BuildConfig de SMS/registro de llamadas, mientras evita un job duplicado de empaquetado de APK de depuración en cada push relevante para Android. +La CI de Android ejecuta tanto `testPlayDebugUnitTest` como `testThirdPartyDebugUnitTest` y luego compila el APK de depuración de Play. El sabor de terceros no tiene un conjunto de código fuente ni manifiesto separado; su lane de tests unitarios sigue compilando el sabor con las flags BuildConfig de SMS/call-log, evitando al mismo tiempo un trabajo duplicado de empaquetado de APK de depuración en cada push relevante para Android. -El fragmento `check-dependencies` ejecuta `pnpm deadcode:dependencies` (una pasada de Knip solo para dependencias de producción fijada a la versión más reciente de Knip, con la edad mínima de lanzamiento de pnpm desactivada para la instalación `dlx`) y `pnpm deadcode:unused-files`, que compara los hallazgos de archivos de producción sin usar de Knip contra `scripts/deadcode-unused-files.allowlist.mjs`. La guarda de archivos sin usar falla cuando un PR agrega un nuevo archivo sin usar no revisado o deja una entrada obsoleta en la lista permitida, a la vez que conserva superficies intencionales de plugins dinámicos, generadas, de build, de live-test y de puentes de paquetes que Knip no puede resolver estáticamente. +El fragmento `check-dependencies` ejecuta `pnpm deadcode:dependencies` (un paso de Knip solo para dependencias de producción fijado a la versión más reciente de Knip, con la edad mínima de publicación de pnpm desactivada para la instalación con `dlx`) y `pnpm deadcode:unused-files`, que compara los hallazgos de archivos no usados de producción de Knip contra `scripts/deadcode-unused-files.allowlist.mjs`. El guard de archivos no usados falla cuando un PR añade un nuevo archivo no usado sin revisar o deja una entrada obsoleta en la lista de permitidos, a la vez que preserva superficies intencionales de plugins dinámicos, generadas, de compilación, live-test y puentes de paquetes que Knip no puede resolver estáticamente. -## Despachos manuales +## Ejecuciones manuales -Los despachos manuales de CI ejecutan el mismo grafo de jobs que la CI normal, pero fuerzan la activación de todos los carriles con alcance que no sean Android: fragmentos de Node en Linux, fragmentos de plugins incluidos, contratos de canales, compatibilidad con Node 22, `check`, `check-additional`, build smoke, verificaciones de docs, Skills de Python, Windows, macOS e i18n de la IU de control. Los despachos manuales independientes de CI ejecutan Android solo con `include_android=true`; el paraguas completo de lanzamiento habilita Android pasando `include_android=true`. Las verificaciones estáticas de prelanzamiento de plugins, el fragmento `agentic-plugins` solo de lanzamiento, el barrido completo por lotes de extensiones y los carriles Docker de prelanzamiento de plugins están excluidos de CI. La suite Docker de prelanzamiento se ejecuta solo cuando `Full Release Validation` despacha el flujo de trabajo separado `Plugin Prerelease` con la puerta de validación de lanzamiento habilitada. +Las ejecuciones manuales de CI ejecutan el mismo grafo de trabajos que la CI normal, pero fuerzan la activación de cada lane con alcance que no sea Android: fragmentos de Node en Linux, fragmentos de plugins bundled, contratos de canal, compatibilidad con Node 22, `check`, `check-additional`, smoke de compilación, comprobaciones de docs, Skills de Python, Windows, macOS e i18n de Control UI. Las ejecuciones manuales independientes de CI ejecutan Android solo con `include_android=true`; el paraguas de lanzamiento completo habilita Android pasando `include_android=true`. Las comprobaciones estáticas de prelanzamiento de plugins, el fragmento `agentic-plugins` solo para lanzamientos, el barrido completo por lotes de extensiones y las lanes de Docker de prelanzamiento de plugins quedan excluidos de CI. La suite de prelanzamiento de Docker solo se ejecuta cuando `Full Release Validation` despacha el workflow independiente `Plugin Prerelease` con la gate de validación de lanzamiento habilitada. -Las ejecuciones manuales usan un grupo de concurrencia único para que una suite completa de candidato de lanzamiento no sea cancelada por otro push o ejecución de PR en el mismo ref. La entrada opcional `target_ref` permite que un llamador confiable ejecute ese grafo contra una rama, etiqueta o SHA completo de commit usando el archivo de flujo de trabajo del ref de despacho seleccionado. +Las ejecuciones manuales usan un grupo de concurrencia único para que una suite completa de release candidate no sea cancelada por otro push o ejecución de PR en el mismo ref. La entrada opcional `target_ref` permite que un llamador confiable ejecute ese grafo contra una rama, etiqueta o SHA de commit completo mientras usa el archivo de workflow del ref de despacho seleccionado. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -79,15 +79,15 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Runners -| Ejecutor | Trabajos | -| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, trabajos de seguridad rápidos y agregados (`security-scm-fast`, `security-dependency-audit`, `security-fast`), comprobaciones rápidas de protocolo/contrato/incluidas, comprobaciones fragmentadas de contratos de canal, fragmentos de `check` excepto lint, fragmentos y agregados de `check-additional`, verificadores agregados de pruebas de Node, comprobaciones de documentación, Skills de Python, workflow-sanity, labeler, auto-response; la preflight de install-smoke también usa Ubuntu hospedado en GitHub para que la matriz de Blacksmith pueda ponerse en cola antes | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, fragmentos de Plugin de menor peso, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` y `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragmentos de pruebas de Linux Node, fragmentos de pruebas de Plugin incluido, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (lo bastante sensible a CPU como para que 8 vCPU costaran más de lo que ahorraban); compilaciones de Docker de install-smoke (el coste de tiempo de cola de 32 vCPU fue mayor que lo que ahorró) | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` en `openclaw/openclaw`; los forks vuelven a `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` en `openclaw/openclaw`; los forks vuelven a `macos-latest` | +| Ejecutor | Trabajos | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, trabajos y agregados de seguridad rápidos (`security-scm-fast`, `security-dependency-audit`, `security-fast`), comprobaciones rápidas de protocolo/contrato/incluidas, comprobaciones fragmentadas de contratos de canales, fragmentos de `check` excepto lint, fragmentos y agregados de `check-additional`, verificadores agregados de pruebas de Node, comprobaciones de documentación, Skills de Python, workflow-sanity, labeler, auto-response; la preflight de install-smoke también usa Ubuntu alojado en GitHub para que la matriz de Blacksmith pueda ponerse en cola antes | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, fragmentos de menor peso de extensiones, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` y `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragmentos de pruebas de Node en Linux, fragmentos de pruebas de plugins incluidos, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (lo bastante sensible a la CPU como para que 8 vCPU costaran más de lo que ahorraban); compilaciones Docker de install-smoke (el tiempo de cola de 32 vCPU costaba más de lo que ahorraba) | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` en `openclaw/openclaw`; las bifurcaciones recurren a `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` en `openclaw/openclaw`; las bifurcaciones recurren a `macos-latest` | ## Equivalentes locales @@ -115,25 +115,25 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` -## Validación completa de versión +## Validación completa de la versión -`Full Release Validation` es el workflow paraguas manual para "ejecutar todo antes de la versión". Acepta una rama, etiqueta o SHA de commit completo, despacha el workflow manual `CI` con ese destino, despacha `Plugin Prerelease` para la prueba exclusiva de versión de Plugin/paquete/estática/Docker, y despacha `OpenClaw Release Checks` para install smoke, aceptación de paquete, suites de ruta de versión de Docker, live/E2E, OpenWebUI, paridad de QA Lab, Matrix y carriles de Telegram. También puede ejecutar el workflow posterior a la publicación `NPM Telegram Beta E2E` cuando se proporciona una especificación de paquete publicada. +`Full Release Validation` es el flujo de trabajo manual general para "ejecutar todo antes del lanzamiento". Acepta una rama, etiqueta o SHA completo de commit, despacha el flujo de trabajo manual `CI` con ese objetivo, despacha `Plugin Prerelease` para pruebas exclusivas de lanzamiento de plugins/paquetes/estáticas/Docker, y despacha `OpenClaw Release Checks` para smoke de instalación, aceptación de paquetes, suites de ruta de lanzamiento de Docker, live/E2E, OpenWebUI, paridad de QA Lab, Matrix y carriles de Telegram. También puede ejecutar el flujo de trabajo posterior a la publicación `NPM Telegram Beta E2E` cuando se proporciona una especificación de paquete publicada. -`release_profile` controla la amplitud live/proveedor pasada a las comprobaciones de versión: +`release_profile` controla la amplitud live/proveedor pasada a las comprobaciones de lanzamiento: -- `minimum` conserva los carriles críticos de versión de OpenAI/core más rápidos. +- `minimum` mantiene los carriles más rápidos críticos para el lanzamiento de OpenAI/núcleo. - `stable` añade el conjunto estable de proveedores/backends. - `full` ejecuta la matriz amplia consultiva de proveedores/medios. -El paraguas registra los ids de ejecución de los workflows hijo despachados, y el trabajo final `Verify full validation` vuelve a comprobar las conclusiones actuales de las ejecuciones hijo y añade tablas de trabajos más lentos para cada ejecución hijo. Si un workflow hijo se vuelve a ejecutar y queda en verde, vuelve a ejecutar solo el trabajo verificador padre para actualizar el resultado del paraguas y el resumen de tiempos. +El flujo general registra los identificadores de las ejecuciones secundarias despachadas, y el trabajo final `Verify full validation` vuelve a comprobar las conclusiones actuales de las ejecuciones secundarias y anexa tablas de los trabajos más lentos para cada ejecución secundaria. Si un flujo de trabajo secundario se vuelve a ejecutar y pasa a verde, vuelve a ejecutar solo el trabajo verificador principal para actualizar el resultado general y el resumen de tiempos. -Para recuperación, tanto `Full Release Validation` como `OpenClaw Release Checks` aceptan `rerun_group`. Usa `all` para un candidato de versión, `ci` solo para el hijo de CI completo normal, `release-checks` para cada hijo de versión, o un grupo más estrecho: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` o `npm-telegram` en el paraguas. Esto mantiene acotada la nueva ejecución de una caja de versión fallida después de una corrección enfocada. +Para recuperación, tanto `Full Release Validation` como `OpenClaw Release Checks` aceptan `rerun_group`. Usa `all` para un candidato de lanzamiento, `ci` solo para el secundario de CI completo normal, `release-checks` para cada secundario de lanzamiento, o un grupo más específico: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` o `npm-telegram` en el flujo general. Esto mantiene acotada una nueva ejecución de una caja de lanzamiento fallida después de una corrección enfocada. -`OpenClaw Release Checks` usa la ref de workflow confiable para resolver la ref seleccionada una vez en un tarball `release-package-under-test`, y luego pasa ese artefacto tanto al workflow Docker de ruta de versión live/E2E como al fragmento de aceptación de paquete. Eso mantiene consistentes los bytes del paquete entre cajas de versión y evita reempaquetar el mismo candidato en varios trabajos hijo. +`OpenClaw Release Checks` usa la referencia de flujo de trabajo de confianza para resolver la referencia seleccionada una vez en un tarball `release-package-under-test`, y luego pasa ese artefacto tanto al flujo de trabajo Docker live/E2E de ruta de lanzamiento como al fragmento de aceptación de paquetes. Eso mantiene coherentes los bytes del paquete entre cajas de lanzamiento y evita volver a empaquetar el mismo candidato en varios trabajos secundarios. ## Fragmentos live y E2E -El hijo live/E2E de versión mantiene cobertura amplia nativa de `pnpm test:live`, pero la ejecuta como fragmentos con nombre mediante `scripts/test-live-shard.mjs` en lugar de un trabajo serial: +El secundario live/E2E de lanzamiento mantiene una cobertura nativa amplia de `pnpm test:live`, pero la ejecuta como fragmentos con nombre mediante `scripts/test-live-shard.mjs` en vez de un trabajo serial: - `native-live-src-agents` - `native-live-src-gateway-core` @@ -145,57 +145,57 @@ El hijo live/E2E de versión mantiene cobertura amplia nativa de `pnpm test:live - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- fragmentos divididos de medios de audio/vídeo y fragmentos de música filtrados por proveedor +- fragmentos separados de audio/vídeo de medios y fragmentos de música filtrados por proveedor -Eso conserva la misma cobertura de archivos y facilita volver a ejecutar y diagnosticar fallos lentos de proveedores live. Los nombres de fragmento agregados `native-live-extensions-o-z`, `native-live-extensions-media` y `native-live-extensions-media-music` siguen siendo válidos para nuevas ejecuciones manuales de una sola vez. +Eso mantiene la misma cobertura de archivos y a la vez hace que los fallos lentos de proveedores live sean más fáciles de volver a ejecutar y diagnosticar. Los nombres de fragmento agregados `native-live-extensions-o-z`, `native-live-extensions-media` y `native-live-extensions-media-music` siguen siendo válidos para nuevas ejecuciones manuales únicas. -Los fragmentos nativos de medios live se ejecutan en `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, compilado por el workflow `Live Media Runner Image`. Esa imagen preinstala `ffmpeg` y `ffprobe`; los trabajos de medios solo verifican los binarios antes de la configuración. Mantén las suites live respaldadas por Docker en ejecutores normales de Blacksmith: los trabajos de contenedor son el lugar equivocado para lanzar pruebas Docker anidadas. +Los fragmentos nativos de medios live se ejecutan en `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, construido por el flujo de trabajo `Live Media Runner Image`. Esa imagen preinstala `ffmpeg` y `ffprobe`; los trabajos de medios solo verifican los binarios antes de la configuración. Mantén las suites live respaldadas por Docker en ejecutores Blacksmith normales: los trabajos de contenedor son el lugar incorrecto para lanzar pruebas Docker anidadas. -Los fragmentos live de modelo/backend respaldados por Docker usan una imagen compartida separada `ghcr.io/openclaw/openclaw-live-test:` por commit seleccionado. El workflow live de versión compila y publica esa imagen una vez, y luego los fragmentos de modelo live Docker, Gateway, backend de CLI, enlace ACP y arnés Codex se ejecutan con `OPENCLAW_SKIP_DOCKER_BUILD=1`. Si esos fragmentos reconstruyen independientemente el destino Docker de código fuente completo, la ejecución de versión está mal configurada y desperdiciará tiempo de reloj en compilaciones de imagen duplicadas. +Los fragmentos live de modelo/backend respaldados por Docker usan una imagen compartida separada `ghcr.io/openclaw/openclaw-live-test:` por commit seleccionado. El flujo de trabajo de lanzamiento live compila y sube esa imagen una vez, luego los fragmentos de modelo live Docker, Gateway, backend de CLI, enlace ACP y arnés de Codex se ejecutan con `OPENCLAW_SKIP_DOCKER_BUILD=1`. Si esos fragmentos recompilan de forma independiente el objetivo Docker completo del código fuente, la ejecución de lanzamiento está mal configurada y desperdiciará tiempo de reloj en compilaciones de imagen duplicadas. -## Aceptación de paquete +## Aceptación de paquetes -Usa `Package Acceptance` cuando la pregunta sea "¿funciona este paquete instalable de OpenClaw como producto?". Es diferente de la CI normal: la CI normal valida el árbol de código fuente, mientras que la aceptación de paquete valida un único tarball mediante el mismo arnés Docker E2E que los usuarios ejercitan después de instalar o actualizar. +Usa `Package Acceptance` cuando la pregunta sea "¿funciona este paquete instalable de OpenClaw como producto?". Es diferente de la CI normal: la CI normal valida el árbol de código fuente, mientras que la aceptación de paquetes valida un único tarball mediante el mismo arnés Docker E2E que los usuarios ejercitan después de instalar o actualizar. ### Trabajos -1. `resolve_package` hace checkout de `workflow_ref`, resuelve un candidato de paquete, escribe `.artifacts/docker-e2e-package/openclaw-current.tgz`, escribe `.artifacts/docker-e2e-package/package-candidate.json`, sube ambos como el artefacto `package-under-test` e imprime la fuente, la ref de workflow, la ref de paquete, la versión, el SHA-256 y el perfil en el resumen de paso de GitHub. -2. `docker_acceptance` llama a `openclaw-live-and-e2e-checks-reusable.yml` con `ref=workflow_ref` y `package_artifact_name=package-under-test`. El workflow reutilizable descarga ese artefacto, valida el inventario del tarball, prepara imágenes Docker de digest de paquete cuando hace falta y ejecuta los carriles Docker seleccionados contra ese paquete en lugar de empaquetar el checkout del workflow. Cuando un perfil selecciona varios `docker_lanes` dirigidos, el workflow reutilizable prepara el paquete y las imágenes compartidas una vez, y luego despliega esos carriles como trabajos Docker dirigidos paralelos con artefactos únicos. -3. `package_telegram` llama opcionalmente a `NPM Telegram Beta E2E`. Se ejecuta cuando `telegram_mode` no es `none` e instala el mismo artefacto `package-under-test` cuando Package Acceptance resolvió uno; un despacho independiente de Telegram aún puede instalar una especificación npm publicada. -4. `summary` falla el workflow si fallaron la resolución del paquete, la aceptación Docker o el carril opcional de Telegram. +1. `resolve_package` hace checkout de `workflow_ref`, resuelve un candidato de paquete, escribe `.artifacts/docker-e2e-package/openclaw-current.tgz`, escribe `.artifacts/docker-e2e-package/package-candidate.json`, sube ambos como el artefacto `package-under-test` e imprime el origen, la referencia de flujo de trabajo, la referencia de paquete, la versión, SHA-256 y el perfil en el resumen de paso de GitHub. +2. `docker_acceptance` llama a `openclaw-live-and-e2e-checks-reusable.yml` con `ref=workflow_ref` y `package_artifact_name=package-under-test`. El flujo de trabajo reutilizable descarga ese artefacto, valida el inventario del tarball, prepara imágenes Docker con resumen de paquete cuando hace falta, y ejecuta los carriles Docker seleccionados contra ese paquete en vez de empaquetar el checkout del flujo de trabajo. Cuando un perfil selecciona varios `docker_lanes` dirigidos, el flujo de trabajo reutilizable prepara el paquete y las imágenes compartidas una vez, y luego despliega esos carriles como trabajos Docker dirigidos paralelos con artefactos únicos. +3. `package_telegram` llama opcionalmente a `NPM Telegram Beta E2E`. Se ejecuta cuando `telegram_mode` no es `none` e instala el mismo artefacto `package-under-test` cuando Package Acceptance resolvió uno; el despacho independiente de Telegram aún puede instalar una especificación de npm publicada. +4. `summary` falla el flujo de trabajo si falló la resolución del paquete, la aceptación Docker o el carril opcional de Telegram. -### Fuentes candidatas +### Orígenes de candidatos -- `source=npm` acepta solo `openclaw@beta`, `openclaw@latest` o una versión exacta de lanzamiento de OpenClaw, como `openclaw@2026.4.27-beta.2`. Usa esto para la aceptación beta/estable publicada. -- `source=ref` empaqueta una rama, etiqueta o SHA completo de commit de `package_ref` de confianza. El resolvedor obtiene ramas/etiquetas de OpenClaw, verifica que se pueda llegar al commit seleccionado desde el historial de ramas del repositorio o desde una etiqueta de lanzamiento, instala dependencias en un worktree separado y lo empaqueta con `scripts/package-openclaw-for-docker.mjs`. +- `source=npm` acepta solo `openclaw@beta`, `openclaw@latest` o una versión exacta de lanzamiento de OpenClaw como `openclaw@2026.4.27-beta.2`. Usa esto para la aceptación beta/estable publicada. +- `source=ref` empaqueta una rama, etiqueta o SHA completo de commit `package_ref` de confianza. El resolvedor obtiene ramas/etiquetas de OpenClaw, verifica que el commit seleccionado sea alcanzable desde el historial de ramas del repositorio o desde una etiqueta de lanzamiento, instala dependencias en un worktree separado y lo empaqueta con `scripts/package-openclaw-for-docker.mjs`. - `source=url` descarga un `.tgz` HTTPS; `package_sha256` es obligatorio. -- `source=artifact` descarga un `.tgz` desde `artifact_run_id` y `artifact_name`; `package_sha256` es opcional, pero debería proporcionarse para artefactos compartidos externamente. +- `source=artifact` descarga un `.tgz` desde `artifact_run_id` y `artifact_name`; `package_sha256` es opcional, pero debe proporcionarse para artefactos compartidos externamente. -Mantén `workflow_ref` y `package_ref` separados. `workflow_ref` es el código de workflow/arnés de confianza que ejecuta la prueba. `package_ref` es el commit de origen que se empaqueta cuando `source=ref`. Esto permite que el arnés de pruebas actual valide commits de origen confiables más antiguos sin ejecutar lógica de workflow antigua. +Mantén `workflow_ref` y `package_ref` separados. `workflow_ref` es el código de workflow/arnés de confianza que ejecuta la prueba. `package_ref` es el commit de origen que se empaqueta cuando `source=ref`. Esto permite que el arnés de pruebas actual valide commits de origen de confianza más antiguos sin ejecutar lógica de workflow antigua. ### Perfiles de suite - `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload` - `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update` - `product` — `package` más `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full` — fragmentos completos de la ruta de lanzamiento Docker con OpenWebUI +- `full` — fragmentos completos de la ruta de lanzamiento de Docker con OpenWebUI - `custom` — `docker_lanes` exactos; obligatorio cuando `suite_profile=custom` -El perfil `package` usa cobertura offline de plugins para que la validación de paquetes publicados no dependa de la disponibilidad en vivo de ClawHub. La ruta opcional de Telegram reutiliza el artefacto `package-under-test` en `NPM Telegram Beta E2E`, con la ruta de especificación npm publicada conservada para ejecuciones independientes. +El perfil `package` usa cobertura de plugins sin conexión para que la validación de paquetes publicados no dependa de la disponibilidad en vivo de ClawHub. El carril opcional de Telegram reutiliza el artefacto `package-under-test` en `NPM Telegram Beta E2E`, con la ruta de especificación npm publicada conservada para despachos independientes. -Las comprobaciones de lanzamiento llaman a Package Acceptance con `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` y `telegram_mode=mock-openai`. Los fragmentos Docker de la ruta de lanzamiento cubren las rutas superpuestas de paquete/actualización/plugin; Package Acceptance mantiene la prueba de compatibilidad de canales incluidos nativa del artefacto, el plugin offline y Telegram contra el mismo tarball de paquete resuelto. Las comprobaciones de lanzamiento entre sistemas operativos siguen cubriendo el onboarding específico del sistema operativo, el instalador y el comportamiento de la plataforma; la validación de producto de paquete/actualización debería empezar con Package Acceptance. Las rutas nuevas de paquete e instalador en Windows también verifican que un paquete instalado pueda importar una sobrescritura de control del navegador desde una ruta absoluta Windows sin procesar. El smoke entre sistemas operativos del turno de agente de OpenAI usa por defecto `OPENCLAW_CROSS_OS_OPENAI_MODEL` cuando está definido; de lo contrario, `openai/gpt-5.4-mini`, para que la prueba de instalación y Gateway se mantenga rápida y determinista. +Las verificaciones de lanzamiento llaman a Package Acceptance con `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` y `telegram_mode=mock-openai`. Los fragmentos Docker de ruta de lanzamiento cubren los carriles superpuestos de paquete/actualización/plugin; Package Acceptance conserva la compatibilidad nativa del artefacto con canales incluidos, plugins sin conexión y prueba de Telegram contra el mismo tarball de paquete resuelto. Las verificaciones de lanzamiento entre sistemas operativos siguen cubriendo el onboarding, el instalador y el comportamiento de plataforma específicos del sistema operativo; la validación de producto de paquete/actualización debe empezar con Package Acceptance. Los carriles nuevos de paquete e instalador de Windows también verifican que un paquete instalado pueda importar una anulación de control de navegador desde una ruta absoluta sin procesar de Windows. El smoke de turno de agente entre sistemas operativos de OpenAI usa por defecto `OPENCLAW_CROSS_OS_OPENAI_MODEL` cuando está definido; de lo contrario, usa `openai/gpt-5.4-mini`, de modo que la prueba de instalación y Gateway se mantenga rápida y determinista. ### Ventanas de compatibilidad heredada -Package Acceptance tiene ventanas acotadas de compatibilidad heredada para paquetes ya publicados. Los paquetes hasta `2026.4.25`, incluido `2026.4.25-beta.*`, pueden usar la ruta de compatibilidad: +Package Acceptance tiene ventanas delimitadas de compatibilidad heredada para paquetes ya publicados. Los paquetes hasta `2026.4.25`, incluido `2026.4.25-beta.*`, pueden usar la ruta de compatibilidad: - las entradas privadas conocidas de QA en `dist/postinstall-inventory.json` pueden apuntar a archivos omitidos del tarball; - `doctor-switch` puede omitir el subcaso de persistencia `gateway install --wrapper` cuando el paquete no expone esa marca; -- `update-channel-switch` puede podar `pnpm.patchedDependencies` faltantes del fixture git falso derivado del tarball y puede registrar `update.channel` persistido faltante; -- los smokes de plugins pueden leer ubicaciones heredadas de registros de instalación o aceptar la persistencia faltante del registro de instalación del marketplace; -- `plugin-update` puede permitir la migración de metadatos de configuración y seguir exigiendo que el registro de instalación y el comportamiento sin reinstalación permanezcan sin cambios. +- `update-channel-switch` puede podar `pnpm.patchedDependencies` faltantes del fixture git falso derivado del tarball y puede registrar `update.channel` persistente faltante; +- los smokes de plugins pueden leer ubicaciones heredadas de registros de instalación o aceptar la falta de persistencia del registro de instalación del marketplace; +- `plugin-update` puede permitir la migración de metadatos de configuración mientras sigue exigiendo que el registro de instalación y el comportamiento sin reinstalación permanezcan sin cambios. -El paquete publicado `2026.4.26` también puede advertir sobre archivos de sello de metadatos de compilación local que ya se habían distribuido. Los paquetes posteriores deben satisfacer los contratos modernos; las mismas condiciones fallan en lugar de advertir u omitirse. +El paquete publicado `2026.4.26` también puede advertir sobre archivos de sello de metadatos de compilación local que ya se habían enviado. Los paquetes posteriores deben cumplir los contratos modernos; las mismas condiciones fallan en lugar de advertir u omitirse. ### Ejemplos @@ -238,152 +238,152 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Al depurar una ejecución fallida de aceptación de paquete, empieza por el resumen de `resolve_package` para confirmar el origen, la versión y el SHA-256 del paquete. Luego inspecciona la ejecución hija `docker_acceptance` y sus artefactos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, registros de ruta, tiempos de fase y comandos de repetición. Prefiere volver a ejecutar el perfil de paquete fallido o las rutas Docker exactas en lugar de volver a ejecutar toda la validación de lanzamiento. +Al depurar una ejecución fallida de aceptación de paquete, empieza por el resumen `resolve_package` para confirmar el origen, la versión y el SHA-256 del paquete. Luego inspecciona la ejecución secundaria `docker_acceptance` y sus artefactos de Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, registros de carril, tiempos de fase y comandos de repetición de ejecución. Prefiere volver a ejecutar el perfil de paquete fallido o los carriles Docker exactos en lugar de repetir toda la validación de lanzamiento. ## Smoke de instalación El workflow separado `Install Smoke` reutiliza el mismo script de alcance mediante su propio job `preflight`. Divide la cobertura smoke en `run_fast_install_smoke` y `run_full_install_smoke`. -- **Ruta rápida** se ejecuta para pull requests que tocan superficies Docker/paquete, cambios de paquete/manifiesto de plugin incluido o superficies principales de plugin/canal/Gateway/Plugin SDK que ejercitan los jobs de smoke Docker. Los cambios solo de origen en plugins incluidos, las ediciones solo de pruebas y las ediciones solo de documentación no reservan workers Docker. La ruta rápida compila una vez la imagen del Dockerfile raíz, comprueba la CLI, ejecuta el smoke de CLI de eliminación de agentes en workspace compartido, ejecuta el e2e de gateway-network del contenedor, verifica un argumento de compilación de extensión incluida y ejecuta el perfil Docker acotado de plugins incluidos con un timeout agregado de comando de 240 segundos (cada ejecución Docker de escenario está limitada por separado). -- **Ruta completa** conserva la instalación de paquete QR y la cobertura Docker/actualización del instalador para ejecuciones nocturnas programadas, despachos manuales, comprobaciones de lanzamiento por workflow-call y pull requests que realmente tocan superficies de instalador/paquete/Docker. En modo completo, install-smoke prepara o reutiliza una imagen de smoke GHCR del Dockerfile raíz de SHA objetivo, luego ejecuta la instalación de paquete QR, smokes del Dockerfile raíz/Gateway, smokes de instalador/actualización y el E2E Docker rápido de plugins incluidos como jobs separados para que el trabajo del instalador no espere detrás de los smokes de la imagen raíz. +- **Ruta rápida** se ejecuta para pull requests que tocan superficies de Docker/paquete, cambios de paquete/manifiesto de plugins incluidos o superficies principales de plugin/canal/gateway/Plugin SDK que ejercitan los jobs smoke de Docker. Los cambios de solo código fuente en plugins incluidos, las ediciones de solo pruebas y las ediciones solo de documentación no reservan workers de Docker. La ruta rápida compila la imagen raíz de Dockerfile una vez, comprueba la CLI, ejecuta el smoke de CLI de eliminación de agentes del espacio de trabajo compartido, ejecuta el e2e de gateway-network del contenedor, verifica un argumento de compilación de extensión incluida y ejecuta el perfil Docker acotado de plugins incluidos bajo un timeout agregado de comando de 240 segundos (cada ejecución Docker de escenario limitada por separado). +- **Ruta completa** conserva la instalación de paquete QR y la cobertura Docker/de actualización del instalador para ejecuciones programadas nocturnas, despachos manuales, verificaciones de lanzamiento por workflow-call y pull requests que realmente tocan superficies de instalador/paquete/Docker. En modo completo, install-smoke prepara o reutiliza una imagen smoke de GHCR para el Dockerfile raíz con SHA objetivo, luego ejecuta la instalación de paquete QR, smokes de Dockerfile raíz/gateway, smokes de instalador/actualización y el E2E Docker rápido de plugins incluidos como jobs separados para que el trabajo del instalador no espere detrás de los smokes de imagen raíz. -Los pushes a `main` (incluidos los commits de merge) no fuerzan la ruta completa; cuando la lógica de alcance de cambios solicitaría cobertura completa en un push, el workflow mantiene el smoke Docker rápido y deja el smoke completo de instalación para la validación nocturna o de lanzamiento. +Los pushes a `main` (incluidos commits de merge) no fuerzan la ruta completa; cuando la lógica de alcance de cambios solicitaría cobertura completa en un push, el workflow mantiene el smoke Docker rápido y deja el smoke completo de instalación para la validación nocturna o de lanzamiento. -El smoke lento de proveedor de imagen con instalación global de Bun está regulado por separado mediante `run_bun_global_install_smoke`. Se ejecuta en la programación nocturna y desde el workflow de comprobaciones de lanzamiento, y los despachos manuales de `Install Smoke` pueden optar por incluirlo, pero los pull requests y los pushes a `main` no. Las pruebas Docker de QR e instalador conservan sus propios Dockerfiles centrados en instalación. +El smoke lento del proveedor de imágenes con instalación global de Bun se controla por separado con `run_bun_global_install_smoke`. Se ejecuta en la programación nocturna y desde el workflow de verificaciones de lanzamiento, y los despachos manuales de `Install Smoke` pueden optar por incluirlo, pero los pull requests y pushes a `main` no. Las pruebas Docker de QR e instalador conservan sus propios Dockerfiles centrados en instalación. -## E2E Docker local +## E2E local de Docker `pnpm test:docker:all` precompila una imagen compartida de prueba en vivo, empaqueta OpenClaw una vez como tarball npm y compila dos imágenes compartidas de `scripts/e2e/Dockerfile`: -- un ejecutor Node/Git básico para rutas de instalador/actualización/dependencias de plugins; -- una imagen funcional que instala el mismo tarball en `/app` para rutas de funcionalidad normal. +- un ejecutor Node/Git básico para carriles de instalador/actualización/dependencias de plugins; +- una imagen funcional que instala el mismo tarball en `/app` para carriles de funcionalidad normal. -Las definiciones de rutas Docker viven en `scripts/lib/docker-e2e-scenarios.mjs`, la lógica del planificador vive en `scripts/lib/docker-e2e-plan.mjs` y el ejecutor solo ejecuta el plan seleccionado. El programador selecciona la imagen por ruta con `OPENCLAW_DOCKER_E2E_BARE_IMAGE` y `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, luego ejecuta rutas con `OPENCLAW_SKIP_DOCKER_BUILD=1`. +Las definiciones de carriles Docker viven en `scripts/lib/docker-e2e-scenarios.mjs`, la lógica del planificador vive en `scripts/lib/docker-e2e-plan.mjs` y el ejecutor solo ejecuta el plan seleccionado. El programador selecciona la imagen por carril con `OPENCLAW_DOCKER_E2E_BARE_IMAGE` y `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, luego ejecuta carriles con `OPENCLAW_SKIP_DOCKER_BUILD=1`. -### Ajustes configurables +### Parámetros ajustables | Variable | Predeterminado | Propósito | | -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Cantidad de ranuras del pool principal para rutas normales. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Cantidad de ranuras del pool final sensible a proveedores. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Límite de rutas en vivo concurrentes para que los proveedores no apliquen throttling. | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Límite de rutas de instalación npm concurrentes. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Límite de rutas multiservicio concurrentes. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Escalonamiento entre inicios de rutas para evitar tormentas de creación del daemon Docker; establece `0` para no escalonar. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout de reserva por ruta (120 minutos); las rutas en vivo/finales seleccionadas usan límites más estrictos. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | sin definir | `1` imprime el plan del programador sin ejecutar rutas. | -| `OPENCLAW_DOCKER_ALL_LANES` | sin definir | Lista exacta de rutas separadas por comas; omite el smoke de limpieza para que los agentes puedan reproducir una ruta fallida. | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Conteo de ranuras del pool principal para carriles normales. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Conteo de ranuras del pool de cola sensible a proveedores. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Límite de carriles en vivo concurrentes para que los proveedores no apliquen throttling. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Límite de carriles concurrentes de instalación npm. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Límite de carriles multiservicio concurrentes. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Escalonamiento entre inicios de carriles para evitar tormentas de creación del daemon Docker; define `0` para no escalonar. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout de respaldo por carril (120 minutos); algunos carriles live/tail usan límites más estrictos. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | sin definir | `1` imprime el plan del programador sin ejecutar carriles. | +| `OPENCLAW_DOCKER_ALL_LANES` | sin definir | Lista exacta de carriles separada por comas; omite el smoke de limpieza para que los agentes puedan reproducir un carril fallido. | -Una ruta más pesada que su límite efectivo todavía puede iniciar desde un pool vacío y luego se ejecuta sola hasta que libera capacidad. Los preflights agregados locales verifican Docker, eliminan contenedores E2E obsoletos de OpenClaw, emiten estado de rutas activas, persisten tiempos de ruta para ordenar de mayor a menor duración y, de forma predeterminada, dejan de programar nuevas rutas agrupadas tras el primer fallo. +Un carril más pesado que su límite efectivo aún puede arrancar desde un pool vacío, luego se ejecuta solo hasta liberar capacidad. Los preflights agregados locales de Docker eliminan contenedores OpenClaw E2E obsoletos, emiten estado de carriles activos, persisten tiempos de carriles para ordenamiento de mayor a menor duración y, por defecto, dejan de programar nuevos carriles agrupados tras el primer fallo. -### Workflow reutilizable en vivo/E2E +### Workflow reutilizable live/E2E -El workflow reutilizable en vivo/E2E pregunta a `scripts/test-docker-all.mjs --plan-json` qué cobertura de paquete, tipo de imagen, imagen en vivo, ruta y credenciales se requiere. Luego `scripts/docker-e2e.mjs` convierte ese plan en salidas y resúmenes de GitHub. Empaqueta OpenClaw mediante `scripts/package-openclaw-for-docker.mjs`, descarga un artefacto de paquete de la ejecución actual o descarga un artefacto de paquete desde `package_artifact_run_id`; valida el inventario del tarball; compila e inserta imágenes GHCR Docker E2E básicas/funcionales etiquetadas por digest de paquete mediante la caché de capas Docker de Blacksmith cuando el plan necesita rutas con paquete instalado; y reutiliza las entradas proporcionadas `docker_e2e_bare_image`/`docker_e2e_functional_image` o imágenes existentes por digest de paquete en lugar de recompilar. Los pulls de imágenes Docker se reintentan con un timeout acotado de 180 segundos por intento para que un flujo de registro/caché bloqueado reintente rápido en lugar de consumir la mayor parte de la ruta crítica de CI. +El workflow reutilizable live/E2E pregunta a `scripts/test-docker-all.mjs --plan-json` qué paquete, tipo de imagen, imagen live, carril y cobertura de credenciales se requieren. `scripts/docker-e2e.mjs` luego convierte ese plan en salidas y resúmenes de GitHub. Empaqueta OpenClaw mediante `scripts/package-openclaw-for-docker.mjs`, descarga un artefacto de paquete de la ejecución actual o descarga un artefacto de paquete desde `package_artifact_run_id`; valida el inventario del tarball; compila y sube imágenes GHCR Docker E2E básicas/funcionales etiquetadas por digest de paquete mediante la caché de capas Docker de Blacksmith cuando el plan necesita carriles con paquete instalado; y reutiliza las entradas `docker_e2e_bare_image`/`docker_e2e_functional_image` proporcionadas o imágenes existentes por digest de paquete en lugar de recompilar. Las descargas de imágenes Docker se reintentan con un timeout acotado de 180 segundos por intento, de modo que un flujo de registro/caché atascado se reintente rápido en lugar de consumir la mayor parte de la ruta crítica de CI. ### Fragmentos de ruta de lanzamiento -La cobertura Docker de lanzamiento ejecuta jobs fragmentados más pequeños con `OPENCLAW_SKIP_DOCKER_BUILD=1` para que cada fragmento descargue solo el tipo de imagen que necesita y ejecute varias rutas mediante el mismo programador ponderado: +La cobertura Docker de lanzamiento ejecuta jobs fragmentados más pequeños con `OPENCLAW_SKIP_DOCKER_BUILD=1`, de modo que cada fragmento descarga solo el tipo de imagen que necesita y ejecuta múltiples carriles mediante el mismo programador ponderado: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels` -Los fragmentos Docker de la versión actual son `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` hasta `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` y `bundled-channels-contracts`. El fragmento agregado `bundled-channels` sigue disponible para repeticiones manuales de una sola vez, y `plugins-runtime-core`, `plugins-runtime` y `plugins-integrations` siguen siendo alias agregados de plugin/runtime. El alias de vía `install-e2e` sigue siendo el alias agregado de repetición manual para ambas vías de instaladores de proveedores. El fragmento `bundled-channels` ejecuta vías divididas `bundled-channel-*` y `bundled-channel-update-*` en lugar de la vía serial todo en uno `bundled-channel-deps`. +Los fragmentos Docker de la versión actual son `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` hasta `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` y `bundled-channels-contracts`. El fragmento agregado `bundled-channels` sigue disponible para repeticiones manuales únicas, y `plugins-runtime-core`, `plugins-runtime` y `plugins-integrations` siguen siendo alias agregados de plugin/runtime. El alias de carril `install-e2e` sigue siendo el alias agregado de repetición manual para ambos carriles de instalador de proveedores. El fragmento `bundled-channels` ejecuta carriles divididos `bundled-channel-*` y `bundled-channel-update-*` en lugar del carril serial todo en uno `bundled-channel-deps`. -OpenWebUI se integra en `plugins-runtime-services` cuando la cobertura completa de la ruta de lanzamiento lo solicita, y conserva un fragmento independiente `openwebui` solo para despachos exclusivos de OpenWebUI. Las vías de actualización de canales incluidos reintentan una vez ante fallos transitorios de red de npm. +OpenWebUI se incluye en `plugins-runtime-services` cuando la cobertura completa de la ruta de lanzamiento lo solicita, y mantiene un fragmento independiente `openwebui` solo para despachos exclusivos de OpenWebUI. Los carriles de actualización de canales incluidos reintentan una vez ante fallos transitorios de red de npm. -Cada fragmento sube `.artifacts/docker-tests/` con registros de vías, tiempos, `summary.json`, `failures.json`, tiempos de fases, JSON del planificador, tablas de vías lentas y comandos de repetición por vía. La entrada `docker_lanes` del flujo de trabajo ejecuta las vías seleccionadas contra las imágenes preparadas en lugar de los trabajos de fragmentos, lo que mantiene la depuración de vías fallidas acotada a un trabajo Docker dirigido y prepara, descarga o reutiliza el artefacto del paquete para esa ejecución; si una vía seleccionada es una vía Docker en vivo, el trabajo dirigido compila localmente la imagen de pruebas en vivo para esa repetición. Los comandos generados de GitHub para repetir por vía incluyen `package_artifact_run_id`, `package_artifact_name` y entradas de imágenes preparadas cuando esos valores existen, de modo que una vía fallida pueda reutilizar el paquete y las imágenes exactos de la ejecución fallida. +Cada fragmento sube `.artifacts/docker-tests/` con registros de carril, tiempos, `summary.json`, `failures.json`, tiempos de fase, JSON del plan del programador, tablas de carriles lentos y comandos de repetición por carril. La entrada `docker_lanes` del flujo de trabajo ejecuta carriles seleccionados contra las imágenes preparadas en lugar de los trabajos de fragmento, lo que mantiene la depuración de carriles fallidos limitada a un trabajo Docker dirigido y prepara, descarga o reutiliza el artefacto del paquete para esa ejecución; si un carril seleccionado es un carril Docker en vivo, el trabajo dirigido compila localmente la imagen de pruebas en vivo para esa repetición. Los comandos de repetición por carril generados para GitHub incluyen `package_artifact_run_id`, `package_artifact_name` y entradas de imagen preparada cuando esos valores existen, de modo que un carril fallido pueda reutilizar el paquete y las imágenes exactos de la ejecución fallida. ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # slow-lane and phase critical-path summaries ``` -El flujo de trabajo programado en vivo/E2E ejecuta a diario la suite Docker completa de la ruta de lanzamiento. +El flujo de trabajo programado live/E2E ejecuta diariamente la suite Docker completa de la ruta de lanzamiento. ## Prelanzamiento de Plugin -`Plugin Prerelease` es una cobertura de producto/paquete más costosa, por lo que es un flujo de trabajo separado despachado por `Full Release Validation` o por un operador explícito. Las pull requests normales, los pushes a `main` y los despachos manuales independientes de CI mantienen esa suite desactivada. Equilibra las pruebas de plugins incluidos entre ocho workers de extensiones; esos trabajos de shards de extensiones ejecutan hasta dos grupos de configuración de plugins a la vez con un worker de Vitest por grupo y un heap de Node más grande para que los lotes de plugins con muchas importaciones no creen trabajos adicionales de CI. +`Plugin Prerelease` es una cobertura de producto/paquete más costosa, por lo que es un flujo de trabajo separado despachado por `Full Release Validation` o por un operador explícito. Las solicitudes de incorporación normales, los envíos a `main` y los despachos manuales independientes de CI mantienen esa suite desactivada. Equilibra las pruebas de plugins incluidos entre ocho workers de extensiones; esos trabajos de shard de extensiones ejecutan hasta dos grupos de configuración de plugins a la vez con un worker de Vitest por grupo y un heap de Node más grande para que los lotes de plugins con muchas importaciones no creen trabajos de CI adicionales. -## Laboratorio de QA +## QA Lab -El laboratorio de QA tiene vías dedicadas de CI fuera del flujo de trabajo principal con alcance inteligente. +QA Lab tiene carriles de CI dedicados fuera del flujo de trabajo principal con alcance inteligente. -- El flujo de trabajo `Parity gate` se ejecuta en cambios coincidentes de PR y en despacho manual; compila el runtime privado de QA y compara los paquetes agénticos simulados de GPT-5.5 y Opus 4.6. -- El flujo de trabajo `QA-Lab - All Lanes` se ejecuta cada noche en `main` y en despacho manual; despliega en abanico la compuerta de paridad simulada, la vía Matrix en vivo y las vías Telegram y Discord en vivo como trabajos paralelos. Los trabajos en vivo usan el entorno `qa-live-shared`, y Telegram/Discord usan leases de Convex. +- El flujo de trabajo `Parity gate` se ejecuta en cambios de PR coincidentes y en despacho manual; compila el runtime privado de QA y compara los paquetes agénticos simulados de GPT-5.5 y Opus 4.6. +- El flujo de trabajo `QA-Lab - All Lanes` se ejecuta cada noche en `main` y en despacho manual; distribuye en paralelo la puerta de paridad simulada, el carril Matrix en vivo y los carriles Telegram y Discord en vivo. Los trabajos en vivo usan el entorno `qa-live-shared`, y Telegram/Discord usan leases de Convex. -Las comprobaciones de lanzamiento ejecutan las vías de transporte en vivo de Matrix y Telegram con el proveedor simulado determinista y modelos calificados como simulados (`mock-openai/gpt-5.5` y `mock-openai/gpt-5.5-alt`) para que el contrato del canal quede aislado de la latencia de modelos en vivo y del inicio normal de plugins de proveedor. El Gateway de transporte en vivo desactiva la búsqueda de memoria porque la paridad de QA cubre el comportamiento de memoria por separado; la conectividad de proveedores está cubierta por las suites separadas de modelo en vivo, proveedor nativo y proveedor Docker. +Las comprobaciones de lanzamiento ejecutan los carriles de transporte en vivo de Matrix y Telegram con el proveedor simulado determinista y modelos calificados como simulados (`mock-openai/gpt-5.5` y `mock-openai/gpt-5.5-alt`) para que el contrato del canal quede aislado de la latencia de modelos en vivo y del arranque normal de plugins de proveedor. El Gateway de transporte en vivo desactiva la búsqueda de memoria porque la paridad de QA cubre el comportamiento de memoria por separado; la conectividad del proveedor está cubierta por las suites separadas de modelo en vivo, proveedor nativo y proveedor Docker. -Matrix usa `--profile fast` para compuertas programadas y de lanzamiento, y agrega `--fail-fast` solo cuando la CLI extraída lo admite. El valor predeterminado de la CLI y la entrada manual del flujo de trabajo siguen siendo `all`; el despacho manual `matrix_profile=all` siempre divide la cobertura completa de Matrix en trabajos `transport`, `media`, `e2ee-smoke`, `e2ee-deep` y `e2ee-cli`. +Matrix usa `--profile fast` para puertas programadas y de lanzamiento, y añade `--fail-fast` solo cuando la CLI extraída lo admite. El valor predeterminado de la CLI y la entrada manual del flujo de trabajo siguen siendo `all`; el despacho manual `matrix_profile=all` siempre divide la cobertura completa de Matrix en trabajos `transport`, `media`, `e2ee-smoke`, `e2ee-deep` y `e2ee-cli`. -`OpenClaw Release Checks` también ejecuta las vías críticas de lanzamiento del laboratorio de QA antes de la aprobación del lanzamiento; su compuerta de paridad de QA ejecuta los paquetes candidato y base como trabajos de vías paralelas, luego descarga ambos artefactos en un pequeño trabajo de informe para la comparación final de paridad. +`OpenClaw Release Checks` también ejecuta los carriles QA Lab críticos para el lanzamiento antes de la aprobación del lanzamiento; su puerta de paridad de QA ejecuta los paquetes candidato y de referencia como trabajos de carril paralelos, y luego descarga ambos artefactos en un pequeño trabajo de informe para la comparación final de paridad. -No pongas la ruta de integración de PR detrás de `Parity gate` a menos que el cambio realmente toque el runtime de QA, la paridad de paquetes de modelos o una superficie propiedad del flujo de trabajo de paridad. Para correcciones normales de canales, configuración, documentación o pruebas unitarias, trátalo como una señal opcional y sigue la evidencia de CI/comprobaciones con alcance. +No pongas la ruta de integración de PR detrás de `Parity gate` a menos que el cambio realmente toque el runtime de QA, la paridad de paquetes de modelos o una superficie propiedad del flujo de trabajo de paridad. Para arreglos normales de canal, configuración, documentación o pruebas unitarias, trátalo como una señal opcional y sigue la evidencia de CI/comprobaciones con alcance. ## CodeQL -El flujo de trabajo `CodeQL` es intencionalmente un escáner de seguridad estrecho de primera pasada, no el barrido completo del repositorio. Las ejecuciones diarias, manuales y de protección de pull requests que no son borrador escanean código de flujos de trabajo de Actions más las superficies JavaScript/TypeScript de mayor riesgo con consultas de seguridad de alta confianza filtradas por `security-severity` alta/crítica. +El flujo de trabajo `CodeQL` es intencionadamente un escáner de seguridad estrecho de primera pasada, no un barrido completo del repositorio. Las ejecuciones diarias, manuales y de protección de solicitudes de incorporación que no son borrador escanean código de flujos de trabajo de Actions más las superficies JavaScript/TypeScript de mayor riesgo con consultas de seguridad de alta confianza filtradas a `security-severity` alta/crítica. -La protección de pull requests se mantiene ligera: solo empieza para cambios bajo `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` o `src`, y ejecuta la misma matriz de seguridad de alta confianza que el flujo de trabajo programado. Android y macOS CodeQL quedan fuera de los valores predeterminados de PR. +La protección de solicitudes de incorporación se mantiene ligera: solo comienza para cambios bajo `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` o `src`, y ejecuta la misma matriz de seguridad de alta confianza que el flujo de trabajo programado. CodeQL para Android y macOS queda fuera de los valores predeterminados de PR. ### Categorías de seguridad | Categoría | Superficie | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | Auth, secretos, sandbox, cron y línea base del gateway | -| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementación de canales del core más runtime de plugins de canal, gateway, Plugin SDK, secretos, puntos de auditoría | -| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, análisis de IP, guardia de red, web-fetch y superficies de política SSRF de Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, helpers de ejecución de procesos, entrega saliente y compuertas de ejecución de herramientas de agentes | -| `/codeql-security-high/plugin-trust-boundary` | Instalación de Plugin, loader, manifiesto, registro, preparación de dependencias de runtime, carga de fuentes y superficies de confianza del contrato de paquete de Plugin SDK | +| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-security-high/core-auth-secrets` | Línea base de autenticación, secretos, sandbox, cron y Gateway | +| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementación de canales del núcleo más el runtime de plugins de canal, Gateway, Plugin SDK, secretos y puntos de auditoría | +| `/codeql-security-high/network-ssrf-boundary` | Superficies del núcleo de SSRF, análisis de IP, protección de red, web-fetch y política SSRF de Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, helpers de ejecución de procesos, entrega saliente y puertas de ejecución de herramientas de agente | +| `/codeql-security-high/plugin-trust-boundary` | Instalación de Plugin, cargador, manifiesto, registro, preparación de dependencias de runtime, carga de fuentes y superficies de confianza del contrato de paquete de Plugin SDK | ### Shards de seguridad específicos de plataforma -- `CodeQL Android Critical Security` — shard programado de seguridad de Android. Compila manualmente la app de Android para CodeQL en el runner Blacksmith Linux más pequeño aceptado por la sanidad del flujo de trabajo. Sube bajo `/codeql-critical-security/android`. -- `CodeQL macOS Critical Security` — shard semanal/manual de seguridad de macOS. Compila manualmente la app de macOS para CodeQL en Blacksmith macOS, filtra los resultados de compilación de dependencias fuera del SARIF subido y sube bajo `/codeql-critical-security/macos`. Se mantiene fuera de los valores predeterminados diarios porque la compilación de macOS domina el tiempo de ejecución incluso cuando está limpia. +- `CodeQL Android Critical Security` — shard programado de seguridad de Android. Compila la app Android manualmente para CodeQL en el runner Blacksmith Linux más pequeño aceptado por la validación de coherencia del flujo de trabajo. Sube bajo `/codeql-critical-security/android`. +- `CodeQL macOS Critical Security` — shard semanal/manual de seguridad de macOS. Compila la app macOS manualmente para CodeQL en Blacksmith macOS, filtra los resultados de compilación de dependencias fuera del SARIF subido y sube bajo `/codeql-critical-security/macos`. Se mantiene fuera de los valores predeterminados diarios porque la compilación de macOS domina el tiempo de ejecución incluso cuando está limpia. ### Categorías de calidad crítica -`CodeQL Critical Quality` es el shard correspondiente no relacionado con seguridad. Ejecuta únicamente consultas de calidad JavaScript/TypeScript de severidad de error y no relacionadas con seguridad sobre superficies estrechas de alto valor en el runner Blacksmith Linux más pequeño. Su protección de pull requests es intencionalmente más pequeña que el perfil programado: las PR que no son borrador solo ejecutan los shards de calidad coincidentes `channel-runtime-boundary`, `gateway-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `plugin-boundary` y `plugin-sdk-package-contract` para cambios de runtime de canal, protocolo/método de servidor de gateway, MCP/proceso/entrega saliente, runtime de proveedor/catálogo de modelos, loader de Plugin, Plugin SDK o contrato de paquete. Los cambios de configuración de CodeQL y de flujo de trabajo de calidad ejecutan los seis shards de calidad de PR. +`CodeQL Critical Quality` es el shard equivalente no relacionado con seguridad. Ejecuta solo consultas de calidad JavaScript/TypeScript de severidad de error y no relacionadas con seguridad sobre superficies estrechas de alto valor en el runner Blacksmith Linux más pequeño. Su protección de solicitudes de incorporación es intencionadamente más pequeña que el perfil programado: las PR que no son borrador solo ejecutan los shards coincidentes `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` y `plugin-sdk-reply-runtime` para cambios en código de ejecución de comandos/modelos/herramientas de agentes y despacho de respuestas, código de esquema/migración/IO de configuración, código de autenticación/secretos/sandbox/seguridad, runtime de canales del núcleo y plugins de canales incluidos, protocolo Gateway/método de servidor, runtime de memoria/enlace de SDK, MCP/proceso/entrega saliente, runtime de proveedor/catálogo de modelos, diagnósticos de sesión/colas de entrega, cargador de plugins, contrato de paquete/Plugin SDK o runtime de respuestas de Plugin SDK. Los cambios en la configuración de CodeQL y en el flujo de trabajo de calidad ejecutan los doce shards de calidad de PR. El despacho manual acepta: ``` -profile=all|channel-runtime-boundary|gateway-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary +profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` Los perfiles estrechos son ganchos de enseñanza/iteración para ejecutar un shard de calidad de forma aislada. -| Categoría | Superficie | -| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `/codeql-critical-quality/core-auth-secrets` | Auth, secretos, sandbox, cron y código del límite de seguridad del gateway | -| `/codeql-critical-quality/config-boundary` | Esquema de configuración, migración, normalización y contratos de IO | -| `/codeql-critical-quality/gateway-runtime-boundary` | Esquemas del protocolo Gateway y contratos de métodos de servidor | -| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementación de canales del core | -| `/codeql-critical-quality/agent-runtime-boundary` | Ejecución de comandos, despacho de modelos/proveedores, despacho y colas de respuesta automática, y contratos de runtime del plano de control ACP | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP y puentes de herramientas, helpers de supervisión de procesos y contratos de entrega saliente | -| `/codeql-critical-quality/memory-runtime-boundary` | SDK de host de memoria, fachadas de runtime de memoria, alias de Plugin SDK de memoria, pegamento de activación de runtime de memoria y comandos de doctor de memoria | -| `/codeql-critical-quality/session-diagnostics-boundary` | Internos de cola de respuestas, colas de entrega de sesiones, helpers de enlace/entrega de sesiones salientes, superficies de paquetes de eventos/registros de diagnóstico y contratos de CLI de doctor de sesión | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respuestas entrantes de Plugin SDK, helpers de payload/fragmentación/runtime de respuestas, opciones de respuesta de canal, colas de entrega y helpers de enlace de sesión/hilo | -| `/codeql-critical-quality/provider-runtime-boundary` | Normalización de catálogo de modelos, autenticación y descubrimiento de proveedores, registro de runtime de proveedores, valores predeterminados/catálogos de proveedores y registros de web/search/fetch/embedding | -| `/codeql-critical-quality/ui-control-plane` | Bootstrap de la UI de control, persistencia local, flujos de control de gateway y contratos de runtime del plano de control de tareas | -| `/codeql-critical-quality/web-media-runtime-boundary` | Fetch/search web del core, IO de medios, comprensión de medios, generación de imágenes y contratos de runtime de generación de medios | -| `/codeql-critical-quality/plugin-boundary` | Loader, registro, superficie pública y contratos de entrypoint de Plugin SDK | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Fuente publicada de Plugin SDK del lado del paquete y helpers de contrato de paquete de plugin | +| Categoría | Superficie | +| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-critical-quality/core-auth-secrets` | Código de límite de seguridad de autenticación, secretos, sandbox, Cron y Gateway | +| `/codeql-critical-quality/config-boundary` | Esquema de configuración, migración, normalización y contratos de E/S | +| `/codeql-critical-quality/gateway-runtime-boundary` | Esquemas del protocolo Gateway y contratos de métodos del servidor | +| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementación del canal core y del Plugin de canal incluido | +| `/codeql-critical-quality/agent-runtime-boundary` | Ejecución de comandos, despacho de modelos/proveedores, despacho y colas de respuesta automática, y contratos de runtime del plano de control ACP | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP y puentes de herramientas, helpers de supervisión de procesos y contratos de entrega saliente | +| `/codeql-critical-quality/memory-runtime-boundary` | SDK de host de memoria, fachadas de runtime de memoria, alias del SDK de Plugin de memoria, pegamento de activación del runtime de memoria y comandos doctor de memoria | +| `/codeql-critical-quality/session-diagnostics-boundary` | Elementos internos de la cola de respuestas, colas de entrega de sesión, helpers de vinculación/entrega de sesiones salientes, superficies de eventos diagnósticos/paquetes de logs y contratos de CLI de doctor de sesión | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respuestas entrantes del SDK de Plugin, helpers de payload/fragmentación/runtime de respuestas, opciones de respuesta de canal, colas de entrega y helpers de vinculación de sesión/hilo | +| `/codeql-critical-quality/provider-runtime-boundary` | Normalización del catálogo de modelos, autenticación y descubrimiento de proveedores, registro del runtime de proveedores, valores predeterminados/catálogos de proveedores y registros de web/búsqueda/fetch/embeddings | +| `/codeql-critical-quality/ui-control-plane` | Arranque de la UI de control, persistencia local, flujos de control de Gateway y contratos de runtime del plano de control de tareas | +| `/codeql-critical-quality/web-media-runtime-boundary` | Contratos de runtime de fetch/búsqueda web core, E/S de medios, comprensión de medios, generación de imágenes y generación de medios | +| `/codeql-critical-quality/plugin-boundary` | Contratos del cargador, registro, superficie pública y entrypoint del SDK de Plugin | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Fuente del SDK de Plugin del lado del paquete publicado y helpers de contrato del paquete de plugin | -La calidad se mantiene separada de la seguridad para que los hallazgos de calidad puedan programarse, medirse, deshabilitarse o ampliarse sin ocultar la señal de seguridad. La expansión de CodeQL para Swift, Python y plugins incluidos debe volver a añadirse como trabajo de seguimiento acotado o fragmentado solo después de que los perfiles estrechos tengan tiempo de ejecución y señal estables. +La calidad se mantiene separada de la seguridad para que los hallazgos de calidad puedan programarse, medirse, desactivarse o ampliarse sin oscurecer la señal de seguridad. La expansión de CodeQL para Swift, Python y plugins incluidos debe volver a añadirse como trabajo de seguimiento acotado o fragmentado solo después de que los perfiles estrechos tengan runtime y señal estables. ## Flujos de trabajo de mantenimiento ### Agente de documentación -El flujo de trabajo `Docs Agent` es un carril de mantenimiento de Codex impulsado por eventos para mantener la documentación existente alineada con los cambios integrados recientemente. No tiene una programación pura: una ejecución correcta de CI por push no bot en `main` puede activarlo, y el despacho manual puede ejecutarlo directamente. Las invocaciones por ejecución de flujo de trabajo se omiten cuando `main` ha avanzado o cuando se creó otra ejecución no omitida de Docs Agent en la última hora. Cuando se ejecuta, revisa el rango de commits desde el SHA de origen anterior no omitido de Docs Agent hasta el `main` actual, de modo que una ejecución por hora puede cubrir todos los cambios de main acumulados desde la última pasada de documentación. +El flujo de trabajo `Docs Agent` es una vía de mantenimiento de Codex orientada por eventos para mantener la documentación existente alineada con los cambios recientemente integrados. No tiene una programación pura: una ejecución de CI exitosa por push no bot en `main` puede activarlo, y el despacho manual puede ejecutarlo directamente. Las invocaciones por ejecución de workflow se omiten cuando `main` ha avanzado o cuando se creó otra ejecución no omitida de Docs Agent en la última hora. Cuando se ejecuta, revisa el rango de commits desde el SHA de origen anterior no omitido de Docs Agent hasta el `main` actual, de modo que una ejecución horaria puede cubrir todos los cambios de main acumulados desde la última pasada de documentación. ### Agente de rendimiento de pruebas -El flujo de trabajo `Test Performance Agent` es un carril de mantenimiento de Codex impulsado por eventos para pruebas lentas. No tiene una programación pura: una ejecución correcta de CI por push no bot en `main` puede activarlo, pero se omite si otra invocación por ejecución de flujo de trabajo ya se ejecutó o se está ejecutando ese día UTC. El despacho manual omite esa compuerta de actividad diaria. El carril crea un informe de rendimiento agrupado de Vitest de la suite completa, permite que Codex haga solo pequeñas correcciones de rendimiento de pruebas que preserven la cobertura en lugar de refactorizaciones amplias, luego vuelve a ejecutar el informe de la suite completa y rechaza los cambios que reduzcan el recuento base de pruebas que pasan. Si la base tiene pruebas fallidas, Codex puede corregir solo fallos evidentes y el informe de suite completa posterior al agente debe pasar antes de confirmar nada. Cuando `main` avanza antes de que llegue el push del bot, el carril hace rebase del parche validado, vuelve a ejecutar `pnpm check:changed` y reintenta el push; los parches obsoletos con conflictos se omiten. Usa Ubuntu alojado en GitHub para que la acción de Codex pueda mantener la misma postura de seguridad sin sudo que el agente de documentación. +El flujo de trabajo `Test Performance Agent` es una vía de mantenimiento de Codex orientada por eventos para pruebas lentas. No tiene una programación pura: una ejecución de CI exitosa por push no bot en `main` puede activarlo, pero se omite si otra invocación por ejecución de workflow ya se ejecutó o está en ejecución ese día UTC. El despacho manual omite esa puerta de actividad diaria. La vía crea un informe de rendimiento de Vitest agrupado de la suite completa, permite que Codex haga solo pequeñas correcciones de rendimiento de pruebas que preserven la cobertura en lugar de refactorizaciones amplias, luego vuelve a ejecutar el informe de la suite completa y rechaza cambios que reduzcan el recuento base de pruebas aprobadas. Si la base tiene pruebas fallidas, Codex puede corregir solo fallos obvios y el informe de suite completa posterior al agente debe pasar antes de que se confirme nada. Cuando `main` avanza antes de que llegue el push del bot, la vía hace rebase del parche validado, vuelve a ejecutar `pnpm check:changed` y reintenta el push; los parches obsoletos con conflictos se omiten. Usa Ubuntu alojado en GitHub para que la acción de Codex pueda mantener la misma postura de seguridad sin sudo que el agente de documentación. ### PR duplicadas después de la fusión -El flujo de trabajo `Duplicate PRs After Merge` es un flujo de trabajo manual de mantenedor para limpiar duplicados después de integrar. De forma predeterminada usa dry-run y solo cierra las PR listadas explícitamente cuando `apply=true`. Antes de modificar GitHub, verifica que la PR integrada esté fusionada y que cada duplicado tenga una incidencia referenciada compartida o hunks modificados superpuestos. +El flujo de trabajo `Duplicate PRs After Merge` es un workflow manual para mantenedores destinado a la limpieza de duplicados posterior a la integración. De forma predeterminada usa dry-run y solo cierra PR listadas explícitamente cuando `apply=true`. Antes de modificar GitHub, verifica que la PR integrada esté fusionada y que cada duplicado tenga un issue referenciado compartido o hunks modificados que se solapen. ```bash gh workflow run duplicate-after-merge.yml \ @@ -392,27 +392,27 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Compuertas de comprobación locales y enrutamiento de cambios +## Puertas de verificación local y enrutamiento de cambios -La lógica local de carriles cambiados vive en `scripts/changed-lanes.mjs` y la ejecuta `scripts/check-changed.mjs`. Esa compuerta de comprobación local es más estricta con los límites de arquitectura que el alcance amplio de la plataforma de CI: +La lógica local de vías modificadas vive en `scripts/changed-lanes.mjs` y la ejecuta `scripts/check-changed.mjs`. Esa puerta de verificación local es más estricta respecto a los límites de arquitectura que el alcance amplio de la plataforma de CI: -- los cambios de producción del núcleo ejecutan la comprobación de tipos de producción del núcleo y de pruebas del núcleo, además del lint y las guardas del núcleo; -- los cambios solo de pruebas del núcleo ejecutan solo la comprobación de tipos de pruebas del núcleo, además del lint del núcleo; -- los cambios de producción de extensión ejecutan la comprobación de tipos de producción de extensión y de pruebas de extensión, además del lint de extensión; -- los cambios solo de pruebas de extensión ejecutan la comprobación de tipos de pruebas de extensión, además del lint de extensión; -- los cambios públicos del SDK de Plugin o del contrato de plugin se expanden a la comprobación de tipos de extensiones porque las extensiones dependen de esos contratos del núcleo (los barridos de extensiones de Vitest siguen siendo trabajo de pruebas explícito); -- los aumentos de versión solo de metadatos de lanzamiento ejecutan comprobaciones dirigidas de versión/configuración/dependencias raíz; -- los cambios desconocidos de raíz/configuración fallan de forma segura hacia todos los carriles de comprobación. +- los cambios de producción core ejecutan typecheck de producción core y de pruebas core, además de lint/guards core; +- los cambios solo de pruebas core ejecutan solo typecheck de pruebas core, además de lint core; +- los cambios de producción de extensión ejecutan typecheck de producción de extensión y de pruebas de extensión, además de lint de extensión; +- los cambios solo de pruebas de extensión ejecutan typecheck de pruebas de extensión, además de lint de extensión; +- los cambios públicos del SDK de Plugin o del contrato de plugin se expanden al typecheck de extensiones porque las extensiones dependen de esos contratos core (los barridos de extensiones de Vitest siguen siendo trabajo de pruebas explícito); +- los aumentos de versión solo de metadatos de release ejecutan verificaciones específicas de versión/configuración/dependencias raíz; +- los cambios desconocidos de raíz/configuración fallan de forma segura hacia todas las vías de verificación. -El enrutamiento local de pruebas cambiadas vive en `scripts/test-projects.test-support.mjs` y es intencionalmente más barato que `check:changed`: las ediciones directas de pruebas se ejecutan a sí mismas, las ediciones de código fuente prefieren mapeos explícitos, luego pruebas hermanas y dependientes del grafo de importación. La configuración compartida de entrega de salas de grupo es uno de los mapeos explícitos: los cambios en la configuración de respuesta visible del grupo, el modo de entrega de respuestas de origen o el prompt del sistema de la herramienta de mensajes se enrutan por las pruebas de respuesta del núcleo, además de regresiones de entrega de Discord y Slack, para que un cambio predeterminado compartido falle antes del primer push de PR. Usa `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` solo cuando el cambio sea tan amplio en el arnés que el conjunto mapeado barato no sea un proxy confiable. +El enrutamiento local de pruebas modificadas vive en `scripts/test-projects.test-support.mjs` y es intencionalmente más barato que `check:changed`: las ediciones directas de pruebas se ejecutan a sí mismas, las ediciones de fuente prefieren mapeos explícitos, luego pruebas hermanas y dependientes del grafo de importación. La configuración compartida de entrega en salas de grupo es uno de los mapeos explícitos: los cambios en la configuración de respuesta visible de grupo, el modo de entrega de respuesta de origen o el prompt de sistema de la herramienta de mensajes pasan por las pruebas core de respuesta, además de regresiones de entrega de Discord y Slack, para que un cambio predeterminado compartido falle antes del primer push de PR. Usa `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` solo cuando el cambio sea lo bastante amplio en el harness como para que el conjunto mapeado barato no sea un proxy confiable. ## Validación de Testbox -Ejecuta Testbox desde la raíz del repo y prefiere una caja nueva precalentada para pruebas amplias. Antes de gastar una compuerta lenta en una caja reutilizada, vencida o que acaba de informar una sincronización inesperadamente grande, ejecuta primero `pnpm testbox:sanity` dentro de la caja. +Ejecuta Testbox desde la raíz del repo y prefiere una caja recién calentada para pruebas amplias. Antes de gastar una puerta lenta en una caja que fue reutilizada, expiró o acaba de informar una sincronización inesperadamente grande, ejecuta primero `pnpm testbox:sanity` dentro de la caja. -La comprobación de cordura falla rápido cuando desaparecen archivos raíz requeridos como `pnpm-lock.yaml` o cuando `git status --short` muestra al menos 200 eliminaciones rastreadas. Eso normalmente significa que el estado de sincronización remota no es una copia confiable de la PR; detén esa caja y precalienta una nueva en lugar de depurar el fallo de prueba del producto. Para PR intencionales con eliminaciones grandes, establece `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para esa ejecución de cordura. +La verificación de cordura falla rápido cuando archivos raíz requeridos como `pnpm-lock.yaml` desaparecieron o cuando `git status --short` muestra al menos 200 eliminaciones con seguimiento. Eso suele significar que el estado de sincronización remota no es una copia confiable de la PR; detén esa caja y calienta una nueva en lugar de depurar el fallo de prueba del producto. Para PR con eliminaciones grandes intencionales, establece `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para esa ejecución de cordura. -`pnpm testbox:run` también termina una invocación local de Blacksmith CLI que permanece en la fase de sincronización durante más de cinco minutos sin salida posterior a la sincronización. Establece `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para deshabilitar esa guarda, o usa un valor mayor en milisegundos para diffs locales inusualmente grandes. +`pnpm testbox:run` también termina una invocación local de la CLI de Blacksmith que permanece en la fase de sincronización durante más de cinco minutos sin salida posterior a la sincronización. Establece `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para desactivar esa protección, o usa un valor mayor en milisegundos para diffs locales inusualmente grandes. ## Relacionado diff --git a/docs/es/cli/cron.md b/docs/es/cli/cron.md index 400f46e4e..ac414182d 100644 --- a/docs/es/cli/cron.md +++ b/docs/es/cli/cron.md @@ -1,14 +1,14 @@ --- read_when: - - Quieres tareas programadas y reactivaciones + - Quieres trabajos programados y reactivaciones - Estás depurando la ejecución de Cron y los registros -summary: Referencia de CLI para `openclaw cron` (programar y ejecutar trabajos en segundo plano) +summary: Referencia de la CLI para `openclaw cron` (programar y ejecutar trabajos en segundo plano) title: Cron x-i18n: - generated_at: "2026-04-30T05:33:18Z" + generated_at: "2026-04-30T09:34:39Z" model: gpt-5.5 provider: openai - source_hash: 658498b09e0f0997d0f05dcdbdbd8822284d747df932f1c51e86f97b94cd81a7 + source_hash: 03d79e0e2c71f673c900b84eb2beeab705662c1d016e1d0567323c8da73060bb source_path: cli/cron.md workflow: 16 --- @@ -18,7 +18,7 @@ x-i18n: Gestiona trabajos de Cron para el programador del Gateway. -Ejecuta `openclaw cron --help` para ver toda la superficie de comandos. Consulta [trabajos de Cron](/es/automation/cron-jobs) para ver la guía conceptual. +Ejecuta `openclaw cron --help` para ver toda la superficie de comandos. Consulta [Trabajos de Cron](/es/automation/cron-jobs) para la guía conceptual. ## Sesiones @@ -34,16 +34,16 @@ Ejecuta `openclaw cron --help` para ver toda la superficie de comandos. Consulta - Las ejecuciones aisladas restablecen el contexto ambiental de conversación. El enrutamiento de canal y grupo, la política de envío/cola, la elevación, el origen y la vinculación de tiempo de ejecución de ACP se restablecen para la nueva ejecución. Las preferencias seguras y las anulaciones explícitas de modelo o autenticación seleccionadas por el usuario pueden conservarse entre ejecuciones. + Las ejecuciones aisladas restablecen el contexto de conversación ambiental. El enrutamiento de canales y grupos, la política de envío/cola, la elevación, el origen y la vinculación del runtime de ACP se restablecen para la nueva ejecución. Las preferencias seguras y las anulaciones explícitas de modelo o autenticación seleccionadas por el usuario pueden conservarse entre ejecuciones. ## Entrega -`openclaw cron list` y `openclaw cron show ` previsualizan la ruta de entrega resuelta. Para `channel: "last"`, la previsualización muestra si la ruta se resolvió desde la sesión principal o actual, o si fallará de forma cerrada. +`openclaw cron list` y `openclaw cron show ` previsualizan la ruta de entrega resuelta. Para `channel: "last"`, la vista previa muestra si la ruta se resolvió desde la sesión principal o la sesión actual, o si fallará de forma cerrada. -Los trabajos aislados de `cron add` usan entrega `--announce` de forma predeterminada. Usa `--no-deliver` para mantener la salida interna. `--deliver` permanece como alias obsoleto de `--announce`. +Los trabajos aislados de `cron add` usan entrega `--announce` de forma predeterminada. Usa `--no-deliver` para mantener la salida interna. `--deliver` permanece como un alias obsoleto de `--announce`. ### Propiedad de la entrega @@ -51,13 +51,13 @@ Los trabajos aislados de `cron add` usan entrega `--announce` de forma predeterm La entrega de chat de Cron aislado se comparte entre el agente y el ejecutor: - El agente puede enviar directamente usando la herramienta `message` cuando hay una ruta de chat disponible. -- `announce` entrega como respaldo la respuesta final solo cuando el agente no envió directamente al destino resuelto. -- `webhook` publica la carga útil terminada en una URL. -- `none` desactiva la entrega de respaldo del ejecutor. +- `announce` entrega como fallback la respuesta final solo cuando el agente no envió directamente al destino resuelto. +- `webhook` publica la carga finalizada en una URL. +- `none` desactiva la entrega fallback del ejecutor. -`--announce` es la entrega de respaldo del ejecutor para la respuesta final. `--no-deliver` desactiva ese respaldo, pero no elimina la herramienta `message` del agente cuando hay una ruta de chat disponible. +`--announce` es la entrega fallback del ejecutor para la respuesta final. `--no-deliver` desactiva ese fallback, pero no elimina la herramienta `message` del agente cuando hay una ruta de chat disponible. -Los recordatorios creados desde un chat activo conservan el destino de entrega de chat en vivo para la entrega de anuncio de respaldo. Las claves de sesión internas pueden estar en minúsculas; no las uses como fuente de verdad para IDs de proveedores sensibles a mayúsculas y minúsculas, como los IDs de sala de Matrix. +Los recordatorios creados desde un chat activo conservan el destino de entrega de chat en vivo para la entrega announce de fallback. Las claves de sesión internas pueden estar en minúsculas; no las uses como fuente de verdad para IDs de proveedor sensibles a mayúsculas y minúsculas, como los IDs de salas de Matrix. ### Entrega de fallos @@ -65,21 +65,19 @@ Las notificaciones de fallo se resuelven en este orden: 1. `delivery.failureDestination` en el trabajo. 2. `cron.failureDestination` global. -3. El destino principal de anuncio del trabajo (cuando no se establece un destino de fallo explícito). +3. El destino announce principal del trabajo (cuando no se define un destino de fallo explícito). Los trabajos de sesión principal solo pueden usar `delivery.failureDestination` cuando el modo de entrega principal es `webhook`. Los trabajos aislados lo aceptan en todos los modos. -Nota: las ejecuciones de Cron aisladas tratan los fallos de agente a nivel de ejecución como errores de trabajo incluso cuando -no se produce una carga útil de respuesta, por lo que los fallos de modelo/proveedor siguen incrementando los contadores -de errores y activando notificaciones de fallo. +Nota: las ejecuciones aisladas de Cron tratan los fallos de agente de nivel de ejecución como errores del trabajo incluso cuando no se produce ninguna carga de respuesta, por lo que los fallos de modelo/proveedor siguen incrementando los contadores de errores y activando notificaciones de fallo. ## Programación ### Trabajos de una sola ejecución -`--at ` programa una ejecución de una sola vez. Las fechas y horas sin desplazamiento se tratan como UTC, a menos que también pases `--tz `, que interpreta la hora de reloj de pared en la zona horaria indicada. +`--at ` programa una ejecución única. Las fechas y horas sin offset se tratan como UTC salvo que también pases `--tz `, que interpreta la hora de reloj de pared en la zona horaria dada. Los trabajos de una sola ejecución se eliminan después de completarse correctamente de forma predeterminada. Usa `--keep-after-run` para conservarlos. @@ -87,20 +85,20 @@ Los trabajos de una sola ejecución se eliminan después de completarse correcta ### Trabajos recurrentes -Los trabajos recurrentes usan reintentos con retroceso exponencial después de errores consecutivos: 30s, 1m, 5m, 15m, 60m. La programación vuelve a la normalidad después de la siguiente ejecución correcta. +Los trabajos recurrentes usan backoff exponencial de reintento después de errores consecutivos: 30s, 1m, 5m, 15m, 60m. La programación vuelve a la normalidad después de la siguiente ejecución correcta. -Las ejecuciones omitidas se registran por separado de los errores de ejecución. No afectan al retroceso de reintento, pero `openclaw cron edit --failure-alert-include-skipped` puede hacer que las alertas de fallo incluyan notificaciones repetidas de ejecuciones omitidas. +Las ejecuciones omitidas se registran por separado de los errores de ejecución. No afectan al backoff de reintento, pero `openclaw cron edit --failure-alert-include-skipped` puede optar por incluir notificaciones repetidas de ejecuciones omitidas en las alertas de fallo. -Para trabajos aislados que apuntan a un proveedor de modelo configurado localmente, Cron ejecuta una comprobación previa ligera del proveedor antes de iniciar el turno del agente. Los proveedores Loopback, de red privada y `.local` con `api: "ollama"` se sondean en `/api/tags`; los proveedores locales compatibles con OpenAI, como vLLM, SGLang y LM Studio, se sondean en `/models`. Si el endpoint no es alcanzable, la ejecución se registra como `skipped` y se reintenta en una programación posterior; los endpoints inactivos coincidentes se guardan en caché durante 5 minutos para evitar que muchos trabajos saturen el mismo servidor local. +Para trabajos aislados que apuntan a un proveedor de modelos local configurado, Cron ejecuta una precomprobación ligera del proveedor antes de iniciar el turno del agente. Los proveedores `api: "ollama"` de loopback, red privada y `.local` se prueban en `/api/tags`; los proveedores locales compatibles con OpenAI, como vLLM, SGLang y LM Studio, se prueban en `/models`. Si el endpoint no está disponible, la ejecución se registra como `skipped` y se reintenta en una programación posterior; los endpoints muertos coincidentes se almacenan en caché durante 5 minutos para evitar que muchos trabajos golpeen el mismo servidor local. -Nota: las definiciones de trabajos de Cron viven en `jobs.json`, mientras que el estado de tiempo de ejecución pendiente vive en `jobs-state.json`. Si `jobs.json` se edita externamente, el Gateway recarga las programaciones modificadas y borra los espacios pendientes obsoletos; las reescrituras solo de formato no borran el espacio pendiente. +Nota: las definiciones de trabajos de Cron viven en `jobs.json`, mientras que el estado de runtime pendiente vive en `jobs-state.json`. Si `jobs.json` se edita externamente, el Gateway recarga las programaciones modificadas y limpia los espacios pendientes obsoletos; las reescrituras solo de formato no limpian el espacio pendiente. ### Ejecuciones manuales -`openclaw cron run` devuelve en cuanto la ejecución manual se encola. Las respuestas correctas incluyen `{ ok: true, enqueued: true, runId }`. Usa `openclaw cron runs --id ` para seguir el resultado eventual. +`openclaw cron run` vuelve en cuanto la ejecución manual queda en cola. Las respuestas correctas incluyen `{ ok: true, enqueued: true, runId }`. Usa `openclaw cron runs --id ` para seguir el resultado eventual. -`openclaw cron run ` fuerza la ejecución de forma predeterminada. Usa `--due` para conservar el comportamiento anterior de "ejecutar solo si corresponde". +`openclaw cron run ` fuerza la ejecución de forma predeterminada. Usa `--due` para conservar el comportamiento anterior de "ejecutar solo si vence". ## Modelos @@ -108,60 +106,60 @@ Nota: las definiciones de trabajos de Cron viven en `jobs.json`, mientras que el `cron add|edit --model ` selecciona un modelo permitido para el trabajo. -Si el modelo no está permitido o no puede resolverse, Cron hace fallar la ejecución con un error de validación explícito en lugar de recurrir al agente del trabajo o a la selección de modelo predeterminada. +Si el modelo no está permitido o no puede resolverse, Cron falla la ejecución con un error de validación explícito en lugar de recurrir al agente del trabajo o a la selección de modelo predeterminada. -`--model` de Cron es un **principal del trabajo**, no una anulación `/model` de sesión de chat. Esto significa: +Cron `--model` es un **primario de trabajo**, no una anulación `/model` de sesión de chat. Eso significa: -- Los respaldos de modelo configurados siguen aplicándose cuando falla el modelo del trabajo seleccionado. -- La carga útil por trabajo `fallbacks` reemplaza la lista de respaldos configurada cuando está presente. -- Una lista de respaldos por trabajo vacía (`fallbacks: []` en la carga útil/API del trabajo) hace que la ejecución de Cron sea estricta. -- Cuando un trabajo tiene `--model` pero no hay ninguna lista de respaldos configurada, OpenClaw pasa una anulación explícita de respaldos vacía para que el principal del agente no se añada como destino de reintento oculto. +- Los fallbacks de modelo configurados siguen aplicándose cuando falla el modelo de trabajo seleccionado. +- `fallbacks` en la carga por trabajo reemplaza la lista de fallbacks configurada cuando está presente. +- Una lista de fallbacks por trabajo vacía (`fallbacks: []` en la carga/API del trabajo) hace que la ejecución de Cron sea estricta. +- Cuando un trabajo tiene `--model` pero no hay una lista de fallbacks configurada, OpenClaw pasa una anulación de fallback vacía explícita para que el primario del agente no se añada como destino de reintento oculto. -### Precedencia del modelo de Cron aislado +### Precedencia de modelo de Cron aislado Cron aislado resuelve el modelo activo en este orden: -1. Anulación de Gmail-hook. +1. Anulación de hook de Gmail. 2. `--model` por trabajo. 3. Anulación de modelo de sesión de Cron almacenada (cuando el usuario seleccionó una). -4. Selección de modelo del agente o predeterminada. +4. Selección de modelo de agente o predeterminada. ### Modo rápido -El modo rápido de Cron aislado sigue la selección de modelo en vivo resuelta. La configuración de modelo `params.fastMode` se aplica de forma predeterminada, pero una anulación de sesión almacenada `fastMode` sigue teniendo prioridad sobre la configuración. +El modo rápido de Cron aislado sigue la selección de modelo en vivo resuelta. La configuración de modelo `params.fastMode` se aplica de forma predeterminada, pero una anulación `fastMode` de sesión almacenada sigue teniendo prioridad sobre la configuración. ### Reintentos de cambio de modelo en vivo -Si una ejecución aislada lanza `LiveSessionModelSwitchError`, Cron conserva el proveedor y modelo cambiados (y la anulación de perfil de autenticación cambiada cuando está presente) para la ejecución activa antes de reintentar. El bucle externo de reintentos está limitado a dos reintentos de cambio después del intento inicial; luego se aborta en lugar de iterar indefinidamente. +Si una ejecución aislada lanza `LiveSessionModelSwitchError`, Cron persiste el proveedor y el modelo cambiados (y la anulación de perfil de autenticación cambiada cuando está presente) para la ejecución activa antes de reintentar. El bucle de reintento externo está limitado a dos reintentos de cambio después del intento inicial, y luego aborta en lugar de entrar en un bucle infinito. ## Salida de ejecución y denegaciones ### Supresión de acuses obsoletos -Los turnos de Cron aislado suprimen las respuestas obsoletas que solo son acuses. Si el primer resultado es solo una actualización de estado intermedia y ninguna ejecución de subagente descendiente es responsable de la respuesta eventual, Cron vuelve a solicitar una vez el resultado real antes de la entrega. +Los turnos de Cron aislado suprimen las respuestas obsoletas que solo son acuses. Si el primer resultado es solo una actualización de estado provisional y ninguna ejecución de subagente descendiente es responsable de la respuesta eventual, Cron vuelve a solicitar una vez el resultado real antes de la entrega. ### Supresión de token silencioso -Si una ejecución de Cron aislado devuelve solo el token silencioso (`NO_REPLY` o `no_reply`), Cron suprime tanto la entrega saliente directa como la ruta de resumen encolado de respaldo, por lo que no se publica nada de vuelta en el chat. +Si una ejecución de Cron aislado devuelve solo el token silencioso (`NO_REPLY` o `no_reply`), Cron suprime tanto la entrega saliente directa como la ruta de resumen en cola de fallback, por lo que no se publica nada de vuelta en el chat. ### Denegaciones estructuradas -Las ejecuciones de Cron aislado prefieren metadatos estructurados de denegación de ejecución de la ejecución incrustada y luego recurren a marcadores de denegación conocidos en la salida final, como `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` y frases de rechazo de vinculación de aprobación. +Las ejecuciones de Cron aislado prefieren metadatos estructurados de denegación de ejecución de la ejecución embebida, y luego recurren a marcadores de denegación conocidos en la salida final, como `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` y frases de rechazo de vinculación de aprobación. -`cron list` y el historial de ejecuciones muestran el motivo de la denegación en lugar de informar un comando bloqueado como `ok`. +`cron list` y el historial de ejecuciones muestran el motivo de denegación en lugar de informar un comando bloqueado como `ok`. ## Retención La retención y la poda se controlan en la configuración: -- `cron.sessionRetention` (predeterminado `24h`) poda las sesiones de ejecuciones aisladas completadas. +- `cron.sessionRetention` (predeterminado `24h`) poda las sesiones de ejecución aisladas completadas. - `cron.runLog.maxBytes` y `cron.runLog.keepLines` podan `~/.openclaw/cron/runs/.jsonl`. -## Migración de trabajos antiguos +## Migrar trabajos antiguos -Si tienes trabajos de Cron anteriores al formato actual de entrega y almacenamiento, ejecuta `openclaw doctor --fix`. Doctor normaliza campos heredados de Cron (`jobId`, `schedule.cron`, campos de entrega de nivel superior, incluido el `threadId` heredado, alias de entrega `provider` de carga útil) y migra trabajos simples de respaldo Webhook con `notify: true` a entrega Webhook explícita cuando `cron.webhook` está configurado. +Si tienes trabajos de Cron de antes del formato actual de entrega y almacenamiento, ejecuta `openclaw doctor --fix`. Doctor normaliza campos de Cron heredados (`jobId`, `schedule.cron`, campos de entrega de nivel superior, incluido `threadId` heredado, alias de entrega `provider` de carga) y migra trabajos simples de fallback de webhook con `notify: true` a entrega webhook explícita cuando `cron.webhook` está configurado. ## Ediciones comunes @@ -178,7 +176,7 @@ Desactiva la entrega para un trabajo aislado: openclaw cron edit --no-deliver ``` -Activa contexto de arranque ligero para un trabajo aislado: +Activa el contexto de arranque ligero para un trabajo aislado: ```bash openclaw cron edit --light-context @@ -208,9 +206,9 @@ openclaw cron add \ --no-deliver ``` -`--light-context` se aplica solo a trabajos de turno de agente aislados. Para ejecuciones de Cron, el modo ligero mantiene vacío el contexto de arranque en lugar de inyectar el conjunto completo de arranque del espacio de trabajo. +`--light-context` se aplica solo a trabajos de turnos de agente aislados. Para ejecuciones de Cron, el modo ligero mantiene vacío el contexto de arranque en lugar de inyectar el conjunto completo de arranque del workspace. -## Comandos comunes de administración +## Comandos de administración comunes Ejecución manual e inspección: @@ -222,9 +220,9 @@ openclaw cron run --due openclaw cron runs --id --limit 50 ``` -Las entradas de `cron runs` incluyen diagnósticos de entrega con el destino de Cron previsto, el destino resuelto, envíos con herramienta de mensajes, uso de respaldo y estado entregado. +Las entradas de `cron runs` incluyen diagnósticos de entrega con el destino de Cron previsto, el destino resuelto, envíos de la herramienta de mensajes, uso de fallback y estado entregado. -Redireccionamiento de agente y sesión: +Redirección de agente y sesión: ```bash openclaw cron edit --agent ops @@ -233,6 +231,8 @@ openclaw cron edit --session current openclaw cron edit --session "session:daily-brief" ``` +`openclaw cron add` advierte cuando se omite `--agent` en trabajos de turnos de agente y recurre al agente predeterminado (`main`). Pasa `--agent ` en el momento de creación para fijar un agente específico. + Ajustes de entrega: ```bash diff --git a/docs/es/gateway/local-models.md b/docs/es/gateway/local-models.md index fad4670d5..d348f4b09 100644 --- a/docs/es/gateway/local-models.md +++ b/docs/es/gateway/local-models.md @@ -3,28 +3,28 @@ read_when: - Quieres servir modelos desde tu propio equipo con GPU - Estás conectando LM Studio o un proxy compatible con OpenAI - Necesitas la guía más segura para modelos locales -summary: Ejecuta OpenClaw en LLM locales (LM Studio, vLLM, LiteLLM, endpoints personalizados de OpenAI) +summary: Ejecutar OpenClaw en LLM locales (LM Studio, vLLM, LiteLLM, puntos de conexión personalizados de OpenAI) title: Modelos locales x-i18n: - generated_at: "2026-04-30T05:42:29Z" + generated_at: "2026-04-30T09:34:49Z" model: gpt-5.5 provider: openai - source_hash: 2ec1be4eac371328c1efe80b71450019f68fb1114df90db1532a4ff72bfa0ab1 + source_hash: 283da11a7896c670d3a249eeb957a252cbda7f7457bd814bb0796f3ca9956723 source_path: gateway/local-models.md workflow: 16 --- -Local es viable, pero OpenClaw espera contexto grande y defensas sólidas contra la inyección de prompts. Las tarjetas pequeñas truncan el contexto y filtran seguridad. Apunta alto: **≥2 Mac Studios al máximo o un equipo GPU equivalente (~$30k+)**. Una sola GPU de **24 GB** funciona solo para prompts más ligeros con mayor latencia. Usa la **variante de modelo más grande / de tamaño completo que puedas ejecutar**; los checkpoints muy cuantizados o “pequeños” aumentan el riesgo de inyección de prompts (consulta [Seguridad](/es/gateway/security)). +Local es viable, pero OpenClaw espera un contexto grande y defensas sólidas contra la inyección de prompts. Las tarjetas pequeñas truncan el contexto y debilitan la seguridad. Apunta alto: **≥2 Mac Studios al máximo o una plataforma GPU equivalente (~$30k+)**. Una sola GPU de **24 GB** solo funciona para prompts más ligeros con mayor latencia. Usa la **variante de modelo más grande / de tamaño completo que puedas ejecutar**; los checkpoints cuantizados de forma agresiva o “pequeños” aumentan el riesgo de inyección de prompts (consulta [Seguridad](/es/gateway/security)). -Si quieres la configuración local con menos fricción, empieza con [LM Studio](/es/providers/lmstudio) u [Ollama](/es/providers/ollama) y `openclaw onboard`. Esta página es la guía opinada para stacks locales de gama alta y servidores locales personalizados compatibles con OpenAI. +Si quieres la configuración local con menos fricción, empieza con [LM Studio](/es/providers/lmstudio) u [Ollama](/es/providers/ollama) y `openclaw onboard`. Esta página es la guía con criterio para stacks locales de gama alta y servidores locales personalizados compatibles con OpenAI. -**Usuarios de WSL2 + Ollama + NVIDIA/CUDA:** El instalador oficial de Ollama para Linux habilita un servicio systemd con `Restart=always`. En configuraciones WSL2 con GPU, el inicio automático puede volver a cargar el último modelo durante el arranque y fijar la memoria del host. Si tu VM WSL2 se reinicia repetidamente después de habilitar Ollama, consulta [bucle de fallos de WSL2](/es/providers/ollama#wsl2-crash-loop-repeated-reboots). +**Usuarios de WSL2 + Ollama + NVIDIA/CUDA:** El instalador oficial de Ollama para Linux habilita un servicio systemd con `Restart=always`. En configuraciones WSL2 con GPU, el inicio automático puede recargar el último modelo durante el arranque y fijar memoria del host. Si tu VM de WSL2 se reinicia repetidamente después de habilitar Ollama, consulta [bucle de fallos de WSL2](/es/providers/ollama#wsl2-crash-loop-repeated-reboots). ## Recomendado: LM Studio + modelo local grande (Responses API) -El mejor stack local actual. Carga un modelo grande en LM Studio (por ejemplo, una compilación de tamaño completo de Qwen, DeepSeek o Llama), habilita el servidor local (predeterminado `http://127.0.0.1:1234`) y usa Responses API para mantener el razonamiento separado del texto final. +El mejor stack local actual. Carga un modelo grande en LM Studio (por ejemplo, una compilación de tamaño completo de Qwen, DeepSeek o Llama), habilita el servidor local (`http://127.0.0.1:1234` de forma predeterminada) y usa Responses API para mantener el razonamiento separado del texto final. ```json5 { @@ -64,15 +64,15 @@ El mejor stack local actual. Carga un modelo grande en LM Studio (por ejemplo, u **Lista de configuración** - Instala LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- En LM Studio, descarga la **compilación de modelo más grande disponible** (evita variantes “pequeñas” o muy cuantizadas), inicia el servidor y confirma que `http://127.0.0.1:1234/v1/models` la enumera. +- En LM Studio, descarga la **compilación de modelo más grande disponible** (evita variantes “pequeñas” o muy cuantizadas), inicia el servidor y confirma que `http://127.0.0.1:1234/v1/models` lo liste. - Sustituye `my-local-model` por el ID de modelo real que se muestra en LM Studio. - Mantén el modelo cargado; la carga en frío añade latencia de inicio. - Ajusta `contextWindow`/`maxTokens` si tu compilación de LM Studio difiere. -- Para WhatsApp, mantente en Responses API para que solo se envíe el texto final. +- Para WhatsApp, usa Responses API para que solo se envíe el texto final. -Mantén los modelos alojados configurados incluso cuando ejecutes localmente; usa `models.mode: "merge"` para que las alternativas sigan disponibles. +Mantén los modelos alojados configurados incluso cuando ejecutes en local; usa `models.mode: "merge"` para que los fallbacks sigan disponibles. -### Configuración híbrida: primario alojado, alternativa local +### Configuración híbrida: primario alojado, fallback local ```json5 { @@ -113,18 +113,18 @@ Mantén los modelos alojados configurados incluso cuando ejecutes localmente; us } ``` -### Local primero con red de seguridad alojada +### Prioridad local con red de seguridad alojada -Intercambia el orden del primario y las alternativas; conserva el mismo bloque de proveedores y `models.mode: "merge"` para poder recurrir a Sonnet u Opus cuando la máquina local no esté disponible. +Intercambia el orden de primario y fallback; mantén el mismo bloque de providers y `models.mode: "merge"` para poder recurrir a Sonnet u Opus cuando la máquina local esté caída. ### Alojamiento regional / enrutamiento de datos -- También existen variantes alojadas de MiniMax/Kimi/GLM en OpenRouter con endpoints fijados por región (por ejemplo, alojadas en EE. UU.). Elige allí la variante regional para mantener el tráfico en la jurisdicción que elijas sin dejar de usar `models.mode: "merge"` para las alternativas de Anthropic/OpenAI. -- Solo local sigue siendo la vía de privacidad más sólida; el enrutamiento regional alojado es el punto intermedio cuando necesitas funciones de proveedor pero quieres controlar el flujo de datos. +- También existen variantes alojadas de MiniMax/Kimi/GLM en OpenRouter con endpoints fijados por región (por ejemplo, alojados en EE. UU.). Elige allí la variante regional para mantener el tráfico en la jurisdicción que elijas y seguir usando `models.mode: "merge"` para fallbacks de Anthropic/OpenAI. +- Solo local sigue siendo la ruta de privacidad más sólida; el enrutamiento regional alojado es el punto intermedio cuando necesitas funciones del proveedor, pero quieres controlar el flujo de datos. ## Otros proxies locales compatibles con OpenAI -MLX (`mlx_lm.server`), vLLM, SGLang, LiteLLM, OAI-proxy o gateways personalizados funcionan si exponen un endpoint de estilo OpenAI `/v1/chat/completions`. Usa el adaptador Chat Completions salvo que el backend documente explícitamente compatibilidad con `/v1/responses`. Sustituye el bloque de proveedor anterior por tu endpoint e ID de modelo: +MLX (`mlx_lm.server`), vLLM, SGLang, LiteLLM, OAI-proxy o Gateways personalizados funcionan si exponen un endpoint `/v1/chat/completions` de estilo OpenAI. Usa el adaptador Chat Completions salvo que el backend documente explícitamente compatibilidad con `/v1/responses`. Sustituye el bloque de provider anterior por tu endpoint e ID de modelo: ```json5 { @@ -158,33 +158,33 @@ MLX (`mlx_lm.server`), vLLM, SGLang, LiteLLM, OAI-proxy o gateways personalizado } ``` -Si `api` se omite en un proveedor personalizado con `baseUrl`, OpenClaw usa de forma predeterminada `openai-completions`. Los endpoints de loopback como `127.0.0.1` son de confianza automáticamente; los endpoints LAN, tailnet y DNS privado aún necesitan `request.allowPrivateNetwork: true`. +Si se omite `api` en un provider personalizado con `baseUrl`, OpenClaw usa `openai-completions` de forma predeterminada. Los endpoints de loopback como `127.0.0.1` se consideran de confianza automáticamente; los endpoints de LAN, tailnet y DNS privado aún necesitan `request.allowPrivateNetwork: true`. -El valor `models.providers..models[].id` es local del proveedor. No incluyas allí el prefijo del proveedor. Por ejemplo, un servidor MLX iniciado con `mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` debe usar este ID de catálogo y referencia de modelo: +El valor `models.providers..models[].id` es local al provider. No incluyas ahí el prefijo del provider. Por ejemplo, un servidor MLX iniciado con `mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` debería usar este ID de catálogo y referencia de modelo: - `models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"` - `agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"` -Configura `input: ["text", "image"]` en modelos locales o con proxy de visión para que los adjuntos de imagen se inyecten en los turnos del agente. El onboarding interactivo de proveedores personalizados infiere los ID comunes de modelos de visión y solo pregunta por nombres desconocidos. El onboarding no interactivo usa la misma inferencia; usa `--custom-image-input` para ID de visión desconocidos o `--custom-text-input` cuando un modelo que parece conocido es solo de texto detrás de tu endpoint. +Configura `input: ["text", "image"]` en modelos locales o de visión proxied para que los adjuntos de imagen se inyecten en los turnos del agente. El onboarding interactivo de provider personalizado infiere IDs comunes de modelos de visión y solo pregunta por nombres desconocidos. El onboarding no interactivo usa la misma inferencia; usa `--custom-image-input` para IDs de visión desconocidos o `--custom-text-input` cuando un modelo que parece conocido es solo de texto detrás de tu endpoint. -Mantén `models.mode: "merge"` para que los modelos alojados sigan disponibles como alternativas. Usa `models.providers..timeoutSeconds` para servidores de modelos locales o remotos lentos antes de aumentar `agents.defaults.timeoutSeconds`. El timeout del proveedor se aplica solo a solicitudes HTTP de modelo, incluida la conexión, encabezados, streaming del cuerpo y la cancelación total de guarded-fetch. +Mantén `models.mode: "merge"` para que los modelos alojados sigan disponibles como fallbacks. Usa `models.providers..timeoutSeconds` para servidores de modelos locales o remotos lentos antes de aumentar `agents.defaults.timeoutSeconds`. El timeout del provider se aplica solo a solicitudes HTTP de modelo, incluida la conexión, las cabeceras, el streaming del cuerpo y la cancelación total de guarded-fetch. -Para proveedores personalizados compatibles con OpenAI, se acepta persistir un marcador local no secreto como `apiKey: "ollama-local"` cuando `baseUrl` resuelve a loopback, una LAN privada, `.local` o un hostname simple. OpenClaw lo trata como una credencial local válida en lugar de informar una clave ausente. Usa un valor real para cualquier proveedor que acepte un hostname público. +Para providers personalizados compatibles con OpenAI, se acepta persistir un marcador local no secreto como `apiKey: "ollama-local"` cuando `baseUrl` resuelve a loopback, una LAN privada, `.local` o un hostname simple. OpenClaw lo trata como una credencial local válida en lugar de informar que falta una clave. Usa un valor real para cualquier provider que acepte un hostname público. -Nota de comportamiento para backends `/v1` locales o con proxy: +Nota de comportamiento para backends `/v1` locales/proxied: - OpenClaw los trata como rutas compatibles con OpenAI de estilo proxy, no como endpoints nativos de OpenAI -- aquí no se aplica el moldeado de solicitudes exclusivo de OpenAI nativo: sin `service_tier`, sin `store` de Responses, sin moldeado de payload de compatibilidad de razonamiento de OpenAI y sin indicios de caché de prompts -- los encabezados ocultos de atribución de OpenClaw (`originator`, `version`, `User-Agent`) no se inyectan en estas URL de proxy personalizadas +- el moldeado de solicitudes exclusivo de OpenAI nativo no se aplica aquí: sin `service_tier`, sin `store` de Responses, sin moldeado de payload de compatibilidad de razonamiento de OpenAI y sin pistas de caché de prompts +- las cabeceras ocultas de atribución de OpenClaw (`originator`, `version`, `User-Agent`) no se inyectan en estas URL de proxy personalizadas Notas de compatibilidad para backends compatibles con OpenAI más estrictos: -- Algunos servidores aceptan solo `messages[].content` como cadena en Chat Completions, no arrays estructurados de partes de contenido. Configura `models.providers..models[].compat.requiresStringContent: true` para esos endpoints. -- Algunos modelos locales emiten solicitudes de herramientas independientes entre corchetes como texto, como `[tool_name]` seguido de JSON y `[END_TOOL_REQUEST]`. OpenClaw las promueve a llamadas reales de herramientas solo cuando el nombre coincide exactamente con una herramienta registrada para el turno; de lo contrario, el bloque se trata como texto no compatible y se oculta de las respuestas visibles para el usuario. -- Si un modelo emite JSON, XML o texto de estilo ReAct que parece una llamada de herramienta pero el proveedor no emitió una invocación estructurada, OpenClaw lo deja como texto y registra una advertencia con el ID de ejecución, proveedor/modelo, patrón detectado y nombre de herramienta cuando esté disponible. Trátalo como incompatibilidad de llamadas de herramientas del proveedor/modelo, no como una ejecución de herramienta completada. -- Si las herramientas aparecen como texto del asistente en lugar de ejecutarse, por ejemplo JSON sin procesar, XML, sintaxis ReAct o un array `tool_calls` vacío en la respuesta del proveedor, primero verifica que el servidor esté usando una plantilla/parser de chat capaz de llamadas de herramientas. Para backends Chat Completions compatibles con OpenAI cuyo parser solo funciona cuando el uso de herramientas se fuerza, configura una sobrescritura de solicitud por modelo en lugar de depender del análisis de texto: +- Algunos servidores solo aceptan `messages[].content` como cadena en Chat Completions, no arrays estructurados de partes de contenido. Configura `models.providers..models[].compat.requiresStringContent: true` para esos endpoints. +- Algunos modelos locales emiten solicitudes de herramientas entre corchetes independientes como texto, como `[tool_name]` seguido de JSON y `[END_TOOL_REQUEST]`. OpenClaw las promueve a llamadas reales a herramientas solo cuando el nombre coincide exactamente con una herramienta registrada para el turno; de lo contrario, el bloque se trata como texto no compatible y se oculta de las respuestas visibles para el usuario. +- Si un modelo emite JSON, XML o texto de estilo ReAct que parece una llamada a herramienta, pero el provider no emitió una invocación estructurada, OpenClaw lo deja como texto y registra una advertencia con el ID de ejecución, provider/modelo, patrón detectado y nombre de herramienta cuando esté disponible. Trátalo como incompatibilidad de llamadas a herramientas del provider/modelo, no como una ejecución de herramienta completada. +- Si las herramientas aparecen como texto del asistente en lugar de ejecutarse, por ejemplo JSON sin procesar, XML, sintaxis ReAct o un array `tool_calls` vacío en la respuesta del provider, primero verifica que el servidor esté usando una plantilla/parser de chat con capacidad para llamadas a herramientas. Para backends Chat Completions compatibles con OpenAI cuyo parser solo funciona cuando el uso de herramientas es obligatorio, configura una anulación de solicitud por modelo en lugar de depender del análisis de texto: ```json5 { @@ -204,13 +204,14 @@ Notas de compatibilidad para backends compatibles con OpenAI más estrictos: } ``` - Usa esto solo para modelos/sesiones donde cada turno normal deba llamar a una herramienta. Sobrescribe el valor de proxy predeterminado de OpenClaw de `tool_choice: "auto"`. Sustituye `local/my-local-model` por la referencia exacta de proveedor/modelo que muestra `openclaw models list`. + Usa esto solo para modelos/sesiones en los que cada turno normal debe llamar a una herramienta. Anula el valor proxy predeterminado de OpenClaw de `tool_choice: "auto"`. + Sustituye `local/my-local-model` por la referencia exacta provider/modelo mostrada por `openclaw models list`. ```bash openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge ``` -- Si un modelo personalizado compatible con OpenAI acepta esfuerzos de razonamiento de OpenAI más allá del perfil integrado, decláralos en el bloque de compatibilidad del modelo. Añadir `"xhigh"` aquí hace que `/think xhigh`, los selectores de sesión, la validación de Gateway y la validación de `llm-task` expongan el nivel para esa referencia configurada de proveedor/modelo: +- Si un modelo personalizado compatible con OpenAI acepta esfuerzos de razonamiento de OpenAI más allá del perfil integrado, decláralos en el bloque compat del modelo. Añadir `"xhigh"` aquí hace que `/think xhigh`, los selectores de sesión, la validación de Gateway y la validación de `llm-task` expongan el nivel para esa referencia provider/modelo configurada: ```json5 { @@ -241,56 +242,56 @@ Notas de compatibilidad para backends compatibles con OpenAI más estrictos: } ``` -- Algunos backends locales más pequeños o más estrictos son inestables con la forma completa del prompt de tiempo de ejecución de agente de OpenClaw, especialmente cuando se incluyen esquemas de herramientas. Primero verifica la ruta del proveedor con la sonda local ligera: +- Algunos backends locales más pequeños o más estrictos son inestables con la forma completa del prompt del entorno de ejecución de agente de OpenClaw, especialmente cuando se incluyen esquemas de herramientas. Primero verifica la ruta del provider con la prueba local ligera: ```bash openclaw infer model run --local --model --prompt "Reply with exactly: pong" --json ``` - Para verificar la ruta de Gateway sin la forma completa del prompt de agente, usa en su lugar la sonda de modelo de Gateway: + Para verificar la ruta de Gateway sin la forma completa del prompt de agente, usa en su lugar la prueba de modelo de Gateway: ```bash openclaw infer model run --gateway --model --prompt "Reply with exactly: pong" --json ``` - Ambas sondas de modelo, local y de Gateway, envían solo el prompt proporcionado. La sonda de Gateway aún valida el enrutamiento de Gateway, la autenticación y la selección de proveedor, pero omite intencionalmente la transcripción previa de la sesión, el contexto AGENTS/bootstrap, el ensamblado del motor de contexto, las herramientas y los servidores MCP incluidos. + Ambas pruebas de modelo, local y Gateway, envían solo el prompt proporcionado. La prueba de Gateway sigue validando el enrutamiento de Gateway, la autenticación y la selección de provider, pero omite intencionalmente el historial previo de la sesión, el contexto AGENTS/bootstrap, el ensamblaje del motor de contexto, las herramientas y los servidores MCP incluidos. Si eso funciona pero los turnos normales del agente de OpenClaw fallan, primero prueba `agents.defaults.experimental.localModelLean: true` para quitar herramientas predeterminadas pesadas como `browser`, `cron` y `message`; esta es una marca experimental, no una configuración estable de modo predeterminado. Consulta - [Funciones experimentales](/es/concepts/experimental-features). Si todavía falla, prueba + [Funciones experimentales](/es/concepts/experimental-features). Si eso sigue fallando, prueba `models.providers..models[].compat.supportsTools: false`. -- Si el backend todavía falla solo en ejecuciones más grandes de OpenClaw, el problema restante - suele ser capacidad del modelo/servidor ascendente o un error del backend, no la +- Si el servicio servidor sigue fallando solo en ejecuciones más grandes de OpenClaw, el problema restante + suele ser la capacidad del modelo/servidor ascendente o un error del servidor subyacente, no la capa de transporte de OpenClaw. ## Solución de problemas - ¿Gateway puede alcanzar el proxy? `curl http://127.0.0.1:1234/v1/models`. -- ¿El modelo de LM Studio está descargado? Recárgalo; el arranque en frío es una causa común de “bloqueos”. +- ¿Modelo de LM Studio descargado? Vuelve a cargarlo; el arranque en frío es una causa común de “bloqueo”. - ¿El servidor local dice `terminated`, `ECONNRESET` o cierra el flujo a mitad del turno? - OpenClaw registra un `model.call.error.failureKind` de baja cardinalidad más la - instantánea de RSS/heap del proceso de OpenClaw en los diagnósticos. Para presión - de memoria en LM Studio/Ollama, compara esa marca de tiempo con el registro del servidor o el registro de cierres / - jetsam de macOS para confirmar si el servidor de modelos fue terminado. -- OpenClaw advierte cuando la ventana de contexto detectada está por debajo de **32k** y bloquea por debajo de **16k**. Si llegas a esa comprobación previa, aumenta el límite de contexto del servidor/modelo o elige un modelo más grande. -- ¿Errores de contexto? Reduce `contextWindow` o aumenta el límite de tu servidor. + OpenClaw registra un `model.call.error.failureKind` de baja cardinalidad junto con la + instantánea de RSS/heap del proceso de OpenClaw en los diagnósticos. Para presión de memoria + de LM Studio/Ollama, compara esa marca de tiempo con el registro del servidor o el registro de fallos / + jetsam de macOS para confirmar si se finalizó el servidor del modelo. +- OpenClaw deriva los umbrales de comprobación previa de la ventana de contexto a partir de la ventana del modelo detectada, o de la ventana de modelo sin límite cuando `agents.defaults.contextTokens` reduce la ventana efectiva. Advierte por debajo del 20% con un piso de **8k**. Los bloqueos estrictos usan el umbral del 10% con un piso de **4k**, limitado a la ventana de contexto efectiva para que los metadatos de modelo sobredimensionados no puedan rechazar un límite de usuario que, por lo demás, es válido. Si alcanzas esa comprobación previa, aumenta el límite de contexto del servidor/modelo o elige un modelo más grande. +- ¿Errores de contexto? Baja `contextWindow` o aumenta el límite de tu servidor. - ¿El servidor compatible con OpenAI devuelve `messages[].content ... expected a string`? - Agrega `compat.requiresStringContent: true` en esa entrada de modelo. + Añade `compat.requiresStringContent: true` en esa entrada de modelo. - ¿Las llamadas directas pequeñas a `/v1/chat/completions` funcionan, pero `openclaw infer model run --local` falla en Gemma u otro modelo local? Revisa primero la URL del proveedor, la referencia del modelo, el marcador de autenticación - y los registros del servidor; `model run` local no incluye herramientas de agente. - Si `model run` local funciona pero los turnos de agente más grandes fallan, reduce la + y los registros del servidor; `model run` local no incluye herramientas del agente. + Si `model run` local funciona pero fallan turnos más grandes del agente, reduce la superficie de herramientas del agente con `localModelLean` o `compat.supportsTools: false`. -- ¿Las llamadas a herramientas aparecen como texto JSON/XML/ReAct sin procesar, o el proveedor devuelve un - arreglo `tool_calls` vacío? No agregues un proxy que convierta a ciegas el - texto del asistente en ejecución de herramientas. Corrige primero la plantilla/parser de chat del servidor. Si el - modelo solo funciona cuando se fuerza el uso de herramientas, agrega la anulación por modelo +- ¿Las llamadas de herramientas aparecen como texto JSON/XML/ReAct sin procesar, o el proveedor devuelve un + arreglo `tool_calls` vacío? No añadas un proxy que convierta a ciegas texto del asistente + en ejecución de herramientas. Corrige primero la plantilla/parser de chat del servidor. Si el + modelo solo funciona cuando se fuerza el uso de herramientas, añade la anulación por modelo `params.extra_body.tool_choice: "required"` anterior y usa esa entrada de modelo - solo para sesiones donde se espera una llamada a herramienta en cada turno. -- Seguridad: los modelos locales omiten los filtros del lado del proveedor; mantén los agentes acotados y la Compaction activada para limitar el alcance de inyección de prompts. + solo para sesiones donde se espera una llamada de herramienta en cada turno. +- Seguridad: los modelos locales omiten los filtros del lado del proveedor; mantén los agentes acotados y Compaction activado para limitar el radio de impacto de la inyección de prompts. ## Relacionado diff --git a/docs/es/plugins/community.md b/docs/es/plugins/community.md index 47b1af66f..44dca918b 100644 --- a/docs/es/plugins/community.md +++ b/docs/es/plugins/community.md @@ -1,41 +1,41 @@ --- read_when: - - Quieres encontrar plugins de terceros para OpenClaw + - Quieres encontrar plugins de OpenClaw de terceros - Quieres publicar o listar tu propio Plugin -summary: 'Plugins de OpenClaw mantenidos por la comunidad: explóralos, instálalos y envía el tuyo' +summary: 'Plugins de OpenClaw mantenidos por la comunidad: explora, instala y envía el tuyo' title: Plugins de la comunidad x-i18n: - generated_at: "2026-04-30T05:51:46Z" + generated_at: "2026-04-30T09:34:49Z" model: gpt-5.5 provider: openai - source_hash: a54130fefc55042d53270e5f7f4b49a4aad715570743013fbfe06b0e2fa067d0 + source_hash: 9685aaf141b739a2a745a6184201ac86689e4284bec6eb068ffbd0d53fb4ecf1 source_path: plugins/community.md workflow: 16 --- -Los plugins comunitarios son paquetes de terceros que amplían OpenClaw con nuevos -canales, herramientas, proveedores u otras capacidades. La comunidad los crea y -mantiene, normalmente se publican en [ClawHub](/es/tools/clawhub), y se pueden instalar -con un solo comando. Npm sigue siendo una alternativa compatible para los paquetes que -aún no se han trasladado a ClawHub. +Los plugins comunitarios son paquetes de terceros que extienden OpenClaw con nuevos +canales, herramientas, proveedores u otras capacidades. La comunidad los crea y mantiene, +normalmente se publican en [ClawHub](/es/tools/clawhub), y se pueden instalar +con un solo comando. Npm sigue siendo una alternativa compatible para paquetes que aún no se han +movido a ClawHub. ClawHub es la superficie canónica de descubrimiento para plugins comunitarios. No abras -PRs solo de documentación únicamente para añadir aquí tu plugin para que sea descubrible; -publícalo en ClawHub en su lugar. +PRs solo de documentación solo para agregar tu plugin aquí por visibilidad; publícalo en +ClawHub en su lugar. ```bash openclaw plugins install ``` -OpenClaw consulta primero ClawHub y recurre automáticamente a npm como alternativa. +OpenClaw comprueba ClawHub primero y recurre automáticamente a npm. ## Plugins listados ### Apify -Extrae datos de cualquier sitio web con más de 20.000 scrapers listos para usar. Permite que tu agente +Extrae datos de cualquier sitio web con más de 20,000 scrapers listos para usar. Permite que tu agente extraiga datos de Instagram, Facebook, TikTok, YouTube, Google Maps, Google -Search, sitios de comercio electrónico y más, solo con pedirlo. +Search, sitios de comercio electrónico y más, con solo pedirlo. - **npm:** `@apify/apify-openclaw-plugin` - **repo:** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin) @@ -47,8 +47,8 @@ openclaw plugins install @apify/apify-openclaw-plugin ### Codex App Server Bridge Puente independiente de OpenClaw para conversaciones de Codex App Server. Vincula un chat a -un hilo de Codex, habla con él en texto plano y contrólalo con comandos nativos de chat -para reanudar, planificar, revisar, seleccionar modelo, compaction y más. +un hilo de Codex, habla con él mediante texto sin formato y contrólalo con comandos nativos +del chat para reanudar, planificar, revisar, seleccionar modelo, Compaction y más. - **npm:** `openclaw-codex-app-server` - **repo:** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server) @@ -59,8 +59,8 @@ openclaw plugins install openclaw-codex-app-server ### DingTalk -Integración de robot empresarial usando el modo Stream. Admite mensajes de texto, imágenes y -archivos mediante cualquier cliente de DingTalk. +Integración de robot empresarial mediante el modo Stream. Admite mensajes de texto, imágenes y +archivos a través de cualquier cliente de DingTalk. - **npm:** `@largezhou/ddingtalk` - **repo:** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk) @@ -71,8 +71,8 @@ openclaw plugins install @largezhou/ddingtalk ### Lossless Claw (LCM) -Plugin de gestión de contexto sin pérdidas para OpenClaw. Resumen de conversaciones basado en DAG -con compaction incremental: conserva la fidelidad completa del contexto +Plugin de Lossless Context Management para OpenClaw. Resumen de conversaciones basado en DAG +con compactación incremental: conserva la fidelidad completa del contexto mientras reduce el uso de tokens. - **npm:** `@martian-engineering/lossless-claw` @@ -85,7 +85,7 @@ openclaw plugins install @martian-engineering/lossless-claw ### Opik Plugin oficial que exporta trazas de agentes a Opik. Supervisa el comportamiento del agente, -el costo, los tokens, los errores y más. +coste, tokens, errores y más. - **npm:** `@opik/opik-openclaw` - **repo:** [github.com/comet-ml/opik-openclaw](https://github.com/comet-ml/opik-openclaw) @@ -96,9 +96,9 @@ openclaw plugins install @opik/opik-openclaw ### Prometheus Avatar -Dale a tu agente de OpenClaw un avatar Live2D con sincronización labial en tiempo real, -expresiones de emoción y texto a voz. Incluye herramientas de creación para generación de activos con IA -y despliegue con un clic en Prometheus Marketplace. Actualmente está en alpha. +Dale a tu agente de OpenClaw un avatar Live2D con sincronización labial en tiempo real, expresiones +emocionales y conversión de texto a voz. Incluye herramientas para creadores para la generación de recursos con IA +y despliegue con un clic en Prometheus Marketplace. Actualmente en alfa. - **npm:** `@prometheusavatar/openclaw-plugin` - **repo:** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar) @@ -109,8 +109,8 @@ openclaw plugins install @prometheusavatar/openclaw-plugin ### QQbot -Conecta OpenClaw a QQ mediante la QQ Bot API. Admite chats privados, menciones de grupo, -mensajes de canal y medios enriquecidos, incluidos voz, imágenes, videos +Conecta OpenClaw a QQ mediante la API de QQ Bot. Admite chats privados, menciones +de grupo, mensajes de canal y medios enriquecidos, incluidos voz, imágenes, videos y archivos. Las versiones actuales de OpenClaw incluyen QQ Bot. Usa la configuración incluida en @@ -126,10 +126,10 @@ openclaw plugins install @tencent-connect/openclaw-qqbot ### wecom -Plugin de canal WeCom para OpenClaw del equipo Tencent WeCom. Impulsado por -conexiones persistentes de WeCom Bot WebSocket, admite mensajes directos y chats de grupo, -respuestas en streaming, mensajería proactiva, procesamiento de imágenes/archivos, formato Markdown, -control de acceso integrado y habilidades de documentos/reuniones/mensajería. +Plugin de canal WeCom para OpenClaw por el equipo de Tencent WeCom. Impulsado por +conexiones persistentes WeCom Bot WebSocket, admite mensajes directos y chats de grupo, +respuestas en streaming, mensajería proactiva, procesamiento de imágenes/archivos, formato +Markdown, control de acceso integrado y Skills de documentos/reuniones/mensajería. - **npm:** `@wecom/wecom-openclaw-plugin` - **repo:** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin) @@ -140,13 +140,13 @@ openclaw plugins install @wecom/wecom-openclaw-plugin ### Yuanbao -Plugin de canal Yuanbao para OpenClaw del equipo Tencent Yuanbao. Impulsado por +Plugin de canal Yuanbao para OpenClaw por el equipo de Tencent Yuanbao. Impulsado por conexiones persistentes WebSocket, admite mensajes directos y chats de grupo, respuestas en streaming, mensajería proactiva, procesamiento de imágenes/archivos/audio/video, formato Markdown, control de acceso integrado y menús de comandos slash. - **npm:** `openclaw-plugin-yuanbao` -- **repo:** [github.com/yb-claw/openclaw-plugin-yuanbao](https://github.com/yb-claw/openclaw-plugin-yuanbao) +- **repo:** [github.com/YuanbaoTeam/yuanbao-openclaw-plugin](https://github.com/YuanbaoTeam/yuanbao-openclaw-plugin) ```bash openclaw plugins install openclaw-plugin-yuanbao @@ -159,24 +159,24 @@ Damos la bienvenida a plugins comunitarios que sean útiles, estén documentados Tu plugin debe poder instalarse mediante `openclaw plugins install \`. - Publica en [ClawHub](/es/tools/clawhub) salvo que necesites específicamente una - distribución solo por npm. - Consulta [Crear Plugins](/es/plugins/building-plugins) para ver la guía completa. + Publica en [ClawHub](/es/tools/clawhub), salvo que necesites específicamente una distribución + solo por npm. + Consulta [Crear plugins](/es/plugins/building-plugins) para ver la guía completa. - El código fuente debe estar en un repositorio público con documentación de configuración y un gestor de - incidencias. + El código fuente debe estar en un repositorio público con documentación de configuración y un rastreador + de incidencias. - No necesitas un PR de documentación solo para hacer que tu plugin sea descubrible. Publícalo + No necesitas un PR de documentación solo para que tu plugin sea descubrible. Publícalo en ClawHub en su lugar. Abre un PR de documentación solo cuando la documentación fuente de OpenClaw necesite un cambio real - de contenido, como corregir la guía de instalación o añadir documentación + de contenido, como corregir las instrucciones de instalación o agregar documentación entre repositorios que pertenezca al conjunto principal de documentación. @@ -184,17 +184,17 @@ Damos la bienvenida a plugins comunitarios que sean útiles, estén documentados ## Nivel de calidad -| Requisito | Motivo | -| -------------------------- | ----------------------------------------------- | -| Publicado en ClawHub o npm | Los usuarios necesitan que `openclaw plugins install` funcione | -| Repositorio público de GitHub | Revisión del código fuente, seguimiento de incidencias, transparencia | +| Requisito | Motivo | +| --------------------------- | --------------------------------------------- | +| Publicado en ClawHub o npm | Los usuarios necesitan que `openclaw plugins install` funcione | +| Repositorio público de GitHub | Revisión de código fuente, seguimiento de incidencias, transparencia | | Documentación de configuración y uso | Los usuarios necesitan saber cómo configurarlo | -| Mantenimiento activo | Actualizaciones recientes o gestión receptiva de incidencias | +| Mantenimiento activo | Actualizaciones recientes o gestión receptiva de incidencias | -Los wrappers de bajo esfuerzo, la propiedad poco clara o los paquetes sin mantenimiento pueden rechazarse. +Los wrappers de bajo esfuerzo, la titularidad poco clara o los paquetes sin mantenimiento pueden rechazarse. ## Relacionado -- [Instalar y configurar Plugins](/es/tools/plugin) — cómo instalar cualquier plugin -- [Crear Plugins](/es/plugins/building-plugins) — crea el tuyo propio -- [Manifiesto de Plugin](/es/plugins/manifest) — esquema del manifiesto +- [Instalar y configurar plugins](/es/tools/plugin) — cómo instalar cualquier plugin +- [Crear plugins](/es/plugins/building-plugins) — crea el tuyo +- [Manifiesto de plugin](/es/plugins/manifest) — esquema del manifiesto diff --git a/docs/es/tools/skills.md b/docs/es/tools/skills.md index 50be846aa..71c456db5 100644 --- a/docs/es/tools/skills.md +++ b/docs/es/tools/skills.md @@ -1,54 +1,58 @@ --- read_when: - - Agregar o modificar Skills - - Cambiar el control de acceso de Skills, las listas de permitidos o las reglas de carga + - Añadir o modificar Skills + - Cambiar el control de activación de Skills, las listas de permitidos o las reglas de carga - Comprender la precedencia de Skills y el comportamiento de las instantáneas sidebarTitle: Skills -summary: 'Skills: administradas frente a las del espacio de trabajo, reglas de control, listas de permitidos de agentes y cableado de configuración' +summary: 'Skills: administradas frente a espacio de trabajo, reglas de control, listas de permitidos de agentes y conexión de configuración' title: Skills x-i18n: - generated_at: "2026-04-30T06:06:13Z" + generated_at: "2026-04-30T09:34:53Z" model: gpt-5.5 provider: openai - source_hash: f744f5e961f872cae02aa0ed77e0bbba35e4715f5762ac45ce190b74b2fd8c5e + source_hash: d7dd17f52119bf0a0bb197025070abb68f7667a7d22c3d5fa6ef2f666110a45a source_path: tools/skills.md workflow: 16 --- -OpenClaw usa carpetas de skill **compatibles con [AgentSkills](https://agentskills.io)** para enseñar al agente cómo usar herramientas. Cada skill es un directorio que contiene un `SKILL.md` con frontmatter YAML e instrucciones. OpenClaw carga Skills incluidas junto con anulaciones locales opcionales, y las filtra en el momento de carga según el entorno, la configuración y la presencia de binarios. +OpenClaw usa carpetas de skills **compatibles con [AgentSkills](https://agentskills.io)** para enseñar al agente a usar herramientas. Cada skill es un directorio que contiene un `SKILL.md` con frontmatter YAML e instrucciones. OpenClaw carga skills incluidas más reemplazos locales opcionales, y las filtra en tiempo de carga según el entorno, la configuración y la presencia de binarios. ## Ubicaciones y precedencia -OpenClaw carga Skills desde estas fuentes, **primero la precedencia más alta**: +OpenClaw carga skills desde estas fuentes, **con la mayor precedencia primero**: -| # | Fuente | Ruta | -| --- | --------------------- | -------------------------------- | -| 1 | Skills del espacio de trabajo | `/skills` | -| 2 | Skills de agente del proyecto | `/.agents/skills` | -| 3 | Skills de agente personales | `~/.agents/skills` | +| # | Fuente | Ruta | +| --- | ------------------------- | -------------------------------- | +| 1 | Skills del workspace | `/skills` | +| 2 | Skills del agente del proyecto | `/.agents/skills` | +| 3 | Skills personales del agente | `~/.agents/skills` | | 4 | Skills gestionadas/locales | `~/.openclaw/skills` | -| 5 | Skills incluidas | incluidas con la instalación | -| 6 | Carpetas de skill adicionales | `skills.load.extraDirs` (configuración) | +| 5 | Skills incluidas | incluidas con la instalación | +| 6 | Carpetas de skills adicionales | `skills.load.extraDirs` (config) | -Si un nombre de skill entra en conflicto, gana la fuente con mayor precedencia. +Si un nombre de skill entra en conflicto, gana la fuente de mayor precedencia. ## Skills por agente frente a compartidas -En configuraciones **multiagente**, cada agente tiene su propio espacio de trabajo: +En configuraciones **multiagente**, cada agente tiene su propio workspace: | Ámbito | Ruta | Visible para | -| -------------------- | ------------------------------------------- | --------------------------- | -| Por agente | `/skills` | Solo ese agente | -| Agente del proyecto | `/.agents/skills` | Solo el agente de ese espacio de trabajo | +| -------------------- | ------------------------------------------- | ---------------------------- | +| Por agente | `/skills` | Solo ese agente | +| Agente del proyecto | `/.agents/skills` | Solo el agente de ese workspace | | Agente personal | `~/.agents/skills` | Todos los agentes en esa máquina | | Gestionadas/locales compartidas | `~/.openclaw/skills` | Todos los agentes en esa máquina | -| Directorios adicionales compartidos | `skills.load.extraDirs` (precedencia más baja) | Todos los agentes en esa máquina | +| Directorios adicionales compartidos | `skills.load.extraDirs` (menor precedencia) | Todos los agentes en esa máquina | -Mismo nombre en varios lugares → gana la fuente con mayor precedencia. El espacio de trabajo supera al agente del proyecto, supera al agente personal, supera a gestionadas/locales, supera a incluidas, supera a directorios adicionales. +Mismo nombre en varios lugares → gana la fuente de mayor precedencia. Workspace supera a +agente del proyecto, supera a agente personal, supera a gestionadas/locales, supera a incluidas, +supera a directorios adicionales. -## Listas de permitidos de Skills de agente +## Listas de permisos de skills por agente -La **ubicación** de un skill y la **visibilidad** de un skill son controles separados. La ubicación/precedencia decide qué copia de un skill con el mismo nombre gana; las listas de permitidos del agente deciden qué Skills puede usar realmente un agente. +La **ubicación** de la skill y la **visibilidad** de la skill son controles separados. +La ubicación/precedencia decide qué copia de una skill con el mismo nombre gana; las listas +de permisos del agente deciden qué skills puede usar realmente un agente. ```json5 { @@ -57,71 +61,83 @@ La **ubicación** de un skill y la **visibilidad** de un skill son controles sep skills: ["github", "weather"], }, list: [ - { id: "writer" }, // hereda github, weather - { id: "docs", skills: ["docs-search"] }, // reemplaza los valores predeterminados - { id: "locked-down", skills: [] }, // sin Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` - - - Omite `agents.defaults.skills` para permitir Skills sin restricciones de forma predeterminada. + + - Omite `agents.defaults.skills` para permitir skills sin restricciones de forma predeterminada. - Omite `agents.list[].skills` para heredar `agents.defaults.skills`. - - Define `agents.list[].skills: []` para no permitir ningún skill. + - Define `agents.list[].skills: []` para no permitir skills. - Una lista no vacía `agents.list[].skills` es el conjunto **final** para ese - agente; no se combina con los valores predeterminados. - - La lista de permitidos efectiva se aplica a la construcción de prompts, el - descubrimiento de comandos de barra de Skills, la sincronización de sandbox y las instantáneas de Skills. + agente; no se fusiona con los valores predeterminados. + - La lista de permisos efectiva se aplica a la construcción de prompts, el descubrimiento + de comandos slash de skills, la sincronización del sandbox y las instantáneas de skills. -## Plugins y Skills +## Plugins y skills -Los Plugins pueden incluir sus propios Skills enumerando directorios `skills` en -`openclaw.plugin.json` (rutas relativas a la raíz del Plugin). Los Skills del Plugin -se cargan cuando el Plugin está habilitado. Este es el lugar adecuado para guías operativas específicas de herramientas que son demasiado largas para la descripción de la herramienta, pero que deberían estar disponibles siempre que el Plugin esté instalado; por ejemplo, el Plugin de navegador incluye un skill `browser-automation` para control de navegador de varios pasos. +Los Plugins pueden incluir sus propias skills listando directorios `skills` en +`openclaw.plugin.json` (rutas relativas a la raíz del Plugin). Las skills del Plugin +se cargan cuando el Plugin está habilitado. Este es el lugar adecuado para guías operativas +específicas de herramientas que son demasiado largas para la descripción de la herramienta pero deben estar +disponibles siempre que el Plugin esté instalado; por ejemplo, el Plugin de navegador +incluye una skill `browser-automation` para el control del navegador en varios pasos. -Los directorios de Skills de Plugin se fusionan en la misma ruta de baja precedencia que -`skills.load.extraDirs`, por lo que un skill incluido, gestionado, de agente o -de espacio de trabajo con el mismo nombre los anula. Puedes restringirlos mediante +Los directorios de skills de Plugin se fusionan en la misma ruta de baja precedencia que +`skills.load.extraDirs`, por lo que una skill incluida, gestionada, de agente o de workspace +con el mismo nombre los reemplaza. Puedes condicionarlas mediante `metadata.openclaw.requires.config` en la entrada de configuración del Plugin. Consulta [Plugins](/es/tools/plugin) para descubrimiento/configuración y [Herramientas](/es/tools) para -la superficie de herramientas que enseñan esos Skills. +la superficie de herramientas que esas skills enseñan. -## Skill Workshop +## Taller de Skills -El Plugin opcional y experimental **Skill Workshop** puede crear o actualizar -Skills de espacio de trabajo a partir de procedimientos reutilizables observados durante el trabajo del agente. Está deshabilitado de forma predeterminada y debe habilitarse explícitamente mediante +El Plugin opcional y experimental **Taller de Skills** puede crear o actualizar +skills del workspace a partir de procedimientos reutilizables observados durante el trabajo del agente. Está +deshabilitado de forma predeterminada y debe habilitarse explícitamente mediante `plugins.entries.skill-workshop`. -Skill Workshop escribe solo en `/skills`, escanea el contenido generado, +Taller de Skills escribe solo en `/skills`, analiza el contenido generado, admite aprobación pendiente o escrituras seguras automáticas, pone en cuarentena -propuestas inseguras y actualiza la instantánea de Skills después de escrituras correctas para que los nuevos Skills estén disponibles sin reiniciar el Gateway. +propuestas inseguras y actualiza la instantánea de skills después de escrituras +correctas para que las nuevas skills estén disponibles sin reiniciar el Gateway. -Úsalo para correcciones como _"la próxima vez, verifica la atribución del GIF"_ o -flujos de trabajo difíciles de consolidar, como listas de comprobación de QA de medios. Empieza con aprobación pendiente; usa escrituras automáticas solo en espacios de trabajo de confianza después de revisar sus propuestas. Guía completa: [Plugin Skill Workshop](/es/plugins/skill-workshop). +Úsalo para correcciones como _"la próxima vez, verifica la atribución de GIF"_ o +flujos de trabajo difíciles de obtener, como listas de comprobación de QA de medios. Empieza con aprobación +pendiente; usa escrituras automáticas solo en workspaces de confianza después de revisar +sus propuestas. Guía completa: [Plugin Taller de Skills](/es/plugins/skill-workshop). ## ClawHub (instalación y sincronización) -[ClawHub](https://clawhub.ai) es el registro público de Skills para OpenClaw. +[ClawHub](https://clawhub.ai) es el registro público de skills para OpenClaw. Usa los comandos nativos `openclaw skills` para descubrir/instalar/actualizar, o la -CLI `clawhub` independiente para flujos de trabajo de publicación/sincronización. Guía completa: +CLI `clawhub` separada para flujos de trabajo de publicación/sincronización. Guía completa: [ClawHub](/es/tools/clawhub). | Acción | Comando | | ---------------------------------- | -------------------------------------- | -| Instalar un skill en el espacio de trabajo | `openclaw skills install ` | -| Actualizar todos los Skills instalados | `openclaw skills update --all` | -| Sincronizar (escanear + publicar actualizaciones) | `clawhub sync --all` | +| Instalar una skill en el workspace | `openclaw skills install ` | +| Actualizar todas las skills instaladas | `openclaw skills update --all` | +| Sincronizar (analizar + publicar actualizaciones) | `clawhub sync --all` | -`openclaw skills install` nativo instala en el directorio `skills/` del espacio de trabajo activo. La CLI `clawhub` independiente también instala en -`./skills` bajo tu directorio de trabajo actual (o recurre al espacio de trabajo de OpenClaw configurado). OpenClaw lo recoge como +`openclaw skills install` nativo instala en el directorio `skills/` del workspace activo. +La CLI `clawhub` separada también instala en `./skills` bajo tu directorio de trabajo actual +(o recurre al workspace configurado de OpenClaw). OpenClaw lo recoge como `/skills` en la siguiente sesión. +Las raíces de skills configuradas también admiten un nivel de agrupación, como +`skills///SKILL.md`, para que las skills de terceros relacionadas puedan +mantenerse bajo una carpeta compartida sin un escaneo recursivo amplio. -Las páginas de Skills de ClawHub muestran el estado del análisis de seguridad más reciente antes de instalar, con páginas de detalle de analizadores para VirusTotal, ClawScan y análisis estático. +Las páginas de skills de ClawHub muestran el estado más reciente del análisis de seguridad antes de instalar, +con páginas de detalle del analizador para VirusTotal, ClawScan y análisis estático. `openclaw skills install ` sigue siendo solo la ruta de instalación; los publicadores recuperan falsos positivos mediante el panel de ClawHub o `clawhub skill rescan `. @@ -129,15 +145,15 @@ recuperan falsos positivos mediante el panel de ClawHub o ## Seguridad -Trata los Skills de terceros como **código no confiable**. Léelos antes de habilitarlos. +Trata las skills de terceros como **código no confiable**. Léelas antes de habilitarlas. Prefiere ejecuciones en sandbox para entradas no confiables y herramientas riesgosas. Consulta [Sandboxing](/es/gateway/sandboxing) para los controles del lado del agente. -- El descubrimiento de Skills de espacio de trabajo y directorios adicionales solo acepta raíces de skill y archivos `SKILL.md` cuyo realpath resuelto permanezca dentro de la raíz configurada. -- Las instalaciones de dependencias de Skills respaldadas por Gateway (`skills.install`, onboarding y la UI de configuración de Skills) ejecutan el analizador integrado de código peligroso antes de ejecutar metadatos de instalador. Los hallazgos `critical` bloquean de forma predeterminada salvo que el llamador establezca explícitamente la anulación peligrosa; los hallazgos sospechosos solo siguen avisando. -- `openclaw skills install ` es diferente: descarga una carpeta de skill de ClawHub en el espacio de trabajo y no usa la ruta de metadatos de instalador anterior. -- `skills.entries.*.env` y `skills.entries.*.apiKey` inyectan secretos en el proceso **host** para ese turno del agente (no en el sandbox). Mantén los secretos fuera de prompts y registros. +- El descubrimiento de skills de workspace y directorios adicionales solo acepta raíces de skills y archivos `SKILL.md` cuyo realpath resuelto permanezca dentro de la raíz configurada. +- Las instalaciones de dependencias de skills respaldadas por Gateway (`skills.install`, onboarding y la UI de configuración de Skills) ejecutan el analizador de código peligroso integrado antes de ejecutar metadatos de instalador. Los hallazgos `critical` bloquean de forma predeterminada salvo que el llamador defina explícitamente el override peligroso; los hallazgos sospechosos siguen solo advirtiendo. +- `openclaw skills install ` es distinto: descarga una carpeta de skill de ClawHub en el workspace y no usa la ruta de metadatos de instalador anterior. +- `skills.entries.*.env` y `skills.entries.*.apiKey` inyectan secretos en el proceso **host** para ese turno del agente (no en el sandbox). Mantén los secretos fuera de prompts y logs. Para un modelo de amenazas y listas de comprobación más amplios, consulta [Seguridad](/es/gateway/security). @@ -152,35 +168,35 @@ description: Generate or edit images via a provider-backed image workflow --- ``` -OpenClaw sigue la especificación AgentSkills para diseño/intención. El parser usado -por el agente incrustado admite solo claves de frontmatter de **una sola línea**; -`metadata` debe ser un **objeto JSON de una sola línea**. Usa `{baseDir}` en -las instrucciones para hacer referencia a la ruta de la carpeta del skill. +OpenClaw sigue la especificación AgentSkills para diseño/intención. El analizador usado +por el agente integrado solo admite claves de frontmatter de **una línea**; +`metadata` debe ser un **objeto JSON de una línea**. Usa `{baseDir}` en +las instrucciones para hacer referencia a la ruta de la carpeta de la skill. -### Claves de frontmatter opcionales +### Claves opcionales de frontmatter URL mostrada como "Sitio web" en la UI de Skills de macOS. También se admite mediante `metadata.openclaw.homepage`. - Cuando es `true`, el skill se expone como comando de barra de usuario. + Cuando es `true`, la skill se expone como un comando slash de usuario. - Cuando es `true`, el skill se excluye del prompt del modelo (sigue disponible mediante invocación de usuario). + Cuando es `true`, la skill se excluye del prompt del modelo (sigue disponible mediante invocación de usuario). - Cuando se establece en `tool`, el comando de barra omite el modelo y despacha directamente a una herramienta. + Cuando se define como `tool`, el comando slash omite el modelo y se despacha directamente a una herramienta. - Nombre de la herramienta que se invoca cuando se establece `command-dispatch: tool`. + Nombre de la herramienta que se invoca cuando se define `command-dispatch: tool`. - Para despacho a herramientas, reenvía la cadena de argumentos sin procesar a la herramienta (sin análisis del núcleo). La herramienta se invoca con `{ command: "", commandName: "", skillName: "" }`. + Para el despacho a herramienta, reenvía la cadena de argumentos sin procesar a la herramienta (sin análisis del core). La herramienta se invoca con `{ command: "", commandName: "", skillName: "" }`. -## Restricciones (filtros en tiempo de carga) +## Condicionamiento (filtros en tiempo de carga) -OpenClaw filtra Skills en el momento de carga usando `metadata` (JSON de una sola línea): +OpenClaw filtra skills en tiempo de carga usando `metadata` (JSON de una línea): ```markdown --- @@ -200,7 +216,7 @@ metadata: Campos bajo `metadata.openclaw`: - Cuando es `true`, incluye siempre el skill (omite otras restricciones). + Cuando es `true`, incluye siempre la skill (omite otras condiciones). Emoji opcional usado por la UI de Skills de macOS. @@ -209,7 +225,7 @@ Campos bajo `metadata.openclaw`: URL opcional mostrada como "Sitio web" en la UI de Skills de macOS. - Lista opcional de plataformas. Si se define, el skill solo es elegible en esos sistemas operativos. + Lista opcional de plataformas. Si se define, la skill solo es elegible en esos SO. Cada uno debe existir en `PATH`. @@ -224,27 +240,27 @@ Campos bajo `metadata.openclaw`: Lista de rutas de `openclaw.json` que deben ser truthy. - Nombre de variable de entorno asociado con `skills.entries..apiKey`. + Nombre de la variable de entorno asociada con `skills.entries..apiKey`. - Especificaciones de instalador opcionales usadas por la UI de Skills de macOS (brew/node/go/uv/download). + Especificaciones opcionales de instalador usadas por la UI de Skills de macOS (brew/node/go/uv/download). -Si no hay `metadata.openclaw`, el skill siempre es elegible (salvo que -esté deshabilitado en la configuración o bloqueado por `skills.allowBundled` para Skills incluidos). +Si no hay `metadata.openclaw`, la skill siempre es elegible (salvo que esté +deshabilitada en la configuración o bloqueada por `skills.allowBundled` para skills incluidas). -Los bloques heredados `metadata.clawdbot` aún se aceptan cuando -`metadata.openclaw` está ausente, por lo que los Skills instalados antiguos conservan sus -restricciones de dependencias y sugerencias de instalador. Los Skills nuevos y actualizados deberían usar +Los bloques heredados `metadata.clawdbot` todavía se aceptan cuando +`metadata.openclaw` está ausente, por lo que las skills instaladas antiguas conservan sus +condiciones de dependencias y sugerencias de instalador. Las skills nuevas y actualizadas deben usar `metadata.openclaw`. ### Notas de sandboxing -- `requires.bins` se comprueba en el **host** en el momento de carga del skill. +- `requires.bins` se comprueba en el **host** en tiempo de carga de la skill. - Si un agente está en sandbox, el binario también debe existir **dentro del contenedor**. Instálalo mediante `agents.defaults.sandbox.docker.setupCommand` (o una imagen personalizada). `setupCommand` se ejecuta una vez después de crear el contenedor. Las instalaciones de paquetes también requieren salida de red, un FS raíz escribible y un usuario root en el sandbox. -- Ejemplo: el skill `summarize` (`skills/summarize/SKILL.md`) necesita la CLI `summarize` en el contenedor de sandbox para ejecutarse allí. +- Ejemplo: la skill `summarize` (`skills/summarize/SKILL.md`) necesita la CLI `summarize` en el contenedor de sandbox para ejecutarse allí. ### Especificaciones de instalador @@ -274,26 +290,26 @@ metadata: ``` - - - Si se listan varios instaladores, el Gateway elige una única opción preferida (brew cuando esté disponible; de lo contrario, node). - - Si todos los instaladores son `download`, OpenClaw lista cada entrada para que puedas ver los artefactos disponibles. - - Las especificaciones de instalador pueden incluir `os: ["darwin"|"linux"|"win32"]` para filtrar opciones por plataforma. - - Las instalaciones de Node respetan `skills.install.nodeManager` en `openclaw.json` (predeterminado: npm; opciones: npm/pnpm/yarn/bun). Esto solo afecta las instalaciones de Skills; el runtime del Gateway debe seguir siendo Node: Bun no se recomienda para WhatsApp/Telegram. - - La selección de instalador respaldada por el Gateway se basa en preferencias: cuando las especificaciones de instalación mezclan tipos, OpenClaw prefiere Homebrew cuando `skills.install.preferBrew` está habilitado y `brew` existe, luego `uv`, luego el gestor de node configurado, y después otros respaldos como `go` o `download`. + + - Si se enumeran varios instaladores, el Gateway elige una sola opción preferida (brew cuando está disponible; de lo contrario, node). + - Si todos los instaladores son `download`, OpenClaw enumera cada entrada para que puedas ver los artefactos disponibles. + - Las especificaciones del instalador pueden incluir `os: ["darwin"|"linux"|"win32"]` para filtrar opciones por plataforma. + - Las instalaciones de Node respetan `skills.install.nodeManager` en `openclaw.json` (predeterminado: npm; opciones: npm/pnpm/yarn/bun). Esto solo afecta a las instalaciones de Skills; el entorno de ejecución del Gateway debe seguir siendo Node; no se recomienda Bun para WhatsApp/Telegram. + - La selección de instalador respaldada por el Gateway se basa en preferencias: cuando las especificaciones de instalación mezclan tipos, OpenClaw prefiere Homebrew cuando `skills.install.preferBrew` está habilitado y `brew` existe, luego `uv`, luego el gestor de node configurado, y luego otros recursos alternativos como `go` o `download`. - Si cada especificación de instalación es `download`, OpenClaw muestra todas las opciones de descarga en lugar de reducirlas a un instalador preferido. - - **Instalaciones de Go:** si falta `go` y `brew` está disponible, el gateway instala Go primero mediante Homebrew y establece `GOBIN` en el `bin` de Homebrew cuando es posible. - - **Instalaciones por descarga:** `url` (obligatorio), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (predeterminado: automático cuando se detecta un archivo comprimido), `stripComponents`, `targetDir` (predeterminado: `~/.openclaw/tools/`). + - **Instalaciones de Go:** si falta `go` y `brew` está disponible, el gateway instala primero Go mediante Homebrew y define `GOBIN` en el `bin` de Homebrew cuando es posible. + - **Instalaciones por descarga:** `url` (obligatorio), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (predeterminado: automático cuando se detecta un archivo), `stripComponents`, `targetDir` (predeterminado: `~/.openclaw/tools/`). ## Sobrescrituras de configuración -Las Skills incluidas y gestionadas se pueden activar o desactivar y recibir valores de env -bajo `skills.entries` en `~/.openclaw/openclaw.json`: +Las Skills incluidas y administradas pueden activarse o desactivarse y recibir valores de entorno +en `skills.entries` dentro de `~/.openclaw/openclaw.json`: ```json5 { @@ -318,78 +334,78 @@ bajo `skills.entries` en `~/.openclaw/openclaw.json`: ``` - `false` deshabilita la skill aunque esté incluida o instalada. - La skill incluida `coding-agent` es de activación explícita: establece - `skills.entries.coding-agent.enabled: true` antes de exponerla a los agentes; - luego asegúrate de que uno de `claude`, `codex`, `opencode` o `pi` esté instalado y + `false` desactiva la Skill incluso si está incluida o instalada. + La Skill incluida `coding-agent` es opcional: define + `skills.entries.coding-agent.enabled: true` antes de exponerla a los agentes, + y luego asegúrate de que uno de `claude`, `codex`, `opencode` o `pi` esté instalado y autenticado para su propia CLI. - Atajo para Skills que declaran `metadata.openclaw.primaryEnv`. Admite texto sin formato o SecretRef. + Atajo para Skills que declaran `metadata.openclaw.primaryEnv`. Admite texto plano o SecretRef. - Se inyecta solo si la variable aún no está establecida en el proceso. + Se inyecta solo si la variable aún no está definida en el proceso. - Contenedor opcional para campos personalizados por skill. Las claves personalizadas deben vivir aquí. + Contenedor opcional para campos personalizados por Skill. Las claves personalizadas deben vivir aquí. - Lista de permitidos opcional solo para Skills **incluidas**. Si se establece, solo las Skills incluidas en la lista son aptas (las Skills gestionadas/de espacio de trabajo no se ven afectadas). + Lista de permitidos opcional solo para Skills **incluidas**. Si se define, solo las Skills incluidas en la lista son elegibles (las Skills administradas/de espacio de trabajo no se ven afectadas). -Si el nombre de la skill contiene guiones, pon la clave entre comillas (JSON5 permite claves -entre comillas). Las claves de configuración coinciden con el **nombre de la skill** de forma predeterminada; si una skill -define `metadata.openclaw.skillKey`, usa esa clave bajo `skills.entries`. +Si el nombre de la Skill contiene guiones, pon la clave entre comillas (JSON5 permite claves +entre comillas). Las claves de configuración coinciden con el **nombre de la Skill** de forma predeterminada; si una Skill +define `metadata.openclaw.skillKey`, usa esa clave en `skills.entries`. -Para generar/editar imágenes de stock dentro de OpenClaw, usa la herramienta principal +Para generación/edición de imágenes de stock dentro de OpenClaw, usa la herramienta principal `image_generate` con `agents.defaults.imageGenerationModel` en lugar -de una skill incluida. Los ejemplos de Skills aquí son para flujos de trabajo personalizados o de terceros. -Para el análisis nativo de imágenes, usa la herramienta `image` con +de una Skill incluida. Los ejemplos de Skills aquí son para flujos de trabajo personalizados o de terceros. +Para análisis de imágenes nativo, usa la herramienta `image` con `agents.defaults.imageModel`. Si eliges `openai/*`, `google/*`, -`fal/*` u otro modelo de imagen específico de proveedor, agrega también la -autenticación/clave de API de ese proveedor. +`fal/*` u otro modelo de imagen específico de proveedor, añade también la clave de autenticación/API +de ese proveedor. ## Inyección de entorno Cuando se inicia una ejecución de agente, OpenClaw: -1. Lee los metadatos de la skill. +1. Lee los metadatos de la Skill. 2. Aplica `skills.entries..env` y `skills.entries..apiKey` a `process.env`. -3. Construye el prompt del sistema con Skills **aptas**. -4. Restaura el entorno original después de que termina la ejecución. +3. Construye el prompt del sistema con Skills **elegibles**. +4. Restaura el entorno original después de que finaliza la ejecución. -La inyección de entorno está **limitada a la ejecución del agente**, no a un entorno -de shell global. +La inyección de entorno está **limitada a la ejecución del agente**, no a un entorno de shell +global. Para el backend incluido `claude-cli`, OpenClaw también materializa la misma -instantánea apta como un Plugin temporal de Claude Code y la pasa con -`--plugin-dir`. Claude Code puede usar entonces su resolutor nativo de Skills mientras -OpenClaw sigue siendo propietario de la precedencia, las listas de permitidos por agente, las puertas de control y la -inyección de env/clave de API de `skills.entries.*`. Otros backends de CLI usan solo el +instantánea elegible como un Plugin temporal de Claude Code y la pasa con +`--plugin-dir`. Claude Code puede entonces usar su resolutor nativo de Skills mientras +OpenClaw sigue controlando la precedencia, las listas de permitidos por agente, las puertas de activación y +la inyección de variables de entorno/claves de API de `skills.entries.*`. Otros backends de CLI usan solo el catálogo del prompt. ## Instantáneas y actualización -OpenClaw toma instantáneas de las Skills aptas **cuando se inicia una sesión** y -reutiliza esa lista para los turnos posteriores en la misma sesión. Los cambios en -Skills o configuración surten efecto en la siguiente sesión nueva. +OpenClaw toma instantáneas de las Skills elegibles **cuando se inicia una sesión** y +reutiliza esa lista para los turnos posteriores de la misma sesión. Los cambios en +Skills o en la configuración surten efecto en la siguiente sesión nueva. Las Skills pueden actualizarse a mitad de sesión en dos casos: - El observador de Skills está habilitado. -- Aparece un nuevo nodo remoto apto. +- Aparece un nuevo nodo remoto elegible. -Piensa en esto como una **recarga en caliente**: la lista actualizada se adopta en el -siguiente turno del agente. Si la lista de Skills permitidas efectiva del agente cambia para esa -sesión, OpenClaw actualiza la instantánea para que las Skills visibles se mantengan alineadas +Piensa en esto como una **recarga en caliente**: la lista actualizada se usa en el +siguiente turno del agente. Si la lista efectiva de Skills permitidas para el agente cambia para esa +sesión, OpenClaw actualiza la instantánea para que las Skills visibles permanezcan alineadas con el agente actual. ### Observador de Skills De forma predeterminada, OpenClaw observa las carpetas de Skills e incrementa la instantánea de Skills -cuando cambian archivos `SKILL.md`. Configura esto bajo `skills.load`: +cuando cambian archivos `SKILL.md`. Configúralo en `skills.load`: ```json5 { @@ -402,28 +418,28 @@ cuando cambian archivos `SKILL.md`. Configura esto bajo `skills.load`: } ``` -### Nodos macOS remotos (gateway Linux) +### Nodos macOS remotos (Gateway en Linux) Si el Gateway se ejecuta en Linux pero hay un **nodo macOS** conectado con -`system.run` permitido (seguridad de aprobaciones Exec no establecida en `deny`), -OpenClaw puede tratar las Skills exclusivas de macOS como aptas cuando los binarios -requeridos están presentes en ese nodo. El agente debe ejecutar esas Skills +`system.run` permitido (seguridad de aprobaciones de Exec no definida en `deny`), +OpenClaw puede tratar las Skills solo para macOS como elegibles cuando los binarios requeridos +están presentes en ese nodo. El agente debe ejecutar esas Skills mediante la herramienta `exec` con `host=node`. -Esto depende de que el nodo informe su compatibilidad con comandos y de una prueba de bin -mediante `system.which` o `system.run`. Los nodos sin conexión **no** hacen visibles -las Skills solo remotas. Si un nodo conectado deja de responder a las pruebas de bin, -OpenClaw borra sus coincidencias de bin en caché para que los agentes ya no vean -Skills que no pueden ejecutarse allí en ese momento. +Esto depende de que el nodo informe su soporte de comandos y de una comprobación de binarios +mediante `system.which` o `system.run`. Los nodos sin conexión **no** hacen +visibles las Skills solo remotas. Si un nodo conectado deja de responder a comprobaciones de +binarios, OpenClaw borra sus coincidencias de binarios en caché para que los agentes ya no vean +Skills que actualmente no pueden ejecutarse allí. ## Impacto en tokens -Cuando las Skills son aptas, OpenClaw inyecta una lista XML compacta de Skills +Cuando las Skills son elegibles, OpenClaw inyecta una lista XML compacta de Skills disponibles en el prompt del sistema (mediante `formatSkillsForPrompt` en -`pi-coding-agent`). El costo es determinista: +`pi-coding-agent`). El coste es determinista: -- **Sobrecarga base** (solo cuando hay ≥1 skill): 195 caracteres. -- **Por skill:** 97 caracteres + la longitud de los valores ``, `` y `` escapados para XML. +- **Sobrecoste base** (solo cuando hay ≥1 Skill): 195 caracteres. +- **Por Skill:** 97 caracteres + la longitud de los valores ``, `` y `` escapados para XML. Fórmula (caracteres): @@ -431,18 +447,18 @@ Fórmula (caracteres): total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped)) ``` -El escapado XML expande `& < > " '` en entidades (`&`, `<`, etc.), -aumentando la longitud. Los conteos de tokens varían según el tokenizador del modelo. Una estimación aproximada -estilo OpenAI es ~4 caracteres/token, por lo que **97 caracteres ≈ 24 tokens** por -skill más las longitudes reales de tus campos. +El escape XML expande `& < > " '` en entidades (`&`, `<`, etc.), +lo que aumenta la longitud. Los conteos de tokens varían según el tokenizador del modelo. Una estimación aproximada +de estilo OpenAI es ~4 caracteres/token, por lo que **97 caracteres ≈ 24 tokens** por +Skill más las longitudes reales de tus campos. -## Ciclo de vida de Skills gestionadas +## Ciclo de vida de Skills administradas -OpenClaw distribuye un conjunto base de Skills como **Skills incluidas** con la +OpenClaw incluye un conjunto base de Skills como **Skills incluidas** con la instalación (paquete npm u OpenClaw.app). `~/.openclaw/skills` existe para -sobrescrituras locales; por ejemplo, fijar o parchear una skill sin -cambiar la copia incluida. Las Skills de espacio de trabajo son propiedad del usuario y sobrescriben -ambas en conflictos de nombre. +sobrescrituras locales; por ejemplo, fijar o parchear una Skill sin +cambiar la copia incluida. Las Skills de espacio de trabajo pertenecen al usuario y sobrescriben +ambas cuando hay conflictos de nombre. ## ¿Buscas más Skills? @@ -452,8 +468,8 @@ Explora [https://clawhub.ai](https://clawhub.ai). Esquema completo de configurac ## Relacionado - [ClawHub](/es/tools/clawhub) — registro público de Skills -- [Crear Skills](/es/tools/creating-skills) — crear Skills personalizadas -- [Plugins](/es/tools/plugin) — descripción general del sistema de plugins +- [Crear Skills](/es/tools/creating-skills) — creación de Skills personalizadas +- [Plugins](/es/tools/plugin) — descripción general del sistema de Plugins - [Plugin Skill Workshop](/es/plugins/skill-workshop) — genera Skills a partir del trabajo del agente - [Configuración de Skills](/es/tools/skills-config) — referencia de configuración de Skills -- [Comandos slash](/es/tools/slash-commands) — todos los comandos slash disponibles +- [Comandos de barra](/es/tools/slash-commands) — todos los comandos de barra disponibles