From 601a50bcc50b889386ab604a2b318ed4232191d2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 15:23:26 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/cli/plugins.md | 211 +++++++-------------- docs/es/concepts/model-providers.md | 268 +++++++++++++++----------- docs/es/pi.md | 279 ++++++++++++++-------------- docs/es/providers/deepseek.md | 48 ++--- docs/es/tools/plugin.md | 244 ++++++++++++++++-------- 5 files changed, 549 insertions(+), 501 deletions(-) diff --git a/docs/es/cli/plugins.md b/docs/es/cli/plugins.md index 45b51d948..975a67d70 100644 --- a/docs/es/cli/plugins.md +++ b/docs/es/cli/plugins.md @@ -2,13 +2,13 @@ read_when: - Quieres instalar o gestionar Plugins de Gateway o paquetes compatibles - Quieres depurar fallos de carga de Plugins -summary: Referencia de CLI para `openclaw plugins` (listar, instalar, marketplace, desinstalar, habilitar/deshabilitar, doctor) +summary: Referencia de la CLI para `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor) title: Plugins x-i18n: - generated_at: "2026-04-24T05:23:50Z" + generated_at: "2026-04-24T15:21:26Z" model: gpt-5.4 provider: openai - source_hash: 35ef8f54c64ea52d7618a0ef8b90d3d75841a27ae4cd689b4ca8e0cfdcddc408 + source_hash: bc693d5e3bc49057e1a108ba65a4dcb3bb662c00229e6fa38a0335afba8240e5 source_path: cli/plugins.md workflow: 15 --- @@ -21,8 +21,8 @@ Relacionado: - Sistema de Plugins: [Plugins](/es/tools/plugin) - Compatibilidad de paquetes: [Paquetes de Plugins](/es/plugins/bundles) -- Manifiesto + esquema de Plugin: [Manifiesto de Plugin](/es/plugins/manifest) -- Endurecimiento de seguridad: [Seguridad](/es/gateway/security) +- Manifest y esquema de Plugin: [Manifest de Plugin](/es/plugins/manifest) +- Refuerzo de seguridad: [Seguridad](/es/gateway/security) ## Comandos @@ -46,17 +46,11 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Los Plugins incluidos se distribuyen con OpenClaw. Algunos están habilitados de forma predeterminada (por ejemplo, -proveedores de modelos incluidos, proveedores de voz incluidos y el Plugin de navegador -incluido); otros requieren `plugins enable`. +Los Plugins incluidos se distribuyen con OpenClaw. Algunos están habilitados de forma predeterminada (por ejemplo, los proveedores de modelos incluidos, los proveedores de voz incluidos y el Plugin de navegador incluido); otros requieren `plugins enable`. -Los Plugins nativos de OpenClaw deben incluir `openclaw.plugin.json` con un esquema JSON -integrado (`configSchema`, incluso si está vacío). Los paquetes compatibles usan en su lugar -sus propios manifiestos de paquete. +Los Plugins nativos de OpenClaw deben incluir `openclaw.plugin.json` con un esquema JSON en línea (`configSchema`, incluso si está vacío). Los paquetes compatibles usan sus propios manifests de paquete en su lugar. -`plugins list` muestra `Format: openclaw` o `Format: bundle`. La salida detallada de list/info -también muestra el subtipo de paquete (`codex`, `claude` o `cursor`) además de las capacidades -del paquete detectadas. +`plugins list` muestra `Format: openclaw` o `Format: bundle`. La salida detallada de list/info también muestra el subtipo del paquete (`codex`, `claude` o `cursor`) además de las capacidades del paquete detectadas. ### Instalar @@ -72,83 +66,50 @@ openclaw plugins install --marketplace # marketplace (explícit openclaw plugins install --marketplace https://github.com// ``` -Los nombres de paquete sin prefijo se comprueban primero en ClawHub y luego en npm. Nota de seguridad: -trata las instalaciones de Plugins como si ejecutarás código. Prefiere versiones fijadas. +Los nombres de paquete sin prefijo se comprueban primero en ClawHub y luego en npm. Nota de seguridad: trata las instalaciones de Plugins como ejecución de código. Prefiere versiones fijadas. -Si tu sección `plugins` está respaldada por un único archivo `$include`, `plugins install/update/enable/disable/uninstall` escribe en ese archivo incluido y deja `openclaw.json` intacto. Los includes de raíz, arrays de includes e includes con sobrescrituras hermanas fallan de forma segura en lugar de aplanarse. Consulta [Config includes](/es/gateway/configuration) para ver los formatos compatibles. +Si tu sección `plugins` está respaldada por un único `$include` de archivo, `plugins install/update/enable/disable/uninstall` escribe en ese archivo incluido y deja `openclaw.json` intacto. Los includes raíz, los arrays de includes y los includes con sobrescrituras hermanas fallan de forma cerrada en lugar de aplanarse. Consulta [Config includes](/es/gateway/configuration) para ver las formas compatibles. -Si la configuración no es válida, `plugins install` normalmente falla de forma segura y te indica que -ejecutes antes `openclaw doctor --fix`. La única excepción documentada es una ruta limitada de -recuperación de Plugins incluidos para Plugins que aceptan explícitamente -`openclaw.install.allowInvalidConfigRecovery`. +Si la configuración no es válida, `plugins install` normalmente falla de forma cerrada y te indica que primero ejecutes `openclaw doctor --fix`. La única excepción documentada es una ruta limitada de recuperación de Plugin incluido para Plugins que optan explícitamente por `openclaw.install.allowInvalidConfigRecovery`. -`--force` reutiliza el destino de instalación existente y sobrescribe en el lugar un -Plugin o paquete de hooks ya instalado. Úsalo cuando quieras reinstalar intencionadamente -el mismo id desde una ruta local nueva, archivo, paquete de ClawHub o artefacto npm. -Para actualizaciones rutinarias de un Plugin npm ya registrado, prefiere -`openclaw plugins update `. +`--force` reutiliza el destino de instalación existente y sobrescribe en su lugar un Plugin o paquete de hooks ya instalado. Úsalo cuando quieras reinstalar intencionalmente el mismo id desde una nueva ruta local, archivo, paquete de ClawHub o artefacto de npm. Para actualizaciones rutinarias de un Plugin de npm ya rastreado, prefiere `openclaw plugins update `. -Si ejecutas `plugins install` para un id de Plugin que ya está instalado, OpenClaw -se detiene y te dirige a `plugins update ` para una actualización normal, -o a `plugins install --force` cuando realmente quieras sobrescribir -la instalación actual desde otra fuente. +Si ejecutas `plugins install` para un id de Plugin que ya está instalado, OpenClaw se detiene y te dirige a `plugins update ` para una actualización normal, o a `plugins install --force` cuando realmente quieres sobrescribir la instalación actual desde otra fuente. -`--pin` solo se aplica a instalaciones npm. No es compatible con `--marketplace`, -porque las instalaciones desde marketplace conservan metadatos del origen del marketplace en lugar de una -especificación npm. +`--pin` se aplica solo a instalaciones desde npm. No es compatible con `--marketplace`, porque las instalaciones desde marketplace conservan metadatos del origen del marketplace en lugar de una especificación de npm. -`--dangerously-force-unsafe-install` es una opción de emergencia para falsos positivos -en el escáner integrado de código peligroso. Permite que la instalación continúe incluso -cuando el escáner integrado informa hallazgos `critical`, pero **no** -omite los bloqueos de política del hook `before_install` del Plugin ni omite -los fallos de escaneo. +`--dangerously-force-unsafe-install` es una opción de emergencia para falsos positivos en el escáner integrado de código peligroso. Permite que la instalación continúe incluso cuando el escáner integrado informa hallazgos `critical`, pero **no** omite los bloqueos de políticas de hooks `before_install` del Plugin y **no** omite fallos de escaneo. -Este indicador de CLI se aplica a los flujos de instalación/actualización de Plugins. Las instalaciones de -dependencias de Skills respaldadas por Gateway usan la sobrescritura de solicitud equivalente -`dangerouslyForceUnsafeInstall`, mientras que `openclaw skills install` sigue siendo un flujo independiente -de descarga/instalación de Skills de ClawHub. +Esta bandera de CLI se aplica a los flujos de instalación/actualización de Plugins. Las instalaciones de dependencias de Skills respaldadas por Gateway usan la anulación de solicitud equivalente `dangerouslyForceUnsafeInstall`, mientras que `openclaw skills install` sigue siendo un flujo independiente de descarga/instalación de Skills desde ClawHub. -`plugins install` también es la superficie de instalación para paquetes de hooks que exponen -`openclaw.hooks` en `package.json`. Usa `openclaw hooks` para la visibilidad filtrada de hooks -y la habilitación por hook, no para la instalación del paquete. +`plugins install` también es la superficie de instalación para paquetes de hooks que exponen `openclaw.hooks` en `package.json`. Usa `openclaw hooks` para la visibilidad filtrada de hooks y la habilitación por hook, no para la instalación del paquete. -Las especificaciones npm son **solo de registro** (nombre de paquete + **versión exacta** opcional o -**dist-tag**). Las especificaciones Git/URL/file y los rangos semver se rechazan. Las instalaciones de -dependencias se ejecutan con `--ignore-scripts` por seguridad. +Las especificaciones de npm son **solo de registro** (nombre del paquete + **versión exacta** opcional o **dist-tag**). Las especificaciones git/URL/file y los rangos semver se rechazan. Las instalaciones de dependencias se ejecutan con `--ignore-scripts` por seguridad. -Las especificaciones sin prefijo y `@latest` permanecen en la línea estable. Si npm resuelve -cualquiera de ellas a una versión preliminar, OpenClaw se detiene y te pide que optes -explícitamente por ella con una etiqueta preliminar como `@beta`/`@rc` o una versión preliminar exacta -como `@1.2.3-beta.4`. +Las especificaciones sin prefijo y `@latest` permanecen en la línea estable. Si npm resuelve cualquiera de ellas a una versión preliminar, OpenClaw se detiene y te pide que optes explícitamente por ella con una etiqueta de preliminar como `@beta`/`@rc` o una versión preliminar exacta como `@1.2.3-beta.4`. -Si una especificación de instalación sin prefijo coincide con el id de un Plugin incluido (por ejemplo `diffs`), OpenClaw -instala directamente el Plugin incluido. Para instalar un paquete npm con el mismo -nombre, usa una especificación con alcance explícito (por ejemplo `@scope/diffs`). +Si una especificación de instalación sin prefijo coincide con el id de un Plugin incluido (por ejemplo, `diffs`), OpenClaw instala ese Plugin incluido directamente. Para instalar un paquete de npm con el mismo nombre, usa una especificación con scope explícito (por ejemplo, `@scope/diffs`). Archivos compatibles: `.zip`, `.tgz`, `.tar.gz`, `.tar`. También se admiten instalaciones desde el marketplace de Claude. -Las instalaciones de ClawHub usan un localizador explícito `clawhub:`: +Las instalaciones desde ClawHub usan un localizador explícito `clawhub:`: ```bash openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -OpenClaw ahora también prefiere ClawHub para especificaciones de Plugin sin prefijo compatibles con npm. Solo -recurre a npm si ClawHub no tiene ese paquete o versión: +OpenClaw ahora también prefiere ClawHub para especificaciones de Plugin válidas para npm sin prefijo. Solo recurre a npm si ClawHub no tiene ese paquete o versión: ```bash openclaw plugins install openclaw-codex-app-server ``` -OpenClaw descarga el archivo del paquete desde ClawHub, comprueba la -compatibilidad anunciada con la API del Plugin / versión mínima del gateway, y luego lo instala a través de la ruta normal -de archivos. Las instalaciones registradas conservan sus metadatos de origen de ClawHub para actualizaciones posteriores. +OpenClaw descarga el archivo del paquete desde ClawHub, comprueba la compatibilidad anunciada de la API de Plugin / mínima de gateway y luego lo instala mediante la ruta normal de archivos. Las instalaciones registradas conservan sus metadatos de origen de ClawHub para futuras actualizaciones. -Usa la forma abreviada `plugin@marketplace` cuando el nombre del marketplace exista en la -caché del registro local de Claude en `~/.claude/plugins/known_marketplaces.json`: +Usa la forma abreviada `plugin@marketplace` cuando el nombre del marketplace exista en la caché de registro local de Claude en `~/.claude/plugins/known_marketplaces.json`: ```bash openclaw plugins marketplace list @@ -164,35 +125,26 @@ openclaw plugins install --marketplace https://github.com// openclaw plugins install --marketplace ./my-marketplace ``` -Los orígenes de marketplace pueden ser: +Los orígenes del marketplace pueden ser: -- un nombre de marketplace conocido por Claude de `~/.claude/plugins/known_marketplaces.json` -- una raíz local de marketplace o una ruta a `marketplace.json` -- una forma abreviada de repositorio GitHub como `owner/repo` -- una URL de repositorio GitHub como `https://github.com/owner/repo` -- una URL git +- un nombre de marketplace conocido por Claude desde `~/.claude/plugins/known_marketplaces.json` +- una raíz de marketplace local o una ruta a `marketplace.json` +- una forma abreviada de repositorio de GitHub como `owner/repo` +- una URL de repositorio de GitHub como `https://github.com/owner/repo` +- una URL de git -Para marketplaces remotos cargados desde GitHub o git, las entradas de Plugin deben permanecer -dentro del repositorio clonado del marketplace. OpenClaw acepta orígenes de ruta relativa desde -ese repositorio y rechaza orígenes de Plugin HTTP(S), de ruta absoluta, git, GitHub y otros orígenes -que no sean ruta desde manifiestos remotos. +Para marketplaces remotos cargados desde GitHub o git, las entradas de Plugin deben permanecer dentro del repositorio clonado del marketplace. OpenClaw acepta orígenes de rutas relativas desde ese repositorio y rechaza orígenes HTTP(S), rutas absolutas, git, GitHub y otros orígenes de Plugin que no sean rutas provenientes de manifests remotos. Para rutas locales y archivos, OpenClaw detecta automáticamente: - Plugins nativos de OpenClaw (`openclaw.plugin.json`) - paquetes compatibles con Codex (`.codex-plugin/plugin.json`) -- paquetes compatibles con Claude (`.claude-plugin/plugin.json` o el diseño predeterminado - de componentes de Claude) +- paquetes compatibles con Claude (`.claude-plugin/plugin.json` o el diseño predeterminado de componentes de Claude) - paquetes compatibles con Cursor (`.cursor-plugin/plugin.json`) -Los paquetes compatibles se instalan en la raíz normal de Plugins y participan en -el mismo flujo de list/info/enable/disable. Actualmente se admiten Skills de paquetes, -command-skills de Claude, valores predeterminados de Claude `settings.json`, valores predeterminados de Claude `.lsp.json` / -`lspServers` declarados en el manifiesto, command-skills de Cursor y directorios de hooks compatibles -de Codex; otras capacidades de paquete detectadas se muestran en diagnósticos/info, -pero todavía no están integradas en la ejecución en tiempo de ejecución. +Los paquetes compatibles se instalan en la raíz normal de Plugins y participan en el mismo flujo de list/info/enable/disable. Actualmente, se admiten bundle skills, command-skills de Claude, valores predeterminados de Claude `settings.json`, valores predeterminados de Claude `.lsp.json` / `lspServers` declarados en el manifest, command-skills de Cursor y directorios de hooks de Codex compatibles; otras capacidades de paquetes detectadas se muestran en los diagnósticos/info, pero todavía no están conectadas a la ejecución en tiempo de ejecución. -### Listar +### Lista ```bash openclaw plugins list @@ -201,9 +153,15 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -Usa `--enabled` para mostrar solo los Plugins cargados. Usa `--verbose` para cambiar de la -vista de tabla a líneas de detalle por Plugin con metadatos de origen/procedencia/versión/activación. Usa `--json` para inventario legible por máquina más -diagnósticos del registro. +Usa `--enabled` para mostrar solo los Plugins cargados. Usa `--verbose` para cambiar de la vista de tabla a líneas de detalle por Plugin con metadatos de source/origin/version/activation. Usa `--json` para obtener un inventario legible por máquina más diagnósticos del registro. + +`plugins list` ejecuta el descubrimiento desde el entorno y la configuración actuales de la CLI. Es útil para comprobar si un Plugin está habilitado o se puede cargar, pero no es una sonda activa del tiempo de ejecución de un proceso Gateway ya en ejecución. Después de cambiar código de Plugin, habilitación, política de hooks o `plugins.load.paths`, reinicia el Gateway que sirve el canal antes de esperar que se ejecute nuevo código `register(api)` o hooks. Para despliegues remotos o en contenedor, verifica que estás reiniciando el proceso hijo real `openclaw gateway run`, no solo un proceso contenedor. + +Para depurar hooks en tiempo de ejecución: + +- `openclaw plugins inspect --json` muestra hooks registrados y diagnósticos de una pasada de inspección con el módulo cargado. +- `openclaw gateway status --deep --require-rpc` confirma el Gateway alcanzable, sugerencias de servicio/proceso, ruta de configuración y estado de RPC. +- Los hooks de conversación no incluidos (`llm_input`, `llm_output`, `agent_end`) requieren `plugins.entries..hooks.allowConversationAccess=true`. Usa `--link` para evitar copiar un directorio local (lo añade a `plugins.load.paths`): @@ -211,11 +169,9 @@ Usa `--link` para evitar copiar un directorio local (lo añade a `plugins.load.p openclaw plugins install -l ./my-plugin ``` -`--force` no es compatible con `--link` porque las instalaciones enlazadas reutilizan la -ruta de origen en lugar de copiar sobre un destino de instalación gestionado. +`--force` no es compatible con `--link` porque las instalaciones enlazadas reutilizan la ruta de origen en lugar de copiar sobre un destino de instalación gestionado. -Usa `--pin` en instalaciones npm para guardar la especificación exacta resuelta (`name@version`) en -`plugins.installs` mientras mantienes el comportamiento predeterminado sin fijar. +Usa `--pin` en instalaciones desde npm para guardar la especificación exacta resuelta (`name@version`) en `plugins.installs` mientras se mantiene el comportamiento predeterminado sin fijar. ### Desinstalar @@ -225,15 +181,11 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` elimina registros de Plugins de `plugins.entries`, `plugins.installs`, -la lista de permitidos de Plugins y las entradas enlazadas de `plugins.load.paths` cuando corresponda. -Para Plugins de memoria activos, la ranura de memoria se restablece a `memory-core`. +`uninstall` elimina registros de Plugin de `plugins.entries`, `plugins.installs`, la lista de permitidos de Plugins y las entradas enlazadas de `plugins.load.paths` cuando corresponda. Para Plugins de Active Memory, la ranura de memoria se restablece a `memory-core`. -De forma predeterminada, desinstalar también elimina el directorio de instalación del Plugin bajo la -raíz de Plugins del directorio de estado activo. Usa -`--keep-files` para conservar los archivos en disco. +De forma predeterminada, uninstall también elimina el directorio de instalación del Plugin bajo la raíz de Plugins del directorio de estado activo. Usa `--keep-files` para conservar los archivos en disco. -`--keep-config` se admite como alias obsoleto de `--keep-files`. +`--keep-config` es compatible como alias obsoleto de `--keep-files`. ### Actualizar @@ -245,38 +197,19 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -Las actualizaciones se aplican a las instalaciones registradas en `plugins.installs` y a las instalaciones registradas -de paquetes de hooks en `hooks.internal.installs`. +Las actualizaciones se aplican a las instalaciones rastreadas en `plugins.installs` y a las instalaciones rastreadas de paquetes de hooks en `hooks.internal.installs`. -Cuando pasas un id de Plugin, OpenClaw reutiliza la especificación de instalación registrada para ese -Plugin. Eso significa que dist-tags almacenados previamente como `@beta` y versiones exactas fijadas -siguen utilizándose en ejecuciones posteriores de `update `. +Cuando pasas un id de Plugin, OpenClaw reutiliza la especificación de instalación registrada para ese Plugin. Eso significa que las dist-tags almacenadas previamente, como `@beta`, y las versiones exactas fijadas se siguen usando en ejecuciones posteriores de `update `. -Para instalaciones npm, también puedes pasar una especificación explícita de paquete npm con una dist-tag -o versión exacta. OpenClaw resuelve ese nombre de paquete de vuelta al registro del Plugin -instalado, actualiza ese Plugin instalado y registra la nueva especificación npm para futuras -actualizaciones basadas en id. +Para instalaciones desde npm, también puedes pasar una especificación explícita de paquete npm con una dist-tag o una versión exacta. OpenClaw resuelve ese nombre de paquete de vuelta al registro de Plugin rastreado, actualiza ese Plugin instalado y registra la nueva especificación de npm para futuras actualizaciones basadas en id. -Pasar el nombre del paquete npm sin versión ni etiqueta también resuelve de vuelta al -registro del Plugin instalado. Usa esto cuando un Plugin estaba fijado a una versión exacta y -quieres volver a la línea de versiones predeterminada del registro. +Pasar el nombre del paquete npm sin una versión o etiqueta también lo resuelve de vuelta al registro de Plugin rastreado. Usa esto cuando un Plugin se fijó a una versión exacta y quieres devolverlo a la línea de versión predeterminada del registro. -Antes de una actualización npm en vivo, OpenClaw compara la versión instalada del paquete con -los metadatos del registro npm. Si la versión instalada y la identidad del artefacto -registrado ya coinciden con el destino resuelto, la actualización se omite sin -descargar, reinstalar ni reescribir `openclaw.json`. +Antes de una actualización real desde npm, OpenClaw comprueba la versión del paquete instalado frente a los metadatos del registro de npm. Si la versión instalada y la identidad del artefacto registrado ya coinciden con el destino resuelto, la actualización se omite sin descargar, reinstalar ni reescribir `openclaw.json`. -Cuando existe un hash de integridad almacenado y el hash del artefacto obtenido cambia, -OpenClaw trata esto como deriva del artefacto npm. El comando interactivo -`openclaw plugins update` imprime los hashes esperados y reales y solicita -confirmación antes de continuar. Los asistentes de actualización no interactivos fallan de forma segura -a menos que quien llama proporcione una política explícita de continuación. +Cuando existe un hash de integridad almacenado y cambia el hash del artefacto obtenido, OpenClaw trata esto como una deriva del artefacto de npm. El comando interactivo `openclaw plugins update` imprime los hashes esperado y real, y solicita confirmación antes de continuar. Los asistentes de actualización no interactivos fallan de forma cerrada a menos que quien los invoque proporcione una política explícita de continuación. -`--dangerously-force-unsafe-install` también está disponible en `plugins update` como una -sobrescritura de emergencia para falsos positivos del escaneo integrado de código peligroso durante -actualizaciones de Plugins. Sigue sin omitir los bloques de política `before_install` de Plugins -ni el bloqueo por fallo de escaneo, y solo se aplica a actualizaciones de Plugins, no a actualizaciones -de paquetes de hooks. +`--dangerously-force-unsafe-install` también está disponible en `plugins update` como una anulación de emergencia para falsos positivos del escaneo integrado de código peligroso durante actualizaciones de Plugins. Sigue sin omitir los bloqueos de políticas `before_install` del Plugin ni el bloqueo por fallos de escaneo, y solo se aplica a actualizaciones de Plugins, no a actualizaciones de paquetes de hooks. ### Inspeccionar @@ -285,25 +218,20 @@ openclaw plugins inspect openclaw plugins inspect --json ``` -Introspección profunda de un solo Plugin. Muestra identidad, estado de carga, origen, -capacidades registradas, hooks, herramientas, comandos, servicios, métodos de gateway, -rutas HTTP, indicadores de política, diagnósticos, metadatos de instalación, capacidades de paquete -y cualquier compatibilidad MCP o servidor LSP detectada. +Introspección profunda de un único Plugin. Muestra identidad, estado de carga, origen, capacidades registradas, hooks, herramientas, comandos, servicios, métodos de gateway, rutas HTTP, indicadores de políticas, diagnósticos, metadatos de instalación, capacidades del paquete y cualquier compatibilidad detectada con servidores MCP o LSP. -Cada Plugin se clasifica según lo que realmente registra en tiempo de ejecución: +Cada Plugin se clasifica según lo que registra realmente en tiempo de ejecución: - **plain-capability** — un tipo de capacidad (por ejemplo, un Plugin solo de proveedor) - **hybrid-capability** — varios tipos de capacidad (por ejemplo, texto + voz + imágenes) - **hook-only** — solo hooks, sin capacidades ni superficies -- **non-capability** — herramientas/comandos/servicios pero sin capacidades +- **non-capability** — herramientas/comandos/servicios, pero sin capacidades -Consulta [Formas de Plugins](/es/plugins/architecture#plugin-shapes) para más información sobre el modelo de capacidades. +Consulta [Formas de Plugin](/es/plugins/architecture#plugin-shapes) para obtener más información sobre el modelo de capacidades. -El indicador `--json` genera un informe legible por máquina adecuado para scripts y -auditorías. +La bandera `--json` genera un informe legible por máquina adecuado para scripting y auditoría. -`inspect --all` renderiza una tabla de toda la flota con forma, tipos de capacidad, -avisos de compatibilidad, capacidades de paquete y columnas de resumen de hooks. +`inspect --all` muestra una tabla de todo el conjunto con columnas de forma, tipos de capacidad, avisos de compatibilidad, capacidades del paquete y resumen de hooks. `info` es un alias de `inspect`. @@ -313,13 +241,9 @@ avisos de compatibilidad, capacidades de paquete y columnas de resumen de hooks. openclaw plugins doctor ``` -`doctor` informa errores de carga de Plugins, diagnósticos de manifiesto/detección y -avisos de compatibilidad. Cuando todo está correcto, imprime `No plugin issues -detected.` +`doctor` informa errores de carga de Plugins, diagnósticos de manifest/descubrimiento y avisos de compatibilidad. Cuando todo está correcto, imprime `No plugin issues detected.` -Para fallos de forma de módulo, como exportaciones `register`/`activate` faltantes, vuelve a ejecutar -con `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir un resumen compacto de la forma de las exportaciones en -la salida de diagnóstico. +Para fallos de forma de módulo, como exportaciones `register`/`activate` ausentes, vuelve a ejecutar con `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir un resumen compacto de la forma de las exportaciones en la salida de diagnóstico. ### Marketplace @@ -328,13 +252,10 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -La lista de marketplace acepta una ruta local de marketplace, una ruta a `marketplace.json`, una -forma abreviada de GitHub como `owner/repo`, una URL de repositorio GitHub o una URL git. `--json` -imprime la etiqueta de origen resuelta más el manifiesto de marketplace analizado y las -entradas de Plugin. +La lista de marketplace acepta una ruta a un marketplace local, una ruta a `marketplace.json`, una forma abreviada de GitHub como `owner/repo`, una URL de repositorio de GitHub o una URL de git. `--json` imprime la etiqueta del origen resuelto junto con el manifest del marketplace analizado y las entradas de Plugins. ## Relacionado -- [Referencia de CLI](/es/cli) -- [Crear Plugins](/es/plugins/building-plugins) +- [Referencia de la CLI](/es/cli) +- [Creación de Plugins](/es/plugins/building-plugins) - [Plugins de la comunidad](/es/plugins/community) diff --git a/docs/es/concepts/model-providers.md b/docs/es/concepts/model-providers.md index b57808e0d..50dedbd0a 100644 --- a/docs/es/concepts/model-providers.md +++ b/docs/es/concepts/model-providers.md @@ -2,76 +2,82 @@ read_when: - Necesitas una referencia de configuración de modelos proveedor por proveedor - Quieres configuraciones de ejemplo o comandos de incorporación de CLI para proveedores de modelos -summary: Resumen del proveedor de modelos con configuraciones de ejemplo + flujos de CLI +summary: Descripción general del proveedor de modelos con configuraciones de ejemplo + flujos de CLI title: Proveedores de modelos x-i18n: - generated_at: "2026-04-24T08:57:02Z" + generated_at: "2026-04-24T15:21:20Z" model: gpt-5.4 provider: openai - source_hash: ac9bf48897446576d8bc339b340295691741a589863bb57b379c17a5519bffd7 + source_hash: 79258cb26fae7926c65b6fe0db938c7b5736a540b33bc24c1fad5ad706ac8204 source_path: concepts/model-providers.md workflow: 15 --- -Esta página cubre los **proveedores de LLM/modelos** (no canales de chat como WhatsApp/Telegram). +Esta página cubre los **proveedores de LLM/modelos** (no los canales de chat como WhatsApp/Telegram). Para las reglas de selección de modelos, consulta [/concepts/models](/es/concepts/models). ## Reglas rápidas - Las referencias de modelo usan `provider/model` (ejemplo: `opencode/claude-opus-4-6`). - `agents.defaults.models` actúa como una lista de permitidos cuando está configurado. -- Ayudantes de CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. +- Ayudas de CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. - `models.providers.*.models[].contextWindow` es metadato nativo del modelo; `contextTokens` es el límite efectivo en tiempo de ejecución. -- Reglas de fallback, sondeos de enfriamiento y persistencia de anulaciones de sesión: [Conmutación por error de modelos](/es/concepts/model-failover). -- Las rutas de la familia OpenAI son específicas por prefijo: `openai/` usa el proveedor directo con clave de API de OpenAI en PI, `openai-codex/` usa OAuth de Codex en PI, y `openai/` junto con `agents.defaults.embeddedHarness.runtime: "codex"` usa el arnés nativo del servidor de aplicaciones Codex. Consulta [OpenAI](/es/providers/openai) y [Codex harness](/es/plugins/codex-harness). -- La habilitación automática del Plugin sigue ese mismo límite: `openai-codex/` pertenece al Plugin de OpenAI, mientras que el Plugin de Codex se habilita mediante `embeddedHarness.runtime: "codex"` o referencias heredadas `codex/`. -- GPT-5.5 actualmente está disponible mediante rutas de suscripción/OAuth: `openai-codex/gpt-5.5` en PI o `openai/gpt-5.5` con el arnés del servidor de aplicaciones Codex. La ruta directa con clave de API para `openai/gpt-5.5` será compatible una vez que OpenAI habilite GPT-5.5 en la API pública; hasta entonces, usa modelos habilitados para API como `openai/gpt-5.4` para configuraciones con `OPENAI_API_KEY`. +- Reglas de fallback, sondeos de cooldown y persistencia de anulaciones de sesión: [Conmutación por error de modelos](/es/concepts/model-failover). +- Las rutas de la familia OpenAI son específicas por prefijo: `openai/` usa el proveedor directo con clave de API de OpenAI en PI, `openai-codex/` usa OAuth de Codex en PI, y `openai/` más `agents.defaults.embeddedHarness.runtime: "codex"` usa el harness nativo del servidor de la app Codex. Consulta [OpenAI](/es/providers/openai) y [Harness de Codex](/es/plugins/codex-harness). +- La activación automática de Plugins sigue ese mismo límite: `openai-codex/` pertenece al Plugin de OpenAI, mientras que el Plugin de Codex se habilita mediante `embeddedHarness.runtime: "codex"` o referencias heredadas `codex/`. +- GPT-5.5 está disponible actualmente mediante rutas de suscripción/OAuth: + `openai-codex/gpt-5.5` en PI o `openai/gpt-5.5` con el harness del servidor de la app Codex. La ruta directa con clave de API para `openai/gpt-5.5` es compatible una vez que OpenAI habilite GPT-5.5 en la API pública; hasta entonces usa modelos habilitados para API, como `openai/gpt-5.4`, para configuraciones con `OPENAI_API_KEY`. ## Comportamiento del proveedor controlado por el Plugin -La mayor parte de la lógica específica de cada proveedor vive en plugins de proveedor (`registerProvider(...)`), mientras que OpenClaw mantiene el bucle de inferencia genérico. Los plugins se encargan de la incorporación, los catálogos de modelos, la asignación de variables de entorno de autenticación, la normalización de transporte/configuración, la limpieza de esquemas de herramientas, la clasificación de conmutación por error, la actualización de OAuth, el informe de uso, los perfiles de thinking/reasoning y más. +La mayor parte de la lógica específica del proveedor vive en Plugins de proveedor (`registerProvider(...)`) mientras OpenClaw mantiene el bucle de inferencia genérico. Los Plugins controlan la incorporación, los catálogos de modelos, el mapeo de variables de entorno de autenticación, la normalización de transporte/configuración, la limpieza del esquema de herramientas, la clasificación de conmutación por error, la actualización de OAuth, los informes de uso, los perfiles de thinking/reasoning y más. -La lista completa de hooks del SDK de proveedores y ejemplos de plugins incluidos está en [Plugins de proveedor](/es/plugins/sdk-provider-plugins). Un proveedor que necesite un ejecutor de solicitudes totalmente personalizado pertenece a una superficie de extensión aparte y más profunda. +La lista completa de hooks del SDK de proveedores y ejemplos de Plugins incluidos está en [Plugins de proveedor](/es/plugins/sdk-provider-plugins). Un proveedor que necesita un ejecutor de solicitudes totalmente personalizado es una superficie de extensión separada y más profunda. -La `capabilities` del tiempo de ejecución del proveedor es metadato compartido del ejecutor (familia del proveedor, particularidades de transcripción/herramientas, pistas de transporte/caché). No es lo mismo que el [modelo de capacidades públicas](/es/plugins/architecture#public-capability-model), que describe lo que registra un Plugin (inferencia de texto, voz, etc.). +La `capabilities` del tiempo de ejecución del proveedor es metadato compartido del runner (familia de proveedor, peculiaridades de transcripción/herramientas, sugerencias de transporte/caché). No es lo mismo que el [modelo público de capacidades](/es/plugins/architecture#public-capability-model), que describe lo que registra un Plugin (inferencia de texto, voz, etc.). ## Rotación de claves de API -- Admite rotación genérica de proveedores para proveedores seleccionados. +- Admite rotación genérica del proveedor para proveedores seleccionados. - Configura varias claves mediante: - - `OPENCLAW_LIVE__KEY` (anulación activa única, prioridad más alta) + - `OPENCLAW_LIVE__KEY` (una sola anulación activa, máxima prioridad) - `_API_KEYS` (lista separada por comas o punto y coma) - `_API_KEY` (clave principal) - `_API_KEY_*` (lista numerada, por ejemplo `_API_KEY_1`) -- Para los proveedores de Google, `GOOGLE_API_KEY` también se incluye como fallback. +- Para proveedores de Google, `GOOGLE_API_KEY` también se incluye como fallback. - El orden de selección de claves preserva la prioridad y elimina valores duplicados. -- Las solicitudes se reintentan con la siguiente clave solo en respuestas por límite de tasa (por ejemplo `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` o mensajes periódicos de límite de uso). -- Los errores que no son por límite de tasa fallan inmediatamente; no se intenta rotación de claves. +- Las solicitudes se reintentan con la siguiente clave solo en respuestas de límite de tasa (por + ejemplo `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +concurrent requests`, `ThrottlingException`, `concurrency limit reached`, + `workers_ai ... quota limit exceeded`, o mensajes periódicos de límite de uso). +- Los fallos que no son por límite de tasa fallan inmediatamente; no se intenta la rotación de claves. - Cuando fallan todas las claves candidatas, se devuelve el error final del último intento. ## Proveedores integrados (catálogo pi-ai) -OpenClaw incluye el catálogo pi-ai. Estos proveedores **no** requieren configuración en `models.providers`; solo configura la autenticación y elige un modelo. +OpenClaw se distribuye con el catálogo pi‑ai. Estos proveedores no requieren +configuración de `models.providers`; solo define la autenticación y elige un modelo. ### OpenAI - Proveedor: `openai` - Autenticación: `OPENAI_API_KEY` -- Rotación opcional: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, además de `OPENCLAW_LIVE_OPENAI_KEY` (anulación única) +- Rotación opcional: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, además de `OPENCLAW_LIVE_OPENAI_KEY` (una sola anulación) - Modelos de ejemplo: `openai/gpt-5.4`, `openai/gpt-5.4-mini` -- El soporte directo por API para GPT-5.5 está preparado aquí para cuando OpenAI exponga GPT-5.5 en la API +- La compatibilidad directa de API para GPT-5.5 está preparada para el futuro aquí una vez que OpenAI exponga GPT-5.5 en la API - CLI: `openclaw onboard --auth-choice openai-api-key` - El transporte predeterminado es `auto` (primero WebSocket, fallback a SSE) -- Anúlalo por modelo mediante `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) +- Anúlalo por modelo mediante `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, o `"auto"`) - El precalentamiento de WebSocket de OpenAI Responses está habilitado de forma predeterminada mediante `params.openaiWsWarmup` (`true`/`false`) -- El procesamiento prioritario de OpenAI se puede habilitar mediante `agents.defaults.models["openai/"].params.serviceTier` +- El procesamiento prioritario de OpenAI puede habilitarse mediante `agents.defaults.models["openai/"].params.serviceTier` - `/fast` y `params.fastMode` asignan solicitudes directas de Responses `openai/*` a `service_tier=priority` en `api.openai.com` - Usa `params.serviceTier` cuando quieras un nivel explícito en lugar del interruptor compartido `/fast` -- Los encabezados ocultos de atribución de OpenClaw (`originator`, `version`, `User-Agent`) se aplican solo al tráfico nativo de OpenAI hacia `api.openai.com`, no a proxies genéricos compatibles con OpenAI -- Las rutas nativas de OpenAI también conservan `store` de Responses, pistas de caché de prompts y el modelado de payload compatible con reasoning de OpenAI; las rutas por proxy no -- `openai/gpt-5.3-codex-spark` está intencionalmente suprimido en OpenClaw porque las solicitudes activas a la API de OpenAI lo rechazan y el catálogo actual de Codex no lo expone +- Los encabezados de atribución ocultos de OpenClaw (`originator`, `version`, + `User-Agent`) se aplican solo al tráfico nativo de OpenAI hacia `api.openai.com`, no a proxies genéricos compatibles con OpenAI +- Las rutas nativas de OpenAI también conservan `store` de Responses, sugerencias de caché de prompts y el modelado de carga útil de compatibilidad de reasoning de OpenAI; las rutas proxy no +- `openai/gpt-5.3-codex-spark` se omite intencionalmente en OpenClaw porque las solicitudes activas a la API de OpenAI lo rechazan y el catálogo actual de Codex no lo expone ```json5 { @@ -83,12 +89,12 @@ OpenClaw incluye el catálogo pi-ai. Estos proveedores **no** requieren configur - Proveedor: `anthropic` - Autenticación: `ANTHROPIC_API_KEY` -- Rotación opcional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, además de `OPENCLAW_LIVE_ANTHROPIC_KEY` (anulación única) +- Rotación opcional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, además de `OPENCLAW_LIVE_ANTHROPIC_KEY` (una sola anulación) - Modelo de ejemplo: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Las solicitudes directas públicas a Anthropic admiten el interruptor compartido `/fast` y `params.fastMode`, incluido el tráfico autenticado con clave de API y OAuth enviado a `api.anthropic.com`; OpenClaw lo asigna a `service_tier` de Anthropic (`auto` frente a `standard_only`) -- Nota sobre Anthropic: el personal de Anthropic nos dijo que el uso de Claude CLI al estilo OpenClaw vuelve a estar permitido, por lo que OpenClaw trata la reutilización de Claude CLI y el uso de `claude -p` como autorizados para esta integración, salvo que Anthropic publique una nueva política. -- El token de configuración de Anthropic sigue disponible como una ruta de token compatible en OpenClaw, pero OpenClaw ahora prefiere la reutilización de Claude CLI y `claude -p` cuando están disponibles. +- Las solicitudes directas públicas a Anthropic admiten el interruptor compartido `/fast` y `params.fastMode`, incluido el tráfico autenticado con clave de API y con OAuth enviado a `api.anthropic.com`; OpenClaw lo asigna a `service_tier` de Anthropic (`auto` frente a `standard_only`) +- Nota sobre Anthropic: personal de Anthropic nos dijo que el uso estilo Claude CLI de OpenClaw vuelve a estar permitido, por lo que OpenClaw considera que la reutilización de Claude CLI y el uso de `claude -p` están autorizados para esta integración a menos que Anthropic publique una nueva política. +- El token de configuración de Anthropic sigue disponible como una ruta de token compatible de OpenClaw, pero OpenClaw ahora prefiere la reutilización de Claude CLI y `claude -p` cuando está disponible. ```json5 { @@ -96,21 +102,23 @@ OpenClaw incluye el catálogo pi-ai. Estos proveedores **no** requieren configur } ``` -### OpenAI Codex OAuth +### OAuth de OpenAI Codex - Proveedor: `openai-codex` - Autenticación: OAuth (ChatGPT) - Referencia de modelo PI: `openai-codex/gpt-5.5` -- Referencia del arnés nativo del servidor de aplicaciones Codex: `openai/gpt-5.5` con `agents.defaults.embeddedHarness.runtime: "codex"` +- Referencia del harness nativo del servidor de la app Codex: `openai/gpt-5.5` con `agents.defaults.embeddedHarness.runtime: "codex"` - Referencias de modelo heredadas: `codex/gpt-*` -- Límite del Plugin: `openai-codex/*` carga el Plugin de OpenAI; el Plugin nativo del servidor de aplicaciones Codex se selecciona solo mediante el tiempo de ejecución del arnés Codex o referencias heredadas `codex/*`. +- Límite del Plugin: `openai-codex/*` carga el Plugin de OpenAI; el Plugin nativo del servidor de la app Codex se selecciona solo mediante el tiempo de ejecución del harness de Codex o referencias heredadas `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` o `openclaw models auth login --provider openai-codex` - El transporte predeterminado es `auto` (primero WebSocket, fallback a SSE) -- Anúlalo por modelo PI mediante `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` o `"auto"`) +- Anúlalo por modelo PI mediante `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"`, o `"auto"`) - `params.serviceTier` también se reenvía en solicitudes nativas de Codex Responses (`chatgpt.com/backend-api`) -- Los encabezados ocultos de atribución de OpenClaw (`originator`, `version`, `User-Agent`) solo se adjuntan en tráfico nativo de Codex hacia `chatgpt.com/backend-api`, no en proxies genéricos compatibles con OpenAI -- Comparte el mismo interruptor `/fast` y la configuración `params.fastMode` que `openai/*` directo; OpenClaw lo asigna a `service_tier=priority` -- `openai-codex/gpt-5.5` conserva `contextWindow = 1000000` nativo y un `contextTokens = 272000` predeterminado en tiempo de ejecución; anula el límite en tiempo de ejecución con `models.providers.openai-codex.models[].contextTokens` +- Los encabezados de atribución ocultos de OpenClaw (`originator`, `version`, + `User-Agent`) solo se adjuntan en el tráfico nativo de Codex hacia + `chatgpt.com/backend-api`, no a proxies genéricos compatibles con OpenAI +- Comparte el mismo interruptor `/fast` y la misma configuración `params.fastMode` que `openai/*` directo; OpenClaw lo asigna a `service_tier=priority` +- `openai-codex/gpt-5.5` conserva `contextWindow = 1000000` nativo y un valor predeterminado de tiempo de ejecución `contextTokens = 272000`; anula el límite de tiempo de ejecución con `models.providers.openai-codex.models[].contextTokens` - Nota de política: OpenAI Codex OAuth es compatible explícitamente para herramientas/flujos de trabajo externos como OpenClaw. - El acceso actual a GPT-5.5 usa esta ruta de OAuth/suscripción hasta que OpenAI habilite GPT-5.5 en la API pública. @@ -134,8 +142,8 @@ OpenClaw incluye el catálogo pi-ai. Estos proveedores **no** requieren configur ### Otras opciones alojadas de estilo suscripción -- [Qwen Cloud](/es/providers/qwen): superficie del proveedor Qwen Cloud más asignación de endpoints de Alibaba DashScope y Coding Plan -- [MiniMax](/es/providers/minimax): acceso por OAuth o clave de API de MiniMax Coding Plan +- [Qwen Cloud](/es/providers/qwen): superficie de proveedor de Qwen Cloud más mapeo de endpoints de Alibaba DashScope y Coding Plan +- [MiniMax](/es/providers/minimax): acceso OAuth o con clave de API de MiniMax Coding Plan - [GLM Models](/es/providers/glm): endpoints de Z.AI Coding Plan o de API general ### OpenCode @@ -156,27 +164,31 @@ OpenClaw incluye el catálogo pi-ai. Estos proveedores **no** requieren configur - Proveedor: `google` - Autenticación: `GEMINI_API_KEY` -- Rotación opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback a `GOOGLE_API_KEY` y `OPENCLAW_LIVE_GEMINI_KEY` (anulación única) +- Rotación opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback de `GOOGLE_API_KEY` y `OPENCLAW_LIVE_GEMINI_KEY` (una sola anulación) - Modelos de ejemplo: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Compatibilidad: la configuración heredada de OpenClaw que usa `google/gemini-3.1-flash-preview` se normaliza a `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Las ejecuciones directas de Gemini también aceptan `agents.defaults.models["google/"].params.cachedContent` (o el heredado `cached_content`) para reenviar un identificador nativo del proveedor `cachedContents/...`; los aciertos de caché de Gemini aparecen como `cacheRead` en OpenClaw +- Las ejecuciones directas de Gemini también aceptan `agents.defaults.models["google/"].params.cachedContent` + (o el heredado `cached_content`) para reenviar un identificador nativo del proveedor + `cachedContents/...`; los aciertos de caché de Gemini se muestran como `cacheRead` de OpenClaw ### Google Vertex y Gemini CLI - Proveedores: `google-vertex`, `google-gemini-cli` - Autenticación: Vertex usa gcloud ADC; Gemini CLI usa su flujo de OAuth -- Precaución: OAuth de Gemini CLI en OpenClaw es una integración no oficial. Algunos usuarios han informado restricciones en cuentas de Google tras usar clientes de terceros. Revisa los términos de Google y usa una cuenta no crítica si decides continuar. -- OAuth de Gemini CLI se distribuye como parte del Plugin `google` incluido. +- Precaución: el OAuth de Gemini CLI en OpenClaw es una integración no oficial. Algunos usuarios han informado restricciones en cuentas de Google después de usar clientes de terceros. Revisa los términos de Google y usa una cuenta no crítica si decides continuar. +- El OAuth de Gemini CLI se distribuye como parte del Plugin `google` incluido. - Instala primero Gemini CLI: - `brew install gemini-cli` - o `npm install -g @google/gemini-cli` - Habilita: `openclaw plugins enable google` - Inicia sesión: `openclaw models auth login --provider google-gemini-cli --set-default` - Modelo predeterminado: `google-gemini-cli/gemini-3-flash-preview` - - Nota: **no** pegas un client id ni un secreto en `openclaw.json`. El flujo de inicio de sesión de CLI almacena los tokens en perfiles de autenticación en el host del Gateway. + - Nota: **no** pegas un id de cliente ni un secreto en `openclaw.json`. El flujo de inicio de sesión del CLI almacena + tokens en perfiles de autenticación en el host del Gateway. - Si las solicitudes fallan después de iniciar sesión, configura `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host del Gateway. - - Las respuestas JSON de Gemini CLI se analizan desde `response`; el uso vuelve a `stats` como fallback, con `stats.cached` normalizado a `cacheRead` de OpenClaw. + - Las respuestas JSON de Gemini CLI se analizan desde `response`; el uso recurre a + `stats`, con `stats.cached` normalizado a `cacheRead` de OpenClaw. ### Z.AI (GLM) @@ -191,7 +203,8 @@ OpenClaw incluye el catálogo pi-ai. Estos proveedores **no** requieren configur - Proveedor: `vercel-ai-gateway` - Autenticación: `AI_GATEWAY_API_KEY` -- Modelos de ejemplo: `vercel-ai-gateway/anthropic/claude-opus-4.6`, `vercel-ai-gateway/moonshotai/kimi-k2.6` +- Modelos de ejemplo: `vercel-ai-gateway/anthropic/claude-opus-4.6`, + `vercel-ai-gateway/moonshotai/kimi-k2.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway @@ -201,63 +214,71 @@ OpenClaw incluye el catálogo pi-ai. Estos proveedores **no** requieren configur - Modelo de ejemplo: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - URL base: `https://api.kilo.ai/api/gateway/` -- El catálogo estático de fallback incluye `kilocode/kilo/auto`; el descubrimiento activo en `https://api.kilo.ai/api/gateway/models` puede ampliar aún más el catálogo en tiempo de ejecución. -- El enrutamiento exacto aguas arriba detrás de `kilocode/kilo/auto` pertenece a Kilo Gateway, no está codificado de forma rígida en OpenClaw. +- El catálogo estático de fallback incluye `kilocode/kilo/auto`; el descubrimiento activo de + `https://api.kilo.ai/api/gateway/models` puede ampliar aún más el catálogo + en tiempo de ejecución. +- El enrutamiento exacto upstream detrás de `kilocode/kilo/auto` lo controla Kilo Gateway, + no está codificado de forma fija en OpenClaw. -Consulta [/providers/kilocode](/es/providers/kilocode) para ver los detalles de configuración. +Consulta [/providers/kilocode](/es/providers/kilocode) para conocer los detalles de configuración. -### Otros plugins de proveedor incluidos +### Otros Plugins de proveedor incluidos -| Proveedor | Id | Variable de entorno de autenticación | Modelo de ejemplo | -| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | -| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | -| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | -| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | -| Groq | `groq` | `GROQ_API_KEY` | — | -| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` o `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` o `KIMICODE_API_KEY` | `kimi/kimi-code` | -| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | -| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | -| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| Proveedor | Id | Variable de entorno de autenticación | Modelo de ejemplo | +| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | +| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | +| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | +| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | +| Groq | `groq` | `GROQ_API_KEY` | — | +| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` o `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | +| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kimi Coding | `kimi` | `KIMI_API_KEY` o `KIMICODE_API_KEY` | `kimi/kimi-code` | +| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | +| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | | NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | -| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | -| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | -| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | -| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | -| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | -| Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | -| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | -| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | -| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | +| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | +| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | +| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | +| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | +| Venice | `venice` | `VENICE_API_KEY` | — | +| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | +| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | +| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -Particularidades que conviene conocer: +Aspectos importantes que conviene conocer: -- **OpenRouter** aplica sus encabezados de atribución de aplicación y los marcadores Anthropic `cache_control` solo en rutas verificadas de `openrouter.ai`. Como ruta tipo proxy compatible con OpenAI, omite el modelado exclusivo de OpenAI nativo (`serviceTier`, `store` de Responses, pistas de caché de prompts, compatibilidad de reasoning de OpenAI). Las referencias basadas en Gemini conservan solo el saneamiento de firmas de pensamiento de Gemini vía proxy. -- **Kilo Gateway** en referencias basadas en Gemini sigue la misma ruta de saneamiento de Gemini vía proxy; `kilocode/kilo/auto` y otras referencias proxy sin compatibilidad con reasoning omiten la inyección de reasoning vía proxy. -- **MiniMax** en la incorporación con clave de API escribe definiciones explícitas de modelos M2.7 con `input: ["text", "image"]`; el catálogo incluido mantiene las referencias de chat como solo texto hasta que esa configuración se materializa. -- **xAI** usa la ruta xAI Responses. `/fast` o `params.fastMode: true` reescribe `grok-3`, `grok-3-mini`, `grok-4` y `grok-4-0709` a sus variantes `*-fast`. `tool_stream` está activado de forma predeterminada; desactívalo con `agents.defaults.models["xai/"].params.tool_stream=false`. -- **Cerebras** los modelos GLM usan `zai-glm-4.7` / `zai-glm-4.6`; la URL base compatible con OpenAI es `https://api.cerebras.ai/v1`. +- **OpenRouter** aplica sus encabezados de atribución de aplicación y los marcadores `cache_control` de Anthropic solo en rutas verificadas de `openrouter.ai`. Como ruta estilo proxy compatible con OpenAI, omite el modelado exclusivo de OpenAI nativo (`serviceTier`, `store` de Responses, sugerencias de caché de prompts, compatibilidad de reasoning de OpenAI). Las referencias respaldadas por Gemini conservan únicamente el saneamiento de firmas de pensamiento de proxy-Gemini. +- **Kilo Gateway**: las referencias respaldadas por Gemini siguen la misma ruta de saneamiento de proxy-Gemini; `kilocode/kilo/auto` y otras referencias proxy no compatibles con reasoning omiten la inyección de reasoning de proxy. +- **MiniMax**: la incorporación con clave de API escribe definiciones explícitas de modelos M2.7 con `input: ["text", "image"]`; el catálogo incluido mantiene las referencias de chat solo como texto hasta que se materializa esa configuración. +- **xAI** usa la ruta de xAI Responses. `/fast` o `params.fastMode: true` reescribe `grok-3`, `grok-3-mini`, `grok-4` y `grok-4-0709` a sus variantes `*-fast`. `tool_stream` viene activado de forma predeterminada; desactívalo mediante `agents.defaults.models["xai/"].params.tool_stream=false`. +- **Cerebras**: los modelos GLM usan `zai-glm-4.7` / `zai-glm-4.6`; la URL base compatible con OpenAI es `https://api.cerebras.ai/v1`. ## Proveedores mediante `models.providers` (personalizado/URL base) -Usa `models.providers` (o `models.json`) para añadir proveedores **personalizados** o proxies compatibles con OpenAI/Anthropic. +Usa `models.providers` (o `models.json`) para añadir proveedores **personalizados** o +proxies compatibles con OpenAI/Anthropic. -Muchos de los plugins de proveedor incluidos a continuación ya publican un catálogo predeterminado. -Usa entradas explícitas `models.providers.` solo cuando quieras anular la URL base, los encabezados o la lista de modelos predeterminados. +Muchos de los Plugins de proveedor incluidos a continuación ya publican un catálogo predeterminado. +Usa entradas explícitas `models.providers.` solo cuando quieras anular la +URL base, los encabezados o la lista de modelos predeterminados. ### Moonshot AI (Kimi) -Moonshot se incluye como Plugin de proveedor. Usa el proveedor integrado de forma predeterminada y añade una entrada explícita `models.providers.moonshot` solo cuando necesites anular la URL base o los metadatos del modelo: +Moonshot se distribuye como un Plugin de proveedor incluido. Usa el proveedor integrado de forma +predeterminada y añade una entrada explícita `models.providers.moonshot` solo cuando +necesites anular la URL base o los metadatos del modelo: - Proveedor: `moonshot` - Autenticación: `MOONSHOT_API_KEY` - Modelo de ejemplo: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` o `openclaw onboard --auth-choice moonshot-api-key-cn` -Ids de modelo de Kimi K2: +Ids de modelo Kimi K2: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -305,7 +326,7 @@ Kimi Coding usa el endpoint compatible con Anthropic de Moonshot AI: } ``` -El id de modelo de compatibilidad heredado `kimi/k2p5` sigue siendo aceptado. +El id de modelo heredado `kimi/k2p5` sigue aceptándose por compatibilidad. ### Volcano Engine (Doubao) @@ -324,9 +345,13 @@ Volcano Engine (火山引擎) proporciona acceso a Doubao y otros modelos en Chi } ``` -La incorporación usa de forma predeterminada la superficie de coding, pero el catálogo general `volcengine/*` se registra al mismo tiempo. +La incorporación usa de forma predeterminada la superficie de coding, pero el +catálogo general `volcengine/*` se registra al mismo tiempo. -En los selectores de incorporación/configuración de modelos, la opción de autenticación de Volcengine prioriza tanto las filas `volcengine/*` como `volcengine-plan/*`. Si esos modelos todavía no están cargados, OpenClaw usa como fallback el catálogo sin filtrar en lugar de mostrar un selector vacío limitado al proveedor. +En los selectores de modelos de incorporación/configuración, la opción de autenticación de Volcengine prioriza tanto las filas +`volcengine/*` como `volcengine-plan/*`. Si esos modelos aún no están cargados, +OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector +vacío limitado al proveedor. Modelos disponibles: @@ -361,9 +386,13 @@ BytePlus ARK proporciona acceso a los mismos modelos que Volcano Engine para usu } ``` -La incorporación usa de forma predeterminada la superficie de coding, pero el catálogo general `byteplus/*` se registra al mismo tiempo. +La incorporación usa de forma predeterminada la superficie de coding, pero el +catálogo general `byteplus/*` se registra al mismo tiempo. -En los selectores de incorporación/configuración de modelos, la opción de autenticación de BytePlus prioriza tanto las filas `byteplus/*` como `byteplus-plan/*`. Si esos modelos todavía no están cargados, OpenClaw usa como fallback el catálogo sin filtrar en lugar de mostrar un selector vacío limitado al proveedor. +En los selectores de modelos de incorporación/configuración, la opción de autenticación de BytePlus prioriza tanto +las filas `byteplus/*` como `byteplus-plan/*`. Si esos modelos aún no están cargados, +OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector +vacío limitado al proveedor. Modelos disponibles: @@ -411,32 +440,35 @@ Synthetic proporciona modelos compatibles con Anthropic detrás del proveedor `s MiniMax se configura mediante `models.providers` porque usa endpoints personalizados: -- OAuth de MiniMax (global): `--auth-choice minimax-global-oauth` -- OAuth de MiniMax (CN): `--auth-choice minimax-cn-oauth` +- MiniMax OAuth (global): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` - Clave de API de MiniMax (global): `--auth-choice minimax-global-api` - Clave de API de MiniMax (CN): `--auth-choice minimax-cn-api` -- Autenticación: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` para `minimax-portal` +- Autenticación: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` o + `MINIMAX_API_KEY` para `minimax-portal` Consulta [/providers/minimax](/es/providers/minimax) para ver detalles de configuración, opciones de modelos y fragmentos de configuración. -En la ruta de streaming compatible con Anthropic de MiniMax, OpenClaw desactiva thinking de forma predeterminada a menos que lo configures explícitamente, y `/fast on` reescribe `MiniMax-M2.7` a `MiniMax-M2.7-highspeed`. +En la ruta de streaming compatible con Anthropic de MiniMax, OpenClaw desactiva thinking de forma +predeterminada a menos que lo configures explícitamente, y `/fast on` reescribe +`MiniMax-M2.7` a `MiniMax-M2.7-highspeed`. -Separación de capacidades controladas por Plugin: +División de capacidades controlada por Plugin: - Los valores predeterminados de texto/chat permanecen en `minimax/MiniMax-M2.7` - La generación de imágenes es `minimax/image-01` o `minimax-portal/image-01` -- El entendimiento de imágenes es `MiniMax-VL-01`, controlado por Plugin, en ambas rutas de autenticación de MiniMax +- La comprensión de imágenes es `MiniMax-VL-01` controlado por Plugin en ambas rutas de autenticación de MiniMax - La búsqueda web permanece en el id de proveedor `minimax` ### LM Studio -LM Studio se incluye como Plugin de proveedor y usa la API nativa: +LM Studio se distribuye como un Plugin de proveedor incluido que usa la API nativa: - Proveedor: `lmstudio` - Autenticación: `LM_API_TOKEN` -- URL base de inferencia predeterminada: `http://localhost:1234/v1` +- URL base predeterminada de inferencia: `http://localhost:1234/v1` -Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `http://localhost:1234/api/v1/models`): +Luego configura un modelo (sustituye por uno de los ids devueltos por `http://localhost:1234/api/v1/models`): ```json5 { @@ -446,15 +478,16 @@ Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `http:/ } ``` -OpenClaw usa `/api/v1/models` y `/api/v1/models/load` nativos de LM Studio para descubrimiento + carga automática, con `/v1/chat/completions` para inferencia de forma predeterminada. -Consulta [/providers/lmstudio](/es/providers/lmstudio) para configuración y solución de problemas. +OpenClaw usa `/api/v1/models` y `/api/v1/models/load` nativos de LM Studio +para descubrimiento + carga automática, con `/v1/chat/completions` para inferencia de forma predeterminada. +Consulta [/providers/lmstudio](/es/providers/lmstudio) para ver configuración y solución de problemas. ### Ollama -Ollama se incluye como Plugin de proveedor y usa la API nativa de Ollama: +Ollama se distribuye como un Plugin de proveedor incluido y usa la API nativa de Ollama: - Proveedor: `ollama` -- Autenticación: no se requiere ninguna (servidor local) +- Autenticación: no se requiere (servidor local) - Modelo de ejemplo: `ollama/llama3.3` - Instalación: [https://ollama.com/download](https://ollama.com/download) @@ -471,23 +504,27 @@ ollama pull llama3.3 } ``` -Ollama se detecta localmente en `http://127.0.0.1:11434` cuando optas por usarlo con `OLLAMA_API_KEY`, y el Plugin de proveedor incluido añade Ollama directamente a `openclaw onboard` y al selector de modelos. Consulta [/providers/ollama](/es/providers/ollama) para ver incorporación, modo nube/local y configuración personalizada. +Ollama se detecta localmente en `http://127.0.0.1:11434` cuando optas por activarlo con +`OLLAMA_API_KEY`, y el Plugin de proveedor incluido añade Ollama directamente a +`openclaw onboard` y al selector de modelos. Consulta [/providers/ollama](/es/providers/ollama) +para ver incorporación, modo local/en la nube y configuración personalizada. ### vLLM -vLLM se incluye como Plugin de proveedor para servidores locales/autohospedados compatibles con OpenAI: +vLLM se distribuye como un Plugin de proveedor incluido para servidores locales/autohospedados +compatibles con OpenAI: - Proveedor: `vllm` - Autenticación: opcional (depende de tu servidor) - URL base predeterminada: `http://127.0.0.1:8000/v1` -Para activar el descubrimiento automático localmente (cualquier valor sirve si tu servidor no exige autenticación): +Para activar el descubrimiento automático localmente (cualquier valor funciona si tu servidor no exige autenticación): ```bash export VLLM_API_KEY="vllm-local" ``` -Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `/v1/models`): +Luego configura un modelo (sustituye por uno de los ids devueltos por `/v1/models`): ```json5 { @@ -497,23 +534,25 @@ Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `/v1/mo } ``` -Consulta [/providers/vllm](/es/providers/vllm) para más detalles. +Consulta [/providers/vllm](/es/providers/vllm) para obtener más detalles. ### SGLang -SGLang se incluye como Plugin de proveedor para servidores rápidos autohospedados compatibles con OpenAI: +SGLang se distribuye como un Plugin de proveedor incluido para servidores autohospedados rápidos +compatibles con OpenAI: - Proveedor: `sglang` - Autenticación: opcional (depende de tu servidor) - URL base predeterminada: `http://127.0.0.1:30000/v1` -Para activar el descubrimiento automático localmente (cualquier valor sirve si tu servidor no exige autenticación): +Para activar el descubrimiento automático localmente (cualquier valor funciona si tu servidor no +exige autenticación): ```bash export SGLANG_API_KEY="sglang-local" ``` -Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `/v1/models`): +Luego configura un modelo (sustituye por uno de los ids devueltos por `/v1/models`): ```json5 { @@ -523,7 +562,7 @@ Luego configura un modelo (sustitúyelo por uno de los ids devueltos por `/v1/mo } ``` -Consulta [/providers/sglang](/es/providers/sglang) para más detalles. +Consulta [/providers/sglang](/es/providers/sglang) para obtener más detalles. ### Proxies locales (LM Studio, vLLM, LiteLLM, etc.) @@ -569,10 +608,13 @@ Notas: - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Recomendado: configura valores explícitos que coincidan con los límites de tu proxy/modelo. +- Recomendación: configura valores explícitos que coincidan con los límites de tu proxy/modelo. - Para `api: "openai-completions"` en endpoints no nativos (cualquier `baseUrl` no vacío cuyo host no sea `api.openai.com`), OpenClaw fuerza `compat.supportsDeveloperRole: false` para evitar errores 400 del proveedor por roles `developer` no compatibles. -- Las rutas tipo proxy compatibles con OpenAI también omiten el modelado de solicitudes exclusivo de OpenAI nativo: sin `service_tier`, sin `store` de Responses, sin pistas de caché de prompts, sin modelado de payload compatible con reasoning de OpenAI y sin encabezados ocultos de atribución de OpenClaw. -- Si `baseUrl` está vacío o se omite, OpenClaw mantiene el comportamiento predeterminado de OpenAI (que se resuelve en `api.openai.com`). +- Las rutas compatibles con OpenAI de estilo proxy también omiten el modelado de solicitudes exclusivo de OpenAI nativo: + sin `service_tier`, sin `store` de Responses, sin sugerencias de caché de prompts, sin + modelado de carga útil de compatibilidad de reasoning de OpenAI y sin encabezados + ocultos de atribución de OpenClaw. +- Si `baseUrl` está vacío o se omite, OpenClaw conserva el comportamiento predeterminado de OpenAI (que se resuelve en `api.openai.com`). - Por seguridad, un `compat.supportsDeveloperRole: true` explícito sigue siendo reemplazado en endpoints `openai-completions` no nativos. ## Ejemplos de CLI diff --git a/docs/es/pi.md b/docs/es/pi.md index 400a2157e..811212969 100644 --- a/docs/es/pi.md +++ b/docs/es/pi.md @@ -1,48 +1,48 @@ --- read_when: - - Entender el diseño de integración del SDK de Pi en OpenClaw + - Comprender el diseño de integración del SDK de Pi en OpenClaw - Modificar el ciclo de vida de la sesión del agente, las herramientas o la conexión del proveedor para Pi -summary: Arquitectura de la integración del agente Pi incrustado de OpenClaw y del ciclo de vida de la sesión +summary: Arquitectura de la integración del agente Pi integrado de OpenClaw y ciclo de vida de la sesión title: Arquitectura de integración de Pi x-i18n: - generated_at: "2026-04-24T05:37:33Z" + generated_at: "2026-04-24T15:21:26Z" model: gpt-5.4 provider: openai - source_hash: 3c0c490cad121a65d557a72887ea619a7d0cff34a62220752214185c9148dc0b + source_hash: 0c0b019ff6d35f6fdcd57b56edd1945e62a96bb4b34e312d7fb0c627f01287f1 source_path: pi.md workflow: 15 --- -Este documento describe cómo OpenClaw se integra con [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) y sus paquetes hermanos (`pi-ai`, `pi-agent-core`, `pi-tui`) para potenciar sus capacidades de agente de IA. +Este documento describe cómo OpenClaw se integra con [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) y sus paquetes relacionados (`pi-ai`, `pi-agent-core`, `pi-tui`) para impulsar sus capacidades de agente de IA. -## Descripción general +## Resumen -OpenClaw usa el SDK de pi para incrustar un agente de codificación con IA en su arquitectura de gateway de mensajería. En lugar de generar pi como un subproceso o usar modo RPC, OpenClaw importa e instancia directamente `AgentSession` de pi mediante `createAgentSession()`. Este enfoque incrustado proporciona: +OpenClaw usa el SDK de pi para integrar un agente de codificación de IA en su arquitectura Gateway de mensajería. En lugar de iniciar pi como un subproceso o usar el modo RPC, OpenClaw importa e instancia directamente `AgentSession` de pi mediante `createAgentSession()`. Este enfoque integrado proporciona: - Control total sobre el ciclo de vida de la sesión y el manejo de eventos -- Inyección de herramientas personalizada (mensajería, sandbox, acciones específicas de canal) +- Inyección de herramientas personalizadas (mensajería, sandbox, acciones específicas del canal) - Personalización del prompt del sistema por canal/contexto -- Persistencia de sesión con soporte de ramificación/Compaction -- Rotación de perfiles de autenticación multiaccount con conmutación por error +- Persistencia de sesión con soporte para bifurcación/Compaction +- Rotación de perfiles de autenticación de múltiples cuentas con failover - Cambio de modelo independiente del proveedor ## Dependencias de paquetes ```json { - "@mariozechner/pi-agent-core": "0.68.1", - "@mariozechner/pi-ai": "0.68.1", - "@mariozechner/pi-coding-agent": "0.68.1", - "@mariozechner/pi-tui": "0.68.1" + "@mariozechner/pi-agent-core": "0.70.2", + "@mariozechner/pi-ai": "0.70.2", + "@mariozechner/pi-coding-agent": "0.70.2", + "@mariozechner/pi-tui": "0.70.2" } ``` -| Paquete | Propósito | -| ---------------- | ------------------------------------------------------------------------------------------------------ | -| `pi-ai` | Abstracciones principales de LLM: `Model`, `streamSimple`, tipos de mensaje, API de proveedores | -| `pi-agent-core` | Bucle del agente, ejecución de herramientas, tipos `AgentMessage` | -| `pi-coding-agent`| SDK de alto nivel: `createAgentSession`, `SessionManager`, `AuthStorage`, `ModelRegistry`, herramientas integradas | -| `pi-tui` | Componentes de interfaz de terminal (usados en el modo TUI local de OpenClaw) | +| Package | Purpose | +| ----------------- | ------------------------------------------------------------------------------------------------------ | +| `pi-ai` | Abstracciones centrales de LLM: `Model`, `streamSimple`, tipos de mensaje, API de proveedores | +| `pi-agent-core` | Bucle del agente, ejecución de herramientas, tipos `AgentMessage` | +| `pi-coding-agent` | SDK de alto nivel: `createAgentSession`, `SessionManager`, `AuthStorage`, `ModelRegistry`, herramientas integradas | +| `pi-tui` | Componentes de interfaz de usuario de terminal (usados en el modo TUI local de OpenClaw) | ## Estructura de archivos @@ -52,55 +52,55 @@ src/agents/ ├── pi-embedded-runner/ │ ├── run.ts # Entrada principal: runEmbeddedPiAgent() │ ├── run/ -│ │ ├── attempt.ts # Lógica de intento único con configuración de sesión +│ │ ├── attempt.ts # Lógica de un solo intento con configuración de sesión │ │ ├── params.ts # Tipo RunEmbeddedPiAgentParams -│ │ ├── payloads.ts # Construir cargas de respuesta a partir de resultados de ejecución -│ │ ├── images.ts # Inyección de imágenes para modelo de visión +│ │ ├── payloads.ts # Construye payloads de respuesta a partir de resultados de ejecución +│ │ ├── images.ts # Inyección de imágenes del modelo de visión │ │ └── types.ts # EmbeddedRunAttemptResult -│ ├── abort.ts # Detección de error de interrupción +│ ├── abort.ts # Detección de errores de cancelación │ ├── cache-ttl.ts # Seguimiento de TTL de caché para poda de contexto │ ├── compact.ts # Lógica manual/automática de Compaction -│ ├── extensions.ts # Cargar extensiones de pi para ejecuciones incrustadas -│ ├── extra-params.ts # Parámetros stream específicos del proveedor -│ ├── google.ts # Correcciones de orden de turnos de Google/Gemini -│ ├── history.ts # Límite de historial (DM frente a grupo) -│ ├── lanes.ts # Vías de comandos globales/de sesión -│ ├── logger.ts # Logger del subsistema -│ ├── model.ts # Resolución de modelo mediante ModelRegistry -│ ├── runs.ts # Seguimiento de ejecuciones activas, interrupción, cola +│ ├── extensions.ts # Carga extensiones de pi para ejecuciones integradas +│ ├── extra-params.ts # Parámetros de flujo específicos del proveedor +│ ├── google.ts # Correcciones de orden de turno para Google/Gemini +│ ├── history.ts # Limitación del historial (DM frente a grupo) +│ ├── lanes.ts # Carriles de comandos de sesión/globales +│ ├── logger.ts # Registrador del subsistema +│ ├── model.ts # Resolución de modelos mediante ModelRegistry +│ ├── runs.ts # Seguimiento de ejecuciones activas, cancelación, cola │ ├── sandbox-info.ts # Información de sandbox para el prompt del sistema │ ├── session-manager-cache.ts # Caché de instancias de SessionManager -│ ├── session-manager-init.ts # Inicialización del archivo de sesión +│ ├── session-manager-init.ts # Inicialización de archivos de sesión │ ├── system-prompt.ts # Constructor del prompt del sistema -│ ├── tool-split.ts # Dividir herramientas en builtIn frente a custom +│ ├── tool-split.ts # Divide herramientas entre builtIn y personalizadas │ ├── types.ts # EmbeddedPiAgentMeta, EmbeddedPiRunResult -│ └── utils.ts # Mapeo ThinkLevel, descripción de error -├── pi-embedded-subscribe.ts # Suscripción/despacho de eventos de sesión +│ └── utils.ts # Mapeo de ThinkLevel, descripción de errores +├── pi-embedded-subscribe.ts # Suscripción/dispatch de eventos de sesión ├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams -├── pi-embedded-subscribe.handlers.ts # Fábrica de controladores de eventos +├── pi-embedded-subscribe.handlers.ts # Fábrica de manejadores de eventos ├── pi-embedded-subscribe.handlers.lifecycle.ts ├── pi-embedded-subscribe.handlers.types.ts -├── pi-embedded-block-chunker.ts # Fragmentación de respuestas en bloque en streaming -├── pi-embedded-messaging.ts # Seguimiento de envíos de herramientas de mensajería +├── pi-embedded-block-chunker.ts # División en bloques de respuestas en streaming +├── pi-embedded-messaging.ts # Seguimiento de envíos de la herramienta de mensajería ├── pi-embedded-helpers.ts # Clasificación de errores, validación de turnos ├── pi-embedded-helpers/ # Módulos auxiliares ├── pi-embedded-utils.ts # Utilidades de formato ├── pi-tools.ts # createOpenClawCodingTools() -├── pi-tools.abort.ts # Contenedor AbortSignal para herramientas +├── pi-tools.abort.ts # Envoltorio de AbortSignal para herramientas ├── pi-tools.policy.ts # Política de lista de permitidos/denegados de herramientas -├── pi-tools.read.ts # Personalizaciones de herramienta read -├── pi-tools.schema.ts # Normalización de esquema de herramientas +├── pi-tools.read.ts # Personalizaciones de la herramienta de lectura +├── pi-tools.schema.ts # Normalización de esquemas de herramientas ├── pi-tools.types.ts # Alias de tipo AnyAgentTool -├── pi-tool-definition-adapter.ts # Adaptador AgentTool -> ToolDefinition -├── pi-settings.ts # Sobrescrituras de configuración +├── pi-tool-definition-adapter.ts # Adaptador de AgentTool -> ToolDefinition +├── pi-settings.ts # Reemplazos de configuración ├── pi-hooks/ # Hooks personalizados de pi -│ ├── compaction-safeguard.ts # Extensión de salvaguarda +│ ├── compaction-safeguard.ts # Extensión de protección │ ├── compaction-safeguard-runtime.ts -│ ├── context-pruning.ts # Extensión de poda de contexto por TTL de caché +│ ├── context-pruning.ts # Extensión de poda de contexto Cache-TTL │ └── context-pruning/ -├── model-auth.ts # Resolución de perfil de autenticación -├── auth-profiles.ts # Almacén de perfiles, enfriamiento, conmutación por error -├── model-selection.ts # Resolución de modelo predeterminado +├── model-auth.ts # Resolución de perfiles de autenticación +├── auth-profiles.ts # Almacén de perfiles, enfriamiento, failover +├── model-selection.ts # Resolución del modelo predeterminado ├── models-config.ts # Generación de models.json ├── model-catalog.ts # Caché del catálogo de modelos ├── context-window-guard.ts # Validación de ventana de contexto @@ -109,18 +109,18 @@ src/agents/ ├── system-prompt.ts # buildAgentSystemPrompt() ├── system-prompt-params.ts # Resolución de parámetros del prompt del sistema ├── system-prompt-report.ts # Generación de informe de depuración -├── tool-summaries.ts # Resúmenes descriptivos de herramientas +├── tool-summaries.ts # Resúmenes de descripciones de herramientas ├── tool-policy.ts # Resolución de política de herramientas -├── transcript-policy.ts # Política de validación de transcripción -├── skills.ts # Instantánea/construcción de prompt de Skills +├── transcript-policy.ts # Política de validación de transcripciones +├── skills.ts # Construcción de snapshot/prompt de Skills ├── skills/ # Subsistema de Skills ├── sandbox.ts # Resolución de contexto de sandbox ├── sandbox/ # Subsistema de sandbox -├── channel-tools.ts # Inyección de herramientas específicas de canal +├── channel-tools.ts # Inyección de herramientas específicas del canal ├── openclaw-tools.ts # Herramientas específicas de OpenClaw ├── bash-tools.ts # Herramientas exec/process -├── apply-patch.ts # herramienta apply_patch (OpenAI) -├── tools/ # Implementaciones individuales de herramientas +├── apply-patch.ts # Herramienta apply_patch (OpenAI) +├── tools/ # Implementaciones de herramientas individuales │ ├── browser-tool.ts │ ├── canvas-tool.ts │ ├── cron-tool.ts @@ -134,19 +134,18 @@ src/agents/ └── ... ``` -Los runtimes de acción de mensajes específicos de canal ahora viven en los directorios -de extensiones propiedad del Plugin en lugar de bajo `src/agents/tools`, por ejemplo: +Los tiempos de ejecución de acciones de mensajes específicos del canal ahora viven en los directorios de extensiones propiedad del Plugin, en lugar de bajo `src/agents/tools`, por ejemplo: -- los archivos de runtime de acción del Plugin de Discord -- el archivo de runtime de acción del Plugin de Slack -- el archivo de runtime de acción del Plugin de Telegram -- el archivo de runtime de acción del Plugin de WhatsApp +- los archivos de tiempo de ejecución de acciones del Plugin de Discord +- el archivo de tiempo de ejecución de acciones del Plugin de Slack +- el archivo de tiempo de ejecución de acciones del Plugin de Telegram +- el archivo de tiempo de ejecución de acciones del Plugin de WhatsApp -## Flujo principal de integración +## Flujo central de integración -### 1. Ejecutar un agente incrustado +### 1. Ejecución de un agente integrado -La entrada principal es `runEmbeddedPiAgent()` en `pi-embedded-runner/run.ts`: +El punto de entrada principal es `runEmbeddedPiAgent()` en `pi-embedded-runner/run.ts`: ```typescript import { runEmbeddedPiAgent } from "./agents/pi-embedded-runner.js"; @@ -224,7 +223,7 @@ const subscription = subscribeEmbeddedPiSession({ }); ``` -Los eventos gestionados incluyen: +Los eventos manejados incluyen: - `message_start` / `message_end` / `message_update` (texto/pensamiento en streaming) - `tool_execution_start` / `tool_execution_update` / `tool_execution_end` @@ -232,35 +231,33 @@ Los eventos gestionados incluyen: - `agent_start` / `agent_end` - `compaction_start` / `compaction_end` -### 4. Prompting +### 4. Prompts -Después de la configuración, se lanza el prompt de la sesión: +Después de la configuración, se envía el prompt a la sesión: ```typescript await session.prompt(effectivePrompt, { images: imageResult.images }); ``` -El SDK gestiona el bucle completo del agente: envío al LLM, ejecución de llamadas a herramientas y respuestas en streaming. +El SDK maneja el bucle completo del agente: envío al LLM, ejecución de llamadas a herramientas y streaming de respuestas. -La inyección de imágenes es local al prompt: OpenClaw carga referencias de imagen del prompt actual y -las pasa mediante `images` solo para ese turno. No vuelve a escanear turnos anteriores del historial -para volver a inyectar cargas de imágenes. +La inyección de imágenes es local al prompt: OpenClaw carga referencias de imagen del prompt actual y las pasa mediante `images` solo para ese turno. No vuelve a escanear turnos anteriores del historial para reinyectar payloads de imagen. ## Arquitectura de herramientas -### Flujo de herramientas +### Canalización de herramientas -1. **Herramientas base**: `codingTools` de pi (read, bash, edit, write) +1. **Herramientas base**: `codingTools` de pi (`read`, `bash`, `edit`, `write`) 2. **Reemplazos personalizados**: OpenClaw reemplaza bash con `exec`/`process`, personaliza read/edit/write para sandbox -3. **Herramientas de OpenClaw**: mensajería, navegador, canvas, sesiones, cron, gateway, etc. -4. **Herramientas de canal**: herramientas de acción específicas de Discord/Telegram/Slack/WhatsApp -5. **Filtrado por política**: herramientas filtradas por políticas de perfil, proveedor, agente, grupo y sandbox -6. **Normalización de esquema**: esquemas limpiados para peculiaridades de Gemini/OpenAI -7. **Contenedor AbortSignal**: herramientas envueltas para respetar señales de interrupción +3. **Herramientas de OpenClaw**: mensajería, navegador, canvas, sesiones, Cron, Gateway, etc. +4. **Herramientas de canal**: herramientas de acciones específicas de Discord/Telegram/Slack/WhatsApp +5. **Filtrado de políticas**: herramientas filtradas por perfil, proveedor, agente, grupo y políticas de sandbox +6. **Normalización de esquemas**: esquemas limpiados para peculiaridades de Gemini/OpenAI +7. **Envoltorio de AbortSignal**: herramientas envueltas para respetar señales de cancelación -### Adaptador de definición de herramienta +### Adaptador de definición de herramientas -`AgentTool` de pi-agent-core tiene una firma `execute` distinta de `ToolDefinition` de pi-coding-agent. El adaptador en `pi-tool-definition-adapter.ts` hace de puente: +`AgentTool` de pi-agent-core tiene una firma `execute` distinta a la de `ToolDefinition` de pi-coding-agent. El adaptador en `pi-tool-definition-adapter.ts` hace de puente: ```typescript export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { @@ -284,7 +281,7 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { ```typescript export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) { return { - builtInTools: [], // Vacío. Sobrescribimos todo + builtInTools: [], // Vacío. Reemplazamos todo customTools: toToolDefinitions(options.tools), }; } @@ -294,9 +291,9 @@ Esto garantiza que el filtrado de políticas, la integración de sandbox y el co ## Construcción del prompt del sistema -El prompt del sistema se construye en `buildAgentSystemPrompt()` (`system-prompt.ts`). Ensambla un prompt completo con secciones que incluyen Tooling, Tool Call Style, Safety guardrails, referencia de OpenClaw CLI, Skills, Docs, Workspace, Sandbox, Messaging, Reply Tags, Voice, Silent Replies, Heartbeats, Runtime metadata, además de Memory y Reactions cuando están habilitados, y archivos de contexto opcionales y contenido adicional del prompt del sistema. Las secciones se recortan para el modo de prompt mínimo usado por subagentes. +El prompt del sistema se construye en `buildAgentSystemPrompt()` (`system-prompt.ts`). Ensambla un prompt completo con secciones que incluyen herramientas, estilo de llamada de herramientas, barreras de seguridad, referencia de la CLI de OpenClaw, Skills, documentación, espacio de trabajo, sandbox, mensajería, etiquetas de respuesta, voz, respuestas silenciosas, Heartbeats, metadatos de tiempo de ejecución, además de memoria y reacciones cuando están habilitadas, y archivos de contexto opcionales y contenido adicional del prompt del sistema. Las secciones se recortan para el modo de prompt mínimo usado por subagentes. -El prompt se aplica después de crear la sesión mediante `applySystemPromptOverrideToSession()`: +El prompt se aplica después de la creación de la sesión mediante `applySystemPromptOverrideToSession()`: ```typescript const systemPromptOverride = createSystemPromptOverride(appendPrompt); @@ -307,17 +304,17 @@ applySystemPromptOverrideToSession(session, systemPromptOverride); ### Archivos de sesión -Las sesiones son archivos JSONL con estructura de árbol (enlace mediante id/parentId). `SessionManager` de Pi gestiona la persistencia: +Las sesiones son archivos JSONL con estructura de árbol (enlaces id/parentId). El `SessionManager` de Pi gestiona la persistencia: ```typescript const sessionManager = SessionManager.open(params.sessionFile); ``` -OpenClaw envuelve esto con `guardSessionManager()` para seguridad de resultados de herramientas. +OpenClaw envuelve esto con `guardSessionManager()` para la seguridad de los resultados de herramientas. -### Caché de sesión +### Caché de sesiones -`session-manager-cache.ts` almacena en caché instancias de SessionManager para evitar análisis repetidos de archivos: +`session-manager-cache.ts` almacena en caché instancias de SessionManager para evitar el análisis repetido de archivos: ```typescript await prewarmSessionFile(params.sessionFile); @@ -325,13 +322,13 @@ sessionManager = SessionManager.open(params.sessionFile); trackSessionManagerAccess(params.sessionFile); ``` -### Límite de historial +### Limitación del historial `limitHistoryTurns()` recorta el historial de conversación según el tipo de canal (DM frente a grupo). ### Compaction -La auto-Compaction se activa en desbordamiento de contexto. Las firmas comunes de desbordamiento +La Compaction automática se activa cuando se desborda el contexto. Las firmas comunes de desbordamiento incluyen `request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` y `ollama error: context @@ -344,25 +341,25 @@ const compactResult = await compactEmbeddedPiSessionDirect({ }); ``` -## Autenticación y resolución de modelo +## Autenticación y resolución de modelos ### Perfiles de autenticación -OpenClaw mantiene un almacén de perfiles de autenticación con varias claves API por proveedor: +OpenClaw mantiene un almacén de perfiles de autenticación con múltiples claves de API por proveedor: ```typescript const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false }); const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile }); ``` -Los perfiles rotan en caso de fallo con seguimiento de enfriamiento: +Los perfiles rotan en caso de errores con seguimiento de enfriamiento: ```typescript await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir }); const rotated = await advanceAuthProfile(); ``` -### Resolución de modelo +### Resolución de modelos ```typescript import { resolveModel } from "./pi-embedded-runner/model.js"; @@ -374,13 +371,13 @@ const { model, error, authStorage, modelRegistry } = resolveModel( config, ); -// Usa ModelRegistry y AuthStorage de pi +// Uses pi's ModelRegistry and AuthStorage authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey); ``` -### Conmutación por error +### Failover -`FailoverError` activa el respaldo de modelo cuando está configurado: +`FailoverError` activa la reserva del modelo cuando está configurada: ```typescript if (fallbackConfigured && isFailoverErrorMessage(errorText)) { @@ -398,9 +395,9 @@ if (fallbackConfigured && isFailoverErrorMessage(errorText)) { OpenClaw carga extensiones personalizadas de pi para comportamientos especializados: -### Salvaguarda de Compaction +### Protección de Compaction -`src/agents/pi-hooks/compaction-safeguard.ts` añade barreras de protección a la Compaction, incluido presupuesto adaptativo de tokens más resúmenes de fallos de herramientas y operaciones con archivos: +`src/agents/pi-hooks/compaction-safeguard.ts` agrega barreras de protección a la Compaction, incluido el presupuesto adaptativo de tokens, además de resúmenes de errores de herramientas y operaciones de archivos: ```typescript if (resolveCompactionMode(params.cfg) === "safeguard") { @@ -411,7 +408,7 @@ if (resolveCompactionMode(params.cfg) === "safeguard") { ### Poda de contexto -`src/agents/pi-hooks/context-pruning.ts` implementa poda de contexto basada en TTL de caché: +`src/agents/pi-hooks/context-pruning.ts` implementa la poda de contexto basada en TTL de caché: ```typescript if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { @@ -425,11 +422,11 @@ if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { } ``` -## Streaming y respuestas en bloque +## Streaming y respuestas por bloques -### Fragmentación en bloques +### División en bloques -`EmbeddedBlockChunker` gestiona el texto en streaming en bloques discretos de respuesta: +`EmbeddedBlockChunker` gestiona el streaming de texto en bloques discretos de respuesta: ```typescript const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null; @@ -437,12 +434,12 @@ const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : n ### Eliminación de etiquetas de pensamiento/final -La salida en streaming se procesa para eliminar bloques ``/`` y extraer contenido ``: +La salida en streaming se procesa para eliminar bloques ``/`` y extraer el contenido de ``: ```typescript const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => { - // Eliminar contenido ... - // Si enforceFinalTag, devolver solo contenido ... + // Strip ... content + // If enforceFinalTag, only return ... content }; ``` @@ -458,20 +455,20 @@ const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDi ### Clasificación de errores -`pi-embedded-helpers.ts` clasifica errores para un manejo apropiado: +`pi-embedded-helpers.ts` clasifica los errores para manejarlos de forma adecuada: ```typescript -isContextOverflowError(errorText) // Contexto demasiado grande -isCompactionFailureError(errorText) // Falló la Compaction -isAuthAssistantError(lastAssistant) // Fallo de autenticación -isRateLimitAssistantError(...) // Límite de tasa -isFailoverAssistantError(...) // Debe hacer failover +isContextOverflowError(errorText) // Context too large +isCompactionFailureError(errorText) // Compaction failed +isAuthAssistantError(lastAssistant) // Auth failure +isRateLimitAssistantError(...) // Rate limited +isFailoverAssistantError(...) // Should failover classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ... ``` -### Respaldo de nivel de pensamiento +### Reserva de nivel de razonamiento -Si un nivel de pensamiento no es compatible, se usa un respaldo: +Si un nivel de razonamiento no es compatible, se usa una reserva: ```typescript const fallbackThinking = pickFallbackThinkingLevel({ @@ -486,7 +483,7 @@ if (fallbackThinking) { ## Integración de sandbox -Cuando el modo sandbox está habilitado, las herramientas y rutas están restringidas: +Cuando el modo sandbox está habilitado, las herramientas y rutas quedan restringidas: ```typescript const sandbox = await resolveSandboxContext({ @@ -496,9 +493,9 @@ const sandbox = await resolveSandboxContext({ }); if (sandboxRoot) { - // Usar herramientas read/edit/write en sandbox - // Exec se ejecuta en contenedor - // Browser usa URL de bridge + // Use sandboxed read/edit/write tools + // Exec runs in container + // Browser uses bridge URL } ``` @@ -508,16 +505,16 @@ if (sandboxRoot) { - Limpieza de cadenas mágicas de rechazo - Validación de turnos para roles consecutivos -- Validación estricta upstream de parámetros de herramientas de Pi +- Validación estricta ascendente de parámetros de herramientas de Pi ### Google/Gemini -- Saneamiento de esquema de herramientas propiedad del Plugin +- Saneamiento de esquemas de herramientas propiedad del Plugin ### OpenAI -- herramienta `apply_patch` para modelos Codex -- manejo de degradación de nivel de pensamiento +- Herramienta `apply_patch` para modelos Codex +- Manejo de degradación del nivel de razonamiento ## Integración de TUI @@ -530,27 +527,27 @@ import { ... } from "@mariozechner/pi-tui"; Esto proporciona la experiencia interactiva de terminal similar al modo nativo de pi. -## Diferencias clave frente a Pi CLI +## Diferencias clave con la CLI de Pi -| Aspecto | Pi CLI | OpenClaw incrustado | -| --------------- | ----------------------- | ---------------------------------------------------------------------------------------------- | -| Invocación | comando `pi` / RPC | SDK mediante `createAgentSession()` | -| Herramientas | Herramientas de codificación predeterminadas | Conjunto personalizado de herramientas de OpenClaw | -| Prompt del sistema | AGENTS.md + prompts | Dinámico por canal/contexto | -| Almacenamiento de sesión | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/` (o `$OPENCLAW_STATE_DIR/agents//sessions/`) | -| Autenticación | Credencial única | Multiprofile con rotación | -| Extensiones | Cargadas desde disco | Rutas programáticas + de disco | -| Manejo de eventos | Renderizado TUI | Basado en callbacks (`onBlockReply`, etc.) | +| Aspecto | CLI de Pi | OpenClaw integrado | +| --------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | +| Invocación | Comando `pi` / RPC | SDK mediante `createAgentSession()` | +| Herramientas | Herramientas de codificación predeterminadas | Conjunto de herramientas personalizadas de OpenClaw | +| Prompt del sistema | AGENTS.md + prompts | Dinámico por canal/contexto | +| Almacenamiento de sesiones | `~/.pi/agent/sessions/` | `~/.openclaw/agents//sessions/` (o `$OPENCLAW_STATE_DIR/agents//sessions/`) | +| Autenticación | Credencial única | Múltiples perfiles con rotación | +| Extensiones | Cargadas desde disco | Rutas programáticas + de disco | +| Manejo de eventos | Renderizado de TUI | Basado en callbacks (`onBlockReply`, etc.) | ## Consideraciones futuras -Áreas de posible rediseño: +Áreas para posible retrabajo: -1. **Alineación de firma de herramientas**: actualmente se adapta entre firmas de pi-agent-core y pi-coding-agent -2. **Envoltorio de session manager**: `guardSessionManager` añade seguridad pero aumenta la complejidad +1. **Alineación de firmas de herramientas**: actualmente se adaptan entre las firmas de pi-agent-core y pi-coding-agent +2. **Envoltorio de session manager**: `guardSessionManager` agrega seguridad, pero aumenta la complejidad 3. **Carga de extensiones**: podría usar `ResourceLoader` de pi más directamente -4. **Complejidad del manejador de streaming**: `subscribeEmbeddedPiSession` ha crecido mucho -5. **Peculiaridades de proveedores**: hay muchas rutas de código específicas de proveedor que pi podría gestionar potencialmente +4. **Complejidad del manejador de streaming**: `subscribeEmbeddedPiSession` ha crecido demasiado +5. **Particularidades de proveedores**: muchos recorridos de código específicos por proveedor que pi podría manejar potencialmente ## Pruebas @@ -568,13 +565,13 @@ La cobertura de integración de Pi abarca estas suites: - `src/agents/pi-settings.test.ts` - `src/agents/pi-hooks/**/*.test.ts` -Live/opt-in: +En vivo/opcional: -- `src/agents/pi-embedded-runner-extraparams.live.test.ts` (habilita `OPENCLAW_LIVE_TEST=1`) +- `src/agents/pi-embedded-runner-extraparams.live.test.ts` (habilitar `OPENCLAW_LIVE_TEST=1`) -Para los comandos actuales de ejecución, consulta [Flujo de trabajo de desarrollo de Pi](/es/pi-dev). +Para los comandos de ejecución actuales, consulte [flujo de desarrollo de Pi](/es/pi-dev). ## Relacionado -- [Flujo de trabajo de desarrollo de Pi](/es/pi-dev) -- [Descripción general de instalación](/es/install) +- [flujo de desarrollo de Pi](/es/pi-dev) +- [Resumen de instalación](/es/install) diff --git a/docs/es/providers/deepseek.md b/docs/es/providers/deepseek.md index 84c8de2d2..2727ed225 100644 --- a/docs/es/providers/deepseek.md +++ b/docs/es/providers/deepseek.md @@ -1,39 +1,39 @@ --- read_when: - Quieres usar DeepSeek con OpenClaw - - Necesitas la variable de entorno de la clave API o la opción de autenticación de la CLI + - Necesitas la variable de entorno de la clave de API o la opción de autenticación de la CLI summary: Configuración de DeepSeek (autenticación + selección de modelo) title: DeepSeek x-i18n: - generated_at: "2026-04-24T05:44:08Z" + generated_at: "2026-04-24T15:21:24Z" model: gpt-5.4 provider: openai - source_hash: ead407c67c05bd8700db1cba36defdd9d47bdc9a071c76a07c4b4fb82f6b80e2 + source_hash: 5b0d2345c72328e14351d71c5784204dc6ed9dc922f919b6adfac394001c3261 source_path: providers/deepseek.md workflow: 15 --- [DeepSeek](https://www.deepseek.com) ofrece potentes modelos de IA con una API compatible con OpenAI. -| Property | Value | +| Propiedad | Valor | | -------- | -------------------------- | -| Provider | `deepseek` | -| Auth | `DEEPSEEK_API_KEY` | -| API | Compatible con OpenAI | -| Base URL | `https://api.deepseek.com` | +| Proveedor | `deepseek` | +| Autenticación | `DEEPSEEK_API_KEY` | +| API | Compatible con OpenAI | +| URL base | `https://api.deepseek.com` | ## Primeros pasos - - Crea una clave API en [platform.deepseek.com](https://platform.deepseek.com/api_keys). + + Crea una clave de API en [platform.deepseek.com](https://platform.deepseek.com/api_keys). ```bash openclaw onboard --auth-choice deepseek-api-key ``` - Esto pedirá tu clave API y establecerá `deepseek/deepseek-chat` como modelo predeterminado. + Esto solicitará tu clave de API y establecerá `deepseek/deepseek-v4-flash` como modelo predeterminado. @@ -45,7 +45,7 @@ x-i18n: - Para instalaciones automatizadas o sin interfaz, pasa todas las banderas directamente: + Para instalaciones con scripts o sin interfaz, pasa todas las opciones directamente: ```bash openclaw onboard --non-interactive \ @@ -60,20 +60,24 @@ x-i18n: -Si el Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `DEEPSEEK_API_KEY` +Si el Gateway se ejecuta como un daemon (launchd/systemd), asegúrate de que `DEEPSEEK_API_KEY` esté disponible para ese proceso (por ejemplo, en `~/.openclaw/.env` o mediante `env.shellEnv`). -## Catálogo incluido +## Catálogo integrado -| Model ref | Name | Input | Context | Max output | Notes | -| ---------------------------- | ----------------- | ----- | ------- | ---------- | ------------------------------------------------- | -| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | Modelo predeterminado; superficie sin thinking de DeepSeek V3.2 | -| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | Superficie V3.2 con razonamiento habilitado | +| Referencia del modelo | Nombre | Entrada | Contexto | Salida máx. | Notas | +| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ | +| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | Modelo predeterminado; superficie V4 con capacidad de thinking | +| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | Superficie V4 con capacidad de thinking | +| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | Superficie sin thinking de DeepSeek V3.2 | +| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | Superficie V3.2 con razonamiento habilitado | -Ambos modelos incluidos anuncian actualmente compatibilidad de uso en streaming en el código fuente. +Los modelos V4 admiten el control `thinking` de DeepSeek. OpenClaw también vuelve a reproducir +`reasoning_content` de DeepSeek en los turnos de seguimiento para que las sesiones de thinking con llamadas +a herramientas puedan continuar. ## Ejemplo de configuración @@ -83,7 +87,7 @@ Ambos modelos incluidos anuncian actualmente compatibilidad de uso en streaming env: { DEEPSEEK_API_KEY: "sk-..." }, agents: { defaults: { - model: { primary: "deepseek/deepseek-chat" }, + model: { primary: "deepseek/deepseek-v4-flash" }, }, }, } @@ -92,8 +96,8 @@ Ambos modelos incluidos anuncian actualmente compatibilidad de uso en streaming ## Relacionado - - Elegir proveedores, referencias de modelo y comportamiento de conmutación por error. + + Elegir proveedores, referencias de modelo y comportamiento de failover. Referencia completa de configuración para agentes, modelos y proveedores. diff --git a/docs/es/tools/plugin.md b/docs/es/tools/plugin.md index e20710250..9f75df234 100644 --- a/docs/es/tools/plugin.md +++ b/docs/es/tools/plugin.md @@ -1,21 +1,25 @@ --- read_when: - - Instalar o configurar plugins - - Comprender las reglas de descubrimiento y carga de plugins - - Trabajar con bundles de plugins compatibles con Codex/Claude + - Instalación o configuración de plugins + - Comprender las reglas de detección y carga de plugins + - Trabajar con paquetes de plugins compatibles con Codex/Claude sidebarTitle: Install and Configure -summary: Instalar, configurar y gestionar plugins de OpenClaw +summary: Instalar, configurar y administrar plugins de OpenClaw title: Plugins x-i18n: - generated_at: "2026-04-24T09:02:17Z" + generated_at: "2026-04-24T15:21:22Z" model: gpt-5.4 provider: openai - source_hash: 83ab1218d6677ad518a4991ca546d55eed9648e1fa92b76b7433ecd5df569e28 + source_hash: 947bb7ffc13280fd63f79bb68cb18a37c6614144b91a83afd38e5ac3c5187aed source_path: tools/plugin.md workflow: 15 --- -Los plugins amplían OpenClaw con nuevas capacidades: canales, proveedores de modelos, arneses de agentes, herramientas, Skills, voz, transcripción en tiempo real, voz en tiempo real, comprensión de medios, generación de imágenes, generación de video, obtención web, búsqueda web y más. Algunos plugins son **core** (incluidos con OpenClaw) y otros son **externos** (publicados en npm por la comunidad). +Los plugins amplían OpenClaw con nuevas capacidades: canales, proveedores de modelos, +arneses de agentes, herramientas, Skills, voz, transcripción en tiempo real, voz en tiempo real, +comprensión de medios, generación de imágenes, generación de video, obtención web, búsqueda web +y más. Algunos plugins son **core** (incluidos con OpenClaw), otros +son **external** (publicados en npm por la comunidad). ## Inicio rápido @@ -43,12 +47,12 @@ Los plugins amplían OpenClaw con nuevas capacidades: canales, proveedores de mo openclaw gateway restart ``` - Luego configúralo en `plugins.entries.\.config` dentro de tu archivo de configuración. + Luego configure en `plugins.entries.\.config` en su archivo de configuración. -Si prefieres control nativo de chat, habilita `commands.plugins: true` y usa: +Si prefiere un control nativo del chat, habilite `commands.plugins: true` y use: ```text /plugin install clawhub:@openclaw/voice-call @@ -56,37 +60,48 @@ Si prefieres control nativo de chat, habilita `commands.plugins: true` y usa: /plugin enable voice-call ``` -La ruta de instalación usa el mismo resolvedor que la CLI: ruta/archivo local, `clawhub:` explícito o especificación de paquete simple (primero ClawHub, luego fallback a npm). +La ruta de instalación usa el mismo resolvedor que la CLI: ruta/archivo local, `clawhub:` +explícito o especificación de paquete simple (primero ClawHub, luego npm como respaldo). -Si la configuración no es válida, la instalación normalmente falla de forma cerrada y te indica usar `openclaw doctor --fix`. La única excepción de recuperación es una ruta limitada de reinstalación de plugins incluidos para plugins que optan por `openclaw.install.allowInvalidConfigRecovery`. +Si la configuración no es válida, la instalación normalmente falla de forma segura y le indica +que use `openclaw doctor --fix`. La única excepción de recuperación es una ruta limitada de +reinstalación de plugins incluidos para plugins que optan por +`openclaw.install.allowInvalidConfigRecovery`. -Las instalaciones empaquetadas de OpenClaw no instalan de forma anticipada todo el árbol de dependencias de tiempo de ejecución de cada plugin incluido. Cuando un plugin incluido propiedad de OpenClaw está activo desde la configuración de plugins, configuración heredada de canal o un manifiesto habilitado por defecto, el arranque repara solo las dependencias de tiempo de ejecución declaradas por ese plugin antes de importarlo. Los plugins externos y las rutas de carga personalizadas todavía deben instalarse mediante `openclaw plugins install`. +Las instalaciones empaquetadas de OpenClaw no instalan de forma anticipada todo el +árbol de dependencias de tiempo de ejecución de cada plugin incluido. +Cuando un plugin incluido y propiedad de OpenClaw está activo desde la +configuración de plugins, la configuración heredada del canal o un manifiesto habilitado +por defecto, el inicio repara solo las dependencias de tiempo de ejecución declaradas de ese plugin antes de importarlo. +Los plugins externos y las rutas de carga personalizadas aún deben instalarse mediante +`openclaw plugins install`. ## Tipos de plugins -OpenClaw reconoce dos formatos de plugins: +OpenClaw reconoce dos formatos de plugin: | Formato | Cómo funciona | Ejemplos | | ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ | | **Native** | `openclaw.plugin.json` + módulo de tiempo de ejecución; se ejecuta en proceso | Plugins oficiales, paquetes npm de la comunidad | | **Bundle** | Diseño compatible con Codex/Claude/Cursor; asignado a funciones de OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Ambos aparecen en `openclaw plugins list`. Consulta [Bundles de plugins](/es/plugins/bundles) para ver detalles sobre bundles. +Ambos aparecen en `openclaw plugins list`. Consulte [Plugin Bundles](/es/plugins/bundles) para obtener detalles sobre los bundles. -Si estás escribiendo un plugin nativo, empieza con [Crear plugins](/es/plugins/building-plugins) y el [Resumen del SDK de plugins](/es/plugins/sdk-overview). +Si está escribiendo un plugin nativo, comience con [Building Plugins](/es/plugins/building-plugins) +y [Plugin SDK Overview](/es/plugins/sdk-overview). ## Plugins oficiales ### Instalables (npm) -| Plugin | Paquete | Documentación | -| --------------- | ---------------------- | ------------------------------------ | -| Matrix | `@openclaw/matrix` | [Matrix](/es/channels/matrix) | +| Plugin | Paquete | Documentación | +| --------------- | ---------------------- | ----------------------------------- | +| Matrix | `@openclaw/matrix` | [Matrix](/es/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/es/channels/msteams) | -| Nostr | `@openclaw/nostr` | [Nostr](/es/channels/nostr) | -| Voice Call | `@openclaw/voice-call` | [Voice Call](/es/plugins/voice-call) | -| Zalo | `@openclaw/zalo` | [Zalo](/es/channels/zalo) | -| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/es/plugins/zalouser) | +| Nostr | `@openclaw/nostr` | [Nostr](/es/channels/nostr) | +| Voice Call | `@openclaw/voice-call` | [Voice Call](/es/plugins/voice-call) | +| Zalo | `@openclaw/zalo` | [Zalo](/es/channels/zalo) | +| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/es/plugins/zalouser) | ### Core (incluidos con OpenClaw) @@ -101,7 +116,7 @@ Si estás escribiendo un plugin nativo, empieza con [Crear plugins](/es/plugins/ - `memory-core` — búsqueda de memoria incluida (predeterminada mediante `plugins.slots.memory`) - - `memory-lancedb` — memoria a largo plazo con instalación bajo demanda y recuperación/captura automáticas (configura `plugins.slots.memory = "memory-lancedb"`) + - `memory-lancedb` — memoria a largo plazo de instalación bajo demanda con recuperación/captura automática (establezca `plugins.slots.memory = "memory-lancedb"`) @@ -109,12 +124,12 @@ Si estás escribiendo un plugin nativo, empieza con [Crear plugins](/es/plugins/ - - `browser` — plugin de navegador incluido para la herramienta de navegador, CLI `openclaw browser`, método de Gateway `browser.request`, tiempo de ejecución del navegador y servicio predeterminado de control del navegador (habilitado por defecto; desactívalo antes de reemplazarlo) - - `copilot-proxy` — puente VS Code Copilot Proxy (deshabilitado por defecto) + - `browser` — plugin de navegador incluido para la herramienta del navegador, la CLI `openclaw browser`, el método Gateway `browser.request`, el tiempo de ejecución del navegador y el servicio de control del navegador predeterminado (habilitado por defecto; desactívelo antes de reemplazarlo) + - `copilot-proxy` — puente de VS Code Copilot Proxy (deshabilitado por defecto) -¿Buscas plugins de terceros? Consulta [Plugins de la comunidad](/es/plugins/community). +¿Busca plugins de terceros? Consulte [Community Plugins](/es/plugins/community). ## Configuración @@ -136,29 +151,42 @@ Si estás escribiendo un plugin nativo, empieza con [Crear plugins](/es/plugins/ | ---------------- | --------------------------------------------------------- | | `enabled` | Interruptor maestro (predeterminado: `true`) | | `allow` | Lista de permitidos de plugins (opcional) | -| `deny` | Lista de bloqueo de plugins (opcional; deny tiene prioridad) | -| `load.paths` | Archivos/directorios adicionales de plugins | -| `slots` | Selectores de ranuras exclusivas (p. ej. `memory`, `contextEngine`) | -| `entries.\` | Interruptores + configuración por plugin | +| `deny` | Lista de bloqueados de plugins (opcional; deny prevalece) | +| `load.paths` | Archivos/directorios de plugins adicionales | +| `slots` | Selectores de ranura exclusivos (p. ej., `memory`, `contextEngine`) | +| `entries.\` | Alternadores + configuración por plugin | -Los cambios de configuración **requieren reiniciar el gateway**. Si el Gateway se está ejecutando con vigilancia de configuración + reinicio en proceso habilitados (la ruta predeterminada de `openclaw gateway`), ese reinicio normalmente se realiza automáticamente poco después de que se escriba la configuración. +Los cambios de configuración **requieren un reinicio del Gateway**. Si el Gateway se está ejecutando con observación de configuración ++ reinicio en proceso habilitado (la ruta predeterminada de `openclaw gateway`), ese +reinicio normalmente se realiza automáticamente un momento después de que se escribe la configuración. +No hay una ruta de recarga en caliente compatible para el código de tiempo de ejecución de plugins nativos ni para los hooks +del ciclo de vida; reinicie el proceso Gateway que atiende el canal activo antes de +esperar que se ejecute el código actualizado de `register(api)`, los hooks `api.on(...)`, herramientas, servicios o +hooks de proveedor/tiempo de ejecución. - - - **Deshabilitado**: el plugin existe, pero las reglas de habilitación lo apagaron. La configuración se conserva. - - **Ausente**: la configuración hace referencia a un id de plugin que el descubrimiento no encontró. - - **No válido**: el plugin existe, pero su configuración no coincide con el esquema declarado. +`openclaw plugins list` es una instantánea local de la CLI/configuración. Un plugin `loaded` allí +significa que el plugin es detectable y cargable desde la configuración/archivos que ve esa +invocación de la CLI. No demuestra que un proceso hijo remoto del Gateway que ya está en ejecución +se haya reiniciado con el mismo código del plugin. En configuraciones VPS/contenedor con procesos envoltorio, +envíe reinicios al proceso real `openclaw gateway run`, o use +`openclaw gateway restart` contra el Gateway en ejecución. + + + - **Disabled**: el plugin existe, pero las reglas de habilitación lo desactivaron. La configuración se conserva. + - **Missing**: la configuración hace referencia a un id de plugin que la detección no encontró. + - **Invalid**: el plugin existe, pero su configuración no coincide con el esquema declarado. -## Descubrimiento y precedencia +## Detección y precedencia -OpenClaw explora plugins en este orden (la primera coincidencia gana): +OpenClaw busca plugins en este orden (la primera coincidencia prevalece): - `plugins.load.paths` — rutas explícitas de archivos o directorios. + `plugins.load.paths` — rutas explícitas de archivo o directorio. - + `\/.openclaw//*.ts` y `\/.openclaw//*/index.ts`. @@ -175,14 +203,38 @@ OpenClaw explora plugins en este orden (la primera coincidencia gana): ### Reglas de habilitación - `plugins.enabled: false` deshabilita todos los plugins -- `plugins.deny` siempre tiene prioridad sobre allow +- `plugins.deny` siempre prevalece sobre allow - `plugins.entries.\.enabled: false` deshabilita ese plugin -- Los plugins de origen workspace están **deshabilitados por defecto** (deben habilitarse explícitamente) -- Los plugins incluidos siguen el conjunto integrado habilitado por defecto salvo que se sobrescriba +- Los plugins originados en el espacio de trabajo están **deshabilitados por defecto** (deben habilitarse explícitamente) +- Los plugins incluidos siguen el conjunto incorporado habilitado por defecto, salvo que se sobrescriba - Las ranuras exclusivas pueden forzar la habilitación del plugin seleccionado para esa ranura -- Algunos plugins incluidos de activación opcional se habilitan automáticamente cuando la configuración nombra una superficie controlada por el plugin, como una referencia de modelo de proveedor, configuración de canal o tiempo de ejecución de arnés -- Las rutas Codex de la familia OpenAI mantienen límites separados de plugins: - `openai-codex/*` pertenece al Plugin de OpenAI, mientras que el Plugin incluido del servidor de aplicaciones Codex se selecciona mediante `embeddedHarness.runtime: "codex"` o referencias heredadas de modelo `codex/*` +- Algunos plugins incluidos de activación opcional se habilitan automáticamente cuando la configuración nombra una + superficie propiedad del plugin, como una referencia de modelo de proveedor, configuración de canal o tiempo de ejecución + del arnés +- Las rutas Codex de la familia OpenAI mantienen límites de plugin separados: + `openai-codex/*` pertenece al plugin OpenAI, mientras que el plugin incluido del servidor de aplicaciones Codex + se selecciona mediante `embeddedHarness.runtime: "codex"` o referencias heredadas de modelo `codex/*` + +## Solución de problemas de Runtime Hooks + +Si un plugin aparece en `plugins list` pero los efectos secundarios de `register(api)` o los hooks +no se ejecutan en el tráfico del chat activo, compruebe primero lo siguiente: + +- Ejecute `openclaw gateway status --deep --require-rpc` y confirme que la URL, + el perfil, la ruta de configuración y el proceso del Gateway activos son los que está editando. +- Reinicie el Gateway activo después de cambios en instalación/configuración/código del plugin. En contenedores + envoltorio, PID 1 puede ser solo un supervisor; reinicie o envíe una señal al proceso hijo + `openclaw gateway run`. +- Use `openclaw plugins inspect --json` para confirmar los registros de hooks y + los diagnósticos. Los hooks de conversación no incluidos, como `llm_input`, + `llm_output` y `agent_end`, necesitan + `plugins.entries..hooks.allowConversationAccess=true`. +- Para el cambio de modelo, prefiera `before_model_resolve`. Se ejecuta antes de la resolución + del modelo para los turnos del agente; `llm_output` solo se ejecuta después de que un intento de modelo + produce salida del asistente. +- Para obtener prueba del modelo de sesión efectivo, use `openclaw sessions` o las + superficies de sesión/estado del Gateway y, al depurar cargas útiles del proveedor, inicie + el Gateway con `--raw-stream --raw-stream-path `. ## Ranuras de plugins (categorías exclusivas) @@ -199,20 +251,20 @@ Algunas categorías son exclusivas (solo una activa a la vez): } ``` -| Ranura | Qué controla | Predeterminado | -| --------------- | ------------------------- | -------------------- | -| `memory` | Plugin de memoria activa | `memory-core` | -| `contextEngine` | Motor de contexto activo | `legacy` (integrado) | +| Ranura | Qué controla | Predeterminado | +| --------------- | -------------------------- | ------------------- | +| `memory` | Plugin de Active Memory | `memory-core` | +| `contextEngine` | Motor de contexto activo | `legacy` (integrado) | -## Referencia de CLI +## Referencia de la CLI ```bash openclaw plugins list # inventario compacto openclaw plugins list --enabled # solo plugins cargados -openclaw plugins list --verbose # líneas detalladas por plugin -openclaw plugins list --json # inventario legible por máquina +openclaw plugins list --verbose # líneas de detalle por plugin +openclaw plugins list --json # inventario legible por máquinas openclaw plugins inspect # detalle profundo -openclaw plugins inspect --json # legible por máquina +openclaw plugins inspect --json # legible por máquinas openclaw plugins inspect --all # tabla de toda la flota openclaw plugins info # alias de inspect openclaw plugins doctor # diagnósticos @@ -224,7 +276,7 @@ openclaw plugins install # instalar desde ruta local openclaw plugins install -l # enlazar (sin copiar) para desarrollo openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # registrar especificación npm resuelta exacta +openclaw plugins install --pin # registrar la especificación exacta de npm resuelta openclaw plugins install --dangerously-force-unsafe-install openclaw plugins update # actualizar un plugin openclaw plugins update --dangerously-force-unsafe-install @@ -238,31 +290,60 @@ openclaw plugins enable openclaw plugins disable ``` -Los plugins incluidos se distribuyen con OpenClaw. Muchos están habilitados por defecto (por ejemplo, proveedores de modelos incluidos, proveedores de voz incluidos y el plugin de navegador incluido). Otros plugins incluidos aún necesitan `openclaw plugins enable `. +Los plugins incluidos vienen con OpenClaw. Muchos están habilitados por defecto (por ejemplo, +los proveedores de modelos incluidos, los proveedores de voz incluidos y el +plugin de navegador incluido). Otros plugins incluidos aún necesitan `openclaw plugins enable `. -`--force` sobrescribe un plugin o paquete de hooks ya instalado en su lugar. Usa `openclaw plugins update ` para actualizaciones rutinarias de plugins npm rastreados. No es compatible con `--link`, que reutiliza la ruta de origen en lugar de copiarla a un destino de instalación gestionado. +`--force` sobrescribe un plugin instalado existente o un paquete de hooks en su lugar. Use +`openclaw plugins update ` para actualizaciones rutinarias de plugins npm +rastreados. No es compatible con `--link`, que reutiliza la ruta de origen en lugar +de copiar sobre un destino de instalación administrado. -Cuando `plugins.allow` ya está configurado, `openclaw plugins install` añade el id del plugin instalado a esa lista de permitidos antes de habilitarlo, para que las instalaciones puedan cargarse inmediatamente después del reinicio. +Cuando `plugins.allow` ya está establecido, `openclaw plugins install` agrega el +id del plugin instalado a esa lista de permitidos antes de habilitarlo, de modo que las instalaciones +se puedan cargar inmediatamente después del reinicio. -`openclaw plugins update ` se aplica a instalaciones rastreadas. Pasar una especificación de paquete npm con una dist-tag o versión exacta resuelve el nombre del paquete de vuelta al registro rastreado del plugin y registra la nueva especificación para futuras actualizaciones. Pasar el nombre del paquete sin versión mueve una instalación fijada exactamente de vuelta a la línea de versión predeterminada del registro. Si el plugin npm instalado ya coincide con la versión resuelta y la identidad del artefacto registrada, OpenClaw omite la actualización sin descargar, reinstalar ni reescribir la configuración. +`openclaw plugins update ` se aplica a instalaciones rastreadas. Pasar +una especificación de paquete npm con una dist-tag o una versión exacta resuelve el nombre del paquete +de vuelta al registro del plugin rastreado y registra la nueva especificación para futuras actualizaciones. +Pasar el nombre del paquete sin una versión mueve una instalación exacta fijada de vuelta a +la línea de publicación predeterminada del registro. Si el plugin npm instalado ya coincide +con la versión resuelta y la identidad del artefacto registrada, OpenClaw omite la actualización +sin descargar, reinstalar ni reescribir la configuración. -`--pin` es solo para npm. No es compatible con `--marketplace`, porque las instalaciones desde marketplace conservan metadatos del origen del marketplace en lugar de una especificación npm. +`--pin` es solo para npm. No es compatible con `--marketplace`, porque +las instalaciones desde marketplace conservan metadatos del origen del marketplace en lugar de una especificación npm. -`--dangerously-force-unsafe-install` es una anulación de emergencia para falsos positivos del escáner integrado de código peligroso. Permite que las instalaciones y actualizaciones de plugins continúen más allá de hallazgos integrados `critical`, pero aún no omite los bloqueos de política `before_install` del plugin ni el bloqueo por fallos del escaneo. +`--dangerously-force-unsafe-install` es una anulación de emergencia para falsos +positivos del escáner integrado de código peligroso. Permite que las instalaciones +y actualizaciones de plugins continúen más allá de hallazgos integrados `critical`, pero aun así +no omite los bloqueos de política `before_install` del plugin ni el bloqueo por fallos de escaneo. -Esta bandera de CLI se aplica solo a los flujos de instalación/actualización de plugins. Las instalaciones de dependencias de Skills respaldadas por Gateway usan en su lugar la anulación correspondiente de solicitud `dangerouslyForceUnsafeInstall`, mientras que `openclaw skills install` sigue siendo el flujo independiente de descarga/instalación de Skills desde ClawHub. +Esta opción de la CLI se aplica solo a los flujos de instalación/actualización de plugins. Las instalaciones +de dependencias de Skills respaldadas por Gateway usan en su lugar la anulación de solicitud correspondiente +`dangerouslyForceUnsafeInstall`, mientras que `openclaw skills install` sigue siendo el flujo separado de descarga/instalación de Skills desde ClawHub. -Los bundles compatibles participan en el mismo flujo de listar/inspeccionar/habilitar/deshabilitar plugins. El soporte actual en tiempo de ejecución incluye Skills de bundles, command-skills de Claude, valores predeterminados de Claude `settings.json`, valores predeterminados de Claude `.lsp.json` y `lspServers` declarados en el manifiesto, command-skills de Cursor y directorios de hooks de Codex compatibles. +Los bundles compatibles participan en el mismo flujo de listar/inspeccionar/habilitar/deshabilitar plugins. +La compatibilidad actual en tiempo de ejecución incluye Skills de bundle, command-skills de Claude, +valores predeterminados de Claude `settings.json`, valores predeterminados de Claude `.lsp.json` y `lspServers` declarados en el manifiesto, +command-skills de Cursor y directorios de hooks de Codex compatibles. -`openclaw plugins inspect ` también informa las capacidades de bundle detectadas, además de las entradas de servidor MCP y LSP compatibles o no compatibles para plugins respaldados por bundles. +`openclaw plugins inspect ` también informa las capacidades de bundle detectadas, además de +las entradas de servidor MCP y LSP compatibles o no compatibles para plugins respaldados por bundles. -Los orígenes de marketplace pueden ser un nombre de marketplace conocido de Claude tomado de `~/.claude/plugins/known_marketplaces.json`, una raíz de marketplace local o ruta `marketplace.json`, una abreviatura de GitHub como `owner/repo`, una URL de repositorio de GitHub o una URL git. Para marketplaces remotos, las entradas de plugin deben permanecer dentro del repositorio clonado del marketplace y usar solo orígenes de rutas relativas. +Los orígenes de marketplace pueden ser un nombre de marketplace conocido de Claude de +`~/.claude/plugins/known_marketplaces.json`, una raíz de marketplace local o una ruta +`marketplace.json`, una abreviatura de GitHub como `owner/repo`, una URL de repositorio de GitHub o una URL git. +Para marketplaces remotos, las entradas de plugin deben permanecer dentro del +repositorio clonado del marketplace y usar solo orígenes de ruta relativa. -Consulta la [referencia de CLI de `openclaw plugins`](/es/cli/plugins) para ver todos los detalles. +Consulte la [referencia de la CLI `openclaw plugins`](/es/cli/plugins) para obtener todos los detalles. -## Resumen de la API de plugins +## Descripción general de la API de plugins -Los plugins nativos exportan un objeto de entrada que expone `register(api)`. Los plugins antiguos todavía pueden usar `activate(api)` como alias heredado, pero los plugins nuevos deben usar `register`. +Los plugins nativos exportan un objeto de entrada que expone `register(api)`. Los plugins +más antiguos aún pueden usar `activate(api)` como alias heredado, pero los plugins nuevos deben +usar `register`. ```typescript export default definePluginEntry({ @@ -282,31 +363,34 @@ export default definePluginEntry({ }); ``` -OpenClaw carga el objeto de entrada y llama a `register(api)` durante la activación del plugin. El cargador todavía usa `activate(api)` como fallback para plugins antiguos, pero los plugins incluidos y los nuevos plugins externos deben tratar `register` como el contrato público. +OpenClaw carga el objeto de entrada y llama a `register(api)` durante la +activación del plugin. El cargador todavía recurre a `activate(api)` para plugins más antiguos, +pero los plugins incluidos y los nuevos plugins externos deben tratar `register` como el +contrato público. -Métodos comunes de registro: +Métodos de registro comunes: | Método | Qué registra | | --------------------------------------- | ---------------------------- | | `registerProvider` | Proveedor de modelos (LLM) | | `registerChannel` | Canal de chat | -| `registerTool` | Herramienta de agente | +| `registerTool` | Herramienta del agente | | `registerHook` / `on(...)` | Hooks del ciclo de vida | | `registerSpeechProvider` | Texto a voz / STT | | `registerRealtimeTranscriptionProvider` | STT en streaming | -| `registerRealtimeVoiceProvider` | Voz dúplex en tiempo real | +| `registerRealtimeVoiceProvider` | Voz bidireccional en tiempo real | | `registerMediaUnderstandingProvider` | Análisis de imagen/audio | | `registerImageGenerationProvider` | Generación de imágenes | | `registerMusicGenerationProvider` | Generación de música | | `registerVideoGenerationProvider` | Generación de video | -| `registerWebFetchProvider` | Proveedor de obtención / scraping web | +| `registerWebFetchProvider` | Proveedor de obtención / raspado web | | `registerWebSearchProvider` | Búsqueda web | | `registerHttpRoute` | Endpoint HTTP | | `registerCommand` / `registerCli` | Comandos de CLI | | `registerContextEngine` | Motor de contexto | | `registerService` | Servicio en segundo plano | -Comportamiento de guardas de hooks para hooks tipados del ciclo de vida: +Comportamiento de las protecciones de hooks para hooks tipados del ciclo de vida: - `before_tool_call`: `{ block: true }` es terminal; se omiten los controladores de menor prioridad. - `before_tool_call`: `{ block: false }` no hace nada y no elimina un bloqueo anterior. @@ -315,13 +399,13 @@ Comportamiento de guardas de hooks para hooks tipados del ciclo de vida: - `message_sending`: `{ cancel: true }` es terminal; se omiten los controladores de menor prioridad. - `message_sending`: `{ cancel: false }` no hace nada y no elimina una cancelación anterior. -Para ver el comportamiento completo de hooks tipados, consulta [Resumen del SDK](/es/plugins/sdk-overview#hook-decision-semantics). +Para ver el comportamiento completo de hooks tipados, consulte [SDK Overview](/es/plugins/sdk-overview#hook-decision-semantics). ## Relacionado -- [Crear plugins](/es/plugins/building-plugins) — crea tu propio plugin -- [Bundles de plugins](/es/plugins/bundles) — compatibilidad con bundles de Codex/Claude/Cursor -- [Manifiesto del Plugin](/es/plugins/manifest) — esquema del manifiesto -- [Registrar herramientas](/es/plugins/building-plugins#registering-agent-tools) — añade herramientas de agente en un plugin -- [Internos del Plugin](/es/plugins/architecture) — modelo de capacidades y flujo de carga -- [Plugins de la comunidad](/es/plugins/community) — listados de terceros +- [Building Plugins](/es/plugins/building-plugins) — cree su propio plugin +- [Plugin Bundles](/es/plugins/bundles) — compatibilidad de bundles de Codex/Claude/Cursor +- [Plugin Manifest](/es/plugins/manifest) — esquema del manifiesto +- [Registering Tools](/es/plugins/building-plugins#registering-agent-tools) — agregue herramientas de agente en un plugin +- [Plugin Internals](/es/plugins/architecture) — modelo de capacidades y canalización de carga +- [Community Plugins](/es/plugins/community) — listados de terceros