From cc8614784805912c49ffceb364db3587bb5b9620 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 05:15:14 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/automation/tasks.md | 213 ++++----- docs/es/concepts/active-memory.md | 613 ++++++++++++++++++++++++++ docs/es/concepts/memory-search.md | 82 ++-- docs/es/concepts/qa-e2e-automation.md | 106 +++-- docs/es/help/testing.md | 597 +++++++++++++------------ docs/es/reference/memory-config.md | 313 ++++++------- docs/es/tools/browser.md | 487 ++++++++++---------- 7 files changed, 1536 insertions(+), 875 deletions(-) create mode 100644 docs/es/concepts/active-memory.md diff --git a/docs/es/automation/tasks.md b/docs/es/automation/tasks.md index 20bab20b5..2252611b0 100644 --- a/docs/es/automation/tasks.md +++ b/docs/es/automation/tasks.md @@ -1,72 +1,72 @@ --- read_when: - - Inspeccionar trabajo en segundo plano en curso o completado recientemente - - Depurar fallas de entrega en ejecuciones desacopladas del agente - - Comprender cómo se relacionan las ejecuciones en segundo plano con las sesiones, cron y heartbeat + - Inspeccionando trabajo en segundo plano en curso o completado recientemente + - Depuración de fallos de entrega para ejecuciones de agentes desacopladas + - Comprender cómo las ejecuciones en segundo plano se relacionan con las sesiones, cron y heartbeat summary: Seguimiento de tareas en segundo plano para ejecuciones de ACP, subagentes, trabajos cron aislados y operaciones de CLI title: Tareas en segundo plano x-i18n: - generated_at: "2026-04-06T03:06:32Z" + generated_at: "2026-04-10T05:12:08Z" model: gpt-5.4 provider: openai - source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff + source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac source_path: automation/tasks.md workflow: 15 --- # Tareas en segundo plano -> **¿Buscas programación?** Consulta [Automatización y tareas](/es/automation) para elegir el mecanismo adecuado. Esta página cubre el **seguimiento** del trabajo en segundo plano, no su programación. +> **¿Buscas programación?** Consulta [Automation & Tasks](/es/automation) para elegir el mecanismo adecuado. Esta página cubre el **seguimiento** del trabajo en segundo plano, no su programación. -Las tareas en segundo plano registran trabajo que se ejecuta **fuera de tu sesión principal de conversación**: -ejecuciones de ACP, lanzamientos de subagentes, ejecuciones aisladas de trabajos cron y operaciones iniciadas desde la CLI. +Las tareas en segundo plano hacen seguimiento del trabajo que se ejecuta **fuera de tu sesión principal de conversación**: +ejecuciones de ACP, lanzamientos de subagentes, ejecuciones aisladas de trabajos cron y operaciones iniciadas por la CLI. -Las tareas **no** reemplazan a las sesiones, los trabajos cron ni a heartbeat; son el **registro de actividad** que anota qué trabajo desacoplado ocurrió, cuándo ocurrió y si se completó correctamente. +Las tareas **no** reemplazan las sesiones, los trabajos cron ni los heartbeats; son el **registro de actividad** que deja constancia de qué trabajo desacoplado ocurrió, cuándo ocurrió y si se completó correctamente. -No todas las ejecuciones de agentes crean una tarea. Los turnos de heartbeat y el chat interactivo normal no lo hacen. Todas las ejecuciones cron, lanzamientos de ACP, lanzamientos de subagentes y comandos de agente de CLI sí lo hacen. +No todas las ejecuciones de agentes crean una tarea. Los turnos de heartbeat y el chat interactivo normal no lo hacen. Todas las ejecuciones de cron, lanzamientos de ACP, lanzamientos de subagentes y comandos de agente de CLI sí lo hacen. ## Resumen rápido -- Las tareas son **registros**, no programadores: cron y heartbeat deciden _cuándo_ se ejecuta el trabajo; las tareas registran _qué ocurrió_. -- ACP, los subagentes, todos los trabajos cron y las operaciones de CLI crean tareas. Los turnos de heartbeat no. +- Las tareas son **registros**, no programadores: cron y heartbeat deciden _cuándo_ se ejecuta el trabajo; las tareas hacen seguimiento de _qué ocurrió_. +- ACP, subagentes, todos los trabajos cron y las operaciones de CLI crean tareas. Los turnos de heartbeat no. - Cada tarea pasa por `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled` o `lost`). -- Las tareas cron siguen activas mientras el entorno de ejecución cron siga siendo propietario del trabajo; las tareas de CLI respaldadas por chat siguen activas solo mientras su contexto de ejecución propietario siga activo. -- La finalización es impulsada por envíos: el trabajo desacoplado puede notificar directamente o despertar la sesión solicitante/heartbeat cuando termina, por lo que los bucles de sondeo de estado normalmente no son el enfoque adecuado. -- Las ejecuciones cron aisladas y las finalizaciones de subagentes limpian, en la medida de lo posible, las pestañas/procesos del navegador rastreados para su sesión hija antes de la contabilidad final de limpieza. -- La entrega de cron aislado suprime las respuestas provisionales obsoletas del padre mientras el trabajo de subagentes descendientes aún se está vaciando, y prefiere la salida final del descendiente cuando esta llega antes de la entrega. +- Las tareas cron permanecen activas mientras el runtime de cron siga siendo propietario del trabajo; las tareas de CLI respaldadas por chat permanecen activas solo mientras su contexto de ejecución propietario siga activo. +- La finalización se impulsa por eventos push: el trabajo desacoplado puede notificar directamente o despertar la sesión solicitante/el heartbeat cuando termina, por lo que los bucles de sondeo de estado normalmente no son la forma correcta. +- Las ejecuciones cron aisladas y las finalizaciones de subagentes limpian, en la medida de lo posible, las pestañas/procesos de navegador rastreados de su sesión hija antes de la contabilidad final de limpieza. +- La entrega cron aislada suprime respuestas parent intermedias obsoletas mientras el trabajo de subagentes descendientes aún se está vaciando, y prefiere la salida final del descendiente cuando esta llega antes de la entrega. - Las notificaciones de finalización se entregan directamente a un canal o se ponen en cola para el siguiente heartbeat. -- `openclaw tasks list` muestra todas las tareas; `openclaw tasks audit` muestra los problemas. +- `openclaw tasks list` muestra todas las tareas; `openclaw tasks audit` muestra problemas. - Los registros terminales se conservan durante 7 días y luego se eliminan automáticamente. ## Inicio rápido ```bash -# Listar todas las tareas (las más nuevas primero) +# Lista todas las tareas (las más recientes primero) openclaw tasks list -# Filtrar por entorno de ejecución o estado +# Filtra por runtime o estado openclaw tasks list --runtime acp openclaw tasks list --status running -# Mostrar detalles de una tarea específica (por ID, ID de ejecución o clave de sesión) +# Muestra detalles de una tarea específica (por ID, ID de ejecución o clave de sesión) openclaw tasks show -# Cancelar una tarea en ejecución (mata la sesión hija) +# Cancela una tarea en ejecución (mata la sesión hija) openclaw tasks cancel -# Cambiar la política de notificaciones de una tarea +# Cambia la política de notificación de una tarea openclaw tasks notify state_changes -# Ejecutar una auditoría de estado +# Ejecuta una auditoría de estado openclaw tasks audit -# Previsualizar o aplicar mantenimiento +# Previsualiza o aplica mantenimiento openclaw tasks maintenance openclaw tasks maintenance --apply -# Inspeccionar el estado de TaskFlow +# Inspecciona el estado de TaskFlow openclaw tasks flow list openclaw tasks flow show openclaw tasks flow cancel @@ -74,25 +74,25 @@ openclaw tasks flow cancel ## Qué crea una tarea -| Origen | Tipo de entorno de ejecución | Cuándo se crea un registro de tarea | Política de notificación predeterminada | -| ---------------------- | ---------------------------- | ------------------------------------------------------ | --------------------------------------- | -| Ejecuciones en segundo plano de ACP | `acp` | Al generar una sesión hija de ACP | `done_only` | -| Orquestación de subagentes | `subagent` | Al generar un subagente mediante `sessions_spawn` | `done_only` | -| Trabajos cron (todos los tipos) | `cron` | En cada ejecución cron (sesión principal y aislada) | `silent` | -| Operaciones de CLI | `cli` | Comandos `openclaw agent` que se ejecutan mediante el gateway | `silent` | -| Trabajos multimedia del agente | `cli` | Ejecuciones de `video_generate` respaldadas por sesión | `silent` | +| Origen | Tipo de runtime | Cuándo se crea un registro de tarea | Política de notificación predeterminada | +| ---------------------- | --------------- | ------------------------------------------------------ | --------------------------------------- | +| Ejecuciones en segundo plano de ACP | `acp` | Al lanzar una sesión ACP hija | `done_only` | +| Orquestación de subagentes | `subagent` | Al lanzar un subagente mediante `sessions_spawn` | `done_only` | +| Trabajos cron (todos los tipos) | `cron` | En cada ejecución cron (sesión principal y aislada) | `silent` | +| Operaciones de CLI | `cli` | Comandos `openclaw agent` que se ejecutan a través del gateway | `silent` | +| Trabajos de medios del agente | `cli` | Ejecuciones `video_generate` respaldadas por sesión | `silent` | -Las tareas cron de sesión principal usan la política de notificación `silent` de forma predeterminada: crean registros para seguimiento, pero no generan notificaciones. Las tareas cron aisladas también usan `silent` de forma predeterminada, pero son más visibles porque se ejecutan en su propia sesión. +Las tareas cron de la sesión principal usan la política de notificación `silent` de forma predeterminada: crean registros para seguimiento, pero no generan notificaciones. Las tareas cron aisladas también usan `silent` de forma predeterminada, pero son más visibles porque se ejecutan en su propia sesión. -Las ejecuciones de `video_generate` respaldadas por sesión también usan la política de notificación `silent`. Siguen creando registros de tareas, pero la finalización se devuelve a la sesión original del agente como una activación interna para que el agente pueda escribir el mensaje de seguimiento y adjuntar por sí mismo el video terminado. Si activas `tools.media.asyncCompletion.directSend`, las finalizaciones asíncronas de `music_generate` y `video_generate` intentan primero una entrega directa al canal antes de volver a la ruta de activación de la sesión solicitante. +Las ejecuciones `video_generate` respaldadas por sesión también usan la política de notificación `silent`. Siguen creando registros de tarea, pero la finalización se devuelve a la sesión original del agente como un wake interno para que el agente pueda escribir el mensaje de seguimiento y adjuntar el video terminado por sí mismo. Si activas `tools.media.asyncCompletion.directSend`, las finalizaciones asíncronas de `music_generate` y `video_generate` intentan primero una entrega directa al canal antes de volver a la ruta de wake de la sesión solicitante. -Mientras una tarea de `video_generate` respaldada por sesión siga activa, la herramienta también actúa como una barrera de seguridad: las llamadas repetidas a `video_generate` en esa misma sesión devuelven el estado de la tarea activa en lugar de iniciar una segunda generación concurrente. Usa `action: "status"` cuando quieras una consulta explícita de progreso/estado desde el lado del agente. +Mientras una tarea `video_generate` respaldada por sesión siga activa, la herramienta también actúa como una barrera de protección: las llamadas repetidas a `video_generate` en esa misma sesión devuelven el estado de la tarea activa en lugar de iniciar una segunda generación simultánea. Usa `action: "status"` cuando quieras una consulta explícita de progreso/estado desde el lado del agente. **Qué no crea tareas:** - Turnos de heartbeat: sesión principal; consulta [Heartbeat](/es/gateway/heartbeat) - Turnos normales de chat interactivo -- Respuestas directas a `/command` +- Respuestas directas de `/command` ## Ciclo de vida de la tarea @@ -102,54 +102,54 @@ stateDiagram-v2 queued --> running : el agente inicia running --> succeeded : se completa correctamente running --> failed : error - running --> timed_out : tiempo de espera superado + running --> timed_out : tiempo de espera excedido running --> cancelled : el operador cancela queued --> lost : sesión desaparecida > 5 min running --> lost : sesión desaparecida > 5 min ``` -| Estado | Qué significa | -| ----------- | ------------------------------------------------------------------------- | -| `queued` | Creada, esperando a que el agente inicie | -| `running` | El turno del agente se está ejecutando activamente | -| `succeeded` | Completada correctamente | -| `failed` | Completada con un error | -| `timed_out` | Superó el tiempo de espera configurado | -| `cancelled` | Detenida por el operador mediante `openclaw tasks cancel` | -| `lost` | El entorno de ejecución perdió el estado de respaldo autoritativo después de un período de gracia de 5 minutos | +| Estado | Qué significa | +| ----------- | -------------------------------------------------------------------------- | +| `queued` | Creada, en espera de que el agente inicie | +| `running` | El turno del agente se está ejecutando activamente | +| `succeeded` | Se completó correctamente | +| `failed` | Se completó con un error | +| `timed_out` | Excedió el tiempo de espera configurado | +| `cancelled` | La detuvo el operador mediante `openclaw tasks cancel` | +| `lost` | El runtime perdió el estado de respaldo autoritativo tras un período de gracia de 5 minutos | -Las transiciones ocurren automáticamente: cuando termina la ejecución del agente asociada, el estado de la tarea se actualiza para coincidir. +Las transiciones ocurren automáticamente: cuando termina la ejecución del agente asociada, el estado de la tarea se actualiza para reflejarlo. -`lost` depende del entorno de ejecución: +`lost` depende del runtime: -- Tareas de ACP: desaparecieron los metadatos de respaldo de la sesión hija de ACP. +- Tareas de ACP: desaparecieron los metadatos de la sesión hija de ACP de respaldo. - Tareas de subagentes: la sesión hija de respaldo desapareció del almacén del agente de destino. -- Tareas cron: el entorno de ejecución cron ya no rastrea el trabajo como activo. -- Tareas de CLI: las tareas aisladas de sesión hija usan la sesión hija; en su lugar, las tareas de CLI respaldadas por chat usan el contexto de ejecución en vivo, por lo que las filas persistentes de sesión de canal/grupo/directa no las mantienen activas. +- Tareas cron: el runtime de cron ya no rastrea el trabajo como activo. +- Tareas de CLI: las tareas de sesión hija aislada usan la sesión hija; las tareas de CLI respaldadas por chat usan en su lugar el contexto de ejecución activo, de modo que las filas persistentes de sesión de canal/grupo/directa no las mantienen activas. ## Entrega y notificaciones Cuando una tarea alcanza un estado terminal, OpenClaw te notifica. Hay dos rutas de entrega: -**Entrega directa**: si la tarea tiene un destino de canal (el `requesterOrigin`), el mensaje de finalización va directamente a ese canal (Telegram, Discord, Slack, etc.). Para las finalizaciones de subagentes, OpenClaw también conserva el enrutamiento de hilo/tema asociado cuando está disponible y puede completar un `to` o una cuenta faltantes a partir de la ruta almacenada de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de abandonar la entrega directa. +**Entrega directa**: si la tarea tiene un destino de canal (el `requesterOrigin`), el mensaje de finalización va directamente a ese canal (Telegram, Discord, Slack, etc.). Para las finalizaciones de subagentes, OpenClaw también conserva el enrutamiento enlazado de hilo/tema cuando está disponible y puede completar un `to` o una cuenta faltantes a partir de la ruta almacenada de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de abandonar la entrega directa. -**Entrega en cola de sesión**: si la entrega directa falla o no se ha configurado un origen, la actualización se pone en cola como un evento del sistema en la sesión del solicitante y aparece en el siguiente heartbeat. +**Entrega en cola de sesión**: si la entrega directa falla o no hay un origen establecido, la actualización se pone en cola como un evento del sistema en la sesión del solicitante y aparece en el siguiente heartbeat. -La finalización de una tarea activa un despertar inmediato de heartbeat para que veas el resultado rápidamente; no tienes que esperar al siguiente tick programado de heartbeat. +La finalización de una tarea activa un wake inmediato del heartbeat para que veas el resultado rápidamente; no tienes que esperar al siguiente intervalo programado de heartbeat. -Eso significa que el flujo de trabajo habitual se basa en envíos: inicia el trabajo desacoplado una vez y luego deja que el entorno de ejecución te despierte o te notifique cuando se complete. Sondea el estado de la tarea solo cuando necesites depuración, intervención o una auditoría explícita. +Eso significa que el flujo de trabajo habitual se basa en eventos push: inicia el trabajo desacoplado una sola vez y luego deja que el runtime te despierte o te notifique al completarse. Sondea el estado de la tarea solo cuando necesites depuración, intervención o una auditoría explícita. ### Políticas de notificación -Controlan cuánto recibes de cada tarea: +Controla cuánto escuchas sobre cada tarea: -| Política | Qué se entrega | -| --------------------- | ----------------------------------------------------------------------- | -| `done_only` (predeterminada) | Solo el estado terminal (`succeeded`, `failed`, etc.); **esta es la opción predeterminada** | -| `state_changes` | Cada transición de estado y actualización de progreso | -| `silent` | Nada en absoluto | +| Política | Qué se entrega | +| ----------------------- | ------------------------------------------------------------------------- | +| `done_only` (predeterminada) | Solo el estado terminal (`succeeded`, `failed`, etc.); **esta es la predeterminada** | +| `state_changes` | Cada transición de estado y actualización de progreso | +| `silent` | Nada en absoluto | Cambia la política mientras una tarea está en ejecución: @@ -173,7 +173,7 @@ Columnas de salida: ID de tarea, tipo, estado, entrega, ID de ejecución, sesió openclaw tasks show ``` -El token de búsqueda acepta un ID de tarea, ID de ejecución o clave de sesión. Muestra el registro completo, incluidos tiempos, estado de entrega, error y resumen terminal. +El token de búsqueda acepta un ID de tarea, un ID de ejecución o una clave de sesión. Muestra el registro completo, incluidos el tiempo, el estado de entrega, el error y el resumen terminal. ### `tasks cancel` @@ -181,7 +181,7 @@ El token de búsqueda acepta un ID de tarea, ID de ejecución o clave de sesión openclaw tasks cancel ``` -Para tareas de ACP y subagentes, esto mata la sesión hija. El estado pasa a `cancelled` y se envía una notificación de entrega. +Para tareas de ACP y subagentes, esto mata la sesión hija. Para las tareas rastreadas por CLI, la cancelación se registra en el registro de tareas (no hay un identificador independiente del runtime hijo). El estado pasa a `cancelled` y se envía una notificación de entrega cuando corresponde. ### `tasks notify` @@ -197,14 +197,14 @@ openclaw tasks audit [--json] Muestra problemas operativos. Los hallazgos también aparecen en `openclaw status` cuando se detectan problemas. -| Hallazgo | Severidad | Activador | -| ------------------------- | --------- | ----------------------------------------------------- | -| `stale_queued` | warn | En cola durante más de 10 minutos | -| `stale_running` | error | En ejecución durante más de 30 minutos | -| `lost` | error | Desapareció la propiedad de la tarea respaldada por el entorno de ejecución | -| `delivery_failed` | warn | La entrega falló y la política de notificación no es `silent` | -| `missing_cleanup` | warn | Tarea terminal sin marca temporal de limpieza | -| `inconsistent_timestamps` | warn | Violación de la cronología (por ejemplo, terminó antes de empezar) | +| Hallazgo | Severidad | Activador | +| -------------------------- | --------- | ---------------------------------------------------- | +| `stale_queued` | warn | En cola durante más de 10 minutos | +| `stale_running` | error | En ejecución durante más de 30 minutos | +| `lost` | error | Desapareció la propiedad de la tarea respaldada por runtime | +| `delivery_failed` | warn | La entrega falló y la política de notificación no es `silent` | +| `missing_cleanup` | warn | Tarea terminal sin marca de tiempo de limpieza | +| `inconsistent_timestamps` | warn | Violación de la línea de tiempo (por ejemplo, terminó antes de comenzar) | ### `tasks maintenance` @@ -213,20 +213,20 @@ openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` -Úsalo para previsualizar o aplicar reconciliación, marcado de limpieza y depuración para las tareas y el estado de Task Flow. +Úsalo para previsualizar o aplicar reconciliación, marcado de limpieza y depuración para tareas y el estado de Task Flow. -La reconciliación depende del entorno de ejecución: +La reconciliación depende del runtime: - Las tareas de ACP/subagentes comprueban su sesión hija de respaldo. -- Las tareas cron comprueban si el entorno de ejecución cron sigue siendo propietario del trabajo. -- Las tareas de CLI respaldadas por chat comprueban el contexto de ejecución en vivo propietario, no solo la fila de sesión del chat. +- Las tareas cron comprueban si el runtime de cron sigue siendo propietario del trabajo. +- Las tareas de CLI respaldadas por chat comprueban el contexto de ejecución activo propietario, no solo la fila de sesión de chat. -La limpieza tras la finalización también depende del entorno de ejecución: +La limpieza tras la finalización también depende del runtime: - La finalización de subagentes cierra, en la medida de lo posible, las pestañas/procesos de navegador rastreados para la sesión hija antes de que continúe la limpieza del anuncio. -- La finalización de cron aislado cierra, en la medida de lo posible, las pestañas/procesos de navegador rastreados para la sesión cron antes de que la ejecución termine por completo. -- La entrega de cron aislado espera el seguimiento de subagentes descendientes cuando es necesario y suprime el texto obsoleto de confirmación del padre en lugar de anunciarlo. -- La entrega de finalización de subagentes prefiere el texto visible más reciente del asistente; si está vacío, recurre al texto más reciente saneado de tool/toolResult, y las ejecuciones de llamadas de herramientas que solo agotan el tiempo pueden reducirse a un breve resumen de progreso parcial. +- La finalización de cron aislado cierra, en la medida de lo posible, las pestañas/procesos de navegador rastreados para la sesión cron antes de que la ejecución se desmonte por completo. +- La entrega cron aislada espera el seguimiento de subagentes descendientes cuando es necesario y suprime el texto obsoleto de acuse de recibo del parent en lugar de anunciarlo. +- La entrega de finalización de subagentes prefiere el texto visible más reciente del asistente; si está vacío, recurre al texto saneado más reciente de tool/toolResult, y las ejecuciones con llamadas a herramientas que solo terminan por tiempo de espera pueden reducirse a un breve resumen de progreso parcial. - Los fallos de limpieza no ocultan el resultado real de la tarea. ### `tasks flow list|show|cancel` @@ -237,19 +237,19 @@ openclaw tasks flow show [--json] openclaw tasks flow cancel ``` -Usa estos comandos cuando lo que te importa es el Task Flow orquestador, en lugar de un registro individual de tarea en segundo plano. +Úsalos cuando lo que te importa es el Task Flow de orquestación en lugar de un registro individual de tarea en segundo plano. -## Tablero de tareas del chat (`/tasks`) +## Tablero de tareas de chat (`/tasks`) -Usa `/tasks` en cualquier sesión de chat para ver las tareas en segundo plano vinculadas a esa sesión. El tablero muestra tareas activas y completadas recientemente con entorno de ejecución, estado, tiempos y detalles de progreso o error. +Usa `/tasks` en cualquier sesión de chat para ver las tareas en segundo plano vinculadas a esa sesión. El tablero muestra tareas activas y completadas recientemente con runtime, estado, tiempo y detalles de progreso o error. -Cuando la sesión actual no tiene tareas vinculadas visibles, `/tasks` recurre a recuentos de tareas locales del agente para que sigas teniendo una vista general sin filtrar detalles de otras sesiones. +Cuando la sesión actual no tiene tareas vinculadas visibles, `/tasks` recurre a los recuentos de tareas locales del agente para que sigas teniendo una visión general sin filtrar detalles de otras sesiones. Para el registro completo del operador, usa la CLI: `openclaw tasks list`. ## Integración de estado (presión de tareas) -`openclaw status` incluye un resumen de tareas de vistazo rápido: +`openclaw status` incluye un resumen de tareas de un vistazo: ``` Tasks: 3 queued · 2 running · 1 issues @@ -257,66 +257,67 @@ Tasks: 3 queued · 2 running · 1 issues El resumen informa: -- **activas**: recuento de `queued` + `running` -- **fallidas**: recuento de `failed` + `timed_out` + `lost` -- **por entorno de ejecución**: desglose por `acp`, `subagent`, `cron`, `cli` +- **active**: recuento de `queued` + `running` +- **failures**: recuento de `failed` + `timed_out` + `lost` +- **byRuntime**: desglose por `acp`, `subagent`, `cron`, `cli` -Tanto `/status` como la herramienta `session_status` usan una instantánea de tareas consciente de la limpieza: se priorizan las tareas activas, se ocultan las filas completadas obsoletas y los fallos recientes solo aparecen cuando no queda trabajo activo. Esto mantiene la tarjeta de estado centrada en lo que importa en este momento. +Tanto `/status` como la herramienta `session_status` usan una instantánea de tareas con conocimiento de limpieza: se priorizan las tareas activas, se ocultan las filas completadas obsoletas y los fallos recientes solo aparecen cuando ya no queda trabajo activo. +Esto mantiene la tarjeta de estado centrada en lo que importa ahora mismo. ## Almacenamiento y mantenimiento -### Dónde se almacenan las tareas +### Dónde viven las tareas -Los registros de tareas se conservan en SQLite en: +Los registros de tareas persisten en SQLite en: ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -El registro se carga en memoria al iniciar el gateway y sincroniza las escrituras con SQLite para asegurar durabilidad entre reinicios. +El registro se carga en memoria al iniciar el gateway y sincroniza las escrituras con SQLite para garantizar durabilidad entre reinicios. ### Mantenimiento automático -Un barrido se ejecuta cada **60 segundos** y maneja tres cosas: +Un proceso de limpieza se ejecuta cada **60 segundos** y se encarga de tres cosas: -1. **Reconciliación**: comprueba si las tareas activas todavía tienen un respaldo autoritativo del entorno de ejecución. Las tareas de ACP/subagentes usan el estado de la sesión hija, las tareas cron usan la propiedad del trabajo activo y las tareas de CLI respaldadas por chat usan el contexto de ejecución propietario. Si ese estado de respaldo desaparece durante más de 5 minutos, la tarea se marca como `lost`. -2. **Marcado de limpieza**: establece una marca temporal `cleanupAfter` en las tareas terminales (`endedAt + 7 days`). +1. **Reconciliación**: comprueba si las tareas activas siguen teniendo respaldo autoritativo del runtime. Las tareas de ACP/subagentes usan el estado de la sesión hija, las tareas cron usan la propiedad del trabajo activo y las tareas de CLI respaldadas por chat usan el contexto de ejecución propietario. Si ese estado de respaldo desaparece durante más de 5 minutos, la tarea se marca como `lost`. +2. **Marcado de limpieza**: establece una marca de tiempo `cleanupAfter` en las tareas terminales (`endedAt` + 7 días). 3. **Depuración**: elimina los registros que hayan superado su fecha `cleanupAfter`. -**Retención**: los registros de tareas terminales se conservan durante **7 días** y luego se eliminan automáticamente. No se requiere configuración. +**Retención**: los registros de tareas terminales se conservan durante **7 días** y luego se eliminan automáticamente. No se necesita configuración. ## Cómo se relacionan las tareas con otros sistemas ### Tareas y Task Flow -[Task Flow](/es/automation/taskflow) es la capa de orquestación de flujos por encima de las tareas en segundo plano. Un solo flujo puede coordinar varias tareas a lo largo de su vida útil utilizando modos de sincronización administrados o reflejados. Usa `openclaw tasks` para inspeccionar registros individuales de tareas y `openclaw tasks flow` para inspeccionar el flujo orquestador. +[Task Flow](/es/automation/taskflow) es la capa de orquestación de flujos por encima de las tareas en segundo plano. Un único flujo puede coordinar varias tareas a lo largo de su ciclo de vida usando modos de sincronización gestionados o reflejados. Usa `openclaw tasks` para inspeccionar registros individuales de tareas y `openclaw tasks flow` para inspeccionar el flujo de orquestación. -Consulta [Task Flow](/es/automation/taskflow) para obtener más detalles. +Consulta [Task Flow](/es/automation/taskflow) para más detalles. ### Tareas y cron -Una **definición** de trabajo cron vive en `~/.openclaw/cron/jobs.json`. **Cada** ejecución cron crea un registro de tarea, tanto en sesión principal como aislada. Las tareas cron de sesión principal usan de forma predeterminada la política de notificación `silent`, por lo que hacen seguimiento sin generar notificaciones. +La **definición** de un trabajo cron vive en `~/.openclaw/cron/jobs.json`. **Cada** ejecución cron crea un registro de tarea, tanto en la sesión principal como en modo aislado. Las tareas cron de la sesión principal usan la política de notificación `silent` de forma predeterminada, por lo que hacen seguimiento sin generar notificaciones. -Consulta [Trabajos cron](/es/automation/cron-jobs). +Consulta [Cron Jobs](/es/automation/cron-jobs). ### Tareas y heartbeat -Las ejecuciones de heartbeat son turnos de sesión principal: no crean registros de tareas. Cuando una tarea se completa, puede activar un despertar de heartbeat para que veas el resultado con rapidez. +Las ejecuciones de heartbeat son turnos de la sesión principal; no crean registros de tarea. Cuando una tarea se completa, puede activar un wake de heartbeat para que veas el resultado con rapidez. Consulta [Heartbeat](/es/gateway/heartbeat). ### Tareas y sesiones -Una tarea puede hacer referencia a un `childSessionKey` (donde se ejecuta el trabajo) y a un `requesterSessionKey` (quién lo inició). Las sesiones son el contexto de la conversación; las tareas son el seguimiento de actividad por encima de ese contexto. +Una tarea puede hacer referencia a una `childSessionKey` (donde se ejecuta el trabajo) y a una `requesterSessionKey` (quién la inició). Las sesiones son el contexto de conversación; las tareas son la capa de seguimiento de actividad por encima de ese contexto. ### Tareas y ejecuciones de agentes -El `runId` de una tarea enlaza con la ejecución del agente que realiza el trabajo. Los eventos del ciclo de vida del agente (inicio, fin, error) actualizan automáticamente el estado de la tarea; no necesitas gestionar el ciclo de vida manualmente. +El `runId` de una tarea enlaza con la ejecución del agente que está realizando el trabajo. Los eventos del ciclo de vida del agente (inicio, fin, error) actualizan automáticamente el estado de la tarea; no necesitas gestionar manualmente el ciclo de vida. ## Relacionado -- [Automatización y tareas](/es/automation): todos los mecanismos de automatización de un vistazo +- [Automation & Tasks](/es/automation): todos los mecanismos de automatización de un vistazo - [Task Flow](/es/automation/taskflow): orquestación de flujos por encima de las tareas -- [Tareas programadas](/es/automation/cron-jobs): programación de trabajo en segundo plano -- [Heartbeat](/es/gateway/heartbeat): turnos periódicos de sesión principal -- [CLI: Tareas](/cli/index#tasks): referencia de comandos de CLI +- [Scheduled Tasks](/es/automation/cron-jobs): programación de trabajo en segundo plano +- [Heartbeat](/es/gateway/heartbeat): turnos periódicos de la sesión principal +- [CLI: Tasks](/cli/index#tasks): referencia de comandos de CLI diff --git a/docs/es/concepts/active-memory.md b/docs/es/concepts/active-memory.md new file mode 100644 index 000000000..045a75db8 --- /dev/null +++ b/docs/es/concepts/active-memory.md @@ -0,0 +1,613 @@ +--- +read_when: + - Quieres entender para qué sirve la memoria activa + - Quieres activar la memoria activa para un agente conversacional + - Quieres ajustar el comportamiento de la memoria activa sin habilitarla en todas partes +summary: Un subagente de memoria bloqueante propiedad del plugin que inyecta memoria relevante en sesiones de chat interactivas +title: Memoria activa +x-i18n: + generated_at: "2026-04-10T05:12:18Z" + model: gpt-5.4 + provider: openai + source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341 + source_path: concepts/active-memory.md + workflow: 15 +--- + +# Memoria activa + +La memoria activa es un subagente de memoria bloqueante opcional propiedad del plugin que se ejecuta +antes de la respuesta principal para las sesiones conversacionales elegibles. + +Existe porque la mayoría de los sistemas de memoria son capaces, pero reactivos. Dependen de +que el agente principal decida cuándo buscar en la memoria, o de que el usuario diga cosas +como "recuerda esto" o "busca en la memoria". Para entonces, el momento en que la memoria +habría hecho que la respuesta se sintiera natural ya pasó. + +La memoria activa le da al sistema una oportunidad acotada de sacar a la superficie memoria relevante +antes de que se genere la respuesta principal. + +## Pega esto en tu agente + +Pega esto en tu agente si quieres que habilite la Memoria activa con una +configuración autónoma y segura por defecto: + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + enabled: true, + agents: ["main"], + allowedChatTypes: ["direct"], + modelFallbackPolicy: "default-remote", + queryMode: "recent", + promptStyle: "balanced", + timeoutMs: 15000, + maxSummaryChars: 220, + persistTranscripts: false, + logging: true, + }, + }, + }, + }, +} +``` + +Esto activa el plugin para el agente `main`, lo mantiene limitado a sesiones +de estilo mensaje directo de forma predeterminada, le permite heredar primero el modelo de la sesión actual y +sigue permitiendo la reserva remota integrada si no hay ningún modelo explícito o heredado +disponible. + +Después de eso, reinicia el gateway: + +```bash +node scripts/run-node.mjs gateway --profile dev +``` + +Para inspeccionarlo en vivo en una conversación: + +```text +/verbose on +``` + +## Activar la memoria activa + +La configuración más segura es: + +1. habilitar el plugin +2. apuntar a un agente conversacional +3. mantener el registro activado solo mientras ajustas la configuración + +Comienza con esto en `openclaw.json`: + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + agents: ["main"], + allowedChatTypes: ["direct"], + modelFallbackPolicy: "default-remote", + queryMode: "recent", + promptStyle: "balanced", + timeoutMs: 15000, + maxSummaryChars: 220, + persistTranscripts: false, + logging: true, + }, + }, + }, + }, +} +``` + +Luego reinicia el gateway: + +```bash +node scripts/run-node.mjs gateway --profile dev +``` + +Qué significa esto: + +- `plugins.entries.active-memory.enabled: true` activa el plugin +- `config.agents: ["main"]` habilita la memoria activa solo para el agente `main` +- `config.allowedChatTypes: ["direct"]` mantiene la memoria activa activada de forma predeterminada solo para sesiones de estilo mensaje directo +- si `config.model` no está configurado, la memoria activa hereda primero el modelo de la sesión actual +- `config.modelFallbackPolicy: "default-remote"` mantiene la reserva remota integrada como predeterminada cuando no hay ningún modelo explícito o heredado disponible +- `config.promptStyle: "balanced"` usa el estilo de prompt predeterminado de propósito general para el modo `recent` +- la memoria activa sigue ejecutándose solo en sesiones de chat interactivas persistentes elegibles + +## Cómo verla + +La memoria activa inyecta contexto del sistema oculto para el modelo. No expone +etiquetas sin procesar `...` al cliente. + +## Alternancia por sesión + +Usa el comando del plugin cuando quieras pausar o reanudar la memoria activa para la +sesión de chat actual sin editar la configuración: + +```text +/active-memory status +/active-memory off +/active-memory on +``` + +Esto tiene alcance de sesión. No cambia +`plugins.entries.active-memory.enabled`, la selección del agente ni otra +configuración global. + +Si quieres que el comando escriba la configuración y pause o reanude la memoria activa para +todas las sesiones, usa la forma global explícita: + +```text +/active-memory status --global +/active-memory off --global +/active-memory on --global +``` + +La forma global escribe `plugins.entries.active-memory.config.enabled`. Deja +`plugins.entries.active-memory.enabled` activado para que el comando siga estando disponible para +volver a activar la memoria activa más adelante. + +Si quieres ver qué está haciendo la memoria activa en una sesión en vivo, activa el modo +detallado para esa sesión: + +```text +/verbose on +``` + +Con el modo detallado activado, OpenClaw puede mostrar: + +- una línea de estado de la memoria activa como `Active Memory: ok 842ms recent 34 chars` +- un resumen de depuración legible como `Active Memory Debug: Lemon pepper wings with blue cheese.` + +Esas líneas se derivan del mismo paso de memoria activa que alimenta el contexto oculto del +sistema, pero están formateadas para humanos en lugar de exponer marcado de prompt sin procesar. + +De forma predeterminada, la transcripción del subagente de memoria bloqueante es temporal y se elimina +después de que finaliza la ejecución. + +Ejemplo de flujo: + +```text +/verbose on +what wings should i order? +``` + +Forma esperada de la respuesta visible: + +```text +...normal assistant reply... + +🧩 Active Memory: ok 842ms recent 34 chars +🔎 Active Memory Debug: Lemon pepper wings with blue cheese. +``` + +## Cuándo se ejecuta + +La memoria activa usa dos compuertas: + +1. **Inclusión por configuración** + El plugin debe estar habilitado, y el id del agente actual debe aparecer en + `plugins.entries.active-memory.config.agents`. +2. **Elegibilidad estricta en tiempo de ejecución** + Incluso cuando está habilitada y dirigida, la memoria activa solo se ejecuta para + sesiones de chat interactivas persistentes elegibles. + +La regla real es: + +```text +plugin enabled ++ +agent id targeted ++ +allowed chat type ++ +eligible interactive persistent chat session += +active memory runs +``` + +Si cualquiera de esos elementos falla, la memoria activa no se ejecuta. + +## Tipos de sesión + +`config.allowedChatTypes` controla qué tipos de conversaciones pueden ejecutar Memoria +activa. + +El valor predeterminado es: + +```json5 +allowedChatTypes: ["direct"] +``` + +Eso significa que la Memoria activa se ejecuta de forma predeterminada en sesiones de estilo mensaje directo, pero +no en sesiones de grupo o canal a menos que las incluyas explícitamente. + +Ejemplos: + +```json5 +allowedChatTypes: ["direct"] +``` + +```json5 +allowedChatTypes: ["direct", "group"] +``` + +```json5 +allowedChatTypes: ["direct", "group", "channel"] +``` + +## Dónde se ejecuta + +La memoria activa es una función de enriquecimiento conversacional, no una +función de inferencia para toda la plataforma. + +| Superficie | ¿Se ejecuta la memoria activa? | +| ------------------------------------------------------------------- | ------------------------------------------------------- | +| Sesiones persistentes de Control UI / chat web | Sí, si el plugin está habilitado y el agente está seleccionado | +| Otras sesiones de canal interactivas en la misma ruta de chat persistente | Sí, si el plugin está habilitado y el agente está seleccionado | +| Ejecuciones sin interfaz de un solo uso | No | +| Ejecuciones de latido/en segundo plano | No | +| Rutas internas genéricas de `agent-command` | No | +| Ejecución interna/de ayuda de subagentes | No | + +## Por qué usarla + +Usa la memoria activa cuando: + +- la sesión es persistente y orientada al usuario +- el agente tiene memoria a largo plazo significativa para buscar +- la continuidad y la personalización importan más que el determinismo puro del prompt + +Funciona especialmente bien para: + +- preferencias estables +- hábitos recurrentes +- contexto del usuario a largo plazo que debería aflorar de forma natural + +No es una buena opción para: + +- automatización +- workers internos +- tareas de API de un solo uso +- lugares donde la personalización oculta sería sorprendente + +## Cómo funciona + +La forma en tiempo de ejecución es: + +```mermaid +flowchart LR + U["User Message"] --> Q["Build Memory Query"] + Q --> R["Active Memory Blocking Memory Sub-Agent"] + R -->|NONE or empty| M["Main Reply"] + R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"] + I --> M["Main Reply"] +``` + +El subagente de memoria bloqueante solo puede usar: + +- `memory_search` +- `memory_get` + +Si la conexión es débil, debe devolver `NONE`. + +## Modos de consulta + +`config.queryMode` controla cuánto de la conversación ve el subagente de memoria bloqueante. + +## Estilos de prompt + +`config.promptStyle` controla cuán dispuesto o estricto es el subagente de memoria bloqueante +al decidir si devolver memoria. + +Estilos disponibles: + +- `balanced`: predeterminado de propósito general para el modo `recent` +- `strict`: el menos dispuesto; ideal cuando quieres muy poca contaminación del contexto cercano +- `contextual`: el más favorable para la continuidad; ideal cuando el historial de conversación debe importar más +- `recall-heavy`: más dispuesto a sacar a la superficie memoria con coincidencias más suaves pero aún plausibles +- `precision-heavy`: prefiere agresivamente `NONE` a menos que la coincidencia sea evidente +- `preference-only`: optimizado para favoritos, hábitos, rutinas, gustos y hechos personales recurrentes + +Asignación predeterminada cuando `config.promptStyle` no está configurado: + +```text +message -> strict +recent -> balanced +full -> contextual +``` + +Si configuras `config.promptStyle` explícitamente, esa anulación prevalece. + +Ejemplo: + +```json5 +promptStyle: "preference-only" +``` + +## Política de reserva de modelo + +Si `config.model` no está configurado, la Memoria activa intenta resolver un modelo en este orden: + +```text +explicit plugin model +-> current session model +-> agent primary model +-> optional built-in remote fallback +``` + +`config.modelFallbackPolicy` controla el último paso. + +Predeterminado: + +```json5 +modelFallbackPolicy: "default-remote" +``` + +Otra opción: + +```json5 +modelFallbackPolicy: "resolved-only" +``` + +Usa `resolved-only` si quieres que la Memoria activa omita la recuperación en lugar de usar +la reserva remota integrada predeterminada cuando no hay ningún modelo explícito o heredado +disponible. + +## Vías de escape avanzadas + +Estas opciones intencionalmente no forman parte de la configuración recomendada. + +`config.thinking` puede anular el nivel de razonamiento del subagente de memoria bloqueante: + +```json5 +thinking: "medium" +``` + +Predeterminado: + +```json5 +thinking: "off" +``` + +No habilites esto de forma predeterminada. La Memoria activa se ejecuta en la ruta de respuesta, por lo que el tiempo +adicional de razonamiento incrementa directamente la latencia visible para el usuario. + +`config.promptAppend` agrega instrucciones adicionales del operador después del prompt predeterminado de Memoria +activa y antes del contexto de la conversación: + +```json5 +promptAppend: "Prefer stable long-term preferences over one-off events." +``` + +`config.promptOverride` reemplaza el prompt predeterminado de Memoria activa. OpenClaw +sigue agregando después el contexto de la conversación: + +```json5 +promptOverride: "You are a memory search agent. Return NONE or one compact user fact." +``` + +No se recomienda personalizar prompts a menos que estés probando deliberadamente un +contrato de recuperación distinto. El prompt predeterminado está ajustado para devolver `NONE` +o contexto compacto de hechos del usuario para el modelo principal. + +### `message` + +Solo se envía el mensaje más reciente del usuario. + +```text +Latest user message only +``` + +Usa esto cuando: + +- quieres el comportamiento más rápido +- quieres el sesgo más fuerte hacia la recuperación de preferencias estables +- los turnos de seguimiento no necesitan contexto conversacional + +Tiempo de espera recomendado: + +- comienza alrededor de `3000` a `5000` ms + +### `recent` + +Se envía el mensaje más reciente del usuario más una pequeña cola conversacional reciente. + +```text +Recent conversation tail: +user: ... +assistant: ... +user: ... + +Latest user message: +... +``` + +Usa esto cuando: + +- quieres un mejor equilibrio entre velocidad y base conversacional +- las preguntas de seguimiento suelen depender de los últimos turnos + +Tiempo de espera recomendado: + +- comienza alrededor de `15000` ms + +### `full` + +La conversación completa se envía al subagente de memoria bloqueante. + +```text +Full conversation context: +user: ... +assistant: ... +user: ... +... +``` + +Usa esto cuando: + +- la mejor calidad de recuperación importa más que la latencia +- la conversación contiene una preparación importante muy atrás en el hilo + +Tiempo de espera recomendado: + +- auméntalo considerablemente en comparación con `message` o `recent` +- comienza alrededor de `15000` ms o más según el tamaño del hilo + +En general, el tiempo de espera debe aumentar con el tamaño del contexto: + +```text +message < recent < full +``` + +## Persistencia de transcripciones + +Las ejecuciones del subagente de memoria bloqueante de la memoria activa crean una transcripción real `session.jsonl` +durante la llamada al subagente de memoria bloqueante. + +De forma predeterminada, esa transcripción es temporal: + +- se escribe en un directorio temporal +- se usa solo para la ejecución del subagente de memoria bloqueante +- se elimina inmediatamente después de que finaliza la ejecución + +Si quieres conservar esas transcripciones del subagente de memoria bloqueante en disco para depuración o +inspección, activa la persistencia explícitamente: + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + agents: ["main"], + persistTranscripts: true, + transcriptDir: "active-memory", + }, + }, + }, + }, +} +``` + +Cuando está habilitada, la memoria activa almacena las transcripciones en un directorio separado dentro de la +carpeta de sesiones del agente de destino, no en la ruta principal de transcripción de la conversación del usuario. + +La disposición predeterminada es conceptualmente: + +```text +agents//sessions/active-memory/.jsonl +``` + +Puedes cambiar el subdirectorio relativo con `config.transcriptDir`. + +Usa esto con cuidado: + +- las transcripciones del subagente de memoria bloqueante pueden acumularse rápidamente en sesiones con mucha actividad +- el modo de consulta `full` puede duplicar mucho contexto de conversación +- estas transcripciones contienen contexto de prompt oculto y memorias recuperadas + +## Configuración + +Toda la configuración de la memoria activa se encuentra en: + +```text +plugins.entries.active-memory +``` + +Los campos más importantes son: + +| Clave | Tipo | Significado | +| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `enabled` | `boolean` | Habilita el plugin en sí | +| `config.agents` | `string[]` | Id. de agentes que pueden usar memoria activa | +| `config.model` | `string` | Referencia opcional del modelo del subagente de memoria bloqueante; cuando no está configurado, la memoria activa usa el modelo de la sesión actual | +| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla cuánto de la conversación ve el subagente de memoria bloqueante | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla cuán dispuesto o estricto es el subagente de memoria bloqueante al decidir si devolver memoria | +| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Anulación avanzada del nivel de razonamiento para el subagente de memoria bloqueante; valor predeterminado `off` por velocidad | +| `config.promptOverride` | `string` | Reemplazo avanzado completo del prompt; no se recomienda para uso normal | +| `config.promptAppend` | `string` | Instrucciones avanzadas adicionales añadidas al prompt predeterminado o reemplazado | +| `config.timeoutMs` | `number` | Tiempo de espera máximo estricto para el subagente de memoria bloqueante | +| `config.maxSummaryChars` | `number` | Cantidad máxima total de caracteres permitida en el resumen de active-memory | +| `config.logging` | `boolean` | Emite registros de memoria activa durante el ajuste | +| `config.persistTranscripts` | `boolean` | Conserva en disco las transcripciones del subagente de memoria bloqueante en lugar de eliminar los archivos temporales | +| `config.transcriptDir` | `string` | Directorio relativo de transcripciones del subagente de memoria bloqueante dentro de la carpeta de sesiones del agente | + +Campos de ajuste útiles: + +| Clave | Tipo | Significado | +| ----------------------------- | -------- | ------------------------------------------------------------ | +| `config.maxSummaryChars` | `number` | Cantidad máxima total de caracteres permitida en el resumen de active-memory | +| `config.recentUserTurns` | `number` | Turnos previos del usuario que se incluirán cuando `queryMode` sea `recent` | +| `config.recentAssistantTurns` | `number` | Turnos previos del asistente que se incluirán cuando `queryMode` sea `recent` | +| `config.recentUserChars` | `number` | Cantidad máxima de caracteres por turno reciente del usuario | +| `config.recentAssistantChars` | `number` | Cantidad máxima de caracteres por turno reciente del asistente | +| `config.cacheTtlMs` | `number` | Reutilización de caché para consultas idénticas repetidas | + +## Configuración recomendada + +Comienza con `recent`. + +```json5 +{ + plugins: { + entries: { + "active-memory": { + enabled: true, + config: { + agents: ["main"], + queryMode: "recent", + promptStyle: "balanced", + timeoutMs: 15000, + maxSummaryChars: 220, + logging: true, + }, + }, + }, + }, +} +``` + +Si quieres inspeccionar el comportamiento en vivo mientras ajustas la configuración, usa `/verbose on` en la +sesión en lugar de buscar un comando de depuración de active-memory independiente. + +Luego cambia a: + +- `message` si quieres menor latencia +- `full` si decides que el contexto adicional vale la pena aunque el subagente de memoria bloqueante sea más lento + +## Depuración + +Si la memoria activa no aparece donde esperas: + +1. Confirma que el plugin esté habilitado en `plugins.entries.active-memory.enabled`. +2. Confirma que el id. del agente actual figure en `config.agents`. +3. Confirma que estás probando mediante una sesión de chat interactiva persistente. +4. Activa `config.logging: true` y observa los registros del gateway. +5. Verifica que la búsqueda en memoria en sí funcione con `openclaw memory status --deep`. + +Si las coincidencias de memoria son ruidosas, ajusta más: + +- `maxSummaryChars` + +Si la memoria activa es demasiado lenta: + +- reduce `queryMode` +- reduce `timeoutMs` +- reduce la cantidad de turnos recientes +- reduce los límites de caracteres por turno + +## Páginas relacionadas + +- [Búsqueda en memoria](/es/concepts/memory-search) +- [Referencia de configuración de memoria](/es/reference/memory-config) +- [Configuración del Plugin SDK](/es/plugins/sdk-setup) diff --git a/docs/es/concepts/memory-search.md b/docs/es/concepts/memory-search.md index 3a952413c..079dc2a36 100644 --- a/docs/es/concepts/memory-search.md +++ b/docs/es/concepts/memory-search.md @@ -2,43 +2,39 @@ read_when: - Quieres entender cómo funciona `memory_search` - Quieres elegir un proveedor de embeddings - - Quieres ajustar la calidad de búsqueda + - Quieres ajustar la calidad de la búsqueda summary: Cómo la búsqueda de memoria encuentra notas relevantes usando embeddings y recuperación híbrida title: Búsqueda de memoria x-i18n: - generated_at: "2026-04-06T03:06:24Z" + generated_at: "2026-04-10T05:12:07Z" model: gpt-5.4 provider: openai - source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9 + source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f source_path: concepts/memory-search.md workflow: 15 --- # Búsqueda de memoria -`memory_search` encuentra notas relevantes de tus archivos de memoria, incluso cuando la -redacción difiere del texto original. Funciona indexando la memoria en pequeños -fragmentos y buscándolos mediante embeddings, palabras clave o ambos. +`memory_search` encuentra notas relevantes de tus archivos de memoria, incluso cuando la redacción difiere del texto original. Funciona indexando la memoria en fragmentos pequeños y buscándolos mediante embeddings, palabras clave o ambos. ## Inicio rápido -Si tienes configurada una clave de API de OpenAI, Gemini, Voyage o Mistral, la búsqueda de memoria -funciona automáticamente. Para establecer un proveedor explícitamente: +Si tienes configurada una clave de API de OpenAI, Gemini, Voyage o Mistral, la búsqueda de memoria funciona automáticamente. Para establecer un proveedor de forma explícita: ```json5 { agents: { defaults: { memorySearch: { - provider: "openai", // or "gemini", "local", "ollama", etc. + provider: "openai", // o "gemini", "local", "ollama", etc. }, }, }, } ``` -Para embeddings locales sin clave de API, usa `provider: "local"` (requiere -node-llama-cpp). +Para embeddings locales sin clave de API, usa `provider: "local"` (requiere `node-llama-cpp`). ## Proveedores compatibles @@ -58,48 +54,41 @@ OpenClaw ejecuta dos rutas de recuperación en paralelo y combina los resultados ```mermaid flowchart LR - Q["Query"] --> E["Embedding"] - Q --> T["Tokenize"] - E --> VS["Vector Search"] - T --> BM["BM25 Search"] - VS --> M["Weighted Merge"] + Q["Consulta"] --> E["Embedding"] + Q --> T["Tokenizar"] + E --> VS["Búsqueda vectorial"] + T --> BM["Búsqueda BM25"] + VS --> M["Combinación ponderada"] BM --> M - M --> R["Top Results"] + M --> R["Resultados principales"] ``` -- **La búsqueda vectorial** encuentra notas con significado similar ("gateway host" coincide con - "the machine running OpenClaw"). -- **La búsqueda por palabras clave BM25** encuentra coincidencias exactas (ID, cadenas de error, claves de - configuración). +- **La búsqueda vectorial** encuentra notas con significado similar ("gateway host" coincide con "la máquina que ejecuta OpenClaw"). +- **La búsqueda de palabras clave BM25** encuentra coincidencias exactas (ID, cadenas de error, claves de configuración). Si solo una ruta está disponible (sin embeddings o sin FTS), la otra se ejecuta sola. -## Mejorar la calidad de búsqueda +## Mejorar la calidad de la búsqueda -Dos funciones opcionales ayudan cuando tienes un historial grande de notas: +Dos funciones opcionales ayudan cuando tienes un historial amplio de notas: ### Decaimiento temporal -Las notas antiguas pierden gradualmente peso en la clasificación para que la información reciente aparezca primero. -Con la vida media predeterminada de 30 días, una nota del mes pasado puntúa con el 50 % de -su peso original. Los archivos permanentes como `MEMORY.md` nunca se degradan. +Las notas antiguas pierden gradualmente peso en la clasificación para que la información reciente aparezca primero. Con la vida media predeterminada de 30 días, una nota del mes pasado obtiene el 50% de su peso original. Los archivos permanentes como `MEMORY.md` nunca se degradan. -Habilita el decaimiento temporal si tu agente tiene meses de notas diarias y la información -desactualizada sigue superando al contexto reciente. +Activa el decaimiento temporal si tu agente tiene meses de notas diarias y la información obsoleta sigue superando al contexto reciente. ### MMR (diversidad) -Reduce los resultados redundantes. Si cinco notas mencionan la misma configuración del router, MMR -garantiza que los resultados principales cubran distintos temas en lugar de repetirse. +Reduce los resultados redundantes. Si cinco notas mencionan la misma configuración del router, MMR garantiza que los resultados principales cubran temas diferentes en lugar de repetirse. -Habilita MMR si `memory_search` sigue devolviendo fragmentos casi duplicados de -distintas notas diarias. +Activa MMR si `memory_search` sigue devolviendo fragmentos casi duplicados de distintas notas diarias. -### Habilitar ambos +### Activar ambos ```json5 { @@ -120,29 +109,22 @@ distintas notas diarias. ## Memoria multimodal -Con Gemini Embedding 2, puedes indexar imágenes y archivos de audio junto con -Markdown. Las consultas de búsqueda siguen siendo texto, pero coinciden con contenido visual y de audio. Consulta la [referencia de configuración de memoria](/es/reference/memory-config) para la -configuración. +Con Gemini Embedding 2, puedes indexar imágenes y archivos de audio junto con Markdown. Las consultas de búsqueda siguen siendo texto, pero coinciden con contenido visual y de audio. Consulta la [referencia de configuración de memoria](/es/reference/memory-config) para la configuración. -## Búsqueda de memoria de sesión +## Búsqueda en la memoria de sesión -Opcionalmente puedes indexar transcripciones de sesión para que `memory_search` pueda recordar -conversaciones anteriores. Esto es optativo mediante -`memorySearch.experimental.sessionMemory`. Consulta la -[referencia de configuración](/es/reference/memory-config) para ver los detalles. +Opcionalmente, puedes indexar transcripciones de sesiones para que `memory_search` pueda recuperar conversaciones anteriores. Esto es opcional mediante `memorySearch.experimental.sessionMemory`. Consulta la [referencia de configuración](/es/reference/memory-config) para más detalles. ## Solución de problemas -**¿No hay resultados?** Ejecuta `openclaw memory status` para comprobar el índice. Si está vacío, ejecuta -`openclaw memory index --force`. +**¿No hay resultados?** Ejecuta `openclaw memory status` para comprobar el índice. Si está vacío, ejecuta `openclaw memory index --force`. -**¿Solo hay coincidencias por palabras clave?** Puede que tu proveedor de embeddings no esté configurado. Comprueba -`openclaw memory status --deep`. +**¿Solo coincidencias por palabras clave?** Puede que tu proveedor de embeddings no esté configurado. Comprueba `openclaw memory status --deep`. -**¿No se encuentra texto CJK?** Reconstruye el índice FTS con -`openclaw memory index --force`. +**¿No se encuentra texto CJK?** Reconstruye el índice FTS con `openclaw memory index --force`. -## Más información +## Lecturas adicionales -- [Memoria](/es/concepts/memory) -- estructura de archivos, backends, herramientas -- [Referencia de configuración de memoria](/es/reference/memory-config) -- todas las opciones de configuración +- [Memoria activa](/es/concepts/active-memory) -- memoria de subagentes para sesiones de chat interactivas +- [Memoria](/es/concepts/memory) -- diseño de archivos, backends, herramientas +- [Referencia de configuración de memoria](/es/reference/memory-config) -- todos los ajustes de configuración diff --git a/docs/es/concepts/qa-e2e-automation.md b/docs/es/concepts/qa-e2e-automation.md index cc38146a1..f60224a68 100644 --- a/docs/es/concepts/qa-e2e-automation.md +++ b/docs/es/concepts/qa-e2e-automation.md @@ -1,51 +1,51 @@ --- read_when: - - Ampliar qa-lab o qa-channel + - Ampliación de qa-lab o qa-channel - Agregar escenarios de QA respaldados por el repositorio - - Crear automatización de QA de mayor realismo alrededor del panel del Gateway -summary: Estructura de automatización de QA privada para qa-lab, qa-channel, escenarios sembrados e informes de protocolo + - Creación de automatización de QA de mayor realismo en torno al panel del Gateway +summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con semilla e informes de protocolo title: Automatización E2E de QA x-i18n: - generated_at: "2026-04-09T01:27:42Z" + generated_at: "2026-04-10T05:12:08Z" model: gpt-5.4 provider: openai - source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833 + source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automatización E2E de QA -La pila de QA privada está pensada para ejercitar OpenClaw de una manera más realista, -con forma de canal, de lo que puede hacerlo una sola prueba unitaria. +La pila privada de QA está pensada para ejercitar OpenClaw de una forma más realista, +con forma de canal, que la que puede cubrir una sola prueba unitaria. -Partes actuales: +Piezas actuales: - `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo, reacción, edición y eliminación. - `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción, inyectar mensajes entrantes y exportar un informe en Markdown. - `qa/`: recursos semilla respaldados por el repositorio para la tarea inicial y los - escenarios base de QA. + escenarios de QA base. El flujo actual del operador de QA es un sitio de QA de dos paneles: - Izquierda: panel del Gateway (Control UI) con el agente. -- Derecha: QA Lab, que muestra la transcripción tipo Slack y el plan del escenario. +- Derecha: QA Lab, que muestra la transcripción estilo Slack y el plan del escenario. -Ejecuta esto con: +Ejecútalo con: ```bash pnpm qa:lab:up ``` Eso compila el sitio de QA, inicia la ruta del gateway respaldada por Docker y expone la -página de QA Lab donde un operador o un bucle de automatización puede dar al agente una -misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o -qué siguió bloqueado. +página de QA Lab donde un operador o un bucle de automatización puede darle al agente una +misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló +o qué siguió bloqueado. -Para iterar más rápido en la UI de QA Lab sin reconstruir la imagen de Docker cada vez, -inicia la pila con un paquete de QA Lab montado mediante bind: +Para iterar más rápido en la interfaz de QA Lab sin reconstruir la imagen de Docker cada vez, +inicia la pila con un paquete de QA Lab montado por enlace: ```bash pnpm openclaw qa docker-build-image @@ -54,10 +54,24 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta mediante bind +`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta por enlace `extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` recompila ese paquete cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash -de recursos de QA Lab. +del recurso de QA Lab. + +Para una ruta desechable en una VM Linux sin incorporar Docker en la ruta de QA, ejecuta: + +```bash +pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline +``` + +Esto arranca un guest nuevo de Multipass, instala dependencias, compila OpenClaw dentro del guest, +ejecuta `qa suite` y luego copia el informe y el resumen normales de QA de vuelta a `.artifacts/qa-e2e/...` en el host. +Reutiliza el mismo comportamiento de selección de escenarios que `qa suite` en el host. +Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que son prácticas para el +guest: claves de proveedor basadas en variables de entorno, la ruta de configuración del proveedor en vivo de QA y +`CODEX_HOME` cuando está presente. Mantén `--output-dir` bajo la raíz del repositorio para que el guest +pueda escribir de vuelta a través del espacio de trabajo montado. ## Semillas respaldadas por el repositorio @@ -67,7 +81,7 @@ Los recursos semilla viven en `qa/`: - `qa/scenarios/*.md` Estos están intencionalmente en git para que el plan de QA sea visible tanto para las personas como para el -agente. La lista base debe seguir siendo lo bastante amplia como para cubrir: +agente. La lista base debe seguir siendo lo bastante amplia para cubrir: - chat por MD y por canal - comportamiento de hilos @@ -75,13 +89,13 @@ agente. La lista base debe seguir siendo lo bastante amplia como para cubrir: - callbacks de cron - recuperación de memoria - cambio de modelo -- transferencia a subagente +- traspaso a subagente - lectura del repositorio y de la documentación - una pequeña tarea de compilación como Lobster Invaders ## Informes -`qa-lab` exporta un informe de protocolo en Markdown a partir de la línea de tiempo observada del bus. +`qa-lab` exporta un informe de protocolo en Markdown a partir de la línea temporal observada del bus. El informe debe responder: - Qué funcionó @@ -89,7 +103,7 @@ El informe debe responder: - Qué siguió bloqueado - Qué escenarios de seguimiento vale la pena agregar -Para comprobaciones de carácter y estilo, ejecuta el mismo escenario en múltiples refs de modelos en vivo +Para comprobaciones de carácter y estilo, ejecuta el mismo escenario con múltiples referencias de modelos en vivo y escribe un informe en Markdown evaluado: ```bash @@ -109,41 +123,41 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -El comando ejecuta procesos hijo locales del gateway de QA, no Docker. Los escenarios de evaluación de carácter -deben establecer la persona mediante `SOUL.md`, y luego ejecutar turnos de usuario normales -como chat, ayuda del espacio de trabajo y pequeñas tareas de archivos. No se le debe decir al modelo -candidato que está siendo evaluado. El comando conserva cada transcripción completa, -registra estadísticas básicas de ejecución y luego pide a los modelos juez en modo fast con -razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor. +El comando ejecuta procesos secundarios locales del gateway de QA, no Docker. Los escenarios de evaluación de carácter +deben establecer la personalidad mediante `SOUL.md` y luego ejecutar turnos de usuario normales +como chat, ayuda del espacio de trabajo y pequeñas tareas sobre archivos. No se le debe indicar al modelo +candidato que está siendo evaluado. El comando conserva cada transcripción completa, registra estadísticas básicas de ejecución y +luego pide a los modelos jueces en modo rápido con razonamiento `xhigh` que clasifiquen las ejecuciones según +naturalidad, vibra y humor. Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo -cada transcripción y estado de ejecución, pero las refs candidatas se sustituyen por -etiquetas neutras como `candidate-01`; el informe vuelve a asignar las clasificaciones a las refs reales después +cada transcripción y el estado de la ejecución, pero las referencias candidatas se reemplazan por etiquetas neutrales +como `candidate-01`; el informe vuelve a asociar las clasificaciones con las referencias reales después del análisis. -Las ejecuciones candidatas usan de forma predeterminada pensamiento `high`, con `xhigh` para los modelos de OpenAI que -lo admiten. Sustituye un candidato específico en línea con +Las ejecuciones candidatas usan por defecto pensamiento `high`, con `xhigh` para modelos de OpenAI que +lo admiten. Sobrescribe un candidato específico en línea con `--model provider/model,thinking=`. `--thinking ` sigue estableciendo un -respaldo global, y la forma anterior `--model-thinking ` se +valor de respaldo global, y la forma anterior `--model-thinking ` se mantiene por compatibilidad. -Las refs candidatas de OpenAI usan de forma predeterminada el modo fast para que se use el procesamiento prioritario allí -donde el proveedor lo admita. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando un -solo candidato o juez necesite una sustitución. Pasa `--fast` solo cuando quieras -forzar el modo fast para todos los modelos candidatos. Las duraciones de candidatos y jueces se -registran en el informe para el análisis comparativo, pero los prompts de los jueces dicen explícitamente que -no clasifiquen por velocidad. -Tanto las ejecuciones de modelos candidatos como las de jueces usan por defecto una concurrencia de 16. Reduce -`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión del gateway local +Las referencias candidatas de OpenAI usan por defecto modo rápido para que se utilice el procesamiento prioritario cuando +el proveedor lo admite. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando un +solo candidato o juez necesite una sobrescritura. Pasa `--fast` solo cuando quieras +forzar el modo rápido para todos los modelos candidatos. Las duraciones de candidatos y jueces se +registran en el informe para análisis comparativo, pero los prompts de los jueces indican explícitamente +que no deben clasificar por velocidad. +Tanto las ejecuciones de modelos candidatos como las de jueces usan por defecto concurrencia 16. Reduce +`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión local sobre el gateway hagan que una ejecución sea demasiado ruidosa. Cuando no se pasa ningún `--model` candidato, la evaluación de carácter usa por defecto `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` y -`google/gemini-3.1-pro-preview` cuando no se pasa `--model`. -Cuando no se pasa `--judge-model`, los jueces usan por defecto +`google/gemini-3.1-pro-preview` cuando no se pasa ningún `--model`. +Cuando no se pasa ningún `--judge-model`, los jueces usan por defecto `openai/gpt-5.4,thinking=xhigh,fast` y `anthropic/claude-opus-4-6,thinking=high`. ## Documentación relacionada -- [Testing](/es/help/testing) -- [QA Channel](/es/channels/qa-channel) -- [Dashboard](/web/dashboard) +- [Pruebas](/es/help/testing) +- [Canal de QA](/es/channels/qa-channel) +- [Panel](/web/dashboard) diff --git a/docs/es/help/testing.md b/docs/es/help/testing.md index cfb9c34e0..0dbda3087 100644 --- a/docs/es/help/testing.md +++ b/docs/es/help/testing.md @@ -3,13 +3,13 @@ read_when: - Ejecutar pruebas localmente o en CI - Agregar regresiones para errores de modelo/proveedor - Depurar el comportamiento del gateway + agente -summary: 'Kit de pruebas: suites unit/e2e/live, ejecutores de Docker y qué cubre cada prueba' +summary: 'Kit de pruebas: suites unitarias/e2e/live, ejecutores de Docker y qué cubre cada prueba' title: Pruebas x-i18n: - generated_at: "2026-04-09T01:30:09Z" + generated_at: "2026-04-10T05:12:07Z" model: gpt-5.4 provider: openai - source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b + source_hash: 21b78e59a5189f4e8e6e1b490d350f4735c0395da31d21fc5d10b825313026b4 source_path: help/testing.md workflow: 15 --- @@ -20,87 +20,109 @@ OpenClaw tiene tres suites de Vitest (unit/integration, e2e, live) y un pequeño Este documento es una guía de “cómo probamos”: -- Qué cubre cada suite (y qué _deliberadamente_ no cubre) +- Qué cubre cada suite (y qué _no_ cubre deliberadamente) - Qué comandos ejecutar para flujos de trabajo comunes (local, antes de hacer push, depuración) - Cómo las pruebas live descubren credenciales y seleccionan modelos/proveedores -- Cómo agregar regresiones para problemas reales de modelos/proveedores +- Cómo agregar regresiones para problemas reales de modelo/proveedor ## Inicio rápido La mayoría de los días: -- Gate completo (esperado antes de hacer push): `pnpm build && pnpm check && pnpm test` -- Ejecución local más rápida de la suite completa en una máquina con suficientes recursos: `pnpm test:max` -- Bucle de vigilancia directo de Vitest: `pnpm test:watch` +- Puerta completa (esperada antes de hacer push): `pnpm build && pnpm check && pnpm test` +- Ejecución local más rápida de la suite completa en una máquina con buenos recursos: `pnpm test:max` +- Bucle directo de observación de Vitest: `pnpm test:watch` - El direccionamiento directo a archivos ahora también enruta rutas de extensiones/canales: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Sitio de QA con respaldo en Docker: `pnpm qa:lab:up` +- Prefiere primero ejecuciones dirigidas cuando estás iterando sobre un único fallo. +- Sitio de QA respaldado por Docker: `pnpm qa:lab:up` +- Lane de QA respaldado por VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Cuando toques pruebas o quieras más confianza: +Cuando tocas pruebas o quieres más confianza: -- Gate de cobertura: `pnpm test:coverage` +- Puerta de cobertura: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` -Al depurar proveedores/modelos reales (requiere credenciales reales): +Cuando depuras proveedores/modelos reales (requiere credenciales reales): -- Suite live (modelos + sondeos de herramientas/imágenes del gateway): `pnpm test:live` -- Apuntar a un archivo live en silencio: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (modelos + sondas de herramientas/imágenes del gateway): `pnpm test:live` +- Dirigir silenciosamente a un archivo live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Consejo: cuando solo necesites un caso fallido, prefiere limitar las pruebas live mediante las variables de entorno de allowlist descritas abajo. +Consejo: cuando solo necesitas un caso fallido, prefiere acotar las pruebas live mediante las variables de entorno de allowlist descritas abajo. + +## Ejecutores específicos de QA + +Estos comandos están junto a las suites de prueba principales cuando necesitas el realismo de qa-lab: + +- `pnpm openclaw qa suite` + - Ejecuta escenarios de QA respaldados por el repositorio directamente en el host. +- `pnpm openclaw qa suite --runner multipass` + - Ejecuta la misma suite de QA dentro de una VM Linux desechable de Multipass. + - Mantiene el mismo comportamiento de selección de escenarios que `qa suite` en el host. + - Reutiliza las mismas banderas de selección de proveedor/modelo que `qa suite`. + - Las ejecuciones live reenvían las entradas de autenticación de QA compatibles que son prácticas para el invitado: + claves de proveedor basadas en entorno, la ruta de configuración del proveedor live de QA y `CODEX_HOME` + cuando está presente. + - Los directorios de salida deben permanecer bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través + del espacio de trabajo montado. + - Escribe el informe y el resumen normales de QA más los registros de Multipass en + `.artifacts/qa-e2e/...`. +- `pnpm qa:lab:up` + - Inicia el sitio de QA respaldado por Docker para trabajo de QA estilo operador. ## Suites de prueba (qué se ejecuta dónde) Piensa en las suites como “realismo creciente” (y mayor inestabilidad/costo): -### Unit / integration (predeterminado) +### Unit / integration (predeterminada) - Comando: `pnpm test` -- Configuración: diez ejecuciones de shards secuenciales (`vitest.full-*.config.ts`) sobre los proyectos de Vitest con alcance existente -- Archivos: inventarios core/unit en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas node permitidas de `ui` cubiertas por `vitest.unit.config.ts` +- Configuración: diez ejecuciones secuenciales por fragmentos (`vitest.full-*.config.ts`) sobre los proyectos acotados existentes de Vitest +- Archivos: inventarios core/unit en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas de nodo de `ui` incluidas en la allowlist cubiertas por `vitest.unit.config.ts` - Alcance: - Pruebas unitarias puras - - Pruebas de integración en proceso (autenticación del gateway, routing, herramientas, análisis, configuración) + - Pruebas de integración en proceso (auth del gateway, enrutamiento, herramientas, análisis, configuración) - Regresiones deterministas para errores conocidos - Expectativas: - Se ejecuta en CI - No requiere claves reales - Debe ser rápida y estable - Nota sobre proyectos: - - `pnpm test` sin objetivo ahora ejecuta once configuraciones de shards más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso nativo gigante del proyecto raíz. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas. - - `pnpm test --watch` sigue usando el grafo de proyectos nativo de `vitest.config.ts` en la raíz, porque un bucle de watch con múltiples shards no es práctico. - - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` enrutan primero los objetivos explícitos de archivos/directorios a través de carriles con alcance, por lo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo completo de inicio del proyecto raíz. - - `pnpm test:changed` expande las rutas modificadas de git en esos mismos carriles con alcance cuando el diff solo toca archivos de origen/prueba enrutable; las ediciones de configuración/preparación siguen recurriendo a la reejecución amplia del proyecto raíz. - - Algunas pruebas seleccionadas de `plugin-sdk` y `commands` también se enrutan por carriles ligeros dedicados que omiten `test/setup-openclaw-runtime.ts`; los archivos con mucho estado/runtime permanecen en los carriles existentes. - - Algunos archivos auxiliares seleccionados de `plugin-sdk` y `commands` también mapean las ejecuciones de modo changed a pruebas hermanas explícitas en esos carriles ligeros, para que las ediciones de helpers eviten reejecutar la suite pesada completa de ese directorio. - - `auto-reply` ahora tiene tres buckets dedicados: helpers core de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de reply fuera de las pruebas baratas de estado/chunk/token. + - `pnpm test` sin destino ahora ejecuta once configuraciones de fragmentos más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso gigante del proyecto raíz nativo. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas. + - `pnpm test --watch` sigue usando el grafo de proyectos raíz nativo de `vitest.config.ts`, porque un bucle de observación de múltiples fragmentos no es práctico. + - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` enrutan primero los destinos explícitos de archivo/directorio mediante lanes acotados, por lo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo de arranque completo del proyecto raíz. + - `pnpm test:changed` expande las rutas git modificadas en los mismos lanes acotados cuando el diff solo toca archivos de código fuente/prueba enrutable; las ediciones de configuración/setup siguen recurriendo a la reejecución amplia del proyecto raíz. + - Algunas pruebas seleccionadas de `plugin-sdk` y `commands` también se enrutan por lanes ligeros dedicados que omiten `test/setup-openclaw-runtime.ts`; los archivos con estado o de runtime pesado permanecen en los lanes existentes. + - Algunos archivos fuente auxiliares seleccionados de `plugin-sdk` y `commands` también asignan las ejecuciones en modo changed a pruebas hermanas explícitas en esos lanes ligeros, de modo que las ediciones auxiliares evitan reejecutar la suite pesada completa para ese directorio. + - `auto-reply` ahora tiene tres buckets dedicados: auxiliares core de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de respuestas fuera de las pruebas baratas de estado/fragmentos/tokens. - Nota sobre el ejecutor integrado: - - Cuando cambies entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de compactación, - conserva ambos niveles de cobertura. - - Agrega regresiones enfocadas de helpers para límites puros de routing/normalización. - - También mantén saludables las suites de integración del ejecutor integrado: + - Cuando cambies las entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de compactación, + mantén ambos niveles de cobertura. + - Agrega regresiones auxiliares enfocadas para límites puros de enrutamiento/normalización. + - Mantén también saludables las suites de integración del ejecutor integrado: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, y + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` y `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Esas suites verifican que los id con alcance y el comportamiento de compactación sigan fluyendo - por las rutas reales de `run.ts` / `compact.ts`; las pruebas solo de helpers no son un - sustituto suficiente de esas rutas de integración. + - Esas suites verifican que los id acotados y el comportamiento de compactación sigan fluyendo + a través de las rutas reales `run.ts` / `compact.ts`; las pruebas solo de auxiliares no son un + sustituto suficiente para esas rutas de integración. - Nota sobre el pool: - La configuración base de Vitest ahora usa `threads` de forma predeterminada. - - La configuración compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos raíz, e2e y live. - - El carril raíz de UI mantiene su configuración y optimizador `jsdom`, pero ahora también se ejecuta en el ejecutor compartido no aislado. - - Cada shard de `pnpm test` hereda los mismos valores predeterminados `threads` + `isolate: false` de la configuración compartida de Vitest. - - El lanzador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` de forma predeterminada para los procesos Node hijo de Vitest, para reducir el churn de compilación de V8 durante ejecuciones locales grandes. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. -- Nota sobre iteración local rápida: - - `pnpm test:changed` enruta a través de carriles con alcance cuando las rutas modificadas se asignan limpiamente a una suite más pequeña. - - `pnpm test:max` y `pnpm test:changed:max` mantienen el mismo comportamiento de routing, solo que con un límite de workers más alto. - - El autoescalado local de workers ahora es intencionalmente conservador y también reduce el ritmo cuando la carga promedio del host ya es alta, para que múltiples ejecuciones concurrentes de Vitest hagan menos daño de forma predeterminada. - - La configuración base de Vitest marca los archivos de proyectos/configuración como `forceRerunTriggers` para que las reejecuciones en modo changed sigan siendo correctas cuando cambie el cableado de pruebas. + - La configuración compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos raíz, las configuraciones e2e y live. + - El lane UI raíz mantiene su configuración `jsdom` y optimizador, pero ahora también se ejecuta en el ejecutor compartido no aislado. + - Cada fragmento de `pnpm test` hereda los mismos valores predeterminados `threads` + `isolate: false` de la configuración compartida de Vitest. + - El lanzador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` para los procesos Node hijos de Vitest de forma predeterminada para reducir la rotación de compilación de V8 durante grandes ejecuciones locales. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. +- Nota de iteración local rápida: + - `pnpm test:changed` enruta mediante lanes acotados cuando las rutas modificadas se asignan claramente a una suite más pequeña. + - `pnpm test:max` y `pnpm test:changed:max` mantienen el mismo comportamiento de enrutamiento, solo que con un límite mayor de workers. + - El autoescalado local de workers ahora es deliberadamente conservador y también reduce la carga cuando el promedio de carga del host ya es alto, de modo que múltiples ejecuciones concurrentes de Vitest hagan menos daño de forma predeterminada. + - La configuración base de Vitest marca los archivos de proyectos/configuración como `forceRerunTriggers` para que las reejecuciones en modo changed sigan siendo correctas cuando cambia el cableado de pruebas. - La configuración mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado en hosts compatibles; establece `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si quieres una ubicación de caché explícita para perfilado directo. - Nota de depuración de rendimiento: - - `pnpm test:perf:imports` habilita el informe de duración de importaciones de Vitest más la salida de desglose de importaciones. - - `pnpm test:perf:imports:changed` limita esa misma vista de perfilado a archivos modificados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado contra la ruta nativa del proyecto raíz para ese diff confirmado e imprime el tiempo total más el RSS máximo en macOS. + - `pnpm test:perf:imports` habilita informes de duración de importación de Vitest más salida de desglose de importaciones. + - `pnpm test:perf:imports:changed` limita la misma vista de perfilado a los archivos modificados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado con la ruta nativa del proyecto raíz para ese diff confirmado e imprime el tiempo total más el RSS máximo de macOS. - `pnpm test:perf:changed:bench -- --worktree` evalúa el árbol de trabajo actual con cambios enrutando la lista de archivos modificados a través de `scripts/test-projects.mjs` y la configuración raíz de Vitest. - - `pnpm test:perf:profile:main` escribe un perfil de CPU del hilo principal para la sobrecarga de inicio y transformación de Vitest/Vite. + - `pnpm test:perf:profile:main` escribe un perfil de CPU del hilo principal para la sobrecarga de arranque y transformación de Vitest/Vite. - `pnpm test:perf:profile:runner` escribe perfiles de CPU+heap del ejecutor para la suite unitaria con el paralelismo de archivos deshabilitado. ### E2E (smoke del gateway) @@ -108,37 +130,37 @@ Piensa en las suites como “realismo creciente” (y mayor inestabilidad/costo) - Comando: `pnpm test:e2e` - Configuración: `vitest.e2e.config.ts` - Archivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Valores predeterminados de runtime: - - Usa `threads` de Vitest con `isolate: false`, igual que el resto del repositorio. +- Valores predeterminados del runtime: + - Usa Vitest `threads` con `isolate: false`, igual que el resto del repositorio. - Usa workers adaptativos (CI: hasta 2, local: 1 de forma predeterminada). - Se ejecuta en modo silencioso de forma predeterminada para reducir la sobrecarga de E/S de consola. -- Anulaciones útiles: - - `OPENCLAW_E2E_WORKERS=` para forzar la cantidad de workers (máximo 16). +- Reemplazos útiles: + - `OPENCLAW_E2E_WORKERS=` para forzar el número de workers (limitado a 16). - `OPENCLAW_E2E_VERBOSE=1` para volver a habilitar la salida detallada en consola. - Alcance: - - Comportamiento end-to-end del gateway en múltiples instancias + - Comportamiento end-to-end del gateway con múltiples instancias - Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas - Expectativas: - - Se ejecuta en CI (cuando está habilitado en el pipeline) + - Se ejecuta en CI (cuando está habilitado en la canalización) - No requiere claves reales - - Tiene más piezas móviles que las pruebas unitarias (puede ser más lenta) + - Tiene más partes móviles que las pruebas unitarias (puede ser más lenta) ### E2E: smoke del backend OpenShell - Comando: `pnpm test:e2e:openshell` - Archivo: `test/openshell-sandbox.e2e.test.ts` - Alcance: - - Inicia un gateway OpenShell aislado en el host mediante Docker + - Inicia en el host un gateway OpenShell aislado mediante Docker - Crea un sandbox a partir de un Dockerfile local temporal - - Ejercita el backend OpenShell de OpenClaw mediante `sandbox ssh-config` + ejecución SSH reales - - Verifica el comportamiento canónico remoto del sistema de archivos a través del puente fs del sandbox + - Ejercita el backend OpenShell de OpenClaw sobre `sandbox ssh-config` + ejecución SSH real + - Verifica el comportamiento canónico del sistema de archivos remoto a través del puente fs del sandbox - Expectativas: - Solo opt-in; no forma parte de la ejecución predeterminada de `pnpm test:e2e` - - Requiere una CLI `openshell` local más un daemon de Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` aislados y luego destruye el gateway y el sandbox de prueba -- Anulaciones útiles: + - Requiere un `openshell` CLI local más un daemon Docker funcional + - Usa `HOME` / `XDG_CONFIG_HOME` aislados y luego destruye el gateway de prueba y el sandbox +- Reemplazos útiles: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar la prueba al ejecutar manualmente la suite e2e más amplia - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apuntar a un binario CLI o script contenedor no predeterminado + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apuntar a un binario CLI no predeterminado o a un script contenedor ### Live (proveedores reales + modelos reales) @@ -148,21 +170,21 @@ Piensa en las suites como “realismo creciente” (y mayor inestabilidad/costo) - Predeterminado: **habilitado** por `pnpm test:live` (establece `OPENCLAW_LIVE_TEST=1`) - Alcance: - “¿Este proveedor/modelo realmente funciona _hoy_ con credenciales reales?” - - Detectar cambios de formato de proveedor, particularidades de llamadas a herramientas, problemas de autenticación y comportamiento con límites de tasa + - Detectar cambios de formato del proveedor, peculiaridades de llamada de herramientas, problemas de auth y comportamiento de límites de tasa - Expectativas: - - No es estable en CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas) + - No es estable en CI por diseño (redes reales, políticas reales de proveedores, cuotas, interrupciones) - Cuesta dinero / usa límites de tasa - - Es preferible ejecutar subconjuntos limitados en lugar de “todo” + - Prefiere ejecutar subconjuntos acotados en lugar de “todo” - Las ejecuciones live obtienen `~/.profile` para recoger claves de API faltantes. -- De forma predeterminada, las ejecuciones live siguen aislando `HOME` y copian el material de configuración/autenticación a un home de prueba temporal para que los fixtures unitarios no puedan mutar tu `~/.openclaw` real. +- De forma predeterminada, las ejecuciones live siguen aislando `HOME` y copian el material de configuración/auth a un home temporal de prueba para que los fixtures unitarios no puedan modificar tu `~/.openclaw` real. - Establece `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando intencionalmente necesites que las pruebas live usen tu directorio home real. -- `pnpm test:live` ahora usa por defecto un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero suprime el aviso adicional de `~/.profile` y silencia los logs de arranque del gateway y el ruido de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los logs completos de inicio. -- Rotación de claves de API (específica del proveedor): establece `*_API_KEYS` con formato de comas/puntos y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o una anulación por live mediante `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas de límite de tasa. +- `pnpm test:live` ahora usa de forma predeterminada un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero suprime el aviso adicional de `~/.profile` y silencia los registros de arranque del gateway/el tráfico Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los registros completos de inicio. +- Rotación de claves de API (específica por proveedor): establece `*_API_KEYS` con formato coma/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o una anulación por live mediante `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan cuando reciben respuestas de límite de tasa. - Salida de progreso/heartbeat: - - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas a proveedores se vean activas incluso cuando la captura de consola de Vitest está en silencio. - - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso de proveedor/gateway se transmitan de inmediato durante las ejecuciones live. + - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas al proveedor se vean activas incluso cuando la captura de consola de Vitest está en modo silencioso. + - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso del proveedor/gateway se transmitan inmediatamente durante las ejecuciones live. - Ajusta los heartbeats de modelo directo con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajusta los heartbeats de gateway/sondeo con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Ajusta los heartbeats de gateway/sonda con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## ¿Qué suite debo ejecutar? @@ -170,42 +192,42 @@ Usa esta tabla de decisión: - Editar lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste mucho) - Tocar redes del gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` -- Depurar “mi bot está caído” / fallos específicos del proveedor / llamadas a herramientas: ejecuta un `pnpm test:live` limitado +- Depurar “mi bot está caído” / fallos específicos del proveedor / llamada de herramientas: ejecuta un `pnpm test:live` acotado -## Live: barrido de capacidades del nodo Android +## Live: barrido de capacidades de nodos Android - Prueba: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **cada comando anunciado actualmente** por un nodo Android conectado y comprobar el comportamiento del contrato del comando. +- Objetivo: invocar **cada comando anunciado actualmente** por un nodo Android conectado y afirmar el comportamiento del contrato de comandos. - Alcance: - - Configuración previa/manual (la suite no instala/ejecuta/empareja la app). + - Configuración manual/preacondicionada (la suite no instala/ejecuta/empareja la app). - Validación `node.invoke` del gateway comando por comando para el nodo Android seleccionado. - Configuración previa obligatoria: - - La app de Android ya está conectada y emparejada con el gateway. - - La app se mantiene en primer plano. + - App de Android ya conectada + emparejada con el gateway. + - App mantenida en primer plano. - Permisos/consentimiento de captura concedidos para las capacidades que esperas que pasen. -- Anulaciones opcionales de objetivo: +- Reemplazos opcionales del objetivo: - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detalles completos de la configuración de Android: [App de Android](/es/platforms/android) +- Detalles completos de la configuración de Android: [Android App](/es/platforms/android) ## Live: smoke de modelos (claves de perfil) -Las pruebas live se dividen en dos capas para poder aislar fallos: +Las pruebas live se dividen en dos capas para que podamos aislar fallos: - “Modelo directo” nos dice si el proveedor/modelo puede responder en absoluto con la clave dada. -- “Smoke del gateway” nos dice si funciona el pipeline completo de gateway+agente para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). +- “Smoke del gateway” nos dice si toda la canalización gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). ### Capa 1: finalización directa del modelo (sin gateway) - Prueba: `src/agents/models.profiles.live.test.ts` - Objetivo: - - Enumerar los modelos descubiertos - - Usar `getApiKeyForModel` para seleccionar los modelos para los que tienes credenciales - - Ejecutar una pequeña finalización por modelo (y regresiones específicas cuando sea necesario) + - Enumerar los modelos detectados + - Usar `getApiKeyForModel` para seleccionar modelos para los que tienes credenciales + - Ejecutar una pequeña finalización por modelo (y regresiones dirigidas cuando sea necesario) - Cómo habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) -- Establece `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` centrado en el smoke del gateway +- Establece `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario, se omite para mantener `pnpm test:live` centrado en el smoke del gateway - Cómo seleccionar modelos: - `OPENCLAW_LIVE_MODELS=modern` para ejecutar la allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` es un alias de la allowlist moderna @@ -213,75 +235,75 @@ Las pruebas live se dividen en dos capas para poder aislar fallos: - Los barridos modern/all usan de forma predeterminada un límite curado de alta señal; establece `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite más pequeño. - Cómo seleccionar proveedores: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por comas) -- De dónde provienen las claves: - - Por defecto: almacén de perfiles y respaldos de entorno - - Establece `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **solo el almacén de perfiles** +- De dónde salen las claves: + - De forma predeterminada: almacenamiento de perfiles y alternativas por entorno + - Establece `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **solo almacenamiento de perfiles** - Por qué existe: - - Separa “la API del proveedor está rota / la clave no es válida” de “el pipeline del agente del gateway está roto” - - Contiene regresiones pequeñas y aisladas (ejemplo: flujos de repetición de razonamiento y llamadas a herramientas de OpenAI Responses/Codex Responses) + - Separa “la API del proveedor está rota / la clave no es válida” de “la canalización del agente gateway está rota” + - Contiene regresiones pequeñas y aisladas (ejemplo: reproducción de razonamiento de OpenAI Responses/Codex Responses + flujos de llamada de herramientas) ### Capa 2: smoke del gateway + agente dev (lo que realmente hace "@openclaw") - Prueba: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - - Levantar un gateway en proceso - - Crear/parchear una sesión `agent:dev:*` (anulación del modelo por ejecución) - - Iterar los modelos con claves y comprobar: + - Iniciar un gateway en proceso + - Crear/parchear una sesión `agent:dev:*` (reemplazo de modelo por ejecución) + - Iterar modelos-con-claves y afirmar: - respuesta “significativa” (sin herramientas) - - que funciona una invocación real de herramienta (sondeo de lectura) - - sondeos opcionales de herramientas adicionales (sondeo exec+read) - - que las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) sigan funcionando -- Detalles del sondeo (para que puedas explicar fallos rápidamente): - - Sondeo `read`: la prueba escribe un archivo nonce en el espacio de trabajo y pide al agente que lo `read` y devuelva el nonce. - - Sondeo `exec+read`: la prueba pide al agente que escriba un nonce en un archivo temporal mediante `exec` y luego lo vuelva a `read`. - - Sondeo de imagen: la prueba adjunta un PNG generado (gato + código aleatorizado) y espera que el modelo devuelva `cat `. + - que funcione una invocación real de herramienta (sonda de lectura) + - sondas opcionales de herramientas adicionales (sonda exec+read) + - que las rutas de regresión de OpenAI (solo tool-call → seguimiento) sigan funcionando +- Detalles de las sondas (para que puedas explicar fallos rápidamente): + - Sonda `read`: la prueba escribe un archivo nonce en el espacio de trabajo y le pide al agente que lo `read` y devuelva el nonce. + - Sonda `exec+read`: la prueba le pide al agente que escriba un nonce en un archivo temporal con `exec` y luego lo lea de vuelta con `read`. + - Sonda de imagen: la prueba adjunta un PNG generado (gato + código aleatorizado) y espera que el modelo devuelva `cat `. - Referencia de implementación: `src/gateway/gateway-models.profiles.live.test.ts` y `src/gateway/live-image-probe.ts`. - Cómo habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) - Cómo seleccionar modelos: - Predeterminado: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` es un alias de la allowlist moderna - - O establece `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o lista separada por comas) para limitar - - Los barridos de gateway modern/all usan de forma predeterminada un límite curado de alta señal; establece `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite más pequeño. + - O establece `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separada por comas) para acotar + - Los barridos modernos/all del gateway usan de forma predeterminada un límite curado de alta señal; establece `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite más pequeño. - Cómo seleccionar proveedores (evitar “todo OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por comas) -- Los sondeos de herramientas + imagen siempre están activados en esta prueba live: - - sondeo `read` + sondeo `exec+read` (estrés de herramientas) - - el sondeo de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen +- Las sondas de herramientas + imagen siempre están activadas en esta prueba live: + - sonda `read` + sonda `exec+read` (estrés de herramientas) + - la sonda de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen - Flujo (alto nivel): - - La prueba genera un PNG pequeño con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) + - La prueba genera un PNG diminuto con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) - Lo envía mediante `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - El gateway analiza los adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - El agente integrado reenvía un mensaje de usuario multimodal al modelo - - Verificación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten pequeños errores) + - Afirmación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores) -Consejo: para ver lo que puedes probar en tu máquina (y los ids exactos `provider/model`), ejecuta: +Consejo: para ver qué puedes probar en tu máquina (y los id exactos `provider/model`), ejecuta: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke del backend de CLI (Claude, Codex, Gemini u otras CLI locales) +## Live: smoke del backend CLI (Claude, Codex, Gemini u otros CLI locales) - Prueba: `src/gateway/gateway-cli-backend.live.test.ts` -- Objetivo: validar el pipeline de Gateway + agente usando un backend de CLI local, sin tocar tu configuración predeterminada. -- Los valores predeterminados de smoke específicos del backend están junto a la definición `cli-backend.ts` de la extensión propietaria. +- Objetivo: validar la canalización Gateway + agente usando un backend CLI local, sin tocar tu configuración predeterminada. +- Los valores predeterminados de smoke específicos del backend viven con la definición `cli-backend.ts` de la extensión propietaria. - Habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Predeterminados: - Proveedor/modelo predeterminado: `claude-cli/claude-sonnet-4-6` - - El comportamiento de comando/args/imagen proviene de los metadatos del plugin propietario del backend de CLI. -- Anulaciones (opcionales): + - El comportamiento de comando/args/imagen proviene de los metadatos del plugin propietario del backend CLI. +- Reemplazos opcionales: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar un adjunto de imagen real (las rutas se inyectan en el prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivos de imagen como args de CLI en lugar de inyectarlas en el prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivos de imagen como args de CLI en lugar de inyección en el prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los args de imagen cuando `IMAGE_ARG` está establecido. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar un segundo turno y validar el flujo de reanudación. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para deshabilitar el sondeo predeterminado de continuidad en la misma sesión de Claude Sonnet -> Opus (establece `1` para forzarlo cuando el modelo seleccionado admita un objetivo de cambio). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para deshabilitar la sonda predeterminada de continuidad en la misma sesión Claude Sonnet -> Opus (establece `1` para forzarla cuando el modelo seleccionado admita un destino de cambio). Ejemplo: @@ -297,7 +319,7 @@ Receta de Docker: pnpm test:docker:live-cli-backend ``` -Recetas de Docker para un solo proveedor: +Recetas de Docker de proveedor único: ```bash pnpm test:docker:live-cli-backend:claude @@ -308,17 +330,17 @@ pnpm test:docker:live-cli-backend:gemini Notas: - El ejecutor de Docker está en `scripts/test-live-cli-backend-docker.sh`. -- Ejecuta el smoke live del backend de CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. -- Resuelve los metadatos del smoke de CLI desde la extensión propietaria y luego instala el paquete de CLI de Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo escribible en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). -- El smoke live del backend de CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada a la herramienta MCP `cron` verificada mediante la CLI del gateway. +- Ejecuta el smoke live del backend CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. +- Resuelve los metadatos del smoke CLI desde la extensión propietaria y luego instala el paquete CLI Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo escribible con caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). +- El smoke live del backend CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada a la herramienta MCP `cron` verificada a través del CLI del gateway. - El smoke predeterminado de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada siga recordando una nota anterior. -## Live: smoke de ACP bind (`/acp spawn ... --bind here`) +## Live: smoke de enlace ACP (`/acp spawn ... --bind here`) - Prueba: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar el flujo real de bind de conversación ACP con un agente ACP live: +- Objetivo: validar el flujo real de conversation-bind de ACP con un agente ACP live: - enviar `/acp spawn --bind here` - - enlazar una conversación sintética de canal de mensajes en su lugar + - enlazar en sitio una conversación sintética de canal de mensajes - enviar un seguimiento normal en esa misma conversación - verificar que el seguimiento llegue a la transcripción de la sesión ACP enlazada - Habilitar: @@ -327,17 +349,17 @@ Notas: - Predeterminados: - Agentes ACP en Docker: `claude,codex,gemini` - Agente ACP para `pnpm test:live ...` directo: `claude` - - Canal sintético: contexto de conversación tipo DM de Slack + - Canal sintético: contexto de conversación estilo DM de Slack - Backend ACP: `acpx` -- Anulaciones: +- Reemplazos: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Notas: - - Este carril usa la superficie `chat.send` del gateway con campos sintéticos de ruta de origen solo para administradores, para que las pruebas puedan adjuntar contexto de canal de mensajes sin simular una entrega externa. - - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro integrado de agentes del plugin `acpx` embebido para el agente de arnés ACP seleccionado. + - Este lane usa la superficie `chat.send` del gateway con campos sintéticos de ruta de origen solo para administradores para que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir una entrega externa. + - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro integrado de agentes del plugin `acpx` incrustado para el agente de arnés ACP seleccionado. Ejemplo: @@ -353,7 +375,7 @@ Receta de Docker: pnpm test:docker:live-acp-bind ``` -Recetas de Docker para un solo agente: +Recetas de Docker de agente único: ```bash pnpm test:docker:live-acp-bind:claude @@ -364,14 +386,14 @@ pnpm test:docker:live-acp-bind:gemini Notas de Docker: - El ejecutor de Docker está en `scripts/test-live-acp-bind-docker.sh`. -- De forma predeterminada, ejecuta el smoke de ACP bind contra todos los agentes CLI live compatibles en secuencia: `claude`, `codex` y luego `gemini`. -- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para limitar la matriz. -- Obtiene `~/.profile`, prepara el material de autenticación CLI correspondiente dentro del contenedor, instala `acpx` en un prefijo npm escribible y luego instala la CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. -- Dentro de Docker, el ejecutor establece `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que acpx mantenga disponibles para la CLI hija del arnés las variables de entorno del proveedor obtenidas desde el profile cargado. +- De forma predeterminada, ejecuta el smoke de enlace ACP contra todos los agentes CLI live compatibles en secuencia: `claude`, `codex` y luego `gemini`. +- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para acotar la matriz. +- Obtiene `~/.profile`, prepara en el contenedor el material de auth CLI correspondiente, instala `acpx` en un prefijo npm escribible y luego instala el CLI live solicitado (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. +- Dentro de Docker, el ejecutor establece `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que acpx mantenga disponibles para el CLI hijo del arnés las variables de entorno del proveedor obtenidas desde el perfil cargado. ### Recetas live recomendadas -Las allowlists explícitas y limitadas son las más rápidas y menos inestables: +Las allowlists acotadas y explícitas son las más rápidas y las menos inestables: - Un solo modelo, directo (sin gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -379,10 +401,10 @@ Las allowlists explícitas y limitadas son las más rápidas y menos inestables: - Un solo modelo, smoke del gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Llamadas a herramientas en varios proveedores: +- Llamada de herramientas en varios proveedores: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Foco en Google (clave de API de Gemini + Antigravity): +- Enfoque en Google (clave de API de Gemini + Antigravity): - Gemini (clave de API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` @@ -390,33 +412,33 @@ Notas: - `google/...` usa la API de Gemini (clave de API). - `google-antigravity/...` usa el puente OAuth de Antigravity (endpoint de agente estilo Cloud Code Assist). -- `google-gemini-cli/...` usa la CLI local de Gemini en tu máquina (autenticación independiente + particularidades de herramientas). +- `google-gemini-cli/...` usa el CLI local de Gemini en tu máquina (auth separada + peculiaridades propias de herramientas). - API de Gemini vs CLI de Gemini: - - API: OpenClaw llama a la API alojada de Gemini de Google mediante HTTP (clave de API / autenticación de perfil); esto es lo que la mayoría de los usuarios quieren decir con “Gemini”. - - CLI: OpenClaw ejecuta un binario `gemini` local; tiene su propia autenticación y puede comportarse de manera diferente (streaming/compatibilidad de herramientas/desfase de versión). + - API: OpenClaw llama a la API alojada de Gemini de Google por HTTP (clave de API / auth de perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”. + - CLI: OpenClaw ejecuta un binario local `gemini`; tiene su propia auth y puede comportarse de forma distinta (streaming/soporte de herramientas/desfase de versión). -## Live: matriz de modelos (qué cubrimos) +## Live: matriz de modelos (lo que cubrimos) No hay una “lista fija de modelos de CI” (live es opt-in), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves. -### Conjunto smoke moderno (llamadas a herramientas + imagen) +### Conjunto smoke moderno (llamada de herramientas + imagen) Esta es la ejecución de “modelos comunes” que esperamos mantener funcionando: -- OpenAI (no Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) +- OpenAI (no-Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (o `anthropic/claude-sonnet-4-6`) -- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos antiguos Gemini 2.x) +- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos Gemini 2.x más antiguos) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` y `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Ejecuta smoke del gateway con herramientas + imagen: +Ejecuta el smoke del gateway con herramientas + imagen: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Base: llamadas a herramientas (Read + Exec opcional) +### Línea base: llamada de herramientas (Read + Exec opcional) -Elige al menos uno por familia de proveedor: +Elige al menos uno por familia de proveedores: - OpenAI: `openai/gpt-5.4` (o `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (o `anthropic/claude-sonnet-4-6`) @@ -424,153 +446,153 @@ Elige al menos uno por familia de proveedor: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Cobertura adicional opcional (sería bueno tenerla): +Cobertura adicional opcional (conveniente tenerla): - xAI: `xai/grok-4` (o la última disponible) - Mistral: `mistral/`… (elige un modelo con capacidad de “tools” que tengas habilitado) - Cerebras: `cerebras/`… (si tienes acceso) -- LM Studio: `lmstudio/`… (local; las llamadas a herramientas dependen del modo de API) +- LM Studio: `lmstudio/`… (local; la llamada de herramientas depende del modo de API) -### Visión: envío de imagen (adjunto → mensaje multimodal) +### Vision: envío de imagen (adjunto → mensaje multimodal) -Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes de OpenAI con capacidad de visión, etc.) para ejercitar el sondeo de imagen. +Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes de Claude/Gemini/OpenAI con capacidad de visión, etc.) para ejercitar la sonda de imagen. ### Agregadores / gateways alternativos Si tienes claves habilitadas, también admitimos pruebas mediante: - OpenRouter: `openrouter/...` (cientos de modelos; usa `openclaw models scan` para encontrar candidatos con capacidad de herramientas+imagen) -- OpenCode: `opencode/...` para Zen y `opencode-go/...` para Go (autenticación mediante `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenCode: `opencode/...` para Zen y `opencode-go/...` para Go (auth mediante `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) Más proveedores que puedes incluir en la matriz live (si tienes credenciales/configuración): - Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Mediante `models.providers` (endpoints personalizados): `minimax` (cloud/API), además de cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) +- Mediante `models.providers` (endpoints personalizados): `minimax` (cloud/API), más cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) -Consejo: no intentes codificar de forma rígida “todos los modelos” en la documentación. La lista autoritativa es lo que devuelva `discoverModels(...)` en tu máquina + las claves disponibles. +Consejo: no intentes codificar “todos los modelos” en la documentación. La lista autorizada es lo que devuelva `discoverModels(...)` en tu máquina + las claves que estén disponibles. -## Credenciales (nunca las confirmes en el repositorio) +## Credenciales (nunca hacer commit) -Las pruebas live descubren credenciales de la misma manera que la CLI. Implicaciones prácticas: +Las pruebas live descubren credenciales de la misma forma que el CLI. Implicaciones prácticas: -- Si la CLI funciona, las pruebas live deberían encontrar las mismas claves. -- Si una prueba live dice “no creds”, depúrala igual que depurarías `openclaw models list` / selección de modelo. +- Si el CLI funciona, las pruebas live deberían encontrar las mismas claves. +- Si una prueba live dice “no creds”, depúralo igual que depurarías `openclaw models list` / selección de modelo. -- Perfiles de autenticación por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significa “profile keys” en las pruebas live) +- Perfiles de auth por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significa “profile keys” en las pruebas live) - Configuración: `~/.openclaw/openclaw.json` (o `OPENCLAW_CONFIG_PATH`) -- Directorio de estado heredado: `~/.openclaw/credentials/` (se copia al home live preparado cuando está presente, pero no es el almacén principal de claves de perfil) -- Las ejecuciones live locales copian la configuración activa, los archivos `auth-profiles.json` por agente, el `credentials/` heredado y los directorios de autenticación CLI externos compatibles a un home de prueba temporal de forma predeterminada; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan las anulaciones de ruta `agents.*.workspace` / `agentDir` para que los sondeos no toquen tu espacio de trabajo real del host. +- Directorio de estado heredado: `~/.openclaw/credentials/` (se copia al home live preparado cuando está presente, pero no es el almacenamiento principal de claves de perfil) +- Las ejecuciones live locales copian de forma predeterminada la configuración activa, los archivos `auth-profiles.json` por agente, el directorio heredado `credentials/` y los directorios de auth CLI externos compatibles a un home temporal de prueba; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan las anulaciones de ruta `agents.*.workspace` / `agentDir` para que las sondas no usen tu espacio de trabajo real del host. -Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores de Docker de abajo (pueden montar `~/.profile` en el contenedor). +Si quieres basarte en claves de entorno (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores de Docker de abajo (pueden montar `~/.profile` dentro del contenedor). -## Live de Deepgram (transcripción de audio) +## Deepgram live (transcripción de audio) - Prueba: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live del plan de coding de BytePlus +## BytePlus coding plan live - Prueba: `src/agents/byteplus.live.test.ts` - Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Anulación opcional del modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Reemplazo opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live de medios de workflow de ComfyUI +## ComfyUI workflow media live - Prueba: `extensions/comfy/comfy.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Alcance: - - Ejercita las rutas empaquetadas de comfy para imagen, video y `music_generate` + - Ejercita las rutas de imagen, video y `music_generate` del paquete comfy integrado - Omite cada capacidad salvo que `models.providers.comfy.` esté configurado - - Útil tras cambiar el envío de workflows de comfy, el polling, las descargas o el registro del plugin + - Útil después de cambiar el envío de flujos de trabajo comfy, el polling, las descargas o el registro del plugin -## Live de generación de imágenes +## Image generation live - Prueba: `src/image-generation/runtime.live.test.ts` - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Arnés: `pnpm test:live:media image` - Alcance: - Enumera cada plugin de proveedor de generación de imágenes registrado - - Carga las variables de entorno de proveedor faltantes desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto las claves de API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizable - - Ejecuta las variantes estándar de generación de imágenes a través de la capacidad compartida de runtime: + - Carga variables de entorno faltantes del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa de forma predeterminada claves de API live/de entorno antes que perfiles de auth almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable + - Ejecuta las variantes estándar de generación de imágenes mediante la capacidad compartida de runtime: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Proveedores empaquetados actuales cubiertos: +- Proveedores integrados cubiertos actualmente: - `openai` - `google` -- Limitación opcional: +- Acotación opcional: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación desde el almacén de perfiles e ignorar anulaciones solo de entorno +- Comportamiento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la auth del almacén de perfiles e ignorar las anulaciones solo de entorno -## Live de generación de música +## Music generation live - Prueba: `extensions/music-generation-providers.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media music` - Alcance: - - Ejercita la ruta compartida empaquetada del proveedor de generación de música + - Ejercita la ruta compartida integrada de proveedores de generación musical - Actualmente cubre Google y MiniMax - - Carga las variables de entorno de proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto las claves de API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizable + - Carga variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa de forma predeterminada claves de API live/de entorno antes que perfiles de auth almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable - Ejecuta ambos modos de runtime declarados cuando están disponibles: - `generate` con entrada solo de prompt - `edit` cuando el proveedor declara `capabilities.edit.enabled` - Cobertura actual del carril compartido: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: archivo live de Comfy independiente, no este barrido compartido -- Limitación opcional: + - `comfy`: archivo live de Comfy separado, no este barrido compartido +- Acotación opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación desde el almacén de perfiles e ignorar anulaciones solo de entorno +- Comportamiento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la auth del almacén de perfiles e ignorar las anulaciones solo de entorno -## Live de generación de video +## Video generation live - Prueba: `extensions/video-generation-providers.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media video` - Alcance: - - Ejercita la ruta compartida empaquetada del proveedor de generación de video - - Carga las variables de entorno de proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto las claves de API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell - - Omite proveedores sin autenticación/perfil/modelo utilizable + - Ejercita la ruta compartida integrada de proveedores de generación de video + - Carga variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa de forma predeterminada claves de API live/de entorno antes que perfiles de auth almacenados, para que claves de prueba obsoletas en `auth-profiles.json` no oculten credenciales reales del shell + - Omite proveedores sin auth/perfil/modelo utilizable - Ejecuta ambos modos de runtime declarados cuando están disponibles: - `generate` con entrada solo de prompt - - `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por búfer en el barrido compartido - - `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local respaldada por búfer en el barrido compartido - - Proveedores actualmente declarados pero omitidos de `imageToVideo` en el barrido compartido: - - `vydra` porque el `veo3` empaquetado es solo texto y el `kling` empaquetado requiere una URL de imagen remota - - Cobertura específica del proveedor Vydra: + - `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local basada en búfer en el barrido compartido + - `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local basada en búfer en el barrido compartido + - Proveedores `imageToVideo` declarados actualmente pero omitidos en el barrido compartido: + - `vydra` porque el `veo3` integrado es solo texto y el `kling` integrado requiere una URL de imagen remota + - Cobertura específica de proveedor para Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - ese archivo ejecuta `veo3` de texto a video más un carril `kling` que usa por defecto un fixture de URL de imagen remota + - ese archivo ejecuta `veo3` de texto a video más un carril `kling` que usa de forma predeterminada un fixture de URL de imagen remota - Cobertura live actual de `videoToVideo`: - - `runway` solo cuando el modelo seleccionado es `runway/gen4_aleph` - - Proveedores actualmente declarados pero omitidos de `videoToVideo` en el barrido compartido: + - solo `runway` cuando el modelo seleccionado es `runway/gen4_aleph` + - Proveedores `videoToVideo` declarados actualmente pero omitidos en el barrido compartido: - `alibaba`, `qwen`, `xai` porque esas rutas actualmente requieren URLs de referencia remotas `http(s)` / MP4 - - `google` porque el carril compartido actual de Gemini/Veo usa entrada local respaldada por búfer y esa ruta no se acepta en el barrido compartido - - `openai` porque el carril compartido actual carece de garantías de acceso específicas de organización para video inpaint/remix -- Limitación opcional: + - `google` porque el carril compartido actual Gemini/Veo usa entrada local basada en búfer y esa ruta no se acepta en el barrido compartido + - `openai` porque el carril compartido actual carece de garantías de acceso específicas de la organización para inpaint/remix de video +- Acotación opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación desde el almacén de perfiles e ignorar anulaciones solo de entorno +- Comportamiento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la auth del almacén de perfiles e ignorar las anulaciones solo de entorno ## Arnés live de medios - Comando: `pnpm test:live:media` - Propósito: - - Ejecuta las suites live compartidas de imagen, música y video mediante un único entrypoint nativo del repositorio - - Carga automáticamente variables de entorno de proveedor faltantes desde `~/.profile` - - Limita automáticamente cada suite a proveedores que actualmente tienen autenticación utilizable de forma predeterminada - - Reutiliza `scripts/test-live.mjs`, para que el comportamiento de heartbeat y modo silencioso siga siendo consistente + - Ejecuta las suites live compartidas de imagen, música y video a través de un único punto de entrada nativo del repositorio + - Carga automáticamente variables de entorno faltantes del proveedor desde `~/.profile` + - Acota automáticamente cada suite a los proveedores que actualmente tienen auth utilizable de forma predeterminada + - Reutiliza `scripts/test-live.mjs`, de modo que el comportamiento de heartbeat y modo silencioso siga siendo consistente - Ejemplos: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -581,120 +603,119 @@ Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.prof Estos ejecutores de Docker se dividen en dos grupos: -- Ejecutores live de modelos: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio local de configuración y el espacio de trabajo (y obteniendo `~/.profile` si está montado). Los entrypoints locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. -- Los ejecutores live de Docker usan por defecto un límite smoke más pequeño para que un barrido completo en Docker siga siendo práctico: +- Ejecutores live de modelos: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio local de configuración y espacio de trabajo (y obteniendo `~/.profile` si está montado). Los puntos de entrada locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. +- Los ejecutores Docker live usan de forma predeterminada un límite smoke más pequeño para que un barrido completo en Docker siga siendo práctico: `test:docker:live-models` usa por defecto `OPENCLAW_LIVE_MAX_MODELS=12`, y `test:docker:live-gateway` usa por defecto `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, - `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, y + `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` y `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Anula esas variables de entorno cuando - quieras explícitamente el escaneo exhaustivo más grande. -- `test:docker:all` construye una vez la imagen Docker live mediante `test:docker:live-build`, y luego la reutiliza para los dos carriles live de Docker. -- Ejecutores smoke de contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` levantan uno o más contenedores reales y verifican rutas de integración de mayor nivel. + quieras explícitamente el barrido exhaustivo más grande. +- `test:docker:all` compila una vez la imagen Docker live mediante `test:docker:live-build`, y luego la reutiliza para los dos lanes Docker live. +- Ejecutores smoke de contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` inician uno o más contenedores reales y verifican rutas de integración de nivel superior. -Los ejecutores Docker live de modelos también montan con bind solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está limitada), y luego los copian al home del contenedor antes de la ejecución para que OAuth de CLI externa pueda actualizar tokens sin mutar el almacén de autenticación del host: +Los ejecutores Docker live de modelos también montan mediante bind solo los homes de auth CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), y luego los copian al home del contenedor antes de la ejecución para que el OAuth de CLI externa pueda refrescar tokens sin modificar el almacén de auth del host: - Modelos directos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke de ACP bind: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) -- Smoke del backend de CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) +- Smoke de enlace ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Smoke del backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) - Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live de Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) -- Asistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Redes del gateway (dos contenedores, autenticación WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Puente de canal MCP (Gateway inicializado + puente stdio + smoke sin procesar de marcos de notificación de Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Asistente de onboarding (TTY, andamiaje completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) +- Redes del gateway (dos contenedores, auth WS + salud): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Puente de canal MCP (Gateway sembrado + puente stdio + smoke sin procesar de marcos de notificación Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) - Plugins (smoke de instalación + alias `/plugin` + semántica de reinicio del paquete Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -Los ejecutores Docker live de modelos también montan con bind la copia de trabajo actual en modo solo lectura y -la preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la -imagen de runtime ligera, al tiempo que sigue ejecutando Vitest contra tu código/configuración local exactos. -El paso de preparación omite cachés grandes solo locales y salidas de build de apps como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios de salida locales de app `.build` o -Gradle, para que las ejecuciones Docker live no pasen minutos copiando -artefactos específicos de la máquina. -También establecen `OPENCLAW_SKIP_CHANNELS=1` para que los sondeos live del gateway no inicien -workers reales de canales de Telegram/Discord/etc. dentro del contenedor. +Los ejecutores Docker live de modelos también montan mediante bind la extracción actual en modo de solo lectura y +la preparan en un directorio temporal de trabajo dentro del contenedor. Esto mantiene ligera la imagen de runtime +aunque sigue ejecutando Vitest contra tu código fuente/configuración local exactos. +El paso de preparación omite grandes cachés solo locales y salidas de compilación de la app como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios de salida Gradle o `.build` locales de la app para que las ejecuciones +live de Docker no pasen minutos copiando artefactos específicos de la máquina. +También establecen `OPENCLAW_SKIP_CHANNELS=1` para que las sondas live del gateway no inicien +workers reales de canales Telegram/Discord/etc. dentro del contenedor. `test:docker:live-models` sigue ejecutando `pnpm test:live`, así que pasa también -`OPENCLAW_LIVE_GATEWAY_*` cuando necesites limitar o excluir cobertura live -del gateway de ese carril Docker. +`OPENCLAW_LIVE_GATEWAY_*` cuando necesites acotar o excluir la cobertura +live del gateway de ese lane Docker. `test:docker:openwebui` es un smoke de compatibilidad de nivel superior: inicia un -contenedor de gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, -inicia un contenedor fijado de Open WebUI contra ese gateway, inicia sesión mediante +contenedor gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, +inicia un contenedor fijado de Open WebUI contra ese gateway, inicia sesión a través de Open WebUI, verifica que `/api/models` expone `openclaw/default`, y luego envía una -solicitud real de chat a través del proxy `/api/chat/completions` de Open WebUI. -La primera ejecución puede ser notablemente más lenta porque Docker podría necesitar descargar la -imagen de Open WebUI y Open WebUI podría necesitar completar su propia configuración de arranque en frío. -Este carril espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` -(`~/.profile` de forma predeterminada) es la forma principal de proporcionarla en ejecuciones con Docker. +solicitud de chat real mediante el proxy `/api/chat/completions` de Open WebUI. +La primera ejecución puede ser notablemente más lenta porque Docker puede necesitar descargar la +imagen de Open WebUI y Open WebUI puede necesitar completar su propia configuración de arranque en frío. +Este lane espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` +(`~/.profile` de forma predeterminada) es la forma principal de proporcionarla en ejecuciones dockerizadas. Las ejecuciones exitosas imprimen una pequeña carga JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` es intencionalmente determinista y no necesita una -cuenta real de Telegram, Discord o iMessage. Inicia un contenedor de Gateway -inicializado, arranca un segundo contenedor que ejecuta `openclaw mcp serve`, luego -verifica el descubrimiento de conversaciones enrutadas, lecturas de transcripciones, metadatos de adjuntos, -comportamiento de cola de eventos live, routing de envíos salientes y notificaciones de estilo Claude de canal + -permisos sobre el puente MCP stdio real. La comprobación de notificaciones -inspecciona directamente los marcos MCP stdio sin procesar, de modo que el smoke valida lo que el -puente realmente emite, no solo lo que un SDK cliente específico exponga por casualidad. +cuenta real de Telegram, Discord o iMessage. Inicia un contenedor Gateway +sembrado, inicia un segundo contenedor que ejecuta `openclaw mcp serve`, y luego +verifica el descubrimiento de conversaciones enrutadas, lecturas de transcripción, metadatos de adjuntos, +comportamiento de cola de eventos live, enrutamiento de envíos salientes y notificaciones +de canal + permisos al estilo Claude sobre el puente MCP stdio real. La comprobación de notificaciones +inspecciona directamente los marcos MCP stdio sin procesar, de modo que el smoke valida lo que +el puente realmente emite, no solo lo que una SDK cliente específica casualmente expone. Smoke manual de hilo ACP en lenguaje natural (no CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantén este script para flujos de trabajo de regresión/depuración. Puede ser necesario de nuevo para validar el routing de hilos ACP, así que no lo elimines. +- Conserva este script para flujos de regresión/depuración. Puede volver a ser necesario para validar el enrutamiento de hilos ACP, así que no lo elimines. Variables de entorno útiles: - `OPENCLAW_CONFIG_DIR=...` (predeterminado: `~/.openclaw`) montado en `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (predeterminado: `~/.openclaw/workspace`) montado en `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (predeterminado: `~/.profile`) montado en `/home/node/.profile` y obtenido antes de ejecutar las pruebas -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predeterminado: `~/.cache/openclaw/docker-cli-tools`) montado en `/home/node/.npm-global` para instalaciones CLI en caché dentro de Docker -- Los directorios/archivos de autenticación CLI externa bajo `$HOME` se montan en modo solo lectura bajo `/host-auth...`, y luego se copian a `/home/node/...` antes de que comiencen las pruebas +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predeterminado: `~/.cache/openclaw/docker-cli-tools`) montado en `/home/node/.npm-global` para instalaciones de CLI en caché dentro de Docker +- Los directorios/archivos de auth CLI externa bajo `$HOME` se montan en solo lectura bajo `/host-auth...`, y luego se copian a `/home/node/...` antes de que empiecen las pruebas - Directorios predeterminados: `.minimax` - Archivos predeterminados: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Las ejecuciones limitadas por proveedor montan solo los directorios/archivos necesarios inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Anúlalo manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, o una lista separada por comas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para limitar la ejecución + - Las ejecuciones de proveedor acotado montan solo los directorios/archivos necesarios inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Anula manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o una lista separada por comas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para acotar la ejecución - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar proveedores dentro del contenedor -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para asegurar que las credenciales provengan del almacén de perfiles (no del entorno) +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantizar que las credenciales provengan del almacén de perfiles (no del entorno) - `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por el gateway para el smoke de Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` para anular el prompt de verificación con nonce usado por el smoke de Open WebUI -- `OPENWEBUI_IMAGE=...` para anular la etiqueta fijada de la imagen de Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` para anular el prompt de comprobación nonce usado por el smoke de Open WebUI +- `OPENWEBUI_IMAGE=...` para anular la etiqueta fijada de imagen de Open WebUI -## Verificación básica de documentación +## Cordura de la documentación -Ejecuta las comprobaciones de docs después de editar documentación: `pnpm check:docs`. -Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobar encabezados dentro de la página: `pnpm docs:check-links:anchors`. +Ejecuta las comprobaciones de documentación después de editar documentación: `pnpm check:docs`. +Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobaciones de encabezados dentro de la página: `pnpm docs:check-links:anchors`. ## Regresión offline (segura para CI) -Estas son regresiones de “pipeline real” sin proveedores reales: +Estas son regresiones de “canalización real” sin proveedores reales: -- Llamadas a herramientas del gateway (OpenAI simulado, gateway real + bucle de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Asistente del gateway (WS `wizard.start`/`wizard.next`, escritura de config + auth obligatoria): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Llamada de herramientas del gateway (OpenAI simulado, gateway real + bucle de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Asistente del gateway (WS `wizard.start`/`wizard.next`, escribe configuración + auth forzada): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evals de confiabilidad del agente (Skills) +## Evaluaciones de confiabilidad del agente (Skills) -Ya tenemos algunas pruebas seguras para CI que se comportan como “evals de confiabilidad del agente”: +Ya tenemos algunas pruebas seguras para CI que se comportan como “evaluaciones de confiabilidad del agente”: -- Llamadas a herramientas simuladas a través del gateway real + bucle de agente (`src/gateway/gateway.test.ts`). -- Flujos end-to-end del asistente que validan el cableado de sesión y los efectos de configuración (`src/gateway/gateway.test.ts`). +- Llamada de herramientas simulada a través del gateway real + bucle de agente (`src/gateway/gateway.test.ts`). +- Flujos end-to-end del asistente que validan el cableado de la sesión y los efectos de configuración (`src/gateway/gateway.test.ts`). -Lo que aún falta para Skills (consulta [Skills](/es/tools/skills)): +Lo que aún falta para Skills (ver [Skills](/es/tools/skills)): -- **Toma de decisiones:** cuando las Skills se enumeran en el prompt, ¿el agente elige la Skill correcta (o evita las irrelevantes)? +- **Toma de decisiones:** cuando las Skills aparecen en el prompt, ¿el agente elige la Skill correcta (o evita las irrelevantes)? - **Cumplimiento:** ¿el agente lee `SKILL.md` antes de usarla y sigue los pasos/args requeridos? -- **Contratos de flujo de trabajo:** escenarios de varios turnos que verifiquen orden de herramientas, arrastre del historial de la sesión y límites del sandbox. +- **Contratos de flujo de trabajo:** escenarios de varios turnos que afirman el orden de herramientas, el arrastre del historial de sesión y los límites del sandbox. -Las evals futuras deberían seguir siendo deterministas primero: +Las evaluaciones futuras deberían seguir siendo deterministas primero: -- Un ejecutor de escenarios que use proveedores simulados para comprobar llamadas a herramientas + orden, lecturas de archivos de Skills y cableado de sesiones. -- Un pequeño conjunto de escenarios centrados en Skills (usar vs evitar, gating, inyección de prompts). -- Evals live opcionales (opt-in, controladas por env) solo después de que la suite segura para CI esté implementada. +- Un ejecutor de escenarios que use proveedores simulados para afirmar llamadas de herramientas + orden, lecturas de archivos de Skill y cableado de sesión. +- Una pequeña suite de escenarios centrados en Skills (usar vs evitar, gating, inyección de prompt). +- Evaluaciones live opcionales (opt-in, controladas por entorno) solo después de que la suite segura para CI ya esté implementada. ## Pruebas de contrato (forma de plugin y canal) Las pruebas de contrato verifican que cada plugin y canal registrado se ajuste a su -contrato de interfaz. Iteran sobre todos los plugins descubiertos y ejecutan un conjunto de -comprobaciones de forma y comportamiento. El carril unitario predeterminado de `pnpm test` +contrato de interfaz. Iteran sobre todos los plugins detectados y ejecutan una suite de +afirmaciones de forma y comportamiento. El lane unitario predeterminado `pnpm test` omite intencionalmente estos archivos compartidos de seams y smoke; ejecuta los comandos de contrato explícitamente cuando toques superficies compartidas de canal o proveedor. @@ -711,28 +732,28 @@ Ubicados en `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Forma básica del plugin (id, nombre, capacidades) - **setup** - Contrato del asistente de configuración - **session-binding** - Comportamiento de enlace de sesión -- **outbound-payload** - Estructura del payload del mensaje +- **outbound-payload** - Estructura de carga de mensaje - **inbound** - Manejo de mensajes entrantes -- **actions** - Manejadores de acciones del canal -- **threading** - Manejo de id de hilo -- **directory** - API de directorio/listado -- **group-policy** - Aplicación de políticas de grupo +- **actions** - Manejadores de acciones de canal +- **threading** - Manejo de ID de hilo +- **directory** - API de directorio/lista +- **group-policy** - Aplicación de la política de grupo ### Contratos de estado del proveedor Ubicados en `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondeos de estado del canal +- **status** - Sondas de estado del canal - **registry** - Forma del registro de plugins ### Contratos de proveedor Ubicados en `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato del flujo de autenticación -- **auth-choice** - Elección/selección de autenticación -- **catalog** - API del catálogo de modelos -- **discovery** - Descubrimiento de plugins +- **auth** - Contrato de flujo de auth +- **auth-choice** - Elección/selección de auth +- **catalog** - API de catálogo de modelos +- **discovery** - Detección de plugins - **loader** - Carga de plugins - **runtime** - Runtime del proveedor - **shape** - Forma/interfaz del plugin @@ -742,7 +763,7 @@ Ubicados en `src/plugins/contracts/*.contract.test.ts`: - Después de cambiar exportaciones o subrutas de plugin-sdk - Después de agregar o modificar un plugin de canal o proveedor -- Después de refactorizar el registro o el descubrimiento de plugins +- Después de refactorizar el registro o la detección de plugins Las pruebas de contrato se ejecutan en CI y no requieren claves de API reales. @@ -750,11 +771,11 @@ Las pruebas de contrato se ejecutan en CI y no requieren claves de API reales. Cuando corrijas un problema de proveedor/modelo descubierto en live: -- Agrega una regresión segura para CI si es posible (proveedor simulado/stub, o captura la transformación exacta de la forma de la solicitud) -- Si es inherentemente solo live (límites de tasa, políticas de autenticación), mantén la prueba live limitada y opt-in mediante variables de entorno -- Prefiere apuntar a la capa más pequeña que detecte el error: - - error de conversión/repetición de solicitud del proveedor → prueba directa de modelos - - error del pipeline del gateway de sesión/historial/herramientas → smoke live del gateway o prueba segura para CI del gateway simulado -- Barandilla de recorrido SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo muestreado por clase de SecretRef desde los metadatos del registro (`listSecretTargetRegistryEntries()`), y luego comprueba que se rechacen los id de exec de segmentos de recorrido. - - Si agregas una nueva familia de objetivos SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente ante ids de objetivo sin clasificar para que las nuevas clases no puedan omitirse silenciosamente. +- Agrega una regresión segura para CI si es posible (proveedor simulado/stub, o captura de la transformación exacta de la forma de la solicitud) +- Si es inherentemente solo live (límites de tasa, políticas de auth), mantén la prueba live acotada y opt-in mediante variables de entorno +- Prefiere dirigirte a la capa más pequeña que detecte el error: + - error de conversión/reproducción de solicitud del proveedor → prueba de modelos directos + - error de la canalización de sesión/historial/herramientas del gateway → smoke live del gateway o prueba simulada del gateway segura para CI +- Barandilla de recorrido de SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo de muestra por clase SecretRef a partir de los metadatos del registro (`listSecretTargetRegistryEntries()`), y luego afirma que se rechazan los id exec de segmento de recorrido. + - Si agregas una nueva familia de objetivos SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente con id de objetivo no clasificados para que las clases nuevas no puedan omitirse en silencio. diff --git a/docs/es/reference/memory-config.md b/docs/es/reference/memory-config.md index e4313d33e..9511a6544 100644 --- a/docs/es/reference/memory-config.md +++ b/docs/es/reference/memory-config.md @@ -1,83 +1,94 @@ --- read_when: - - Quieres configurar proveedores de memory search o modelos de embeddings - - Quieres configurar el backend QMD - - Quieres ajustar la búsqueda híbrida, MMR o el decaimiento temporal - - Quieres habilitar la indexación de memoria multimodal -summary: Todas las opciones de configuración para memory search, proveedores de embeddings, QMD, búsqueda híbrida e indexación multimodal + - Desea configurar proveedores de búsqueda de memoria o modelos de embeddings + - Desea configurar el backend de QMD + - Desea ajustar la búsqueda híbrida, MMR o el decaimiento temporal + - Desea habilitar la indexación de memoria multimodal +summary: Todos los parámetros de configuración para la búsqueda de memoria, los proveedores de embeddings, QMD, la búsqueda híbrida y la indexación multimodal title: Referencia de configuración de memoria x-i18n: - generated_at: "2026-04-06T03:11:55Z" + generated_at: "2026-04-10T05:12:12Z" model: gpt-5.4 provider: openai - source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd + source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb source_path: reference/memory-config.md workflow: 15 --- # Referencia de configuración de memoria -Esta página enumera todas las opciones de configuración para memory search de OpenClaw. Para -resúmenes conceptuales, consulta: +Esta página enumera todos los parámetros de configuración para la búsqueda de memoria de OpenClaw. Para obtener vistas conceptuales generales, consulte: -- [Resumen de memoria](/es/concepts/memory) -- cómo funciona la memoria -- [Motor integrado](/es/concepts/memory-builtin) -- backend predeterminado de SQLite +- [Descripción general de la memoria](/es/concepts/memory) -- cómo funciona la memoria +- [Motor integrado](/es/concepts/memory-builtin) -- backend SQLite predeterminado - [Motor QMD](/es/concepts/memory-qmd) -- sidecar local-first -- [Memory Search](/es/concepts/memory-search) -- pipeline de búsqueda y ajuste +- [Búsqueda de memoria](/es/concepts/memory-search) -- canalización de búsqueda y ajuste +- [Memoria activa](/es/concepts/active-memory) -- habilitar el subagente de memoria para sesiones interactivas -Toda la configuración de memory search se encuentra en `agents.defaults.memorySearch` en -`openclaw.json`, salvo que se indique lo contrario. +Todos los ajustes de búsqueda de memoria se encuentran en `agents.defaults.memorySearch` en +`openclaw.json`, a menos que se indique lo contrario. + +Si busca el interruptor de función de **memoria activa** y la configuración del subagente, +se encuentran en `plugins.entries.active-memory` en lugar de `memorySearch`. + +La memoria activa usa un modelo de dos puertas: + +1. el plugin debe estar habilitado y apuntar al id del agente actual +2. la solicitud debe ser una sesión de chat persistente e interactiva elegible + +Consulte [Memoria activa](/es/concepts/active-memory) para ver el modelo de activación, +la configuración propiedad del plugin, la persistencia de transcripciones y el patrón de implementación segura. --- ## Selección de proveedor -| Clave | Tipo | Predeterminado | Descripción | -| ---------- | --------- | ---------------- | -------------------------------------------------------------------------------------------- | -| `provider` | `string` | detección automática | ID del adaptador de embeddings: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` | +| Key | Type | Default | Description | +| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------- | +| `provider` | `string` | detectado automáticamente | ID del adaptador de embeddings: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` | | `model` | `string` | predeterminado del proveedor | Nombre del modelo de embeddings | -| `fallback` | `string` | `"none"` | ID del adaptador de fallback cuando falla el principal | -| `enabled` | `boolean` | `true` | Habilitar o deshabilitar memory search | +| `fallback` | `string` | `"none"` | ID del adaptador de respaldo cuando falla el principal | +| `enabled` | `boolean` | `true` | Habilitar o deshabilitar la búsqueda de memoria | ### Orden de detección automática -Cuando `provider` no está establecido, OpenClaw selecciona el primero disponible: +Cuando `provider` no está configurado, OpenClaw selecciona el primero disponible: 1. `local` -- si `memorySearch.local.modelPath` está configurado y el archivo existe. 2. `openai` -- si se puede resolver una clave de OpenAI. 3. `gemini` -- si se puede resolver una clave de Gemini. 4. `voyage` -- si se puede resolver una clave de Voyage. 5. `mistral` -- si se puede resolver una clave de Mistral. -6. `bedrock` -- si se resuelve la cadena de credenciales del AWS SDK (rol de instancia, claves de acceso, perfil, SSO, identidad web o configuración compartida). +6. `bedrock` -- si la cadena de credenciales del SDK de AWS se resuelve (rol de instancia, claves de acceso, perfil, SSO, identidad web o configuración compartida). -`ollama` es compatible, pero no se detecta automáticamente (debes establecerlo explícitamente). +`ollama` es compatible, pero no se detecta automáticamente (configúrelo explícitamente). ### Resolución de claves de API -Los embeddings remotos requieren una clave de API. Bedrock usa en su lugar la cadena de credenciales -predeterminada del AWS SDK (roles de instancia, SSO, claves de acceso). +Los embeddings remotos requieren una clave de API. Bedrock usa la cadena de credenciales predeterminada del SDK de AWS +en su lugar (roles de instancia, SSO, claves de acceso). -| Proveedor | Variable de entorno | Clave de configuración | +| Provider | Env var | Config key | | -------- | ------------------------------ | --------------------------------- | | OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | | Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | | Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | | Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Bedrock | cadena de credenciales de AWS | No necesita clave de API | +| Bedrock | cadena de credenciales de AWS | No se necesita clave de API | | Ollama | `OLLAMA_API_KEY` (marcador de posición) | -- | -Codex OAuth cubre solo chat/completions y no satisface -las solicitudes de embeddings. +Codex OAuth solo cubre chat/completions y no satisface las solicitudes +de embeddings. --- ## Configuración de endpoint remoto -Para endpoints personalizados compatibles con OpenAI o para sobrescribir valores predeterminados del proveedor: +Para endpoints personalizados compatibles con OpenAI o para sobrescribir los valores predeterminados del proveedor: -| Clave | Tipo | Descripción | +| Key | Type | Description | | ---------------- | -------- | -------------------------------------------------- | -| `remote.baseUrl` | `string` | URL base personalizada de la API | +| `remote.baseUrl` | `string` | URL base de API personalizada | | `remote.apiKey` | `string` | Sobrescribir la clave de API | | `remote.headers` | `object` | Encabezados HTTP adicionales (fusionados con los valores predeterminados del proveedor) | @@ -102,21 +113,21 @@ Para endpoints personalizados compatibles con OpenAI o para sobrescribir valores ## Configuración específica de Gemini -| Clave | Tipo | Predeterminado | Descripción | +| Key | Type | Default | Description | | ---------------------- | -------- | ---------------------- | ------------------------------------------ | -| `model` | `string` | `gemini-embedding-001` | También admite `gemini-embedding-2-preview` | +| `model` | `string` | `gemini-embedding-001` | También es compatible con `gemini-embedding-2-preview` | | `outputDimensionality` | `number` | `3072` | Para Embedding 2: 768, 1536 o 3072 | -Cambiar el modelo o `outputDimensionality` activa automáticamente una reindexación completa. +Cambiar el modelo o `outputDimensionality` desencadena una reindexación completa automática. --- ## Configuración de embeddings de Bedrock -Bedrock usa la cadena de credenciales predeterminada del AWS SDK; no se necesitan claves de API. -Si OpenClaw se ejecuta en EC2 con un rol de instancia con Bedrock habilitado, solo establece el +Bedrock usa la cadena de credenciales predeterminada del SDK de AWS -- no se necesitan claves de API. +Si OpenClaw se ejecuta en EC2 con un rol de instancia habilitado para Bedrock, solo configure el proveedor y el modelo: ```json5 @@ -132,17 +143,17 @@ proveedor y el modelo: } ``` -| Clave | Tipo | Predeterminado | Descripción | +| Key | Type | Default | Description | | ---------------------- | -------- | ------------------------------ | ------------------------------- | | `model` | `string` | `amazon.titan-embed-text-v2:0` | Cualquier ID de modelo de embeddings de Bedrock | | `outputDimensionality` | `number` | predeterminado del modelo | Para Titan V2: 256, 512 o 1024 | ### Modelos compatibles -Se admiten los siguientes modelos (con detección de familia y valores predeterminados +Los siguientes modelos son compatibles (con detección de familia y valores predeterminados de dimensiones): -| ID de modelo | Proveedor | Dimensiones predeterminadas | Dimensiones configurables | +| Model ID | Provider | Default Dims | Configurable Dims | | ------------------------------------------ | ---------- | ------------ | -------------------- | | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | @@ -160,16 +171,16 @@ la configuración del modelo base. ### Autenticación -La autenticación de Bedrock usa el orden estándar de resolución de credenciales del AWS SDK: +La autenticación de Bedrock usa el orden estándar de resolución de credenciales del SDK de AWS: 1. Variables de entorno (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) -2. Caché de tokens SSO +2. Caché de tokens de SSO 3. Credenciales de token de identidad web 4. Archivos compartidos de credenciales y configuración 5. Credenciales de metadatos de ECS o EC2 -La región se resuelve a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, el -`baseUrl` del proveedor `amazon-bedrock`, o usa por defecto `us-east-1`. +La región se resuelve a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, la +`baseUrl` del proveedor `amazon-bedrock`, o usa `us-east-1` de forma predeterminada. ### Permisos de IAM @@ -183,7 +194,7 @@ El rol o usuario de IAM necesita: } ``` -Para aplicar el principio de privilegio mínimo, limita `InvokeModel` al modelo específico: +Para aplicar el principio de privilegio mínimo, limite `InvokeModel` al modelo específico: ``` arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 @@ -193,12 +204,12 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 ## Configuración de embeddings locales -| Clave | Tipo | Predeterminado | Descripción | +| Key | Type | Default | Description | | --------------------- | -------- | ---------------------- | ------------------------------- | | `local.modelPath` | `string` | descargado automáticamente | Ruta al archivo del modelo GGUF | -| `local.modelCacheDir` | `string` | predeterminado de node-llama-cpp | Directorio de caché para modelos descargados | +| `local.modelCacheDir` | `string` | valor predeterminado de node-llama-cpp | Directorio de caché para los modelos descargados | -Modelo predeterminado: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, descarga automática). +Modelo predeterminado: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, se descarga automáticamente). Requiere compilación nativa: `pnpm approve-builds` y luego `pnpm rebuild node-llama-cpp`. --- @@ -207,28 +218,28 @@ Requiere compilación nativa: `pnpm approve-builds` y luego `pnpm rebuild node-l Todo bajo `memorySearch.query.hybrid`: -| Clave | Tipo | Predeterminado | Descripción | +| Key | Type | Default | Description | | --------------------- | --------- | ------- | ---------------------------------- | -| `enabled` | `boolean` | `true` | Habilitar búsqueda híbrida BM25 + vectorial | -| `vectorWeight` | `number` | `0.7` | Peso para puntuaciones vectoriales (0-1) | -| `textWeight` | `number` | `0.3` | Peso para puntuaciones BM25 (0-1) | +| `enabled` | `boolean` | `true` | Habilitar la búsqueda híbrida BM25 + vectorial | +| `vectorWeight` | `number` | `0.7` | Peso para las puntuaciones vectoriales (0-1) | +| `textWeight` | `number` | `0.3` | Peso para las puntuaciones BM25 (0-1) | | `candidateMultiplier` | `number` | `4` | Multiplicador del tamaño del conjunto de candidatos | ### MMR (diversidad) -| Clave | Tipo | Predeterminado | Descripción | +| Key | Type | Default | Description | | ------------- | --------- | ------- | ------------------------------------ | -| `mmr.enabled` | `boolean` | `false` | Habilitar reclasificación MMR | +| `mmr.enabled` | `boolean` | `false` | Habilitar la reclasificación MMR | | `mmr.lambda` | `number` | `0.7` | 0 = máxima diversidad, 1 = máxima relevancia | ### Decaimiento temporal (recencia) -| Clave | Tipo | Predeterminado | Descripción | +| Key | Type | Default | Description | | ---------------------------- | --------- | ------- | ------------------------- | -| `temporalDecay.enabled` | `boolean` | `false` | Habilitar impulso de recencia | +| `temporalDecay.enabled` | `boolean` | `false` | Habilitar el impulso por recencia | | `temporalDecay.halfLifeDays` | `number` | `30` | La puntuación se reduce a la mitad cada N días | -Los archivos permanentes (`MEMORY.md`, archivos no fechados en `memory/`) nunca se degradan. +Los archivos perennes (`MEMORY.md`, archivos sin fecha en `memory/`) nunca se ven afectados por el decaimiento. ### Ejemplo completo @@ -255,7 +266,7 @@ Los archivos permanentes (`MEMORY.md`, archivos no fechados en `memory/`) nunca ## Rutas de memoria adicionales -| Clave | Tipo | Descripción | +| Key | Type | Description | | ------------ | ---------- | ---------------------------------------- | | `extraPaths` | `string[]` | Directorios o archivos adicionales para indexar | @@ -271,15 +282,15 @@ Los archivos permanentes (`MEMORY.md`, archivos no fechados en `memory/`) nunca } ``` -Las rutas pueden ser absolutas o relativas al workspace. Los directorios se escanean +Las rutas pueden ser absolutas o relativas al workspace. Los directorios se exploran de forma recursiva en busca de archivos `.md`. El manejo de enlaces simbólicos depende del backend activo: -el motor integrado ignora los enlaces simbólicos, mientras que QMD sigue el comportamiento del escáner -subyacente de QMD. +el motor integrado ignora los enlaces simbólicos, mientras que QMD sigue el comportamiento del +escáner QMD subyacente. -Para la búsqueda de transcripciones entre agentes con ámbito de agente, usa +Para la búsqueda de transcripciones entre agentes con alcance por agente, use `agents.list[].memorySearch.qmd.extraCollections` en lugar de `memory.qmd.paths`. -Esas colecciones extra siguen la misma forma `{ path, name, pattern? }`, pero -se fusionan por agente y pueden conservar nombres compartidos explícitos cuando la ruta +Esas colecciones adicionales siguen la misma forma `{ path, name, pattern? }`, pero +se combinan por agente y pueden conservar nombres compartidos explícitos cuando la ruta apunta fuera del workspace actual. Si la misma ruta resuelta aparece tanto en `memory.qmd.paths` como en `memorySearch.qmd.extraCollections`, QMD conserva la primera entrada y omite el @@ -289,15 +300,15 @@ duplicado. ## Memoria multimodal (Gemini) -Indexa imágenes y audio junto con Markdown usando Gemini Embedding 2: +Indexe imágenes y audio junto con Markdown usando Gemini Embedding 2: -| Clave | Tipo | Predeterminado | Descripción | +| Key | Type | Default | Description | | ------------------------- | ---------- | ---------- | -------------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | Habilitar indexación multimodal | +| `multimodal.enabled` | `boolean` | `false` | Habilitar la indexación multimodal | | `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` o `["all"]` | | `multimodal.maxFileBytes` | `number` | `10000000` | Tamaño máximo de archivo para indexación | -Solo se aplica a los archivos en `extraPaths`. Las raíces de memoria predeterminadas siguen siendo solo Markdown. +Solo se aplica a los archivos en `extraPaths`. Las raíces de memoria predeterminadas siguen siendo solo de Markdown. Requiere `gemini-embedding-2-preview`. `fallback` debe ser `"none"`. Formatos compatibles: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` @@ -307,117 +318,117 @@ Formatos compatibles: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` ## Caché de embeddings -| Clave | Tipo | Predeterminado | Descripción | -| ------------------ | --------- | ------- | -------------------------------- | -| `cache.enabled` | `boolean` | `false` | Almacenar en caché embeddings de fragmentos en SQLite | -| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings en caché | +| Clave | Tipo | Predeterminado | Descripción | +| ------------------ | --------- | -------------- | -------------------------------- | +| `cache.enabled` | `boolean` | `false` | Almacenar en caché embeddings de fragmentos en SQLite | +| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings en caché | -Evita volver a generar embeddings de texto sin cambios durante la reindexación o actualizaciones de transcripciones. +Evita volver a generar embeddings para texto sin cambios durante la reindexación o las actualizaciones de transcripciones. --- ## Indexación por lotes -| Clave | Tipo | Predeterminado | Descripción | -| ----------------------------- | --------- | ------- | -------------------------- | -| `remote.batch.enabled` | `boolean` | `false` | Habilitar API de embeddings por lotes | -| `remote.batch.concurrency` | `number` | `2` | Trabajos por lotes en paralelo | -| `remote.batch.wait` | `boolean` | `true` | Esperar a que finalice el lote | -| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de sondeo | -| `remote.batch.timeoutMinutes` | `number` | -- | Tiempo de espera del lote | +| Clave | Tipo | Predeterminado | Descripción | +| ----------------------------- | --------- | -------------- | -------------------------- | +| `remote.batch.enabled` | `boolean` | `false` | Habilitar la API de embeddings por lotes | +| `remote.batch.concurrency` | `number` | `2` | Trabajos por lotes en paralelo | +| `remote.batch.wait` | `boolean` | `true` | Esperar a que termine el lote | +| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de sondeo | +| `remote.batch.timeoutMinutes` | `number` | -- | Tiempo de espera del lote | -Disponible para `openai`, `gemini` y `voyage`. Los lotes de OpenAI suelen ser -los más rápidos y baratos para rellenos grandes. +Disponible para `openai`, `gemini` y `voyage`. El procesamiento por lotes de OpenAI suele ser +el más rápido y económico para grandes backfills. --- ## Búsqueda de memoria de sesión (experimental) -Indexa transcripciones de sesión y muéstralas a través de `memory_search`: +Indexe transcripciones de sesión y muéstrelas a través de `memory_search`: -| Clave | Tipo | Predeterminado | Descripción | -| ----------------------------- | ---------- | ------------ | --------------------------------------- | -| `experimental.sessionMemory` | `boolean` | `false` | Habilitar indexación de sesiones | -| `sources` | `string[]` | `["memory"]` | Añade `"sessions"` para incluir transcripciones | -| `sync.sessions.deltaBytes` | `number` | `100000` | Umbral de bytes para reindexación | -| `sync.sessions.deltaMessages` | `number` | `50` | Umbral de mensajes para reindexación | +| Clave | Tipo | Predeterminado | Descripción | +| ----------------------------- | ---------- | -------------- | --------------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | Habilitar la indexación de sesiones | +| `sources` | `string[]` | `["memory"]` | Agregue `"sessions"` para incluir transcripciones | +| `sync.sessions.deltaBytes` | `number` | `100000` | Umbral de bytes para reindexar | +| `sync.sessions.deltaMessages` | `number` | `50` | Umbral de mensajes para reindexar | -La indexación de sesiones es optativa y se ejecuta de forma asíncrona. Los resultados pueden estar -ligeramente desactualizados. Los registros de sesión viven en disco, así que trata el acceso al sistema de archivos como el -límite de confianza. +La indexación de sesiones es opcional y se ejecuta de forma asíncrona. Los resultados pueden quedar +ligeramente desactualizados. Los registros de sesión se almacenan en disco, así que trate el acceso al sistema de archivos +como el límite de confianza. --- ## Aceleración vectorial de SQLite (sqlite-vec) -| Clave | Tipo | Predeterminado | Descripción | -| ---------------------------- | --------- | ------- | --------------------------------- | -| `store.vector.enabled` | `boolean` | `true` | Usar sqlite-vec para consultas vectoriales | -| `store.vector.extensionPath` | `string` | empaquetado | Sobrescribir la ruta de sqlite-vec | +| Clave | Tipo | Predeterminado | Descripción | +| ---------------------------- | --------- | -------------- | --------------------------------- | +| `store.vector.enabled` | `boolean` | `true` | Usar sqlite-vec para consultas vectoriales | +| `store.vector.extensionPath` | `string` | integrado | Sobrescribir la ruta de sqlite-vec | -Cuando sqlite-vec no está disponible, OpenClaw recurre automáticamente a similitud +Cuando sqlite-vec no está disponible, OpenClaw recurre automáticamente a la similitud de coseno en proceso. --- ## Almacenamiento del índice -| Clave | Tipo | Predeterminado | Descripción | -| --------------------- | -------- | ------------------------------------- | ------------------------------------------- | -| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Ubicación del índice (admite el token `{agentId}`) | -| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizador FTS5 (`unicode61` o `trigram`) | +| Clave | Tipo | Predeterminado | Descripción | +| ------------------- | -------- | ------------------------------------- | ------------------------------------------- | +| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Ubicación del índice (admite el token `{agentId}`) | +| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizador FTS5 (`unicode61` o `trigram`) | --- -## Configuración del backend QMD +## Configuración del backend de QMD -Establece `memory.backend = "qmd"` para habilitarlo. Toda la configuración de QMD se encuentra en +Configure `memory.backend = "qmd"` para habilitarlo. Todos los ajustes de QMD se encuentran en `memory.qmd`: -| Clave | Tipo | Predeterminado | Descripción | -| ------------------------ | --------- | -------- | -------------------------------------------- | -| `command` | `string` | `qmd` | Ruta al ejecutable de QMD | -| `searchMode` | `string` | `search` | Comando de búsqueda: `search`, `vsearch`, `query` | -| `includeDefaultMemory` | `boolean` | `true` | Autoindexar `MEMORY.md` + `memory/**/*.md` | -| `paths[]` | `array` | -- | Rutas adicionales: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | Indexar transcripciones de sesión | -| `sessions.retentionDays` | `number` | -- | Retención de transcripciones | -| `sessions.exportDir` | `string` | -- | Directorio de exportación | +| Clave | Tipo | Predeterminado | Descripción | +| ------------------------ | --------- | -------------- | -------------------------------------------- | +| `command` | `string` | `qmd` | Ruta del ejecutable de QMD | +| `searchMode` | `string` | `search` | Comando de búsqueda: `search`, `vsearch`, `query` | +| `includeDefaultMemory` | `boolean` | `true` | Indexar automáticamente `MEMORY.md` + `memory/**/*.md` | +| `paths[]` | `array` | -- | Rutas adicionales: `{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | Indexar transcripciones de sesión | +| `sessions.retentionDays` | `number` | -- | Retención de transcripciones | +| `sessions.exportDir` | `string` | -- | Directorio de exportación | -OpenClaw prefiere las formas actuales de colección QMD y de consulta MCP, pero mantiene -funcionando versiones anteriores de QMD recurriendo a indicadores heredados de colección `--mask` -y nombres anteriores de herramientas MCP cuando es necesario. +OpenClaw prefiere las formas actuales de colecciones de QMD y consultas de MCP, pero mantiene +las versiones anteriores de QMD funcionando mediante retroceso a las marcas heredadas de colección `--mask` +y a nombres anteriores de herramientas MCP cuando es necesario. -Las sobrescrituras de modelos de QMD permanecen del lado de QMD, no en la configuración de OpenClaw. Si necesitas -sobrescribir globalmente los modelos de QMD, establece variables de entorno como -`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` y `QMD_GENERATE_MODEL` en el -entorno de runtime del gateway. +Las sobrescrituras de modelo de QMD permanecen del lado de QMD, no en la configuración de OpenClaw. Si necesita +sobrescribir globalmente los modelos de QMD, configure variables de entorno como +`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` y `QMD_GENERATE_MODEL` en el entorno de ejecución +del gateway. ### Programación de actualizaciones -| Clave | Tipo | Predeterminado | Descripción | -| ------------------------- | --------- | ------- | ------------------------------------- | -| `update.interval` | `string` | `5m` | Intervalo de actualización | -| `update.debounceMs` | `number` | `15000` | Antirrebote de cambios de archivos | -| `update.onBoot` | `boolean` | `true` | Actualizar al iniciar | -| `update.waitForBootSync` | `boolean` | `false` | Bloquear el inicio hasta que finalice la actualización | -| `update.embedInterval` | `string` | -- | Cadencia separada para embeddings | -| `update.commandTimeoutMs` | `number` | -- | Tiempo de espera para comandos de QMD | -| `update.updateTimeoutMs` | `number` | -- | Tiempo de espera para operaciones de actualización de QMD | -| `update.embedTimeoutMs` | `number` | -- | Tiempo de espera para operaciones de embeddings de QMD | +| Clave | Tipo | Predeterminado | Descripción | +| ------------------------- | --------- | -------------- | ------------------------------------- | +| `update.interval` | `string` | `5m` | Intervalo de actualización | +| `update.debounceMs` | `number` | `15000` | Debounce de cambios de archivos | +| `update.onBoot` | `boolean` | `true` | Actualizar al iniciar | +| `update.waitForBootSync` | `boolean` | `false` | Bloquear el inicio hasta que termine la actualización | +| `update.embedInterval` | `string` | -- | Cadencia separada para embeddings | +| `update.commandTimeoutMs` | `number` | -- | Tiempo de espera para comandos de QMD | +| `update.updateTimeoutMs` | `number` | -- | Tiempo de espera para operaciones de actualización de QMD | +| `update.embedTimeoutMs` | `number` | -- | Tiempo de espera para operaciones de embeddings de QMD | ### Límites -| Clave | Tipo | Predeterminado | Descripción | -| ------------------------- | -------- | ------- | -------------------------- | -| `limits.maxResults` | `number` | `6` | Máximo de resultados de búsqueda | -| `limits.maxSnippetChars` | `number` | -- | Limitar longitud del fragmento | -| `limits.maxInjectedChars` | `number` | -- | Limitar total de caracteres inyectados | -| `limits.timeoutMs` | `number` | `4000` | Tiempo de espera de la búsqueda | +| Clave | Tipo | Predeterminado | Descripción | +| ------------------------- | -------- | -------------- | -------------------------- | +| `limits.maxResults` | `number` | `6` | Máximo de resultados de búsqueda | +| `limits.maxSnippetChars` | `number` | -- | Limitar la longitud del fragmento | +| `limits.maxInjectedChars` | `number` | -- | Limitar el total de caracteres inyectados | +| `limits.timeoutMs` | `number` | `4000` | Tiempo de espera de búsqueda | ### Alcance -Controla qué sesiones pueden recibir resultados de búsqueda de QMD. Mismo esquema que +Controla qué sesiones pueden recibir resultados de búsqueda de QMD. El mismo esquema que [`session.sendPolicy`](/es/gateway/configuration-reference#session): ```json5 @@ -434,17 +445,17 @@ Controla qué sesiones pueden recibir resultados de búsqueda de QMD. Mismo esqu ``` El valor predeterminado es solo DM. `match.keyPrefix` coincide con la clave de sesión normalizada; -`match.rawKeyPrefix` coincide con la clave sin procesar, incluida `agent::`. +`match.rawKeyPrefix` coincide con la clave sin procesar, incluido `agent::`. ### Citas `memory.citations` se aplica a todos los backends: | Valor | Comportamiento | -| ---------------- | --------------------------------------------------- | -| `auto` (predeterminado) | Incluir pie `Source: ` en los fragmentos | +| ---------------- | --------------------------------------------------------- | +| `auto` (predeterminado) | Incluir el pie `Source: ` en los fragmentos | | `on` | Incluir siempre el pie | -| `off` | Omitir el pie (la ruta aún se pasa al agente internamente) | +| `off` | Omitir el pie (la ruta sigue pasándose al agente internamente) | ### Ejemplo completo de QMD @@ -469,22 +480,22 @@ El valor predeterminado es solo DM. `match.keyPrefix` coincide con la clave de s --- -## Sueños (experimental) +## Dreaming (experimental) -Sueños se configura en `plugins.entries.memory-core.config.dreaming`, +Dreaming se configura en `plugins.entries.memory-core.config.dreaming`, no en `agents.defaults.memorySearch`. -Sueños se ejecuta como un único barrido programado y usa fases internas ligera/profunda/REM como +Dreaming se ejecuta como un barrido programado y usa fases internas light/deep/REM como detalle de implementación. -Para el comportamiento conceptual y los comandos de barra, consulta [Sueños](/concepts/dreaming). +Para el comportamiento conceptual y los comandos con barra, consulte [Dreaming](/es/concepts/dreaming). -### Configuración del usuario +### Ajustes del usuario -| Clave | Tipo | Predeterminado | Descripción | -| ----------- | --------- | ----------- | ------------------------------------------------- | -| `enabled` | `boolean` | `false` | Habilitar o deshabilitar por completo Sueños | -| `frequency` | `string` | `0 3 * * *` | Cadencia cron opcional para el barrido completo de Sueños | +| Clave | Tipo | Predeterminado | Descripción | +| ----------- | --------- | -------------- | ------------------------------------------------- | +| `enabled` | `boolean` | `false` | Habilitar o deshabilitar completamente Dreaming | +| `frequency` | `string` | `0 3 * * *` | Cadencia cron opcional para el barrido completo de Dreaming | ### Ejemplo @@ -507,6 +518,6 @@ Para el comportamiento conceptual y los comandos de barra, consulta [Sueños](/c Notas: -- Sueños escribe el estado de máquina en `memory/.dreams/`. -- Sueños escribe salida narrativa legible para humanos en `DREAMS.md` (o `dreams.md` existente). -- La política de fases ligera/profunda/REM y los umbrales son comportamiento interno, no configuración visible para el usuario. +- Dreaming escribe el estado de la máquina en `memory/.dreams/`. +- Dreaming escribe la salida narrativa legible para humanos en `DREAMS.md` (o `dreams.md` existente). +- La política y los umbrales de las fases light/deep/REM son comportamiento interno, no configuración orientada al usuario. diff --git a/docs/es/tools/browser.md b/docs/es/tools/browser.md index bb58dcbc7..66688a51f 100644 --- a/docs/es/tools/browser.md +++ b/docs/es/tools/browser.md @@ -2,14 +2,14 @@ read_when: - Agregar automatización del navegador controlada por el agente - Depurar por qué openclaw está interfiriendo con tu propio Chrome - - Implementar la configuración y el ciclo de vida del navegador en la aplicación de macOS -summary: Servicio integrado de control del navegador + comandos de acción + - Implementar la configuración del navegador + el ciclo de vida en la app de macOS +summary: Servicio de control del navegador integrado + comandos de acción title: Navegador (gestionado por OpenClaw) x-i18n: - generated_at: "2026-04-05T12:56:23Z" + generated_at: "2026-04-10T05:12:09Z" model: gpt-5.4 provider: openai - source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a + source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604 source_path: tools/browser.md workflow: 15 --- @@ -17,22 +17,22 @@ x-i18n: # Navegador (gestionado por openclaw) OpenClaw puede ejecutar un **perfil dedicado de Chrome/Brave/Edge/Chromium** que el agente controla. -Está aislado de tu navegador personal y se gestiona a través de un pequeño +Está aislado de tu navegador personal y se gestiona mediante un pequeño servicio de control local dentro del Gateway (solo loopback). Vista para principiantes: -- Piénsalo como un **navegador independiente, solo para el agente**. -- El perfil `openclaw` **no** toca tu perfil de navegador personal. +- Piensa en él como un **navegador separado, solo para el agente**. +- El perfil `openclaw` **no** toca tu perfil personal del navegador. - El agente puede **abrir pestañas, leer páginas, hacer clic y escribir** en un entorno seguro. -- El perfil integrado `user` se adjunta a tu sesión real de Chrome con sesión iniciada mediante Chrome MCP. +- El perfil integrado `user` se conecta a tu sesión real de Chrome con inicio de sesión mediante Chrome MCP. -## Qué obtienes +## Lo que obtienes -- Un perfil de navegador independiente llamado **openclaw** (con acento naranja de forma predeterminada). +- Un perfil de navegador separado llamado **openclaw** (acento naranja de forma predeterminada). - Control determinista de pestañas (listar/abrir/enfocar/cerrar). -- Acciones del agente (clic/escribir/arrastrar/seleccionar), snapshots, capturas de pantalla y PDF. -- Soporte opcional para varios perfiles (`openclaw`, `work`, `remote`, ...). +- Acciones del agente (clic/escritura/arrastrar/seleccionar), instantáneas, capturas de pantalla y PDF. +- Compatibilidad opcional con varios perfiles (`openclaw`, `work`, `remote`, ...). Este navegador **no** es tu navegador de uso diario. Es una superficie segura y aislada para la automatización y verificación del agente. @@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Si obtienes “Browser disabled”, actívalo en la configuración (ver más abajo) y reinicia el +Si aparece “Browser disabled”, actívalo en la configuración (consulta más abajo) y reinicia el Gateway. -Si `openclaw browser` falta por completo, o el agente dice que la herramienta de navegador -no está disponible, ve a [Comando o herramienta de navegador ausente](/tools/browser#missing-browser-command-or-tool). +Si `openclaw browser` no aparece en absoluto, o el agente dice que la herramienta de navegador +no está disponible, ve a [Falta el comando o la herramienta del navegador](/es/tools/browser#missing-browser-command-or-tool). -## Control de plugins +## Control del plugin -La herramienta predeterminada `browser` ahora es un plugin incluido que se envía habilitado de -forma predeterminada. Eso significa que puedes desactivarlo o sustituirlo sin eliminar el resto del +La herramienta `browser` predeterminada ahora es un plugin incluido que se envía habilitado de +forma predeterminada. Eso significa que puedes desactivarlo o reemplazarlo sin eliminar el resto del sistema de plugins de OpenClaw: ```json5 @@ -76,24 +76,24 @@ mismo nombre de herramienta `browser`. La experiencia predeterminada del navegad - `plugins.entries.browser.enabled` no deshabilitado - `browser.enabled=true` -Si desactivas solo el plugin, la CLI del navegador incluida (`openclaw browser`), +Si desactivas solo el plugin, el CLI de navegador incluido (`openclaw browser`), el método del gateway (`browser.request`), la herramienta del agente y el servicio predeterminado de control del navegador -desaparecen todos juntos. Tu configuración `browser.*` permanece intacta para que un +desaparecen juntos. Tu configuración `browser.*` permanece intacta para que un plugin de reemplazo la reutilice. -El plugin del navegador incluido también es ahora el propietario de la implementación del runtime del navegador. -El núcleo solo conserva helpers compartidos del Plugin SDK más reexportaciones de compatibilidad para -rutas internas de importación más antiguas. En la práctica, eliminar o sustituir el paquete del plugin del navegador -elimina el conjunto de funciones del navegador en lugar de dejar detrás un segundo -runtime propiedad del núcleo. +El plugin de navegador incluido también es ahora el propietario de la implementación del tiempo de ejecución del navegador. +El núcleo conserva solo los helpers compartidos del Plugin SDK más las reexportaciones de compatibilidad para +rutas de importación internas antiguas. En la práctica, eliminar o reemplazar el paquete del plugin de navegador +elimina el conjunto de funciones del navegador en lugar de dejar detrás un segundo tiempo de ejecución +propiedad del núcleo. -Los cambios en la configuración del navegador siguen requiriendo un reinicio del Gateway para que el plugin incluido +Los cambios de configuración del navegador siguen requiriendo un reinicio del Gateway para que el plugin incluido pueda volver a registrar su servicio de navegador con la nueva configuración. -## Comando o herramienta de navegador ausente +## Falta el comando o la herramienta del navegador -Si `openclaw browser` de repente se convierte en un comando desconocido tras una actualización, o -el agente informa de que falta la herramienta de navegador, la causa más común es una +Si `openclaw browser` de repente pasa a ser un comando desconocido después de una actualización, o +el agente informa que falta la herramienta de navegador, la causa más común es una lista restrictiva `plugins.allow` que no incluye `browser`. Ejemplo de configuración incorrecta: @@ -106,7 +106,7 @@ Ejemplo de configuración incorrecta: } ``` -Corrígelo agregando `browser` a la allowlist de plugins: +Corrígelo agregando `browser` a la lista de permitidos de plugins: ```json5 { @@ -118,49 +118,48 @@ Corrígelo agregando `browser` a la allowlist de plugins: Notas importantes: -- `browser.enabled=true` no es suficiente por sí solo cuando `plugins.allow` está establecido. -- `plugins.entries.browser.enabled=true` tampoco es suficiente por sí solo cuando `plugins.allow` está establecido. -- `tools.alsoAllow: ["browser"]` **no** carga el plugin del navegador incluido. Solo ajusta la política de herramientas después de que el plugin ya esté cargado. -- Si no necesitas una allowlist de plugins restrictiva, eliminar `plugins.allow` también restaura el comportamiento predeterminado del navegador incluido. +- `browser.enabled=true` por sí solo no es suficiente cuando `plugins.allow` está configurado. +- `plugins.entries.browser.enabled=true` por sí solo tampoco es suficiente cuando `plugins.allow` está configurado. +- `tools.alsoAllow: ["browser"]` **no** carga el plugin de navegador incluido. Solo ajusta la política de herramientas después de que el plugin ya esté cargado. +- Si no necesitas una lista restrictiva de plugins permitidos, quitar `plugins.allow` también restaura el comportamiento predeterminado del navegador incluido. Síntomas típicos: - `openclaw browser` es un comando desconocido. - Falta `browser.request`. -- El agente informa de que la herramienta de navegador no está disponible o falta. +- El agente informa que la herramienta de navegador no está disponible o falta. ## Perfiles: `openclaw` frente a `user` - `openclaw`: navegador gestionado y aislado (no requiere extensión). -- `user`: perfil integrado de conexión Chrome MCP para tu **sesión real de Chrome** - con sesión iniciada. +- `user`: perfil integrado de conexión Chrome MCP para tu **sesión real de Chrome con inicio de sesión**. -Para las llamadas de la herramienta de navegador del agente: +Para llamadas a la herramienta de navegador del agente: -- Predeterminado: usa el navegador aislado `openclaw`. -- Prefiere `profile="user"` cuando importen las sesiones existentes con inicio de sesión y el usuario - esté en la computadora para hacer clic o aprobar cualquier aviso de conexión. +- Predeterminado: usar el navegador aislado `openclaw`. +- Preferir `profile="user"` cuando importan las sesiones existentes con inicio de sesión y el usuario + está en la computadora para hacer clic o aprobar cualquier solicitud de conexión. - `profile` es la anulación explícita cuando quieres un modo de navegador específico. -Establece `browser.defaultProfile: "openclaw"` si quieres el modo gestionado de forma predeterminada. +Establece `browser.defaultProfile: "openclaw"` si quieres el modo gestionado como predeterminado. ## Configuración -La configuración del navegador vive en `~/.openclaw/openclaw.json`. +La configuración del navegador se encuentra en `~/.openclaw/openclaw.json`. ```json5 { browser: { - enabled: true, // default: true + enabled: true, // predeterminado: true ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // default trusted-network mode - // allowPrivateNetwork: true, // legacy alias + dangerouslyAllowPrivateNetwork: true, // modo predeterminado de red de confianza + // allowPrivateNetwork: true, // alias heredado // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override - remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) - remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) + // cdpUrl: "http://127.0.0.1:18792", // anulación heredada de perfil único + remoteCdpTimeoutMs: 1500, // tiempo de espera HTTP de CDP remoto (ms) + remoteCdpHandshakeTimeoutMs: 3000, // tiempo de espera del protocolo de enlace WebSocket de CDP remoto (ms) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -189,31 +188,31 @@ La configuración del navegador vive en `~/.openclaw/openclaw.json`. Notas: -- El servicio de control del navegador se vincula a loopback en un puerto derivado de `gateway.port` +- El servicio de control del navegador se enlaza a loopback en un puerto derivado de `gateway.port` (predeterminado: `18791`, que es gateway + 2). - Si anulas el puerto del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), - los puertos del navegador derivados se desplazan para permanecer en la misma “familia”. -- `cdpUrl` usa de forma predeterminada el puerto CDP local gestionado cuando no está establecido. -- `remoteCdpTimeoutMs` se aplica a las comprobaciones de accesibilidad de CDP remotas (no loopback). -- `remoteCdpHandshakeTimeoutMs` se aplica a las comprobaciones de accesibilidad del handshake de WebSocket CDP remoto. -- La navegación/apertura de pestañas del navegador está protegida contra SSRF antes de la navegación y se vuelve a comprobar en la medida de lo posible en la URL final `http(s)` tras la navegación. -- En el modo SSRF estricto, el descubrimiento/sondeo de endpoints CDP remotos (`cdpUrl`, incluidas las búsquedas `/json/version`) también se comprueba. -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` usa `true` de forma predeterminada (modelo de red de confianza). Establécelo en `false` para una navegación estricta solo pública. + los puertos derivados del navegador se desplazan para permanecer en la misma “familia”. +- `cdpUrl` usa de forma predeterminada el puerto CDP local gestionado cuando no está configurado. +- `remoteCdpTimeoutMs` se aplica a las comprobaciones de accesibilidad de CDP remoto (no loopback). +- `remoteCdpHandshakeTimeoutMs` se aplica a las comprobaciones de accesibilidad del WebSocket de CDP remoto. +- La navegación/apertura de pestañas del navegador está protegida contra SSRF antes de la navegación y se vuelve a verificar en la medida de lo posible en la URL final `http(s)` después de la navegación. +- En el modo SSRF estricto, también se comprueban el descubrimiento y las sondas del endpoint CDP remoto (`cdpUrl`, incluidas las búsquedas de `/json/version`). +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` usa `true` de forma predeterminada (modelo de red de confianza). Establécelo en `false` para navegación estricta solo pública. - `browser.ssrfPolicy.allowPrivateNetwork` sigue siendo compatible como alias heredado por compatibilidad. -- `attachOnly: true` significa “nunca iniciar un navegador local; solo adjuntarse si ya está en ejecución”. +- `attachOnly: true` significa “nunca iniciar un navegador local; solo conectarse si ya está en ejecución”. - `color` + `color` por perfil tiñen la interfaz del navegador para que puedas ver qué perfil está activo. -- El perfil predeterminado es `openclaw` (navegador independiente gestionado por OpenClaw). Usa `defaultProfile: "user"` para optar por el navegador de usuario con sesión iniciada. -- Orden de detección automática: navegador predeterminado del sistema si está basado en Chromium; si no, Chrome → Brave → Edge → Chromium → Chrome Canary. -- Los perfiles `openclaw` locales asignan automáticamente `cdpPort`/`cdpUrl`; establécelos solo para CDP remoto. +- El perfil predeterminado es `openclaw` (navegador independiente gestionado por OpenClaw). Usa `defaultProfile: "user"` para optar por el navegador del usuario con inicio de sesión. +- Orden de detección automática: navegador predeterminado del sistema si está basado en Chromium; en caso contrario Chrome → Brave → Edge → Chromium → Chrome Canary. +- Los perfiles `openclaw` locales asignan automáticamente `cdpPort`/`cdpUrl`; configúralos solo para CDP remoto. - `driver: "existing-session"` usa Chrome DevTools MCP en lugar de CDP sin procesar. No - establezcas `cdpUrl` para ese driver. -- Establece `browser.profiles..userDataDir` cuando un perfil existing-session - deba adjuntarse a un perfil de usuario Chromium no predeterminado como Brave o Edge. + configures `cdpUrl` para ese controlador. +- Configura `browser.profiles..userDataDir` cuando un perfil existing-session + deba conectarse a un perfil de usuario Chromium no predeterminado como Brave o Edge. ## Usar Brave (u otro navegador basado en Chromium) -Si tu navegador **predeterminado del sistema** está basado en Chromium (Chrome/Brave/Edge/etc), -OpenClaw lo usa automáticamente. Establece `browser.executablePath` para anular la +Si tu navegador **predeterminado del sistema** está basado en Chromium (Chrome/Brave/Edge/etc.), +OpenClaw lo usa automáticamente. Configura `browser.executablePath` para anular la detección automática: Ejemplo de CLI: @@ -247,19 +246,19 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Control local frente a remoto -- **Control local (predeterminado):** el Gateway inicia el servicio de control en loopback y puede lanzar un navegador local. -- **Control remoto (host node):** ejecuta un host node en la máquina que tiene el navegador; el Gateway redirige las acciones del navegador hacia él. -- **CDP remoto:** establece `browser.profiles..cdpUrl` (o `browser.cdpUrl`) para - adjuntarte a un navegador remoto basado en Chromium. En este caso, OpenClaw no iniciará un navegador local. +- **Control local (predeterminado):** el Gateway inicia el servicio de control de loopback y puede iniciar un navegador local. +- **Control remoto (host de nodo):** ejecuta un host de nodo en la máquina que tiene el navegador; el Gateway redirige las acciones del navegador a él. +- **CDP remoto:** configura `browser.profiles..cdpUrl` (o `browser.cdpUrl`) para + conectarte a un navegador remoto basado en Chromium. En este caso, OpenClaw no iniciará un navegador local. -El comportamiento de detención difiere según el modo de perfil: +El comportamiento de detención varía según el modo del perfil: - perfiles locales gestionados: `openclaw browser stop` detiene el proceso del navegador que - OpenClaw lanzó -- perfiles solo adjuntos y CDP remotos: `openclaw browser stop` cierra la - sesión de control activa y libera las anulaciones de emulación de Playwright/CDP (viewport, - esquema de color, configuración regional, zona horaria, modo sin conexión y estado similar), incluso - aunque OpenClaw no haya iniciado ningún proceso de navegador + OpenClaw inició +- perfiles de solo conexión y CDP remoto: `openclaw browser stop` cierra la sesión de control activa + y libera las anulaciones de emulación de Playwright/CDP (viewport, + combinación de colores, configuración regional, zona horaria, modo sin conexión y estado similar), aunque + OpenClaw no haya iniciado ningún proceso del navegador Las URL de CDP remoto pueden incluir autenticación: @@ -267,30 +266,30 @@ Las URL de CDP remoto pueden incluir autenticación: - Autenticación HTTP Basic (por ejemplo, `https://user:pass@provider.example`) OpenClaw conserva la autenticación al llamar a los endpoints `/json/*` y al conectarse -al WebSocket CDP. Prefiere variables de entorno o gestores de secretos para -los tokens en lugar de confirmarlos en archivos de configuración. +al WebSocket de CDP. Prefiere variables de entorno o gestores de secretos para los +tokens en lugar de confirmarlos en archivos de configuración. -## Proxy de navegador node (predeterminado sin configuración) +## Proxy de navegador del nodo (predeterminado sin configuración) -Si ejecutas un **host node** en la máquina que tiene tu navegador, OpenClaw puede +Si ejecutas un **host de nodo** en la máquina que tiene tu navegador, OpenClaw puede redirigir automáticamente las llamadas de la herramienta de navegador a ese nodo sin ninguna configuración adicional del navegador. Esta es la ruta predeterminada para gateways remotos. Notas: -- El host node expone su servidor local de control del navegador mediante un **comando proxy**. +- El host de nodo expone su servidor local de control del navegador mediante un **comando proxy**. - Los perfiles provienen de la propia configuración `browser.profiles` del nodo (igual que en local). - `nodeHost.browserProxy.allowProfiles` es opcional. Déjalo vacío para el comportamiento heredado/predeterminado: todos los perfiles configurados siguen siendo accesibles a través del proxy, incluidas las rutas de creación/eliminación de perfiles. -- Si estableces `nodeHost.browserProxy.allowProfiles`, OpenClaw lo trata como un límite de mínimo privilegio: solo se pueden dirigir perfiles de la allowlist, y las rutas persistentes de creación/eliminación de perfiles quedan bloqueadas en la superficie del proxy. +- Si configuras `nodeHost.browserProxy.allowProfiles`, OpenClaw lo trata como un límite de privilegio mínimo: solo se pueden dirigir los perfiles permitidos, y las rutas persistentes de creación/eliminación de perfiles se bloquean en la superficie del proxy. - Desactívalo si no lo quieres: - En el nodo: `nodeHost.browserProxy.enabled=false` - En el gateway: `gateway.nodes.browser.mode="off"` ## Browserless (CDP remoto alojado) -[Browserless](https://browserless.io) es un servicio alojado de Chromium que expone -URL de conexión CDP a través de HTTPS y WebSocket. OpenClaw puede usar cualquiera de las dos formas, pero -para un perfil de navegador remoto la opción más sencilla es la URL directa de WebSocket +[Browserless](https://browserless.io) es un servicio Chromium alojado que expone +URL de conexión CDP mediante HTTPS y WebSocket. OpenClaw puede usar cualquiera de las dos formas, pero +para un perfil de navegador remoto la opción más sencilla es la URL WebSocket directa de la documentación de conexión de Browserless. Ejemplo: @@ -314,30 +313,30 @@ Ejemplo: Notas: -- Sustituye `` por tu token real de Browserless. +- Reemplaza `` por tu token real de Browserless. - Elige el endpoint regional que coincida con tu cuenta de Browserless (consulta su documentación). -- Si Browserless te da una URL base HTTPS, puedes convertirla a - `wss://` para una conexión CDP directa o mantener la URL HTTPS y dejar que OpenClaw +- Si Browserless te proporciona una URL base HTTPS, puedes convertirla a + `wss://` para una conexión CDP directa o conservar la URL HTTPS y dejar que OpenClaw descubra `/json/version`. -## Proveedores CDP directos por WebSocket +## Proveedores CDP WebSocket directos -Algunos servicios de navegador alojados exponen un endpoint **WebSocket directo** en lugar del -descubrimiento CDP estándar basado en HTTP (`/json/version`). OpenClaw admite ambos: +Algunos servicios de navegador alojados exponen un endpoint **WebSocket directo** en lugar de +la detección CDP estándar basada en HTTP (`/json/version`). OpenClaw es compatible con ambos: - **Endpoints HTTP(S)** — OpenClaw llama a `/json/version` para descubrir la URL del depurador WebSocket y luego se conecta. - **Endpoints WebSocket** (`ws://` / `wss://`) — OpenClaw se conecta directamente, - omitiendo `/json/version`. Usa esto para servicios como + omitiendo `/json/version`. Úsalo para servicios como [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com) o cualquier proveedor que te entregue una + [Browserbase](https://www.browserbase.com), o cualquier proveedor que te dé una URL WebSocket. ### Browserbase [Browserbase](https://www.browserbase.com) es una plataforma en la nube para ejecutar -navegadores headless con resolución integrada de CAPTCHA, modo sigiloso y -proxies residenciales. +navegadores headless con resolución de CAPTCHA integrada, modo sigiloso y proxies +residenciales. ```json5 { @@ -359,60 +358,60 @@ proxies residenciales. Notas: - [Regístrate](https://www.browserbase.com/sign-up) y copia tu **API Key** - desde el [panel general](https://www.browserbase.com/overview). -- Sustituye `` por tu clave de API real de Browserbase. -- Browserbase crea automáticamente una sesión de navegador al conectar por WebSocket, así que no - hace falta un paso manual de creación de sesión. -- El nivel gratuito permite una sesión concurrente y una hora de navegador al mes. + desde el [panel de Overview](https://www.browserbase.com/overview). +- Reemplaza `` con tu clave API real de Browserbase. +- Browserbase crea automáticamente una sesión del navegador al conectarse por WebSocket, por lo que no + se necesita ningún paso manual de creación de sesión. +- El nivel gratuito permite una sesión simultánea y una hora de navegador al mes. Consulta [pricing](https://www.browserbase.com/pricing) para los límites de los planes de pago. - Consulta la [documentación de Browserbase](https://docs.browserbase.com) para la referencia completa de la API, - guías del SDK y ejemplos de integración. + las guías del SDK y los ejemplos de integración. ## Seguridad Ideas clave: -- El control del navegador es solo loopback; el acceso fluye a través de la autenticación del Gateway o del emparejamiento de nodos. +- El control del navegador es solo por loopback; el acceso fluye a través de la autenticación del Gateway o del emparejamiento de nodos. - La API HTTP independiente del navegador en loopback usa **solo autenticación con secreto compartido**: - autenticación bearer con token del gateway, `x-openclaw-password` o autenticación HTTP Basic con la - contraseña configurada del gateway. -- Las cabeceras de identidad de Tailscale Serve y `gateway.auth.mode: "trusted-proxy"` **no** + autenticación Bearer con token del gateway, `x-openclaw-password`, o autenticación HTTP Basic con la + contraseña del gateway configurada. +- Los encabezados de identidad de Tailscale Serve y `gateway.auth.mode: "trusted-proxy"` **no** autentican esta API independiente del navegador en loopback. - Si el control del navegador está habilitado y no hay autenticación con secreto compartido configurada, OpenClaw - genera automáticamente `gateway.auth.token` al inicio y lo persiste en la configuración. + genera automáticamente `gateway.auth.token` al inicio y lo conserva en la configuración. - OpenClaw **no** genera automáticamente ese token cuando `gateway.auth.mode` ya es - `password`, `none` o `trusted-proxy`. -- Mantén el Gateway y cualquier host node en una red privada (Tailscale); evita la exposición pública. + `password`, `none`, o `trusted-proxy`. +- Mantén el Gateway y cualquier host de nodo en una red privada (Tailscale); evita la exposición pública. - Trata las URL/tokens de CDP remoto como secretos; prefiere variables de entorno o un gestor de secretos. Consejos para CDP remoto: - Prefiere endpoints cifrados (HTTPS o WSS) y tokens de corta duración cuando sea posible. -- Evita incrustar tokens de larga duración directamente en archivos de configuración. +- Evita incrustar tokens de larga duración directamente en los archivos de configuración. -## Perfiles (varios navegadores) +## Perfiles (multinavegador) OpenClaw admite varios perfiles con nombre (configuraciones de enrutamiento). Los perfiles pueden ser: - **gestionados por openclaw**: una instancia dedicada de navegador basado en Chromium con su propio directorio de datos de usuario + puerto CDP -- **remotos**: una URL CDP explícita (navegador basado en Chromium ejecutándose en otro lugar) -- **sesión existente**: tu perfil de Chrome existente mediante conexión automática de Chrome DevTools MCP +- **remoto**: una URL CDP explícita (navegador basado en Chromium ejecutándose en otro lugar) +- **sesión existente**: tu perfil existente de Chrome mediante conexión automática con Chrome DevTools MCP Valores predeterminados: - El perfil `openclaw` se crea automáticamente si falta. -- El perfil `user` está integrado para la conexión existing-session mediante Chrome MCP. -- Los perfiles existing-session son optativos más allá de `user`; créalos con `--driver existing-session`. +- El perfil `user` está integrado para la conexión existing-session de Chrome MCP. +- Los perfiles existing-session son optativos además de `user`; créalos con `--driver existing-session`. - Los puertos CDP locales se asignan desde **18800–18899** de forma predeterminada. -- Al eliminar un perfil, su directorio de datos local se mueve a la Papelera. +- Eliminar un perfil mueve su directorio de datos local a la Papelera. Todos los endpoints de control aceptan `?profile=`; la CLI usa `--browser-profile`. ## Existing-session mediante Chrome DevTools MCP -OpenClaw también puede adjuntarse a un perfil de navegador basado en Chromium en ejecución mediante el +OpenClaw también puede conectarse a un perfil de navegador basado en Chromium en ejecución mediante el servidor oficial Chrome DevTools MCP. Esto reutiliza las pestañas y el estado de inicio de sesión -ya abiertos en ese perfil de navegador. +ya abiertos en ese perfil del navegador. Referencias oficiales de contexto y configuración: @@ -424,7 +423,7 @@ Perfil integrado: - `user` Opcional: crea tu propio perfil existing-session personalizado si quieres un -nombre, color o directorio de datos de navegador diferente. +nombre, color o directorio de datos del navegador diferente. Comportamiento predeterminado: @@ -452,7 +451,7 @@ Luego, en el navegador correspondiente: 1. Abre la página de inspección de ese navegador para depuración remota. 2. Habilita la depuración remota. -3. Mantén el navegador en ejecución y aprueba el aviso de conexión cuando OpenClaw se adjunte. +3. Mantén el navegador en ejecución y aprueba la solicitud de conexión cuando OpenClaw se conecte. Páginas de inspección habituales: @@ -469,7 +468,7 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Cómo es un resultado correcto: +Cómo se ve cuando funciona correctamente: - `status` muestra `driver: existing-session` - `status` muestra `transport: chrome-mcp` @@ -481,59 +480,58 @@ Qué comprobar si la conexión no funciona: - el navegador basado en Chromium de destino es versión `144+` - la depuración remota está habilitada en la página de inspección de ese navegador -- el navegador mostró y aceptaste el aviso de consentimiento de conexión +- el navegador mostró la solicitud de consentimiento de conexión y la aceptaste - `openclaw doctor` migra la configuración antigua del navegador basada en extensiones y comprueba que Chrome esté instalado localmente para los perfiles predeterminados con conexión automática, pero no puede - habilitar la depuración remota en el navegador por ti + habilitar por ti la depuración remota del lado del navegador Uso por parte del agente: - Usa `profile="user"` cuando necesites el estado del navegador del usuario con sesión iniciada. - Si usas un perfil existing-session personalizado, pasa ese nombre de perfil explícito. -- Elige este modo solo cuando el usuario esté en la computadora para aprobar el aviso - de conexión. -- el Gateway o el host node pueden iniciar `npx chrome-devtools-mcp@latest --autoConnect` +- Elige este modo solo cuando el usuario esté en la computadora para aprobar la + solicitud de conexión. +- el Gateway o el host de nodo pueden iniciar `npx chrome-devtools-mcp@latest --autoConnect` Notas: - Esta ruta tiene más riesgo que el perfil aislado `openclaw` porque puede - actuar dentro de tu sesión del navegador con inicio de sesión. -- OpenClaw no inicia el navegador para este driver; solo se adjunta a una + actuar dentro de tu sesión de navegador con inicio de sesión. +- OpenClaw no inicia el navegador para este controlador; se conecta únicamente a una sesión existente. - OpenClaw usa aquí el flujo oficial `--autoConnect` de Chrome DevTools MCP. Si - `userDataDir` está establecido, OpenClaw lo pasa para apuntar a ese directorio explícito - de datos de usuario Chromium. + `userDataDir` está configurado, OpenClaw lo pasa para apuntar a ese directorio + explícito de datos de usuario de Chromium. - Las capturas de pantalla de existing-session admiten capturas de página y capturas de elementos con `--ref` - desde snapshots, pero no selectores CSS `--element`. -- Las capturas de pantalla de página de existing-session funcionan sin Playwright mediante Chrome MCP. - Las capturas de elementos basadas en refs (`--ref`) también funcionan ahí, pero `--full-page` - no puede combinarse con `--ref` ni con `--element`. -- Las acciones de existing-session siguen siendo más limitadas que la ruta de navegador gestionado: + desde instantáneas, pero no selectores CSS `--element`. +- Las capturas de página de existing-session funcionan sin Playwright mediante Chrome MCP. + Las capturas de elementos basadas en ref (`--ref`) también funcionan ahí, pero `--full-page` + no se puede combinar con `--ref` ni con `--element`. +- Las acciones de existing-session siguen siendo más limitadas que la ruta del navegador + gestionado: - `click`, `type`, `hover`, `scrollIntoView`, `drag` y `select` requieren - refs de snapshot en lugar de selectores CSS + refs de instantánea en lugar de selectores CSS - `click` es solo con el botón izquierdo (sin anulaciones de botón ni modificadores) - `type` no admite `slowly=true`; usa `fill` o `press` - `press` no admite `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` y `evaluate` no admiten anulaciones de tiempo de espera por llamada - - `select` actualmente admite solo un valor -- `wait --url` de existing-session admite patrones exactos, subcadenas y glob - como otros drivers de navegador. `wait --load networkidle` todavía no está admitido. -- Los hooks de carga de existing-session requieren `ref` o `inputRef`, admiten un archivo - a la vez y no admiten direccionamiento CSS `element`. -- Los hooks de diálogo de existing-session no admiten anulaciones de tiempo de espera. -- Algunas funciones siguen requiriendo la ruta de navegador gestionado, incluidas - acciones por lotes, exportación de PDF, interceptación de descargas y `responsebody`. + - `select` actualmente admite solo un único valor +- `wait --url` en existing-session admite patrones exactos, de subcadena y glob + como otros controladores de navegador. `wait --load networkidle` aún no es compatible. +- Los hooks de carga de archivos en existing-session requieren `ref` o `inputRef`, admiten un archivo a la vez y no admiten el direccionamiento CSS `element`. +- Los hooks de diálogo en existing-session no admiten anulaciones de tiempo de espera. +- Algunas funciones aún requieren la ruta del navegador gestionado, incluidas acciones por lotes, exportación a PDF, interceptación de descargas y `responsebody`. - Existing-session es local al host. Si Chrome está en otra máquina o en un - espacio de nombres de red diferente, usa CDP remoto o un host node en su lugar. + espacio de nombres de red diferente, usa CDP remoto o un host de nodo en su lugar. ## Garantías de aislamiento -- **Directorio de datos de usuario dedicado**: nunca toca tu perfil de navegador personal. -- **Puertos dedicados**: evita `9222` para prevenir conflictos con flujos de trabajo de desarrollo. -- **Control determinista de pestañas**: apunta a las pestañas por `targetId`, no por “última pestaña”. +- **Directorio de datos de usuario dedicado**: nunca toca tu perfil personal del navegador. +- **Puertos dedicados**: evita `9222` para impedir colisiones con flujos de trabajo de desarrollo. +- **Control determinista de pestañas**: apunta a las pestañas por `targetId`, no por “la última pestaña”. -## Selección de navegador +## Selección del navegador Al iniciar localmente, OpenClaw elige el primero disponible: @@ -557,7 +555,7 @@ Solo para integraciones locales, el Gateway expone una pequeña API HTTP en loop - Estado/inicio/detención: `GET /`, `POST /start`, `POST /stop` - Pestañas: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` -- Snapshot/captura de pantalla: `GET /snapshot`, `POST /screenshot` +- Instantánea/captura de pantalla: `GET /snapshot`, `POST /screenshot` - Acciones: `POST /navigate`, `POST /act` - Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog` - Descargas: `POST /download`, `POST /wait/download` @@ -570,50 +568,71 @@ Solo para integraciones locales, el Gateway expone una pequeña API HTTP en loop Todos los endpoints aceptan `?profile=`. -Si la autenticación del gateway con secreto compartido está configurada, las rutas HTTP del navegador también requieren autenticación: +Si está configurada la autenticación del gateway con secreto compartido, las rutas HTTP del navegador también requieren autenticación: - `Authorization: Bearer ` - `x-openclaw-password: ` o autenticación HTTP Basic con esa contraseña Notas: -- Esta API independiente del navegador en loopback **no** consume cabeceras de identidad de proxy de confianza ni - de Tailscale Serve. +- Esta API independiente del navegador en loopback **no** consume trusted-proxy ni + encabezados de identidad de Tailscale Serve. - Si `gateway.auth.mode` es `none` o `trusted-proxy`, estas rutas del navegador en loopback no heredan esos modos con identidad; mantenlas solo en loopback. +### Contrato de error de `/act` + +`POST /act` usa una respuesta de error estructurada para la validación a nivel de ruta y +los errores de política: + +```json +{ "error": "", "code": "ACT_*" } +``` + +Valores actuales de `code`: + +- `ACT_KIND_REQUIRED` (HTTP 400): falta `kind` o no se reconoce. +- `ACT_INVALID_REQUEST` (HTTP 400): la carga útil de la acción no superó la normalización o validación. +- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): se usó `selector` con un tipo de acción no compatible. +- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (o `wait --fn`) está deshabilitado por la configuración. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` de nivel superior o por lotes entra en conflicto con el destino de la solicitud. +- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): la acción no es compatible con perfiles existing-session. + +Otros errores de tiempo de ejecución aún pueden devolver `{ "error": "" }` sin un +campo `code`. + ### Requisito de Playwright -Algunas funciones (navigate/act/AI snapshot/role snapshot, capturas de elementos, +Algunas funciones (navigate/act/instantánea AI/instantánea de rol, capturas de pantalla de elementos, PDF) requieren Playwright. Si Playwright no está instalado, esos endpoints devuelven un error 501 claro. Lo que sigue funcionando sin Playwright: -- Snapshots ARIA -- Capturas de página para el navegador gestionado `openclaw` cuando hay un WebSocket CDP - por pestaña disponible -- Capturas de página para perfiles `existing-session` / Chrome MCP -- Capturas de pantalla de existing-session basadas en refs (`--ref`) desde la salida de snapshot +- Instantáneas ARIA +- Capturas de pantalla de página para el navegador gestionado `openclaw` cuando hay disponible un + WebSocket CDP por pestaña +- Capturas de pantalla de página para perfiles `existing-session` / Chrome MCP +- Capturas de pantalla basadas en ref (`--ref`) de `existing-session` desde la salida de instantáneas -Lo que todavía necesita Playwright: +Lo que sigue necesitando Playwright: - `navigate` - `act` -- Snapshots AI / snapshots de rol -- Capturas de elementos con selector CSS (`--element`) +- Instantáneas AI / instantáneas de rol +- Capturas de pantalla de elementos con selector CSS (`--element`) - Exportación completa de PDF del navegador -Las capturas de elementos también rechazan `--full-page`; la ruta devuelve `fullPage is +Las capturas de pantalla de elementos también rechazan `--full-page`; la ruta devuelve `fullPage is not supported for element screenshots`. -Si ves `Playwright is not available in this gateway build`, instala el paquete completo -de Playwright (no `playwright-core`) y reinicia el gateway, o reinstala -OpenClaw con soporte para navegador. +Si ves `Playwright is not available in this gateway build`, instala el paquete completo de +Playwright (no `playwright-core`) y reinicia el gateway, o reinstala +OpenClaw con compatibilidad para navegador. #### Instalación de Playwright en Docker -Si tu Gateway se ejecuta en Docker, evita `npx playwright` (conflictos de anulación de npm). +Si tu Gateway se ejecuta en Docker, evita `npx playwright` (conflictos con las anulaciones de npm). Usa la CLI incluida en su lugar: ```bash @@ -621,7 +640,7 @@ docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -Para conservar las descargas del navegador, establece `PLAYWRIGHT_BROWSERS_PATH` (por ejemplo, +Para conservar las descargas del navegador, configura `PLAYWRIGHT_BROWSERS_PATH` (por ejemplo, `/home/node/.cache/ms-playwright`) y asegúrate de que `/home/node` se conserve mediante `OPENCLAW_HOME_VOLUME` o un bind mount. Consulta [Docker](/es/install/docker). @@ -631,19 +650,19 @@ Flujo de alto nivel: - Un pequeño **servidor de control** acepta solicitudes HTTP. - Se conecta a navegadores basados en Chromium (Chrome/Brave/Edge/Chromium) mediante **CDP**. -- Para acciones avanzadas (clic/escritura/snapshot/PDF), usa **Playwright** sobre +- Para acciones avanzadas (clic/escritura/instantánea/PDF), usa **Playwright** sobre CDP. - Cuando falta Playwright, solo están disponibles las operaciones que no usan Playwright. -Este diseño mantiene al agente sobre una interfaz estable y determinista, al tiempo que te permite cambiar -entre navegadores y perfiles locales/remotos. +Este diseño mantiene al agente sobre una interfaz estable y determinista, al tiempo que te permite +intercambiar navegadores y perfiles locales/remotos. ## Referencia rápida de la CLI Todos los comandos aceptan `--browser-profile ` para apuntar a un perfil específico. -Todos los comandos también aceptan `--json` para salida legible por máquina (payloads estables). +Todos los comandos también aceptan `--json` para salida legible por máquina (cargas útiles estables). -Básicos: +Aspectos básicos: - `openclaw browser status` - `openclaw browser start` @@ -674,10 +693,10 @@ Inspección: Nota sobre el ciclo de vida: -- Para perfiles solo adjuntos y CDP remotos, `openclaw browser stop` sigue siendo el - comando correcto de limpieza tras las pruebas. Cierra la sesión de control activa y - limpia las anulaciones temporales de emulación en lugar de matar el navegador - subyacente. +- Para perfiles de solo conexión y CDP remoto, `openclaw browser stop` sigue siendo el + comando de limpieza correcto después de las pruebas. Cierra la sesión de control activa y + borra las anulaciones temporales de emulación en lugar de cerrar el + navegador subyacente. - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -728,57 +747,57 @@ Estado: Notas: -- `upload` y `dialog` son llamadas de **preparación**; ejecútalas antes del clic/pulsación - que activa el selector/diálogo. -- Las rutas de salida de descargas y trazas están limitadas a raíces temporales de OpenClaw: - - trazas: `/tmp/openclaw` (respaldo: `${os.tmpdir()}/openclaw`) - - descargas: `/tmp/openclaw/downloads` (respaldo: `${os.tmpdir()}/openclaw/downloads`) -- Las rutas de subida están limitadas a una raíz temporal de subidas de OpenClaw: - - subidas: `/tmp/openclaw/uploads` (respaldo: `${os.tmpdir()}/openclaw/uploads`) -- `upload` también puede establecer entradas de archivo directamente mediante `--input-ref` o `--element`. +- `upload` y `dialog` son llamadas de **preparación**; ejecútalas antes del clic/tecla + que activa el selector de archivos o el cuadro de diálogo. +- Las rutas de salida de descargas y trazas están restringidas a las raíces temporales de OpenClaw: + - trazas: `/tmp/openclaw` (alternativa: `${os.tmpdir()}/openclaw`) + - descargas: `/tmp/openclaw/downloads` (alternativa: `${os.tmpdir()}/openclaw/downloads`) +- Las rutas de carga están restringidas a una raíz temporal de cargas de OpenClaw: + - cargas: `/tmp/openclaw/uploads` (alternativa: `${os.tmpdir()}/openclaw/uploads`) +- `upload` también puede configurar entradas de archivo directamente mediante `--input-ref` o `--element`. - `snapshot`: - - `--format ai` (predeterminado cuando Playwright está instalado): devuelve un snapshot AI con refs numéricos (`aria-ref=""`). + - `--format ai` (predeterminado cuando Playwright está instalado): devuelve una instantánea AI con refs numéricas (`aria-ref=""`). - `--format aria`: devuelve el árbol de accesibilidad (sin refs; solo inspección). - - `--efficient` (o `--mode efficient`): preajuste compacto de snapshot de rol (interactive + compact + depth + menor maxChars). - - Configuración predeterminada (solo herramienta/CLI): establece `browser.snapshotDefaults.mode: "efficient"` para usar snapshots eficientes cuando quien llama no pasa un modo (consulta [Configuración del Gateway](/es/gateway/configuration-reference#browser)). - - Las opciones de snapshot de rol (`--interactive`, `--compact`, `--depth`, `--selector`) fuerzan un snapshot basado en roles con refs como `ref=e12`. - - `--frame "