diff --git a/docs/es/automation/cron-jobs.md b/docs/es/automation/cron-jobs.md index ae3f35dc8..28e2ce8b7 100644 --- a/docs/es/automation/cron-jobs.md +++ b/docs/es/automation/cron-jobs.md @@ -1,22 +1,22 @@ --- read_when: - - Programación de tareas en segundo plano o activaciones - - Conexión de desencadenadores externos (webhooks, Gmail) a OpenClaw + - Programación de trabajos en segundo plano o activaciones + - Conectar desencadenadores externos (webhooks, Gmail) a OpenClaw - Decidir entre heartbeat y cron para las tareas programadas -summary: Trabajos programados, webhooks y desencadenadores de PubSub de Gmail para el programador del Gateway +summary: Trabajos programados, webhooks y desencadenadores de Gmail PubSub para el programador del Gateway title: Tareas programadas x-i18n: - generated_at: "2026-04-11T02:44:18Z" + generated_at: "2026-04-12T05:11:01Z" model: gpt-5.4 provider: openai - source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665 + source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f source_path: automation/cron-jobs.md workflow: 15 --- # Tareas programadas (Cron) -Cron es el programador integrado del Gateway. Conserva los trabajos, activa al agente en el momento adecuado y puede devolver la salida a un canal de chat o a un endpoint de webhook. +Cron es el programador integrado del Gateway. Conserva los trabajos, activa el agente en el momento adecuado y puede entregar la salida de vuelta a un canal de chat o a un endpoint de webhook. ## Inicio rápido @@ -39,84 +39,96 @@ openclaw cron runs --id ## Cómo funciona cron -- Cron se ejecuta **dentro del proceso Gateway** (no dentro del modelo). -- Los trabajos se conservan en `~/.openclaw/cron/jobs.json`, por lo que los reinicios no hacen perder la programación. -- Todas las ejecuciones de cron crean registros de [tarea en segundo plano](/es/automation/tasks). -- Los trabajos de una sola ejecución (`--at`) se eliminan automáticamente después de completarse con éxito de forma predeterminada. -- Las ejecuciones aisladas de cron intentan cerrar, en la medida de lo posible, las pestañas/procesos del navegador rastreados para su sesión `cron:` cuando la ejecución termina, para que la automatización desacoplada del navegador no deje procesos huérfanos. -- Las ejecuciones aisladas de cron también protegen contra respuestas de confirmación obsoletas. Si el primer resultado es solo una actualización de estado provisional (`on it`, `pulling everything together` y pistas similares) y ninguna ejecución descendiente de subagente sigue siendo responsable de la respuesta final, OpenClaw vuelve a hacer un prompt una vez para obtener el resultado real antes de entregarlo. +- Cron se ejecuta **dentro del** proceso del Gateway (no dentro del modelo). +- Los trabajos se conservan en `~/.openclaw/cron/jobs.json`, por lo que los reinicios no pierden las programaciones. +- Todas las ejecuciones de cron crean registros de [tareas en segundo plano](/es/automation/tasks). +- Los trabajos de una sola ejecución (`--at`) se eliminan automáticamente después de un éxito de forma predeterminada. +- Las ejecuciones aisladas de cron cierran, en la medida de lo posible, las pestañas/procesos del navegador rastreados para su sesión `cron:` cuando la ejecución se completa, para que la automatización desacoplada del navegador no deje procesos huérfanos. +- Las ejecuciones aisladas de cron también protegen contra respuestas de confirmación obsoletas. Si el primer resultado es solo una actualización provisional de estado (`on it`, `pulling everything together` y pistas similares) y ninguna ejecución descendiente de subagente sigue siendo responsable de la respuesta final, OpenClaw vuelve a solicitar una vez el resultado real antes de entregarlo. -La reconciliación de tareas para cron es propiedad del runtime: una tarea de cron activa sigue viva mientras el runtime de cron siga rastreando ese trabajo como en ejecución, incluso si todavía existe una fila antigua de sesión hija. +La conciliación de tareas para cron es propiedad del runtime: una tarea cron activa permanece activa mientras el runtime de cron siga rastreando ese trabajo como en ejecución, incluso si todavía existe una fila antigua de sesión hija. Una vez que el runtime deja de ser propietario del trabajo y expira el período de gracia de 5 minutos, el mantenimiento puede marcar la tarea como `lost`. ## Tipos de programación -| Tipo | Indicador CLI | Descripción | -| ------- | ------------- | ------------------------------------------------------------- | -| `at` | `--at` | Marca de tiempo de una sola ejecución (ISO 8601 o relativa como `20m`) | -| `every` | `--every` | Intervalo fijo | -| `cron` | `--cron` | Expresión cron de 5 o 6 campos con `--tz` opcional | +| Tipo | Indicador de CLI | Descripción | +| ------- | ---------------- | ------------------------------------------------------- | +| `at` | `--at` | Marca de tiempo de una sola ejecución (ISO 8601 o relativa como `20m`) | +| `every` | `--every` | Intervalo fijo | +| `cron` | `--cron` | Expresión cron de 5 campos o 6 campos con `--tz` opcional | -Las marcas de tiempo sin zona horaria se tratan como UTC. Agrega `--tz America/New_York` para programación según la hora local. +Las marcas de tiempo sin zona horaria se tratan como UTC. Agrega `--tz America/New_York` para una programación en hora local de reloj. -Las expresiones recurrentes al inicio de cada hora se escalonan automáticamente hasta 5 minutos para reducir picos de carga. Usa `--exact` para forzar una sincronización precisa o `--stagger 30s` para una ventana explícita. +Las expresiones recurrentes al comienzo de cada hora se escalonan automáticamente hasta 5 minutos para reducir los picos de carga. Usa `--exact` para forzar una sincronización precisa o `--stagger 30s` para una ventana explícita. + +### El día del mes y el día de la semana usan lógica OR + +Las expresiones cron son analizadas por [croner](https://github.com/Hexagon/croner). Cuando tanto los campos de día del mes como de día de la semana no son comodines, croner coincide cuando **cualquiera** de los campos coincide, no ambos. Este es el comportamiento estándar de Vixie cron. + +``` +# Intended: "9 AM on the 15th, only if it's a Monday" +# Actual: "9 AM on every 15th, AND 9 AM on every Monday" +0 9 15 * 1 +``` + +Esto se activa ~5–6 veces por mes en lugar de 0–1 vez por mes. OpenClaw usa aquí el comportamiento OR predeterminado de Croner. Para requerir ambas condiciones, usa el modificador de día de la semana `+` de Croner (`0 9 15 * +1`) o programa en un campo y valida el otro en el prompt o comando de tu trabajo. ## Estilos de ejecución -| Estilo | valor de `--session` | Se ejecuta en | Ideal para | -| --------------- | -------------------- | ------------------------ | ------------------------------ | +| Estilo | Valor de `--session` | Se ejecuta en | Ideal para | +| --------------- | -------------------- | ------------------------- | ------------------------------ | | Sesión principal | `main` | Siguiente turno de heartbeat | Recordatorios, eventos del sistema | -| Aislado | `isolated` | `cron:` dedicado | Informes, tareas en segundo plano | -| Sesión actual | `current` | Vinculado en el momento de la creación | Trabajo recurrente con contexto | +| Aislado | `isolated` | `cron:` dedicado | Informes, tareas en segundo plano | +| Sesión actual | `current` | Vinculada en el momento de creación | Trabajo recurrente con contexto | | Sesión personalizada | `session:custom-id` | Sesión nombrada persistente | Flujos de trabajo que se basan en el historial | -Los trabajos de **sesión principal** ponen en cola un evento del sistema y, opcionalmente, activan el heartbeat (`--wake now` o `--wake next-heartbeat`). Los trabajos **aislados** ejecutan un turno de agente dedicado con una sesión nueva. Las **sesiones personalizadas** (`session:xxx`) conservan el contexto entre ejecuciones, lo que permite flujos de trabajo como reuniones diarias que se basan en resúmenes anteriores. +Los trabajos de **sesión principal** encolan un evento del sistema y opcionalmente activan el heartbeat (`--wake now` o `--wake next-heartbeat`). Los trabajos **aislados** ejecutan un turno de agente dedicado con una sesión nueva. Las **sesiones personalizadas** (`session:xxx`) conservan el contexto entre ejecuciones, lo que permite flujos de trabajo como resúmenes diarios que se basan en resúmenes anteriores. -Para los trabajos aislados, el desmontaje del runtime ahora incluye una limpieza del navegador para esa sesión de cron en la medida de lo posible. Los fallos de limpieza se ignoran para que el resultado real de cron siga teniendo prioridad. +Para los trabajos aislados, el desmontaje del runtime ahora incluye una limpieza del navegador en la medida de lo posible para esa sesión cron. Los fallos de limpieza se ignoran para que el resultado real de cron siga prevaleciendo. -Cuando las ejecuciones aisladas de cron orquestan subagentes, la entrega también prioriza la salida final descendiente sobre el texto provisional obsoleto del padre. Si los descendientes todavía se están ejecutando, OpenClaw suprime esa actualización parcial del padre en lugar de anunciarla. +Cuando las ejecuciones aisladas de cron orquestan subagentes, la entrega también prefiere la salida final descendiente sobre el texto provisional obsoleto del padre. Si los descendientes todavía se están ejecutando, OpenClaw suprime esa actualización parcial del padre en lugar de anunciarla. ### Opciones de payload para trabajos aislados - `--message`: texto del prompt (obligatorio para aislado) -- `--model` / `--thinking`: anulaciones del modelo y del nivel de razonamiento -- `--light-context`: omite la inyección de archivos de arranque del espacio de trabajo -- `--tools exec,read`: restringe qué herramientas puede usar el trabajo +- `--model` / `--thinking`: reemplazos del modelo y nivel de razonamiento +- `--light-context`: omitir la inyección de archivos de arranque del espacio de trabajo +- `--tools exec,read`: restringir qué herramientas puede usar el trabajo -`--model` usa el modelo permitido seleccionado para ese trabajo. Si el modelo solicitado no está permitido, cron registra una advertencia y vuelve a la selección de modelo predeterminada o del agente del trabajo. Las cadenas de fallback configuradas siguen aplicándose, pero una simple anulación de modelo sin una lista explícita de fallback por trabajo ya no agrega el primario del agente como un objetivo extra de reintento oculto. +`--model` usa el modelo permitido seleccionado para ese trabajo. Si el modelo solicitado no está permitido, cron registra una advertencia y vuelve a la selección de modelo del agente/predeterminada del trabajo. Las cadenas de respaldo configuradas siguen aplicándose, pero un simple reemplazo de modelo sin una lista explícita de respaldo por trabajo ya no añade el primario del agente como un objetivo adicional de reintento oculto. La precedencia de selección de modelo para trabajos aislados es: -1. Anulación de modelo del hook de Gmail (cuando la ejecución vino de Gmail y esa anulación está permitida) +1. Reemplazo de modelo del hook de Gmail (cuando la ejecución provino de Gmail y ese reemplazo está permitido) 2. `model` del payload por trabajo -3. Anulación de modelo conservada en la sesión de cron -4. Selección de modelo predeterminada o del agente +3. Reemplazo de modelo de la sesión cron almacenada +4. Selección de modelo del agente/predeterminada -El modo rápido también sigue la selección activa resuelta. Si la configuración del modelo seleccionado tiene `params.fastMode`, el cron aislado lo usa de forma predeterminada. Una anulación almacenada de `fastMode` en la sesión sigue teniendo prioridad sobre la configuración en cualquier dirección. +El modo rápido también sigue la selección activa resuelta. Si la configuración del modelo seleccionado tiene `params.fastMode`, el cron aislado lo usa de forma predeterminada. Un reemplazo almacenado de `fastMode` en la sesión sigue teniendo prioridad sobre la configuración en cualquier dirección. -Si una ejecución aislada encuentra una transferencia activa de cambio de modelo, cron vuelve a intentar con el proveedor/modelo cambiado y conserva esa selección activa antes de reintentar. Cuando el cambio también incluye un nuevo perfil de autenticación, cron también conserva esa anulación del perfil de autenticación. Los reintentos están limitados: después del intento inicial más 2 reintentos por cambio, cron aborta en lugar de entrar en un bucle infinito. +Si una ejecución aislada encuentra una transferencia en vivo de cambio de modelo, cron reintenta con el proveedor/modelo cambiado y conserva esa selección activa antes de reintentar. Cuando el cambio también incluye un nuevo perfil de autenticación, cron también conserva ese reemplazo del perfil de autenticación. Los reintentos están acotados: después del intento inicial más 2 reintentos por cambio, cron aborta en lugar de entrar en un bucle infinito. ## Entrega y salida -| Modo | Qué sucede | -| --------- | ----------------------------------------------------------- | +| Modo | Qué sucede | +| --------- | ------------------------------------------------------- | | `announce` | Entrega un resumen al canal de destino (predeterminado para aislado) | -| `webhook` | Envía por POST el payload del evento finalizado a una URL | -| `none` | Solo interno, sin entrega | +| `webhook` | Hace POST del payload del evento finalizado a una URL | +| `none` | Solo interno, sin entrega | -Usa `--announce --channel telegram --to "-1001234567890"` para entrega al canal. Para temas de foros de Telegram, usa `-1001234567890:topic:123`. Los destinos de Slack/Discord/Mattermost deben usar prefijos explícitos (`channel:`, `user:`). +Usa `--announce --channel telegram --to "-1001234567890"` para la entrega al canal. Para temas de foro de Telegram, usa `-1001234567890:topic:123`. Los destinos de Slack/Discord/Mattermost deben usar prefijos explícitos (`channel:`, `user:`). -Para trabajos aislados propiedad de cron, el ejecutor es propietario de la ruta de entrega final. Al agente se le pide que devuelva un resumen en texto plano, y luego ese resumen se envía mediante `announce`, `webhook` o se conserva internamente para `none`. `--no-deliver` no devuelve la entrega al agente; mantiene la ejecución como interna. +Para trabajos aislados propiedad de cron, el ejecutor es responsable de la ruta de entrega final. Se solicita al agente que devuelva un resumen en texto plano, y ese resumen luego se envía mediante `announce`, `webhook` o se mantiene interno para `none`. `--no-deliver` no devuelve la entrega al agente; mantiene la ejecución como interna. -Si la tarea original indica explícitamente que se debe enviar un mensaje a algún destinatario externo, el agente debe indicar quién/dónde debe recibir ese mensaje en su salida en lugar de intentar enviarlo directamente. +Si la tarea original indica explícitamente enviar un mensaje a algún destinatario externo, el agente debe indicar a quién/dónde debe ir ese mensaje en su salida en lugar de intentar enviarlo directamente. Las notificaciones de fallo siguen una ruta de destino separada: -- `cron.failureDestination` establece un valor predeterminado global para las notificaciones de fallo. -- `job.delivery.failureDestination` lo anula por trabajo. -- Si ninguno está configurado y el trabajo ya entrega mediante `announce`, las notificaciones de fallo ahora recurren a ese destino principal de anuncio. +- `cron.failureDestination` establece un valor global predeterminado para las notificaciones de fallo. +- `job.delivery.failureDestination` lo reemplaza por trabajo. +- Si ninguno está configurado y el trabajo ya entrega mediante `announce`, las notificaciones de fallo ahora vuelven a ese destino principal de anuncio. - `delivery.failureDestination` solo es compatible con trabajos `sessionTarget="isolated"` a menos que el modo principal de entrega sea `webhook`. ## Ejemplos de CLI @@ -132,7 +144,7 @@ openclaw cron add \ --wake now ``` -Trabajo recurrente aislado con entrega: +Trabajo aislado recurrente con entrega: ```bash openclaw cron add \ @@ -146,7 +158,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -Trabajo aislado con anulación de modelo y razonamiento: +Trabajo aislado con reemplazo de modelo y nivel de razonamiento: ```bash openclaw cron add \ @@ -185,7 +197,7 @@ Los tokens en la cadena de consulta se rechazan. ### POST /hooks/wake -Pone en cola un evento del sistema para la sesión principal: +Encola un evento del sistema para la sesión principal: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -212,23 +224,23 @@ Campos: `message` (obligatorio), `name`, `agentId`, `wakeMode`, `deliver`, `chan ### Hooks mapeados (POST /hooks/\) -Los nombres de hook personalizados se resuelven mediante `hooks.mappings` en la configuración. Los mapeos pueden transformar payloads arbitrarios en acciones `wake` o `agent` con plantillas o transformaciones de código. +Los nombres de hook personalizados se resuelven mediante `hooks.mappings` en la configuración. Las asignaciones pueden transformar payloads arbitrarios en acciones `wake` o `agent` con plantillas o transformaciones de código. ### Seguridad - Mantén los endpoints de hook detrás de loopback, tailnet o un proxy inverso de confianza. - Usa un token de hook dedicado; no reutilices tokens de autenticación del gateway. - Mantén `hooks.path` en una subruta dedicada; `/` se rechaza. -- Configura `hooks.allowedAgentIds` para limitar el enrutamiento explícito de `agentId`. -- Mantén `hooks.allowRequestSessionKey=false` a menos que necesites sesiones seleccionadas por quien llama. -- Si habilitas `hooks.allowRequestSessionKey`, también configura `hooks.allowedSessionKeyPrefixes` para restringir las formas permitidas de la clave de sesión. +- Establece `hooks.allowedAgentIds` para limitar el enrutamiento explícito de `agentId`. +- Mantén `hooks.allowRequestSessionKey=false` a menos que necesites sesiones seleccionadas por el solicitante. +- Si habilitas `hooks.allowRequestSessionKey`, establece también `hooks.allowedSessionKeyPrefixes` para restringir las formas permitidas de la clave de sesión. - Los payloads del hook se encapsulan con límites de seguridad de forma predeterminada. ## Integración de Gmail PubSub -Conecta los desencadenadores del buzón de Gmail a OpenClaw mediante Google PubSub. +Conecta desencadenadores del buzón de Gmail a OpenClaw mediante Google PubSub. -**Requisitos previos**: CLI de `gcloud`, `gog` (gogcli), hooks de OpenClaw habilitados, Tailscale para el endpoint HTTPS público. +**Requisitos previos**: CLI de `gcloud`, `gog` (gogcli), hooks de OpenClaw habilitados, Tailscale para el endpoint público HTTPS. ### Configuración con asistente (recomendada) @@ -240,11 +252,11 @@ Esto escribe la configuración `hooks.gmail`, habilita el ajuste preestablecido ### Inicio automático del Gateway -Cuando `hooks.enabled=true` y `hooks.gmail.account` está configurado, el Gateway inicia `gog gmail watch serve` al arrancar y renueva automáticamente la suscripción de watch. Configura `OPENCLAW_SKIP_GMAIL_WATCHER=1` para excluirte. +Cuando `hooks.enabled=true` y `hooks.gmail.account` está configurado, el Gateway inicia `gog gmail watch serve` al arrancar y renueva automáticamente la suscripción. Establece `OPENCLAW_SKIP_GMAIL_WATCHER=1` para excluirte. ### Configuración manual de una sola vez -1. Selecciona el proyecto de GCP que es propietario del cliente OAuth usado por `gog`: +1. Selecciona el proyecto de GCP que posee el cliente OAuth usado por `gog`: ```bash gcloud auth login @@ -252,7 +264,7 @@ gcloud config set project gcloud services enable gmail.googleapis.com pubsub.googleapis.com ``` -2. Crea el tema y otorga a Gmail acceso de push: +2. Crea el tema y concede acceso push de Gmail: ```bash gcloud pubsub topics create gog-gmail-watch @@ -261,7 +273,7 @@ gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ --role=roles/pubsub.publisher ``` -3. Inicia la suscripción de watch: +3. Inicia la suscripción: ```bash gog gmail watch start \ @@ -270,7 +282,7 @@ gog gmail watch start \ --topic projects//topics/gog-gmail-watch ``` -### Anulación de modelo de Gmail +### Reemplazo de modelo de Gmail ```json5 { @@ -283,7 +295,7 @@ gog gmail watch start \ } ``` -## Gestión de trabajos +## Administrar trabajos ```bash # List all jobs @@ -309,12 +321,12 @@ openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --mes openclaw cron edit --clear-agent ``` -Nota sobre la anulación de modelo: +Nota sobre el reemplazo de modelo: - `openclaw cron add|edit --model ...` cambia el modelo seleccionado del trabajo. -- Si el modelo está permitido, ese proveedor/modelo exacto llega a la ejecución aislada del agente. -- Si no está permitido, cron muestra una advertencia y vuelve a la selección de modelo predeterminada o del agente del trabajo. -- Las cadenas de fallback configuradas siguen aplicándose, pero una simple anulación con `--model` sin una lista explícita de fallback por trabajo ya no recurre al primario del agente como un objetivo adicional de reintento silencioso. +- Si el modelo está permitido, ese proveedor/modelo exacto llega a la ejecución del agente aislado. +- Si no está permitido, cron muestra una advertencia y vuelve a la selección de modelo del agente/predeterminada del trabajo. +- Las cadenas de respaldo configuradas siguen aplicándose, pero un simple reemplazo con `--model` sin una lista explícita de respaldo por trabajo ya no recurre al primario del agente como un objetivo adicional de reintento silencioso. ## Configuración @@ -338,15 +350,15 @@ Nota sobre la anulación de modelo: Desactiva cron: `cron.enabled: false` o `OPENCLAW_SKIP_CRON=1`. -**Reintento de una sola ejecución**: los errores transitorios (límite de tasa, sobrecarga, red, error del servidor) se reintentan hasta 3 veces con backoff exponencial. Los errores permanentes se desactivan de inmediato. +**Reintento de una sola ejecución**: los errores transitorios (límite de velocidad, sobrecarga, red, error del servidor) se reintentan hasta 3 veces con retroceso exponencial. Los errores permanentes se desactivan de inmediato. -**Reintento recurrente**: backoff exponencial (de 30s a 60m) entre reintentos. El backoff se restablece después de la siguiente ejecución correcta. +**Reintento recurrente**: retroceso exponencial (de 30s a 60m) entre reintentos. El retroceso se restablece después de la siguiente ejecución exitosa. **Mantenimiento**: `cron.sessionRetention` (predeterminado `24h`) elimina las entradas de sesión de ejecuciones aisladas. `cron.runLog.maxBytes` / `cron.runLog.keepLines` eliminan automáticamente los archivos de registro de ejecución. ## Solución de problemas -### Escalera de comandos +### Secuencia de comandos ```bash openclaw status @@ -359,30 +371,30 @@ openclaw logs --follow openclaw doctor ``` -### Cron no se activa +### Cron no se ejecuta -- Comprueba `cron.enabled` y la variable de entorno `OPENCLAW_SKIP_CRON`. -- Confirma que el Gateway se esté ejecutando de forma continua. +- Verifica `cron.enabled` y la variable de entorno `OPENCLAW_SKIP_CRON`. +- Confirma que el Gateway esté ejecutándose de forma continua. - Para programaciones `cron`, verifica la zona horaria (`--tz`) frente a la zona horaria del host. -- `reason: not-due` en la salida de ejecución significa que la ejecución manual se comprobó con `openclaw cron run --due` y que el trabajo aún no vencía. +- `reason: not-due` en la salida de ejecución significa que la ejecución manual se comprobó con `openclaw cron run --due` y que el trabajo aún no debía ejecutarse. -### Cron se activó pero no hubo entrega +### Cron se ejecutó pero no hubo entrega - El modo de entrega `none` significa que no se espera ningún mensaje externo. -- Un destino de entrega faltante o no válido (`channel`/`to`) significa que la salida se omitió. +- Un destino de entrega faltante o no válido (`channel`/`to`) significa que se omitió la salida. - Los errores de autenticación del canal (`unauthorized`, `Forbidden`) significan que la entrega fue bloqueada por las credenciales. -- Si la ejecución aislada devuelve solo el token silencioso (`NO_REPLY` / `no_reply`), OpenClaw suprime la entrega directa saliente y también suprime la ruta de resumen en cola de fallback, por lo que no se publica nada de vuelta en el chat. -- Para los trabajos aislados propiedad de cron, no esperes que el agente use la herramienta de mensajes como fallback. El ejecutor es propietario de la entrega final; `--no-deliver` la mantiene interna en lugar de permitir un envío directo. +- Si la ejecución aislada devuelve solo el token silencioso (`NO_REPLY` / `no_reply`), OpenClaw suprime la entrega saliente directa y también la ruta de resumen en cola de respaldo, por lo que no se publica nada de vuelta en el chat. +- Para trabajos aislados propiedad de cron, no esperes que el agente use la herramienta de mensajes como respaldo. El ejecutor es responsable de la entrega final; `--no-deliver` la mantiene interna en lugar de permitir un envío directo. -### Consideraciones sobre la zona horaria +### Problemas habituales con zonas horarias - Cron sin `--tz` usa la zona horaria del host del gateway. - Las programaciones `at` sin zona horaria se tratan como UTC. -- `activeHours` de heartbeat usa la resolución de zona horaria configurada. +- `activeHours` de Heartbeat usa la resolución de zona horaria configurada. ## Relacionado - [Automatización y tareas](/es/automation) — todos los mecanismos de automatización de un vistazo - [Tareas en segundo plano](/es/automation/tasks) — registro de tareas para ejecuciones de cron - [Heartbeat](/es/gateway/heartbeat) — turnos periódicos de la sesión principal -- [Zona horaria](/es/concepts/timezone) — configuración de la zona horaria +- [Zona horaria](/es/concepts/timezone) — configuración de zona horaria diff --git a/docs/es/concepts/active-memory.md b/docs/es/concepts/active-memory.md index dba95915a..35d07e5dc 100644 --- a/docs/es/concepts/active-memory.md +++ b/docs/es/concepts/active-memory.md @@ -3,34 +3,34 @@ 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 propiedad del plugin que inyecta memoria relevante en sesiones de chat interactivas +summary: Un subagente de memoria de bloqueo propiedad del plugin que inyecta memoria relevante en las sesiones de chat interactivas title: Memoria activa x-i18n: - generated_at: "2026-04-11T04:55:45Z" + generated_at: "2026-04-12T05:11:00Z" model: gpt-5.4 provider: openai - source_hash: e8b0e6539e09678e9e8def68795f8bcb992f98509423da3da3123eda88ec1dd5 + source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84 source_path: concepts/active-memory.md workflow: 15 --- # Memoria activa -La memoria activa es un subagente de memoria de bloqueo opcional propiedad del plugin que se ejecuta -antes de la respuesta principal en las sesiones conversacionales elegibles. +La memoria activa es un subagente opcional de memoria de bloqueo propiedad del plugin que se ejecuta +antes de la respuesta principal en las sesiones conversacionales aptas. 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 el que la memoria habría hecho que la respuesta se sintiera natural ya pasó. -La memoria activa da al sistema una oportunidad limitada de mostrar memoria relevante +La memoria activa le da al sistema una oportunidad limitada para mostrar 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: +configuración autocontenida y segura por defecto: ```json5 { @@ -42,7 +42,7 @@ configuración autónoma y segura por defecto: enabled: true, agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -58,10 +58,10 @@ configuración autónoma y segura por defecto: Esto activa el plugin para el agente `main`, lo mantiene limitado de forma predeterminada a sesiones de estilo mensaje directo, 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 +usa el modelo de respaldo configurado solo si no hay un modelo explícito o heredado disponible. -Después de eso, reinicia la gateway: +Después de eso, reinicia el gateway: ```bash openclaw gateway @@ -78,8 +78,8 @@ Para inspeccionarlo en vivo en una conversación: La configuración más segura es: 1. habilitar el plugin -2. dirigirlo a un agente conversacional -3. mantener el registro activado solo mientras haces ajustes +2. apuntar a un agente conversacional +3. mantener el registro activado solo mientras ajustas el comportamiento Empieza con esto en `openclaw.json`: @@ -92,7 +92,7 @@ Empieza con esto en `openclaw.json`: config: { agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -106,7 +106,7 @@ Empieza con esto en `openclaw.json`: } ``` -Luego reinicia la gateway: +Luego reinicia el gateway: ```bash openclaw gateway @@ -115,17 +115,17 @@ openclaw gateway Qué significa esto: - `plugins.entries.active-memory.enabled: true` activa el plugin -- `config.agents: ["main"]` hace que solo el agente `main` use la memoria activa +- `config.agents: ["main"]` habilita la memoria activa solo para el agente `main` - `config.allowedChatTypes: ["direct"]` mantiene la memoria activa habilitada 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 valor predeterminado cuando no hay un modelo explícito o heredado disponible -- `config.promptStyle: "balanced"` usa el estilo de prompt general predeterminado para el modo `recent` -- la memoria activa sigue ejecutándose solo en sesiones de chat persistentes, interactivas y elegibles +- si `config.model` no está configurado, la memoria activa primero hereda el modelo de la sesión actual +- `config.modelFallback` opcionalmente proporciona tu propio proveedor/modelo de respaldo para la recuperación +- `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 persistentes, interactivas y aptas ## Cómo verlo La memoria activa inyecta contexto oculto del sistema para el modelo. No expone -etiquetas sin procesar `...` al cliente. +etiquetas `...` sin procesar al cliente. ## Alternancia por sesión @@ -152,11 +152,11 @@ todas las sesiones, usa la forma global explícita: ``` La forma global escribe `plugins.entries.active-memory.config.enabled`. Deja -`plugins.entries.active-memory.enabled` activado para que el comando siga disponible para -volver a activar la memoria activa más adelante. +`plugins.entries.active-memory.enabled` activado para que el comando siga estando disponible y +puedas 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: +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 @@ -164,14 +164,14 @@ el modo detallado para esa sesión: Con el modo detallado habilitado, OpenClaw puede mostrar: -- una línea de estado de la memoria activa como `Active Memory: ok 842ms recent 34 chars` +- una línea de estado de 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. +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 el marcado del prompt sin procesar. De forma predeterminada, la transcripción del subagente de memoria de bloqueo es temporal y se elimina -después de que se completa la ejecución. +después de que la ejecución termina. Flujo de ejemplo: @@ -180,7 +180,7 @@ Flujo de ejemplo: what wings should i order? ``` -Forma visible de respuesta esperada: +Forma visible esperada de la respuesta: ```text ...normal assistant reply... @@ -191,14 +191,14 @@ Forma visible de respuesta esperada: ## Cuándo se ejecuta -La memoria activa usa dos controles: +La memoria activa usa dos compuertas: -1. **Participación mediante configuración** +1. **Inclusión mediante 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 en - sesiones de chat persistentes, interactivas y elegibles. + sesiones de chat persistentes, interactivas y aptas. La regla real es: @@ -218,8 +218,8 @@ Si cualquiera de esas condiciones falla, la memoria activa no se ejecuta. ## Tipos de sesión -`config.allowedChatTypes` controla qué tipos de conversaciones pueden ejecutar Memoria -activa en absoluto. +`config.allowedChatTypes` controla qué tipos de conversaciones pueden ejecutar la Memoria +activa. El valor predeterminado es: @@ -227,8 +227,8 @@ El valor predeterminado es: allowedChatTypes: ["direct"] ``` -Eso significa que 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 habilites explícitamente. +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: @@ -246,38 +246,38 @@ 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. +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 la UI de control / chat web | Sí, si el plugin está habilitado y el agente está dirigido | -| Otras sesiones de canales interactivos en la misma ruta de chat persistente | Sí, si el plugin está habilitado y el agente está dirigido | -| Ejecuciones puntuales sin interfaz | No | -| Ejecuciones de latido/en segundo plano | No | -| Rutas internas genéricas de `agent-command` | No | -| Ejecución de subagentes/ayudantes internos | No | +| Superficie | ¿Se ejecuta la memoria activa? | +| ------------------------------------------------------------------- | -------------------------------------------------------- | +| Sesiones persistentes de Control UI / chat web | Sí, si el plugin está habilitado y el agente está dirigido | +| Otras sesiones de canal interactivas en la misma ruta de chat persistente | Sí, si el plugin está habilitado y el agente está dirigido | +| Ejecuciones sin interfaz de una sola vez | 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 bruto del prompt +- el agente tiene memoria significativa de largo plazo 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 de usuario a largo plazo que debería aparecer de forma natural +- contexto de usuario de largo plazo que debería aparecer de forma natural No es adecuada para: - automatización - workers internos -- tareas puntuales de API -- lugares donde la personalización oculta sería sorprendente +- tareas de API de una sola vez +- lugares donde una personalización oculta sería sorprendente ## Cómo funciona @@ -305,15 +305,15 @@ Si la conexión es débil, debe devolver `NONE`. ## Estilos de prompt -`config.promptStyle` controla qué tan dispuesto o estricto es el subagente de memoria de bloqueo -al decidir si devolver memoria. +`config.promptStyle` controla qué tan ansioso o estricto es el subagente de memoria de bloqueo +al decidir si debe devolver memoria. Estilos disponibles: - `balanced`: valor predeterminado de propósito general para el modo `recent` -- `strict`: el menos dispuesto; mejor cuando quieres muy poca influencia del contexto cercano -- `contextual`: el más favorable para la continuidad; mejor cuando el historial de conversación debe importar más -- `recall-heavy`: más dispuesto a mostrar memoria en coincidencias menos claras pero aún plausibles +- `strict`: el menos ansioso; es mejor cuando quieres muy poca contaminación del contexto cercano +- `contextual`: el más favorable a la continuidad; es mejor cuando el historial de conversación debe importar más +- `recall-heavy`: más dispuesto a mostrar memoria con coincidencias más suaves pero aún plausibles - `precision-heavy`: prefiere agresivamente `NONE` a menos que la coincidencia sea obvia - `preference-only`: optimizado para favoritos, hábitos, rutinas, gustos y hechos personales recurrentes @@ -325,7 +325,7 @@ recent -> balanced full -> contextual ``` -Si configuras `config.promptStyle` explícitamente, esa anulación tiene prioridad. +Si configuras `config.promptStyle` explícitamente, esa anulación prevalece. Ejemplo: @@ -333,36 +333,32 @@ Ejemplo: promptStyle: "preference-only" ``` -## Política de reserva del modelo +## Política de modelo de respaldo -Si `config.model` no está configurado, Memoria activa intenta resolver un modelo en este orden: +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 +-> optional configured fallback model ``` -`config.modelFallbackPolicy` controla el último paso. +`config.modelFallback` controla el paso del modelo de respaldo configurado. -Predeterminado: +Respaldo personalizado opcional: ```json5 -modelFallbackPolicy: "default-remote" +modelFallback: "google/gemini-3-flash" ``` -Otra opción: +Si no se resuelve ningún modelo explícito, heredado o de respaldo configurado, la Memoria activa +omite la recuperación en ese turno. -```json5 -modelFallbackPolicy: "resolved-only" -``` +`config.modelFallbackPolicy` se conserva solo como un campo de compatibilidad obsoleto +para configuraciones antiguas. Ya no cambia el comportamiento en tiempo de ejecución. -Usa `resolved-only` si quieres que Memoria activa omita la recuperación en lugar de usar -la reserva remota integrada predeterminada cuando no haya un modelo explícito o heredado -disponible. - -## Vías de escape avanzadas +## Válvulas de escape avanzadas Estas opciones intencionalmente no forman parte de la configuración recomendada. @@ -372,17 +368,17 @@ Estas opciones intencionalmente no forman parte de la configuración recomendada thinking: "medium" ``` -Predeterminado: +Valor predeterminado: ```json5 thinking: "off" ``` -No habilites esto de forma predeterminada. Memoria activa se ejecuta en la ruta de respuesta, por lo que el +No habilites esto de forma predeterminada. La Memoria activa se ejecuta en la ruta de respuesta, así que el tiempo adicional de razonamiento aumenta 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: +`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." @@ -395,7 +391,7 @@ sigue agregando después el contexto de la conversación: promptOverride: "You are a memory search agent. Return NONE or one compact user fact." ``` -No se recomienda la personalización del prompt a menos que estés probando deliberadamente un +No se recomienda personalizar el prompt a menos que estés probando deliberadamente un contrato de recuperación diferente. El prompt predeterminado está ajustado para devolver `NONE` o contexto compacto de hechos del usuario para el modelo principal. @@ -407,11 +403,11 @@ Solo se envía el mensaje más reciente del usuario. Latest user message only ``` -Úsalo cuando: +Usa esto cuando: -- quieras el comportamiento más rápido -- quieras el sesgo más fuerte hacia la recuperación de preferencias estables -- los turnos de seguimiento no necesiten contexto conversacional +- 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: @@ -419,7 +415,7 @@ Tiempo de espera recomendado: ### `recent` -Se envían el mensaje más reciente del usuario y una pequeña cola conversacional reciente. +Se envían el mensaje más reciente del usuario más una pequeña cola conversacional reciente. ```text Recent conversation tail: @@ -431,10 +427,10 @@ Latest user message: ... ``` -Úsalo cuando: +Usa esto cuando: -- quieras un mejor equilibrio entre velocidad y base conversacional -- las preguntas de seguimiento dependan con frecuencia de los últimos turnos +- quieres un mejor equilibrio entre velocidad y fundamento conversacional +- las preguntas de seguimiento a menudo dependen de los últimos turnos Tiempo de espera recomendado: @@ -452,17 +448,17 @@ user: ... ... ``` -Úsalo cuando: +Usa esto cuando: -- la mayor calidad de recuperación importe más que la latencia -- la conversación contenga una preparación importante muy atrás en el hilo +- la mayor calidad de recuperación importa más que la latencia +- la conversación contiene preparación importante mucho más atrás en el hilo Tiempo de espera recomendado: -- auméntalo sustancialmente en comparación con `message` o `recent` -- empieza alrededor de `15000` ms o más, según el tamaño del hilo +- auméntalo considerablemente en comparación con `message` o `recent` +- empieza 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: +En general, el tiempo de espera debería aumentar con el tamaño del contexto: ```text message < recent < full @@ -471,7 +467,7 @@ message < recent < full ## Persistencia de transcripciones Las ejecuciones del subagente de memoria de bloqueo de la memoria activa crean una transcripción real `session.jsonl` -durante la llamada del subagente de memoria de bloqueo. +durante la llamada al subagente de memoria de bloqueo. De forma predeterminada, esa transcripción es temporal: @@ -479,7 +475,7 @@ De forma predeterminada, esa transcripción es temporal: - se usa solo para la ejecución del subagente de memoria de bloqueo - se elimina inmediatamente después de que termina la ejecución -Si quieres conservar en disco esas transcripciones del subagente de memoria de bloqueo para depuración o +Si quieres conservar esas transcripciones del subagente de memoria de bloqueo en disco para depuración o inspección, activa la persistencia explícitamente: ```json5 @@ -500,10 +496,10 @@ inspección, activa la persistencia explícitamente: ``` 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. +carpeta de sesiones del agente de destino, no en la ruta principal de la transcripción +de la conversación del usuario. -La disposición predeterminada es conceptualmente: +El diseño predeterminado es conceptualmente: ```text agents//sessions/active-memory/.jsonl @@ -511,7 +507,7 @@ agents//sessions/active-memory/.jso Puedes cambiar el subdirectorio relativo con `config.transcriptDir`. -Usa esto con cuidado: +Úsalo con cuidado: - las transcripciones del subagente de memoria de bloqueo pueden acumularse rápidamente en sesiones con mucha actividad - el modo de consulta `full` puede duplicar mucho contexto de conversación @@ -527,27 +523,27 @@ plugins.entries.active-memory Los campos más importantes son: -| Clave | Tipo | Significado | -| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| `enabled` | `boolean` | Habilita el propio plugin | -| `config.agents` | `string[]` | IDs de agentes que pueden usar memoria activa | -| `config.model` | `string` | Referencia opcional al modelo del subagente de memoria de bloqueo; cuando no está configurado, la memoria activa usa el modelo de la sesión actual | -| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla cuánta conversación ve el subagente de memoria de bloqueo | -| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla qué tan dispuesto o estricto es el subagente de memoria de bloqueo 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 de bloqueo; valor predeterminado `off` para velocidad | -| `config.promptOverride` | `string` | Reemplazo avanzado completo del prompt; no se recomienda para uso normal | -| `config.promptAppend` | `string` | Instrucciones adicionales avanzadas añadidas al prompt predeterminado o reemplazado | -| `config.timeoutMs` | `number` | Tiempo de espera máximo estricto para el subagente de memoria de bloqueo | -| `config.maxSummaryChars` | `number` | Número máximo total de caracteres permitidos 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 de bloqueo en lugar de eliminar archivos temporales | +| Clave | Tipo | Significado | +| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `enabled` | `boolean` | Habilita el propio plugin | +| `config.agents` | `string[]` | Ids de agentes que pueden usar memoria activa | +| `config.model` | `string` | Referencia opcional de modelo del subagente de memoria de bloqueo; cuando no está configurado, la memoria activa usa el modelo de la sesión actual | +| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla cuánta conversación ve el subagente de memoria de bloqueo | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla qué tan ansioso o estricto es el subagente de memoria de bloqueo 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 de bloqueo; valor predeterminado `off` para mayor velocidad | +| `config.promptOverride` | `string` | Reemplazo avanzado completo del prompt; no recomendado para uso normal | +| `config.promptAppend` | `string` | Instrucciones adicionales avanzadas agregadas al prompt predeterminado o anulado | +| `config.timeoutMs` | `number` | Tiempo de espera máximo estricto para el subagente de memoria de bloqueo | +| `config.maxSummaryChars` | `number` | Máximo total de caracteres permitidos en el resumen de active-memory | +| `config.logging` | `boolean` | Emite registros de memoria activa mientras ajustas el comportamiento | +| `config.persistTranscripts` | `boolean` | Conserva las transcripciones del subagente de memoria de bloqueo en disco en lugar de eliminar archivos temporales | | `config.transcriptDir` | `string` | Directorio relativo de transcripciones del subagente de memoria de bloqueo dentro de la carpeta de sesiones del agente | -Campos útiles para ajuste: +Campos útiles para ajustar: | Clave | Tipo | Significado | | ----------------------------- | -------- | ------------------------------------------------------------ | -| `config.maxSummaryChars` | `number` | Número máximo total de caracteres permitidos en el resumen de active-memory | +| `config.maxSummaryChars` | `number` | Máximo total de caracteres permitidos 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` | Máximo de caracteres por turno reciente del usuario | @@ -578,7 +574,7 @@ Empieza con `recent`. } ``` -Si quieres inspeccionar el comportamiento en vivo mientras haces ajustes, usa `/verbose on` en la +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 separado. Luego cambia a: @@ -590,11 +586,11 @@ Luego cambia a: 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 esté listado en `config.agents`. +1. Confirma que el plugin está habilitado en `plugins.entries.active-memory.enabled`. +2. Confirma que el id del agente actual aparece en `config.agents`. 3. Confirma que estás probando mediante una sesión de chat persistente e interactiva. -4. Activa `config.logging: true` y observa los registros de la gateway. -5. Verifica que la búsqueda de memoria en sí funcione con `openclaw memory status --deep`. +4. Activa `config.logging: true` y observa los registros del gateway. +5. Verifica que la búsqueda en memoria funciona con `openclaw memory status --deep`. Si los resultados de memoria son ruidosos, ajusta más estrictamente: @@ -604,7 +600,7 @@ Si la memoria activa es demasiado lenta: - reduce `queryMode` - reduce `timeoutMs` -- reduce los recuentos de turnos recientes +- reduce la cantidad de turnos recientes - reduce los límites de caracteres por turno ## Páginas relacionadas diff --git a/docs/es/concepts/system-prompt.md b/docs/es/concepts/system-prompt.md index 940573251..6ca615016 100644 --- a/docs/es/concepts/system-prompt.md +++ b/docs/es/concepts/system-prompt.md @@ -1,14 +1,14 @@ --- read_when: - - Editar el texto del prompt del sistema, la lista de herramientas o las secciones de hora/heartbeat - - Cambiar el arranque del espacio de trabajo o el comportamiento de inyección de Skills + - Editar el texto del prompt del sistema, la lista de herramientas o las secciones de hora/latido + - Cambiar el comportamiento de inicialización del espacio de trabajo o de inyección de Skills summary: Qué contiene el prompt del sistema de OpenClaw y cómo se ensambla title: Prompt del sistema x-i18n: - generated_at: "2026-04-08T02:14:24Z" + generated_at: "2026-04-12T05:10:59Z" model: gpt-5.4 provider: openai - source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a + source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f source_path: concepts/system-prompt.md workflow: 15 --- @@ -19,86 +19,62 @@ OpenClaw crea un prompt del sistema personalizado para cada ejecución del agent El prompt es ensamblado por OpenClaw e inyectado en cada ejecución del agente. -Los plugins de proveedor pueden aportar orientación del prompt compatible con caché sin reemplazar -el prompt completo propiedad de OpenClaw. El runtime del proveedor puede: +Los plugins de proveedor pueden aportar guía de prompt consciente de caché sin reemplazar el prompt completo propiedad de OpenClaw. El runtime del proveedor puede: -- reemplazar un pequeño conjunto de secciones centrales con nombre (`interaction_style`, +- reemplazar un pequeño conjunto de secciones principales con nombre (`interaction_style`, `tool_call_style`, `execution_bias`) - inyectar un **prefijo estable** por encima del límite de caché del prompt - inyectar un **sufijo dinámico** por debajo del límite de caché del prompt -Usa contribuciones propiedad del proveedor para el ajuste específico de familias de modelos. Conserva la mutación heredada del prompt -`before_prompt_build` por compatibilidad o para cambios de prompt verdaderamente globales, -no para el comportamiento normal del proveedor. +Usa contribuciones propiedad del proveedor para ajustes específicos de familias de modelos. Mantén la mutación de prompt heredada `before_prompt_build` para compatibilidad o para cambios de prompt verdaderamente globales, no para el comportamiento normal del proveedor. ## Estructura El prompt es intencionalmente compacto y usa secciones fijas: -- **Herramientas**: recordatorio de la fuente de verdad de herramientas estructuradas más orientación de runtime para el uso de herramientas. -- **Seguridad**: recordatorio breve de barreras de protección para evitar comportamientos de búsqueda de poder o eludir la supervisión. -- **Skills** (cuando estén disponibles): indica al modelo cómo cargar instrucciones de Skills bajo demanda. +- **Herramientas**: recordatorio de la fuente de verdad de herramientas estructuradas más guía de runtime para el uso de herramientas. +- **Seguridad**: breve recordatorio de barreras de protección para evitar comportamiento de búsqueda de poder o elusión de supervisión. +- **Skills** (cuando están disponibles): indica al modelo cómo cargar instrucciones de Skills bajo demanda. - **Autoactualización de OpenClaw**: cómo inspeccionar la configuración de forma segura con - `config.schema.lookup`, aplicar parches a la configuración con `config.patch`, reemplazar la - configuración completa con `config.apply` y ejecutar `update.run` solo a petición explícita del usuario. - La herramienta `gateway`, solo para el propietario, también se niega a reescribir - `tools.exec.ask` / `tools.exec.security`, incluidas las alias heredadas `tools.bash.*` - que se normalizan a esas rutas exec protegidas. + `config.schema.lookup`, aplicar parches a la configuración con `config.patch`, reemplazar la configuración completa con `config.apply` y ejecutar `update.run` solo a petición explícita del usuario. La herramienta `gateway`, solo para propietarios, también se niega a reescribir `tools.exec.ask` / `tools.exec.security`, incluidas las aliases heredadas `tools.bash.*` que se normalizan a esas rutas de ejecución protegidas. - **Espacio de trabajo**: directorio de trabajo (`agents.defaults.workspace`). - **Documentación**: ruta local a la documentación de OpenClaw (repositorio o paquete npm) y cuándo leerla. - **Archivos del espacio de trabajo (inyectados)**: indica que los archivos de arranque se incluyen a continuación. -- **Sandbox** (cuando está habilitado): indica el runtime en sandbox, las rutas del sandbox y si exec con privilegios elevados está disponible. +- **Sandbox** (cuando está habilitado): indica el runtime aislado, las rutas del sandbox y si la ejecución elevada está disponible. - **Fecha y hora actuales**: hora local del usuario, zona horaria y formato de hora. -- **Etiquetas de respuesta**: sintaxis opcional de etiquetas de respuesta para los proveedores compatibles. -- **Heartbeats**: prompt y comportamiento de confirmación del heartbeat, cuando los heartbeats están habilitados para el agente predeterminado. -- **Runtime**: host, sistema operativo, node, raíz del repositorio (cuando se detecta), nivel de razonamiento (una línea). -- **Razonamiento**: nivel actual de visibilidad + pista sobre el cambio con /reasoning. +- **Etiquetas de respuesta**: sintaxis opcional de etiquetas de respuesta para proveedores compatibles. +- **Heartbeats**: prompt de heartbeat y comportamiento de acuse de recibo, cuando los heartbeats están habilitados para el agente predeterminado. +- **Runtime**: host, SO, node, modelo, raíz del repositorio (cuando se detecta), nivel de razonamiento (una línea). +- **Razonamiento**: nivel de visibilidad actual + sugerencia del toggle `/reasoning`. -La sección Herramientas también incluye orientación de runtime para trabajos de larga duración: +La sección Herramientas también incluye guía de runtime para trabajo de larga duración: -- usa cron para seguimientos futuros (`check back later`, recordatorios, trabajo recurrente) - en lugar de bucles de espera con `exec`, trucos de retraso con `yieldMs` o sondeo repetido de `process` -- usa `exec` / `process` solo para comandos que empiezan ahora y continúan ejecutándose - en segundo plano -- cuando la reactivación automática al completarse está habilitada, inicia el comando una sola vez y confía en - la ruta de reactivación basada en push cuando emita salida o falle -- usa `process` para registros, estado, entrada o intervención cuando necesites - inspeccionar un comando en ejecución -- si la tarea es más grande, prefiere `sessions_spawn`; la finalización del subagente es - basada en push y se anuncia automáticamente de vuelta al solicitante -- no sondees `subagents list` / `sessions_list` en un bucle solo para esperar - la finalización +- usa cron para seguimiento futuro (`check back later`, recordatorios, trabajo recurrente) en lugar de bucles de espera con `exec`, trucos de retraso con `yieldMs` o sondeo repetido de `process` +- usa `exec` / `process` solo para comandos que comienzan ahora y continúan ejecutándose en segundo plano +- cuando la reactivación automática al completarse está habilitada, inicia el comando una vez y confía en la ruta de reactivación basada en push cuando emita salida o falle +- usa `process` para logs, estado, entrada o intervención cuando necesites inspeccionar un comando en ejecución +- si la tarea es más grande, prefiere `sessions_spawn`; la finalización del subagente es basada en push y se anuncia automáticamente al solicitante +- no sondees `subagents list` / `sessions_list` en un bucle solo para esperar la finalización -Cuando la herramienta experimental `update_plan` está habilitada, Herramientas también le indica al -modelo que la use solo para trabajo no trivial de varios pasos, que mantenga exactamente un paso -`in_progress` y que evite repetir el plan completo después de cada actualización. +Cuando la herramienta experimental `update_plan` está habilitada, Herramientas también indica al modelo que la use solo para trabajo no trivial de varios pasos, mantenga exactamente un paso `in_progress` y evite repetir el plan completo después de cada actualización. -Las barreras de protección de seguridad en el prompt del sistema son orientativas. Guían el comportamiento del modelo, pero no aplican la política. Usa la política de herramientas, las aprobaciones de exec, el sandboxing y las listas permitidas de canales para la aplicación estricta; los operadores pueden desactivar esto por diseño. +Las barreras de seguridad en el prompt del sistema son orientativas. Guían el comportamiento del modelo, pero no aplican la política. Usa la política de herramientas, las aprobaciones de ejecución, el sandboxing y las listas de permitidos de canales para una aplicación estricta; los operadores pueden desactivarlas por diseño. -En los canales con tarjetas o botones de aprobación nativos, el prompt de runtime ahora le indica al -agente que confíe primero en esa UI de aprobación nativa. Solo debe incluir un comando manual -`/approve` cuando el resultado de la herramienta diga que las aprobaciones en el chat no están disponibles o -que la aprobación manual es la única vía. +En canales con tarjetas o botones de aprobación nativos, el prompt de runtime ahora indica al agente que confíe primero en esa IU de aprobación nativa. Solo debe incluir un comando manual `/approve` cuando el resultado de la herramienta diga que las aprobaciones por chat no están disponibles o que la aprobación manual es la única vía. ## Modos de prompt -OpenClaw puede renderizar prompts del sistema más pequeños para subagentes. El runtime establece un -`promptMode` para cada ejecución (no es una configuración visible para el usuario): +OpenClaw puede renderizar prompts del sistema más pequeños para subagentes. El runtime establece un `promptMode` para cada ejecución (no es una configuración de cara al usuario): - `full` (predeterminado): incluye todas las secciones anteriores. -- `minimal`: se usa para subagentes; omite **Skills**, **Memory Recall**, **Autoactualización de OpenClaw**, - **Alias de modelos**, **Identidad del usuario**, **Etiquetas de respuesta**, - **Mensajería**, **Respuestas silenciosas** y **Heartbeats**. Herramientas, **Seguridad**, - Espacio de trabajo, Sandbox, Fecha y hora actuales (cuando se conocen), Runtime y el - contexto inyectado siguen estando disponibles. -- `none`: devuelve solo la línea base de identidad. +- `minimal`: se usa para subagentes; omite **Skills**, **Recuperación de memoria**, **Autoactualización de OpenClaw**, **Aliases de modelos**, **Identidad del usuario**, **Etiquetas de respuesta**, **Mensajería**, **Respuestas silenciosas** y **Heartbeats**. Herramientas, **Seguridad**, Espacio de trabajo, Sandbox, Fecha y hora actuales (cuando se conocen), Runtime y el contexto inyectado siguen estando disponibles. +- `none`: devuelve solo la línea de identidad base. -Cuando `promptMode=minimal`, los prompts inyectados adicionales se etiquetan como **Contexto del subagente** -en lugar de **Contexto del chat grupal**. +Cuando `promptMode=minimal`, los prompts inyectados adicionales se etiquetan como **Contexto del subagente** en lugar de **Contexto de chat grupal**. -## Inyección del arranque del espacio de trabajo +## Inyección de arranque del espacio de trabajo -Los archivos de arranque se recortan y se anexan bajo **Contexto del proyecto** para que el modelo vea el contexto de identidad y perfil sin necesitar lecturas explícitas: +Los archivos de arranque se recortan y se agregan en **Contexto del proyecto** para que el modelo vea el contexto de identidad y perfil sin necesitar lecturas explícitas: - `AGENTS.md` - `SOUL.md` @@ -109,44 +85,26 @@ Los archivos de arranque se recortan y se anexan bajo **Contexto del proyecto** - `BOOTSTRAP.md` (solo en espacios de trabajo completamente nuevos) - `MEMORY.md` cuando está presente; en caso contrario, `memory.md` como alternativa en minúsculas -Todos estos archivos se **inyectan en la ventana de contexto** en cada turno, salvo que se aplique una restricción específica del archivo. `HEARTBEAT.md` se omite en ejecuciones normales cuando -los heartbeats están deshabilitados para el agente predeterminado o -`agents.defaults.heartbeat.includeSystemPromptSection` es false. Mantén los archivos inyectados concisos, -especialmente `MEMORY.md`, que puede crecer con el tiempo y provocar -un uso de contexto inesperadamente alto y una compactación más frecuente. +Todos estos archivos se **inyectan en la ventana de contexto** en cada turno, a menos que se aplique una compuerta específica por archivo. `HEARTBEAT.md` se omite en ejecuciones normales cuando los heartbeats están deshabilitados para el agente predeterminado o cuando `agents.defaults.heartbeat.includeSystemPromptSection` es false. Mantén los archivos inyectados concisos, especialmente `MEMORY.md`, que puede crecer con el tiempo y provocar un uso de contexto inesperadamente alto y compactaciones más frecuentes. -> **Nota:** los archivos diarios `memory/*.md` **no** se inyectan automáticamente. Se -> accede a ellos bajo demanda mediante las herramientas `memory_search` y `memory_get`, por lo que -> no cuentan contra la ventana de contexto a menos que el modelo los lea explícitamente. +> **Nota:** los archivos diarios `memory/*.md` **no** forman parte del Contexto del proyecto de arranque normal. En turnos normales se accede a ellos bajo demanda mediante las herramientas `memory_search` y `memory_get`, por lo que no cuentan contra la ventana de contexto a menos que el modelo los lea explícitamente. Los turnos simples `/new` y `/reset` son la excepción: el runtime puede anteponer memoria diaria reciente como un bloque único de contexto de inicio para ese primer turno. -Los archivos grandes se truncan con un marcador. El tamaño máximo por archivo está controlado por -`agents.defaults.bootstrapMaxChars` (predeterminado: 20000). El contenido total de arranque inyectado -entre archivos está limitado por `agents.defaults.bootstrapTotalMaxChars` -(predeterminado: 150000). Los archivos faltantes inyectan un breve marcador de archivo faltante. Cuando ocurre truncamiento, -OpenClaw puede inyectar un bloque de advertencia en Contexto del proyecto; esto se controla con -`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; -predeterminado: `once`). +Los archivos grandes se truncan con un marcador. El tamaño máximo por archivo está controlado por `agents.defaults.bootstrapMaxChars` (predeterminado: 20000). El contenido total de arranque inyectado entre archivos está limitado por `agents.defaults.bootstrapTotalMaxChars` (predeterminado: 150000). Los archivos faltantes inyectan un breve marcador de archivo faltante. Cuando ocurre truncamiento, OpenClaw puede inyectar un bloque de advertencia en Contexto del proyecto; esto se controla con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; predeterminado: `once`). -Las sesiones de subagentes solo inyectan `AGENTS.md` y `TOOLS.md` (los demás archivos de arranque -se filtran para mantener pequeño el contexto del subagente). +Las sesiones de subagentes solo inyectan `AGENTS.md` y `TOOLS.md` (los demás archivos de arranque se filtran para mantener pequeño el contexto del subagente). -Los hooks internos pueden interceptar este paso mediante `agent:bootstrap` para mutar o reemplazar -los archivos de arranque inyectados (por ejemplo, cambiando `SOUL.md` por una persona alternativa). +Los hooks internos pueden interceptar este paso mediante `agent:bootstrap` para mutar o reemplazar los archivos de arranque inyectados (por ejemplo, intercambiar `SOUL.md` por una persona alternativa). Si quieres que el agente suene menos genérico, empieza con [Guía de personalidad de SOUL.md](/es/concepts/soul). -Para inspeccionar cuánto aporta cada archivo inyectado (sin procesar frente a inyectado, truncamiento y además la sobrecarga del esquema de herramientas), usa `/context list` o `/context detail`. Consulta [Contexto](/es/concepts/context). +Para inspeccionar cuánto aporta cada archivo inyectado (bruto frente a inyectado, truncamiento, además de la sobrecarga del esquema de herramientas), usa `/context list` o `/context detail`. Consulta [Contexto](/es/concepts/context). ## Manejo del tiempo -El prompt del sistema incluye una sección dedicada de **Fecha y hora actuales** cuando se conoce la -zona horaria del usuario. Para mantener la estabilidad de la caché del prompt, ahora solo incluye -la **zona horaria** (sin reloj dinámico ni formato de hora). +El prompt del sistema incluye una sección dedicada de **Fecha y hora actuales** cuando se conoce la zona horaria del usuario. Para mantener estable la caché del prompt, ahora solo incluye la **zona horaria** (sin reloj dinámico ni formato de hora). -Usa `session_status` cuando el agente necesite la hora actual; la tarjeta de estado -incluye una línea de marca temporal. La misma herramienta también puede configurar opcionalmente una anulación del -modelo por sesión (`model=default` la borra). +Usa `session_status` cuando el agente necesite la hora actual; la tarjeta de estado incluye una línea de marca de tiempo. La misma herramienta también puede establecer opcionalmente una anulación de modelo por sesión (`model=default` la borra). Configura con: @@ -157,15 +115,12 @@ Consulta [Fecha y hora](/es/date-time) para ver todos los detalles del comportam ## Skills -Cuando existen Skills elegibles, OpenClaw inyecta una **lista compacta de skills disponibles** -(`formatSkillsForPrompt`) que incluye la **ruta del archivo** de cada Skill. El -prompt le indica al modelo que use `read` para cargar el SKILL.md en la ubicación -indicada (espacio de trabajo, gestionado o incluido). Si no hay Skills elegibles, la -sección Skills se omite. +Cuando existen Skills aptas, OpenClaw inyecta una **lista compacta de Skills disponibles** +(`formatSkillsForPrompt`) que incluye la **ruta de archivo** para cada Skill. El +prompt indica al modelo que use `read` para cargar el SKILL.md en la ubicación +indicada (espacio de trabajo, gestionado o integrado). Si no hay Skills aptas, se omite la sección Skills. -La elegibilidad incluye restricciones de metadatos de Skills, comprobaciones del entorno/configuración de runtime -y la lista efectiva de Skills permitidas del agente cuando `agents.defaults.skills` o -`agents.list[].skills` está configurado. +La aptitud incluye compuertas de metadatos de Skills, comprobaciones del entorno/configuración de runtime y la lista efectiva de Skills permitidas del agente cuando `agents.defaults.skills` o `agents.list[].skills` está configurado. ``` @@ -177,13 +132,8 @@ y la lista efectiva de Skills permitidas del agente cuando `agents.defaults.skil ``` -Esto mantiene pequeño el prompt base y al mismo tiempo permite un uso específico y dirigido de las Skills. +Esto mantiene pequeño el prompt base y al mismo tiempo permite un uso dirigido de Skills. ## Documentación -Cuando está disponible, el prompt del sistema incluye una sección de **Documentación** que apunta al -directorio local de documentación de OpenClaw (ya sea `docs/` en el espacio de trabajo del repositorio o la -documentación incluida en el paquete npm) y también menciona el espejo público, el repositorio fuente, la comunidad de Discord y -ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descubrir skills. El prompt le indica al modelo que consulte primero la documentación local -para el comportamiento, los comandos, la configuración o la arquitectura de OpenClaw, y que ejecute -`openclaw status` por sí mismo cuando sea posible (preguntando al usuario solo cuando no tenga acceso). +Cuando está disponible, el prompt del sistema incluye una sección de **Documentación** que apunta al directorio local de documentación de OpenClaw (ya sea `docs/` en el espacio de trabajo del repositorio o la documentación integrada del paquete npm) y también menciona el mirror público, el repositorio fuente, el Discord de la comunidad y ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descubrir Skills. El prompt indica al modelo que consulte primero la documentación local para el comportamiento, los comandos, la configuración o la arquitectura de OpenClaw, y que ejecute `openclaw status` por sí mismo cuando sea posible (preguntando al usuario solo cuando no tenga acceso). diff --git a/docs/es/plugins/architecture.md b/docs/es/plugins/architecture.md index 19ea36102..628080fb3 100644 --- a/docs/es/plugins/architecture.md +++ b/docs/es/plugins/architecture.md @@ -2,29 +2,29 @@ read_when: - Compilar o depurar plugins nativos de OpenClaw - Comprender el modelo de capacidades de plugins o los límites de propiedad - - Trabajar en la canalización de carga de plugins o el registro + - Trabajar en la canalización de carga de plugins o en el registro - Implementar hooks de tiempo de ejecución del proveedor o plugins de canal sidebarTitle: Internals -summary: 'Detalles internos de plugins: modelo de capacidades, propiedad, contratos, canalización de carga y asistentes de tiempo de ejecución' -title: Detalles internos de plugins +summary: 'Internos de plugins: modelo de capacidades, propiedad, contratos, canalización de carga y asistentes de tiempo de ejecución' +title: Internos de plugins x-i18n: - generated_at: "2026-04-11T15:15:57Z" + generated_at: "2026-04-12T05:11:01Z" model: gpt-5.4 provider: openai - source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 + source_hash: 6165a9da8b40de3bb7334fcb16023da5515deb83c4897ca1df1726f4a97db9e0 source_path: plugins/architecture.md workflow: 15 --- -# Detalles internos de plugins +# Internos de plugins Esta es la **referencia de arquitectura profunda**. Para guías prácticas, consulta: - - [Instalar y usar plugins](/es/tools/plugin) — guía del usuario + - [Instalar y usar plugins](/es/tools/plugin) — guía de usuario - [Primeros pasos](/es/plugins/building-plugins) — primer tutorial de plugins - - [Plugins de canal](/es/plugins/sdk-channel-plugins) — compilar un canal de mensajería - - [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — compilar un proveedor de modelos - - [Información general del SDK](/es/plugins/sdk-overview) — mapa de importaciones y API de registro + - [Plugins de canal](/es/plugins/sdk-channel-plugins) — crea un canal de mensajería + - [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — crea un proveedor de modelos + - [Descripción general del SDK](/es/plugins/sdk-overview) — mapa de importaciones y API de registro Esta página cubre la arquitectura interna del sistema de plugins de OpenClaw. @@ -34,47 +34,46 @@ Esta página cubre la arquitectura interna del sistema de plugins de OpenClaw. Las capacidades son el modelo público de **plugins nativos** dentro de OpenClaw. Cada plugin nativo de OpenClaw se registra en uno o más tipos de capacidad: -| Capacidad | Método de registro | Plugins de ejemplo | -| ---------------------- | ------------------------------------------------ | ------------------------------------ | -| Inferencia de texto | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend de inferencia de CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Voz | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Capacidad | Método de registro | Plugins de ejemplo | +| --------------------- | ----------------------------------------------- | ------------------------------------ | +| Inferencia de texto | `api.registerProvider(...)` | `openai`, `anthropic` | +| Backend de inferencia de CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Voz | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Transcripción en tiempo real | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Voz en tiempo real | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Comprensión de medios | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Generación de imágenes | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Generación de música | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Generación de video | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Obtención web | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Búsqueda web | `api.registerWebSearchProvider(...)` | `google` | -| Canal / mensajería | `api.registerChannel(...)` | `msteams`, `matrix` | +| Voz en tiempo real | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Comprensión de medios | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Generación de imágenes | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Generación de música | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Generación de video | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Obtención web | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Búsqueda web | `api.registerWebSearchProvider(...)` | `google` | +| Canal / mensajería | `api.registerChannel(...)` | `msteams`, `matrix` | Un plugin que registra cero capacidades pero proporciona hooks, herramientas o -servicios es un plugin **heredado solo con hooks**. Ese patrón sigue siendo totalmente compatible. +servicios es un plugin **heredado solo de hooks**. Ese patrón sigue siendo totalmente compatible. ### Postura de compatibilidad externa -El modelo de capacidades ya está implementado en el núcleo y hoy lo usan los plugins -nativos/integrados, pero la compatibilidad de plugins externos aún necesita un estándar -más estricto que “está exportado, por lo tanto está congelado”. +El modelo de capacidades ya está incorporado en el core y es usado por plugins +agrupados/nativos hoy en día, pero la compatibilidad de los plugins externos aún necesita un criterio más estricto que “está +exportado, por lo tanto está congelado”. Guía actual: -- **plugins externos existentes:** mantén funcionando las integraciones basadas en hooks; trátalas +- **plugins externos existentes:** mantén funcionando las integraciones basadas en hooks; trátalo como la línea base de compatibilidad -- **nuevos plugins nativos/integrados:** prefiere el registro explícito de capacidades en lugar de - accesos específicos del proveedor o nuevos diseños solo con hooks -- **plugins externos que adoptan registro de capacidades:** permitido, pero trata las - superficies auxiliares específicas de capacidades como evolutivas a menos que la documentación marque - explícitamente un contrato como estable +- **nuevos plugins agrupados/nativos:** prefiere el registro explícito de capacidades en lugar de + accesos específicos de proveedor o nuevos diseños solo de hooks +- **plugins externos que adopten el registro de capacidades:** está permitido, pero trata las + superficies auxiliares específicas de capacidades como evolutivas, a menos que la documentación marque explícitamente un + contrato como estable Regla práctica: - las API de registro de capacidades son la dirección prevista -- los hooks heredados siguen siendo la vía más segura para no romper plugins externos durante +- los hooks heredados siguen siendo la ruta más segura para evitar incompatibilidades para los plugins externos durante la transición -- no todas las subrutas auxiliares exportadas son equivalentes; prefiere el contrato - documentado y limitado, no exportaciones auxiliares incidentales +- no todos los subpaths auxiliares exportados son iguales; prefiere el contrato documentado y acotado, no exportaciones auxiliares incidentales ### Formas de plugins @@ -83,29 +82,29 @@ de registro (no solo según metadatos estáticos): - **plain-capability** -- registra exactamente un tipo de capacidad (por ejemplo, un plugin solo de proveedor como `mistral`) -- **hybrid-capability** -- registra varios tipos de capacidad (por ejemplo, - `openai` posee inferencia de texto, voz, comprensión de medios y generación +- **hybrid-capability** -- registra múltiples tipos de capacidad (por ejemplo, + `openai` es propietario de la inferencia de texto, voz, comprensión de medios y generación de imágenes) - **hook-only** -- registra solo hooks (tipados o personalizados), sin capacidades, herramientas, comandos ni servicios - **non-capability** -- registra herramientas, comandos, servicios o rutas, pero no capacidades -Usa `openclaw plugins inspect ` para ver la forma de un plugin y el desglose -de sus capacidades. Consulta la [referencia de CLI](/cli/plugins#inspect) para más detalles. +Usa `openclaw plugins inspect ` para ver la forma y el desglose de capacidades +de un plugin. Consulta la [referencia de CLI](/cli/plugins#inspect) para más detalles. ### Hooks heredados -El hook `before_agent_start` sigue siendo compatible como vía de compatibilidad para -plugins solo con hooks. Plugins heredados del mundo real todavía dependen de él. +El hook `before_agent_start` sigue siendo compatible como ruta de compatibilidad para +plugins solo de hooks. Los plugins heredados del mundo real siguen dependiendo de él. Dirección: - mantenerlo funcionando - documentarlo como heredado -- preferir `before_model_resolve` para trabajo de sustitución de modelo/proveedor -- preferir `before_prompt_build` para trabajo de mutación del prompt -- eliminarlo solo cuando baje el uso real y la cobertura de fixtures demuestre que la migración es segura +- preferir `before_model_resolve` para trabajo de reemplazo de modelo/proveedor +- preferir `before_prompt_build` para trabajo de mutación de prompts +- eliminarlo solo después de que baje el uso real y la cobertura de fixtures demuestre la seguridad de la migración ### Señales de compatibilidad @@ -115,72 +114,72 @@ una de estas etiquetas: | Señal | Significado | | ------------------------- | ------------------------------------------------------------ | | **config valid** | La configuración se analiza correctamente y los plugins se resuelven | -| **compatibility advisory** | El plugin usa un patrón compatible pero antiguo (por ejemplo, `hook-only`) | +| **compatibility advisory** | El plugin usa un patrón compatible pero antiguo (p. ej., `hook-only`) | | **legacy warning** | El plugin usa `before_agent_start`, que está obsoleto | | **hard error** | La configuración no es válida o el plugin no pudo cargarse | Ni `hook-only` ni `before_agent_start` romperán tu plugin hoy -- -`hook-only` es solo informativo, y `before_agent_start` solo activa una advertencia. Estas +`hook-only` es informativo, y `before_agent_start` solo activa una advertencia. Estas señales también aparecen en `openclaw status --all` y `openclaw plugins doctor`. -## Información general de la arquitectura +## Descripción general de la arquitectura El sistema de plugins de OpenClaw tiene cuatro capas: -1. **Manifiesto + descubrimiento** - OpenClaw encuentra plugins candidatos desde rutas configuradas, raíces de workspace, - raíces globales de extensiones y extensiones integradas. El descubrimiento lee primero los - manifiestos nativos `openclaw.plugin.json` junto con los manifiestos de paquetes compatibles. +1. **Manifest + descubrimiento** + OpenClaw encuentra plugins candidatos a partir de rutas configuradas, raíces del workspace, + raíces globales de extensiones y extensiones agrupadas. El descubrimiento lee primero los manifests nativos + `openclaw.plugin.json` junto con los manifests de bundles compatibles. 2. **Habilitación + validación** - El núcleo decide si un plugin descubierto está habilitado, deshabilitado, bloqueado o - seleccionado para un espacio exclusivo como la memoria. + El core decide si un plugin descubierto está habilitado, deshabilitado, bloqueado o + seleccionado para un slot exclusivo como memory. 3. **Carga en tiempo de ejecución** Los plugins nativos de OpenClaw se cargan dentro del proceso mediante jiti y registran - capacidades en un registro central. Los paquetes compatibles se normalizan en + capacidades en un registro central. Los bundles compatibles se normalizan en registros del registro sin importar código de tiempo de ejecución. 4. **Consumo de superficies** - El resto de OpenClaw lee el registro para exponer herramientas, canales, configuración - del proveedor, hooks, rutas HTTP, comandos de CLI y servicios. + El resto de OpenClaw lee el registro para exponer herramientas, canales, configuración de proveedor, + hooks, rutas HTTP, comandos de CLI y servicios. -En el caso específico del CLI de plugins, el descubrimiento del comando raíz se divide en dos fases: +Específicamente para la CLI de plugins, el descubrimiento de comandos raíz se divide en dos fases: - los metadatos en tiempo de análisis provienen de `registerCli(..., { descriptors: [...] })` -- el módulo real de CLI del plugin puede seguir siendo diferido y registrarse en la primera invocación +- el módulo real de la CLI del plugin puede permanecer diferido y registrarse en la primera invocación -Eso mantiene el código de CLI propiedad del plugin dentro del plugin, al tiempo que permite a OpenClaw -reservar nombres de comandos raíz antes del análisis. +Eso mantiene el código de CLI propiedad del plugin dentro del plugin, mientras permite que OpenClaw +reserve nombres de comandos raíz antes del análisis. El límite de diseño importante: -- el descubrimiento y la validación de configuración deben funcionar a partir de **metadatos de manifiesto/esquema** +- el descubrimiento y la validación de configuración deben funcionar a partir de **metadatos de manifest/esquema** sin ejecutar código del plugin - el comportamiento nativo en tiempo de ejecución proviene de la ruta `register(api)` del módulo del plugin -Esa separación permite que OpenClaw valide la configuración, explique plugins faltantes o deshabilitados y -construya sugerencias de UI/esquema antes de que el tiempo de ejecución completo esté activo. +Esa división permite que OpenClaw valide la configuración, explique plugins faltantes o deshabilitados, y +construya pistas de UI/esquema antes de que el tiempo de ejecución completo esté activo. -### Plugins de canal y la herramienta compartida de mensajes +### Plugins de canal y la herramienta de mensajes compartida -Los plugins de canal no necesitan registrar una herramienta independiente de enviar/editar/reaccionar para -acciones normales de chat. OpenClaw mantiene una sola herramienta compartida `message` en el núcleo, y -los plugins de canal se encargan del descubrimiento y la ejecución específicos del canal detrás de ella. +Los plugins de canal no necesitan registrar una herramienta separada de enviar/editar/reaccionar para +acciones normales de chat. OpenClaw mantiene una única herramienta `message` compartida en el core, y +los plugins de canal son propietarios del descubrimiento y la ejecución específicos del canal detrás de ella. El límite actual es: -- el núcleo posee el host de la herramienta compartida `message`, el cableado del prompt, el +- el core es propietario del host de la herramienta `message` compartida, la integración con prompts, el mantenimiento de sesiones/hilos y el despacho de ejecución -- los plugins de canal poseen el descubrimiento de acciones con alcance, el descubrimiento de - capacidades y cualquier fragmento de esquema específico del canal -- los plugins de canal poseen la gramática de conversación de sesión específica del proveedor, como - la forma en que los ID de conversación codifican los ID de hilo o heredan de conversaciones padre +- los plugins de canal son propietarios del descubrimiento de acciones por alcance, el descubrimiento de capacidades y cualquier + fragmento de esquema específico del canal +- los plugins de canal son propietarios de la gramática de conversación de sesión específica del proveedor, como + cómo los ID de conversación codifican los ID de hilo o heredan de conversaciones padre - los plugins de canal ejecutan la acción final a través de su adaptador de acciones -Para los plugins de canal, la superficie del SDK es -`ChannelMessageActionAdapter.describeMessageTool(...)`. Esa llamada unificada de descubrimiento -permite que un plugin devuelva juntas sus acciones visibles, capacidades y contribuciones -al esquema para que esas piezas no se desalineen entre sí. +Para plugins de canal, la superficie del SDK es +`ChannelMessageActionAdapter.describeMessageTool(...)`. Esa llamada de descubrimiento unificada +permite que un plugin devuelva juntas sus acciones visibles, capacidades y contribuciones de esquema +para que esas piezas no se desincronicen. -El núcleo pasa el alcance de tiempo de ejecución a ese paso de descubrimiento. Los campos importantes incluyen: +El core pasa el alcance de tiempo de ejecución a ese paso de descubrimiento. Los campos importantes incluyen: - `accountId` - `currentChannelId` @@ -189,128 +188,125 @@ El núcleo pasa el alcance de tiempo de ejecución a ese paso de descubrimiento. - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` de entrada confiable +- `requesterSenderId` entrante de confianza -Esto importa para los plugins sensibles al contexto. Un canal puede ocultar o exponer +Eso importa para plugins sensibles al contexto. Un canal puede ocultar o exponer acciones de mensaje según la cuenta activa, la sala/hilo/mensaje actual o la -identidad confiable del solicitante, sin codificar ramas específicas del canal en la -herramienta central `message`. +identidad confiable del solicitante, sin codificar ramas específicas del canal en la herramienta `message` del +core. -Por eso los cambios de enrutamiento del embedded-runner siguen siendo trabajo de plugins: el runner es -responsable de reenviar la identidad actual de chat/sesión al límite de descubrimiento del plugin -para que la herramienta compartida `message` exponga la superficie correcta, propiedad del canal, -para el turno actual. +Por eso los cambios de enrutamiento del embedded-runner siguen siendo trabajo del plugin: el runner es +responsable de reenviar la identidad actual del chat/sesión al límite de descubrimiento del plugin para que la +herramienta `message` compartida exponga la superficie propiedad del canal correcta para el turno actual. -Para los asistentes de ejecución propiedad del canal, los plugins integrados deben mantener el tiempo de ejecución -de ejecución dentro de sus propios módulos de extensión. El núcleo ya no posee los +Para los asistentes de ejecución propiedad del canal, los plugins agrupados deben mantener el tiempo de ejecución +de ejecución dentro de sus propios módulos de extensión. El core ya no es propietario de los tiempos de ejecución de acciones de mensaje de Discord, Slack, Telegram o WhatsApp en `src/agents/tools`. -No publicamos subrutas separadas `plugin-sdk/*-action-runtime`, y los plugins integrados -deben importar directamente su propio código local de tiempo de ejecución desde sus +No publicamos subpaths separados `plugin-sdk/*-action-runtime`, y los plugins agrupados +deben importar directamente su propio código de tiempo de ejecución local desde sus módulos propiedad de la extensión. -El mismo límite se aplica a las uniones del SDK con nombre de proveedor en general: el núcleo no debe -importar barriles de conveniencia específicos del canal para extensiones como Slack, Discord, Signal, -WhatsApp o similares. Si el núcleo necesita un comportamiento, debe consumir el propio barril -`api.ts` / `runtime-api.ts` del plugin integrado o elevar la necesidad a una capacidad -genérica y limitada del SDK compartido. +El mismo límite se aplica a los seams del SDK con nombre de proveedor en general: el core no +debe importar barriles de conveniencia específicos del canal para Slack, Discord, Signal, +WhatsApp o extensiones similares. Si el core necesita un comportamiento, debe consumir el +propio barril `api.ts` / `runtime-api.ts` del plugin agrupado o promover esa necesidad +a una capacidad genérica y acotada en el SDK compartido. -En el caso específico de las encuestas, hay dos rutas de ejecución: +Específicamente para las encuestas, hay dos rutas de ejecución: -- `outbound.sendPoll` es la base compartida para canales que encajan en el modelo - común de encuestas -- `actions.handleAction("poll")` es la ruta preferida para semánticas de encuesta específicas del canal - o parámetros de encuesta adicionales +- `outbound.sendPoll` es la base compartida para canales que encajan en el modelo común + de encuestas +- `actions.handleAction("poll")` es la ruta preferida para la semántica de encuestas específica del canal o parámetros adicionales de encuestas -Ahora el núcleo difiere el análisis compartido de encuestas hasta después de que el despacho de encuestas del plugin -rechace la acción, de modo que los controladores de encuestas propiedad del plugin puedan aceptar -campos de encuesta específicos del canal sin quedar bloqueados primero por el analizador -genérico de encuestas. +El core ahora difiere el análisis compartido de encuestas hasta después de que el despacho de encuestas del plugin rechace +la acción, de modo que los controladores de encuestas propiedad del plugin puedan aceptar campos de encuesta específicos del canal sin quedar +bloqueados primero por el analizador genérico de encuestas. -Consulta [Canalización de carga](#load-pipeline) para ver la secuencia completa de inicio. +Consulta [Canalización de carga](#load-pipeline) para la secuencia completa de inicio. ## Modelo de propiedad de capacidades -OpenClaw trata un plugin nativo como el límite de propiedad para una **empresa** o una -**función**, no como una mezcla de integraciones no relacionadas. +OpenClaw trata un plugin nativo como el límite de propiedad de una **empresa** o una +**función**, no como un conjunto de integraciones no relacionadas. Eso significa: -- un plugin de empresa normalmente debe poseer todas las superficies de OpenClaw - orientadas a esa empresa -- un plugin de función normalmente debe poseer la superficie completa de la función que introduce -- los canales deben consumir capacidades compartidas del núcleo en lugar de volver a implementar - comportamiento de proveedores de forma ad hoc +- un plugin de empresa normalmente debe ser propietario de todas las + superficies de OpenClaw orientadas a esa empresa +- un plugin de función normalmente debe ser propietario de la superficie completa de la función que introduce +- los canales deben consumir capacidades compartidas del core en lugar de volver a implementar + comportamiento de proveedor de forma ad hoc Ejemplos: -- el plugin integrado `openai` posee el comportamiento de proveedor de modelos de OpenAI y el comportamiento de OpenAI - para voz + voz en tiempo real + comprensión de medios + generación de imágenes -- el plugin integrado `elevenlabs` posee el comportamiento de voz de ElevenLabs -- el plugin integrado `microsoft` posee el comportamiento de voz de Microsoft -- el plugin integrado `google` posee el comportamiento de proveedor de modelos de Google más el comportamiento de Google para - comprensión de medios + generación de imágenes + búsqueda web -- el plugin integrado `firecrawl` posee el comportamiento de obtención web de Firecrawl -- los plugins integrados `minimax`, `mistral`, `moonshot` y `zai` poseen sus +- el plugin agrupado `openai` es propietario del comportamiento del proveedor de modelos de OpenAI y del comportamiento de OpenAI + de voz + voz en tiempo real + comprensión de medios + generación de imágenes +- el plugin agrupado `elevenlabs` es propietario del comportamiento de voz de ElevenLabs +- el plugin agrupado `microsoft` es propietario del comportamiento de voz de Microsoft +- el plugin agrupado `google` es propietario del comportamiento del proveedor de modelos de Google más el comportamiento de Google + de comprensión de medios + generación de imágenes + búsqueda web +- el plugin agrupado `firecrawl` es propietario del comportamiento de obtención web de Firecrawl +- los plugins agrupados `minimax`, `mistral`, `moonshot` y `zai` son propietarios de sus backends de comprensión de medios -- el plugin integrado `qwen` posee el comportamiento de proveedor de texto de Qwen más - el comportamiento de comprensión de medios y generación de video -- el plugin `voice-call` es un plugin de función: posee transporte de llamadas, herramientas, - CLI, rutas y puenteado de flujo multimedia de Twilio, pero consume capacidades compartidas de voz - más transcripción en tiempo real y voz en tiempo real en lugar de importar plugins de proveedor directamente +- el plugin agrupado `qwen` es propietario del comportamiento del proveedor de texto de Qwen más el + comportamiento de comprensión de medios y generación de video +- el plugin `voice-call` es un plugin de función: es propietario del transporte de llamadas, herramientas, + CLI, rutas y el puente de flujo de medios de Twilio, pero consume capacidades compartidas de voz + más transcripción en tiempo real y voz en tiempo real en lugar de importar directamente plugins de proveedor El estado final previsto es: - OpenAI vive en un solo plugin aunque abarque modelos de texto, voz, imágenes y video futuro -- otro proveedor puede hacer lo mismo para su propia área funcional -- los canales no se preocupan por qué plugin del proveedor posee el proveedor; consumen el - contrato de capacidad compartida expuesto por el núcleo +- otro proveedor puede hacer lo mismo para su propia área de superficie +- los canales no se preocupan por qué plugin del proveedor es propietario del proveedor; consumen el + contrato de capacidad compartida expuesto por el core Esta es la distinción clave: - **plugin** = límite de propiedad -- **capacidad** = contrato del núcleo que varios plugins pueden implementar o consumir +- **capacidad** = contrato del core que múltiples plugins pueden implementar o consumir -Así que si OpenClaw agrega un nuevo dominio como video, la primera pregunta no es -“¿qué proveedor debería codificar de forma rígida el manejo de video?”. La primera pregunta es “¿cuál es -el contrato central de capacidad de video?”. Una vez que ese contrato existe, los plugins de proveedor +Así que, si OpenClaw agrega un nuevo dominio como video, la primera pregunta no es +“¿qué proveedor debería codificar el manejo de video de forma rígida?” La primera pregunta es “¿cuál es +el contrato de capacidad de video del core?” Una vez que ese contrato existe, los plugins de proveedor pueden registrarse en él y los plugins de canal/función pueden consumirlo. Si la capacidad todavía no existe, el movimiento correcto suele ser: -1. definir la capacidad faltante en el núcleo +1. definir la capacidad faltante en el core 2. exponerla a través de la API/tiempo de ejecución del plugin de forma tipada 3. conectar canales/funciones a esa capacidad 4. dejar que los plugins de proveedor registren implementaciones -Esto mantiene la propiedad explícita y evita al mismo tiempo un comportamiento del núcleo que dependa de un +Esto mantiene la propiedad explícita y evita al mismo tiempo que el comportamiento del core dependa de un único proveedor o de una ruta de código específica de un plugin puntual. ### Capas de capacidades -Usa este modelo mental al decidir dónde pertenece el código: +Usa este modelo mental al decidir dónde debe estar el código: -- **capa de capacidades del núcleo**: orquestación compartida, política, fallback, reglas de - combinación de configuración, semántica de entrega y contratos tipados -- **capa de plugin del proveedor**: API específicas del proveedor, autenticación, catálogos de modelos, síntesis de voz, - generación de imágenes, backends futuros de video, endpoints de uso -- **capa de plugin de canal/función**: integración con Slack/Discord/voice-call/etc. - que consume capacidades del núcleo y las presenta en una superficie +- **capa de capacidades del core**: orquestación compartida, política, fallback, reglas + de combinación de configuración, semántica de entrega y contratos tipados +- **capa de plugins de proveedor**: APIs específicas del proveedor, autenticación, catálogos de modelos, síntesis de voz, + generación de imágenes, futuros backends de video, endpoints de uso +- **capa de plugins de canal/función**: integración con Slack/Discord/voice-call/etc. + que consume capacidades del core y las presenta en una superficie Por ejemplo, TTS sigue esta forma: -- el núcleo posee la política de TTS en tiempo de respuesta, el orden de fallback, las preferencias y la entrega por canal -- `openai`, `elevenlabs` y `microsoft` poseen las implementaciones de síntesis +- el core es propietario de la política de TTS en el momento de la respuesta, el orden de fallback, las preferencias y la entrega por canal +- `openai`, `elevenlabs` y `microsoft` son propietarios de las implementaciones de síntesis - `voice-call` consume el asistente de tiempo de ejecución de TTS para telefonía -Ese mismo patrón debe preferirse para capacidades futuras. +Ese mismo patrón debería preferirse para futuras capacidades. ### Ejemplo de plugin de empresa con múltiples capacidades Un plugin de empresa debe sentirse cohesivo desde fuera. Si OpenClaw tiene contratos compartidos para modelos, voz, transcripción en tiempo real, voz en tiempo real, comprensión de medios, generación de imágenes, generación de video, obtención web y búsqueda web, -un proveedor puede poseer todas sus superficies en un solo lugar: +un proveedor puede ser propietario de todas sus superficies en un solo lugar: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -364,62 +360,62 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Lo que importa no son los nombres exactos de los asistentes. Importa la forma: +Lo importante no son los nombres exactos de los asistentes. Lo que importa es la forma: -- un solo plugin posee la superficie del proveedor -- el núcleo sigue poseyendo los contratos de capacidad +- un solo plugin es propietario de la superficie del proveedor +- el core sigue siendo propietario de los contratos de capacidad - los plugins de canal y de función consumen asistentes `api.runtime.*`, no código del proveedor -- las pruebas de contrato pueden afirmar que el plugin registró las capacidades que - afirma poseer +- las pruebas de contrato pueden afirmar que el plugin registró las capacidades de las que + dice ser propietario ### Ejemplo de capacidad: comprensión de video -OpenClaw ya trata la comprensión de imagen/audio/video como una sola -capacidad compartida. El mismo modelo de propiedad se aplica allí: +OpenClaw ya trata la comprensión de imagen/audio/video como una capacidad compartida. +El mismo modelo de propiedad se aplica ahí: -1. el núcleo define el contrato de comprensión de medios +1. el core define el contrato de comprensión de medios 2. los plugins de proveedor registran `describeImage`, `transcribeAudio` y - `describeVideo`, según corresponda -3. los plugins de canal y de función consumen el comportamiento compartido del núcleo en lugar de + `describeVideo` según corresponda +3. los plugins de canal y de función consumen el comportamiento compartido del core en lugar de conectarse directamente al código del proveedor -Eso evita incorporar las suposiciones de video de un proveedor dentro del núcleo. El plugin posee -la superficie del proveedor; el núcleo posee el contrato de capacidad y el comportamiento de fallback. +Eso evita incorporar en el core los supuestos de video de un proveedor. El plugin es propietario de +la superficie del proveedor; el core es propietario del contrato de capacidad y del comportamiento de fallback. -La generación de video ya usa esa misma secuencia: el núcleo posee el contrato tipado de -capacidad y el asistente de tiempo de ejecución, y los plugins de proveedor registran -implementaciones `api.registerVideoGenerationProvider(...)` en relación con él. +La generación de video ya usa esa misma secuencia: el core es propietario del contrato tipado de +capacidad y del asistente de tiempo de ejecución, y los plugins de proveedor registran +implementaciones `api.registerVideoGenerationProvider(...)` en él. -¿Necesitas una lista concreta de despliegue? Consulta +¿Necesitas una lista de despliegue concreta? Consulta [Recetario de capacidades](/es/plugins/architecture). ## Contratos y cumplimiento -La superficie de la API de plugins está intencionalmente tipada y centralizada en +La superficie de la API de plugins es intencionadamente tipada y centralizada en `OpenClawPluginApi`. Ese contrato define los puntos de registro compatibles y los asistentes de tiempo de ejecución en los que un plugin puede apoyarse. -Por qué esto importa: +Por qué importa esto: -- los autores de plugins obtienen un único estándar interno estable -- el núcleo puede rechazar propiedad duplicada, como dos plugins que registren el mismo - ID de proveedor -- el inicio puede mostrar diagnósticos accionables para registros con formato incorrecto -- las pruebas de contrato pueden hacer cumplir la propiedad de los plugins integrados y evitar desviaciones silenciosas +- los autores de plugins obtienen un estándar interno estable +- el core puede rechazar propiedad duplicada, como dos plugins que registran el mismo + id de proveedor +- el inicio puede mostrar diagnósticos accionables para registros malformados +- las pruebas de contrato pueden aplicar la propiedad de plugins agrupados y evitar desvíos silenciosos Hay dos capas de cumplimiento: -1. **cumplimiento del registro en tiempo de ejecución** +1. **cumplimiento de registro en tiempo de ejecución** El registro de plugins valida los registros a medida que se cargan los plugins. Ejemplos: - ID de proveedor duplicados, ID de proveedor de voz duplicados y - registros mal formados producen diagnósticos del plugin en lugar de comportamiento indefinido. + id de proveedor duplicados, id de proveedor de voz duplicados y registros + malformados producen diagnósticos de plugin en lugar de comportamiento indefinido. 2. **pruebas de contrato** - Los plugins integrados se capturan en registros de contrato durante las ejecuciones de prueba para que - OpenClaw pueda afirmar la propiedad de forma explícita. Hoy esto se usa para proveedores de modelos, - proveedores de voz, proveedores de búsqueda web y propiedad del registro integrado. + Los plugins agrupados se capturan en registros de contrato durante las ejecuciones de prueba para que + OpenClaw pueda afirmar explícitamente la propiedad. Hoy esto se usa para + proveedores de modelos, proveedores de voz, proveedores de búsqueda web y propiedad de registro agrupado. -El efecto práctico es que OpenClaw sabe, de antemano, qué plugin posee qué -superficie. Eso permite que el núcleo y los canales se compongan sin problemas porque la propiedad está +El efecto práctico es que OpenClaw sabe, de antemano, qué plugin es propietario de qué +superficie. Eso permite que el core y los canales se compongan sin fricciones porque la propiedad está declarada, tipada y es comprobable, en lugar de implícita. ### Qué pertenece a un contrato @@ -428,17 +424,17 @@ Los buenos contratos de plugins son: - tipados - pequeños -- específicos de una capacidad -- propiedad del núcleo -- reutilizables por varios plugins +- específicos de capacidades +- propiedad del core +- reutilizables por múltiples plugins - consumibles por canales/funciones sin conocimiento del proveedor Los malos contratos de plugins son: -- política específica del proveedor oculta en el núcleo -- vías de escape puntuales de plugins que eluden el registro -- código de canal que accede directamente a una implementación del proveedor -- objetos de tiempo de ejecución ad hoc que no forman parte de `OpenClawPluginApi` ni de +- política específica del proveedor oculta en el core +- vías de escape puntuales de plugins que evitan el registro +- código de canal que entra directamente en una implementación del proveedor +- objetos ad hoc de tiempo de ejecución que no forman parte de `OpenClawPluginApi` ni de `api.runtime` En caso de duda, eleva el nivel de abstracción: define primero la capacidad y luego @@ -447,32 +443,33 @@ deja que los plugins se conecten a ella. ## Modelo de ejecución Los plugins nativos de OpenClaw se ejecutan **dentro del proceso** con el Gateway. No están -aislados en sandbox. Un plugin nativo cargado tiene el mismo límite de confianza a nivel de proceso que -el código del núcleo. +aislados. Un plugin nativo cargado tiene el mismo límite de confianza a nivel de proceso que +el código del core. Implicaciones: -- un plugin nativo puede registrar herramientas, manejadores de red, hooks y servicios +- un plugin nativo puede registrar herramientas, controladores de red, hooks y servicios - un error en un plugin nativo puede bloquear o desestabilizar el gateway -- un plugin nativo malicioso equivale a ejecución arbitraria de código dentro del proceso de OpenClaw +- un plugin nativo malicioso equivale a ejecución arbitraria de código dentro + del proceso de OpenClaw -Los paquetes compatibles son más seguros por defecto porque OpenClaw actualmente los trata -como paquetes de metadatos/contenido. En las versiones actuales, eso significa sobre todo -Skills integradas. +Los bundles compatibles son más seguros de forma predeterminada porque OpenClaw actualmente los trata +como paquetes de metadatos/contenido. En las versiones actuales, eso significa principalmente +Skills agrupadas. -Usa listas de permitidos y rutas explícitas de instalación/carga para plugins no integrados. Trata -los plugins de workspace como código para tiempo de desarrollo, no como valores predeterminados de producción. +Usa allowlists y rutas explícitas de instalación/carga para plugins no agrupados. Trata +los plugins del workspace como código de tiempo de desarrollo, no como valores predeterminados de producción. -Para los nombres de paquetes integrados del workspace, mantén el ID del plugin anclado en el nombre npm: -`@openclaw/` de forma predeterminada, o con un sufijo tipado aprobado como +Para nombres de paquetes agrupados del workspace, mantén el id del plugin anclado al nombre +de npm: `@openclaw/` de forma predeterminada, o un sufijo tipado aprobado como `-provider`, `-plugin`, `-speech`, `-sandbox` o `-media-understanding` cuando -el paquete expone intencionalmente un rol de plugin más limitado. +el paquete expone intencionadamente un rol de plugin más acotado. Nota importante sobre confianza: -- `plugins.allow` confía en **ID de plugin**, no en la procedencia de la fuente. -- Un plugin de workspace con el mismo ID que un plugin integrado intencionalmente sombrea - la copia integrada cuando ese plugin de workspace está habilitado/en la lista de permitidos. +- `plugins.allow` confía en **ids de plugin**, no en la procedencia del origen. +- Un plugin del workspace con el mismo id que un plugin agrupado sombrea intencionadamente + la copia agrupada cuando ese plugin del workspace está habilitado/en la allowlist. - Esto es normal y útil para desarrollo local, pruebas de parches y hotfixes. ## Límite de exportación @@ -481,67 +478,71 @@ OpenClaw exporta capacidades, no conveniencias de implementación. Mantén público el registro de capacidades. Recorta las exportaciones auxiliares que no sean contratos: -- subrutas específicas de asistentes de plugins integrados -- subrutas de infraestructura de tiempo de ejecución que no estén pensadas como API pública +- subpaths auxiliares específicos de plugins agrupados +- subpaths de plomería de tiempo de ejecución no pensados como API pública - asistentes de conveniencia específicos del proveedor -- asistentes de configuración/incorporación que sean detalles de implementación +- asistentes de configuración/incorporación que son detalles de implementación -Algunas subrutas auxiliares de plugins integrados todavía permanecen en el mapa generado de exportaciones del SDK -por compatibilidad y mantenimiento de plugins integrados. Ejemplos actuales incluyen +Algunos subpaths auxiliares de plugins agrupados aún permanecen en el mapa generado de exportación del SDK +por compatibilidad y mantenimiento de plugins agrupados. Ejemplos actuales incluyen `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` y varias uniones `plugin-sdk/matrix*`. Trátalas como +`plugin-sdk/zalo-setup` y varios seams `plugin-sdk/matrix*`. Trátalos como exportaciones reservadas de detalle de implementación, no como el patrón de SDK recomendado para -nuevos plugins externos. +nuevos plugins de terceros. ## Canalización de carga -Al inicio, OpenClaw hace aproximadamente esto: +Al iniciar, OpenClaw hace aproximadamente esto: 1. descubre raíces candidatas de plugins -2. lee manifiestos nativos o de paquetes compatibles y metadatos del paquete -3. rechaza candidatos no seguros +2. lee manifests nativos o de bundles compatibles y metadatos de paquetes +3. rechaza candidatos inseguros 4. normaliza la configuración de plugins (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. decide la habilitación de cada candidato -6. carga los módulos nativos habilitados mediante jiti +6. carga módulos nativos habilitados mediante jiti 7. llama a los hooks nativos `register(api)` (o `activate(api)` — un alias heredado) y recopila los registros en el registro de plugins 8. expone el registro a las superficies de comandos/tiempo de ejecución -`activate` es un alias heredado de `register`: el cargador resuelve el que esté presente (`def.register ?? def.activate`) y lo llama en el mismo punto. Todos los plugins integrados usan `register`; para plugins nuevos, prefiere `register`. +`activate` es un alias heredado de `register`: el cargador resuelve el que esté presente (`def.register ?? def.activate`) y lo llama en el mismo punto. Todos los plugins agrupados usan `register`; prefiere `register` para plugins nuevos. -Las compuertas de seguridad ocurren **antes** de la ejecución en tiempo de ejecución. Los candidatos se bloquean -cuando la entrada escapa de la raíz del plugin, la ruta es escribible por cualquiera o la propiedad de la ruta -parece sospechosa para plugins no integrados. +Las puertas de seguridad ocurren **antes** de la ejecución en tiempo de ejecución. Los candidatos se bloquean +cuando la entrada escapa de la raíz del plugin, la ruta es editable por cualquiera o la +propiedad de la ruta parece sospechosa para plugins no agrupados. -### Comportamiento basado primero en el manifiesto +### Comportamiento centrado en el manifest -El manifiesto es la fuente de verdad del plano de control. OpenClaw lo usa para: +El manifest es la fuente de verdad del plano de control. OpenClaw lo usa para: - identificar el plugin -- descubrir canales/Skills/esquema de configuración declarados o capacidades del paquete +- descubrir canales/Skills/esquema de configuración declarados o capacidades del bundle - validar `plugins.entries..config` -- complementar etiquetas/placeholders de la UI de control +- ampliar etiquetas/placeholders de Control UI - mostrar metadatos de instalación/catálogo - preservar descriptores económicos de activación y configuración sin cargar el tiempo de ejecución del plugin -Para plugins nativos, el módulo de tiempo de ejecución es la parte del plano de datos. Registra el -comportamiento real, como hooks, herramientas, comandos o flujos del proveedor. +Para plugins nativos, el módulo de tiempo de ejecución es la parte del plano de datos. Registra +comportamiento real como hooks, herramientas, comandos o flujos de proveedor. -Los bloques opcionales `activation` y `setup` del manifiesto permanecen en el plano de control. +Los bloques opcionales `activation` y `setup` del manifest permanecen en el plano de control. Son descriptores solo de metadatos para la planificación de activación y el descubrimiento de configuración; no reemplazan el registro en tiempo de ejecución, `register(...)` ni `setupEntry`. +El descubrimiento de configuración ahora prefiere ids propiedad del descriptor como `setup.providers` y +`setup.cliBackends` para acotar plugins candidatos antes de volver a `setup-api` para plugins que aún necesitan hooks de tiempo de ejecución en configuración. Si más de +un plugin descubierto reclama el mismo id normalizado de proveedor de configuración o backend de CLI, la búsqueda de configuración rechaza al propietario ambiguo en lugar de depender del orden de descubrimiento. + ### Qué almacena en caché el cargador -OpenClaw mantiene cachés breves dentro del proceso para: +OpenClaw mantiene cachés cortas dentro del proceso para: - resultados de descubrimiento -- datos del registro de manifiestos +- datos del registro de manifests - registros de plugins cargados -Estas cachés reducen picos de inicio y la sobrecarga de comandos repetidos. Es seguro +Estas cachés reducen el inicio con ráfagas y la sobrecarga de comandos repetidos. Es seguro pensar en ellas como cachés de rendimiento de corta duración, no como persistencia. Nota de rendimiento: @@ -553,38 +554,37 @@ Nota de rendimiento: ## Modelo de registro -Los plugins cargados no mutan directamente variables globales aleatorias del núcleo. Se registran en un +Los plugins cargados no mutan directamente globals aleatorios del core. Se registran en un registro central de plugins. -El registro realiza seguimiento de: +El registro rastrea: - registros de plugins (identidad, origen, procedencia, estado, diagnósticos) - herramientas - hooks heredados y hooks tipados - canales - proveedores -- manejadores RPC del gateway +- controladores RPC del gateway - rutas HTTP - registradores de CLI - servicios en segundo plano - comandos propiedad del plugin -Luego, las funciones del núcleo leen de ese registro en lugar de hablar con módulos de plugins +Luego, las funciones del core leen desde ese registro en lugar de hablar con los módulos de plugins directamente. Esto mantiene la carga en una sola dirección: - módulo del plugin -> registro en el registro -- tiempo de ejecución del núcleo -> consumo del registro +- tiempo de ejecución del core -> consumo del registro -Esa separación importa para la mantenibilidad. Significa que la mayoría de las superficies del núcleo solo -necesitan un punto de integración: “leer el registro”, no “hacer casos especiales para cada módulo +Esa separación importa para la mantenibilidad. Significa que la mayoría de las superficies del core solo +necesitan un punto de integración: “leer el registro”, no “hacer un caso especial para cada módulo de plugin”. -## Callbacks de vinculación de conversaciones +## Callbacks de asociación de conversaciones -Los plugins que vinculan una conversación pueden reaccionar cuando se resuelve una aprobación. +Los plugins que asocian una conversación pueden reaccionar cuando se resuelve una aprobación. -Usa `api.onConversationBindingResolved(...)` para recibir un callback después de que una solicitud de vinculación -sea aprobada o denegada: +Usa `api.onConversationBindingResolved(...)` para recibir un callback después de que una solicitud de asociación sea aprobada o denegada: ```ts export default { @@ -608,21 +608,21 @@ Campos de la carga útil del callback: - `status`: `"approved"` o `"denied"` - `decision`: `"allow-once"`, `"allow-always"` o `"deny"` -- `binding`: la vinculación resuelta para solicitudes aprobadas -- `request`: el resumen de la solicitud original, sugerencia de desvinculación, ID del remitente y +- `binding`: la asociación resuelta para solicitudes aprobadas +- `request`: el resumen de la solicitud original, sugerencia de desvinculación, id del remitente y metadatos de la conversación -Este callback es solo de notificación. No cambia quién tiene permiso para vincular una -conversación y se ejecuta después de que finaliza el manejo de aprobación del núcleo. +Este callback es solo de notificación. No cambia quién tiene permitido asociar una +conversación, y se ejecuta después de que termine el manejo de aprobación del core. ## Hooks de tiempo de ejecución del proveedor Los plugins de proveedor ahora tienen dos capas: -- metadatos del manifiesto: `providerAuthEnvVars` para una búsqueda ligera de autenticación del proveedor por entorno - antes de cargar el tiempo de ejecución, `providerAuthAliases` para variantes del proveedor que comparten - autenticación, `channelEnvVars` para una búsqueda ligera de entorno/configuración del canal antes de cargar el tiempo de ejecución, - además de `providerAuthChoices` para etiquetas ligeras de incorporación/elección de autenticación y +- metadatos del manifest: `providerAuthEnvVars` para búsquedas económicas de autenticación del proveedor mediante variables de entorno + antes de cargar el tiempo de ejecución, `providerAuthAliases` para variantes de proveedor que comparten + autenticación, `channelEnvVars` para búsquedas económicas de entorno/configuración del canal antes de la carga del tiempo de ejecución, + además de `providerAuthChoices` para etiquetas económicas de incorporación/opciones de autenticación y metadatos de flags de CLI antes de cargar el tiempo de ejecución - hooks en tiempo de configuración: `catalog` / `discovery` heredado más `applyConfigDefaults` - hooks de tiempo de ejecución: `normalizeModelId`, `normalizeTransport`, @@ -645,87 +645,87 @@ Los plugins de proveedor ahora tienen dos capas: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw sigue poseyendo el bucle genérico del agente, el failover, el manejo de transcripciones y la -política de herramientas. Estos hooks son la superficie de extensión para comportamiento específico del proveedor sin -necesitar un transporte de inferencia completamente personalizado. +OpenClaw sigue siendo propietario del bucle genérico del agente, failover, manejo de +transcripciones y política de herramientas. Estos hooks son la superficie de extensión para comportamiento específico del proveedor sin +necesitar todo un transporte de inferencia personalizado. -Usa el `providerAuthEnvVars` del manifiesto cuando el proveedor tenga credenciales basadas en entorno -que las rutas genéricas de autenticación/estado/selector de modelo deban ver sin cargar el tiempo de ejecución del plugin. -Usa `providerAuthAliases` del manifiesto cuando un ID de proveedor deba reutilizar -las variables de entorno, perfiles de autenticación, autenticación respaldada por configuración y -la opción de incorporación de clave API de otro ID de proveedor. Usa `providerAuthChoices` del manifiesto cuando las -superficies de CLI de incorporación/elección de autenticación deban conocer el ID de elección del proveedor, las etiquetas de grupo -y la configuración simple de autenticación con un solo flag sin cargar el tiempo de ejecución del proveedor. Mantén `envVars` del tiempo de ejecución del proveedor para sugerencias orientadas al operador, como etiquetas de incorporación o variables -de configuración de client-id/client-secret de OAuth. +Usa el manifest `providerAuthEnvVars` cuando el proveedor tenga credenciales basadas en variables de entorno +que las rutas genéricas de autenticación/estado/selector de modelos deban ver sin cargar el tiempo de ejecución del plugin. +Usa el manifest `providerAuthAliases` cuando un id de proveedor deba reutilizar +las variables de entorno, perfiles de autenticación, autenticación respaldada por configuración y la opción de incorporación con clave API +de otro id de proveedor. Usa el manifest `providerAuthChoices` cuando las +superficies de CLI de incorporación/opción de autenticación deban conocer el id de opción del proveedor, las etiquetas de grupo y la lógica +simple de autenticación con un solo flag sin cargar el tiempo de ejecución del proveedor. Mantén `envVars` del tiempo de ejecución del proveedor para sugerencias orientadas al operador, como etiquetas de incorporación o variables de +configuración de client-id/client-secret de OAuth. -Usa `channelEnvVars` del manifiesto cuando un canal tenga autenticación o configuración basada en entorno que -los prompts genéricos de fallback de entorno del shell, comprobaciones de configuración/estado o configuración deban ver +Usa el manifest `channelEnvVars` cuando un canal tenga autenticación o configuración impulsada por variables de entorno que +los mecanismos genéricos de fallback del entorno de shell, verificaciones de config/status o prompts de configuración deban ver sin cargar el tiempo de ejecución del canal. -### Orden de hooks y uso +### Orden y uso de hooks -Para los plugins de modelo/proveedor, OpenClaw llama a los hooks aproximadamente en este orden. +Para plugins de modelo/proveedor, OpenClaw llama a los hooks aproximadamente en este orden. La columna “Cuándo usar” es la guía rápida de decisión. -| # | Hook | Qué hace | Cuándo usar | +| # | Hook | Qué hace | Cuándo usarlo | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Publica la configuración del proveedor en `models.providers` durante la generación de `models.json` | El proveedor posee un catálogo o valores predeterminados de URL base | -| 2 | `applyConfigDefaults` | Aplica valores predeterminados globales propiedad del proveedor durante la materialización de la configuración | Los valores predeterminados dependen del modo de autenticación, del entorno o de la semántica de la familia de modelos del proveedor | -| -- | _(built-in model lookup)_ | OpenClaw prueba primero la ruta normal de registro/catálogo | _(no es un hook de plugin)_ | -| 3 | `normalizeModelId` | Normaliza alias heredados o de vista previa de ID de modelo antes de la búsqueda | El proveedor posee la limpieza de alias antes de la resolución del modelo canónico | -| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` de la familia del proveedor antes del ensamblado genérico del modelo | El proveedor posee la limpieza del transporte para ID de proveedor personalizados en la misma familia de transporte | -| 5 | `normalizeConfig` | Normaliza `models.providers.` antes de la resolución en tiempo de ejecución/del proveedor | El proveedor necesita limpieza de configuración que debe vivir con el plugin; los asistentes integrados de la familia Google también respaldan entradas de configuración de Google compatibles | -| 6 | `applyNativeStreamingUsageCompat` | Aplica reescrituras de compatibilidad de uso de streaming nativo a proveedores de configuración | El proveedor necesita correcciones de metadatos de uso de streaming nativo impulsadas por endpoints | -| 7 | `resolveConfigApiKey` | Resuelve autenticación con marcador de entorno para proveedores de configuración antes de cargar la autenticación de tiempo de ejecución | El proveedor tiene resolución de clave API con marcador de entorno propiedad del proveedor; `amazon-bedrock` también tiene aquí un resolvedor integrado de marcador de entorno AWS | +| 1 | `catalog` | Publica la configuración del proveedor en `models.providers` durante la generación de `models.json` | El proveedor es propietario de un catálogo o de valores predeterminados de URL base | +| 2 | `applyConfigDefaults` | Aplica valores predeterminados globales de configuración propiedad del proveedor durante la materialización de la configuración | Los valores predeterminados dependen del modo de autenticación, del entorno o de la semántica de la familia de modelos del proveedor | +| -- | _(búsqueda de modelos integrados)_ | OpenClaw prueba primero la ruta normal de registro/catálogo | _(no es un hook de plugin)_ | +| 3 | `normalizeModelId` | Normaliza aliases heredados o de vista previa de id de modelo antes de la búsqueda | El proveedor es propietario de la limpieza de aliases antes de la resolución canónica del modelo | +| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` de la familia del proveedor antes del ensamblado genérico del modelo | El proveedor es propietario de la limpieza del transporte para ids de proveedor personalizados dentro de la misma familia de transporte | +| 5 | `normalizeConfig` | Normaliza `models.providers.` antes de la resolución del proveedor/en tiempo de ejecución | El proveedor necesita una limpieza de configuración que deba vivir con el plugin; los asistentes agrupados de la familia Google también respaldan las entradas compatibles de configuración de Google | +| 6 | `applyNativeStreamingUsageCompat` | Aplica reescrituras de compatibilidad de uso de streaming nativo a los proveedores de configuración | El proveedor necesita correcciones de metadatos de uso de streaming nativo basadas en endpoints | +| 7 | `resolveConfigApiKey` | Resuelve autenticación por marcador de entorno para proveedores de configuración antes de cargar la autenticación en tiempo de ejecución | El proveedor tiene resolución de clave API por marcador de entorno propiedad del proveedor; `amazon-bedrock` también tiene aquí un resolvedor integrado de marcador de entorno de AWS | | 8 | `resolveSyntheticAuth` | Expone autenticación local/alojada por uno mismo o respaldada por configuración sin persistir texto sin formato | El proveedor puede operar con un marcador de credencial sintética/local | -| 9 | `resolveExternalAuthProfiles` | Superpone perfiles de autenticación externa propiedad del proveedor; el valor predeterminado de `persistence` es `runtime-only` para credenciales propiedad de CLI/app | El proveedor reutiliza credenciales de autenticación externa sin persistir tokens de actualización copiados | -| 10 | `shouldDeferSyntheticProfileAuth` | Relega marcadores de posición sintéticos almacenados detrás de autenticación respaldada por entorno/configuración | El proveedor almacena perfiles sintéticos de marcador de posición que no deben ganar prioridad | -| 11 | `resolveDynamicModel` | Fallback síncrono para ID de modelo propiedad del proveedor que aún no están en el registro local | El proveedor acepta ID de modelo arbitrarios del upstream | -| 12 | `prepareDynamicModel` | Calentamiento asíncrono; luego `resolveDynamicModel` vuelve a ejecutarse | El proveedor necesita metadatos de red antes de resolver ID desconocidos | -| 13 | `normalizeResolvedModel` | Reescritura final antes de que el embedded runner use el modelo resuelto | El proveedor necesita reescrituras de transporte pero sigue usando un transporte del núcleo | -| 14 | `contributeResolvedModelCompat` | Aporta flags de compatibilidad para modelos del proveedor detrás de otro transporte compatible | El proveedor reconoce sus propios modelos en transportes proxy sin asumir el control del proveedor | -| 15 | `capabilities` | Metadatos de transcripción/herramientas propiedad del proveedor usados por la lógica compartida del núcleo | El proveedor necesita particularidades de la transcripción o de la familia del proveedor | +| 9 | `resolveExternalAuthProfiles` | Superpone perfiles de autenticación externa propiedad del proveedor; el valor predeterminado de `persistence` es `runtime-only` para credenciales propiedad de CLI/app | El proveedor reutiliza credenciales de autenticación externas sin persistir tokens de actualización copiados | +| 10 | `shouldDeferSyntheticProfileAuth` | Hace que los marcadores de posición de perfiles sintéticos almacenados queden por detrás de la autenticación respaldada por entorno/configuración | El proveedor almacena perfiles de marcador de posición sintéticos que no deberían tener precedencia | +| 11 | `resolveDynamicModel` | Fallback síncrono para ids de modelo propiedad del proveedor que todavía no están en el registro local | El proveedor acepta ids de modelo arbitrarios del upstream | +| 12 | `prepareDynamicModel` | Calentamiento asíncrono; luego `resolveDynamicModel` se ejecuta de nuevo | El proveedor necesita metadatos de red antes de resolver ids desconocidos | +| 13 | `normalizeResolvedModel` | Reescritura final antes de que el embedded runner use el modelo resuelto | El proveedor necesita reescrituras de transporte pero sigue usando un transporte del core | +| 14 | `contributeResolvedModelCompat` | Aporta flags de compatibilidad para modelos del proveedor detrás de otro transporte compatible | El proveedor reconoce sus propios modelos en transportes proxy sin asumir la propiedad del proveedor | +| 15 | `capabilities` | Metadatos de transcripción/herramientas propiedad del proveedor usados por la lógica compartida del core | El proveedor necesita particularidades de transcripción/familia de proveedor | | 16 | `normalizeToolSchemas` | Normaliza esquemas de herramientas antes de que el embedded runner los vea | El proveedor necesita limpieza de esquemas de la familia de transporte | -| 17 | `inspectToolSchemas` | Expone diagnósticos de esquema propiedad del proveedor después de la normalización | El proveedor quiere advertencias de palabras clave sin enseñar al núcleo reglas específicas del proveedor | -| 18 | `resolveReasoningOutputMode` | Selecciona el contrato de salida de razonamiento nativo frente al etiquetado | El proveedor necesita razonamiento etiquetado/salida final en lugar de campos nativos | -| 19 | `prepareExtraParams` | Normalización de parámetros de solicitud antes de los envoltorios genéricos de opciones de stream | El proveedor necesita parámetros de solicitud predeterminados o limpieza de parámetros por proveedor | -| 20 | `createStreamFn` | Reemplaza por completo la ruta normal de stream con un transporte personalizado | El proveedor necesita un protocolo de cable personalizado, no solo un envoltorio | -| 21 | `wrapStreamFn` | Envoltorio del stream después de aplicar los envoltorios genéricos | El proveedor necesita envoltorios de compatibilidad de encabezados/cuerpo/modelo de la solicitud sin un transporte personalizado | -| 22 | `resolveTransportTurnState` | Adjunta encabezados o metadatos nativos por turno al transporte | El proveedor quiere que transportes genéricos envíen identidad de turno nativa del proveedor | -| 23 | `resolveWebSocketSessionPolicy` | Adjunta encabezados nativos de WebSocket o política de enfriamiento de sesión | El proveedor quiere que transportes WS genéricos ajusten encabezados de sesión o la política de fallback | -| 24 | `formatApiKey` | Formateador de perfil de autenticación: el perfil almacenado se convierte en la cadena `apiKey` de tiempo de ejecución | El proveedor almacena metadatos adicionales de autenticación y necesita una forma de token de tiempo de ejecución personalizada | -| 25 | `refreshOAuth` | Sustitución de actualización de OAuth para endpoints de actualización personalizados o política de fallo de actualización | El proveedor no encaja con los refrescadores compartidos `pi-ai` | -| 26 | `buildAuthDoctorHint` | Sugerencia de reparación anexada cuando falla la actualización de OAuth | El proveedor necesita orientación de reparación de autenticación propiedad del proveedor después de un fallo de actualización | -| 27 | `matchesContextOverflowError` | Comparador propiedad del proveedor para desbordamiento de ventana de contexto | El proveedor tiene errores de desbordamiento sin procesar que la heurística genérica no detectaría | -| 28 | `classifyFailoverReason` | Clasificación de motivo de failover propiedad del proveedor | El proveedor puede mapear errores sin procesar de API/transporte a límite de tasa/sobrecarga/etc. | -| 29 | `isCacheTtlEligible` | Política de caché de prompt para proveedores proxy/backhaul | El proveedor necesita control específico del proxy para TTL de caché | -| 30 | `buildMissingAuthMessage` | Sustitución del mensaje genérico de recuperación por autenticación faltante | El proveedor necesita una sugerencia específica del proveedor para recuperar autenticación faltante | -| 31 | `suppressBuiltInModel` | Supresión de modelos upstream obsoletos más una sugerencia opcional de error orientada al usuario | El proveedor necesita ocultar filas upstream obsoletas o reemplazarlas por una sugerencia del proveedor | -| 32 | `augmentModelCatalog` | Filas de catálogo sintéticas/finales agregadas después del descubrimiento | El proveedor necesita filas sintéticas de compatibilidad futura en `models list` y selectores | -| 33 | `isBinaryThinking` | Alternancia de razonamiento activado/desactivado para proveedores de pensamiento binario | El proveedor expone solo pensamiento binario activado/desactivado | -| 34 | `supportsXHighThinking` | Compatibilidad con razonamiento `xhigh` para modelos seleccionados | El proveedor quiere `xhigh` solo en un subconjunto de modelos | -| 35 | `resolveDefaultThinkingLevel` | Nivel `/think` predeterminado para una familia de modelos específica | El proveedor posee la política predeterminada de `/think` para una familia de modelos | -| 36 | `isModernModelRef` | Comparador de modelos modernos para filtros de perfiles activos y selección de smoke | El proveedor posee la coincidencia de modelos preferidos para live/smoke | -| 37 | `prepareRuntimeAuth` | Intercambia una credencial configurada por el token/clave real de tiempo de ejecución justo antes de la inferencia | El proveedor necesita un intercambio de token o una credencial de solicitud de corta duración | -| 38 | `resolveUsageAuth` | Resuelve credenciales de uso/facturación para `/usage` y superficies relacionadas de estado | El proveedor necesita análisis personalizado de tokens de uso/cuota o una credencial de uso diferente | -| 39 | `fetchUsageSnapshot` | Obtiene y normaliza instantáneas de uso/cuota específicas del proveedor después de resolver la autenticación | El proveedor necesita un endpoint de uso específico del proveedor o un analizador de carga útil | -| 40 | `createEmbeddingProvider` | Construye un adaptador de embeddings propiedad del proveedor para memoria/búsqueda | El comportamiento de embeddings para memoria pertenece al plugin del proveedor | -| 41 | `buildReplayPolicy` | Devuelve una política de replay que controla el manejo de transcripciones para el proveedor | El proveedor necesita una política personalizada de transcripciones (por ejemplo, eliminación de bloques de razonamiento) | -| 42 | `sanitizeReplayHistory` | Reescribe el historial de replay después de la limpieza genérica de transcripciones | El proveedor necesita reescrituras de replay específicas del proveedor además de los asistentes compartidos de compactación | +| 17 | `inspectToolSchemas` | Expone diagnósticos de esquema propiedad del proveedor después de la normalización | El proveedor quiere advertencias de palabras clave sin enseñar al core reglas específicas del proveedor | +| 18 | `resolveReasoningOutputMode` | Selecciona el contrato de salida de razonamiento nativo frente al etiquetado | El proveedor necesita salida final/de razonamiento etiquetada en lugar de campos nativos | +| 19 | `prepareExtraParams` | Normalización de parámetros de solicitud antes de los wrappers genéricos de opciones de stream | El proveedor necesita parámetros de solicitud predeterminados o limpieza de parámetros por proveedor | +| 20 | `createStreamFn` | Reemplaza por completo la ruta normal de stream con un transporte personalizado | El proveedor necesita un protocolo de cable personalizado, no solo un wrapper | +| 21 | `wrapStreamFn` | Wrapper de stream después de aplicar los wrappers genéricos | El proveedor necesita wrappers de compatibilidad de encabezados/cuerpo/modelo de solicitud sin un transporte personalizado | +| 22 | `resolveTransportTurnState` | Adjunta encabezados o metadatos nativos por turno del transporte | El proveedor quiere que los transportes genéricos envíen identidad de turno nativa del proveedor | +| 23 | `resolveWebSocketSessionPolicy` | Adjunta encabezados nativos de WebSocket o política de enfriamiento de sesión | El proveedor quiere que los transportes genéricos de WS ajusten los encabezados de sesión o la política de fallback | +| 24 | `formatApiKey` | Formateador de perfil de autenticación: el perfil almacenado se convierte en la cadena `apiKey` del tiempo de ejecución | El proveedor almacena metadatos adicionales de autenticación y necesita una forma personalizada del token en tiempo de ejecución | +| 25 | `refreshOAuth` | Reemplazo de actualización de OAuth para endpoints de actualización personalizados o política de fallo de actualización | El proveedor no encaja en los refrescadores compartidos `pi-ai` | +| 26 | `buildAuthDoctorHint` | Sugerencia de reparación agregada cuando falla la actualización de OAuth | El proveedor necesita orientación de reparación de autenticación propiedad del proveedor tras un fallo de actualización | +| 27 | `matchesContextOverflowError` | Comparador de desbordamiento de ventana de contexto propiedad del proveedor | El proveedor tiene errores de desbordamiento sin procesar que las heurísticas genéricas no detectarían | +| 28 | `classifyFailoverReason` | Clasificación de razones de failover propiedad del proveedor | El proveedor puede mapear errores sin procesar de API/transporte a límite de tasa, sobrecarga, etc. | +| 29 | `isCacheTtlEligible` | Política de caché de prompts para proveedores proxy/backhaul | El proveedor necesita control de TTL de caché específico de proxy | +| 30 | `buildMissingAuthMessage` | Reemplazo del mensaje genérico de recuperación por falta de autenticación | El proveedor necesita una sugerencia de recuperación por falta de autenticación específica del proveedor | +| 31 | `suppressBuiltInModel` | Supresión de modelos upstream obsoletos más sugerencia opcional de error orientada al usuario | El proveedor necesita ocultar filas upstream obsoletas o reemplazarlas con una sugerencia del proveedor | +| 32 | `augmentModelCatalog` | Filas sintéticas/finales de catálogo agregadas después del descubrimiento | El proveedor necesita filas sintéticas de compatibilidad futura en `models list` y selectores | +| 33 | `isBinaryThinking` | Alternancia de razonamiento activado/desactivado para proveedores de razonamiento binario | El proveedor expone solo razonamiento binario activado/desactivado | +| 34 | `supportsXHighThinking` | Compatibilidad con razonamiento `xhigh` para modelos seleccionados | El proveedor quiere `xhigh` solo en un subconjunto de modelos | +| 35 | `resolveDefaultThinkingLevel` | Nivel predeterminado de `/think` para una familia de modelos específica | El proveedor es propietario de la política predeterminada de `/think` para una familia de modelos | +| 36 | `isModernModelRef` | Comparador de modelos modernos para filtros de perfiles en vivo y selección de smoke | El proveedor es propietario de la coincidencia de modelos preferidos para pruebas en vivo/smoke | +| 37 | `prepareRuntimeAuth` | Intercambia una credencial configurada por el token/clave real del tiempo de ejecución justo antes de la inferencia | El proveedor necesita un intercambio de token o una credencial de solicitud de corta duración | +| 38 | `resolveUsageAuth` | Resuelve credenciales de uso/facturación para `/usage` y superficies de estado relacionadas | El proveedor necesita análisis personalizado de tokens de uso/cuota o una credencial de uso diferente | +| 39 | `fetchUsageSnapshot` | Obtiene y normaliza snapshots de uso/cuota específicos del proveedor después de resolver la autenticación | El proveedor necesita un endpoint de uso específico del proveedor o un analizador de carga útil | +| 40 | `createEmbeddingProvider` | Construye un adaptador de embeddings propiedad del proveedor para memory/search | El comportamiento de embeddings de memory pertenece al plugin del proveedor | +| 41 | `buildReplayPolicy` | Devuelve una política de replay que controla el manejo de transcripciones para el proveedor | El proveedor necesita una política de transcripción personalizada (por ejemplo, eliminación de bloques de razonamiento) | +| 42 | `sanitizeReplayHistory` | Reescribe el historial de replay después de la limpieza genérica de transcripciones | El proveedor necesita reescrituras específicas del proveedor para replay más allá de los asistentes compartidos de compactación | | 43 | `validateReplayTurns` | Validación final o remodelado de turnos de replay antes del embedded runner | El transporte del proveedor necesita una validación de turnos más estricta después de la sanitización genérica | | 44 | `onModelSelected` | Ejecuta efectos secundarios posteriores a la selección propiedad del proveedor | El proveedor necesita telemetría o estado propiedad del proveedor cuando un modelo pasa a estar activo | `normalizeModelId`, `normalizeTransport` y `normalizeConfig` primero comprueban el -plugin de proveedor coincidente y luego continúan con otros plugins de proveedor con capacidad de hook -hasta que uno cambie realmente el ID del modelo o el transporte/la configuración. Eso mantiene funcionando -los shims de alias/compatibilidad del proveedor sin exigir que quien llama sepa qué -plugin integrado posee la reescritura. Si ningún hook de proveedor reescribe una entrada de configuración compatible -de la familia Google, el normalizador de configuración integrado de Google sigue aplicando +plugin de proveedor coincidente y luego recorren el resto de plugins de proveedor con capacidad de hooks +hasta que uno realmente cambia el id del modelo o el transporte/configuración. Eso mantiene +funcionando los shims de alias/proveedor de compatibilidad sin exigir que quien llama sepa qué +plugin agrupado es propietario de la reescritura. Si ningún hook de proveedor reescribe una entrada de configuración compatible +de la familia Google, el normalizador de configuración agrupado de Google sigue aplicando esa limpieza de compatibilidad. -Si el proveedor necesita un protocolo de cable completamente personalizado o un ejecutor de solicitudes personalizado, -esa es otra clase de extensión. Estos hooks son para comportamiento del proveedor que -sigue ejecutándose en el bucle normal de inferencia de OpenClaw. +Si el proveedor necesita un protocolo de cable totalmente personalizado o un ejecutor de solicitudes personalizado, +esa es una clase distinta de extensión. Estos hooks son para comportamiento de proveedor +que sigue ejecutándose en el bucle de inferencia normal de OpenClaw. ### Ejemplo de proveedor @@ -786,92 +786,107 @@ api.registerProvider({ - Anthropic usa `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - y `wrapStreamFn` porque posee la compatibilidad futura de Claude 4.6, - sugerencias de familia del proveedor, orientación para reparación de autenticación, integración de endpoint de uso, - elegibilidad de caché de prompt, valores predeterminados de configuración conscientes de la autenticación, política predeterminada/adaptativa de pensamiento de Claude y modelado de stream específico de Anthropic para + y `wrapStreamFn` porque es propietario de la compatibilidad futura de Claude 4.6, + de las sugerencias de familia de proveedor, de la guía de reparación de autenticación, de la integración + del endpoint de uso, de la elegibilidad de caché de prompts, de los valores predeterminados de configuración conscientes de autenticación, de la política + predeterminada/adaptativa de pensamiento de Claude y del modelado de stream específico de Anthropic para encabezados beta, `/fast` / `serviceTier` y `context1m`. -- Los asistentes de stream específicos de Claude de Anthropic permanecen por ahora en la propia unión pública - `api.ts` / `contract-api.ts` del plugin integrado. Esa superficie del paquete +- Los asistentes de stream específicos de Claude de Anthropic permanecen por ahora en el + seam público propio `api.ts` / `contract-api.ts` del plugin agrupado. Esa superficie del paquete exporta `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` y los constructores de envoltorios de Anthropic de nivel inferior, en lugar de ampliar el SDK genérico en torno a las reglas de encabezados beta de un único + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` y los builders + de wrappers de Anthropic de más bajo nivel en lugar de ampliar el SDK genérico en torno a las reglas de encabezados beta de un solo proveedor. - OpenAI usa `resolveDynamicModel`, `normalizeResolvedModel` y - `capabilities` además de `buildMissingAuthMessage`, `suppressBuiltInModel`, + `capabilities`, además de `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef` - porque posee la compatibilidad futura de GPT-5.4, la normalización directa de OpenAI - `openai-completions` -> `openai-responses`, sugerencias de autenticación compatibles con Codex, - la supresión de Spark, filas sintéticas de lista OpenAI y la política de pensamiento/modelo activo de GPT-5; la familia de stream `openai-responses-defaults` posee los envoltorios nativos compartidos de OpenAI Responses para - encabezados de atribución, + porque es propietario de la compatibilidad futura de GPT-5.4, de la normalización directa de OpenAI + `openai-completions` -> `openai-responses`, de las sugerencias de autenticación conscientes de Codex, + de la supresión de Spark, de las filas sintéticas de lista de OpenAI y de la política de pensamiento/modelo en vivo de GPT-5; la familia de streams `openai-responses-defaults` es propietaria de los wrappers compartidos nativos de OpenAI Responses para encabezados de atribución, `/fast`/`serviceTier`, verbosidad de texto, búsqueda web nativa de Codex, - modelado de carga útil de compatibilidad de razonamiento y gestión de contexto de Responses. -- OpenRouter usa `catalog` además de `resolveDynamicModel` y - `prepareDynamicModel` porque el proveedor es de paso y puede exponer nuevos - ID de modelo antes de que se actualice el catálogo estático de OpenClaw; también usa + modelado de carga útil compatible con razonamiento y gestión del contexto de Responses. +- OpenRouter usa `catalog`, además de `resolveDynamicModel` y + `prepareDynamicModel`, porque el proveedor es de paso y puede exponer nuevos + ids de modelo antes de que se actualice el catálogo estático de OpenClaw; también usa `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` para mantener - fuera del núcleo los encabezados de solicitud específicos del proveedor, metadatos de enrutamiento, parches de razonamiento y la política de caché de prompt. Su política de replay proviene de la - familia `passthrough-gemini`, mientras que la familia de stream `openrouter-thinking` - posee la inyección de razonamiento de proxy y los saltos de modelo no compatible / `auto`. + fuera del core los encabezados de solicitud específicos del proveedor, los metadatos de enrutamiento, los parches de razonamiento y + la política de caché de prompts. Su política de replay proviene de la + familia `passthrough-gemini`, mientras que la familia de streams `openrouter-thinking` + es propietaria de la inyección de razonamiento proxy y de las omisiones de modelos no compatibles / `auto`. - GitHub Copilot usa `catalog`, `auth`, `resolveDynamicModel` y - `capabilities` además de `prepareRuntimeAuth` y `fetchUsageSnapshot` porque + `capabilities`, además de `prepareRuntimeAuth` y `fetchUsageSnapshot`, porque necesita inicio de sesión de dispositivo propiedad del proveedor, comportamiento de fallback de modelo, particularidades de transcripción de Claude, un intercambio de token de GitHub -> token de Copilot y un endpoint de uso propiedad del proveedor. - OpenAI Codex usa `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` y `augmentModelCatalog` además de - `prepareExtraParams`, `resolveUsageAuth` y `fetchUsageSnapshot` porque - sigue ejecutándose en transportes OpenAI del núcleo, pero posee su normalización de transporte/URL base, - política de fallback de actualización OAuth, elección de transporte predeterminada, - filas sintéticas de catálogo de Codex e integración del endpoint de uso de ChatGPT; comparte la misma familia de stream `openai-responses-defaults` que OpenAI directo. + `normalizeResolvedModel`, `refreshOAuth` y `augmentModelCatalog`, además de + `prepareExtraParams`, `resolveUsageAuth` y `fetchUsageSnapshot`, porque + sigue ejecutándose sobre los transportes centrales de OpenAI, pero es propietario de su normalización de transporte/base URL, + de la política de fallback de actualización de OAuth, de la elección de transporte predeterminada, + de las filas sintéticas de catálogo de Codex y de la integración del endpoint de uso de ChatGPT; comparte + la misma familia de streams `openai-responses-defaults` que OpenAI directo. - Google AI Studio y Gemini CLI OAuth usan `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` e `isModernModelRef` porque la - familia de replay `google-gemini` posee el fallback de compatibilidad futura de Gemini 3.1, - validación nativa de replay de Gemini, saneamiento de replay de arranque, modo de - salida de razonamiento etiquetado y coincidencia de modelos modernos, mientras que la - familia de stream `google-thinking` posee la normalización de carga útil de pensamiento de Gemini; + familia de replay `google-gemini` es propietaria del fallback de compatibilidad futura de Gemini 3.1, + de la validación nativa de replay de Gemini, de la sanitización de replay de bootstrap, + del modo de salida de razonamiento etiquetado y de la coincidencia de modelos modernos, mientras que la + familia de streams `google-thinking` es propietaria de la normalización de la carga útil de pensamiento de Gemini; Gemini CLI OAuth también usa `formatApiKey`, `resolveUsageAuth` y - `fetchUsageSnapshot` para formateo de tokens, análisis de tokens y conexión del endpoint de cuota. -- Anthropic Vertex usa `buildReplayPolicy` mediante la - familia de replay `anthropic-by-model` para que la limpieza de replay específica de Claude permanezca - limitada a los ID de Claude en lugar de a todo transporte `anthropic-messages`. + `fetchUsageSnapshot` para el formateo de tokens, el análisis de tokens y la conexión + del endpoint de cuota. +- Anthropic Vertex usa `buildReplayPolicy` a través de la + familia de replay `anthropic-by-model` para que la limpieza de replay específica de Claude quede + acotada a ids de Claude en lugar de a cada transporte `anthropic-messages`. - Amazon Bedrock usa `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` y `resolveDefaultThinkingLevel` porque posee la clasificación específica de Bedrock para errores de limitación/no listo/desbordamiento de contexto - en tráfico Anthropic sobre Bedrock; su política de replay sigue compartiendo la misma protección - solo para Claude de `anthropic-by-model`. + `classifyFailoverReason` y `resolveDefaultThinkingLevel` porque es propietario + de la clasificación de errores específicos de Bedrock de limitación/no listo/desbordamiento de contexto + para tráfico Anthropic-on-Bedrock; su política de replay sigue compartiendo la misma + protección solo para Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode y Opencode Go usan `buildReplayPolicy` - mediante la familia de replay `passthrough-gemini` porque proxifican modelos Gemini - a través de transportes compatibles con OpenAI y necesitan saneamiento de - firma de pensamiento de Gemini sin validación nativa de replay de Gemini ni reescrituras de arranque. -- MiniMax usa `buildReplayPolicy` mediante la - familia de replay `hybrid-anthropic-openai` porque un proveedor posee tanto semántica - de mensajes Anthropic como semántica compatible con OpenAI; mantiene - la eliminación de bloques de pensamiento solo de Claude en el lado Anthropic mientras sustituye el modo de - salida de razonamiento de vuelta a nativo, y la familia de stream `minimax-fast-mode` posee reescrituras de modelo en modo rápido en la ruta de stream compartida. -- Moonshot usa `catalog` además de `wrapStreamFn` porque sigue usando el - transporte compartido de OpenAI, pero necesita normalización de carga útil de pensamiento propiedad del proveedor; la familia de stream `moonshot-thinking` mapea configuración más estado de `/think` en su carga útil nativa de pensamiento binario. + a través de la familia de replay `passthrough-gemini` porque hacen proxy de modelos Gemini + mediante transportes compatibles con OpenAI y necesitan + sanitización de firmas de pensamiento de Gemini sin validación nativa de replay de Gemini ni reescrituras + de bootstrap. +- MiniMax usa `buildReplayPolicy` a través de la + familia de replay `hybrid-anthropic-openai` porque un solo proveedor es propietario tanto de semántica + de mensajes Anthropic como de compatibilidad con OpenAI; mantiene la eliminación de bloques de pensamiento exclusivos de Claude + en el lado Anthropic mientras reemplaza el modo de salida de razonamiento de vuelta a nativo, y la familia de streams `minimax-fast-mode` es propietaria de las reescrituras de modelos de modo rápido en la ruta de stream compartida. +- Moonshot usa `catalog`, además de `wrapStreamFn`, porque sigue usando el transporte + compartido de OpenAI pero necesita normalización de carga útil de pensamiento propiedad del proveedor; la + familia de streams `moonshot-thinking` asigna config más estado `/think` a su + carga útil nativa de pensamiento binario. - Kilocode usa `catalog`, `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` porque necesita encabezados de solicitud propiedad del proveedor, - normalización de carga útil de razonamiento, sugerencias de transcripción de Gemini y control de TTL de caché de Anthropic; la familia de stream `kilocode-thinking` mantiene la inyección del pensamiento Kilo en la ruta de stream proxy compartida mientras omite `kilo/auto` y - otros ID de modelo proxy que no admiten cargas útiles explícitas de razonamiento. + normalización de carga útil de razonamiento, sugerencias de transcripción de Gemini y control + de TTL de caché de Anthropic; la familia de streams `kilocode-thinking` mantiene la inyección + de pensamiento de Kilo en la ruta de stream proxy compartida mientras omite `kilo/auto` y + otros ids de modelo proxy que no admiten cargas útiles explícitas de razonamiento. - Z.AI usa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` y `fetchUsageSnapshot` porque posee el fallback de GLM-5, - los valores predeterminados de `tool_stream`, la UX de pensamiento binario, la coincidencia de modelos modernos y tanto la autenticación de uso como la obtención de cuota; la familia de stream `tool-stream-default-on` mantiene el envoltorio predeterminado activado de `tool_stream` fuera del código manual por proveedor. + `resolveUsageAuth` y `fetchUsageSnapshot` porque es propietario del fallback de GLM-5, + de los valores predeterminados de `tool_stream`, de la UX de pensamiento binario, de la coincidencia de modelos modernos y tanto + de la autenticación de uso como de la obtención de cuota; la familia de streams `tool-stream-default-on` mantiene el wrapper predeterminado activado `tool_stream` fuera del pegamento manuscrito por proveedor. - xAI usa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef` - porque posee la normalización nativa del transporte xAI Responses, reescrituras de alias de modo rápido de Grok, `tool_stream` predeterminado, limpieza estricta de herramientas / carga útil de razonamiento, reutilización de autenticación fallback para herramientas propiedad del plugin, resolución de modelos Grok con compatibilidad futura y parches de compatibilidad propiedad del proveedor como el perfil de esquema de herramientas de xAI, - palabras clave de esquema no compatibles, `web_search` nativo y decodificación de argumentos de llamadas de herramientas con entidades HTML. -- Mistral, OpenCode Zen y OpenCode Go usan solo `capabilities` para mantener las particularidades de transcripción/herramientas fuera del núcleo. -- Los proveedores integrados solo de catálogo como `byteplus`, `cloudflare-ai-gateway`, + porque es propietario de la normalización nativa de transporte xAI Responses, de las reescrituras de alias de modo rápido de Grok, del valor predeterminado `tool_stream`, de la limpieza estricta de herramientas / carga útil de razonamiento, + de la reutilización de autenticación de fallback para herramientas propiedad del plugin, de la resolución de modelos Grok con compatibilidad futura + y de parches de compatibilidad propiedad del proveedor, como el perfil de esquema de herramientas de xAI, + palabras clave de esquema no compatibles, `web_search` nativo y la decodificación de argumentos de llamadas a herramientas + con entidades HTML. +- Mistral, OpenCode Zen y OpenCode Go usan solo `capabilities` para mantener + fuera del core las particularidades de transcripción/herramientas. +- Los proveedores agrupados solo de catálogo como `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` y `volcengine` usan solo `catalog`. -- Qwen usa `catalog` para su proveedor de texto además de registros compartidos de comprensión de medios y generación de video para sus superficies multimodales. -- MiniMax y Xiaomi usan `catalog` además de hooks de uso porque su comportamiento de `/usage` - es propiedad del plugin aunque la inferencia siga ejecutándose mediante transportes compartidos. +- Qwen usa `catalog` para su proveedor de texto, además de registros compartidos de comprensión de medios y + generación de video para sus superficies multimodales. +- MiniMax y Xiaomi usan `catalog`, además de hooks de uso, porque su comportamiento `/usage` + es propiedad del plugin aunque la inferencia siga ejecutándose a través de los transportes compartidos. ## Asistentes de tiempo de ejecución -Los plugins pueden acceder a asistentes seleccionados del núcleo mediante `api.runtime`. Para TTS: +Los plugins pueden acceder a asistentes seleccionados del core mediante `api.runtime`. Para TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -892,12 +907,12 @@ const voices = await api.runtime.tts.listVoices({ Notas: -- `textToSpeech` devuelve la carga útil normal de salida TTS del núcleo para superficies de archivo/nota de voz. -- Usa la configuración central `messages.tts` y la selección del proveedor. -- Devuelve un búfer de audio PCM + frecuencia de muestreo. Los plugins deben remuestrear/codificar para los proveedores. +- `textToSpeech` devuelve la carga útil de salida TTS normal del core para superficies de archivo/nota de voz. +- Usa la configuración del core `messages.tts` y la selección de proveedor. +- Devuelve buffer de audio PCM + frecuencia de muestreo. Los plugins deben remuestrear/codificar para los proveedores. - `listVoices` es opcional por proveedor. Úsalo para selectores de voz o flujos de configuración propiedad del proveedor. -- Los listados de voces pueden incluir metadatos más ricos, como configuraciones regionales, género y etiquetas de personalidad para selectores conscientes del proveedor. -- OpenAI y ElevenLabs son compatibles con telefonía hoy. Microsoft no. +- Los listados de voces pueden incluir metadatos más ricos como configuración regional, género y etiquetas de personalidad para selectores conscientes del proveedor. +- OpenAI y ElevenLabs admiten telefonía hoy. Microsoft no. Los plugins también pueden registrar proveedores de voz mediante `api.registerSpeechProvider(...)`. @@ -919,15 +934,15 @@ api.registerSpeechProvider({ Notas: -- Mantén la política de TTS, el fallback y la entrega de respuestas en el núcleo. +- Mantén la política de TTS, el fallback y la entrega de respuestas en el core. - Usa proveedores de voz para comportamiento de síntesis propiedad del proveedor. -- La entrada heredada `edge` de Microsoft se normaliza al ID de proveedor `microsoft`. -- El modelo de propiedad preferido está orientado a la empresa: un proveedor puede poseer - proveedores de texto, voz, imágenes y medios futuros a medida que OpenClaw agrega esos +- La entrada heredada `edge` de Microsoft se normaliza al id de proveedor `microsoft`. +- El modelo de propiedad preferido está orientado por empresa: un solo plugin de proveedor puede ser propietario de + texto, voz, imagen y futuros proveedores de medios a medida que OpenClaw agregue esos contratos de capacidad. -Para comprensión de imagen/audio/video, los plugins registran un único proveedor tipado de -comprensión de medios en lugar de una bolsa genérica de clave/valor: +Para comprensión de imagen/audio/video, los plugins registran un único proveedor tipado +de comprensión de medios en lugar de una bolsa genérica de clave/valor: ```ts api.registerMediaUnderstandingProvider({ @@ -941,16 +956,16 @@ api.registerMediaUnderstandingProvider({ Notas: -- Mantén la orquestación, el fallback, la configuración y la conexión de canales en el núcleo. +- Mantén la orquestación, el fallback, la configuración y la conexión con canales en el core. - Mantén el comportamiento del proveedor en el plugin del proveedor. -- La expansión aditiva debe seguir siendo tipada: nuevos métodos opcionales, nuevos campos - opcionales de resultado, nuevas capacidades opcionales. +- La expansión aditiva debe seguir siendo tipada: nuevos métodos opcionales, nuevos + campos opcionales de resultado, nuevas capacidades opcionales. - La generación de video ya sigue el mismo patrón: - - el núcleo posee el contrato de capacidad y el asistente de tiempo de ejecución + - el core es propietario del contrato de capacidad y del asistente de tiempo de ejecución - los plugins de proveedor registran `api.registerVideoGenerationProvider(...)` - los plugins de función/canal consumen `api.runtime.videoGeneration.*` -Para los asistentes de tiempo de ejecución de comprensión de medios, los plugins pueden llamar a: +Para asistentes de tiempo de ejecución de comprensión de medios, los plugins pueden llamar a: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -972,7 +987,7 @@ o el alias STT anterior: const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Opcional cuando no se puede inferir el MIME de forma fiable: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` @@ -981,11 +996,11 @@ Notas: - `api.runtime.mediaUnderstanding.*` es la superficie compartida preferida para comprensión de imagen/audio/video. -- Usa la configuración central de audio de comprensión de medios (`tools.media.audio`) y el orden de fallback del proveedor. -- Devuelve `{ text: undefined }` cuando no se produce salida de transcripción (por ejemplo, entrada omitida o no compatible). +- Usa la configuración de audio de comprensión de medios del core (`tools.media.audio`) y el orden de fallback del proveedor. +- Devuelve `{ text: undefined }` cuando no se produce salida de transcripción (por ejemplo, entrada omitida/no compatible). - `api.runtime.stt.transcribeAudioFile(...)` permanece como alias de compatibilidad. -Los plugins también pueden iniciar ejecuciones de subagentes en segundo plano mediante `api.runtime.subagent`: +Los plugins también pueden lanzar ejecuciones de subagentes en segundo plano mediante `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -999,14 +1014,14 @@ const result = await api.runtime.subagent.run({ Notas: -- `provider` y `model` son sustituciones opcionales por ejecución, no cambios persistentes de sesión. -- OpenClaw solo respeta esos campos de sustitución para llamadores de confianza. +- `provider` y `model` son reemplazos opcionales por ejecución, no cambios persistentes de sesión. +- OpenClaw solo respeta esos campos de reemplazo para llamadores de confianza. - Para ejecuciones de fallback propiedad del plugin, los operadores deben habilitarlo explícitamente con `plugins.entries..subagent.allowModelOverride: true`. -- Usa `plugins.entries..subagent.allowedModels` para restringir plugins de confianza a objetivos canónicos `provider/model` específicos, o `"*"` para permitir explícitamente cualquier objetivo. -- Las ejecuciones de subagentes de plugins no confiables siguen funcionando, pero las solicitudes de sustitución se rechazan en lugar de aplicar un fallback silencioso. +- Usa `plugins.entries..subagent.allowedModels` para restringir los plugins de confianza a objetivos canónicos específicos `provider/model`, o `"*"` para permitir explícitamente cualquier objetivo. +- Las ejecuciones de subagentes de plugins no confiables siguen funcionando, pero las solicitudes de reemplazo se rechazan en lugar de recurrir silenciosamente al fallback. Para búsqueda web, los plugins pueden consumir el asistente compartido de tiempo de ejecución en lugar de -acceder directamente a la conexión de herramientas del agente: +entrar en la integración de herramientas del agente: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1027,9 +1042,9 @@ Los plugins también pueden registrar proveedores de búsqueda web mediante Notas: -- Mantén en el núcleo la selección de proveedor, resolución de credenciales y semántica compartida de solicitudes. +- Mantén en el core la selección de proveedor, la resolución de credenciales y la semántica compartida de solicitudes. - Usa proveedores de búsqueda web para transportes de búsqueda específicos del proveedor. -- `api.runtime.webSearch.*` es la superficie compartida preferida para plugins de función/canal que necesitan comportamiento de búsqueda sin depender del envoltorio de herramientas del agente. +- `api.runtime.webSearch.*` es la superficie compartida preferida para plugins de función/canal que necesitan comportamiento de búsqueda sin depender del wrapper de la herramienta del agente. ### `api.runtime.imageGeneration` @@ -1045,7 +1060,7 @@ const providers = api.runtime.imageGeneration.listProviders({ ``` - `generate(...)`: genera una imagen usando la cadena configurada de proveedores de generación de imágenes. -- `listProviders(...)`: enumera los proveedores disponibles de generación de imágenes y sus capacidades. +- `listProviders(...)`: enumera los proveedores de generación de imágenes disponibles y sus capacidades. ## Rutas HTTP del Gateway @@ -1067,28 +1082,28 @@ api.registerHttpRoute({ Campos de la ruta: - `path`: ruta bajo el servidor HTTP del gateway. -- `auth`: obligatorio. Usa `"gateway"` para requerir autenticación normal del gateway, o `"plugin"` para autenticación administrada por el plugin/verificación de webhook. +- `auth`: obligatorio. Usa `"gateway"` para requerir autenticación normal del gateway, o `"plugin"` para autenticación/verificación de webhook administrada por el plugin. - `match`: opcional. `"exact"` (predeterminado) o `"prefix"`. - `replaceExisting`: opcional. Permite que el mismo plugin reemplace su propio registro de ruta existente. -- `handler`: devuelve `true` cuando la ruta haya manejado la solicitud. +- `handler`: devuelve `true` cuando la ruta manejó la solicitud. Notas: -- `api.registerHttpHandler(...)` fue eliminado y provocará un error de carga del plugin. Usa `api.registerHttpRoute(...)` en su lugar. -- Las rutas de plugins deben declarar `auth` de forma explícita. -- Los conflictos exactos de `path + match` se rechazan a menos que `replaceExisting: true`, y un plugin no puede reemplazar la ruta de otro plugin. -- Las rutas superpuestas con distintos niveles de `auth` se rechazan. Mantén las cadenas de caída `exact`/`prefix` solo en el mismo nivel de autenticación. -- Las rutas con `auth: "plugin"` **no** reciben automáticamente ámbitos de tiempo de ejecución del operador. Son para webhooks/verificación de firmas administrados por el plugin, no para llamadas privilegiadas a asistentes del Gateway. -- Las rutas con `auth: "gateway"` se ejecutan dentro de un ámbito de tiempo de ejecución de solicitud del Gateway, pero ese ámbito es intencionalmente conservador: - - la autenticación bearer con secreto compartido (`gateway.auth.mode = "token"` / `"password"`) mantiene los ámbitos de tiempo de ejecución de las rutas del plugin fijados en `operator.write`, incluso si quien llama envía `x-openclaw-scopes` +- `api.registerHttpHandler(...)` fue eliminado y causará un error de carga del plugin. Usa `api.registerHttpRoute(...)` en su lugar. +- Las rutas de plugins deben declarar `auth` explícitamente. +- Los conflictos exactos de `path + match` se rechazan salvo que `replaceExisting: true`, y un plugin no puede reemplazar la ruta de otro plugin. +- Las rutas superpuestas con diferentes niveles de `auth` se rechazan. Mantén las cadenas de continuidad `exact`/`prefix` solo en el mismo nivel de autenticación. +- Las rutas `auth: "plugin"` **no** reciben automáticamente ámbitos de tiempo de ejecución del operador. Son para webhooks/verificación de firmas administrados por el plugin, no para llamadas auxiliares privilegiadas del Gateway. +- Las rutas `auth: "gateway"` se ejecutan dentro de un ámbito de tiempo de ejecución de solicitud del Gateway, pero ese ámbito es intencionalmente conservador: + - la autenticación bearer de secreto compartido (`gateway.auth.mode = "token"` / `"password"`) mantiene los ámbitos de tiempo de ejecución de rutas de plugin fijados en `operator.write`, incluso si quien llama envía `x-openclaw-scopes` - los modos HTTP confiables con identidad (por ejemplo `trusted-proxy` o `gateway.auth.mode = "none"` en un ingreso privado) respetan `x-openclaw-scopes` solo cuando el encabezado está presente explícitamente - - si `x-openclaw-scopes` no está presente en esas solicitudes de rutas de plugin con identidad, el ámbito de tiempo de ejecución vuelve a `operator.write` -- Regla práctica: no asumas que una ruta de plugin autenticada por gateway es una superficie implícita de administración. Si tu ruta necesita comportamiento exclusivo de administrador, exige un modo de autenticación con identidad y documenta el contrato explícito del encabezado `x-openclaw-scopes`. + - si `x-openclaw-scopes` no está presente en esas solicitudes de ruta de plugin con identidad, el ámbito de tiempo de ejecución vuelve a `operator.write` +- Regla práctica: no asumas que una ruta de plugin con autenticación de gateway es implícitamente una superficie de administrador. Si tu ruta necesita comportamiento exclusivo de administrador, exige un modo de autenticación con identidad y documenta el contrato explícito del encabezado `x-openclaw-scopes`. -## Rutas de importación del Plugin SDK +## Rutas de importación del SDK de plugins -Usa subrutas del SDK en lugar de la importación monolítica `openclaw/plugin-sdk` al -crear plugins: +Usa subpaths del SDK en lugar de la importación monolítica `openclaw/plugin-sdk` al +desarrollar plugins: - `openclaw/plugin-sdk/plugin-entry` para primitivas de registro de plugins. - `openclaw/plugin-sdk/core` para el contrato genérico compartido orientado a plugins. @@ -1106,19 +1121,18 @@ crear plugins: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` y - `openclaw/plugin-sdk/webhook-ingress` para la conexión compartida de - configuración/autenticación/respuesta/webhook. + `openclaw/plugin-sdk/webhook-ingress` para la integración compartida de configuración/autenticación/respuesta/webhook. `channel-inbound` es el hogar compartido para debounce, coincidencia de menciones, - asistentes de política de menciones entrantes, formato de envolturas y asistentes de contexto - de envolturas entrantes. - `channel-setup` es la unión limitada de configuración de instalación opcional. - `setup-runtime` es la superficie de configuración segura para tiempo de ejecución usada por `setupEntry` / + asistentes de política de menciones entrantes, formato de sobres y asistentes de contexto + de sobres entrantes. + `channel-setup` es el seam acotado de configuración de instalación opcional. + `setup-runtime` es la superficie de configuración segura en tiempo de ejecución usada por `setupEntry` / inicio diferido, incluidos los adaptadores de parche de configuración seguros para importación. - `setup-adapter-runtime` es la unión del adaptador de configuración de cuentas consciente del entorno. - `setup-tools` es la unión pequeña de asistentes para CLI/archivos/documentación (`formatCliCommand`, + `setup-adapter-runtime` es el seam de adaptador de configuración de cuentas sensible al entorno. + `setup-tools` es el seam pequeño de asistentes de CLI/archivo/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Subrutas de dominio como `openclaw/plugin-sdk/channel-config-helpers`, +- Subpaths de dominio como `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1137,98 +1151,102 @@ crear plugins: `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` y `openclaw/plugin-sdk/directory-runtime` para asistentes compartidos de tiempo de ejecución/configuración. - `telegram-command-config` es la unión pública limitada para normalización/validación de comandos personalizados de Telegram y sigue estando disponible incluso si la superficie de contrato integrada de Telegram no está disponible temporalmente. - `text-runtime` es la unión compartida de texto/Markdown/logging, incluida la eliminación de texto visible para el asistente, asistentes de renderizado/fragmentación de Markdown, asistentes de redacción, asistentes de etiquetas de directiva y utilidades de texto seguro. -- Las uniones de canal específicas de aprobación deben preferir un solo contrato - `approvalCapability` en el plugin. Luego el núcleo lee autenticación, entrega, renderizado, - enrutamiento nativo y comportamiento diferido del manejador nativo a través de esa única capacidad + `telegram-command-config` es el seam público acotado para la + normalización/validación de comandos personalizados de Telegram y sigue disponible aunque la + superficie de contrato agrupada de Telegram no esté disponible temporalmente. + `text-runtime` es el seam compartido de texto/markdown/logging, que incluye + eliminación de texto visible para el asistente, asistentes de renderizado/fragmentación de markdown, asistentes de redacción, asistentes de etiquetas de directivas y utilidades de texto seguro. +- Los seams de canal específicos de aprobación deben preferir un único contrato `approvalCapability` + en el plugin. Luego el core lee autenticación, entrega, renderizado, + enrutamiento nativo y comportamiento diferido del controlador nativo a través de esa única capacidad en lugar de mezclar comportamiento de aprobación en campos no relacionados del plugin. -- `openclaw/plugin-sdk/channel-runtime` está obsoleto y permanece solo como una - unión de compatibilidad para plugins antiguos. El código nuevo debe importar las primitivas genéricas más limitadas, y el código del repositorio no debe agregar nuevas importaciones de esta unión. -- Los elementos internos de extensiones integradas siguen siendo privados. Los plugins externos deben usar solo subrutas `openclaw/plugin-sdk/*`. El código principal/de pruebas de OpenClaw puede usar los - puntos de entrada públicos del repositorio bajo la raíz de un paquete de plugin como `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` y archivos de alcance limitado como - `login-qr-api.js`. Nunca importes `src/*` de un paquete de plugin desde el núcleo ni desde +- `openclaw/plugin-sdk/channel-runtime` está obsoleto y permanece solo como un + shim de compatibilidad para plugins antiguos. El código nuevo debe importar las primitivas genéricas más acotadas en su lugar, y el código del repo no debe agregar nuevas importaciones del shim. +- Los internos de extensiones agrupadas siguen siendo privados. Los plugins externos deben usar solo + subpaths `openclaw/plugin-sdk/*`. El código core/de prueba de OpenClaw puede usar los puntos de entrada públicos del repo + bajo la raíz de un paquete de plugin como `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` y archivos de alcance reducido como + `login-qr-api.js`. Nunca importes `src/*` de un paquete de plugin desde el core ni desde otra extensión. -- División de puntos de entrada del repositorio: +- División de puntos de entrada del repo: `/api.js` es el barril de asistentes/tipos, `/runtime-api.js` es el barril solo de tiempo de ejecución, - `/index.js` es el punto de entrada del plugin integrado + `/index.js` es el punto de entrada del plugin agrupado, y `/setup-entry.js` es el punto de entrada del plugin de configuración. -- Ejemplos actuales de proveedores integrados: +- Ejemplos actuales de proveedores agrupados: - Anthropic usa `api.js` / `contract-api.js` para asistentes de stream de Claude como `wrapAnthropicProviderStream`, asistentes de encabezados beta y análisis de `service_tier`. - - OpenAI usa `api.js` para constructores de proveedores, asistentes de modelo predeterminado y - constructores de proveedores en tiempo real. - - OpenRouter usa `api.js` para su constructor de proveedor más asistentes de incorporación/configuración, - mientras que `register.runtime.js` todavía puede reexportar asistentes genéricos - `plugin-sdk/provider-stream` para uso local del repositorio. -- Los puntos de entrada públicos cargados mediante fachada prefieren la instantánea de configuración activa del tiempo de ejecución - cuando existe y luego recurren al archivo de configuración resuelto en disco cuando + - OpenAI usa `api.js` para builders de proveedores, asistentes de modelo predeterminado y + builders de proveedores en tiempo real. + - OpenRouter usa `api.js` para su builder de proveedor más asistentes de incorporación/configuración, + mientras `register.runtime.js` puede seguir reexportando asistentes genéricos + `plugin-sdk/provider-stream` para uso local del repo. +- Los puntos de entrada públicos cargados por fachada prefieren la instantánea de configuración activa de tiempo de ejecución + cuando existe una; luego recurren al archivo de configuración resuelto en disco cuando OpenClaw aún no está sirviendo una instantánea de tiempo de ejecución. -- Las primitivas genéricas compartidas siguen siendo el contrato público preferido del SDK. Todavía existe un pequeño conjunto reservado - de compatibilidad de uniones auxiliares con marca de canal integrado. Trátalas como - uniones de mantenimiento/compatibilidad integradas, no como nuevos objetivos de importación de terceros; los nuevos contratos entre canales deben seguir aterrizando en subrutas genéricas `plugin-sdk/*` o en los barriles locales del plugin `api.js` / +- Las primitivas genéricas compartidas siguen siendo el contrato público preferido del SDK. Aún existe + un pequeño conjunto de compatibilidad reservado de seams auxiliares de canal con marca agrupada. Trátalos como seams de mantenimiento/compatibilidad agrupados, no como nuevos objetivos de importación para terceros; los nuevos contratos entre canales deben seguir llegando a subpaths genéricos `plugin-sdk/*` o a los barriles locales del plugin `api.js` / `runtime-api.js`. Nota de compatibilidad: - Evita el barril raíz `openclaw/plugin-sdk` en código nuevo. -- Prefiere primero las primitivas estables y limitadas. Las subrutas más nuevas de configuración/emparejamiento/respuesta/ - feedback/contrato/entrada/threading/comando/secret-input/webhook/infra/ - allowlist/status/message-tool son el contrato previsto para trabajo nuevo - de plugins integrados y externos. +- Prefiere primero las primitivas estables y acotadas. Los subpaths más recientes de configuración/asociación/respuesta/ + feedback/contrato/entrada/hilos/comando/secret-input/webhook/infra/ + allowlist/status/message-tool son el contrato previsto para trabajo nuevo con + plugins agrupados y externos. El análisis/coincidencia de objetivos pertenece a `openclaw/plugin-sdk/channel-targets`. - Las compuertas de acciones de mensaje y los asistentes de ID de mensaje de reacciones pertenecen a + Las compuertas de acciones de mensajes y los asistentes de id de mensaje para reacciones pertenecen a `openclaw/plugin-sdk/channel-actions`. -- Los barriles de asistentes específicos de extensiones integradas no son estables de forma predeterminada. Si un - asistente solo es necesario para una extensión integrada, mantenlo detrás de la - unión local `api.js` o `runtime-api.js` de la extensión en lugar de promoverlo a +- Los barriles auxiliares específicos de extensiones agrupadas no son estables de forma predeterminada. Si un + asistente solo lo necesita una extensión agrupada, mantenlo detrás del seam + local `api.js` o `runtime-api.js` de la extensión en lugar de promoverlo a `openclaw/plugin-sdk/`. -- Las nuevas uniones de asistentes compartidos deben ser genéricas, no con marca de canal. El análisis de objetivos compartidos - pertenece a `openclaw/plugin-sdk/channel-targets`; los elementos internos específicos del canal permanecen detrás de la unión local `api.js` o `runtime-api.js` - del plugin propietario. -- Existen subrutas específicas de capacidad como `image-generation`, - `media-understanding` y `speech` porque los plugins nativos/integrados - las usan hoy. Su presencia no significa por sí sola que cada asistente exportado sea un contrato externo congelado a largo plazo. +- Los nuevos seams de asistentes compartidos deben ser genéricos, no de marca de canal. El análisis compartido de + objetivos pertenece a `openclaw/plugin-sdk/channel-targets`; los internos específicos del canal + permanecen detrás del seam local `api.js` o `runtime-api.js` del plugin propietario. +- Subpaths específicos de capacidades como `image-generation`, + `media-understanding` y `speech` existen porque los plugins agrupados/nativos los usan + hoy. Su presencia no significa por sí sola que cada asistente exportado sea un + contrato externo congelado a largo plazo. ## Esquemas de la herramienta de mensajes -Los plugins deben poseer contribuciones al esquema específico del canal en `describeMessageTool(...)`. -Mantén los campos específicos del proveedor en el plugin, no en el núcleo compartido. +Los plugins deben ser propietarios de las contribuciones de esquema específicas del canal para +`describeMessageTool(...)`. Mantén los campos específicos del proveedor en el plugin, no en el core compartido. -Para fragmentos de esquema portátiles compartidos, reutiliza los asistentes genéricos exportados a través de +Para fragmentos de esquema portables compartidos, reutiliza los asistentes genéricos exportados a través de `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` para cargas útiles de estilo cuadrícula de botones -- `createMessageToolCardSchema()` para cargas útiles estructuradas de tarjetas +- `createMessageToolCardSchema()` para cargas útiles de tarjeta estructurada Si una forma de esquema solo tiene sentido para un proveedor, defínela en el propio código fuente de ese plugin en lugar de promoverla al SDK compartido. ## Resolución de objetivos de canal -Los plugins de canal deben poseer la semántica específica del canal para objetivos. Mantén genérico el -host compartido de salida y usa la superficie del adaptador de mensajería para las reglas del proveedor: +Los plugins de canal deben ser propietarios de la semántica de objetivos específica del canal. Mantén +genérico el host de salida compartido y usa la superficie del adaptador de mensajería para las reglas del proveedor: - `messaging.inferTargetChatType({ to })` decide si un objetivo normalizado debe tratarse como `direct`, `group` o `channel` antes de la búsqueda en directorio. -- `messaging.targetResolver.looksLikeId(raw, normalized)` le indica al núcleo si una - entrada debe saltar directamente a resolución tipo ID en lugar de búsqueda en directorio. -- `messaging.targetResolver.resolveTarget(...)` es el fallback del plugin cuando - el núcleo necesita una resolución final propiedad del proveedor después de la normalización o - después de un fallo de búsqueda en directorio. -- `messaging.resolveOutboundSessionRoute(...)` posee la construcción específica del proveedor de la - ruta de sesión de salida una vez resuelto un objetivo. +- `messaging.targetResolver.looksLikeId(raw, normalized)` le dice al core si una + entrada debe ir directamente a resolución tipo id en lugar de búsqueda en directorio. +- `messaging.targetResolver.resolveTarget(...)` es el fallback del plugin cuando el + core necesita una resolución final propiedad del proveedor tras la normalización o tras un fallo + en el directorio. +- `messaging.resolveOutboundSessionRoute(...)` es propietario de la construcción específica del proveedor + de rutas de sesión de salida una vez que se resuelve un objetivo. División recomendada: - Usa `inferTargetChatType` para decisiones de categoría que deban ocurrir antes de buscar pares/grupos. -- Usa `looksLikeId` para comprobaciones de “tratar esto como un ID de objetivo explícito/nativo”. +- Usa `looksLikeId` para comprobaciones de “tratar esto como un id de objetivo explícito/nativo”. - Usa `resolveTarget` para fallback de normalización específico del proveedor, no para búsqueda amplia en directorio. -- Mantén ID nativos del proveedor como ID de chat, ID de hilo, JID, handles e ID de sala +- Mantén ids nativos del proveedor como ids de chat, ids de hilo, JID, handles e ids de sala dentro de valores `target` o parámetros específicos del proveedor, no en campos genéricos del SDK. ## Directorios respaldados por configuración @@ -1237,20 +1255,20 @@ Los plugins que derivan entradas de directorio a partir de la configuración deb plugin y reutilizar los asistentes compartidos de `openclaw/plugin-sdk/directory-runtime`. -Úsalo cuando un canal necesite pares/grupos respaldados por configuración como: +Usa esto cuando un canal necesite pares/grupos respaldados por configuración, como: -- pares DM controlados por allowlist +- pares de DM controlados por allowlist - mapas configurados de canal/grupo - fallbacks estáticos de directorio con alcance por cuenta -Los asistentes compartidos en `directory-runtime` solo manejan operaciones genéricas: +Los asistentes compartidos de `directory-runtime` solo manejan operaciones genéricas: - filtrado de consultas - aplicación de límites -- asistentes de desduplicación/normalización +- asistentes de deduplicación/normalización - construcción de `ChannelDirectoryEntry[]` -La inspección de cuentas específica del canal y la normalización de ID deben permanecer en la +La inspección de cuentas específica del canal y la normalización de ids deben permanecer en la implementación del plugin. ## Catálogos de proveedores @@ -1262,24 +1280,25 @@ Los plugins de proveedor pueden definir catálogos de modelos para inferencia co `models.providers`: - `{ provider }` para una entrada de proveedor -- `{ providers }` para varias entradas de proveedor +- `{ providers }` para múltiples entradas de proveedor -Usa `catalog` cuando el plugin posea ID de modelo específicos del proveedor, valores predeterminados de URL base o metadatos de modelo protegidos por autenticación. +Usa `catalog` cuando el plugin sea propietario de ids de modelo específicos del proveedor, valores predeterminados de URL base o metadatos de modelos condicionados por autenticación. -`catalog.order` controla cuándo se combina el catálogo de un plugin con respecto a los +`catalog.order` controla cuándo se fusiona el catálogo de un plugin en relación con los proveedores implícitos integrados de OpenClaw: -- `simple`: proveedores simples impulsados por clave API o entorno +- `simple`: proveedores simples con clave API o impulsados por entorno - `profile`: proveedores que aparecen cuando existen perfiles de autenticación -- `paired`: proveedores que sintetizan varias entradas de proveedor relacionadas -- `late`: última pasada, después de otros proveedores implícitos +- `paired`: proveedores que sintetizan múltiples entradas de proveedor relacionadas +- `late`: pasada final, después de otros proveedores implícitos -Los proveedores posteriores ganan en caso de colisión de clave, por lo que los plugins pueden sobrescribir intencionalmente una entrada integrada de proveedor con el mismo ID de proveedor. +Los proveedores posteriores ganan en caso de colisión de claves, por lo que los plugins pueden +reemplazar intencionadamente una entrada de proveedor integrada con el mismo id de proveedor. Compatibilidad: - `discovery` sigue funcionando como alias heredado -- si se registran tanto `catalog` como `discovery`, OpenClaw usa `catalog` +- si se registran `catalog` y `discovery`, OpenClaw usa `catalog` ## Inspección de canal de solo lectura @@ -1289,9 +1308,9 @@ Si tu plugin registra un canal, prefiere implementar Por qué: - `resolveAccount(...)` es la ruta de tiempo de ejecución. Puede asumir que las credenciales - están completamente materializadas y puede fallar rápido cuando faltan secretos requeridos. + están completamente materializadas y puede fallar rápidamente cuando faltan secretos requeridos. - Las rutas de comandos de solo lectura como `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` y los flujos de reparación de doctor/configuración + `openclaw channels status`, `openclaw channels resolve` y los flujos de doctor/reparación de configuración no deberían necesitar materializar credenciales de tiempo de ejecución solo para describir la configuración. @@ -1304,13 +1323,14 @@ Comportamiento recomendado de `inspectAccount(...)`: - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- No necesitas devolver valores sin procesar del token solo para informar disponibilidad de solo lectura. Devolver `tokenStatus: "available"` (y el campo de origen correspondiente) es suficiente para comandos de estilo estado. +- No necesitas devolver valores de token sin procesar solo para informar disponibilidad de solo lectura. Devolver `tokenStatus: "available"` (y el campo de origen correspondiente) es suficiente para comandos de tipo estado. - Usa `configured_unavailable` cuando una credencial esté configurada mediante SecretRef pero - no disponible en la ruta de comando actual. + no disponible en la ruta actual del comando. -Esto permite que los comandos de solo lectura informen “configurado pero no disponible en esta ruta de comando” en lugar de fallar o informar incorrectamente que la cuenta no está configurada. +Esto permite que los comandos de solo lectura informen “configurado pero no disponible en esta ruta de comando” +en lugar de bloquearse o informar incorrectamente que la cuenta no está configurada. -## Paquetes agrupados +## Paquetes agrupadores Un directorio de plugin puede incluir un `package.json` con `openclaw.extensions`: @@ -1324,42 +1344,43 @@ Un directorio de plugin puede incluir un `package.json` con `openclaw.extensions } ``` -Cada entrada se convierte en un plugin. Si el paquete enumera varias extensiones, el ID del plugin +Cada entrada se convierte en un plugin. Si el paquete enumera múltiples extensiones, el id del plugin pasa a ser `name/`. Si tu plugin importa dependencias npm, instálalas en ese directorio para que `node_modules` esté disponible (`npm install` / `pnpm install`). -Compuerta de seguridad: cada entrada de `openclaw.extensions` debe permanecer dentro del directorio del plugin -después de la resolución de symlinks. Las entradas que escapen del directorio del paquete se +Barandilla de seguridad: cada entrada de `openclaw.extensions` debe permanecer dentro del directorio del plugin +después de resolver symlinks. Las entradas que escapan del directorio del paquete se rechazan. Nota de seguridad: `openclaw plugins install` instala dependencias de plugins con -`npm install --omit=dev --ignore-scripts` (sin scripts de ciclo de vida y sin dependencias de desarrollo en tiempo de ejecución). Mantén los árboles de dependencias de plugins como “pure JS/TS” y evita paquetes que requieran compilaciones `postinstall`. +`npm install --omit=dev --ignore-scripts` (sin scripts de ciclo de vida, sin dependencias de desarrollo en tiempo de ejecución). Mantén los árboles de dependencias de plugins en “JS/TS puro” y evita paquetes que requieran compilaciones en `postinstall`. Opcional: `openclaw.setupEntry` puede apuntar a un módulo ligero solo de configuración. Cuando OpenClaw necesita superficies de configuración para un plugin de canal deshabilitado, o -cuando un plugin de canal está habilitado pero aún no configurado, carga `setupEntry` -en lugar de la entrada completa del plugin. Esto mantiene el inicio y la configuración más ligeros -cuando la entrada principal del plugin también conecta herramientas, hooks u otro código exclusivo de tiempo de ejecución. +cuando un plugin de canal está habilitado pero sigue sin configurarse, carga `setupEntry` +en lugar del punto de entrada completo del plugin. Esto hace que el inicio y la configuración sean más ligeros +cuando el punto de entrada principal del plugin también conecta herramientas, hooks u otro código +solo de tiempo de ejecución. Opcional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -puede incorporar un plugin de canal a la misma ruta `setupEntry` durante la fase de -inicio previa a escucha del gateway, incluso cuando el canal ya está configurado. +puede hacer que un plugin de canal opte por esa misma ruta `setupEntry` durante la +fase de inicio previa a `listen` del gateway, incluso cuando el canal ya está configurado. Usa esto solo cuando `setupEntry` cubra completamente la superficie de inicio que debe existir antes de que el gateway empiece a escuchar. En la práctica, eso significa que la entrada de configuración -debe registrar cada capacidad propiedad del canal de la que dependa el inicio, como: +debe registrar todas las capacidades propiedad del canal de las que dependa el inicio, como: - el propio registro del canal - cualquier ruta HTTP que deba estar disponible antes de que el gateway empiece a escuchar -- cualquier método del gateway, herramienta o servicio que deba existir durante esa misma ventana +- cualquier método, herramienta o servicio del gateway que deba existir durante esa misma ventana -Si tu entrada completa sigue poseyendo alguna capacidad de inicio requerida, no habilites -este flag. Mantén el comportamiento predeterminado del plugin y deja que OpenClaw cargue la +Si tu entrada completa sigue siendo propietaria de alguna capacidad de inicio requerida, no habilites +este flag. Mantén el plugin con el comportamiento predeterminado y deja que OpenClaw cargue la entrada completa durante el inicio. -Los canales integrados también pueden publicar asistentes de superficie de contrato solo de configuración que el núcleo +Los canales agrupados también pueden publicar asistentes de superficie de contrato solo de configuración que el core puede consultar antes de que se cargue el tiempo de ejecución completo del canal. La superficie actual de promoción de configuración es: @@ -1367,20 +1388,21 @@ de promoción de configuración es: - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -El núcleo usa esa superficie cuando necesita promover una configuración heredada de canal de cuenta única -a `channels..accounts.*` sin cargar la entrada completa del plugin. -Matrix es el ejemplo integrado actual: mueve solo claves de autenticación/arranque a una -cuenta promocionada con nombre cuando ya existen cuentas con nombre, y puede preservar una -clave configurada de cuenta predeterminada no canónica en lugar de crear siempre +El core usa esa superficie cuando necesita promover una configuración heredada de canal de cuenta única +a `channels..accounts.*` sin cargar el punto de entrada completo del plugin. +Matrix es el ejemplo agrupado actual: mueve solo claves de autenticación/bootstrap a una +cuenta promovida con nombre cuando ya existen cuentas con nombre, y puede preservar una +clave predeterminada configurada no canónica en lugar de crear siempre `accounts.default`. -Esos adaptadores de parche de configuración mantienen diferido el descubrimiento de superficies de contrato integradas. El tiempo -de importación sigue siendo ligero; la superficie de promoción se carga solo en el primer uso en lugar de reingresar al inicio del canal integrado durante la importación del módulo. +Esos adaptadores de parche de configuración mantienen perezoso el descubrimiento de la superficie de contrato agrupada. El tiempo +de importación sigue siendo ligero; la superficie de promoción se carga solo en el primer uso en lugar de +reingresar al inicio del canal agrupado al importar el módulo. Cuando esas superficies de inicio incluyen métodos RPC del gateway, mantenlos en un -prefijo específico del plugin. Los espacios de nombres administrativos del núcleo (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) siguen reservados y siempre se resuelven -a `operator.admin`, incluso si un plugin solicita un ámbito más limitado. +prefijo específico del plugin. Los espacios de nombres administrativos del core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) permanecen reservados y siempre se resuelven +a `operator.admin`, incluso si un plugin solicita un ámbito más acotado. Ejemplo: @@ -1397,10 +1419,10 @@ Ejemplo: } ``` -### Metadatos de catálogo de canal +### Metadatos del catálogo de canales Los plugins de canal pueden anunciar metadatos de configuración/descubrimiento mediante `openclaw.channel` y -sugerencias de instalación mediante `openclaw.install`. Esto mantiene el núcleo sin datos de catálogo. +sugerencias de instalación mediante `openclaw.install`. Esto mantiene el catálogo del core libre de datos. Ejemplo: @@ -1415,7 +1437,7 @@ Ejemplo: "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Chat autoalojado mediante bots de webhook de Nextcloud Talk.", + "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1431,38 +1453,37 @@ Ejemplo: Campos útiles de `openclaw.channel` además del ejemplo mínimo: - `detailLabel`: etiqueta secundaria para superficies más ricas de catálogo/estado -- `docsLabel`: reemplaza el texto del enlace de documentación -- `preferOver`: ID de plugin/canal de menor prioridad que esta entrada de catálogo debe superar +- `docsLabel`: reemplaza el texto del enlace para el enlace de documentación +- `preferOver`: ids de plugin/canal de menor prioridad que esta entrada de catálogo debe superar - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controles de texto para superficies de selección -- `markdownCapable`: marca el canal como compatible con Markdown para decisiones de formato saliente +- `markdownCapable`: marca el canal como compatible con markdown para decisiones de formato de salida - `exposure.configured`: oculta el canal de las superficies de listado de canales configurados cuando se establece en `false` -- `exposure.setup`: oculta el canal de selectores interactivos de configuración cuando se establece en `false` +- `exposure.setup`: oculta el canal de los selectores interactivos de configuración cuando se establece en `false` - `exposure.docs`: marca el canal como interno/privado para superficies de navegación de documentación -- `showConfigured` / `showInSetup`: alias heredados todavía aceptados por compatibilidad; prefiere `exposure` -- `quickstartAllowFrom`: incorpora el canal al flujo estándar de inicio rápido `allowFrom` -- `forceAccountBinding`: requiere vinculación explícita de cuenta incluso cuando solo existe una cuenta +- `showConfigured` / `showInSetup`: alias heredados aún aceptados por compatibilidad; prefiere `exposure` +- `quickstartAllowFrom`: hace que el canal participe en el flujo estándar de quickstart `allowFrom` +- `forceAccountBinding`: requiere asociación explícita de cuenta incluso cuando solo existe una cuenta - `preferSessionLookupForAnnounceTarget`: prefiere la búsqueda de sesión al resolver objetivos de anuncio -OpenClaw también puede combinar **catálogos de canales externos** (por ejemplo, una exportación de registro MPM). -Coloca un archivo JSON en una de estas ubicaciones: +OpenClaw también puede fusionar **catálogos externos de canales** (por ejemplo, una +exportación de registro MPM). Coloca un archivo JSON en una de estas rutas: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -O apunta `OPENCLAW_PLUGIN_CATALOG_PATHS` (o `OPENCLAW_MPM_CATALOG_PATHS`) a +O haz que `OPENCLAW_PLUGIN_CATALOG_PATHS` (o `OPENCLAW_MPM_CATALOG_PATHS`) apunte a uno o más archivos JSON (delimitados por coma/punto y coma/`PATH`). Cada archivo debe -contener `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. El analizador también acepta `"packages"` o `"plugins"` como alias heredados para la clave `"entries"`. +contener `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. El analizador también acepta `"packages"` o `"plugins"` como aliases heredados para la clave `"entries"`. ## Plugins del motor de contexto -Los plugins del motor de contexto poseen la orquestación del contexto de sesión para ingesta, ensamblaje +Los plugins del motor de contexto son propietarios de la orquestación del contexto de sesión para ingesta, ensamblado y compactación. Regístralos desde tu plugin con `api.registerContextEngine(id, factory)` y luego selecciona el motor activo con `plugins.slots.contextEngine`. -Usa esto cuando tu plugin necesite reemplazar o extender la canalización de contexto predeterminada -en lugar de solo agregar búsqueda de memoria o hooks. +Usa esto cuando tu plugin necesite reemplazar o extender la canalización de contexto predeterminada en lugar de solo agregar búsqueda en memory o hooks. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1490,8 +1511,8 @@ export default function (api) { } ``` -Si tu motor **no** posee el algoritmo de compactación, mantén `compact()` -implementado y delega explícitamente: +Si tu motor **no** es propietario del algoritmo de compactación, mantén `compact()` +implementado y delega explícitamente en él: ```ts import { @@ -1528,46 +1549,45 @@ export default function (api) { ## Agregar una nueva capacidad -Cuando un plugin necesita un comportamiento que no encaja en la API actual, no eludas -el sistema de plugins con un acceso privado. Agrega la capacidad faltante. +Cuando un plugin necesite un comportamiento que no encaje en la API actual, no evites +el sistema de plugins con un acceso privado. Agrega la capacidad que falta. Secuencia recomendada: -1. definir el contrato del núcleo - Decide qué comportamiento compartido debe poseer el núcleo: política, fallback, combinación de configuración, - ciclo de vida, semántica orientada a canales y forma del asistente de tiempo de ejecución. +1. definir el contrato del core + Decide qué comportamiento compartido debe ser propiedad del core: política, fallback, combinación de configuración, + ciclo de vida, semántica orientada al canal y forma del asistente de tiempo de ejecución. 2. agregar superficies tipadas de registro/tiempo de ejecución para plugins - Extiende `OpenClawPluginApi` y/o `api.runtime` con la superficie tipada de capacidad - más pequeña que sea útil. -3. conectar consumidores del núcleo + canal/función - Los canales y plugins de función deben consumir la nueva capacidad a través del núcleo, - no importando directamente una implementación de proveedor. -4. registrar implementaciones de proveedor - Los plugins de proveedor registran luego sus backends contra la capacidad. + Extiende `OpenClawPluginApi` y/o `api.runtime` con la superficie tipada de capacidad más pequeña que sea útil. +3. conectar consumidores del core y de canal/función + Los canales y plugins de función deben consumir la nueva capacidad a través del core, + no importando directamente una implementación del proveedor. +4. registrar implementaciones del proveedor + Los plugins de proveedor registran entonces sus backends en la capacidad. 5. agregar cobertura de contrato - Agrega pruebas para que la forma de propiedad y registro siga siendo explícita con el tiempo. + Agrega pruebas para que la propiedad y la forma del registro sigan siendo explícitas con el tiempo. -Así es como OpenClaw sigue siendo opinado sin quedar codificado rígidamente a la -visión del mundo de un solo proveedor. Consulta el [Recetario de capacidades](/es/plugins/architecture) -para ver una lista concreta de archivos y un ejemplo desarrollado. +Así es como OpenClaw mantiene una postura definida sin quedar codificado rígidamente a la +visión del mundo de un proveedor. Consulta el [Recetario de capacidades](/es/plugins/architecture) +para una lista concreta de archivos y un ejemplo trabajado. -### Lista de comprobación de capacidades +### Lista de verificación de capacidades -Cuando agregas una nueva capacidad, la implementación normalmente debe tocar estas -superficies de forma conjunta: +Cuando agregues una nueva capacidad, la implementación normalmente debería tocar estas +superficies en conjunto: -- tipos de contrato del núcleo en `src//types.ts` -- asistente de runner/tiempo de ejecución del núcleo en `src//runtime.ts` +- tipos de contrato del core en `src//types.ts` +- runner/asistente de tiempo de ejecución del core en `src//runtime.ts` - superficie de registro de la API de plugins en `src/plugins/types.ts` - conexión del registro de plugins en `src/plugins/registry.ts` -- exposición del tiempo de ejecución del plugin en `src/plugins/runtime/*` cuando los - plugins de función/canal necesitan consumirla +- exposición del tiempo de ejecución del plugin en `src/plugins/runtime/*` cuando los plugins de función/canal + necesiten consumirlo - asistentes de captura/prueba en `src/test-utils/plugin-registration.ts` - aserciones de propiedad/contrato en `src/plugins/contracts/registry.ts` - documentación para operadores/plugins en `docs/` Si falta una de esas superficies, normalmente es una señal de que la capacidad -aún no está completamente integrada. +todavía no está completamente integrada. ### Plantilla de capacidad @@ -1605,7 +1625,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Eso mantiene la regla simple: -- el núcleo posee el contrato de capacidad + la orquestación -- los plugins de proveedor poseen las implementaciones del proveedor +- el core es propietario del contrato de capacidad y de la orquestación +- los plugins de proveedor son propietarios de las implementaciones del proveedor - los plugins de función/canal consumen asistentes de tiempo de ejecución - las pruebas de contrato mantienen explícita la propiedad diff --git a/docs/es/plugins/manifest.md b/docs/es/plugins/manifest.md index 397676192..f0b182d5f 100644 --- a/docs/es/plugins/manifest.md +++ b/docs/es/plugins/manifest.md @@ -5,37 +5,38 @@ read_when: summary: Requisitos del manifiesto del plugin + esquema JSON (validación estricta de la configuración) title: Manifiesto del plugin x-i18n: - generated_at: "2026-04-11T15:15:53Z" + generated_at: "2026-04-12T05:11:00Z" model: gpt-5.4 provider: openai - source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 + source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91 source_path: plugins/manifest.md workflow: 15 --- # Manifiesto del plugin (`openclaw.plugin.json`) -Esta página es solo para el **manifiesto nativo de plugins de OpenClaw**. +Esta página es solo para el **manifiesto nativo de plugin de OpenClaw**. Para diseños de paquetes compatibles, consulta [Paquetes de plugins](/es/plugins/bundles). -Los formatos de paquetes compatibles usan archivos de manifiesto distintos: +Los formatos de paquete compatibles usan archivos de manifiesto diferentes: -- Paquete de Codex: `.codex-plugin/plugin.json` -- Paquete de Claude: `.claude-plugin/plugin.json` o el diseño predeterminado de componentes de Claude sin manifiesto -- Paquete de Cursor: `.cursor-plugin/plugin.json` +- Paquete Codex: `.codex-plugin/plugin.json` +- Paquete Claude: `.claude-plugin/plugin.json` o el diseño predeterminado de componentes de Claude + sin manifiesto +- Paquete Cursor: `.cursor-plugin/plugin.json` OpenClaw también detecta automáticamente esos diseños de paquetes, pero no se validan contra el esquema de `openclaw.plugin.json` descrito aquí. -Para los paquetes compatibles, OpenClaw actualmente lee los metadatos del paquete junto con las -raíces de Skills declaradas, las raíces de comandos de Claude, los valores predeterminados de `settings.json` del paquete de Claude, -los valores predeterminados de LSP del paquete de Claude y los paquetes de hooks compatibles cuando el diseño coincide con las expectativas del runtime de +Para los paquetes compatibles, OpenClaw actualmente lee los metadatos del paquete más las +raíces de Skills declaradas, las raíces de comandos de Claude, los valores predeterminados de `settings.json` del paquete Claude, +los valores predeterminados de LSP del paquete Claude y los paquetes de hooks compatibles cuando el diseño coincide con las expectativas del runtime de OpenClaw. -Cada plugin nativo de OpenClaw **debe** incluir un archivo `openclaw.plugin.json` en la +Todo plugin nativo de OpenClaw **debe** incluir un archivo `openclaw.plugin.json` en la **raíz del plugin**. OpenClaw usa este manifiesto para validar la configuración -**sin ejecutar código del plugin**. Los manifiestos faltantes o inválidos se tratan como +**sin ejecutar código del plugin**. Los manifiestos faltantes o no válidos se tratan como errores del plugin y bloquean la validación de la configuración. Consulta la guía completa del sistema de plugins: [Plugins](/es/tools/plugin). @@ -51,19 +52,21 @@ código de tu plugin. - identidad del plugin - validación de la configuración -- metadatos de autenticación e incorporación que deban estar disponibles sin iniciar el runtime del plugin -- pistas de activación de bajo costo que las superficies del plano de control puedan inspeccionar antes de que se cargue el runtime -- descriptores de configuración de bajo costo que las superficies de configuración/incorporación puedan inspeccionar antes de que se cargue el runtime -- metadatos de alias y habilitación automática que deban resolverse antes de que se cargue el runtime del plugin -- metadatos abreviados de propiedad de familias de modelos que deban activar automáticamente el plugin antes de que se cargue el runtime -- instantáneas estáticas de propiedad de capacidades usadas para el cableado de compatibilidad de plugins incluidos y la cobertura de contratos -- metadatos de configuración específicos del canal que deban combinarse en las superficies de catálogo y validación sin cargar el runtime -- pistas de UI para la configuración +- metadatos de autenticación e incorporación que deberían estar disponibles sin iniciar el runtime del plugin +- pistas de activación de bajo costo que las superficies del plano de control pueden inspeccionar antes de que se cargue el runtime +- descriptores de configuración de bajo costo que las superficies de configuración/incorporación pueden inspeccionar antes de que se cargue el runtime +- metadatos de alias y habilitación automática que deberían resolverse antes de que se cargue el runtime del plugin +- metadatos abreviados de propiedad de familias de modelos que deberían activar automáticamente el + plugin antes de que se cargue el runtime +- instantáneas estáticas de propiedad de capacidades usadas para el cableado de compatibilidad de paquetes integrados y la cobertura de contratos +- metadatos de configuración específicos del canal que deberían fusionarse en los catálogos y superficies de validación + sin cargar el runtime +- pistas de UI de configuración No lo uses para: -- registrar comportamiento en runtime -- declarar entrypoints de código +- registrar comportamiento del runtime +- declarar puntos de entrada de código - metadatos de instalación de npm Eso pertenece al código de tu plugin y a `package.json`. @@ -87,7 +90,7 @@ Eso pertenece al código de tu plugin y a `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin de proveedor OpenRouter", + "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -108,19 +111,19 @@ Eso pertenece al código de tu plugin y a `package.json`. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "Clave API de OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "Clave API de OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "Clave API", + "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -139,62 +142,62 @@ Eso pertenece al código de tu plugin y a `package.json`. ## Referencia de campos de nivel superior -| Campo | Obligatorio | Tipo | Qué significa | -| ----------------------------------- | ----------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Sí | `string` | Id canónico del plugin. Este es el id usado en `plugins.entries.`. | -| `configSchema` | Sí | `object` | Esquema JSON inline para la configuración de este plugin. | -| `enabledByDefault` | No | `true` | Marca un plugin incluido como habilitado de forma predeterminada. Omítelo, o establece cualquier valor distinto de `true`, para dejar el plugin deshabilitado de forma predeterminada. | -| `legacyPluginIds` | No | `string[]` | Ids heredados que se normalizan a este id canónico del plugin. | -| `autoEnableWhenConfiguredProviders` | No | `string[]` | Ids de proveedores que deben habilitar automáticamente este plugin cuando la autenticación, la configuración o las referencias de modelos los mencionen. | -| `kind` | No | `"memory"` \| `"context-engine"` | Declara un tipo de plugin exclusivo usado por `plugins.slots.*`. | -| `channels` | No | `string[]` | Ids de canales propiedad de este plugin. Se usan para descubrimiento y validación de configuración. | -| `providers` | No | `string[]` | Ids de proveedores propiedad de este plugin. | -| `modelSupport` | No | `object` | Metadatos abreviados de familias de modelos propiedad del manifiesto usados para cargar automáticamente el plugin antes del runtime. | -| `cliBackends` | No | `string[]` | Ids de backends de inferencia de CLI propiedad de este plugin. Se usan para la activación automática al inicio a partir de referencias explícitas de configuración. | -| `commandAliases` | No | `object[]` | Nombres de comandos propiedad de este plugin que deben producir diagnósticos de configuración y de CLI conscientes del plugin antes de que se cargue el runtime. | -| `providerAuthEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno de autenticación del proveedor que OpenClaw puede inspeccionar sin cargar código del plugin. | -| `providerAuthAliases` | No | `Record` | Ids de proveedores que deben reutilizar otro id de proveedor para la búsqueda de autenticación; por ejemplo, un proveedor de programación que comparte la clave API base del proveedor y los perfiles de autenticación. | -| `channelEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno del canal que OpenClaw puede inspeccionar sin cargar código del plugin. Úsalo para superficies de configuración o autenticación del canal basadas en variables de entorno que los helpers genéricos de inicio/configuración deban ver. | -| `providerAuthChoices` | No | `object[]` | Metadatos ligeros de opciones de autenticación para selectores de incorporación, resolución de proveedores preferidos y cableado simple de flags de CLI. | -| `activation` | No | `object` | Pistas ligeras de activación para carga desencadenada por proveedor, comando, canal, ruta y capacidad. Solo metadatos; el runtime del plugin sigue siendo el responsable del comportamiento real. | +| Campo | Obligatorio | Tipo | Qué significa | +| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Sí | `string` | ID canónico del plugin. Este es el ID usado en `plugins.entries.`. | +| `configSchema` | Sí | `object` | Esquema JSON en línea para la configuración de este plugin. | +| `enabledByDefault` | No | `true` | Marca un plugin integrado como habilitado de forma predeterminada. Omítelo, o establece cualquier valor distinto de `true`, para dejar el plugin deshabilitado de forma predeterminada. | +| `legacyPluginIds` | No | `string[]` | IDs heredados que se normalizan a este ID canónico de plugin. | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | IDs de proveedor que deberían habilitar automáticamente este plugin cuando la autenticación, la configuración o las referencias de modelos los mencionen. | +| `kind` | No | `"memory"` \| `"context-engine"` | Declara un tipo exclusivo de plugin usado por `plugins.slots.*`. | +| `channels` | No | `string[]` | IDs de canal propiedad de este plugin. Se usan para descubrimiento y validación de configuración. | +| `providers` | No | `string[]` | IDs de proveedor propiedad de este plugin. | +| `modelSupport` | No | `object` | Metadatos abreviados de familia de modelos propiedad del manifiesto usados para cargar automáticamente el plugin antes del runtime. | +| `cliBackends` | No | `string[]` | IDs de backend de inferencia de CLI propiedad de este plugin. Se usan para la activación automática al inicio desde referencias explícitas de configuración. | +| `commandAliases` | No | `object[]` | Nombres de comandos propiedad de este plugin que deberían producir diagnósticos de configuración y de CLI con reconocimiento del plugin antes de que se cargue el runtime. | +| `providerAuthEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno de autenticación de proveedor que OpenClaw puede inspeccionar sin cargar el código del plugin. | +| `providerAuthAliases` | No | `Record` | IDs de proveedor que deberían reutilizar otro ID de proveedor para la búsqueda de autenticación, por ejemplo un proveedor de programación que comparte la clave API y los perfiles de autenticación del proveedor base. | +| `channelEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno de canal que OpenClaw puede inspeccionar sin cargar el código del plugin. Úsalo para superficies de configuración o autenticación de canal basadas en variables de entorno que los ayudantes genéricos de inicio/configuración deberían ver. | +| `providerAuthChoices` | No | `object[]` | Metadatos ligeros de opciones de autenticación para selectores de incorporación, resolución de proveedor preferido y conexión simple de flags de CLI. | +| `activation` | No | `object` | Pistas ligeras de activación para carga desencadenada por proveedor, comando, canal, ruta y capacidad. Solo metadatos; el runtime del plugin sigue siendo el dueño del comportamiento real. | | `setup` | No | `object` | Descriptores ligeros de configuración/incorporación que las superficies de descubrimiento y configuración pueden inspeccionar sin cargar el runtime del plugin. | -| `contracts` | No | `object` | Instantánea estática de capacidades incluidas para speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, búsqueda web y propiedad de herramientas. | -| `channelConfigs` | No | `Record` | Metadatos de configuración de canal propiedad del manifiesto que se combinan en las superficies de descubrimiento y validación antes de que se cargue el runtime. | -| `skills` | No | `string[]` | Directorios de Skills que se cargarán, relativos a la raíz del plugin. | +| `contracts` | No | `object` | Instantánea estática de capacidades integradas para speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search y propiedad de herramientas. | +| `channelConfigs` | No | `Record` | Metadatos de configuración de canal propiedad del manifiesto fusionados en las superficies de descubrimiento y validación antes de que se cargue el runtime. | +| `skills` | No | `string[]` | Directorios de Skills que se deben cargar, relativos a la raíz del plugin. | | `name` | No | `string` | Nombre legible del plugin. | -| `description` | No | `string` | Resumen corto que se muestra en las superficies del plugin. | +| `description` | No | `string` | Resumen breve mostrado en las superficies del plugin. | | `version` | No | `string` | Versión informativa del plugin. | | `uiHints` | No | `Record` | Etiquetas de UI, placeholders y pistas de sensibilidad para los campos de configuración. | ## Referencia de `providerAuthChoices` Cada entrada de `providerAuthChoices` describe una opción de incorporación o autenticación. -OpenClaw la lee antes de que se cargue el runtime del proveedor. +OpenClaw lee esto antes de que se cargue el runtime del proveedor. -| Campo | Obligatorio | Tipo | Qué significa | -| --------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | Sí | `string` | Id del proveedor al que pertenece esta opción. | -| `method` | Sí | `string` | Id del método de autenticación al que se debe dirigir. | -| `choiceId` | Sí | `string` | Id estable de opción de autenticación usado por los flujos de incorporación y CLI. | -| `choiceLabel` | No | `string` | Etiqueta visible para el usuario. Si se omite, OpenClaw usa `choiceId` como alternativa. | -| `choiceHint` | No | `string` | Texto breve de ayuda para el selector. | -| `assistantPriority` | No | `number` | Los valores más bajos se ordenan antes en los selectores interactivos controlados por el asistente. | -| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción en los selectores del asistente, pero sigue permitiendo la selección manual desde CLI. | -| `deprecatedChoiceIds` | No | `string[]` | Ids heredados de opciones que deben redirigir a los usuarios a esta opción de reemplazo. | -| `groupId` | No | `string` | Id opcional de grupo para agrupar opciones relacionadas. | -| `groupLabel` | No | `string` | Etiqueta visible para el usuario de ese grupo. | -| `groupHint` | No | `string` | Texto breve de ayuda para el grupo. | -| `optionKey` | No | `string` | Clave interna de opción para flujos simples de autenticación con una sola flag. | -| `cliFlag` | No | `string` | Nombre de la flag de CLI, como `--openrouter-api-key`. | -| `cliOption` | No | `string` | Forma completa de la opción de CLI, como `--openrouter-api-key `. | -| `cliDescription` | No | `string` | Descripción usada en la ayuda de CLI. | -| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | En qué superficies de incorporación debe aparecer esta opción. Si se omite, el valor predeterminado es `["text-inference"]`. | +| Campo | Obligatorio | Tipo | Qué significa | +| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `provider` | Sí | `string` | ID del proveedor al que pertenece esta opción. | +| `method` | Sí | `string` | ID del método de autenticación al que se debe dirigir. | +| `choiceId` | Sí | `string` | ID estable de opción de autenticación usado por los flujos de incorporación y de CLI. | +| `choiceLabel` | No | `string` | Etiqueta visible para el usuario. Si se omite, OpenClaw usa `choiceId` como valor alternativo. | +| `choiceHint` | No | `string` | Texto breve de ayuda para el selector. | +| `assistantPriority` | No | `number` | Los valores más bajos se ordenan antes en los selectores interactivos guiados por el asistente. | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción en los selectores del asistente mientras sigue permitiendo la selección manual por CLI. | +| `deprecatedChoiceIds` | No | `string[]` | IDs heredados de opciones que deberían redirigir a los usuarios a esta opción de reemplazo. | +| `groupId` | No | `string` | ID de grupo opcional para agrupar opciones relacionadas. | +| `groupLabel` | No | `string` | Etiqueta visible para el usuario de ese grupo. | +| `groupHint` | No | `string` | Texto breve de ayuda para el grupo. | +| `optionKey` | No | `string` | Clave de opción interna para flujos de autenticación simples de una sola flag. | +| `cliFlag` | No | `string` | Nombre de la flag de CLI, como `--openrouter-api-key`. | +| `cliOption` | No | `string` | Forma completa de la opción de CLI, como `--openrouter-api-key `. | +| `cliDescription` | No | `string` | Descripción usada en la ayuda de CLI. | +| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | En qué superficies de incorporación debería aparecer esta opción. Si se omite, el valor predeterminado es `["text-inference"]`. | ## Referencia de `commandAliases` -Usa `commandAliases` cuando un plugin es propietario de un nombre de comando de runtime que los usuarios pueden -poner por error en `plugins.allow` o intentar ejecutar como un comando raíz de CLI. OpenClaw -usa estos metadatos para diagnósticos sin importar código de runtime del plugin. +Usa `commandAliases` cuando un plugin es propietario de un nombre de comando del runtime que los usuarios pueden +poner por error en `plugins.allow` o intentar ejecutar como un comando CLI raíz. OpenClaw +usa estos metadatos para diagnósticos sin importar el código del runtime del plugin. ```json { @@ -208,19 +211,19 @@ usa estos metadatos para diagnósticos sin importar código de runtime del plugi } ``` -| Campo | Obligatorio | Tipo | Qué significa | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | -| `name` | Sí | `string` | Nombre del comando que pertenece a este plugin. | -| `kind` | No | `"runtime-slash"` | Marca el alias como un comando slash de chat en lugar de un comando raíz de CLI. | -| `cliCommand` | No | `string` | Comando raíz de CLI relacionado que se debe sugerir para operaciones de CLI, si existe. | +| Campo | Obligatorio | Tipo | Qué significa | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ | +| `name` | Sí | `string` | Nombre del comando que pertenece a este plugin. | +| `kind` | No | `"runtime-slash"` | Marca el alias como un comando slash de chat en lugar de un comando CLI raíz. | +| `cliCommand` | No | `string` | Comando CLI raíz relacionado que se debe sugerir para operaciones de CLI, si existe. | ## Referencia de `activation` Usa `activation` cuando el plugin puede declarar de forma ligera qué eventos del plano de control -deben activarlo más adelante. +deberían activarlo más adelante. -Este bloque es solo metadatos. No registra comportamiento en runtime, y no -reemplaza `register(...)`, `setupEntry` ni otros entrypoints de runtime/plugin. +Este bloque es solo metadatos. No registra comportamiento del runtime, y no +reemplaza `register(...)`, `setupEntry` ni otros puntos de entrada de runtime/plugin. ```json { @@ -234,13 +237,13 @@ reemplaza `register(...)`, `setupEntry` ni otros entrypoints de runtime/plugin. } ``` -| Campo | Obligatorio | Tipo | Qué significa | -| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------ | -| `onProviders` | No | `string[]` | Ids de proveedores que deben activar este plugin cuando se soliciten. | -| `onCommands` | No | `string[]` | Ids de comandos que deben activar este plugin. | -| `onChannels` | No | `string[]` | Ids de canales que deben activar este plugin. | -| `onRoutes` | No | `string[]` | Tipos de rutas que deben activar este plugin. | -| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Pistas generales de capacidades usadas por la planificación de activación del plano de control. | +| Campo | Obligatorio | Tipo | Qué significa | +| ---------------- | ----------- | ---------------------------------------------------- | ----------------------------------------------------------------- | +| `onProviders` | No | `string[]` | IDs de proveedor que deberían activar este plugin cuando se soliciten. | +| `onCommands` | No | `string[]` | IDs de comando que deberían activar este plugin. | +| `onChannels` | No | `string[]` | IDs de canal que deberían activar este plugin. | +| `onRoutes` | No | `string[]` | Tipos de ruta que deberían activar este plugin. | +| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Pistas amplias de capacidad usadas por la planificación de activación del plano de control. | ## Referencia de `setup` @@ -265,25 +268,36 @@ antes de que se cargue el runtime. ``` El `cliBackends` de nivel superior sigue siendo válido y continúa describiendo -backends de inferencia de CLI. `setup.cliBackends` es la superficie descriptiva específica de configuración para -flujos de plano de control/configuración que deben seguir siendo solo metadatos. +los backends de inferencia de CLI. `setup.cliBackends` es la superficie de descriptor específica de configuración para +los flujos de configuración/plano de control que deben seguir siendo solo metadatos. + +Cuando están presentes, `setup.providers` y `setup.cliBackends` son la superficie preferida de búsqueda basada primero en descriptores +para el descubrimiento de configuración. Si el descriptor solo +reduce el plugin candidato y la configuración aún necesita hooks de runtime más completos en tiempo de configuración, +establece `requiresRuntime: true` y mantén `setup-api` como la +ruta de ejecución de respaldo. + +Debido a que la búsqueda de configuración puede ejecutar código `setup-api` propiedad del plugin, los valores normalizados de +`setup.providers[].id` y `setup.cliBackends[]` deben seguir siendo únicos entre +los plugins detectados. La propiedad ambigua falla de forma cerrada en lugar de elegir un +ganador según el orden de descubrimiento. ### Referencia de `setup.providers` -| Campo | Obligatorio | Tipo | Qué significa | -| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | Sí | `string` | Id del proveedor expuesto durante la configuración o incorporación. | -| `authMethods` | No | `string[]` | Ids de métodos de configuración/autenticación que este proveedor admite sin cargar todo el runtime. | +| Campo | Obligatorio | Tipo | Qué significa | +| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- | +| `id` | Sí | `string` | ID de proveedor expuesto durante la configuración o la incorporación. Mantén los IDs normalizados globalmente únicos. | +| `authMethods` | No | `string[]` | IDs de métodos de configuración/autenticación que este proveedor admite sin cargar el runtime completo. | | `envVars` | No | `string[]` | Variables de entorno que las superficies genéricas de configuración/estado pueden comprobar antes de que se cargue el runtime del plugin. | ### Campos de `setup` -| Campo | Obligatorio | Tipo | Qué significa | -| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------- | -| `providers` | No | `object[]` | Descriptores de configuración de proveedores expuestos durante la configuración y la incorporación. | -| `cliBackends` | No | `string[]` | Ids de backends disponibles en tiempo de configuración sin activación completa del runtime. | -| `configMigrations` | No | `string[]` | Ids de migraciones de configuración propiedad de la superficie de configuración de este plugin. | -| `requiresRuntime` | No | `boolean` | Indica si la configuración aún necesita ejecutar el runtime del plugin después de consultar el descriptor. | +| Campo | Obligatorio | Tipo | Qué significa | +| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- | +| `providers` | No | `object[]` | Descriptores de configuración de proveedor expuestos durante la configuración y la incorporación. | +| `cliBackends` | No | `string[]` | IDs de backend en tiempo de configuración usados para la búsqueda de configuración basada primero en descriptores. Mantén los IDs normalizados globalmente únicos. | +| `configMigrations` | No | `string[]` | IDs de migración de configuración propiedad de la superficie de configuración de este plugin. | +| `requiresRuntime` | No | `boolean` | Si la configuración aún necesita la ejecución de `setup-api` después de la búsqueda por descriptores. | ## Referencia de `uiHints` @@ -304,14 +318,14 @@ flujos de plano de control/configuración que deben seguir siendo solo metadatos Cada pista de campo puede incluir: -| Campo | Tipo | Qué significa | -| ------------- | ---------- | ------------------------------------------- | -| `label` | `string` | Etiqueta del campo visible para el usuario. | -| `help` | `string` | Texto breve de ayuda. | -| `tags` | `string[]` | Etiquetas opcionales de UI. | -| `advanced` | `boolean` | Marca el campo como avanzado. | -| `sensitive` | `boolean` | Marca el campo como secreto o sensible. | -| `placeholder` | `string` | Texto de placeholder para entradas de formularios. | +| Campo | Tipo | Qué significa | +| ------------- | ---------- | ---------------------------------------------- | +| `label` | `string` | Etiqueta del campo visible para el usuario. | +| `help` | `string` | Texto breve de ayuda. | +| `tags` | `string[]` | Etiquetas de UI opcionales. | +| `advanced` | `boolean` | Marca el campo como avanzado. | +| `sensitive` | `boolean` | Marca el campo como secreto o sensible. | +| `placeholder` | `string` | Texto de placeholder para entradas de formulario. | ## Referencia de `contracts` @@ -336,22 +350,22 @@ leer sin importar el runtime del plugin. Cada lista es opcional: -| Campo | Tipo | Qué significa | -| -------------------------------- | ---------- | ----------------------------------------------------------------- | -| `speechProviders` | `string[]` | Ids de proveedores de speech propiedad de este plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ids de proveedores de transcripción en tiempo real propiedad de este plugin. | -| `realtimeVoiceProviders` | `string[]` | Ids de proveedores de voz en tiempo real propiedad de este plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ids de proveedores de media-understanding propiedad de este plugin. | -| `imageGenerationProviders` | `string[]` | Ids de proveedores de generación de imágenes propiedad de este plugin. | -| `videoGenerationProviders` | `string[]` | Ids de proveedores de generación de video propiedad de este plugin. | -| `webFetchProviders` | `string[]` | Ids de proveedores de web-fetch propiedad de este plugin. | -| `webSearchProviders` | `string[]` | Ids de proveedores de búsqueda web propiedad de este plugin. | -| `tools` | `string[]` | Nombres de herramientas del agente propiedad de este plugin para comprobaciones de contratos incluidos. | +| Campo | Tipo | Qué significa | +| -------------------------------- | ---------- | ----------------------------------------------------------- | +| `speechProviders` | `string[]` | IDs de proveedor de speech propiedad de este plugin. | +| `realtimeTranscriptionProviders` | `string[]` | IDs de proveedor de realtime transcription propiedad de este plugin. | +| `realtimeVoiceProviders` | `string[]` | IDs de proveedor de realtime voice propiedad de este plugin. | +| `mediaUnderstandingProviders` | `string[]` | IDs de proveedor de media-understanding propiedad de este plugin. | +| `imageGenerationProviders` | `string[]` | IDs de proveedor de image-generation propiedad de este plugin. | +| `videoGenerationProviders` | `string[]` | IDs de proveedor de video-generation propiedad de este plugin. | +| `webFetchProviders` | `string[]` | IDs de proveedor de web-fetch propiedad de este plugin. | +| `webSearchProviders` | `string[]` | IDs de proveedor de web search propiedad de este plugin. | +| `tools` | `string[]` | Nombres de herramientas del agente propiedad de este plugin para comprobaciones de contratos integrados. | ## Referencia de `channelConfigs` -Usa `channelConfigs` cuando un plugin de canal necesita metadatos de configuración ligeros antes de que se -cargue el runtime. +Usa `channelConfigs` cuando un plugin de canal necesita metadatos ligeros de configuración antes +de que se cargue el runtime. ```json { @@ -366,12 +380,12 @@ cargue el runtime. }, "uiHints": { "homeserverUrl": { - "label": "URL del homeserver", + "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Conexión al homeserver de Matrix", + "description": "Matrix homeserver connection", "preferOver": ["matrix-legacy"] } } @@ -382,16 +396,16 @@ Cada entrada de canal puede incluir: | Campo | Tipo | Qué significa | | ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | -| `schema` | `object` | Esquema JSON para `channels.`. Obligatorio para cada entrada declarada de configuración de canal. | -| `uiHints` | `Record` | Etiquetas de UI/placeholders/pistas de sensibilidad opcionales para esa sección de configuración del canal. | -| `label` | `string` | Etiqueta del canal combinada en las superficies de selección e inspección cuando los metadatos del runtime no están listos. | -| `description` | `string` | Descripción breve del canal para las superficies de inspección y catálogo. | -| `preferOver` | `string[]` | Ids heredados o de menor prioridad a los que este canal debe superar en las superficies de selección. | +| `schema` | `object` | Esquema JSON para `channels.`. Es obligatorio para cada entrada declarada de configuración de canal. | +| `uiHints` | `Record` | Etiquetas de UI, placeholders y pistas de sensibilidad opcionales para esa sección de configuración del canal. | +| `label` | `string` | Etiqueta del canal fusionada en las superficies de selector e inspección cuando los metadatos del runtime no están listos. | +| `description` | `string` | Descripción breve del canal para las superficies de inspección y catálogo. | +| `preferOver` | `string[]` | IDs de plugin heredados o de menor prioridad a los que este canal debería superar en las superficies de selección. | ## Referencia de `modelSupport` Usa `modelSupport` cuando OpenClaw deba inferir tu plugin de proveedor a partir de -ids abreviados de modelos como `gpt-5.4` o `claude-sonnet-4.6` antes de que se cargue el runtime del plugin. +IDs abreviados de modelo como `gpt-5.4` o `claude-sonnet-4.6` antes de que se cargue el runtime del plugin. ```json { @@ -406,70 +420,70 @@ OpenClaw aplica esta precedencia: - las referencias explícitas `provider/model` usan los metadatos del manifiesto `providers` propietario - `modelPatterns` tienen prioridad sobre `modelPrefixes` -- si un plugin no incluido y uno incluido coinciden, gana el plugin no incluido +- si un plugin no integrado y un plugin integrado coinciden, gana el plugin no integrado - la ambigüedad restante se ignora hasta que el usuario o la configuración especifiquen un proveedor Campos: -| Campo | Tipo | Qué significa | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Prefijos que se comparan con `startsWith` contra ids abreviados de modelos. | -| `modelPatterns` | `string[]` | Fuentes regex que se comparan con ids abreviados de modelos después de quitar el sufijo del perfil. | +| Campo | Tipo | Qué significa | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Prefijos comparados con `startsWith` contra IDs abreviados de modelo. | +| `modelPatterns` | `string[]` | Orígenes de regex comparados contra IDs abreviados de modelo después de eliminar el sufijo del perfil. | -Las claves heredadas de capacidades de nivel superior están obsoletas. Usa `openclaw doctor --fix` para +Las claves heredadas de capacidad de nivel superior están obsoletas. Usa `openclaw doctor --fix` para mover `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` y `webSearchProviders` a `contracts`; la -carga normal del manifiesto ya no trata esos campos de nivel superior como propiedad +`webFetchProviders` y `webSearchProviders` bajo `contracts`; la carga normal +del manifiesto ya no trata esos campos de nivel superior como propiedad de capacidades. ## Manifiesto frente a package.json -Los dos archivos cumplen funciones distintas: +Los dos archivos cumplen funciones diferentes: -| Archivo | Úsalo para | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Descubrimiento, validación de configuración, metadatos de opciones de autenticación y pistas de UI que deben existir antes de que se ejecute el código del plugin | -| `package.json` | Metadatos de npm, instalación de dependencias y el bloque `openclaw` usado para entrypoints, control de instalación, configuración o metadatos de catálogo | +| Archivo | Úsalo para | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Descubrimiento, validación de la configuración, metadatos de opciones de autenticación y pistas de UI que deben existir antes de que se ejecute el código del plugin | +| `package.json` | Metadatos de npm, instalación de dependencias y el bloque `openclaw` usado para puntos de entrada, restricción de instalación, configuración o metadatos de catálogo | -Si no estás seguro de dónde debe ir una pieza de metadatos, usa esta regla: +Si no estás seguro de dónde pertenece una pieza de metadatos, usa esta regla: - si OpenClaw debe conocerla antes de cargar el código del plugin, colócala en `openclaw.plugin.json` - si trata sobre empaquetado, archivos de entrada o comportamiento de instalación de npm, colócala en `package.json` -### Campos de `package.json` que afectan al descubrimiento +### Campos de package.json que afectan al descubrimiento -Algunos metadatos del plugin previos al runtime viven intencionalmente en `package.json` dentro del +Algunos metadatos de plugin previos al runtime viven intencionalmente en `package.json` dentro del bloque `openclaw` en lugar de `openclaw.plugin.json`. Ejemplos importantes: -| Campo | Qué significa | -| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Declara entrypoints nativos del plugin. | -| `openclaw.setupEntry` | Entrypoint ligero solo para configuración usado durante la incorporación y el inicio diferido de canales. | -| `openclaw.channel` | Metadatos ligeros del catálogo de canales, como etiquetas, rutas de documentación, alias y texto de selección. | -| `openclaw.channel.configuredState` | Metadatos ligeros del verificador de estado configurado que pueden responder "¿ya existe una configuración solo con variables de entorno?" sin cargar el runtime completo del canal. | -| `openclaw.channel.persistedAuthState` | Metadatos ligeros del verificador de autenticación persistida que pueden responder "¿ya hay algo con sesión iniciada?" sin cargar el runtime completo del canal. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Pistas de instalación/actualización para plugins incluidos y publicados externamente. | -| `openclaw.install.defaultChoice` | Ruta de instalación preferida cuando hay varias fuentes de instalación disponibles. | -| `openclaw.install.minHostVersion` | Versión mínima compatible del host OpenClaw, usando un límite inferior de semver como `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Permite una ruta de recuperación de reinstalación limitada para plugins incluidos cuando la configuración es inválida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies del canal solo de configuración se carguen antes que el plugin completo del canal durante el inicio. | +| Campo | Qué significa | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Declara puntos de entrada nativos del plugin. | +| `openclaw.setupEntry` | Punto de entrada ligero solo para configuración usado durante la incorporación y el inicio diferido de canales. | +| `openclaw.channel` | Metadatos ligeros del catálogo de canales como etiquetas, rutas de documentación, alias y texto de selección. | +| `openclaw.channel.configuredState` | Metadatos ligeros del verificador de estado configurado que pueden responder “¿ya existe una configuración solo con variables de entorno?” sin cargar el runtime completo del canal. | +| `openclaw.channel.persistedAuthState` | Metadatos ligeros del verificador de autenticación persistida que pueden responder “¿ya hay algo con sesión iniciada?” sin cargar el runtime completo del canal. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Pistas de instalación/actualización para plugins integrados y plugins publicados externamente. | +| `openclaw.install.defaultChoice` | Ruta de instalación preferida cuando hay varias fuentes de instalación disponibles. | +| `openclaw.install.minHostVersion` | Versión mínima compatible del host OpenClaw, usando un mínimo semver como `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Permite una ruta limitada de recuperación por reinstalación de plugin integrado cuando la configuración no es válida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies de canal solo de configuración se carguen antes del plugin completo del canal durante el inicio. | -`openclaw.install.minHostVersion` se aplica durante la instalación y la -carga del registro del manifiesto. Los valores inválidos se rechazan; los valores más nuevos pero válidos omiten el +`openclaw.install.minHostVersion` se aplica durante la instalación y la carga del registro +de manifiestos. Los valores no válidos se rechazan; los valores válidos pero más recientes omiten el plugin en hosts más antiguos. `openclaw.install.allowInvalidConfigRecovery` es intencionalmente limitado. No -hace instalables configuraciones rotas arbitrarias. Actualmente solo permite a los flujos de instalación -recuperarse de fallos específicos de actualización de plugins incluidos obsoletos, como una -ruta faltante de plugin incluido o una entrada obsoleta `channels.` para ese mismo -plugin incluido. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores +hace instalables configuraciones arbitrarias rotas. Actualmente solo permite que los +flujos de instalación se recuperen de fallos específicos de actualización de plugins integrados obsoletos, como una +ruta faltante de plugin integrado o una entrada obsoleta `channels.` para ese mismo +plugin integrado. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores a `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` son metadatos del paquete para un pequeño +`openclaw.channel.persistedAuthState` son metadatos de paquete para un pequeño módulo verificador: ```json @@ -487,11 +501,12 @@ módulo verificador: ``` Úsalo cuando los flujos de configuración, doctor o estado configurado necesiten una -comprobación barata de autenticación sí/no antes de que se cargue el plugin completo del canal. La exportación de destino debe ser una pequeña -función que solo lea el estado persistido; no la enrutes a través del barrel completo del runtime del canal. +comprobación ligera de sí/no de autenticación antes de que se cargue el plugin completo del canal. La +exportación de destino debe ser una función pequeña que lea solo el estado persistido; no la encamines a través del barrel completo del runtime +del canal. `openclaw.channel.configuredState` sigue la misma forma para comprobaciones ligeras -de estado configurado solo con variables de entorno: +de estado configurado solo por entorno: ```json { @@ -507,29 +522,29 @@ de estado configurado solo con variables de entorno: } ``` -Úsalo cuando un canal pueda responder el estado configurado a partir de variables de entorno u otras pequeñas -entradas ajenas al runtime. Si la comprobación necesita resolución completa de la configuración o el +Úsalo cuando un canal pueda responder al estado configurado desde variables de entorno u otras entradas pequeñas +que no pertenecen al runtime. Si la comprobación necesita la resolución completa de la configuración o el runtime real del canal, mantén esa lógica en el hook `config.hasConfiguredState` -del plugin. +del plugin en su lugar. ## Requisitos del esquema JSON -- **Cada plugin debe incluir un esquema JSON**, aunque no acepte configuración. +- **Todo plugin debe incluir un esquema JSON**, incluso si no acepta configuración. - Se acepta un esquema vacío (por ejemplo, `{ "type": "object", "additionalProperties": false }`). -- Los esquemas se validan en el momento de lectura/escritura de la configuración, no en runtime. +- Los esquemas se validan en tiempo de lectura/escritura de la configuración, no en tiempo de runtime. ## Comportamiento de validación -- Las claves desconocidas en `channels.*` son **errores**, a menos que el id del canal esté declarado por +- Las claves desconocidas `channels.*` son **errores**, a menos que el ID del canal esté declarado por un manifiesto de plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` y `plugins.slots.*` - deben hacer referencia a ids de plugin **detectables**. Los ids desconocidos son **errores**. + deben hacer referencia a IDs de plugin **detectables**. Los IDs desconocidos son **errores**. - Si un plugin está instalado pero tiene un manifiesto o esquema roto o faltante, la validación falla y Doctor informa el error del plugin. - Si existe configuración del plugin pero el plugin está **deshabilitado**, la configuración se conserva y - se muestra una **advertencia** en Doctor + logs. + se muestra una **advertencia** en Doctor + los registros. -Consulta la [Referencia de configuración](/es/gateway/configuration) para el esquema completo de `plugins.*`. +Consulta [Referencia de configuración](/es/gateway/configuration) para ver el esquema completo de `plugins.*`. ## Notas @@ -538,28 +553,28 @@ Consulta la [Referencia de configuración](/es/gateway/configuration) para el es descubrimiento + validación. - Los manifiestos nativos se analizan con JSON5, por lo que se aceptan comentarios, comas finales y claves sin comillas siempre que el valor final siga siendo un objeto. -- El cargador del manifiesto solo lee los campos documentados del manifiesto. Evita agregar +- El cargador de manifiestos solo lee los campos de manifiesto documentados. Evita añadir aquí claves personalizadas de nivel superior. -- `providerAuthEnvVars` es la ruta ligera de metadatos para sondas de autenticación, validación de marcadores de variables de entorno - y superficies similares de autenticación de proveedores que no deberían iniciar el runtime del plugin +- `providerAuthEnvVars` es la ruta ligera de metadatos para sondeos de autenticación, validación + de marcadores de variables de entorno y superficies similares de autenticación de proveedor que no deberían iniciar el runtime del plugin solo para inspeccionar nombres de variables de entorno. -- `providerAuthAliases` permite que variantes de proveedores reutilicen la autenticación de otro proveedor - en variables de entorno, perfiles de autenticación, autenticación basada en configuración y opción de incorporación - con clave API sin codificar esa relación en el core. -- `channelEnvVars` es la ruta ligera de metadatos para fallback de variables de entorno del shell, prompts de configuración - y superficies similares de canal que no deberían iniciar el runtime del plugin +- `providerAuthAliases` permite que las variantes de proveedor reutilicen las + variables de entorno de autenticación, los perfiles de autenticación, la autenticación basada en configuración y la opción de incorporación de clave API + de otro proveedor sin codificar esa relación en el núcleo. +- `channelEnvVars` es la ruta ligera de metadatos para la reserva de variables de entorno del shell, los prompts de configuración + y superficies de canal similares que no deberían iniciar el runtime del plugin solo para inspeccionar nombres de variables de entorno. - `providerAuthChoices` es la ruta ligera de metadatos para selectores de opciones de autenticación, - resolución de `--auth-choice`, mapeo de proveedores preferidos y registro simple de flags de CLI de incorporación - antes de que se cargue el runtime del proveedor. Para metadatos del asistente en runtime - que requieran código del proveedor, consulta - [Hooks de runtime del proveedor](/es/plugins/architecture#provider-runtime-hooks). + resolución de `--auth-choice`, asignación de proveedor preferido y registro simple de flags de CLI + antes de que se cargue el runtime del proveedor. Para metadatos del asistente del runtime + que requieren código del proveedor, consulta + [Hooks del runtime del proveedor](/es/plugins/architecture#provider-runtime-hooks). - Los tipos exclusivos de plugin se seleccionan mediante `plugins.slots.*`. - - `kind: "memory"` se selecciona con `plugins.slots.memory`. - - `kind: "context-engine"` se selecciona con `plugins.slots.contextEngine` + - `kind: "memory"` se selecciona mediante `plugins.slots.memory`. + - `kind: "context-engine"` se selecciona mediante `plugins.slots.contextEngine` (predeterminado: `legacy` integrado). - `channels`, `providers`, `cliBackends` y `skills` pueden omitirse cuando un - plugin no los necesite. + plugin no los necesita. - Si tu plugin depende de módulos nativos, documenta los pasos de compilación y cualquier requisito de lista permitida del gestor de paquetes (por ejemplo, pnpm `allow-build-scripts` - `pnpm rebuild `). diff --git a/docs/es/reference/templates/AGENTS.md b/docs/es/reference/templates/AGENTS.md index b5e947aa7..ce066822b 100644 --- a/docs/es/reference/templates/AGENTS.md +++ b/docs/es/reference/templates/AGENTS.md @@ -1,35 +1,40 @@ --- read_when: - - Inicializar manualmente un workspace -summary: Plantilla de workspace para AGENTS.md + - Inicializar manualmente un espacio de trabajo +summary: Plantilla de espacio de trabajo para AGENTS.md title: Plantilla de AGENTS.md x-i18n: - generated_at: "2026-04-11T02:47:33Z" + generated_at: "2026-04-12T05:10:59Z" model: gpt-5.4 provider: openai - source_hash: 6d8a3e96f547da6cc082d747c042555b0ec4963b66921d1700b4590f0e0c38b4 + source_hash: b7a68a1f0b4b837298bfe6edf8ce855d6ef6902ea8e7277b0d9a8442b23daf54 source_path: reference/templates/AGENTS.md workflow: 15 --- -# AGENTS.md - Tu workspace +# AGENTS.md - Tu espacio de trabajo Esta carpeta es tu hogar. Trátala como tal. ## Primera ejecución -Si existe `BOOTSTRAP.md`, ese es tu certificado de nacimiento. Síguelo, descubre quién eres y luego elimínalo. No volverás a necesitarlo. +Si existe `BOOTSTRAP.md`, ese es tu certificado de nacimiento. Síguelo, averigua quién eres y luego elimínalo. No lo volverás a necesitar. ## Inicio de sesión -Antes de hacer cualquier otra cosa: +Usa primero el contexto de inicio proporcionado por el entorno de ejecución. -1. Lee `SOUL.md` — esto es quién eres -2. Lee `USER.md` — esta es la persona a la que estás ayudando -3. Lee `memory/YYYY-MM-DD.md` (hoy + ayer) para obtener contexto reciente -4. **Si estás en MAIN SESSION** (chat directo con tu humano): también lee `MEMORY.md` +Ese contexto puede incluir ya: -No pidas permiso. Simplemente hazlo. +- `AGENTS.md`, `SOUL.md` y `USER.md` +- memoria diaria reciente como `memory/YYYY-MM-DD.md` +- `MEMORY.md` cuando esta sea la sesión principal + +No vuelvas a leer manualmente los archivos de inicio a menos que: + +1. El usuario lo pida explícitamente +2. Al contexto proporcionado le falte algo que necesites +3. Necesites una lectura de seguimiento más profunda más allá del contexto de inicio proporcionado ## Memoria @@ -38,33 +43,33 @@ Despiertas desde cero en cada sesión. Estos archivos son tu continuidad: - **Notas diarias:** `memory/YYYY-MM-DD.md` (crea `memory/` si hace falta) — registros en bruto de lo que ocurrió - **Largo plazo:** `MEMORY.md` — tus recuerdos seleccionados, como la memoria a largo plazo de una persona -Captura lo importante. Decisiones, contexto, cosas para recordar. Omite los secretos, salvo que te pidan conservarlos. +Captura lo importante. Decisiones, contexto, cosas para recordar. Omite los secretos a menos que te pidan conservarlos. ### 🧠 MEMORY.md - Tu memoria a largo plazo - **Cárgalo SOLO en la sesión principal** (chats directos con tu humano) - **NO lo cargues en contextos compartidos** (Discord, chats grupales, sesiones con otras personas) -- Esto es por **seguridad** — contiene contexto personal que no debería filtrarse a desconocidos -- Puedes **leer, editar y actualizar** MEMORY.md libremente en las sesiones principales -- Escribe eventos significativos, pensamientos, decisiones, opiniones y lecciones aprendidas -- Esta es tu memoria seleccionada — la esencia destilada, no los registros en bruto -- Con el tiempo, revisa tus archivos diarios y actualiza MEMORY.md con lo que valga la pena conservar +- Esto es por **seguridad** — contiene contexto personal que no debería filtrarse a extraños +- Puedes **leer, editar y actualizar** `MEMORY.md` libremente en las sesiones principales +- Escribe eventos, pensamientos, decisiones, opiniones y lecciones aprendidas significativas +- Esta es tu memoria seleccionada — la esencia destilada, no registros en bruto +- Con el tiempo, revisa tus archivos diarios y actualiza `MEMORY.md` con lo que valga la pena conservar -### 📝 Escríbelo - ¡Nada de "notas mentales"! +### 📝 ¡Anótalo - Nada de "notas mentales"! - **La memoria es limitada** — si quieres recordar algo, ESCRÍBELO EN UN ARCHIVO - Las "notas mentales" no sobreviven a los reinicios de sesión. Los archivos sí. - Cuando alguien diga "recuerda esto" → actualiza `memory/YYYY-MM-DD.md` o el archivo correspondiente - Cuando aprendas una lección → actualiza AGENTS.md, TOOLS.md o la skill correspondiente - Cuando cometas un error → documéntalo para que tu yo futuro no lo repita -- **Texto > Cerebro** 📝 +- **Texto > cerebro** 📝 ## Líneas rojas -- No exfiltres datos privados. Nunca. +- No extraigas datos privados. Nunca. - No ejecutes comandos destructivos sin preguntar. -- `trash` > `rm` (recuperable es mejor que desaparecido para siempre) -- Si dudas, pregunta. +- `trash` > `rm` (recuperable es mejor que perdido para siempre) +- En caso de duda, pregunta. ## Externo vs interno @@ -72,11 +77,11 @@ Captura lo importante. Decisiones, contexto, cosas para recordar. Omite los secr - Leer archivos, explorar, organizar, aprender - Buscar en la web, revisar calendarios -- Trabajar dentro de este workspace +- Trabajar dentro de este espacio de trabajo **Pregunta primero:** -- Enviar correos electrónicos, tuits o publicaciones públicas +- Enviar correos, tuits, publicaciones públicas - Cualquier cosa que salga de la máquina - Cualquier cosa sobre la que no estés seguro @@ -84,27 +89,27 @@ Captura lo importante. Decisiones, contexto, cosas para recordar. Omite los secr Tienes acceso a las cosas de tu humano. Eso no significa que _compartas_ sus cosas. En grupos, eres un participante — no su voz, no su representante. Piensa antes de hablar. -### 💬 ¡Saber cuándo hablar! +### 💬 ¡Sabe cuándo hablar! -En chats grupales donde recibes cada mensaje, sé **inteligente sobre cuándo participar**: +En chats grupales donde recibes todos los mensajes, sé **inteligente sobre cuándo contribuir**: **Responde cuando:** - Te mencionen directamente o te hagan una pregunta - Puedas aportar valor real (información, perspectiva, ayuda) - Algo ingenioso/divertido encaje de forma natural -- Corregir información errónea importante -- Resumir cuando te lo pidan +- Corrijas desinformación importante +- Resumas cuando te lo pidan -**Guarda silencio (HEARTBEAT_OK) cuando:** +**Quédate en silencio (`HEARTBEAT_OK`) cuando:** -- Sea solo charla casual entre humanos +- Solo sea charla casual entre personas - Alguien ya haya respondido la pregunta -- Tu respuesta sería solo "sí" o "bien" +- Tu respuesta solo sería "sí" o "qué bien" - La conversación fluya bien sin ti -- Agregar un mensaje interrumpiría el ambiente +- Añadir un mensaje interrumpiría el ambiente -**La regla humana:** Los humanos en chats grupales no responden a todos y cada uno de los mensajes. Tú tampoco deberías hacerlo. Calidad > cantidad. Si no lo enviarías en un chat grupal real con amigos, no lo envíes. +**La regla humana:** Las personas en los chats grupales no responden a cada mensaje. Tú tampoco deberías hacerlo. Calidad > cantidad. Si no lo enviarías en un chat grupal real con amigos, no lo envíes. **Evita el triple toque:** No respondas varias veces al mismo mensaje con reacciones distintas. Una respuesta pensada vale más que tres fragmentos. @@ -117,57 +122,57 @@ En plataformas que admiten reacciones (Discord, Slack), usa reacciones con emoji **Reacciona cuando:** - Aprecies algo pero no necesites responder (👍, ❤️, 🙌) -- Algo te haga reír (😂, 💀) -- Algo te parezca interesante o dé que pensar (🤔, 💡) -- Quieras reconocerlo sin interrumpir la conversación +- Algo te haya hecho reír (😂, 💀) +- Algo te parezca interesante o te haga pensar (🤔, 💡) +- Quieras reconocer algo sin interrumpir el flujo - Sea una situación simple de sí/no o aprobación (✅, 👀) **Por qué importa:** -Las reacciones son señales sociales ligeras. Los humanos las usan constantemente — dicen "vi esto, te reconozco" sin llenar el chat de ruido. Tú también deberías hacerlo. +Las reacciones son señales sociales ligeras. Las personas las usan constantemente — dicen "vi esto, te reconozco" sin llenar el chat de ruido. Tú también deberías hacerlo. -**No exageres:** Una reacción por mensaje como máximo. Elige la que mejor encaje. +**No te excedas:** Una reacción por mensaje como máximo. Elige la que mejor encaje. ## Herramientas -Las Skills te proporcionan tus herramientas. Cuando necesites una, revisa su `SKILL.md`. Guarda notas locales (nombres de cámaras, detalles SSH, preferencias de voz) en `TOOLS.md`. +Las Skills te proporcionan tus herramientas. Cuando necesites una, revisa su `SKILL.md`. Guarda notas locales (nombres de cámaras, detalles de SSH, preferencias de voz) en `TOOLS.md`. -**🎭 Narración por voz:** Si tienes `sag` (ElevenLabs TTS), usa la voz para historias, resúmenes de películas y momentos de "hora del cuento". Es mucho más atractivo que muros de texto. Sorprende a la gente con voces divertidas. +**🎭 Narración por voz:** Si tienes `sag` (ElevenLabs TTS), usa la voz para historias, resúmenes de películas y momentos de "storytime". Es mucho más atractivo que paredes de texto. Sorprende a la gente con voces graciosas. **📝 Formato por plataforma:** -- **Discord/WhatsApp:** ¡No uses tablas Markdown! Usa listas con viñetas -- **Enlaces en Discord:** Envuelve varios enlaces en `<>` para suprimir incrustaciones: `` -- **WhatsApp:** Sin encabezados — usa **negrita** o MAYÚSCULAS para dar énfasis +- **Discord/WhatsApp:** ¡No uses tablas Markdown! Usa listas con viñetas en su lugar +- **Enlaces en Discord:** Encierra varios enlaces entre `<>` para suprimir vistas previas: `` +- **WhatsApp:** Sin encabezados — usa **negrita** o MAYÚSCULAS para enfatizar ## 💓 Heartbeats - ¡Sé proactivo! -Cuando recibas una encuesta heartbeat (el mensaje coincide con el prompt heartbeat configurado), no respondas simplemente `HEARTBEAT_OK` siempre. ¡Usa los heartbeats de forma productiva! +Cuando recibas un sondeo de heartbeat (un mensaje que coincida con el prompt de heartbeat configurado), no respondas solo `HEARTBEAT_OK` cada vez. ¡Usa los heartbeats de forma productiva! -Puedes editar libremente `HEARTBEAT.md` con una lista corta de comprobación o recordatorios. Mantenlo pequeño para limitar el consumo de tokens. +Puedes editar `HEARTBEAT.md` libremente con una lista breve de verificación o recordatorios. Mantenlo pequeño para limitar el consumo de tokens. -### Heartbeat vs Cron: cuándo usar cada uno +### Heartbeat vs cron: cuándo usar cada uno **Usa heartbeat cuando:** -- Se puedan agrupar varias comprobaciones (bandeja de entrada + calendario + notificaciones en un solo turno) +- Puedan agruparse varias comprobaciones (bandeja de entrada + calendario + notificaciones en un solo turno) - Necesites contexto conversacional de mensajes recientes -- El tiempo pueda variar un poco (cada ~30 min está bien, no hace falta exactitud) -- Quieras reducir llamadas API combinando comprobaciones periódicas +- El tiempo pueda variar un poco (cada ~30 min está bien, no hace falta precisión exacta) +- Quieras reducir las llamadas a la API combinando comprobaciones periódicas **Usa cron cuando:** -- La hora exacta importa ("a las 9:00 AM en punto todos los lunes") -- La tarea necesita aislamiento del historial de la sesión principal -- Quieras un modelo o nivel de thinking diferente para la tarea -- Recordatorios puntuales ("recuérdame esto en 20 minutos") -- La salida deba entregarse directamente a un canal sin implicar la sesión principal +- La hora exacta importe ("9:00 AM en punto todos los lunes") +- La tarea necesite aislamiento del historial de la sesión principal +- Quieras un modelo o nivel de razonamiento distinto para la tarea +- Sean recordatorios de una sola vez ("recuérdamelo en 20 minutos") +- La salida deba enviarse directamente a un canal sin intervención de la sesión principal **Consejo:** Agrupa comprobaciones periódicas similares en `HEARTBEAT.md` en lugar de crear varios trabajos cron. Usa cron para horarios precisos y tareas independientes. -**Cosas para revisar (ve rotándolas, 2-4 veces al día):** +**Cosas que revisar (rota entre estas, 2-4 veces al día):** -- **Correos electrónicos** - ¿Hay mensajes no leídos urgentes? -- **Calendario** - ¿Hay eventos próximos en las siguientes 24-48 h? +- **Correos** - ¿Hay mensajes urgentes sin leer? +- **Calendario** - ¿Hay próximos eventos en las siguientes 24-48 h? - **Menciones** - ¿Notificaciones de Twitter/redes sociales? - **Clima** - ¿Es relevante si tu humano podría salir? @@ -186,21 +191,21 @@ Puedes editar libremente `HEARTBEAT.md` con una lista corta de comprobación o r **Cuándo contactar:** - Llegó un correo importante -- Se acerca un evento del calendario (<2 h) +- Se acerca un evento del calendario (<2h) - Encontraste algo interesante -- Han pasado >8 h desde que dijiste algo +- Han pasado >8h desde que dijiste algo -**Cuándo mantener silencio (HEARTBEAT_OK):** +**Cuándo mantenerte en silencio (`HEARTBEAT_OK`):** - Es tarde por la noche (23:00-08:00) salvo urgencia - El humano está claramente ocupado - No hay nada nuevo desde la última comprobación -- Acabas de revisar hace <30 minutos +- Acabas de comprobarlo hace <30 minutos **Trabajo proactivo que puedes hacer sin preguntar:** - Leer y organizar archivos de memoria -- Revisar proyectos (`git status`, etc.) +- Revisar proyectos (git status, etc.) - Actualizar documentación - Hacer commit y push de tus propios cambios - **Revisar y actualizar MEMORY.md** (ver abajo) @@ -210,14 +215,14 @@ Puedes editar libremente `HEARTBEAT.md` con una lista corta de comprobación o r Periódicamente (cada pocos días), usa un heartbeat para: 1. Leer los archivos recientes `memory/YYYY-MM-DD.md` -2. Identificar eventos significativos, lecciones o ideas que valga la pena conservar a largo plazo +2. Identificar eventos, lecciones o ideas significativas que valga la pena conservar a largo plazo 3. Actualizar `MEMORY.md` con aprendizajes destilados 4. Eliminar de MEMORY.md la información desactualizada que ya no sea relevante -Piensa en ello como una persona revisando su diario y actualizando su modelo mental. Los archivos diarios son notas en bruto; MEMORY.md es sabiduría seleccionada. +Piensa en ello como una persona que revisa su diario y actualiza su modelo mental. Los archivos diarios son notas en bruto; `MEMORY.md` es sabiduría seleccionada. -El objetivo: ser útil sin resultar molesto. Revisa unas pocas veces al día, haz trabajo útil en segundo plano, pero respeta los momentos de silencio. +El objetivo: ser útil sin resultar molesto. Haz comprobaciones unas cuantas veces al día, realiza trabajo útil en segundo plano, pero respeta los momentos de tranquilidad. ## Hazlo tuyo -Este es un punto de partida. Añade tus propias convenciones, estilo y reglas a medida que descubras qué funciona. +Este es un punto de partida. Añade tus propias convenciones, estilo y reglas a medida que descubras lo que funciona. diff --git a/docs/es/reference/token-use.md b/docs/es/reference/token-use.md index d5ece5a1d..823588d8d 100644 --- a/docs/es/reference/token-use.md +++ b/docs/es/reference/token-use.md @@ -1,22 +1,21 @@ --- read_when: - - Explicar el uso de tokens, los costos o las ventanas de contexto - - Depurar el crecimiento del contexto o el comportamiento de compactación -summary: Cómo OpenClaw construye el contexto del prompt y reporta el uso de tokens + costos + - Explicación del uso de tokens, costos o ventanas de contexto + - Depuración del crecimiento del contexto o del comportamiento de compactación +summary: Cómo OpenClaw construye el contexto del prompt e informa el uso de tokens + costos title: Uso de tokens y costos x-i18n: - generated_at: "2026-04-07T05:06:40Z" + generated_at: "2026-04-12T05:10:59Z" model: gpt-5.4 provider: openai - source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9 + source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb source_path: reference/token-use.md workflow: 15 --- # Uso de tokens y costos -OpenClaw rastrea **tokens**, no caracteres. Los tokens son específicos del modelo, pero la mayoría de los -modelos de estilo OpenAI promedian ~4 caracteres por token para texto en inglés. +OpenClaw rastrea **tokens**, no caracteres. Los tokens dependen del modelo, pero la mayoría de los modelos de estilo OpenAI promedian ~4 caracteres por token para texto en inglés. ## Cómo se construye el prompt del sistema @@ -25,69 +24,69 @@ OpenClaw ensambla su propio prompt del sistema en cada ejecución. Incluye: - Lista de herramientas + descripciones breves - Lista de Skills (solo metadatos; las instrucciones se cargan bajo demanda con `read`) - Instrucciones de autoactualización -- Espacio de trabajo + archivos de arranque (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` cuando son nuevos, más `MEMORY.md` cuando está presente o `memory.md` como respaldo en minúsculas). Los archivos grandes se truncan mediante `agents.defaults.bootstrapMaxChars` (predeterminado: 20000), y la inyección total de arranque está limitada por `agents.defaults.bootstrapTotalMaxChars` (predeterminado: 150000). Los archivos `memory/*.md` se cargan bajo demanda mediante herramientas de memoria y no se inyectan automáticamente. +- Archivos del espacio de trabajo + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` cuando son nuevos, además de `MEMORY.md` cuando está presente o `memory.md` como alternativa en minúsculas). Los archivos grandes se truncan según `agents.defaults.bootstrapMaxChars` (predeterminado: 20000), y la inyección total de bootstrap está limitada por `agents.defaults.bootstrapTotalMaxChars` (predeterminado: 150000). Los archivos diarios `memory/*.md` no forman parte del prompt bootstrap normal; permanecen disponibles bajo demanda mediante herramientas de memoria en turnos normales, pero `/new` y `/reset` sin argumentos pueden anteponer un bloque único de contexto de inicio con memoria diaria reciente para ese primer turno. Ese preludio de inicio está controlado por `agents.defaults.startupContext`. - Hora (UTC + zona horaria del usuario) - Etiquetas de respuesta + comportamiento de heartbeat - Metadatos de tiempo de ejecución (host/OS/model/thinking) Consulta el desglose completo en [Prompt del sistema](/es/concepts/system-prompt). -## Qué cuenta en la ventana de contexto +## Qué cuenta dentro de la ventana de contexto Todo lo que recibe el modelo cuenta para el límite de contexto: -- Prompt del sistema (todas las secciones listadas arriba) -- Historial de conversación (mensajes de usuario + asistente) +- Prompt del sistema (todas las secciones enumeradas arriba) +- Historial de conversación (mensajes del usuario + del asistente) - Llamadas a herramientas y resultados de herramientas - Adjuntos/transcripciones (imágenes, audio, archivos) - Resúmenes de compactación y artefactos de poda -- Wrappers del proveedor o encabezados de seguridad (no visibles, pero igualmente contados) +- Wrappers del proveedor o encabezados de seguridad (no visibles, pero igualmente contabilizados) -Para imágenes, OpenClaw reduce la escala de las cargas de imágenes de transcripción/herramientas antes de las llamadas al proveedor. +En el caso de imágenes, OpenClaw reduce la escala de las cargas de imágenes de transcripción/herramientas antes de las llamadas al proveedor. Usa `agents.defaults.imageMaxDimensionPx` (predeterminado: `1200`) para ajustarlo: -- Los valores más bajos normalmente reducen el uso de vision-tokens y el tamaño de la carga útil. -- Los valores más altos conservan más detalle visual para OCR/capturas de pantalla con mucha interfaz. +- Los valores más bajos suelen reducir el uso de vision tokens y el tamaño de la carga. +- Los valores más altos conservan más detalle visual para capturas de pantalla centradas en OCR/UI. Para un desglose práctico (por archivo inyectado, herramientas, Skills y tamaño del prompt del sistema), usa `/context list` o `/context detail`. Consulta [Contexto](/es/concepts/context). ## Cómo ver el uso actual de tokens -Usa estos comandos en el chat: +Usa esto en el chat: -- `/status` → **tarjeta de estado rica en emojis** con el modelo de la sesión, uso de contexto, - tokens de entrada/salida de la última respuesta y **costo estimado** (solo con clave API). -- `/usage off|tokens|full` → añade un **pie de uso por respuesta** a cada respuesta. - - Persiste por sesión (almacenado como `responseUsage`). +- `/status` → **tarjeta de estado con muchos emojis** con el modelo de la sesión, uso de contexto, + tokens de entrada/salida de la última respuesta y **costo estimado** (solo con API key). +- `/usage off|tokens|full` → agrega un **pie de uso por respuesta** a cada respuesta. + - Persiste por sesión (se almacena como `responseUsage`). - La autenticación OAuth **oculta el costo** (solo tokens). -- `/usage cost` → muestra un resumen local de costos a partir de los registros de sesión de OpenClaw. +- `/usage cost` → muestra un resumen local de costos a partir de los logs de sesión de OpenClaw. Otras superficies: -- **TUI/Web TUI:** `/status` + `/usage` están admitidos. +- **TUI/Web TUI:** `/status` y `/usage` son compatibles. - **CLI:** `openclaw status --usage` y `openclaw channels list` muestran ventanas de cuota del proveedor normalizadas (`X% left`, no costos por respuesta). Proveedores actuales con ventana de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi y z.ai. Las superficies de uso normalizan alias comunes de campos nativos del proveedor antes de mostrarlos. -Para el tráfico Responses de la familia OpenAI, eso incluye tanto `input_tokens` / -`output_tokens` como `prompt_tokens` / `completion_tokens`, para que los nombres de campos -específicos del transporte no cambien `/status`, `/usage` ni los resúmenes de sesión. -El uso JSON de Gemini CLI también se normaliza: el texto de la respuesta viene de `response`, y -`stats.cached` se asigna a `cacheRead`, usando `stats.input_tokens - stats.cached` -cuando el CLI omite un campo explícito `stats.input`. -Para el tráfico Responses nativo de la familia OpenAI, los alias de uso de WebSocket/SSE se -normalizan de la misma forma, y los totales vuelven a entrada + salida normalizadas cuando -falta `total_tokens` o es `0`. -Cuando la instantánea actual de la sesión es escasa, `/status` y `session_status` también pueden -recuperar contadores de tokens/caché y la etiqueta del modelo activo de tiempo de ejecución desde el -registro de uso más reciente de la transcripción. Los valores live existentes distintos de cero siguen teniendo -prioridad sobre los valores de respaldo de la transcripción, y los totales orientados al prompt más grandes +Para tráfico de Responses de la familia OpenAI, eso incluye tanto `input_tokens` / +`output_tokens` como `prompt_tokens` / `completion_tokens`, por lo que los nombres +de campos específicos del transporte no cambian `/status`, `/usage` ni los resúmenes de sesión. +El uso JSON de Gemini CLI también se normaliza: el texto de respuesta proviene de `response`, y +`stats.cached` se asigna a `cacheRead`, con `stats.input_tokens - stats.cached` +usado cuando la CLI omite un campo explícito `stats.input`. +Para tráfico nativo de Responses de la familia OpenAI, los alias de uso de WebSocket/SSE se +normalizan de la misma manera, y los totales recurren a entrada + salida normalizadas cuando +`total_tokens` falta o es `0`. +Cuando la instantánea de la sesión actual es escasa, `/status` y `session_status` también pueden +recuperar contadores de tokens/cache y la etiqueta del modelo activo en tiempo de ejecución desde el +log de uso de la transcripción más reciente. Los valores no nulos existentes en vivo siguen teniendo +prioridad sobre los valores recuperados de la transcripción, y los totales orientados al prompt más grandes de la transcripción pueden prevalecer cuando faltan los totales almacenados o son menores. La autenticación de uso para ventanas de cuota del proveedor proviene de hooks específicos del proveedor cuando -están disponibles; de lo contrario, OpenClaw vuelve a credenciales OAuth/clave API coincidentes de -perfiles de autenticación, entorno o configuración. +están disponibles; de lo contrario, OpenClaw recurre a hacer coincidir credenciales OAuth/API key +desde perfiles de autenticación, variables de entorno o configuración. ## Estimación de costos (cuando se muestra) @@ -97,36 +96,35 @@ Los costos se estiman a partir de tu configuración de precios del modelo: models.providers..models[].cost ``` -Estos son **USD por 1M de tokens** para `input`, `output`, `cacheRead` y -`cacheWrite`. Si faltan los precios, OpenClaw muestra solo los tokens. Los tokens OAuth +Estos son **USD por 1M tokens** para `input`, `output`, `cacheRead` y +`cacheWrite`. Si faltan los precios, OpenClaw muestra solo tokens. Los tokens OAuth nunca muestran costo en dólares. -## TTL de caché e impacto de la poda +## Impacto del TTL de caché y la poda -El almacenamiento en caché del prompt del proveedor solo se aplica dentro de la ventana TTL de la caché. OpenClaw puede -ejecutar opcionalmente **poda de cache-ttl**: poda la sesión una vez que el TTL de la caché -ha expirado y luego restablece la ventana de caché para que las solicitudes posteriores puedan reutilizar el -contexto recién almacenado en caché en lugar de volver a almacenar el historial completo. Esto mantiene los -costos de escritura de caché más bajos cuando una sesión queda inactiva después del TTL. +El almacenamiento en caché de prompts del proveedor solo se aplica dentro de la ventana TTL de caché. OpenClaw puede +ejecutar opcionalmente **poda por cache-ttl**: poda la sesión una vez que el TTL de caché +ha expirado, luego restablece la ventana de caché para que las solicitudes posteriores puedan reutilizar +el contexto recién almacenado en caché en lugar de volver a almacenar en caché todo el historial. Esto mantiene +más bajos los costos de escritura en caché cuando una sesión queda inactiva más allá del TTL. -Configúralo en [Configuración del gateway](/es/gateway/configuration) y consulta los -detalles del comportamiento en [Poda de sesiones](/es/concepts/session-pruning). +Configúralo en [Configuración de Gateway](/es/gateway/configuration) y consulta los +detalles del comportamiento en [Poda de sesión](/es/concepts/session-pruning). -Heartbeat puede mantener la caché **activa** durante períodos de inactividad. Si el TTL de caché de tu modelo +Heartbeat puede mantener la caché **caliente** durante periodos de inactividad. Si el TTL de caché de tu modelo es `1h`, establecer el intervalo de heartbeat justo por debajo de eso (por ejemplo, `55m`) puede evitar -volver a almacenar el prompt completo, reduciendo los costos de escritura de caché. +volver a almacenar en caché el prompt completo, reduciendo los costos de escritura en caché. En configuraciones con varios agentes, puedes mantener una configuración de modelo compartida y ajustar el comportamiento de caché por agente con `agents.list[].params.cacheRetention`. -Para una guía completa opción por opción, consulta [Almacenamiento en caché de prompts](/es/reference/prompt-caching). +Para una guía completa opción por opción, consulta [Prompt Caching](/es/reference/prompt-caching). -Para los precios de la API de Anthropic, las lecturas de caché son significativamente más baratas que los -tokens de entrada, mientras que las escrituras de caché se facturan con un multiplicador más alto. Consulta los -precios de almacenamiento en caché de prompts de Anthropic para ver las tarifas y multiplicadores TTL más recientes: +Para los precios de la API de Anthropic, las lecturas de caché son significativamente más baratas que los tokens +de entrada, mientras que las escrituras de caché se facturan con un multiplicador más alto. Consulta los precios de caché de prompt de Anthropic para ver las tarifas más recientes y los multiplicadores de TTL: [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### Ejemplo: mantener activa la caché de 1h con heartbeat +### Ejemplo: mantener caliente una caché de 1h con heartbeat ```yaml agents: @@ -156,19 +154,19 @@ agents: - id: "research" default: true heartbeat: - every: "55m" # mantener activa la caché larga para sesiones profundas + every: "55m" # mantiene caliente la caché larga para sesiones profundas - id: "alerts" params: - cacheRetention: "none" # evitar escrituras de caché para notificaciones en ráfagas + cacheRetention: "none" # evita escrituras de caché para notificaciones intermitentes ``` -`agents.list[].params` se fusiona sobre `params` del modelo seleccionado, así que puedes -sobrescribir solo `cacheRetention` y heredar sin cambios otros valores predeterminados del modelo. +`agents.list[].params` se fusiona sobre `params` del modelo seleccionado, por lo que puedes +sobrescribir solo `cacheRetention` y heredar sin cambios los demás valores predeterminados del modelo. -### Ejemplo: habilitar el encabezado beta de contexto 1M de Anthropic +### Ejemplo: habilitar el encabezado beta de contexto Anthropic 1M -La ventana de contexto 1M de Anthropic está actualmente restringida por beta. OpenClaw puede inyectar el -valor requerido de `anthropic-beta` cuando habilitas `context1m` en modelos Opus +La ventana de contexto de 1M de Anthropic está actualmente protegida por beta. OpenClaw puede inyectar el +valor `anthropic-beta` requerido cuando habilitas `context1m` en modelos Opus o Sonnet compatibles. ```yaml @@ -194,9 +192,9 @@ rechaza esa combinación con HTTP 401. ## Consejos para reducir la presión de tokens - Usa `/compact` para resumir sesiones largas. -- Recorta salidas grandes de herramientas en tus flujos de trabajo. +- Recorta las salidas grandes de herramientas en tus flujos de trabajo. - Reduce `agents.defaults.imageMaxDimensionPx` para sesiones con muchas capturas de pantalla. - Mantén breves las descripciones de Skills (la lista de Skills se inyecta en el prompt). -- Prefiere modelos más pequeños para trabajo exploratorio y verboso. +- Prefiere modelos más pequeños para trabajo detallado y exploratorio. Consulta [Skills](/es/tools/skills) para la fórmula exacta de sobrecarga de la lista de Skills.