From cfa2d9c97024b5f7687c0dc2a63214d9fb99e798 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 18 Apr 2026 05:07:22 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/concepts/agent-workspace.md | 137 +- docs/es/concepts/context.md | 134 +- docs/es/concepts/qa-e2e-automation.md | 188 ++- docs/es/concepts/system-prompt.md | 144 ++- docs/es/gateway/configuration-reference.md | 1353 ++++++++++---------- docs/es/gateway/protocol.md | 465 +++---- docs/es/help/testing.md | 791 ++++++------ docs/es/platforms/macos.md | 174 +-- docs/es/plugins/sdk-channel-plugins.md | 339 ++--- docs/es/plugins/sdk-overview.md | 516 ++++---- docs/es/refactor/qa.md | 231 ++-- 11 files changed, 2303 insertions(+), 2169 deletions(-) diff --git a/docs/es/concepts/agent-workspace.md b/docs/es/concepts/agent-workspace.md index 898681765..3706dc13f 100644 --- a/docs/es/concepts/agent-workspace.md +++ b/docs/es/concepts/agent-workspace.md @@ -5,10 +5,10 @@ read_when: summary: 'Espacio de trabajo del agente: ubicación, diseño y estrategia de copia de seguridad' title: Espacio de trabajo del agente x-i18n: - generated_at: "2026-04-05T12:39:30Z" + generated_at: "2026-04-18T04:59:11Z" model: gpt-5.4 provider: openai - source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a + source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e source_path: concepts/agent-workspace.md workflow: 15 --- @@ -16,24 +16,24 @@ x-i18n: # Espacio de trabajo del agente El espacio de trabajo es el hogar del agente. Es el único directorio de trabajo usado para -herramientas de archivos y para el contexto del espacio de trabajo. Mantenlo privado y trátalo como memoria. +las herramientas de archivos y para el contexto del espacio de trabajo. Mantenlo privado y trátalo como memoria. Esto es independiente de `~/.openclaw/`, que almacena configuración, credenciales y sesiones. -**Importante:** el espacio de trabajo es el **cwd predeterminado**, no un sandbox estricto. Las herramientas -resuelven rutas relativas con respecto al espacio de trabajo, pero las rutas absolutas aún pueden llegar -a otras ubicaciones del host a menos que el sandboxing esté habilitado. Si necesitas aislamiento, usa -[`agents.defaults.sandbox`](/gateway/sandboxing) (y/o configuración de sandbox por agente). -Cuando el sandboxing está habilitado y `workspaceAccess` no es `"rw"`, las herramientas operan -dentro de un espacio de trabajo aislado bajo `~/.openclaw/sandboxes`, no en el espacio de trabajo del host. +**Importante:** el espacio de trabajo es el **cwd predeterminado**, no un sandbox rígido. Las herramientas +resuelven las rutas relativas contra el espacio de trabajo, pero las rutas absolutas aún pueden llegar +a otras ubicaciones del host a menos que el sandbox esté habilitado. Si necesitas aislamiento, usa +[`agents.defaults.sandbox`](/es/gateway/sandboxing) (y/o la configuración de sandbox por agente). +Cuando el sandbox está habilitado y `workspaceAccess` no es `"rw"`, las herramientas operan +dentro de un espacio de trabajo aislado bajo `~/.openclaw/sandboxes`, no en tu espacio de trabajo del host. ## Ubicación predeterminada - Predeterminado: `~/.openclaw/workspace` - Si `OPENCLAW_PROFILE` está establecido y no es `"default"`, el valor predeterminado pasa a ser `~/.openclaw/workspace-`. -- Sobrescríbelo en `~/.openclaw/openclaw.json`: +- Puedes sobrescribirlo en `~/.openclaw/openclaw.json`: ```json5 { @@ -44,12 +44,11 @@ dentro de un espacio de trabajo aislado bajo `~/.openclaw/sandboxes`, no en el e ``` `openclaw onboard`, `openclaw configure` o `openclaw setup` crearán el -espacio de trabajo y sembrarán los archivos bootstrap si faltan. -Las copias semilla del sandbox solo aceptan archivos normales dentro del espacio de trabajo; los -alias de symlink/hardlink que se resuelven fuera del espacio de trabajo de origen se ignoran. +espacio de trabajo y sembrarán los archivos de arranque si faltan. +Las copias de siembra del sandbox solo aceptan archivos regulares dentro del espacio de trabajo; +los alias de enlaces simbólicos/enlaces físicos que se resuelven fuera del espacio de trabajo de origen se ignoran. -Si ya gestionas tú mismo los archivos del espacio de trabajo, puedes desactivar la -creación de archivos bootstrap: +Si ya administras tú mismo los archivos del espacio de trabajo, puedes deshabilitar la creación de archivos de arranque: ```json5 { agent: { skipBootstrap: true } } @@ -58,15 +57,15 @@ creación de archivos bootstrap: ## Carpetas adicionales del espacio de trabajo Las instalaciones antiguas pueden haber creado `~/openclaw`. Mantener varios directorios de espacio de trabajo -puede causar confusión por desajustes de autenticación o de estado, porque solo un +puede causar deriva confusa de autenticación o estado, porque solo un espacio de trabajo está activo a la vez. **Recomendación:** mantén un único espacio de trabajo activo. Si ya no usas las -carpetas extra, archívalas o muévelas a la Papelera (por ejemplo `trash ~/openclaw`). -Si intencionadamente mantienes varios espacios de trabajo, asegúrate de que +carpetas adicionales, archívalas o muévelas a la Papelera (por ejemplo `trash ~/openclaw`). +Si intencionalmente mantienes varios espacios de trabajo, asegúrate de que `agents.defaults.workspace` apunte al activo. -`openclaw doctor` avisa cuando detecta directorios adicionales de espacio de trabajo. +`openclaw doctor` advierte cuando detecta directorios adicionales del espacio de trabajo. ## Mapa de archivos del espacio de trabajo (qué significa cada archivo) @@ -75,88 +74,88 @@ Estos son los archivos estándar que OpenClaw espera dentro del espacio de traba - `AGENTS.md` - Instrucciones operativas para el agente y cómo debe usar la memoria. - Se carga al inicio de cada sesión. - - Buen lugar para reglas, prioridades y detalles de "cómo comportarse". + - Buen lugar para reglas, prioridades y detalles sobre "cómo comportarse". - `SOUL.md` - Personalidad, tono y límites. - Se carga en cada sesión. - - Guía: [Guía de personalidad de SOUL.md](/concepts/soul) + - Guía: [Guía de personalidad de SOUL.md](/es/concepts/soul) - `USER.md` - Quién es el usuario y cómo dirigirse a él. - Se carga en cada sesión. - `IDENTITY.md` - - El nombre, estilo y emoji del agente. - - Se crea/actualiza durante el ritual de bootstrap. + - El nombre, la vibra y el emoji del agente. + - Se crea/actualiza durante el ritual de arranque. - `TOOLS.md` - - Notas sobre tus herramientas y convenciones locales. + - Notas sobre tus herramientas locales y convenciones. - No controla la disponibilidad de herramientas; es solo orientación. - `HEARTBEAT.md` - - Lista de comprobación opcional y pequeña para ejecuciones de heartbeat. - - Mantenla breve para evitar gastar tokens. + - Lista de verificación opcional y pequeña para ejecuciones de Heartbeat. + - Mantenla breve para evitar gasto de tokens. - `BOOT.md` - - Lista de comprobación opcional de arranque ejecutada al reiniciar la gateway cuando los hooks internos están habilitados. + - Lista de verificación opcional de inicio ejecutada al reiniciar el Gateway cuando los hooks internos están habilitados. - Mantenla breve; usa la herramienta de mensajes para envíos salientes. - `BOOTSTRAP.md` - - Ritual único de la primera ejecución. + - Ritual único de primera ejecución. - Solo se crea para un espacio de trabajo completamente nuevo. - - Elimínalo cuando el ritual haya terminado. + - Elimínalo una vez que el ritual esté completo. - `memory/YYYY-MM-DD.md` - Registro diario de memoria (un archivo por día). - - Se recomienda leer el de hoy y el de ayer al inicio de la sesión. + - Se recomienda leer el de hoy y el de ayer al iniciar la sesión. - `MEMORY.md` (opcional) - Memoria de largo plazo curada. - Cárgala solo en la sesión principal y privada (no en contextos compartidos/de grupo). -Consulta [Memory](/concepts/memory) para ver el flujo de trabajo y el vaciado automático de memoria. +Consulta [Memory](/es/concepts/memory) para el flujo de trabajo y el volcado automático de memoria. - `skills/` (opcional) - - Skills específicas del espacio de trabajo. + - Skills específicos del espacio de trabajo. - Ubicación de Skills de mayor precedencia para ese espacio de trabajo. - - Sobrescribe Skills de agentes del proyecto, Skills de agentes personales, Skills gestionadas, Skills integradas y `skills.load.extraDirs` cuando los nombres colisionan. + - Sobrescribe Skills del agente del proyecto, Skills personales del agente, Skills administrados, Skills incluidos y `skills.load.extraDirs` cuando los nombres coinciden. - `canvas/` (opcional) - - Archivos de UI de canvas para pantallas de nodo (por ejemplo `canvas/index.html`). + - Archivos de la interfaz Canvas para visualizaciones de nodos (por ejemplo `canvas/index.html`). -Si falta cualquier archivo bootstrap, OpenClaw inyecta un marcador de "archivo faltante" en -la sesión y continúa. Los archivos bootstrap grandes se truncan al inyectarse; -ajusta los límites con `agents.defaults.bootstrapMaxChars` (predeterminado: 20000) y -`agents.defaults.bootstrapTotalMaxChars` (predeterminado: 150000). -`openclaw setup` puede recrear los valores predeterminados que falten sin sobrescribir +Si falta algún archivo de arranque, OpenClaw inserta un marcador de "archivo faltante" en +la sesión y continúa. Los archivos de arranque grandes se truncan al insertarse; +ajusta los límites con `agents.defaults.bootstrapMaxChars` (predeterminado: 12000) y +`agents.defaults.bootstrapTotalMaxChars` (predeterminado: 60000). +`openclaw setup` puede recrear los valores predeterminados faltantes sin sobrescribir los archivos existentes. ## Lo que NO está en el espacio de trabajo -Esto vive bajo `~/.openclaw/` y NO debe confirmarse en el repositorio del espacio de trabajo: +Estos elementos viven bajo `~/.openclaw/` y NO deben confirmarse en el repositorio del espacio de trabajo: - `~/.openclaw/openclaw.json` (configuración) -- `~/.openclaw/agents//agent/auth-profiles.json` (perfiles de autenticación de modelos: OAuth + API keys) -- `~/.openclaw/credentials/` (estado de canal/proveedor más datos heredados de importación OAuth) -- `~/.openclaw/agents//sessions/` (transcripciones de sesión + metadatos) -- `~/.openclaw/skills/` (Skills gestionadas) +- `~/.openclaw/agents//agent/auth-profiles.json` (perfiles de autenticación del modelo: OAuth + claves API) +- `~/.openclaw/credentials/` (estado de canal/proveedor más datos de importación heredados de OAuth) +- `~/.openclaw/agents//sessions/` (transcripciones de sesiones + metadatos) +- `~/.openclaw/skills/` (Skills administrados) Si necesitas migrar sesiones o configuración, cópialas por separado y mantenlas fuera del control de versiones. ## Copia de seguridad con Git (recomendada, privada) -Trata el espacio de trabajo como memoria privada. Ponlo en un repositorio git **privado** para que esté +Trata el espacio de trabajo como memoria privada. Ponlo en un repositorio de git **privado** para que esté respaldado y sea recuperable. -Ejecuta estos pasos en la máquina donde se ejecuta la Gateway (ahí es donde vive el +Ejecuta estos pasos en la máquina donde se ejecuta el Gateway (ahí es donde vive el espacio de trabajo). -### 1) Inicializar el repositorio +### 1) Inicializa el repositorio Si git está instalado, los espacios de trabajo completamente nuevos se inicializan automáticamente. Si este -espacio de trabajo todavía no es un repositorio, ejecuta: +espacio de trabajo aún no es un repositorio, ejecuta: ```bash cd ~/.openclaw/workspace @@ -165,12 +164,12 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ git commit -m "Add agent workspace" ``` -### 2) Añadir un remoto privado (opciones sencillas para principiantes) +### 2) Añade un remoto privado (opciones amigables para principiantes) Opción A: interfaz web de GitHub -1. Crea un nuevo repositorio **privado** en GitHub. -2. No lo inicialices con un README (evita conflictos de merge). +1. Crea un repositorio **privado** nuevo en GitHub. +2. No lo inicialices con un README (evita conflictos de fusión). 3. Copia la URL remota HTTPS. 4. Añade el remoto y haz push: @@ -189,8 +188,8 @@ gh repo create openclaw-workspace --private --source . --remote origin --push Opción C: interfaz web de GitLab -1. Crea un nuevo repositorio **privado** en GitLab. -2. No lo inicialices con un README (evita conflictos de merge). +1. Crea un repositorio **privado** nuevo en GitLab. +2. No lo inicialices con un README (evita conflictos de fusión). 3. Copia la URL remota HTTPS. 4. Añade el remoto y haz push: @@ -213,14 +212,14 @@ git push Incluso en un repositorio privado, evita almacenar secretos en el espacio de trabajo: -- API keys, tokens OAuth, contraseñas o credenciales privadas. +- Claves API, tokens OAuth, contraseñas o credenciales privadas. - Cualquier cosa bajo `~/.openclaw/`. -- Volcados sin procesar de chats o adjuntos sensibles. +- Volcados sin procesar de chats o archivos adjuntos sensibles. -Si debes almacenar referencias sensibles, usa placeholders y guarda el secreto -real en otro lugar (gestor de contraseñas, variables de entorno o `~/.openclaw/`). +Si debes almacenar referencias sensibles, usa marcadores de posición y guarda el secreto real en otra parte +(administrador de contraseñas, variables de entorno o `~/.openclaw/`). -Inicio sugerido para `.gitignore`: +Plantilla sugerida para `.gitignore`: ```gitignore .DS_Store @@ -230,24 +229,24 @@ Inicio sugerido para `.gitignore`: **/secrets* ``` -## Mover el espacio de trabajo a una nueva máquina +## Mover el espacio de trabajo a una máquina nueva 1. Clona el repositorio en la ruta deseada (predeterminada `~/.openclaw/workspace`). 2. Establece `agents.defaults.workspace` en esa ruta dentro de `~/.openclaw/openclaw.json`. 3. Ejecuta `openclaw setup --workspace ` para sembrar cualquier archivo faltante. -4. Si necesitas sesiones, copia `~/.openclaw/agents//sessions/` desde la - máquina antigua por separado. +4. Si necesitas las sesiones, copia `~/.openclaw/agents//sessions/` desde la + máquina anterior por separado. ## Notas avanzadas -- El enrutamiento multiagente puede usar distintos espacios de trabajo por agente. Consulta - [Enrutamiento de canales](/channels/channel-routing) para la configuración de enrutamiento. -- Si `agents.defaults.sandbox` está habilitado, las sesiones no principales pueden usar - espacios de trabajo aislados por sesión bajo `agents.defaults.sandbox.workspaceRoot`. +- El enrutamiento de múltiples agentes puede usar diferentes espacios de trabajo por agente. Consulta + [Enrutamiento de canales](/es/channels/channel-routing) para la configuración de enrutamiento. +- Si `agents.defaults.sandbox` está habilitado, las sesiones no principales pueden usar espacios de trabajo + aislados por sesión bajo `agents.defaults.sandbox.workspaceRoot`. ## Relacionado -- [Órdenes permanentes](/automation/standing-orders) — instrucciones persistentes en archivos del espacio de trabajo -- [Heartbeat](/gateway/heartbeat) — archivo de espacio de trabajo HEARTBEAT.md -- [Sesión](/concepts/session) — rutas de almacenamiento de sesiones -- [Sandboxing](/gateway/sandboxing) — acceso al espacio de trabajo en entornos aislados +- [Standing Orders](/es/automation/standing-orders) — instrucciones persistentes en archivos del espacio de trabajo +- [Heartbeat](/es/gateway/heartbeat) — archivo `HEARTBEAT.md` del espacio de trabajo +- [Session](/es/concepts/session) — rutas de almacenamiento de sesiones +- [Sandboxing](/es/gateway/sandboxing) — acceso al espacio de trabajo en entornos con sandbox diff --git a/docs/es/concepts/context.md b/docs/es/concepts/context.md index eb986b32b..4db9b126f 100644 --- a/docs/es/concepts/context.md +++ b/docs/es/concepts/context.md @@ -1,15 +1,15 @@ --- read_when: - Quieres entender qué significa “contexto” en OpenClaw - - Estás depurando por qué el modelo “sabe” algo (o por qué lo olvidó) + - Estás depurando por qué el modelo “sabe” algo (o lo olvidó) - Quieres reducir la sobrecarga de contexto (`/context`, `/status`, `/compact`) -summary: 'Contexto: lo que ve el modelo, cómo se construye y cómo inspeccionarlo' +summary: 'Contexto: qué ve el modelo, cómo se construye y cómo inspeccionarlo' title: Contexto x-i18n: - generated_at: "2026-04-12T23:28:13Z" + generated_at: "2026-04-18T04:59:12Z" model: gpt-5.4 provider: openai - source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d + source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9 source_path: concepts/context.md workflow: 15 --- @@ -20,21 +20,21 @@ x-i18n: Modelo mental para principiantes: -- **Prompt del sistema** (construido por OpenClaw): reglas, herramientas, lista de Skills, hora/entorno de ejecución y archivos del espacio de trabajo inyectados. -- **Historial de la conversación**: tus mensajes + los mensajes del asistente de esta sesión. +- **Prompt del sistema** (construido por OpenClaw): reglas, herramientas, lista de Skills, tiempo/runtime y archivos del espacio de trabajo inyectados. +- **Historial de la conversación**: tus mensajes + los mensajes del asistente para esta sesión. - **Llamadas/resultados de herramientas + adjuntos**: salida de comandos, lecturas de archivos, imágenes/audio, etc. -El contexto _no es lo mismo_ que la “memoria”: la memoria puede almacenarse en disco y recargarse más tarde; el contexto es lo que está dentro de la ventana actual del modelo. +El contexto _no es lo mismo_ que la “memoria”: la memoria puede almacenarse en disco y volver a cargarse más tarde; el contexto es lo que está dentro de la ventana actual del modelo. ## Inicio rápido (inspeccionar el contexto) - `/status` → vista rápida de “¿qué tan llena está mi ventana?” + configuración de la sesión. - `/context list` → qué está inyectado + tamaños aproximados (por archivo + totales). -- `/context detail` → desglose más profundo: por archivo, tamaños de esquema de herramientas, tamaños de entradas de Skills y tamaño del prompt del sistema. -- `/usage tokens` → agrega un pie de uso por respuesta a las respuestas normales. -- `/compact` → resume el historial más antiguo en una entrada compacta para liberar espacio en la ventana. +- `/context detail` → desglose más profundo: por archivo, tamaños de esquema por herramienta, tamaños de entrada por skill y tamaño del prompt del sistema. +- `/usage tokens` → añade un pie de uso por respuesta a las respuestas normales. +- `/compact` → resume el historial anterior en una entrada compacta para liberar espacio en la ventana. -Consulta también: [Comandos con barra](/es/tools/slash-commands), [Uso de tokens y costos](/es/reference/token-use), [Compaction](/es/concepts/compaction). +Consulta también: [Comandos de barra](/es/tools/slash-commands), [Uso de tokens y costos](/es/reference/token-use), [Compaction](/es/concepts/compaction). ## Salida de ejemplo @@ -43,44 +43,44 @@ Los valores varían según el modelo, el proveedor, la política de herramientas ### `/context list` ``` -🧠 Desglose del contexto -Espacio de trabajo: -Máximo de bootstrap/archivo: 20,000 caracteres +🧠 Context breakdown +Workspace: +Bootstrap max/file: 12,000 chars Sandbox: mode=non-main sandboxed=false -Prompt del sistema (ejecución): 38,412 caracteres (~9,603 tokens) (Contexto del proyecto 23,901 caracteres (~5,976 tokens)) +System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) -Archivos del espacio de trabajo inyectados: -- AGENTS.md: OK | bruto 1,742 caracteres (~436 tokens) | inyectado 1,742 caracteres (~436 tokens) -- SOUL.md: OK | bruto 912 caracteres (~228 tokens) | inyectado 912 caracteres (~228 tokens) -- TOOLS.md: TRUNCATED | bruto 54,210 caracteres (~13,553 tokens) | inyectado 20,962 caracteres (~5,241 tokens) -- IDENTITY.md: OK | bruto 211 caracteres (~53 tokens) | inyectado 211 caracteres (~53 tokens) -- USER.md: OK | bruto 388 caracteres (~97 tokens) | inyectado 388 caracteres (~97 tokens) -- HEARTBEAT.md: MISSING | bruto 0 | inyectado 0 -- BOOTSTRAP.md: OK | 0 caracteres (~0 tokens) | inyectado 0 caracteres (~0 tokens) +Injected workspace files: +- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) +- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) +- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) +- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) +- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) +- HEARTBEAT.md: MISSING | raw 0 | injected 0 +- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) -Lista de Skills (texto del prompt del sistema): 2,184 caracteres (~546 tokens) (12 Skills) -Herramientas: read, edit, write, exec, process, browser, message, sessions_send, … -Lista de herramientas (texto del prompt del sistema): 1,032 caracteres (~258 tokens) -Esquemas de herramientas (JSON): 31,988 caracteres (~7,997 tokens) (cuentan para el contexto; no se muestran como texto) -Herramientas: (igual que arriba) +Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills) +Tools: read, edit, write, exec, process, browser, message, sessions_send, … +Tool list (system prompt text): 1,032 chars (~258 tok) +Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text) +Tools: (same as above) -Tokens de sesión (en caché): 14,250 total / ctx=32,000 +Session tokens (cached): 14,250 total / ctx=32,000 ``` ### `/context detail` ``` -🧠 Desglose del contexto (detallado) +🧠 Context breakdown (detailed) … -Principales Skills (tamaño de entrada del prompt): -- frontend-design: 412 caracteres (~103 tokens) -- oracle: 401 caracteres (~101 tokens) -… (+10 más Skills) +Top skills (prompt entry size): +- frontend-design: 412 chars (~103 tok) +- oracle: 401 chars (~101 tok) +… (+10 more skills) -Principales herramientas (tamaño del esquema): -- browser: 9,812 caracteres (~2,453 tokens) -- exec: 6,240 caracteres (~1,560 tokens) -… (+N más herramientas) +Top tools (schema size): +- browser: 9,812 chars (~2,453 tok) +- exec: 6,240 chars (~1,560 tok) +… (+N more tools) ``` ## Qué cuenta para la ventana de contexto @@ -91,25 +91,25 @@ Todo lo que recibe el modelo cuenta, incluido: - Historial de la conversación. - Llamadas de herramientas + resultados de herramientas. - Adjuntos/transcripciones (imágenes/audio/archivos). -- Resúmenes de Compaction y artefactos de poda. -- “Wrappers” del proveedor o encabezados ocultos (no visibles, pero igualmente cuentan). +- Resúmenes de Compaction y artefactos de pruning. +- “Wrappers” del proveedor o encabezados ocultos (no visibles, pero aun así cuentan). ## Cómo OpenClaw construye el prompt del sistema -El prompt del sistema es **propiedad de OpenClaw** y se reconstruye en cada ejecución. Incluye: +El prompt del sistema **pertenece a OpenClaw** y se reconstruye en cada ejecución. Incluye: - Lista de herramientas + descripciones breves. - Lista de Skills (solo metadatos; ver abajo). - Ubicación del espacio de trabajo. -- Hora (UTC + hora del usuario convertida, si está configurada). -- Metadatos del entorno de ejecución (host/SO/modelo/thinking). -- Archivos bootstrap del espacio de trabajo inyectados bajo **Contexto del proyecto**. +- Hora (UTC + hora del usuario convertida si está configurada). +- Metadatos del runtime (host/OS/modelo/thinking). +- Archivos bootstrap del espacio de trabajo inyectados bajo **Project Context**. Desglose completo: [Prompt del sistema](/es/concepts/system-prompt). -## Archivos del espacio de trabajo inyectados (Contexto del proyecto) +## Archivos del espacio de trabajo inyectados (Project Context) -De forma predeterminada, OpenClaw inyecta un conjunto fijo de archivos del espacio de trabajo (si existen): +De forma predeterminada, OpenClaw inyecta un conjunto fijo de archivos del espacio de trabajo (si están presentes): - `AGENTS.md` - `SOUL.md` @@ -117,17 +117,17 @@ De forma predeterminada, OpenClaw inyecta un conjunto fijo de archivos del espac - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (solo en la primera ejecución) +- `BOOTSTRAP.md` (solo la primera ejecución) -Los archivos grandes se truncan por archivo usando `agents.defaults.bootstrapMaxChars` (valor predeterminado: `20000` caracteres). OpenClaw también aplica un límite total de inyección bootstrap entre archivos con `agents.defaults.bootstrapTotalMaxChars` (valor predeterminado: `150000` caracteres). `/context` muestra los tamaños **bruto vs. inyectado** y si hubo truncamiento. +Los archivos grandes se truncan por archivo usando `agents.defaults.bootstrapMaxChars` (predeterminado `12000` caracteres). OpenClaw también aplica un límite total de inyección bootstrap entre archivos con `agents.defaults.bootstrapTotalMaxChars` (predeterminado `60000` caracteres). `/context` muestra los tamaños **sin procesar vs inyectados** y si ocurrió truncamiento. -Cuando ocurre truncamiento, el entorno de ejecución puede inyectar un bloque de advertencia dentro del prompt en Contexto del proyecto. Configúralo con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; valor predeterminado: `once`). +Cuando ocurre truncamiento, el runtime puede inyectar un bloque de advertencia dentro del prompt en Project Context. Configura esto con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; predeterminado `once`). -## Skills: inyectadas vs. cargadas bajo demanda +## Skills: inyectadas vs cargadas bajo demanda -El prompt del sistema incluye una lista compacta de **Skills** (nombre + descripción + ubicación). Esta lista tiene una sobrecarga real. +El prompt del sistema incluye una **lista de Skills** compacta (nombre + descripción + ubicación). Esta lista tiene una sobrecarga real. -Las instrucciones de Skills _no_ se incluyen de forma predeterminada. Se espera que el modelo use `read` para leer el `SKILL.md` de la Skill **solo cuando sea necesario**. +Las instrucciones de Skill _no_ se incluyen de forma predeterminada. Se espera que el modelo haga `read` del `SKILL.md` de la skill **solo cuando sea necesario**. ## Herramientas: hay dos costos @@ -140,37 +140,37 @@ Las herramientas afectan al contexto de dos maneras: ## Comandos, directivas y "atajos en línea" -Los comandos con barra los gestiona el Gateway. Hay algunos comportamientos diferentes: +Los comandos de barra son manejados por el Gateway. Hay algunos comportamientos diferentes: - **Comandos independientes**: un mensaje que es solo `/...` se ejecuta como comando. - **Directivas**: `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` se eliminan antes de que el modelo vea el mensaje. - - Los mensajes que contienen solo directivas conservan la configuración de la sesión. - - Las directivas en línea dentro de un mensaje normal actúan como sugerencias por mensaje. -- **Atajos en línea** (solo remitentes en allowlist): ciertos tokens `/...` dentro de un mensaje normal pueden ejecutarse inmediatamente (ejemplo: “hey /status”), y se eliminan antes de que el modelo vea el texto restante. + - Los mensajes compuestos solo por directivas conservan la configuración de la sesión. + - Las directivas en línea en un mensaje normal actúan como sugerencias por mensaje. +- **Atajos en línea** (solo remitentes permitidos): ciertos tokens `/...` dentro de un mensaje normal pueden ejecutarse inmediatamente (ejemplo: “hey /status”), y se eliminan antes de que el modelo vea el texto restante. -Detalles: [Comandos con barra](/es/tools/slash-commands). +Detalles: [Comandos de barra](/es/tools/slash-commands). -## Sesiones, Compaction y poda (qué persiste) +## Sesiones, Compaction y pruning (qué persiste) Lo que persiste entre mensajes depende del mecanismo: -- El **historial normal** persiste en la transcripción de la sesión hasta que la política lo compacte o pode. -- **Compaction** conserva un resumen dentro de la transcripción y mantiene intactos los mensajes recientes. -- La **poda** elimina resultados antiguos de herramientas del prompt _en memoria_ para una ejecución, pero no reescribe la transcripción. +- **El historial normal** persiste en la transcripción de la sesión hasta que la política lo compacta/poda. +- **Compaction** conserva un resumen en la transcripción y mantiene intactos los mensajes recientes. +- **Pruning** elimina resultados antiguos de herramientas del prompt _en memoria_ para una ejecución, pero no reescribe la transcripción. -Documentación: [Session](/es/concepts/session), [Compaction](/es/concepts/compaction), [Poda de sesión](/es/concepts/session-pruning). +Documentación: [Sesión](/es/concepts/session), [Compaction](/es/concepts/compaction), [Poda de sesión](/es/concepts/session-pruning). -De forma predeterminada, OpenClaw usa el motor de contexto `legacy` integrado para el ensamblaje y la compactación. Si instalas un Plugin que proporciona `kind: "context-engine"` y lo seleccionas con `plugins.slots.contextEngine`, OpenClaw delega el ensamblaje de contexto, `/compact` y los hooks relacionados del ciclo de vida del contexto de subagentes a ese motor. `ownsCompaction: false` no hace fallback automático al motor legacy; el motor activo igualmente debe implementar `compact()` correctamente. Consulta +De forma predeterminada, OpenClaw usa el motor de contexto `legacy` integrado para el ensamblaje y la compacción. Si instalas un Plugin que proporciona `kind: "context-engine"` y lo seleccionas con `plugins.slots.contextEngine`, OpenClaw delega en ese motor el ensamblaje del contexto, `/compact` y los hooks relacionados del ciclo de vida del contexto del subagente. `ownsCompaction: false` no vuelve automáticamente al motor legacy; el motor activo debe seguir implementando `compact()` correctamente. Consulta [Context Engine](/es/concepts/context-engine) para ver la interfaz conectable completa, los hooks del ciclo de vida y la configuración. ## Qué informa realmente `/context` -`/context` prefiere el informe más reciente del prompt del sistema **construido en una ejecución** cuando está disponible: +`/context` prefiere el informe más reciente del prompt del sistema **construido durante la ejecución** cuando está disponible: -- `System prompt (run)` = capturado de la última ejecución embebida (con capacidad de herramientas) y persistido en el almacén de sesiones. -- `System prompt (estimate)` = calculado sobre la marcha cuando no existe un informe de ejecución (o cuando se ejecuta mediante un backend de CLI que no genera el informe). +- `System prompt (run)` = capturado de la última ejecución embebida (con capacidad de herramientas) y persistido en el almacenamiento de la sesión. +- `System prompt (estimate)` = calculado sobre la marcha cuando no existe un informe de ejecución (o al ejecutarse mediante un backend de CLI que no genera el informe). -En ambos casos, informa tamaños y los principales contribuyentes; no vuelca el prompt completo del sistema ni los esquemas de herramientas. +En cualquier caso, informa tamaños y principales contribuyentes; **no** muestra el prompt completo del sistema ni los esquemas de herramientas. ## Relacionado diff --git a/docs/es/concepts/qa-e2e-automation.md b/docs/es/concepts/qa-e2e-automation.md index e62fd3987..a70fc2df1 100644 --- a/docs/es/concepts/qa-e2e-automation.md +++ b/docs/es/concepts/qa-e2e-automation.md @@ -1,28 +1,32 @@ --- read_when: - - Ampliación de qa-lab o qa-channel + - Ampliar qa-lab o qa-channel - Agregar escenarios de QA respaldados por el repositorio - Crear una automatización de QA de mayor realismo en torno al panel de Gateway -summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con semillas e informes de protocolo +summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con seed e informes de protocolo title: Automatización E2E de QA x-i18n: - generated_at: "2026-04-17T05:13:50Z" + generated_at: "2026-04-18T04:59:15Z" model: gpt-5.4 provider: openai - source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0 + source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automatización E2E de QA -La pila privada de QA está pensada para ejercitar OpenClaw de una forma más realista y con forma de canal que la que puede ofrecer una sola prueba unitaria. +La pila privada de QA está pensada para ejercitar OpenClaw de una manera más realista, +con forma de canal, que la que puede cubrir una sola prueba unitaria. -Componentes actuales: +Piezas actuales: -- `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo, reacción, edición y eliminación. -- `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción, inyectar mensajes entrantes y exportar un informe en Markdown. -- `qa/`: recursos semilla respaldados por el repositorio para la tarea de inicio y los escenarios base de QA. +- `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo, + reacción, edición y eliminación. +- `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción, + inyectar mensajes entrantes y exportar un informe en Markdown. +- `qa/`: recursos seed respaldados por el repositorio para la tarea inicial y los + escenarios base de QA. El flujo actual del operador de QA es un sitio de QA de dos paneles: @@ -35,9 +39,13 @@ Ejecútalo con: pnpm qa:lab:up ``` -Eso compila el sitio de QA, inicia la ruta de Gateway respaldada por Docker y expone la página de QA Lab donde un operador o un bucle de automatización puede dar al agente una misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o qué siguió bloqueado. +Eso compila el sitio de QA, inicia el carril de Gateway respaldado por Docker y expone la +página de QA Lab, donde un operador o un bucle de automatización puede darle al agente una +misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o +qué siguió bloqueado. -Para una iteración más rápida de la interfaz de QA Lab sin recompilar la imagen de Docker cada vez, inicia la pila con un bundle de QA Lab montado con bind mount: +Para una iteración más rápida de la UI de QA Lab sin reconstruir la imagen de Docker cada vez, +inicia la pila con un bundle de QA Lab montado por enlace: ```bash pnpm openclaw qa docker-build-image @@ -46,100 +54,144 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta con bind mount `extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` recompila ese bundle cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash de recursos de QA Lab. +`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta por enlace +`extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` +recompila ese bundle cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash +de recursos de QA Lab. -Para una ruta de smoke real de transporte para Matrix, ejecuta: +Para un carril smoke de Matrix con transporte real, ejecuta: ```bash pnpm openclaw qa matrix ``` -Esa ruta aprovisiona un homeserver Tuwunel desechable en Docker, registra usuarios temporales para driver, SUT y observador, crea una sala privada y luego ejecuta el Plugin real de Matrix dentro de un proceso hijo de Gateway de QA. La ruta de transporte en vivo mantiene la configuración hija limitada al transporte bajo prueba, por lo que Matrix se ejecuta sin `qa-channel` en la configuración hija. Escribe los artefactos del informe estructurado y un registro combinado de stdout/stderr en el directorio de salida de QA de Matrix seleccionado. Para capturar también la salida externa de compilación/lanzamiento de `scripts/run-node.mjs`, establece `OPENCLAW_RUN_NODE_OUTPUT_LOG=` en un archivo de registro local del repositorio. +Ese carril aprovisiona un homeserver Tuwunel desechable en Docker, registra usuarios temporales +de controlador, SUT y observador, crea una sala privada y luego ejecuta el Plugin real de Matrix dentro +de un proceso hijo de Gateway de QA. El carril de transporte en vivo mantiene la configuración del proceso hijo +limitada al transporte bajo prueba, por lo que Matrix se ejecuta sin `qa-channel` en la configuración +del proceso hijo. Escribe los artefactos de informe estructurado y un registro combinado de stdout/stderr +en el directorio de salida de Matrix QA seleccionado. Para capturar también la salida externa de compilación/lanzamiento +de `scripts/run-node.mjs`, establece `OPENCLAW_RUN_NODE_OUTPUT_LOG=` en un archivo de registro local del repositorio. -Para una ruta de smoke real de transporte para Telegram, ejecuta: +Para un carril smoke de Telegram con transporte real, ejecuta: ```bash pnpm openclaw qa telegram ``` -Esa ruta apunta a un grupo privado real de Telegram en lugar de aprovisionar un servidor desechable. Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación bot a bot funciona mejor cuando ambos bots tienen habilitado Bot-to-Bot Communication Mode en `@BotFather`. +Ese carril apunta a un grupo privado real de Telegram en lugar de aprovisionar un servidor desechable. +Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo +grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación bot a bot +funciona mejor cuando ambos bots tienen habilitado el modo de comunicación Bot-to-Bot +en `@BotFather`. -Las rutas de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada una invente su propia forma de lista de escenarios: +Los carriles de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada uno invente +su propia forma de lista de escenarios. -`qa-channel` sigue siendo la suite amplia de comportamiento sintético del producto y no forma parte de la matriz de cobertura de transporte en vivo. +`qa-channel` sigue siendo la amplia suite sintética de comportamiento del producto y no forma parte +de la matriz de cobertura de transporte en vivo. -| Ruta | Canary | Restricción por mención | Bloqueo por allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda | -| -------- | ------ | ----------------------- | --------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Carril | Canary | Puerta por mención | Bloqueo por allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando help | +| -------- | ------ | ------------------ | --------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Esto mantiene a `qa-channel` como la suite amplia de comportamiento del producto, mientras que Matrix, Telegram y futuros transportes en vivo comparten una lista explícita de comprobaciones de contrato de transporte. +Esto mantiene `qa-channel` como la amplia suite de comportamiento del producto, mientras que Matrix, +Telegram y futuros transportes en vivo comparten una lista explícita de comprobación del contrato +de transporte. -Para una ruta de VM Linux desechable sin incorporar Docker en la ruta de QA, ejecuta: +Para un carril de VM Linux desechable sin incorporar Docker en la ruta de QA, ejecuta: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Esto arranca un invitado fresco de Multipass, instala dependencias, compila OpenClaw dentro del invitado, ejecuta `qa suite` y luego copia el informe y el resumen normales de QA de vuelta a `.artifacts/qa-e2e/...` en el host. +Esto inicia un huésped nuevo de Multipass, instala dependencias, compila OpenClaw +dentro del huésped, ejecuta `qa suite` y luego copia el informe y resumen normales de QA de vuelta a +`.artifacts/qa-e2e/...` en el host. Reutiliza el mismo comportamiento de selección de escenarios que `qa suite` en el host. -Las ejecuciones de la suite en host y en Multipass ejecutan en paralelo varios escenarios seleccionados con workers de Gateway aislados de forma predeterminada, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para ejecución en serie. -Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que resultan prácticas para el invitado: claves de proveedor basadas en env, la ruta de configuración del proveedor en vivo de QA y `CODEX_HOME` cuando está presente. Mantén `--output-dir` bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través del espacio de trabajo montado. +Las ejecuciones del host y de Multipass ejecutan varios escenarios seleccionados en paralelo +con workers de Gateway aislados de forma predeterminada, hasta 64 workers o la cantidad de escenarios +seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o +`--concurrency 1` para ejecución en serie. +Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que son prácticas para el +huésped: claves de proveedor basadas en variables de entorno, la ruta de configuración del proveedor en vivo de QA y +`CODEX_HOME` cuando esté presente. Mantén `--output-dir` bajo la raíz del repositorio para que el huésped +pueda escribir de vuelta a través del espacio de trabajo montado. -## Semillas respaldadas por el repositorio +## Seeds respaldados por el repositorio -Los recursos semilla viven en `qa/`: +Los recursos seed viven en `qa/`: - `qa/scenarios/index.md` -- `qa/scenarios/*.md` +- `qa/scenarios//*.md` -Estos están intencionalmente en git para que el plan de QA sea visible tanto para humanos como para el agente. +Estos están intencionalmente en git para que el plan de QA sea visible tanto para las personas como para el +agente. -`qa-lab` debe seguir siendo un ejecutor genérico de Markdown. Cada archivo Markdown de escenario es la fuente de verdad para una ejecución de prueba y debe definir: +`qa-lab` debe seguir siendo un ejecutor genérico de Markdown. Cada archivo Markdown de escenario es +la fuente de verdad para una ejecución de prueba y debe definir: - metadatos del escenario -- referencias a documentación y código +- metadatos opcionales de categoría, capacidad, carril y riesgo +- referencias de documentación y código - requisitos opcionales de Plugin - parche opcional de configuración de Gateway - el `qa-flow` ejecutable -La superficie de ejecución reutilizable que respalda `qa-flow` puede seguir siendo genérica y transversal. Por ejemplo, los escenarios en Markdown pueden combinar helpers del lado del transporte con helpers del lado del navegador que controlan la Control UI integrada a través de la interfaz `browser.request` de Gateway sin añadir un ejecutor de caso especial. +La superficie de ejecución reutilizable que respalda `qa-flow` puede seguir siendo genérica +y transversal. Por ejemplo, los escenarios Markdown pueden combinar ayudantes del lado del transporte +con ayudantes del lado del navegador que controlan la Control UI integrada a través de la +interfaz `browser.request` de Gateway sin agregar un ejecutor de caso especial. -La lista base debe seguir siendo lo bastante amplia para cubrir: +Los archivos de escenario deben agruparse por capacidad del producto en lugar de por carpeta del árbol +de código fuente. Mantén estables los ID de escenario cuando los archivos se muevan; usa `docsRefs` y `codeRefs` +para la trazabilidad de implementación. -- chat por MD y por canal +La lista base debe seguir siendo lo suficientemente amplia como para cubrir: + +- chat por MD y canal - comportamiento de hilos - ciclo de vida de acciones de mensajes - callbacks de Cron - recuperación de memoria - cambio de modelo -- traspaso a subagente +- transferencia a subagente - lectura del repositorio y de la documentación -- una pequeña tarea de compilación, como Lobster Invaders +- una pequeña tarea de compilación como Lobster Invaders -## Rutas de proveedor simulado +## Carriles de proveedor simulado -`qa suite` tiene dos rutas locales de proveedor simulado: +`qa suite` tiene dos carriles locales de proveedor simulado: -- `mock-openai` es el simulador de OpenClaw consciente del escenario. Sigue siendo la ruta simulada determinista predeterminada para QA respaldado por el repositorio y compuertas de paridad. -- `aimock` inicia un servidor de proveedor respaldado por AIMock para cobertura experimental de protocolo, fixtures, grabación/reproducción y caos. Es aditivo y no reemplaza al despachador de escenarios `mock-openai`. +- `mock-openai` es el simulador de OpenClaw consciente del escenario. Sigue siendo el + carril simulado determinista predeterminado para QA respaldado por el repositorio y compuertas de paridad. +- `aimock` inicia un servidor de proveedor respaldado por AIMock para cobertura experimental de protocolo, + fixtures, grabación/reproducción y caos. Es complementario y no reemplaza al despachador de escenarios + `mock-openai`. -La implementación de rutas de proveedor vive en `extensions/qa-lab/src/providers/`. -Cada proveedor es dueño de sus valores predeterminados, el arranque de su servidor local, la configuración del modelo de Gateway, las necesidades de preparación del perfil de autenticación y las capacidades en vivo/simuladas. El código compartido de suite y Gateway debe enrutar a través del registro de proveedores en lugar de ramificarse por nombres de proveedor. +La implementación del carril de proveedor vive en `extensions/qa-lab/src/providers/`. +Cada proveedor es dueño de sus valores predeterminados, el arranque del servidor local, la configuración +del modelo de Gateway, las necesidades de preparación del perfil de autenticación y los indicadores de capacidad +live/mock. El código compartido de suite y Gateway debe enrutar a través del registro de proveedores +en lugar de ramificarse según los nombres de proveedor. ## Adaptadores de transporte -`qa-lab` es dueño de una interfaz genérica de transporte para escenarios de QA en Markdown. -`qa-channel` es el primer adaptador sobre esa interfaz, pero el objetivo del diseño es más amplio: -los futuros canales reales o sintéticos deberían conectarse al mismo ejecutor de suite en lugar de añadir un ejecutor de QA específico de transporte. +`qa-lab` es dueño de una interfaz genérica de transporte para escenarios Markdown de QA. +`qa-channel` es el primer adaptador sobre esa interfaz, pero el objetivo de diseño es más amplio: +canales futuros, reales o sintéticos, deberían integrarse en el mismo ejecutor de suite en lugar +de agregar un ejecutor de QA específico para cada transporte. A nivel de arquitectura, la división es: - `qa-lab` es dueño de la ejecución genérica de escenarios, la concurrencia de workers, la escritura de artefactos y los informes. -- el adaptador de transporte es dueño de la configuración de Gateway, la preparación, la observación entrante y saliente, las acciones de transporte y el estado de transporte normalizado. -- los archivos de escenarios en Markdown bajo `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de ejecución reutilizable que los ejecuta. +- el adaptador de transporte es dueño de la configuración de Gateway, la preparación, la observación de entrada y salida, las acciones de transporte y el estado de transporte normalizado. +- los archivos Markdown de escenarios bajo `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de ejecución reutilizable que los ejecuta. -La guía de adopción orientada a mantenedores para nuevos adaptadores de canal se encuentra en +La guía de adopción dirigida a mantenedores para nuevos adaptadores de canal se encuentra en [Testing](/es/help/testing#adding-a-channel-to-qa). ## Informes @@ -150,9 +202,10 @@ El informe debe responder: - Qué funcionó - Qué falló - Qué siguió bloqueado -- Qué escenarios de seguimiento vale la pena añadir +- Qué escenarios de seguimiento vale la pena agregar -Para comprobaciones de carácter y estilo, ejecuta el mismo escenario en varias referencias de modelos en vivo y escribe un informe evaluado en Markdown: +Para comprobaciones de carácter y estilo, ejecuta el mismo escenario con múltiples referencias de modelos en vivo +y escribe un informe Markdown evaluado: ```bash pnpm openclaw qa character-eval \ @@ -171,13 +224,30 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -El comando ejecuta procesos hijo locales de Gateway de QA, no Docker. Los escenarios de evaluación de carácter deben establecer la persona mediante `SOUL.md` y luego ejecutar turnos de usuario normales, como chat, ayuda del espacio de trabajo y pequeñas tareas sobre archivos. No se debe informar al modelo candidato de que está siendo evaluado. El comando conserva cada transcripción completa, registra estadísticas básicas de ejecución y luego pide a los modelos jueces en modo rápido con razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibe y humor. -Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo cada transcripción y estado de ejecución, pero las referencias candidatas se sustituyen por etiquetas neutrales como `candidate-01`; el informe vuelve a asociar las clasificaciones con las referencias reales después del análisis. -Las ejecuciones candidatas usan `high` thinking de forma predeterminada, con `xhigh` para los modelos de OpenAI que lo admiten. Sustituye un candidato específico en línea con -`--model provider/model,thinking=`. `--thinking ` sigue estableciendo un valor de respaldo global, y la forma anterior `--model-thinking ` se mantiene por compatibilidad. -Las referencias candidatas de OpenAI usan el modo rápido de forma predeterminada para que se use el procesamiento con prioridad cuando el proveedor lo admita. Añade `,fast`, `,no-fast` o `,fast=false` en línea cuando un candidato o juez concreto necesite una sustitución. Pasa `--fast` solo cuando quieras forzar el modo rápido para todos los modelos candidatos. Las duraciones de candidatos y jueces se registran en el informe para análisis comparativos, pero los prompts de los jueces indican explícitamente que no deben clasificar por velocidad. -Tanto las ejecuciones de modelos candidatos como las de modelos jueces usan concurrencia 16 de forma predeterminada. Reduce -`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión sobre Gateway local hagan que una ejecución sea demasiado ruidosa. +El comando ejecuta procesos hijo locales de Gateway de QA, no Docker. Los escenarios de evaluación de carácter +deben establecer la personalidad mediante `SOUL.md`, y luego ejecutar turnos de usuario normales +como chat, ayuda del espacio de trabajo y pequeñas tareas con archivos. No se le debe decir al +modelo candidato que está siendo evaluado. El comando conserva cada transcripción completa, +registra estadísticas básicas de ejecución y luego pide a los modelos jueces en modo fast con +razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor. +Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo +cada transcripción y estado de ejecución, pero las referencias candidatas se reemplazan por +etiquetas neutras como `candidate-01`; el informe vuelve a mapear las clasificaciones a las referencias reales +después del análisis. +Las ejecuciones candidatas usan `high` thinking de forma predeterminada, con `xhigh` para los modelos de OpenAI +que lo admiten. Sustituye un candidato específico en línea con +`--model provider/model,thinking=`. `--thinking ` sigue estableciendo una +alternativa global, y la forma antigua `--model-thinking ` se +mantiene por compatibilidad. +Las referencias candidatas de OpenAI usan el modo fast de forma predeterminada para que se use procesamiento prioritario +cuando el proveedor lo admita. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando +un solo candidato o juez necesite una sustitución. Pasa `--fast` solo cuando quieras +forzar el modo fast para todos los modelos candidatos. Las duraciones de candidatos y jueces se +registran en el informe para análisis comparativo, pero los prompts de los jueces indican explícitamente +que no se clasifique por velocidad. +Tanto las ejecuciones de modelos candidatos como las de los jueces usan concurrencia 16 de forma predeterminada. Reduce +`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión del Gateway local +hagan que una ejecución sea demasiado ruidosa. Cuando no se pasa ningún `--model` candidato, la evaluación de carácter usa por defecto `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, diff --git a/docs/es/concepts/system-prompt.md b/docs/es/concepts/system-prompt.md index 684bf2945..cc243d401 100644 --- a/docs/es/concepts/system-prompt.md +++ b/docs/es/concepts/system-prompt.md @@ -1,14 +1,14 @@ --- read_when: - - Editar el texto del prompt del sistema, la lista de herramientas o las secciones de tiempo/Heartbeat - - Cambiar el comportamiento de arranque del espacio de trabajo o de inyección de Skills + - Edición del texto del prompt del sistema, la lista de herramientas o las secciones de hora/Heartbeat + - Cambio del comportamiento de arranque del espacio de trabajo o de inyección de Skills summary: Qué contiene el prompt del sistema de OpenClaw y cómo se ensambla title: Prompt del sistema x-i18n: - generated_at: "2026-04-15T19:41:57Z" + generated_at: "2026-04-18T04:59:11Z" model: gpt-5.4 provider: openai - source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 + source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab source_path: concepts/system-prompt.md workflow: 15 --- @@ -19,61 +19,80 @@ OpenClaw crea un prompt del sistema personalizado para cada ejecución del agent El prompt es ensamblado por OpenClaw e inyectado en cada ejecución del agente. -Los plugins de proveedor pueden aportar guía de prompt compatible con caché sin reemplazar el prompt completo propiedad de OpenClaw. El runtime del proveedor puede: +Los plugins de proveedores pueden aportar guía de prompt consciente de la caché sin reemplazar el prompt completo propiedad de OpenClaw. El runtime del proveedor puede: - reemplazar un pequeño conjunto de secciones principales con nombre (`interaction_style`, `tool_call_style`, `execution_bias`) - inyectar un **prefijo estable** por encima del límite de caché del prompt - inyectar un **sufijo dinámico** por debajo del límite de caché del prompt -Usa contribuciones propiedad del proveedor para ajustes específicos de familias de modelos. Mantén la mutación heredada del prompt `before_prompt_build` para compatibilidad o para cambios de prompt verdaderamente globales, no para el comportamiento normal del proveedor. +Usa aportes propiedad del proveedor para ajustes específicos de familias de modelos. Mantén la mutación de prompt heredada de `before_prompt_build` para compatibilidad o para cambios de prompt realmente globales, no para el comportamiento normal del proveedor. ## Estructura El prompt es intencionalmente compacto y usa secciones fijas: -- **Herramientas**: recordatorio de la fuente de verdad de herramientas estructuradas más la guía de uso de herramientas en runtime. -- **Seguridad**: breve recordatorio de barreras de protección para evitar conductas de búsqueda de poder o eludir la supervisión. -- **Skills** (cuando están disponibles): le indica al modelo cómo cargar instrucciones de Skills bajo demanda. -- **Autoactualización de OpenClaw**: cómo inspeccionar la configuración de forma segura con `config.schema.lookup`, modificar la configuración con `config.patch`, reemplazar la configuración completa con `config.apply`, y ejecutar `update.run` solo a solicitud explícita del usuario. La herramienta `gateway`, solo para propietarios, también rechaza reescribir `tools.exec.ask` / `tools.exec.security`, incluidas las alias heredadas `tools.bash.*` que se normalizan a esas rutas protegidas de exec. +- **Herramientas**: recordatorio de la fuente de verdad de herramientas estructuradas más guía de uso de herramientas en tiempo de ejecución. +- **Seguridad**: recordatorio breve de barreras de protección para evitar conductas de búsqueda de poder o evasión de supervisión. +- **Skills** (cuando están disponibles): le dice al modelo cómo cargar instrucciones de Skills bajo demanda. +- **Autoactualización de OpenClaw**: cómo inspeccionar la configuración de forma segura con + `config.schema.lookup`, parchear la configuración con `config.patch`, reemplazar la configuración completa con `config.apply` y ejecutar `update.run` solo cuando el usuario lo solicite explícitamente. La herramienta `gateway`, solo para propietarios, también se niega a reescribir + `tools.exec.ask` / `tools.exec.security`, incluidas las alias heredadas `tools.bash.*` + que se normalizan a esas rutas de ejecución protegidas. - **Espacio de trabajo**: directorio de trabajo (`agents.defaults.workspace`). - **Documentación**: ruta local a la documentación de OpenClaw (repositorio o paquete npm) y cuándo leerla. -- **Archivos del espacio de trabajo (inyectados)**: indica que los archivos de arranque se incluyen más abajo. -- **Sandbox** (cuando está habilitado): indica el runtime aislado, las rutas del sandbox y si exec elevado está disponible. +- **Archivos del espacio de trabajo (inyectados)**: indica que los archivos de arranque están incluidos más abajo. +- **Sandbox** (cuando está habilitado): indica el runtime aislado, las rutas del sandbox y si la ejecución con privilegios elevados está disponible. - **Fecha y hora actuales**: hora local del usuario, zona horaria y formato de hora. - **Etiquetas de respuesta**: sintaxis opcional de etiquetas de respuesta para proveedores compatibles. -- **Heartbeats**: prompt de Heartbeat y comportamiento de acuse de recibo, cuando Heartbeats están habilitados para el agente predeterminado. +- **Heartbeats**: prompt de Heartbeat y comportamiento de confirmación, cuando los Heartbeats están habilitados para el agente predeterminado. - **Runtime**: host, SO, node, modelo, raíz del repositorio (cuando se detecta), nivel de razonamiento (una línea). -- **Razonamiento**: nivel de visibilidad actual + pista para alternar con /reasoning. +- **Razonamiento**: nivel de visibilidad actual + sugerencia para alternar con /reasoning. -La sección de Herramientas también incluye guía de runtime para trabajos de larga duración: +La sección Herramientas también incluye guía de runtime para trabajo de larga duración: -- usa cron para seguimientos futuros (`check back later`, recordatorios, trabajo recurrente) en lugar de bucles de espera con `exec`, trucos de retraso con `yieldMs` o sondeo repetido de `process` -- usa `exec` / `process` solo para comandos que comienzan ahora y siguen ejecutándose en segundo plano -- cuando la reactivación automática por finalización está habilitada, inicia el comando una sola vez y confía en la ruta de reactivación basada en push cuando emita salida o falle -- usa `process` para registros, estado, entrada o intervención cuando necesites inspeccionar un comando en ejecución -- si la tarea es más grande, prefiere `sessions_spawn`; la finalización del subagente se basa en push y se anuncia automáticamente al solicitante -- no sondees `subagents list` / `sessions_list` en un bucle solo para esperar la finalización +- usar Cron para seguimientos futuros (`check back later`, recordatorios, trabajo recurrente) + en lugar de bucles de suspensión con `exec`, trucos de retraso con `yieldMs` o sondeos repetidos de `process` +- usar `exec` / `process` solo para comandos que empiezan ahora y continúan ejecutándose + en segundo plano +- cuando el despertar automático al completarse está habilitado, iniciar el comando una sola vez y confiar en + la vía de despertar basada en push cuando emita salida o falle +- usar `process` para registros, estado, entrada o intervención cuando necesites + inspeccionar un comando en ejecución +- si la tarea es más grande, preferir `sessions_spawn`; la finalización de subagentes está + basada en push y se anuncia automáticamente de vuelta al solicitante +- no sondear `subagents list` / `sessions_list` en un bucle solo para esperar + la finalización -Cuando la herramienta experimental `update_plan` está habilitada, Herramientas también le indica al modelo que la use solo para trabajo no trivial de varios pasos, que mantenga exactamente un paso `in_progress` y que evite repetir el plan completo después de cada actualización. +Cuando la herramienta experimental `update_plan` está habilitada, Herramientas también le dice al +modelo que la use solo para trabajo no trivial de varios pasos, que mantenga exactamente un +paso `in_progress` y que evite repetir el plan completo después de cada actualización. -Las barreras de protección de Seguridad en el prompt del sistema son de carácter orientativo. Guían el comportamiento del modelo, pero no aplican políticas. Usa la política de herramientas, aprobaciones de exec, sandboxing y listas permitidas de canales para una aplicación estricta; los operadores pueden deshabilitarlas por diseño. +Las barreras de seguridad del prompt del sistema son orientativas. Guían el comportamiento del modelo, pero no aplican la política. Usa la política de herramientas, las aprobaciones de ejecución, el sandboxing y las listas de permitidos de canales para la aplicación estricta; los operadores pueden desactivarlas por diseño. -En los canales con tarjetas o botones de aprobación nativos, el prompt de runtime ahora le indica al agente que primero confíe en esa IU de aprobación nativa. Solo debe incluir un comando manual `/approve` cuando el resultado de la herramienta diga que las aprobaciones en el chat no están disponibles o que la aprobación manual es la única opción. +En canales con tarjetas o botones de aprobación nativos, el prompt de runtime ahora le dice al +agente que confíe primero en esa interfaz de aprobación nativa. Solo debe incluir un comando manual +`/approve` cuando el resultado de la herramienta diga que las aprobaciones en el chat no están disponibles o +que la aprobación manual es la única vía. -## Modos de prompt +## Modos del prompt -OpenClaw puede renderizar prompts del sistema más pequeños para subagentes. El runtime establece un `promptMode` para cada ejecución (no es una configuración orientada al usuario): +OpenClaw puede renderizar prompts del sistema más pequeños para subagentes. El runtime establece un +`promptMode` para cada ejecución (no es una configuración orientada al usuario): - `full` (predeterminado): incluye todas las secciones anteriores. -- `minimal`: se usa para subagentes; omite **Skills**, **Memory Recall**, **Autoactualización de OpenClaw**, **Alias de modelos**, **Identidad del usuario**, **Etiquetas de respuesta**, **Mensajería**, **Respuestas silenciosas** y **Heartbeats**. Herramientas, **Seguridad**, Espacio de trabajo, Sandbox, Fecha y hora actuales (cuando se conocen), Runtime y el contexto inyectado siguen disponibles. +- `minimal`: se usa para subagentes; omite **Skills**, **Recuperación de memoria**, **Autoactualización de OpenClaw**, **Alias de modelos**, **Identidad del usuario**, **Etiquetas de respuesta**, + **Mensajería**, **Respuestas silenciosas** y **Heartbeats**. Herramientas, **Seguridad**, + Espacio de trabajo, Sandbox, Fecha y hora actuales (cuando se conocen), Runtime y el + contexto inyectado siguen estando disponibles. - `none`: devuelve solo la línea base de identidad. -Cuando `promptMode=minimal`, los prompts adicionales inyectados se etiquetan como **Contexto del subagente** en lugar de **Contexto de chat grupal**. +Cuando `promptMode=minimal`, los prompts inyectados adicionales se etiquetan como **Contexto del subagente** +en lugar de **Contexto del chat grupal**. -## Inyección de arranque del espacio de trabajo +## Inyección del arranque del espacio de trabajo -Los archivos de arranque se recortan y se anexan en **Contexto del proyecto** para que el modelo vea la identidad y el contexto del perfil sin necesidad de lecturas explícitas: +Los archivos de arranque se recortan y se agregan bajo **Contexto del proyecto** para que el modelo vea el contexto de identidad y perfil sin necesitar lecturas explícitas: - `AGENTS.md` - `SOUL.md` @@ -82,40 +101,68 @@ Los archivos de arranque se recortan y se anexan en **Contexto del proyecto** pa - `USER.md` - `HEARTBEAT.md` - `BOOTSTRAP.md` (solo en espacios de trabajo completamente nuevos) -- `MEMORY.md` cuando está presente; de lo contrario, `memory.md` como alternativa en minúsculas +- `MEMORY.md` cuando está presente; en caso contrario, `memory.md` como alternativa en minúsculas -Todos estos archivos se **inyectan en la ventana de contexto** en cada turno, a menos que se aplique una condición específica del archivo. `HEARTBEAT.md` se omite en ejecuciones normales cuando Heartbeats están deshabilitados para el agente predeterminado o `agents.defaults.heartbeat.includeSystemPromptSection` es false. Mantén los archivos inyectados concisos, especialmente `MEMORY.md`, que puede crecer con el tiempo y provocar un uso de contexto inesperadamente alto y una Compaction más frecuente. +Todos estos archivos se **inyectan en la ventana de contexto** en cada turno, a menos que +se aplique una compuerta específica del archivo. `HEARTBEAT.md` se omite en ejecuciones normales cuando +los Heartbeats están deshabilitados para el agente predeterminado o +`agents.defaults.heartbeat.includeSystemPromptSection` es false. Mantén los archivos inyectados concisos, +especialmente `MEMORY.md`, que puede crecer con el tiempo y provocar un uso de contexto inesperadamente alto y una Compaction más frecuente. -> **Nota:** los archivos diarios `memory/*.md` **no** forman parte del Contexto del proyecto de arranque normal. En turnos normales se accede a ellos bajo demanda mediante las herramientas `memory_search` y `memory_get`, por lo que no cuentan contra la ventana de contexto a menos que el modelo los lea explícitamente. Los turnos simples `/new` y `/reset` son la excepción: el runtime puede anteponer memoria diaria reciente como un bloque único de contexto de inicio para ese primer turno. +> **Nota:** los archivos diarios `memory/*.md` **no** forman parte del Contexto del proyecto de arranque normal. +> En turnos normales, se accede a ellos bajo demanda mediante las herramientas +> `memory_search` y `memory_get`, por lo que no cuentan contra la ventana de +> contexto a menos que el modelo los lea explícitamente. Los turnos simples `/new` y +> `/reset` son la excepción: el runtime puede anteponer memoria diaria reciente +> como un bloque único de contexto de inicio para ese primer turno. -Los archivos grandes se truncan con un marcador. El tamaño máximo por archivo está controlado por `agents.defaults.bootstrapMaxChars` (predeterminado: 20000). El contenido total de arranque inyectado entre archivos está limitado por `agents.defaults.bootstrapTotalMaxChars` (predeterminado: 150000). Los archivos ausentes inyectan un marcador breve de archivo faltante. Cuando se produce truncamiento, OpenClaw puede inyectar un bloque de advertencia en Contexto del proyecto; contrólalo con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; predeterminado: `once`). +Los archivos grandes se truncan con un marcador. El tamaño máximo por archivo está controlado por +`agents.defaults.bootstrapMaxChars` (predeterminado: 12000). El contenido total de arranque inyectado +entre archivos está limitado por `agents.defaults.bootstrapTotalMaxChars` +(predeterminado: 60000). Los archivos ausentes inyectan un marcador corto de archivo faltante. Cuando ocurre truncamiento, +OpenClaw puede inyectar un bloque de advertencia en Contexto del proyecto; controla esto con +`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; +predeterminado: `once`). -Las sesiones de subagentes solo inyectan `AGENTS.md` y `TOOLS.md` (los demás archivos de arranque se filtran para mantener pequeño el contexto del subagente). +Las sesiones de subagentes solo inyectan `AGENTS.md` y `TOOLS.md` (los demás archivos de arranque +se filtran para mantener pequeño el contexto del subagente). -Los hooks internos pueden interceptar este paso mediante `agent:bootstrap` para mutar o reemplazar los archivos de arranque inyectados (por ejemplo, cambiar `SOUL.md` por una personalidad alternativa). +Los hooks internos pueden interceptar este paso mediante `agent:bootstrap` para mutar o reemplazar +los archivos de arranque inyectados (por ejemplo, reemplazando `SOUL.md` por una persona alternativa). -Si quieres que el agente suene menos genérico, empieza con la [Guía de personalidad de SOUL.md](/es/concepts/soul). +Si quieres que el agente suene menos genérico, empieza con +[Guía de personalidad de SOUL.md](/es/concepts/soul). Para inspeccionar cuánto aporta cada archivo inyectado (sin procesar frente a inyectado, truncamiento, además de la sobrecarga del esquema de herramientas), usa `/context list` o `/context detail`. Consulta [Contexto](/es/concepts/context). ## Manejo del tiempo -El prompt del sistema incluye una sección dedicada de **Fecha y hora actuales** cuando se conoce la zona horaria del usuario. Para mantener estable la caché del prompt, ahora solo incluye la **zona horaria** (sin reloj dinámico ni formato de hora). +El prompt del sistema incluye una sección dedicada de **Fecha y hora actuales** cuando se conoce la +zona horaria del usuario. Para mantener estable la caché del prompt, ahora solo incluye la +**zona horaria** (sin reloj dinámico ni formato de hora). -Usa `session_status` cuando el agente necesite la hora actual; la tarjeta de estado incluye una línea de marca de tiempo. La misma herramienta también puede establecer opcionalmente una anulación de modelo por sesión (`model=default` la borra). +Usa `session_status` cuando el agente necesite la hora actual; la tarjeta de estado +incluye una línea de marca de tiempo. La misma herramienta también puede establecer opcionalmente una +anulación de modelo por sesión (`model=default` la borra). Configura con: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Consulta [Fecha y hora](/es/date-time) para ver los detalles completos del comportamiento. +Consulta [Fecha y hora](/es/date-time) para ver todos los detalles del comportamiento. ## Skills -Cuando existen Skills aptas, OpenClaw inyecta una **lista compacta de Skills disponibles** (`formatSkillsForPrompt`) que incluye la **ruta del archivo** para cada Skill. El prompt le indica al modelo que use `read` para cargar el SKILL.md en la ubicación indicada (espacio de trabajo, administrado o incluido). Si no hay Skills aptas, se omite la sección Skills. +Cuando existen Skills elegibles, OpenClaw inyecta una **lista compacta de Skills disponibles** +(`formatSkillsForPrompt`) que incluye la **ruta del archivo** para cada Skill. El +prompt le indica al modelo que use `read` para cargar el SKILL.md en la ubicación +indicada (espacio de trabajo, administrado o empaquetado). Si no hay Skills elegibles, se omite la sección +Skills. -La aptitud incluye condiciones de metadatos de Skills, comprobaciones del entorno/configuración de runtime y la lista permitida efectiva de Skills del agente cuando `agents.defaults.skills` o `agents.list[].skills` está configurado. +La elegibilidad incluye compuertas de metadatos de Skills, comprobaciones del entorno/configuración de runtime +y la lista de permitidos efectiva de Skills del agente cuando `agents.defaults.skills` o +`agents.list[].skills` está configurado. ``` @@ -127,20 +174,25 @@ La aptitud incluye condiciones de metadatos de Skills, comprobaciones del entorn ``` -Esto mantiene pequeño el prompt base y, al mismo tiempo, permite el uso dirigido de Skills. +Esto mantiene pequeño el prompt base mientras sigue permitiendo el uso dirigido de Skills. El presupuesto de la lista de Skills pertenece al subsistema de Skills: - Predeterminado global: `skills.limits.maxSkillsPromptChars` - Anulación por agente: `agents.list[].skillsLimits.maxSkillsPromptChars` -Los extractos genéricos acotados de runtime usan una superficie distinta: +Los extractos de runtime genéricos limitados usan una superficie diferente: - `agents.defaults.contextLimits.*` - `agents.list[].contextLimits.*` -Esa división mantiene el dimensionamiento de Skills separado del dimensionamiento de lectura/inyección en runtime, como `memory_get`, resultados de herramientas en vivo y actualizaciones de `AGENTS.md` posteriores a Compaction. +Esa separación mantiene el dimensionamiento de Skills separado del dimensionamiento de lectura/inyección del runtime, como +`memory_get`, resultados de herramientas en vivo y actualizaciones de AGENTS.md posteriores a la Compaction. ## Documentación -Cuando está disponible, el prompt del sistema incluye una sección de **Documentación** que apunta al directorio local de documentación de OpenClaw (ya sea `docs/` en el espacio de trabajo del repositorio o la documentación incluida en el paquete npm) y también menciona el espejo público, el repositorio fuente, el Discord de la comunidad y ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descubrir Skills. El prompt le indica al modelo que consulte primero la documentación local para el comportamiento, los comandos, la configuración o la arquitectura de OpenClaw, y que ejecute `openclaw status` por sí mismo cuando sea posible (preguntando al usuario solo cuando no tenga acceso). +Cuando está disponible, el prompt del sistema incluye una sección de **Documentación** que apunta al +directorio local de documentación de OpenClaw (ya sea `docs/` en el espacio de trabajo del repositorio o la documentación del paquete npm empaquetado) y también menciona la réplica pública, el repositorio fuente, el Discord de la comunidad y +ClawHub ([https://clawhub.ai](https://clawhub.ai)) para el descubrimiento de Skills. El prompt le indica al modelo que consulte primero la documentación local +para el comportamiento, los comandos, la configuración o la arquitectura de OpenClaw, y que ejecute +`openclaw status` por sí mismo cuando sea posible (preguntando al usuario solo cuando no tenga acceso). diff --git a/docs/es/gateway/configuration-reference.md b/docs/es/gateway/configuration-reference.md index 794657685..bedaa9be3 100644 --- a/docs/es/gateway/configuration-reference.md +++ b/docs/es/gateway/configuration-reference.md @@ -1,35 +1,35 @@ --- read_when: - - Necesita la semántica exacta de la configuración a nivel de campo o los valores predeterminados - - Está validando bloques de configuración de canal, modelo, Gateway o herramienta -summary: Referencia de configuración del Gateway para las claves principales de OpenClaw, los valores predeterminados y los enlaces a referencias dedicadas de subsistemas + - Necesitas la semántica exacta de configuración a nivel de campo o los valores predeterminados. + - Estás validando bloques de configuración de canal, modelo, Gateway o herramienta. +summary: Referencia de configuración del Gateway para las claves principales de OpenClaw, los valores predeterminados y enlaces a referencias dedicadas de subsistemas title: Referencia de configuración x-i18n: - generated_at: "2026-04-15T19:41:56Z" + generated_at: "2026-04-18T04:59:13Z" model: gpt-5.4 provider: openai - source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d + source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f source_path: gateway/configuration-reference.md workflow: 15 --- # Referencia de configuración -Referencia de configuración principal para `~/.openclaw/openclaw.json`. Para una descripción general orientada a tareas, consulte [Configuration](/es/gateway/configuration). +Referencia de configuración principal para `~/.openclaw/openclaw.json`. Para una descripción general orientada a tareas, consulta [Configuración](/es/gateway/configuration). -Esta página cubre las principales superficies de configuración de OpenClaw y enlaza a otras páginas cuando un subsistema tiene su propia referencia más detallada. **No** intenta incluir en una sola página cada catálogo de comandos propiedad de canales/plugins ni cada ajuste profundo de memoria/QMD. +Esta página cubre las principales superficies de configuración de OpenClaw y enlaza cuando un subsistema tiene su propia referencia más detallada. **No** intenta incluir en línea cada catálogo de comandos propiedad de canales/plugins ni cada ajuste profundo de memoria/QMD en una sola página. -Fuente de verdad en el código: +Fuente de verdad del código: -- `openclaw config schema` imprime el JSON Schema en vivo usado para la validación y la interfaz de usuario de Control, con los metadatos integrados de bundled/plugin/channel fusionados cuando están disponibles -- `config.schema.lookup` devuelve un nodo del esquema delimitado por ruta para herramientas de exploración detallada -- `pnpm config:docs:check` / `pnpm config:docs:gen` validan el hash de línea base de la documentación de configuración frente a la superficie actual del esquema +- `openclaw config schema` imprime el JSON Schema activo usado para validación y la Control UI, con los metadatos de bundled/plugin/channel fusionados cuando están disponibles +- `config.schema.lookup` devuelve un nodo de esquema con alcance a una ruta para herramientas de exploración detallada +- `pnpm config:docs:check` / `pnpm config:docs:gen` validan el hash de referencia base de la documentación de configuración frente a la superficie actual del esquema Referencias detalladas dedicadas: -- [Referencia de configuración de memoria](/es/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` y la configuración de dreaming en `plugins.entries.memory-core.config.dreaming` -- [Comandos de barra](/es/tools/slash-commands) para el catálogo actual de comandos integrados + bundled -- páginas del canal/plugin propietario para superficies de comandos específicas de cada canal +- [Referencia de configuración de memoria](/es/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` y la configuración de Dreaming bajo `plugins.entries.memory-core.config.dreaming` +- [Comandos slash](/es/tools/slash-commands) para el catálogo actual de comandos integrados + bundled +- páginas del canal/plugin propietario para superficies de comandos específicas del canal El formato de configuración es **JSON5** (se permiten comentarios y comas finales). Todos los campos son opcionales: OpenClaw usa valores predeterminados seguros cuando se omiten. @@ -39,32 +39,32 @@ El formato de configuración es **JSON5** (se permiten comentarios y comas final Cada canal se inicia automáticamente cuando existe su sección de configuración (a menos que `enabled: false`). -### Acceso a mensajes directos y grupos +### Acceso a MD y grupos -Todos los canales admiten políticas de mensajes directos y políticas de grupo: +Todos los canales admiten políticas de MD y políticas de grupo: | Política de MD | Comportamiento | | ------------------- | ------------------------------------------------------------- | -| `pairing` (predeterminado) | Los remitentes desconocidos reciben un código de emparejamiento de un solo uso; el propietario debe aprobar | -| `allowlist` | Solo remitentes en `allowFrom` (o en el almacén de permisos emparejados) | -| `open` | Permitir todos los MD entrantes (requiere `allowFrom: ["*"]`) | -| `disabled` | Ignorar todos los MD entrantes | +| `pairing` (default) | Los remitentes desconocidos reciben un código de vinculación de un solo uso; el propietario debe aprobarlo | +| `allowlist` | Solo remitentes en `allowFrom` (o en el almacén de permitidos emparejados) | +| `open` | Permitir todas las MD entrantes (requiere `allowFrom: ["*"]`) | +| `disabled` | Ignorar todas las MD entrantes | -| Política de grupo | Comportamiento | -| --------------------- | ------------------------------------------------------ | -| `allowlist` (predeterminada) | Solo grupos que coincidan con la lista de permitidos configurada | -| `open` | Omitir las listas de permitidos de grupos (la exigencia de mención sigue aplicándose) | -| `disabled` | Bloquear todos los mensajes de grupo/sala | +| Política de grupo | Comportamiento | +| --------------------- | ----------------------------------------------------- | +| `allowlist` (default) | Solo grupos que coincidan con la lista de permitidos configurada | +| `open` | Omitir las listas de permitidos de grupos (el requisito de mención sigue aplicándose) | +| `disabled` | Bloquear todos los mensajes de grupo/sala | -`channels.defaults.groupPolicy` establece el valor predeterminado cuando `groupPolicy` de un proveedor no está configurado. -Los códigos de emparejamiento caducan después de 1 hora. Las solicitudes pendientes de emparejamiento de MD están limitadas a **3 por canal**. -Si falta por completo un bloque de proveedor (`channels.` ausente), la política de grupo en tiempo de ejecución recurre a `allowlist` (fail-closed) con una advertencia al iniciar. +`channels.defaults.groupPolicy` establece el valor predeterminado cuando `groupPolicy` de un proveedor no está definido. +Los códigos de vinculación vencen después de 1 hora. Las solicitudes pendientes de vinculación de MD están limitadas a **3 por canal**. +Si falta por completo un bloque de proveedor (`channels.` ausente), la política de grupo en tiempo de ejecución vuelve a `allowlist` (fallo cerrado) con una advertencia al iniciar. -### Reemplazos de modelo por canal +### Sobrescrituras de modelo por canal -Use `channels.modelByChannel` para fijar IDs de canal específicos a un modelo. Los valores aceptan `provider/model` o alias de modelo configurados. La asignación de canal se aplica cuando una sesión todavía no tiene un reemplazo de modelo (por ejemplo, configurado mediante `/model`). +Usa `channels.modelByChannel` para fijar IDs de canal específicos a un modelo. Los valores aceptan `provider/model` o alias de modelo configurados. La asignación de canal se aplica cuando una sesión no tiene ya una sobrescritura de modelo (por ejemplo, establecida mediante `/model`). ```json5 { @@ -85,9 +85,9 @@ Use `channels.modelByChannel` para fijar IDs de canal específicos a un modelo. } ``` -### Valores predeterminados de canal y Heartbeat +### Valores predeterminados del canal y Heartbeat -Use `channels.defaults` para el comportamiento compartido de políticas de grupo y Heartbeat entre proveedores: +Usa `channels.defaults` para el comportamiento compartido de política de grupo y Heartbeat entre proveedores: ```json5 { @@ -105,15 +105,15 @@ Use `channels.defaults` para el comportamiento compartido de políticas de grupo } ``` -- `channels.defaults.groupPolicy`: política de grupo de respaldo cuando `groupPolicy` a nivel de proveedor no está configurado. -- `channels.defaults.contextVisibility`: modo predeterminado de visibilidad de contexto suplementario para todos los canales. Valores: `all` (predeterminado, incluir todo el contexto citado/de hilo/historial), `allowlist` (incluir solo contexto de remitentes permitidos), `allowlist_quote` (igual que allowlist, pero conservando el contexto explícito de cita/respuesta). Reemplazo por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: incluir estados de canal correctos en la salida de Heartbeat. +- `channels.defaults.groupPolicy`: política de grupo de respaldo cuando `groupPolicy` a nivel de proveedor no está definido. +- `channels.defaults.contextVisibility`: modo predeterminado de visibilidad de contexto suplementario para todos los canales. Valores: `all` (predeterminado, incluir todo el contexto citado/de hilo/de historial), `allowlist` (incluir solo contexto de remitentes en la lista de permitidos), `allowlist_quote` (igual que allowlist pero conserva el contexto explícito de cita/respuesta). Sobrescritura por canal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: incluir estados de canal saludables en la salida de Heartbeat. - `channels.defaults.heartbeat.showAlerts`: incluir estados degradados/con error en la salida de Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: mostrar una salida de Heartbeat compacta con estilo de indicador. +- `channels.defaults.heartbeat.useIndicator`: mostrar la salida de Heartbeat en estilo compacto con indicador. ### WhatsApp -WhatsApp se ejecuta a través del canal web del Gateway (Baileys Web). Se inicia automáticamente cuando existe una sesión vinculada. +WhatsApp se ejecuta a través del canal web del gateway (Baileys Web). Se inicia automáticamente cuando existe una sesión vinculada. ```json5 { @@ -164,10 +164,10 @@ WhatsApp se ejecuta a través del canal web del Gateway (Baileys Web). Se inicia } ``` -- Los comandos salientes usan por defecto la cuenta `default` si está presente; de lo contrario, el primer ID de cuenta configurado (ordenado). -- `channels.whatsapp.defaultAccount` opcional reemplaza esa selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. -- El directorio de autenticación heredado de Baileys para una sola cuenta se migra mediante `openclaw doctor` a `whatsapp/default`. -- Reemplazos por cuenta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Los comandos salientes usan de forma predeterminada la cuenta `default` si existe; de lo contrario, el primer id de cuenta configurado (ordenado). +- `channels.whatsapp.defaultAccount` opcional sobrescribe esa selección predeterminada de cuenta de respaldo cuando coincide con un id de cuenta configurado. +- El directorio heredado de autenticación de Baileys para una sola cuenta se migra con `openclaw doctor` a `whatsapp/default`. +- Sobrescrituras por cuenta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,13 +225,13 @@ WhatsApp se ejecuta a través del canal web del Gateway (Baileys Web). Se inicia } ``` -- Token del bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo archivo normal; se rechazan los enlaces simbólicos), con `TELEGRAM_BOT_TOKEN` como respaldo para la cuenta predeterminada. -- `channels.telegram.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. -- En configuraciones con múltiples cuentas (2 o más IDs de cuenta), establezca un valor predeterminado explícito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) para evitar el enrutamiento de respaldo; `openclaw doctor` advierte cuando falta o no es válido. -- `configWrites: false` bloquea las escrituras de configuración iniciadas desde Telegram (migraciones de ID de supergrupo, `/config set|unset`). -- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran vinculaciones persistentes de ACP para temas de foros (use el formato canónico `chatId:topic:topicId` en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). -- Las vistas previas de flujo de Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y de grupo). -- Política de reintento: consulte [Política de reintento](/es/concepts/retry). +- Token del bot: `channels.telegram.botToken` o `channels.telegram.tokenFile` (solo archivo normal; se rechazan enlaces simbólicos), con `TELEGRAM_BOT_TOKEN` como respaldo para la cuenta predeterminada. +- `channels.telegram.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- En configuraciones con múltiples cuentas (2 o más ids de cuenta), establece un valor predeterminado explícito (`channels.telegram.defaultAccount` o `channels.telegram.accounts.default`) para evitar el enrutamiento de respaldo; `openclaw doctor` advierte cuando falta o es inválido. +- `configWrites: false` bloquea escrituras de configuración iniciadas desde Telegram (migraciones de ID de supergrupo, `/config set|unset`). +- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran enlaces ACP persistentes para temas de foro (usa el formato canónico `chatId:topic:topicId` en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- Las vistas previas de streaming en Telegram usan `sendMessage` + `editMessageText` (funciona en chats directos y grupales). +- Política de reintento: consulta [Política de reintento](/es/concepts/retry). ### Discord @@ -334,35 +334,35 @@ WhatsApp se ejecuta a través del canal web del Gateway (Baileys Web). Se inicia ``` - Token: `channels.discord.token`, con `DISCORD_BOT_TOKEN` como respaldo para la cuenta predeterminada. -- Las llamadas salientes directas que proporcionan un `token` explícito de Discord usan ese token para la llamada; la configuración de reintentos/políticas de la cuenta sigue viniendo de la cuenta seleccionada en la instantánea activa del tiempo de ejecución. -- `channels.discord.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. -- Use `user:` (MD) o `channel:` (canal de servidor) para los destinos de entrega; los IDs numéricos sin prefijo se rechazan. -- Los slugs de servidor están en minúsculas y los espacios se reemplazan por `-`; las claves de canal usan el nombre convertido en slug (sin `#`). Se prefieren los IDs de servidor. -- Los mensajes creados por bots se ignoran de forma predeterminada. `allowBots: true` los habilita; use `allowBots: "mentions"` para aceptar solo mensajes de bots que mencionen al bot (los mensajes propios siguen filtrándose). -- `channels.discord.guilds..ignoreOtherMentions` (y los reemplazos por canal) descarta mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here). -- `maxLinesPerMessage` (predeterminado: 17) divide mensajes largos en líneas incluso cuando están por debajo de 2000 caracteres. +- Las llamadas salientes directas que proporcionan un `token` de Discord explícito usan ese token para la llamada; los ajustes de política/reintento de la cuenta siguen viniendo de la cuenta seleccionada en la instantánea activa del tiempo de ejecución. +- `channels.discord.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- Usa `user:` (MD) o `channel:` (canal de guild) para los destinos de entrega; los IDs numéricos sin prefijo se rechazan. +- Los slugs de guild están en minúsculas y con los espacios reemplazados por `-`; las claves de canal usan el nombre convertido a slug (sin `#`). Se prefieren los IDs de guild. +- Los mensajes creados por bots se ignoran de forma predeterminada. `allowBots: true` los habilita; usa `allowBots: "mentions"` para aceptar solo mensajes de bots que mencionen al bot (los mensajes propios siguen filtrándose). +- `channels.discord.guilds..ignoreOtherMentions` (y las sobrescrituras por canal) descarta mensajes que mencionan a otro usuario o rol, pero no al bot (excluyendo @everyone/@here). +- `maxLinesPerMessage` (predeterminado 17) divide mensajes altos incluso cuando están por debajo de 2000 caracteres. - `channels.discord.threadBindings` controla el enrutamiento vinculado a hilos de Discord: - - `enabled`: reemplazo de Discord para las funciones de sesión vinculadas a hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, y la entrega/el enrutamiento vinculados) - - `idleHours`: reemplazo de Discord para la pérdida automática de foco por inactividad en horas (`0` lo desactiva) - - `maxAgeHours`: reemplazo de Discord para la antigüedad máxima estricta en horas (`0` lo desactiva) - - `spawnSubagentSessions`: interruptor de activación para la creación/vinculación automática de hilos con `sessions_spawn({ thread: true })` -- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran vinculaciones persistentes de ACP para canales e hilos (use el ID del canal/hilo en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). + - `enabled`: sobrescritura de Discord para funciones de sesión vinculadas a hilos (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, y entrega/enrutamiento vinculados) + - `idleHours`: sobrescritura de Discord para auto-unfocus por inactividad en horas (`0` lo desactiva) + - `maxAgeHours`: sobrescritura de Discord para la antigüedad máxima estricta en horas (`0` lo desactiva) + - `spawnSubagentSessions`: interruptor de opt-in para la creación/vinculación automática de hilos con `sessions_spawn({ thread: true })` +- Las entradas `bindings[]` de nivel superior con `type: "acp"` configuran enlaces ACP persistentes para canales e hilos (usa el id de canal/hilo en `match.peer.id`). La semántica de los campos se comparte en [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). - `channels.discord.ui.components.accentColor` establece el color de acento para los contenedores de componentes v2 de Discord. -- `channels.discord.voice` habilita conversaciones en canales de voz de Discord y reemplazos opcionales de unión automática + TTS. -- `channels.discord.voice.daveEncryption` y `channels.discord.voice.decryptionFailureTolerance` se pasan a las opciones DAVE de `@discordjs/voice` (`true` y `24` de forma predeterminada). -- OpenClaw además intenta recuperar la recepción de voz saliendo y volviendo a unirse a una sesión de voz después de fallos repetidos de descifrado. -- `channels.discord.streaming` es la clave canónica del modo de flujo. Los valores heredados `streamMode` y booleanos `streaming` se migran automáticamente. -- `channels.discord.autoPresence` asigna la disponibilidad del tiempo de ejecución a la presencia del bot (healthy => online, degraded => idle, exhausted => dnd) y permite reemplazos opcionales del texto de estado. -- `channels.discord.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia por nombre/tag mutable (modo de compatibilidad break-glass). -- `channels.discord.execApprovals`: entrega nativa en Discord de aprobaciones de exec y autorización de aprobadores. - - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, las aprobaciones de exec se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. - - `approvers`: IDs de usuario de Discord autorizados para aprobar solicitudes de exec. Si se omite, usa `commands.ownerAllowFrom` como respaldo. - - `agentFilter`: lista opcional de permitidos de IDs de agente. Omítala para reenviar aprobaciones para todos los agentes. +- `channels.discord.voice` habilita conversaciones en canales de voz de Discord y sobrescrituras opcionales de unión automática + TTS. +- `channels.discord.voice.daveEncryption` y `channels.discord.voice.decryptionFailureTolerance` se transfieren a las opciones DAVE de `@discordjs/voice` (`true` y `24` de forma predeterminada). +- OpenClaw además intenta recuperar la recepción de voz saliendo y volviendo a unirse a una sesión de voz después de fallas repetidas de descifrado. +- `channels.discord.streaming` es la clave canónica del modo de transmisión. Los valores heredados `streamMode` y `streaming` booleano se migran automáticamente. +- `channels.discord.autoPresence` asigna la disponibilidad del tiempo de ejecución a la presencia del bot (healthy => online, degraded => idle, exhausted => dnd) y permite sobrescrituras opcionales de texto de estado. +- `channels.discord.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia por nombre/tag mutable (modo de compatibilidad de emergencia). +- `channels.discord.execApprovals`: entrega nativa de aprobaciones de ejecución de Discord y autorización de aprobadores. + - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, las aprobaciones de ejecución se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. + - `approvers`: IDs de usuario de Discord autorizados para aprobar solicitudes de ejecución. Si se omite, usa `commands.ownerAllowFrom` como respaldo. + - `agentFilter`: lista opcional de permitidos de IDs de agente. Omítela para reenviar aprobaciones para todos los agentes. - `sessionFilter`: patrones opcionales de clave de sesión (subcadena o regex). - - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado) las envía a los MD de los aprobadores, `"channel"` las envía al canal de origen, `"both"` las envía a ambos. Cuando el destino incluye `"channel"`, los botones solo pueden usarlos los aprobadores resueltos. - - `cleanupAfterResolve`: cuando es `true`, elimina los MD de aprobación después de aprobar, denegar o agotar el tiempo. + - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado) las envía a las MD de los aprobadores, `"channel"` las envía al canal de origen, `"both"` las envía a ambos. Cuando el destino incluye `"channel"`, los botones solo pueden ser usados por aprobadores resueltos. + - `cleanupAfterResolve`: cuando es `true`, elimina las MD de aprobación después de aprobar, denegar o agotar el tiempo de espera. -**Modos de notificación de reacciones:** `off` (ninguno), `own` (mensajes del bot, predeterminado), `all` (todos los mensajes), `allowlist` (desde `guilds..users` en todos los mensajes). +**Modos de notificación de reacciones:** `off` (ninguno), `own` (mensajes del bot, predeterminado), `all` (todos los mensajes), `allowlist` (de `guilds..users` en todos los mensajes). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp se ejecuta a través del canal web del Gateway (Baileys Web). Se inicia } ``` -- JSON de cuenta de servicio: integrado (`serviceAccount`) o basado en archivo (`serviceAccountFile`). +- JSON de cuenta de servicio: en línea (`serviceAccount`) o basado en archivo (`serviceAccountFile`). - También se admite SecretRef para la cuenta de servicio (`serviceAccountRef`). -- Variables de entorno de respaldo: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Use `spaces/` o `users/` para los destinos de entrega. -- `channels.googlechat.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia mutable por principal de correo electrónico (modo de compatibilidad break-glass). +- Respaldos por variable de entorno: `GOOGLE_CHAT_SERVICE_ACCOUNT` o `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Usa `spaces/` o `users/` para los destinos de entrega. +- `channels.googlechat.dangerouslyAllowNameMatching` vuelve a habilitar la coincidencia mutable de principals de correo electrónico (modo de compatibilidad de emergencia). ### Slack @@ -464,34 +464,29 @@ WhatsApp se ejecuta a través del canal web del Gateway (Baileys Web). Se inicia } ``` -- El **modo Socket** requiere tanto `botToken` como `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como respaldo de variables de entorno para la cuenta predeterminada). -- El **modo HTTP** requiere `botToken` más `signingSecret` (en la raíz o por cuenta). -- `botToken`, `appToken`, `signingSecret` y `userToken` aceptan cadenas - de texto sin formato u objetos SecretRef. -- Las instantáneas de cuenta de Slack exponen campos de origen/estado por credencial, como - `botTokenSource`, `botTokenStatus`, `appTokenStatus` y, en modo HTTP, - `signingSecretStatus`. `configured_unavailable` significa que la cuenta está - configurada mediante SecretRef pero la ruta actual de comando/tiempo de ejecución no pudo - resolver el valor del secreto. -- `configWrites: false` bloquea las escrituras de configuración iniciadas desde Slack. -- `channels.slack.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. -- `channels.slack.streaming.mode` es la clave canónica del modo de flujo de Slack. `channels.slack.streaming.nativeTransport` controla el transporte nativo de flujo de Slack. Los valores heredados `streamMode`, booleanos `streaming` y `nativeStreaming` se migran automáticamente. -- Use `user:` (MD) o `channel:` para los destinos de entrega. +- **Modo socket** requiere tanto `botToken` como `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` como respaldo por variable de entorno para la cuenta predeterminada). +- **Modo HTTP** requiere `botToken` más `signingSecret` (en la raíz o por cuenta). +- `botToken`, `appToken`, `signingSecret` y `userToken` aceptan cadenas de texto sin formato u objetos SecretRef. +- Las instantáneas de cuenta de Slack exponen campos por credencial de fuente/estado como `botTokenSource`, `botTokenStatus`, `appTokenStatus` y, en modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que la cuenta está configurada mediante SecretRef, pero la ruta actual de comando/tiempo de ejecución no pudo resolver el valor secreto. +- `configWrites: false` bloquea escrituras de configuración iniciadas desde Slack. +- `channels.slack.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- `channels.slack.streaming.mode` es la clave canónica del modo de transmisión de Slack. `channels.slack.streaming.nativeTransport` controla el transporte nativo de transmisión de Slack. Los valores heredados `streamMode`, `streaming` booleano y `nativeStreaming` se migran automáticamente. +- Usa `user:` (MD) o `channel:` para los destinos de entrega. -**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). +**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (de `reactionAllowlist`). -**Aislamiento de sesiones por hilo:** `thread.historyScope` es por hilo (predeterminado) o compartido en todo el canal. `thread.inheritParent` copia la transcripción del canal principal a los hilos nuevos. +**Aislamiento de sesión por hilo:** `thread.historyScope` es por hilo (predeterminado) o compartido en todo el canal. `thread.inheritParent` copia la transcripción del canal padre a los hilos nuevos. -- El flujo nativo de Slack más el estado de hilo estilo asistente de Slack "is typing..." requieren un destino de respuesta en hilo. Los MD de nivel superior permanecen fuera de hilo de forma predeterminada, por lo que usan `typingReaction` o la entrega normal en lugar de la vista previa estilo hilo. -- `typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras se está generando una respuesta y luego la elimina al finalizar. Use un shortcode de emoji de Slack como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega nativa en Slack de aprobaciones de exec y autorización de aprobadores. Mismo esquema que Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuario de Slack), `agentFilter`, `sessionFilter` y `target` (`"dm"`, `"channel"` o `"both"`). +- La transmisión nativa de Slack más el estado de hilo estilo asistente de Slack "is typing..." requieren un destino de hilo de respuesta. Las MD de nivel superior permanecen fuera de hilo de forma predeterminada, así que usan `typingReaction` o entrega normal en lugar de la vista previa estilo hilo. +- `typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras se está ejecutando una respuesta y luego la elimina al completarse. Usa un shortcode de emoji de Slack como `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: entrega nativa de aprobaciones de ejecución de Slack y autorización de aprobadores. Mismo esquema que Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuario de Slack), `agentFilter`, `sessionFilter` y `target` (`"dm"`, `"channel"` o `"both"`). | Grupo de acciones | Predeterminado | Notas | | ----------------- | -------------- | ------------------------- | | reactions | habilitado | Reaccionar + listar reacciones | | messages | habilitado | Leer/enviar/editar/eliminar | | pins | habilitado | Fijar/desfijar/listar | -| memberInfo | habilitado | Información del miembro | +| memberInfo | habilitado | Información de miembro | | emojiList | habilitado | Lista de emojis personalizados | ### Mattermost @@ -526,23 +521,18 @@ Mattermost se distribuye como un Plugin: `openclaw plugins install @openclaw/mat } ``` -Modos de chat: `oncall` (responder con mención @, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que comienzan con un prefijo de activación). +Modos de chat: `oncall` (responder en @mención, predeterminado), `onmessage` (cada mensaje), `onchar` (mensajes que empiezan con prefijo disparador). Cuando los comandos nativos de Mattermost están habilitados: -- `commands.callbackPath` debe ser una ruta (por ejemplo `/api/channels/mattermost/command`), no una URL completa. -- `commands.callbackUrl` debe resolver al endpoint del Gateway de OpenClaw y debe ser accesible desde el servidor de Mattermost. -- Las devoluciones de llamada nativas de barra se autentican con los tokens por comando devueltos - por Mattermost durante el registro del comando de barra. Si el registro falla o no - se activan comandos, OpenClaw rechaza las devoluciones de llamada con - `Unauthorized: invalid command token.` -- Para hosts de devolución de llamada privados/tailnet/internos, Mattermost puede requerir que - `ServiceSettings.AllowedUntrustedInternalConnections` incluya el host/dominio de devolución de llamada. - Use valores de host/dominio, no URL completas. +- `commands.callbackPath` debe ser una ruta (por ejemplo, `/api/channels/mattermost/command`), no una URL completa. +- `commands.callbackUrl` debe resolver al endpoint del gateway de OpenClaw y ser accesible desde el servidor de Mattermost. +- Las devoluciones de llamada slash nativas se autentican con los tokens por comando devueltos por Mattermost durante el registro de comandos slash. Si el registro falla o no se activa ningún comando, OpenClaw rechaza las devoluciones de llamada con `Unauthorized: invalid command token.` +- Para hosts de devolución de llamada privados/tailnet/internos, Mattermost puede requerir que `ServiceSettings.AllowedUntrustedInternalConnections` incluya el host/dominio de devolución de llamada. Usa valores de host/dominio, no URLs completas. - `channels.mattermost.configWrites`: permitir o denegar escrituras de configuración iniciadas desde Mattermost. - `channels.mattermost.requireMention`: requerir `@mention` antes de responder en canales. -- `channels.mattermost.groups..requireMention`: reemplazo por canal para la exigencia de mención (`"*"` para el valor predeterminado). -- `channels.mattermost.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. +- `channels.mattermost.groups..requireMention`: sobrescritura por canal del requisito de mención (`"*"` como predeterminado). +- `channels.mattermost.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. ### Signal @@ -563,11 +553,11 @@ Cuando los comandos nativos de Mattermost están habilitados: } ``` -**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (desde `reactionAllowlist`). +**Modos de notificación de reacciones:** `off`, `own` (predeterminado), `all`, `allowlist` (de `reactionAllowlist`). - `channels.signal.account`: fija el inicio del canal a una identidad de cuenta específica de Signal. -- `channels.signal.configWrites`: permite o deniega las escrituras de configuración iniciadas desde Signal. -- `channels.signal.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. +- `channels.signal.configWrites`: permite o deniega escrituras de configuración iniciadas desde Signal. +- `channels.signal.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. ### BlueBubbles @@ -587,13 +577,13 @@ BlueBubbles es la ruta recomendada para iMessage (respaldada por Plugin, configu ``` - Rutas de claves principales cubiertas aquí: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. -- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de BlueBubbles a sesiones persistentes de ACP. Use un identificador o cadena de destino de BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de los campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- `channels.bluebubbles.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de BlueBubbles a sesiones ACP persistentes. Usa un handle de BlueBubbles o una cadena objetivo (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). - La configuración completa del canal BlueBubbles está documentada en [BlueBubbles](/es/channels/bluebubbles). ### iMessage -OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puerto. +OpenClaw genera `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puerto. ```json5 { @@ -617,17 +607,17 @@ OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). No se requiere daemon ni puer } ``` -- `channels.imessage.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. +- `channels.imessage.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. -- Requiere acceso total al disco para la base de datos de Messages. -- Prefiera destinos `chat_id:`. Use `imsg chats --limit 20` para listar chats. -- `cliPath` puede apuntar a un contenedor SSH; configure `remoteHost` (`host` o `user@host`) para recuperar adjuntos mediante SCP. +- Requiere acceso completo al disco para la base de datos de Messages. +- Se prefieren destinos `chat_id:`. Usa `imsg chats --limit 20` para listar los chats. +- `cliPath` puede apuntar a un wrapper SSH; establece `remoteHost` (`host` o `user@host`) para la obtención de adjuntos mediante SCP. - `attachmentRoots` y `remoteAttachmentRoots` restringen las rutas de adjuntos entrantes (predeterminado: `/Users/*/Library/Messages/Attachments`). -- SCP usa validación estricta de claves de host, así que asegúrese de que la clave del host de retransmisión ya exista en `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: permite o deniega las escrituras de configuración iniciadas desde iMessage. -- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de iMessage a sesiones persistentes de ACP. Use un identificador normalizado o un destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de los campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). +- SCP usa verificación estricta de clave de host, así que asegúrate de que la clave del host de retransmisión ya exista en `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: permite o deniega escrituras de configuración iniciadas desde iMessage. +- Las entradas `bindings[]` de nivel superior con `type: "acp"` pueden vincular conversaciones de iMessage a sesiones ACP persistentes. Usa un handle normalizado o un destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) en `match.peer.id`. Semántica compartida de campos: [Agentes ACP](/es/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -669,19 +659,19 @@ Matrix está respaldado por una extensión y se configura en `channels.matrix`. ``` - La autenticación por token usa `accessToken`; la autenticación por contraseña usa `userId` + `password`. -- `channels.matrix.proxy` enruta el tráfico HTTP de Matrix a través de un proxy HTTP(S) explícito. Las cuentas con nombre pueden reemplazarlo con `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` y esta activación de red son controles independientes. +- `channels.matrix.proxy` enruta el tráfico HTTP de Matrix a través de un proxy HTTP(S) explícito. Las cuentas con nombre pueden sobrescribirlo con `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` y esta opción de red son controles independientes. - `channels.matrix.defaultAccount` selecciona la cuenta preferida en configuraciones con múltiples cuentas. -- `channels.matrix.autoJoin` tiene como valor predeterminado `off`, por lo que las salas invitadas y las nuevas invitaciones estilo MD se ignoran hasta que configure `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega nativa en Matrix de aprobaciones de exec y autorización de aprobadores. - - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, las aprobaciones de exec se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. - - `approvers`: IDs de usuario de Matrix (por ejemplo `@owner:example.org`) autorizados para aprobar solicitudes de exec. - - `agentFilter`: lista opcional de permitidos de IDs de agente. Omítala para reenviar aprobaciones para todos los agentes. +- `channels.matrix.autoJoin` tiene como valor predeterminado `off`, por lo que las salas invitadas y las invitaciones nuevas estilo MD se ignoran hasta que establezcas `autoJoin: "allowlist"` con `autoJoinAllowlist` o `autoJoin: "always"`. +- `channels.matrix.execApprovals`: entrega nativa de aprobaciones de ejecución de Matrix y autorización de aprobadores. + - `enabled`: `true`, `false` o `"auto"` (predeterminado). En modo automático, las aprobaciones de ejecución se activan cuando los aprobadores pueden resolverse desde `approvers` o `commands.ownerAllowFrom`. + - `approvers`: IDs de usuario de Matrix (por ejemplo `@owner:example.org`) autorizados para aprobar solicitudes de ejecución. + - `agentFilter`: lista opcional de permitidos de IDs de agente. Omítela para reenviar aprobaciones para todos los agentes. - `sessionFilter`: patrones opcionales de clave de sesión (subcadena o regex). - `target`: dónde enviar las solicitudes de aprobación. `"dm"` (predeterminado), `"channel"` (sala de origen) o `"both"`. - - Reemplazos por cuenta: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` controla cómo los MD de Matrix se agrupan en sesiones: `per-user` (predeterminado) comparte por par enrutado, mientras que `per-room` aísla cada sala de MD. -- Los sondeos de estado de Matrix y las búsquedas en directorios en vivo usan la misma política de proxy que el tráfico de tiempo de ejecución. + - Sobrescrituras por cuenta: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` controla cómo las MD de Matrix se agrupan en sesiones: `per-user` (predeterminado) comparte por par enrutado, mientras que `per-room` aísla cada sala de MD. +- Las sondas de estado de Matrix y las búsquedas del directorio en vivo usan la misma política de proxy que el tráfico en tiempo de ejecución. - La configuración completa de Matrix, las reglas de direccionamiento y los ejemplos de configuración están documentados en [Matrix](/es/channels/matrix). ### Microsoft Teams @@ -702,7 +692,7 @@ Microsoft Teams está respaldado por una extensión y se configura en `channels. ``` - Rutas de claves principales cubiertas aquí: `channels.msteams`, `channels.msteams.configWrites`. -- La configuración completa de Teams (credenciales, Webhook, política de MD/grupos, reemplazos por equipo/por canal) está documentada en [Microsoft Teams](/es/channels/msteams). +- La configuración completa de Teams (credenciales, webhook, política de MD/grupo, sobrescrituras por equipo/por canal) está documentada en [Microsoft Teams](/es/channels/msteams). ### IRC @@ -728,12 +718,12 @@ IRC está respaldado por una extensión y se configura en `channels.irc`. ``` - Rutas de claves principales cubiertas aquí: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opcional reemplaza la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado. -- La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permitidos/exigencia de mención) está documentada en [IRC](/es/channels/irc). +- `channels.irc.defaultAccount` opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un id de cuenta configurado. +- La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permitidos/requisito de mención) está documentada en [IRC](/es/channels/irc). ### Múltiples cuentas (todos los canales) -Ejecute múltiples cuentas por canal (cada una con su propio `accountId`): +Ejecuta múltiples cuentas por canal (cada una con su propio `accountId`): ```json5 { @@ -755,27 +745,27 @@ Ejecute múltiples cuentas por canal (cada una con su propio `accountId`): ``` - `default` se usa cuando se omite `accountId` (CLI + enrutamiento). -- Los tokens de entorno solo se aplican a la cuenta **predeterminada**. -- La configuración base del canal se aplica a todas las cuentas a menos que se reemplace por cuenta. -- Use `bindings[].match.accountId` para enrutar cada cuenta a un agente diferente. -- Si agrega una cuenta no predeterminada mediante `openclaw channels add` (o el proceso de incorporación del canal) mientras sigue usando una configuración de canal de nivel superior de cuenta única, OpenClaw primero promociona los valores de cuenta única de nivel superior con ámbito de cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueve a `channels..accounts.default`; Matrix puede preservar en su lugar un destino existente con nombre/predeterminado que coincida. -- Las vinculaciones existentes solo del canal (sin `accountId`) siguen coincidiendo con la cuenta predeterminada; las vinculaciones con ámbito de cuenta siguen siendo opcionales. -- `openclaw doctor --fix` también repara formas mixtas moviendo los valores de cuenta única de nivel superior con ámbito de cuenta a la cuenta promocionada elegida para ese canal. La mayoría de los canales usan `accounts.default`; Matrix puede preservar en su lugar un destino existente con nombre/predeterminado que coincida. +- Los tokens de entorno solo se aplican a la cuenta **default**. +- Los ajustes base del canal se aplican a todas las cuentas salvo que se sobrescriban por cuenta. +- Usa `bindings[].match.accountId` para enrutar cada cuenta a un agente distinto. +- Si agregas una cuenta no predeterminada mediante `openclaw channels add` (o la incorporación del canal) mientras aún estás en una configuración de canal de nivel superior de cuenta única, OpenClaw primero promueve los valores de cuenta única de nivel superior con alcance de cuenta al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueve a `channels..accounts.default`; Matrix puede conservar en su lugar un destino con nombre/default existente que coincida. +- Los enlaces existentes solo de canal (sin `accountId`) siguen coincidiendo con la cuenta predeterminada; los enlaces con alcance de cuenta siguen siendo opcionales. +- `openclaw doctor --fix` también repara formas mixtas moviendo los valores de cuenta única de nivel superior con alcance de cuenta a la cuenta promovida elegida para ese canal. La mayoría de los canales usan `accounts.default`; Matrix puede conservar en su lugar un destino con nombre/default existente que coincida. ### Otros canales de extensión -Muchos canales de extensión se configuran como `channels.` y están documentados en sus páginas dedicadas de canal (por ejemplo, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). -Consulte el índice completo de canales: [Canales](/es/channels). +Muchos canales de extensión se configuran como `channels.` y están documentados en sus páginas de canal dedicadas (por ejemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). +Consulta el índice completo de canales: [Canales](/es/channels). -### Exigencia de mención en chats grupales +### Requisito de mención en chats grupales -Los mensajes de grupo requieren mención de forma predeterminada (**require mention**) (mención en metadatos o patrones regex seguros). Se aplica a los chats grupales de WhatsApp, Telegram, Discord, Google Chat e iMessage. +Los mensajes de grupo requieren mención de forma predeterminada (**require mention**) (mención en metadatos o patrones regex seguros). Se aplica a chats grupales de WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipos de mención:** -- **Menciones en metadatos**: menciones @ nativas de la plataforma. Se ignoran en el modo de chat propio de WhatsApp. -- **Patrones de texto**: patrones regex seguros en `agents.list[].groupChat.mentionPatterns`. Los patrones no válidos y las repeticiones anidadas no seguras se ignoran. -- La exigencia de mención solo se aplica cuando la detección es posible (menciones nativas o al menos un patrón). +- **Menciones en metadatos**: @menciones nativas de la plataforma. Se ignoran en el modo de chat propio de WhatsApp. +- **Patrones de texto**: patrones regex seguros en `agents.list[].groupChat.mentionPatterns`. Los patrones inválidos y las repeticiones anidadas no seguras se ignoran. +- El requisito de mención solo se aplica cuando la detección es posible (menciones nativas o al menos un patrón). ```json5 { @@ -788,9 +778,9 @@ Los mensajes de grupo requieren mención de forma predeterminada (**require ment } ``` -`messages.groupChat.historyLimit` establece el valor predeterminado global. Los canales pueden reemplazarlo con `channels..historyLimit` (o por cuenta). Establézcalo en `0` para desactivarlo. +`messages.groupChat.historyLimit` establece el valor predeterminado global. Los canales pueden sobrescribirlo con `channels..historyLimit` (o por cuenta). Establece `0` para desactivarlo. -#### Límites de historial de MD +#### Límites del historial de MD ```json5 { @@ -805,13 +795,13 @@ Los mensajes de grupo requieren mención de forma predeterminada (**require ment } ``` -Resolución: reemplazo por MD → valor predeterminado del proveedor → sin límite (se conserva todo). +Resolución: sobrescritura por MD → valor predeterminado del proveedor → sin límite (se conserva todo). -Compatible con: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Compatibles: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Modo de chat propio -Incluya su propio número en `allowFrom` para habilitar el modo de chat propio (ignora las menciones @ nativas y solo responde a patrones de texto): +Incluye tu propio número en `allowFrom` para habilitar el modo de chat propio (ignora las @menciones nativas, solo responde a patrones de texto): ```json5 { @@ -861,32 +851,32 @@ Incluya su propio número en `allowFrom` para habilitar el modo de chat propio ( -- Este bloque configura las superficies de comandos. Para el catálogo actual de comandos integrados + bundled, consulte [Comandos de barra](/es/tools/slash-commands). -- Esta página es una **referencia de claves de configuración**, no el catálogo completo de comandos. Los comandos propiedad de canales/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` y Talk `/voice`, están documentados en sus páginas de canal/plugin y en [Comandos de barra](/es/tools/slash-commands). +- Este bloque configura las superficies de comandos. Para el catálogo actual de comandos integrados + bundled, consulta [Comandos slash](/es/tools/slash-commands). +- Esta página es una **referencia de claves de configuración**, no el catálogo completo de comandos. Los comandos propiedad de canales/plugins como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` y Talk `/voice` están documentados en sus páginas de canal/plugin además de en [Comandos slash](/es/tools/slash-commands). - Los comandos de texto deben ser mensajes **independientes** con `/` inicial. - `native: "auto"` activa los comandos nativos para Discord/Telegram y deja Slack desactivado. - `nativeSkills: "auto"` activa los comandos nativos de Skills para Discord/Telegram y deja Slack desactivado. -- Reemplazo por canal: `channels.discord.commands.native` (bool o `"auto"`). `false` borra los comandos registrados previamente. -- Reemplace el registro nativo de Skills por canal con `channels..commands.nativeSkills`. +- Sobrescritura por canal: `channels.discord.commands.native` (bool o `"auto"`). `false` borra los comandos registrados previamente. +- Sobrescribe el registro nativo de Skills por canal con `channels..commands.nativeSkills`. - `channels.telegram.customCommands` agrega entradas adicionales al menú del bot de Telegram. - `bash: true` habilita `! ` para el shell del host. Requiere `tools.elevated.enabled` y que el remitente esté en `tools.elevated.allowFrom.`. -- `config: true` habilita `/config` (lee/escribe `openclaw.json`). Para clientes `chat.send` del Gateway, las escrituras persistentes de `/config set|unset` también requieren `operator.admin`; `/config show` de solo lectura sigue estando disponible para clientes normales del operador con alcance de escritura. +- `config: true` habilita `/config` (lee/escribe `openclaw.json`). Para clientes `chat.send` del gateway, las escrituras persistentes de `/config set|unset` también requieren `operator.admin`; `/config show` de solo lectura sigue disponible para clientes operadores normales con alcance de escritura. - `mcp: true` habilita `/mcp` para la configuración del servidor MCP administrado por OpenClaw en `mcp.servers`. -- `plugins: true` habilita `/plugins` para descubrimiento de plugins, instalación y controles de activación/desactivación. -- `channels..configWrites` regula las mutaciones de configuración por canal (predeterminado: true). -- Para canales con múltiples cuentas, `channels..accounts..configWrites` también regula las escrituras dirigidas a esa cuenta (por ejemplo `/allowlist --config --account ` o `/config set channels..accounts....`). -- `restart: false` desactiva `/restart` y las acciones de la herramienta de reinicio del Gateway. Predeterminado: `true`. -- `ownerAllowFrom` es la lista explícita de permitidos del propietario para comandos/herramientas solo para el propietario. Es independiente de `allowFrom`. -- `ownerDisplay: "hash"` aplica hash a los IDs del propietario en el prompt del sistema. Configure `ownerDisplaySecret` para controlar el hash. -- `allowFrom` es por proveedor. Cuando está configurado, es la **única** fuente de autorización (las listas de permitidos/emparejamiento del canal y `useAccessGroups` se ignoran). -- `useAccessGroups: false` permite que los comandos omitan las políticas de grupos de acceso cuando `allowFrom` no está configurado. +- `plugins: true` habilita `/plugins` para descubrimiento de plugins, instalación y controles de habilitación/deshabilitación. +- `channels..configWrites` controla las mutaciones de configuración por canal (predeterminado: true). +- Para canales con múltiples cuentas, `channels..accounts..configWrites` también controla las escrituras dirigidas a esa cuenta (por ejemplo `/allowlist --config --account ` o `/config set channels..accounts....`). +- `restart: false` desactiva `/restart` y las acciones de la herramienta de reinicio del gateway. Predeterminado: `true`. +- `ownerAllowFrom` es la lista de permitidos explícita del propietario para comandos/herramientas solo para el propietario. Está separada de `allowFrom`. +- `ownerDisplay: "hash"` aplica hash a los ids del propietario en el prompt del sistema. Establece `ownerDisplaySecret` para controlar el hash. +- `allowFrom` es por proveedor. Cuando está definido, es la **única** fuente de autorización (las listas de permitidos/emparejamiento del canal y `useAccessGroups` se ignoran). +- `useAccessGroups: false` permite que los comandos omitan las políticas de grupos de acceso cuando `allowFrom` no está definido. - Mapa de documentación de comandos: - - catálogo integrado + bundled: [Comandos de barra](/es/tools/slash-commands) - - superficies de comandos específicas por canal: [Canales](/es/channels) + - catálogo integrado + bundled: [Comandos slash](/es/tools/slash-commands) + - superficies de comandos específicas del canal: [Canales](/es/channels) - comandos de QQ Bot: [QQ Bot](/es/channels/qqbot) - - comandos de emparejamiento: [Pairing](/es/channels/pairing) + - comandos de vinculación: [Vinculación](/es/channels/pairing) - comando de tarjeta de LINE: [LINE](/es/channels/line) - - dreaming de memoria: [Dreaming](/es/concepts/dreaming) + - memory dreaming: [Dreaming](/es/concepts/dreaming) @@ -906,7 +896,7 @@ Predeterminado: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raíz opcional del repositorio mostrada en la línea Runtime del prompt del sistema. Si no se configura, OpenClaw la detecta automáticamente recorriendo hacia arriba desde el workspace. +Raíz opcional del repositorio que se muestra en la línea Runtime del prompt del sistema. Si no está definida, OpenClaw la detecta automáticamente recorriendo hacia arriba desde el workspace. ```json5 { @@ -916,8 +906,7 @@ Raíz opcional del repositorio mostrada en la línea Runtime del prompt del sist ### `agents.defaults.skills` -Lista opcional predeterminada de permitidos de Skills para agentes que no configuran -`agents.list[].skills`. +Lista de permitidos predeterminada opcional de Skills para agentes que no establecen `agents.list[].skills`. ```json5 { @@ -932,11 +921,10 @@ Lista opcional predeterminada de permitidos de Skills para agentes que no config } ``` -- Omita `agents.defaults.skills` para Skills sin restricciones de forma predeterminada. -- Omita `agents.list[].skills` para heredar los valores predeterminados. -- Configure `agents.list[].skills: []` para no tener Skills. -- Una lista no vacía en `agents.list[].skills` es el conjunto final para ese agente; no - se combina con los valores predeterminados. +- Omite `agents.defaults.skills` para tener Skills sin restricciones de forma predeterminada. +- Omite `agents.list[].skills` para heredar los valores predeterminados. +- Establece `agents.list[].skills: []` para no tener Skills. +- Una lista no vacía en `agents.list[].skills` es el conjunto final para ese agente; no se fusiona con los valores predeterminados. ### `agents.defaults.skipBootstrap` @@ -952,7 +940,7 @@ Desactiva la creación automática de archivos bootstrap del workspace (`AGENTS. Controla cuándo se inyectan los archivos bootstrap del workspace en el prompt del sistema. Predeterminado: `"always"`. -- `"continuation-skip"`: los turnos seguros de continuación (después de una respuesta completada del asistente) omiten la reinyección del bootstrap del workspace, reduciendo el tamaño del prompt. Las ejecuciones de Heartbeat y los reintentos posteriores a Compaction siguen reconstruyendo el contexto. +- `"continuation-skip"`: los turnos de continuación seguros (después de una respuesta completada del asistente) omiten la reinyección del bootstrap del workspace, reduciendo el tamaño del prompt. Las ejecuciones de Heartbeat y los reintentos posteriores a la Compaction siguen reconstruyendo el contexto. ```json5 { @@ -962,21 +950,21 @@ Controla cuándo se inyectan los archivos bootstrap del workspace en el prompt d ### `agents.defaults.bootstrapMaxChars` -Máximo de caracteres por archivo bootstrap del workspace antes del truncamiento. Predeterminado: `20000`. +Máximo de caracteres por archivo bootstrap del workspace antes del truncamiento. Predeterminado: `12000`. ```json5 { - agents: { defaults: { bootstrapMaxChars: 20000 } }, + agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` -Máximo total de caracteres inyectados en todos los archivos bootstrap del workspace. Predeterminado: `150000`. +Máximo total de caracteres inyectados entre todos los archivos bootstrap del workspace. Predeterminado: `60000`. ```json5 { - agents: { defaults: { bootstrapTotalMaxChars: 150000 } }, + agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` @@ -986,7 +974,7 @@ Controla el texto de advertencia visible para el agente cuando el contexto boots Predeterminado: `"once"`. - `"off"`: nunca inyecta texto de advertencia en el prompt del sistema. -- `"once"`: inyecta la advertencia una vez por firma única de truncamiento (recomendado). +- `"once"`: inyecta la advertencia una vez por firma de truncamiento única (recomendado). - `"always"`: inyecta la advertencia en cada ejecución cuando existe truncamiento. ```json5 @@ -997,7 +985,7 @@ Predeterminado: `"once"`. ### Mapa de propiedad del presupuesto de contexto -OpenClaw tiene múltiples presupuestos de alto volumen para prompt/contexto, y están +OpenClaw tiene múltiples presupuestos de prompt/contexto de gran volumen, y están divididos intencionalmente por subsistema en lugar de pasar todos por una sola opción genérica. @@ -1005,16 +993,16 @@ opción genérica. `agents.defaults.bootstrapTotalMaxChars`: inyección bootstrap normal del workspace. - `agents.defaults.startupContext.*`: - preludio de inicio de una sola vez para ejecuciones de `/new` y `/reset`, incluidos los archivos recientes diarios de - `memory/*.md`. + preludio de inicio de una sola vez para `/new` y `/reset`, incluidos los + archivos recientes diarios `memory/*.md`. - `skills.limits.*`: la lista compacta de Skills inyectada en el prompt del sistema. - `agents.defaults.contextLimits.*`: - extractos acotados en tiempo de ejecución y bloques inyectados propiedad del runtime. + extractos limitados en tiempo de ejecución y bloques inyectados propiedad del runtime. - `memory.qmd.limits.*`: - tamaño del fragmento indexado de búsqueda de memoria y de la inyección. + tamaño de fragmentos de búsqueda de memoria indexada e inyección. -Use el reemplazo correspondiente por agente solo cuando un agente necesite un +Usa la sobrescritura por agente correspondiente solo cuando un agente necesite un presupuesto diferente: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1043,7 +1031,7 @@ Controla el preludio de inicio del primer turno inyectado en ejecuciones simples #### `agents.defaults.contextLimits` -Valores predeterminados compartidos para superficies de contexto acotadas del runtime. +Valores predeterminados compartidos para superficies de contexto limitadas en tiempo de ejecución. ```json5 { @@ -1060,18 +1048,14 @@ Valores predeterminados compartidos para superficies de contexto acotadas del ru } ``` -- `memoryGetMaxChars`: límite predeterminado del extracto de `memory_get` antes de que se agreguen - los metadatos de truncamiento y el aviso de continuación. -- `memoryGetDefaultLines`: ventana predeterminada de líneas de `memory_get` cuando se omite `lines`. -- `toolResultMaxChars`: límite de resultados de herramienta en vivo usado para resultados persistidos y - recuperación por desbordamiento. -- `postCompactionMaxChars`: límite del extracto de AGENTS.md usado durante la inyección de actualización - posterior a Compaction. +- `memoryGetMaxChars`: límite predeterminado del extracto de `memory_get` antes de que se agreguen los metadatos de truncamiento y el aviso de continuación. +- `memoryGetDefaultLines`: ventana de líneas predeterminada de `memory_get` cuando se omite `lines`. +- `toolResultMaxChars`: límite activo de resultados de herramientas usado para resultados persistidos y recuperación por desbordamiento. +- `postCompactionMaxChars`: límite del extracto de AGENTS.md usado durante la inyección de actualización posterior a Compaction. #### `agents.list[].contextLimits` -Reemplazo por agente para las opciones compartidas de `contextLimits`. Los campos omitidos heredan -de `agents.defaults.contextLimits`. +Sobrescritura por agente para las opciones compartidas de `contextLimits`. Los campos omitidos heredan de `agents.defaults.contextLimits`. ```json5 { @@ -1112,7 +1096,7 @@ no afecta la lectura de archivos `SKILL.md` bajo demanda. #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Reemplazo por agente para el presupuesto del prompt de Skills. +Sobrescritura por agente para el presupuesto del prompt de Skills. ```json5 { @@ -1135,7 +1119,7 @@ Tamaño máximo en píxeles del lado más largo de la imagen en bloques de image Predeterminado: `1200`. Los valores más bajos suelen reducir el uso de tokens de visión y el tamaño de la carga útil de la solicitud en ejecuciones con muchas capturas de pantalla. -Los valores más altos conservan más detalle visual. +Los valores más altos preservan más detalle visual. ```json5 { @@ -1219,42 +1203,42 @@ Formato de hora en el prompt del sistema. Predeterminado: `auto` (preferencia de - Lo usa la ruta de la herramienta `image` como configuración de su modelo de visión. - También se usa como enrutamiento de respaldo cuando el modelo seleccionado/predeterminado no puede aceptar entrada de imagen. - `imageGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usan la capacidad compartida de generación de imágenes y cualquier futura superficie de herramienta/plugin que genere imágenes. - - Valores típicos: `google/gemini-3.1-flash-image-preview` para generación nativa de imágenes de Gemini, `fal/fal-ai/flux/dev` para fal, o `openai/gpt-image-1` para OpenAI Images. - - Si selecciona directamente un proveedor/modelo, configure también la autenticación/la clave API del proveedor correspondiente (por ejemplo `GEMINI_API_KEY` o `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). - - Si se omite, `image_generate` aún puede inferir un proveedor predeterminado con autenticación disponible. Primero prueba el proveedor predeterminado actual y luego los demás proveedores de generación de imágenes registrados en orden por ID de proveedor. + - Lo usa la capacidad compartida de generación de imágenes y cualquier futura superficie de herramienta/plugin que genere imágenes. + - Valores típicos: `google/gemini-3.1-flash-image-preview` para generación de imágenes nativa de Gemini, `fal/fal-ai/flux/dev` para fal, u `openai/gpt-image-1` para OpenAI Images. + - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API del proveedor correspondiente (por ejemplo `GEMINI_API_KEY` o `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `FAL_KEY` para `fal/*`). + - Si se omite, `image_generate` aún puede inferir un valor predeterminado de proveedor respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los proveedores restantes de generación de imágenes registrados en orden de id de proveedor. - `musicGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usan la capacidad compartida de generación de música y la herramienta integrada `music_generate`. + - Lo usa la capacidad compartida de generación de música y la herramienta integrada `music_generate`. - Valores típicos: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` o `minimax/music-2.5+`. - - Si se omite, `music_generate` aún puede inferir un proveedor predeterminado con autenticación disponible. Primero prueba el proveedor predeterminado actual y luego los demás proveedores de generación de música registrados en orden por ID de proveedor. - - Si selecciona directamente un proveedor/modelo, configure también la autenticación/la clave API del proveedor correspondiente. + - Si se omite, `music_generate` aún puede inferir un valor predeterminado de proveedor respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los proveedores restantes de generación de música registrados en orden de id de proveedor. + - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API del proveedor correspondiente. - `videoGenerationModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usan la capacidad compartida de generación de video y la herramienta integrada `video_generate`. + - Lo usa la capacidad compartida de generación de video y la herramienta integrada `video_generate`. - Valores típicos: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` o `qwen/wan2.7-r2v`. - - Si se omite, `video_generate` aún puede inferir un proveedor predeterminado con autenticación disponible. Primero prueba el proveedor predeterminado actual y luego los demás proveedores de generación de video registrados en orden por ID de proveedor. - - Si selecciona directamente un proveedor/modelo, configure también la autenticación/la clave API del proveedor correspondiente. - - El proveedor bundled de generación de video de Qwen admite hasta 1 video de salida, 1 imagen de entrada, 4 videos de entrada, 10 segundos de duración y opciones a nivel de proveedor para `size`, `aspectRatio`, `resolution`, `audio` y `watermark`. + - Si se omite, `video_generate` aún puede inferir un valor predeterminado de proveedor respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los proveedores restantes de generación de video registrados en orden de id de proveedor. + - Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API del proveedor correspondiente. + - El proveedor bundled de generación de video Qwen admite hasta 1 video de salida, 1 imagen de entrada, 4 videos de entrada, 10 segundos de duración y opciones a nivel de proveedor `size`, `aspectRatio`, `resolution`, `audio` y `watermark`. - `pdfModel`: acepta una cadena (`"provider/model"`) o un objeto (`{ primary, fallbacks }`). - - Lo usa la herramienta `pdf` para el enrutamiento de modelos. - - Si se omite, la herramienta PDF recurre a `imageModel` y luego al modelo resuelto de la sesión/predeterminado. + - Lo usa la herramienta `pdf` para el enrutamiento del modelo. + - Si se omite, la herramienta PDF usa `imageModel` como respaldo y luego el modelo resuelto de la sesión/predeterminado. - `pdfMaxBytesMb`: límite predeterminado de tamaño de PDF para la herramienta `pdf` cuando no se pasa `maxBytesMb` en el momento de la llamada. - `pdfMaxPages`: máximo predeterminado de páginas consideradas por el modo de respaldo de extracción en la herramienta `pdf`. - `verboseDefault`: nivel verbose predeterminado para agentes. Valores: `"off"`, `"on"`, `"full"`. Predeterminado: `"off"`. - `elevatedDefault`: nivel predeterminado de salida elevada para agentes. Valores: `"off"`, `"on"`, `"ask"`, `"full"`. Predeterminado: `"on"`. -- `model.primary`: formato `provider/model` (por ejemplo `openai/gpt-5.4`). Si omite el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese ID exacto de modelo y solo después recurre al proveedor predeterminado configurado (comportamiento de compatibilidad obsoleto, por lo que se prefiere `provider/model` explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. -- `models`: el catálogo y la lista de permitidos de modelos configurados para `/model`. Cada entrada puede incluir `alias` (atajo) y `params` (específicos del proveedor, por ejemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parámetros globales predeterminados del proveedor aplicados a todos los modelos. Se configuran en `agents.defaults.params` (por ejemplo `{ cacheRetention: "long" }`). -- Precedencia de combinación de `params` (configuración): `agents.defaults.params` (base global) es reemplazado por `agents.defaults.models["provider/model"].params` (por modelo), y luego `agents.list[].params` (ID del agente correspondiente) reemplaza por clave. Consulte [Prompt Caching](/es/reference/prompt-caching) para más detalles. -- `embeddedHarness`: política predeterminada de runtime de bajo nivel para agentes integrados. Use `runtime: "auto"` para permitir que los harness de plugins registrados reclamen modelos compatibles, `runtime: "pi"` para forzar el harness PI integrado o un ID de harness registrado como `runtime: "codex"`. Configure `fallback: "none"` para desactivar el respaldo automático a PI. -- Los escritores de configuración que mutan estos campos (por ejemplo `/models set`, `/models set-image` y los comandos para agregar/eliminar respaldos) guardan la forma canónica de objeto y preservan las listas de respaldo existentes cuando es posible. +- `model.primary`: formato `provider/model` (por ejemplo `openai/gpt-5.4`). Si omites el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese id de modelo exacto, y solo entonces vuelve al proveedor predeterminado configurado (comportamiento heredado y obsoleto de compatibilidad, así que se prefiere `provider/model` explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado. +- `models`: el catálogo de modelos configurado y la lista de permitidos para `/model`. Cada entrada puede incluir `alias` (atajo) y `params` (específicos del proveedor, por ejemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parámetros globales predeterminados del proveedor aplicados a todos los modelos. Se establecen en `agents.defaults.params` (por ejemplo `{ cacheRetention: "long" }`). +- Precedencia de fusión de `params` (config): `agents.defaults.params` (base global) es sobrescrito por `agents.defaults.models["provider/model"].params` (por modelo), y luego `agents.list[].params` (id de agente coincidente) sobrescribe por clave. Consulta [Prompt Caching](/es/reference/prompt-caching) para más detalles. +- `embeddedHarness`: política predeterminada de runtime de agente incrustado de bajo nivel. Usa `runtime: "auto"` para permitir que los harnesses de plugins registrados reclamen modelos compatibles, `runtime: "pi"` para forzar el harness PI integrado, o un id de harness registrado como `runtime: "codex"`. Establece `fallback: "none"` para desactivar el respaldo automático a PI. +- Los escritores de configuración que mutan estos campos (por ejemplo `/models set`, `/models set-image` y comandos de agregar/quitar respaldo) guardan la forma canónica de objeto y preservan las listas de respaldo existentes cuando es posible. - `maxConcurrent`: máximo de ejecuciones paralelas de agentes entre sesiones (cada sesión sigue serializada). Predeterminado: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` controla qué ejecutor de bajo nivel ejecuta los turnos de agentes integrados. +`embeddedHarness` controla qué ejecutor de bajo nivel ejecuta los turnos de agente incrustado. La mayoría de las implementaciones deberían mantener el valor predeterminado `{ runtime: "auto", fallback: "pi" }`. -Úselo cuando un Plugin de confianza proporcione un harness nativo, como el harness bundled -del servidor de aplicaciones de Codex. +Úsalo cuando un plugin de confianza proporcione un harness nativo, como el harness bundled +de servidor de aplicación Codex. ```json5 { @@ -1270,13 +1254,13 @@ del servidor de aplicaciones de Codex. } ``` -- `runtime`: `"auto"`, `"pi"` o un ID de harness de Plugin registrado. El Plugin bundled de Codex registra `codex`. -- `fallback`: `"pi"` o `"none"`. `"pi"` mantiene el harness PI integrado como respaldo de compatibilidad. `"none"` hace que la selección de un harness de Plugin faltante o no compatible falle en lugar de usar PI silenciosamente. -- Reemplazos por entorno: `OPENCLAW_AGENT_RUNTIME=` reemplaza `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desactiva el respaldo a PI para ese proceso. -- Para implementaciones solo de Codex, configure `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` y `embeddedHarness.fallback: "none"`. -- Esto solo controla el harness de chat integrado. La generación de medios, visión, PDF, música, video y TTS siguen usando su configuración de proveedor/modelo. +- `runtime`: `"auto"`, `"pi"` o un id de harness de plugin registrado. El plugin bundled Codex registra `codex`. +- `fallback`: `"pi"` o `"none"`. `"pi"` mantiene el harness PI integrado como respaldo de compatibilidad. `"none"` hace que la selección de un harness de plugin ausente o no compatible falle en lugar de usar PI silenciosamente. +- Sobrescrituras de entorno: `OPENCLAW_AGENT_RUNTIME=` sobrescribe `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desactiva el respaldo a PI para ese proceso. +- Para implementaciones solo de Codex, establece `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` y `embeddedHarness.fallback: "none"`. +- Esto solo controla el harness de chat incrustado. La generación de medios, visión, PDF, música, video y TTS siguen usando su configuración de proveedor/modelo. -**Alias abreviados integrados** (solo se aplican cuando el modelo está en `agents.defaults.models`): +**Atajos de alias integrados** (solo se aplican cuando el modelo está en `agents.defaults.models`): | Alias | Modelo | | ------------------- | -------------------------------------- | @@ -1289,15 +1273,15 @@ del servidor de aplicaciones de Codex. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Sus alias configurados siempre prevalecen sobre los predeterminados. +Tus alias configurados siempre tienen prioridad sobre los predeterminados. -Los modelos GLM-4.x de Z.AI habilitan automáticamente el modo thinking a menos que configure `--thinking off` o defina usted mismo `agents.defaults.models["zai/"].params.thinking`. -Los modelos de Z.AI habilitan `tool_stream` de forma predeterminada para el streaming de llamadas a herramientas. Configure `agents.defaults.models["zai/"].params.tool_stream` en `false` para desactivarlo. -Los modelos Claude 4.6 de Anthropic usan `adaptive` como thinking predeterminado cuando no se configura un nivel explícito de thinking. +Los modelos Z.AI GLM-4.x habilitan automáticamente el modo thinking a menos que establezcas `--thinking off` o definas tú mismo `agents.defaults.models["zai/"].params.thinking`. +Los modelos Z.AI habilitan `tool_stream` de forma predeterminada para el streaming de llamadas a herramientas. Establece `agents.defaults.models["zai/"].params.tool_stream` en `false` para desactivarlo. +Los modelos Anthropic Claude 4.6 usan `adaptive` thinking de forma predeterminada cuando no se establece un nivel explícito de thinking. ### `agents.defaults.cliBackends` -Backends de CLI opcionales para ejecuciones de respaldo solo de texto (sin llamadas a herramientas). Son útiles como respaldo cuando fallan los proveedores de API. +Backends opcionales de CLI para ejecuciones de respaldo solo de texto (sin llamadas a herramientas). Útiles como respaldo cuando fallan los proveedores de API. ```json5 { @@ -1326,12 +1310,12 @@ Backends de CLI opcionales para ejecuciones de respaldo solo de texto (sin llama ``` - Los backends de CLI son principalmente de texto; las herramientas siempre están desactivadas. -- Las sesiones son compatibles cuando se configura `sessionArg`. -- Se admite el paso directo de imágenes cuando `imageArg` acepta rutas de archivo. +- Las sesiones son compatibles cuando se establece `sessionArg`. +- El paso de imágenes es compatible cuando `imageArg` acepta rutas de archivos. ### `agents.defaults.systemPromptOverride` -Reemplaza todo el prompt del sistema ensamblado por OpenClaw con una cadena fija. Se configura en el nivel predeterminado (`agents.defaults.systemPromptOverride`) o por agente (`agents.list[].systemPromptOverride`). Los valores por agente tienen prioridad; un valor vacío o que solo contiene espacios en blanco se ignora. Es útil para experimentos controlados de prompts. +Reemplaza todo el prompt del sistema ensamblado por OpenClaw con una cadena fija. Se establece en el nivel predeterminado (`agents.defaults.systemPromptOverride`) o por agente (`agents.list[].systemPromptOverride`). Los valores por agente tienen prioridad; un valor vacío o con solo espacios en blanco se ignora. Útil para experimentos controlados de prompt. ```json5 { @@ -1372,15 +1356,15 @@ Ejecuciones periódicas de Heartbeat. } ``` -- `every`: cadena de duración (ms/s/m/h). Predeterminado: `30m` (autenticación con clave API) o `1h` (autenticación OAuth). Configure `0m` para desactivarlo. -- `includeSystemPromptSection`: cuando es false, omite la sección de Heartbeat del prompt del sistema y omite la inyección de `HEARTBEAT.md` en el contexto bootstrap. Predeterminado: `true`. -- `suppressToolErrorWarnings`: cuando es true, suprime las cargas útiles de advertencia de errores de herramientas durante las ejecuciones de Heartbeat. -- `timeoutSeconds`: tiempo máximo en segundos permitido para un turno de agente de Heartbeat antes de abortarlo. Déjelo sin configurar para usar `agents.defaults.timeoutSeconds`. -- `directPolicy`: política de entrega directa/MD. `allow` (predeterminado) permite la entrega con destino directo. `block` suprime la entrega con destino directo y emite `reason=dm-blocked`. +- `every`: cadena de duración (ms/s/m/h). Predeterminado: `30m` (autenticación con clave de API) o `1h` (autenticación OAuth). Establece `0m` para desactivar. +- `includeSystemPromptSection`: cuando es false, omite la sección Heartbeat del prompt del sistema y omite la inyección de `HEARTBEAT.md` en el contexto bootstrap. Predeterminado: `true`. +- `suppressToolErrorWarnings`: cuando es true, suprime las cargas útiles de advertencia de error de herramientas durante las ejecuciones de Heartbeat. +- `timeoutSeconds`: tiempo máximo en segundos permitido para un turno de agente de Heartbeat antes de cancelarlo. Déjalo sin definir para usar `agents.defaults.timeoutSeconds`. +- `directPolicy`: política de entrega directa/MD. `allow` (predeterminado) permite la entrega a destino directo. `block` suprime la entrega a destino directo y emite `reason=dm-blocked`. - `lightContext`: cuando es true, las ejecuciones de Heartbeat usan un contexto bootstrap ligero y conservan solo `HEARTBEAT.md` de los archivos bootstrap del workspace. -- `isolatedSession`: cuando es true, cada ejecución de Heartbeat se realiza en una sesión nueva sin historial previo de conversación. Mismo patrón de aislamiento que Cron `sessionTarget: "isolated"`. Reduce el costo de tokens por Heartbeat de ~100K a ~2-5K tokens. -- Por agente: configure `agents.list[].heartbeat`. Cuando cualquier agente define `heartbeat`, **solo esos agentes** ejecutan Heartbeat. -- Los Heartbeats ejecutan turnos completos del agente: intervalos más cortos consumen más tokens. +- `isolatedSession`: cuando es true, cada Heartbeat se ejecuta en una sesión nueva sin historial de conversación previo. Mismo patrón de aislamiento que Cron `sessionTarget: "isolated"`. Reduce el costo de tokens por Heartbeat de ~100K a ~2-5K tokens. +- Por agente: establece `agents.list[].heartbeat`. Cuando cualquier agente define `heartbeat`, **solo esos agentes** ejecutan Heartbeat. +- Heartbeat ejecuta turnos completos del agente: intervalos más cortos consumen más tokens. ### `agents.defaults.compaction` @@ -1410,19 +1394,19 @@ Ejecuciones periódicas de Heartbeat. } ``` -- `mode`: `default` o `safeguard` (resumen por fragmentos para historiales largos). Consulte [Compaction](/es/concepts/compaction). -- `provider`: ID de un Plugin proveedor de Compaction registrado. Cuando se configura, se llama a `summarize()` del proveedor en lugar del resumen LLM integrado. En caso de error, recurre al integrado. Configurar un proveedor fuerza `mode: "safeguard"`. Consulte [Compaction](/es/concepts/compaction). -- `timeoutSeconds`: segundos máximos permitidos para una sola operación de Compaction antes de que OpenClaw la aborte. Predeterminado: `900`. -- `identifierPolicy`: `strict` (predeterminado), `off` o `custom`. `strict` antepone orientación integrada de conservación de identificadores opacos durante el resumen de Compaction. -- `identifierInstructions`: texto personalizado opcional de conservación de identificadores usado cuando `identifierPolicy=custom`. -- `postCompactionSections`: nombres opcionales de secciones H2/H3 de AGENTS.md para volver a inyectar después de Compaction. El valor predeterminado es `["Session Startup", "Red Lines"]`; configure `[]` para desactivar la reinyección. Cuando no se configura o se configura explícitamente con ese par predeterminado, también se aceptan los encabezados heredados `Every Session`/`Safety` como respaldo heredado. -- `model`: reemplazo opcional `provider/model-id` solo para el resumen de Compaction. Úselo cuando la sesión principal deba conservar un modelo pero los resúmenes de Compaction deban ejecutarse con otro; cuando no se configura, Compaction usa el modelo principal de la sesión. -- `notifyUser`: cuando es `true`, envía un aviso breve al usuario cuando comienza Compaction (por ejemplo, "Compacting context..."). Está desactivado de forma predeterminada para mantener Compaction silencioso. -- `memoryFlush`: turno agéntico silencioso antes de la Compactación automática para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura. +- `mode`: `default` o `safeguard` (resumen por fragmentos para historiales largos). Consulta [Compaction](/es/concepts/compaction). +- `provider`: id de un Plugin proveedor de Compaction registrado. Cuando se establece, se llama a `summarize()` del proveedor en lugar del resumen LLM integrado. En caso de fallo, vuelve al integrado. Establecer un proveedor fuerza `mode: "safeguard"`. Consulta [Compaction](/es/concepts/compaction). +- `timeoutSeconds`: máximo de segundos permitidos para una sola operación de Compaction antes de que OpenClaw la cancele. Predeterminado: `900`. +- `identifierPolicy`: `strict` (predeterminado), `off` o `custom`. `strict` antepone instrucciones integradas de conservación de identificadores opacos durante el resumen de Compaction. +- `identifierInstructions`: texto opcional personalizado de conservación de identificadores usado cuando `identifierPolicy=custom`. +- `postCompactionSections`: nombres opcionales de secciones H2/H3 de AGENTS.md para reinyectar después de Compaction. Predeterminado: `["Session Startup", "Red Lines"]`; establece `[]` para desactivar la reinyección. Cuando no está definido o se establece explícitamente en ese par predeterminado, también se aceptan los encabezados heredados `Every Session`/`Safety` como respaldo heredado. +- `model`: sobrescritura opcional `provider/model-id` solo para el resumen de Compaction. Úsalo cuando la sesión principal deba mantener un modelo pero los resúmenes de Compaction deban ejecutarse en otro; cuando no está definido, Compaction usa el modelo principal de la sesión. +- `notifyUser`: cuando es `true`, envía un aviso breve al usuario cuando comienza Compaction (por ejemplo, "Compacting context..."). Está desactivado de forma predeterminada para que Compaction sea silenciosa. +- `memoryFlush`: turno agentivo silencioso antes de la auto-Compaction para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura. ### `agents.defaults.contextPruning` -Poda **resultados antiguos de herramientas** del contexto en memoria antes de enviarlo al LLM. **No** modifica el historial de la sesión en disco. +Elimina **resultados antiguos de herramientas** del contexto en memoria antes de enviarlo al LLM. **No** modifica el historial de la sesión en disco. ```json5 { @@ -1447,8 +1431,8 @@ Poda **resultados antiguos de herramientas** del contexto en memoria antes de en - `mode: "cache-ttl"` habilita pasadas de poda. -- `ttl` controla con qué frecuencia puede volver a ejecutarse la poda (después del último acceso a caché). -- La poda primero recorta suavemente los resultados sobredimensionados de herramientas y luego vacía por completo resultados antiguos de herramientas si es necesario. +- `ttl` controla con qué frecuencia puede volver a ejecutarse la poda (después del último acceso a la caché). +- La poda primero recorta suavemente los resultados de herramientas sobredimensionados y luego limpia por completo los resultados más antiguos si es necesario. **Soft-trim** conserva el principio y el final e inserta `...` en el medio. @@ -1456,13 +1440,13 @@ Poda **resultados antiguos de herramientas** del contexto en memoria antes de en Notas: -- Los bloques de imagen nunca se recortan ni se vacían. +- Los bloques de imagen nunca se recortan ni se limpian. - Las proporciones se basan en caracteres (aproximadas), no en recuentos exactos de tokens. - Si existen menos de `keepLastAssistants` mensajes del asistente, la poda se omite. -Consulte [Poda de sesiones](/es/concepts/session-pruning) para ver detalles del comportamiento. +Consulta [Poda de sesión](/es/concepts/session-pruning) para los detalles del comportamiento. ### Streaming por bloques @@ -1481,10 +1465,10 @@ Consulte [Poda de sesiones](/es/concepts/session-pruning) para ver detalles del ``` - Los canales que no son Telegram requieren `*.blockStreaming: true` explícito para habilitar respuestas por bloques. -- Reemplazos por canal: `channels..blockStreamingCoalesce` (y variantes por cuenta). Signal/Slack/Discord/Google Chat usan como predeterminado `minChars: 1500`. -- `humanDelay`: pausa aleatoria entre respuestas por bloques. `natural` = 800–2500 ms. Reemplazo por agente: `agents.list[].humanDelay`. +- Sobrescrituras por canal: `channels..blockStreamingCoalesce` (y variantes por cuenta). Signal/Slack/Discord/Google Chat tienen como valor predeterminado `minChars: 1500`. +- `humanDelay`: pausa aleatoria entre respuestas por bloques. `natural` = 800–2500 ms. Sobrescritura por agente: `agents.list[].humanDelay`. -Consulte [Streaming](/es/concepts/streaming) para ver el comportamiento y los detalles de fragmentación. +Consulta [Streaming](/es/concepts/streaming) para el comportamiento y los detalles de fragmentación. ### Indicadores de escritura @@ -1500,15 +1484,15 @@ Consulte [Streaming](/es/concepts/streaming) para ver el comportamiento y los de ``` - Predeterminados: `instant` para chats directos/menciones, `message` para chats grupales sin mención. -- Reemplazos por sesión: `session.typingMode`, `session.typingIntervalSeconds`. +- Sobrescrituras por sesión: `session.typingMode`, `session.typingIntervalSeconds`. -Consulte [Indicadores de escritura](/es/concepts/typing-indicators). +Consulta [Indicadores de escritura](/es/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandbox opcional para el agente integrado. Consulte [Sandboxing](/es/gateway/sandboxing) para la guía completa. +Sandbox opcional para el agente incrustado. Consulta [Sandboxing](/es/gateway/sandboxing) para la guía completa. ```json5 { @@ -1603,7 +1587,7 @@ Sandbox opcional para el agente integrado. Consulte [Sandboxing](/es/gateway/san } ``` - + **Backend:** @@ -1616,33 +1600,33 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del r **Configuración del backend SSH:** -- `target`: destino SSH en formato `user@host[:port]` +- `target`: destino SSH con formato `user@host[:port]` - `command`: comando del cliente SSH (predeterminado: `ssh`) - `workspaceRoot`: raíz remota absoluta usada para workspaces por alcance - `identityFile` / `certificateFile` / `knownHostsFile`: archivos locales existentes pasados a OpenSSH - `identityData` / `certificateData` / `knownHostsData`: contenidos en línea o SecretRefs que OpenClaw materializa en archivos temporales en tiempo de ejecución -- `strictHostKeyChecking` / `updateHostKeys`: opciones de política de clave de host de OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: opciones de política de claves de host de OpenSSH **Precedencia de autenticación SSH:** - `identityData` tiene prioridad sobre `identityFile` - `certificateData` tiene prioridad sobre `certificateFile` - `knownHostsData` tiene prioridad sobre `knownHostsFile` -- Los valores `*Data` respaldados por SecretRef se resuelven desde la instantánea activa del runtime de secretos antes de que comience la sesión de sandbox +- Los valores `*Data` respaldados por SecretRef se resuelven a partir de la instantánea activa del runtime de secretos antes de que comience la sesión del sandbox **Comportamiento del backend SSH:** - inicializa el workspace remoto una vez después de crear o recrear -- luego mantiene como canónico el workspace SSH remoto -- enruta `exec`, herramientas de archivos y rutas de medios sobre SSH -- no sincroniza automáticamente de vuelta al host los cambios remotos -- no admite contenedores de navegador en sandbox +- luego mantiene el workspace SSH remoto como canónico +- enruta `exec`, herramientas de archivos y rutas de medios a través de SSH +- no sincroniza automáticamente los cambios remotos de vuelta al host +- no admite contenedores de navegador del sandbox **Acceso al workspace:** -- `none`: workspace de sandbox por alcance bajo `~/.openclaw/sandboxes` -- `ro`: workspace de sandbox en `/workspace`, workspace del agente montado como solo lectura en `/agent` -- `rw`: workspace del agente montado en lectura/escritura en `/workspace` +- `none`: workspace del sandbox por alcance en `~/.openclaw/sandboxes` +- `ro`: workspace del sandbox en `/workspace`, workspace del agente montado como solo lectura en `/agent` +- `rw`: workspace del agente montado con lectura/escritura en `/workspace` **Alcance:** @@ -1678,30 +1662,30 @@ Cuando se selecciona `backend: "openshell"`, la configuración específica del r **Modo OpenShell:** -- `mirror`: inicializa el remoto desde el local antes de `exec`, sincroniza de vuelta después de `exec`; el workspace local sigue siendo canónico +- `mirror`: inicializa el remoto desde el local antes de `exec`, sincroniza de vuelta después de `exec`; el workspace local sigue siendo el canónico - `remote`: inicializa el remoto una vez cuando se crea el sandbox y luego mantiene el workspace remoto como canónico -En modo `remote`, las ediciones locales del host hechas fuera de OpenClaw no se sincronizan automáticamente dentro del sandbox después del paso de inicialización. -El transporte es SSH hacia el sandbox de OpenShell, pero el Plugin gestiona el ciclo de vida del sandbox y la sincronización espejo opcional. +En modo `remote`, las ediciones locales del host realizadas fuera de OpenClaw no se sincronizan automáticamente con el sandbox después del paso de inicialización. +El transporte es SSH al sandbox de OpenShell, pero el plugin es propietario del ciclo de vida del sandbox y de la sincronización mirror opcional. -**`setupCommand`** se ejecuta una vez después de crear el contenedor (mediante `sh -lc`). Necesita salida de red, raíz escribible y usuario root. +**`setupCommand`** se ejecuta una vez después de la creación del contenedor (mediante `sh -lc`). Necesita salida de red, raíz escribible y usuario root. -**Los contenedores usan por defecto `network: "none"`**; configure `"bridge"` (o una red bridge personalizada) si el agente necesita acceso saliente. -`"host"` está bloqueado. `"container:"` está bloqueado de forma predeterminada a menos que configure explícitamente -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). +**Los contenedores tienen como valor predeterminado `network: "none"`**: establécelo en `"bridge"` (o una red bridge personalizada) si el agente necesita acceso saliente. +`"host"` está bloqueado. `"container:"` está bloqueado de forma predeterminada a menos que establezcas explícitamente +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (modo de emergencia). -**Los adjuntos entrantes** se almacenan provisionalmente en `media/inbound/*` en el workspace activo. +**Los adjuntos entrantes** se preparan en `media/inbound/*` en el workspace activo. -**`docker.binds`** monta directorios adicionales del host; los montajes globales y por agente se combinan. +**`docker.binds`** monta directorios adicionales del host; los binds globales y por agente se fusionan. **Navegador en sandbox** (`sandbox.browser.enabled`): Chromium + CDP en un contenedor. La URL de noVNC se inyecta en el prompt del sistema. No requiere `browser.enabled` en `openclaw.json`. -El acceso de observador por noVNC usa autenticación VNC de forma predeterminada y OpenClaw emite una URL con token de corta duración (en lugar de exponer la contraseña en la URL compartida). +El acceso de observador de noVNC usa autenticación VNC de forma predeterminada y OpenClaw emite una URL con token de corta duración (en lugar de exponer la contraseña en la URL compartida). - `allowHostControl: false` (predeterminado) bloquea que las sesiones en sandbox apunten al navegador del host. -- `network` usa como predeterminado `openclaw-sandbox-browser` (red bridge dedicada). Configure `bridge` solo cuando desee explícitamente conectividad global de bridge. -- `cdpSourceRange` restringe opcionalmente el ingreso de CDP en el borde del contenedor a un rango CIDR (por ejemplo `172.21.0.1/32`). -- `sandbox.browser.binds` monta directorios adicionales del host solo en el contenedor del navegador en sandbox. Cuando se configura (incluido `[]`), reemplaza `docker.binds` para el contenedor del navegador. -- Los valores predeterminados de lanzamiento se definen en `scripts/sandbox-browser-entrypoint.sh` y están ajustados para hosts en contenedor: +- `network` tiene como valor predeterminado `openclaw-sandbox-browser` (red bridge dedicada). Establécelo en `bridge` solo cuando quieras explícitamente conectividad bridge global. +- `cdpSourceRange` restringe opcionalmente la entrada de CDP en el borde del contenedor a un rango CIDR (por ejemplo `172.21.0.1/32`). +- `sandbox.browser.binds` monta directorios adicionales del host solo en el contenedor del navegador en sandbox. Cuando se establece (incluido `[]`), reemplaza `docker.binds` para el contenedor del navegador. +- Los valores predeterminados de lanzamiento se definen en `scripts/sandbox-browser-entrypoint.sh` y están ajustados para hosts de contenedores: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1722,26 +1706,26 @@ El acceso de observador por noVNC usa autenticación VNC de forma predeterminada - `--disable-3d-apis`, `--disable-software-rasterizer` y `--disable-gpu` están habilitados de forma predeterminada y pueden desactivarse con `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` si el uso de WebGL/3D lo requiere. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` vuelve a habilitar las extensiones si su flujo de trabajo + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` vuelve a habilitar las extensiones si tu flujo de trabajo depende de ellas. - `--renderer-process-limit=2` puede cambiarse con - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; configure `0` para usar el + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; establece `0` para usar el límite de procesos predeterminado de Chromium. - - además de `--no-sandbox` y `--disable-setuid-sandbox` cuando `noSandbox` está habilitado. - - Los valores predeterminados son la línea base de la imagen del contenedor; use una imagen de navegador personalizada con un entrypoint personalizado para cambiar los valores predeterminados del contenedor. + - además `--no-sandbox` y `--disable-setuid-sandbox` cuando `noSandbox` está habilitado. + - Los valores predeterminados son la línea base de la imagen del contenedor; usa una imagen de navegador personalizada con un entrypoint personalizado para cambiar los valores predeterminados del contenedor. -El sandboxing del navegador y `sandbox.docker.binds` solo están disponibles con Docker. +El sandboxing del navegador y `sandbox.docker.binds` son solo para Docker. -Compilar imágenes: +Construir imágenes: ```bash scripts/sandbox-setup.sh # main sandbox image scripts/sandbox-browser-setup.sh # optional browser image ``` -### `agents.list` (reemplazos por agente) +### `agents.list` (sobrescrituras por agente) ```json5 { @@ -1790,27 +1774,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: ID estable del agente (obligatorio). -- `default`: cuando se configuran varios, gana el primero (se registra una advertencia). Si no se configura ninguno, la primera entrada de la lista es la predeterminada. -- `model`: la forma de cadena reemplaza solo `primary`; la forma de objeto `{ primary, fallbacks }` reemplaza ambos (`[]` desactiva los respaldos globales). Los trabajos Cron que solo reemplazan `primary` siguen heredando los respaldos predeterminados a menos que configure `fallbacks: []`. -- `params`: parámetros de flujo por agente combinados sobre la entrada de modelo seleccionada en `agents.defaults.models`. Use esto para reemplazos específicos del agente como `cacheRetention`, `temperature` o `maxTokens` sin duplicar todo el catálogo de modelos. -- `skills`: lista opcional de permitidos de Skills por agente. Si se omite, el agente hereda `agents.defaults.skills` cuando está configurado; una lista explícita reemplaza los valores predeterminados en lugar de combinarse, y `[]` significa sin Skills. -- `thinkingDefault`: nivel predeterminado opcional de thinking por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Reemplaza `agents.defaults.thinkingDefault` para este agente cuando no se configura un reemplazo por mensaje o por sesión. -- `reasoningDefault`: visibilidad predeterminada opcional del razonamiento por agente (`on | off | stream`). Se aplica cuando no se configura un reemplazo de razonamiento por mensaje o por sesión. -- `fastModeDefault`: valor predeterminado opcional por agente para modo rápido (`true | false`). Se aplica cuando no se configura un reemplazo de modo rápido por mensaje o por sesión. -- `embeddedHarness`: reemplazo opcional por agente para la política del harness de bajo nivel. Use `{ runtime: "codex", fallback: "none" }` para que un agente use solo Codex mientras otros agentes conservan el respaldo predeterminado PI. -- `runtime`: descriptor opcional del runtime por agente. Use `type: "acp"` con valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar por defecto sesiones de harness ACP. +- `id`: id estable del agente (obligatorio). +- `default`: cuando se establecen varios, gana el primero (se registra una advertencia). Si no se establece ninguno, la primera entrada de la lista es la predeterminada. +- `model`: la forma de cadena sobrescribe solo `primary`; la forma de objeto `{ primary, fallbacks }` sobrescribe ambos (`[]` desactiva los respaldos globales). Los trabajos Cron que solo sobrescriben `primary` siguen heredando los respaldos predeterminados a menos que establezcas `fallbacks: []`. +- `params`: parámetros de stream por agente fusionados sobre la entrada de modelo seleccionada en `agents.defaults.models`. Usa esto para sobrescrituras específicas del agente como `cacheRetention`, `temperature` o `maxTokens` sin duplicar todo el catálogo de modelos. +- `skills`: lista de permitidos opcional de Skills por agente. Si se omite, el agente hereda `agents.defaults.skills` cuando está establecido; una lista explícita reemplaza los valores predeterminados en lugar de fusionarlos, y `[]` significa que no hay Skills. +- `thinkingDefault`: sobrescritura opcional por agente para el nivel predeterminado de thinking (`off | minimal | low | medium | high | xhigh | adaptive`). Sobrescribe `agents.defaults.thinkingDefault` para este agente cuando no se establece una sobrescritura por mensaje o sesión. +- `reasoningDefault`: sobrescritura opcional por agente para la visibilidad predeterminada de reasoning (`on | off | stream`). Se aplica cuando no se establece una sobrescritura de reasoning por mensaje o sesión. +- `fastModeDefault`: valor predeterminado opcional por agente para el modo rápido (`true | false`). Se aplica cuando no se establece una sobrescritura por mensaje o sesión. +- `embeddedHarness`: sobrescritura opcional por agente de la política del harness de bajo nivel. Usa `{ runtime: "codex", fallback: "none" }` para hacer que un agente sea solo Codex mientras otros agentes conservan el respaldo predeterminado a PI. +- `runtime`: descriptor de runtime opcional por agente. Usa `type: "acp"` con valores predeterminados de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) cuando el agente deba usar por defecto sesiones de harness ACP. - `identity.avatar`: ruta relativa al workspace, URL `http(s)` o URI `data:`. -- `identity` deriva valores predeterminados: `ackReaction` desde `emoji`, `mentionPatterns` desde `name`/`emoji`. -- `subagents.allowAgents`: lista de permitidos de IDs de agente para `sessions_spawn` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). -- Protección de herencia de sandbox: si la sesión solicitante está en sandbox, `sessions_spawn` rechaza objetivos que se ejecutarían sin sandbox. -- `subagents.requireAgentId`: cuando es true, bloquea llamadas a `sessions_spawn` que omiten `agentId` (fuerza la selección explícita del perfil; predeterminado: false). +- `identity` deriva valores predeterminados: `ackReaction` de `emoji`, `mentionPatterns` de `name`/`emoji`. +- `subagents.allowAgents`: lista de permitidos de ids de agente para `sessions_spawn` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- Protección de herencia del sandbox: si la sesión solicitante está en sandbox, `sessions_spawn` rechaza destinos que se ejecutarían sin sandbox. +- `subagents.requireAgentId`: cuando es true, bloquea las llamadas a `sessions_spawn` que omiten `agentId` (fuerza la selección explícita de perfil; predeterminado: false). --- -## Enrutamiento de múltiples agentes +## Enrutamiento multiagente -Ejecute múltiples agentes aislados dentro de un Gateway. Consulte [Multi-Agent](/es/concepts/multi-agent). +Ejecuta varios agentes aislados dentro de un Gateway. Consulta [Multi-Agent](/es/concepts/multi-agent). ```json5 { @@ -1827,9 +1811,9 @@ Ejecute múltiples agentes aislados dentro de un Gateway. Consulte [Multi-Agent] } ``` -### Campos de coincidencia de vinculaciones +### Campos de coincidencia de enlaces -- `type` (opcional): `route` para enrutamiento normal (si falta, el valor predeterminado es route), `acp` para vinculaciones persistentes de conversación ACP. +- `type` (opcional): `route` para enrutamiento normal (si falta, type usa route por defecto), `acp` para enlaces persistentes de conversación ACP. - `match.channel` (obligatorio) - `match.accountId` (opcional; `*` = cualquier cuenta; omitido = cuenta predeterminada) - `match.peer` (opcional; `{ kind: direct|group|channel, id }`) @@ -1847,7 +1831,7 @@ Ejecute múltiples agentes aislados dentro de un Gateway. Consulte [Multi-Agent] Dentro de cada nivel, gana la primera entrada coincidente de `bindings`. -Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de la conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden por niveles de las vinculaciones de ruta anterior. +Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de conversación (`match.channel` + cuenta + `match.peer.id`) y no usa el orden de niveles de enlaces de route anterior. ### Perfiles de acceso por agente @@ -1944,7 +1928,7 @@ Para entradas `type: "acp"`, OpenClaw resuelve por identidad exacta de la conver -Consulte [Sandbox y herramientas de múltiples agentes](/es/tools/multi-agent-sandbox-tools) para ver detalles de precedencia. +Consulta [Sandbox y herramientas multiagente](/es/tools/multi-agent-sandbox-tools) para los detalles de precedencia. --- @@ -1995,37 +1979,37 @@ Consulte [Sandbox y herramientas de múltiples agentes](/es/tools/multi-agent-sa } ``` - + - **`scope`**: estrategia base de agrupación de sesiones para contextos de chat grupal. - `per-sender` (predeterminado): cada remitente obtiene una sesión aislada dentro del contexto de un canal. - - `global`: todos los participantes de un contexto de canal comparten una sola sesión (úselo solo cuando se pretenda un contexto compartido). -- **`dmScope`**: cómo se agrupan los MD. - - `main`: todos los MD comparten la sesión principal. - - `per-peer`: aísla por ID de remitente entre canales. + - `global`: todos los participantes en un contexto de canal comparten una sola sesión (úsalo solo cuando se pretenda contexto compartido). +- **`dmScope`**: cómo se agrupan las MD. + - `main`: todas las MD comparten la sesión principal. + - `per-peer`: aísla por id de remitente entre canales. - `per-channel-peer`: aísla por canal + remitente (recomendado para bandejas de entrada multiusuario). - `per-account-channel-peer`: aísla por cuenta + canal + remitente (recomendado para múltiples cuentas). -- **`identityLinks`**: asigna IDs canónicos a peers con prefijo de proveedor para compartir sesiones entre canales. -- **`reset`**: política principal de reinicio. `daily` reinicia a la hora local `atHour`; `idle` reinicia tras `idleMinutes`. Cuando ambos están configurados, gana el que expire primero. -- **`resetByType`**: reemplazos por tipo (`direct`, `group`, `thread`). Se acepta el heredado `dm` como alias de `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` de la sesión principal permitido al crear una sesión de hilo bifurcada (predeterminado `100000`). - - Si `totalTokens` de la sesión principal está por encima de este valor, OpenClaw inicia una sesión de hilo nueva en lugar de heredar el historial de transcripción de la sesión principal. - - Configure `0` para desactivar esta protección y permitir siempre la bifurcación desde la sesión principal. +- **`identityLinks`**: asigna ids canónicos a peers con prefijo de proveedor para compartir sesiones entre canales. +- **`reset`**: política principal de reinicio. `daily` reinicia a `atHour` en hora local; `idle` reinicia después de `idleMinutes`. Cuando ambos están configurados, gana el que venza primero. +- **`resetByType`**: sobrescrituras por tipo (`direct`, `group`, `thread`). Se acepta el heredado `dm` como alias de `direct`. +- **`parentForkMaxTokens`**: máximo de `totalTokens` permitido de la sesión padre al crear una sesión de hilo bifurcada (predeterminado `100000`). + - Si `totalTokens` del padre está por encima de este valor, OpenClaw inicia una sesión de hilo nueva en lugar de heredar el historial de transcripción del padre. + - Establece `0` para desactivar esta protección y permitir siempre la bifurcación desde el padre. - **`mainKey`**: campo heredado. El runtime siempre usa `"main"` para el bucket principal de chat directo. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de respuesta mutua entre agentes durante intercambios agente a agente (entero, rango: `0`–`5`). `0` desactiva el encadenamiento ping-pong. -- **`sendPolicy`**: coincidencia por `channel`, `chatType` (`direct|group|channel`, con alias heredado `dm`), `keyPrefix` o `rawKeyPrefix`. La primera denegación gana. -- **`maintenance`**: controles de limpieza y retención del almacén de sesiones. +- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de respuesta entre agentes durante intercambios agente a agente (entero, rango: `0`–`5`). `0` desactiva la cadena ping-pong. +- **`sendPolicy`**: coincide por `channel`, `chatType` (`direct|group|channel`, con alias heredado `dm`), `keyPrefix` o `rawKeyPrefix`. Gana la primera denegación. +- **`maintenance`**: controles de limpieza + retención del almacén de sesiones. - `mode`: `warn` solo emite advertencias; `enforce` aplica la limpieza. - `pruneAfter`: límite de antigüedad para entradas obsoletas (predeterminado `30d`). - `maxEntries`: número máximo de entradas en `sessions.json` (predeterminado `500`). - `rotateBytes`: rota `sessions.json` cuando supera este tamaño (predeterminado `10mb`). - - `resetArchiveRetention`: retención para archivos de transcripción `*.reset.`. De forma predeterminada usa `pruneAfter`; configure `false` para desactivarlo. + - `resetArchiveRetention`: retención para archivos de transcripción `*.reset.`. Usa `pruneAfter` por defecto; establece `false` para desactivar. - `maxDiskBytes`: presupuesto opcional de disco para el directorio de sesiones. En modo `warn` registra advertencias; en modo `enforce` elimina primero los artefactos/sesiones más antiguos. - - `highWaterBytes`: objetivo opcional después de la limpieza del presupuesto. De forma predeterminada es `80%` de `maxDiskBytes`. + - `highWaterBytes`: objetivo opcional después de la limpieza por presupuesto. Usa `80%` de `maxDiskBytes` por defecto. - **`threadBindings`**: valores predeterminados globales para funciones de sesión vinculadas a hilos. - - `enabled`: interruptor maestro predeterminado (los proveedores pueden reemplazarlo; Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: pérdida automática de foco por inactividad predeterminada en horas (`0` la desactiva; los proveedores pueden reemplazarla) - - `maxAgeHours`: antigüedad máxima estricta predeterminada en horas (`0` la desactiva; los proveedores pueden reemplazarla) + - `enabled`: interruptor maestro predeterminado (los proveedores pueden sobrescribirlo; Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: auto-unfocus predeterminado por inactividad en horas (`0` lo desactiva; los proveedores pueden sobrescribirlo) + - `maxAgeHours`: antigüedad máxima estricta predeterminada en horas (`0` lo desactiva; los proveedores pueden sobrescribirlo) @@ -2063,7 +2047,7 @@ Consulte [Sandbox y herramientas de múltiples agentes](/es/tools/multi-agent-sa ### Prefijo de respuesta -Reemplazos por canal/cuenta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Sobrescrituras por canal/cuenta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. Resolución (gana la más específica): cuenta → canal → global. `""` desactiva y detiene la cascada. `"auto"` deriva `[{identity.name}]`. @@ -2071,28 +2055,28 @@ Resolución (gana la más específica): cuenta → canal → global. `""` desact | Variable | Descripción | Ejemplo | | ----------------- | ---------------------- | --------------------------- | -| `{model}` | Nombre corto del modelo | `claude-opus-4-6` | +| `{model}` | Nombre corto del modelo | `claude-opus-4-6` | | `{modelFull}` | Identificador completo del modelo | `anthropic/claude-opus-4-6` | | `{provider}` | Nombre del proveedor | `anthropic` | -| `{thinkingLevel}` | Nivel actual de thinking | `high`, `low`, `off` | -| `{identity.name}` | Nombre de identidad del agente | (igual que `"auto"`) | +| `{thinkingLevel}` | Nivel actual de thinking | `high`, `low`, `off` | +| `{identity.name}` | Nombre de identidad del agente | (igual que `"auto"`) | -Las variables no distinguen mayúsculas de minúsculas. `{think}` es un alias de `{thinkingLevel}`. +Las variables no distinguen entre mayúsculas y minúsculas. `{think}` es un alias de `{thinkingLevel}`. -### Reacción de acuse +### Reacción de confirmación -- De forma predeterminada usa `identity.emoji` del agente activo; de lo contrario `"👀"`. Configure `""` para desactivarla. -- Reemplazos por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Usa por defecto `identity.emoji` del agente activo, en caso contrario `"👀"`. Establece `""` para desactivar. +- Sobrescrituras por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. - Orden de resolución: cuenta → canal → `messages.ackReaction` → respaldo de identidad. - Alcance: `group-mentions` (predeterminado), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: elimina el acuse después de responder en Slack, Discord y Telegram. +- `removeAckAfterReply`: elimina la confirmación después de responder en Slack, Discord y Telegram. - `messages.statusReactions.enabled`: habilita reacciones de estado del ciclo de vida en Slack, Discord y Telegram. - En Slack y Discord, dejarlo sin configurar mantiene habilitadas las reacciones de estado cuando las reacciones de acuse están activas. - En Telegram, configúrelo explícitamente en `true` para habilitar las reacciones de estado del ciclo de vida. + En Slack y Discord, dejarlo sin definir mantiene habilitadas las reacciones de estado cuando las reacciones de confirmación están activas. + En Telegram, establécelo explícitamente en `true` para habilitar las reacciones de estado del ciclo de vida. -### Antirrebote de entrada +### Debounce entrante -Agrupa mensajes rápidos de solo texto del mismo remitente en un único turno del agente. Los medios/adjuntos se vacían inmediatamente. Los comandos de control omiten el antirrebote. +Agrupa mensajes rápidos solo de texto del mismo remitente en un único turno de agente. Los medios/adjuntos se vacían de inmediato. Los comandos de control omiten el debounce. ### TTS (texto a voz) @@ -2135,11 +2119,11 @@ Agrupa mensajes rápidos de solo texto del mismo remitente en un único turno de } ``` -- `auto` controla el modo predeterminado de auto-TTS: `off`, `always`, `inbound` o `tagged`. `/tts on|off` puede reemplazar las preferencias locales, y `/tts status` muestra el estado efectivo. -- `summaryModel` reemplaza `agents.defaults.model.primary` para el resumen automático. -- `modelOverrides` está habilitado de forma predeterminada; `modelOverrides.allowProvider` tiene como valor predeterminado `false` (activación explícita). -- Las claves API usan como respaldo `ELEVENLABS_API_KEY`/`XI_API_KEY` y `OPENAI_API_KEY`. -- `openai.baseUrl` reemplaza el endpoint de TTS de OpenAI. El orden de resolución es configuración, luego `OPENAI_TTS_BASE_URL` y después `https://api.openai.com/v1`. +- `auto` controla el modo predeterminado de auto-TTS: `off`, `always`, `inbound` o `tagged`. `/tts on|off` puede sobrescribir las preferencias locales y `/tts status` muestra el estado efectivo. +- `summaryModel` sobrescribe `agents.defaults.model.primary` para el resumen automático. +- `modelOverrides` está habilitado de forma predeterminada; `modelOverrides.allowProvider` usa `false` por defecto (opt-in). +- Las claves de API usan como respaldo `ELEVENLABS_API_KEY`/`XI_API_KEY` y `OPENAI_API_KEY`. +- `openai.baseUrl` sobrescribe el endpoint TTS de OpenAI. El orden de resolución es configuración, luego `OPENAI_TTS_BASE_URL` y luego `https://api.openai.com/v1`. - Cuando `openai.baseUrl` apunta a un endpoint que no es de OpenAI, OpenClaw lo trata como un servidor TTS compatible con OpenAI y flexibiliza la validación de modelo/voz. --- @@ -2174,9 +2158,9 @@ Valores predeterminados para el modo Talk (macOS/iOS/Android). - Las claves heredadas planas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) son solo de compatibilidad y se migran automáticamente a `talk.providers.`. - Los IDs de voz usan como respaldo `ELEVENLABS_VOICE_ID` o `SAG_VOICE_ID`. - `providers.*.apiKey` acepta cadenas de texto sin formato u objetos SecretRef. -- El respaldo `ELEVENLABS_API_KEY` solo se aplica cuando no hay una clave API de Talk configurada. -- `providers.*.voiceAliases` permite que las directivas de Talk usen nombres descriptivos. -- `silenceTimeoutMs` controla cuánto tiempo espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no se configura, conserva la ventana de pausa predeterminada de la plataforma (`700 ms en macOS y Android, 900 ms en iOS`). +- El respaldo `ELEVENLABS_API_KEY` solo se aplica cuando no hay una clave de API de Talk configurada. +- `providers.*.voiceAliases` permite que las directivas de Talk usen nombres amigables. +- `silenceTimeoutMs` controla cuánto espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no se define, se mantiene la ventana de pausa predeterminada de la plataforma (`700 ms en macOS y Android, 900 ms en iOS`). --- @@ -2186,35 +2170,35 @@ Valores predeterminados para el modo Talk (macOS/iOS/Android). `tools.profile` establece una lista base de permitidos antes de `tools.allow`/`tools.deny`: -La incorporación local establece de forma predeterminada las nuevas configuraciones locales en `tools.profile: "coding"` cuando no está configurado (los perfiles explícitos existentes se conservan). +La incorporación local configura por defecto los nuevos archivos de configuración locales con `tools.profile: "coding"` cuando no está definido (los perfiles explícitos existentes se conservan). | Perfil | Incluye | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | solo `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Sin restricciones (igual que no configurado) | +| `full` | Sin restricción (igual que no definido) | ### Grupos de herramientas -| Grupo | Herramientas | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` se acepta como alias de `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Grupo | Herramientas | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` se acepta como alias de `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Todas las herramientas integradas (excluye los plugins de proveedor) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Todas las herramientas integradas (excluye plugins de proveedor) | ### `tools.allow` / `tools.deny` -Política global de permitir/denegar herramientas (denegar tiene prioridad). No distingue mayúsculas de minúsculas y admite comodines `*`. Se aplica incluso cuando el sandbox de Docker está desactivado. +Política global de permitir/denegar herramientas (denegar tiene prioridad). No distingue entre mayúsculas y minúsculas, admite comodines `*`. Se aplica incluso cuando el sandbox de Docker está desactivado. ```json5 { @@ -2256,9 +2240,9 @@ Controla el acceso elevado de `exec` fuera del sandbox: } ``` -- El reemplazo por agente (`agents.list[].tools.elevated`) solo puede restringir aún más. +- La sobrescritura por agente (`agents.list[].tools.elevated`) solo puede restringir aún más. - `/elevated on|off|ask|full` almacena el estado por sesión; las directivas en línea se aplican a un solo mensaje. -- `exec` elevado omite el sandboxing y usa la ruta de escape configurada (`gateway` de forma predeterminada, o `node` cuando el destino de exec es `node`). +- `exec` elevado omite el sandboxing y usa la ruta de escape configurada (`gateway` de forma predeterminada, o `node` cuando el objetivo de exec es `node`). ### `tools.exec` @@ -2282,8 +2266,8 @@ Controla el acceso elevado de `exec` fuera del sandbox: ### `tools.loopDetection` -Las comprobaciones de seguridad contra bucles de herramientas están **desactivadas de forma predeterminada**. Configure `enabled: true` para activar la detección. -Los ajustes pueden definirse globalmente en `tools.loopDetection` y reemplazarse por agente en `agents.list[].tools.loopDetection`. +Las comprobaciones de seguridad de bucles de herramientas están **desactivadas de forma predeterminada**. Establece `enabled: true` para activar la detección. +La configuración puede definirse globalmente en `tools.loopDetection` y sobrescribirse por agente en `agents.list[].tools.loopDetection`. ```json5 { @@ -2304,13 +2288,13 @@ Los ajustes pueden definirse globalmente en `tools.loopDetection` y reemplazarse } ``` -- `historySize`: máximo historial de llamadas a herramientas conservado para el análisis de bucles. +- `historySize`: máximo de historial de llamadas a herramientas conservado para análisis de bucles. - `warningThreshold`: umbral de patrón repetitivo sin progreso para advertencias. - `criticalThreshold`: umbral repetitivo más alto para bloquear bucles críticos. - `globalCircuitBreakerThreshold`: umbral de parada total para cualquier ejecución sin progreso. - `detectors.genericRepeat`: advierte sobre llamadas repetidas a la misma herramienta/con los mismos argumentos. -- `detectors.knownPollNoProgress`: advierte/bloquea herramientas de sondeo conocidas (`process.poll`, `command_status`, etc.). -- `detectors.pingPong`: advierte/bloquea patrones alternados de pares sin progreso. +- `detectors.knownPollNoProgress`: advierte/bloquea en herramientas de sondeo conocidas (`process.poll`, `command_status`, etc.). +- `detectors.pingPong`: advierte/bloquea en patrones alternos de pares sin progreso. - Si `warningThreshold >= criticalThreshold` o `criticalThreshold >= globalCircuitBreakerThreshold`, la validación falla. ### `tools.web` @@ -2345,7 +2329,7 @@ Los ajustes pueden definirse globalmente en `tools.loopDetection` y reemplazarse ### `tools.media` -Configura la comprensión de medios entrantes (imagen/audio/video): +Configura el entendimiento de medios entrantes (imagen/audio/video): ```json5 { @@ -2377,32 +2361,32 @@ Configura la comprensión de medios entrantes (imagen/audio/video): } ``` - + -**Entrada de proveedor** (`type: "provider"` o omitido): +**Entrada de proveedor** (`type: "provider"` u omitido): -- `provider`: ID del proveedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) -- `model`: reemplazo de ID de modelo +- `provider`: id del proveedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.) +- `model`: sobrescritura del id del modelo - `profile` / `preferredProfile`: selección de perfil de `auth-profiles.json` **Entrada de CLI** (`type: "cli"`): -- `command`: ejecutable a ejecutar -- `args`: argumentos con plantillas (admite `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) +- `command`: ejecutable que se va a ejecutar +- `args`: argumentos con plantilla (admite `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.) **Campos comunes:** - `capabilities`: lista opcional (`image`, `audio`, `video`). Valores predeterminados: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: reemplazos por entrada. -- Los fallos recurren a la siguiente entrada. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: sobrescrituras por entrada. +- Los fallos pasan a la siguiente entrada. La autenticación del proveedor sigue el orden estándar: `auth-profiles.json` → variables de entorno → `models.providers.*.apiKey`. **Campos de finalización asíncrona:** -- `asyncCompletion.directSend`: cuando es `true`, las tareas asíncronas completadas de `music_generate` +- `asyncCompletion.directSend`: cuando es `true`, las tareas completadas asíncronas `music_generate` y `video_generate` intentan primero la entrega directa al canal. Predeterminado: `false` - (ruta heredada de activación de la sesión solicitante/entrega por modelo). + (ruta heredada de activación de sesión del solicitante/entrega de modelo). @@ -2421,7 +2405,7 @@ La autenticación del proveedor sigue el orden estándar: `auth-profiles.json` ### `tools.sessions` -Controla qué sesiones pueden ser objetivo de las herramientas de sesión (`sessions_list`, `sessions_history`, `sessions_send`). +Controla a qué sesiones pueden dirigirse las herramientas de sesión (`sessions_list`, `sessions_history`, `sessions_send`). Predeterminado: `tree` (sesión actual + sesiones generadas por ella, como subagentes). @@ -2438,11 +2422,11 @@ Predeterminado: `tree` (sesión actual + sesiones generadas por ella, como subag Notas: -- `self`: solo la clave de sesión actual. +- `self`: solo la clave de la sesión actual. - `tree`: sesión actual + sesiones generadas por la sesión actual (subagentes). -- `agent`: cualquier sesión perteneciente al ID del agente actual (puede incluir otros usuarios si ejecuta sesiones por remitente bajo el mismo ID de agente). +- `agent`: cualquier sesión que pertenezca al id del agente actual (puede incluir otros usuarios si ejecutas sesiones por remitente bajo el mismo id de agente). - `all`: cualquier sesión. El direccionamiento entre agentes sigue requiriendo `tools.agentToAgent`. -- Restricción por sandbox: cuando la sesión actual está en sandbox y `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilidad se fuerza a `tree` incluso si `tools.sessions.visibility="all"`. +- Restricción del sandbox: cuando la sesión actual está en sandbox y `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, la visibilidad se fuerza a `tree` incluso si `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2468,14 +2452,14 @@ Notas: - Los adjuntos solo son compatibles con `runtime: "subagent"`. El runtime ACP los rechaza. - Los archivos se materializan en el workspace hijo en `.openclaw/attachments//` con un `.manifest.json`. -- El contenido de los adjuntos se redacta automáticamente del almacenamiento persistente de la transcripción. +- El contenido de los adjuntos se redacta automáticamente de la persistencia de transcripciones. - Las entradas Base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección de tamaño previa a la decodificación. -- Los permisos de archivos son `0700` para directorios y `0600` para archivos. -- La limpieza sigue la política `cleanup`: `delete` siempre elimina los adjuntos; `keep` solo los conserva cuando `retainOnSessionKeep: true`. +- Los permisos de archivo son `0700` para directorios y `0600` para archivos. +- La limpieza sigue la política `cleanup`: `delete` siempre elimina los adjuntos; `keep` los conserva solo cuando `retainOnSessionKeep: true`. ### `tools.experimental` -Indicadores experimentales para herramientas integradas. Desactivados de forma predeterminada, salvo que se aplique una regla estricta de activación automática agéntica de GPT-5. +Indicadores experimentales de herramientas integradas. Predeterminado desactivado salvo que se aplique una regla de autoactivación estrictamente agentiva de GPT-5. ```json5 { @@ -2489,8 +2473,8 @@ Indicadores experimentales para herramientas integradas. Desactivados de forma p Notas: -- `planTool`: habilita la herramienta estructurada experimental `update_plan` para el seguimiento de trabajo no trivial de varios pasos. -- Predeterminado: `false` a menos que `agents.defaults.embeddedPi.executionContract` (o un reemplazo por agente) esté configurado en `"strict-agentic"` para una ejecución de la familia GPT-5 de OpenAI o OpenAI Codex. Configure `true` para forzar la activación de la herramienta fuera de ese alcance, o `false` para mantenerla desactivada incluso en ejecuciones GPT-5 strict-agentic. +- `planTool`: habilita la herramienta estructurada experimental `update_plan` para seguimiento de trabajo no trivial de varios pasos. +- Predeterminado: `false` a menos que `agents.defaults.embeddedPi.executionContract` (o una sobrescritura por agente) esté establecido en `"strict-agentic"` para una ejecución de la familia GPT-5 de OpenAI o OpenAI Codex. Establece `true` para forzar la activación fuera de ese ámbito, o `false` para mantenerla desactivada incluso en ejecuciones GPT-5 strict-agentic. - Cuando está habilitada, el prompt del sistema también agrega orientación de uso para que el modelo solo la use en trabajo sustancial y mantenga como máximo un paso `in_progress`. ### `agents.defaults.subagents` @@ -2512,15 +2496,15 @@ Notas: ``` - `model`: modelo predeterminado para subagentes generados. Si se omite, los subagentes heredan el modelo del llamador. -- `allowAgents`: lista predeterminada de permitidos de IDs de agente de destino para `sessions_spawn` cuando el agente solicitante no define su propio `subagents.allowAgents` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). -- `runTimeoutSeconds`: tiempo de espera predeterminado (segundos) para `sessions_spawn` cuando la llamada a la herramienta omite `runTimeoutSeconds`. `0` significa sin tiempo de espera. +- `allowAgents`: lista de permitidos predeterminada de ids de agentes de destino para `sessions_spawn` cuando el agente solicitante no establece su propio `subagents.allowAgents` (`["*"]` = cualquiera; predeterminado: solo el mismo agente). +- `runTimeoutSeconds`: tiempo de espera predeterminado (segundos) para `sessions_spawn` cuando la llamada de herramienta omite `runTimeoutSeconds`. `0` significa sin tiempo de espera. - Política de herramientas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Proveedores personalizados y URL base +## Proveedores personalizados y URLs base -OpenClaw usa el catálogo integrado de modelos. Agregue proveedores personalizados mediante `models.providers` en la configuración o `~/.openclaw/agents//agent/models.json`. +OpenClaw usa el catálogo integrado de modelos. Agrega proveedores personalizados mediante `models.providers` en la configuración o `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2549,48 +2533,48 @@ OpenClaw usa el catálogo integrado de modelos. Agregue proveedores personalizad } ``` -- Use `authHeader: true` + `headers` para necesidades personalizadas de autenticación. -- Reemplace la raíz de configuración del agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, un alias heredado de variable de entorno). -- Precedencia de combinación para IDs de proveedor coincidentes: - - Los valores no vacíos de `baseUrl` en el `models.json` del agente prevalecen. - - Los valores no vacíos de `apiKey` del agente prevalecen solo cuando ese proveedor no está gestionado por SecretRef en el contexto actual de configuración/perfil de autenticación. - - Los valores `apiKey` de proveedores gestionados por SecretRef se actualizan desde marcadores de origen (`ENV_VAR_NAME` para referencias de entorno, `secretref-managed` para referencias de archivo/exec) en lugar de persistir secretos resueltos. - - Los valores de encabezados de proveedores gestionados por SecretRef se actualizan desde marcadores de origen (`secretref-env:ENV_VAR_NAME` para referencias de entorno, `secretref-managed` para referencias de archivo/exec). - - Los `apiKey`/`baseUrl` del agente vacíos o ausentes recurren a `models.providers` en la configuración. - - Los valores coincidentes de modelo `contextWindow`/`maxTokens` usan el valor más alto entre la configuración explícita y los valores implícitos del catálogo. - - Los `contextTokens` coincidentes del modelo preservan un límite explícito del runtime cuando está presente; úselo para limitar el contexto efectivo sin cambiar los metadatos nativos del modelo. - - Use `models.mode: "replace"` cuando quiera que la configuración reescriba completamente `models.json`. - - La persistencia de marcadores es autoritativa respecto al origen: los marcadores se escriben desde la instantánea activa de configuración de origen (antes de la resolución), no desde los valores secretos resueltos del runtime. +- Usa `authHeader: true` + `headers` para necesidades personalizadas de autenticación. +- Sobrescribe la raíz de configuración del agente con `OPENCLAW_AGENT_DIR` (o `PI_CODING_AGENT_DIR`, un alias heredado de variable de entorno). +- Precedencia de fusión para ids de proveedor coincidentes: + - Los valores no vacíos de `baseUrl` de `models.json` del agente tienen prioridad. + - Los valores no vacíos de `apiKey` del agente tienen prioridad solo cuando ese proveedor no está administrado por SecretRef en el contexto actual de configuración/perfil de autenticación. + - Los valores `apiKey` administrados por SecretRef se actualizan desde marcadores de origen (`ENV_VAR_NAME` para refs de entorno, `secretref-managed` para refs de archivo/exec) en lugar de persistir secretos resueltos. + - Los valores de encabezado de proveedor administrados por SecretRef se actualizan desde marcadores de origen (`secretref-env:ENV_VAR_NAME` para refs de entorno, `secretref-managed` para refs de archivo/exec). + - `apiKey`/`baseUrl` del agente vacíos o ausentes usan como respaldo `models.providers` en la configuración. + - `contextWindow`/`maxTokens` del modelo coincidente usan el valor más alto entre la configuración explícita y los valores implícitos del catálogo. + - `contextTokens` del modelo coincidente conserva un límite explícito del runtime cuando está presente; úsalo para limitar el contexto efectivo sin cambiar los metadatos nativos del modelo. + - Usa `models.mode: "replace"` cuando quieras que la configuración reescriba completamente `models.json`. + - La persistencia de marcadores es autoritativa por origen: los marcadores se escriben desde la instantánea activa de configuración de origen (previa a la resolución), no desde los valores secretos resueltos del runtime. ### Detalles de campos del proveedor - `models.mode`: comportamiento del catálogo de proveedores (`merge` o `replace`). -- `models.providers`: mapa de proveedores personalizados indexado por ID de proveedor. +- `models.providers`: mapa de proveedores personalizados indexado por id de proveedor. - `models.providers.*.api`: adaptador de solicitudes (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc.). - `models.providers.*.apiKey`: credencial del proveedor (se prefiere SecretRef/sustitución por entorno). - `models.providers.*.auth`: estrategia de autenticación (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, inyecta `options.num_ctx` en las solicitudes (predeterminado: `true`). - `models.providers.*.authHeader`: fuerza el transporte de credenciales en el encabezado `Authorization` cuando sea necesario. - `models.providers.*.baseUrl`: URL base de la API upstream. -- `models.providers.*.headers`: encabezados estáticos adicionales para enrutamiento de proxy/inquilino. -- `models.providers.*.request`: reemplazos de transporte para solicitudes HTTP del proveedor de modelos. - - `request.headers`: encabezados adicionales (se combinan con los valores predeterminados del proveedor). Los valores aceptan SecretRef. - - `request.auth`: reemplazo de estrategia de autenticación. Modos: `"provider-default"` (usa la autenticación integrada del proveedor), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` opcional). - - `request.proxy`: reemplazo de proxy HTTP. Modos: `"env-proxy"` (usa variables de entorno `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Ambos modos aceptan un subobjeto `tls` opcional. - - `request.tls`: reemplazo de TLS para conexiones directas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceptan SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: cuando es `true`, permite HTTPS a `baseUrl` cuando DNS resuelve a rangos privados, CGNAT o similares, mediante la protección SSRF de obtención HTTP del proveedor (activación explícita del operador para endpoints compatibles con OpenAI autohospedados de confianza). WebSocket usa el mismo `request` para encabezados/TLS, pero no esa protección SSRF de obtención. Predeterminado `false`. +- `models.providers.*.headers`: encabezados estáticos extra para enrutamiento de proxy/tenant. +- `models.providers.*.request`: sobrescrituras de transporte para solicitudes HTTP del proveedor de modelos. + - `request.headers`: encabezados extra (fusionados con los valores predeterminados del proveedor). Los valores aceptan SecretRef. + - `request.auth`: sobrescritura de estrategia de autenticación. Modos: `"provider-default"` (usa la autenticación integrada del proveedor), `"authorization-bearer"` (con `token`), `"header"` (con `headerName`, `value`, `prefix` opcional). + - `request.proxy`: sobrescritura del proxy HTTP. Modos: `"env-proxy"` (usa las variables de entorno `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (con `url`). Ambos modos aceptan un subobjeto `tls` opcional. + - `request.tls`: sobrescritura TLS para conexiones directas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceptan SecretRef), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork`: cuando es `true`, permite HTTPS a `baseUrl` cuando DNS se resuelve a rangos privados, CGNAT o similares, mediante la protección SSRF de fetch HTTP del proveedor (opt-in del operador para endpoints OpenAI-compatibles autohospedados de confianza). WebSocket usa el mismo `request` para encabezados/TLS, pero no esa protección SSRF de fetch. Predeterminado `false`. - `models.providers.*.models`: entradas explícitas del catálogo de modelos del proveedor. - `models.providers.*.models.*.contextWindow`: metadatos de la ventana de contexto nativa del modelo. -- `models.providers.*.models.*.contextTokens`: límite opcional de contexto del runtime. Úselo cuando quiera un presupuesto de contexto efectivo menor que `contextWindow` nativo del modelo. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: indicio opcional de compatibilidad. Para `api: "openai-completions"` con un `baseUrl` no nativo no vacío (host distinto de `api.openai.com`), OpenClaw fuerza esto a `false` en tiempo de ejecución. Un `baseUrl` vacío/omitido conserva el comportamiento predeterminado de OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: indicio opcional de compatibilidad para endpoints de chat compatibles con OpenAI que solo aceptan cadenas. Cuando es `true`, OpenClaw aplana arreglos `messages[].content` de texto puro en cadenas simples antes de enviar la solicitud. -- `plugins.entries.amazon-bedrock.config.discovery`: raíz de la configuración de detección automática de Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: activa o desactiva la detección implícita. -- `plugins.entries.amazon-bedrock.config.discovery.region`: región de AWS para la detección. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de ID de proveedor para detección dirigida. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de sondeo para la actualización de la detección. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: ventana de contexto de respaldo para modelos detectados. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de salida de respaldo para modelos detectados. +- `models.providers.*.models.*.contextTokens`: límite opcional de contexto en runtime. Úsalo cuando quieras un presupuesto efectivo de contexto menor que `contextWindow` nativo del modelo. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: pista opcional de compatibilidad. Para `api: "openai-completions"` con un `baseUrl` no nativo no vacío (host distinto de `api.openai.com`), OpenClaw fuerza esto a `false` en runtime. Un `baseUrl` vacío u omitido mantiene el comportamiento predeterminado de OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: pista opcional de compatibilidad para endpoints de chat OpenAI-compatibles solo con cadenas. Cuando es `true`, OpenClaw aplana arreglos `messages[].content` de texto puro en cadenas simples antes de enviar la solicitud. +- `plugins.entries.amazon-bedrock.config.discovery`: raíz de configuración del descubrimiento automático de Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: activa/desactiva el descubrimiento implícito. +- `plugins.entries.amazon-bedrock.config.discovery.region`: región de AWS para el descubrimiento. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de id de proveedor para descubrimiento dirigido. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de sondeo para la actualización del descubrimiento. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: ventana de contexto de respaldo para modelos descubiertos. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: tokens máximos de salida de respaldo para modelos descubiertos. ### Ejemplos de proveedores @@ -2628,7 +2612,7 @@ OpenClaw usa el catálogo integrado de modelos. Agregue proveedores personalizad } ``` -Use `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI directo. +Usa `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI directo. @@ -2645,7 +2629,7 @@ Use `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI directo. } ``` -Configure `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Use referencias `opencode/...` para el catálogo Zen o referencias `opencode-go/...` para el catálogo Go. Atajo: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. +Establece `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Usa referencias `opencode/...` para el catálogo Zen o referencias `opencode-go/...` para el catálogo Go. Atajo: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`. @@ -2662,11 +2646,11 @@ Configure `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`). Use referencias `openco } ``` -Configure `ZAI_API_KEY`. `z.ai/*` y `z-ai/*` son alias aceptados. Atajo: `openclaw onboard --auth-choice zai-api-key`. +Establece `ZAI_API_KEY`. `z.ai/*` y `z-ai/*` se aceptan como alias. Atajo: `openclaw onboard --auth-choice zai-api-key`. - Endpoint general: `https://api.z.ai/api/paas/v4` -- Endpoint de programación (predeterminado): `https://api.z.ai/api/coding/paas/v4` -- Para el endpoint general, defina un proveedor personalizado con el reemplazo de URL base. +- Endpoint de coding (predeterminado): `https://api.z.ai/api/coding/paas/v4` +- Para el endpoint general, define un proveedor personalizado con la sobrescritura de URL base. @@ -2708,8 +2692,8 @@ Configure `ZAI_API_KEY`. `z.ai/*` y `z-ai/*` son alias aceptados. Atajo: `opencl Para el endpoint de China: `baseUrl: "https://api.moonshot.cn/v1"` o `openclaw onboard --auth-choice moonshot-api-key-cn`. Los endpoints nativos de Moonshot anuncian compatibilidad de uso de streaming en el transporte compartido -`openai-completions`, y OpenClaw basa eso en las capacidades del endpoint -en lugar de hacerlo solo en el ID integrado del proveedor. +`openai-completions`, y OpenClaw se basa en las capacidades del endpoint +en lugar de solo en el id integrado del proveedor. @@ -2766,7 +2750,7 @@ Compatible con Anthropic, proveedor integrado. Atajo: `openclaw onboard --auth-c } ``` -La URL base debe omitir `/v1` (el cliente de Anthropic lo agrega). Atajo: `openclaw onboard --auth-choice synthetic-api-key`. +La URL base debe omitir `/v1` (el cliente Anthropic la agrega). Atajo: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2806,20 +2790,20 @@ La URL base debe omitir `/v1` (el cliente de Anthropic lo agrega). Atajo: `openc } ``` -Configure `MINIMAX_API_KEY`. Atajos: +Establece `MINIMAX_API_KEY`. Atajos: `openclaw onboard --auth-choice minimax-global-api` o `openclaw onboard --auth-choice minimax-cn-api`. El catálogo de modelos usa por defecto solo M2.7. En la ruta de streaming compatible con Anthropic, OpenClaw desactiva thinking de MiniMax -de forma predeterminada a menos que configure `thinking` explícitamente. `/fast on` o -`params.fastMode: true` reescriben `MiniMax-M2.7` a +de forma predeterminada a menos que establezcas explícitamente `thinking` tú mismo. `/fast on` o +`params.fastMode: true` reescribe `MiniMax-M2.7` a `MiniMax-M2.7-highspeed`. -Consulte [Modelos locales](/es/gateway/local-models). Resumen: ejecute un modelo local grande mediante la API Responses de LM Studio en hardware serio; mantenga los modelos alojados fusionados como respaldo. +Consulta [Modelos locales](/es/gateway/local-models). Resumen: ejecuta un modelo local grande mediante la API de Responses de LM Studio en hardware potente; mantén fusionados los modelos alojados para respaldo. @@ -2850,14 +2834,14 @@ Consulte [Modelos locales](/es/gateway/local-models). Resumen: ejecute un modelo } ``` -- `allowBundled`: lista opcional de permitidos solo para Skills bundled (las Skills administradas/del workspace no se ven afectadas). -- `load.extraDirs`: raíces compartidas adicionales de Skills (precedencia más baja). +- `allowBundled`: lista de permitidos opcional solo para Skills bundled (las Skills administradas/de workspace no se ven afectadas). +- `load.extraDirs`: raíces adicionales de Skills compartidas (precedencia más baja). - `install.preferBrew`: cuando es true, prefiere instaladores de Homebrew cuando `brew` está disponible antes de recurrir a otros tipos de instalador. -- `install.nodeManager`: preferencia de instalador de Node para especificaciones - `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `install.nodeManager`: preferencia del instalador Node para especificaciones `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` desactiva una Skill incluso si está bundled/instalada. -- `entries..apiKey`: comodidad para Skills que declaran una variable de entorno principal (cadena de texto sin formato u objeto SecretRef). +- `entries..apiKey`: conveniencia para Skills que declaran una variable de entorno primaria (cadena de texto sin formato u objeto SecretRef). --- @@ -2885,43 +2869,43 @@ Consulte [Modelos locales](/es/gateway/local-models). Resumen: ejecute un modelo } ``` -- Cargado desde `~/.openclaw/extensions`, `/.openclaw/extensions` y `plugins.load.paths`. -- La detección acepta plugins nativos de OpenClaw, además de bundles compatibles de Codex y Claude, incluidos bundles de Claude sin manifiesto con diseño predeterminado. -- **Los cambios de configuración requieren reiniciar el Gateway.** -- `allow`: lista opcional de permitidos (solo se cargan los plugins incluidos). `deny` tiene prioridad. -- `plugins.entries..apiKey`: campo de conveniencia para clave API a nivel de plugin (cuando el plugin lo admite). -- `plugins.entries..env`: mapa de variables de entorno con alcance al plugin. -- `plugins.entries..hooks.allowPromptInjection`: cuando es `false`, el núcleo bloquea `before_prompt_build` e ignora los campos de mutación del prompt del heredado `before_agent_start`, mientras preserva los heredados `modelOverride` y `providerOverride`. Se aplica a hooks de plugins nativos y a directorios de hooks proporcionados por bundles compatibles. -- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en este plugin para solicitar reemplazos por ejecución de `provider` y `model` en ejecuciones de subagentes en segundo plano. -- `plugins.entries..subagent.allowedModels`: lista opcional de permitidos de destinos canónicos `provider/model` para reemplazos de subagentes de confianza. Use `"*"` solo cuando desee intencionalmente permitir cualquier modelo. -- `plugins.entries..config`: objeto de configuración definido por el plugin (validado por el esquema del plugin nativo de OpenClaw cuando está disponible). -- `plugins.entries.firecrawl.config.webFetch`: ajustes del proveedor de obtención web de Firecrawl. +- Se cargan desde `~/.openclaw/extensions`, `/.openclaw/extensions` y `plugins.load.paths`. +- El descubrimiento acepta plugins nativos de OpenClaw, además de bundles compatibles de Codex y Claude, incluidos bundles de Claude sin manifiesto con el diseño predeterminado. +- **Los cambios de configuración requieren reiniciar el gateway.** +- `allow`: lista de permitidos opcional (solo se cargan los plugins listados). `deny` tiene prioridad. +- `plugins.entries..apiKey`: campo de conveniencia de clave API a nivel de plugin (cuando el plugin lo admite). +- `plugins.entries..env`: mapa de variables de entorno con alcance del plugin. +- `plugins.entries..hooks.allowPromptInjection`: cuando es `false`, el núcleo bloquea `before_prompt_build` e ignora campos que mutan el prompt de `before_agent_start` heredado, mientras conserva `modelOverride` y `providerOverride` heredados. Se aplica a hooks de plugins nativos y a directorios de hooks compatibles proporcionados por bundles. +- `plugins.entries..subagent.allowModelOverride`: confía explícitamente en que este plugin solicite sobrescrituras por ejecución de `provider` y `model` para ejecuciones de subagentes en segundo plano. +- `plugins.entries..subagent.allowedModels`: lista de permitidos opcional de destinos canónicos `provider/model` para sobrescrituras confiables de subagentes. Usa `"*"` solo cuando realmente quieras permitir cualquier modelo. +- `plugins.entries..config`: objeto de configuración definido por el plugin (validado por el esquema nativo del plugin de OpenClaw cuando está disponible). +- `plugins.entries.firecrawl.config.webFetch`: configuración del proveedor web-fetch de Firecrawl. - `apiKey`: clave API de Firecrawl (acepta SecretRef). Usa como respaldo `plugins.entries.firecrawl.config.webSearch.apiKey`, el heredado `tools.web.fetch.firecrawl.apiKey` o la variable de entorno `FIRECRAWL_API_KEY`. - `baseUrl`: URL base de la API de Firecrawl (predeterminada: `https://api.firecrawl.dev`). - `onlyMainContent`: extrae solo el contenido principal de las páginas (predeterminado: `true`). - `maxAgeMs`: antigüedad máxima de caché en milisegundos (predeterminado: `172800000` / 2 días). - - `timeoutSeconds`: tiempo de espera de solicitud de scraping en segundos (predeterminado: `60`). -- `plugins.entries.xai.config.xSearch`: ajustes de xAI X Search (búsqueda web de Grok). + - `timeoutSeconds`: tiempo de espera de la solicitud de scrape en segundos (predeterminado: `60`). +- `plugins.entries.xai.config.xSearch`: configuración de xAI X Search (búsqueda web de Grok). - `enabled`: habilita el proveedor X Search. - - `model`: modelo de Grok a usar para la búsqueda (por ejemplo `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: ajustes de dreaming de memoria. Consulte [Dreaming](/es/concepts/dreaming) para las fases y umbrales. - - `enabled`: interruptor maestro de dreaming (predeterminado `false`). - - `frequency`: frecuencia Cron para cada barrido completo de dreaming (predeterminada `"0 3 * * *"`). - - La política de fases y los umbrales son detalles de implementación (no son claves de configuración de cara al usuario). + - `model`: modelo Grok que se va a usar para la búsqueda (por ejemplo `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: configuración de memory dreaming. Consulta [Dreaming](/es/concepts/dreaming) para fases y umbrales. + - `enabled`: interruptor principal de dreaming (predeterminado `false`). + - `frequency`: cadencia Cron para cada barrido completo de dreaming (`"0 3 * * *"` por defecto). + - la política de fases y los umbrales son detalles de implementación (no claves de configuración orientadas al usuario). - La configuración completa de memoria está en [Referencia de configuración de memoria](/es/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Los plugins de bundles de Claude habilitados también pueden aportar valores predeterminados integrados de Pi desde `settings.json`; OpenClaw los aplica como ajustes sanitizados del agente, no como parches de configuración bruta de OpenClaw. -- `plugins.slots.memory`: elija el ID del plugin de memoria activo, o `"none"` para desactivar plugins de memoria. -- `plugins.slots.contextEngine`: elija el ID del plugin de motor de contexto activo; el valor predeterminado es `"legacy"` salvo que instale y seleccione otro motor. -- `plugins.installs`: metadatos de instalación gestionados por la CLI y usados por `openclaw plugins update`. +- Los plugins Claude bundle habilitados también pueden aportar valores predeterminados incrustados de Pi desde `settings.json`; OpenClaw los aplica como ajustes de agente saneados, no como parches sin procesar de configuración de OpenClaw. +- `plugins.slots.memory`: elige el id del plugin de memoria activo, o `"none"` para desactivar plugins de memoria. +- `plugins.slots.contextEngine`: elige el id del plugin activo de motor de contexto; el valor predeterminado es `"legacy"` a menos que instales y selecciones otro motor. +- `plugins.installs`: metadatos de instalación administrados por la CLI usados por `openclaw plugins update`. - Incluye `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Trate `plugins.installs.*` como estado administrado; prefiera comandos de la CLI en lugar de ediciones manuales. + - Trata `plugins.installs.*` como estado administrado; prefiere comandos de CLI en lugar de ediciones manuales. -Consulte [Plugins](/es/tools/plugin). +Consulta [Plugins](/es/tools/plugin). --- @@ -2962,28 +2946,28 @@ Consulte [Plugins](/es/tools/plugin). ``` - `evaluateEnabled: false` desactiva `act:evaluate` y `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` está desactivado cuando no se configura, por lo que la navegación del navegador sigue siendo estricta de forma predeterminada. -- Configure `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo cuando confíe intencionalmente en la navegación del navegador hacia redes privadas. -- En modo estricto, los endpoints de perfiles CDP remotos (`profiles.*.cdpUrl`) están sujetos al mismo bloqueo de red privada durante las comprobaciones de accesibilidad/detección. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` está desactivado cuando no se define, por lo que la navegación del navegador permanece estricta de forma predeterminada. +- Establece `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` solo cuando confíes intencionalmente en la navegación del navegador por redes privadas. +- En modo estricto, los endpoints de perfiles CDP remotos (`profiles.*.cdpUrl`) están sujetos al mismo bloqueo de red privada durante las comprobaciones de alcance/detección. - `ssrfPolicy.allowPrivateNetwork` sigue siendo compatible como alias heredado. -- En modo estricto, use `ssrfPolicy.hostnameAllowlist` y `ssrfPolicy.allowedHostnames` para excepciones explícitas. -- Los perfiles remotos son solo de conexión (start/stop/reset desactivados). +- En modo estricto, usa `ssrfPolicy.hostnameAllowlist` y `ssrfPolicy.allowedHostnames` para excepciones explícitas. +- Los perfiles remotos son solo de conexión (inicio/detención/reinicio desactivados). - `profiles.*.cdpUrl` acepta `http://`, `https://`, `ws://` y `wss://`. - Use HTTP(S) cuando quiera que OpenClaw detecte `/json/version`; use WS(S) - cuando su proveedor le proporcione una URL WebSocket directa de DevTools. -- Los perfiles `existing-session` son solo del host y usan Chrome MCP en lugar de CDP. -- Los perfiles `existing-session` pueden configurar `userDataDir` para apuntar a un perfil específico - de navegador basado en Chromium, como Brave o Edge. -- Los perfiles `existing-session` conservan los límites actuales de la ruta Chrome MCP: - acciones basadas en instantáneas/referencias en lugar de selección por CSS, hooks - de carga de un solo archivo, sin reemplazos de tiempo de espera de diálogos, sin `wait --load networkidle`, y sin - `responsebody`, exportación a PDF, intercepción de descargas ni acciones por lotes. -- Los perfiles `openclaw` locales administrados asignan automáticamente `cdpPort` y `cdpUrl`; solo - configure `cdpUrl` explícitamente para CDP remoto. -- Orden de detección automática: navegador predeterminado si está basado en Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Servicio de control: solo local loopback (puerto derivado de `gateway.port`, predeterminado `18791`). -- `extraArgs` agrega indicadores adicionales de inicio al arranque local de Chromium (por ejemplo - `--disable-gpu`, tamaño de ventana o indicadores de depuración). + Usa HTTP(S) cuando quieras que OpenClaw detecte `/json/version`; usa WS(S) + cuando tu proveedor te proporcione una URL directa de WebSocket de DevTools. +- Los perfiles `existing-session` son solo para host y usan Chrome MCP en lugar de CDP. +- Los perfiles `existing-session` pueden establecer `userDataDir` para apuntar a un perfil + específico de navegador basado en Chromium como Brave o Edge. +- Los perfiles `existing-session` mantienen los límites actuales de la ruta Chrome MCP: + acciones guiadas por snapshot/ref en lugar de selección por CSS, hooks de carga de un solo archivo, + sin sobrescrituras de tiempo de espera de diálogos, sin `wait --load networkidle`, y sin + `responsebody`, exportación PDF, interceptación de descargas ni acciones por lotes. +- Los perfiles locales administrados `openclaw` asignan automáticamente `cdpPort` y `cdpUrl`; solo + establece `cdpUrl` explícitamente para CDP remoto. +- Orden de autodetección: navegador predeterminado si está basado en Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Servicio de control: solo loopback (puerto derivado de `gateway.port`, predeterminado `18791`). +- `extraArgs` agrega flags de lanzamiento extra al inicio local de Chromium (por ejemplo + `--disable-gpu`, tamaño de ventana o flags de depuración). --- @@ -3001,8 +2985,8 @@ Consulte [Plugins](/es/tools/plugin). } ``` -- `seamColor`: color de acento para el chrome de la UI de la aplicación nativa (tinte de la burbuja del modo Talk, etc.). -- `assistant`: reemplazo de identidad para la UI de Control. Usa la identidad del agente activo como respaldo. +- `seamColor`: color de acento para el chrome de la UI de la app nativa (tinte de la burbuja del modo Talk, etc.). +- `assistant`: sobrescritura de identidad de la Control UI. Usa como respaldo la identidad activa del agente. --- @@ -3071,64 +3055,64 @@ Consulte [Plugins](/es/tools/plugin). -- `mode`: `local` (ejecutar el gateway) o `remote` (conectarse a un gateway remoto). El Gateway se niega a iniciar salvo que sea `local`. +- `mode`: `local` (ejecutar gateway) o `remote` (conectarse a un gateway remoto). El Gateway se niega a iniciarse salvo que sea `local`. - `port`: puerto multiplexado único para WS + HTTP. Precedencia: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (predeterminado), `lan` (`0.0.0.0`), `tailnet` (solo IP de Tailscale) o `custom`. -- **Alias heredados de bind**: use valores de modo bind en `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), no alias de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Nota sobre Docker**: el bind `loopback` predeterminado escucha en `127.0.0.1` dentro del contenedor. Con la red bridge de Docker (`-p 18789:18789`), el tráfico llega por `eth0`, por lo que el gateway queda inaccesible. Use `--network host`, o configure `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) para escuchar en todas las interfaces. -- **Auth**: obligatoria de forma predeterminada. Los binds que no son loopback requieren autenticación del gateway. En la práctica eso significa un token/contraseña compartidos o un proxy inverso con reconocimiento de identidad con `gateway.auth.mode: "trusted-proxy"`. El asistente de incorporación genera un token de forma predeterminada. -- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados (incluidos SecretRefs), configure `gateway.auth.mode` explícitamente como `token` o `password`. Los flujos de inicio e instalación/reparación del servicio fallan cuando ambos están configurados y el modo no está definido. -- `gateway.auth.mode: "none"`: modo explícito sin autenticación. Úselo solo para configuraciones locales de local loopback de confianza; intencionalmente no se ofrece en las indicaciones de incorporación. -- `gateway.auth.mode: "trusted-proxy"`: delega la autenticación en un proxy inverso con reconocimiento de identidad y confía en los encabezados de identidad de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/es/gateway/trusted-proxy-auth)). Este modo espera una fuente proxy **no loopback**; los proxies inversos loopback en el mismo host no satisfacen la autenticación trusted-proxy. -- `gateway.auth.allowTailscale`: cuando es `true`, los encabezados de identidad de Tailscale Serve pueden satisfacer la autenticación de la UI de Control/WebSocket (verificados mediante `tailscale whois`). Los endpoints de la API HTTP **no** usan esa autenticación por encabezado de Tailscale; siguen el modo normal de autenticación HTTP del gateway. Este flujo sin token asume que el host del gateway es de confianza. Tiene como valor predeterminado `true` cuando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitador opcional de fallos de autenticación. Se aplica por IP del cliente y por alcance de autenticación (secreto compartido y token del dispositivo se rastrean de forma independiente). Los intentos bloqueados devuelven `429` + `Retry-After`. - - En la ruta asíncrona de la UI de Control de Tailscale Serve, los intentos fallidos para el mismo `{scope, clientIp}` se serializan antes de la escritura del fallo. Por tanto, intentos erróneos concurrentes del mismo cliente pueden activar el limitador en la segunda solicitud en lugar de que ambos compitan y pasen como simples discrepancias. - - `gateway.auth.rateLimit.exemptLoopback` tiene como valor predeterminado `true`; configure `false` cuando intencionalmente quiera limitar también el tráfico localhost (para configuraciones de prueba o implementaciones estrictas con proxy). -- Los intentos de autenticación WS con origen en navegador siempre se limitan con la exención loopback desactivada (defensa en profundidad contra fuerza bruta basada en navegador sobre localhost). -- En loopback, esos bloqueos con origen en navegador se aíslan por valor - `Origin` normalizado, por lo que fallos repetidos desde un origen localhost no - bloquean automáticamente otro origen diferente. +- **Alias heredados de bind**: usa valores de modo bind en `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), no alias de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Nota de Docker**: el bind predeterminado `loopback` escucha en `127.0.0.1` dentro del contenedor. Con redes bridge de Docker (`-p 18789:18789`), el tráfico llega por `eth0`, así que el gateway no es accesible. Usa `--network host`, o establece `bind: "lan"` (o `bind: "custom"` con `customBindHost: "0.0.0.0"`) para escuchar en todas las interfaces. +- **Auth**: requerido de forma predeterminada. Los binds no loopback requieren autenticación del gateway. En la práctica eso significa un token/contraseña compartidos o un proxy inverso con reconocimiento de identidad con `gateway.auth.mode: "trusted-proxy"`. El asistente de onboarding genera un token por defecto. +- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados (incluidos SecretRefs), establece `gateway.auth.mode` explícitamente en `token` o `password`. El inicio y los flujos de instalación/reparación del servicio fallan cuando ambos están configurados y `mode` no está definido. +- `gateway.auth.mode: "none"`: modo explícito sin autenticación. Úsalo solo para configuraciones locales de loopback de confianza; intencionalmente no se ofrece en los prompts de onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega la autenticación a un proxy inverso con reconocimiento de identidad y confía en los encabezados de identidad de `gateway.trustedProxies` (consulta [Auth de proxy de confianza](/es/gateway/trusted-proxy-auth)). Este modo espera un origen de proxy **no loopback**; los proxies inversos loopback en el mismo host no cumplen con la autenticación trusted-proxy. +- `gateway.auth.allowTailscale`: cuando es `true`, los encabezados de identidad de Tailscale Serve pueden satisfacer la autenticación de Control UI/WebSocket (verificados mediante `tailscale whois`). Los endpoints de la API HTTP **no** usan esa autenticación por encabezado de Tailscale; siguen el modo normal de autenticación HTTP del gateway. Este flujo sin token asume que el host del gateway es de confianza. Su valor predeterminado es `true` cuando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitador opcional de fallos de autenticación. Se aplica por IP de cliente y por alcance de autenticación (se registran por separado el secreto compartido y el token de dispositivo). Los intentos bloqueados devuelven `429` + `Retry-After`. + - En la ruta asíncrona de Control UI de Tailscale Serve, los intentos fallidos del mismo `{scope, clientIp}` se serializan antes de escribir el fallo. Por lo tanto, intentos incorrectos simultáneos del mismo cliente pueden activar el limitador en la segunda solicitud en lugar de dejar que ambas compitan como simples discrepancias. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` de forma predeterminada; establécelo en `false` cuando quieras intencionalmente limitar también el tráfico localhost (para configuraciones de prueba o implementaciones estrictas con proxy). +- Los intentos de autenticación WS con origen en navegador siempre se limitan con la exención de loopback desactivada (defensa en profundidad contra fuerza bruta de localhost basada en navegador). +- En loopback, esos bloqueos con origen en navegador se aíslan por valor `Origin` + normalizado, de modo que los fallos repetidos desde un origen localhost no + bloqueen automáticamente un origen distinto. - `tailscale.mode`: `serve` (solo tailnet, bind loopback) o `funnel` (público, requiere autenticación). -- `controlUi.allowedOrigins`: lista explícita de orígenes de navegador permitidos para conexiones WebSocket al Gateway. Obligatoria cuando se esperan clientes del navegador desde orígenes no loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo peligroso que habilita el respaldo de origen mediante encabezado Host para implementaciones que dependen intencionalmente de la política de origen basada en Host-header. +- `controlUi.allowedOrigins`: lista explícita de orígenes de navegador permitidos para conexiones WebSocket del Gateway. Requerida cuando se esperan clientes de navegador desde orígenes no loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo peligroso que habilita el respaldo de origen por encabezado Host para implementaciones que dependen intencionalmente de la política de origen basada en Host. - `remote.transport`: `ssh` (predeterminado) o `direct` (ws/wss). Para `direct`, `remote.url` debe ser `ws://` o `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: reemplazo break-glass del lado del cliente que permite `ws://` en texto plano hacia IP de red privada de confianza; el valor predeterminado sigue siendo permitir texto plano solo en loopback. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: sobrescritura de emergencia del lado del cliente que permite `ws://` en texto sin cifrar hacia IP de red privada de confianza; el valor predeterminado sigue siendo solo loopback para texto sin cifrar. - `gateway.remote.token` / `.password` son campos de credenciales del cliente remoto. No configuran por sí mismos la autenticación del gateway. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para el relay externo de APNs usado por compilaciones oficiales/TestFlight de iOS después de publicar registros respaldados por relay en el gateway. Esta URL debe coincidir con la URL del relay compilada en la build de iOS. -- `gateway.push.apns.relay.timeoutMs`: tiempo de espera en milisegundos para el envío del gateway al relay. Predeterminado: `10000`. -- Los registros respaldados por relay se delegan a una identidad específica del gateway. La app iOS emparejada obtiene `gateway.identity.get`, incluye esa identidad en el registro del relay y reenvía al gateway un permiso de envío con alcance al registro. Otro gateway no puede reutilizar ese registro almacenado. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: reemplazos temporales por entorno para la configuración del relay anterior. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo para desarrollo para URL de relay HTTP en loopback. Las URL de relay de producción deben permanecer en HTTPS. -- `gateway.channelHealthCheckMinutes`: intervalo del monitor de salud de canales en minutos. Configure `0` para desactivar globalmente los reinicios del monitor de salud. Predeterminado: `5`. -- `gateway.channelStaleEventThresholdMinutes`: umbral de socket obsoleto en minutos. Manténgalo mayor o igual que `gateway.channelHealthCheckMinutes`. Predeterminado: `30`. -- `gateway.channelMaxRestartsPerHour`: número máximo de reinicios del monitor de salud por canal/cuenta en una hora móvil. Predeterminado: `10`. -- `channels..healthMonitor.enabled`: exclusión por canal para los reinicios del monitor de salud, manteniendo habilitado el monitor global. -- `channels..accounts..healthMonitor.enabled`: reemplazo por cuenta para canales con múltiples cuentas. Cuando está configurado, tiene prioridad sobre el reemplazo a nivel de canal. -- Las rutas de llamada del gateway local pueden usar `gateway.remote.*` como respaldo solo cuando `gateway.auth.*` no está configurado. -- Si `gateway.auth.token` / `gateway.auth.password` está configurado explícitamente mediante SecretRef y no se puede resolver, la resolución falla en modo cerrado (sin enmascaramiento por respaldo remoto). -- `trustedProxies`: IP de proxies inversos que terminan TLS o inyectan encabezados de cliente reenviado. Incluya solo proxies que controle. Las entradas loopback siguen siendo válidas para configuraciones de proxy en el mismo host/detección local (por ejemplo Tailscale Serve o un proxy inverso local), pero **no** hacen que las solicitudes loopback sean elegibles para `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: cuando es `true`, el gateway acepta `X-Real-IP` si falta `X-Forwarded-For`. Predeterminado `false` para comportamiento fail-closed. -- `gateway.tools.deny`: nombres adicionales de herramientas bloqueadas para HTTP `POST /tools/invoke` (amplía la lista predeterminada de denegación). +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para el relay APNs externo usado por las compilaciones oficiales/TestFlight de iOS después de que publiquen registros respaldados por relay en el gateway. Esta URL debe coincidir con la URL del relay compilada en la build de iOS. +- `gateway.push.apns.relay.timeoutMs`: tiempo de espera en milisegundos para envíos del gateway al relay. Predeterminado: `10000`. +- Los registros respaldados por relay se delegan a una identidad específica del gateway. La app iOS emparejada obtiene `gateway.identity.get`, incluye esa identidad en el registro del relay y reenvía al gateway un permiso de envío con alcance del registro. Otro gateway no puede reutilizar ese registro almacenado. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: sobrescrituras temporales por entorno para la configuración del relay anterior. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch solo para desarrollo para URLs loopback HTTP del relay. Las URLs de relay de producción deben seguir usando HTTPS. +- `gateway.channelHealthCheckMinutes`: intervalo del monitor de salud de canales en minutos. Establece `0` para desactivar globalmente los reinicios del monitor de salud. Predeterminado: `5`. +- `gateway.channelStaleEventThresholdMinutes`: umbral de socket obsoleto en minutos. Mantén este valor mayor o igual que `gateway.channelHealthCheckMinutes`. Predeterminado: `30`. +- `gateway.channelMaxRestartsPerHour`: máximo de reinicios del monitor de salud por canal/cuenta dentro de una hora móvil. Predeterminado: `10`. +- `channels..healthMonitor.enabled`: opt-out por canal de los reinicios del monitor de salud manteniendo habilitado el monitor global. +- `channels..accounts..healthMonitor.enabled`: sobrescritura por cuenta para canales con múltiples cuentas. Cuando se establece, tiene prioridad sobre la sobrescritura a nivel de canal. +- Las rutas de llamada del gateway local pueden usar `gateway.remote.*` como respaldo solo cuando `gateway.auth.*` no está definido. +- Si `gateway.auth.token` / `gateway.auth.password` están configurados explícitamente mediante SecretRef y no se resuelven, la resolución falla en modo cerrado (sin enmascaramiento por respaldo remoto). +- `trustedProxies`: IP de proxies inversos que terminan TLS o inyectan encabezados de cliente reenviado. Lista solo proxies que controles. Las entradas loopback siguen siendo válidas para configuraciones de detección local/proxy en el mismo host (por ejemplo Tailscale Serve o un proxy inverso local), pero **no** hacen que las solicitudes loopback sean elegibles para `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: cuando es `true`, el gateway acepta `X-Real-IP` si falta `X-Forwarded-For`. Predeterminado `false` para comportamiento de fallo cerrado. +- `gateway.tools.deny`: nombres adicionales de herramientas bloqueados para HTTP `POST /tools/invoke` (amplía la lista predeterminada de denegación). - `gateway.tools.allow`: elimina nombres de herramientas de la lista predeterminada de denegación HTTP. ### Endpoints compatibles con OpenAI -- Chat Completions: desactivado de forma predeterminada. Habilítelo con `gateway.http.endpoints.chatCompletions.enabled: true`. -- API Responses: `gateway.http.endpoints.responses.enabled`. -- Endurecimiento de entrada por URL de Responses: +- Chat Completions: desactivado de forma predeterminada. Habilítalo con `gateway.http.endpoints.chatCompletions.enabled: true`. +- API de Responses: `gateway.http.endpoints.responses.enabled`. +- Endurecimiento de entrada por URL en Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Las listas de permitidos vacías se tratan como no configuradas; use `gateway.http.endpoints.responses.files.allowUrl=false` + Las listas de permitidos vacías se tratan como no definidas; usa `gateway.http.endpoints.responses.files.allowUrl=false` y/o `gateway.http.endpoints.responses.images.allowUrl=false` para desactivar la obtención por URL. - Encabezado opcional de endurecimiento de respuesta: - - `gateway.http.securityHeaders.strictTransportSecurity` (configúrelo solo para orígenes HTTPS que controle; consulte [Trusted Proxy Auth](/es/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (establécelo solo para orígenes HTTPS que controles; consulta [Auth de proxy de confianza](/es/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Aislamiento de múltiples instancias +### Aislamiento multiinstancia -Ejecute varios gateways en un mismo host con puertos y directorios de estado únicos: +Ejecuta varios gateways en un mismo host con puertos y directorios de estado únicos: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3136,9 +3120,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Indicadores de conveniencia: `--dev` (usa `~/.openclaw-dev` + puerto `19001`), `--profile ` (usa `~/.openclaw-`). +Flags de conveniencia: `--dev` (usa `~/.openclaw-dev` + puerto `19001`), `--profile ` (usa `~/.openclaw-`). -Consulte [Múltiples Gateways](/es/gateway/multiple-gateways). +Consulta [Múltiples Gateways](/es/gateway/multiple-gateways). ### `gateway.tls` @@ -3157,10 +3141,10 @@ Consulte [Múltiples Gateways](/es/gateway/multiple-gateways). ``` - `enabled`: habilita la terminación TLS en el listener del gateway (HTTPS/WSS) (predeterminado: `false`). -- `autoGenerate`: genera automáticamente un par local de certificado/clave autofirmado cuando no hay archivos explícitos configurados; solo para uso local/desarrollo. -- `certPath`: ruta del sistema de archivos al archivo del certificado TLS. -- `keyPath`: ruta del sistema de archivos a la clave privada TLS; manténgala con permisos restringidos. -- `caPath`: ruta opcional del paquete CA para verificación de clientes o cadenas de confianza personalizadas. +- `autoGenerate`: genera automáticamente un par local autocertificado de cert/key cuando no hay archivos explícitos configurados; solo para uso local/dev. +- `certPath`: ruta del sistema de archivos al archivo de certificado TLS. +- `keyPath`: ruta del sistema de archivos al archivo de clave privada TLS; mantén permisos restringidos. +- `caPath`: ruta opcional al bundle de CA para verificación de clientes o cadenas de confianza personalizadas. ### `gateway.reload` @@ -3176,13 +3160,13 @@ Consulte [Múltiples Gateways](/es/gateway/multiple-gateways). } ``` -- `mode`: controla cómo se aplican las ediciones de configuración en tiempo de ejecución. - - `"off"`: ignora ediciones en vivo; los cambios requieren un reinicio explícito. - - `"restart"`: siempre reinicia el proceso del gateway cuando cambia la configuración. - - `"hot"`: aplica los cambios en el proceso sin reiniciar. - - `"hybrid"` (predeterminado): intenta primero la recarga en caliente; recurre a reinicio si es necesario. -- `debounceMs`: ventana de antirrebote en ms antes de aplicar cambios de configuración (entero no negativo). -- `deferralTimeoutMs`: tiempo máximo en ms de espera para que finalicen operaciones en curso antes de forzar un reinicio (predeterminado: `300000` = 5 minutos). +- `mode`: controla cómo se aplican las ediciones de configuración en runtime. + - `"off"`: ignora las ediciones en vivo; los cambios requieren un reinicio explícito. + - `"restart"`: siempre reinicia el proceso del gateway ante cambios de configuración. + - `"hot"`: aplica los cambios dentro del proceso sin reiniciar. + - `"hybrid"` (predeterminado): primero intenta hot reload; recurre a reinicio si es necesario. +- `debounceMs`: ventana de debounce en ms antes de aplicar cambios de configuración (entero no negativo). +- `deferralTimeoutMs`: tiempo máximo en ms para esperar operaciones en curso antes de forzar un reinicio (predeterminado: `300000` = 5 minutos). --- @@ -3220,36 +3204,36 @@ Consulte [Múltiples Gateways](/es/gateway/multiple-gateways). ``` Auth: `Authorization: Bearer ` o `x-openclaw-token: `. -Los tokens de hooks en la cadena de consulta se rechazan. +Los tokens de hooks en query string se rechazan. Notas de validación y seguridad: - `hooks.enabled=true` requiere un `hooks.token` no vacío. - `hooks.token` debe ser **distinto** de `gateway.auth.token`; se rechaza reutilizar el token del Gateway. -- `hooks.path` no puede ser `/`; use una subruta dedicada como `/hooks`. -- Si `hooks.allowRequestSessionKey=true`, restrinja `hooks.allowedSessionKeyPrefixes` (por ejemplo `["hook:"]`). +- `hooks.path` no puede ser `/`; usa una subruta dedicada como `/hooks`. +- Si `hooks.allowRequestSessionKey=true`, restringe `hooks.allowedSessionKeyPrefixes` (por ejemplo `["hook:"]`). **Endpoints:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` del cuerpo de la solicitud solo se acepta cuando `hooks.allowRequestSessionKey=true` (predeterminado: `false`). + - `sessionKey` de la carga útil de la solicitud solo se acepta cuando `hooks.allowRequestSessionKey=true` (predeterminado: `false`). - `POST /hooks/` → se resuelve mediante `hooks.mappings` - `match.path` coincide con la subruta después de `/hooks` (por ejemplo `/hooks/gmail` → `gmail`). - `match.source` coincide con un campo de la carga útil para rutas genéricas. -- Plantillas como `{{messages[0].subject}}` leen desde la carga útil. +- Las plantillas como `{{messages[0].subject}}` leen desde la carga útil. - `transform` puede apuntar a un módulo JS/TS que devuelve una acción de hook. - - `transform.module` debe ser una ruta relativa y permanecer dentro de `hooks.transformsDir` (se rechazan las rutas absolutas y la navegación de directorios). -- `agentId` enruta a un agente específico; los IDs desconocidos recurren al predeterminado. + - `transform.module` debe ser una ruta relativa y permanecer dentro de `hooks.transformsDir` (se rechazan rutas absolutas y recorridos de directorio). +- `agentId` enruta a un agente específico; los IDs desconocidos vuelven al predeterminado. - `allowedAgentIds`: restringe el enrutamiento explícito (`*` u omitido = permitir todos, `[]` = denegar todos). -- `defaultSessionKey`: clave de sesión fija opcional para ejecuciones del agente de hooks sin `sessionKey` explícita. -- `allowRequestSessionKey`: permite que los llamadores de `/hooks/agent` configuren `sessionKey` (predeterminado: `false`). +- `defaultSessionKey`: clave de sesión fija opcional para ejecuciones del agente de hooks sin `sessionKey` explícito. +- `allowRequestSessionKey`: permite que los llamadores de `/hooks/agent` establezcan `sessionKey` (predeterminado: `false`). - `allowedSessionKeyPrefixes`: lista opcional de prefijos permitidos para valores explícitos de `sessionKey` (solicitud + mapeo), por ejemplo `["hook:"]`. -- `deliver: true` envía la respuesta final a un canal; `channel` tiene como valor predeterminado `last`. -- `model` reemplaza el LLM para esta ejecución del hook (debe estar permitido si el catálogo de modelos está configurado). +- `deliver: true` envía la respuesta final a un canal; `channel` usa `last` por defecto. +- `model` sobrescribe el LLM para esta ejecución de hook (debe estar permitido si el catálogo de modelos está configurado). @@ -3276,12 +3260,12 @@ Notas de validación y seguridad: } ``` -- El Gateway inicia automáticamente `gog gmail watch serve` al arrancar cuando está configurado. Configure `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desactivarlo. -- No ejecute un `gog gmail watch serve` independiente junto con el Gateway. +- El Gateway inicia automáticamente `gog gmail watch serve` al arrancar cuando está configurado. Establece `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desactivarlo. +- No ejecutes un `gog gmail watch serve` separado junto al Gateway. --- -## Host de Canvas +## Canvas host ```json5 { @@ -3296,15 +3280,15 @@ Notas de validación y seguridad: - Sirve HTML/CSS/JS editables por el agente y A2UI por HTTP bajo el puerto del Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Solo local: mantenga `gateway.bind: "loopback"` (predeterminado). -- Binds no loopback: las rutas de canvas requieren autenticación del Gateway (token/password/trusted-proxy), igual que otras superficies HTTP del Gateway. -- Los WebViews de Node normalmente no envían encabezados de autenticación; después de que un node se empareja y conecta, el Gateway anuncia URL de capacidades con alcance al node para acceso a canvas/A2UI. -- Las URL de capacidades están vinculadas a la sesión WS activa del node y caducan rápidamente. No se usa respaldo basado en IP. -- Inyecta un cliente de recarga en vivo en el HTML servido. +- Solo local: mantén `gateway.bind: "loopback"` (predeterminado). +- En binds no loopback: las rutas de canvas requieren autenticación del Gateway (token/password/trusted-proxy), igual que las demás superficies HTTP del Gateway. +- Los Node WebViews normalmente no envían encabezados de autenticación; después de que un Node se empareja y conecta, el Gateway anuncia URL de capacidad con alcance de nodo para acceso a canvas/A2UI. +- Las URL de capacidad están vinculadas a la sesión WS activa del nodo y caducan rápidamente. No se usa respaldo basado en IP. +- Inyecta el cliente de live reload en el HTML servido. - Crea automáticamente un `index.html` inicial cuando está vacío. - También sirve A2UI en `/__openclaw__/a2ui/`. - Los cambios requieren reiniciar el gateway. -- Desactive la recarga en vivo para directorios grandes o errores `EMFILE`. +- Desactiva live reload para directorios grandes o errores `EMFILE`. --- @@ -3324,9 +3308,9 @@ Notas de validación y seguridad: - `minimal` (predeterminado): omite `cliPath` + `sshPort` de los registros TXT. - `full`: incluye `cliPath` + `sshPort`. -- El nombre de host tiene como valor predeterminado `openclaw`. Reemplácelo con `OPENCLAW_MDNS_HOSTNAME`. +- El nombre de host usa `openclaw` por defecto. Sobrescríbelo con `OPENCLAW_MDNS_HOSTNAME`. -### Amplia área (DNS-SD) +### Wide-area (DNS-SD) ```json5 { @@ -3336,7 +3320,7 @@ Notas de validación y seguridad: } ``` -Escribe una zona DNS-SD unicast en `~/.openclaw/dns/`. Para descubrimiento entre redes, combínelo con un servidor DNS (se recomienda CoreDNS) + DNS dividido de Tailscale. +Escribe una zona DNS-SD unicast en `~/.openclaw/dns/`. Para descubrimiento entre redes, combínalo con un servidor DNS (se recomienda CoreDNS) + split DNS de Tailscale. Configuración: `openclaw dns setup --apply`. @@ -3361,14 +3345,14 @@ Configuración: `openclaw dns setup --apply`. } ``` -- Las variables de entorno en línea solo se aplican si el entorno del proceso no contiene la clave. -- Archivos `.env`: `.env` del CWD + `~/.openclaw/.env` (ninguno reemplaza variables existentes). -- `shellEnv`: importa claves esperadas ausentes desde el perfil de su shell de inicio de sesión. -- Consulte [Environment](/es/help/environment) para ver la precedencia completa. +- Las variables de entorno en línea solo se aplican si al entorno del proceso le falta la clave. +- Archivos `.env`: `.env` del CWD + `~/.openclaw/.env` (ninguno sobrescribe variables existentes). +- `shellEnv`: importa claves esperadas faltantes desde el perfil de tu shell de inicio de sesión. +- Consulta [Entorno](/es/help/environment) para la precedencia completa. ### Sustitución de variables de entorno -Haga referencia a variables de entorno en cualquier cadena de configuración con `${VAR_NAME}`: +Haz referencia a variables de entorno en cualquier cadena de configuración con `${VAR_NAME}`: ```json5 { @@ -3379,19 +3363,19 @@ Haga referencia a variables de entorno en cualquier cadena de configuración con ``` - Solo coinciden nombres en mayúsculas: `[A-Z_][A-Z0-9_]*`. -- Variables ausentes/vacías generan un error al cargar la configuración. -- Escape con `$${VAR}` para un `${VAR}` literal. +- Las variables faltantes/vacías generan un error al cargar la configuración. +- Escapa con `$${VAR}` para un `${VAR}` literal. - Funciona con `$include`. --- -## Secrets +## Secretos -Las referencias de secreto son aditivas: los valores en texto sin formato siguen funcionando. +Las refs secretas son aditivas: los valores en texto sin formato siguen funcionando. ### `SecretRef` -Use una sola forma de objeto: +Usa una única forma de objeto: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3399,17 +3383,17 @@ Use una sola forma de objeto: Validación: -- Patrón de `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- Patrón de id para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- patrón de `provider`: `^[a-z][a-z0-9_-]{0,63}$` +- patrón de id de `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` id: puntero JSON absoluto (por ejemplo `"/providers/openai/apiKey"`) -- Patrón de id para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- Los id de `source: "exec"` no deben contener segmentos de ruta delimitados por `/` que sean `.` o `..` (por ejemplo `a/../b` se rechaza) +- patrón de id de `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- Los ids de `source: "exec"` no deben contener segmentos de ruta delimitados por `/` como `.` o `..` (por ejemplo se rechaza `a/../b`) ### Superficie de credenciales compatible - Matriz canónica: [Superficie de credenciales SecretRef](/es/reference/secretref-credential-surface) - `secrets apply` apunta a rutas de credenciales compatibles de `openclaw.json`. -- Las referencias de `auth-profiles.json` se incluyen en la resolución en tiempo de ejecución y en la cobertura de auditoría. +- Las refs de `auth-profiles.json` se incluyen en la resolución en runtime y en la cobertura de auditoría. ### Configuración de proveedores de secretos @@ -3443,11 +3427,11 @@ Notas: - El proveedor `file` admite `mode: "json"` y `mode: "singleValue"` (`id` debe ser `"value"` en modo singleValue). - El proveedor `exec` requiere una ruta `command` absoluta y usa cargas útiles de protocolo en stdin/stdout. -- De forma predeterminada, se rechazan las rutas de comando que son enlaces simbólicos. Configure `allowSymlinkCommand: true` para permitir rutas con enlaces simbólicos mientras se valida la ruta resuelta del destino. -- Si `trustedDirs` está configurado, la comprobación de directorio de confianza se aplica a la ruta resuelta del destino. -- El entorno hijo de `exec` es mínimo de forma predeterminada; pase explícitamente las variables necesarias con `passEnv`. -- Las referencias de secreto se resuelven en el momento de activación en una instantánea en memoria y luego las rutas de solicitud solo leen esa instantánea. -- El filtrado por superficie activa se aplica durante la activación: las referencias no resueltas en superficies habilitadas hacen fallar el inicio/la recarga, mientras que las superficies inactivas se omiten con diagnósticos. +- De forma predeterminada, se rechazan rutas de comandos con symlink. Establece `allowSymlinkCommand: true` para permitir rutas con symlink mientras se valida la ruta del destino resuelto. +- Si `trustedDirs` está configurado, la comprobación de directorio de confianza se aplica a la ruta del destino resuelto. +- El entorno hijo de `exec` es mínimo de forma predeterminada; pasa explícitamente las variables necesarias con `passEnv`. +- Las refs secretas se resuelven en el momento de activación en una instantánea en memoria, y luego las rutas de solicitud solo leen esa instantánea. +- El filtrado de superficie activa se aplica durante la activación: las refs no resueltas en superficies habilitadas hacen fallar el inicio/recarga, mientras que las superficies inactivas se omiten con diagnósticos. --- @@ -3470,11 +3454,11 @@ Notas: ``` - Los perfiles por agente se almacenan en `/auth-profiles.json`. -- `auth-profiles.json` admite referencias a nivel de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credenciales estáticas. +- `auth-profiles.json` admite refs a nivel de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credenciales estáticas. - Los perfiles en modo OAuth (`auth.profiles..mode = "oauth"`) no admiten credenciales de perfil de autenticación respaldadas por SecretRef. -- Las credenciales estáticas del runtime provienen de instantáneas resueltas en memoria; las entradas estáticas heredadas de `auth.json` se depuran cuando se detectan. +- Las credenciales estáticas en runtime provienen de instantáneas resueltas en memoria; las entradas heredadas estáticas de `auth.json` se depuran cuando se detectan. - Importaciones heredadas de OAuth desde `~/.openclaw/credentials/oauth.json`. -- Consulte [OAuth](/es/concepts/oauth). +- Consulta [OAuth](/es/concepts/oauth). - Comportamiento del runtime de secretos y herramientas `audit/configure/apply`: [Gestión de secretos](/es/gateway/secrets). ### `auth.cooldowns` @@ -3497,21 +3481,20 @@ Notas: } ``` -- `billingBackoffHours`: retroceso base en horas cuando un perfil falla por errores reales - de facturación/crédito insuficiente (predeterminado: `5`). El texto explícito de facturación aún puede - llegar aquí incluso en respuestas `401`/`403`, pero los comparadores de texto - específicos del proveedor siguen limitados al proveedor al que pertenecen (por ejemplo OpenRouter - `Key limit exceeded`). Los mensajes de ventana de uso reintentables HTTP `402` o - de límite de gasto de organización/workspace permanecen en la ruta `rate_limit` - en su lugar. -- `billingBackoffHoursByProvider`: reemplazos opcionales por proveedor para las horas de retroceso de facturación. -- `billingMaxHours`: límite en horas para el crecimiento exponencial del retroceso de facturación (predeterminado: `24`). -- `authPermanentBackoffMinutes`: retroceso base en minutos para fallos `auth_permanent` de alta confianza (predeterminado: `10`). -- `authPermanentMaxMinutes`: límite en minutos para el crecimiento del retroceso de `auth_permanent` (predeterminado: `60`). -- `failureWindowHours`: ventana móvil en horas usada para contadores de retroceso (predeterminado: `24`). -- `overloadedProfileRotations`: máximo de rotaciones de perfil de autenticación del mismo proveedor para errores de sobrecarga antes de cambiar al respaldo del modelo (predeterminado: `1`). Las formas de proveedor ocupado, como `ModelNotReadyException`, llegan aquí. +- `billingBackoffHours`: backoff base en horas cuando un perfil falla debido a errores reales + de facturación/crédito insuficiente (predeterminado: `5`). El texto explícito de facturación + aún puede terminar aquí incluso en respuestas `401`/`403`, pero los matchers de texto + específicos del proveedor siguen limitados al proveedor que les corresponde (por ejemplo OpenRouter + `Key limit exceeded`). Los mensajes reintentables de uso por ventana `402` HTTP o de + límite de gasto de organización/workspace permanecen en la ruta `rate_limit`. +- `billingBackoffHoursByProvider`: sobrescrituras opcionales por proveedor para horas de backoff de facturación. +- `billingMaxHours`: límite en horas para el crecimiento exponencial del backoff de facturación (predeterminado: `24`). +- `authPermanentBackoffMinutes`: backoff base en minutos para fallos `auth_permanent` de alta confianza (predeterminado: `10`). +- `authPermanentMaxMinutes`: límite en minutos para el crecimiento del backoff de `auth_permanent` (predeterminado: `60`). +- `failureWindowHours`: ventana móvil en horas usada para contadores de backoff (predeterminado: `24`). +- `overloadedProfileRotations`: máximo de rotaciones de auth-profile del mismo proveedor para errores de sobrecarga antes de cambiar al modelo de respaldo (predeterminado: `1`). Las formas de proveedor ocupado como `ModelNotReadyException` llegan aquí. - `overloadedBackoffMs`: retraso fijo antes de reintentar una rotación de proveedor/perfil sobrecargado (predeterminado: `0`). -- `rateLimitedProfileRotations`: máximo de rotaciones de perfil de autenticación del mismo proveedor para errores de límite de velocidad antes de cambiar al respaldo del modelo (predeterminado: `1`). Ese bucket de límite de velocidad incluye texto con forma de proveedor como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` y `resource exhausted`. +- `rateLimitedProfileRotations`: máximo de rotaciones de auth-profile del mismo proveedor para errores de límite de tasa antes de cambiar al modelo de respaldo (predeterminado: `1`). Ese grupo de límites de tasa incluye texto con forma de proveedor como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` y `resource exhausted`. --- @@ -3531,13 +3514,13 @@ Notas: ``` - Archivo de registro predeterminado: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Configure `logging.file` para una ruta estable. -- `consoleLevel` aumenta a `debug` con `--verbose`. -- `maxFileBytes`: tamaño máximo del archivo de registro en bytes antes de que se supriman las escrituras (entero positivo; predeterminado: `524288000` = 500 MB). Use rotación externa de registros para implementaciones de producción. +- Establece `logging.file` para una ruta estable. +- `consoleLevel` sube a `debug` con `--verbose`. +- `maxFileBytes`: tamaño máximo del archivo de registro en bytes antes de que se supriman escrituras (entero positivo; predeterminado: `524288000` = 500 MB). Usa rotación de logs externa para implementaciones de producción. --- -## Diagnóstico +## Diagnósticos ```json5 { @@ -3571,19 +3554,19 @@ Notas: ``` - `enabled`: interruptor maestro para la salida de instrumentación (predeterminado: `true`). -- `flags`: arreglo de cadenas de indicadores que habilitan salida de registro dirigida (admite comodines como `"telegram.*"` o `"*"`). +- `flags`: arreglo de cadenas de flags que habilitan salida de logs dirigida (admite comodines como `"telegram.*"` o `"*"`). - `stuckSessionWarnMs`: umbral de antigüedad en ms para emitir advertencias de sesión atascada mientras una sesión permanece en estado de procesamiento. -- `otel.enabled`: habilita el pipeline de exportación de OpenTelemetry (predeterminado: `false`). -- `otel.endpoint`: URL del colector para la exportación OTel. +- `otel.enabled`: habilita la canalización de exportación de OpenTelemetry (predeterminado: `false`). +- `otel.endpoint`: URL del recolector para exportación OTel. - `otel.protocol`: `"http/protobuf"` (predeterminado) o `"grpc"`. -- `otel.headers`: encabezados adicionales de metadatos HTTP/gRPC enviados con las solicitudes de exportación OTel. -- `otel.serviceName`: nombre del servicio para atributos de recursos. -- `otel.traces` / `otel.metrics` / `otel.logs`: habilitan la exportación de trazas, métricas o registros. +- `otel.headers`: encabezados de metadatos HTTP/gRPC extra enviados con las solicitudes de exportación OTel. +- `otel.serviceName`: nombre del servicio para atributos de recurso. +- `otel.traces` / `otel.metrics` / `otel.logs`: habilitan exportación de trazas, métricas o logs. - `otel.sampleRate`: tasa de muestreo de trazas `0`–`1`. - `otel.flushIntervalMs`: intervalo periódico de vaciado de telemetría en ms. -- `cacheTrace.enabled`: registra instantáneas de rastro de caché para ejecuciones integradas (predeterminado: `false`). -- `cacheTrace.filePath`: ruta de salida para el JSONL de rastro de caché (predeterminado: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlan qué se incluye en la salida del rastro de caché (todos con valor predeterminado: `true`). +- `cacheTrace.enabled`: registra instantáneas de rastreo de caché para ejecuciones incrustadas (predeterminado: `false`). +- `cacheTrace.filePath`: ruta de salida para JSONL de rastreo de caché (predeterminado: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlan qué se incluye en la salida del rastreo de caché (todos usan `true` por defecto). --- @@ -3605,12 +3588,12 @@ Notas: } ``` -- `channel`: canal de lanzamiento para instalaciones npm/git: `"stable"`, `"beta"` o `"dev"`. +- `channel`: canal de versión para instalaciones npm/git — `"stable"`, `"beta"` o `"dev"`. - `checkOnStart`: comprueba actualizaciones de npm cuando se inicia el gateway (predeterminado: `true`). -- `auto.enabled`: habilita la actualización automática en segundo plano para instalaciones de paquetes (predeterminado: `false`). -- `auto.stableDelayHours`: retraso mínimo en horas antes de la aplicación automática en el canal estable (predeterminado: `6`; máximo: `168`). -- `auto.stableJitterHours`: ventana adicional de distribución del despliegue del canal estable en horas (predeterminado: `12`; máximo: `168`). -- `auto.betaCheckIntervalHours`: con qué frecuencia se ejecutan las comprobaciones del canal beta en horas (predeterminado: `1`; máximo: `24`). +- `auto.enabled`: habilita actualización automática en segundo plano para instalaciones de paquetes (predeterminado: `false`). +- `auto.stableDelayHours`: retraso mínimo en horas antes de la aplicación automática del canal estable (predeterminado: `6`; máximo: `168`). +- `auto.stableJitterHours`: ventana adicional en horas para escalonar el despliegue del canal estable (predeterminado: `12`; máximo: `168`). +- `auto.betaCheckIntervalHours`: frecuencia en horas de las comprobaciones del canal beta (predeterminado: `1`; máximo: `24`). --- @@ -3643,22 +3626,22 @@ Notas: } ``` -- `enabled`: compuerta global de funciones ACP (predeterminado: `false`). -- `dispatch.enabled`: compuerta independiente para el despacho de turnos de sesión ACP (predeterminado: `true`). Configure `false` para mantener disponibles los comandos ACP mientras bloquea la ejecución. -- `backend`: ID predeterminado del backend de runtime ACP (debe coincidir con un Plugin de runtime ACP registrado). -- `defaultAgent`: ID de agente ACP de respaldo cuando las generadas no especifican un destino explícito. -- `allowedAgents`: lista de permitidos de IDs de agente autorizados para sesiones del runtime ACP; vacío significa sin restricción adicional. +- `enabled`: puerta global de funciones ACP (predeterminado: `false`). +- `dispatch.enabled`: puerta independiente para el despacho de turnos de sesión ACP (predeterminado: `true`). Establécelo en `false` para mantener disponibles los comandos ACP mientras se bloquea la ejecución. +- `backend`: id predeterminado del backend de runtime ACP (debe coincidir con un plugin de runtime ACP registrado). +- `defaultAgent`: id del agente ACP de respaldo cuando los spawns no especifican un destino explícito. +- `allowedAgents`: lista de permitidos de ids de agentes autorizados para sesiones de runtime ACP; vacío significa sin restricción adicional. - `maxConcurrentSessions`: máximo de sesiones ACP activas simultáneamente. - `stream.coalesceIdleMs`: ventana de vaciado por inactividad en ms para texto transmitido. -- `stream.maxChunkChars`: tamaño máximo de fragmento antes de dividir la proyección de bloques transmitidos. -- `stream.repeatSuppression`: suprime líneas repetidas de estado/herramientas por turno (predeterminado: `true`). -- `stream.deliveryMode`: `"live"` transmite de forma incremental; `"final_only"` almacena en búfer hasta los eventos terminales del turno. -- `stream.hiddenBoundarySeparator`: separador antes del texto visible tras eventos ocultos de herramientas (predeterminado: `"paragraph"`). +- `stream.maxChunkChars`: tamaño máximo de fragmento antes de dividir la proyección del bloque transmitido. +- `stream.repeatSuppression`: suprime líneas repetidas de estado/herramienta por turno (predeterminado: `true`). +- `stream.deliveryMode`: `"live"` transmite de forma incremental; `"final_only"` almacena en búfer hasta eventos terminales del turno. +- `stream.hiddenBoundarySeparator`: separador antes del texto visible después de eventos ocultos de herramientas (predeterminado: `"paragraph"`). - `stream.maxOutputChars`: máximo de caracteres de salida del asistente proyectados por turno ACP. - `stream.maxSessionUpdateChars`: máximo de caracteres para líneas proyectadas de estado/actualización ACP. -- `stream.tagVisibility`: registro de nombres de etiquetas a reemplazos booleanos de visibilidad para eventos transmitidos. -- `runtime.ttlMinutes`: TTL de inactividad en minutos para trabajadores de sesión ACP antes de que sean elegibles para limpieza. -- `runtime.installCommand`: comando de instalación opcional que se ejecuta al preparar un entorno de runtime ACP. +- `stream.tagVisibility`: registro de nombres de etiquetas a sobrescrituras booleanas de visibilidad para eventos transmitidos. +- `runtime.ttlMinutes`: TTL de inactividad en minutos para workers de sesión ACP antes de ser elegibles para limpieza. +- `runtime.installCommand`: comando opcional de instalación que se ejecuta al inicializar un entorno de runtime ACP. --- @@ -3676,15 +3659,15 @@ Notas: - `cli.banner.taglineMode` controla el estilo del eslogan del banner: - `"random"` (predeterminado): eslóganes rotativos divertidos/de temporada. - - `"default"`: eslogan neutral fijo (`Todos tus chats, un solo OpenClaw.`). - - `"off"`: sin texto de eslogan (el título/versión del banner se sigue mostrando). -- Para ocultar todo el banner (no solo los eslóganes), configure la variable de entorno `OPENCLAW_HIDE_BANNER=1`. + - `"default"`: eslogan neutral fijo (`Todos tus chats, un OpenClaw.`). + - `"off"`: sin texto de eslogan (el título/versión del banner siguen mostrándose). +- Para ocultar todo el banner (no solo los eslóganes), establece la variable de entorno `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Metadatos escritos por los flujos de configuración guiada de la CLI (`onboard`, `configure`, `doctor`): +Metadatos escritos por flujos guiados de configuración de CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3702,13 +3685,13 @@ Metadatos escritos por los flujos de configuración guiada de la CLI (`onboard`, ## Identidad -Consulte los campos de identidad de `agents.list` en [Valores predeterminados del agente](#agent-defaults). +Consulta los campos de identidad de `agents.list` en [Valores predeterminados del agente](#agent-defaults). --- ## Bridge (heredado, eliminado) -Las compilaciones actuales ya no incluyen el bridge TCP. Los nodes se conectan mediante el WebSocket del Gateway. Las claves `bridge.*` ya no forman parte del esquema de configuración (la validación falla hasta que se eliminen; `openclaw doctor --fix` puede quitar claves desconocidas). +Las compilaciones actuales ya no incluyen el bridge TCP. Los Nodes se conectan mediante el WebSocket del Gateway. Las claves `bridge.*` ya no forman parte del esquema de configuración (la validación falla hasta que se eliminen; `openclaw doctor --fix` puede quitar claves desconocidas). @@ -3748,10 +3731,10 @@ Las compilaciones actuales ya no incluyen el bridge TCP. Los nodes se conectan m } ``` -- `sessionRetention`: cuánto tiempo conservar las sesiones completadas de ejecuciones aisladas de Cron antes de podarlas de `sessions.json`. También controla la limpieza de transcripciones archivadas eliminadas de Cron. Predeterminado: `24h`; configure `false` para desactivarlo. -- `runLog.maxBytes`: tamaño máximo por archivo de registro de ejecución (`cron/runs/.jsonl`) antes de podar. Predeterminado: `2_000_000` bytes. -- `runLog.keepLines`: líneas más recientes conservadas cuando se activa la poda del registro de ejecución. Predeterminado: `2000`. -- `webhookToken`: token bearer usado para la entrega POST del Webhook de Cron (`delivery.mode = "webhook"`); si se omite, no se envía encabezado de autenticación. +- `sessionRetention`: cuánto tiempo conservar las sesiones completadas de ejecuciones Cron aisladas antes de eliminarlas de `sessions.json`. También controla la limpieza de transcripciones Cron eliminadas archivadas. Predeterminado: `24h`; establece `false` para desactivar. +- `runLog.maxBytes`: tamaño máximo por archivo de log de ejecución (`cron/runs/.jsonl`) antes de la poda. Predeterminado: `2_000_000` bytes. +- `runLog.keepLines`: líneas más recientes conservadas cuando se activa la poda del log de ejecución. Predeterminado: `2000`. +- `webhookToken`: token bearer usado para la entrega POST de Webhook de Cron (`delivery.mode = "webhook"`); si se omite no se envía encabezado de autenticación. - `webhook`: URL heredada obsoleta de respaldo del Webhook (http/https) usada solo para trabajos almacenados que todavía tienen `notify: true`. ### `cron.retry` @@ -3768,11 +3751,11 @@ Las compilaciones actuales ya no incluyen el bridge TCP. Los nodes se conectan m } ``` -- `maxAttempts`: número máximo de reintentos para trabajos de una sola ejecución ante errores transitorios (predeterminado: `3`; rango: `0`–`10`). -- `backoffMs`: arreglo de retrasos de retroceso en ms para cada intento de reintento (predeterminado: `[30000, 60000, 300000]`; de 1 a 10 entradas). -- `retryOn`: tipos de error que activan reintentos: `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omítalo para reintentar todos los tipos transitorios. +- `maxAttempts`: número máximo de reintentos para trabajos de una sola vez ante errores transitorios (predeterminado: `3`; rango: `0`–`10`). +- `backoffMs`: arreglo de retrasos de backoff en ms para cada intento de reintento (predeterminado: `[30000, 60000, 300000]`; 1–10 entradas). +- `retryOn`: tipos de error que activan reintentos — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omítelo para reintentar todos los tipos transitorios. -Se aplica solo a trabajos Cron de una sola ejecución. Los trabajos recurrentes usan un manejo de fallos independiente. +Se aplica solo a trabajos Cron de una sola vez. Los trabajos recurrentes usan un manejo de fallos independiente. ### `cron.failureAlert` @@ -3791,10 +3774,10 @@ Se aplica solo a trabajos Cron de una sola ejecución. Los trabajos recurrentes ``` - `enabled`: habilita alertas de fallo para trabajos Cron (predeterminado: `false`). -- `after`: fallos consecutivos antes de que se dispare una alerta (entero positivo, mínimo: `1`). -- `cooldownMs`: milisegundos mínimos entre alertas repetidas del mismo trabajo (entero no negativo). -- `mode`: modo de entrega — `"announce"` envía mediante un mensaje del canal; `"webhook"` publica en el Webhook configurado. -- `accountId`: ID opcional de cuenta o canal para delimitar la entrega de alertas. +- `after`: fallos consecutivos antes de que se dispare una alerta (entero positivo, mín.: `1`). +- `cooldownMs`: milisegundos mínimos entre alertas repetidas para el mismo trabajo (entero no negativo). +- `mode`: modo de entrega — `"announce"` envía mediante un mensaje de canal; `"webhook"` publica en el Webhook configurado. +- `accountId`: id opcional de cuenta o canal para limitar el alcance de la entrega de alertas. ### `cron.failureDestination` @@ -3812,15 +3795,15 @@ Se aplica solo a trabajos Cron de una sola ejecución. Los trabajos recurrentes ``` - Destino predeterminado para notificaciones de fallo de Cron en todos los trabajos. -- `mode`: `"announce"` o `"webhook"`; usa `"announce"` como valor predeterminado cuando existe suficiente información de destino. -- `channel`: reemplazo de canal para entrega `announce`. `"last"` reutiliza el último canal de entrega conocido. -- `to`: destino explícito de `announce` o URL de Webhook. Obligatorio para modo Webhook. -- `accountId`: reemplazo opcional de cuenta para la entrega. -- `delivery.failureDestination` por trabajo reemplaza este valor predeterminado global. -- Cuando no hay un destino de fallo global ni por trabajo, los trabajos que ya entregan mediante `announce` recurren a ese destino principal de announce en caso de fallo. -- `delivery.failureDestination` solo es compatible con trabajos `sessionTarget="isolated"` salvo que el `delivery.mode` principal del trabajo sea `"webhook"`. +- `mode`: `"announce"` o `"webhook"`; usa `"announce"` por defecto cuando existen suficientes datos de destino. +- `channel`: sobrescritura de canal para entrega `announce`. `"last"` reutiliza el último canal de entrega conocido. +- `to`: destino explícito de `announce` o URL de Webhook. Obligatorio para modo webhook. +- `accountId`: sobrescritura opcional de cuenta para la entrega. +- `delivery.failureDestination` por trabajo sobrescribe este valor predeterminado global. +- Cuando no se establece ningún destino de fallo ni global ni por trabajo, los trabajos que ya entregan mediante `announce` vuelven a ese destino principal de `announce` en caso de fallo. +- `delivery.failureDestination` solo es compatible con trabajos `sessionTarget="isolated"` a menos que el `delivery.mode` principal del trabajo sea `"webhook"`. -Consulte [Trabajos Cron](/es/automation/cron-jobs). Las ejecuciones aisladas de Cron se rastrean como [tareas en segundo plano](/es/automation/tasks). +Consulta [Trabajos Cron](/es/automation/cron-jobs). Las ejecuciones Cron aisladas se registran como [tareas en segundo plano](/es/automation/tasks). --- @@ -3831,31 +3814,31 @@ Marcadores de posición de plantilla expandidos en `tools.media.models[].args`: | Variable | Descripción | | ------------------ | ------------------------------------------------- | | `{{Body}}` | Cuerpo completo del mensaje entrante | -| `{{RawBody}}` | Cuerpo sin procesar (sin envoltorios de historial/remitente) | -| `{{BodyStripped}}` | Cuerpo con las menciones de grupo eliminadas | +| `{{RawBody}}` | Cuerpo sin procesar (sin wrappers de historial/remitente) | +| `{{BodyStripped}}` | Cuerpo con menciones de grupo eliminadas | | `{{From}}` | Identificador del remitente | | `{{To}}` | Identificador del destino | -| `{{MessageSid}}` | ID del mensaje del canal | +| `{{MessageSid}}` | Id del mensaje del canal | | `{{SessionId}}` | UUID de la sesión actual | | `{{IsNewSession}}` | `"true"` cuando se crea una sesión nueva | -| `{{MediaUrl}}` | Pseudo-URL de medios entrantes | +| `{{MediaUrl}}` | Pseudo-URL del medio entrante | | `{{MediaPath}}` | Ruta local del medio | | `{{MediaType}}` | Tipo de medio (image/audio/document/…) | | `{{Transcript}}` | Transcripción de audio | -| `{{Prompt}}` | Prompt de medios resuelto para entradas de CLI | -| `{{MaxChars}}` | Máximo de caracteres de salida resuelto para entradas de CLI | +| `{{Prompt}}` | Prompt de medios resuelto para entradas CLI | +| `{{MaxChars}}` | Máximo de caracteres de salida resuelto para entradas CLI | | `{{ChatType}}` | `"direct"` o `"group"` | -| `{{GroupSubject}}` | Asunto del grupo (best effort) | -| `{{GroupMembers}}` | Vista previa de miembros del grupo (best effort) | -| `{{SenderName}}` | Nombre visible del remitente (best effort) | -| `{{SenderE164}}` | Número de teléfono del remitente (best effort) | -| `{{Provider}}` | Indicio del proveedor (whatsapp, telegram, discord, etc.) | +| `{{GroupSubject}}` | Asunto del grupo (mejor esfuerzo) | +| `{{GroupMembers}}` | Vista previa de miembros del grupo (mejor esfuerzo) | +| `{{SenderName}}` | Nombre para mostrar del remitente (mejor esfuerzo) | +| `{{SenderE164}}` | Número de teléfono del remitente (mejor esfuerzo) | +| `{{Provider}}` | Pista del proveedor (whatsapp, telegram, discord, etc.) | --- ## Inclusiones de configuración (`$include`) -Divida la configuración en varios archivos: +Divide la configuración en varios archivos: ```json5 // ~/.openclaw/openclaw.json @@ -3871,12 +3854,12 @@ Divida la configuración en varios archivos: **Comportamiento de fusión:** - Archivo único: reemplaza el objeto contenedor. -- Arreglo de archivos: fusión profunda en orden (los posteriores reemplazan a los anteriores). -- Claves hermanas: se fusionan después de las inclusiones (reemplazan los valores incluidos). +- Arreglo de archivos: fusión profunda en orden (los posteriores sobrescriben a los anteriores). +- Claves hermanas: se fusionan después de las inclusiones (sobrescriben los valores incluidos). - Inclusiones anidadas: hasta 10 niveles de profundidad. -- Rutas: se resuelven relativas al archivo que incluye, pero deben permanecer dentro del directorio de configuración de nivel superior (`dirname` de `openclaw.json`). Se permiten formas absolutas/`../` solo cuando siguen resolviéndose dentro de ese límite. +- Rutas: se resuelven en relación con el archivo que incluye, pero deben permanecer dentro del directorio de configuración de nivel superior (`dirname` de `openclaw.json`). Las formas absolutas/`../` se permiten solo cuando siguen resolviéndose dentro de ese límite. - Errores: mensajes claros para archivos faltantes, errores de análisis e inclusiones circulares. --- -_Relacionado: [Configuration](/es/gateway/configuration) · [Ejemplos de configuración](/es/gateway/configuration-examples) · [Doctor](/es/gateway/doctor)_ +_Relacionado: [Configuración](/es/gateway/configuration) · [Ejemplos de configuración](/es/gateway/configuration-examples) · [Doctor](/es/gateway/doctor)_ diff --git a/docs/es/gateway/protocol.md b/docs/es/gateway/protocol.md index a5f93e346..fded9cf1e 100644 --- a/docs/es/gateway/protocol.md +++ b/docs/es/gateway/protocol.md @@ -1,32 +1,32 @@ --- read_when: - - Implementación o actualización de clientes WS del Gateway - - Depuración de incompatibilidades del protocolo o fallos de conexión + - Implementación o actualización de clientes WS de Gateway + - Depuración de discrepancias de protocolo o fallos de conexión - Regeneración del esquema/modelos del protocolo -summary: 'Protocolo WebSocket del Gateway: saludo inicial, tramas, control de versiones' -title: Protocolo Gateway +summary: 'Protocolo WebSocket de Gateway: handshake, tramas, control de versiones' +title: Protocolo de Gateway x-i18n: - generated_at: "2026-04-16T05:15:09Z" + generated_at: "2026-04-18T04:59:13Z" model: gpt-5.4 provider: openai - source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3 + source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41 source_path: gateway/protocol.md workflow: 15 --- -# Protocolo Gateway (WebSocket) +# Protocolo de Gateway (WebSocket) -El protocolo WS del Gateway es el **plano de control único + transporte de nodos** para +El protocolo WS de Gateway es el **único plano de control + transporte de nodos** para OpenClaw. Todos los clientes (CLI, interfaz web, app de macOS, nodos iOS/Android, -nodos sin interfaz) se conectan mediante WebSocket y declaran su **rol** + **alcance** en el -momento del saludo inicial. +nodos sin interfaz) se conectan por WebSocket y declaran su **rol** + **alcance** en el +momento del handshake. ## Transporte - WebSocket, tramas de texto con cargas útiles JSON. - La primera trama **debe** ser una solicitud `connect`. -## Saludo inicial (`connect`) +## Handshake (`connect`) Gateway → Cliente (desafío previo a la conexión): @@ -96,7 +96,21 @@ Gateway → Cliente: ``` `server`, `features`, `snapshot` y `policy` son obligatorios según el esquema -(`src/gateway/protocol/schema/frames.ts`). `auth` y `canvasHostUrl` son opcionales. +(`src/gateway/protocol/schema/frames.ts`). `canvasHostUrl` es opcional. `auth` +informa el rol/alcances negociados cuando están disponibles, e incluye `deviceToken` +cuando el gateway emite uno. + +Cuando no se emite ningún token de dispositivo, `hello-ok.auth` todavía puede informar los +permisos negociados: + +```json +{ + "auth": { + "role": "operator", + "scopes": ["operator.read", "operator.write"] + } +} +``` Cuando se emite un token de dispositivo, `hello-ok` también incluye: @@ -110,8 +124,8 @@ Cuando se emite un token de dispositivo, `hello-ok` también incluye: } ``` -Durante la transferencia de arranque confiable, `hello-ok.auth` también puede incluir -entradas de rol acotadas adicionales en `deviceTokens`: +Durante la transferencia de arranque confiable, `hello-ok.auth` también puede incluir entradas de rol +adicionales acotadas en `deviceTokens`: ```json { @@ -130,13 +144,12 @@ entradas de rol acotadas adicionales en `deviceTokens`: } ``` -Para el flujo integrado de arranque nodo/operador, el token principal del nodo mantiene -`scopes: []` y cualquier token de operador transferido sigue estando acotado a la lista -permitida del operador de arranque (`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). Las comprobaciones de alcance de arranque -siguen teniendo prefijo de rol: las entradas de operador solo satisfacen solicitudes de -operador, y los roles que no son de operador siguen necesitando alcances bajo el prefijo -de su propio rol. +Para el flujo de arranque integrado de nodo/operador, el token principal del nodo sigue siendo +`scopes: []` y cualquier token de operador transferido sigue acotado a la lista de permisos del operador +de arranque (`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). Las comprobaciones de alcance de arranque siguen con prefijo de rol: +las entradas de operador solo satisfacen solicitudes de operador, y los roles que no son de operador +siguen necesitando alcances bajo el prefijo de su propio rol. ### Ejemplo de nodo @@ -173,22 +186,22 @@ de su propio rol. } ``` -## Estructura de tramas +## Enmarcado - **Solicitud**: `{type:"req", id, method, params}` - **Respuesta**: `{type:"res", id, ok, payload|error}` - **Evento**: `{type:"event", event, payload, seq?, stateVersion?}` -Los métodos con efectos secundarios requieren **claves de idempotencia** (véase el esquema). +Los métodos con efectos secundarios requieren **claves de idempotencia** (ver esquema). ## Roles + alcances ### Roles -- `operator` = cliente del plano de control (CLI/interfaz de usuario/automatización). -- `node` = host de capacidades (camera/screen/canvas/system.run). +- `operator` = cliente del plano de control (CLI/UI/automatización). +- `node` = host de capacidades (`camera`/`screen`/`canvas`/`system.run`). -### Alcances (operator) +### Alcances (`operator`) Alcances comunes: @@ -202,69 +215,69 @@ Alcances comunes: `talk.config` con `includeSecrets: true` requiere `operator.talk.secrets` (o `operator.admin`). -Los métodos RPC del Gateway registrados por Plugin pueden solicitar su propio alcance de operador, pero -los prefijos reservados de administración del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, +Los métodos RPC de Gateway registrados por Plugin pueden solicitar su propio alcance de operador, pero +los prefijos administrativos centrales reservados (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) siempre se resuelven como `operator.admin`. -El alcance del método es solo la primera puerta de control. Algunos comandos con barra a los que se accede mediante -`chat.send` aplican comprobaciones más estrictas a nivel de comando además de eso. Por ejemplo, las escrituras persistentes de -`/config set` y `/config unset` requieren `operator.admin`. +El alcance del método es solo el primer filtro. Algunos comandos slash alcanzados mediante +`chat.send` aplican comprobaciones más estrictas a nivel de comando además de eso. Por ejemplo, las escrituras +persistentes de `/config set` y `/config unset` requieren `operator.admin`. -`node.pair.approve` también tiene una comprobación adicional de alcance en el momento de aprobación además del +`node.pair.approve` también tiene una comprobación adicional de alcance en el momento de la aprobación además del alcance base del método: - solicitudes sin comando: `operator.pairing` -- solicitudes con comandos de nodo que no son exec: `operator.pairing` + `operator.write` +- solicitudes con comandos de nodo que no son `exec`: `operator.pairing` + `operator.write` - solicitudes que incluyen `system.run`, `system.run.prepare` o `system.which`: `operator.pairing` + `operator.admin` -### Capacidades/comandos/permisos (node) +### `caps`/`commands`/`permissions` (`node`) -Los nodos declaran capacidades reclamadas en el momento de conectarse: +Los nodos declaran reclamaciones de capacidad en el momento de conectarse: -- `caps`: categorías de capacidades de alto nivel. -- `commands`: lista permitida de comandos para `invoke`. -- `permissions`: controles detallados (por ejemplo, `screen.record`, `camera.capture`). +- `caps`: categorías de capacidad de alto nivel. +- `commands`: lista permitida de comandos para invocación. +- `permissions`: controles granulares (por ejemplo, `screen.record`, `camera.capture`). -El Gateway las trata como **reclamaciones** y aplica listas permitidas del lado del servidor. +Gateway los trata como **reclamaciones** y aplica listas permitidas del lado del servidor. ## Presencia -- `system-presence` devuelve entradas indexadas por identidad del dispositivo. -- Las entradas de presencia incluyen `deviceId`, `roles` y `scopes` para que las interfaces puedan mostrar una sola fila por dispositivo - incluso cuando se conecta como **operator** y **node** al mismo tiempo. +- `system-presence` devuelve entradas indexadas por identidad de dispositivo. +- Las entradas de presencia incluyen `deviceId`, `roles` y `scopes` para que las UI puedan mostrar una sola fila por dispositivo + incluso cuando se conecta tanto como **operator** como **node**. ## Familias comunes de métodos RPC Esta página no es un volcado completo generado, pero la superficie WS pública es más amplia -que los ejemplos de saludo inicial/autenticación anteriores. Estas son las principales familias de métodos que el +que los ejemplos de handshake/autenticación anteriores. Estas son las principales familias de métodos que Gateway expone hoy. -`hello-ok.features.methods` es una lista de descubrimiento conservadora construida a partir de +`hello-ok.features.methods` es una lista conservadora de descubrimiento construida a partir de `src/gateway/server-methods-list.ts` más las exportaciones de métodos de plugins/canales cargados. -Trátela como descubrimiento de funcionalidades, no como un volcado generado de cada helper invocable +Trátela como descubrimiento de funciones, no como un volcado generado de cada helper invocable implementado en `src/gateway/server-methods/*.ts`. ### Sistema e identidad -- `health` devuelve la instantánea de estado del Gateway almacenada en caché o recién sondeada. -- `status` devuelve el resumen del Gateway estilo `/status`; los campos sensibles - se incluyen solo para clientes operator con alcance de administrador. -- `gateway.identity.get` devuelve la identidad del dispositivo Gateway usada por los flujos - de retransmisión y emparejamiento. -- `system-presence` devuelve la instantánea de presencia actual de los dispositivos - operator/node conectados. +- `health` devuelve la instantánea de estado del gateway almacenada en caché o recién sondeada. +- `status` devuelve el resumen del gateway al estilo `/status`; los campos sensibles se + incluyen solo para clientes `operator` con alcance de administrador. +- `gateway.identity.get` devuelve la identidad del dispositivo del gateway usada por los flujos de relay y + emparejamiento. +- `system-presence` devuelve la instantánea de presencia actual para los dispositivos + `operator`/`node` conectados. - `system-event` agrega un evento del sistema y puede actualizar/transmitir el contexto de presencia. - `last-heartbeat` devuelve el evento Heartbeat persistido más reciente. -- `set-heartbeats` activa o desactiva el procesamiento de Heartbeat en el Gateway. +- `set-heartbeats` activa o desactiva el procesamiento de Heartbeat en el gateway. ### Modelos y uso - `models.list` devuelve el catálogo de modelos permitido en tiempo de ejecución. - `usage.status` devuelve resúmenes de ventanas de uso/restante de cuota del proveedor. - `usage.cost` devuelve resúmenes agregados de uso de costo para un intervalo de fechas. -- `doctor.memory.status` devuelve la preparación de memoria vectorial / incrustación para el +- `doctor.memory.status` devuelve la preparación de memoria vectorial/embeddings para el espacio de trabajo del agente predeterminado activo. - `sessions.usage` devuelve resúmenes de uso por sesión. - `sessions.usage.timeseries` devuelve series temporales de uso para una sesión. @@ -272,108 +285,107 @@ implementado en `src/gateway/server-methods/*.ts`. ### Canales y helpers de inicio de sesión -- `channels.status` devuelve resúmenes de estado de canales/plugins integrados y empaquetados. -- `channels.logout` cierra la sesión de un canal/cuenta específico donde el canal +- `channels.status` devuelve resúmenes de estado de canales/plugins integrados + empaquetados. +- `channels.logout` cierra la sesión de un canal/cuenta específicos cuando el canal admite cierre de sesión. -- `web.login.start` inicia un flujo de inicio de sesión QR/web para el proveedor de canal web +- `web.login.start` inicia un flujo de inicio de sesión por QR/web para el proveedor del canal web actual compatible con QR. -- `web.login.wait` espera a que ese flujo de inicio de sesión QR/web se complete e inicia el - canal si tiene éxito. +- `web.login.wait` espera a que ese flujo de inicio de sesión por QR/web finalice y arranca el + canal si se completa con éxito. - `push.test` envía una notificación push APNs de prueba a un nodo iOS registrado. -- `voicewake.get` devuelve los activadores de palabra de activación almacenados. -- `voicewake.set` actualiza los activadores de palabra de activación y transmite el cambio. +- `voicewake.get` devuelve los disparadores de palabras de activación almacenados. +- `voicewake.set` actualiza los disparadores de palabras de activación y transmite el cambio. ### Mensajería y registros - `send` es el RPC de entrega saliente directa para envíos dirigidos a canal/cuenta/hilo fuera del ejecutor de chat. -- `logs.tail` devuelve el final del registro de archivos configurado del Gateway con cursor/límite y - controles máximos de bytes. +- `logs.tail` devuelve la cola del archivo de registros configurado del gateway con cursor/límite y + controles de bytes máximos. ### Talk y TTS -- `talk.config` devuelve la carga útil efectiva de configuración de Talk; `includeSecrets` +- `talk.config` devuelve la carga útil de configuración efectiva de Talk; `includeSecrets` requiere `operator.talk.secrets` (o `operator.admin`). -- `talk.mode` establece/transmite el estado actual del modo Talk para clientes - de WebChat/Control UI. -- `talk.speak` sintetiza voz mediante el proveedor de voz Talk activo. +- `talk.mode` establece/transmite el estado actual del modo Talk para los clientes de WebChat/Control UI. +- `talk.speak` sintetiza voz a través del proveedor de voz activo de Talk. - `tts.status` devuelve el estado de activación de TTS, el proveedor activo, los proveedores de respaldo y el estado de configuración del proveedor. - `tts.providers` devuelve el inventario visible de proveedores TTS. -- `tts.enable` y `tts.disable` activan o desactivan el estado de preferencias de TTS. +- `tts.enable` y `tts.disable` activan y desactivan el estado de preferencias de TTS. - `tts.setProvider` actualiza el proveedor TTS preferido. - `tts.convert` ejecuta una conversión puntual de texto a voz. ### Secretos, configuración, actualización y asistente -- `secrets.reload` vuelve a resolver las SecretRef activas e intercambia el estado de secretos en tiempo de ejecución +- `secrets.reload` vuelve a resolver los SecretRef activos e intercambia el estado de secretos en tiempo de ejecución solo si todo se completa correctamente. -- `secrets.resolve` resuelve asignaciones de secretos dirigidas a comandos para un conjunto - específico de comando/destino. +- `secrets.resolve` resuelve asignaciones de secretos dirigidas a comandos para un conjunto específico + de comandos/objetivos. - `config.get` devuelve la instantánea y el hash de la configuración actual. - `config.set` escribe una carga útil de configuración validada. -- `config.patch` fusiona una actualización parcial de configuración. -- `config.apply` valida y reemplaza la carga útil completa de configuración. +- `config.patch` fusiona una actualización parcial de la configuración. +- `config.apply` valida y reemplaza la carga útil de configuración completa. - `config.schema` devuelve la carga útil del esquema de configuración en vivo usada por Control UI y - herramientas CLI: esquema, `uiHints`, versión y metadatos de generación, incluidos - metadatos de esquema de plugins + canales cuando el runtime puede cargarlos. El esquema + las herramientas CLI: esquema, `uiHints`, versión y metadatos de generación, incluidos + metadatos de esquema de plugins + canales cuando el entorno de ejecución puede cargarlos. El esquema incluye metadatos de campo `title` / `description` derivados de las mismas etiquetas - y texto de ayuda usados por la interfaz, incluidas ramas anidadas de objeto, comodín, - elemento de matriz y composición `anyOf` / `oneOf` / `allOf` cuando existe documentación - de campo coincidente. -- `config.schema.lookup` devuelve una carga útil de búsqueda con alcance a ruta para una ruta de configuración: - ruta normalizada, un nodo de esquema superficial, la sugerencia coincidente + `hintPath`, y - resúmenes inmediatos de elementos secundarios para exploración en interfaz/CLI. - - Los nodos de esquema de búsqueda conservan la documentación orientada al usuario y los campos de validación comunes: + y el mismo texto de ayuda usados por la UI, incluidas las ramas anidadas de composición de objetos, comodines, + elementos de array y `anyOf` / `oneOf` / `allOf` cuando existe documentación de campo + coincidente. +- `config.schema.lookup` devuelve una carga útil de búsqueda acotada a ruta para una ruta de configuración: + ruta normalizada, un nodo superficial del esquema, `hint` + `hintPath` coincidentes y + resúmenes inmediatos de hijos para la exploración detallada en UI/CLI. + - Los nodos de esquema de búsqueda conservan la documentación orientada al usuario y los campos comunes de validación: `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, - límites numéricos/de cadena/de matriz/de objeto, y marcas booleanas como + límites numéricos/de cadenas/de arrays/de objetos y banderas booleanas como `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`. - - Los resúmenes de elementos secundarios exponen `key`, `path` normalizada, `type`, `required`, + - Los resúmenes de hijos exponen `key`, `path` normalizada, `type`, `required`, `hasChildren`, además de `hint` / `hintPath` coincidentes. -- `update.run` ejecuta el flujo de actualización del Gateway y programa un reinicio solo cuando - la actualización en sí se completó correctamente. +- `update.run` ejecuta el flujo de actualización del gateway y programa un reinicio solo cuando + la propia actualización se completó correctamente. - `wizard.start`, `wizard.next`, `wizard.status` y `wizard.cancel` exponen el - asistente de incorporación mediante WS RPC. + asistente de incorporación a través de WS RPC. ### Familias principales existentes -#### Helpers de agente y espacio de trabajo +#### Agente y helpers de espacio de trabajo -- `agents.list` devuelve entradas de agentes configuradas. -- `agents.create`, `agents.update` y `agents.delete` administran registros de agentes y +- `agents.list` devuelve las entradas de agente configuradas. +- `agents.create`, `agents.update` y `agents.delete` administran los registros de agentes y la conexión del espacio de trabajo. - `agents.files.list`, `agents.files.get` y `agents.files.set` administran los archivos del espacio de trabajo de arranque expuestos para un agente. - `agent.identity.get` devuelve la identidad efectiva del asistente para un agente o sesión. -- `agent.wait` espera a que una ejecución finalice y devuelve la instantánea terminal cuando +- `agent.wait` espera a que una ejecución termine y devuelve la instantánea terminal cuando está disponible. #### Control de sesión -- `sessions.list` devuelve el índice actual de sesiones. +- `sessions.list` devuelve el índice de sesión actual. - `sessions.subscribe` y `sessions.unsubscribe` activan o desactivan las suscripciones a eventos de cambio de sesión para el cliente WS actual. - `sessions.messages.subscribe` y `sessions.messages.unsubscribe` activan o desactivan - las suscripciones a eventos de transcripción/mensajes para una sesión. + las suscripciones a eventos de transcripción/mensaje para una sesión. - `sessions.preview` devuelve vistas previas acotadas de la transcripción para claves de sesión específicas. -- `sessions.resolve` resuelve o canoniza un destino de sesión. +- `sessions.resolve` resuelve o canonicaliza un destino de sesión. - `sessions.create` crea una nueva entrada de sesión. - `sessions.send` envía un mensaje a una sesión existente. - `sessions.steer` es la variante de interrumpir y redirigir para una sesión activa. - `sessions.abort` aborta el trabajo activo de una sesión. -- `sessions.patch` actualiza metadatos/sobrescrituras de la sesión. -- `sessions.reset`, `sessions.delete` y `sessions.compact` realizan mantenimiento de - sesión. +- `sessions.patch` actualiza metadatos/anulaciones de la sesión. +- `sessions.reset`, `sessions.delete` y `sessions.compact` realizan tareas de + mantenimiento de la sesión. - `sessions.get` devuelve la fila completa de la sesión almacenada. -- la ejecución de chat sigue usando `chat.history`, `chat.send`, `chat.abort` y +- la ejecución del chat sigue usando `chat.history`, `chat.send`, `chat.abort` y `chat.inject`. -- `chat.history` está normalizado para visualización para clientes de UI: las etiquetas de directivas en línea se - eliminan del texto visible, las cargas útiles XML de llamadas a herramientas en texto plano (incluidas +- `chat.history` está normalizado para visualización para clientes UI: las etiquetas de directiva en línea se + eliminan del texto visible, las cargas útiles XML de llamada de herramienta en texto plano (incluidas `...`, `...`, - `...`, `...`, y - bloques truncados de llamadas a herramientas) y los tokens de control del modelo filtrados en ASCII/ancho completo + `...`, `...` y + bloques de llamada de herramienta truncados) y los tokens de control del modelo filtrados en ASCII/ancho completo se eliminan, las filas del asistente compuestas únicamente por tokens silenciosos como `NO_REPLY` / `no_reply` exactos se omiten, y las filas sobredimensionadas pueden reemplazarse por marcadores de posición. @@ -382,8 +394,8 @@ implementado en `src/gateway/server-methods/*.ts`. - `device.pair.list` devuelve los dispositivos emparejados pendientes y aprobados. - `device.pair.approve`, `device.pair.reject` y `device.pair.remove` administran los registros de emparejamiento de dispositivos. -- `device.token.rotate` rota un token de dispositivo emparejado dentro de los límites - aprobados de su rol y alcances. +- `device.token.rotate` rota un token de dispositivo emparejado dentro de sus límites aprobados de rol + y alcance. - `device.token.revoke` revoca un token de dispositivo emparejado. #### Emparejamiento de nodos, invocación y trabajo pendiente @@ -392,26 +404,26 @@ implementado en `src/gateway/server-methods/*.ts`. `node.pair.reject` y `node.pair.verify` cubren el emparejamiento de nodos y la verificación de arranque. - `node.list` y `node.describe` devuelven el estado de nodos conocidos/conectados. -- `node.rename` actualiza la etiqueta de un nodo emparejado. +- `node.rename` actualiza una etiqueta de nodo emparejado. - `node.invoke` reenvía un comando a un nodo conectado. - `node.invoke.result` devuelve el resultado de una solicitud de invocación. -- `node.event` transporta eventos originados en el nodo de vuelta al Gateway. -- `node.canvas.capability.refresh` actualiza tokens de capacidad de canvas con alcance limitado. +- `node.event` transporta eventos originados en el nodo de vuelta al gateway. +- `node.canvas.capability.refresh` actualiza tokens acotados de capacidad de canvas. - `node.pending.pull` y `node.pending.ack` son las API de cola para nodos conectados. - `node.pending.enqueue` y `node.pending.drain` administran trabajo pendiente duradero - para nodos sin conexión/desconectados. + para nodos desconectados o fuera de línea. #### Familias de aprobación - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` y - `exec.approval.resolve` cubren solicitudes puntuales de aprobación de exec además de - búsqueda/repetición de aprobaciones pendientes. -- `exec.approval.waitDecision` espera una aprobación exec pendiente y devuelve - la decisión final (o `null` por tiempo de espera agotado). + `exec.approval.resolve` cubren solicitudes puntuales de aprobación de `exec` más + la búsqueda/repetición de aprobaciones pendientes. +- `exec.approval.waitDecision` espera una aprobación `exec` pendiente y devuelve + la decisión final (o `null` en caso de tiempo de espera agotado). - `exec.approvals.get` y `exec.approvals.set` administran instantáneas de la política - de aprobación exec del Gateway. -- `exec.approvals.node.get` y `exec.approvals.node.set` administran la política local del nodo para exec - mediante comandos de retransmisión del nodo. + de aprobación `exec` del gateway. +- `exec.approvals.node.get` y `exec.approvals.node.set` administran la política local de aprobación `exec` + del nodo mediante comandos de relay del nodo. - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` y `plugin.approval.resolve` cubren flujos de aprobación definidos por Plugin. @@ -426,46 +438,44 @@ implementado en `src/gateway/server-methods/*.ts`. ### Familias comunes de eventos -- `chat`: actualizaciones de chat de UI como `chat.inject` y otros eventos de chat - solo de transcripción. +- `chat`: actualizaciones de chat de la UI, como `chat.inject` y otros + eventos de chat solo de transcripción. - `session.message` y `session.tool`: actualizaciones de transcripción/flujo de eventos para una sesión suscrita. -- `sessions.changed`: cambió el índice de sesiones o los metadatos. -- `presence`: actualizaciones de instantáneas de presencia del sistema. -- `tick`: evento periódico de keepalive/vivacidad. -- `health`: actualización de instantánea de estado del Gateway. +- `sessions.changed`: cambió el índice de sesión o sus metadatos. +- `presence`: actualizaciones de la instantánea de presencia del sistema. +- `tick`: evento periódico de keepalive / actividad. +- `health`: actualización de la instantánea de estado del gateway. - `heartbeat`: actualización del flujo de eventos Heartbeat. -- `cron`: evento de cambio de ejecución/trabajo Cron. -- `shutdown`: notificación de apagado del Gateway. +- `cron`: evento de cambio de ejecución/trabajo de Cron. +- `shutdown`: notificación de apagado del gateway. - `node.pair.requested` / `node.pair.resolved`: ciclo de vida del emparejamiento de nodos. - `node.invoke.request`: difusión de solicitud de invocación de nodo. - `device.pair.requested` / `device.pair.resolved`: ciclo de vida del dispositivo emparejado. -- `voicewake.changed`: cambió la configuración de activadores de palabra de activación. -- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida de la - aprobación exec. -- `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida de la - aprobación de Plugin. +- `voicewake.changed`: cambió la configuración de disparadores de palabra de activación. +- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida de aprobación de `exec`. +- `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida de aprobación de Plugin. ### Métodos helper de nodo - Los nodos pueden llamar a `skills.bins` para obtener la lista actual de ejecutables de Skills para comprobaciones de permiso automático. -### Métodos helper de operator +### Métodos helper de operador -- Los operadores pueden llamar a `commands.list` (`operator.read`) para obtener el inventario - de comandos en tiempo de ejecución de un agente. +- Los operadores pueden llamar a `commands.list` (`operator.read`) para obtener el inventario de comandos en tiempo de ejecución para un + agente. - `agentId` es opcional; omítalo para leer el espacio de trabajo del agente predeterminado. - `scope` controla a qué superficie apunta el `name` principal: - - `text` devuelve el token principal del comando de texto sin la `/` inicial - - `native` y la ruta predeterminada `both` devuelven nombres nativos sensibles al proveedor + - `text` devuelve el token principal de comando de texto sin la `/` inicial + - `native` y la ruta predeterminada `both` devuelven nombres nativos compatibles con proveedor cuando están disponibles - - `textAliases` contiene alias exactos con barra como `/model` y `/m`. - - `nativeName` contiene el nombre de comando nativo sensible al proveedor cuando existe. - - `provider` es opcional y solo afecta al nombre nativo además de la disponibilidad de comandos - nativos del Plugin. - - `includeArgs=false` omite metadatos de argumentos serializados de la respuesta. -- Los operadores pueden llamar a `tools.catalog` (`operator.read`) para obtener el catálogo de herramientas en tiempo de ejecución de un + - `textAliases` contiene alias slash exactos como `/model` y `/m`. + - `nativeName` contiene el nombre de comando nativo compatible con el proveedor cuando existe. + - `provider` es opcional y solo afecta el nombre nativo más la disponibilidad de comandos nativos + del Plugin. + - `includeArgs=false` omite del resultado los metadatos serializados de argumentos. +- Los operadores pueden llamar a `tools.catalog` (`operator.read`) para obtener el catálogo de herramientas en tiempo de ejecución para un agente. La respuesta incluye herramientas agrupadas y metadatos de procedencia: - `source`: `core` o `plugin` - `pluginId`: propietario del Plugin cuando `source="plugin"` @@ -473,10 +483,10 @@ implementado en `src/gateway/server-methods/*.ts`. - Los operadores pueden llamar a `tools.effective` (`operator.read`) para obtener el inventario efectivo de herramientas en tiempo de ejecución para una sesión. - `sessionKey` es obligatorio. - - El Gateway deriva el contexto confiable de tiempo de ejecución del lado del servidor a partir de la sesión en lugar de aceptar - autenticación o contexto de entrega proporcionados por el llamador. - - La respuesta tiene alcance de sesión y refleja lo que la conversación activa puede usar ahora mismo, - incluidas herramientas core, de Plugin y de canal. + - El gateway deriva el contexto confiable de tiempo de ejecución del lado del servidor a partir de la sesión en lugar de aceptar + autenticación o contexto de entrega proporcionados por quien llama. + - La respuesta está acotada a la sesión y refleja lo que la conversación activa puede usar en este momento, + incluidas herramientas de núcleo, Plugin y canal. - Los operadores pueden llamar a `skills.status` (`operator.read`) para obtener el inventario visible de Skills para un agente. - `agentId` es opcional; omítalo para leer el espacio de trabajo del agente predeterminado. @@ -487,151 +497,152 @@ implementado en `src/gateway/server-methods/*.ts`. - Los operadores pueden llamar a `skills.install` (`operator.admin`) en dos modos: - Modo ClawHub: `{ source: "clawhub", slug, version?, force? }` instala una carpeta de skill en el directorio `skills/` del espacio de trabajo del agente predeterminado. - - Modo instalador del Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - ejecuta una acción declarada `metadata.openclaw.install` en el host del Gateway. + - Modo instalador de gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` + ejecuta una acción declarada `metadata.openclaw.install` en el host del gateway. - Los operadores pueden llamar a `skills.update` (`operator.admin`) en dos modos: - - El modo ClawHub actualiza un slug rastreado o todas las instalaciones rastreadas de ClawHub en + - El modo ClawHub actualiza un `slug` rastreado o todas las instalaciones rastreadas de ClawHub en el espacio de trabajo del agente predeterminado. - - El modo de configuración aplica un parche a valores `skills.entries.` como `enabled`, + - El modo configuración aplica un parche a valores `skills.entries.` como `enabled`, `apiKey` y `env`. -## Aprobaciones exec +## Aprobaciones de `exec` -- Cuando una solicitud exec necesita aprobación, el Gateway difunde `exec.approval.requested`. -- Los clientes operator resuelven llamando a `exec.approval.resolve` (requiere alcance `operator.approvals`). +- Cuando una solicitud `exec` necesita aprobación, el gateway difunde `exec.approval.requested`. +- Los clientes operador resuelven llamando a `exec.approval.resolve` (requiere alcance `operator.approvals`). - Para `host=node`, `exec.approval.request` debe incluir `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadatos de sesión canónicos). Las solicitudes sin `systemRunPlan` se rechazan. - Después de la aprobación, las llamadas reenviadas `node.invoke system.run` reutilizan ese - `systemRunPlan` canónico como el contexto autoritativo de comando/cwd/sesión. -- Si un llamador modifica `command`, `rawCommand`, `cwd`, `agentId` o - `sessionKey` entre prepare y el reenvío final aprobado de `system.run`, el - Gateway rechaza la ejecución en lugar de confiar en la carga útil modificada. + `systemRunPlan` canónico como contexto autoritativo de comando/cwd/sesión. +- Si quien llama modifica `command`, `rawCommand`, `cwd`, `agentId` o + `sessionKey` entre `prepare` y el reenvío final aprobado de `system.run`, el + gateway rechaza la ejecución en lugar de confiar en la carga útil modificada. ## Respaldo de entrega del agente - Las solicitudes `agent` pueden incluir `deliver=true` para solicitar entrega saliente. -- `bestEffortDeliver=false` mantiene el comportamiento estricto: los destinos de entrega no resueltos o solo internos devuelven `INVALID_REQUEST`. -- `bestEffortDeliver=true` permite recurrir a ejecución solo de sesión cuando no se puede resolver ninguna ruta de entrega externa (por ejemplo, sesiones internas/de webchat o configuraciones ambiguas de múltiples canales). +- `bestEffortDeliver=false` mantiene un comportamiento estricto: los destinos de entrega no resueltos o solo internos devuelven `INVALID_REQUEST`. +- `bestEffortDeliver=true` permite recurrir a ejecución solo de sesión cuando no puede resolverse ninguna ruta externa entregable (por ejemplo, sesiones internas/webchat o configuraciones ambiguas de múltiples canales). ## Control de versiones -- `PROTOCOL_VERSION` vive en `src/gateway/protocol/schema/protocol-schemas.ts`. -- Los clientes envían `minProtocol` + `maxProtocol`; el servidor rechaza incompatibilidades. +- `PROTOCOL_VERSION` se encuentra en `src/gateway/protocol/schema/protocol-schemas.ts`. +- Los clientes envían `minProtocol` + `maxProtocol`; el servidor rechaza discrepancias. - Los esquemas + modelos se generan a partir de definiciones TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` -### Constantes de cliente +### Constantes del cliente El cliente de referencia en `src/gateway/client.ts` usa estos valores predeterminados. Los valores son estables en todo el protocolo v3 y son la línea base esperada para clientes de terceros. -| Constante | Predeterminado | Fuente | +| Constant | Default | Source | | ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | -| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | -| Tiempo de espera de solicitud (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | -| Tiempo de espera previo a autenticación / desafío de conexión | `10_000` ms | `src/gateway/handshake-timeouts.ts` (límite `250`–`10_000`) | -| Retroceso inicial de reconexión | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | -| Retroceso máximo de reconexión | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | -| Límite de reintento rápido después de cierre por token de dispositivo | `250` ms | `src/gateway/client.ts` | -| Gracia de parada forzada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | -| Tiempo de espera predeterminado de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | -| Intervalo `tick` predeterminado (antes de `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | -| Cierre por tiempo de espera de `tick` | código `4000` cuando el silencio supera `tickIntervalMs * 2` | `src/gateway/client.ts` | -| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | +| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | +| Tiempo de espera de solicitud (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | +| Tiempo de espera de preautorización / desafío de conexión | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) | +| Retroceso inicial de reconexión | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | +| Retroceso máximo de reconexión | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | +| Límite de reintento rápido tras cierre por token de dispositivo | `250` ms | `src/gateway/client.ts` | +| Período de gracia de parada forzada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | +| Tiempo de espera predeterminado de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | +| Intervalo `tick` predeterminado (antes de `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | +| Cierre por tiempo de espera de `tick` | código `4000` cuando el silencio supera `tickIntervalMs * 2` | `src/gateway/client.ts` | +| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | El servidor anuncia los valores efectivos `policy.tickIntervalMs`, `policy.maxPayload` y `policy.maxBufferedBytes` en `hello-ok`; los clientes deben respetar esos valores -en lugar de los predeterminados previos al saludo inicial. +en lugar de los valores predeterminados previos al handshake. ## Autenticación -- La autenticación del Gateway con secreto compartido usa `connect.params.auth.token` o +- La autenticación del gateway con secreto compartido usa `connect.params.auth.token` o `connect.params.auth.password`, según el modo de autenticación configurado. - Los modos con identidad, como Tailscale Serve - (`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"` sin loopback, - satisfacen la comprobación de autenticación de conexión a partir de los + (`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"` + en interfaces que no son de loopback, satisfacen la comprobación de autenticación de `connect` a partir de encabezados de la solicitud en lugar de `connect.params.auth.*`. -- `gateway.auth.mode: "none"` para ingreso privado omite por completo la autenticación de conexión con secreto compartido; no exponga ese modo en ingresos públicos/no confiables. -- Después del emparejamiento, el Gateway emite un **token de dispositivo** con alcance limitado al rol + alcances +- `gateway.auth.mode: "none"` para ingreso privado omite por completo la autenticación `connect` con secreto compartido; + no exponga ese modo en ingresos públicos o no confiables. +- Después del emparejamiento, Gateway emite un **token de dispositivo** limitado al rol + alcances de la conexión. Se devuelve en `hello-ok.auth.deviceToken` y el cliente debe persistirlo para conexiones futuras. - Los clientes deben persistir el `hello-ok.auth.deviceToken` principal después de cualquier - conexión satisfactoria. -- Al reconectar con ese token de dispositivo **almacenado**, también se debe reutilizar el conjunto de alcances - aprobados almacenado para ese token. Esto conserva el acceso de lectura/sondeo/estado - que ya se había concedido y evita reducir silenciosamente las reconexiones a un - alcance implícito más limitado de solo administrador. -- Ensamblaje de autenticación de conexión del lado del cliente (`selectConnectAuth` en + conexión exitosa. +- Al reconectarse con ese token de dispositivo **almacenado**, también se debe reutilizar el conjunto de alcances aprobados + almacenado para ese token. Esto preserva el acceso de lectura/sondeo/estado + que ya se concedió y evita que las reconexiones colapsen silenciosamente a un + alcance implícito más estrecho de solo administrador. +- Ensamblado de autenticación `connect` del lado del cliente (`selectConnectAuth` en `src/gateway/client.ts`): - `auth.password` es ortogonal y siempre se reenvía cuando está establecido. - - `auth.token` se completa en orden de prioridad: primero un token compartido explícito, - luego un `deviceToken` explícito, y después un token por dispositivo almacenado (indexado por + - `auth.token` se completa en este orden de prioridad: primero el token compartido explícito, + luego un `deviceToken` explícito y, después, un token almacenado por dispositivo (indexado por `deviceId` + `role`). - `auth.bootstrapToken` se envía solo cuando ninguna de las opciones anteriores resolvió un `auth.token`. Un token compartido o cualquier token de dispositivo resuelto lo suprime. - La autopromoción de un token de dispositivo almacenado en el reintento puntual - `AUTH_TOKEN_MISMATCH` está restringida a **endpoints confiables únicamente** — - loopback, o `wss://` con `tlsFingerprint` fijado. Un `wss://` público - sin fijación no cumple ese requisito. + `AUTH_TOKEN_MISMATCH` está restringida **solo a endpoints confiables**: + loopback, o `wss://` con `tlsFingerprint` fijado. `wss://` público + sin fijación no califica. - Las entradas adicionales `hello-ok.auth.deviceTokens` son tokens de transferencia de arranque. - Persístalos solo cuando la conexión haya usado autenticación de arranque sobre un transporte confiable + Persístalos solo cuando la conexión haya usado autenticación de arranque en un transporte confiable como `wss://` o loopback/emparejamiento local. - Si un cliente proporciona un `deviceToken` **explícito** o `scopes` explícitos, ese - conjunto de alcances solicitado por el llamador sigue siendo el autoritativo; los alcances en caché solo - se reutilizan cuando el cliente está reutilizando el token por dispositivo almacenado. -- Los tokens de dispositivo se pueden rotar/revocar mediante `device.token.rotate` y - `device.token.revoke` (requiere el alcance `operator.pairing`). -- La emisión/rotación de tokens sigue limitada al conjunto de roles aprobados registrado en - la entrada de emparejamiento de ese dispositivo; rotar un token no puede expandir el dispositivo a un + conjunto de alcances solicitado por el llamador sigue siendo autoritativo; los alcances en caché solo + se reutilizan cuando el cliente está reutilizando el token almacenado por dispositivo. +- Los tokens de dispositivo pueden rotarse/revocarse mediante `device.token.rotate` y + `device.token.revoke` (requiere alcance `operator.pairing`). +- La emisión/rotación de tokens se mantiene limitada al conjunto de roles aprobado registrado en + la entrada de emparejamiento de ese dispositivo; rotar un token no puede ampliar el dispositivo a un rol que la aprobación de emparejamiento nunca concedió. -- Para las sesiones de tokens de dispositivos emparejados, la administración del dispositivo tiene alcance propio salvo que el - llamador también tenga `operator.admin`: los llamadores que no son administradores solo pueden eliminar/revocar/rotar +- Para sesiones de token de dispositivo emparejado, la administración del dispositivo está autocontenida salvo que el + llamador también tenga `operator.admin`: quienes no son administradores solo pueden quitar/revocar/rotar su **propia** entrada de dispositivo. -- `device.token.rotate` también comprueba el conjunto solicitado de alcances de operador frente a los - alcances actuales de la sesión del llamador. Los llamadores que no son administradores no pueden rotar un token a - un conjunto más amplio de alcances de operador que el que ya poseen. -- Los fallos de autenticación incluyen `error.details.code` además de sugerencias de recuperación: +- `device.token.rotate` también verifica el conjunto solicitado de alcances de operador frente a los + alcances de la sesión actual del llamador. Quienes no son administradores no pueden rotar un token a + un conjunto de alcances de operador más amplio del que ya tienen. +- Los fallos de autenticación incluyen `error.details.code` más sugerencias de recuperación: - `error.details.canRetryWithDeviceToken` (booleano) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Comportamiento del cliente para `AUTH_TOKEN_MISMATCH`: - - Los clientes confiables pueden intentar un reintento limitado con un token por dispositivo en caché. - - Si ese reintento falla, los clientes deben detener los bucles automáticos de reconexión y mostrar orientación para que el operador actúe. + - Los clientes confiables pueden intentar un reintento acotado con un token almacenado por dispositivo. + - Si ese reintento falla, los clientes deben detener los bucles automáticos de reconexión y mostrar orientación de acción al operador. ## Identidad del dispositivo + emparejamiento -- Los nodos deben incluir una identidad estable de dispositivo (`device.id`) derivada de una - huella digital de par de claves. -- Los Gateways emiten tokens por dispositivo + rol. -- Las aprobaciones de emparejamiento son necesarias para nuevos ID de dispositivo, salvo que la aprobación automática local +- Los nodos deben incluir una identidad de dispositivo estable (`device.id`) derivada de la huella digital + de un par de claves. +- Los gateways emiten tokens por dispositivo + rol. +- Las aprobaciones de emparejamiento son necesarias para nuevos ID de dispositivo, a menos que la aprobación automática local esté habilitada. -- La aprobación automática de emparejamiento se centra en conexiones directas locales por loopback. -- OpenClaw también tiene una ruta estrecha de autoconexión local de backend/contenedor para - flujos helper confiables con secreto compartido. -- Las conexiones tailnet o LAN del mismo host siguen tratándose como remotas para el emparejamiento y +- La aprobación automática de emparejamiento se centra en conexiones directas de loopback local. +- OpenClaw también tiene una ruta estrecha de autoconexión local al backend/contenedor para + flujos auxiliares confiables con secreto compartido. +- Las conexiones tailnet o LAN del mismo host se siguen tratando como remotas para el emparejamiento y requieren aprobación. -- Todos los clientes WS deben incluir identidad `device` durante `connect` (operator + node). +- Todos los clientes WS deben incluir identidad `device` durante `connect` (`operator` + `node`). Control UI puede omitirla solo en estos modos: - `gateway.controlUi.allowInsecureAuth=true` para compatibilidad con HTTP inseguro solo en localhost. - - autenticación satisfactoria de operator de Control UI con `gateway.auth.mode: "trusted-proxy"`. - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (medida de emergencia, degradación grave de seguridad). + - autenticación exitosa de Control UI de operador con `gateway.auth.mode: "trusted-proxy"`. + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (medida extrema, degradación grave de seguridad). - Todas las conexiones deben firmar el nonce `connect.challenge` proporcionado por el servidor. -### Diagnósticos de migración de autenticación del dispositivo +### Diagnósticos de migración de autenticación de dispositivo -Para clientes heredados que siguen usando el comportamiento de firma previo al desafío, `connect` ahora devuelve +Para clientes heredados que todavía usan el comportamiento de firma previo al desafío, `connect` ahora devuelve códigos de detalle `DEVICE_AUTH_*` en `error.details.code` con un `error.details.reason` estable. Fallos comunes de migración: -| Mensaje | details.code | details.reason | Significado | +| Message | details.code | details.reason | Meaning | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | El cliente omitió `device.nonce` (o lo envió vacío). | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | El cliente firmó con un nonce obsoleto/incorrecto. | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La carga útil de la firma no coincide con la carga útil v2. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | La marca de tiempo firmada está fuera de la desviación permitida. | -| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` no coincide con la huella de la clave pública. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Falló el formato/canonización de la clave pública. | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | El cliente omitió `device.nonce` (o lo envió vacío). | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | El cliente firmó con un nonce obsoleto o incorrecto. | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La carga útil de la firma no coincide con la carga útil v2. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | La marca de tiempo firmada está fuera del desfase permitido. | +| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` no coincide con la huella digital de la clave pública. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | El formato/canonicalización de la clave pública falló. | Objetivo de la migración: @@ -641,16 +652,16 @@ Objetivo de la migración: - La carga útil de firma preferida es `v3`, que vincula `platform` y `deviceFamily` además de los campos de dispositivo/cliente/rol/alcances/token/nonce. - Las firmas heredadas `v2` siguen aceptándose por compatibilidad, pero la fijación de metadatos - de dispositivos emparejados sigue controlando la política de comandos al reconectar. + de dispositivos emparejados sigue controlando la política de comandos al reconectarse. ## TLS + fijación - TLS es compatible con conexiones WS. -- Los clientes pueden fijar opcionalmente la huella digital del certificado del Gateway (véase la configuración `gateway.tls` - además de `gateway.remote.tlsFingerprint` o la CLI `--tls-fingerprint`). +- Los clientes pueden fijar opcionalmente la huella digital del certificado del gateway (consulte la configuración `gateway.tls` + más `gateway.remote.tlsFingerprint` o la CLI `--tls-fingerprint`). ## Alcance -Este protocolo expone la **API completa del Gateway** (estado, canales, modelos, chat, +Este protocolo expone la **API completa del gateway** (estado, canales, modelos, chat, agente, sesiones, nodos, aprobaciones, etc.). La superficie exacta está definida por los esquemas TypeBox en `src/gateway/protocol/schema.ts`. diff --git a/docs/es/help/testing.md b/docs/es/help/testing.md index 722d27d62..6ce364cc2 100644 --- a/docs/es/help/testing.md +++ b/docs/es/help/testing.md @@ -2,27 +2,27 @@ read_when: - Ejecutar pruebas localmente o en CI - Agregar regresiones para errores de modelo/proveedor - - Depurar el comportamiento del Gateway + agente -summary: 'Kit de pruebas: suites unitarias/e2e/en vivo, ejecutores de Docker y qué cubre cada prueba' + - Depurar el comportamiento de Gateway + agente +summary: 'Kit de pruebas: suites unitarias/e2e/live, ejecutores de Docker y qué cubre cada prueba' title: Pruebas x-i18n: - generated_at: "2026-04-17T05:13:51Z" + generated_at: "2026-04-18T04:59:12Z" model: gpt-5.4 provider: openai - source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 + source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a source_path: help/testing.md workflow: 15 --- # Pruebas -OpenClaw tiene tres suites de Vitest (unitaria/integración, e2e, en vivo) y un pequeño conjunto de ejecutores de Docker. +OpenClaw tiene tres suites de Vitest (unitarias/integración, e2e, live) y un pequeño conjunto de ejecutores de Docker. -Esta documentación es una guía de “cómo probamos”: +Este documento es una guía de “cómo probamos”: -- Qué cubre cada suite (y qué deliberadamente _no_ cubre) +- Qué cubre cada suite (y qué _deliberadamente_ no cubre) - Qué comandos ejecutar para flujos de trabajo comunes (local, antes de hacer push, depuración) -- Cómo las pruebas en vivo descubren credenciales y seleccionan modelos/proveedores +- Cómo las pruebas live descubren credenciales y seleccionan modelos/proveedores - Cómo agregar regresiones para problemas reales de modelo/proveedor ## Inicio rápido @@ -31,83 +31,83 @@ La mayoría de los días: - Puerta completa (esperada antes de hacer push): `pnpm build && pnpm check && pnpm test` - Ejecución local más rápida de la suite completa en una máquina con buenos recursos: `pnpm test:max` -- Bucle directo de observación de Vitest: `pnpm test:watch` +- Bucle directo de vigilancia de Vitest: `pnpm test:watch` - El direccionamiento directo a archivos ahora también enruta rutas de extensiones/canales: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Prefiere primero las ejecuciones dirigidas cuando estés iterando sobre un único fallo. - Sitio de QA respaldado por Docker: `pnpm qa:lab:up` - Canal de QA respaldado por VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Cuando toques pruebas o quieras más confianza: +Cuando tocas pruebas o quieres más confianza: - Puerta de cobertura: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` -Cuando depures proveedores/modelos reales (requiere credenciales reales): +Al depurar proveedores/modelos reales (requiere credenciales reales): -- Suite en vivo (modelos + sondeos de herramientas/imágenes del Gateway): `pnpm test:live` -- Dirigir silenciosamente un archivo en vivo: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (sondeos de modelos + herramientas/imágenes de Gateway): `pnpm test:live` +- Apuntar silenciosamente a un solo archivo live: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Consejo: cuando solo necesites un caso fallido, prefiere acotar las pruebas en vivo mediante las variables de entorno de lista permitida descritas abajo. +Consejo: cuando solo necesites un caso fallido, prefiere acotar las pruebas live mediante las variables de entorno de lista permitida descritas abajo. ## Ejecutores específicos de QA -Estos comandos se sitúan junto a las suites principales de pruebas cuando necesitas el realismo de qa-lab: +Estos comandos están junto a las suites de prueba principales cuando necesitas el realismo de qa-lab: - `pnpm openclaw qa suite` - - Ejecuta directamente en el host escenarios de QA respaldados por el repositorio. - - Ejecuta varios escenarios seleccionados en paralelo de forma predeterminada con workers de Gateway aislados, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para el canal serial anterior. + - Ejecuta escenarios de QA respaldados por el repositorio directamente en el host. + - Ejecuta en paralelo varios escenarios seleccionados por defecto con workers de Gateway aislados, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency ` para ajustar la cantidad de workers, o `--concurrency 1` para el canal serial anterior. - Admite los modos de proveedor `live-frontier`, `mock-openai` y `aimock`. - `aimock` inicia un servidor de proveedor local respaldado por AIMock para cobertura experimental de fixtures y simulaciones de protocolo sin reemplazar el canal `mock-openai` con reconocimiento de escenarios. + `aimock` inicia un servidor de proveedor local respaldado por AIMock para cobertura experimental de fixtures y simulaciones de protocolo sin reemplazar el canal `mock-openai` orientado a escenarios. - `pnpm openclaw qa suite --runner multipass` - - Ejecuta la misma suite de QA dentro de una VM Linux desechable de Multipass. + - Ejecuta la misma suite de QA dentro de una VM Linux Multipass desechable. - Mantiene el mismo comportamiento de selección de escenarios que `qa suite` en el host. - Reutiliza las mismas banderas de selección de proveedor/modelo que `qa suite`. - - Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que son prácticas para el huésped: - claves de proveedor basadas en entorno, la ruta de configuración del proveedor en vivo de QA y `CODEX_HOME` cuando está presente. - - Los directorios de salida deben permanecer bajo la raíz del repositorio para que el huésped pueda escribir de vuelta a través del espacio de trabajo montado. - - Escribe el informe y resumen normales de QA, además de los registros de Multipass, bajo + - Las ejecuciones live reenvían las entradas de autenticación de QA compatibles que son prácticas para el invitado: + claves de proveedor basadas en env, la ruta de configuración del proveedor live de QA y `CODEX_HOME` cuando está presente. + - Los directorios de salida deben permanecer bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través del espacio de trabajo montado. + - Escribe el informe + resumen normales de QA más los logs de Multipass en `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia el sitio de QA respaldado por Docker para trabajo de QA de estilo operador. + - Inicia el sitio de QA respaldado por Docker para trabajo de QA estilo operador. - `pnpm openclaw qa aimock` - Inicia solo el servidor de proveedor local AIMock para pruebas rápidas directas del protocolo. - `pnpm openclaw qa matrix` - - Ejecuta el canal de QA en vivo de Matrix contra un homeserver Tuwunel desechable respaldado por Docker. + - Ejecuta el canal de QA live de Matrix contra un homeserver Tuwunel desechable respaldado por Docker. - Este host de QA hoy es solo para repositorio/desarrollo. Las instalaciones empaquetadas de OpenClaw no incluyen `qa-lab`, por lo que no exponen `openclaw qa`. - - Los checkouts del repositorio cargan directamente el ejecutor incluido; no se necesita un paso separado de instalación del Plugin. - - Aprovisiona tres usuarios temporales de Matrix (`driver`, `sut`, `observer`) más una sala privada, y luego inicia un proceso hijo de Gateway de QA con el Plugin real de Matrix como transporte del SUT. - - Usa por defecto la imagen estable fijada de Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Sustitúyela con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` cuando necesites probar otra imagen. - - Matrix no expone banderas compartidas de fuente de credenciales porque el canal aprovisiona usuarios desechables localmente. - - Escribe un informe de QA de Matrix, un resumen, un artefacto de eventos observados y un registro combinado de salida estándar/error estándar bajo `.artifacts/qa-e2e/...`. + - Los checkouts del repositorio cargan el ejecutor integrado directamente; no se necesita un paso separado de instalación del Plugin. + - Aprovisiona tres usuarios temporales de Matrix (`driver`, `sut`, `observer`) más una sala privada, y luego inicia un proceso hijo de Gateway de QA con el Plugin real de Matrix como transporte SUT. + - Usa la imagen estable fijada de Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1` por defecto. Sustitúyela con `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` cuando necesites probar una imagen diferente. + - Matrix no expone banderas compartidas de origen de credenciales porque el canal aprovisiona usuarios desechables localmente. + - Escribe un informe de QA de Matrix, un resumen, un artefacto de eventos observados y un log combinado de salida estándar/error estándar en `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Ejecuta el canal de QA en vivo de Telegram contra un grupo privado real usando los tokens del bot driver y del bot SUT desde el entorno. + - Ejecuta el canal de QA live de Telegram contra un grupo privado real usando los tokens del bot driver y del bot SUT desde env. - Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. El id del grupo debe ser el id numérico del chat de Telegram. - - Admite `--credential-source convex` para credenciales compartidas agrupadas. Usa por defecto el modo de entorno, o establece `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases agrupados. + - Admite `--credential-source convex` para credenciales compartidas en pool. Usa el modo env por defecto, o establece `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por arrendamientos compartidos. - Requiere dos bots distintos en el mismo grupo privado, con el bot SUT exponiendo un nombre de usuario de Telegram. - - Para una observación estable de bot a bot, habilita el Modo de Comunicación Bot a Bot en `@BotFather` para ambos bots y asegúrate de que el bot driver pueda observar el tráfico de bots del grupo. - - Escribe un informe de QA de Telegram, un resumen y un artefacto de mensajes observados bajo `.artifacts/qa-e2e/...`. + - Para una observación estable entre bots, habilita el modo de comunicación Bot-to-Bot en `@BotFather` para ambos bots y asegúrate de que el bot driver pueda observar el tráfico de bots del grupo. + - Escribe un informe de QA de Telegram, un resumen y un artefacto de mensajes observados en `.artifacts/qa-e2e/...`. -Los canales de transporte en vivo comparten un contrato estándar para que los nuevos transportes no diverjan: +Los canales de transporte live comparten un contrato estándar para que los nuevos transportes no diverjan: -`qa-channel` sigue siendo la suite amplia de QA sintética y no forma parte de la matriz de cobertura de transporte en vivo. +`qa-channel` sigue siendo la suite amplia de QA sintética y no forma parte de la matriz de cobertura de transporte live. -| Canal | Canary | Restricción por menciones | Bloqueo por lista permitida | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento de hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda | -| -------- | ------ | ------------------------- | --------------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Canal | Canary | Mención obligatoria | Bloqueo por lista permitida | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando help | +| -------- | ------ | ------------------- | --------------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenciales compartidas de Telegram mediante Convex (v1) Cuando `--credential-source convex` (o `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para -`openclaw qa telegram`, QA lab adquiere un lease exclusivo de un grupo respaldado por Convex, envía Heartbeat -de ese lease mientras el canal está en ejecución y libera el lease al apagarse. +`openclaw qa telegram`, qa-lab adquiere un arrendamiento exclusivo de un pool respaldado por Convex, envía Heartbeat +de ese arrendamiento mientras el canal está en ejecución y libera el arrendamiento al cerrarse. Andamiaje de referencia del proyecto Convex: - `qa/convex-credential-broker/` -Variables de entorno requeridas: +Variables de entorno obligatorias: - `OPENCLAW_QA_CONVEX_SITE_URL` (por ejemplo `https://your-deployment.convex.site`) - Un secreto para el rol seleccionado: @@ -115,21 +115,21 @@ Variables de entorno requeridas: - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` - Selección del rol de credencial: - CLI: `--credential-role maintainer|ci` - - Valor predeterminado por entorno: `OPENCLAW_QA_CREDENTIAL_ROLE` (predeterminado: `maintainer`) + - Valor predeterminado en env: `OPENCLAW_QA_CREDENTIAL_ROLE` (por defecto `maintainer`) Variables de entorno opcionales: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (predeterminado: `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (predeterminado: `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (predeterminado: `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (predeterminado: `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (predeterminado: `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (predeterminado `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (predeterminado `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (predeterminado `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (predeterminado `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (predeterminado `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreo opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URL de Convex `http://` de loopback local solo para desarrollo local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs de Convex `http://` de loopback para desarrollo exclusivamente local. -`OPENCLAW_QA_CONVEX_SITE_URL` debe usar `https://` en operación normal. +`OPENCLAW_QA_CONVEX_SITE_URL` debe usar `https://` en funcionamiento normal. -Los comandos administrativos de mantenedor (agregar/eliminar/listar del grupo) requieren +Los comandos administrativos de mantenimiento (agregar/eliminar/listar pool) requieren específicamente `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. Ayudantes de CLI para mantenedores: @@ -154,22 +154,22 @@ Contrato predeterminado del endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-crede - `POST /release` - Solicitud: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Éxito: `{ status: "ok" }` (o `2xx` vacío) -- `POST /admin/add` (solo con secreto de mantenedor) +- `POST /admin/add` (solo con secreto de maintainer) - Solicitud: `{ kind, actorId, payload, note?, status? }` - Éxito: `{ status: "ok", credential }` -- `POST /admin/remove` (solo con secreto de mantenedor) +- `POST /admin/remove` (solo con secreto de maintainer) - Solicitud: `{ credentialId, actorId }` - Éxito: `{ status: "ok", changed, credential }` - - Protección de lease activo: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (solo con secreto de mantenedor) + - Protección por arrendamiento activo: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (solo con secreto de maintainer) - Solicitud: `{ kind?, status?, includePayload?, limit? }` - Éxito: `{ status: "ok", credentials, count }` -Forma de payload para el tipo Telegram: +Forma de la carga útil para el tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` debe ser una cadena con el id numérico del chat de Telegram. -- `admin/add` valida esta forma para `kind: "telegram"` y rechaza payloads malformados. +- `admin/add` valida esta forma para `kind: "telegram"` y rechaza cargas útiles mal formadas. ### Agregar un canal a QA @@ -178,48 +178,48 @@ Agregar un canal al sistema de QA en Markdown requiere exactamente dos cosas: 1. Un adaptador de transporte para el canal. 2. Un paquete de escenarios que ejercite el contrato del canal. -No agregues una nueva raíz de comando de QA de nivel superior cuando el host compartido `qa-lab` puede -ser dueño del flujo. +No agregues una nueva raíz de comandos de QA de nivel superior cuando el host compartido `qa-lab` pueda +controlar el flujo. -`qa-lab` es dueño de la mecánica compartida del host: +`qa-lab` controla la mecánica compartida del host: -- la raíz del comando `openclaw qa` -- el inicio y apagado de la suite -- la concurrencia de workers -- la escritura de artefactos -- la generación de informes -- la ejecución de escenarios -- alias de compatibilidad para escenarios antiguos de `qa-channel` +- la raíz de comandos `openclaw qa` +- inicio y desmontaje de la suite +- concurrencia de workers +- escritura de artefactos +- generación de informes +- ejecución de escenarios +- alias de compatibilidad para escenarios `qa-channel` antiguos -Los Plugins de ejecutor son dueños del contrato de transporte: +Los plugins de ejecutor controlan el contrato de transporte: - cómo se monta `openclaw qa ` bajo la raíz compartida `qa` -- cómo se configura el Gateway para ese transporte -- cómo se comprueba la preparación +- cómo se configura Gateway para ese transporte +- cómo se verifica la preparación - cómo se inyectan eventos entrantes - cómo se observan los mensajes salientes - cómo se exponen las transcripciones y el estado de transporte normalizado -- cómo se ejecutan las acciones respaldadas por transporte -- cómo se maneja el restablecimiento o limpieza específicos del transporte +- cómo se ejecutan acciones respaldadas por transporte +- cómo se maneja el restablecimiento o la limpieza específicos del transporte -El umbral mínimo de adopción para un canal nuevo es: +El requisito mínimo de adopción para un canal nuevo es: -1. Mantener `qa-lab` como dueño de la raíz compartida `qa`. -2. Implementar el ejecutor de transporte en la interfaz de host compartido de `qa-lab`. -3. Mantener la mecánica específica del transporte dentro del Plugin del ejecutor o del arnés del canal. -4. Montar el ejecutor como `openclaw qa ` en lugar de registrar una raíz de comando competidora. - Los Plugins de ejecutor deben declarar `qaRunners` en `openclaw.plugin.json` y exportar un arreglo `qaRunnerCliRegistrations` coincidente desde `runtime-api.ts`. - Mantén `runtime-api.ts` liviano; la ejecución diferida de CLI y del ejecutor debe permanecer detrás de puntos de entrada separados. -5. Crear o adaptar escenarios en Markdown bajo `qa/scenarios/`. -6. Usar los ayudantes genéricos de escenarios para los escenarios nuevos. -7. Mantener funcionando los alias de compatibilidad existentes, salvo que el repositorio esté realizando una migración intencional. +1. Mantener `qa-lab` como propietario de la raíz compartida `qa`. +2. Implementar el ejecutor de transporte en la interfaz compartida del host `qa-lab`. +3. Mantener la mecánica específica del transporte dentro del plugin del ejecutor o del arnés del canal. +4. Montar el ejecutor como `openclaw qa ` en lugar de registrar una raíz de comandos competidora. + Los plugins de ejecutor deben declarar `qaRunners` en `openclaw.plugin.json` y exportar un arreglo `qaRunnerCliRegistrations` coincidente desde `runtime-api.ts`. + Mantén `runtime-api.ts` liviano; la ejecución diferida de CLI y del ejecutor debe permanecer detrás de entrypoints separados. +5. Crear o adaptar escenarios en Markdown bajo los directorios temáticos `qa/scenarios/`. +6. Usar los ayudantes genéricos de escenarios para escenarios nuevos. +7. Mantener funcionando los alias de compatibilidad existentes, a menos que el repositorio esté haciendo una migración intencional. La regla de decisión es estricta: -- Si un comportamiento puede expresarse una sola vez en `qa-lab`, colócalo en `qa-lab`. -- Si un comportamiento depende de un transporte de canal, mantenlo en ese Plugin de ejecutor o arnés del Plugin. -- Si un escenario necesita una nueva capacidad que más de un canal puede usar, agrega un ayudante genérico en lugar de una rama específica por canal en `suite.ts`. -- Si un comportamiento solo tiene sentido para un transporte, mantén el escenario específico del transporte y hazlo explícito en el contrato del escenario. +- Si un comportamiento puede expresarse una sola vez en `qa-lab`, ponlo en `qa-lab`. +- Si un comportamiento depende de un transporte de canal, mantenlo en ese plugin de ejecutor o arnés de plugin. +- Si un escenario necesita una nueva capacidad que más de un canal pueda usar, agrega un ayudante genérico en lugar de una rama específica del canal en `suite.ts`. +- Si un comportamiento solo tiene sentido para un transporte, mantén el escenario específico de ese transporte y hazlo explícito en el contrato del escenario. Los nombres preferidos de ayudantes genéricos para escenarios nuevos son: @@ -236,7 +236,7 @@ Los nombres preferidos de ayudantes genéricos para escenarios nuevos son: - `formatTransportTranscript` - `resetTransport` -Siguen disponibles alias de compatibilidad para escenarios existentes, incluidos: +Los alias de compatibilidad siguen disponibles para escenarios existentes, incluidos: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -244,104 +244,104 @@ Siguen disponibles alias de compatibilidad para escenarios existentes, incluidos - `formatConversationTranscript` - `resetBus` -El trabajo de canales nuevos debe usar los nombres de ayudantes genéricos. +El trabajo en canales nuevos debe usar los nombres de ayudantes genéricos. Los alias de compatibilidad existen para evitar una migración de un solo día, no como modelo para la creación de escenarios nuevos. -## Suites de pruebas (qué se ejecuta dónde) +## Suites de prueba (qué se ejecuta dónde) -Piensa en las suites como de “realismo creciente” (y costo/inestabilidad crecientes): +Piense en las suites como “realismo creciente” (y mayor inestabilidad/costo): -### Unitaria / integración (predeterminada) +### Unitarias / integración (predeterminada) - Comando: `pnpm test` -- Configuración: diez ejecuciones secuenciales de shards (`vitest.full-*.config.ts`) sobre los proyectos de Vitest con alcance existente -- Archivos: inventarios de core/unit bajo `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas de nodo `ui` incluidas en la lista permitida cubiertas por `vitest.unit.config.ts` +- Configuración: diez ejecuciones secuenciales por shard (`vitest.full-*.config.ts`) sobre los proyectos de Vitest acotados existentes +- Archivos: inventarios core/unit en `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` y las pruebas de nodo de `ui` incluidas en la lista permitida cubiertas por `vitest.unit.config.ts` - Alcance: - Pruebas unitarias puras - - Pruebas de integración en proceso (autenticación del gateway, enrutamiento, herramientas, análisis, configuración) + - Pruebas de integración en proceso (autenticación de Gateway, enrutamiento, herramientas, parsing, configuración) - Regresiones deterministas para errores conocidos - Expectativas: - Se ejecuta en CI - No requiere claves reales - Debe ser rápida y estable - Nota sobre proyectos: - - `pnpm test` sin destino específico ahora ejecuta once configuraciones de shards más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso nativo gigantesco del proyecto raíz. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas. - - `pnpm test --watch` sigue usando el grafo de proyectos nativo de raíz `vitest.config.ts`, porque un bucle de observación con múltiples shards no es práctico. - - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` enrutan primero los destinos explícitos de archivo/directorio a través de canales con alcance, por lo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo completo de arranque del proyecto raíz. - - `pnpm test:changed` expande las rutas de git modificadas a esos mismos canales con alcance cuando el diff solo toca archivos de origen/prueba enrutable; las ediciones de configuración/preparación siguen recurriendo a la reejecución amplia del proyecto raíz. - - Las pruebas unitarias de importación ligera de agentes, comandos, plugins, ayudantes de auto-reply, `plugin-sdk` y áreas utilitarias puras similares se enrutan por el canal `unit-fast`, que omite `test/setup-openclaw-runtime.ts`; los archivos con estado o pesados en tiempo de ejecución permanecen en los canales existentes. - - Los archivos fuente auxiliares seleccionados de `plugin-sdk` y `commands` también asignan las ejecuciones en modo cambiado a pruebas hermanas explícitas en esos canales ligeros, de modo que las ediciones de ayudantes evitan volver a ejecutar la suite pesada completa de ese directorio. - - `auto-reply` ahora tiene tres grupos dedicados: ayudantes principales de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de reply fuera de las pruebas baratas de estado/chunk/token. + - `pnpm test` sin objetivo ahora ejecuta once configuraciones por shard más pequeñas (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) en lugar de un único proceso raíz nativo gigante. Esto reduce el RSS máximo en máquinas cargadas y evita que el trabajo de auto-reply/extensiones deje sin recursos a suites no relacionadas. + - `pnpm test --watch` sigue usando el grafo de proyectos nativo de `vitest.config.ts`, porque un bucle de watch con múltiples shards no es práctico. + - `pnpm test`, `pnpm test:watch` y `pnpm test:perf:imports` dirigen primero objetivos explícitos de archivo/directorio a través de canales acotados, por lo que `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar el costo de inicio completo del proyecto raíz. + - `pnpm test:changed` expande las rutas git modificadas a los mismos canales acotados cuando el diff solo toca archivos fuente/de prueba enrutable; las ediciones de configuración/preparación siguen recurriendo a la reejecución amplia del proyecto raíz. + - Las pruebas unitarias livianas en importación de agentes, comandos, plugins, ayudantes de auto-reply, `plugin-sdk` y áreas utilitarias puras similares se dirigen al canal `unit-fast`, que omite `test/setup-openclaw-runtime.ts`; los archivos pesados con estado/runtime permanecen en los canales existentes. + - Algunos archivos fuente auxiliares seleccionados de `plugin-sdk` y `commands` también mapean ejecuciones en modo changed a pruebas hermanas explícitas en esos canales livianos, para que las ediciones en ayudantes eviten volver a ejecutar la suite pesada completa de ese directorio. + - `auto-reply` ahora tiene tres buckets dedicados: ayudantes core de nivel superior, pruebas de integración `reply.*` de nivel superior y el subárbol `src/auto-reply/reply/**`. Esto mantiene el trabajo más pesado del arnés de respuesta fuera de las pruebas baratas de status/chunk/token. - Nota sobre el ejecutor integrado: - - Cuando cambies las entradas de descubrimiento de herramientas de mensajes o el contexto de tiempo de ejecución de Compaction, + - Cuando cambies las entradas de descubrimiento de herramientas de mensajes o el contexto de runtime de Compaction, mantén ambos niveles de cobertura. - - Agrega regresiones enfocadas de ayudantes para límites puros de enrutamiento/normalización. - - También mantén saludables las suites de integración del ejecutor integrado: + - Agrega regresiones centradas en ayudantes para límites puros de enrutamiento/normalización. + - También mantén sanas las suites de integración del ejecutor integrado: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` y `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Esas suites verifican que los ids con alcance y el comportamiento de Compaction sigan fluyendo + - Estas suites verifican que los ids acotados y el comportamiento de Compaction sigan fluyendo por las rutas reales `run.ts` / `compact.ts`; las pruebas solo de ayudantes no son un sustituto suficiente para esas rutas de integración. - Nota sobre el pool: - - La configuración base de Vitest ahora usa `threads` de forma predeterminada. - - La configuración compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos raíz, e2e y las configuraciones en vivo. - - El canal UI raíz mantiene su configuración `jsdom` y optimizador, pero ahora también se ejecuta en el ejecutor compartido no aislado. + - La configuración base de Vitest ahora usa `threads` por defecto. + - La configuración compartida de Vitest también fija `isolate: false` y usa el ejecutor no aislado en los proyectos raíz, e2e y live. + - El canal UI raíz mantiene su configuración y optimizador de `jsdom`, pero ahora también se ejecuta en el ejecutor compartido no aislado. - Cada shard de `pnpm test` hereda los mismos valores predeterminados `threads` + `isolate: false` de la configuración compartida de Vitest. - - El iniciador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` de forma predeterminada para los procesos Node hijos de Vitest para reducir la agitación de compilación de V8 durante grandes ejecuciones locales. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. + - El lanzador compartido `scripts/run-vitest.mjs` ahora también agrega `--no-maglev` por defecto para los procesos Node hijo de Vitest para reducir la agitación de compilación de V8 durante grandes ejecuciones locales. Establece `OPENCLAW_VITEST_ENABLE_MAGLEV=1` si necesitas comparar con el comportamiento estándar de V8. - Nota sobre iteración local rápida: - - `pnpm test:changed` enruta mediante canales con alcance cuando las rutas modificadas se asignan limpiamente a una suite más pequeña. - - `pnpm test:max` y `pnpm test:changed:max` mantienen el mismo comportamiento de enrutamiento, solo con un límite mayor de workers. - - El autoescalado local de workers ahora es intencionalmente conservador y también reduce la carga cuando el promedio de carga del host ya es alto, de modo que varias ejecuciones concurrentes de Vitest hagan menos daño de forma predeterminada. - - La configuración base de Vitest marca los archivos de proyectos/configuración como `forceRerunTriggers` para que las reejecuciones en modo cambiado sigan siendo correctas cuando cambia el cableado de pruebas. + - `pnpm test:changed` se enruta por canales acotados cuando las rutas modificadas se asignan limpiamente a una suite más pequeña. + - `pnpm test:max` y `pnpm test:changed:max` mantienen el mismo comportamiento de enrutamiento, solo que con un límite mayor de workers. + - El autoescalado local de workers ahora es intencionalmente conservador y también retrocede cuando la carga media del host ya es alta, por lo que múltiples ejecuciones concurrentes de Vitest causan menos daño por defecto. + - La configuración base de Vitest marca los archivos de proyectos/configuración como `forceRerunTriggers` para que las reejecuciones en modo changed sigan siendo correctas cuando cambia el cableado de pruebas. - La configuración mantiene `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado en hosts compatibles; establece `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` si quieres una ubicación de caché explícita para perfilado directo. -- Nota de depuración de rendimiento: - - `pnpm test:perf:imports` habilita el informe de duración de importación de Vitest más la salida del desglose de importaciones. - - `pnpm test:perf:imports:changed` aplica ese mismo perfilado a los archivos modificados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado con la ruta nativa del proyecto raíz para ese diff confirmado e imprime el tiempo total más el RSS máximo de macOS. -- `pnpm test:perf:changed:bench -- --worktree` evalúa el árbol actual con cambios pasando la lista de archivos modificados por `scripts/test-projects.mjs` y la configuración raíz de Vitest. - - `pnpm test:perf:profile:main` escribe un perfil de CPU del hilo principal para la sobrecarga de arranque y transformación de Vitest/Vite. +- Nota sobre depuración de rendimiento: + - `pnpm test:perf:imports` habilita informes de duración de importación de Vitest más salida de desglose de importaciones. + - `pnpm test:perf:imports:changed` limita la misma vista de perfilado a los archivos modificados desde `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` enrutado frente a la ruta nativa del proyecto raíz para ese diff confirmado e imprime tiempo total más RSS máximo de macOS. +- `pnpm test:perf:changed:bench -- --worktree` mide el árbol sucio actual enr utando la lista de archivos modificados a través de `scripts/test-projects.mjs` y la configuración raíz de Vitest. + - `pnpm test:perf:profile:main` escribe un perfil de CPU del hilo principal para la sobrecarga de inicio y transformación de Vitest/Vite. - `pnpm test:perf:profile:runner` escribe perfiles de CPU+heap del ejecutor para la suite unitaria con el paralelismo de archivos deshabilitado. -### E2E (prueba rápida del gateway) +### E2E (prueba rápida de Gateway) - Comando: `pnpm test:e2e` - Configuración: `vitest.e2e.config.ts` - Archivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Valores predeterminados de tiempo de ejecución: - - Usa `threads` de Vitest con `isolate: false`, en línea con el resto del repositorio. - - Usa workers adaptativos (CI: hasta 2, local: 1 de forma predeterminada). - - Se ejecuta en modo silencioso de forma predeterminada para reducir la sobrecarga de E/S de consola. -- Sustituciones útiles: - - `OPENCLAW_E2E_WORKERS=` para forzar la cantidad de workers (limitada a 16). - - `OPENCLAW_E2E_VERBOSE=1` para volver a habilitar la salida detallada de consola. +- Valores predeterminados de runtime: + - Usa Vitest `threads` con `isolate: false`, igual que el resto del repositorio. + - Usa workers adaptativos (CI: hasta 2, local: 1 por defecto). + - Se ejecuta en modo silencioso por defecto para reducir la sobrecarga de E/S de consola. +- Overrides útiles: + - `OPENCLAW_E2E_WORKERS=` para forzar la cantidad de workers (máximo 16). + - `OPENCLAW_E2E_VERBOSE=1` para volver a habilitar la salida detallada en consola. - Alcance: - - Comportamiento end-to-end del gateway con múltiples instancias + - Comportamiento end-to-end de Gateway con múltiples instancias - Superficies WebSocket/HTTP, emparejamiento de nodos y redes más pesadas - Expectativas: - - Se ejecuta en CI (cuando está habilitado en la canalización) + - Se ejecuta en CI (cuando está habilitado en el pipeline) - No requiere claves reales - - Tiene más piezas móviles que las pruebas unitarias (puede ser más lento) + - Tiene más piezas móviles que las pruebas unitarias (puede ser más lenta) -### E2E: prueba rápida del backend de OpenShell +### E2E: prueba rápida del backend OpenShell - Comando: `pnpm test:e2e:openshell` - Archivo: `test/openshell-sandbox.e2e.test.ts` - Alcance: - - Inicia un gateway aislado de OpenShell en el host mediante Docker - - Crea un sandbox a partir de un Dockerfile local temporal - - Ejercita el backend de OpenClaw para OpenShell sobre `sandbox ssh-config` real + ejecución SSH - - Verifica el comportamiento canónico remoto del sistema de archivos a través del puente fs del sandbox + - Inicia un Gateway OpenShell aislado en el host mediante Docker + - Crea un sandbox desde un Dockerfile local temporal + - Ejercita el backend OpenShell de OpenClaw sobre `sandbox ssh-config` + ejecución SSH reales + - Verifica el comportamiento canónico remoto del sistema de archivos mediante el puente fs del sandbox - Expectativas: - - Solo de adhesión voluntaria; no forma parte de la ejecución predeterminada de `pnpm test:e2e` - - Requiere un CLI local de `openshell` más un daemon de Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` aislados y luego destruye el gateway y sandbox de prueba -- Sustituciones útiles: + - Solo opcional; no forma parte de la ejecución predeterminada de `pnpm test:e2e` + - Requiere un CLI `openshell` local más un daemon Docker funcional + - Usa `HOME` / `XDG_CONFIG_HOME` aislados, luego destruye el Gateway de prueba y el sandbox +- Overrides útiles: - `OPENCLAW_E2E_OPENSHELL=1` para habilitar la prueba al ejecutar manualmente la suite e2e más amplia - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apuntar a un binario CLI no predeterminado o a un script contenedor -### En vivo (proveedores reales + modelos reales) +### Live (proveedores reales + modelos reales) - Comando: `pnpm test:live` - Configuración: `vitest.live.config.ts` @@ -349,92 +349,92 @@ Piensa en las suites como de “realismo creciente” (y costo/inestabilidad cre - Predeterminado: **habilitado** por `pnpm test:live` (establece `OPENCLAW_LIVE_TEST=1`) - Alcance: - “¿Este proveedor/modelo realmente funciona _hoy_ con credenciales reales?” - - Detectar cambios de formato del proveedor, particularidades de llamadas a herramientas, problemas de autenticación y comportamiento de límites de tasa + - Detectar cambios de formato del proveedor, peculiaridades de llamadas a herramientas, problemas de autenticación y comportamiento de límites de tasa - Expectativas: - - No es estable para CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas) - - Cuesta dinero / usa límites de tasa - - Es preferible ejecutar subconjuntos acotados en lugar de “todo” -- Las ejecuciones en vivo cargan `~/.profile` para recoger claves de API faltantes. -- De forma predeterminada, las ejecuciones en vivo siguen aislando `HOME` y copian el material de configuración/autenticación a un home temporal de prueba para que los fixtures unitarios no puedan mutar tu `~/.openclaw` real. -- Establece `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando intencionalmente necesites que las pruebas en vivo usen tu directorio home real. -- `pnpm test:live` ahora usa de forma predeterminada un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero oculta el aviso extra de `~/.profile` y silencia los registros de arranque del gateway y el ruido de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los registros completos de arranque. -- Rotación de claves de API (específica por proveedor): establece `*_API_KEYS` con formato de coma/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o la sustitución por ejecución en vivo `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas de límite de tasa. + - No es estable en CI por diseño (redes reales, políticas reales de proveedores, cuotas, caídas) + - Cuesta dinero / consume límites de tasa + - Conviene ejecutar subconjuntos acotados en lugar de “todo” +- Las ejecuciones live cargan `~/.profile` para recoger claves API faltantes. +- Por defecto, las ejecuciones live siguen aislando `HOME` y copian el material de configuración/autenticación a un home temporal de prueba para que los fixtures unitarios no puedan modificar tu `~/.openclaw` real. +- Establece `OPENCLAW_LIVE_USE_REAL_HOME=1` solo cuando intencionalmente necesites que las pruebas live usen tu directorio home real. +- `pnpm test:live` ahora usa por defecto un modo más silencioso: mantiene la salida de progreso `[live] ...`, pero suprime el aviso adicional de `~/.profile` y silencia los logs de arranque de Gateway/el ruido de Bonjour. Establece `OPENCLAW_LIVE_TEST_QUIET=0` si quieres recuperar los logs completos de inicio. +- Rotación de claves API (específica por proveedor): establece `*_API_KEYS` con formato separado por comas/punto y coma o `*_API_KEY_1`, `*_API_KEY_2` (por ejemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) o un override por live mediante `OPENCLAW_LIVE_*_KEY`; las pruebas reintentan ante respuestas por límite de tasa. - Salida de progreso/Heartbeat: - - Las suites en vivo ahora emiten líneas de progreso a stderr para que las llamadas largas al proveedor muestren actividad visible incluso cuando la captura de consola de Vitest está en modo silencioso. - - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso de proveedor/gateway se transmitan de inmediato durante las ejecuciones en vivo. + - Las suites live ahora emiten líneas de progreso a stderr para que las llamadas largas a proveedores muestren actividad visible incluso cuando la captura de consola de Vitest está en modo silencioso. + - `vitest.live.config.ts` deshabilita la interceptación de consola de Vitest para que las líneas de progreso de proveedor/Gateway se transmitan inmediatamente durante las ejecuciones live. - Ajusta los Heartbeat de modelo directo con `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Ajusta los Heartbeat de gateway/sondeo con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Ajusta los Heartbeat de Gateway/sondeo con `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## ¿Qué suite debería ejecutar? +## ¿Qué suite debo ejecutar? Usa esta tabla de decisión: -- Edición de lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste mucho) -- Cambios en redes del gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` -- Depuración de “mi bot está caído” / fallos específicos del proveedor / llamadas a herramientas: ejecuta `pnpm test:live` acotado +- Si editas lógica/pruebas: ejecuta `pnpm test` (y `pnpm test:coverage` si cambiaste bastante) +- Si tocas redes de Gateway / protocolo WS / emparejamiento: agrega `pnpm test:e2e` +- Si depuras “mi bot está caído” / fallos específicos del proveedor / llamadas a herramientas: ejecuta un `pnpm test:live` acotado -## En vivo: barrido de capacidades del nodo Android +## Live: barrido de capacidades de Node Android - Prueba: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **cada comando actualmente anunciado** por un nodo Android conectado y verificar el comportamiento del contrato de comando. +- Objetivo: invocar **cada comando anunciado actualmente** por un Node Android conectado y comprobar el comportamiento del contrato del comando. - Alcance: - - Configuración manual/condicionada previa (la suite no instala/ejecuta/empareja la app). - - Validación `node.invoke` del gateway comando por comando para el nodo Android seleccionado. -- Configuración previa requerida: - - La app de Android ya está conectada y emparejada con el gateway. - - La app se mantiene en primer plano. + - Configuración previa/manual (la suite no instala/ejecuta/empareja la app). + - Validación `node.invoke` de Gateway comando por comando para el Node Android seleccionado. +- Configuración previa obligatoria: + - App Android ya conectada y emparejada con Gateway. + - La app debe mantenerse en primer plano. - Permisos/consentimiento de captura otorgados para las capacidades que esperas que pasen. -- Sustituciones opcionales de destino: +- Overrides de objetivo opcionales: - `OPENCLAW_ANDROID_NODE_ID` o `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detalles completos de configuración de Android: [App de Android](/es/platforms/android) +- Detalles completos de configuración de Android: [App Android](/es/platforms/android) -## En vivo: prueba rápida de modelos (claves de perfiles) +## Live: prueba rápida de modelos (claves de perfil) -Las pruebas en vivo se dividen en dos capas para que podamos aislar fallos: +Las pruebas live se dividen en dos capas para poder aislar fallos: -- “Modelo directo” nos dice si el proveedor/modelo puede responder con esa clave. -- “Prueba rápida del gateway” nos dice si el flujo completo de gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). +- “Modelo directo” nos dice si el proveedor/modelo puede responder con la clave dada. +- “Prueba rápida de Gateway” nos dice si la canalización completa de gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.). -### Capa 1: finalización directa del modelo (sin gateway) +### Capa 1: finalización directa del modelo (sin Gateway) - Prueba: `src/agents/models.profiles.live.test.ts` - Objetivo: - - Enumerar los modelos descubiertos - - Usar `getApiKeyForModel` para seleccionar los modelos para los que tienes credenciales - - Ejecutar una pequeña finalización por modelo (y regresiones dirigidas cuando sea necesario) + - Enumerar los modelos detectados + - Usar `getApiKeyForModel` para seleccionar modelos para los que tienes credenciales + - Ejecutar una pequeña finalización por modelo (y regresiones específicas cuando sea necesario) - Cómo habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) -- Establece `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` enfocado en la prueba rápida del gateway +- Establece `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` centrado en la prueba rápida de Gateway - Cómo seleccionar modelos: - `OPENCLAW_LIVE_MODELS=modern` para ejecutar la lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` es un alias de la lista permitida moderna - o `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (lista permitida separada por comas) - - Los barridos modern/all usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite más pequeño. + - Los barridos modern/all usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor. - Cómo seleccionar proveedores: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (lista permitida separada por comas) -- De dónde provienen las claves: - - De forma predeterminada: almacén de perfiles y valores de entorno alternativos +- De dónde vienen las claves: + - Por defecto: almacén de perfiles y respaldos en env - Establece `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **solo el almacén de perfiles** - Por qué existe esto: - - Separa “la API del proveedor está rota / la clave es inválida” de “la canalización del agente del gateway está rota” - - Contiene regresiones pequeñas y aisladas (ejemplo: repetición de razonamiento de OpenAI Responses/Codex Responses + flujos de llamadas a herramientas) + - Separa “la API del proveedor está rota / la clave no es válida” de “la canalización del agente de Gateway está rota” + - Contiene regresiones pequeñas y aisladas (ejemplo: reproducción de razonamiento de OpenAI Responses/Codex Responses + flujos de llamada a herramientas) -### Capa 2: prueba rápida del Gateway + agente de desarrollo (lo que realmente hace "@openclaw") +### Capa 2: prueba rápida de Gateway + agente de desarrollo (lo que realmente hace "@openclaw") - Prueba: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - - Iniciar un gateway en proceso - - Crear/parchear una sesión `agent:dev:*` (sustitución de modelo por ejecución) - - Iterar sobre modelos con claves y verificar: + - Iniciar un Gateway en proceso + - Crear/parchear una sesión `agent:dev:*` (override de modelo por ejecución) + - Iterar sobre modelos con claves y comprobar: - respuesta “significativa” (sin herramientas) - - que funciona una invocación real de herramienta (sondeo de lectura) - - sondeos opcionales de herramientas adicionales (sondeo de exec+read) + - que una invocación real de herramienta funcione (sondeo de lectura) + - sondeos opcionales adicionales de herramientas (sondeo exec+read) - que las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) sigan funcionando -- Detalles de los sondeos (para que puedas explicar los fallos rápidamente): +- Detalles de los sondeos (para que puedas explicar fallos rápidamente): - sondeo `read`: la prueba escribe un archivo nonce en el espacio de trabajo y le pide al agente que lo `read` y devuelva el nonce. - - sondeo `exec+read`: la prueba le pide al agente que escriba con `exec` un nonce en un archivo temporal y luego lo lea con `read`. + - sondeo `exec+read`: la prueba le pide al agente que escriba mediante `exec` un nonce en un archivo temporal y luego lo lea de vuelta con `read`. - sondeo de imagen: la prueba adjunta un PNG generado (gato + código aleatorio) y espera que el modelo devuelva `cat `. - Referencia de implementación: `src/gateway/gateway-models.profiles.live.test.ts` y `src/gateway/live-image-probe.ts`. - Cómo habilitar: @@ -443,18 +443,18 @@ Las pruebas en vivo se dividen en dos capas para que podamos aislar fallos: - Predeterminado: lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` es un alias de la lista permitida moderna - O establece `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separada por comas) para acotar - - Los barridos de gateway modern/all usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite más pequeño. + - Los barridos de Gateway modern/all usan por defecto un límite curado de alta señal; establece `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor. - Cómo seleccionar proveedores (evitar “todo OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (lista permitida separada por comas) -- Los sondeos de herramientas + imagen siempre están activados en esta prueba en vivo: +- Los sondeos de herramientas + imagen siempre están activados en esta prueba live: - sondeo `read` + sondeo `exec+read` (estrés de herramientas) - el sondeo de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen - Flujo (alto nivel): - - La prueba genera un PNG pequeño con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) + - La prueba genera un pequeño PNG con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`) - Lo envía mediante `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - El Gateway analiza los adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Gateway analiza los adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - El agente integrado reenvía un mensaje de usuario multimodal al modelo - - Verificación: la respuesta contiene `cat` + el código (tolerancia de OCR: se permiten pequeños errores) + - Comprobación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores) Consejo: para ver qué puedes probar en tu máquina (y los ids exactos `provider/model`), ejecuta: @@ -463,26 +463,26 @@ openclaw models list openclaw models list --json ``` -## En vivo: prueba rápida del backend de CLI (Claude, Codex, Gemini u otros CLI locales) +## Live: prueba rápida de backend CLI (Claude, Codex, Gemini u otros CLI locales) - Prueba: `src/gateway/gateway-cli-backend.live.test.ts` -- Objetivo: validar la canalización Gateway + agente usando un backend de CLI local, sin tocar tu configuración predeterminada. -- Los valores predeterminados de prueba rápida específicos del backend se encuentran en la definición `cli-backend.ts` de la extensión propietaria. +- Objetivo: validar la canalización de Gateway + agente usando un backend CLI local, sin tocar tu configuración predeterminada. +- Los valores predeterminados de prueba rápida específicos del backend están en la definición `cli-backend.ts` de la extensión propietaria. - Habilitar: - `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Valores predeterminados: +- Predeterminados: - Proveedor/modelo predeterminado: `claude-cli/claude-sonnet-4-6` - - El comportamiento de comando/args/imagen proviene de los metadatos del Plugin propietario del backend de CLI. -- Sustituciones (opcionales): + - El comportamiento de comando/args/imagen proviene de los metadatos del Plugin del backend CLI propietario. +- Overrides opcionales: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar un adjunto de imagen real (las rutas se inyectan en el prompt). - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivos de imagen como args de CLI en lugar de inyección en el prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los args de imagen cuando `IMAGE_ARG` está establecido. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los args de imagen cuando se establece `IMAGE_ARG`. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar un segundo turno y validar el flujo de reanudación. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para deshabilitar el sondeo predeterminado de continuidad en la misma sesión Claude Sonnet -> Opus (establécelo en `1` para forzarlo cuando el modelo seleccionado admita un destino de cambio). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para deshabilitar el sondeo predeterminado de continuidad en la misma sesión de Claude Sonnet -> Opus (establece `1` para forzarlo cuando el modelo seleccionado admita un destino de cambio). Ejemplo: @@ -498,7 +498,7 @@ Receta de Docker: pnpm test:docker:live-cli-backend ``` -Recetas de Docker de un solo proveedor: +Recetas de Docker para un solo proveedor: ```bash pnpm test:docker:live-cli-backend:claude @@ -510,37 +510,37 @@ pnpm test:docker:live-cli-backend:gemini Notas: - El ejecutor de Docker está en `scripts/test-live-cli-backend-docker.sh`. -- Ejecuta la prueba rápida en vivo del backend de CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. -- Resuelve los metadatos de prueba rápida de CLI desde la extensión propietaria y luego instala el paquete Linux CLI correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo escribible en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portable de suscripción a Claude Code mediante `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` desde `claude setup-token`. Primero demuestra `claude -p` directo en Docker y luego ejecuta dos turnos del backend de CLI del Gateway sin preservar las variables de entorno de clave de API de Anthropic. Este canal de suscripción deshabilita por defecto los sondeos de Claude MCP/tool e imagen porque Claude actualmente enruta el uso de apps de terceros mediante facturación por uso adicional en lugar de los límites normales del plan de suscripción. -- La prueba rápida en vivo del backend de CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada a la herramienta MCP `cron` verificada mediante la CLI del gateway. -- La prueba rápida predeterminada de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada siga recordando una nota anterior. +- Ejecuta la prueba rápida live del backend CLI dentro de la imagen Docker del repositorio como el usuario no root `node`. +- Resuelve los metadatos de la prueba rápida CLI desde la extensión propietaria y luego instala el paquete CLI de Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo grabable en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portátil de suscripción de Claude Code mediante `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primero comprueba `claude -p` directamente en Docker y luego ejecuta dos turnos del backend CLI de Gateway sin conservar las variables de entorno de clave API de Anthropic. Este canal de suscripción deshabilita por defecto los sondeos de herramienta MCP e imagen de Claude porque Claude actualmente enruta el uso de aplicaciones de terceros mediante facturación por uso adicional en lugar de los límites normales del plan de suscripción. +- La prueba rápida live del backend CLI ahora ejercita el mismo flujo end-to-end para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen, luego llamada a herramienta MCP `cron` verificada mediante la CLI de Gateway. +- La prueba rápida predeterminada de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada aún recuerde una nota anterior. -## En vivo: prueba rápida de vinculación ACP (`/acp spawn ... --bind here`) +## Live: prueba rápida de enlace ACP (`/acp spawn ... --bind here`) - Prueba: `src/gateway/gateway-acp-bind.live.test.ts` -- Objetivo: validar el flujo real de vinculación de conversación ACP con un agente ACP en vivo: +- Objetivo: validar el flujo real de enlace de conversación de ACP con un agente ACP live: - enviar `/acp spawn --bind here` - - vincular en el lugar una conversación sintética de canal de mensajes + - enlazar en su lugar una conversación sintética de canal de mensajes - enviar un seguimiento normal en esa misma conversación - - verificar que el seguimiento llegue a la transcripción de la sesión ACP vinculada + - verificar que el seguimiento llegue a la transcripción de la sesión ACP enlazada - Habilitar: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Valores predeterminados: +- Predeterminados: - Agentes ACP en Docker: `claude,codex,gemini` - Agente ACP para `pnpm test:live ...` directo: `claude` - - Canal sintético: contexto de conversación estilo mensaje directo de Slack - - Backend de ACP: `acpx` -- Sustituciones: + - Canal sintético: contexto de conversación estilo DM de Slack + - Backend ACP: `acpx` +- Overrides: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Notas: - - Este canal usa la superficie `chat.send` del gateway con campos de ruta de origen sintética solo para administradores, de modo que las pruebas puedan adjuntar contexto de canal de mensajes sin simular una entrega externa. - - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro de agentes incorporado del Plugin `acpx` integrado para el agente de arnés ACP seleccionado. + - Este canal usa la superficie `chat.send` de Gateway con campos sintéticos de ruta de origen solo para administrador, para que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir entrega externa. + - Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está establecido, la prueba usa el registro integrado de agentes del Plugin `acpx` incluido para el agente de arnés ACP seleccionado. Ejemplo: @@ -556,7 +556,7 @@ Receta de Docker: pnpm test:docker:live-acp-bind ``` -Recetas de Docker de un solo agente: +Recetas de Docker para un solo agente: ```bash pnpm test:docker:live-acp-bind:claude @@ -567,31 +567,31 @@ pnpm test:docker:live-acp-bind:gemini Notas de Docker: - El ejecutor de Docker está en `scripts/test-live-acp-bind-docker.sh`. -- De forma predeterminada, ejecuta la prueba rápida de vinculación ACP contra todos los agentes CLI en vivo compatibles en secuencia: `claude`, `codex` y luego `gemini`. +- Por defecto, ejecuta la prueba rápida de enlace ACP contra todos los agentes CLI live compatibles en secuencia: `claude`, `codex` y luego `gemini`. - Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` o `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para acotar la matriz. -- Carga `~/.profile`, prepara en el contenedor el material de autenticación de CLI correspondiente, instala `acpx` en un prefijo npm escribible y luego instala el CLI en vivo solicitado (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. -- Dentro de Docker, el ejecutor establece `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que acpx mantenga disponibles para el CLI hijo del arnés las variables de entorno del proveedor desde el perfil cargado. +- Carga `~/.profile`, prepara el material de autenticación CLI correspondiente dentro del contenedor, instala `acpx` en un prefijo npm grabable y luego instala la CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) si falta. +- Dentro de Docker, el ejecutor establece `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que acpx mantenga disponibles para la CLI hija del arnés las variables de entorno del proveedor procedentes del perfil cargado. -## En vivo: prueba rápida del arnés app-server de Codex +## Live: prueba rápida del arnés app-server de Codex -- Objetivo: validar el arnés de Codex propiedad del Plugin mediante el método - normal `agent` del gateway: - - cargar el Plugin incluido `codex` +- Objetivo: validar el arnés Codex propiedad del Plugin mediante el método + `agent` normal de Gateway: + - cargar el Plugin integrado `codex` - seleccionar `OPENCLAW_AGENT_RUNTIME=codex` - - enviar un primer turno de agente del gateway a `codex/gpt-5.4` + - enviar un primer turno del agente de Gateway a `codex/gpt-5.4` - enviar un segundo turno a la misma sesión de OpenClaw y verificar que el hilo - app-server pueda reanudarse - - ejecutar `/codex status` y `/codex models` por la misma ruta de comando - del gateway + del app-server pueda reanudarse + - ejecutar `/codex status` y `/codex models` mediante la misma ruta de comando + de Gateway - Prueba: `src/gateway/gateway-codex-harness.live.test.ts` - Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modelo predeterminado: `codex/gpt-5.4` - Sondeo de imagen opcional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sondeo opcional MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- La prueba rápida establece `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que un arnés - de Codex roto no pueda pasar recurriendo silenciosamente a PI. -- Autenticación: `OPENAI_API_KEY` desde el shell/perfil, más los opcionales - `~/.codex/auth.json` y `~/.codex/config.toml` copiados +- Sondeo MCP/herramienta opcional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- La prueba rápida establece `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que un + arnés Codex roto no pueda pasar recurriendo silenciosamente a PI. +- Autenticación: `OPENAI_API_KEY` desde el shell/perfil, más copia opcional de + `~/.codex/auth.json` y `~/.codex/config.toml` Receta local: @@ -615,61 +615,61 @@ Notas de Docker: - El ejecutor de Docker está en `scripts/test-live-codex-harness-docker.sh`. - Carga el `~/.profile` montado, pasa `OPENAI_API_KEY`, copia los archivos de - autenticación de Codex CLI cuando están presentes, instala `@openai/codex` en un prefijo - npm montado y escribible, prepara el árbol fuente y luego ejecuta solo la prueba en vivo del arnés Codex. -- Docker habilita por defecto los sondeos de imagen y MCP/tool. Establece + autenticación de CLI de Codex cuando están presentes, instala `@openai/codex` en un prefijo npm + montado y grabable, prepara el árbol fuente y luego ejecuta solo la prueba live del arnés Codex. +- Docker habilita por defecto los sondeos de imagen y MCP/herramientas. Establece `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` o `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` cuando necesites una ejecución de depuración más acotada. -- Docker también exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, en línea con la configuración - de la prueba en vivo, para que `openai-codex/*` o el fallback a PI no puedan ocultar una regresión +- Docker también exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, igual que la configuración de la prueba + live, para que el respaldo a `openai-codex/*` o PI no pueda ocultar una regresión del arnés Codex. -### Recetas recomendadas para pruebas en vivo +### Recetas live recomendadas -Las listas permitidas acotadas y explícitas son las más rápidas y las menos inestables: +Las listas permitidas acotadas y explícitas son las más rápidas y menos inestables: -- Modelo único, directo (sin gateway): +- Modelo único, directo (sin Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modelo único, prueba rápida del gateway: +- Modelo único, prueba rápida de Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Llamadas a herramientas en varios proveedores: +- Llamada a herramientas en varios proveedores: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Enfoque en Google (clave de API de Gemini + Antigravity): - - Gemini (clave de API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Enfoque en Google (clave API de Gemini + Antigravity): + - Gemini (clave API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Notas: -- `google/...` usa la API de Gemini (clave de API). +- `google/...` usa la API de Gemini (clave API). - `google-antigravity/...` usa el puente OAuth de Antigravity (endpoint de agente estilo Cloud Code Assist). -- `google-gemini-cli/...` usa el CLI local de Gemini en tu máquina (autenticación independiente + particularidades de herramientas). +- `google-gemini-cli/...` usa el CLI local de Gemini en tu máquina (autenticación independiente + peculiaridades de herramientas). - API de Gemini vs CLI de Gemini: - - API: OpenClaw llama a la API hospedada de Gemini de Google por HTTP (autenticación por clave de API / perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”. - - CLI: OpenClaw ejecuta un binario local `gemini`; tiene su propia autenticación y puede comportarse de manera diferente (streaming/compatibilidad con herramientas/desfase de versión). + - API: OpenClaw llama a la API alojada de Gemini de Google por HTTP (autenticación con clave API / perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”. + - CLI: OpenClaw ejecuta un binario `gemini` local; tiene su propia autenticación y puede comportarse de forma diferente (streaming/compatibilidad con herramientas/desfase de versión). -## En vivo: matriz de modelos (qué cubrimos) +## Live: matriz de modelos (qué cubrimos) -No existe una “lista fija de modelos de CI” (las pruebas en vivo son optativas), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves. +No hay una “lista fija de modelos de CI” (live es opcional), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves. -### Conjunto moderno de prueba rápida (llamadas a herramientas + imagen) +### Conjunto moderno de prueba rápida (llamada a herramientas + imagen) -Esta es la ejecución de “modelos comunes” que esperamos mantener funcionando: +Esta es la ejecución de “modelos comunes” que esperamos mantener funcional: -- OpenAI (no Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) +- OpenAI (no-Codex): `openai/gpt-5.4` (opcional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (o `anthropic/claude-sonnet-4-6`) -- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita los modelos Gemini 2.x más antiguos) +- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos antiguos de Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` y `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Ejecuta la prueba rápida del gateway con herramientas + imagen: +Ejecuta la prueba rápida de Gateway con herramientas + imagen: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Base: llamadas a herramientas (Read + Exec opcional) +### Línea base: llamada a herramientas (Read + Exec opcional) Elige al menos uno por familia de proveedores: @@ -679,16 +679,16 @@ Elige al menos uno por familia de proveedores: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Cobertura adicional opcional (buena de tener): +Cobertura adicional opcional (bueno tenerla): - xAI: `xai/grok-4` (o la última disponible) - Mistral: `mistral/`… (elige un modelo con capacidad de “tools” que tengas habilitado) - Cerebras: `cerebras/`… (si tienes acceso) -- LM Studio: `lmstudio/`… (local; las llamadas a herramientas dependen del modo de API) +- LM Studio: `lmstudio/`… (local; la llamada a herramientas depende del modo API) ### Visión: envío de imagen (adjunto → mensaje multimodal) -Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes de OpenAI con capacidad de visión, etc.) para ejercitar el sondeo de imagen. +Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes de OpenAI con visión, etc.) para ejercitar el sondeo de imagen. ### Agregadores / gateways alternativos @@ -697,63 +697,63 @@ Si tienes claves habilitadas, también admitimos pruebas mediante: - OpenRouter: `openrouter/...` (cientos de modelos; usa `openclaw models scan` para encontrar candidatos con capacidad de herramientas+imagen) - OpenCode: `opencode/...` para Zen y `opencode-go/...` para Go (autenticación mediante `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Más proveedores que puedes incluir en la matriz en vivo (si tienes credenciales/configuración): +Más proveedores que puedes incluir en la matriz live (si tienes credenciales/configuración): - Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` - Mediante `models.providers` (endpoints personalizados): `minimax` (nube/API), además de cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.) -Consejo: no intentes codificar “todos los modelos” en la documentación. La lista autoritativa es cualquier cosa que `discoverModels(...)` devuelva en tu máquina + cualquier clave disponible. +Consejo: no intentes fijar “todos los modelos” en la documentación. La lista autoritativa es la que devuelva `discoverModels(...)` en tu máquina + las claves disponibles. -## Credenciales (nunca las confirmes en el repositorio) +## Credenciales (nunca las confirmes) -Las pruebas en vivo descubren credenciales de la misma manera que la CLI. Implicaciones prácticas: +Las pruebas live descubren credenciales del mismo modo que la CLI. Implicaciones prácticas: -- Si la CLI funciona, las pruebas en vivo deberían encontrar las mismas claves. -- Si una prueba en vivo dice “sin credenciales”, depúrala igual que depurarías `openclaw models list` / la selección de modelo. +- Si la CLI funciona, las pruebas live deberían encontrar las mismas claves. +- Si una prueba live dice “no creds”, depura del mismo modo que depurarías `openclaw models list` / la selección de modelos. -- Perfiles de autenticación por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significa “claves de perfil” en las pruebas en vivo) +- Perfiles de autenticación por agente: `~/.openclaw/agents//agent/auth-profiles.json` (esto es lo que significan las “profile keys” en las pruebas live) - Configuración: `~/.openclaw/openclaw.json` (o `OPENCLAW_CONFIG_PATH`) -- Directorio de estado heredado: `~/.openclaw/credentials/` (se copia al home en vivo preparado cuando está presente, pero no es el almacén principal de claves de perfil) -- Las ejecuciones locales en vivo copian por defecto la configuración activa, los archivos `auth-profiles.json` por agente, `credentials/` heredado y los directorios de autenticación de CLI externos compatibles a un home temporal de prueba; los homes en vivo preparados omiten `workspace/` y `sandboxes/`, y las sustituciones de ruta `agents.*.workspace` / `agentDir` se eliminan para que los sondeos no usen tu espacio de trabajo real del host. +- Directorio de estado heredado: `~/.openclaw/credentials/` (se copia al home live preparado cuando está presente, pero no es el almacén principal de claves de perfil) +- Las ejecuciones live locales copian por defecto la configuración activa, los archivos `auth-profiles.json` por agente, `credentials/` heredado y los directorios de autenticación de CLI externos compatibles a un home temporal de prueba; los homes live preparados omiten `workspace/` y `sandboxes/`, y se eliminan los overrides de ruta `agents.*.workspace` / `agentDir` para que los sondeos no toquen tu espacio de trabajo real del host. -Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores de Docker de abajo (pueden montar `~/.profile` dentro del contenedor). +Si quieres depender de claves env (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores de Docker de abajo (pueden montar `~/.profile` dentro del contenedor). -## En vivo: Deepgram (transcripción de audio) +## Live de Deepgram (transcripción de audio) - Prueba: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## En vivo: plan de codificación de BytePlus +## Live de plan de codificación de BytePlus - Prueba: `src/agents/byteplus.live.test.ts` - Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Sustitución opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Override opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## En vivo: medios de flujo de trabajo de ComfyUI +## Live de medios de flujo de trabajo de ComfyUI - Prueba: `extensions/comfy/comfy.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Alcance: - - Ejercita las rutas incluidas de imagen, video y `music_generate` de comfy + - Ejercita las rutas integradas de imagen, video y `music_generate` de comfy - Omite cada capacidad a menos que `models.providers.comfy.` esté configurado - - Útil después de cambiar el envío de flujos de trabajo de comfy, el polling, las descargas o el registro del Plugin + - Útil después de cambiar el envío de flujos de trabajo de comfy, el sondeo, las descargas o el registro del Plugin -## En vivo: generación de imágenes +## Live de generación de imágenes - Prueba: `src/image-generation/runtime.live.test.ts` - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Arnés: `pnpm test:live:media image` - Alcance: - - Enumera cada Plugin de proveedor de generación de imágenes registrado - - Carga variables de entorno de proveedor faltantes desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves de API en vivo/de entorno antes que los perfiles de autenticación almacenados, de modo que claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell + - Enumera todos los plugins de proveedor de generación de imágenes registrados + - Carga las variables de entorno de proveedor faltantes desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell - Omite proveedores sin autenticación/perfil/modelo utilizable - - Ejecuta las variantes estándar de generación de imágenes mediante la capacidad compartida de tiempo de ejecución: + - Ejecuta las variantes estándar de generación de imágenes mediante la capacidad de runtime compartida: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Proveedores incluidos actualmente cubiertos: +- Proveedores integrados cubiertos actualmente: - `openai` - `google` - Acotación opcional: @@ -761,75 +761,75 @@ Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.prof - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar sustituciones solo de entorno + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env -## En vivo: generación de música +## Live de generación de música - Prueba: `extensions/music-generation-providers.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media music` - Alcance: - - Ejercita la ruta compartida incluida de proveedor de generación de música + - Ejercita la ruta compartida integrada del proveedor de generación de música - Actualmente cubre Google y MiniMax - - Carga variables de entorno de proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves de API en vivo/de entorno antes que los perfiles de autenticación almacenados, de modo que claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell + - Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell - Omite proveedores sin autenticación/perfil/modelo utilizable - - Ejecuta ambos modos de tiempo de ejecución declarados cuando están disponibles: + - Ejecuta ambos modos de runtime declarados cuando están disponibles: - `generate` con entrada solo de prompt - `edit` cuando el proveedor declara `capabilities.edit.enabled` - - Cobertura compartida actual: + - Cobertura actual del canal compartido: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: archivo en vivo separado de Comfy, no este barrido compartido + - `comfy`: archivo live de Comfy separado, no este barrido compartido - Acotación opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar sustituciones solo de entorno + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env -## En vivo: generación de video +## Live de generación de video - Prueba: `extensions/video-generation-providers.live.test.ts` - Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Arnés: `pnpm test:live:media video` - Alcance: - - Ejercita la ruta compartida incluida de proveedor de generación de video - - Usa por defecto la ruta de prueba rápida segura para lanzamientos: proveedores no FAL, una solicitud de texto a video por proveedor, prompt de langosta de un segundo y un límite de operación por proveedor tomado de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` de forma predeterminada) - - Omite FAL de forma predeterminada porque la latencia de cola del lado del proveedor puede dominar el tiempo del lanzamiento; pasa `--video-providers fal` o `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para ejecutarlo explícitamente - - Carga variables de entorno de proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear - - Usa por defecto claves de API en vivo/de entorno antes que los perfiles de autenticación almacenados, de modo que claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell + - Ejercita la ruta compartida integrada del proveedor de generación de video + - Usa por defecto la ruta de prueba rápida segura para lanzamiento: proveedores que no son FAL, una solicitud de texto a video por proveedor, prompt lobster de un segundo y un límite de operación por proveedor desde `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por defecto) + - Omite FAL por defecto porque la latencia de cola del lado del proveedor puede dominar el tiempo de lanzamiento; pasa `--video-providers fal` o `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para ejecutarlo explícitamente + - Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear + - Usa por defecto claves API live/env antes que los perfiles de autenticación almacenados, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell - Omite proveedores sin autenticación/perfil/modelo utilizable - - Ejecuta solo `generate` de forma predeterminada + - Ejecuta solo `generate` por defecto - Establece `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para ejecutar también los modos de transformación declarados cuando estén disponibles: - `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por búfer en el barrido compartido - `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local respaldada por búfer en el barrido compartido - Proveedores `imageToVideo` actualmente declarados pero omitidos en el barrido compartido: - - `vydra` porque `veo3` incluido es solo de texto y `kling` incluido requiere una URL de imagen remota - - Cobertura específica de proveedor para Vydra: + - `vydra` porque el `veo3` integrado es solo texto y el `kling` integrado requiere una URL de imagen remota + - Cobertura específica del proveedor Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - ese archivo ejecuta `veo3` de texto a video más un canal `kling` que usa por defecto un fixture de URL de imagen remota - - Cobertura actual en vivo de `videoToVideo`: - - `runway` solo cuando el modelo seleccionado es `runway/gen4_aleph` + - Cobertura live actual de `videoToVideo`: + - solo `runway` cuando el modelo seleccionado es `runway/gen4_aleph` - Proveedores `videoToVideo` actualmente declarados pero omitidos en el barrido compartido: - `alibaba`, `qwen`, `xai` porque esas rutas actualmente requieren URLs de referencia remotas `http(s)` / MP4 - `google` porque el canal compartido actual de Gemini/Veo usa entrada local respaldada por búfer y esa ruta no se acepta en el barrido compartido - - `openai` porque el canal compartido actual no garantiza acceso específico de organización a inpaint/remix de video + - `openai` porque el canal compartido actual carece de garantías de acceso específicas de la organización para inpaint/remix de video - Acotación opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir cada proveedor en el barrido predeterminado, incluido FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos los proveedores en el barrido predeterminado, incluido FAL - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reducir el límite de operación de cada proveedor en una ejecución agresiva de prueba rápida - Comportamiento de autenticación opcional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar sustituciones solo de entorno + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar autenticación del almacén de perfiles e ignorar los overrides solo de env -## Arnés multimedia en vivo +## Arnés live de medios - Comando: `pnpm test:live:media` - Propósito: - - Ejecuta las suites compartidas en vivo de imagen, música y video mediante un único punto de entrada nativo del repositorio - - Carga automáticamente variables de entorno de proveedor faltantes desde `~/.profile` - - Acota automáticamente cada suite a proveedores que actualmente tengan autenticación utilizable de forma predeterminada - - Reutiliza `scripts/test-live.mjs`, por lo que el comportamiento de Heartbeat y modo silencioso se mantiene consistente + - Ejecuta las suites live compartidas de imagen, música y video mediante un único entrypoint nativo del repositorio + - Carga automáticamente las variables de entorno de proveedor faltantes desde `~/.profile` + - Acota automáticamente cada suite a los proveedores que actualmente tienen autenticación utilizable por defecto + - Reutiliza `scripts/test-live.mjs`, para que el comportamiento de Heartbeat y de modo silencioso siga siendo consistente - Ejemplos: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -840,60 +840,61 @@ Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.prof Estos ejecutores de Docker se dividen en dos grupos: -- Ejecutores en vivo de modelos: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo en vivo correspondiente de claves de perfil dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio local de configuración y espacio de trabajo (y cargando `~/.profile` si está montado). Los puntos de entrada locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. -- Los ejecutores en vivo de Docker usan por defecto un límite de prueba rápida más pequeño para que un barrido completo en Docker siga siendo práctico: +- Ejecutores de modelos live: `test:docker:live-models` y `test:docker:live-gateway` ejecutan solo su archivo live de claves de perfil correspondiente dentro de la imagen Docker del repositorio (`src/agents/models.profiles.live.test.ts` y `src/gateway/gateway-models.profiles.live.test.ts`), montando tu directorio de configuración local y espacio de trabajo (y cargando `~/.profile` si está montado). Los entrypoints locales correspondientes son `test:live:models-profiles` y `test:live:gateway-profiles`. +- Los ejecutores live de Docker usan por defecto un límite menor de prueba rápida para que un barrido completo en Docker siga siendo práctico: `test:docker:live-models` usa por defecto `OPENCLAW_LIVE_MAX_MODELS=12`, y `test:docker:live-gateway` usa por defecto `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` y `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sustituye esas variables de entorno cuando - explícitamente quieras el análisis exhaustivo más grande. -- `test:docker:all` construye una vez la imagen Docker en vivo mediante `test:docker:live-build` y luego la reutiliza para los dos canales en vivo de Docker. -- Ejecutores de prueba rápida de contenedores: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` inician uno o más contenedores reales y verifican rutas de integración de más alto nivel. + explícitamente quieras el escaneo exhaustivo más grande. +- `test:docker:all` construye la imagen Docker live una vez mediante `test:docker:live-build`, luego la reutiliza para los dos canales Docker live. +- Los ejecutores de prueba rápida en contenedor: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` y `test:docker:plugins` inician uno o más contenedores reales y verifican rutas de integración de más alto nivel. -Los ejecutores Docker en vivo de modelos también montan por enlace solo los homes de autenticación de CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), y luego los copian al home del contenedor antes de la ejecución para que el OAuth de CLI externo pueda renovar tokens sin modificar el almacén de autenticación del host: +Los ejecutores Docker de modelos live también montan mediante bind solo los homes de autenticación CLI necesarios (o todos los compatibles cuando la ejecución no está acotada), luego los copian al home del contenedor antes de la ejecución para que OAuth de CLI externa pueda refrescar tokens sin mutar el almacén de autenticación del host: - Modelos directos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Prueba rápida de vinculación ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) -- Prueba rápida del backend de CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) +- Prueba rápida de enlace ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) +- Prueba rápida de backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) - Prueba rápida del arnés app-server de Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) - Gateway + agente de desarrollo: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) -- Prueba rápida en vivo de Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) +- Prueba rápida live de Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Asistente de onboarding (TTY, andamiaje completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Redes del Gateway (dos contenedores, autenticación WS + salud): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Puente de canal MCP (Gateway sembrado + puente stdio + prueba rápida sin procesar de tramas de notificación de Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Redes de Gateway (dos contenedores, autenticación WS + estado de salud): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Puente de canal MCP (Gateway inicializado + puente stdio + prueba rápida de tramas de notificación sin procesar de Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) - Plugins (prueba rápida de instalación + alias `/plugin` + semántica de reinicio del paquete Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -Los ejecutores Docker en vivo de modelos también montan por enlace el checkout actual en modo de solo lectura y -lo preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la imagen de tiempo de ejecución -ligera y aun así ejecuta Vitest contra tu código/configuración local exactos. -El paso de preparación omite grandes cachés solo locales y salidas de compilación de apps como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios de salida locales de app `.build` o -Gradle para que las ejecuciones en vivo de Docker no pasen minutos copiando +Los ejecutores Docker de modelos live también montan mediante bind el checkout actual en modo de solo lectura y +lo preparan en un directorio de trabajo temporal dentro del contenedor. Esto mantiene la +imagen de runtime liviana y a la vez ejecuta Vitest contra tu código/configuración local exactos. +El paso de preparación omite grandes cachés solo locales y salidas de compilación de app como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` y directorios locales de `.build` de app o +salida de Gradle para que las ejecuciones live de Docker no pasen minutos copiando artefactos específicos de la máquina. -También establecen `OPENCLAW_SKIP_CHANNELS=1` para que los sondeos en vivo del gateway no inicien +También establecen `OPENCLAW_SKIP_CHANNELS=1` para que los sondeos live de Gateway no inicien workers reales de canales de Telegram/Discord/etc. dentro del contenedor. -`test:docker:live-models` sigue ejecutando `pnpm test:live`, así que también debes pasar -`OPENCLAW_LIVE_GATEWAY_*` cuando necesites acotar o excluir la cobertura en vivo del gateway de ese canal Docker. -`test:docker:openwebui` es una prueba rápida de compatibilidad de más alto nivel: inicia un -contenedor del Gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, -inicia un contenedor fijado de Open WebUI contra ese gateway, inicia sesión mediante -Open WebUI, verifica que `/api/models` expone `openclaw/default`, y luego envía una -solicitud de chat real mediante el proxy `/api/chat/completions` de Open WebUI. +`test:docker:live-models` sigue ejecutando `pnpm test:live`, así que transmite también +`OPENCLAW_LIVE_GATEWAY_*` cuando necesites acotar o excluir la cobertura live de Gateway +de ese canal Docker. +`test:docker:openwebui` es una prueba rápida de compatibilidad de nivel superior: inicia un +contenedor Gateway de OpenClaw con los endpoints HTTP compatibles con OpenAI habilitados, +inicia un contenedor fijado de Open WebUI contra ese Gateway, inicia sesión mediante +Open WebUI, verifica que `/api/models` exponga `openclaw/default` y luego envía una +solicitud real de chat mediante el proxy `/api/chat/completions` de Open WebUI. La primera ejecución puede ser notablemente más lenta porque Docker puede necesitar descargar la -imagen de Open WebUI y Open WebUI puede necesitar completar su propia configuración de arranque en frío. -Este canal espera una clave de modelo en vivo utilizable, y `OPENCLAW_PROFILE_FILE` -(`~/.profile` de forma predeterminada) es la forma principal de proporcionarla en ejecuciones dockerizadas. -Las ejecuciones exitosas imprimen un pequeño payload JSON como `{ "ok": true, "model": +imagen de Open WebUI y Open WebUI puede necesitar terminar su propia configuración de arranque en frío. +Este canal espera una clave de modelo live utilizable, y `OPENCLAW_PROFILE_FILE` +(`~/.profile` por defecto) es la forma principal de proporcionarla en ejecuciones con Docker. +Las ejecuciones exitosas imprimen una pequeña carga útil JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` es intencionalmente determinista y no necesita una -cuenta real de Telegram, Discord o iMessage. Inicia un contenedor del Gateway -sembrado, inicia un segundo contenedor que lanza `openclaw mcp serve`, y luego +cuenta real de Telegram, Discord o iMessage. Inicia un contenedor Gateway +inicializado, arranca un segundo contenedor que ejecuta `openclaw mcp serve` y luego verifica descubrimiento de conversaciones enrutadas, lecturas de transcripción, metadatos de adjuntos, -comportamiento de la cola de eventos en vivo, enrutamiento de envío saliente y notificaciones estilo Claude de canal + -permisos sobre el puente MCP stdio real. La comprobación de notificaciones +comportamiento de la cola de eventos live, enrutamiento de envío saliente y notificaciones +de canal + permisos estilo Claude sobre el puente MCP stdio real. La comprobación de notificaciones inspecciona directamente las tramas MCP stdio sin procesar para que la prueba rápida valide lo que el -puente realmente emite, no solo lo que una SDK cliente específica expone por casualidad. +puente realmente emite, no solo lo que una SDK cliente específica casualmente expone. Prueba manual ACP de hilo en lenguaje natural (no CI): @@ -905,117 +906,117 @@ Variables de entorno útiles: - `OPENCLAW_CONFIG_DIR=...` (predeterminado: `~/.openclaw`) montado en `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (predeterminado: `~/.openclaw/workspace`) montado en `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (predeterminado: `~/.profile`) montado en `/home/node/.profile` y cargado antes de ejecutar las pruebas -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar solo variables de entorno cargadas desde `OPENCLAW_PROFILE_FILE`, usando directorios temporales de configuración/espacio de trabajo y sin montajes de autenticación de CLI externos +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar solo variables de entorno cargadas desde `OPENCLAW_PROFILE_FILE`, usando directorios temporales de configuración/espacio de trabajo y sin montajes externos de autenticación CLI - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (predeterminado: `~/.cache/openclaw/docker-cli-tools`) montado en `/home/node/.npm-global` para instalaciones CLI en caché dentro de Docker -- Los directorios/archivos de autenticación de CLI externos bajo `$HOME` se montan en modo de solo lectura bajo `/host-auth...`, y luego se copian a `/home/node/...` antes de iniciar las pruebas +- Los directorios/archivos de autenticación de CLI externos bajo `$HOME` se montan en modo de solo lectura bajo `/host-auth...`, luego se copian a `/home/node/...` antes de iniciar las pruebas - Directorios predeterminados: `.minimax` - Archivos predeterminados: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Las ejecuciones acotadas por proveedor montan solo los directorios/archivos necesarios inferidos a partir de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Las ejecuciones acotadas por proveedor montan solo los directorios/archivos necesarios inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Sustituye manualmente con `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` o una lista separada por comas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para acotar la ejecución - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar proveedores dentro del contenedor - `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar una imagen existente `openclaw:local-live` en reejecuciones que no necesitan recompilación -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantizar que las credenciales provengan del almacén de perfiles (no del entorno) -- `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por el gateway para la prueba rápida de Open WebUI +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para asegurar que las credenciales provengan del almacén de perfiles (no de env) +- `OPENCLAW_OPENWEBUI_MODEL=...` para elegir el modelo expuesto por Gateway para la prueba rápida de Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...` para sustituir el prompt de verificación de nonce usado por la prueba rápida de Open WebUI -- `OPENWEBUI_IMAGE=...` para sustituir la etiqueta fijada de la imagen de Open WebUI +- `OPENWEBUI_IMAGE=...` para sustituir la etiqueta fijada de imagen de Open WebUI -## Comprobación de cordura de la documentación +## Verificación de documentación -Ejecuta las comprobaciones de documentación después de editar documentación: `pnpm check:docs`. -Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobar encabezados dentro de la página: `pnpm docs:check-links:anchors`. +Ejecuta las comprobaciones de documentación después de editar docs: `pnpm check:docs`. +Ejecuta la validación completa de anclas de Mintlify cuando también necesites comprobaciones de encabezados dentro de la página: `pnpm docs:check-links:anchors`. -## Regresión sin conexión (segura para CI) +## Regresión offline (segura para CI) Estas son regresiones de “canalización real” sin proveedores reales: -- Llamadas a herramientas del Gateway (simulación de OpenAI, gateway real + bucle de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Asistente del Gateway (WS `wizard.start`/`wizard.next`, escribe configuración + autenticación exigida): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Llamada a herramientas de Gateway (mock OpenAI, loop real de Gateway + agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Asistente de Gateway (WS `wizard.start`/`wizard.next`, escribe configuración + autenticación exigida): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evaluaciones de confiabilidad del agente (Skills) +## Evaluaciones de fiabilidad del agente (Skills) -Ya tenemos algunas pruebas seguras para CI que se comportan como “evaluaciones de confiabilidad del agente”: +Ya tenemos algunas pruebas seguras para CI que se comportan como “evaluaciones de fiabilidad del agente”: -- Llamadas a herramientas simuladas a través del gateway real + bucle de agente (`src/gateway/gateway.test.ts`). -- Flujos end-to-end del asistente que validan el cableado de sesión y los efectos de configuración (`src/gateway/gateway.test.ts`). +- Llamada simulada a herramientas mediante el loop real de Gateway + agente (`src/gateway/gateway.test.ts`). +- Flujos end-to-end del asistente que validan el cableado de la sesión y los efectos de configuración (`src/gateway/gateway.test.ts`). -Lo que todavía falta para Skills (consulta [Skills](/es/tools/skills)): +Qué sigue faltando para Skills (ver [Skills](/es/tools/skills)): -- **Toma de decisiones:** cuando se enumeran Skills en el prompt, ¿el agente elige la Skill correcta (o evita las irrelevantes)? +- **Toma de decisiones:** cuando Skills aparecen en el prompt, ¿el agente elige la Skill correcta (o evita las irrelevantes)? - **Cumplimiento:** ¿el agente lee `SKILL.md` antes de usarla y sigue los pasos/args requeridos? -- **Contratos de flujo de trabajo:** escenarios de varios turnos que verifiquen orden de herramientas, arrastre del historial de sesión y límites del sandbox. +- **Contratos de flujo de trabajo:** escenarios de varios turnos que comprueban el orden de herramientas, el arrastre del historial de sesión y los límites del sandbox. Las evaluaciones futuras deben seguir siendo deterministas primero: -- Un ejecutor de escenarios que use proveedores simulados para verificar llamadas a herramientas + orden, lecturas de archivos de Skill y cableado de sesión. -- Un pequeño conjunto de escenarios centrados en Skills (usar vs evitar, restricciones, inyección de prompt). -- Evaluaciones opcionales en vivo (optativas, controladas por entorno) solo después de que la suite segura para CI esté lista. +- Un ejecutor de escenarios que use proveedores simulados para comprobar llamadas a herramientas + orden, lecturas de archivos de Skill y cableado de sesión. +- Una pequeña suite de escenarios centrados en Skills (usar vs evitar, puertas, prompt injection). +- Evaluaciones live opcionales (opt-in, controladas por env) solo después de que la suite segura para CI esté implementada. ## Pruebas de contrato (forma de Plugin y canal) -Las pruebas de contrato verifican que cada Plugin y canal registrados se ajusten a su -contrato de interfaz. Iteran sobre todos los Plugins descubiertos y ejecutan una suite de -verificaciones de forma y comportamiento. El canal unitario predeterminado `pnpm test` +Las pruebas de contrato verifican que cada Plugin y canal registrados cumplan con su +contrato de interfaz. Iteran sobre todos los plugins detectados y ejecutan una suite de +comprobaciones de forma y comportamiento. El canal unitario predeterminado `pnpm test` omite intencionalmente estos archivos compartidos de interfaz y prueba rápida; ejecuta los comandos de contrato explícitamente cuando toques superficies compartidas de canal o proveedor. ### Comandos - Todos los contratos: `pnpm test:contracts` -- Solo contratos de canales: `pnpm test:contracts:channels` -- Solo contratos de proveedores: `pnpm test:contracts:plugins` +- Solo contratos de canal: `pnpm test:contracts:channels` +- Solo contratos de proveedor: `pnpm test:contracts:plugins` -### Contratos de canales +### Contratos de canal Ubicados en `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Forma básica del Plugin (id, nombre, capacidades) - **setup** - Contrato del asistente de configuración - **session-binding** - Comportamiento de vinculación de sesión -- **outbound-payload** - Estructura del payload del mensaje +- **outbound-payload** - Estructura de la carga útil del mensaje - **inbound** - Manejo de mensajes entrantes - **actions** - Manejadores de acciones del canal - **threading** - Manejo de id de hilo -- **directory** - API de directorio/listado -- **group-policy** - Aplicación de políticas de grupo +- **directory** - API de directorio/lista +- **group-policy** - Aplicación de la política de grupo ### Contratos de estado del proveedor Ubicados en `src/plugins/contracts/*.contract.test.ts`. - **status** - Sondeos de estado del canal -- **registry** - Forma del registro de Plugins +- **registry** - Forma del registro de Plugin -### Contratos de proveedores +### Contratos de proveedor Ubicados en `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato del flujo de autenticación -- **auth-choice** - Opción/selección de autenticación -- **catalog** - API de catálogo de modelos -- **discovery** - Descubrimiento de Plugins -- **loader** - Carga de Plugins -- **runtime** - Tiempo de ejecución del proveedor +- **auth** - Contrato de flujo de autenticación +- **auth-choice** - Elección/selección de autenticación +- **catalog** - API del catálogo de modelos +- **discovery** - Descubrimiento de Plugin +- **loader** - Carga de Plugin +- **runtime** - Runtime del proveedor - **shape** - Forma/interfaz del Plugin - **wizard** - Asistente de configuración -### Cuándo ejecutar +### Cuándo ejecutarlas - Después de cambiar exportaciones o subrutas de plugin-sdk -- Después de agregar o modificar un canal o Plugin de proveedor -- Después de refactorizar el registro o descubrimiento de Plugins +- Después de agregar o modificar un Plugin de canal o proveedor +- Después de refactorizar el registro o descubrimiento de plugins -Las pruebas de contrato se ejecutan en CI y no requieren claves de API reales. +Las pruebas de contrato se ejecutan en CI y no requieren claves API reales. ## Agregar regresiones (guía) -Cuando corrijas un problema de proveedor/modelo descubierto en vivo: +Cuando corrijas un problema de proveedor/modelo detectado en live: - Agrega una regresión segura para CI si es posible (proveedor simulado/stub, o captura la transformación exacta de la forma de la solicitud) -- Si es inherentemente solo en vivo (límites de tasa, políticas de autenticación), mantén la prueba en vivo acotada y optativa mediante variables de entorno +- Si es inherentemente solo live (límites de tasa, políticas de autenticación), mantén la prueba live acotada y opt-in mediante variables de entorno - Prefiere apuntar a la capa más pequeña que detecte el error: - - error de conversión/repetición de solicitud del proveedor → prueba directa de modelos - - error de sesión/historial/canalización de herramientas del gateway → prueba rápida en vivo del gateway o prueba simulada del gateway segura para CI -- Protección para recorrido de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo de muestra por clase de SecretRef a partir de metadatos del registro (`listSecretTargetRegistryEntries()`), y luego verifica que se rechacen ids de exec de segmentos de recorrido. - - Si agregas una nueva familia de objetivos SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente en ids de objetivo no clasificados para que las clases nuevas no puedan omitirse silenciosamente. + - error de conversión/reproducción de solicitud del proveedor → prueba de modelos directos + - error en la canalización de sesión/historial/herramientas de Gateway → prueba rápida live de Gateway o prueba simulada segura para CI de Gateway +- Barandilla de recorrido de SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva un objetivo de muestra por clase de SecretRef a partir de los metadatos del registro (`listSecretTargetRegistryEntries()`), y luego comprueba que se rechacen los ids exec de segmento de recorrido. + - Si agregas una nueva familia de objetivos SecretRef `includeInPlan` en `src/secrets/target-registry-data.ts`, actualiza `classifyTargetClass` en esa prueba. La prueba falla intencionalmente en ids de objetivo no clasificados para que las clases nuevas no puedan omitirse en silencio. diff --git a/docs/es/platforms/macos.md b/docs/es/platforms/macos.md index 4028f6d5d..edaf29593 100644 --- a/docs/es/platforms/macos.md +++ b/docs/es/platforms/macos.md @@ -1,76 +1,76 @@ --- read_when: - - Implementando funciones de la app de macOS - - Cambiando el ciclo de vida del gateway o el puente de nodos en macOS -summary: App complementaria de OpenClaw para macOS (barra de menús + broker del gateway) -title: App de macOS + - Implementación de funciones de la aplicación para macOS + - Cambio del ciclo de vida del Gateway o del puenteo de nodos en macOS +summary: Aplicación complementaria de OpenClaw para macOS (barra de menús + intermediario del Gateway) +title: Aplicación para macOS x-i18n: - generated_at: "2026-04-05T12:49:00Z" + generated_at: "2026-04-18T04:59:12Z" model: gpt-5.4 provider: openai - source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135 + source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0 source_path: platforms/macos.md workflow: 15 --- -# Complemento de OpenClaw para macOS (barra de menús + broker del gateway) +# Complemento de OpenClaw para macOS (barra de menús + intermediario del Gateway) -La app de macOS es el **complemento de barra de menús** de OpenClaw. Gestiona permisos, -administra/se conecta al Gateway localmente (launchd o manual) y expone capacidades -de macOS al agente como un nodo. +La aplicación de macOS es el **complemento de barra de menús** para OpenClaw. Se encarga de los permisos, +administra/se conecta al Gateway localmente (launchd o manual) y expone capacidades de macOS +al agente como un Node. ## Qué hace - Muestra notificaciones nativas y estado en la barra de menús. -- Gestiona los prompts de TCC (Notificaciones, Accesibilidad, Grabación de Pantalla, Micrófono, - Reconocimiento de Voz, Automatización/AppleScript). +- Gestiona los avisos de TCC (Notificaciones, Accesibilidad, Grabación de pantalla, Micrófono, + Reconocimiento de voz, Automatización/AppleScript). - Ejecuta o se conecta al Gateway (local o remoto). -- Expone herramientas exclusivas de macOS (Canvas, Cámara, Grabación de Pantalla, `system.run`). -- Inicia el servicio local de node host en modo **remoto** (launchd), y lo detiene en modo **local**. -- Opcionalmente aloja **PeekabooBridge** para automatización de UI. -- Instala la CLI global (`openclaw`) bajo demanda mediante npm, pnpm o bun (la app prefiere npm, luego pnpm y después bun; Node sigue siendo el tiempo de ejecución recomendado para el Gateway). +- Expone herramientas exclusivas de macOS (Canvas, Camera, Screen Recording, `system.run`). +- Inicia el servicio local del host de Node en modo **remoto** (launchd) y lo detiene en modo **local**. +- Puede alojar opcionalmente **PeekabooBridge** para automatización de UI. +- Instala la CLI global (`openclaw`) a pedido mediante npm, pnpm o bun (la aplicación prefiere npm, luego pnpm y luego bun; Node sigue siendo el entorno de ejecución recomendado para Gateway). -## Modo local vs remoto +## Modo local vs. remoto -- **Local** (predeterminado): la app se conecta a un Gateway local ya en ejecución si existe; - en caso contrario habilita el servicio launchd mediante `openclaw gateway install`. -- **Remoto**: la app se conecta a un Gateway por SSH/Tailscale y nunca inicia +- **Local** (predeterminado): la aplicación se conecta a un Gateway local en ejecución si existe; + de lo contrario, habilita el servicio launchd mediante `openclaw gateway install`. +- **Remoto**: la aplicación se conecta a un Gateway a través de SSH/Tailscale y nunca inicia un proceso local. - La app inicia el **servicio local de node host** para que el Gateway remoto pueda alcanzar este Mac. - La app no inicia el Gateway como proceso hijo. - El descubrimiento del Gateway ahora prefiere nombres MagicDNS de Tailscale frente a IP tailnet sin procesar, - de modo que la app de Mac se recupera con más fiabilidad cuando cambian las IP tailnet. + La aplicación inicia el **servicio local del host de Node** para que el Gateway remoto pueda acceder a esta Mac. + La aplicación no genera el Gateway como un proceso hijo. + La detección del Gateway ahora prioriza los nombres MagicDNS de Tailscale sobre las IP sin procesar de la tailnet, + por lo que la aplicación para Mac se recupera de forma más confiable cuando cambian las IP de la tailnet. ## Control de launchd -La app gestiona un LaunchAgent por usuario con la etiqueta `ai.openclaw.gateway` -(o `ai.openclaw.` al usar `--profile`/`OPENCLAW_PROFILE`; el heredado `com.openclaw.*` sigue descargándose). +La aplicación administra un LaunchAgent por usuario con la etiqueta `ai.openclaw.gateway` +(o `ai.openclaw.` cuando se usa `--profile`/`OPENCLAW_PROFILE`; el legado `com.openclaw.*` todavía se descarga). ```bash launchctl kickstart -k gui/$UID/ai.openclaw.gateway launchctl bootout gui/$UID/ai.openclaw.gateway ``` -Sustituye la etiqueta por `ai.openclaw.` cuando ejecutes un profile con nombre. +Reemplaza la etiqueta por `ai.openclaw.` cuando ejecutes un perfil con nombre. -Si el LaunchAgent no está instalado, actívalo desde la app o ejecuta +Si el LaunchAgent no está instalado, habilítalo desde la aplicación o ejecuta `openclaw gateway install`. -## Capacidades del nodo (mac) +## Capacidades del Node (mac) -La app de macOS se presenta como un nodo. Comandos habituales: +La aplicación de macOS se presenta como un Node. Comandos comunes: - Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*` -- Cámara: `camera.snap`, `camera.clip` -- Pantalla: `screen.record` +- Camera: `camera.snap`, `camera.clip` +- Pantalla: `screen.snapshot`, `screen.record` - Sistema: `system.run`, `system.notify` -El nodo informa un mapa `permissions` para que los agentes puedan decidir qué está permitido. +El Node informa un mapa `permissions` para que los agentes puedan decidir qué está permitido. -Servicio de nodo + IPC de la app: +Servicio de Node + IPC de la aplicación: -- Cuando el servicio headless de node host está en ejecución (modo remoto), se conecta al WS del Gateway como un nodo. -- `system.run` se ejecuta en la app de macOS (contexto UI/TCC) mediante un socket Unix local; los prompts y la salida permanecen en la app. +- Cuando el servicio sin interfaz del host de Node está en ejecución (modo remoto), se conecta al Gateway WS como un Node. +- `system.run` se ejecuta en la aplicación de macOS (contexto UI/TCC) a través de un socket Unix local; los avisos y la salida permanecen dentro de la aplicación. Diagrama (SCI): @@ -81,10 +81,10 @@ Gateway -> Node Service (WS) Mac App (UI + TCC + system.run) ``` -## Aprobaciones de exec (`system.run`) +## Aprobaciones de ejecución (`system.run`) -`system.run` está controlado por **Exec approvals** en la app de macOS (Settings → Exec approvals). -Security + ask + allowlist se almacenan localmente en el Mac en: +`system.run` está controlado por las **aprobaciones de ejecución** en la aplicación de macOS (Ajustes → Aprobaciones de ejecución). +La seguridad + solicitud + lista de permitidos se almacenan localmente en la Mac en: ``` ~/.openclaw/exec-approvals.json @@ -112,15 +112,15 @@ Ejemplo: Notas: - Las entradas de `allowlist` son patrones glob para rutas resueltas de binarios. -- El texto bruto del comando de shell que contiene sintaxis de control o expansión del shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) se trata como un fallo de allowlist y requiere aprobación explícita (o incluir el binario del shell en la allowlist). -- Elegir “Always Allow” en el prompt agrega ese comando a la allowlist. -- Las sobrescrituras del entorno en `system.run` se filtran (elimina `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) y luego se fusionan con el entorno de la app. -- Para wrappers de shell (`bash|sh|zsh ... -c/-lc`), las sobrescrituras del entorno con alcance de solicitud se reducen a una pequeña allowlist explícita (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -- Para decisiones de permitir siempre en modo allowlist, los wrappers de despacho conocidos (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persisten rutas internas del ejecutable en lugar de rutas del wrapper. Si el desempaquetado no es seguro, no se persiste automáticamente ninguna entrada de allowlist. +- El texto de comandos de shell sin procesar que contiene sintaxis de control o expansión del shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) se trata como una ausencia en la lista de permitidos y requiere aprobación explícita (o añadir el binario del shell a la lista de permitidos). +- Elegir “Permitir siempre” en el aviso añade ese comando a la lista de permitidos. +- Las anulaciones de entorno de `system.run` se filtran (elimina `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) y luego se fusionan con el entorno de la aplicación. +- Para envoltorios de shell (`bash|sh|zsh ... -c/-lc`), las anulaciones de entorno con alcance de solicitud se reducen a una pequeña lista de permitidos explícita (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +- Para decisiones de permitir siempre en modo de lista de permitidos, los envoltorios de despacho conocidos (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) conservan las rutas del ejecutable interno en lugar de las rutas del envoltorio. Si desenvolverlo no es seguro, no se conserva automáticamente ninguna entrada en la lista de permitidos. -## Deep links +## Enlaces profundos -La app registra el esquema de URL `openclaw://` para acciones locales. +La aplicación registra el esquema de URL `openclaw://` para acciones locales. ### `openclaw://agent` @@ -133,90 +133,90 @@ Parámetros de consulta: - `thinking` (opcional) - `deliver` / `to` / `channel` (opcional) - `timeoutSeconds` (opcional) -- `key` (opcional, clave de modo unattended) +- `key` (opcional, clave para modo no supervisado) Seguridad: -- Sin `key`, la app solicita confirmación. -- Sin `key`, la app aplica un límite corto de mensaje para el prompt de confirmación e ignora `deliver` / `to` / `channel`. -- Con una `key` válida, la ejecución es unattended (pensado para automatizaciones personales). +- Sin `key`, la aplicación solicita confirmación. +- Sin `key`, la aplicación aplica un límite corto al mensaje para el aviso de confirmación e ignora `deliver` / `to` / `channel`. +- Con una `key` válida, la ejecución no es supervisada (pensado para automatizaciones personales). -## Flujo de onboarding (típico) +## Flujo de incorporación (típico) -1. Instala e inicia **OpenClaw.app**. -2. Completa la lista de comprobación de permisos (prompts de TCC). -3. Asegúrate de que el modo **Local** esté activo y el Gateway esté en ejecución. -4. Instala la CLI si quieres acceso desde terminal. +1. Instala y abre **OpenClaw.app**. +2. Completa la lista de comprobación de permisos (avisos de TCC). +3. Asegúrate de que el modo **Local** esté activo y de que el Gateway esté en ejecución. +4. Instala la CLI si quieres acceso desde la terminal. -## Ubicación del directorio de state (macOS) +## Ubicación del directorio de estado (macOS) -Evita poner tu directorio de state de OpenClaw en iCloud u otras carpetas sincronizadas con la nube. -Las rutas respaldadas por sincronización pueden añadir latencia y ocasionalmente provocar carreras de bloqueo/sincronización de archivos para +Evita colocar el directorio de estado de OpenClaw en iCloud u otras carpetas sincronizadas con la nube. +Las rutas respaldadas por sincronización pueden añadir latencia y, ocasionalmente, provocar condiciones de carrera de bloqueo/sincronización de archivos para sesiones y credenciales. -Prefiere una ruta local no sincronizada como: +Prefiere una ruta de estado local no sincronizada, como: __OC_I18N_900005__ -Si `openclaw doctor` detecta state bajo: +Si `openclaw doctor` detecta el estado en: - `~/Library/Mobile Documents/com~apple~CloudDocs/...` - `~/Library/CloudStorage/...` -advertirá y recomendará volver a una ruta local. +mostrará una advertencia y recomendará volver a una ruta local. ## Flujo de compilación y desarrollo (nativo) - `cd apps/macos && swift build` - `swift run OpenClaw` (o Xcode) -- Empaquetar la app: `scripts/package-mac-app.sh` +- Empaquetar la aplicación: `scripts/package-mac-app.sh` -## Depurar conectividad con el gateway (CLI de macOS) +## Depurar la conectividad del Gateway (CLI de macOS) -Usa la CLI de depuración para ejercitar el mismo handshake WebSocket y la lógica de descubrimiento del Gateway -que usa la app de macOS, sin iniciar la app. +Usa la CLI de depuración para probar el mismo protocolo de enlace WebSocket del Gateway y la misma lógica de detección +que usa la aplicación de macOS, sin abrir la aplicación. __OC_I18N_900006__ Opciones de conexión: -- `--url `: sobrescribe la configuración -- `--mode `: resuelve desde la configuración (predeterminado: configuración o local) -- `--probe`: fuerza una sonda nueva de estado +- `--url `: anula la configuración +- `--mode `: resuelve desde la configuración (predeterminado: config o local) +- `--probe`: fuerza una nueva comprobación de estado - `--timeout `: tiempo de espera de la solicitud (predeterminado: `15000`) - `--json`: salida estructurada para comparar diferencias -Opciones de descubrimiento: +Opciones de detección: -- `--include-local`: incluye gateways que normalmente se filtrarían como “local” -- `--timeout `: ventana total de descubrimiento (predeterminado: `2000`) +- `--include-local`: incluye Gateways que se filtrarían como “locales” +- `--timeout `: ventana total de detección (predeterminada: `2000`) - `--json`: salida estructurada para comparar diferencias Consejo: compáralo con `openclaw gateway discover --json` para ver si la -canalización de descubrimiento de la app de macOS (`local.` más el dominio amplio configurado, con -respaldo de wide-area y Tailscale Serve) difiere del descubrimiento basado en `dns-sd` -de la CLI de Node. +canalización de detección de la aplicación de macOS (`local.` más el dominio de área amplia configurado, con +área amplia y Tailscale Serve como alternativas) +difiere de la detección basada en `dns-sd` de la CLI de Node. ## Infraestructura de conexión remota (túneles SSH) -Cuando la app de macOS se ejecuta en modo **remoto**, abre un túnel SSH para que los componentes de UI locales -puedan comunicarse con un Gateway remoto como si estuviera en localhost. +Cuando la aplicación de macOS se ejecuta en modo **Remoto**, abre un túnel SSH para que los componentes +de UI locales puedan comunicarse con un Gateway remoto como si estuviera en localhost. ### Túnel de control (puerto WebSocket del Gateway) -- **Propósito:** comprobaciones de estado, status, Web Chat, configuración y otras llamadas del plano de control. +- **Propósito:** comprobaciones de estado, estado, Web Chat, configuración y otras llamadas del plano de control. - **Puerto local:** el puerto del Gateway (predeterminado `18789`), siempre estable. - **Puerto remoto:** el mismo puerto del Gateway en el host remoto. -- **Comportamiento:** no hay puerto local aleatorio; la app reutiliza un túnel saludable existente +- **Comportamiento:** no se usa un puerto local aleatorio; la aplicación reutiliza un túnel saludable existente o lo reinicia si es necesario. - **Forma de SSH:** `ssh -N -L :127.0.0.1:` con opciones BatchMode + ExitOnForwardFailure + keepalive. -- **Informe de IP:** el túnel SSH usa loopback, así que el gateway verá la - IP del nodo como `127.0.0.1`. Usa transporte **Direct (ws/wss)** si quieres que aparezca la IP - real del cliente (consulta [acceso remoto en macOS](/platforms/mac/remote)). +- **Informe de IP:** el túnel SSH usa loopback, por lo que el gateway verá la IP del node + como `127.0.0.1`. Usa el transporte **Direct (ws/wss)** si quieres que aparezca la IP real + del cliente (consulta [acceso remoto en macOS](/es/platforms/mac/remote)). -Para los pasos de configuración, consulta [acceso remoto en macOS](/platforms/mac/remote). Para -detalles del protocolo, consulta [Gateway protocol](/gateway/protocol). +Para ver los pasos de configuración, consulta [acceso remoto en macOS](/es/platforms/mac/remote). Para detalles +del protocolo, consulta [protocolo del Gateway](/es/gateway/protocol). ## Documentación relacionada -- [Gateway runbook](/gateway) -- [Gateway (macOS)](/platforms/mac/bundled-gateway) -- [permisos de macOS](/platforms/mac/permissions) -- [Canvas](/platforms/mac/canvas) +- [Guía operativa del Gateway](/es/gateway) +- [Gateway (macOS)](/es/platforms/mac/bundled-gateway) +- [Permisos de macOS](/es/platforms/mac/permissions) +- [Canvas](/es/platforms/mac/canvas) diff --git a/docs/es/plugins/sdk-channel-plugins.md b/docs/es/plugins/sdk-channel-plugins.md index e8898acde..2138f7f54 100644 --- a/docs/es/plugins/sdk-channel-plugins.md +++ b/docs/es/plugins/sdk-channel-plugins.md @@ -1,28 +1,28 @@ --- read_when: - - Está creando un nuevo Plugin de canal de mensajería. - - Quiere conectar OpenClaw a una plataforma de mensajería. - - Necesita comprender la superficie del adaptador `ChannelPlugin`. + - Estás creando un nuevo Plugin de canal de mensajería + - Quieres conectar OpenClaw a una plataforma de mensajería + - 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 +title: Creación de Plugins de canal x-i18n: - generated_at: "2026-04-15T19:41:53Z" + generated_at: "2026-04-18T04:59:37Z" model: gpt-5.4 provider: openai - source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b + source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -# Crear Plugins de canal +# Creación de Plugins de canal -Esta guía recorre la creación de un Plugin de canal que conecta OpenClaw a una -plataforma de mensajería. Al final tendrá un canal funcional con seguridad en MD, +Esta guía recorre 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 en MD, emparejamiento, encadenamiento de respuestas y mensajería saliente. - Si todavía no ha creado ningún Plugin de OpenClaw, lea 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 manifiesto. @@ -30,85 +30,84 @@ emparejamiento, encadenamiento de respuestas y mensajería saliente. ## Cómo funcionan los Plugins de canal Los Plugins de canal no necesitan sus propias herramientas de enviar/editar/reaccionar. OpenClaw mantiene una -herramienta `message` compartida en el núcleo. Su Plugin es responsable de: +única herramienta `message` compartida en el núcleo. Tu Plugin gestiona: - **Configuración** — resolución de cuentas y asistente de configuración - **Seguridad** — política de MD y listas de permitidos - **Emparejamiento** — flujo de aprobación de MD -- **Gramática de sesión** — cómo los identificadores de conversación específicos del proveedor se asignan a chats base, identificadores de hilo y alternativas del elemento superior -- **Salida** — envío de texto, medios y encuestas a la plataforma +- **Gramática de sesión** — cómo los id. de conversación específicos del proveedor se asignan a chats base, id. de hilo y alternativas de respaldo de padre +- **Salida** — envío de texto, contenido multimedia y encuestas a la plataforma - **Encadenamiento** — cómo se encadenan las respuestas -El núcleo es responsable de la herramienta de mensajes compartida, el cableado del prompt, la forma externa de la clave de sesión, -la contabilidad genérica `:thread:` y el despacho. +El núcleo gestiona la herramienta compartida de mensajes, la conexión del prompt, la forma externa de la clave de sesión, +la contabilidad genérica de `:thread:` y el despacho. -Si su canal agrega parámetros a la herramienta de mensajes que transportan fuentes de medios, exponga esos +Si tu canal añade parámetros a la herramienta de mensajes que transportan fuentes multimedia, expón esos nombres de parámetros 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. -Prefiera devolver un mapa indexado por acción, como -`{ "set-profile": ["avatarUrl", "avatarPath"] }`, para que acciones no relacionadas no -hereden los argumentos de medios de otra acción. Un arreglo plano también funciona para parámetros que +así 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 por acción como +`{ "set-profile": ["avatarUrl", "avatarPath"] }` para que acciones no relacionadas no +hereden los argumentos multimedia de otra acción. Un arreglo plano sigue funcionando para parámetros que se comparten intencionalmente entre todas las acciones expuestas. -Si su plataforma almacena alcance adicional dentro de los identificadores de conversación, mantenga ese análisis -en el Plugin con `messaging.resolveSessionConversation(...)`. Ese es el gancho canónico para asignar -`rawId` al identificador de conversación base, identificador de hilo opcional, -`baseConversationId` explícito y cualquier `parentConversationCandidates`. -Cuando devuelva `parentConversationCandidates`, manténgalos ordenados desde el -elemento superior más específico hasta la conversación base o más amplia. +Si tu plataforma almacena alcance adicional dentro de los id. de conversación, mantén ese análisis +en el Plugin con `messaging.resolveSessionConversation(...)`. Ese es el hook canónico para mapear +`rawId` al id. base de conversación, id. opcional de hilo, `baseConversationId` +explícito y cualquier `parentConversationCandidates`. +Cuando devuelvas `parentConversationCandidates`, mantenlos ordenados desde el +padre más específico hasta la conversación base más amplia. Los Plugins incluidos que necesitan 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(...)` coincidente. El núcleo usa esa superficie segura para el arranque +`resolveSessionConversation(...)` equivalente. 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 una -alternativa heredada de compatibilidad cuando un Plugin solo necesita alternativas del elemento superior -además del identificador 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 +`messaging.resolveParentConversationCandidates(...)` sigue disponible como alternativa heredada de compatibilidad +cuando un Plugin solo necesita padres alternativos además del id. genérico/sin procesar. Si existen ambos hooks, el núcleo usa +primero `resolveSessionConversation(...).parentConversationCandidates` y solo +recurre a `resolveParentConversationCandidates(...)` cuando el hook canónico los 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 para aprobaciones. -- El núcleo es responsable de `/approve` en el mismo chat, de las cargas útiles compartidas de botones de aprobación y de la entrega genérica de respaldo. -- Prefiera un solo objeto `approvalCapability` en el Plugin del canal cuando el canal necesite comportamiento específico de aprobación. -- `ChannelPlugin.approvals` se eliminó. Coloque los datos de entrega/aprobación nativa/renderizado/autenticación en `approvalCapability`. -- `plugin.auth` es solo para login/logout; el núcleo 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 aprobación. -- Use `approvalCapability.getActionAvailabilityState` para la disponibilidad de autenticación de aprobación en el mismo chat. -- Si su canal expone aprobaciones nativas de ejecución, use `approvalCapability.getExecInitiatingSurfaceState` para el estado de la superficie iniciadora/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 del cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` completa esto para el caso común. -- Use `outbound.shouldSuppressLocalPayloadPrompt` o `outbound.beforeDeliverPayload` para el comportamiento específico del canal en el ciclo de vida de la carga útil, como ocultar prompts locales de aprobación duplicados o enviar indicadores de escritura antes de la entrega. -- Use `approvalCapability.delivery` solo para el enrutamiento de aprobaciones nativas o la supresión de respaldo. -- Use `approvalCapability.nativeRuntime` para datos de aprobación nativa que pertenezcan al canal. Manténgalo diferido en puntos de entrada críticos del canal con `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que puede importar su módulo de tiempo de ejecución bajo demanda y aun así permitir que el núcleo ensamble el ciclo de vida de aprobación. -- Use `approvalCapability.render` solo cuando un canal realmente necesite cargas útiles de aprobación personalizadas en lugar del renderizador compartido. -- Use `approvalCapability.describeExecApprovalSetup` cuando el canal quiera que la respuesta de ruta deshabilitada explique los ajustes exactos de configuración necesarios 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, use `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 núcleo. -- Si un canal necesita entrega de aprobación nativa, mantenga el código del canal enfocado en la normalización del destino más los datos de transporte/presentación. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` y `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque 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 encargarse del filtrado de solicitudes, enrutamiento, deduplicación, expiración, suscripción al Gateway y avisos de redirección. `nativeRuntime` se divide en algunas uniones más pequeñas: -- `availability` — si la cuenta está configurada y si se debe manejar una solicitud -- `presentation` — asigna el modelo de vista de aprobación compartido a cargas útiles nativas pendientes/resueltas/expiradas o acciones finales -- `transport` — prepara destinos y envía/actualiza/elimina mensajes de aprobación nativa -- `interactions` — ganchos opcionales de asociar/desasociar/borrar acción para botones o reacciones nativos -- `observe` — ganchos opcionales de diagnóstico de entrega -- Si el canal necesita objetos que pertenecen al tiempo de ejecución, como un cliente, token, app Bolt o receptor de Webhook, regístrelos mediante `openclaw/plugin-sdk/channel-runtime-context`. El registro genérico de contexto de tiempo de ejecución permite que el núcleo inicialice controladores impulsados por capacidades a partir del estado de inicio del canal sin agregar lógica de envoltura específica de aprobación. -- Recurra a `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` de nivel inferior solo cuando la unión guiada por capacidades todavía no sea lo bastante expresiva. -- Los canales de aprobación nativa deben enrutar tanto `accountId` como `approvalKind` a través de esos helpers. `accountId` mantiene la política de aprobación multicuenta dentro del alcance de la cuenta de bot correcta, y `approvalKind` mantiene disponible para el canal el comportamiento de aprobación de ejecución frente al de Plugin sin ramas codificadas en el núcleo. -- El núcleo 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 de “la aprobación fue a los MD / a otro canal” desde `createChannelNativeApprovalRuntime`; en su lugar, exponga un enrutamiento preciso del origen y del MD del aprobador mediante los helpers de capacidad de aprobación compartida y deje que el núcleo agregue las entregas reales antes de publicar cualquier aviso de vuelta en el chat iniciador. -- Preserve de extremo a extremo el tipo de identificador de aprobación entregado. Los clientes nativos no deben - inferir ni reescribir el enrutamiento de aprobación de ejecución frente al de Plugin a partir del estado local del canal. -- Distintos tipos de aprobación pueden exponer intencionalmente superficies nativas diferentes. +- El núcleo gestiona `/approve` en el mismo chat, las cargas útiles compartidas de botones de aprobación y 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 hooks de autenticación de aprobación desde ese objeto. +- `approvalCapability.authorizeActorAction` y `approvalCapability.getActionAvailabilityState` son la separación canónica para la autenticación de aprobaciones. +- Usa `approvalCapability.getActionAvailabilityState` para la disponibilidad de autenticación de aprobaciones en el mismo chat. +- Si tu canal expone aprobaciones nativas de ejecución, usa `approvalCapability.getExecInitiatingSurfaceState` para el estado de la superficie iniciadora/cliente nativo cuando difiera de la autenticación de aprobación en el mismo chat. El núcleo usa ese hook específico de ejecución para distinguir `enabled` de `disabled`, decidir si el canal iniciador admite aprobaciones nativas de ejecución e incluir el canal en la guía de respaldo del 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 útil, como ocultar prompts locales duplicados de aprobación o enviar indicadores de escritura antes de la entrega. +- Usa `approvalCapability.delivery` solo para enrutamiento de aprobaciones nativas o supresión del respaldo. +- Usa `approvalCapability.nativeRuntime` para datos nativos de aprobación gestionados por el canal. Mantenlo diferido en puntos de entrada calientes 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 útiles de aprobación personalizadas en lugar del renderizador compartido. +- Usa `approvalCapability.describeExecApprovalSetup` cuando el canal quiera que la respuesta de ruta deshabilitada explique los parámetros exactos de configuración necesarios para habilitar aprobaciones nativas de ejecución. El hook 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 de MD estables de tipo propietario a partir de la configuración existente, usa `createResolvedApproverActionAuthAdapter` desde `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` en el mismo chat sin añadir lógica de aprobación específica al núcleo. +- Si un canal necesita entrega de aprobación nativa, mantén el código del canal enfocado en la normalización del destino más los datos de transporte/presentación. Usa `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` y `createApproverRestrictedNativeApprovalCapability` desde `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 gestionar el filtrado de solicitudes, el enrutamiento, la eliminación de duplicados, la expiración, la suscripción al Gateway y los avisos de redirección. `nativeRuntime` se divide en algunas separaciones más pequeñas: +- `availability` — si la cuenta está configurada y si una solicitud debe gestionarse +- `presentation` — asigna el modelo de vista compartido de aprobación a cargas útiles nativas pendientes/resueltas/expiradas o acciones finales +- `transport` — prepara destinos más envío/actualización/eliminación de mensajes nativos de aprobación +- `interactions` — hooks opcionales para enlazar/desenlazar/borrar acciones de botones o reacciones nativas +- `observe` — hooks opcionales de diagnóstico de entrega +- Si el canal necesita objetos gestionados por el tiempo de ejecución como un cliente, token, app 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 inicialice controladores guiados por capacidades a partir del estado de arranque del canal sin añadir pegamento contenedor específico de aprobación. +- Recurre a `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` de nivel inferior solo cuando la separación guiada por capacidades todavía no sea lo bastante expresiva. +- Los canales de aprobación nativa deben enrutar tanto `accountId` como `approvalKind` a través de esos helpers. `accountId` mantiene la política de aprobación multicuenta con el alcance correcto para la cuenta del bot, y `approvalKind` mantiene disponible para el canal el comportamiento de aprobación de ejecución frente al de Plugin sin ramas codificadas en el núcleo. +- El núcleo ahora también gestiona los avisos de redirección de aprobación. Los Plugins de canal no deben enviar sus propios mensajes de seguimiento de "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 helpers compartidos de capacidad de aprobación y deja que el núcleo agregue las entregas reales antes de publicar cualquier aviso en el 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 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 de aprobación nativa tanto para identificadores 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, a la vez que 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. + - Slack mantiene disponible el enrutamiento de aprobación nativa tanto para id. de ejecución como de Plugin. + - Matrix mantiene el mismo enrutamiento nativo de MD/canal y la misma experiencia de reacciones para aprobaciones de ejecución + y de Plugin, al tiempo que sigue permitiendo que la autenticación difiera según el tipo de aprobación. +- `createApproverRestrictedNativeApprovalAdapter` sigue existiendo como contenedor de compatibilidad, pero el código nuevo debe preferir el constructor de capacidades y exponer `approvalCapability` en el Plugin. -Para puntos de entrada críticos del canal, prefiera las subrutas de tiempo de ejecución más específicas cuando solo -necesite una parte de esa familia: +Para puntos de entrada calientes del canal, prefiere las subrutas de tiempo de ejecución más estrechas cuando solo +necesites una parte de esa familia: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -120,46 +119,47 @@ necesite una parte de esa familia: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -De igual manera, prefiera `openclaw/plugin-sdk/setup-runtime`, +Del mismo modo, prefiere `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-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 necesite la superficie -paraguas más amplia. +`openclaw/plugin-sdk/reply-chunking` cuando no necesites la +superficie paraguas más amplia. Para la configuración específicamente: - `openclaw/plugin-sdk/setup-runtime` cubre los helpers de configuración seguros para tiempo de ejecución: - adaptadores de parcheo de configuración seguros para importación (`createPatchedAccountSetupAdapter`, + adaptadores de parche de configuración seguros para importación (`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 de adaptador - específica y acotada para entorno para `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/setup-adapter-runtime` es la separación estrecha de adaptador + consciente del entorno para `createEnvPatchedAccountSetupAdapter` - `openclaw/plugin-sdk/channel-setup` cubre los constructores de configuración de instalación opcional - más algunas primitivas seguras para configuración: + más algunos primitivos seguros para configuración: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Si su canal admite configuración o autenticación impulsadas por variables de 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árelos en el manifiesto del Plugin con `channelEnvVars`. Mantenga `envVars` del tiempo de ejecución del canal o constantes locales solo para el texto dirigido a operadores. +Si tu canal admite configuración o autenticación basada en variables de entorno y los flujos genéricos de inicio/configuración +deben conocer esos nombres de variables antes de que 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 +constantes locales solo para el texto dirigido al operador. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` y `splitSetupEntries` -- use la unión más amplia `openclaw/plugin-sdk/setup` solo cuando también necesite los - helpers compartidos más pesados de configuración/configuración, como +- usa la separació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 `moveSingleAccountChannelSectionToDefaultAccount(...)` -Si su canal solo quiere anunciar “instale primero este Plugin” en las -superficies de configuración, prefiera `createOptionalChannelSetupSurface(...)`. El +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 el texto -del enlace a la documentación. +el mismo mensaje de instalación requerida en la validación, finalización y texto +de enlace a la documentación. -Para otras rutas críticas del canal, prefiera los helpers específicos en lugar de las +Para otras rutas calientes del canal, prefiere los helpers estrechos en lugar de las superficies heredadas más amplias: - `openclaw/plugin-sdk/account-core`, @@ -168,52 +168,52 @@ superficies heredadas más amplias: `openclaw/plugin-sdk/account-helpers` para configuración multicuenta y respaldo de cuenta predeterminada - `openclaw/plugin-sdk/inbound-envelope` y - `openclaw/plugin-sdk/inbound-reply-dispatch` para cableado de ruta/sobre entrante y - registrar-y-despachar -- `openclaw/plugin-sdk/messaging-targets` para análisis y coincidencia de destinos + `openclaw/plugin-sdk/inbound-reply-dispatch` para el cableado de ruta/sobre de entrada y + registro y despacho +- `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 medios más delegados de identidad/envío - salientes -- `openclaw/plugin-sdk/thread-bindings-runtime` para el ciclo de vida de asociaciones de hilo + `openclaw/plugin-sdk/outbound-runtime` para carga de medios más delegados de + identidad/envío salientes +- `openclaw/plugin-sdk/thread-bindings-runtime` para el ciclo de vida de los vínculos de hilo y el registro de adaptadores -- `openclaw/plugin-sdk/agent-media-payload` solo cuando siga siendo necesario un diseño heredado de campos - de carga útil de agente/medios -- `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/agent-media-payload` solo cuando todavía se requiera una disposición heredada + de campos de carga útil de agente/medios +- `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 para respaldo -Los canales solo de autenticación normalmente pueden quedarse en la ruta predeterminada: el núcleo se encarga de 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 implementar su propio ciclo de vida de aprobación. +Los canales solo de autenticación normalmente pueden detenerse en la ruta predeterminada: el núcleo 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. ## Política de menciones entrantes -Mantenga el manejo de menciones entrantes dividido en dos capas: +Mantén el manejo de menciones entrantes dividido en dos capas: -- recopilación de evidencia que pertenece al Plugin +- recopilación de evidencias gestionada por el Plugin - evaluación de políticas compartidas -Use `openclaw/plugin-sdk/channel-inbound` para la capa compartida. +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 helpers de entrada. -Buen ajuste para lógica local del Plugin: +Buen encaje para lógica local del Plugin: - detección de respuesta al bot - detección de cita del bot -- comprobaciones de participación en el hilo +- comprobaciones de participación en hilos - exclusiones de mensajes de servicio/sistema -- cachés nativos de la plataforma necesarios para demostrar participación del bot +- cachés nativos de la plataforma necesarios para demostrar la participación del bot -Buen ajuste para el helper compartido: +Buen encaje para el helper compartido: - `requireMention` - resultado de mención explícita -- lista de permitidos de mención implícita +- lista de permitidos de menciones implícitas - omisión de comandos - decisión final de omitir -Flujo recomendado: +Flujo preferido: -1. Calcule los datos locales de mención. -2. Pase esos datos a `resolveInboundMentionDecision({ facts, policy })`. -3. Use `decision.effectiveWasMentioned`, `decision.shouldBypassMention` y `decision.shouldSkip` en su compuerta de entrada. +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 compuerta de entrada. ```typescript import { @@ -252,8 +252,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` expone los mismos helpers de mención compartidos para -los Plugins de canal incluidos que ya dependen de la inyección en tiempo de ejecución: +`api.runtime.channel.mentions` expone los mismos helpers compartidos de menciones para +los Plugins de canal incluidos que ya dependen de inyección en tiempo de ejecución: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -261,7 +261,12 @@ los Plugins de canal incluidos que ya dependen de la inyección en tiempo de eje - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -Los helpers antiguos `resolveMentionGating*` siguen estando en +Si solo necesitas `implicitMentionKindWhen` y +`resolveInboundMentionDecision`, importa desde +`openclaw/plugin-sdk/channel-mention-gating` para evitar cargar helpers de tiempo de ejecución +de entrada no relacionados. + +Los antiguos helpers `resolveMentionGating*` siguen estando en `openclaw/plugin-sdk/channel-inbound` solo como exportaciones de compatibilidad. El código nuevo debe usar `resolveInboundMentionDecision({ facts, policy })`. @@ -270,9 +275,9 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. - Cree los archivos estándar del Plugin. El campo `channel` en `package.json` es - lo que hace que este sea un Plugin de canal. Para conocer toda la superficie de metadatos del paquete, - consulte [Configuración y Setup 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 Setup del Plugin](/es/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -286,7 +291,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Connect OpenClaw to Acme Chat." + "blurb": "Conecta OpenClaw con Acme Chat." } } } @@ -298,7 +303,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Acme Chat channel plugin", + "description": "Plugin de canal de Acme Chat", "configSchema": { "type": "object", "additionalProperties": false, @@ -321,11 +326,11 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. - - La interfaz `ChannelPlugin` tiene muchas superficies de adaptador opcionales. Empiece con - lo mínimo — `id` y `setup` — y agregue adaptadores según los necesite. + + La interfaz `ChannelPlugin` tiene muchas superficies opcionales de adaptador. Comienza con + lo mínimo — `id` y `setup` — y añade adaptadores según los necesites. - Cree `src/channel.ts`: + Crea `src/channel.ts`: ```typescript src/channel.ts import { @@ -418,25 +423,25 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. }); ``` - - En lugar de implementar manualmente interfaces de adaptador de bajo nivel, usted pasa + + En lugar de implementar manualmente interfaces de adaptador de bajo nivel, pasas opciones declarativas y el constructor las compone: | Opción | Qué conecta | | --- | --- | | `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) | + | `pairing.text` | Flujo de emparejamiento por MD basado en texto con intercambio de código | + | `threading` | Resolutor del modo de respuesta (fijo, con alcance por cuenta o personalizado) | + | `outbound.attachedResults` | Funciones de envío que devuelven metadatos del resultado (id. de mensaje) | - También puede pasar objetos de adaptador sin procesar en lugar de opciones declarativas - si necesita control total. + También puedes pasar objetos de adaptador sin procesar en lugar de las opciones declarativas + si necesitas control total. - - Cree `index.ts`: + + Crea `index.ts`: ```typescript index.ts import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -471,22 +476,22 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. }); ``` - Coloque los descriptores de CLI que pertenecen al canal en `registerCliMetadata(...)` para que OpenClaw + Coloca los descriptores de CLI gestionados por el 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. Mantenga `registerFull(...)` para trabajo exclusivo de tiempo de ejecución. - Si `registerFull(...)` registra métodos RPC del Gateway, use un + mientras que las cargas completas normales sigan 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 núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) permanecen reservados y siempre - se resuelven en `operator.admin`. - `defineChannelPluginEntry` maneja automáticamente la división del modo de registro. Consulte + se resuelven a `operator.admin`. + `defineChannelPluginEntry` gestiona automáticamente la división del modo de registro. Consulta [Puntos de entrada](/es/plugins/sdk-entrypoints#definechannelpluginentry) para ver todas las opciones. - - Cree `setup-entry.ts` para carga ligera durante la incorporación: + + Crea `setup-entry.ts` para una carga ligera durante la incorporación: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -496,20 +501,20 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. ``` OpenClaw carga esto en lugar de la entrada completa cuando el canal está deshabilitado - o no está configurado. Evita cargar código pesado de tiempo de ejecución durante los flujos de configuración. - Consulte [Setup y Configuración](/es/plugins/sdk-setup#setup-entry) para más detalles. + o sin configurar. Evita cargar código pesado de tiempo de ejecución durante los flujos de configuración. + Consulta [Setup y Configuración](/es/plugins/sdk-setup#setup-entry) para más detalles. - Los canales de workspace incluidos que dividen exportaciones seguras para configuración en módulos - auxiliares pueden usar `defineBundledChannelSetupEntry(...)` de + Los canales incluidos del espacio de trabajo que dividen las exportaciones seguras para configuración en módulos + auxiliares pueden usar `defineBundledChannelSetupEntry(...)` desde `openclaw/plugin-sdk/channel-entry-contract` cuando también necesitan un - setter explícito de tiempo de ejecución para configuración. + setter explícito de tiempo de ejecución para el momento de configuración. - - Su Plugin necesita recibir mensajes de la plataforma y reenviarlos a + + Tu Plugin necesita recibir mensajes desde 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 entrante de su canal: + la despacha a través del controlador de entrada de tu canal: ```typescript registerFull(api) { @@ -533,23 +538,23 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`. ``` - El manejo de mensajes entrantes es específico de cada canal. Cada Plugin de canal es responsable de - su propia canalización de entrada. Revise los Plugins de canal incluidos - (por ejemplo, el paquete de 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 gestiona + su propia canalización de entrada. Mira los Plugins de canal incluidos + (por ejemplo, el paquete Plugin de Microsoft Teams o Google Chat) para ver patrones reales. -Escriba pruebas colocadas junto al código 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("acme-chat plugin", () => { - it("resolves account from config", () => { + describe("plugin acme-chat", () => { + it("resuelve la cuenta desde la configuración", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -559,7 +564,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`: expect(account.token).toBe("test-token"); }); - it("inspects account without materializing secrets", () => { + it("inspecciona la cuenta sin materializar secretos", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -568,7 +573,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`: expect(result.tokenStatus).toBe("available"); }); - it("reports missing config", () => { + it("informa de configuración faltante", () => { const cfg = { channels: {} } as any; const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined); expect(result.configured).toBe(false); @@ -580,7 +585,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`: pnpm test -- /acme-chat/ ``` - Para los helpers de prueba compartidos, consulte [Pruebas](/es/plugins/sdk-testing). + Para los helpers de pruebas compartidos, consulta [Pruebas](/es/plugins/sdk-testing). @@ -589,17 +594,17 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`: ``` /acme-chat/ -├── package.json # openclaw.channel metadata -├── openclaw.plugin.json # Manifest with config schema +├── package.json # metadatos de openclaw.channel +├── openclaw.plugin.json # Manifiesto con esquema de configuración ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Public exports (optional) -├── runtime-api.ts # Internal runtime exports (optional) +├── api.ts # Exportaciones públicas (opcional) +├── runtime-api.ts # Exportaciones internas de tiempo de ejecución (opcional) └── src/ - ├── channel.ts # ChannelPlugin via createChatChannelPlugin - ├── channel.test.ts # Tests - ├── client.ts # Platform API client - └── runtime.ts # Runtime store (if needed) + ├── channel.ts # ChannelPlugin mediante createChatChannelPlugin + ├── channel.test.ts # Pruebas + ├── client.ts # Cliente API de la plataforma + └── runtime.ts # Almacén de tiempo de ejecución (si es necesario) ``` ## Temas avanzados @@ -608,7 +613,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`: Modos de respuesta fijos, con alcance por cuenta o personalizados - + describeMessageTool y descubrimiento de acciones @@ -620,15 +625,15 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`: -Algunas uniones auxiliares incluidas siguen existiendo para el mantenimiento y la -compatibilidad de Plugins incluidos. No son el patrón recomendado para nuevos Plugins de canal; -prefiera las subrutas genéricas de canal/configuración/respuesta/tiempo de ejecución de la superficie común del SDK -a menos que esté manteniendo directamente esa familia de Plugins incluidos. +Todavía existen algunas separaciones auxiliares incluidas 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 +salvo que estés manteniendo directamente esa familia de Plugins incluidos. ## Siguientes pasos -- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — si su Plugin también proporciona modelos +- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — si tu Plugin también proporciona modelos - [Resumen 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 - [Manifiesto del Plugin](/es/plugins/manifest) — esquema completo del manifiesto diff --git a/docs/es/plugins/sdk-overview.md b/docs/es/plugins/sdk-overview.md index 9a6abc68a..d2188ce76 100644 --- a/docs/es/plugins/sdk-overview.md +++ b/docs/es/plugins/sdk-overview.md @@ -1,28 +1,28 @@ --- read_when: - Necesitas saber desde qué subruta del SDK importar - - Quieres una referencia de todos los métodos de registro en `OpenClawPluginApi` + - Quieres una referencia de todos los métodos de registro en OpenClawPluginApi - Estás buscando una exportación específica del SDK sidebarTitle: SDK Overview summary: Mapa de importación, referencia de la API de registro y arquitectura del SDK -title: Descripción general del SDK de Plugin +title: Resumen del SDK de Plugin x-i18n: - generated_at: "2026-04-17T05:13:51Z" + generated_at: "2026-04-18T04:59:38Z" model: gpt-5.4 provider: openai - source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a + source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331 source_path: plugins/sdk-overview.md workflow: 15 --- -# Descripción general del SDK de Plugin +# Resumen del SDK de Plugin -El SDK de plugin es el contrato tipado entre los plugins y el núcleo. Esta página es la +El SDK de Plugin es el contrato tipado entre los plugins y el núcleo. Esta página es la referencia para **qué importar** y **qué puedes registrar**. **¿Buscas una guía práctica?** - - ¿Primer plugin? Empieza con [Primeros pasos](/es/plugins/building-plugins) + - ¿Tu primer plugin? Empieza con [Primeros pasos](/es/plugins/building-plugins) - ¿Plugin de canal? Consulta [Plugins de canal](/es/plugins/sdk-channel-plugins) - ¿Plugin de proveedor? Consulta [Plugins de proveedor](/es/plugins/sdk-provider-plugins) @@ -37,43 +37,43 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Cada subruta es un módulo pequeño y autocontenido. Esto mantiene un inicio rápido y -evita problemas de dependencias circulares. Para los helpers de entrada/compilación específicos -de canal, prefiere `openclaw/plugin-sdk/channel-core`; reserva `openclaw/plugin-sdk/core` para -la superficie paraguas más amplia y los helpers compartidos como +evita problemas de dependencia circular. Para los helpers de entrada/construcción específicos de canal, +prefiere `openclaw/plugin-sdk/channel-core`; reserva `openclaw/plugin-sdk/core` para +la superficie paraguas más amplia y los helpers compartidos, como `buildChannelConfigSchema`. -No agregues ni dependas de interfaces de conveniencia nombradas por proveedor como +No añadas ni dependas de superficies de conveniencia con nombre de proveedor como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de -interfaces helper con marca de canal. Los plugins incluidos deberían componer subrutas -genéricas del SDK dentro de sus propios barrels `api.ts` o `runtime-api.ts`, y el núcleo -debería usar esos barrels locales del plugin o agregar un contrato genérico y estrecho del SDK -cuando la necesidad sea realmente entre canales. +superficies helper con marca de canal. Los plugins empaquetados deben componer +subrutas genéricas del SDK dentro de sus propios barrels `api.ts` o `runtime-api.ts`, y el núcleo +debe usar esos barrels locales del plugin o añadir un contrato SDK genérico y estrecho +cuando la necesidad sea realmente transversal a varios canales. -El mapa de exportación generado todavía contiene un pequeño conjunto de interfaces helper -de plugins incluidos, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +El mapa de exportación generado todavía contiene un pequeño conjunto de +superficies helper de plugins empaquetados como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` y `plugin-sdk/matrix*`. Esas -subrutas existen solo para el mantenimiento y la compatibilidad de plugins incluidos; se +subrutas existen solo para mantenimiento y compatibilidad de plugins empaquetados; se omiten intencionalmente de la tabla común de abajo y no son la ruta de importación recomendada para nuevos plugins de terceros. ## Referencia de subrutas Las subrutas más usadas habitualmente, agrupadas por propósito. La lista completa generada de -más de 200 subrutas se encuentra en `scripts/lib/plugin-sdk-entrypoints.json`. +más de 200 subrutas vive en `scripts/lib/plugin-sdk-entrypoints.json`. -Las subrutas helper reservadas para plugins incluidos siguen apareciendo en esa lista generada. +Las subrutas helper reservadas para plugins empaquetados siguen apareciendo en esa lista generada. Trátalas como superficies de detalle de implementación/compatibilidad a menos que una página de documentación -promocione explícitamente una como pública. +promueva explícitamente una como pública. -### Entrada de plugin +### Entrada de Plugin -| Subruta | Exportaciones clave | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | -| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| Subruta | Exportaciones clave | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | @@ -82,273 +82,287 @@ promocione explícitamente una como pública. | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Exportación del esquema Zod raíz de `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, además de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Helpers compartidos del asistente de configuración, prompts de allowlist, constructores de estado de configuración | + | `plugin-sdk/setup` | Helpers compartidos para asistentes de configuración, prompts de allowlist y constructores de estado de configuración | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helpers de configuración/puerta de acciones para múltiples cuentas, helpers de fallback de cuenta predeterminada | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalización de ID de cuenta | - | `plugin-sdk/account-resolution` | Helpers de búsqueda de cuentas y fallback predeterminado | - | `plugin-sdk/account-helpers` | Helpers acotados de lista de cuentas/acciones de cuenta | + | `plugin-sdk/account-core` | Helpers de compuertas de acción/configuración para múltiples cuentas, y helpers de fallback de cuenta predeterminada | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalización de id de cuenta | + | `plugin-sdk/account-resolution` | Helpers de búsqueda de cuenta + fallback predeterminado | + | `plugin-sdk/account-helpers` | Helpers específicos para lista de cuentas/acciones de cuenta | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Tipos de esquema de configuración de canal | - | `plugin-sdk/telegram-command-config` | Helpers de normalización/validación de comandos personalizados de Telegram con fallback de contrato incluido | + | `plugin-sdk/telegram-command-config` | Helpers de normalización/validación de comandos personalizados de Telegram con fallback de contrato empaquetado | + | `plugin-sdk/command-gating` | Helpers específicos para compuertas de autorización de comandos | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helpers compartidos de enrutamiento entrante y construcción de sobres | + | `plugin-sdk/inbound-envelope` | Helpers compartidos para rutas de entrada + construcción de sobres | | `plugin-sdk/inbound-reply-dispatch` | Helpers compartidos para registrar y despachar entradas | - | `plugin-sdk/messaging-targets` | Helpers de análisis/coincidencia de objetivos | - | `plugin-sdk/outbound-media` | Helpers compartidos de carga de medios salientes | - | `plugin-sdk/outbound-runtime` | Helpers de identidad saliente y delegado de envío | - | `plugin-sdk/thread-bindings-runtime` | Helpers de adaptador y ciclo de vida de vinculaciones de hilos | + | `plugin-sdk/messaging-targets` | Helpers de análisis/coincidencia de destinos | + | `plugin-sdk/outbound-media` | Helpers compartidos para carga de medios salientes | + | `plugin-sdk/outbound-runtime` | Helpers de delegación de envío/identidad saliente | + | `plugin-sdk/poll-runtime` | Helpers específicos de normalización de encuestas | + | `plugin-sdk/thread-bindings-runtime` | Helpers para el ciclo de vida de vinculaciones de hilos y adaptadores | | `plugin-sdk/agent-media-payload` | Constructor heredado de payload de medios del agente | - | `plugin-sdk/conversation-runtime` | Helpers de conversación/vinculación de hilos, emparejamiento y vinculaciones configuradas | - | `plugin-sdk/runtime-config-snapshot` | Helper de instantánea de configuración en tiempo de ejecución | - | `plugin-sdk/runtime-group-policy` | Helpers de resolución de políticas de grupo en tiempo de ejecución | - | `plugin-sdk/channel-status` | Helpers compartidos de instantánea/resumen de estado de canal | - | `plugin-sdk/channel-config-primitives` | Primitivas acotadas de esquema de configuración de canal | - | `plugin-sdk/channel-config-writes` | Helpers de autorización de escritura de configuración de canal | - | `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas de plugins de canal | + | `plugin-sdk/conversation-runtime` | Helpers para vinculaciones de conversación/hilo, pairing y binding configurado | + | `plugin-sdk/runtime-config-snapshot` | Helper de instantánea de configuración de runtime | + | `plugin-sdk/runtime-group-policy` | Helpers de resolución de políticas de grupo en runtime | + | `plugin-sdk/channel-status` | Helpers compartidos para instantáneas/resúmenes de estado del canal | + | `plugin-sdk/channel-config-primitives` | Primitivas específicas de esquema de configuración de canal | + | `plugin-sdk/channel-config-writes` | Helpers de autorización para escritura de configuración de canal | + | `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas para plugins de canal | | `plugin-sdk/allowlist-config-edit` | Helpers de lectura/edición de configuración de allowlist | - | `plugin-sdk/group-access` | Helpers compartidos de decisión de acceso a grupos | - | `plugin-sdk/direct-dm` | Helpers compartidos de autenticación/protección para mensajes directos | + | `plugin-sdk/group-access` | Helpers compartidos para decisiones de acceso a grupos | + | `plugin-sdk/direct-dm` | Helpers compartidos de autenticación/protección para DM directos | | `plugin-sdk/interactive-runtime` | Helpers de normalización/reducción de payloads de respuesta interactiva | - | `plugin-sdk/channel-inbound` | Helpers de debounce de entrada, coincidencia de menciones, política de menciones y sobres | + | `plugin-sdk/channel-inbound` | Barrel de compatibilidad para debounce de entrada, coincidencia de menciones, helpers de política de menciones y helpers de sobres | + | `plugin-sdk/channel-mention-gating` | Helpers específicos de política de menciones sin la superficie más amplia de runtime de entrada | + | `plugin-sdk/channel-location` | Helpers de contexto y formato de ubicación del canal | + | `plugin-sdk/channel-logging` | Helpers de registro del canal para descartes de entrada y fallos de typing/ack | | `plugin-sdk/channel-send-result` | Tipos de resultado de respuesta | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Helpers de análisis/coincidencia de objetivos | + | `plugin-sdk/channel-targets` | Helpers de análisis/coincidencia de destinos | | `plugin-sdk/channel-contract` | Tipos de contrato de canal | - | `plugin-sdk/channel-feedback` | Integración de feedback/reacciones | - | `plugin-sdk/channel-secret-runtime` | Helpers acotados de contrato de secretos como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` y tipos de destino de secretos | + | `plugin-sdk/channel-feedback` | Cableado de feedback/reacciones | + | `plugin-sdk/channel-secret-runtime` | Helpers específicos de contrato de secretos, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, y tipos de destino de secretos | | Subruta | Exportaciones clave | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helpers curados de configuración de proveedores locales/autohospedados | - | `plugin-sdk/self-hosted-provider-setup` | Helpers enfocados de configuración de proveedores autohospedados compatibles con OpenAI | - | `plugin-sdk/cli-backend` | Valores predeterminados del backend de CLI y constantes de watchdog | - | `plugin-sdk/provider-auth-runtime` | Helpers de resolución de claves API en tiempo de ejecución para plugins de proveedor | - | `plugin-sdk/provider-auth-api-key` | Helpers de onboarding/escritura de perfiles de clave API como `upsertApiKeyProfile` | + | `plugin-sdk/provider-setup` | Helpers de configuración seleccionados para proveedores locales/autohospedados | + | `plugin-sdk/self-hosted-provider-setup` | Helpers específicos de configuración para proveedores autohospedados compatibles con OpenAI | + | `plugin-sdk/cli-backend` | Valores predeterminados del backend de CLI + constantes watchdog | + | `plugin-sdk/provider-auth-runtime` | Helpers de runtime para resolución de claves API en plugins de proveedor | + | `plugin-sdk/provider-auth-api-key` | Helpers de incorporación/escritura de perfiles de claves API como `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | Constructor estándar de resultados de autenticación OAuth | - | `plugin-sdk/provider-auth-login` | Helpers interactivos compartidos de inicio de sesión para plugins de proveedor | + | `plugin-sdk/provider-auth-login` | Helpers compartidos de inicio de sesión interactivo para plugins de proveedor | | `plugin-sdk/provider-env-vars` | Helpers de búsqueda de variables de entorno de autenticación del proveedor | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, helpers de endpoint de proveedor y helpers de normalización de ID de modelo como `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, helpers de endpoint del proveedor y helpers de normalización de id de modelo como `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helpers genéricos de capacidad HTTP/endpoint de proveedor | - | `plugin-sdk/provider-web-fetch-contract` | Helpers acotados de contrato de configuración/selección de web-fetch como `enablePluginInConfig` y `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helpers de registro/caché de proveedor web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helpers acotados de configuración/credenciales de búsqueda web para proveedores que no necesitan integración de habilitación de plugin | - | `plugin-sdk/provider-web-search-contract` | Helpers acotados de contrato de configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance | - | `plugin-sdk/provider-web-search` | Helpers de registro/caché/tiempo de ejecución de proveedor de búsqueda web | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza de esquemas Gemini y diagnósticos, y helpers de compatibilidad de xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Helpers genéricos de HTTP/capacidades de endpoint del proveedor | + | `plugin-sdk/provider-web-fetch-contract` | Helpers específicos de contrato para configuración/selección de web-fetch, como `enablePluginInConfig` y `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Helpers de registro/caché para proveedores web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helpers específicos de configuración/credenciales de búsqueda web para proveedores que no necesitan cableado de habilitación del plugin | + | `plugin-sdk/provider-web-search-contract` | Helpers específicos de contrato para configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance | + | `plugin-sdk/provider-web-search` | Helpers de registro/caché/runtime para proveedores de búsqueda web | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquema Gemini, y helpers de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` y similares | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de streams y helpers compartidos de wrapper para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Helpers de parcheo de configuración de onboarding | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream y helpers compartidos de wrapper para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Helpers de parcheo de configuración de incorporación | | `plugin-sdk/global-singleton` | Helpers de singleton/mapa/caché locales al proceso | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registro de comandos, helpers de autorización del remitente | - | `plugin-sdk/command-status` | Constructores de mensajes de comandos/ayuda como `buildCommandsMessagePaginated` y `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Helpers de resolución de aprobadores y autenticación de acciones en el mismo chat | - | `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprobación de ejecución nativa | - | `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidad/entrega de aprobación | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers del registro de comandos, helpers de autorización de remitente | + | `plugin-sdk/command-status` | Constructores de mensajes de comando/ayuda como `buildCommandsMessagePaginated` y `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Helpers de resolución de aprobadores y de autenticación de acciones en el mismo chat | + | `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprobación para exec nativo | + | `plugin-sdk/approval-delivery-runtime` | Adaptadores de capacidad/entrega de aprobación nativa | | `plugin-sdk/approval-gateway-runtime` | Helper compartido de resolución de Gateway de aprobación | - | `plugin-sdk/approval-handler-adapter-runtime` | Helpers ligeros de carga de adaptadores de aprobación nativa para puntos de entrada de canal críticos | - | `plugin-sdk/approval-handler-runtime` | Helpers más amplios de tiempo de ejecución del manejador de aprobación; prefiere las interfaces más acotadas de adaptador/Gateway cuando sean suficientes | - | `plugin-sdk/approval-native-runtime` | Helpers nativos de objetivo de aprobación y vinculación de cuenta | - | `plugin-sdk/approval-reply-runtime` | Helpers de payload de respuesta para aprobaciones de ejecución/plugin | - | `plugin-sdk/command-auth-native` | Helpers de autenticación de comandos nativos y de objetivos de sesión nativa | + | `plugin-sdk/approval-handler-adapter-runtime` | Helpers ligeros de carga de adaptadores de aprobación nativa para entrypoints de canal de alta frecuencia | + | `plugin-sdk/approval-handler-runtime` | Helpers más amplios de runtime para manejadores de aprobación; prefiere las superficies más específicas de adaptador/Gateway cuando sean suficientes | + | `plugin-sdk/approval-native-runtime` | Helpers nativos de destino de aprobación + binding de cuenta | + | `plugin-sdk/approval-reply-runtime` | Helpers de payload de respuesta para aprobación de exec/plugin | + | `plugin-sdk/command-auth-native` | Helpers de autenticación de comandos nativos + de destino de sesión nativa | | `plugin-sdk/command-detection` | Helpers compartidos de detección de comandos | - | `plugin-sdk/command-surface` | Helpers de normalización del cuerpo del comando y de superficie de comando | + | `plugin-sdk/command-surface` | Helpers de normalización del cuerpo del comando y de la superficie de comandos | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Helpers acotados de recopilación de contratos de secretos para superficies de secretos de canal/plugin | - | `plugin-sdk/secret-ref-runtime` | Helpers acotados de `coerceSecretRef` y tipado de SecretRef para el análisis de contrato/configuración de secretos | - | `plugin-sdk/security-runtime` | Helpers compartidos de confianza, restricción de mensajes directos, contenido externo y recopilación de secretos | - | `plugin-sdk/ssrf-policy` | Helpers de política SSRF para allowlist de hosts y red privada | - | `plugin-sdk/ssrf-runtime` | Helpers de despachador fijado, `fetch` protegido por SSRF y política SSRF | - | `plugin-sdk/secret-input` | Helpers de análisis de entrada de secretos | - | `plugin-sdk/webhook-ingress` | Helpers de solicitud/objetivo de Webhook | + | `plugin-sdk/channel-secret-runtime` | Helpers específicos de recopilación de contratos de secretos para superficies de secretos de canal/plugin | + | `plugin-sdk/secret-ref-runtime` | Helpers específicos de tipado de `coerceSecretRef` y SecretRef para análisis de contrato/configuración de secretos | + | `plugin-sdk/security-runtime` | Helpers compartidos de confianza, compuerta de DM, contenido externo y recopilación de secretos | + | `plugin-sdk/ssrf-policy` | Helpers de allowlist de hosts y de política SSRF de red privada | + | `plugin-sdk/ssrf-dispatcher` | Helpers específicos de dispatcher fijado sin la amplia superficie de runtime de infraestructura | + | `plugin-sdk/ssrf-runtime` | Helpers de dispatcher fijado, fetch protegido contra SSRF y política SSRF | + | `plugin-sdk/secret-input` | Helpers de análisis de entrada secreta | + | `plugin-sdk/webhook-ingress` | Helpers de solicitud/destino de Webhook | | `plugin-sdk/webhook-request-guards` | Helpers de tamaño de cuerpo/timeout de solicitud | - + | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/runtime` | Helpers amplios de tiempo de ejecución, logging, respaldo e instalación de plugins | - | `plugin-sdk/runtime-env` | Helpers acotados de entorno de ejecución, logger, timeout, reintento y backoff | - | `plugin-sdk/channel-runtime-context` | Helpers genéricos de registro y búsqueda de contexto de tiempo de ejecución de canal | + | `plugin-sdk/runtime` | Helpers amplios de runtime/logging/copias de seguridad/instalación de plugins | + | `plugin-sdk/runtime-env` | Helpers específicos de entorno de runtime, logger, timeout, retry y backoff | + | `plugin-sdk/channel-runtime-context` | Helpers genéricos de registro y búsqueda de contexto de runtime de canal | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Helpers compartidos de comandos, hooks, HTTP e interacción del plugin | - | `plugin-sdk/hook-runtime` | Helpers compartidos del pipeline de Webhook y hooks internos | - | `plugin-sdk/lazy-runtime` | Helpers de importación/vinculación lazy en tiempo de ejecución como `createLazyRuntimeModule`, `createLazyRuntimeMethod` y `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | Helpers compartidos de plugin para comandos/hooks/http/interactivos | + | `plugin-sdk/hook-runtime` | Helpers compartidos del pipeline de hooks internos/Webhook | + | `plugin-sdk/lazy-runtime` | Helpers de importación/binding diferido de runtime como `createLazyRuntimeModule`, `createLazyRuntimeMethod` y `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Helpers de ejecución de procesos | | `plugin-sdk/cli-runtime` | Helpers de formato, espera y versión de CLI | - | `plugin-sdk/gateway-runtime` | Helpers del cliente de Gateway y de parcheo de estado del canal | + | `plugin-sdk/gateway-runtime` | Helpers de cliente de Gateway y de parche de estado del canal | | `plugin-sdk/config-runtime` | Helpers de carga/escritura de configuración | - | `plugin-sdk/telegram-command-config` | Normalización de nombres/descripciones de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato incluida de Telegram no está disponible | - | `plugin-sdk/approval-runtime` | Helpers de aprobación de ejecución/plugin, constructores de capacidad de aprobación, helpers de autenticación/perfil, helpers nativos de enrutamiento/tiempo de ejecución | - | `plugin-sdk/reply-runtime` | Helpers compartidos de tiempo de ejecución para entrada/respuesta, fragmentación, despacho, Heartbeat, planificador de respuestas | - | `plugin-sdk/reply-dispatch-runtime` | Helpers acotados de despacho/finalización de respuestas | + | `plugin-sdk/telegram-command-config` | Helpers de normalización de nombre/descripción de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato empaquetada de Telegram no está disponible | + | `plugin-sdk/text-autolink-runtime` | Detección de autolinks de referencias de archivo sin el amplio barrel `text-runtime` | + | `plugin-sdk/approval-runtime` | Helpers de aprobación de exec/plugin, constructores de capacidad de aprobación, helpers de auth/perfil, helpers de routing/runtime nativo | + | `plugin-sdk/reply-runtime` | Helpers compartidos de runtime de entrada/respuesta, chunking, despacho, Heartbeat, planificador de respuestas | + | `plugin-sdk/reply-dispatch-runtime` | Helpers específicos de despacho/finalización de respuestas | | `plugin-sdk/reply-history` | Helpers compartidos de historial de respuestas de ventana corta como `buildHistoryContext`, `recordPendingHistoryEntry` y `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helpers acotados de fragmentación de texto/Markdown | - | `plugin-sdk/session-store-runtime` | Helpers de ruta de almacenamiento de sesiones y `updated-at` | - | `plugin-sdk/state-paths` | Helpers de ruta para directorios de estado/OAuth | - | `plugin-sdk/routing` | Helpers de ruta/clave de sesión/vinculación de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helpers compartidos de resumen de estado de canal/cuenta, valores predeterminados del estado de ejecución y helpers de metadatos de incidencias | - | `plugin-sdk/target-resolver-runtime` | Helpers compartidos de resolución de objetivos | + | `plugin-sdk/reply-chunking` | Helpers específicos de fragmentación de texto/markdown | + | `plugin-sdk/session-store-runtime` | Helpers de ruta de almacenamiento de sesión + updated-at | + | `plugin-sdk/state-paths` | Helpers de rutas de directorio de estado/OAuth | + | `plugin-sdk/routing` | Helpers de ruta/clave de sesión/binding de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Helpers compartidos de resumen de estado de canal/cuenta, valores predeterminados de estado de runtime y helpers de metadatos de incidencias | + | `plugin-sdk/target-resolver-runtime` | Helpers compartidos de resolución de destino | | `plugin-sdk/string-normalization-runtime` | Helpers de normalización de slug/cadenas | - | `plugin-sdk/request-url` | Extrae URL de cadena de entradas tipo fetch/solicitud | + | `plugin-sdk/request-url` | Extraer URL de cadena de entradas tipo fetch/request | | `plugin-sdk/run-command` | Ejecutor de comandos temporizado con resultados normalizados de stdout/stderr | - | `plugin-sdk/param-readers` | Lectores comunes de parámetros de herramientas/CLI | - | `plugin-sdk/tool-payload` | Extrae payloads normalizados de objetos de resultado de herramientas | - | `plugin-sdk/tool-send` | Extrae campos canónicos de objetivo de envío desde argumentos de herramientas | + | `plugin-sdk/param-readers` | Lectores comunes de parámetros de herramienta/CLI | + | `plugin-sdk/tool-payload` | Extraer payloads normalizados de objetos de resultado de herramientas | + | `plugin-sdk/tool-send` | Extraer campos de destino de envío canónicos de argumentos de herramienta | | `plugin-sdk/temp-path` | Helpers compartidos de rutas temporales de descarga | | `plugin-sdk/logging-core` | Helpers de logger de subsistema y redacción | - | `plugin-sdk/markdown-table-runtime` | Helpers de modo de tablas Markdown | - | `plugin-sdk/json-store` | Helpers pequeños de lectura/escritura de estado JSON | - | `plugin-sdk/file-lock` | Helpers de bloqueo de archivos reentrantes | - | `plugin-sdk/persistent-dedupe` | Helpers de caché de desduplicación respaldada en disco | - | `plugin-sdk/acp-runtime` | Helpers de tiempo de ejecución/sesión de ACP y de despacho de respuestas | - | `plugin-sdk/agent-config-primitives` | Primitivas acotadas del esquema de configuración de tiempo de ejecución del agente | + | `plugin-sdk/markdown-table-runtime` | Helpers de modo de tabla Markdown | + | `plugin-sdk/json-store` | Pequeños helpers de lectura/escritura de estado JSON | + | `plugin-sdk/file-lock` | Helpers de bloqueo de archivos reentrante | + | `plugin-sdk/persistent-dedupe` | Helpers de caché de deduplicación respaldada por disco | + | `plugin-sdk/acp-runtime` | Helpers de runtime/sesión ACP y despacho de respuestas | + | `plugin-sdk/acp-binding-resolve-runtime` | Resolución de binding ACP de solo lectura sin importaciones de inicio del ciclo de vida | + | `plugin-sdk/agent-config-primitives` | Primitivas específicas de esquema de configuración de runtime del agente | | `plugin-sdk/boolean-param` | Lector flexible de parámetros booleanos | - | `plugin-sdk/dangerous-name-runtime` | Helpers de resolución de coincidencias de nombres peligrosos | - | `plugin-sdk/device-bootstrap` | Helpers de bootstrap de dispositivo y token de emparejamiento | + | `plugin-sdk/dangerous-name-runtime` | Helpers de resolución de coincidencia de nombres peligrosos | + | `plugin-sdk/device-bootstrap` | Helpers de bootstrap del dispositivo y token de pairing | | `plugin-sdk/extension-shared` | Primitivas helper compartidas para canal pasivo, estado y proxy ambiental | - | `plugin-sdk/models-provider-runtime` | Helpers del comando `/models` y de respuesta de proveedor | + | `plugin-sdk/models-provider-runtime` | Helpers de respuesta de proveedor/comando `/models` | | `plugin-sdk/skill-commands-runtime` | Helpers de listado de comandos de Skills | - | `plugin-sdk/native-command-registry` | Helpers nativos de registro/creación/serialización de comandos | - | `plugin-sdk/agent-harness` | Superficie experimental de plugin confiable para harnesses de agente de bajo nivel: tipos de harness, helpers de dirección/abortado de ejecución activa, helpers del puente de herramientas de OpenClaw y utilidades de resultados de intentos | + | `plugin-sdk/native-command-registry` | Helpers de registro/construcción/serialización de comandos nativos | + | `plugin-sdk/agent-harness` | Superficie experimental de plugin confiable para harnesses de agente de bajo nivel: tipos de harness, helpers de steering/abort de ejecución activa, helpers de puente de herramientas de OpenClaw y utilidades de resultados de intentos | | `plugin-sdk/provider-zai-endpoint` | Helpers de detección de endpoint de Z.A.I | | `plugin-sdk/infra-runtime` | Helpers de eventos del sistema/Heartbeat | - | `plugin-sdk/collection-runtime` | Helpers pequeños de caché acotada | - | `plugin-sdk/diagnostic-runtime` | Helpers de marcas y eventos de diagnóstico | - | `plugin-sdk/error-runtime` | Helpers de grafo de errores, formato, clasificación compartida de errores, `isApprovalNotFoundError` | + | `plugin-sdk/collection-runtime` | Pequeños helpers de caché acotada | + | `plugin-sdk/diagnostic-runtime` | Helpers de flags y eventos de diagnóstico | + | `plugin-sdk/error-runtime` | Grafo de errores, formato, helpers compartidos de clasificación de errores, `isApprovalNotFoundError` | | `plugin-sdk/fetch-runtime` | Helpers de fetch envuelto, proxy y búsqueda fijada | - | `plugin-sdk/host-runtime` | Helpers de normalización de hostname y host SCP | - | `plugin-sdk/retry-runtime` | Helpers de configuración y ejecución de reintentos | - | `plugin-sdk/agent-runtime` | Helpers de directorio/identidad/workspace del agente | - | `plugin-sdk/directory-runtime` | Consulta/desduplicación de directorios respaldada por configuración | + | `plugin-sdk/runtime-fetch` | Fetch de runtime con reconocimiento de dispatcher sin importaciones de proxy/fetch protegido | + | `plugin-sdk/response-limit-runtime` | Lector acotado del cuerpo de la respuesta sin la amplia superficie de runtime de medios | + | `plugin-sdk/session-binding-runtime` | Estado actual del binding de conversación sin routing de binding configurado ni almacenes de pairing | + | `plugin-sdk/session-store-runtime` | Helpers de lectura del almacenamiento de sesión sin importaciones amplias de escritura/mantenimiento de configuración | + | `plugin-sdk/context-visibility-runtime` | Resolución de visibilidad de contexto y filtrado de contexto suplementario sin importaciones amplias de configuración/seguridad | + | `plugin-sdk/string-coerce-runtime` | Helpers específicos de coerción y normalización de cadenas/registros primitivos sin importaciones de markdown/logging | + | `plugin-sdk/host-runtime` | Helpers de hostname y normalización de host SCP | + | `plugin-sdk/retry-runtime` | Helpers de configuración de retry y ejecutor de retry | + | `plugin-sdk/agent-runtime` | Helpers de directorio/identidad/espacio de trabajo del agente | + | `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorio respaldada por configuración | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/media-runtime` | Helpers compartidos para obtener/transformar/almacenar medios, además de constructores de payload de medios | - | `plugin-sdk/media-generation-runtime` | Helpers compartidos de failover de generación de medios, selección de candidatos y mensajes de modelo faltante | - | `plugin-sdk/media-understanding` | Tipos de proveedor para comprensión de medios, además de exportaciones helper orientadas al proveedor para imagen/audio | - | `plugin-sdk/text-runtime` | Helpers compartidos de texto/Markdown/logging como eliminación de texto visible para el asistente, helpers de renderizado/fragmentación/tablas Markdown, helpers de redacción, helpers de etiquetas de directivas y utilidades de texto seguro | + | `plugin-sdk/media-runtime` | Helpers compartidos de fetch/transformación/almacenamiento de medios, además de constructores de payload de medios | + | `plugin-sdk/media-generation-runtime` | Helpers compartidos de failover de generación de medios, selección de candidatos y mensajería de modelo faltante | + | `plugin-sdk/media-understanding` | Tipos de proveedor de comprensión de medios, además de exportaciones helper orientadas al proveedor para imagen/audio | + | `plugin-sdk/text-runtime` | Helpers compartidos de texto/markdown/logging como eliminación de texto visible para el asistente, helpers de render/chunking/tabla Markdown, helpers de redacción, helpers de etiquetas de directivas y utilidades de texto seguro | | `plugin-sdk/text-chunking` | Helper de fragmentación de texto saliente | - | `plugin-sdk/speech` | Tipos de proveedor de voz, además de helpers orientados al proveedor para directivas, registro y validación | - | `plugin-sdk/speech-core` | Helpers compartidos de tipos de proveedor de voz, registro, directivas y normalización | + | `plugin-sdk/speech` | Tipos de proveedor de speech, además de helpers orientados al proveedor para directivas, registro y validación | + | `plugin-sdk/speech-core` | Tipos compartidos de proveedor de speech, helpers de registro, directivas y normalización | | `plugin-sdk/realtime-transcription` | Tipos de proveedor de transcripción en tiempo real y helpers de registro | | `plugin-sdk/realtime-voice` | Tipos de proveedor de voz en tiempo real y helpers de registro | | `plugin-sdk/image-generation` | Tipos de proveedor de generación de imágenes | - | `plugin-sdk/image-generation-core` | Helpers compartidos de tipos de generación de imágenes, failover, autenticación y registro | - | `plugin-sdk/music-generation` | Tipos de proveedor/solicitud/resultado para generación musical | - | `plugin-sdk/music-generation-core` | Helpers compartidos de tipos de generación musical, failover, búsqueda de proveedores y análisis de model-ref | - | `plugin-sdk/video-generation` | Tipos de proveedor/solicitud/resultado para generación de video | - | `plugin-sdk/video-generation-core` | Helpers compartidos de tipos de generación de video, failover, búsqueda de proveedores y análisis de model-ref | - | `plugin-sdk/webhook-targets` | Helpers de registro de objetivos de Webhook e instalación de rutas | - | `plugin-sdk/webhook-path` | Helpers de normalización de rutas de Webhook | + | `plugin-sdk/image-generation-core` | Tipos compartidos de generación de imágenes, helpers de failover, auth y registro | + | `plugin-sdk/music-generation` | Tipos de proveedor/solicitud/resultado de generación de música | + | `plugin-sdk/music-generation-core` | Tipos compartidos de generación de música, helpers de failover, búsqueda de proveedores y análisis de model-ref | + | `plugin-sdk/video-generation` | Tipos de proveedor/solicitud/resultado de generación de video | + | `plugin-sdk/video-generation-core` | Tipos compartidos de generación de video, helpers de failover, búsqueda de proveedores y análisis de model-ref | + | `plugin-sdk/webhook-targets` | Helpers de registro de destinos de Webhook e instalación de rutas | + | `plugin-sdk/webhook-path` | Helpers de normalización de ruta de Webhook | | `plugin-sdk/web-media` | Helpers compartidos de carga de medios remotos/locales | - | `plugin-sdk/zod` | `zod` reexportado para consumidores del SDK de plugin | + | `plugin-sdk/zod` | `zod` reexportado para consumidores del SDK de Plugin | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | Subruta | Exportaciones clave | | --- | --- | - | `plugin-sdk/memory-core` | Superficie helper incluida de memory-core para helpers de administrador/configuración/archivos/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Fachada de tiempo de ejecución de índice/búsqueda de memoria | + | `plugin-sdk/memory-core` | Superficie helper empaquetada de memory-core para helpers de administrador/configuración/archivo/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime de índice/búsqueda de memoria | | `plugin-sdk/memory-core-host-engine-foundation` | Exportaciones del motor base del host de memoria | | `plugin-sdk/memory-core-host-engine-embeddings` | Contratos de embeddings del host de memoria, acceso al registro, proveedor local y helpers genéricos por lotes/remotos | | `plugin-sdk/memory-core-host-engine-qmd` | Exportaciones del motor QMD del host de memoria | | `plugin-sdk/memory-core-host-engine-storage` | Exportaciones del motor de almacenamiento del host de memoria | | `plugin-sdk/memory-core-host-multimodal` | Helpers multimodales del host de memoria | - | `plugin-sdk/memory-core-host-query` | Helpers de consultas del host de memoria | + | `plugin-sdk/memory-core-host-query` | Helpers de consulta del host de memoria | | `plugin-sdk/memory-core-host-secret` | Helpers de secretos del host de memoria | - | `plugin-sdk/memory-core-host-events` | Helpers de diario de eventos del host de memoria | + | `plugin-sdk/memory-core-host-events` | Helpers del diario de eventos del host de memoria | | `plugin-sdk/memory-core-host-status` | Helpers de estado del host de memoria | - | `plugin-sdk/memory-core-host-runtime-cli` | Helpers de tiempo de ejecución de CLI del host de memoria | - | `plugin-sdk/memory-core-host-runtime-core` | Helpers de tiempo de ejecución central del host de memoria | - | `plugin-sdk/memory-core-host-runtime-files` | Helpers de archivos/tiempo de ejecución del host de memoria | - | `plugin-sdk/memory-host-core` | Alias neutral respecto del proveedor para helpers de tiempo de ejecución central del host de memoria | - | `plugin-sdk/memory-host-events` | Alias neutral respecto del proveedor para helpers de diario de eventos del host de memoria | - | `plugin-sdk/memory-host-files` | Alias neutral respecto del proveedor para helpers de archivos/tiempo de ejecución del host de memoria | - | `plugin-sdk/memory-host-markdown` | Helpers compartidos de Markdown administrado para plugins adyacentes a memoria | - | `plugin-sdk/memory-host-search` | Fachada de tiempo de ejecución de Active Memory para acceso al administrador de búsqueda | - | `plugin-sdk/memory-host-status` | Alias neutral respecto del proveedor para helpers de estado del host de memoria | - | `plugin-sdk/memory-lancedb` | Superficie helper incluida de memory-lancedb | + | `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime de CLI del host de memoria | + | `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime del núcleo del host de memoria | + | `plugin-sdk/memory-core-host-runtime-files` | Helpers de archivos/runtime del host de memoria | + | `plugin-sdk/memory-host-core` | Alias neutral respecto al proveedor para los helpers de runtime del núcleo del host de memoria | + | `plugin-sdk/memory-host-events` | Alias neutral respecto al proveedor para los helpers del diario de eventos del host de memoria | + | `plugin-sdk/memory-host-files` | Alias neutral respecto al proveedor para los helpers de archivos/runtime del host de memoria | + | `plugin-sdk/memory-host-markdown` | Helpers compartidos de markdown gestionado para plugins adyacentes a memoria | + | `plugin-sdk/memory-host-search` | Fachada de runtime de Active Memory para acceso al administrador de búsqueda | + | `plugin-sdk/memory-host-status` | Alias neutral respecto al proveedor para los helpers de estado del host de memoria | + | `plugin-sdk/memory-lancedb` | Superficie helper empaquetada de memory-lancedb | - + | Familia | Subrutas actuales | Uso previsto | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de soporte del plugin Browser incluido (`browser-support` sigue siendo el barrel de compatibilidad) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/de tiempo de ejecución de Matrix incluida | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/de tiempo de ejecución de LINE incluida | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper de IRC incluida | - | Helpers específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Interfaces de compatibilidad/helper de canales incluidos | - | Helpers específicos de autenticación/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Interfaces helper de funciones/plugins incluidos; `plugin-sdk/github-copilot-token` exporta actualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de soporte del Plugin Browser empaquetado (`browser-support` sigue siendo el barrel de compatibilidad) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/runtime empaquetada de Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime empaquetada de LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper empaquetada de IRC | + | Helpers específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Superficies de compatibilidad/helper de canales empaquetados | + | Helpers específicos de autenticación/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Superficies helper de funciones/plugins empaquetados; `plugin-sdk/github-copilot-token` actualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` | ## API de registro -La callback `register(api)` recibe un objeto `OpenClawPluginApi` con estos +La devolución de llamada `register(api)` recibe un objeto `OpenClawPluginApi` con estos métodos: ### Registro de capacidades -| Método | Qué registra | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Inferencia de texto (LLM) | +| Método | Qué registra | +| ------------------------------------------------ | ------------------------------------------ | +| `api.registerProvider(...)` | Inferencia de texto (LLM) | | `api.registerAgentHarness(...)` | Ejecutor experimental de agente de bajo nivel | -| `api.registerCliBackend(...)` | Backend de inferencia de CLI local | -| `api.registerChannel(...)` | Canal de mensajería | -| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real por streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex | -| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video | -| `api.registerImageGenerationProvider(...)` | Generación de imágenes | -| `api.registerMusicGenerationProvider(...)` | Generación musical | -| `api.registerVideoGenerationProvider(...)` | Generación de video | -| `api.registerWebFetchProvider(...)` | Proveedor de obtención / scraping web | -| `api.registerWebSearchProvider(...)` | Búsqueda web | +| `api.registerCliBackend(...)` | Backend local de inferencia de CLI | +| `api.registerChannel(...)` | Canal de mensajería | +| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real en streaming | +| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex | +| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video | +| `api.registerImageGenerationProvider(...)` | Generación de imágenes | +| `api.registerMusicGenerationProvider(...)` | Generación de música | +| `api.registerVideoGenerationProvider(...)` | Generación de video | +| `api.registerWebFetchProvider(...)` | Proveedor de fetch / scraping web | +| `api.registerWebSearchProvider(...)` | Búsqueda web | ### Herramientas y comandos -| Método | Qué registra | -| ------------------------------- | -------------------------------------------- | -| `api.registerTool(tool, opts?)` | Herramienta de agente (obligatoria o `{ optional: true }`) | -| `api.registerCommand(def)` | Comando personalizado (omite el LLM) | +| Método | Qué registra | +| ------------------------------- | --------------------------------------------- | +| `api.registerTool(tool, opts?)` | Herramienta del agente (obligatoria o `{ optional: true }`) | +| `api.registerCommand(def)` | Comando personalizado (omite el LLM) | ### Infraestructura -| Método | Qué registra | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Hook de evento | -| `api.registerHttpRoute(params)` | Endpoint HTTP de Gateway | -| `api.registerGatewayMethod(name, handler)` | Método RPC de Gateway | -| `api.registerCli(registrar, opts?)` | Subcomando de CLI | -| `api.registerService(service)` | Servicio en segundo plano | -| `api.registerInteractiveHandler(registration)` | Manejador interactivo | -| `api.registerMemoryPromptSupplement(builder)` | Sección adicional del prompt adyacente a memoria | -| `api.registerMemoryCorpusSupplement(adapter)` | Corpus adicional de búsqueda/lectura de memoria | +| Método | Qué registra | +| ---------------------------------------------- | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook de evento | +| `api.registerHttpRoute(params)` | Endpoint HTTP de Gateway | +| `api.registerGatewayMethod(name, handler)` | Método RPC de Gateway | +| `api.registerCli(registrar, opts?)` | Subcomando de CLI | +| `api.registerService(service)` | Servicio en segundo plano | +| `api.registerInteractiveHandler(registration)` | Manejador interactivo | +| `api.registerMemoryPromptSupplement(builder)` | Sección de prompt aditiva adyacente a memoria | +| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de búsqueda/lectura de memoria | -Los espacios de nombres administrativos reservados del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, +Los espacios de nombres de administración reservados del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) siempre permanecen como `operator.admin`, incluso si un plugin intenta asignar un -alcance más limitado a un método de Gateway. Prefiere prefijos específicos del plugin para +alcance más estrecho a un método de Gateway. Prefiere prefijos específicos del plugin para métodos propiedad del plugin. ### Metadatos de registro de CLI @@ -357,9 +371,9 @@ métodos propiedad del plugin. - `commands`: raíces de comandos explícitas propiedad del registrador - `descriptors`: descriptores de comandos en tiempo de análisis usados para la ayuda de la CLI raíz, - el enrutamiento y el registro lazy de CLI del plugin + el routing y el registro diferido de CLI del plugin -Si quieres que un comando de plugin permanezca con carga lazy en la ruta normal de la CLI raíz, +Si quieres que un comando de plugin permanezca con carga diferida en la ruta normal de la CLI raíz, proporciona `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese registrador. @@ -373,7 +387,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Administra cuentas, verificación, dispositivos y estado del perfil de Matrix", + description: "Administra cuentas de Matrix, verificación, dispositivos y estado del perfil", hasSubcommands: true, }, ], @@ -381,19 +395,19 @@ api.registerCli( ); ``` -Usa `commands` por sí solo solo cuando no necesites registro lazy de la CLI raíz. -Esa ruta de compatibilidad eager sigue siendo compatible, pero no instala -placeholders respaldados por descriptores para la carga lazy en tiempo de análisis. +Usa `commands` por sí solo solo cuando no necesites registro diferido en la CLI raíz. +Esa ruta de compatibilidad ansiosa sigue siendo compatible, pero no instala +placeholders respaldados por descriptores para la carga diferida en tiempo de análisis. ### Registro de backend de CLI `api.registerCliBackend(...)` permite que un plugin sea propietario de la configuración predeterminada de un -backend de CLI de IA local como `codex-cli`. +backend local de CLI de IA como `codex-cli`. - El `id` del backend se convierte en el prefijo del proveedor en referencias de modelo como `codex-cli/gpt-5`. - La `config` del backend usa la misma forma que `agents.defaults.cliBackends.`. -- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.` sobre el - valor predeterminado del plugin antes de ejecutar la CLI. +- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.` sobre la + predeterminada del plugin antes de ejecutar la CLI. - Usa `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión (por ejemplo, para normalizar formas antiguas de flags). @@ -401,65 +415,65 @@ backend de CLI de IA local como `codex-cli`. | Método | Qué registra | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Motor de contexto (uno activo a la vez). La callback `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar las adiciones al prompt. | +| `api.registerContextEngine(id, factory)` | Motor de contexto (solo uno activo a la vez). La devolución de llamada `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar adiciones al prompt. | | `api.registerMemoryCapability(capability)` | Capacidad de memoria unificada | | `api.registerMemoryPromptSection(builder)` | Constructor de sección de prompt de memoria | -| `api.registerMemoryFlushPlan(resolver)` | Resolutor del plan de vaciado de memoria | -| `api.registerMemoryRuntime(runtime)` | Adaptador de tiempo de ejecución de memoria | +| `api.registerMemoryFlushPlan(resolver)` | Resolutor de plan de vaciado de memoria | +| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memoria | ### Adaptadores de embeddings de memoria -| Método | Qué registra | -| ---------------------------------------------- | --------------------------------------------- | +| Método | Qué registra | +| ---------------------------------------------- | ---------------------------------------------- | | `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embeddings de memoria para el plugin activo | - `registerMemoryCapability` es la API exclusiva preferida para plugins de memoria. - `registerMemoryCapability` también puede exponer `publicArtifacts.listArtifacts(...)` para que los plugins complementarios puedan consumir artefactos de memoria exportados mediante - `openclaw/plugin-sdk/memory-host-core` en lugar de acceder al diseño privado de un + `openclaw/plugin-sdk/memory-host-core` en lugar de acceder al layout privado de un plugin de memoria específico. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` y - `registerMemoryRuntime` son APIs exclusivas heredadas compatibles para plugins de memoria. + `registerMemoryRuntime` son API exclusivas compatibles con versiones heredadas para plugins de memoria. - `registerMemoryEmbeddingProvider` permite que el plugin de memoria activo registre uno - o más ID de adaptadores de embeddings (por ejemplo `openai`, `gemini` o un ID personalizado + o más ids de adaptador de embeddings (por ejemplo `openai`, `gemini` o un id personalizado definido por el plugin). - La configuración del usuario, como `agents.defaults.memorySearch.provider` y - `agents.defaults.memorySearch.fallback`, se resuelve contra esos ID de adaptadores + `agents.defaults.memorySearch.fallback`, se resuelve respecto de esos ids de adaptador registrados. ### Eventos y ciclo de vida -| Método | Qué hace | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida | -| `api.onConversationBindingResolved(handler)` | Callback de vinculación de conversación | +| Método | Qué hace | +| -------------------------------------------- | --------------------------- | +| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida | +| `api.onConversationBindingResolved(handler)` | Devolución de llamada de binding de conversación | ### Semántica de decisión de hooks -- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad. -- `before_tool_call`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación. -- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad. -- `before_install`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación. -- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier manejador reclama el despacho, se omiten los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo. -- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad. -- `message_sending`: devolver `{ cancel: false }` se trata como ausencia de decisión (igual que omitir `cancel`), no como una anulación. +- `before_tool_call`: devolver `{ block: true }` es terminal. En cuanto cualquier manejador lo establece, se omiten los manejadores de menor prioridad. +- `before_tool_call`: devolver `{ block: false }` se trata como si no hubiera decisión (igual que omitir `block`), no como una anulación. +- `before_install`: devolver `{ block: true }` es terminal. En cuanto cualquier manejador lo establece, se omiten los manejadores de menor prioridad. +- `before_install`: devolver `{ block: false }` se trata como si no hubiera decisión (igual que omitir `block`), no como una anulación. +- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. En cuanto cualquier manejador reclama el despacho, se omiten los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo. +- `message_sending`: devolver `{ cancel: true }` es terminal. En cuanto cualquier manejador lo establece, se omiten los manejadores de menor prioridad. +- `message_sending`: devolver `{ cancel: false }` se trata como si no hubiera decisión (igual que omitir `cancel`), no como una anulación. ### Campos del objeto API -| Campo | Tipo | Descripción | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | -| `api.id` | `string` | ID del plugin | -| `api.name` | `string` | Nombre para mostrar | -| `api.version` | `string?` | Versión del plugin (opcional) | -| `api.description` | `string?` | Descripción del plugin (opcional) | -| `api.source` | `string` | Ruta de origen del plugin | -| `api.rootDir` | `string?` | Directorio raíz del plugin (opcional) | -| `api.config` | `OpenClawConfig` | Instantánea de configuración actual (instantánea activa en memoria del tiempo de ejecución cuando está disponible) | -| `api.pluginConfig` | `Record` | Configuración específica del plugin desde `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helpers de tiempo de ejecución](/es/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger con alcance (`debug`, `info`, `warn`, `error`) | +| Campo | Tipo | Descripción | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Id del Plugin | +| `api.name` | `string` | Nombre para mostrar | +| `api.version` | `string?` | Versión del Plugin (opcional) | +| `api.description` | `string?` | Descripción del Plugin (opcional) | +| `api.source` | `string` | Ruta de origen del Plugin | +| `api.rootDir` | `string?` | Directorio raíz del Plugin (opcional) | +| `api.config` | `OpenClawConfig` | Instantánea actual de la configuración (instantánea activa del runtime en memoria cuando esté disponible) | +| `api.pluginConfig` | `Record` | Configuración específica del plugin desde `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/es/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger con alcance (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Modo de carga actual; `"setup-runtime"` es la ventana ligera de inicio/configuración previa a la entrada completa | -| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin | +| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin | ## Convención de módulos internos @@ -468,48 +482,48 @@ Dentro de tu plugin, usa archivos barrel locales para las importaciones internas ``` my-plugin/ api.ts # Exportaciones públicas para consumidores externos - runtime-api.ts # Exportaciones internas solo para tiempo de ejecución + runtime-api.ts # Exportaciones internas solo para runtime index.ts # Punto de entrada del plugin setup-entry.ts # Entrada ligera solo para configuración (opcional) ``` Nunca importes tu propio plugin mediante `openclaw/plugin-sdk/` - desde código de producción. Enruta las importaciones internas mediante `./api.ts` o + desde código de producción. Enruta las importaciones internas por `./api.ts` o `./runtime-api.ts`. La ruta del SDK es solo el contrato externo. -Las superficies públicas de plugins incluidos cargadas mediante fachada (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` y archivos de entrada públicos similares) ahora prefieren la -instantánea activa de configuración en tiempo de ejecución cuando OpenClaw ya se está ejecutando. Si aún no -existe una instantánea de tiempo de ejecución, recurren a la configuración resuelta en disco. +Las superficies públicas de plugins empaquetados cargadas mediante fachada (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` y archivos públicos de entrada similares) ahora prefieren la +instantánea activa de configuración del runtime cuando OpenClaw ya está en ejecución. Si aún no existe ninguna +instantánea de runtime, vuelven a la configuración resuelta en disco. -Los plugins de proveedor también pueden exponer un barrel de contrato local y acotado del plugin cuando un +Los plugins de proveedor también pueden exponer un barrel de contrato local del plugin y más específico cuando un helper es intencionalmente específico del proveedor y todavía no pertenece a una subruta genérica del SDK. -Ejemplo actual incluido: el proveedor Anthropic mantiene sus helpers de stream de Claude -en su propia interfaz pública `api.ts` / `contract-api.ts` en lugar de +Ejemplo empaquetado actual: el proveedor Anthropic mantiene sus helpers de stream de Claude +en su propia superficie pública `api.ts` / `contract-api.ts` en lugar de promover la lógica de encabezados beta de Anthropic y `service_tier` a un contrato genérico `plugin-sdk/*`. -Otros ejemplos actuales incluidos: +Otros ejemplos empaquetados actuales: - `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedor, - helpers de modelos predeterminados y constructores de proveedores realtime + helpers de modelo predeterminado y constructores de proveedor en tiempo real - `@openclaw/openrouter-provider`: `api.ts` exporta el constructor del proveedor además de - helpers de onboarding/configuración + helpers de incorporación/configuración - El código de producción de extensiones también debería evitar importaciones de `openclaw/plugin-sdk/`. + El código de producción de extensiones también debe evitar las importaciones `openclaw/plugin-sdk/`. Si un helper es realmente compartido, promuévelo a una subruta neutral del SDK como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` u otra - superficie orientada a capacidades, en lugar de acoplar dos plugins entre sí. + superficie orientada a capacidades en lugar de acoplar dos plugins entre sí. ## Relacionado - [Puntos de entrada](/es/plugins/sdk-entrypoints) — opciones de `definePluginEntry` y `defineChannelPluginEntry` -- [Helpers de tiempo de ejecución](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime` -- [Configuración y config](/es/plugins/sdk-setup) — empaquetado, manifests, esquemas de configuración +- [Helpers de runtime](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime` +- [Configuración y setup](/es/plugins/sdk-setup) — empaquetado, manifiestos, esquemas de configuración - [Pruebas](/es/plugins/sdk-testing) — utilidades de prueba y reglas de lint - [Migración del SDK](/es/plugins/sdk-migration) — migración desde superficies obsoletas -- [Internos del plugin](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades +- [Internals del Plugin](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades diff --git a/docs/es/refactor/qa.md b/docs/es/refactor/qa.md index d6116edc2..922b63dab 100644 --- a/docs/es/refactor/qa.md +++ b/docs/es/refactor/qa.md @@ -1,16 +1,16 @@ --- x-i18n: - generated_at: "2026-04-08T05:03:29Z" + generated_at: "2026-04-18T04:59:38Z" model: gpt-5.4 provider: openai - source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd + source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca source_path: refactor/qa.md workflow: 15 --- # Refactorización de QA -Estado: migración fundacional completada. +Estado: se consolidó la migración fundacional. ## Objetivo @@ -18,17 +18,17 @@ Mover QA de OpenClaw de un modelo de definición dividida a una única fuente de - metadatos de escenarios - prompts enviados al modelo -- configuración y limpieza -- lógica del harness +- configuración y desmontaje +- lógica del arnés - aserciones y criterios de éxito - artefactos e indicaciones para informes -El estado final deseado es un harness de QA genérico que cargue archivos potentes de definición de escenarios en lugar de codificar la mayor parte del comportamiento en TypeScript. +El estado final deseado es un arnés de QA genérico que cargue archivos potentes de definición de escenarios en lugar de codificar la mayor parte del comportamiento en TypeScript. ## Estado actual La fuente principal de verdad ahora vive en `qa/scenarios/index.md` más un archivo por -escenario en `qa/scenarios/*.md`. +escenario en `qa/scenarios//*.md`. Implementado: @@ -36,56 +36,56 @@ Implementado: - metadatos canónicos del paquete de QA - identidad del operador - misión inicial -- `qa/scenarios/*.md` - - un archivo Markdown por escenario +- `qa/scenarios//*.md` + - un archivo markdown por escenario - metadatos del escenario - - vinculaciones de handlers + - enlaces de handlers - configuración de ejecución específica del escenario - `extensions/qa-lab/src/scenario-catalog.ts` - - analizador del paquete Markdown + validación con zod + - analizador del paquete markdown + validación con zod - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - - renderizado del plan a partir del paquete Markdown + - renderizado del plan a partir del paquete markdown - `extensions/qa-lab/src/qa-agent-workspace.ts` - - genera archivos de compatibilidad sembrados más `QA_SCENARIOS.md` + - siembra archivos de compatibilidad generados más `QA_SCENARIOS.md` - `extensions/qa-lab/src/suite.ts` - - selecciona escenarios ejecutables mediante vinculaciones de handlers definidas en Markdown -- Protocolo del bus de QA + UI + - selecciona escenarios ejecutables mediante enlaces de handlers definidos en markdown +- Protocolo de bus de QA + UI - adjuntos en línea genéricos para renderizado de imagen/video/audio/archivo Superficies divididas restantes: - `extensions/qa-lab/src/suite.ts` - - todavía posee la mayor parte de la lógica ejecutable de handlers personalizados + - todavía mantiene la mayor parte de la lógica ejecutable personalizada de handlers - `extensions/qa-lab/src/report.ts` - - todavía deriva la estructura del informe a partir de las salidas de tiempo de ejecución + - todavía deriva la estructura del informe a partir de las salidas del runtime -Así que la división de la fuente de verdad está solucionada, pero la ejecución sigue estando mayormente respaldada por handlers en lugar de ser completamente declarativa. +Así que la división de la fuente de verdad está resuelta, pero la ejecución sigue dependiendo en gran medida de handlers en lugar de ser totalmente declarativa. -## Cómo es la superficie real de escenarios +## Cómo es realmente la superficie de escenarios -Al leer la suite actual se observan algunas clases distintas de escenarios. +Leer la suite actual muestra algunas clases distintas de escenarios. ### Interacción simple -- línea base de canal -- línea base de DM +- línea base del canal +- línea base de MD - seguimiento en hilo - cambio de modelo - continuación de aprobación - reacción/edición/eliminación -### Mutación de configuración y tiempo de ejecución +### Mutación de configuración y runtime -- desactivación de Skills mediante parche de configuración -- activación tras reinicio con aplicación de configuración +- deshabilitación de Skill mediante parche de configuración +- reactivación tras reinicio con config apply - cambio de capacidad tras reinicio de configuración -- verificación de deriva del inventario de tiempo de ejecución +- comprobación de deriva del inventario del runtime ### Aserciones de sistema de archivos y repositorio -- informe de descubrimiento de código/documentación +- informe de descubrimiento de source/docs - compilar Lobster Invaders -- búsqueda de artefactos de imagen generada +- búsqueda de artefacto de imagen generado ### Orquestación de memoria @@ -93,57 +93,56 @@ Al leer la suite actual se observan algunas clases distintas de escenarios. - herramientas de memoria en contexto de canal - fallback ante fallo de memoria - clasificación de memoria de sesión -- aislamiento de memoria de hilos -- barrido de memory dreaming +- aislamiento de memoria por hilo +- barrido de Dreaming de memoria ### Integración de herramientas y plugins - llamada MCP plugin-tools - visibilidad de Skills -- instalación en caliente de Skills -- generación de imágenes nativa -- ida y vuelta de imágenes -- comprensión de imágenes a partir de adjuntos +- instalación dinámica de Skills +- generación nativa de imágenes +- roundtrip de imagen +- comprensión de imagen desde adjunto -### Múltiples turnos y múltiples actores +### Multiturno y multiactor -- transferencia a subagentes -- síntesis fanout de subagentes -- flujos tipo recuperación tras reinicio +- transferencia a subagente +- síntesis con fanout de subagentes +- flujos de estilo de recuperación tras reinicio -Estas categorías importan porque impulsan los requisitos del DSL. Una lista plana de prompt + texto esperado no es suficiente. +Estas categorías importan porque determinan los requisitos del DSL. Una lista plana de prompt + texto esperado no es suficiente. ## Dirección ### Fuente única de verdad -Usar `qa/scenarios/index.md` más `qa/scenarios/*.md` como la fuente de verdad -creada. +Usar `qa/scenarios/index.md` más `qa/scenarios//*.md` como fuente de verdad redactada. El paquete debe seguir siendo: -- legible por humanos en revisión -- interpretable por máquinas +- legible para humanos en revisión +- interpretable por máquina - lo bastante rico para impulsar: - ejecución de la suite - - bootstrap del espacio de trabajo de QA + - arranque del espacio de trabajo de QA - metadatos de la UI de QA Lab - prompts de documentación/descubrimiento - generación de informes ### Formato de autoría preferido -Usar Markdown como formato de nivel superior, con YAML estructurado dentro de él. +Usar markdown como formato de nivel superior, con YAML estructurado dentro. Forma recomendada: - frontmatter YAML - id - - título - - superficie + - title + - surface - tags - - referencias de documentación - - referencias de código + - referencias a docs + - referencias a código - anulaciones de modelo/proveedor - prerrequisitos - secciones en prosa @@ -156,13 +155,13 @@ Forma recomendada: - assertions - cleanup -Esto proporciona: +Esto aporta: - mejor legibilidad en PR que un JSON gigante - contexto más rico que YAML puro - análisis estricto y validación con zod -El JSON sin procesar es aceptable solo como forma intermedia generada. +El JSON sin procesar es aceptable solo como forma generada intermedia. ## Forma propuesta del archivo de escenario @@ -187,11 +186,11 @@ codeRefs: - src/gateway/chat-attachments.ts --- -# Objetivo +# Objective -Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimiento. +Verify generated media is reattached on the follow-up turn. -# Configuración +# Setup ```yaml scenario.setup - action: config.patch @@ -204,7 +203,7 @@ Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimie key: agent:qa:image-roundtrip ``` -# Pasos +# Steps ```yaml scenario.steps - action: agent.send @@ -223,7 +222,7 @@ Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimie - fromArtifact: lighthouseImage ``` -# Expectativa +# Expect ```yaml scenario.expect - assert: outbound.textIncludes @@ -237,9 +236,9 @@ Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimie ``` ```` -## Capacidades del runner que debe cubrir el DSL +## Capacidades del ejecutor que el DSL debe cubrir -Según la suite actual, el runner genérico necesita más que ejecución de prompts. +Basándose en la suite actual, el ejecutor genérico necesita más que ejecución de prompts. ### Acciones de entorno y configuración @@ -250,14 +249,14 @@ Según la suite actual, el runner genérico necesita más que ejecución de prom - `thread.create` - `workspace.writeSkill` -### Acciones de turnos del agente +### Acciones de turno del agente - `agent.send` - `agent.wait` - `bus.injectInbound` - `bus.injectOutbound` -### Acciones de configuración y tiempo de ejecución +### Acciones de configuración y runtime - `config.get` - `config.patch` @@ -275,7 +274,7 @@ Según la suite actual, el runner genérico necesita más que ejecución de prom - `artifact.captureGeneratedImage` - `artifact.capturePath` -### Acciones de memoria y cron +### Acciones de memoria y Cron - `memory.indexForce` - `memory.searchCli` @@ -314,48 +313,48 @@ Ejemplos de la suite actual: - crear un hilo y luego reutilizar `threadId` - crear una sesión y luego reutilizar `sessionKey` - generar una imagen y luego adjuntar el archivo en el siguiente turno -- generar una cadena de marcador de activación y luego afirmar que aparece más tarde +- generar una cadena de marcador de activación y luego afirmar que aparezca después Capacidades necesarias: - `saveAs` - `${vars.name}` - `${artifacts.name}` -- referencias tipadas para rutas, claves de sesión, ids de hilos, marcadores y salidas de herramientas +- referencias tipadas para rutas, claves de sesión, ids de hilo, marcadores, salidas de herramientas -Sin soporte para variables, el harness seguirá filtrando la lógica de los escenarios de vuelta a TypeScript. +Sin soporte para variables, el arnés seguirá filtrando la lógica del escenario de vuelta a TypeScript. -## Qué debería permanecer como escape hatches +## Qué debería mantenerse como vías de escape -Un runner declarativo completamente puro no es realista en la fase 1. +Un ejecutor declarativo completamente puro no es realista en la fase 1. -Algunos escenarios son inherentemente intensivos en orquestación: +Algunos escenarios son intrínsecamente intensivos en orquestación: -- barrido de memory dreaming -- activación tras reinicio con aplicación de configuración +- barrido de Dreaming de memoria +- reactivación tras reinicio con config apply - cambio de capacidad tras reinicio de configuración -- resolución de artefactos de imagen generada por marca de tiempo/ruta +- resolución de artefactos de imagen generados por marca de tiempo/ruta - evaluación de informes de descubrimiento Por ahora, estos deberían usar handlers personalizados explícitos. Regla recomendada: -- 85-90% declarativo -- pasos de `customHandler` explícitos para el resto difícil +- 85-90 % declarativo +- pasos `customHandler` explícitos para la parte difícil restante - solo handlers personalizados con nombre y documentados -- nada de código en línea anónimo en el archivo de escenario +- nada de código en línea anónimo en el archivo del escenario -Eso mantiene limpio el motor genérico y al mismo tiempo permite seguir avanzando. +Eso mantiene limpio el motor genérico y aun así permite avanzar. ## Cambio de arquitectura ### Actual -El Markdown de escenarios ya es la fuente de verdad para: +El markdown de escenarios ya es la fuente de verdad para: - ejecución de la suite -- archivos de bootstrap del espacio de trabajo +- archivos de arranque del espacio de trabajo - catálogo de escenarios de la UI de QA Lab - metadatos de informes - prompts de descubrimiento @@ -372,11 +371,11 @@ Compatibilidad generada: Hecho. -- se agregó `qa/scenarios/index.md` -- se dividieron los escenarios en `qa/scenarios/*.md` -- se agregó un analizador para el contenido del paquete Markdown YAML con nombre +- se añadió `qa/scenarios/index.md` +- se dividieron los escenarios en `qa/scenarios//*.md` +- se añadió un analizador para el contenido nombrado del paquete markdown YAML - se validó con zod -- se cambiaron los consumidores al paquete analizado +- se cambiaron los consumidores para usar el paquete analizado - se eliminaron `qa/seed-scenarios.json` y `qa/QA_KICKOFF_TASK.md` a nivel de repositorio ### Fase 2: motor genérico @@ -393,49 +392,49 @@ Entregable: - el motor ejecuta escenarios declarativos simples -Comenzar con escenarios que son principalmente prompt + espera + aserción: +Empezar con escenarios que son mayormente prompt + espera + aserción: - seguimiento en hilo -- comprensión de imágenes a partir de adjuntos +- comprensión de imagen desde adjunto - visibilidad e invocación de Skills -- línea base de canal +- línea base del canal Entregable: -- los primeros escenarios reales definidos en Markdown funcionando a través del motor genérico +- primeros escenarios reales definidos en markdown enviados a producción a través del motor genérico ### Fase 4: migrar escenarios intermedios -- ida y vuelta de generación de imágenes +- roundtrip de generación de imagen - herramientas de memoria en contexto de canal - clasificación de memoria de sesión -- transferencia a subagentes -- síntesis fanout de subagentes +- transferencia a subagente +- síntesis con fanout de subagentes Entregable: -- variables, artefactos, aserciones de herramientas y aserciones de logs de solicitudes demostradas +- variables, artefactos, aserciones de herramientas y aserciones de request-log demostradas ### Fase 5: mantener los escenarios difíciles en handlers personalizados -- barrido de memory dreaming -- activación tras reinicio con aplicación de configuración +- barrido de Dreaming de memoria +- reactivación tras reinicio con config apply - cambio de capacidad tras reinicio de configuración -- deriva del inventario de tiempo de ejecución +- deriva del inventario del runtime Entregable: -- el mismo formato de autoría, pero con bloques explícitos de pasos personalizados donde sea necesario +- mismo formato de autoría, pero con bloques de pasos personalizados explícitos donde sea necesario ### Fase 6: eliminar el mapa de escenarios codificado Una vez que la cobertura del paquete sea lo bastante buena: -- eliminar la mayor parte de la ramificación TypeScript específica por escenario de `extensions/qa-lab/src/suite.ts` +- eliminar la mayor parte del branching específico de escenarios en TypeScript de `extensions/qa-lab/src/suite.ts` -## Slack falso / soporte para contenido multimedia enriquecido +## Soporte de Fake Slack / medios enriquecidos -El bus de QA actual está orientado primero al texto. +El bus de QA actual está orientado principalmente a texto. Archivos relevantes: @@ -455,7 +454,7 @@ Todavía no modela adjuntos multimedia en línea. ### Contrato de transporte necesario -Agregar un modelo genérico de adjuntos del bus de QA: +Añadir un modelo genérico de adjuntos del bus de QA: ```ts type QaBusAttachment = { @@ -474,7 +473,7 @@ type QaBusAttachment = { }; ``` -Luego agregar `attachments?: QaBusAttachment[]` a: +Luego añadir `attachments?: QaBusAttachment[]` a: - `QaBusMessage` - `QaBusInboundMessageInput` @@ -482,15 +481,15 @@ Luego agregar `attachments?: QaBusAttachment[]` a: ### Por qué genérico primero -No construir un modelo de multimedia solo para Slack. +No construyas un modelo de medios solo para Slack. En su lugar: -- un modelo genérico de transporte de QA -- múltiples renderizadores sobre él - - el chat actual de QA Lab - - un futuro Slack falso web - - cualquier otra vista de transporte falsa +- un modelo de transporte de QA genérico +- múltiples renderizadores encima de él + - chat actual de QA Lab + - futuro fake Slack web + - cualquier otra vista de transporte simulado Esto evita lógica duplicada y permite que los escenarios multimedia sigan siendo agnósticos al transporte. @@ -501,15 +500,15 @@ Actualizar la UI de QA para renderizar: - vista previa de imagen en línea - reproductor de audio en línea - reproductor de video en línea -- chip de adjunto de archivo +- chip de archivo adjunto -La UI actual ya puede renderizar hilos y reacciones, por lo que el renderizado de adjuntos debería integrarse sobre el mismo modelo de tarjeta de mensaje. +La UI actual ya puede renderizar hilos y reacciones, así que el renderizado de adjuntos debería añadirse sobre el mismo modelo de tarjeta de mensaje. ### Trabajo de escenarios habilitado por el transporte multimedia -Una vez que los adjuntos fluyan por el bus de QA, podremos agregar escenarios de chat falso más ricos: +Una vez que los adjuntos fluyan por el bus de QA, podremos añadir escenarios de chat simulado más ricos: -- respuesta con imagen en línea en Slack falso +- respuesta con imagen en línea en fake Slack - comprensión de adjuntos de audio - comprensión de adjuntos de video - orden mixto de adjuntos @@ -519,22 +518,22 @@ Una vez que los adjuntos fluyan por el bus de QA, podremos agregar escenarios de El siguiente bloque de implementación debería ser: -1. agregar el cargador de escenarios Markdown + esquema zod -2. generar el catálogo actual a partir de Markdown +1. añadir cargador de escenarios markdown + esquema zod +2. generar el catálogo actual a partir de markdown 3. migrar primero algunos escenarios simples -4. agregar compatibilidad genérica con adjuntos del bus de QA -5. renderizar imágenes en línea en la UI de QA +4. añadir soporte genérico para adjuntos en el bus de QA +5. renderizar imagen en línea en la UI de QA 6. luego ampliar a audio y video Este es el camino más pequeño que demuestra ambos objetivos: -- QA genérico definido en Markdown -- superficies de mensajería falsa más ricas +- QA genérico definido en markdown +- superficies de mensajería simulada más ricas ## Preguntas abiertas -- si los archivos de escenarios deberían permitir plantillas de prompts Markdown incrustadas con interpolación de variables -- si setup/cleanup deberían ser secciones con nombre o simplemente listas ordenadas de acciones +- si los archivos de escenarios deberían permitir plantillas de prompt markdown incrustadas con interpolación de variables +- si setup/cleanup deberían ser secciones con nombre o simplemente listas de acciones ordenadas - si las referencias a artefactos deberían estar fuertemente tipadas en el esquema o basadas en cadenas -- si los handlers personalizados deberían vivir en un único registro o en registros por superficie +- si los handlers personalizados deberían vivir en un solo registro o en registros por superficie - si el archivo de compatibilidad JSON generado debería seguir versionado durante la migración