From 9e1aa4eecedf1512d7d450e9807af4a4dc7735cc Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 21 Apr 2026 19:22:10 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/automation/tasks.md | 180 +++++------ docs/es/channels/synology-chat.md | 95 +++--- docs/es/ci.md | 94 +++--- docs/es/gateway/multiple-gateways.md | 172 ++++++----- docs/es/plugins/manifest.md | 402 +++++++++++++------------ docs/es/plugins/sdk-channel-plugins.md | 393 ++++++++++++------------ docs/es/providers/github-copilot.md | 90 +++--- docs/es/tools/subagents.md | 254 ++++++++-------- docs/es/tools/thinking.md | 128 ++++---- 9 files changed, 900 insertions(+), 908 deletions(-) diff --git a/docs/es/automation/tasks.md b/docs/es/automation/tasks.md index 043c19811..0495c63c1 100644 --- a/docs/es/automation/tasks.md +++ b/docs/es/automation/tasks.md @@ -6,36 +6,36 @@ read_when: summary: Seguimiento de tareas en segundo plano para ejecuciones de ACP, subagentes, trabajos de Cron aislados y operaciones de CLI title: Tareas en segundo plano x-i18n: - generated_at: "2026-04-21T05:12:47Z" + generated_at: "2026-04-21T19:20:30Z" model: gpt-5.4 provider: openai - source_hash: ba5511b1c421bdf505fc7d34f09e453ac44e85213fcb0f082078fa957aa91fe7 + source_hash: a4cd666b3eaffde8df0b5e1533eb337e44a0824824af6f8a240f18a89f71b402 source_path: automation/tasks.md workflow: 15 --- # Tareas en segundo plano -> **¿Buscas programación?** Consulta [Automation & Tasks](/es/automation) para elegir el mecanismo adecuado. Esta página cubre el **seguimiento** del trabajo en segundo plano, no su programación. +> **¿Buscas programación?** Consulta [Automatización y tareas](/es/automation) para elegir el mecanismo adecuado. Esta página cubre el **seguimiento** del trabajo en segundo plano, no su programación. Las tareas en segundo plano hacen seguimiento del trabajo que se ejecuta **fuera de tu sesión principal de conversación**: ejecuciones de ACP, lanzamientos de subagentes, ejecuciones aisladas de trabajos de Cron y operaciones iniciadas por la CLI. -Las tareas **no** sustituyen a las sesiones, los trabajos de Cron ni los Heartbeat; son el **registro de actividad** que deja constancia de qué trabajo desacoplado ocurrió, cuándo ocurrió y si tuvo éxito. +Las tareas **no** reemplazan a las sesiones, los trabajos de Cron ni los Heartbeat — son el **registro de actividad** que deja constancia de qué trabajo desacoplado ocurrió, cuándo y si tuvo éxito. -No todas las ejecuciones de agentes crean una tarea. Los turnos de Heartbeat y el chat interactivo normal no lo hacen. Todas las ejecuciones de Cron, los lanzamientos de ACP, los lanzamientos de subagentes y los comandos de agente desde la CLI sí lo hacen. +No todas las ejecuciones de agentes crean una tarea. Los turnos de Heartbeat y el chat interactivo normal no lo hacen. Todas las ejecuciones de Cron, los lanzamientos de ACP, los lanzamientos de subagentes y los comandos de agente de la CLI sí lo hacen. -## En resumen +## Resumen rápido -- Las tareas son **registros**, no programadores: Cron y Heartbeat deciden _cuándo_ se ejecuta el trabajo; las tareas hacen seguimiento de _lo que ocurrió_. +- Las tareas son **registros**, no programadores: Cron y Heartbeat deciden _cuándo_ se ejecuta el trabajo; las tareas hacen seguimiento de _qué ocurrió_. - ACP, los subagentes, todos los trabajos de Cron y las operaciones de CLI crean tareas. Los turnos de Heartbeat no. - Cada tarea pasa por `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled` o `lost`). -- Las tareas de Cron permanecen activas mientras el entorno de ejecución de Cron siga siendo propietario del trabajo; las tareas de CLI respaldadas por chat permanecen activas solo mientras el contexto de ejecución propietario siga activo. -- La finalización se basa en envío: el trabajo desacoplado puede notificar directamente o reactivar la sesión/Heartbeat solicitante cuando termina, por lo que los bucles de sondeo de estado normalmente no son el enfoque adecuado. -- Las ejecuciones aisladas de Cron y las finalizaciones de subagentes limpian en la medida de lo posible las pestañas/procesos de navegador rastreados para su sesión hija antes de la limpieza contable final. -- La entrega de ejecuciones aisladas de Cron suprime respuestas intermedias obsoletas del padre mientras el trabajo de subagentes descendientes sigue vaciándose, y da preferencia a la salida final descendiente cuando esta llega antes de la entrega. +- Las tareas de Cron permanecen activas mientras el entorno de ejecución de Cron siga siendo propietario del trabajo; las tareas de CLI respaldadas por chat permanecen activas solo mientras su contexto de ejecución propietario siga activo. +- La finalización se basa en envíos: el trabajo desacoplado puede notificar directamente o despertar la sesión/Heartbeat solicitante cuando termina, por lo que los bucles de sondeo de estado normalmente no son el enfoque adecuado. +- Las ejecuciones aisladas de Cron y las finalizaciones de subagentes limpian, en el mejor de los casos, las pestañas/procesos del navegador rastreados para su sesión hija antes de la contabilidad final de limpieza. +- La entrega de Cron aislado suprime las respuestas intermedias obsoletas del padre mientras el trabajo descendiente del subagente aún se está vaciando, y prioriza la salida final descendiente cuando llega antes de la entrega. - Las notificaciones de finalización se entregan directamente a un canal o se ponen en cola para el siguiente Heartbeat. - `openclaw tasks list` muestra todas las tareas; `openclaw tasks audit` muestra los problemas. - Los registros terminales se conservan durante 7 días y luego se eliminan automáticamente. @@ -43,20 +43,20 @@ No todas las ejecuciones de agentes crean una tarea. Los turnos de Heartbeat y e ## Inicio rápido ```bash -# Lista todas las tareas (las más nuevas primero) +# Lista todas las tareas (las más recientes primero) openclaw tasks list # Filtra por entorno de ejecución o estado openclaw tasks list --runtime acp openclaw tasks list --status running -# Muestra los detalles de una tarea específica (por ID, ID de ejecución o clave de sesión) +# Muestra detalles de una tarea específica (por ID, ID de ejecución o clave de sesión) openclaw tasks show # Cancela una tarea en ejecución (mata la sesión hija) openclaw tasks cancel -# Cambia la política de notificación de una tarea +# Cambia la política de notificaciones de una tarea openclaw tasks notify state_changes # Ejecuta una auditoría de estado @@ -74,23 +74,23 @@ openclaw tasks flow cancel ## Qué crea una tarea -| Origen | Tipo de entorno de ejecución | Cuándo se crea un registro de tarea | Política de notificación predeterminada | -| ---------------------- | ---------------------------- | -------------------------------------------------------- | --------------------------------------- | -| Ejecuciones en segundo plano de ACP | `acp` | Al lanzar una sesión hija de ACP | `done_only` | -| Orquestación de subagentes | `subagent` | Al lanzar un subagente mediante `sessions_spawn` | `done_only` | -| Trabajos de Cron (todos los tipos) | `cron` | En cada ejecución de Cron (sesión principal y aislada) | `silent` | -| Operaciones de CLI | `cli` | Comandos `openclaw agent` que se ejecutan por el Gateway | `silent` | -| Trabajos de medios del agente | `cli` | Ejecuciones `video_generate` respaldadas por sesión | `silent` | +| Origen | Tipo de entorno de ejecución | Cuándo se crea un registro de tarea | Política de notificación predeterminada | +| ---------------------- | ---------------------------- | ------------------------------------------------------ | --------------------------------------- | +| Ejecuciones en segundo plano de ACP | `acp` | Al lanzar una sesión hija de ACP | `done_only` | +| Orquestación de subagentes | `subagent` | Al lanzar un subagente mediante `sessions_spawn` | `done_only` | +| Trabajos de Cron (todos los tipos) | `cron` | En cada ejecución de Cron (sesión principal y aislada) | `silent` | +| Operaciones de CLI | `cli` | Comandos `openclaw agent` que se ejecutan a través del Gateway | `silent` | +| Trabajos multimedia del agente | `cli` | Ejecuciones `video_generate` respaldadas por sesión | `silent` | -Las tareas de Cron de la sesión principal usan `silent` como política de notificación predeterminada: crean registros para seguimiento, pero no generan notificaciones. Las tareas de Cron aisladas también usan `silent` de forma predeterminada, pero son más visibles porque se ejecutan en su propia sesión. +Las tareas de Cron de la sesión principal usan la política de notificación `silent` de forma predeterminada: crean registros para seguimiento, pero no generan notificaciones. Las tareas de Cron aisladas también usan `silent` de forma predeterminada, pero son más visibles porque se ejecutan en su propia sesión. -Las ejecuciones `video_generate` respaldadas por sesión también usan `silent` como política de notificación predeterminada. Siguen creando registros de tareas, pero la finalización se devuelve a la sesión original del agente como una reactivación interna para que el agente pueda escribir el mensaje de seguimiento y adjuntar él mismo el video terminado. Si activas `tools.media.asyncCompletion.directSend`, las finalizaciones asíncronas de `music_generate` y `video_generate` intentan primero la entrega directa al canal antes de recurrir a la ruta de reactivación de la sesión solicitante. +Las ejecuciones `video_generate` respaldadas por sesión también usan la política de notificación `silent`. Siguen creando registros de tarea, pero la finalización se devuelve a la sesión original del agente como una activación interna para que el agente pueda escribir el mensaje de seguimiento y adjuntar por sí mismo el video finalizado. Si activas `tools.media.asyncCompletion.directSend`, las finalizaciones asíncronas de `music_generate` y `video_generate` intentan primero la entrega directa al canal antes de recurrir a la ruta de activación de la sesión solicitante. -Mientras una tarea `video_generate` respaldada por sesión sigue activa, la herramienta también actúa como barrera de seguridad: las llamadas repetidas a `video_generate` en esa misma sesión devuelven el estado de la tarea activa en lugar de iniciar una segunda generación simultánea. Usa `action: "status"` cuando quieras una consulta explícita de progreso/estado desde el lado del agente. +Mientras una tarea `video_generate` respaldada por sesión siga activa, la herramienta también actúa como protección: las llamadas repetidas a `video_generate` en esa misma sesión devuelven el estado de la tarea activa en lugar de iniciar una segunda generación concurrente. Usa `action: "status"` cuando quieras una consulta explícita de progreso/estado del lado del agente. **Qué no crea tareas:** -- Turnos de Heartbeat: sesión principal; consulta [Heartbeat](/es/gateway/heartbeat) +- Turnos de Heartbeat — sesión principal; consulta [Heartbeat](/es/gateway/heartbeat) - Turnos normales de chat interactivo - Respuestas directas de `/command` @@ -99,59 +99,59 @@ Mientras una tarea `video_generate` respaldada por sesión sigue activa, la herr ```mermaid stateDiagram-v2 [*] --> queued - queued --> running : el agente comienza - running --> succeeded : completa correctamente + queued --> running : agent starts + running --> succeeded : completes ok running --> failed : error - running --> timed_out : tiempo de espera excedido - running --> cancelled : el operador cancela - queued --> lost : sesión ausente > 5 min - running --> lost : sesión ausente > 5 min + running --> timed_out : timeout exceeded + running --> cancelled : operator cancels + queued --> lost : session gone > 5 min + running --> lost : session gone > 5 min ``` -| Estado | Qué significa | -| ----------- | ------------------------------------------------------------------------- | -| `queued` | Creada, esperando a que el agente comience | -| `running` | El turno del agente se está ejecutando activamente | -| `succeeded` | Finalizó correctamente | -| `failed` | Finalizó con un error | -| `timed_out` | Superó el tiempo de espera configurado | -| `cancelled` | Detenida por el operador mediante `openclaw tasks cancel` | +| Estado | Qué significa | +| ----------- | -------------------------------------------------------------------------- | +| `queued` | Creada, esperando a que el agente inicie | +| `running` | El turno del agente se está ejecutando activamente | +| `succeeded` | Completada correctamente | +| `failed` | Completada con un error | +| `timed_out` | Superó el tiempo de espera configurado | +| `cancelled` | Detenida por el operador mediante `openclaw tasks cancel` | | `lost` | El entorno de ejecución perdió el estado de respaldo autoritativo tras un período de gracia de 5 minutos | -Las transiciones ocurren automáticamente: cuando termina la ejecución del agente asociada, el estado de la tarea se actualiza para reflejarlo. +Las transiciones ocurren automáticamente: cuando finaliza la ejecución del agente asociada, el estado de la tarea se actualiza para coincidir. `lost` depende del entorno de ejecución: -- Tareas de ACP: desaparecieron los metadatos de respaldo de la sesión hija de ACP. +- Tareas de ACP: desaparecieron los metadatos de la sesión hija de ACP de respaldo. - Tareas de subagentes: la sesión hija de respaldo desapareció del almacén del agente de destino. -- Tareas de Cron: el entorno de ejecución de Cron ya no rastrea el trabajo como activo. -- Tareas de CLI: las tareas aisladas de sesión hija usan la sesión hija; las tareas de CLI respaldadas por chat usan en su lugar el contexto de ejecución activo, por lo que las filas persistentes de sesión de canal/grupo/directa no las mantienen activas. +- Tareas de Cron: el entorno de ejecución de Cron ya no registra el trabajo como activo. +- Tareas de CLI: las tareas aisladas de sesión hija usan la sesión hija; las tareas de CLI respaldadas por chat usan en su lugar el contexto de ejecución en vivo, por lo que las filas persistentes de sesión de canal/grupo/directa no las mantienen activas. ## Entrega y notificaciones -Cuando una tarea alcanza un estado terminal, OpenClaw te lo notifica. Hay dos rutas de entrega: +Cuando una tarea alcanza un estado terminal, OpenClaw te notifica. Hay dos rutas de entrega: -**Entrega directa**: si la tarea tiene un destino de canal (el `requesterOrigin`), el mensaje de finalización va directamente a ese canal (Telegram, Discord, Slack, etc.). Para las finalizaciones de subagentes, OpenClaw también conserva el enrutamiento de hilo/tema vinculado cuando está disponible y puede completar un `to` o cuenta ausentes a partir de la ruta almacenada de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de abandonar la entrega directa. +**Entrega directa**: si la tarea tiene un destino de canal (el `requesterOrigin`), el mensaje de finalización va directamente a ese canal (Telegram, Discord, Slack, etc.). Para finalizaciones de subagentes, OpenClaw también conserva el enrutamiento vinculado de hilo/tema cuando está disponible y puede completar un `to` o una cuenta faltantes a partir de la ruta almacenada de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de abandonar la entrega directa. -**Entrega en cola de sesión**: si la entrega directa falla o no se establece un origen, la actualización se pone en cola como un evento del sistema en la sesión del solicitante y aparece en el siguiente Heartbeat. +**Entrega en cola de sesión**: si la entrega directa falla o no se establece ningún origen, la actualización se pone en cola como un evento del sistema en la sesión del solicitante y aparece en el siguiente Heartbeat. -La finalización de una tarea activa una reactivación inmediata de Heartbeat para que veas el resultado rápidamente; no tienes que esperar al siguiente tick programado de Heartbeat. +La finalización de la tarea activa un Heartbeat inmediato para que veas el resultado rápidamente; no tienes que esperar al siguiente tick programado de Heartbeat. -Eso significa que el flujo de trabajo habitual se basa en envío: inicia el trabajo desacoplado una vez y luego deja que el entorno de ejecución te reactive o te notifique al completarse. Sondea el estado de la tarea solo cuando necesites depuración, intervención o una auditoría explícita. +Eso significa que el flujo de trabajo habitual se basa en envíos: inicia el trabajo desacoplado una vez y luego deja que el entorno de ejecución te despierte o notifique al completarse. Sondea el estado de la tarea solo cuando necesites depuración, intervención o una auditoría explícita. ### Políticas de notificación -Controla cuánto quieres saber sobre cada tarea: +Controla cuánto recibes de cada tarea: | Política | Qué se entrega | | --------------------- | ----------------------------------------------------------------------- | -| `done_only` (predeterminada) | Solo el estado terminal (`succeeded`, `failed`, etc.); **esta es la opción predeterminada** | +| `done_only` (predeterminada) | Solo el estado terminal (`succeeded`, `failed`, etc.) — **esta es la opción predeterminada** | | `state_changes` | Cada transición de estado y actualización de progreso | | `silent` | Nada en absoluto | -Cambia la política mientras una tarea está en ejecución: +Cambia la política mientras una tarea se está ejecutando: ```bash openclaw tasks notify state_changes @@ -173,7 +173,7 @@ Columnas de salida: ID de tarea, tipo, estado, entrega, ID de ejecución, sesió openclaw tasks show ``` -El token de búsqueda acepta un ID de tarea, ID de ejecución o clave de sesión. Muestra el registro completo, incluidos tiempo, estado de entrega, error y resumen terminal. +El token de búsqueda acepta un ID de tarea, un ID de ejecución o una clave de sesión. Muestra el registro completo, incluidos el tiempo, el estado de entrega, el error y el resumen terminal. ### `tasks cancel` @@ -181,7 +181,7 @@ El token de búsqueda acepta un ID de tarea, ID de ejecución o clave de sesión openclaw tasks cancel ``` -Para tareas de ACP y subagentes, esto mata la sesión hija. Para tareas rastreadas por CLI, la cancelación se registra en el registro de tareas (no hay un identificador independiente del entorno de ejecución hijo). El estado pasa a `cancelled` y se envía una notificación de entrega cuando corresponde. +Para tareas de ACP y subagentes, esto mata la sesión hija. Para las tareas seguidas por CLI, la cancelación se registra en el registro de tareas (no existe un identificador independiente del entorno de ejecución hijo). El estado pasa a `cancelled` y se envía una notificación de entrega cuando corresponde. ### `tasks notify` @@ -197,14 +197,14 @@ openclaw tasks audit [--json] Muestra problemas operativos. Los hallazgos también aparecen en `openclaw status` cuando se detectan problemas. -| Hallazgo | Severidad | Disparador | -| ------------------------- | --------- | ----------------------------------------------------- | -| `stale_queued` | warn | En cola durante más de 10 minutos | -| `stale_running` | error | En ejecución durante más de 30 minutos | -| `lost` | error | Desapareció la propiedad de la tarea respaldada por el entorno de ejecución | -| `delivery_failed` | warn | La entrega falló y la política de notificación no es `silent` | -| `missing_cleanup` | warn | Tarea terminal sin marca de tiempo de limpieza | -| `inconsistent_timestamps` | warn | Violación de la línea temporal (por ejemplo, terminó antes de empezar) | +| Hallazgo | Severidad | Disparador | +| -------------------------- | --------- | ----------------------------------------------------- | +| `stale_queued` | warn | En cola durante más de 10 minutos | +| `stale_running` | error | En ejecución durante más de 30 minutos | +| `lost` | error | Desapareció la propiedad de la tarea respaldada por el entorno de ejecución | +| `delivery_failed` | warn | La entrega falló y la política de notificación no es `silent` | +| `missing_cleanup` | warn | Tarea terminal sin marca temporal de limpieza | +| `inconsistent_timestamps` | warn | Violación de cronología (por ejemplo, terminó antes de comenzar) | ### `tasks maintenance` @@ -213,20 +213,20 @@ openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` -Usa esto para previsualizar o aplicar conciliación, marcado de limpieza y depuración para las tareas y el estado de Task Flow. +Úsalo para previsualizar o aplicar reconciliación, marcado de limpieza y eliminación para las tareas y el estado de Task Flow. -La conciliación depende del entorno de ejecución: +La reconciliación depende del entorno de ejecución: -- Las tareas de ACP/subagentes verifican su sesión hija de respaldo. -- Las tareas de Cron verifican si el entorno de ejecución de Cron sigue siendo propietario del trabajo. -- Las tareas de CLI respaldadas por chat verifican el contexto de ejecución activo propietario, no solo la fila de sesión de chat. +- Las tareas de ACP/subagentes comprueban su sesión hija de respaldo. +- Las tareas de Cron comprueban si el entorno de ejecución de Cron sigue siendo propietario del trabajo. +- Las tareas de CLI respaldadas por chat comprueban el contexto de ejecución en vivo propietario, no solo la fila de la sesión de chat. -La limpieza de finalización también depende del entorno de ejecución: +La limpieza tras la finalización también depende del entorno de ejecución: -- La finalización de subagentes cierra en la medida de lo posible las pestañas/procesos de navegador rastreados para la sesión hija antes de que continúe la limpieza del anuncio. -- La finalización de Cron aislado cierra en la medida de lo posible las pestañas/procesos de navegador rastreados para la sesión de Cron antes de que la ejecución se desmonte por completo. -- La entrega de Cron aislado espera el seguimiento de subagentes descendientes cuando es necesario y suprime el texto obsoleto de acuse de recibo del padre en lugar de anunciarlo. -- La entrega de finalización de subagentes da preferencia al texto visible más reciente del asistente; si está vacío, recurre al texto sanitizado más reciente de `tool`/`toolResult`, y las ejecuciones de solo llamada a herramienta que terminan por tiempo de espera pueden resumirse en un breve resumen de progreso parcial. +- La finalización de subagentes cierra, en el mejor de los casos, las pestañas/procesos del navegador rastreados para la sesión hija antes de que continúe la limpieza del anuncio. +- La finalización de Cron aislado cierra, en el mejor de los casos, las pestañas/procesos del navegador rastreados para la sesión de Cron antes de que la ejecución se desmonte por completo. +- La entrega de Cron aislado espera, cuando es necesario, el seguimiento descendiente del subagente y suprime el texto obsoleto de confirmación del padre en lugar de anunciarlo. +- La entrega de finalización de subagentes prioriza el texto visible más reciente del asistente; si está vacío, recurre al texto saneado más reciente de tool/toolResult, y las ejecuciones de llamadas de herramientas con solo tiempo de espera pueden reducirse a un breve resumen de progreso parcial. Las ejecuciones terminales fallidas anuncian el estado de fallo sin volver a reproducir el texto de respuesta capturado. - Los errores de limpieza no ocultan el resultado real de la tarea. ### `tasks flow list|show|cancel` @@ -237,14 +237,14 @@ openclaw tasks flow show [--json] openclaw tasks flow cancel ``` -Úsalos cuando lo que te importa es el TaskFlow orquestador y no un registro individual de tarea en segundo plano. +Úsalos cuando lo que te importe sea el Task Flow de orquestación en lugar de un registro individual de tarea en segundo plano. ## Tablero de tareas del chat (`/tasks`) Usa `/tasks` en cualquier sesión de chat para ver las tareas en segundo plano vinculadas a esa sesión. El tablero muestra -tareas activas y completadas recientemente con el entorno de ejecución, estado, tiempo y detalles de progreso o error. +las tareas activas y completadas recientemente con el entorno de ejecución, el estado, el tiempo y el detalle del progreso o del error. -Cuando la sesión actual no tiene tareas vinculadas visibles, `/tasks` recurre a los conteos de tareas locales del agente +Cuando la sesión actual no tiene tareas vinculadas visibles, `/tasks` recurre a los recuentos de tareas locales del agente para que sigas obteniendo una visión general sin filtrar detalles de otras sesiones. Para el registro completo del operador, usa la CLI: `openclaw tasks list`. @@ -263,7 +263,9 @@ El resumen informa: - **failures** — recuento de `failed` + `timed_out` + `lost` - **byRuntime** — desglose por `acp`, `subagent`, `cron`, `cli` -Tanto `/status` como la herramienta `session_status` usan una instantánea de tareas con reconocimiento de limpieza: se da prioridad a las tareas activas, las filas completadas obsoletas se ocultan y los fallos recientes solo aparecen cuando ya no queda trabajo activo. Esto mantiene la tarjeta de estado centrada en lo que importa en este momento. +Tanto `/status` como la herramienta `session_status` usan una instantánea de tareas con reconocimiento de limpieza: se priorizan las tareas activas, +se ocultan las filas completadas obsoletas y los fallos recientes solo aparecen cuando ya no queda trabajo activo. +Esto mantiene la tarjeta de estado centrada en lo que importa ahora mismo. ## Almacenamiento y mantenimiento @@ -275,50 +277,50 @@ Los registros de tareas persisten en SQLite en: $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -El registro se carga en memoria al iniciar el Gateway y sincroniza las escrituras con SQLite para garantizar durabilidad entre reinicios. +El registro se carga en memoria al iniciar el Gateway y sincroniza las escrituras con SQLite para ofrecer durabilidad entre reinicios. ### Mantenimiento automático Un proceso de barrido se ejecuta cada **60 segundos** y gestiona tres cosas: -1. **Conciliación** — comprueba si las tareas activas siguen teniendo un respaldo autoritativo del entorno de ejecución. Las tareas de ACP/subagentes usan el estado de la sesión hija, las tareas de Cron usan la propiedad del trabajo activo y las tareas de CLI respaldadas por chat usan el contexto de ejecución propietario. Si ese estado de respaldo desaparece durante más de 5 minutos, la tarea se marca como `lost`. -2. **Marcado de limpieza** — establece una marca de tiempo `cleanupAfter` en las tareas terminales (`endedAt` + 7 días). -3. **Depuración** — elimina los registros que han superado su fecha `cleanupAfter`. +1. **Reconciliación** — comprueba si las tareas activas siguen teniendo respaldo autoritativo del entorno de ejecución. Las tareas de ACP/subagentes usan el estado de la sesión hija, las tareas de Cron usan la propiedad activa del trabajo y las tareas de CLI respaldadas por chat usan el contexto de ejecución propietario. Si ese estado de respaldo desaparece durante más de 5 minutos, la tarea se marca como `lost`. +2. **Marcado de limpieza** — establece una marca temporal `cleanupAfter` en las tareas terminales (`endedAt` + 7 días). +3. **Eliminación** — borra los registros que han superado su fecha `cleanupAfter`. -**Retención**: los registros de tareas terminales se conservan durante **7 días** y luego se depuran automáticamente. No se necesita configuración. +**Retención**: los registros de tareas terminales se conservan durante **7 días** y luego se eliminan automáticamente. No se necesita configuración. ## Cómo se relacionan las tareas con otros sistemas ### Tareas y TaskFlow -[TaskFlow](/es/automation/taskflow) es la capa de orquestación de flujos por encima de las tareas en segundo plano. Un único flujo puede coordinar varias tareas a lo largo de su ciclo de vida mediante modos de sincronización administrados o reflejados. Usa `openclaw tasks` para inspeccionar registros individuales de tareas y `openclaw tasks flow` para inspeccionar el flujo orquestador. +[TaskFlow](/es/automation/taskflow) es la capa de orquestación de flujos por encima de las tareas en segundo plano. Un único flujo puede coordinar varias tareas durante su ciclo de vida mediante modos de sincronización gestionados o reflejados. Usa `openclaw tasks` para inspeccionar registros individuales de tareas y `openclaw tasks flow` para inspeccionar el flujo de orquestación. Consulta [TaskFlow](/es/automation/taskflow) para más detalles. ### Tareas y Cron -La **definición** de un trabajo de Cron vive en `~/.openclaw/cron/jobs.json`; el estado de ejecución vive junto a ella en `~/.openclaw/cron/jobs-state.json`. **Cada** ejecución de Cron crea un registro de tarea, tanto en la sesión principal como en modo aislado. Las tareas de Cron de la sesión principal usan `silent` como política de notificación predeterminada para hacer seguimiento sin generar notificaciones. +La **definición** de un trabajo de Cron vive en `~/.openclaw/cron/jobs.json`; el estado de ejecución en tiempo de ejecución vive junto a él en `~/.openclaw/cron/jobs-state.json`. **Cada** ejecución de Cron crea un registro de tarea, tanto en la sesión principal como en modo aislado. Las tareas de Cron de la sesión principal usan de forma predeterminada la política de notificación `silent`, por lo que hacen seguimiento sin generar notificaciones. -Consulta [Cron Jobs](/es/automation/cron-jobs). +Consulta [Trabajos de Cron](/es/automation/cron-jobs). ### Tareas y Heartbeat -Las ejecuciones de Heartbeat son turnos de la sesión principal; no crean registros de tareas. Cuando una tarea termina, puede activar una reactivación de Heartbeat para que veas el resultado con rapidez. +Las ejecuciones de Heartbeat son turnos de la sesión principal: no crean registros de tarea. Cuando una tarea se completa, puede activar un Heartbeat para que veas el resultado rápidamente. Consulta [Heartbeat](/es/gateway/heartbeat). ### Tareas y sesiones -Una tarea puede hacer referencia a un `childSessionKey` (donde se ejecuta el trabajo) y a un `requesterSessionKey` (quién lo inició). Las sesiones son el contexto de conversación; las tareas son el seguimiento de actividad por encima de ese contexto. +Una tarea puede hacer referencia a un `childSessionKey` (donde se ejecuta el trabajo) y a un `requesterSessionKey` (quién lo inició). Las sesiones son el contexto de conversación; las tareas son la capa de seguimiento de actividad sobre ese contexto. ### Tareas y ejecuciones de agentes -El `runId` de una tarea enlaza con la ejecución del agente que realiza el trabajo. Los eventos del ciclo de vida del agente (inicio, fin, error) actualizan automáticamente el estado de la tarea; no necesitas gestionar manualmente el ciclo de vida. +El `runId` de una tarea enlaza con la ejecución del agente que realiza el trabajo. Los eventos del ciclo de vida del agente (inicio, finalización, error) actualizan automáticamente el estado de la tarea; no necesitas gestionar el ciclo de vida manualmente. ## Relacionado -- [Automation & Tasks](/es/automation) — todos los mecanismos de automatización de un vistazo +- [Automatización y tareas](/es/automation) — todos los mecanismos de automatización de un vistazo - [TaskFlow](/es/automation/taskflow) — orquestación de flujos por encima de las tareas -- [Scheduled Tasks](/es/automation/cron-jobs) — programación de trabajo en segundo plano +- [Tareas programadas](/es/automation/cron-jobs) — programación de trabajo en segundo plano - [Heartbeat](/es/gateway/heartbeat) — turnos periódicos de la sesión principal -- [CLI: Tasks](/cli/index#tasks) — referencia de comandos de la CLI +- [CLI: Tasks](/cli/index#tasks) — referencia de comandos de CLI diff --git a/docs/es/channels/synology-chat.md b/docs/es/channels/synology-chat.md index 4591e40e8..766009397 100644 --- a/docs/es/channels/synology-chat.md +++ b/docs/es/channels/synology-chat.md @@ -1,38 +1,38 @@ --- read_when: - Configuración de Synology Chat con OpenClaw - - Depuración del enrutamiento de webhooks de Synology Chat -summary: Configuración de webhooks de Synology Chat y configuración de OpenClaw + - Depuración del enrutamiento del Webhook de Synology Chat +summary: Configuración del Webhook de Synology Chat y configuración de OpenClaw title: Synology Chat x-i18n: - generated_at: "2026-04-05T12:36:19Z" + generated_at: "2026-04-21T19:20:29Z" model: gpt-5.4 provider: openai - source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81 + source_hash: 7288e2aa873ee1a1f57861d839cfb44ff324e3d40a7f36da07c6ba43cbe1e6e6 source_path: channels/synology-chat.md workflow: 15 --- # Synology Chat -Estado: canal de mensajes directos de plugin empaquetado que usa webhooks de Synology Chat. -El plugin acepta mensajes entrantes desde webhooks salientes de Synology Chat y envía respuestas -mediante un webhook entrante de Synology Chat. +Estado: plugin incluido de canal de mensajes directos que usa Webhooks de Synology Chat. +El plugin acepta mensajes entrantes desde Webhooks salientes de Synology Chat y envía respuestas +mediante un Webhook entrante de Synology Chat. -## Plugin empaquetado +## Plugin incluido -Synology Chat se incluye como plugin empaquetado en las versiones actuales de OpenClaw, por lo que las compilaciones empaquetadas normales no necesitan una instalación independiente. +Synology Chat se distribuye como un plugin incluido en las versiones actuales de OpenClaw, por lo que las compilaciones empaquetadas normales no necesitan una instalación independiente. -Si usas una compilación antigua o una instalación personalizada que excluye Synology Chat, +Si estás en una compilación más antigua o en una instalación personalizada que excluye Synology Chat, instálalo manualmente: -Instalar desde una copia local: +Instalar desde una copia local del repositorio: ```bash openclaw plugins install ./path/to/local/synology-chat-plugin ``` -Detalles: [Plugins](/tools/plugin) +Detalles: [Plugins](/es/tools/plugin) ## Configuración rápida @@ -42,20 +42,20 @@ Detalles: [Plugins](/tools/plugin) - `openclaw onboard` ahora muestra Synology Chat en la misma lista de configuración de canales que `openclaw channels add`. - Configuración no interactiva: `openclaw channels add --channel synology-chat --token --url ` 2. En las integraciones de Synology Chat: - - Crea un webhook entrante y copia su URL. - - Crea un webhook saliente con tu token secreto. -3. Apunta la URL del webhook saliente a tu gateway de OpenClaw: + - Crea un Webhook entrante y copia su URL. + - Crea un Webhook saliente con tu token secreto. +3. Apunta la URL del Webhook saliente a tu Gateway de OpenClaw: - `https://gateway-host/webhook/synology` de forma predeterminada. - O tu `channels.synology-chat.webhookPath` personalizado. 4. Completa la configuración en OpenClaw. - Guiado: `openclaw onboard` - Directo: `openclaw channels add --channel synology-chat --token --url ` -5. Reinicia el gateway y envía un mensaje directo al bot de Synology Chat. +5. Reinicia el Gateway y envía un MD al bot de Synology Chat. -Detalles de autenticación del webhook: +Detalles de autenticación del Webhook: -- OpenClaw acepta el token del webhook saliente desde `body.token`, luego - `?token=...` y después desde los encabezados. +- OpenClaw acepta el token del Webhook saliente desde `body.token`, luego + `?token=...`, y después desde los encabezados. - Formas de encabezado aceptadas: - `x-synology-token` - `x-webhook-token` @@ -93,16 +93,16 @@ Para la cuenta predeterminada, puedes usar variables de entorno: - `SYNOLOGY_RATE_LIMIT` - `OPENCLAW_BOT_NAME` -Los valores de la configuración prevalecen sobre las variables de entorno. +Los valores de configuración sobrescriben las variables de entorno. -## Política de mensajes directos y control de acceso +## Política de MD y control de acceso - `dmPolicy: "allowlist"` es el valor predeterminado recomendado. - `allowedUserIds` acepta una lista (o una cadena separada por comas) de IDs de usuario de Synology. -- En modo `allowlist`, una lista `allowedUserIds` vacía se trata como una configuración incorrecta y la ruta del webhook no se iniciará (usa `dmPolicy: "open"` para permitir a todos). +- En el modo `allowlist`, una lista vacía de `allowedUserIds` se trata como una mala configuración y la ruta del Webhook no se iniciará (usa `dmPolicy: "open"` para permitir a todos). - `dmPolicy: "open"` permite cualquier remitente. -- `dmPolicy: "disabled"` bloquea los mensajes directos. -- La vinculación del destinatario de respuesta permanece en el `user_id` numérico estable de forma predeterminada. `channels.synology-chat.dangerouslyAllowNameMatching: true` es un modo de compatibilidad de emergencia que vuelve a habilitar la búsqueda mutable por nombre de usuario/apodo para la entrega de respuestas. +- `dmPolicy: "disabled"` bloquea los MD. +- La vinculación del destinatario de la respuesta permanece en `user_id` numérico estable de forma predeterminada. `channels.synology-chat.dangerouslyAllowNameMatching: true` es un modo de compatibilidad de emergencia que vuelve a habilitar la búsqueda por nombre de usuario/apodo mutable para la entrega de respuestas. - Las aprobaciones de emparejamiento funcionan con: - `openclaw pairing list synology-chat` - `openclaw pairing approve synology-chat ` @@ -119,18 +119,19 @@ openclaw message send --channel synology-chat --target synology-chat:123456 --te ``` Los envíos de contenido multimedia son compatibles mediante entrega de archivos basada en URL. +Las URL de archivos salientes deben usar `http` o `https`, y los destinos de red privados u otros destinos bloqueados se rechazan antes de que OpenClaw reenvíe la URL al Webhook del NAS. ## Varias cuentas Se admiten varias cuentas de Synology Chat en `channels.synology-chat.accounts`. -Cada cuenta puede sobrescribir el token, la URL entrante, la ruta del webhook, la política de mensajes directos y los límites. -Las sesiones de mensajes directos se aíslan por cuenta y usuario, por lo que el mismo `user_id` -numérico en dos cuentas distintas de Synology no comparte el estado de la transcripción. -Asigna a cada cuenta habilitada un `webhookPath` distinto. OpenClaw ahora rechaza rutas exactas duplicadas -y se niega a iniciar cuentas con nombre que solo heredan una ruta de webhook compartida en configuraciones de varias cuentas. -Si intencionadamente necesitas la herencia heredada para una cuenta con nombre, establece +Cada cuenta puede sobrescribir token, URL entrante, ruta del Webhook, política de MD y límites. +Las sesiones de mensajes directos se aíslan por cuenta y usuario, por lo que el mismo `user_id` numérico +en dos cuentas distintas de Synology no comparte el estado de la transcripción. +Asigna a cada cuenta habilitada un `webhookPath` distinto. OpenClaw ahora rechaza las rutas exactas duplicadas +y se niega a iniciar cuentas con nombre que solo heredan una ruta de Webhook compartida en configuraciones de varias cuentas. +Si intencionalmente necesitas la herencia heredada para una cuenta con nombre, establece `dangerouslyAllowInheritedWebhookPath: true` en esa cuenta o en `channels.synology-chat`, -pero las rutas exactas duplicadas siguen rechazándose en modo cerrado. Prefiere rutas explícitas por cuenta. +pero las rutas exactas duplicadas siguen rechazándose en modo cerrado. Se prefieren rutas explícitas por cuenta. ```json5 { @@ -159,33 +160,33 @@ pero las rutas exactas duplicadas siguen rechazándose en modo cerrado. Prefiere - Mantén `token` en secreto y rótalo si se filtra. - Mantén `allowInsecureSsl: false` a menos que confíes explícitamente en un certificado local autofirmado del NAS. -- Las solicitudes entrantes de webhook se verifican por token y se limitan por tasa por remitente. -- Las comprobaciones de tokens no válidos usan comparación de secretos en tiempo constante y fallan en modo cerrado. +- Las solicitudes entrantes del Webhook se verifican por token y tienen limitación de tasa por remitente. +- Las comprobaciones de token no válido usan comparación de secretos en tiempo constante y fallan en modo cerrado. - Prefiere `dmPolicy: "allowlist"` para producción. - Mantén `dangerouslyAllowNameMatching` desactivado a menos que necesites explícitamente la entrega de respuestas heredada basada en nombre de usuario. -- Mantén `dangerouslyAllowInheritedWebhookPath` desactivado a menos que aceptes explícitamente el riesgo de enrutamiento por ruta compartida en una configuración de varias cuentas. +- Mantén `dangerouslyAllowInheritedWebhookPath` desactivado a menos que aceptes explícitamente el riesgo de enrutamiento de ruta compartida en una configuración de varias cuentas. -## Resolución de problemas +## Solución de problemas - `Missing required fields (token, user_id, text)`: - - a la carga útil del webhook saliente le falta uno de los campos obligatorios - - si Synology envía el token en los encabezados, asegúrate de que el gateway/proxy conserve esos encabezados + - a la carga útil del Webhook saliente le falta uno de los campos obligatorios + - si Synology envía el token en encabezados, asegúrate de que el Gateway/proxy conserve esos encabezados - `Invalid token`: - - el secreto del webhook saliente no coincide con `channels.synology-chat.token` - - la solicitud está llegando a la cuenta o ruta de webhook incorrecta + - el secreto del Webhook saliente no coincide con `channels.synology-chat.token` + - la solicitud está llegando a la cuenta o ruta de Webhook incorrecta - un proxy inverso eliminó el encabezado del token antes de que la solicitud llegara a OpenClaw - `Rate limit exceeded`: - - demasiados intentos con token no válido desde la misma fuente pueden bloquear temporalmente esa fuente - - los remitentes autenticados también tienen un límite de tasa independiente por usuario + - demasiados intentos de token no válido desde la misma fuente pueden bloquear temporalmente esa fuente + - los remitentes autenticados también tienen un límite de tasa de mensajes independiente por usuario - `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`: - - `dmPolicy="allowlist"` está habilitado, pero no hay usuarios configurados + - `dmPolicy="allowlist"` está habilitado pero no hay usuarios configurados - `User not authorized`: - el `user_id` numérico del remitente no está en `allowedUserIds` ## Relacionado -- [Resumen de canales](/channels) — todos los canales compatibles -- [Pairing](/channels/pairing) — autenticación de mensajes directos y flujo de emparejamiento -- [Grupos](/channels/groups) — comportamiento de chats grupales y control por menciones -- [Enrutamiento de canales](/channels/channel-routing) — enrutamiento de sesiones para mensajes -- [Seguridad](/gateway/security) — modelo de acceso y endurecimiento +- [Channels Overview](/es/channels) — todos los canales compatibles +- [Pairing](/es/channels/pairing) — autenticación de MD y flujo de emparejamiento +- [Groups](/es/channels/groups) — comportamiento del chat grupal y control por menciones +- [Channel Routing](/es/channels/channel-routing) — enrutamiento de sesiones para mensajes +- [Security](/es/gateway/security) — modelo de acceso y refuerzo de seguridad diff --git a/docs/es/ci.md b/docs/es/ci.md index 63738f07c..6b0bdbc91 100644 --- a/docs/es/ci.md +++ b/docs/es/ci.md @@ -1,89 +1,89 @@ --- read_when: - Necesitas entender por qué un trabajo de CI se ejecutó o no se ejecutó - - Estás depurando comprobaciones fallidas de GitHub Actions -summary: Grafo de trabajos de CI, compuertas por alcance y equivalentes de comandos locales + - Estás depurando verificaciones fallidas de GitHub Actions +summary: Gráfico de trabajos de CI, compuertas de alcance y equivalentes de comandos locales title: Canalización de CI x-i18n: - generated_at: "2026-04-21T05:13:26Z" + generated_at: "2026-04-21T19:20:30Z" model: gpt-5.4 provider: openai - source_hash: 88a98d777fd61be1603417b71779aaf42a24d602b2437ad549f0075f22494cec + source_hash: 4d01a178402976cdf7c3c864695e8a12d3f7d1d069a77ea1b02a8aef2a3497f7 source_path: ci.md workflow: 15 --- # Canalización de CI -La CI se ejecuta en cada push a `main` y en cada pull request. Usa alcance inteligente para omitir trabajos costosos cuando solo cambiaron áreas no relacionadas. +La CI se ejecuta en cada push a `main` y en cada pull request. Usa un alcance inteligente para omitir trabajos costosos cuando solo cambiaron áreas no relacionadas. ## Resumen de trabajos -| Trabajo | Propósito | Cuándo se ejecuta | -| -------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Detectar cambios solo en docs, alcances cambiados, extensiones cambiadas y construir el manifiesto de CI | Siempre en pushes y PR no borrador | -| `security-scm-fast` | Detección de claves privadas y auditoría de workflows mediante `zizmor` | Siempre en pushes y PR no borrador | -| `security-dependency-audit` | Auditoría sin dependencias del lockfile de producción contra avisos de npm | Siempre en pushes y PR no borrador | -| `security-fast` | Agregado requerido para los trabajos rápidos de seguridad | Siempre en pushes y PR no borrador | -| `build-artifacts` | Construir `dist/` y la UI de Control una vez, subir artifacts reutilizables para trabajos descendientes | Cambios relevantes para Node | -| `checks-fast-core` | Carriles rápidos de corrección en Linux, como verificaciones de bundled/plugin-contract/protocol | Cambios relevantes para Node | -| `checks-fast-contracts-channels` | Verificaciones fragmentadas de contratos de canales con un resultado agregado estable | Cambios relevantes para Node | -| `checks-node-extensions` | Fragmentos completos de pruebas de bundled-plugin en toda la suite de extensiones | Cambios relevantes para Node | -| `checks-node-core-test` | Fragmentos de pruebas Node del núcleo, excluyendo carriles de canales, bundled, contratos y extensiones | Cambios relevantes para Node | -| `extension-fast` | Pruebas focalizadas solo para los bundled plugins cambiados | Cuando se detectan cambios en extensiones | -| `check` | Equivalente principal fragmentado de la compuerta local: tipos prod, lint, guardas, tipos de prueba y smoke estricto | Cambios relevantes para Node | -| `check-additional` | Guardas de arquitectura, límites, superficie de extensiones, límites de paquetes y fragmentos de gateway-watch | Cambios relevantes para Node | -| `build-smoke` | Pruebas smoke del CLI construido y smoke de memoria al inicio | Cambios relevantes para Node | -| `checks` | Carriles restantes de Linux Node: pruebas de canales y compatibilidad Node 22 solo para push | Cambios relevantes para Node | -| `check-docs` | Formato, lint y verificación de enlaces rotos de docs | Cuando cambian las docs | +| Trabajo | Propósito | Cuándo se ejecuta | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | +| `preflight` | Detectar cambios solo en docs, alcances modificados, extensiones modificadas y construir el manifiesto de CI | Siempre en pushes y PRs que no sean borradores | +| `security-scm-fast` | Detección de claves privadas y auditoría de workflows mediante `zizmor` | Siempre en pushes y PRs que no sean borradores | +| `security-dependency-audit` | Auditoría del lockfile de producción sin dependencias frente a avisos de npm | Siempre en pushes y PRs que no sean borradores | +| `security-fast` | Agregado obligatorio para los trabajos rápidos de seguridad | Siempre en pushes y PRs que no sean borradores | +| `build-artifacts` | Compilar `dist/` y la interfaz de usuario de Control una vez, y subir artefactos reutilizables para trabajos posteriores | Cambios relevantes para Node | +| `checks-fast-core` | Carriles rápidos de corrección en Linux, como comprobaciones de bundled/plugin-contract/protocol | Cambios relevantes para Node | +| `checks-fast-contracts-channels` | Comprobaciones fragmentadas de contratos de canal con un resultado de comprobación agregado estable | Cambios relevantes para Node | +| `checks-node-extensions` | Fragmentos completos de pruebas de bundled-plugin en toda la suite de extensiones | Cambios relevantes para Node | +| `checks-node-core-test` | Fragmentos de pruebas del núcleo de Node, excluyendo carriles de canales, bundled, contratos y extensiones | Cambios relevantes para Node | +| `extension-fast` | Pruebas focalizadas solo para los plugins empaquetados modificados | Cuando se detectan cambios en extensiones | +| `check` | Equivalente fragmentado de la compuerta principal local: tipos de prod, lint, guardas, tipos de prueba y smoke estricto | Cambios relevantes para Node | +| `check-additional` | Guardas de arquitectura, límites, superficie de extensiones, límites de paquetes y fragmentos de gateway-watch | Cambios relevantes para Node | +| `build-smoke` | Pruebas smoke del CLI compilado y smoke de memoria al inicio | Cambios relevantes para Node | +| `checks` | Carriles restantes de Linux Node: pruebas de canales y compatibilidad con Node 22 solo en push | Cambios relevantes para Node | +| `check-docs` | Formato de docs, lint y comprobaciones de enlaces rotos | Cuando cambian las docs | | `skills-python` | Ruff + pytest para Skills respaldadas por Python | Cambios relevantes para Skills de Python | -| `checks-windows` | Carriles de prueba específicos de Windows | Cambios relevantes para Windows | -| `macos-node` | Carril de pruebas TypeScript en macOS usando los artifacts compartidos ya construidos | Cambios relevantes para macOS | -| `macos-swift` | Lint, compilación y pruebas Swift para la app de macOS | Cambios relevantes para macOS | -| `android` | Matriz de compilación y pruebas de Android | Cambios relevantes para Android | +| `checks-windows` | Carriles de prueba específicos de Windows | Cambios relevantes para Windows | +| `macos-node` | Carril de pruebas de TypeScript en macOS usando los artefactos compilados compartidos | Cambios relevantes para macOS | +| `macos-swift` | Lint, compilación y pruebas de Swift para la app de macOS | Cambios relevantes para macOS | +| `android` | Matriz de compilación y pruebas de Android | Cambios relevantes para Android | ## Orden de fallo rápido -Los trabajos se ordenan para que las verificaciones baratas fallen antes de que se ejecuten las costosas: +Los trabajos están ordenados para que las comprobaciones baratas fallen antes de que se ejecuten las costosas: 1. `preflight` decide qué carriles existen en absoluto. La lógica `docs-scope` y `changed-scope` son pasos dentro de este trabajo, no trabajos independientes. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` y `skills-python` fallan rápido sin esperar a los trabajos más pesados de artifacts y matrices de plataforma. -3. `build-artifacts` se superpone con los carriles rápidos de Linux para que los consumidores descendientes puedan empezar en cuanto la compilación compartida esté lista. -4. Después se expanden los carriles más pesados de plataforma y runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` y `android`. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` y `skills-python` fallan rápido sin esperar a los trabajos más pesados de artefactos y matrices de plataforma. +3. `build-artifacts` se superpone con los carriles rápidos de Linux para que los consumidores posteriores puedan comenzar en cuanto la compilación compartida esté lista. +4. Después de eso, los carriles más pesados de plataforma y runtime se expanden: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` y `android`. -La lógica de alcance vive en `scripts/ci-changed-scope.mjs` y está cubierta por pruebas unitarias en `src/scripts/ci-changed-scope.test.ts`. -El workflow separado `install-smoke` reutiliza el mismo script de alcance mediante su propio trabajo `preflight`. Calcula `run_install_smoke` a partir de la señal más acotada changed-smoke, por lo que el smoke de Docker/install solo se ejecuta para cambios relevantes de instalación, empaquetado y contenedores. +La lógica de alcance está en `scripts/ci-changed-scope.mjs` y está cubierta por pruebas unitarias en `src/scripts/ci-changed-scope.test.ts`. +El workflow separado `install-smoke` reutiliza el mismo script de alcance mediante su propio trabajo `preflight`. Calcula `run_install_smoke` a partir de la señal más limitada changed-smoke, por lo que el smoke de Docker/install solo se ejecuta para cambios relevantes de instalación, empaquetado y contenedores. -La lógica local de carriles cambiados vive en `scripts/changed-lanes.mjs` y la ejecuta `scripts/check-changed.mjs`. Esa compuerta local es más estricta con los límites de arquitectura que el alcance amplio de plataforma de CI: los cambios de producción del núcleo ejecutan typecheck prod del núcleo más pruebas del núcleo, los cambios solo en pruebas del núcleo ejecutan solo typecheck/pruebas del núcleo, los cambios de producción de extensiones ejecutan typecheck prod de extensiones más pruebas de extensiones, y los cambios solo en pruebas de extensiones ejecutan solo typecheck/pruebas de extensiones. Los cambios en el Plugin SDK público o en plugin-contract amplían la validación a extensiones porque las extensiones dependen de esos contratos del núcleo. Los cambios desconocidos en raíz/config fallan de forma segura hacia todos los carriles. +La lógica local de carriles modificados está en `scripts/changed-lanes.mjs` y es ejecutada por `scripts/check-changed.mjs`. Esa compuerta local es más estricta respecto a los límites de arquitectura que el amplio alcance de plataformas de CI: los cambios de producción del núcleo ejecutan typecheck de prod del núcleo más pruebas del núcleo, los cambios solo en pruebas del núcleo ejecutan solo typecheck/pruebas del núcleo, los cambios de producción de extensiones ejecutan typecheck de prod de extensiones más pruebas de extensiones, y los cambios solo en pruebas de extensiones ejecutan solo typecheck/pruebas de extensiones. Los cambios en el SDK público de Plugin o en plugin-contract amplían la validación a extensiones porque las extensiones dependen de esos contratos del núcleo. Los cambios desconocidos en raíz/config fallan de forma segura hacia todos los carriles. -En los pushes, la matriz `checks` agrega el carril `compat-node22`, solo para push. En los pull requests, ese carril se omite y la matriz se mantiene enfocada en los carriles normales de prueba/canales. +En los pushes, la matriz `checks` agrega el carril `compat-node22`, que solo se ejecuta en push. En pull requests, ese carril se omite y la matriz se mantiene enfocada en los carriles normales de pruebas/canales. -Las familias de pruebas Node más lentas se dividen en fragmentos por archivos incluidos para que cada trabajo siga siendo pequeño: los contratos de canales dividen la cobertura de registro y núcleo en ocho fragmentos ponderados cada uno, las pruebas del comando de respuesta de auto-reply se dividen en cuatro fragmentos por patrón de inclusión, y los demás grupos grandes de prefijos de respuesta de auto-reply se dividen en dos fragmentos cada uno. `check-additional` también separa el trabajo de compilación/canary de límites de paquetes del trabajo de topología de runtime de gateway/architecture. +Las familias de pruebas de Node más lentas se dividen en fragmentos por archivos incluidos para que cada trabajo siga siendo pequeño: los contratos de canal dividen la cobertura de registro y núcleo en ocho fragmentos ponderados cada uno, las pruebas de comandos de respuesta de auto-reply se dividen en cuatro fragmentos por patrón de inclusión, y los otros grupos grandes de prefijos de respuesta de auto-reply se dividen en dos fragmentos cada uno. `check-additional` también separa el trabajo de compilación/canary de límites de paquetes del trabajo de topología de runtime de gateway/arquitectura. -GitHub puede marcar trabajos reemplazados como `cancelled` cuando llega un push más nuevo al mismo PR o ref `main`. Trátalo como ruido de CI, a menos que la ejecución más reciente para la misma ref también esté fallando. Las verificaciones agregadas de fragmentos destacan explícitamente este caso de cancelación para que sea más fácil distinguirlo de un fallo de prueba. +GitHub puede marcar trabajos reemplazados como `cancelled` cuando llega un push más reciente al mismo PR o a la referencia `main`. Trátalo como ruido de CI a menos que la ejecución más reciente para la misma referencia también esté fallando. Las comprobaciones agregadas de fragmentos señalan este caso de cancelación explícitamente para que sea más fácil distinguirlo de un fallo de prueba. ## Runners | Runner | Trabajos | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, verificaciones de Linux, verificaciones de docs, Skills de Python, `android` | -| `blacksmith-32vcpu-windows-2025` | `checks-windows` | -| `macos-latest` | `macos-node`, `macos-swift` | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, comprobaciones de Linux, comprobaciones de docs, Skills de Python, `android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` en `openclaw/openclaw`; los forks vuelven a `macos-latest` | ## Equivalentes locales ```bash -pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD -pnpm check:changed # smart local gate: changed typecheck/lint/tests by boundary lane -pnpm check # fast local gate: production tsgo + sharded lint + parallel fast guards +pnpm changed:lanes # inspecciona el clasificador local de carriles modificados para origin/main...HEAD +pnpm check:changed # compuerta local inteligente: typecheck/lint/pruebas modificados por carril de límite +pnpm check # compuerta local rápida: tsgo de producción + lint fragmentado + guardas rápidas en paralelo pnpm check:test-types -pnpm check:timed # same gate with per-stage timings +pnpm check:timed # la misma compuerta con tiempos por etapa pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression -pnpm test # vitest tests +pnpm test # pruebas de vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # docs format + lint + broken links -pnpm build # build dist when CI artifact/build-smoke lanes matter +pnpm check:docs # formato de docs + lint + enlaces rotos +pnpm build # compila dist cuando importan los carriles de artefactos/`build-smoke` de CI ``` diff --git a/docs/es/gateway/multiple-gateways.md b/docs/es/gateway/multiple-gateways.md index bcc960b0c..4007e43e5 100644 --- a/docs/es/gateway/multiple-gateways.md +++ b/docs/es/gateway/multiple-gateways.md @@ -2,92 +2,44 @@ read_when: - Ejecutar más de un Gateway en la misma máquina - Necesita configuración/estado/puertos aislados por Gateway -summary: Ejecutar múltiples Gateways de OpenClaw en un solo host (aislamiento, puertos y perfiles) -title: Múltiples Gateways +summary: Ejecutar varios Gateways de OpenClaw en un solo host (aislamiento, puertos y perfiles) +title: Varios Gateways x-i18n: - generated_at: "2026-04-21T17:45:43Z" + generated_at: "2026-04-21T19:20:30Z" model: gpt-5.4 provider: openai - source_hash: 8c3fcb921bc6596040e9249467964bd9dcd40ea7c16e958bb378247b0f994a7b + source_hash: 36796da339d5baea1704a7f42530030ea6ef4fa4bde43452ffec946b917ed4a3 source_path: gateway/multiple-gateways.md workflow: 15 --- -# Múltiples Gateways (mismo host) +# Varios Gateways (mismo host) -La mayoría de las configuraciones deberían usar un solo Gateway porque un único Gateway puede gestionar múltiples conexiones de mensajería y agentes. Si necesita un aislamiento o redundancia más sólidos (por ejemplo, un bot de rescate), ejecute Gateways separados con perfiles y puertos aislados. +La mayoría de las configuraciones deberían usar un solo Gateway porque un único Gateway puede gestionar varias conexiones de mensajería y agentes. Si necesita un aislamiento más fuerte o redundancia (por ejemplo, un bot de rescate), ejecute Gateways separados con perfiles y puertos aislados. -## Lista de verificación de aislamiento (obligatoria) +## Configuración recomendada principal -- `OPENCLAW_CONFIG_PATH` — archivo de configuración por instancia -- `OPENCLAW_STATE_DIR` — sesiones, credenciales y cachés por instancia -- `agents.defaults.workspace` — raíz de espacio de trabajo por instancia -- `gateway.port` (o `--port`) — único por instancia -- Los puertos derivados (browser/canvas) no deben superponerse +Para la mayoría de los usuarios, la configuración más simple para un bot de rescate es: -Si estos se comparten, tendrá condiciones de carrera en la configuración y conflictos de puertos. +- mantener el bot principal en el perfil predeterminado +- ejecutar el bot de rescate con `--profile rescue` +- usar un bot de Telegram completamente separado para la cuenta de rescate +- mantener el bot de rescate en un puerto base diferente, como `19789` -## Recomendado: use el perfil predeterminado para principal y un perfil con nombre para rescate +Esto mantiene el bot de rescate aislado del bot principal para que pueda depurar o aplicar cambios de configuración si el bot principal deja de funcionar. Deje al menos 20 puertos entre los puertos base para que los puertos derivados de browser/canvas/CDP nunca entren en conflicto. -Los perfiles aplican automáticamente alcance a `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` y agregan sufijos a los nombres de servicio. Para la mayoría de las configuraciones de bot de rescate, mantenga el bot principal en el perfil predeterminado y asigne solo al bot de rescate un perfil con nombre como `rescue`. +## Inicio rápido del bot de rescate + +Use esto como la ruta predeterminada, a menos que tenga una razón de peso para hacer otra cosa: ```bash -# principal (perfil predeterminado) -openclaw setup -openclaw gateway --port 18789 - -# rescate -openclaw --profile rescue setup -openclaw --profile rescue gateway --port 19001 -``` - -Servicios: - -```bash -openclaw gateway install -openclaw --profile rescue gateway install -``` - -Si quiere que ambos Gateways usen perfiles con nombre, eso también funciona, pero no es obligatorio. - -## Guía del bot de rescate - -Configuración recomendada: - -- mantenga el bot principal en el perfil predeterminado -- ejecute el bot de rescate con `--profile rescue` -- use un bot de Telegram completamente independiente para la cuenta de rescate -- mantenga el bot de rescate en un puerto base diferente, como `19001` - -Esto mantiene el bot de rescate aislado del bot principal para que pueda depurar o aplicar cambios de configuración si el bot principal deja de funcionar. Deje al menos 20 puertos entre los puertos base para que los puertos derivados de browser/canvas/CDP nunca colisionen. - -### Canal/cuenta de rescate recomendados - -Para la mayoría de las configuraciones, use un bot de Telegram completamente independiente para el perfil de rescate. - -Por qué Telegram: - -- fácil de mantener solo para operadores -- token e identidad del bot separados -- independiente de la instalación del canal/aplicación del bot principal -- ruta de recuperación simple basada en DM cuando el bot principal no funciona - -La parte importante es la independencia total: cuenta de bot separada, credenciales separadas, perfil de OpenClaw separado, espacio de trabajo separado y puerto separado. - -### Flujo de instalación recomendado - -Use esto como configuración predeterminada a menos que tenga una razón de peso para hacer otra cosa: - -```bash -# Bot principal (perfil predeterminado, puerto 18789) -openclaw onboard -openclaw gateway install - -# Bot de rescate (bot de Telegram separado, perfil separado, puerto 19001) +# Bot de rescate (bot de Telegram separado, perfil separado, puerto 19789) openclaw --profile rescue onboard -openclaw --profile rescue gateway install +openclaw --profile rescue gateway install --port 19789 ``` +Si su bot principal ya está en ejecución, normalmente eso es todo lo que necesita. + Durante `openclaw --profile rescue onboard`: - use el token del bot de Telegram separado @@ -95,9 +47,26 @@ Durante `openclaw --profile rescue onboard`: - use un puerto base al menos 20 superior al del bot principal - acepte el espacio de trabajo de rescate predeterminado, a menos que ya gestione uno usted mismo -Si el onboarding ya instaló el servicio de rescate por usted, el `gateway install` final no es necesario. +Si el onboarding ya instaló el servicio de rescate por usted, el comando final `gateway install` no es necesario. -### Qué cambia el onboarding +## Por qué esto funciona + +El bot de rescate se mantiene independiente porque tiene su propio: + +- perfil/configuración +- directorio de estado +- espacio de trabajo +- puerto base (más los puertos derivados) +- token del bot de Telegram + +Para la mayoría de las configuraciones, use un bot de Telegram completamente separado para el perfil de rescate: + +- fácil de mantener solo para operadores +- token e identidad del bot separados +- independiente de la instalación del canal/app del bot principal +- ruta de recuperación simple basada en DM cuando el bot principal está roto + +## Qué cambia `--profile rescue onboard` `openclaw --profile rescue onboard` usa el flujo de onboarding normal, pero escribe todo en un perfil separado. @@ -110,20 +79,67 @@ En la práctica, eso significa que el bot de rescate obtiene su propio: Por lo demás, las indicaciones son las mismas que en el onboarding normal. +## Configuración general de varios Gateways + +La distribución del bot de rescate anterior es la opción predeterminada más sencilla, pero el mismo patrón de aislamiento funciona para cualquier par o grupo de Gateways en un mismo host. + +Para una configuración más general, dé a cada Gateway adicional su propio perfil con nombre y su propio puerto base: + +```bash +# principal (perfil predeterminado) +openclaw setup +openclaw gateway --port 18789 + +# gateway adicional +openclaw --profile ops setup +openclaw --profile ops gateway --port 19789 +``` + +Si quiere que ambos Gateways usen perfiles con nombre, eso también funciona: + +```bash +openclaw --profile main setup +openclaw --profile main gateway --port 18789 + +openclaw --profile ops setup +openclaw --profile ops gateway --port 19789 +``` + +Los servicios siguen el mismo patrón: + +```bash +openclaw gateway install +openclaw --profile ops gateway install --port 19789 +``` + +Use el inicio rápido del bot de rescate cuando quiera una vía de operador de respaldo. Use el patrón general de perfiles cuando quiera varios Gateways persistentes para distintos canales, tenants, espacios de trabajo o funciones operativas. + +## Lista de verificación de aislamiento + +Mantenga estos elementos únicos para cada instancia de Gateway: + +- `OPENCLAW_CONFIG_PATH` — archivo de configuración por instancia +- `OPENCLAW_STATE_DIR` — sesiones, credenciales y cachés por instancia +- `agents.defaults.workspace` — raíz del espacio de trabajo por instancia +- `gateway.port` (o `--port`) — único por instancia +- puertos derivados de browser/canvas/CDP + +Si estos se comparten, tendrá condiciones de carrera de configuración y conflictos de puertos. + ## Asignación de puertos (derivados) Puerto base = `gateway.port` (o `OPENCLAW_GATEWAY_PORT` / `--port`). -- puerto del servicio de control del browser = base + 2 (solo loopback) +- puerto del servicio de control del navegador = base + 2 (solo loopback local) - el host de canvas se sirve en el servidor HTTP del Gateway (mismo puerto que `gateway.port`) -- los puertos CDP del perfil de browser se asignan automáticamente desde `browser.controlPort + 9 .. + 108` +- los puertos CDP del perfil del navegador se asignan automáticamente desde `browser.controlPort + 9 .. + 108` -Si sustituye cualquiera de estos en la configuración o el entorno, debe mantenerlos únicos por instancia. +Si sobrescribe cualquiera de estos en la configuración o en variables de entorno, debe mantenerlos únicos por instancia. ## Notas sobre browser/CDP (error común) -- **No** fije `browser.cdpUrl` a los mismos valores en múltiples instancias. -- Cada instancia necesita su propio puerto de control de browser y rango de CDP (derivado de su puerto de gateway). +- **No** fije `browser.cdpUrl` a los mismos valores en varias instancias. +- Cada instancia necesita su propio puerto de control del navegador y su propio rango de CDP (derivado de su puerto de Gateway). - Si necesita puertos CDP explícitos, configure `browser.profiles..cdpPort` por instancia. - Chrome remoto: use `browser.profiles..cdpUrl` (por perfil, por instancia). @@ -136,10 +152,10 @@ openclaw gateway --port 18789 OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \ OPENCLAW_STATE_DIR=~/.openclaw-rescue \ -openclaw gateway --port 19001 +openclaw gateway --port 19789 ``` -## Verificaciones rápidas +## Comprobaciones rápidas ```bash openclaw gateway status --deep @@ -153,4 +169,4 @@ openclaw --profile rescue browser status Interpretación: - `gateway status --deep` ayuda a detectar servicios launchd/systemd/schtasks obsoletos de instalaciones anteriores. -- El texto de advertencia de `gateway probe`, como `multiple reachable gateways detected`, es esperable solo cuando ejecuta intencionalmente más de un gateway aislado. +- El texto de advertencia de `gateway probe`, como `multiple reachable gateways detected`, es esperado solo cuando ejecuta intencionalmente más de un gateway aislado. diff --git a/docs/es/plugins/manifest.md b/docs/es/plugins/manifest.md index 5a6e9dad7..3892aac4f 100644 --- a/docs/es/plugins/manifest.md +++ b/docs/es/plugins/manifest.md @@ -1,38 +1,38 @@ --- read_when: - - Estás creando un Plugin de OpenClaw - - Necesitas entregar un esquema de configuración del plugin o depurar errores de validación del plugin -summary: Requisitos del manifiesto del Plugin + esquema JSON (validación estricta de la configuración) -title: Manifiesto del Plugin + - Estás creando un plugin de OpenClaw + - Necesitas enviar un esquema de configuración del plugin o depurar errores de validación del plugin +summary: Requisitos del manifiesto de Plugin + esquema JSON (validación estricta de configuración) +title: Manifiesto de Plugin x-i18n: - generated_at: "2026-04-19T01:11:08Z" + generated_at: "2026-04-21T19:20:33Z" model: gpt-5.4 provider: openai - source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181 + source_hash: 304c08035724dfb1ce6349972729b621aafc00880d4d259db78c22b86e9056ba source_path: plugins/manifest.md workflow: 15 --- -# Manifiesto del Plugin (`openclaw.plugin.json`) +# Manifiesto de Plugin (`openclaw.plugin.json`) -Esta página es solo para el **manifiesto nativo de Plugin de OpenClaw**. +Esta página es solo para el **manifiesto nativo de plugin de OpenClaw**. -Para diseños de paquetes compatibles, consulta [Plugin bundles](/es/plugins/bundles). +Para diseños de paquetes compatibles, consulta [Paquetes de Plugin](/es/plugins/bundles). -Los formatos de paquete compatibles usan archivos de manifiesto distintos: +Los formatos de paquetes compatibles usan archivos de manifiesto distintos: -- Paquete de Codex: `.codex-plugin/plugin.json` -- Paquete de Claude: `.claude-plugin/plugin.json` o el diseño predeterminado de componentes de Claude sin un manifiesto -- Paquete de Cursor: `.cursor-plugin/plugin.json` +- Paquete Codex: `.codex-plugin/plugin.json` +- Paquete Claude: `.claude-plugin/plugin.json` o el diseño de componentes predeterminado 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í. +OpenClaw también detecta automáticamente esos diseños de paquetes, pero no se validan con el esquema `openclaw.plugin.json` descrito aquí. -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 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 OpenClaw. +Para los paquetes compatibles, OpenClaw actualmente lee los metadatos del paquete junto con las raíces de skill 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 de tiempo de ejecución de OpenClaw. -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 no válidos se tratan como errores del plugin y bloquean la validación de la configuración. +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 no válidos se tratan como errores del plugin y bloquean la validación de configuración. Consulta la guía completa del sistema de plugins: [Plugins](/es/tools/plugin). -Para el modelo de capacidades nativo y la guía actual de compatibilidad externa: +Para el modelo nativo de capacidades y la guía actual de compatibilidad externa: [Modelo de capacidades](/es/plugins/architecture#public-capability-model). ## Qué hace este archivo @@ -42,24 +42,24 @@ Para el modelo de capacidades nativo y la guía actual de compatibilidad externa Úsalo para: - identidad del plugin -- validación de la configuración -- metadatos de autenticación e incorporación que deben estar disponibles sin iniciar el runtime del plugin -- pistas de activación ligeras que las superficies del plano de control pueden inspeccionar antes de que se cargue el runtime -- descriptores de configuración ligeros que las superficies de configuración/incorporación pueden inspeccionar antes de que se cargue el runtime -- metadatos de alias y autoactivación que deben resolverse antes de que se cargue el runtime del plugin -- metadatos abreviados de propiedad de familias de modelos que deben autoactivar el plugin antes de que se cargue el runtime -- instantáneas estáticas de propiedad de capacidades usadas para el cableado de compatibilidad empaquetado y la cobertura de contratos -- metadatos ligeros del ejecutor de QA que el host compartido `openclaw qa` puede inspeccionar antes de que se cargue el runtime del plugin -- metadatos de configuración específicos del canal que deben fusionarse en las superficies de catálogo y validación sin cargar el runtime -- pistas de IU para la configuración +- validación de configuración +- metadatos de autenticación e incorporación que deben estar disponibles sin iniciar el tiempo de ejecución del plugin +- indicios de activación ligeros que las superficies del plano de control pueden inspeccionar antes de que se cargue el tiempo de ejecución +- descriptores de configuración ligeros que las superficies de configuración/incorporación pueden inspeccionar antes de que se cargue el tiempo de ejecución +- metadatos de alias y autoactivación que deben resolverse antes de que se cargue el tiempo de ejecución del plugin +- metadatos abreviados de pertenencia de familias de modelos que deben autoactivar el plugin antes de que se cargue el tiempo de ejecución +- instantáneas estáticas de pertenencia de capacidades usadas para el cableado de compatibilidad incluido y la cobertura de contratos +- metadatos ligeros del ejecutor de QA que el host compartido `openclaw qa` puede inspeccionar antes de que se cargue el tiempo de ejecución del plugin +- metadatos de configuración específicos del canal que deben integrarse en las superficies de catálogo y validación sin cargar el tiempo de ejecución +- indicios de UI para configuración No lo uses para: -- registrar comportamiento en runtime -- declarar puntos de entrada del código +- registrar comportamiento en tiempo de ejecución +- 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`. +Eso corresponde a tu código del plugin y a `package.json`. ## Ejemplo mínimo @@ -139,64 +139,64 @@ 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 en línea para la configuración de este plugin. | -| `enabledByDefault` | No | `true` | Marca un plugin empaquetado 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 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 exclusivo de plugin 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. | -| `providerEndpoints` | No | `object[]` | Metadatos de host/baseUrl de endpoints, propiedad del manifiesto, para rutas de proveedores que el núcleo debe clasificar antes de que se cargue el runtime del proveedor. | -| `cliBackends` | No | `string[]` | IDs de backends de inferencia de CLI propiedad de este plugin. Se usan para la autoactivación al inicio a partir de referencias explícitas de configuración. | -| `syntheticAuthRefs` | No | `string[]` | Referencias de proveedor o backend de CLI cuyo hook de autenticación sintética, propiedad del plugin, debe sondearse durante el descubrimiento en frío de modelos antes de que se cargue el runtime. | -| `nonSecretAuthMarkers` | No | `string[]` | Valores de marcador de clave API, propiedad del plugin empaquetado, que representan un estado de credenciales no secretas local, OAuth o ambiental. | -| `commandAliases` | No | `object[]` | Nombres de comandos propiedad de este plugin que deben generar diagnósticos de configuración y CLI conscientes del plugin antes de que se cargue el runtime. | -| `providerAuthEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno para autenticación del proveedor que OpenClaw puede inspeccionar sin cargar el 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 código 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 env 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 proveedor preferido y conexión simple de flags de CLI. | -| `activation` | No | `object` | Pistas ligeras de activación para carga disparada por proveedor, comando, canal, ruta y capacidad. Solo metadatos; el runtime del plugin sigue siendo propietario 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. | -| `qaRunners` | No | `object[]` | Descriptores ligeros de ejecutores de QA usados por el host compartido `openclaw qa` antes de que se cargue el runtime del plugin. | -| `contracts` | No | `object` | Instantánea estática de capacidades empaquetadas para propiedad de speech, transcripción en tiempo real, voz en tiempo real, media-understanding, generación de imágenes, generación de música, generación de video, web-fetch, búsqueda web y 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 breve que se muestra en las superficies del plugin. | -| `version` | No | `string` | Versión informativa del plugin. | -| `uiHints` | No | `Record` | Etiquetas de IU, marcadores de posición y pistas de sensibilidad para campos de configuración. | +| 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 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 de plugin. | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | IDs de proveedor que deben autohabilitar 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 familias de modelos, propiedad del manifiesto, usados para autocargar el plugin antes del tiempo de ejecución. | +| `providerEndpoints` | No | `object[]` | Metadatos de host/baseUrl de endpoints, propiedad del manifiesto, para rutas de proveedor que el núcleo debe clasificar antes de que se cargue el tiempo de ejecución del proveedor. | +| `cliBackends` | No | `string[]` | IDs de backends de inferencia de CLI propiedad de este plugin. Se usan para autoactivación al inicio a partir de referencias explícitas de configuración. | +| `syntheticAuthRefs` | No | `string[]` | Referencias de proveedor o backend de CLI cuyo hook de autenticación sintética, propiedad del plugin, debe sondearse durante el descubrimiento en frío de modelos antes de que se cargue el tiempo de ejecución. | +| `nonSecretAuthMarkers` | No | `string[]` | Valores de marcador de clave API, propiedad de plugins incluidos, que representan estado no secreto de credenciales locales, OAuth o ambientales. | +| `commandAliases` | No | `object[]` | Nombres de comando propiedad de este plugin que deben producir diagnósticos de configuración y CLI conscientes del plugin antes de que se cargue el tiempo de ejecución. | +| `providerAuthEnvVars` | No | `Record` | Metadatos ligeros de variables de entorno de autenticación de proveedor que OpenClaw puede inspeccionar sin cargar código del plugin. | +| `providerAuthAliases` | No | `Record` | IDs de proveedor que deben reutilizar otro ID de proveedor para la búsqueda de autenticación; por ejemplo, un proveedor de coding 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 código del plugin. Úsalo para superficies de configuración o autenticación de 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 proveedor preferido y cableado simple de flags de CLI. | +| `activation` | No | `object` | Indicios ligeros de activación para carga desencadenada por proveedor, comando, canal, ruta y capacidad. Solo metadatos; el tiempo de ejecución del plugin sigue siendo el propietario 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 tiempo de ejecución del plugin. | +| `qaRunners` | No | `object[]` | Descriptores ligeros de ejecutores de QA usados por el host compartido `openclaw qa` antes de que se cargue el tiempo de ejecución del plugin. | +| `contracts` | No | `object` | Instantánea estática de capacidades incluidas para speech, transcripción en tiempo real, voz en tiempo real, comprensión de medios, generación de imágenes, generación de música, generación de video, web-fetch, búsqueda web y propiedad de herramientas. | +| `channelConfigs` | No | `Record` | Metadatos de configuración de canal, propiedad del manifiesto, integrados en las superficies de descubrimiento y validación antes de que se cargue el tiempo de ejecución. | +| `skills` | No | `string[]` | Directorios de Skills que se cargarán, relativos a la raíz del plugin. | +| `name` | No | `string` | Nombre legible del plugin. | +| `description` | No | `string` | Resumen breve que se muestra en las superficies del plugin. | +| `version` | No | `string` | Versión informativa del plugin. | +| `uiHints` | No | `Record` | Etiquetas de UI, placeholders e indicios de sensibilidad para 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 tiempo de ejecución 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 despachar. | -| `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 valor de reserva. | -| `choiceHint` | No | `string` | Texto breve de ayuda para el selector. | -| `assistantPriority` | No | `number` | Los valores más bajos se ordenan antes en selectores interactivos guiados por el asistente. | -| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción de los selectores del asistente, pero sigue permitiendo la selección manual por CLI. | -| `deprecatedChoiceIds` | No | `string[]` | IDs heredados de opciones que deben 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 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 la 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 enviará. | +| `choiceId` | Sí | `string` | ID estable de opción de autenticación usado por los flujos de incorporación y CLI. | +| `choiceLabel` | No | `string` | Etiqueta orientada al usuario. Si se omite, OpenClaw usa `choiceId` como valor de respaldo. | +| `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 impulsados por el asistente. | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción de los selectores del asistente, pero sigue permitiendo la selección manual por 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 orientada al usuario para 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"]`. | ## Referencia de `commandAliases` -Usa `commandAliases` cuando un plugin es propietario de un nombre de comando en runtime que los usuarios podrían 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 el código del runtime del plugin. +Usa `commandAliases` cuando un plugin es propietario de un nombre de comando en tiempo de ejecución que los usuarios podrían poner por error en `plugins.allow` o intentar ejecutar como un comando CLI raíz. OpenClaw usa estos metadatos para diagnósticos sin importar código de tiempo de ejecución del plugin. ```json { @@ -210,11 +210,11 @@ Usa `commandAliases` cuando un plugin es propietario de un nombre de comando en } ``` -| 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` @@ -222,26 +222,26 @@ Usa `activation` cuando el plugin puede declarar de forma ligera qué eventos de ## Referencia de `qaRunners` -Usa `qaRunners` cuando un plugin aporta uno o más ejecutores de transporte bajo la raíz compartida `openclaw qa`. Mantén estos metadatos ligeros y estáticos; el runtime del plugin sigue siendo propietario del registro real de CLI a través de una superficie ligera `runtime-api.ts` que exporta `qaRunnerCliRegistrations`. +Usa `qaRunners` cuando un plugin aporta uno o más ejecutores de transporte bajo la raíz compartida `openclaw qa`. Mantén estos metadatos ligeros y estáticos; el tiempo de ejecución del plugin sigue siendo el propietario del registro real de CLI a través de una superficie ligera `runtime-api.ts` que exporta `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Ejecuta la ruta de QA en vivo de Matrix respaldada por Docker contra un homeserver desechable" + "description": "Ejecuta la vía de QA en vivo de Matrix con Docker contra un servidor doméstico desechable" } ] } ``` -| Campo | Obligatorio | Tipo | Qué significa | -| ------------- | ----------- | -------- | ----------------------------------------------------------------- | -| `commandName` | Sí | `string` | Subcomando montado bajo `openclaw qa`, por ejemplo `matrix`. | -| `description` | No | `string` | Texto de ayuda de reserva usado cuando el host compartido necesita un comando stub. | +| Campo | Obligatorio | Tipo | Qué significa | +| ------------- | -------- | -------- | ------------------------------------------------------------------ | +| `commandName` | Sí | `string` | Subcomando montado bajo `openclaw qa`, por ejemplo `matrix`. | +| `description` | No | `string` | Texto de ayuda de respaldo usado cuando el host compartido necesita un comando simulado. | -Este bloque es solo metadatos. No registra comportamiento en runtime y no reemplaza `register(...)`, `setupEntry` ni otros puntos de entrada de runtime/plugin. -Los consumidores actuales lo usan como una pista de reducción antes de una carga más amplia del plugin, por lo que la falta de metadatos de activación normalmente solo afecta al rendimiento; no debería cambiar la corrección mientras sigan existiendo los mecanismos heredados de propiedad del manifiesto. +Este bloque es solo metadatos. No registra comportamiento en tiempo de ejecución y no reemplaza `register(...)`, `setupEntry` ni otros puntos de entrada de runtime/plugin. +Los consumidores actuales lo usan como una pista de reducción antes de una carga más amplia del plugin, por lo que la ausencia de metadatos de activación normalmente solo cuesta rendimiento; no debería cambiar la corrección mientras sigan existiendo los respaldos heredados de pertenencia del manifiesto. ```json { @@ -255,23 +255,23 @@ Los consumidores actuales lo usan como una pista de reducción antes de una carg } ``` -| 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 amplias de capacidad usadas por la planificación de activación del plano de control. | +| Campo | Obligatorio | Tipo | Qué significa | +| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | +| `onProviders` | No | `string[]` | IDs de proveedor que deben activar este plugin cuando se soliciten. | +| `onCommands` | No | `string[]` | IDs de comando que deben activar este plugin. | +| `onChannels` | No | `string[]` | IDs de canal que deben activar este plugin. | +| `onRoutes` | No | `string[]` | Tipos de ruta que deben activar este plugin. | +| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Indicios amplios de capacidad usados por la planificación de activación del plano de control. | Consumidores activos actuales: -- la planificación de CLI activada por comandos recurre al comportamiento heredado de `commandAliases[].cliCommand` o `commandAliases[].name` -- la planificación de configuración/canal activada por canales recurre a la propiedad heredada de `channels[]` cuando faltan metadatos explícitos de activación de canales -- la planificación de configuración/runtime activada por proveedores recurre a la propiedad heredada de `providers[]` y `cliBackends[]` de nivel superior cuando faltan metadatos explícitos de activación de proveedores +- la planificación de CLI activada por comandos usa como respaldo `commandAliases[].cliCommand` o `commandAliases[].name` +- la planificación de configuración/canal activada por canal usa como respaldo la pertenencia heredada `channels[]` cuando faltan metadatos explícitos de activación de canal +- la planificación de configuración/runtime activada por proveedor usa como respaldo la pertenencia heredada `providers[]` y `cliBackends[]` de nivel superior cuando faltan metadatos explícitos de activación de proveedor ## Referencia de `setup` -Usa `setup` cuando las superficies de configuración e incorporación necesiten metadatos ligeros propiedad del plugin antes de que se cargue el runtime. +Usa `setup` cuando las superficies de configuración e incorporación necesiten metadatos ligeros, propiedad del plugin, antes de que se cargue el tiempo de ejecución. ```json { @@ -290,39 +290,39 @@ Usa `setup` cuando las superficies de configuración e incorporación necesiten } ``` -`cliBackends` de nivel superior sigue siendo válido y continúa describiendo backends de inferencia de CLI. `setup.cliBackends` es la superficie descriptora específica de configuración para flujos de plano de control/configuración que deben seguir siendo solo metadatos. +El `cliBackends` de nivel superior sigue siendo válido y continúa describiendo backends de inferencia de CLI. `setup.cliBackends` es la superficie de descriptor específica de configuración para 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 orientada primero por 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 ricos en tiempo de configuración, establece `requiresRuntime: true` y mantén `setup-api` como ruta de ejecución de reserva. +Cuando están presentes, `setup.providers` y `setup.cliBackends` son la superficie preferida, basada primero en descriptores, para la búsqueda de configuración. Si el descriptor solo reduce el plugin candidato y la configuración aún necesita hooks más completos de tiempo de configuración en tiempo de ejecución, establece `requiresRuntime: true` y conserva `setup-api` como ruta de ejecución de respaldo. -Dado 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 descubiertos. La propiedad ambigua falla de forma cerrada en lugar de elegir un ganador según el orden de descubrimiento. +Como 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. 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. | +| Campo | Obligatorio | Tipo | Qué significa | +| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ | +| `id` | Sí | `string` | ID de proveedor expuesto durante la configuración o 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 tiempo de ejecución completo. | +| `envVars` | No | `string[]` | Variables de entorno que las superficies genéricas de configuración/estado pueden comprobar antes de que se cargue el tiempo de ejecución del plugin. | ### Campos de `setup` -| 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 orientada por 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 ejecución de `setup-api` después de la búsqueda por descriptores. | +| 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 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 ejecutar `setup-api` después de la búsqueda por descriptor. | ## Referencia de `uiHints` -`uiHints` es un mapa de nombres de campos de configuración a pequeñas pistas de renderizado. +`uiHints` es un mapa de nombres de campos de configuración a pequeños indicios de renderizado. ```json { "uiHints": { "apiKey": { "label": "Clave API", - "help": "Se usa para las solicitudes a OpenRouter", + "help": "Se usa para solicitudes de OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -330,20 +330,20 @@ Dado que la búsqueda de configuración puede ejecutar código `setup-api` propi } ``` -Cada pista de campo puede incluir: +Cada indicio 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 IU. | -| `advanced` | `boolean` | Marca el campo como avanzado. | -| `sensitive` | `boolean` | Marca el campo como secreto o sensible. | -| `placeholder` | `string` | Texto de marcador de posición para entradas de formulario. | +| Campo | Tipo | Qué significa | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Etiqueta del campo orientada al 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 placeholder para entradas de formulario. | ## Referencia de `contracts` -Usa `contracts` solo para metadatos estáticos de propiedad de capacidades que OpenClaw puede leer sin importar el runtime del plugin. +Usa `contracts` solo para metadatos estáticos de propiedad de capacidades que OpenClaw puede leer sin importar el tiempo de ejecución del plugin. ```json { @@ -363,21 +363,21 @@ Usa `contracts` solo para metadatos estáticos de propiedad de capacidades que O 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 contrato empaquetadas. | +| Campo | Tipo | Qué significa | +| -------------------------------- | ---------- | -------------------------------------------------------------- | +| `speechProviders` | `string[]` | IDs de proveedores de speech que pertenecen a este plugin. | +| `realtimeTranscriptionProviders` | `string[]` | IDs de proveedores de transcripción en tiempo real que pertenecen a este plugin. | +| `realtimeVoiceProviders` | `string[]` | IDs de proveedores de voz en tiempo real que pertenecen a este plugin. | +| `mediaUnderstandingProviders` | `string[]` | IDs de proveedores de comprensión de medios que pertenecen a este plugin. | +| `imageGenerationProviders` | `string[]` | IDs de proveedores de generación de imágenes que pertenecen a este plugin. | +| `videoGenerationProviders` | `string[]` | IDs de proveedores de generación de video que pertenecen a este plugin. | +| `webFetchProviders` | `string[]` | IDs de proveedores de web-fetch que pertenecen a este plugin. | +| `webSearchProviders` | `string[]` | IDs de proveedores de búsqueda web que pertenecen a este plugin. | +| `tools` | `string[]` | Nombres de herramientas del agente que pertenecen a este plugin para comprobaciones de contratos incluidos. | ## Referencia de `channelConfigs` -Usa `channelConfigs` cuando un plugin de canal necesita metadatos ligeros de configuración 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 tiempo de ejecución. ```json { @@ -392,12 +392,12 @@ Usa `channelConfigs` cuando un plugin de canal necesita metadatos ligeros de con }, "uiHints": { "homeserverUrl": { - "label": "URL del homeserver", + "label": "URL del servidor doméstico", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Conexión al homeserver de Matrix", + "description": "Conexión al servidor doméstico Matrix", "preferOver": ["matrix-legacy"] } } @@ -406,17 +406,17 @@ Usa `channelConfigs` cuando un plugin de canal necesita metadatos ligeros de con 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 IU, marcadores de posición o pistas de sensibilidad opcionales para esa sección de configuración del canal. | -| `label` | `string` | Etiqueta del canal fusionada en las superficies de selección e inspección cuando los metadatos de runtime aún no están listos. | -| `description` | `string` | Descripción breve del canal para las superficies de inspección y catálogo. | -| `preferOver` | `string[]` | IDs de plugins heredados o de menor prioridad a los que este canal debe superar en las superficies de selección. | +| 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/indicios de sensibilidad opcionales para esa sección de configuración del canal. | +| `label` | `string` | Etiqueta del canal integrada en las superficies de selector e inspección cuando los metadatos de tiempo de ejecución 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 de plugins a los que este canal debe 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. +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 tiempo de ejecución del plugin. ```json { @@ -429,28 +429,28 @@ Usa `modelSupport` cuando OpenClaw deba inferir tu plugin de proveedor a partir OpenClaw aplica esta precedencia: -- las referencias explícitas `provider/model` usan los metadatos del manifiesto `providers` propietario -- `modelPatterns` tiene prioridad sobre `modelPrefixes` -- si coinciden un plugin no empaquetado y un plugin empaquetado, gana el plugin no empaquetado +- las referencias explícitas `provider/model` usan los metadatos del manifiesto `providers` del propietario +- `modelPatterns` tienen prioridad sobre `modelPrefixes` +- si un plugin no incluido y un plugin incluido coinciden, gana el plugin no incluido - 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 comparados con `startsWith` frente a IDs abreviados de modelos. | -| `modelPatterns` | `string[]` | Orígenes de regex comparados 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 modelos. | +| `modelPatterns` | `string[]` | Fuentes regex comparadas con IDs abreviados de modelos después de eliminar el sufijo del perfil. | Las claves heredadas de capacidades de nivel superior están obsoletas. Usa `openclaw doctor --fix` para mover `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `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 +## Manifiesto frente a `package.json` Los dos archivos cumplen funciones distintas: -| Archivo | Úsalo para | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.plugin.json` | Descubrimiento, validación de configuración, metadatos de opciones de autenticación y pistas de IU 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, control de instalación, configuración o metadatos de catálogo | +| Archivo | Úsalo para | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Descubrimiento, validación de configuración, metadatos de opciones de autenticación e indicios 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, control 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: @@ -459,26 +459,28 @@ Si no estás seguro de dónde debe ir una pieza de metadatos, usa esta regla: ### Campos de `package.json` que afectan al descubrimiento -Algunos metadatos del plugin previos al runtime viven intencionalmente en `package.json` bajo el bloque `openclaw` en lugar de `openclaw.plugin.json`. +Algunos metadatos del plugin previos al tiempo de ejecución viven intencionalmente en `package.json`, dentro del bloque `openclaw`, en lugar de `openclaw.plugin.json`. Ejemplos importantes: -| 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 arranque diferido del canal. | -| `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 configuración solo por env?” sin cargar el runtime completo del canal. | -| `openclaw.channel.persistedAuthState` | Metadatos ligeros del verificador de autenticación persistida que pueden responder “¿ya hay algo autenticado?” sin cargar el runtime completo del canal. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Pistas de instalación/actualización para plugins empaquetados 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 semver como `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Permite una ruta limitada de recuperación por reinstalación de plugin empaquetado cuando la configuración no es válida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies de 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 de configuración usado durante la incorporación, el inicio diferido de canales y el descubrimiento de estado de canal/SecretRef de solo lectura. | +| `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 por entorno?” sin cargar el tiempo de ejecución completo del canal. | +| `openclaw.channel.persistedAuthState` | Metadatos ligeros del verificador de autenticación persistida que pueden responder “¿ya hay algo autenticado?” sin cargar el tiempo de ejecución completo del canal. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Indicios 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 de OpenClaw, usando un mínimo 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 no es válida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies de canal solo de configuración se carguen antes del plugin de canal completo durante el inicio. | -`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 nuevos omiten el plugin en hosts antiguos. +`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 más nuevos pero válidos omiten el plugin en hosts más antiguos. -`openclaw.install.allowInvalidConfigRecovery` es intencionalmente limitado. No hace instalables configuraciones rotas arbitrarias. Hoy solo permite que los flujos de instalación se recuperen de fallos concretos y obsoletos de actualización de plugins empaquetados, como una ruta faltante del plugin empaquetado o una entrada obsoleta `channels.` para ese mismo plugin empaquetado. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores a `openclaw doctor --fix`. +Los plugins de canal deben proporcionar `openclaw.setupEntry` cuando el estado, la lista de canales o los análisis de SecretRef necesiten identificar cuentas configuradas sin cargar el tiempo de ejecución completo. La entrada de configuración debe exponer metadatos del canal junto con adaptadores de configuración, estado y secretos seguros para la configuración; mantén los clientes de red, listeners de Gateway y tiempos de ejecución de transporte en el punto de entrada principal de la extensión. + +`openclaw.install.allowInvalidConfigRecovery` es intencionalmente limitado. No hace instalables configuraciones arbitrariamente rotas. Hoy solo permite que los flujos de instalación se recuperen de fallos concretos de actualización de plugins incluidos obsoletos, como una ruta faltante del 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 a `openclaw doctor --fix`. `openclaw.channel.persistedAuthState` es metadato de paquete para un pequeño módulo verificador: @@ -496,9 +498,9 @@ Ejemplos importantes: } ``` -Úsalo cuando los flujos de configuración, doctor o estado configurado necesiten una comprobación ligera de autenticación sí/no antes de que se cargue el plugin completo del canal. La exportación de destino debe ser una función pequeña que solo lea el estado persistido; no la enrutes a través del barrel completo del runtime del canal. +Úsalo cuando los flujos de configuración, doctor o estado configurado necesiten una comprobación ligera de autenticación sí/no antes de que se cargue el plugin de canal completo. La exportación de destino debe ser una función pequeña que lea solo el estado persistido; no la enrutes a través del barrel completo del tiempo de ejecución del canal. -`openclaw.channel.configuredState` sigue la misma forma para comprobaciones ligeras de estado configurado solo por env: +`openclaw.channel.configuredState` sigue la misma forma para comprobaciones ligeras de estado configurado solo por entorno: ```json { @@ -514,46 +516,46 @@ Ejemplos importantes: } ``` -Úsalo cuando un canal pueda responder el estado configurado a partir de env u otras entradas pequeñas que no sean de 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. +Úsalo cuando un canal pueda responder al estado configurado desde el entorno u otras entradas mínimas que no sean de tiempo de ejecución. Si la comprobación necesita la resolución completa de configuración o el tiempo de ejecución real del canal, mantén esa lógica en el hook `config.hasConfiguredState` del plugin. ## Requisitos del esquema JSON - **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 configuración, no en tiempo de ejecución. ## Comportamiento de validación -- 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 **descubribles**. Los IDs desconocidos son **errores**. +- Las claves desconocidas de `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**. - 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 y en los logs. +- Si existe configuración del plugin pero el plugin está **deshabilitado**, la configuración se conserva y 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 - El manifiesto es **obligatorio para los plugins nativos de OpenClaw**, incluidas las cargas desde el sistema de archivos local. -- El runtime sigue cargando el módulo del plugin por separado; el manifiesto es solo para descubrimiento + validación. +- El tiempo de ejecución sigue cargando el módulo del plugin por separado; el manifiesto es solo para 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 de manifiestos solo lee los campos de manifiesto documentados. Evita añadir aquí claves personalizadas de nivel superior. -- `providerAuthEnvVars` es la ruta de metadatos ligera para sondeos de autenticación, validación de marcadores de env y superficies similares de autenticación del proveedor que no deberían iniciar el runtime del plugin solo para inspeccionar nombres de env. -- `providerAuthAliases` permite que las variantes de proveedores 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. -- `providerEndpoints` permite que los plugins de proveedores sean propietarios de metadatos simples de coincidencia de host/baseUrl de endpoints. Úsalo solo para clases de endpoint que el núcleo ya admita; el plugin sigue siendo propietario del comportamiento en runtime. -- `syntheticAuthRefs` es la ruta de metadatos ligera para hooks de autenticación sintética propiedad del proveedor que deben ser visibles para el descubrimiento en frío de modelos antes de que exista el registro de runtime. Enumera solo referencias cuyo proveedor o backend de CLI en runtime implemente realmente `resolveSyntheticAuth`. -- `nonSecretAuthMarkers` es la ruta de metadatos ligera para claves API de marcador de posición propiedad de plugins empaquetados, como marcadores de credenciales locales, OAuth o ambientales. El núcleo los trata como no secretos para la visualización de autenticación y auditorías de secretos sin codificar el proveedor propietario. -- `channelEnvVars` es la ruta de metadatos ligera para fallback de env del shell, prompts de configuración y superficies similares de canal que no deberían iniciar el runtime del plugin solo para inspeccionar nombres de env. -- `providerAuthChoices` es la ruta de metadatos ligera para selectores de opciones de autenticación, resolución de `--auth-choice`, asignación de proveedor preferido y registro simple de flags de CLI de incorporación antes de que se cargue el runtime del proveedor. Para metadatos del asistente de runtime que requieren código del proveedor, consulta [Hooks de runtime del proveedor](/es/plugins/architecture#provider-runtime-hooks). +- `providerAuthEnvVars` es la ruta de metadatos ligera para sondeos de autenticación, validación de marcadores de entorno y superficies similares de autenticación de proveedor que no deberían iniciar el tiempo de ejecución del plugin solo para inspeccionar nombres de variables de entorno. +- `providerAuthAliases` permite que variantes de proveedor reutilicen las variables de entorno de autenticación, los perfiles de autenticación, la autenticación respaldada por configuración y la opción de incorporación con clave API de otro proveedor, sin codificar esa relación en el núcleo. +- `providerEndpoints` permite que los plugins de proveedor sean propietarios de metadatos simples de coincidencia de host/baseUrl de endpoints. Úsalo solo para clases de endpoints que el núcleo ya admite; el plugin sigue siendo el propietario del comportamiento en tiempo de ejecución. +- `syntheticAuthRefs` es la ruta de metadatos ligera para hooks de autenticación sintética, propiedad del proveedor, que deben ser visibles para el descubrimiento en frío de modelos antes de que exista el registro de tiempo de ejecución. Incluye solo referencias cuyo proveedor o backend de CLI en tiempo de ejecución implemente realmente `resolveSyntheticAuth`. +- `nonSecretAuthMarkers` es la ruta de metadatos ligera para claves API de marcador de posición, propiedad de plugins incluidos, como marcadores de credenciales locales, OAuth o ambientales. + El núcleo las trata como no secretas para la visualización de autenticación y las auditorías de secretos, sin codificar el proveedor propietario. +- `channelEnvVars` es la ruta de metadatos ligera para el respaldo por variables de entorno del shell, prompts de configuración y superficies similares de canal que no deberían iniciar el tiempo de ejecución del plugin solo para inspeccionar nombres de variables de entorno. +- `providerAuthChoices` es la ruta de metadatos ligera para selectores de opciones de autenticación, resolución de `--auth-choice`, mapeo de proveedor preferido y registro simple de flags de CLI de incorporación antes de que se cargue el tiempo de ejecución del proveedor. Para metadatos del asistente de tiempo de ejecución que requieren código del proveedor, consulta [Hooks de tiempo de ejecución del proveedor](/es/plugins/architecture#provider-runtime-hooks). - Los tipos exclusivos de plugin se seleccionan mediante `plugins.slots.*`. - `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 necesita. -- Si tu plugin depende de módulos nativos, documenta los pasos de compilación y cualquier requisito de lista de permisos del administrador de paquetes (por ejemplo, pnpm `allow-build-scripts` + - `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. +- Si tu plugin depende de módulos nativos, documenta los pasos de compilación y cualquier requisito de lista de permitidos del gestor de paquetes (por ejemplo, pnpm `allow-build-scripts` - `pnpm rebuild `). ## Relacionado - [Creación de Plugins](/es/plugins/building-plugins) — primeros pasos con plugins -- [Arquitectura de Plugins](/es/plugins/architecture) — arquitectura interna +- [Arquitectura de Plugin](/es/plugins/architecture) — arquitectura interna - [Resumen del SDK](/es/plugins/sdk-overview) — referencia del SDK de Plugin diff --git a/docs/es/plugins/sdk-channel-plugins.md b/docs/es/plugins/sdk-channel-plugins.md index c3a1cd17b..ee79fe3f4 100644 --- a/docs/es/plugins/sdk-channel-plugins.md +++ b/docs/es/plugins/sdk-channel-plugins.md @@ -1,111 +1,111 @@ --- read_when: - - Estás creando un nuevo Plugin de canal de mensajería + - Estás creando un nuevo plugin de canal de mensajería - Quieres conectar OpenClaw a una plataforma de mensajería - - Necesitas entender la superficie del adaptador de ChannelPlugin + - Necesitas comprender la superficie del adaptador `ChannelPlugin` sidebarTitle: Channel Plugins -summary: Guía paso a paso para crear un Plugin de canal de mensajería para OpenClaw -title: Crear Plugins de canal +summary: Guía paso a paso para crear un plugin de canal de mensajería para OpenClaw +title: Creación de plugins de canal x-i18n: - generated_at: "2026-04-21T05:17:06Z" + generated_at: "2026-04-21T19:20:33Z" model: gpt-5.4 provider: openai - source_hash: 569394aeefa0231ae3157a13406f91c97fe7eeff2b62df0d35a893f1ad4d5d05 + source_hash: 35cae55c13b69f2219bd2f9bd3ee2f7d8c4075bd87f0be11c35a0fddb070fe1e source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# Crear Plugins de canal +# Creación de plugins de canal -Esta guía te acompaña en la creación de un Plugin de canal que conecta OpenClaw con una -plataforma de mensajería. Al final tendrás un canal funcional con seguridad para MD, -vinculación, hilos de respuesta y mensajería saliente. +Esta guía explica paso a paso cómo crear un plugin de canal que conecte OpenClaw con una +plataforma de mensajería. Al final tendrás un canal funcional con seguridad en MD, +emparejamiento, hilos de respuesta y mensajería saliente. - Si todavía no has creado ningún Plugin de OpenClaw, lee primero + Si todavía no has creado ningún plugin de OpenClaw, lee primero [Primeros pasos](/es/plugins/building-plugins) para conocer la estructura básica - del paquete y la configuración del manifest. + del paquete y la configuración del manifiesto. -## Cómo funcionan los Plugins de canal +## Cómo funcionan los plugins de canal -Los Plugins de canal no necesitan sus propias tools de enviar/editar/reaccionar. OpenClaw mantiene una -tool `message` compartida en el core. Tu Plugin es responsable de: +Los plugins de canal no necesitan sus propias herramientas para enviar/editar/reaccionar. OpenClaw mantiene una única +herramienta `message` compartida en el núcleo. Tu plugin se encarga de: - **Configuración** — resolución de cuentas y asistente de configuración - **Seguridad** — política de MD y listas de permitidos -- **Vinculación** — flujo de aprobación de MD -- **Gramática de sesión** — cómo los IDs de conversación específicos del proveedor se asignan a chats base, IDs de hilo y respaldos de padre -- **Salida** — envío de texto, multimedia y sondeos a la plataforma -- **Hilos** — cómo se encadenan las respuestas +- **Emparejamiento** — flujo de aprobación de MD +- **Gramática de sesión** — cómo los ids de conversación específicos del proveedor se asignan a chats base, ids de hilo y alternativas de respaldo del padre +- **Salida** — envío de texto, contenido multimedia y encuestas a la plataforma +- **Hilos** — cómo se estructuran las respuestas en hilos -El core es responsable de la tool `message` compartida, el cableado del prompt, la forma externa de la clave de sesión, -la contabilidad genérica de `:thread:` y el despacho. +El núcleo se encarga de la herramienta `message` compartida, la conexión del prompt, la forma externa de la clave de sesión, +el control genérico de `:thread:` y el despacho. -Si tu canal agrega parámetros de tool de mensaje que incluyen fuentes de multimedia, expón esos -nombres de parámetros mediante `describeMessageTool(...).mediaSourceParams`. El core usa -esa lista explícita para la normalización de rutas del sandbox y la política de acceso a multimedia saliente, -así que los Plugins no necesitan casos especiales en el core compartido para parámetros específicos del proveedor +Si tu canal agrega parámetros a la herramienta de mensajes que contienen fuentes multimedia, expón esos +nombres de parámetro mediante `describeMessageTool(...).mediaSourceParams`. El núcleo usa +esa lista explícita para la normalización de rutas del sandbox y la política de acceso a medios salientes, +por lo que los plugins no necesitan casos especiales en el núcleo compartido para parámetros específicos del proveedor como avatar, adjunto o imagen de portada. -Prefiere devolver un mapa con clave por acción como -`{ "set-profile": ["avatarUrl", "avatarPath"] }` para que acciones no relacionadas no +Prefiere devolver un mapa indexado por acción como +`{ "set-profile": ["avatarUrl", "avatarPath"] }` para que las acciones no relacionadas no hereden los argumentos multimedia de otra acción. Un arreglo plano sigue funcionando para parámetros que -intencionalmente se comparten entre todas las acciones expuestas. +se comparten intencionalmente entre todas las acciones expuestas. -Si tu plataforma almacena alcance adicional dentro de los IDs de conversación, mantén ese análisis -en el Plugin con `messaging.resolveSessionConversation(...)`. Ese es el gancho canónico -para mapear `rawId` al ID de conversación base, ID de hilo opcional, +Si tu plataforma almacena alcance adicional dentro de los ids de conversación, mantén ese análisis +en el plugin con `messaging.resolveSessionConversation(...)`. Ese es el gancho canónico +para asignar `rawId` al id de conversación base, el id de hilo opcional, `baseConversationId` explícito y cualquier `parentConversationCandidates`. Cuando devuelvas `parentConversationCandidates`, mantenlos ordenados desde el -padre más específico hasta la conversación más amplia/base. +padre más específico hasta la conversación base o más amplia. -Los Plugins integrados que necesitan el mismo análisis antes de que arranque el registro de canales +Los plugins incluidos que necesiten el mismo análisis antes de que se inicie el registro de canales también pueden exponer un archivo `session-key-api.ts` de nivel superior con una exportación -`resolveSessionConversation(...)` equivalente. El core usa esa superficie segura para bootstrap -solo cuando el registro de Plugins en tiempo de ejecución todavía no está disponible. +`resolveSessionConversation(...)` correspondiente. El núcleo usa esa superficie segura para el arranque +solo cuando el registro de plugins en tiempo de ejecución todavía no está disponible. -`messaging.resolveParentConversationCandidates(...)` sigue disponible como respaldo heredado de compatibilidad cuando un Plugin solo necesita respaldos de padre además del ID genérico/raw. Si existen ambos ganchos, el core usa primero -`resolveSessionConversation(...).parentConversationCandidates` y solo -recurre a `resolveParentConversationCandidates(...)` cuando el gancho canónico -los omite. +`messaging.resolveParentConversationCandidates(...)` sigue disponible como alternativa heredada de compatibilidad cuando un plugin solo necesita +alternativas de respaldo del padre además del id genérico o sin procesar. Si existen ambos ganchos, el núcleo usa +primero `resolveSessionConversation(...).parentConversationCandidates` y solo recurre a `resolveParentConversationCandidates(...)` cuando el gancho canónico +las omite. ## Aprobaciones y capacidades del canal -La mayoría de los Plugins de canal no necesitan código específico de aprobaciones. +La mayoría de los plugins de canal no necesitan código específico de aprobaciones. -- El core es responsable de `/approve` en el mismo chat, las cargas compartidas de botones de aprobación y la entrega genérica de respaldo. -- Prefiere un único objeto `approvalCapability` en el Plugin de canal cuando el canal necesita comportamiento específico de aprobación. -- `ChannelPlugin.approvals` se eliminó. Coloca en `approvalCapability` los datos sobre entrega/aprobación nativa/renderizado/autenticación. -- `plugin.auth` es solo para login/logout; el core ya no lee ganchos de autenticación de aprobación desde ese objeto. -- `approvalCapability.authorizeActorAction` y `approvalCapability.getActionAvailabilityState` son la unión canónica para autenticación de aprobaciones. -- Usa `approvalCapability.getActionAvailabilityState` para la disponibilidad de autenticación de aprobaciones en el mismo chat. -- Si tu canal expone aprobaciones de ejecución nativas, usa `approvalCapability.getExecInitiatingSurfaceState` para el estado de cliente nativo/superficie iniciadora cuando difiera de la autenticación de aprobación en el mismo chat. El core usa ese gancho específico de ejecución para distinguir `enabled` frente a `disabled`, decidir si el canal iniciador admite aprobaciones nativas de ejecución e incluir el canal en la guía de respaldo de cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` lo completa para el caso común. -- Usa `outbound.shouldSuppressLocalPayloadPrompt` o `outbound.beforeDeliverPayload` para comportamiento específico del canal en el ciclo de vida de la carga, como ocultar solicitudes locales duplicadas de aprobación o enviar indicadores de escritura antes de la entrega. +- El núcleo se encarga de `/approve` en el mismo chat, de las cargas compartidas de botones de aprobación y de la entrega genérica de respaldo. +- Prefiere un único objeto `approvalCapability` en el plugin del canal cuando el canal necesite comportamiento específico de aprobación. +- `ChannelPlugin.approvals` se eliminó. Coloca los datos de entrega/aprobación nativa/renderizado/autenticación en `approvalCapability`. +- `plugin.auth` es solo para inicio y cierre de sesión; el núcleo ya no lee ganchos de autenticación de aprobación desde ese objeto. +- `approvalCapability.authorizeActorAction` y `approvalCapability.getActionAvailabilityState` son la superficie canónica para la autenticación de aprobaciones. +- Usa `approvalCapability.getActionAvailabilityState` para la disponibilidad de autenticación de aprobación en el mismo chat. +- Si tu canal expone aprobaciones nativas de ejecución, usa `approvalCapability.getExecInitiatingSurfaceState` para el estado de superficie de inicio/cliente nativo cuando difiera de la autenticación de aprobación en el mismo chat. El núcleo usa ese gancho específico de ejecución para distinguir `enabled` frente a `disabled`, decidir si el canal iniciador admite aprobaciones nativas de ejecución e incluir el canal en la guía de respaldo para clientes nativos. `createApproverRestrictedNativeApprovalCapability(...)` completa esto para el caso común. +- Usa `outbound.shouldSuppressLocalPayloadPrompt` o `outbound.beforeDeliverPayload` para comportamiento específico del canal en el ciclo de vida de la carga, como ocultar prompts locales de aprobación duplicados o enviar indicadores de escritura antes de la entrega. - Usa `approvalCapability.delivery` solo para enrutamiento de aprobación nativa o supresión de respaldo. -- Usa `approvalCapability.nativeRuntime` para datos de aprobación nativa propiedad del canal. Mantenlo lazy en puntos de entrada calientes del canal con `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que puede importar tu módulo runtime bajo demanda y aun así permitir que el core ensamble el ciclo de vida de aprobación. -- Usa `approvalCapability.render` solo cuando un canal realmente necesite cargas personalizadas de aprobación en lugar del renderizador compartido. -- Usa `approvalCapability.describeExecApprovalSetup` cuando el canal quiera que la respuesta de ruta deshabilitada explique las claves exactas de configuración necesarias para habilitar aprobaciones nativas de ejecución. El gancho recibe `{ channel, channelLabel, accountId }`; los canales con cuentas nombradas deben renderizar rutas con alcance por cuenta como `channels..accounts..execApprovals.*` en lugar de valores predeterminados de nivel superior. -- Si un canal puede inferir identidades tipo propietario estables en MD a partir de la configuración existente, usa `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` en el mismo chat sin agregar lógica específica de aprobación en el core. -- Si un canal necesita entrega de aprobación nativa, mantén el código del canal centrado en la normalización del destino más los datos de transporte/presentación. Usa `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` y `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloca los datos específicos del canal detrás de `approvalCapability.nativeRuntime`, idealmente mediante `createChannelApprovalNativeRuntimeAdapter(...)` o `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que el core pueda ensamblar el controlador y encargarse del filtrado de solicitudes, enrutamiento, deduplicación, caducidad, suscripción al Gateway y avisos de redirección. `nativeRuntime` está dividido en varias uniones más pequeñas: -- `availability` — si la cuenta está configurada y si una solicitud debe manejarse -- `presentation` — asignar el modelo de vista de aprobación compartido a cargas nativas pendientes/resueltas/caducadas o acciones finales -- `transport` — preparar destinos más enviar/actualizar/eliminar mensajes nativos de aprobación -- `interactions` — ganchos opcionales para bind/unbind/clear-action de botones o reacciones nativas +- Usa `approvalCapability.nativeRuntime` para los datos de aprobación nativa propios del canal. Mantenlo perezoso en puntos de entrada activos del canal con `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que puede importar tu módulo de tiempo de ejecución bajo demanda y aun así permitir que el núcleo ensamble el ciclo de vida de la aprobación. +- Usa `approvalCapability.render` solo cuando un canal realmente necesite cargas de aprobación personalizadas en lugar del renderizador compartido. +- Usa `approvalCapability.describeExecApprovalSetup` cuando el canal quiera que la respuesta de la ruta deshabilitada explique exactamente qué opciones de configuración se necesitan para habilitar aprobaciones nativas de ejecución. El gancho recibe `{ channel, channelLabel, accountId }`; los canales con cuentas con nombre deben renderizar rutas con alcance por cuenta como `channels..accounts..execApprovals.*` en lugar de valores predeterminados de nivel superior. +- Si un canal puede inferir identidades estables tipo propietario en MD a partir de la configuración existente, usa `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` en el mismo chat sin agregar lógica específica de aprobación al núcleo. +- Si un canal necesita entrega de aprobación nativa, mantén el código del canal centrado en la normalización del destino más los datos de transporte/presentación. Usa `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` y `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloca los datos específicos del canal detrás de `approvalCapability.nativeRuntime`, idealmente mediante `createChannelApprovalNativeRuntimeAdapter(...)` o `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que el núcleo pueda ensamblar el controlador y ocuparse del filtrado de solicitudes, enrutamiento, eliminación de duplicados, vencimiento, suscripción al gateway y avisos de redirección. `nativeRuntime` se divide en unas pocas superficies más pequeñas: +- `availability` — si la cuenta está configurada y si debe atenderse una solicitud +- `presentation` — asigna el modelo de vista de aprobación compartido a cargas nativas pendientes/resueltas/vencidas o acciones finales +- `transport` — prepara destinos y envía/actualiza/elimina mensajes de aprobación nativa +- `interactions` — ganchos opcionales para asociar/desasociar/borrar acciones de botones o reacciones nativos - `observe` — ganchos opcionales de diagnóstico de entrega -- Si el canal necesita objetos propiedad del runtime como un cliente, token, app Bolt o receptor Webhook, regístralos mediante `openclaw/plugin-sdk/channel-runtime-context`. El registro genérico de contexto runtime permite que el core inicialice controladores orientados por capacidades a partir del estado de inicio del canal sin agregar glue específico de aprobación. -- Recurre a `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` de nivel más bajo solo cuando la unión orientada por capacidades todavía no sea lo bastante expresiva. -- Los canales de aprobación nativa deben enrutar tanto `accountId` como `approvalKind` mediante esos helpers. `accountId` mantiene la política de aprobación multicuenta dentro de la cuenta correcta del bot, y `approvalKind` mantiene disponible para el canal el comportamiento de aprobación de ejecución frente a aprobación de Plugin sin ramas codificadas en el core. -- El core ahora también es responsable de los avisos de redirección de aprobación. Los Plugins de canal no deben enviar sus propios mensajes de seguimiento del tipo “la aprobación fue a MD / otro canal” desde `createChannelNativeApprovalRuntime`; en su lugar, expón con precisión el enrutamiento de origen + MD del aprobador mediante los helpers compartidos de capacidad de aprobación y deja que el core agregue las entregas reales antes de publicar cualquier aviso de vuelta al chat iniciador. -- Conserva de extremo a extremo el tipo de ID de aprobación entregado. Los clientes nativos no deben - adivinar ni reescribir el enrutamiento de aprobación de ejecución frente a Plugin desde el estado local del canal. -- Diferentes tipos de aprobación pueden exponer intencionalmente distintas superficies nativas. - Ejemplos integrados actuales: - - Slack mantiene disponible el enrutamiento nativo de aprobación tanto para IDs de ejecución como de Plugin. - - Matrix mantiene el mismo enrutamiento nativo por MD/canal y UX de reacciones para aprobaciones de ejecución - y de Plugin, al tiempo que permite que la autenticación difiera según el tipo de aprobación. -- `createApproverRestrictedNativeApprovalAdapter` sigue existiendo como wrapper de compatibilidad, pero el código nuevo debe preferir el constructor de capacidades y exponer `approvalCapability` en el Plugin. +- Si el canal necesita objetos administrados en tiempo de ejecución, como un cliente, token, aplicación Bolt o receptor de Webhook, regístralos mediante `openclaw/plugin-sdk/channel-runtime-context`. El registro genérico de contexto de tiempo de ejecución permite que el núcleo inicie controladores basados en capacidades desde el estado de inicio del canal sin agregar código de integración específico de aprobación. +- Recurre a los niveles inferiores `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` solo cuando la superficie guiada por capacidades todavía no sea lo bastante expresiva. +- Los canales con aprobación nativa deben enrutar tanto `accountId` como `approvalKind` a través de esos ayudantes. `accountId` mantiene la política de aprobación multicuenta delimitada a la cuenta de bot correcta, y `approvalKind` mantiene disponible para el canal el comportamiento de aprobación de ejecución frente a plugin sin ramas codificadas en el núcleo. +- El núcleo ahora también se encarga de los avisos de redirección de aprobaciones. Los plugins de canal no deben enviar sus propios mensajes de seguimiento de tipo "la aprobación fue a MD / a otro canal" desde `createChannelNativeApprovalRuntime`; en su lugar, expón un enrutamiento preciso del origen + MD del aprobador mediante los ayudantes compartidos de capacidad de aprobación y deja que el núcleo agregue las entregas reales antes de publicar cualquier aviso de vuelta en el chat iniciador. +- Conserva de extremo a extremo el tipo de id de aprobación entregado. Los clientes nativos no deben + deducir ni reescribir el enrutamiento de aprobaciones de ejecución frente a plugin a partir del estado local del canal. +- Distintos tipos de aprobación pueden exponer intencionalmente distintas superficies nativas. + Ejemplos actuales incluidos: + - Slack mantiene disponible el enrutamiento nativo de aprobaciones tanto para ids de ejecución como de plugin. + - Matrix mantiene el mismo enrutamiento nativo de MD/canal y la misma UX de reacciones para aprobaciones de ejecución + y de plugin, y aun así permite que la autenticación difiera según el tipo de aprobación. +- `createApproverRestrictedNativeApprovalAdapter` sigue existiendo como envoltorio de compatibilidad, pero el código nuevo debe preferir el generador de capacidades y exponer `approvalCapability` en el plugin. -Para puntos de entrada calientes del canal, prefiere las subrutas runtime más específicas cuando solo +Para puntos de entrada activos del canal, prefiere las subrutas de tiempo de ejecución más específicas cuando solo necesites una parte de esa familia: - `openclaw/plugin-sdk/approval-auth-runtime` @@ -123,93 +123,100 @@ Del mismo modo, prefiere `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` y -`openclaw/plugin-sdk/reply-chunking` cuando no necesites la -superficie paraguas más amplia. +`openclaw/plugin-sdk/reply-chunking` cuando no necesites la superficie general +más amplia. -Para la configuración inicial en particular: +Específicamente para la configuración: -- `openclaw/plugin-sdk/setup-runtime` cubre los helpers de configuración seguros para runtime: - adaptadores seguros para importación de parche de configuración (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` cubre los ayudantes de configuración seguros para tiempo de ejecución: + adaptadores de parcheo de configuración seguros para importar (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`), salida de notas de búsqueda, - `promptResolvedAllowFrom`, `splitSetupEntries` y los constructores - delegados de proxy de configuración -- `openclaw/plugin-sdk/setup-adapter-runtime` es la unión estrecha de adaptador - sensible al entorno para `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` cubre los constructores de configuración con instalación opcional + `promptResolvedAllowFrom`, `splitSetupEntries` y los generadores + delegados del proxy de configuración +- `openclaw/plugin-sdk/setup-adapter-runtime` es la superficie de adaptador + estrecha y consciente del entorno para `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` cubre los generadores de configuración de instalación opcional más algunas primitivas seguras para configuración: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Si tu canal admite configuración o autenticación impulsada por variables de entorno y los flujos genéricos de inicio/configuración -deben conocer esos nombres de entorno antes de que cargue el runtime, decláralos en el -manifest del Plugin con `channelEnvVars`. Mantén `envVars` del runtime del canal o constantes -locales solo para el texto visible para operadores. +Si tu canal admite configuración o autenticación controladas por entorno y los +flujos genéricos de inicio/configuración deben conocer esos nombres de variables de entorno antes de que se cargue el tiempo de ejecución, decláralos en el +manifiesto del plugin con `channelEnvVars`. Mantén `envVars` del tiempo de ejecución del canal o las constantes locales solo para el texto orientado a operadores. + +Si tu canal puede aparecer en `status`, `channels list`, `channels status` o en exploraciones de SecretRef antes de que se inicie el tiempo de ejecución del plugin, agrega `openclaw.setupEntry` en +`package.json`. Ese punto de entrada debe ser seguro de importar en rutas de comandos de solo lectura y debe devolver los metadatos del canal, el adaptador de configuración seguro, el adaptador de estado y los metadatos de destino de secretos del canal necesarios para esos resúmenes. No inicies clientes, listeners ni transportes de tiempo de ejecución desde el punto de entrada de configuración. + `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` y `splitSetupEntries` -- usa la unión más amplia `openclaw/plugin-sdk/setup` solo cuando también necesites los - helpers compartidos más pesados de configuración/configuración como +- usa la superficie más amplia `openclaw/plugin-sdk/setup` solo cuando también necesites los + ayudantes compartidos más pesados de configuración/configuración como `moveSingleAccountChannelSectionToDefaultAccount(...)` -Si tu canal solo quiere anunciar “instala primero este Plugin” en las superficies de configuración, prefiere `createOptionalChannelSetupSurface(...)`. El adaptador/asistente generado falla en modo cerrado en escrituras de configuración y finalización, y reutiliza el mismo mensaje de instalación obligatoria en la validación, la finalización y el texto de enlaces de documentación. +Si tu canal solo quiere anunciar "instala primero este plugin" en las +superficies de configuración, prefiere `createOptionalChannelSetupSurface(...)`. El +adaptador/asistente generado falla de forma cerrada en escrituras de configuración y finalización, y reutiliza +el mismo mensaje de instalación requerida en la validación, finalización y texto de enlace a la documentación. -Para otras rutas calientes del canal, prefiere los helpers específicos en lugar de superficies heredadas más amplias: +Para otras rutas activas del canal, prefiere los ayudantes más específicos frente a las superficies +heredadas más amplias: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` y - `openclaw/plugin-sdk/account-helpers` para configuración multicuenta y - respaldo de cuenta predeterminada + `openclaw/plugin-sdk/account-helpers` para la configuración multicuenta y + el respaldo a la cuenta predeterminada - `openclaw/plugin-sdk/inbound-envelope` y - `openclaw/plugin-sdk/inbound-reply-dispatch` para enrutamiento/sobre de entrada y - cableado de registro y despacho -- `openclaw/plugin-sdk/messaging-targets` para análisis y coincidencia de destinos + `openclaw/plugin-sdk/inbound-reply-dispatch` para el cableado de rutas/sobres entrantes y + de registrar y despachar +- `openclaw/plugin-sdk/messaging-targets` para análisis/coincidencia de destinos - `openclaw/plugin-sdk/outbound-media` y - `openclaw/plugin-sdk/outbound-runtime` para carga de multimedia más - delegados de identidad/envío saliente y planificación de carga -- `openclaw/plugin-sdk/thread-bindings-runtime` para ciclo de vida de vinculación de hilos - y registro de adaptadores -- `openclaw/plugin-sdk/agent-media-payload` solo cuando todavía se requiera - un diseño heredado de campos de carga de agente/multimedia -- `openclaw/plugin-sdk/telegram-command-config` para normalización de comandos personalizados de Telegram, - validación de duplicados/conflictos y un contrato de configuración de comandos - estable como respaldo + `openclaw/plugin-sdk/outbound-runtime` para la carga de medios más los + delegados de identidad/envío saliente y la planificación de cargas +- `openclaw/plugin-sdk/thread-bindings-runtime` para el ciclo de vida de la asociación de hilos + y el registro de adaptadores +- `openclaw/plugin-sdk/agent-media-payload` solo cuando todavía se requiera un diseño heredado + de campos de carga de agente/medios +- `openclaw/plugin-sdk/telegram-command-config` para la normalización de comandos personalizados de Telegram, + la validación de duplicados/conflictos y un contrato de configuración de comandos + estable para respaldo -Los canales solo de autenticación normalmente pueden quedarse en la ruta predeterminada: el core gestiona las aprobaciones y el Plugin solo expone capacidades de salida/autenticación. Los canales de aprobación nativa como Matrix, Slack, Telegram y transportes de chat personalizados deben usar los helpers nativos compartidos en lugar de crear su propio ciclo de vida de aprobación. +Los canales solo de autenticación normalmente pueden detenerse en la ruta predeterminada: el núcleo maneja las aprobaciones y el plugin solo expone capacidades de salida/autenticación. Los canales con aprobación nativa, como Matrix, Slack, Telegram y transportes de chat personalizados, deben usar los ayudantes nativos compartidos en lugar de crear su propio ciclo de vida de aprobación. ## Política de menciones entrantes Mantén el manejo de menciones entrantes dividido en dos capas: -- recopilación de evidencia propiedad del Plugin -- evaluación compartida de políticas +- recopilación de evidencia propia del plugin +- evaluación de políticas compartidas -Usa `openclaw/plugin-sdk/channel-mention-gating` para decisiones de política de mención. -Usa `openclaw/plugin-sdk/channel-inbound` solo cuando necesites el barrel más amplio de -helpers de entrada. +Usa `openclaw/plugin-sdk/channel-mention-gating` para decisiones de política de menciones. +Usa `openclaw/plugin-sdk/channel-inbound` solo cuando necesites el barrel más amplio +de ayudantes de entrada. -Buena opción para lógica local del Plugin: +Buena opción para lógica local del plugin: - detección de respuesta al bot -- detección de cita al bot -- comprobaciones de participación en hilo +- detección de cita del bot +- comprobaciones de participación en hilos - exclusiones de mensajes de servicio/sistema -- cachés nativas de la plataforma necesarias para demostrar participación del bot +- cachés nativos de la plataforma necesarios para demostrar la participación del bot -Buena opción para el helper compartido: +Buena opción para el ayudante compartido: - `requireMention` - resultado explícito de mención -- lista de permitidos de mención implícita -- bypass de comandos +- lista de permitidos de menciones implícitas +- omisión para comandos - decisión final de omitir -Flujo preferido: +Flujo recomendado: 1. Calcula los datos locales de mención. 2. Pasa esos datos a `resolveInboundMentionDecision({ facts, policy })`. -3. Usa `decision.effectiveWasMentioned`, `decision.shouldBypassMention` y `decision.shouldSkip` en tu restricción de entrada. +3. Usa `decision.effectiveWasMentioned`, `decision.shouldBypassMention` y `decision.shouldSkip` en tu compuerta de entrada. ```typescript import { @@ -248,8 +255,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` expone los mismos helpers compartidos de menciones para -Plugins de canal integrados que ya dependen de inyección runtime: +`api.runtime.channel.mentions` expone los mismos ayudantes compartidos de menciones para +plugins de canal incluidos que ya dependen de la inyección en tiempo de ejecución: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -259,21 +266,21 @@ Plugins de canal integrados que ya dependen de inyección runtime: Si solo necesitas `implicitMentionKindWhen` y `resolveInboundMentionDecision`, importa desde -`openclaw/plugin-sdk/channel-mention-gating` para evitar cargar helpers runtime -de entrada no relacionados. +`openclaw/plugin-sdk/channel-mention-gating` para evitar cargar ayudantes +de tiempo de ejecución entrante no relacionados. -Los helpers más antiguos `resolveMentionGating*` siguen en +Los ayudantes antiguos `resolveMentionGating*` siguen estando en `openclaw/plugin-sdk/channel-inbound` solo como exportaciones de compatibilidad. El código nuevo debe usar `resolveInboundMentionDecision({ facts, policy })`. -## Recorrido +## Tutorial paso a paso - - Crea los archivos estándar del Plugin. El campo `channel` en `package.json` es - lo que hace que este sea un Plugin de canal. Para la superficie completa de metadatos del paquete, - consulta [Configuración y config del Plugin](/es/plugins/sdk-setup#openclaw-channel): + + Crea los archivos estándar del plugin. El campo `channel` en `package.json` es + lo que convierte esto en un plugin de canal. Para la superficie completa de metadatos del paquete, + consulta [Configuración y ajuste del plugin](/es/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -287,7 +294,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Conecta OpenClaw con Acme Chat." + "blurb": "Connect OpenClaw to Acme Chat." } } } @@ -299,7 +306,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Plugin de canal Acme Chat", + "description": "Acme Chat channel plugin", "configSchema": { "type": "object", "additionalProperties": false, @@ -322,9 +329,9 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. - + La interfaz `ChannelPlugin` tiene muchas superficies de adaptador opcionales. Empieza con - el mínimo — `id` y `setup` — y agrega adaptadores según los necesites. + lo mínimo — `id` y `setup` — y agrega adaptadores según los necesites. Crea `src/channel.ts`: @@ -334,7 +341,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. createChannelPluginBase, } from "openclaw/plugin-sdk/channel-core"; import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core"; - import { acmeChatApi } from "./client.js"; // tu cliente API de plataforma + import { acmeChatApi } from "./client.js"; // your platform API client type ResolvedAccount = { accountId: string | null; @@ -375,7 +382,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. }, }), - // Seguridad de MD: quién puede enviar mensajes al bot + // DM security: who can message the bot security: { dm: { channelKey: "acme-chat", @@ -385,21 +392,21 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. }, }, - // Vinculación: flujo de aprobación para nuevos contactos de MD + // Pairing: approval flow for new DM contacts pairing: { text: { - idLabel: "nombre de usuario de Acme Chat", - message: "Envía este código para verificar tu identidad:", + idLabel: "Acme Chat username", + message: "Send this code to verify your identity:", notify: async ({ target, code }) => { - await acmeChatApi.sendDm(target, `Código de vinculación: ${code}`); + await acmeChatApi.sendDm(target, `Pairing code: ${code}`); }, }, }, - // Hilos: cómo se entregan las respuestas + // Threading: how replies are delivered threading: { topLevelReplyToMode: "reply" }, - // Salida: enviar mensajes a la plataforma + // Outbound: send messages to the platform outbound: { attachedResults: { sendText: async (params) => { @@ -419,15 +426,15 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. }); ``` - + En lugar de implementar manualmente interfaces de adaptador de bajo nivel, pasas - opciones declarativas y el constructor las compone: + opciones declarativas y el generador las compone: | Opción | Qué conecta | | --- | --- | - | `security.dm` | Resolver con alcance para seguridad de MD desde campos de config | - | `pairing.text` | Flujo de vinculación de MD basado en texto con intercambio de código | - | `threading` | Resolver del modo de respuesta (fijo, con alcance por cuenta o personalizado) | + | `security.dm` | Resolutor de seguridad de MD con alcance desde campos de configuración | + | `pairing.text` | Flujo de emparejamiento por texto en MD con intercambio de código | + | `threading` | Resolutor de modo de respuesta (fijo, con alcance por cuenta o personalizado) | | `outbound.attachedResults` | Funciones de envío que devuelven metadatos del resultado (IDs de mensaje) | También puedes pasar objetos de adaptador sin procesar en lugar de opciones declarativas @@ -436,7 +443,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. - + Crea `index.ts`: ```typescript index.ts @@ -446,20 +453,20 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. export default defineChannelPluginEntry({ id: "acme-chat", name: "Acme Chat", - description: "Plugin de canal Acme Chat", + description: "Acme Chat channel plugin", plugin: acmeChatPlugin, registerCliMetadata(api) { api.registerCli( ({ program }) => { program .command("acme-chat") - .description("Administración de Acme Chat"); + .description("Acme Chat management"); }, { descriptors: [ { name: "acme-chat", - description: "Administración de Acme Chat", + description: "Acme Chat management", hasSubcommands: false, }, ], @@ -472,22 +479,22 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. }); ``` - Coloca descriptores CLI propiedad del canal en `registerCliMetadata(...)` para que OpenClaw - pueda mostrarlos en la ayuda raíz sin activar el runtime completo del canal, - mientras que las cargas completas normales siguen recogiendo los mismos descriptores para el registro real de comandos. - Mantén `registerFull(...)` para trabajo solo de runtime. + Coloca los descriptores de CLI propios del canal en `registerCliMetadata(...)` para que OpenClaw + pueda mostrarlos en la ayuda raíz sin activar el tiempo de ejecución completo del canal, + mientras que las cargas completas normales siguen recogiendo los mismos descriptores para el registro real + de comandos. Mantén `registerFull(...)` para trabajo exclusivo de tiempo de ejecución. Si `registerFull(...)` registra métodos RPC del Gateway, usa un - prefijo específico del Plugin. Los espacios de nombres administrativos del core (`config.*`, + prefijo específico del plugin. Los espacios de nombres de administración del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) permanecen reservados y siempre se resuelven a `operator.admin`. - `defineChannelPluginEntry` maneja automáticamente la división por modo de registro. Consulta - [Puntos de entrada](/es/plugins/sdk-entrypoints#definechannelpluginentry) para todas las + `defineChannelPluginEntry` maneja automáticamente la separación por modo de registro. Consulta + [Puntos de entrada](/es/plugins/sdk-entrypoints#definechannelpluginentry) para ver todas las opciones. - - Crea `setup-entry.ts` para carga ligera durante el onboarding: + + Crea `setup-entry.ts` para una carga ligera durante la incorporación: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -497,18 +504,18 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. ``` OpenClaw carga esto en lugar de la entrada completa cuando el canal está deshabilitado - o sin configurar. Evita cargar código runtime pesado durante los flujos de configuración. - Consulta [Configuración y config](/es/plugins/sdk-setup#setup-entry) para más detalles. + o no configurado. Evita incorporar código pesado de tiempo de ejecución durante los flujos de configuración. + Consulta [Configuración y ajuste](/es/plugins/sdk-setup#setup-entry) para más detalles. - Los canales integrados del workspace que separan exportaciones seguras para configuración en módulos laterales - pueden usar `defineBundledChannelSetupEntry(...)` de + Los canales incluidos del workspace que dividen exportaciones seguras para configuración en módulos + complementarios pueden usar `defineBundledChannelSetupEntry(...)` de `openclaw/plugin-sdk/channel-entry-contract` cuando también necesiten un - setter runtime explícito en tiempo de configuración. + setter explícito del tiempo de ejecución en configuración. - - Tu Plugin necesita recibir mensajes de la plataforma y reenviarlos a + + Tu plugin necesita recibir mensajes de la plataforma y reenviarlos a OpenClaw. El patrón típico es un Webhook que verifica la solicitud y la despacha a través del controlador de entrada de tu canal: @@ -516,13 +523,13 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // autenticación gestionada por Plugin (verifica tú mismo las firmas) + auth: "plugin", // autenticación administrada por el plugin (verifica tú mismo las firmas) handler: async (req, res) => { const event = parseWebhookPayload(req); // Tu controlador de entrada despacha el mensaje a OpenClaw. - // El cableado exacto depende del SDK de tu plataforma: - // consulta un ejemplo real en el paquete integrado de Plugin de Microsoft Teams o Google Chat. + // El cableado exacto depende del SDK de tu plataforma — + // consulta un ejemplo real en el paquete de plugin incluido de Microsoft Teams o Google Chat. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -534,23 +541,23 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. ``` - El manejo de mensajes entrantes es específico de cada canal. Cada Plugin de canal posee - su propia canalización de entrada. Mira Plugins de canal integrados - (por ejemplo el paquete Plugin de Microsoft Teams o Google Chat) para ver patrones reales. + El manejo de mensajes entrantes es específico de cada canal. Cada plugin de canal se encarga de + su propia canalización de entrada. Consulta los plugins de canal incluidos + (por ejemplo, el paquete de plugin de Microsoft Teams o Google Chat) para ver patrones reales. - -Escribe pruebas colocadas conjuntamente en `src/channel.test.ts`: + +Escribe pruebas colocadas junto al código en `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; import { acmeChatPlugin } from "./channel.js"; - describe("plugin acme-chat", () => { - it("resuelve la cuenta desde la configuración", () => { + describe("acme-chat plugin", () => { + it("resolves account from config", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -560,7 +567,7 @@ Escribe pruebas colocadas conjuntamente en `src/channel.test.ts`: expect(account.token).toBe("test-token"); }); - it("inspecciona la cuenta sin materializar secretos", () => { + it("inspects account without materializing secrets", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -569,7 +576,7 @@ Escribe pruebas colocadas conjuntamente en `src/channel.test.ts`: expect(result.tokenStatus).toBe("available"); }); - it("informa configuración faltante", () => { + it("reports missing config", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -581,7 +588,7 @@ Escribe pruebas colocadas conjuntamente en `src/channel.test.ts`: pnpm test -- /acme-chat/ ``` - Para helpers de prueba compartidos, consulta [Pruebas](/es/plugins/sdk-testing). + Para ayudantes de prueba compartidos, consulta [Pruebas](/es/plugins/sdk-testing). @@ -590,17 +597,17 @@ Escribe pruebas colocadas conjuntamente en `src/channel.test.ts`: ``` /acme-chat/ -├── package.json # metadatos openclaw.channel -├── openclaw.plugin.json # Manifest con esquema de configuración +├── package.json # metadatos de openclaw.channel +├── openclaw.plugin.json # Manifiesto con esquema de configuración ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # Exportaciones públicas (opcional) -├── runtime-api.ts # Exportaciones runtime internas (opcional) +├── runtime-api.ts # Exportaciones internas de tiempo de ejecución (opcional) └── src/ ├── channel.ts # ChannelPlugin mediante createChatChannelPlugin ├── channel.test.ts # Pruebas - ├── client.ts # Cliente API de plataforma - └── runtime.ts # Almacén runtime (si hace falta) + ├── client.ts # Cliente de API de la plataforma + └── runtime.ts # Almacén de tiempo de ejecución (si es necesario) ``` ## Temas avanzados @@ -609,27 +616,27 @@ Escribe pruebas colocadas conjuntamente en `src/channel.test.ts`: Modos de respuesta fijos, con alcance por cuenta o personalizados - - describeMessageTool y descubrimiento de acciones + + describeMessageTool y detección de acciones inferTargetChatType, looksLikeId, resolveTarget - - TTS, STT, multimedia, subagente mediante api.runtime + + TTS, STT, medios, subagent mediante api.runtime -Algunas uniones helper integradas todavía existen para mantenimiento de Plugins integrados y -compatibilidad. No son el patrón recomendado para nuevos Plugins de canal; -prefiere las subrutas genéricas channel/setup/reply/runtime de la superficie -común del SDK a menos que estés manteniendo directamente esa familia de Plugins integrados. +Algunas superficies auxiliares incluidas siguen existiendo para mantenimiento y +compatibilidad de plugins incluidos. No son el patrón recomendado para plugins de canal nuevos; +prefiere las subrutas genéricas de channel/setup/reply/runtime de la superficie +común del SDK, a menos que estés manteniendo directamente esa familia de plugins incluidos. ## Siguientes pasos -- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — si tu Plugin también ofrece modelos -- [Resumen del SDK](/es/plugins/sdk-overview) — referencia completa de importaciones de subrutas +- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — si tu plugin también proporciona modelos +- [Descripción general del SDK](/es/plugins/sdk-overview) — referencia completa de importaciones por subruta - [Pruebas del SDK](/es/plugins/sdk-testing) — utilidades de prueba y pruebas de contrato -- [Manifest de Plugin](/es/plugins/manifest) — esquema completo del manifest +- [Manifiesto del plugin](/es/plugins/manifest) — esquema completo del manifiesto diff --git a/docs/es/providers/github-copilot.md b/docs/es/providers/github-copilot.md index 2452694c3..885e6f73c 100644 --- a/docs/es/providers/github-copilot.md +++ b/docs/es/providers/github-copilot.md @@ -5,27 +5,23 @@ read_when: summary: Inicia sesión en GitHub Copilot desde OpenClaw usando el flujo de dispositivo title: GitHub Copilot x-i18n: - generated_at: "2026-04-21T05:18:27Z" + generated_at: "2026-04-21T19:20:31Z" model: gpt-5.4 provider: openai - source_hash: f7faafbd3bdcd8886e75fb0d40c3eec66355df3fca6160ebbbb9a0018b7839fe + source_hash: b5169839322f64b24b194302b61c5bad67c6cb6595989f9a1ef65867d8b68659 source_path: providers/github-copilot.md workflow: 15 --- # GitHub Copilot -GitHub Copilot es el asistente de programación con IA de GitHub. Proporciona acceso a -modelos de Copilot para tu cuenta y plan de GitHub. OpenClaw puede usar Copilot como proveedor -de modelos de dos formas diferentes. +GitHub Copilot es el asistente de programación con IA de GitHub. Proporciona acceso a modelos de Copilot para tu cuenta y plan de GitHub. OpenClaw puede usar Copilot como proveedor de modelos de dos formas diferentes. ## Dos formas de usar Copilot en OpenClaw - Usa el flujo nativo de inicio de sesión por dispositivo para obtener un token de GitHub y luego intercambiarlo por - tokens de la API de Copilot cuando OpenClaw se ejecute. Esta es la ruta **predeterminada** y más simple - porque no requiere VS Code. + Usa el flujo nativo de inicio de sesión por dispositivo para obtener un token de GitHub y luego intercambiarlo por tokens de la API de Copilot cuando OpenClaw se ejecute. Esta es la ruta **predeterminada** y más sencilla porque no requiere VS Code. @@ -33,12 +29,11 @@ de modelos de dos formas diferentes. openclaw models auth login-github-copilot ``` - Se te pedirá que visites una URL e introduzcas un código de un solo uso. Mantén la - terminal abierta hasta que termine. + Se te pedirá que visites una URL e introduzcas un código de un solo uso. Mantén la terminal abierta hasta que se complete. ```bash - openclaw models set github-copilot/claude-opus-4.6 + openclaw models set github-copilot/claude-opus-4.7 ``` O en la configuración: @@ -46,7 +41,7 @@ de modelos de dos formas diferentes. ```json5 { agents: { - defaults: { model: { primary: "github-copilot/claude-opus-4.6" } }, + defaults: { model: { primary: "github-copilot/claude-opus-4.7" } }, }, } ``` @@ -56,12 +51,10 @@ de modelos de dos formas diferentes. - Usa la extensión de VS Code **Copilot Proxy** como puente local. OpenClaw se comunica con - el endpoint `/v1` del proxy y usa la lista de modelos que configures allí. + Usa la extensión de VS Code **Copilot Proxy** como puente local. OpenClaw se comunica con el endpoint `/v1` del proxy y usa la lista de modelos que configures allí. - Elige esto cuando ya ejecutes Copilot Proxy en VS Code o necesites enrutar - a través de él. Debes habilitar el Plugin y mantener la extensión de VS Code en ejecución. + Elige esta opción cuando ya uses Copilot Proxy en VS Code o necesites enrutar a través de él. Debes habilitar el Plugin y mantener la extensión de VS Code en ejecución. @@ -69,9 +62,9 @@ de modelos de dos formas diferentes. ## Indicadores opcionales -| Indicador | Descripción | -| -------------- | ------------------------------------------------------- | -| `--yes` | Omite la solicitud de confirmación | +| Flag | Descripción | +| --------------- | --------------------------------------------------- | +| `--yes` | Omite el aviso de confirmación | | `--set-default` | También aplica el modelo predeterminado recomendado del proveedor | ```bash @@ -84,61 +77,47 @@ openclaw models auth login --provider github-copilot --method device --set-defau - El flujo de inicio de sesión por dispositivo requiere un TTY interactivo. Ejecútalo directamente en una - terminal, no en un script no interactivo ni en una canalización de CI. + El flujo de inicio de sesión por dispositivo requiere un TTY interactivo. Ejecútalo directamente en una terminal, no en un script no interactivo ni en una canalización de CI. - La disponibilidad de modelos de Copilot depende de tu plan de GitHub. Si se - rechaza un modelo, prueba otro ID (por ejemplo `github-copilot/gpt-4.1`). + La disponibilidad de modelos de Copilot depende de tu plan de GitHub. Si se rechaza un modelo, prueba con otro ID (por ejemplo, `github-copilot/gpt-4.1`). - Los IDs de modelo Claude usan automáticamente el transporte Anthropic Messages. GPT, - los modelos de la serie o y Gemini mantienen el transporte OpenAI Responses. OpenClaw - selecciona el transporte correcto según la referencia del modelo. + Los ID de modelos Claude usan automáticamente el transporte Anthropic Messages. Los modelos GPT, de la serie o y Gemini mantienen el transporte OpenAI Responses. OpenClaw selecciona el transporte correcto según la referencia del modelo. - OpenClaw resuelve la autenticación de Copilot desde variables de entorno en el siguiente - orden de prioridad: + OpenClaw resuelve la autenticación de Copilot a partir de las variables de entorno en el siguiente orden de prioridad: - | Prioridad | Variable | Notas | - | --------- | ---------------------- | ------------------------------------- | - | 1 | `COPILOT_GITHUB_TOKEN` | Máxima prioridad, específica de Copilot | - | 2 | `GH_TOKEN` | Token de GitHub CLI (respaldo) | - | 3 | `GITHUB_TOKEN` | Token estándar de GitHub (mínima prioridad) | + | Priority | Variable | Notes | + | -------- | --------------------- | -------------------------------- | + | 1 | `COPILOT_GITHUB_TOKEN` | Prioridad más alta, específica de Copilot | + | 2 | `GH_TOKEN` | Token de GitHub CLI (respaldo) | + | 3 | `GITHUB_TOKEN` | Token estándar de GitHub (prioridad más baja) | - Cuando se establecen varias variables, OpenClaw usa la de mayor prioridad. - El flujo de inicio de sesión por dispositivo (`openclaw models auth login-github-copilot`) almacena - su token en el almacén de perfiles de autenticación y tiene prioridad sobre todas las variables de entorno. + Cuando hay varias variables configuradas, OpenClaw usa la de mayor prioridad. + El flujo de inicio de sesión por dispositivo (`openclaw models auth login-github-copilot`) almacena su token en el almacén de perfiles de autenticación y tiene prioridad sobre todas las variables de entorno. - El inicio de sesión almacena un token de GitHub en el almacén de perfiles de autenticación y lo intercambia - por un token de la API de Copilot cuando OpenClaw se ejecuta. No necesitas gestionar el - token manualmente. + El inicio de sesión almacena un token de GitHub en el almacén de perfiles de autenticación y lo intercambia por un token de la API de Copilot cuando OpenClaw se ejecuta. No necesitas gestionar el token manualmente. -Requiere un TTY interactivo. Ejecuta el comando de inicio de sesión directamente en una terminal, no -dentro de un script sin interfaz o un trabajo de CI. +Requiere un TTY interactivo. Ejecuta el comando de inicio de sesión directamente en una terminal, no dentro de un script sin interfaz ni de un trabajo de CI. -## Embeddings de búsqueda de memoria +## Incrustaciones de búsqueda de memoria -GitHub Copilot también puede servir como proveedor de embeddings para -[búsqueda de memoria](/es/concepts/memory-search). Si tienes una suscripción a Copilot y -has iniciado sesión, OpenClaw puede usarlo para embeddings sin una clave API independiente. +GitHub Copilot también puede servir como proveedor de incrustaciones para la [búsqueda de memoria](/es/concepts/memory-search). Si tienes una suscripción a Copilot y has iniciado sesión, OpenClaw puede usarlo para incrustaciones sin una clave de API independiente. ### Detección automática -Cuando `memorySearch.provider` es `"auto"` (el valor predeterminado), GitHub Copilot se prueba -con prioridad 15, después de los embeddings locales pero antes de OpenAI y otros -proveedores de pago. Si hay un token de GitHub disponible, OpenClaw descubre los modelos de -embeddings disponibles desde la API de Copilot y elige automáticamente el mejor. +Cuando `memorySearch.provider` es `"auto"` (el valor predeterminado), GitHub Copilot se prueba con prioridad 15: después de las incrustaciones locales, pero antes de OpenAI y otros proveedores de pago. Si hay disponible un token de GitHub, OpenClaw descubre los modelos de incrustación disponibles desde la API de Copilot y elige automáticamente el mejor. ### Configuración explícita @@ -148,7 +127,7 @@ embeddings disponibles desde la API de Copilot y elige automáticamente el mejor defaults: { memorySearch: { provider: "github-copilot", - // Opcional: sobrescribir el modelo detectado automáticamente + // Opcional: sobrescribe el modelo detectado automáticamente model: "text-embedding-3-small", }, }, @@ -159,19 +138,18 @@ embeddings disponibles desde la API de Copilot y elige automáticamente el mejor ### Cómo funciona 1. OpenClaw resuelve tu token de GitHub (desde variables de entorno o perfil de autenticación). -2. Lo intercambia por un token de la API de Copilot de corta duración. -3. Consulta el endpoint `/models` de Copilot para descubrir los modelos de embeddings disponibles. +2. Lo intercambia por un token de API de Copilot de corta duración. +3. Consulta el endpoint `/models` de Copilot para descubrir los modelos de incrustación disponibles. 4. Elige el mejor modelo (prefiere `text-embedding-3-small`). -5. Envía solicitudes de embeddings al endpoint `/embeddings` de Copilot. +5. Envía solicitudes de incrustación al endpoint `/embeddings` de Copilot. -La disponibilidad de modelos depende de tu plan de GitHub. Si no hay modelos de embeddings -disponibles, OpenClaw omite Copilot y prueba el siguiente proveedor. +La disponibilidad de modelos depende de tu plan de GitHub. Si no hay modelos de incrustación disponibles, OpenClaw omite Copilot y prueba el siguiente proveedor. ## Relacionado - Elegir proveedores, referencias de modelo y comportamiento de failover. + Elegir proveedores, referencias de modelos y comportamiento de conmutación por error. Detalles de autenticación y reglas de reutilización de credenciales. diff --git a/docs/es/tools/subagents.md b/docs/es/tools/subagents.md index 047c5db77..9a85016b6 100644 --- a/docs/es/tools/subagents.md +++ b/docs/es/tools/subagents.md @@ -1,26 +1,26 @@ --- read_when: - - Quieres trabajo en segundo plano o en paralelo mediante el agente - - Estás cambiando `sessions_spawn` o la política de herramientas de subagentes + - Quieres trabajo en segundo plano/en paralelo mediante el agente + - Estás cambiando la política de la herramienta `sessions_spawn` o de subagentes - Estás implementando o solucionando problemas de sesiones de subagentes vinculadas a hilos -summary: 'Subagentes: ejecución de agentes aislados que anuncian los resultados de vuelta al chat solicitante' +summary: 'Subagentes: ejecución de agentes aislados que anuncian los resultados de vuelta al chat del solicitante' title: Subagentes x-i18n: - generated_at: "2026-04-05T12:57:23Z" + generated_at: "2026-04-21T19:20:34Z" model: gpt-5.4 provider: openai - source_hash: 9df7cc35a3069ce4eb9c92a95df3ce5365a00a3fae92ff73def75461b58fec3f + source_hash: 218913f0db88d40e1b5fdb0201b8d23e7af23df572c86ff4be2637cb62498281 source_path: tools/subagents.md workflow: 15 --- # Subagentes -Los subagentes son ejecuciones de agentes en segundo plano generadas a partir de una ejecución de agente existente. Se ejecutan en su propia sesión (`agent::subagent:`) y, cuando terminan, **anuncian** su resultado de vuelta al canal de chat solicitante. Cada ejecución de subagente se registra como una [tarea en segundo plano](/es/automation/tasks). +Los subagentes son ejecuciones de agentes en segundo plano generadas desde una ejecución de agente existente. Se ejecutan en su propia sesión (`agent::subagent:`) y, cuando terminan, **anuncian** su resultado de vuelta al canal de chat del solicitante. Cada ejecución de subagente se rastrea como una [tarea en segundo plano](/es/automation/tasks). -## Comando slash +## Comando de barra -Usa `/subagents` para inspeccionar o controlar ejecuciones de subagentes para la **sesión actual**: +Usa `/subagents` para inspeccionar o controlar las ejecuciones de subagentes de la **sesión actual**: - `/subagents list` - `/subagents kill ` @@ -30,7 +30,7 @@ Usa `/subagents` para inspeccionar o controlar ejecuciones de subagentes para la - `/subagents steer ` - `/subagents spawn [--model ] [--thinking ]` -Controles de vinculación a hilos: +Controles de vinculación a hilo: Estos comandos funcionan en canales que admiten vinculaciones persistentes a hilos. Consulta **Canales compatibles con hilos** más abajo. @@ -41,128 +41,124 @@ Estos comandos funcionan en canales que admiten vinculaciones persistentes a hil - `/session max-age ` `/subagents info` muestra metadatos de la ejecución (estado, marcas de tiempo, id de sesión, ruta de la transcripción, limpieza). -Usa `sessions_history` para una vista de recuperación acotada y filtrada por seguridad; inspecciona la -ruta de la transcripción en disco cuando necesites la transcripción completa sin procesar. +Usa `sessions_history` para una vista de recuperación acotada y filtrada por seguridad; inspecciona la ruta de la transcripción en disco cuando necesites la transcripción completa en bruto. -### Comportamiento de spawn +### Comportamiento de creación -`/subagents spawn` inicia un subagente en segundo plano como un comando de usuario, no como un relé interno, y envía una actualización final de finalización de vuelta al chat solicitante cuando la ejecución termina. +`/subagents spawn` inicia un subagente en segundo plano como un comando de usuario, no como un relé interno, y envía una única actualización final de finalización de vuelta al chat del solicitante cuando la ejecución termina. -- El comando de spawn no bloquea; devuelve inmediatamente un id de ejecución. -- Al completarse, el subagente anuncia un mensaje de resumen/resultado de vuelta al canal de chat solicitante. -- La entrega de finalización está basada en envío. Una vez generado, no hagas sondeos en bucle a `/subagents list`, - `sessions_list` o `sessions_history` solo para esperar a que - termine; inspecciona el estado solo bajo demanda para depuración o intervención. -- Al completarse, OpenClaw cierra en la medida de lo posible las pestañas/procesos de navegador rastreados abiertos por esa sesión de subagente antes de que continúe el flujo de limpieza del anuncio. -- Para spawns manuales, la entrega es resistente: - - OpenClaw primero intenta la entrega directa con `agent` usando una clave de idempotencia estable. +- El comando de creación no bloquea; devuelve un id de ejecución de inmediato. +- Al completarse, el subagente anuncia un mensaje de resumen/resultado de vuelta al canal de chat del solicitante. +- La entrega de finalización es basada en push. Una vez creado, no hagas sondeos en bucle de `/subagents list`, `sessions_list` o `sessions_history` solo para esperar a que termine; inspecciona el estado solo bajo demanda para depuración o intervención. +- Al completarse, OpenClaw cierra en el mejor de los casos las pestañas/procesos del navegador rastreados que haya abierto esa sesión de subagente antes de que continúe el flujo de limpieza del anuncio. +- Para creaciones manuales, la entrega es resiliente: + - OpenClaw intenta primero la entrega directa de `agent` con una clave de idempotencia estable. - Si la entrega directa falla, recurre al enrutamiento por cola. - - Si el enrutamiento por cola sigue sin estar disponible, el anuncio se reintenta con un retroceso exponencial corto antes del abandono final. -- La entrega de finalización conserva la ruta del solicitante resuelta: - - las rutas de finalización vinculadas a hilos o conversaciones tienen prioridad cuando están disponibles - - si el origen de finalización solo proporciona un canal, OpenClaw completa el destino/cuenta que falta usando la ruta resuelta de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que la entrega directa siga funcionando -- La transferencia de finalización a la sesión solicitante es contexto interno generado en runtime (no texto redactado por el usuario) e incluye: - - `Result` (el texto de respuesta `assistant` visible más reciente, o en su defecto el texto más reciente saneado de tool/toolResult) + - Si el enrutamiento por cola sigue sin estar disponible, el anuncio se reintenta con un breve retroceso exponencial antes de desistir definitivamente. +- La entrega de finalización mantiene la ruta resuelta del solicitante: + - las rutas de finalización vinculadas a hilo o a conversación tienen prioridad cuando están disponibles + - si el origen de la finalización solo proporciona un canal, OpenClaw completa el destino/la cuenta faltantes a partir de la ruta resuelta de la sesión del solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que la entrega directa siga funcionando +- La transferencia de finalización a la sesión del solicitante es contexto interno generado en tiempo de ejecución (no texto escrito por el usuario) e incluye: + - `Result` (el texto más reciente visible de la respuesta `assistant`, o bien el texto más reciente saneado de tool/toolResult; las ejecuciones fallidas terminales no reutilizan el texto de respuesta capturado) - `Status` (`completed successfully` / `failed` / `timed out` / `unknown`) - estadísticas compactas de runtime/tokens - - una instrucción de entrega que indica al agente solicitante que reescriba en voz normal de asistente (no reenviar metadatos internos sin procesar) -- `--model` y `--thinking` anulan los valores predeterminados para esa ejecución específica. + - una instrucción de entrega que le indica al agente solicitante que reescriba en voz normal de asistente (sin reenviar metadatos internos en bruto) +- `--model` y `--thinking` reemplazan los valores predeterminados para esa ejecución específica. - Usa `info`/`log` para inspeccionar detalles y salida después de la finalización. -- `/subagents spawn` es modo de una sola ejecución (`mode: "run"`). Para sesiones persistentes vinculadas a hilos, usa `sessions_spawn` con `thread: true` y `mode: "session"`. -- Para sesiones del arnés ACP (Codex, Claude Code, Gemini CLI), usa `sessions_spawn` con `runtime: "acp"` y consulta [Agentes ACP](/tools/acp-agents). +- `/subagents spawn` es modo de un solo uso (`mode: "run"`). Para sesiones persistentes vinculadas a hilos, usa `sessions_spawn` con `thread: true` y `mode: "session"`. +- Para sesiones del arnés ACP (Codex, Claude Code, Gemini CLI), usa `sessions_spawn` con `runtime: "acp"` y consulta [Agentes ACP](/es/tools/acp-agents). Objetivos principales: -- Paralelizar trabajo de “investigación / tarea larga / herramienta lenta” sin bloquear la ejecución principal. -- Mantener a los subagentes aislados de forma predeterminada (separación de sesiones + sandboxing opcional). -- Hacer que la superficie de herramientas sea difícil de usar incorrectamente: los subagentes **no** reciben herramientas de sesión de forma predeterminada. -- Admitir profundidad de anidamiento configurable para patrones de orquestación. +- Paralelizar trabajo de "investigación / tarea larga / herramienta lenta" sin bloquear la ejecución principal. +- Mantener los subagentes aislados de forma predeterminada (separación de sesiones + sandboxing opcional). +- Mantener la superficie de herramientas difícil de usar mal: los subagentes **no** reciben herramientas de sesión de forma predeterminada. +- Admitir profundidad de anidación configurable para patrones de orquestación. -Nota sobre costo: cada subagente tiene su **propio** contexto y uso de tokens. Para tareas pesadas o repetitivas, -establece un modelo más barato para los subagentes y mantén tu agente principal en un modelo de mayor calidad. -Puedes configurarlo mediante `agents.defaults.subagents.model` o anulaciones por agente. +Nota de costo: cada subagente tiene su **propio** contexto y uso de tokens. Para tareas pesadas o repetitivas, establece un modelo más barato para los subagentes y mantén tu agente principal en un modelo de mayor calidad. +Puedes configurarlo mediante `agents.defaults.subagents.model` o con reemplazos por agente. ## Herramienta Usa `sessions_spawn`: - Inicia una ejecución de subagente (`deliver: false`, carril global: `subagent`) -- Luego ejecuta un paso de anuncio y publica la respuesta de anuncio en el canal de chat solicitante -- Modelo predeterminado: hereda del llamador salvo que establezcas `agents.defaults.subagents.model` (o `agents.list[].subagents.model` por agente); un `sessions_spawn.model` explícito sigue teniendo prioridad. -- Thinking predeterminado: hereda del llamador salvo que establezcas `agents.defaults.subagents.thinking` (o `agents.list[].subagents.thinking` por agente); un `sessions_spawn.thinking` explícito sigue teniendo prioridad. -- Tiempo de espera predeterminado de la ejecución: si se omite `sessions_spawn.runTimeoutSeconds`, OpenClaw usa `agents.defaults.subagents.runTimeoutSeconds` cuando está configurado; en caso contrario recurre a `0` (sin tiempo de espera). +- Luego ejecuta un paso de anuncio y publica la respuesta del anuncio en el canal de chat del solicitante +- Modelo predeterminado: hereda del llamador, a menos que establezcas `agents.defaults.subagents.model` (o `agents.list[].subagents.model` por agente); un `sessions_spawn.model` explícito sigue teniendo prioridad. +- Pensamiento predeterminado: hereda del llamador, a menos que establezcas `agents.defaults.subagents.thinking` (o `agents.list[].subagents.thinking` por agente); un `sessions_spawn.thinking` explícito sigue teniendo prioridad. +- Tiempo de espera predeterminado de la ejecución: si se omite `sessions_spawn.runTimeoutSeconds`, OpenClaw usa `agents.defaults.subagents.runTimeoutSeconds` cuando esté establecido; en caso contrario, recurre a `0` (sin tiempo de espera). Parámetros de la herramienta: - `task` (obligatorio) - `label?` (opcional) -- `agentId?` (opcional; generar bajo otro id de agente si está permitido) -- `model?` (opcional; anula el modelo del subagente; los valores no válidos se omiten y el subagente se ejecuta con el modelo predeterminado con una advertencia en el resultado de la herramienta) -- `thinking?` (opcional; anula el nivel de thinking para la ejecución del subagente) -- `runTimeoutSeconds?` (usa por defecto `agents.defaults.subagents.runTimeoutSeconds` cuando está configurado; en caso contrario `0`; cuando se establece, la ejecución del subagente se aborta tras N segundos) +- `agentId?` (opcional; crear bajo otro id de agente si está permitido) +- `model?` (opcional; reemplaza el modelo del subagente; los valores no válidos se omiten y el subagente se ejecuta con el modelo predeterminado con una advertencia en el resultado de la herramienta) +- `thinking?` (opcional; reemplaza el nivel de pensamiento para la ejecución del subagente) +- `runTimeoutSeconds?` (usa como valor predeterminado `agents.defaults.subagents.runTimeoutSeconds` cuando esté establecido; en caso contrario `0`; cuando se establece, la ejecución del subagente se aborta después de N segundos) - `thread?` (predeterminado `false`; cuando es `true`, solicita vinculación del hilo del canal para esta sesión de subagente) - `mode?` (`run|session`) - el valor predeterminado es `run` - si `thread: true` y se omite `mode`, el valor predeterminado pasa a ser `session` - `mode: "session"` requiere `thread: true` - `cleanup?` (`delete|keep`, predeterminado `keep`) -- `sandbox?` (`inherit|require`, predeterminado `inherit`; `require` rechaza el spawn salvo que el runtime hijo de destino esté en sandbox) +- `sandbox?` (`inherit|require`, predeterminado `inherit`; `require` rechaza la creación a menos que el runtime hijo de destino esté en sandbox) - `sessions_spawn` **no** acepta parámetros de entrega por canal (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Para la entrega, usa `message`/`sessions_send` desde la ejecución generada. ## Sesiones vinculadas a hilos -Cuando las vinculaciones a hilos están habilitadas para un canal, un subagente puede permanecer vinculado a un hilo para que los mensajes de usuario de seguimiento en ese hilo sigan enrutándose a la misma sesión de subagente. +Cuando las vinculaciones a hilos están habilitadas para un canal, un subagente puede permanecer vinculado a un hilo para que los mensajes posteriores del usuario en ese hilo sigan enroutándose a la misma sesión de subagente. ### Canales compatibles con hilos -- Discord (actualmente el único canal compatible): admite sesiones persistentes de subagentes vinculadas a hilos (`sessions_spawn` con `thread: true`), controles manuales de hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) y claves de adaptador `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` y `channels.discord.threadBindings.spawnSubagentSessions`. +- Discord (actualmente el único canal compatible): admite sesiones persistentes de subagentes vinculadas a hilos (`sessions_spawn` con `thread: true`), controles manuales de hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`), y las claves del adaptador `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`, y `channels.discord.threadBindings.spawnSubagentSessions`. Flujo rápido: -1. Genera con `sessions_spawn` usando `thread: true` (y opcionalmente `mode: "session"`). +1. Crea con `sessions_spawn` usando `thread: true` (y opcionalmente `mode: "session"`). 2. OpenClaw crea o vincula un hilo a ese destino de sesión en el canal activo. 3. Las respuestas y mensajes de seguimiento en ese hilo se enrutan a la sesión vinculada. -4. Usa `/session idle` para inspeccionar/actualizar el desenfoque automático por inactividad y `/session max-age` para controlar el límite estricto. +4. Usa `/session idle` para inspeccionar/actualizar el desenfoque automático por inactividad y `/session max-age` para controlar el límite máximo estricto. 5. Usa `/unfocus` para desvincular manualmente. Controles manuales: - `/focus ` vincula el hilo actual (o crea uno) a un destino de subagente/sesión. - `/unfocus` elimina la vinculación del hilo actualmente vinculado. -- `/agents` muestra las ejecuciones activas y el estado de la vinculación (`thread:` o `unbound`). +- `/agents` lista las ejecuciones activas y el estado de vinculación (`thread:` o `unbound`). - `/session idle` y `/session max-age` solo funcionan para hilos vinculados enfocados. Interruptores de configuración: -- Valor predeterminado global: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours` -- Las claves de anulación por canal y de vinculación automática de spawn son específicas del adaptador. Consulta **Canales compatibles con hilos** más arriba. +- Predeterminado global: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours` +- Los reemplazos por canal y las claves de vinculación automática al crear son específicos del adaptador. Consulta **Canales compatibles con hilos** más arriba. -Consulta [Referencia de configuración](/es/gateway/configuration-reference) y [Comandos slash](/tools/slash-commands) para obtener detalles actuales del adaptador. +Consulta [Referencia de configuración](/es/gateway/configuration-reference) y [Comandos de barra](/es/tools/slash-commands) para conocer los detalles actuales del adaptador. -Allowlist: +Lista de permitidos: -- `agents.list[].subagents.allowAgents`: lista de ids de agentes a los que se puede apuntar mediante `agentId` (`["*"]` para permitir cualquiera). Valor predeterminado: solo el agente solicitante. -- `agents.defaults.subagents.allowAgents`: allowlist predeterminada de agentes de destino usada cuando el agente solicitante no establece su propia `subagents.allowAgents`. +- `agents.list[].subagents.allowAgents`: lista de ids de agentes a los que se puede apuntar mediante `agentId` (`["*"]` para permitir cualquiera). Predeterminado: solo el agente solicitante. +- `agents.defaults.subagents.allowAgents`: lista de permitidos predeterminada de agentes de destino usada cuando el agente solicitante no establece su propio `subagents.allowAgents`. - Protección de herencia de sandbox: si la sesión solicitante está en sandbox, `sessions_spawn` rechaza destinos que se ejecutarían sin sandbox. -- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: cuando es true, bloquea llamadas `sessions_spawn` que omiten `agentId` (fuerza selección explícita de perfil). Valor predeterminado: false. +- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: cuando es true, bloquea las llamadas a `sessions_spawn` que omiten `agentId` (fuerza la selección explícita de perfil). Predeterminado: false. Descubrimiento: -- Usa `agents_list` para ver qué ids de agentes están permitidos actualmente para `sessions_spawn`. +- Usa `agents_list` para ver qué ids de agentes están actualmente permitidos para `sessions_spawn`. Archivado automático: -- Las sesiones de subagentes se archivan automáticamente tras `agents.defaults.subagents.archiveAfterMinutes` (predeterminado: 60). +- Las sesiones de subagentes se archivan automáticamente después de `agents.defaults.subagents.archiveAfterMinutes` (predeterminado: 60). - El archivado usa `sessions.delete` y renombra la transcripción a `*.deleted.` (misma carpeta). -- `cleanup: "delete"` archiva inmediatamente después del anuncio (pero conserva la transcripción mediante cambio de nombre). -- El archivado automático es una operación en la medida de lo posible; los temporizadores pendientes se pierden si el gateway se reinicia. +- `cleanup: "delete"` archiva inmediatamente después del anuncio (aun así conserva la transcripción mediante cambio de nombre). +- El archivado automático es en el mejor de los casos; los temporizadores pendientes se pierden si el Gateway se reinicia. - `runTimeoutSeconds` **no** archiva automáticamente; solo detiene la ejecución. La sesión permanece hasta el archivado automático. - El archivado automático se aplica por igual a sesiones de profundidad 1 y profundidad 2. -- La limpieza del navegador es independiente de la limpieza de archivo: las pestañas/procesos del navegador rastreados se cierran en la medida de lo posible cuando termina la ejecución, incluso si se conserva el registro de la transcripción/sesión. +- La limpieza del navegador es independiente de la limpieza por archivado: las pestañas/procesos del navegador rastreados se cierran en el mejor de los casos cuando la ejecución termina, aunque se conserve el registro de la sesión/transcripción. ## Subagentes anidados -De forma predeterminada, los subagentes no pueden generar sus propios subagentes (`maxSpawnDepth: 1`). Puedes habilitar un nivel de anidamiento estableciendo `maxSpawnDepth: 2`, lo que permite el **patrón de orquestación**: principal → subagente orquestador → sub-subagentes trabajadores. +De forma predeterminada, los subagentes no pueden crear sus propios subagentes (`maxSpawnDepth: 1`). Puedes habilitar un nivel de anidación estableciendo `maxSpawnDepth: 2`, lo que permite el **patrón de orquestación**: principal → subagente orquestador → sub-subagentes trabajadores. ### Cómo habilitarlo @@ -171,10 +167,10 @@ De forma predeterminada, los subagentes no pueden generar sus propios subagentes agents: { defaults: { subagents: { - maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1) - maxChildrenPerAgent: 5, // max active children per agent session (default: 5) - maxConcurrent: 8, // global concurrency lane cap (default: 8) - runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout) + maxSpawnDepth: 2, // permitir que los subagentes creen hijos (predeterminado: 1) + maxChildrenPerAgent: 5, // máximo de hijos activos por sesión de agente (predeterminado: 5) + maxConcurrent: 8, // límite global de concurrencia del carril (predeterminado: 8) + runTimeoutSeconds: 900, // tiempo de espera predeterminado para sessions_spawn cuando se omite (0 = sin tiempo de espera) }, }, }, @@ -183,58 +179,55 @@ De forma predeterminada, los subagentes no pueden generar sus propios subagentes ### Niveles de profundidad -| Profundidad | Forma de la clave de sesión | Rol | ¿Puede generar? | -| ----------- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | -| 0 | `agent::main` | Agente principal | Siempre | -| 1 | `agent::subagent:` | Subagente (orquestador cuando se permite profundidad 2) | Solo si `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | Sub-subagente (trabajador hoja) | Nunca | +| Depth | Forma de la clave de sesión | Rol | ¿Puede crear? | +| ----- | -------------------------------------------- | --------------------------------------------- | --------------------------- | +| 0 | `agent::main` | Agente principal | Siempre | +| 1 | `agent::subagent:` | Subagente (orquestador cuando se permite profundidad 2) | Solo si `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | Sub-subagente (trabajador hoja) | Nunca | ### Cadena de anuncios -Los resultados fluyen de vuelta por la cadena: +Los resultados fluyen de vuelta hacia arriba en la cadena: 1. El trabajador de profundidad 2 termina → anuncia a su padre (orquestador de profundidad 1) 2. El orquestador de profundidad 1 recibe el anuncio, sintetiza resultados, termina → anuncia al principal 3. El agente principal recibe el anuncio y lo entrega al usuario -Cada nivel solo ve anuncios de sus hijos directos. +Cada nivel solo ve los anuncios de sus hijos directos. Guía operativa: -- Inicia el trabajo hijo una sola vez y espera eventos de finalización en lugar de crear bucles de sondeo - alrededor de `sessions_list`, `sessions_history`, `/subagents list` o - comandos `exec` con sleep. -- Si llega un evento de finalización hijo después de que ya enviaste la respuesta final, - el seguimiento correcto es el token silencioso exacto `NO_REPLY` / `no_reply`. +- Inicia el trabajo hijo una vez y espera a los eventos de finalización en lugar de construir bucles de sondeo alrededor de `sessions_list`, `sessions_history`, `/subagents list` o comandos `exec` de espera. +- Si llega un evento de finalización hijo después de que ya enviaste la respuesta final, la continuación correcta es el token silencioso exacto `NO_REPLY` / `no_reply`. ### Política de herramientas por profundidad -- El rol y el alcance de control se escriben en los metadatos de la sesión en el momento del spawn. Eso evita que las claves de sesión planas o restauradas recuperen accidentalmente privilegios de orquestador. -- **Profundidad 1 (orquestador, cuando `maxSpawnDepth >= 2`)**: obtiene `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` para poder gestionar sus hijos. Otras herramientas de sesión/sistema siguen denegadas. -- **Profundidad 1 (hoja, cuando `maxSpawnDepth == 1`)**: sin herramientas de sesión (comportamiento predeterminado actual). -- **Profundidad 2 (trabajador hoja)**: sin herramientas de sesión — `sessions_spawn` siempre está denegado en profundidad 2. No puede generar más hijos. +- El rol y el alcance de control se escriben en los metadatos de la sesión en el momento de la creación. Eso evita que claves de sesión planas o restauradas recuperen accidentalmente privilegios de orquestación. +- **Profundidad 1 (orquestador, cuando `maxSpawnDepth >= 2`)**: Recibe `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` para poder gestionar a sus hijos. Las demás herramientas de sesión/sistema siguen denegadas. +- **Profundidad 1 (hoja, cuando `maxSpawnDepth == 1`)**: Sin herramientas de sesión (comportamiento predeterminado actual). +- **Profundidad 2 (trabajador hoja)**: Sin herramientas de sesión — `sessions_spawn` siempre está denegado en profundidad 2. No puede crear más hijos. -### Límite de spawn por agente +### Límite de creación por agente -Cada sesión de agente (a cualquier profundidad) puede tener como máximo `maxChildrenPerAgent` (predeterminado: 5) hijos activos al mismo tiempo. Esto evita el fan-out descontrolado de un único orquestador. +Cada sesión de agente (en cualquier profundidad) puede tener como máximo `maxChildrenPerAgent` (predeterminado: 5) hijos activos al mismo tiempo. Esto evita una expansión descontrolada desde un solo orquestador. ### Detención en cascada -Detener un orquestador de profundidad 1 detiene automáticamente todos sus hijos de profundidad 2: +Detener un orquestador de profundidad 1 detiene automáticamente a todos sus hijos de profundidad 2: -- `/stop` en el chat principal detiene todos los agentes de profundidad 1 y se propaga a sus hijos de profundidad 2. +- `/stop` en el chat principal detiene a todos los agentes de profundidad 1 y se propaga a sus hijos de profundidad 2. - `/subagents kill ` detiene un subagente específico y se propaga a sus hijos. - `/subagents kill all` detiene todos los subagentes del solicitante y se propaga. ## Autenticación -La autenticación del subagente se resuelve por **id de agente**, no por tipo de sesión: +La autenticación de subagentes se resuelve por **id de agente**, no por tipo de sesión: - La clave de sesión del subagente es `agent::subagent:`. - El almacén de autenticación se carga desde el `agentDir` de ese agente. -- Los perfiles de autenticación del agente principal se fusionan como **respaldo**; los perfiles del agente anulan a los del principal en caso de conflicto. +- Los perfiles de autenticación del agente principal se fusionan como **respaldo**; los perfiles del agente reemplazan a los perfiles principales en caso de conflicto. -Nota: la fusión es aditiva, por lo que los perfiles del principal siempre están disponibles como respaldo. La autenticación totalmente aislada por agente todavía no se admite. +Nota: la fusión es aditiva, así que los perfiles principales siempre están disponibles como respaldo. La autenticación totalmente aislada por agente aún no es compatible. ## Anuncio @@ -242,67 +235,60 @@ Los subagentes informan de vuelta mediante un paso de anuncio: - El paso de anuncio se ejecuta dentro de la sesión del subagente (no en la sesión del solicitante). - Si el subagente responde exactamente `ANNOUNCE_SKIP`, no se publica nada. -- Si el texto más reciente del asistente es el token silencioso exacto `NO_REPLY` / `no_reply`, - la salida del anuncio se suprime aunque existiera progreso visible previo. +- Si el texto más reciente del asistente es el token silencioso exacto `NO_REPLY` / `no_reply`, la salida del anuncio se suprime aunque haya habido progreso visible anterior. - En caso contrario, la entrega depende de la profundidad del solicitante: - - las sesiones solicitantes de nivel superior usan una llamada de seguimiento `agent` con entrega externa (`deliver=true`) - - las sesiones solicitantes de subagentes anidados reciben una inyección interna de seguimiento (`deliver=false`) para que el orquestador pueda sintetizar resultados de hijos dentro de la sesión + - las sesiones solicitantes de nivel superior usan una llamada de seguimiento a `agent` con entrega externa (`deliver=true`) + - las sesiones solicitantes de subagentes anidados reciben una inyección interna de seguimiento (`deliver=false`) para que el orquestador pueda sintetizar los resultados hijos dentro de la sesión - si una sesión solicitante de subagente anidado ya no existe, OpenClaw recurre al solicitante de esa sesión cuando está disponible -- Para sesiones solicitantes de nivel superior, la entrega directa en modo finalización primero resuelve cualquier ruta vinculada de conversación/hilo y anulación de hook, luego completa los campos de destino de canal que faltan desde la ruta almacenada de la sesión solicitante. Eso mantiene las finalizaciones en el chat/tema correcto incluso cuando el origen de finalización solo identifica el canal. -- La agregación de finalización de hijos se limita a la ejecución solicitante actual al construir hallazgos de finalización anidados, lo que evita que salidas antiguas de hijos de ejecuciones previas se filtren a la finalización actual. +- Para las sesiones solicitantes de nivel superior, la entrega directa en modo de finalización primero resuelve cualquier ruta vinculada de conversación/hilo y la anulación del hook, luego completa los campos faltantes del destino del canal a partir de la ruta almacenada de la sesión solicitante. Eso mantiene las finalizaciones en el chat/tema correcto incluso cuando el origen de la finalización solo identifica el canal. +- La agregación de finalización hija se limita a la ejecución solicitante actual al construir los hallazgos de finalización anidada, lo que evita que salidas hijas obsoletas de ejecuciones anteriores se filtren al anuncio actual. - Las respuestas de anuncio conservan el enrutamiento de hilo/tema cuando está disponible en los adaptadores de canal. -- El contexto de anuncio se normaliza en un bloque de evento interno estable: +- El contexto del anuncio se normaliza a un bloque estable de evento interno: - origen (`subagent` o `cron`) - - clave/id de la sesión hija + - clave/id de sesión hija - tipo de anuncio + etiqueta de tarea - - línea de estado derivada del resultado del runtime (`success`, `error`, `timeout` o `unknown`) - - contenido del resultado seleccionado del último texto visible del asistente, o en su defecto texto saneado del último tool/toolResult - - una instrucción de seguimiento que describe cuándo responder frente a permanecer en silencio -- `Status` no se infiere a partir de la salida del modelo; proviene de señales del resultado del runtime. -- En caso de tiempo de espera, si el hijo solo llegó a completar llamadas de herramientas, el anuncio puede condensar ese historial en un breve resumen de progreso parcial en lugar de reproducir salida sin procesar de herramientas. + - línea de estado derivada del resultado del runtime (`success`, `error`, `timeout`, o `unknown`) + - contenido del resultado seleccionado a partir del último texto visible del asistente, o en su defecto del texto saneado más reciente de tool/toolResult; las ejecuciones fallidas terminales informan el estado de error sin reproducir el texto de respuesta capturado + - una instrucción de seguimiento que describe cuándo responder frente a cuándo permanecer en silencio +- `Status` no se infiere de la salida del modelo; proviene de señales del resultado del runtime. +- En caso de tiempo de espera, si el hijo solo llegó a realizar llamadas a herramientas, el anuncio puede contraer ese historial en un breve resumen de progreso parcial en lugar de reproducir la salida bruta de las herramientas. -Las cargas útiles del anuncio incluyen una línea de estadísticas al final (incluso cuando van envueltas): +Las cargas útiles del anuncio incluyen una línea de estadísticas al final (incluso cuando están envueltas): - Runtime (por ejemplo, `runtime 5m12s`) - Uso de tokens (entrada/salida/total) - Costo estimado cuando el precio del modelo está configurado (`models.providers.*.models[].cost`) -- `sessionKey`, `sessionId` y ruta de la transcripción (para que el agente principal pueda recuperar el historial mediante `sessions_history` o inspeccionar el archivo en disco) -- Los metadatos internos están pensados solo para orquestación; las respuestas orientadas al usuario deben reescribirse en voz normal de asistente. +- `sessionKey`, `sessionId` y la ruta de la transcripción (para que el agente principal pueda recuperar el historial mediante `sessions_history` o inspeccionar el archivo en disco) +- Los metadatos internos están pensados solo para orquestación; las respuestas orientadas al usuario deben reescribirse con voz normal de asistente. `sessions_history` es la ruta de orquestación más segura: - la recuperación del asistente se normaliza primero: - - se eliminan las etiquetas de thinking + - se eliminan las etiquetas de pensamiento - se eliminan los bloques de andamiaje `` / `` - - se eliminan bloques de carga útil XML de llamada a herramientas en texto plano, como `...`, - `...`, `...` y - `...`, incluidas las - cargas truncadas que nunca se cierran limpiamente - - se elimina el andamiaje degradado de llamada/resultado de herramientas y los marcadores de contexto histórico - - se eliminan tokens filtrados de control del modelo como `<|assistant|>`, otros tokens ASCII - `<|...|>` y variantes de ancho completo `<｜...｜>` - - se elimina XML malformado de llamada a herramientas de MiniMax -- el texto parecido a credenciales/tokens se redacta + - se eliminan los bloques de carga útil XML de llamadas a herramientas en texto plano como `...`, `...`, `...` y `...`, incluidas las cargas truncadas que nunca se cierran correctamente + - se eliminan el andamiaje degradado de llamadas/resultados de herramientas y los marcadores de contexto histórico + - se eliminan los tokens de control del modelo filtrados, como `<|assistant|>`, otros tokens ASCII `<|...|>`, y las variantes de ancho completo `<｜...｜>` + - se elimina el XML malformado de llamadas a herramientas de MiniMax +- se redacta el texto similar a credenciales/tokens - los bloques largos pueden truncarse -- los historiales muy grandes pueden eliminar filas antiguas o sustituir una fila sobredimensionada por - `[sessions_history omitted: message too large]` -- la inspección de la transcripción sin procesar en disco es la alternativa cuando necesitas la transcripción completa byte por byte +- los historiales muy grandes pueden omitir filas antiguas o reemplazar una fila sobredimensionada por `[sessions_history omitted: message too large]` +- la inspección de la transcripción bruta en disco es la alternativa cuando necesitas la transcripción completa byte por byte -## Política de herramientas (herramientas de subagente) +## Política de herramientas (herramientas de subagentes) -De forma predeterminada, los subagentes obtienen **todas las herramientas excepto las herramientas de sesión** y las herramientas del sistema: +De forma predeterminada, los subagentes reciben **todas las herramientas excepto las herramientas de sesión** y las herramientas de sistema: - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -Aquí también `sessions_history` sigue siendo una vista de recuperación acotada y saneada; no es -un volcado de transcripción sin procesar. +`sessions_history` aquí también sigue siendo una vista de recuperación acotada y saneada; no es un volcado bruto de la transcripción. -Cuando `maxSpawnDepth >= 2`, los subagentes orquestadores de profundidad 1 reciben además `sessions_spawn`, `subagents`, `sessions_list` y `sessions_history` para poder gestionar sus hijos. +Cuando `maxSpawnDepth >= 2`, los subagentes orquestadores de profundidad 1 reciben además `sessions_spawn`, `subagents`, `sessions_list` y `sessions_history` para poder gestionar a sus hijos. -Anúlalo mediante configuración: +Anulación mediante configuración: ```json5 { @@ -316,9 +302,9 @@ Anúlalo mediante configuración: tools: { subagents: { tools: { - // deny wins + // deny gana deny: ["gateway", "cron"], - // if allow is set, it becomes allow-only (deny still wins) + // si se establece allow, pasa a ser solo allow (deny sigue ganando) // allow: ["read", "exec", "process"] }, }, @@ -335,14 +321,14 @@ Los subagentes usan un carril de cola dedicado dentro del proceso: ## Detención -- Enviar `/stop` en el chat solicitante aborta la sesión solicitante y detiene cualquier ejecución activa de subagente generada a partir de ella, propagándose a hijos anidados. +- Enviar `/stop` en el chat del solicitante aborta la sesión del solicitante y detiene cualquier ejecución activa de subagente creada desde ella, propagándose a hijos anidados. - `/subagents kill ` detiene un subagente específico y se propaga a sus hijos. ## Limitaciones -- El anuncio del subagente es **best-effort**. Si el gateway se reinicia, se pierde el trabajo pendiente de “anunciar de vuelta”. -- Los subagentes siguen compartiendo los mismos recursos del proceso del gateway; trata `maxConcurrent` como una válvula de seguridad. -- `sessions_spawn` siempre es no bloqueante: devuelve `{ status: "accepted", runId, childSessionKey }` inmediatamente. +- El anuncio de subagente es **en el mejor de los casos**. Si el Gateway se reinicia, se pierde el trabajo pendiente de "anunciar de vuelta". +- Los subagentes siguen compartiendo los mismos recursos del proceso Gateway; trata `maxConcurrent` como una válvula de seguridad. +- `sessions_spawn` siempre es no bloqueante: devuelve `{ status: "accepted", runId, childSessionKey }` de inmediato. - El contexto del subagente solo inyecta `AGENTS.md` + `TOOLS.md` (no `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ni `BOOTSTRAP.md`). -- La profundidad máxima de anidamiento es 5 (rango de `maxSpawnDepth`: 1–5). Se recomienda profundidad 2 para la mayoría de los casos de uso. +- La profundidad máxima de anidación es 5 (rango de `maxSpawnDepth`: 1–5). Se recomienda profundidad 2 para la mayoría de los casos de uso. - `maxChildrenPerAgent` limita los hijos activos por sesión (predeterminado: 5, rango: 1–20). diff --git a/docs/es/tools/thinking.md b/docs/es/tools/thinking.md index 8e2db8f25..d99bb31f4 100644 --- a/docs/es/tools/thinking.md +++ b/docs/es/tools/thinking.md @@ -1,131 +1,131 @@ --- read_when: - - Ajuste del análisis o los valores predeterminados de las directivas de thinking, modo rápido o detalle + - Ajustar el análisis o los valores predeterminados de las directivas de razonamiento, modo rápido o detallado summary: Sintaxis de directivas para /think, /fast, /verbose, /trace y visibilidad del razonamiento -title: Niveles de thinking +title: Niveles de razonamiento x-i18n: - generated_at: "2026-04-21T13:39:23Z" + generated_at: "2026-04-21T19:20:52Z" model: gpt-5.4 provider: openai - source_hash: 1b0217f6e5a5cb3400090f31ad5271ca61848a40f77d3f942851e7c2f2352886 + source_hash: c77f6f1318c428bbd21725ea5f32f8088506a10cbbf5b5cbca5973c72a5a81f9 source_path: tools/thinking.md workflow: 15 --- -# Niveles de thinking (directivas `/think`) +# Niveles de razonamiento (directivas `/think`) ## Qué hace -- Directiva inline en cualquier cuerpo entrante: `/t `, `/think:` o `/thinking `. +- Directiva en línea en cualquier cuerpo entrante: `/t `, `/think:` o `/thinking `. - Niveles (alias): `off | minimal | low | medium | high | xhigh | adaptive | max` - - minimal → “think” - - low → “think hard” - - medium → “think harder” + - minimal → “pensar” + - low → “pensar intensamente” + - medium → “pensar más intensamente” - high → “ultrathink” (presupuesto máximo) - xhigh → “ultrathink+” (esfuerzo de GPT-5.2 + modelos Codex y Anthropic Claude Opus 4.7) - - adaptive → thinking adaptativo gestionado por el proveedor (compatible con Claude 4.6 en Anthropic/Bedrock y Anthropic Claude Opus 4.7) + - adaptive → razonamiento adaptativo gestionado por el proveedor (compatible con Claude 4.6 en Anthropic/Bedrock y Anthropic Claude Opus 4.7) - max → razonamiento máximo del proveedor (actualmente Anthropic Claude Opus 4.7) - `x-high`, `x_high`, `extra-high`, `extra high` y `extra_high` se asignan a `xhigh`. - `highest` se asigna a `high`. -- Notas del proveedor: - - Los menús y selectores de thinking dependen del perfil del proveedor. Los plugins de proveedor declaran el conjunto exacto de niveles para el modelo seleccionado, incluidas etiquetas como el binario `on`. +- Notas sobre proveedores: + - Los menús y selectores de razonamiento están controlados por el perfil del proveedor. Los plugins del proveedor declaran el conjunto exacto de niveles para el modelo seleccionado, incluidas etiquetas como el binario `on`. - `adaptive`, `xhigh` y `max` solo se anuncian para perfiles de proveedor/modelo que los admiten. Las directivas escritas para niveles no compatibles se rechazan con las opciones válidas de ese modelo. - - Los niveles no compatibles ya almacenados, incluidos los valores antiguos `max` después de cambiar de modelo, se reasignan al nivel compatible más alto para el modelo seleccionado. - - Los modelos Anthropic Claude 4.6 usan `adaptive` de forma predeterminada cuando no se establece un nivel explícito de thinking. - - Anthropic Claude Opus 4.7 no usa thinking adaptativo de forma predeterminada. El valor predeterminado de esfuerzo de su API sigue siendo gestionado por el proveedor salvo que establezcas explícitamente un nivel de thinking. - - Anthropic Claude Opus 4.7 asigna `/think xhigh` a thinking adaptativo más `output_config.effort: "xhigh"`, porque `/think` es una directiva de thinking y `xhigh` es la configuración de esfuerzo de Opus 4.7. - - Anthropic Claude Opus 4.7 también expone `/think max`; se asigna a la misma ruta de esfuerzo máximo gestionada por el proveedor. - - Los modelos OpenAI GPT asignan `/think` mediante la compatibilidad de esfuerzo de la API Responses específica de cada modelo. `/think off` envía `reasoning.effort: "none"` solo cuando el modelo de destino lo admite; de lo contrario, OpenClaw omite el payload de razonamiento desactivado en lugar de enviar un valor no compatible. - - MiniMax (`minimax/*`) en la ruta de streaming compatible con Anthropic usa por defecto `thinking: { type: "disabled" }` salvo que establezcas explícitamente thinking en los parámetros del modelo o de la solicitud. Esto evita deltas filtrados de `reasoning_content` del formato de stream Anthropic no nativo de MiniMax. - - Z.AI (`zai/*`) solo admite thinking binario (`on`/`off`). Cualquier nivel distinto de `off` se trata como `on` (asignado a `low`). - - Moonshot (`moonshot/*`) asigna `/think off` a `thinking: { type: "disabled" }` y cualquier nivel distinto de `off` a `thinking: { type: "enabled" }`. Cuando thinking está habilitado, Moonshot solo acepta `tool_choice` `auto|none`; OpenClaw normaliza los valores incompatibles a `auto`. + - Los niveles incompatibles ya almacenados se reasignan según el rango del perfil del proveedor. `adaptive` vuelve a `medium` en modelos no adaptativos, mientras que `xhigh` y `max` vuelven al mayor nivel compatible distinto de `off` para el modelo seleccionado. + - Los modelos Anthropic Claude 4.6 usan `adaptive` de forma predeterminada cuando no se establece un nivel de razonamiento explícito. + - Anthropic Claude Opus 4.7 no usa razonamiento adaptativo de forma predeterminada. El valor predeterminado de esfuerzo de su API sigue siendo propiedad del proveedor, a menos que establezca explícitamente un nivel de razonamiento. + - Anthropic Claude Opus 4.7 asigna `/think xhigh` a razonamiento adaptativo más `output_config.effort: "xhigh"`, porque `/think` es una directiva de razonamiento y `xhigh` es la configuración de esfuerzo de Opus 4.7. + - Anthropic Claude Opus 4.7 también expone `/think max`; se asigna a la misma ruta de esfuerzo máximo propiedad del proveedor. + - Los modelos OpenAI GPT asignan `/think` mediante la compatibilidad específica del modelo con `effort` de la API Responses. `/think off` envía `reasoning.effort: "none"` solo cuando el modelo de destino lo admite; de lo contrario, OpenClaw omite la carga útil de razonamiento deshabilitado en lugar de enviar un valor no compatible. + - MiniMax (`minimax/*`) en la ruta de streaming compatible con Anthropic usa de forma predeterminada `thinking: { type: "disabled" }`, a menos que establezca explícitamente el razonamiento en los parámetros del modelo o de la solicitud. Esto evita deltas filtrados de `reasoning_content` del formato de stream no nativo de Anthropic de MiniMax. + - Z.AI (`zai/*`) solo admite razonamiento binario (`on`/`off`). Cualquier nivel distinto de `off` se trata como `on` (asignado a `low`). + - Moonshot (`moonshot/*`) asigna `/think off` a `thinking: { type: "disabled" }` y cualquier nivel distinto de `off` a `thinking: { type: "enabled" }`. Cuando el razonamiento está habilitado, Moonshot solo acepta `tool_choice` `auto|none`; OpenClaw normaliza los valores incompatibles a `auto`. ## Orden de resolución -1. Directiva inline en el mensaje (se aplica solo a ese mensaje). -2. Anulación de sesión (se establece enviando un mensaje que solo contiene la directiva). +1. Directiva en línea en el mensaje (se aplica solo a ese mensaje). +2. Anulación de sesión (establecida al enviar un mensaje que contiene solo la directiva). 3. Valor predeterminado por agente (`agents.list[].thinkingDefault` en la configuración). 4. Valor predeterminado global (`agents.defaults.thinkingDefault` en la configuración). -5. Fallback: valor predeterminado declarado por el proveedor cuando está disponible, `low` para otros modelos del catálogo marcados como compatibles con razonamiento, `off` en caso contrario. +5. Alternativa: valor predeterminado declarado por el proveedor cuando está disponible, `low` para otros modelos del catálogo marcados como compatibles con razonamiento y `off` en caso contrario. ## Establecer un valor predeterminado de sesión -- Envía un mensaje que sea **solo** la directiva (se permiten espacios), por ejemplo `/think:medium` o `/t high`. -- Esto permanece para la sesión actual (por remitente de forma predeterminada); se borra con `/think:off` o con el restablecimiento por inactividad de la sesión. -- Se envía una respuesta de confirmación (`Thinking level set to high.` / `Thinking disabled.`). Si el nivel no es válido (por ejemplo `/thinking big`), el comando se rechaza con una sugerencia y el estado de la sesión se deja sin cambios. -- Envía `/think` (o `/think:`) sin argumento para ver el nivel actual de thinking. +- Envíe un mensaje que sea **solo** la directiva (se permiten espacios), por ejemplo `/think:medium` o `/t high`. +- Esto se mantiene para la sesión actual (por remitente de forma predeterminada); se borra con `/think:off` o al restablecerse la sesión por inactividad. +- Se envía una respuesta de confirmación (`Thinking level set to high.` / `Thinking disabled.`). Si el nivel no es válido (por ejemplo `/thinking big`), el comando se rechaza con una sugerencia y el estado de la sesión no cambia. +- Envíe `/think` (o `/think:`) sin argumento para ver el nivel de razonamiento actual. ## Aplicación por agente -- **Embedded Pi**: el nivel resuelto se pasa al runtime del agente Pi en proceso. +- **Pi integrado**: el nivel resuelto se pasa al runtime del agente Pi en proceso. ## Modo rápido (/fast) - Niveles: `on|off`. -- Un mensaje que solo contiene la directiva activa una anulación de modo rápido de sesión y responde `Fast mode enabled.` / `Fast mode disabled.`. -- Envía `/fast` (o `/fast status`) sin modo para ver el estado efectivo actual del modo rápido. +- Un mensaje que contiene solo la directiva activa o desactiva una anulación de modo rápido para la sesión y responde `Fast mode enabled.` / `Fast mode disabled.`. +- Envíe `/fast` (o `/fast status`) sin modo para ver el estado efectivo actual del modo rápido. - OpenClaw resuelve el modo rápido en este orden: - 1. `/fast on|off` inline/solo-directiva + 1. `/fast on|off` en línea o como única directiva 2. Anulación de sesión 3. Valor predeterminado por agente (`agents.list[].fastModeDefault`) 4. Configuración por modelo: `agents.defaults.models["/"].params.fastMode` - 5. Fallback: `off` + 5. Alternativa: `off` - Para `openai/*`, el modo rápido se asigna al procesamiento prioritario de OpenAI enviando `service_tier=priority` en las solicitudes Responses compatibles. -- Para `openai-codex/*`, el modo rápido envía la misma marca `service_tier=priority` en Codex Responses. OpenClaw mantiene un único interruptor compartido `/fast` en ambas rutas de autenticación. +- Para `openai-codex/*`, el modo rápido envía la misma marca `service_tier=priority` en Codex Responses. OpenClaw mantiene un único conmutador `/fast` compartido entre ambas rutas de autenticación. - Para solicitudes públicas directas `anthropic/*`, incluido el tráfico autenticado con OAuth enviado a `api.anthropic.com`, el modo rápido se asigna a los niveles de servicio de Anthropic: `/fast on` establece `service_tier=auto`, `/fast off` establece `service_tier=standard_only`. -- Para `minimax/*` en la ruta compatible con Anthropic, `/fast on` (o `params.fastMode: true`) reescribe `MiniMax-M2.7` a `MiniMax-M2.7-highspeed`. -- Los parámetros explícitos de modelo Anthropic `serviceTier` / `service_tier` anulan el valor predeterminado del modo rápido cuando ambos están configurados. OpenClaw sigue omitiendo la inyección de nivel de servicio de Anthropic para URL base proxy no Anthropic. +- Para `minimax/*` en la ruta compatible con Anthropic, `/fast on` (o `params.fastMode: true`) reescribe `MiniMax-M2.7` como `MiniMax-M2.7-highspeed`. +- Los parámetros explícitos del modelo Anthropic `serviceTier` / `service_tier` anulan el valor predeterminado del modo rápido cuando ambos están configurados. OpenClaw sigue omitiendo la inyección del nivel de servicio de Anthropic para URL base proxy que no sean de Anthropic. -## Directivas de detalle (/verbose o /v) +## Directivas detalladas (/verbose o /v) - Niveles: `on` (mínimo) | `full` | `off` (predeterminado). -- Un mensaje que solo contiene la directiva activa el detalle de la sesión y responde `Verbose logging enabled.` / `Verbose logging disabled.`; los niveles no válidos devuelven una sugerencia sin cambiar el estado. -- `/verbose off` almacena una anulación explícita de sesión; bórrala mediante la UI de Sessions eligiendo `inherit`. -- La directiva inline afecta solo a ese mensaje; en otros casos se aplican los valores predeterminados de sesión/globales. -- Envía `/verbose` (o `/verbose:`) sin argumento para ver el nivel actual de detalle. -- Cuando el detalle está activado, los agentes que emiten resultados estructurados de herramientas (Pi, otros agentes JSON) envían cada llamada de herramienta de vuelta como su propio mensaje solo de metadatos, con el prefijo ` : ` cuando esté disponible (ruta/comando). Estos resúmenes de herramientas se envían en cuanto se inicia cada herramienta (burbujas separadas), no como deltas de streaming. -- Los resúmenes de fallos de herramientas siguen siendo visibles en modo normal, pero los sufijos de detalle de error sin procesar se ocultan salvo que verbose esté en `on` o `full`. -- Cuando verbose es `full`, las salidas de herramientas también se reenvían al finalizar (burbuja separada, truncada a una longitud segura). Si cambias `/verbose on|full|off` mientras una ejecución está en curso, las burbujas de herramientas posteriores respetan la nueva configuración. +- Un mensaje que contiene solo la directiva activa el modo detallado de la sesión y responde `Verbose logging enabled.` / `Verbose logging disabled.`; los niveles no válidos devuelven una sugerencia sin cambiar el estado. +- `/verbose off` almacena una anulación explícita de sesión; bórrela mediante la UI de sesiones eligiendo `inherit`. +- La directiva en línea afecta solo a ese mensaje; en otros casos se aplican los valores predeterminados de sesión/globales. +- Envíe `/verbose` (o `/verbose:`) sin argumento para ver el nivel detallado actual. +- Cuando el modo detallado está activado, los agentes que emiten resultados estructurados de herramientas (Pi, otros agentes JSON) envían cada llamada de herramienta como su propio mensaje solo de metadatos, con el prefijo ` : ` cuando está disponible (ruta/comando). Estos resúmenes de herramientas se envían en cuanto cada herramienta empieza (burbujas separadas), no como deltas de streaming. +- Los resúmenes de fallos de herramientas siguen siendo visibles en modo normal, pero los sufijos con detalles de error sin procesar se ocultan a menos que el modo detallado sea `on` o `full`. +- Cuando el modo detallado es `full`, las salidas de herramientas también se reenvían tras completarse (burbuja separada, truncada a una longitud segura). Si cambia `/verbose on|full|off` mientras una ejecución está en curso, las burbujas de herramientas posteriores respetarán la nueva configuración. ## Directivas de rastreo de plugins (/trace) - Niveles: `on` | `off` (predeterminado). -- Un mensaje que solo contiene la directiva activa la salida de rastreo de plugins de la sesión y responde `Plugin trace enabled.` / `Plugin trace disabled.`. -- La directiva inline afecta solo a ese mensaje; en otros casos se aplican los valores predeterminados de sesión/globales. -- Envía `/trace` (o `/trace:`) sin argumento para ver el nivel actual de rastreo. -- `/trace` es más limitado que `/verbose`: solo expone líneas de rastreo/depuración controladas por plugins, como resúmenes de depuración de Active Memory. +- Un mensaje que contiene solo la directiva activa la salida de rastreo de plugins de la sesión y responde `Plugin trace enabled.` / `Plugin trace disabled.`. +- La directiva en línea afecta solo a ese mensaje; en otros casos se aplican los valores predeterminados de sesión/globales. +- Envíe `/trace` (o `/trace:`) sin argumento para ver el nivel de rastreo actual. +- `/trace` es más específico que `/verbose`: solo expone líneas de rastreo/depuración propiedad del plugin, como los resúmenes de depuración de Active Memory. - Las líneas de rastreo pueden aparecer en `/status` y como mensaje de diagnóstico de seguimiento después de la respuesta normal del asistente. ## Visibilidad del razonamiento (/reasoning) - Niveles: `on|off|stream`. -- Un mensaje que solo contiene la directiva activa si los bloques de thinking se muestran en las respuestas. +- Un mensaje que contiene solo la directiva activa o desactiva si los bloques de razonamiento se muestran en las respuestas. - Cuando está habilitado, el razonamiento se envía como un **mensaje separado** con el prefijo `Reasoning:`. - `stream` (solo Telegram): transmite el razonamiento en la burbuja de borrador de Telegram mientras se genera la respuesta y luego envía la respuesta final sin razonamiento. - Alias: `/reason`. -- Envía `/reasoning` (o `/reasoning:`) sin argumento para ver el nivel actual de razonamiento. -- Orden de resolución: directiva inline, luego anulación de sesión, luego valor predeterminado por agente (`agents.list[].reasoningDefault`) y luego fallback (`off`). +- Envíe `/reasoning` (o `/reasoning:`) sin argumento para ver el nivel actual de razonamiento. +- Orden de resolución: directiva en línea, luego anulación de sesión, luego valor predeterminado por agente (`agents.list[].reasoningDefault`) y luego alternativa (`off`). ## Relacionado -- La documentación del modo elevado se encuentra en [Elevated mode](/es/tools/elevated). +- La documentación del modo elevado está en [Modo elevado](/es/tools/elevated). ## Heartbeats -- El cuerpo de la sonda de Heartbeat es el prompt de heartbeat configurado (predeterminado: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Las directivas inline en un mensaje heartbeat se aplican como de costumbre (pero evita cambiar los valores predeterminados de sesión desde heartbeats). -- La entrega de Heartbeat usa por defecto solo el payload final. Para enviar también el mensaje separado `Reasoning:` (cuando esté disponible), establece `agents.defaults.heartbeat.includeReasoning: true` o `agents.list[].heartbeat.includeReasoning: true` por agente. +- El cuerpo de la sonda de Heartbeat es la indicación de heartbeat configurada (predeterminada: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Las directivas en línea en un mensaje de heartbeat se aplican como de costumbre (pero evite cambiar los valores predeterminados de sesión desde heartbeats). +- La entrega de Heartbeat usa de forma predeterminada solo la carga útil final. Para enviar también el mensaje separado `Reasoning:` (cuando esté disponible), configure `agents.defaults.heartbeat.includeReasoning: true` o `agents.list[].heartbeat.includeReasoning: true` por agente. -## UI de chat web +## UI del chat web -- El selector de thinking del chat web refleja el nivel almacenado de la sesión desde el almacén/configuración de sesión entrante cuando se carga la página. -- Elegir otro nivel escribe inmediatamente la anulación de sesión mediante `sessions.patch`; no espera al siguiente envío y no es una anulación puntual `thinkingOnce`. -- La primera opción es siempre `Default ()`, donde el valor predeterminado resuelto proviene del perfil de thinking del proveedor del modelo activo de la sesión. -- El selector usa `thinkingOptions` devuelto por la fila de sesión del gateway. La UI del navegador no mantiene su propia lista regex de proveedores; los plugins se encargan de los conjuntos de niveles específicos de cada modelo. -- `/think:` sigue funcionando y actualiza el mismo nivel almacenado de sesión, por lo que las directivas de chat y el selector permanecen sincronizados. +- El selector de razonamiento del chat web refleja el nivel almacenado de la sesión desde el almacén/configuración de sesión entrante cuando se carga la página. +- Elegir otro nivel escribe inmediatamente la anulación de la sesión mediante `sessions.patch`; no espera al siguiente envío y no es una anulación de un solo uso `thinkingOnce`. +- La primera opción siempre es `Default ()`, donde el valor predeterminado resuelto proviene del perfil de razonamiento del proveedor del modelo activo de la sesión. +- El selector usa `thinkingOptions` devuelto por la fila de sesión del gateway. La UI del navegador no mantiene su propia lista regex de proveedores; los plugins son propietarios de los conjuntos de niveles específicos del modelo. +- `/think:` sigue funcionando y actualiza el mismo nivel almacenado de la sesión, de modo que las directivas del chat y el selector permanecen sincronizados. -## Perfiles de proveedor +## Perfiles del proveedor -- Los plugins de proveedor pueden exponer `resolveThinkingProfile(ctx)` para definir los niveles compatibles y el valor predeterminado del modelo. -- Cada nivel de perfil tiene un `id` canónico almacenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` o `max`) y puede incluir una `label` para mostrar. Los proveedores binarios usan `{ id: "low", label: "on" }`. +- Los plugins del proveedor pueden exponer `resolveThinkingProfile(ctx)` para definir los niveles compatibles y el valor predeterminado del modelo. +- Cada nivel del perfil tiene un `id` canónico almacenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` o `max`) y puede incluir una `label` de visualización. Los proveedores binarios usan `{ id: "low", label: "on" }`. - Los hooks heredados publicados (`supportsXHighThinking`, `isBinaryThinking` y `resolveDefaultThinkingLevel`) siguen existiendo como adaptadores de compatibilidad, pero los nuevos conjuntos de niveles personalizados deben usar `resolveThinkingProfile`. -- Las filas del Gateway exponen `thinkingOptions` y `thinkingDefault` para que los clientes ACP/chat muestren el mismo perfil que usa la validación del runtime. +- Las filas del Gateway exponen `thinkingOptions` y `thinkingDefault` para que los clientes ACP/chat representen el mismo perfil que usa la validación en tiempo de ejecución.