chore(i18n): refresh es translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
b4c04744c6
commit
cc86147848
@ -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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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 <lookup>
|
||||
|
||||
# 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 <lookup>
|
||||
|
||||
# Cambiar la política de notificaciones de una tarea
|
||||
# Cambia la política de notificación de una tarea
|
||||
openclaw tasks notify <lookup> 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 <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
@ -74,25 +74,25 @@ openclaw tasks flow cancel <lookup>
|
||||
|
||||
## 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.
|
||||
|
||||
<Tip>
|
||||
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.
|
||||
</Tip>
|
||||
|
||||
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 <lookup>
|
||||
```
|
||||
|
||||
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 <lookup>
|
||||
```
|
||||
|
||||
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 <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
613
docs/es/concepts/active-memory.md
Normal file
613
docs/es/concepts/active-memory.md
Normal file
@ -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 `<active_memory_plugin>...</active_memory_plugin>` 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/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.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)
|
||||
@ -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.
|
||||
|
||||
<Tip>
|
||||
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.
|
||||
</Tip>
|
||||
|
||||
### 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.
|
||||
|
||||
<Tip>
|
||||
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.
|
||||
</Tip>
|
||||
|
||||
### 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
|
||||
|
||||
@ -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=<level>`. `--thinking <level>` sigue estableciendo un
|
||||
respaldo global, y la forma anterior `--model-thinking <provider/model=level>` se
|
||||
valor de respaldo global, y la forma anterior `--model-thinking <provider/model=level>` 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)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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 |
|
||||
|
||||
<Warning>
|
||||
Cambiar el modelo o `outputDimensionality` activa automáticamente una reindexación completa.
|
||||
Cambiar el modelo o `outputDimensionality` desencadena una reindexación completa automática.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## 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:<id>:`.
|
||||
`match.rawKeyPrefix` coincide con la clave sin procesar, incluido `agent:<id>:`.
|
||||
|
||||
### Citas
|
||||
|
||||
`memory.citations` se aplica a todos los backends:
|
||||
|
||||
| Valor | Comportamiento |
|
||||
| ---------------- | --------------------------------------------------- |
|
||||
| `auto` (predeterminado) | Incluir pie `Source: <path#line>` en los fragmentos |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `auto` (predeterminado) | Incluir el pie `Source: <path#line>` 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.
|
||||
|
||||
@ -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.<name>.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.<name>.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.<name>.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.<name>.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 `<BROWSERLESS_API_KEY>` por tu token real de Browserless.
|
||||
- Reemplaza `<BROWSERLESS_API_KEY>` 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 `<BROWSERBASE_API_KEY>` 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 `<BROWSERBASE_API_KEY>` 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=<name>`; 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=<name>`.
|
||||
|
||||
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 <gateway token>`
|
||||
- `x-openclaw-password: <gateway 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": "<message>", "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": "<message>" }` 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 <name>` 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="<n>"`).
|
||||
- `--format ai` (predeterminado cuando Playwright está instalado): devuelve una instantánea AI con refs numéricas (`aria-ref="<n>"`).
|
||||
- `--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 "<iframe selector>"` limita los snapshots de rol a un iframe (se combina con refs de rol como `e12`).
|
||||
- `--efficient` (o `--mode efficient`): preajuste de instantánea compacta por rol (interactiva + compacta + profundidad + `maxChars` más bajo).
|
||||
- Predeterminado de configuración (solo herramienta/CLI): configura `browser.snapshotDefaults.mode: "efficient"` para usar instantáneas eficientes cuando quien llama no pasa un modo (consulta [Configuración del Gateway](/es/gateway/configuration-reference#browser)).
|
||||
- Las opciones de instantánea por rol (`--interactive`, `--compact`, `--depth`, `--selector`) fuerzan una instantánea basada en roles con refs como `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita las instantáneas por rol a un iframe (se combina con refs por rol como `e12`).
|
||||
- `--interactive` genera una lista plana y fácil de elegir de elementos interactivos (lo mejor para ejecutar acciones).
|
||||
- `--labels` agrega una captura de pantalla solo del viewport con etiquetas de ref superpuestas (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc requieren un `ref` de `snapshot` (ya sea numérico `12` o ref de rol `e12`).
|
||||
Los selectores CSS no son compatibles intencionalmente para acciones.
|
||||
- `--labels` agrega una captura de pantalla solo de la ventana gráfica con etiquetas ref superpuestas (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc. requieren una `ref` de `snapshot` (ya sea numérica `12` o ref por rol `e12`).
|
||||
Los selectores CSS no se admiten intencionalmente para acciones.
|
||||
|
||||
## Snapshots y refs
|
||||
## Instantáneas y refs
|
||||
|
||||
OpenClaw admite dos estilos de “snapshot”:
|
||||
|
||||
- **Snapshot AI (refs numéricos)**: `openclaw browser snapshot` (predeterminado; `--format ai`)
|
||||
- Salida: un snapshot de texto que incluye refs numéricos.
|
||||
- **Instantánea AI (refs numéricas)**: `openclaw browser snapshot` (predeterminado; `--format ai`)
|
||||
- Salida: una instantánea de texto que incluye refs numéricas.
|
||||
- Acciones: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Internamente, el ref se resuelve mediante `aria-ref` de Playwright.
|
||||
- Internamente, la ref se resuelve mediante `aria-ref` de Playwright.
|
||||
|
||||
- **Snapshot de rol (refs de rol como `e12`)**: `openclaw browser snapshot --interactive` (o `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- **Instantánea por rol (refs por rol como `e12`)**: `openclaw browser snapshot --interactive` (o `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Salida: una lista/árbol basado en roles con `[ref=e12]` (y opcionalmente `[nth=1]`).
|
||||
- Acciones: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- Internamente, el ref se resuelve mediante `getByRole(...)` (más `nth()` para duplicados).
|
||||
- Agrega `--labels` para incluir una captura de pantalla del viewport con etiquetas `e12` superpuestas.
|
||||
- Internamente, la ref se resuelve mediante `getByRole(...)` (más `nth()` para duplicados).
|
||||
- Agrega `--labels` para incluir una captura de pantalla de la ventana gráfica con etiquetas `e12` superpuestas.
|
||||
|
||||
Comportamiento de los refs:
|
||||
Comportamiento de las refs:
|
||||
|
||||
- Los refs **no son estables entre navegaciones**; si algo falla, vuelve a ejecutar `snapshot` y usa un ref nuevo.
|
||||
- Si el snapshot de rol se tomó con `--frame`, los refs de rol quedan limitados a ese iframe hasta el siguiente snapshot de rol.
|
||||
- Las refs **no son estables entre navegaciones**; si algo falla, vuelve a ejecutar `snapshot` y usa una ref nueva.
|
||||
- Si la instantánea por rol se tomó con `--frame`, las refs por rol quedan limitadas a ese iframe hasta la siguiente instantánea por rol.
|
||||
|
||||
## Potenciadores de wait
|
||||
## Mejoras de `wait`
|
||||
|
||||
Puedes esperar algo más que tiempo/texto:
|
||||
Puedes esperar algo más que solo tiempo/texto:
|
||||
|
||||
- Esperar una URL (globs admitidos por Playwright):
|
||||
- Esperar URL (globs compatibles con Playwright):
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
- Esperar un estado de carga:
|
||||
- Esperar estado de carga:
|
||||
- `openclaw browser wait --load networkidle`
|
||||
- Esperar un predicado JS:
|
||||
- Esperar un predicado de JS:
|
||||
- `openclaw browser wait --fn "window.ready===true"`
|
||||
- Esperar a que un selector sea visible:
|
||||
- Esperar a que un selector se vuelva visible:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
Se pueden combinar:
|
||||
@ -793,22 +812,22 @@ openclaw browser wait "#main" \
|
||||
|
||||
## Flujos de depuración
|
||||
|
||||
Cuando una acción falla (por ejemplo, “not visible”, “strict mode violation”, “covered”):
|
||||
Cuando falla una acción (por ejemplo, “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Usa `click <ref>` / `type <ref>` (prefiere refs de rol en modo interactivo)
|
||||
2. Usa `click <ref>` / `type <ref>` (prefiere refs por rol en modo interactivo)
|
||||
3. Si sigue fallando: `openclaw browser highlight <ref>` para ver a qué apunta Playwright
|
||||
4. Si la página se comporta de forma extraña:
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
5. Para depuración profunda: graba una traza:
|
||||
5. Para una depuración profunda: graba una traza:
|
||||
- `openclaw browser trace start`
|
||||
- reproduce el problema
|
||||
- `openclaw browser trace stop` (imprime `TRACE:<path>`)
|
||||
|
||||
## Salida JSON
|
||||
|
||||
`--json` es para scripting y herramientas estructuradas.
|
||||
`--json` es para scripts y herramientas estructuradas.
|
||||
|
||||
Ejemplos:
|
||||
|
||||
@ -819,7 +838,7 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
Los snapshots de rol en JSON incluyen `refs` más un pequeño bloque `stats` (líneas/caracteres/refs/interactivos) para que las herramientas puedan razonar sobre el tamaño y la densidad del payload.
|
||||
Las instantáneas por rol en JSON incluyen `refs` más un pequeño bloque `stats` (líneas/caracteres/refs/interactivos) para que las herramientas puedan razonar sobre el tamaño y la densidad de la carga útil.
|
||||
|
||||
## Controles de estado y entorno
|
||||
|
||||
@ -828,23 +847,23 @@ Son útiles para flujos de trabajo de “hacer que el sitio se comporte como X
|
||||
- Cookies: `cookies`, `cookies set`, `cookies clear`
|
||||
- Storage: `storage local|session get|set|clear`
|
||||
- Sin conexión: `set offline on|off`
|
||||
- Cabeceras: `set headers --headers-json '{"X-Debug":"1"}'` (el heredado `set headers --json '{"X-Debug":"1"}'` sigue siendo compatible)
|
||||
- Encabezados: `set headers --headers-json '{"X-Debug":"1"}'` (el heredado `set headers --json '{"X-Debug":"1"}'` sigue siendo compatible)
|
||||
- Autenticación HTTP Basic: `set credentials user pass` (o `--clear`)
|
||||
- Geolocalización: `set geo <lat> <lon> --origin "https://example.com"` (o `--clear`)
|
||||
- Multimedia: `set media dark|light|no-preference|none`
|
||||
- Medios: `set media dark|light|no-preference|none`
|
||||
- Zona horaria / configuración regional: `set timezone ...`, `set locale ...`
|
||||
- Dispositivo / viewport:
|
||||
- `set device "iPhone 14"` (preajustes de dispositivos Playwright)
|
||||
- Dispositivo / ventana gráfica:
|
||||
- `set device "iPhone 14"` (preajustes de dispositivos de Playwright)
|
||||
- `set viewport 1280 720`
|
||||
|
||||
## Seguridad y privacidad
|
||||
|
||||
- El perfil del navegador openclaw puede contener sesiones con inicio de sesión; trátalo como información sensible.
|
||||
- El perfil de navegador openclaw puede contener sesiones con inicio de sesión; trátalo como información sensible.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` y `wait --fn`
|
||||
ejecutan JavaScript arbitrario en el contexto de la página. La inyección de prompts puede dirigir
|
||||
esto. Desactívalo con `browser.evaluateEnabled=false` si no lo necesitas.
|
||||
- Para notas sobre inicios de sesión y anti-bot (X/Twitter, etc.), consulta [Inicio de sesión en el navegador + publicación en X/Twitter](/tools/browser-login).
|
||||
- Mantén el Gateway/host node en privado (solo loopback o tailnet).
|
||||
- Para inicios de sesión y notas anti-bot (X/Twitter, etc.), consulta [Inicio de sesión en navegador + publicación en X/Twitter](/es/tools/browser-login).
|
||||
- Mantén el Gateway/host de nodo privado (solo loopback o tailnet).
|
||||
- Los endpoints CDP remotos son potentes; túnelalos y protégelos.
|
||||
|
||||
Ejemplo de modo estricto (bloquear destinos privados/internos de forma predeterminada):
|
||||
@ -855,7 +874,7 @@ Ejemplo de modo estricto (bloquear destinos privados/internos de forma predeterm
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: false,
|
||||
hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
allowedHostnames: ["localhost"], // optional exact allow
|
||||
allowedHostnames: ["localhost"], // permiso exacto opcional
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -863,11 +882,11 @@ Ejemplo de modo estricto (bloquear destinos privados/internos de forma predeterm
|
||||
|
||||
## Solución de problemas
|
||||
|
||||
Para problemas específicos de Linux (especialmente snap Chromium), consulta
|
||||
[Solución de problemas del navegador](/tools/browser-linux-troubleshooting).
|
||||
Para problemas específicos de Linux (especialmente Chromium de snap), consulta
|
||||
[Solución de problemas del navegador](/es/tools/browser-linux-troubleshooting).
|
||||
|
||||
Para configuraciones divididas WSL2 Gateway + Windows Chrome en hosts distintos, consulta
|
||||
[Solución de problemas de WSL2 + Windows + Chrome remoto por CDP](/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
Para configuraciones divididas entre Gateway en WSL2 + Chrome en Windows, consulta
|
||||
[Solución de problemas de WSL2 + Windows + Chrome remoto por CDP](/es/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
## Herramientas del agente + cómo funciona el control
|
||||
|
||||
@ -875,22 +894,22 @@ El agente obtiene **una herramienta** para la automatización del navegador:
|
||||
|
||||
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
|
||||
|
||||
Cómo se mapea:
|
||||
Cómo se asigna:
|
||||
|
||||
- `browser snapshot` devuelve un árbol de interfaz estable (AI o ARIA).
|
||||
- `browser act` usa los ID `ref` del snapshot para hacer clic/escribir/arrastrar/seleccionar.
|
||||
- `browser snapshot` devuelve un árbol de UI estable (AI o ARIA).
|
||||
- `browser act` usa los ID `ref` de la instantánea para hacer clic/escribir/arrastrar/seleccionar.
|
||||
- `browser screenshot` captura píxeles (página completa o elemento).
|
||||
- `browser` acepta:
|
||||
- `profile` para elegir un perfil de navegador con nombre (openclaw, chrome o CDP remoto).
|
||||
- `target` (`sandbox` | `host` | `node`) para seleccionar dónde vive el navegador.
|
||||
- En sesiones con sandbox, `target: "host"` requiere `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Si se omite `target`: las sesiones con sandbox usan `sandbox` de forma predeterminada, las sesiones sin sandbox usan `host`.
|
||||
- Si hay un nodo con capacidad de navegador conectado, la herramienta puede redirigirse automáticamente a él a menos que fijes `target="host"` o `target="node"`.
|
||||
- En sesiones aisladas en sandbox, `target: "host"` requiere `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Si se omite `target`: las sesiones en sandbox usan `sandbox` de forma predeterminada, las sesiones sin sandbox usan `host`.
|
||||
- Si hay conectado un nodo con capacidad de navegador, la herramienta puede redirigirse automáticamente a él a menos que fijes `target="host"` o `target="node"`.
|
||||
|
||||
Esto mantiene al agente determinista y evita selectores frágiles.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Resumen de herramientas](/tools) — todas las herramientas de agente disponibles
|
||||
- [Sandboxing](/es/gateway/sandboxing) — control del navegador en entornos con sandbox
|
||||
- [Seguridad](/es/gateway/security) — riesgos y endurecimiento del control del navegador
|
||||
- [Resumen de herramientas](/es/tools) — todas las herramientas del agente disponibles
|
||||
- [Sandboxing](/es/gateway/sandboxing) — control del navegador en entornos aislados
|
||||
- [Security](/es/gateway/security) — riesgos y endurecimiento del control del navegador
|
||||
|
||||
Loading…
Reference in New Issue
Block a user