openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh es translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-09 01:35:03 +00:00
parent 77940525e9
commit 96b4470fb0
21 changed files with 3920 additions and 4322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

428
docs/es/channels/discord.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Trabajando en funciones del canal de Discord
summary: Estado de compatibilidad, capacidades y configuración del bot de Discord
summary: Estado del soporte del bot de Discord, capacidades y configuración
title: Discord
x-i18n:
generated_at: "2026-04-06T03:08:07Z"
generated_at: "2026-04-09T01:29:29Z"
model: gpt-5.4
provider: openai
source_hash: 54af2176a1b4fa1681e3f07494def0c652a2730165058848000e71a59e2a9d08
source_hash: 3cd2886fad941ae2129e681911309539e9a65a2352b777b538d7f4686a68f73f
source_path: channels/discord.md
workflow: 15
---
# Discord (API de bot)
Estado: listo para mensajes directos y canales de servidor mediante el gateway oficial de Discord.
Estado: listo para mensajes directos y canales de servidor mediante la gateway oficial de Discord.
<CardGroup cols={3}>
<Card title="Vinculación" icon="link" href="/es/channels/pairing">
Los mensajes directos de Discord usan el modo de vinculación de forma predeterminada.
<Card title="Emparejamiento" icon="link" href="/es/channels/pairing">
Los mensajes directos de Discord usan el modo de emparejamiento de forma predeterminada.
</Card>
<Card title="Comandos slash" icon="terminal" href="/es/tools/slash-commands">
<Card title="Comandos de barra inclinada" icon="terminal" href="/es/tools/slash-commands">
Comportamiento nativo de comandos y catálogo de comandos.
</Card>
<Card title="Solución de problemas del canal" icon="wrench" href="/es/channels/troubleshooting">
@ -30,7 +30,7 @@ Estado: listo para mensajes directos y canales de servidor mediante el gateway o
## Configuración rápida
Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servidor y vincularlo con OpenClaw. Recomendamos añadir tu bot a tu propio servidor privado. Si aún no tienes uno, [crea uno primero](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (elige **Create My Own > For me and my friends**).
Necesitarás crear una aplicación nueva con un bot, añadir el bot a tu servidor y emparejarlo con OpenClaw. Recomendamos añadir tu bot a tu propio servidor privado. Si todavía no tienes uno, [crea uno primero](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (elige **Create My Own > For me and my friends**).
<Steps>
<Step title="Crear una aplicación de Discord y un bot">
@ -41,16 +41,16 @@ Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servido
</Step>
<Step title="Habilitar intents privilegiados">
Sigue en la página **Bot**, desplázate hacia abajo hasta **Privileged Gateway Intents** y habilita:
Aún en la página **Bot**, desplázate hacia abajo hasta **Privileged Gateway Intents** y habilita:
- **Message Content Intent** (obligatorio)
- **Server Members Intent** (recomendado; obligatorio para listas de permitidos basadas en roles y coincidencia de nombre a ID)
- **Server Members Intent** (recomendado; obligatorio para listas de permitidos por rol y coincidencia de nombre a ID)
- **Presence Intent** (opcional; solo se necesita para actualizaciones de presencia)
</Step>
<Step title="Copiar el token de tu bot">
Vuelve a desplazarte hacia arriba en la página **Bot** y haz clic en **Reset Token**.
Vuelve a subir en la página **Bot** y haz clic en **Reset Token**.
<Note>
A pesar del nombre, esto genera tu primer token; no se está "restableciendo" nada.
@ -61,7 +61,7 @@ Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servido
</Step>
<Step title="Generar una URL de invitación y añadir el bot a tu servidor">
Haz clic en **OAuth2** en la barra lateral. Generarás una URL de invitación con los permisos correctos para añadir el bot a tu servidor.
Haz clic en **OAuth2** en la barra lateral. Generarás una URL de invitación con los permisos adecuados para añadir el bot a tu servidor.
Desplázate hacia abajo hasta **OAuth2 URL Generator** y habilita:
@ -81,26 +81,26 @@ Necesitarás crear una nueva aplicación con un bot, añadir el bot a tu servido
</Step>
<Step title="Habilitar el modo desarrollador y recopilar tus IDs">
De vuelta en la app de Discord, debes habilitar el modo desarrollador para poder copiar los IDs internos.
<Step title="Habilitar el modo desarrollador y recopilar tus ID">
De vuelta en la app de Discord, debes habilitar el modo desarrollador para poder copiar IDs internas.
1. Haz clic en **User Settings** (icono de engranaje junto a tu avatar) → **Advanced** → activa **Developer Mode**
2. Haz clic derecho en el **icono de tu servidor** en la barra lateral → **Copy Server ID**
3. Haz clic derecho en **tu propio avatar** → **Copy User ID**
3. Haz clic derecho en tu **propio avatar** → **Copy User ID**
Guarda tu **Server ID** y tu **User ID** junto con tu Bot Token; enviarás los tres a OpenClaw en el siguiente paso.
Guarda tu **Server ID** y **User ID** junto con tu Bot Token; enviarás los tres a OpenClaw en el siguiente paso.
</Step>
<Step title="Permitir mensajes directos de miembros del servidor">
Para que la vinculación funcione, Discord debe permitir que tu bot te envíe mensajes directos. Haz clic derecho en el **icono de tu servidor** → **Privacy Settings** → activa **Direct Messages**.
Para que el emparejamiento funcione, Discord debe permitir que tu bot te envíe mensajes directos. Haz clic derecho en el **icono de tu servidor** → **Privacy Settings** → activa **Direct Messages**.
Esto permite que los miembros del servidor (incluidos los bots) te envíen mensajes directos. Mantén esto habilitado si quieres usar mensajes directos de Discord con OpenClaw. Si solo planeas usar canales del servidor, puedes desactivar los mensajes directos después de la vinculación.
Esto permite que los miembros del servidor (incluidos los bots) te envíen mensajes directos. Mantén esto habilitado si quieres usar mensajes directos de Discord con OpenClaw. Si solo planeas usar canales de servidor, puedes desactivar los mensajes directos después del emparejamiento.
</Step>
<Step title="Configurar tu token de bot de forma segura (no lo envíes por chat)">
El token de tu bot de Discord es un secreto (como una contraseña). Configúralo en la máquina donde se ejecuta OpenClaw antes de enviar mensajes a tu agente.
<Step title="Establecer el token de tu bot de forma segura (no lo envíes en el chat)">
El token de tu bot de Discord es un secreto (como una contraseña). Establécelo en la máquina que ejecuta OpenClaw antes de enviar mensajes a tu agente.
```bash
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
@ -110,17 +110,17 @@ openclaw config set channels.discord.enabled true --strict-json
openclaw gateway
```
Si OpenClaw ya se está ejecutando como servicio en segundo plano, reinícialo mediante la app de OpenClaw para Mac o deteniendo y reiniciando el proceso `openclaw gateway run`.
Si OpenClaw ya se está ejecutando como servicio en segundo plano, reinícialo mediante la app OpenClaw para Mac o deteniendo y reiniciando el proceso `openclaw gateway run`.
</Step>
<Step title="Configurar OpenClaw y vincularlo">
<Step title="Configurar OpenClaw y emparejar">
<Tabs>
<Tab title="Pregúntale a tu agente">
Chatea con tu agente de OpenClaw en cualquier canal existente (por ejemplo, Telegram) y díselo. Si Discord es tu primer canal, usa en su lugar la pestaña de CLI / config.
> "Ya configuré mi token de bot de Discord en la configuración. Por favor, termina la configuración de Discord con el User ID `<user_id>` y el Server ID `<server_id>`."
> "Ya configuré el token de mi bot de Discord en la configuración. Completa la configuración de Discord con User ID `<user_id>` y Server ID `<server_id>`."
</Tab>
<Tab title="CLI / config">
Si prefieres una configuración basada en archivos, establece:
@ -140,27 +140,27 @@ openclaw gateway
}
```
Respaldo de entorno para la cuenta predeterminada:
Respaldo por variable de entorno para la cuenta predeterminada:
```bash
DISCORD_BOT_TOKEN=...
```
Se admiten valores `token` en texto plano. También se admiten valores SecretRef para `channels.discord.token` en proveedores env/file/exec. Consulta [Gestión de secretos](/es/gateway/secrets).
Se admiten valores `token` en texto plano. También se admiten valores SecretRef para `channels.discord.token` en proveedores env/file/exec. Consulta [Secrets Management](/es/gateway/secrets).
</Tab>
</Tabs>
</Step>
<Step title="Aprobar la primera vinculación por mensaje directo">
Espera hasta que el gateway esté en ejecución y luego envía un mensaje directo a tu bot en Discord. Responderá con un código de vinculación.
<Step title="Aprobar el primer emparejamiento por mensaje directo">
Espera hasta que la gateway esté en ejecución y luego envía un mensaje directo a tu bot en Discord. Responderá con un código de emparejamiento.
<Tabs>
<Tab title="Pregúntale a tu agente">
Envía el código de vinculación a tu agente en tu canal existente:
Envía el código de emparejamiento a tu agente en tu canal existente:
> "Aprueba este código de vinculación de Discord: `<CODE>`"
> "Aprueba este código de emparejamiento de Discord: `<CODE>`"
</Tab>
<Tab title="CLI">
@ -172,7 +172,7 @@ openclaw pairing approve discord <CODE>
</Tab>
</Tabs>
Los códigos de vinculación caducan después de 1 hora.
Los códigos de emparejamiento caducan después de 1 hora.
Ahora deberías poder chatear con tu agente en Discord mediante mensaje directo.
@ -180,13 +180,13 @@ openclaw pairing approve discord <CODE>
</Steps>
<Note>
La resolución del token tiene en cuenta la cuenta. Los valores de token en la configuración prevalecen sobre el respaldo del entorno. `DISCORD_BOT_TOKEN` solo se usa para la cuenta predeterminada.
Para llamadas salientes avanzadas (herramienta de mensajes/acciones de canal), se usa un `token` explícito por llamada para esa llamada. Esto se aplica a acciones de envío y de lectura/sondeo (por ejemplo read/search/fetch/thread/pins/permissions). La política de cuenta y la configuración de reintentos siguen viniendo de la cuenta seleccionada en la instantánea activa del runtime.
La resolución del token tiene en cuenta la cuenta. Los valores del token en la configuración tienen prioridad sobre el respaldo por variable de entorno. `DISCORD_BOT_TOKEN` solo se usa para la cuenta predeterminada.
Para llamadas salientes avanzadas (acciones de canal/herramienta de mensajes), se usa un `token` explícito por llamada para esa llamada. Esto se aplica a acciones de envío y de lectura/sondeo (por ejemplo read/search/fetch/thread/pins/permissions). La política de cuenta y la configuración de reintentos siguen viniendo de la cuenta seleccionada en la instantánea activa del runtime.
</Note>
## Recomendado: configurar un espacio de trabajo de servidor
Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Discord como un espacio de trabajo completo donde cada canal obtiene su propia sesión de agente con su propio contexto. Esto se recomienda para servidores privados donde solo están tú y tu bot.
Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Discord como un espacio de trabajo completo donde cada canal obtiene su propia sesión de agente con su propio contexto. Esto se recomienda para servidores privados donde solo estáis tú y tu bot.
<Steps>
<Step title="Añadir tu servidor a la lista de permitidos de servidores">
@ -220,11 +220,11 @@ Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Di
</Step>
<Step title="Permitir respuestas sin @mention">
De forma predeterminada, tu agente solo responde en canales del servidor cuando se le menciona con @. En un servidor privado, probablemente quieras que responda a cada mensaje.
De forma predeterminada, tu agente solo responde en canales de servidor cuando se le menciona con @. En un servidor privado, probablemente quieras que responda a todos los mensajes.
<Tabs>
<Tab title="Pregúntale a tu agente">
> "Permite que mi agente responda en este servidor sin tener que mencionarlo con @"
> "Permite que mi agente responda en este servidor sin necesidad de que se le mencione con @"
</Tab>
<Tab title="Config">
Establece `requireMention: false` en la configuración de tu servidor:
@ -248,40 +248,40 @@ Una vez que los mensajes directos funcionen, puedes configurar tu servidor de Di
</Step>
<Step title="Planificar la memoria en canales del servidor">
De forma predeterminada, la memoria a largo plazo (MEMORY.md) solo se carga en sesiones de mensajes directos. Los canales del servidor no cargan automáticamente MEMORY.md.
<Step title="Planificar la memoria en canales de servidor">
De forma predeterminada, la memoria a largo plazo (MEMORY.md) solo se carga en sesiones de mensajes directos. Los canales de servidor no cargan automáticamente MEMORY.md.
<Tabs>
<Tab title="Pregúntale a tu agente">
> "Cuando haga preguntas en canales de Discord, usa memory_search o memory_get si necesitas contexto a largo plazo de MEMORY.md."
</Tab>
<Tab title="Manual">
Si necesitas contexto compartido en cada canal, coloca las instrucciones estables en `AGENTS.md` o `USER.md` (se inyectan en cada sesión). Mantén las notas a largo plazo en `MEMORY.md` y accede a ellas bajo demanda con las herramientas de memoria.
Si necesitas contexto compartido en cada canal, coloca las instrucciones estables en `AGENTS.md` o `USER.md` (se inyectan en cada sesión). Mantén las notas a largo plazo en `MEMORY.md` y accede a ellas bajo demanda con herramientas de memoria.
</Tab>
</Tabs>
</Step>
</Steps>
Ahora crea algunos canales en tu servidor de Discord y empieza a chatear. Tu agente puede ver el nombre del canal, y cada canal obtiene su propia sesión aislada, así que puedes configurar `#coding`, `#home`, `#research` o lo que mejor se adapte a tu flujo de trabajo.
Ahora crea algunos canales en tu servidor de Discord y empieza a chatear. Tu agente puede ver el nombre del canal, y cada canal obtiene su propia sesión aislada, por lo que puedes configurar `#coding`, `#home`, `#research` o lo que mejor se adapte a tu flujo de trabajo.
## Modelo de runtime
- El gateway gestiona la conexión de Discord.
- La gateway es propietaria de la conexión de Discord.
- El enrutamiento de respuestas es determinista: las respuestas entrantes de Discord vuelven a Discord.
- De forma predeterminada (`session.dmScope=main`), los chats directos comparten la sesión principal del agente (`agent:main:main`).
- Los canales del servidor usan claves de sesión aisladas (`agent:<agentId>:discord:channel:<channelId>`).
- Los mensajes directos grupales se ignoran de forma predeterminada (`channels.discord.dm.groupEnabled=false`).
- Los comandos slash nativos se ejecutan en sesiones de comando aisladas (`agent:<agentId>:discord:slash:<userId>`), mientras siguen llevando `CommandTargetSessionKey` a la sesión de conversación enrutada.
- Los canales de servidor usan claves de sesión aisladas (`agent:<agentId>:discord:channel:<channelId>`).
- Los mensajes directos de grupo se ignoran de forma predeterminada (`channels.discord.dm.groupEnabled=false`).
- Los comandos nativos de barra inclinada se ejecutan en sesiones de comando aisladas (`agent:<agentId>:discord:slash:<userId>`), mientras siguen llevando `CommandTargetSessionKey` a la sesión de conversación enrutada.
## Canales de foro
Los canales de foro y multimedia de Discord solo aceptan publicaciones en hilos. OpenClaw admite dos formas de crearlos:
- Envía un mensaje al foro principal (`channel:<forumId>`) para crear automáticamente un hilo. El título del hilo usa la primera línea no vacía de tu mensaje.
- Envía un mensaje al padre del foro (`channel:<forumId>`) para crear automáticamente un hilo. El título del hilo usa la primera línea no vacía de tu mensaje.
- Usa `openclaw message thread create` para crear un hilo directamente. No pases `--message-id` para canales de foro.
Ejemplo: enviar al foro principal para crear un hilo
Ejemplo: enviar al padre del foro para crear un hilo
```bash
openclaw message send --channel discord --target channel:<forumId> \
@ -295,35 +295,35 @@ openclaw message thread create --channel discord --target channel:<forumId> \
--thread-name "Topic title" --message "Body of the post"
```
Los foros principales no aceptan componentes de Discord. Si necesitas componentes, envía el mensaje al hilo mismo (`channel:<threadId>`).
Los padres de foro no aceptan componentes de Discord. Si necesitas componentes, envíalos al propio hilo (`channel:<threadId>`).
## Componentes interactivos
OpenClaw admite contenedores de componentes v2 de Discord para mensajes del agente. Usa la herramienta de mensajes con una carga `components`. Los resultados de interacción se enrutan de vuelta al agente como mensajes entrantes normales y siguen la configuración existente de Discord `replyToMode`.
OpenClaw admite contenedores de componentes v2 de Discord para mensajes del agente. Usa la herramienta de mensajes con una carga útil `components`. Los resultados de interacción se enrutan de vuelta al agente como mensajes entrantes normales y siguen la configuración existente de `replyToMode` de Discord.
Bloques compatibles:
- `text`, `section`, `separator`, `actions`, `media-gallery`, `file`
- Las filas de acciones permiten hasta 5 botones o un solo menú de selección
- Las filas de acciones permiten hasta 5 botones o un único menú de selección
- Tipos de selección: `string`, `user`, `role`, `mentionable`, `channel`
De forma predeterminada, los componentes son de un solo uso. Establece `components.reusable=true` para permitir que botones, selecciones y formularios se usen varias veces hasta que caduquen.
De forma predeterminada, los componentes son de un solo uso. Establece `components.reusable=true` para permitir que botones, selectores y formularios se usen varias veces hasta que caduquen.
Para restringir quién puede hacer clic en un botón, establece `allowedUsers` en ese botón (IDs de usuario de Discord, etiquetas o `*`). Cuando está configurado, los usuarios que no coincidan reciben una denegación efímera.
Los comandos slash `/model` y `/models` abren un selector de modelo interactivo con menús desplegables de proveedor y modelo, además de un paso de envío. La respuesta del selector es efímera y solo el usuario que lo invocó puede usarla.
Los comandos de barra inclinada `/model` y `/models` abren un selector interactivo de modelo con menús desplegables de proveedor y modelo, además de un paso Submit. La respuesta del selector es efímera y solo el usuario que lo invocó puede usarla.
Archivos adjuntos:
- Los bloques `file` deben apuntar a una referencia de adjunto (`attachment://<filename>`)
- Proporciona el adjunto mediante `media`/`path`/`filePath` (archivo único); usa `media-gallery` para varios archivos
- Usa `filename` para anular el nombre de carga cuando deba coincidir con la referencia del adjunto
- Usa `filename` para reemplazar el nombre de carga cuando deba coincidir con la referencia del adjunto
Formularios modales:
- Añade `components.modal` con hasta 5 campos
- Tipos de campo: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select`
- OpenClaw añade automáticamente un botón activador
- OpenClaw añade un botón disparador automáticamente
Ejemplo:
@ -383,32 +383,32 @@ Ejemplo:
<Tabs>
<Tab title="Política de mensajes directos">
`channels.discord.dmPolicy` controla el acceso por mensaje directo (heredado: `channels.discord.dm.policy`):
`channels.discord.dmPolicy` controla el acceso a mensajes directos (heredado: `channels.discord.dm.policy`):
- `pairing` (predeterminado)
- `allowlist`
- `open` (requiere que `channels.discord.allowFrom` incluya `"*"`; heredado: `channels.discord.dm.allowFrom`)
- `disabled`
Si la política de mensajes directos no es abierta, los usuarios desconocidos se bloquean (o se les pide vinculación en modo `pairing`).
Si la política de mensajes directos no está abierta, los usuarios desconocidos se bloquean (o se les solicita emparejamiento en modo `pairing`).
Precedencia de múltiples cuentas:
Precedencia en múltiples cuentas:
- `channels.discord.accounts.default.allowFrom` se aplica solo a la cuenta `default`.
- Las cuentas con nombre heredan `channels.discord.allowFrom` cuando su propio `allowFrom` no está establecido.
- Las cuentas con nombre heredan `channels.discord.allowFrom` cuando su propio `allowFrom` no está definido.
- Las cuentas con nombre no heredan `channels.discord.accounts.default.allowFrom`.
Formato de destino de mensaje directo para la entrega:
Formato de destino de mensajes directos para la entrega:
- `user:<id>`
- mención `<@id>`
Los IDs numéricos sin prefijo son ambiguos y se rechazan a menos que se proporcione un tipo de destino explícito de usuario/canal.
Los ID numéricos sin prefijo son ambiguos y se rechazan a menos que se proporcione un tipo de destino explícito de usuario/canal.
</Tab>
<Tab title="Política de servidores">
El manejo de servidores se controla con `channels.discord.groupPolicy`:
<Tab title="Política de servidor">
El manejo de servidores está controlado por `channels.discord.groupPolicy`:
- `open`
- `allowlist`
@ -418,12 +418,12 @@ Ejemplo:
Comportamiento de `allowlist`:
- el servidor debe coincidir con `channels.discord.guilds` (`id` preferido, se acepta slug)
- listas de remitentes opcionales: `users` (se recomiendan IDs estables) y `roles` (solo IDs de rol); si se configura cualquiera de las dos, los remitentes se permiten cuando coinciden con `users` O `roles`
- la coincidencia directa por nombre/etiqueta está desactivada de forma predeterminada; habilita `channels.discord.dangerouslyAllowNameMatching: true` solo como modo de compatibilidad de último recurso
- se admiten nombres/etiquetas para `users`, pero los IDs son más seguros; `openclaw security audit` avisa cuando se usan entradas de nombre/etiqueta
- el servidor debe coincidir con `channels.discord.guilds` (`id` preferido, slug aceptado)
- listas de permitidos opcionales para remitentes: `users` (se recomiendan IDs estables) y `roles` (solo IDs de rol); si cualquiera está configurado, los remitentes están permitidos cuando coinciden con `users` O `roles`
- la coincidencia directa por nombre/etiqueta está desactivada de forma predeterminada; habilita `channels.discord.dangerouslyAllowNameMatching: true` solo como modo de compatibilidad de emergencia
- se admiten nombres/etiquetas para `users`, pero los IDs son más seguros; `openclaw security audit` advierte cuando se usan entradas de nombre/etiqueta
- si un servidor tiene `channels` configurado, los canales no listados se deniegan
- si un servidor no tiene bloque `channels`, se permiten todos los canales de ese servidor incluido en la lista de permitidos
- si un servidor no tiene bloque `channels`, todos los canales de ese servidor en la lista de permitidos están permitidos
Ejemplo:
@ -449,23 +449,23 @@ Ejemplo:
}
```
Si solo estableces `DISCORD_BOT_TOKEN` y no creas un bloque `channels.discord`, el respaldo del runtime será `groupPolicy="allowlist"` (con una advertencia en los registros), incluso si `channels.defaults.groupPolicy` es `open`.
Si solo configuras `DISCORD_BOT_TOKEN` y no creas un bloque `channels.discord`, el respaldo del runtime es `groupPolicy="allowlist"` (con una advertencia en los registros), incluso si `channels.defaults.groupPolicy` es `open`.
</Tab>
<Tab title="Menciones y mensajes directos grupales">
Los mensajes del servidor requieren mención de forma predeterminada.
<Tab title="Menciones y mensajes directos de grupo">
Los mensajes de servidor están restringidos por mención de forma predeterminada.
La detección de mención incluye:
- mención explícita al bot
- mención explícita del bot
- patrones de mención configurados (`agents.list[].groupChat.mentionPatterns`, respaldo `messages.groupChat.mentionPatterns`)
- comportamiento implícito de respuesta al bot en casos compatibles
- comportamiento implícito de respuesta al bot en los casos compatibles
`requireMention` se configura por servidor/canal (`channels.discord.guilds...`).
`ignoreOtherMentions` opcionalmente descarta mensajes que mencionen a otro usuario/rol pero no al bot (excluyendo @everyone/@here).
`ignoreOtherMentions` descarta opcionalmente mensajes que mencionan a otro usuario/rol pero no al bot (excepto @everyone/@here).
Mensajes directos grupales:
Mensajes directos de grupo:
- predeterminado: ignorados (`dm.groupEnabled=false`)
- lista de permitidos opcional mediante `dm.groupChannels` (IDs o slugs de canal)
@ -475,7 +475,7 @@ Ejemplo:
### Enrutamiento de agentes basado en roles
Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a distintos agentes según el ID del rol. Los bindings basados en roles aceptan solo IDs de rol y se evalúan después de los bindings de peer o parent-peer y antes de los bindings solo de servidor. Si un binding también establece otros campos de coincidencia (por ejemplo `peer` + `guildId` + `roles`), todos los campos configurados deben coincidir.
Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a distintos agentes por ID de rol. Las vinculaciones basadas en rol aceptan solo IDs de rol y se evalúan después de las vinculaciones de par o par padre y antes de las vinculaciones solo de servidor. Si una vinculación también establece otros campos de coincidencia (por ejemplo `peer` + `guildId` + `roles`), todos los campos configurados deben coincidir.
```json5
{
@ -499,10 +499,10 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di
}
```
## Configuración del Developer Portal
## Configuración del portal para desarrolladores
<AccordionGroup>
<Accordion title="Crear aplicación y bot">
<Accordion title="Crear app y bot">
1. Discord Developer Portal -> **Applications** -> **New Application**
2. **Bot** -> **Add Bot**
@ -516,7 +516,7 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di
- Message Content Intent
- Server Members Intent (recomendado)
Presence intent es opcional y solo es obligatorio si quieres recibir actualizaciones de presencia. Establecer la presencia del bot (`setPresence`) no requiere habilitar actualizaciones de presencia para miembros.
Presence intent es opcional y solo es obligatorio si quieres recibir actualizaciones de presencia. Configurar la presencia del bot (`setPresence`) no requiere habilitar actualizaciones de presencia para los miembros.
</Accordion>
@ -534,12 +534,12 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di
- Attach Files
- Add Reactions (opcional)
Evita `Administrator` a menos que sea explícitamente necesario.
Evita `Administrator` salvo que sea explícitamente necesario.
</Accordion>
<Accordion title="Copiar IDs">
Habilita el modo desarrollador de Discord y luego copia:
Habilita Discord Developer Mode y luego copia:
- ID del servidor
- ID del canal
@ -553,14 +553,14 @@ Usa `bindings[].match.roles` para enrutar miembros de servidores de Discord a di
## Comandos nativos y autenticación de comandos
- `commands.native` usa `"auto"` de forma predeterminada y está habilitado para Discord.
- Anulación por canal: `channels.discord.commands.native`.
- `commands.native=false` borra explícitamente los comandos nativos de Discord registrados anteriormente.
- Reemplazo por canal: `channels.discord.commands.native`.
- `commands.native=false` borra explícitamente comandos nativos de Discord registrados anteriormente.
- La autenticación de comandos nativos usa las mismas listas de permitidos/políticas de Discord que el manejo normal de mensajes.
- Los comandos pueden seguir siendo visibles en la interfaz de Discord para usuarios no autorizados; la ejecución sigue aplicando la autorización de OpenClaw y devuelve "not authorized".
- Los comandos pueden seguir siendo visibles en la interfaz de Discord para usuarios que no están autorizados; la ejecución sigue aplicando la autenticación de OpenClaw y devuelve "no autorizado".
Consulta [Comandos slash](/es/tools/slash-commands) para ver el catálogo y comportamiento de comandos.
Consulta [Slash commands](/es/tools/slash-commands) para el catálogo y el comportamiento de los comandos.
Configuración predeterminada de comandos slash:
Configuración predeterminada de comandos de barra inclinada:
- `ephemeral: true`
@ -581,20 +581,22 @@ Configuración predeterminada de comandos slash:
- `batched`
Nota: `off` desactiva el encadenamiento implícito de respuestas. Las etiquetas explícitas `[[reply_to_*]]` siguen respetándose.
`first` siempre adjunta la referencia de respuesta nativa implícita a la primera salida de mensaje de Discord del turno.
`batched` solo adjunta la referencia de respuesta nativa implícita de Discord cuando el turno entrante fue un lote con debounce de varios mensajes. Esto es útil
cuando quieres respuestas nativas principalmente para chats ambiguos y con ráfagas, no para cada turno de mensaje único.
`first` siempre adjunta la referencia implícita de respuesta nativa al primer mensaje saliente de Discord del turno.
`batched` solo adjunta la referencia implícita de respuesta nativa de Discord cuando el
turno entrante fue un lote con antirrebote de varios mensajes. Esto es útil
cuando quieres respuestas nativas principalmente para chats ambiguos con ráfagas, no para cada
turno de un solo mensaje.
Los IDs de mensaje se muestran en el contexto/historial para que los agentes puedan dirigirse a mensajes específicos.
Los IDs de mensaje se muestran en el contexto/historial para que los agentes puedan dirigirse a mensajes concretos.
</Accordion>
<Accordion title="Vista previa de streaming en vivo">
OpenClaw puede transmitir respuestas preliminares enviando un mensaje temporal y editándolo a medida que llega el texto.
<Accordion title="Vista previa de transmisión en vivo">
OpenClaw puede transmitir borradores de respuesta enviando un mensaje temporal y editándolo a medida que llega texto.
- `channels.discord.streaming` controla el streaming de vista previa (`off` | `partial` | `block` | `progress`, predeterminado: `off`).
- El valor predeterminado sigue siendo `off` porque las ediciones de vista previa de Discord pueden alcanzar rápidamente los límites de tasa, especialmente cuando varios bots o gateways comparten la misma cuenta o el tráfico del servidor.
- `progress` se acepta para mantener coherencia entre canales y se asigna a `partial` en Discord.
- `channels.discord.streaming` controla la transmisión de vista previa (`off` | `partial` | `block` | `progress`, predeterminado: `off`).
- El valor predeterminado sigue siendo `off` porque las ediciones de vista previa de Discord pueden alcanzar rápidamente los límites de tasa, especialmente cuando varios bots o gateways comparten la misma cuenta o tráfico de servidor.
- `progress` se acepta por consistencia entre canales y se asigna a `partial` en Discord.
- `channels.discord.streamMode` es un alias heredado y se migra automáticamente.
- `partial` edita un único mensaje de vista previa a medida que llegan los tokens.
- `block` emite fragmentos del tamaño del borrador (usa `draftChunk` para ajustar tamaño y puntos de corte).
@ -611,7 +613,7 @@ Configuración predeterminada de comandos slash:
}
```
Valores predeterminados de fragmentación en modo `block` (limitados por `channels.discord.textChunkLimit`):
Valores predeterminados de fragmentación del modo `block` (limitados a `channels.discord.textChunkLimit`):
```json5
{
@ -628,21 +630,21 @@ Configuración predeterminada de comandos slash:
}
```
La vista previa de streaming es solo de texto; las respuestas multimedia vuelven al envío normal.
La transmisión de vista previa es solo de texto; las respuestas con archivos multimedia vuelven a la entrega normal.
Nota: la vista previa de streaming es independiente del streaming por bloques. Cuando el streaming por bloques está habilitado explícitamente
para Discord, OpenClaw omite la vista previa de streaming para evitar streaming doble.
Nota: la transmisión de vista previa es independiente de la transmisión por bloques. Cuando la transmisión por bloques está explícitamente
habilitada para Discord, OpenClaw omite la vista previa para evitar transmisión doble.
</Accordion>
<Accordion title="Historial, contexto y comportamiento de hilos">
Contexto de historial del servidor:
Contexto del historial de servidores:
- `channels.discord.historyLimit` predeterminado `20`
- respaldo: `messages.groupChat.historyLimit`
- `0` lo desactiva
- `0` desactiva
Controles de historial de mensajes directos:
Controles del historial de mensajes directos:
- `channels.discord.dmHistoryLimit`
- `channels.discord.dms["<user_id>"].historyLimit`
@ -650,25 +652,25 @@ Configuración predeterminada de comandos slash:
Comportamiento de hilos:
- los hilos de Discord se enrutan como sesiones de canal
- los metadatos del hilo principal pueden usarse para vincular con la sesión principal
- la configuración del hilo hereda la configuración del canal principal a menos que exista una entrada específica para el hilo
- los metadatos del hilo padre pueden usarse para el enlace de sesión padre
- la configuración del hilo hereda la configuración del canal padre, salvo que exista una entrada específica para el hilo
Los temas del canal se inyectan como contexto **no confiable** (no como prompt del sistema).
El contexto de respuesta y de mensaje citado actualmente se mantiene tal como se recibió.
Las listas de permitidos de Discord bloquean principalmente quién puede activar al agente, no constituyen un límite completo de redacción de contexto suplementario.
Los temas de canal se inyectan como contexto **no confiable** (no como prompt del sistema).
El contexto de respuestas y mensajes citados actualmente permanece tal como se recibe.
Las listas de permitidos de Discord controlan principalmente quién puede activar el agente, no son un límite completo de redacción de contexto suplementario.
</Accordion>
<Accordion title="Sesiones vinculadas a hilos para subagentes">
Discord puede vincular un hilo a un destino de sesión para que los mensajes posteriores de ese hilo sigan enrutándose a la misma sesión (incluidas sesiones de subagentes).
Discord puede vincular un hilo a un destino de sesión para que los mensajes posteriores en ese hilo sigan enrutándose a la misma sesión (incluidas sesiones de subagentes).
Comandos:
- `/focus <target>` vincula el hilo actual/nuevo a un destino de subagente/sesión
- `/unfocus` elimina la vinculación actual del hilo
- `/agents` muestra ejecuciones activas y estado de vinculación
- `/session idle <duration|off>` inspecciona/actualiza la desvinculación automática por inactividad para bindings enfocados
- `/session max-age <duration|off>` inspecciona/actualiza la antigüedad máxima estricta para bindings enfocados
- `/unfocus` elimina la vinculación del hilo actual
- `/agents` muestra ejecuciones activas y estado de la vinculación
- `/session idle <duration|off>` inspecciona/actualiza el desenfoque automático por inactividad para vinculaciones enfocadas
- `/session max-age <duration|off>` inspecciona/actualiza la antigüedad máxima estricta para vinculaciones enfocadas
Configuración:
@ -687,7 +689,7 @@ Configuración predeterminada de comandos slash:
enabled: true,
idleHours: 24,
maxAgeHours: 0,
spawnSubagentSessions: false, // opt-in
spawnSubagentSessions: false, // activación opcional
},
},
},
@ -697,17 +699,17 @@ Configuración predeterminada de comandos slash:
Notas:
- `session.threadBindings.*` establece los valores predeterminados globales.
- `channels.discord.threadBindings.*` anula el comportamiento de Discord.
- `spawnSubagentSessions` debe ser true para crear/vincular hilos automáticamente para `sessions_spawn({ thread: true })`.
- `spawnAcpSessions` debe ser true para crear/vincular hilos automáticamente para ACP (`/acp spawn ... --thread ...` o `sessions_spawn({ runtime: "acp", thread: true })`).
- Si los thread bindings están deshabilitados para una cuenta, `/focus` y las operaciones relacionadas con thread binding no están disponibles.
- `channels.discord.threadBindings.*` reemplaza el comportamiento de Discord.
- `spawnSubagentSessions` debe ser true para crear/vincular automáticamente hilos para `sessions_spawn({ thread: true })`.
- `spawnAcpSessions` debe ser true para crear/vincular automáticamente hilos para ACP (`/acp spawn ... --thread ...` o `sessions_spawn({ runtime: "acp", thread: true })`).
- Si las vinculaciones de hilos están deshabilitadas para una cuenta, `/focus` y las operaciones relacionadas no están disponibles.
Consulta [Subagentes](/es/tools/subagents), [Agentes ACP](/es/tools/acp-agents) y [Referencia de configuración](/es/gateway/configuration-reference).
Consulta [Sub-agents](/es/tools/subagents), [ACP Agents](/es/tools/acp-agents) y [Configuration Reference](/es/gateway/configuration-reference).
</Accordion>
<Accordion title="Bindings persistentes de canal ACP">
Para espacios de trabajo ACP estables "siempre activos", configura bindings ACP tipados de nivel superior dirigidos a conversaciones de Discord.
<Accordion title="Vinculaciones persistentes de canal ACP">
Para espacios de trabajo ACP estables "siempre activos", configura vinculaciones ACP tipadas de nivel superior dirigidas a conversaciones de Discord.
Ruta de configuración:
@ -763,15 +765,15 @@ Configuración predeterminada de comandos slash:
Notas:
- `/acp spawn codex --bind here` vincula el canal o hilo actual de Discord en su lugar y mantiene los mensajes futuros enrutados a la misma sesión ACP.
- Eso aún puede significar "iniciar una sesión ACP nueva de Codex", pero no crea por sí solo un nuevo hilo de Discord. El canal existente sigue siendo la superficie del chat.
- Codex aún puede ejecutarse en su propio `cwd` o espacio de trabajo de backend en disco. Ese espacio de trabajo es estado del runtime, no un hilo de Discord.
- Los mensajes de hilo pueden heredar el binding ACP del canal principal.
- En un canal o hilo vinculado, `/new` y `/reset` reinician la misma sesión ACP en el mismo lugar.
- Los thread bindings temporales siguen funcionando y pueden anular la resolución del destino mientras estén activos.
- `spawnAcpSessions` solo es obligatorio cuando OpenClaw necesita crear/vincular un hilo secundario mediante `--thread auto|here`. No es obligatorio para `/acp spawn ... --bind here` en el canal actual.
- `/acp spawn codex --bind here` vincula el canal o hilo actual de Discord en el lugar y mantiene los mensajes futuros enrutados a la misma sesión ACP.
- Esto todavía puede significar "iniciar una sesión ACP nueva de Codex", pero no crea por sí solo un hilo nuevo de Discord. El canal existente sigue siendo la superficie de chat.
- Codex puede seguir ejecutándose en su propio `cwd` o espacio de trabajo de backend en disco. Ese espacio de trabajo es estado de runtime, no un hilo de Discord.
- Los mensajes del hilo pueden heredar la vinculación ACP del canal padre.
- En un canal o hilo vinculado, `/new` y `/reset` restablecen la misma sesión ACP en el lugar.
- Las vinculaciones temporales de hilos siguen funcionando y pueden reemplazar la resolución de destino mientras estén activas.
- `spawnAcpSessions` solo es obligatorio cuando OpenClaw necesita crear/vincular un hilo hijo mediante `--thread auto|here`. No es obligatorio para `/acp spawn ... --bind here` en el canal actual.
Consulta [Agentes ACP](/es/tools/acp-agents) para ver detalles del comportamiento de los bindings.
Consulta [ACP Agents](/es/tools/acp-agents) para obtener detalles sobre el comportamiento de las vinculaciones.
</Accordion>
@ -795,11 +797,11 @@ Configuración predeterminada de comandos slash:
- `channels.discord.accounts.<accountId>.ackReaction`
- `channels.discord.ackReaction`
- `messages.ackReaction`
- respaldo del emoji de identidad del agente (`agents.list[].identity.emoji`, si no "👀")
- respaldo al emoji de identidad del agente (`agents.list[].identity.emoji`, o "👀" si no existe)
Notas:
- Discord acepta emoji Unicode o nombres de emoji personalizados.
- Discord acepta emoji unicode o nombres de emoji personalizados.
- Usa `""` para desactivar la reacción para un canal o cuenta.
</Accordion>
@ -807,7 +809,7 @@ Configuración predeterminada de comandos slash:
<Accordion title="Escrituras de configuración">
Las escrituras de configuración iniciadas desde el canal están habilitadas de forma predeterminada.
Esto afecta a los flujos `/config set|unset` (cuando las funciones de comando están habilitadas).
Esto afecta a los flujos `/config set|unset` (cuando las funciones de comandos están habilitadas).
Desactivar:
@ -823,8 +825,8 @@ Configuración predeterminada de comandos slash:
</Accordion>
<Accordion title="Proxy del gateway">
Enruta el tráfico WebSocket del gateway de Discord y las búsquedas REST de inicio (ID de aplicación + resolución de lista de permitidos) a través de un proxy HTTP(S) con `channels.discord.proxy`.
<Accordion title="Proxy de gateway">
Enruta el tráfico WebSocket de la gateway de Discord y las búsquedas REST de inicio (ID de aplicación + resolución de lista de permitidos) mediante un proxy HTTP(S) con `channels.discord.proxy`.
```json5
{
@ -836,7 +838,7 @@ Configuración predeterminada de comandos slash:
}
```
Anulación por cuenta:
Reemplazo por cuenta:
```json5
{
@ -854,8 +856,8 @@ Configuración predeterminada de comandos slash:
</Accordion>
<Accordion title="Compatibilidad con PluralKit">
Habilita la resolución de PluralKit para asignar mensajes proxy a la identidad del miembro del sistema:
<Accordion title="Soporte para PluralKit">
Habilita la resolución de PluralKit para asignar mensajes proxificados a la identidad del miembro del sistema:
```json5
{
@ -873,14 +875,14 @@ Configuración predeterminada de comandos slash:
Notas:
- las listas de permitidos pueden usar `pk:<memberId>`
- los nombres de visualización de miembros se comparan por nombre/slug solo cuando `channels.discord.dangerouslyAllowNameMatching: true`
- las búsquedas usan el ID del mensaje original y están limitadas por ventana temporal
- si la búsqueda falla, los mensajes proxy se tratan como mensajes de bot y se descartan a menos que `allowBots=true`
- los nombres visibles de miembro coinciden por nombre/slug solo cuando `channels.discord.dangerouslyAllowNameMatching: true`
- las búsquedas usan el ID del mensaje original y están limitadas por una ventana temporal
- si la búsqueda falla, los mensajes proxificados se tratan como mensajes de bot y se descartan salvo que `allowBots=true`
</Accordion>
<Accordion title="Configuración de presencia">
Las actualizaciones de presencia se aplican cuando estableces un campo de estado o actividad, o cuando habilitas la presencia automática.
Las actualizaciones de presencia se aplican cuando estableces un campo de estado o actividad, o cuando habilitas presencia automática.
Ejemplo solo de estado:
@ -894,7 +896,7 @@ Configuración predeterminada de comandos slash:
}
```
Ejemplo de actividad (el tipo de actividad predeterminado es estado personalizado):
Ejemplo de actividad (el estado personalizado es el tipo de actividad predeterminado):
```json5
{
@ -907,7 +909,7 @@ Configuración predeterminada de comandos slash:
}
```
Ejemplo de streaming:
Ejemplo de transmisión:
```json5
{
@ -930,7 +932,7 @@ Configuración predeterminada de comandos slash:
- 4: Custom (usa el texto de actividad como estado; el emoji es opcional)
- 5: Competing
Ejemplo de presencia automática (señal de estado del runtime):
Ejemplo de presencia automática (señal de estado de salud del runtime):
```json5
{
@ -947,7 +949,7 @@ Configuración predeterminada de comandos slash:
}
```
La presencia automática asigna la disponibilidad del runtime al estado de Discord: saludable => online, degradado o desconocido => idle, agotado o no disponible => dnd. Anulaciones opcionales de texto:
La presencia automática asigna la disponibilidad del runtime al estado de Discord: healthy => online, degraded o unknown => idle, exhausted o unavailable => dnd. Reemplazos de texto opcionales:
- `autoPresence.healthyText`
- `autoPresence.degradedText`
@ -956,43 +958,43 @@ Configuración predeterminada de comandos slash:
</Accordion>
<Accordion title="Aprobaciones en Discord">
Discord admite el manejo de aprobaciones mediante botones en mensajes directos y, opcionalmente, puede publicar solicitudes de aprobación en el canal de origen.
Discord admite manejo de aprobaciones con botones en mensajes directos y puede, de forma opcional, publicar solicitudes de aprobación en el canal de origen.
Ruta de configuración:
- `channels.discord.execApprovals.enabled`
- `channels.discord.execApprovals.approvers` (opcional; usa como respaldo `commands.ownerAllowFrom` cuando sea posible)
- `channels.discord.execApprovals.approvers` (opcional; usa `commands.ownerAllowFrom` como respaldo cuando es posible)
- `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, predeterminado: `dm`)
- `agentFilter`, `sessionFilter`, `cleanupAfterResolve`
Discord habilita automáticamente las aprobaciones nativas de ejecución cuando `enabled` no está establecido o es `"auto"` y al menos se puede resolver un aprobador, ya sea desde `execApprovals.approvers` o desde `commands.ownerAllowFrom`. Discord no infiere aprobadores de ejecución desde `allowFrom` del canal, `dm.allowFrom` heredado ni `defaultTo` de mensaje directo. Establece `enabled: false` para desactivar explícitamente Discord como cliente nativo de aprobación.
Discord habilita automáticamente las aprobaciones nativas de ejecución cuando `enabled` no está definido o es `"auto"` y al menos un aprobador puede resolverse, ya sea desde `execApprovals.approvers` o desde `commands.ownerAllowFrom`. Discord no infiere aprobadores de ejecución desde `allowFrom` del canal, `dm.allowFrom` heredado ni `defaultTo` de mensajes directos. Establece `enabled: false` para desactivar Discord explícitamente como cliente de aprobación nativo.
Cuando `target` es `channel` o `both`, la solicitud de aprobación es visible en el canal. Solo los aprobadores resueltos pueden usar los botones; los demás usuarios reciben una denegación efímera. Las solicitudes de aprobación incluyen el texto del comando, así que habilita la entrega en canal solo en canales de confianza. Si el ID del canal no puede derivarse de la clave de sesión, OpenClaw vuelve a la entrega por mensaje directo.
Cuando `target` es `channel` o `both`, la solicitud de aprobación es visible en el canal. Solo los aprobadores resueltos pueden usar los botones; otros usuarios reciben una denegación efímera. Las solicitudes de aprobación incluyen el texto del comando, así que habilita la entrega en canal solo en canales de confianza. Si el ID del canal no puede derivarse de la clave de sesión, OpenClaw vuelve a la entrega por mensaje directo.
Discord también renderiza los botones compartidos de aprobación usados por otros canales de chat. El adaptador nativo de Discord añade principalmente el enrutamiento de mensajes directos a aprobadores y la distribución en canal.
Cuando esos botones están presentes, son la UX principal de aprobación; OpenClaw
Discord también renderiza los botones de aprobación compartidos usados por otros canales de chat. El adaptador nativo de Discord añade principalmente enrutamiento por mensaje directo para aprobadores y difusión al canal.
Cuando esos botones están presentes, son la experiencia principal de aprobación; OpenClaw
solo debería incluir un comando manual `/approve` cuando el resultado de la herramienta indique
que las aprobaciones por chat no están disponibles o que la aprobación manual es la única vía.
La autenticación del gateway para este controlador usa el mismo contrato compartido de resolución de credenciales que otros clientes del gateway:
La autenticación de gateway para este manejador usa el mismo contrato compartido de resolución de credenciales que otros clientes de Gateway:
- autenticación local con prioridad de entorno (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` y luego `gateway.auth.*`)
- en modo local, `gateway.remote.*` puede usarse como respaldo solo cuando `gateway.auth.*` no está establecido; los SecretRef locales configurados pero no resueltos fallan en modo cerrado
- compatibilidad con modo remoto mediante `gateway.remote.*` cuando corresponda
- las anulaciones de URL son seguras para anulación: las anulaciones de CLI no reutilizan credenciales implícitas, y las anulaciones de entorno usan solo credenciales del entorno
- autenticación local con prioridad a entorno (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` y luego `gateway.auth.*`)
- en modo local, `gateway.remote.*` puede usarse como respaldo solo cuando `gateway.auth.*` no está configurado; los SecretRef locales configurados pero no resueltos fallan en modo cerrado
- soporte de modo remoto mediante `gateway.remote.*` cuando corresponda
- los reemplazos de URL son seguros para reemplazo: los reemplazos de CLI no reutilizan credenciales implícitas, y los reemplazos de entorno usan solo credenciales del entorno
Comportamiento de resolución de aprobación:
- Los IDs con prefijo `plugin:` se resuelven mediante `plugin.approval.resolve`.
- Los demás IDs se resuelven mediante `exec.approval.resolve`.
- Discord no realiza aquí un salto adicional de respaldo de exec a plugin; el prefijo
del ID decide qué método del gateway llama.
- Otros IDs se resuelven mediante `exec.approval.resolve`.
- Discord no realiza aquí un salto adicional de respaldo de exec a plugin; el
prefijo del ID decide qué método de gateway llama.
Las aprobaciones de ejecución caducan después de 30 minutos de forma predeterminada. Si las aprobaciones fallan con
IDs de aprobación desconocidos, verifica la resolución de aprobadores, la habilitación de la función y
IDs de aprobación desconocidos, verifica la resolución de aprobadores, la habilitación de funciones y
que el tipo de ID de aprobación entregado coincida con la solicitud pendiente.
Documentación relacionada: [Aprobaciones de ejecución](/es/tools/exec-approvals)
Documentación relacionada: [Exec approvals](/es/tools/exec-approvals)
</Accordion>
</AccordionGroup>
@ -1008,24 +1010,26 @@ Ejemplos principales:
- moderación: `timeout`, `kick`, `ban`
- presencia: `setPresence`
Los controles de acciones se encuentran en `channels.discord.actions.*`.
La acción `event-create` acepta un parámetro `image` opcional (URL o ruta de archivo local) para establecer la imagen de portada del evento programado.
Comportamiento predeterminado de controles:
Los controles de acciones están en `channels.discord.actions.*`.
| Grupo de acciones | Predeterminado |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
Comportamiento predeterminado de los controles:
| Grupo de acciones | Predeterminado |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | habilitado |
| roles | deshabilitado |
| moderation | deshabilitado |
| presence | deshabilitado |
| roles | deshabilitado |
| moderation | deshabilitado |
| presence | deshabilitado |
## UI de componentes v2
## Interfaz Components v2
OpenClaw usa componentes v2 de Discord para aprobaciones de ejecución y marcadores entre contextos. Las acciones de mensajes de Discord también pueden aceptar `components` para UI personalizada (avanzado; requiere construir una carga de componente mediante la herramienta de Discord), mientras que los `embeds` heredados siguen disponibles pero no se recomiendan.
OpenClaw usa Discord components v2 para aprobaciones de ejecución y marcadores entre contextos. Las acciones de mensajes de Discord también pueden aceptar `components` para una interfaz personalizada (avanzado; requiere construir una carga útil de componentes mediante la herramienta de Discord), mientras que los `embeds` heredados siguen estando disponibles, pero no se recomiendan.
- `channels.discord.ui.components.accentColor` establece el color de acento usado por los contenedores de componentes de Discord (hex).
- Establécelo por cuenta con `channels.discord.accounts.<id>.ui.components.accentColor`.
- `embeds` se ignoran cuando hay componentes v2 presentes.
- `embeds` se ignoran cuando hay components v2 presentes.
Ejemplo:
@ -1045,15 +1049,15 @@ Ejemplo:
## Canales de voz
OpenClaw puede unirse a canales de voz de Discord para conversaciones continuas en tiempo real. Esto es independiente de los archivos adjuntos de mensajes de voz.
OpenClaw puede unirse a canales de voz de Discord para conversaciones continuas en tiempo real. Esto es independiente de los adjuntos de mensajes de voz.
Requisitos:
- Habilita comandos nativos (`commands.native` o `channels.discord.commands.native`).
- Configura `channels.discord.voice`.
- El bot necesita permisos de Connect + Speak en el canal de voz de destino.
- El bot necesita permisos Connect + Speak en el canal de voz de destino.
Usa el comando nativo exclusivo de Discord `/vc join|leave|status` para controlar las sesiones. El comando usa el agente predeterminado de la cuenta y sigue las mismas reglas de lista de permitidos y política de grupo que otros comandos de Discord.
Usa el comando nativo exclusivo de Discord `/vc join|leave|status` para controlar sesiones. El comando usa el agente predeterminado de la cuenta y sigue las mismas reglas de lista de permitidos y política de grupo que otros comandos de Discord.
Ejemplo de unión automática:
@ -1083,23 +1087,23 @@ Ejemplo de unión automática:
Notas:
- `voice.tts` anula `messages.tts` solo para la reproducción de voz.
- Los turnos de transcripción de voz derivan el estado de propietario de `allowFrom` de Discord (o `dm.allowFrom`); los hablantes que no son propietarios no pueden acceder a herramientas exclusivas del propietario (por ejemplo `gateway` y `cron`).
- La voz está habilitada de forma predeterminada; establece `channels.discord.voice.enabled=false` para deshabilitarla.
- `voice.daveEncryption` y `voice.decryptionFailureTolerance` se transfieren a las opciones de unión de `@discordjs/voice`.
- `voice.tts` reemplaza `messages.tts` solo para la reproducción de voz.
- Los turnos de transcripción de voz derivan el estado de propietario desde `allowFrom` de Discord (o `dm.allowFrom`); los hablantes que no son propietarios no pueden acceder a herramientas exclusivas del propietario (por ejemplo `gateway` y `cron`).
- La voz está habilitada de forma predeterminada; establece `channels.discord.voice.enabled=false` para desactivarla.
- `voice.daveEncryption` y `voice.decryptionFailureTolerance` se pasan directamente a las opciones de unión de `@discordjs/voice`.
- Los valores predeterminados de `@discordjs/voice` son `daveEncryption=true` y `decryptionFailureTolerance=24` si no se establecen.
- OpenClaw también observa fallos de descifrado en recepción y se recupera automáticamente saliendo y volviendo a unirse al canal de voz después de fallos repetidos en una ventana corta.
- Si los registros de recepción muestran repetidamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, esto puede ser el error ascendente de recepción de `@discordjs/voice` registrado en [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419).
- OpenClaw también supervisa los fallos de descifrado de recepción y se recupera automáticamente saliendo y volviendo a unirse al canal de voz después de fallos repetidos en una ventana corta.
- Si los registros de recepción muestran repetidamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, esto puede ser el error upstream de recepción de `@discordjs/voice` rastreado en [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419).
## Mensajes de voz
Los mensajes de voz de Discord muestran una vista previa de forma de onda y requieren audio OGG/Opus más metadatos. OpenClaw genera la forma de onda automáticamente, pero necesita `ffmpeg` y `ffprobe` disponibles en el host del gateway para inspeccionar y convertir archivos de audio.
Los mensajes de voz de Discord muestran una vista previa de forma de onda y requieren audio OGG/Opus más metadatos. OpenClaw genera la forma de onda automáticamente, pero necesita que `ffmpeg` y `ffprobe` estén disponibles en el host de la gateway para inspeccionar y convertir archivos de audio.
Requisitos y restricciones:
- Proporciona una **ruta de archivo local** (las URL se rechazan).
- Omite el contenido de texto (Discord no permite texto + mensaje de voz en la misma carga).
- Se acepta cualquier formato de audio; OpenClaw lo convierte a OGG/Opus cuando sea necesario.
- Proporciona una **ruta de archivo local** (las URLs se rechazan).
- Omite el contenido de texto (Discord no permite texto + mensaje de voz en la misma carga útil).
- Se acepta cualquier formato de audio; OpenClaw convierte a OGG/Opus cuando es necesario.
Ejemplo:
@ -1110,18 +1114,18 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a
## Solución de problemas
<AccordionGroup>
<Accordion title="Se usaron intents no permitidos o el bot no ve mensajes del servidor">
<Accordion title="Se usaron intents no permitidos o el bot no ve mensajes de servidor">
- habilita Message Content Intent
- habilita Server Members Intent cuando dependas de la resolución de usuario/miembro
- reinicia el gateway después de cambiar los intents
- reinicia la gateway después de cambiar intents
</Accordion>
<Accordion title="Mensajes del servidor bloqueados inesperadamente">
<Accordion title="Los mensajes de servidor se bloquean inesperadamente">
- verifica `groupPolicy`
- verifica la lista de permitidos de servidores en `channels.discord.guilds`
- verifica la lista de permitidos del servidor en `channels.discord.guilds`
- si existe el mapa `guild.channels`, solo se permiten los canales listados
- verifica el comportamiento de `requireMention` y los patrones de mención
@ -1138,13 +1142,13 @@ openclaw logs --follow
<Accordion title="Require mention false pero sigue bloqueado">
Causas comunes:
- `groupPolicy="allowlist"` sin una lista de permitidos coincidente de servidor/canal
- `requireMention` configurado en el lugar incorrecto (debe estar en `channels.discord.guilds` o en la entrada del canal)
- `groupPolicy="allowlist"` sin una lista de permitidos de servidor/canal que coincida
- `requireMention` configurado en el lugar equivocado (debe estar en `channels.discord.guilds` o en la entrada del canal)
- remitente bloqueado por la lista de permitidos `users` del servidor/canal
</Accordion>
<Accordion title="Los controladores de larga duración agotan el tiempo o duplican respuestas">
<Accordion title="Los manejadores de larga duración agotan el tiempo o duplican respuestas">
Registros típicos:
@ -1152,16 +1156,16 @@ openclaw logs --follow
- `Slow listener detected ...`
- `discord inbound worker timed out after ...`
Control de presupuesto del listener:
Ajuste del presupuesto del listener:
- cuenta única: `channels.discord.eventQueue.listenerTimeout`
- varias cuentas: `channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`
- múltiples cuentas: `channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`
Control de tiempo de espera de ejecución del worker:
Ajuste del tiempo límite de ejecución del worker:
- cuenta única: `channels.discord.inboundWorker.runTimeoutMs`
- varias cuentas: `channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs`
- predeterminado: `1800000` (30 minutos); establece `0` para deshabilitarlo
- múltiples cuentas: `channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs`
- predeterminado: `1800000` (30 minutos); establece `0` para desactivar
Línea base recomendada:
@ -1185,22 +1189,22 @@ openclaw logs --follow
```
Usa `eventQueue.listenerTimeout` para una configuración lenta del listener y `inboundWorker.runTimeoutMs`
solo si quieres una válvula de seguridad independiente para turnos de agente en cola.
solo si quieres una válvula de seguridad independiente para turnos del agente en cola.
</Accordion>
<Accordion title="Desajustes en la auditoría de permisos">
Las comprobaciones de permisos de `channels status --probe` solo funcionan para IDs numéricos de canal.
Las comprobaciones de permisos de `channels status --probe` solo funcionan con IDs numéricos de canal.
Si usas claves slug, la coincidencia en runtime puede seguir funcionando, pero el sondeo no puede verificar completamente los permisos.
Si usas claves slug, la coincidencia en runtime aún puede funcionar, pero el sondeo no puede verificar completamente los permisos.
</Accordion>
<Accordion title="Problemas de mensajes directos y vinculación">
<Accordion title="Problemas de mensajes directos y emparejamiento">
- mensaje directo deshabilitado: `channels.discord.dm.enabled=false`
- mensajes directos deshabilitados: `channels.discord.dm.enabled=false`
- política de mensajes directos deshabilitada: `channels.discord.dmPolicy="disabled"` (heredado: `channels.discord.dm.policy`)
- esperando aprobación de vinculación en modo `pairing`
- esperando aprobación de emparejamiento en modo `pairing`
</Accordion>
@ -1208,19 +1212,19 @@ openclaw logs --follow
De forma predeterminada, los mensajes creados por bots se ignoran.
Si estableces `channels.discord.allowBots=true`, usa reglas estrictas de mención y lista de permitidos para evitar comportamientos en bucle.
Prefiere `channels.discord.allowBots="mentions"` para aceptar solo mensajes de bots que mencionen al bot.
Prefiere `channels.discord.allowBots="mentions"` para aceptar solo mensajes de bot que mencionen al bot.
</Accordion>
<Accordion title="La STT de voz se pierde con DecryptionFailed(...)">
<Accordion title="Las transcripciones de voz STT se pierden con DecryptionFailed(...)">
- mantén OpenClaw actualizado (`openclaw update`) para que esté presente la lógica de recuperación de recepción de voz de Discord
- confirma `channels.discord.voice.daveEncryption=true` (predeterminado)
- empieza desde `channels.discord.voice.decryptionFailureTolerance=24` (valor predeterminado ascendente) y ajusta solo si hace falta
- empieza con `channels.discord.voice.decryptionFailureTolerance=24` (valor predeterminado upstream) y ajústalo solo si es necesario
- observa los registros para:
- `discord voice: DAVE decrypt failures detected`
- `discord voice: repeated decrypt failures; attempting rejoin`
- si los fallos continúan después de la reconexión automática, recopila registros y compáralos con [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)
- si los fallos continúan después de volver a unirse automáticamente, recopila registros y compáralos con [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)
</Accordion>
</AccordionGroup>
@ -1229,20 +1233,20 @@ openclaw logs --follow
Referencia principal:
- [Referencia de configuración - Discord](/es/gateway/configuration-reference#discord)
- [Configuration reference - Discord](/es/gateway/configuration-reference#discord)
Campos de Discord de alta señal:
- inicio/autenticación: `enabled`, `token`, `accounts.*`, `allowBots`
- política: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*`
- comando: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*`
- comandos: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*`
- cola de eventos: `eventQueue.listenerTimeout` (presupuesto del listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency`
- worker entrante: `inboundWorker.runTimeoutMs`
- respuesta/historial: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- entrega: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage`
- streaming: `streaming` (alias heredado: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce`
- transmisión: `streaming` (alias heredado: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce`
- multimedia/reintentos: `mediaMaxMb`, `retry`
- `mediaMaxMb` limita las cargas salientes a Discord (predeterminado: `100MB`)
- `mediaMaxMb` limita las subidas salientes a Discord (predeterminado: `100MB`)
- acciones: `actions.*`
- presencia: `activity`, `status`, `activityType`, `activityUrl`
- UI: `ui.components.accentColor`
@ -1250,16 +1254,16 @@ Campos de Discord de alta señal:
## Seguridad y operaciones
- Trata los tokens del bot como secretos (se prefiere `DISCORD_BOT_TOKEN` en entornos supervisados).
- Otorga permisos de Discord con privilegio mínimo.
- Si el despliegue/estado de comandos está obsoleto, reinicia el gateway y vuelve a comprobar con `openclaw channels status --probe`.
- Trata los tokens de bot como secretos (`DISCORD_BOT_TOKEN` es lo preferido en entornos supervisados).
- Otorga permisos de Discord con privilegios mínimos.
- Si el despliegue/estado de comandos está desactualizado, reinicia la gateway y vuelve a comprobar con `openclaw channels status --probe`.
## Relacionado
- [Vinculación](/es/channels/pairing)
- [Emparejamiento](/es/channels/pairing)
- [Grupos](/es/channels/groups)
- [Enrutamiento de canales](/es/channels/channel-routing)
- [Seguridad](/es/gateway/security)
- [Enrutamiento de múltiples agentes](/es/concepts/multi-agent)
- [Enrutamiento multiagente](/es/concepts/multi-agent)
- [Solución de problemas](/es/channels/troubleshooting)
- [Comandos slash](/es/tools/slash-commands)
- [Comandos de barra inclinada](/es/tools/slash-commands)

664
docs/es/channels/matrix.md
View File

File diff suppressed because it is too large Load Diff

183
docs/es/concepts/agent-loop.md
View File

@ -1,175 +1,176 @@
---
read_when:
- Necesitas un recorrido exacto del bucle del agente o de los eventos del ciclo de vida
summary: Ciclo de vida del bucle del agente, streams y semántica de espera
- Necesitas una guía exacta del bucle del agente o de los eventos del ciclo de vida
summary: Ciclo de vida del bucle del agente, flujos y semántica de espera
title: Bucle del agente
x-i18n:
generated_at: "2026-04-05T12:39:34Z"
generated_at: "2026-04-09T01:27:48Z"
model: gpt-5.4
provider: openai
source_hash: 8e562e63c494881e9c345efcb93c5f972d69aaec61445afc3d4ad026b2d26883
source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1
source_path: concepts/agent-loop.md
workflow: 15
---
# Bucle del agente (OpenClaw)
Un bucle agéntico es la ejecución completa y “real” de un agente: entrada → ensamblaje de contexto → inferencia del modelo →
Un bucle agéntico es la ejecución “real” completa de un agente: entrada → ensamblaje de contexto → inferencia del modelo →
ejecución de herramientas → respuestas en streaming → persistencia. Es la ruta autoritativa que convierte un mensaje
en acciones y una respuesta final, mientras mantiene coherente el estado de la sesión.
En OpenClaw, un bucle es una única ejecución serializada por sesión que emite eventos de ciclo de vida y de stream
mientras el modelo piensa, llama herramientas y transmite salida. Este documento explica cómo está
conectado de extremo a extremo ese bucle auténtico.
En OpenClaw, un bucle es una sola ejecución serializada por sesión que emite eventos de ciclo de vida y de flujo
mientras el modelo piensa, llama herramientas y transmite la salida. Este documento explica cómo se conecta ese bucle auténtico de extremo a extremo.
## Puntos de entrada
- RPC del Gateway: `agent` y `agent.wait`.
- RPC del gateway: `agent` y `agent.wait`.
- CLI: comando `agent`.
## Cómo funciona (alto nivel)
## Cómo funciona (visión general)
1. El RPC `agent` valida parámetros, resuelve la sesión (`sessionKey`/`sessionId`), conserva los metadatos de la sesión y devuelve `{ runId, acceptedAt }` de inmediato.
1. El RPC `agent` valida los parámetros, resuelve la sesión (sessionKey/sessionId), persiste los metadatos de la sesión y devuelve `{ runId, acceptedAt }` de inmediato.
2. `agentCommand` ejecuta el agente:
- resuelve el modelo y los valores predeterminados de thinking/verbose
- resuelve los valores predeterminados de modelo + thinking/verbose
- carga la instantánea de Skills
- llama a `runEmbeddedPiAgent` (tiempo de ejecución de pi-agent-core)
- llama a `runEmbeddedPiAgent` (runtime de pi-agent-core)
- emite **lifecycle end/error** si el bucle integrado no emite uno
3. `runEmbeddedPiAgent`:
- serializa ejecuciones mediante colas por sesión y una cola global
- resuelve el perfil de modelo y autenticación y construye la sesión de pi
- se suscribe a eventos de pi y transmite deltas del asistente y de herramientas
- serializa las ejecuciones mediante colas por sesión y una cola global
- resuelve el perfil de modelo + autenticación y construye la sesión de Pi
- se suscribe a los eventos de Pi y transmite los deltas del asistente/herramientas
- aplica el tiempo de espera -> aborta la ejecución si se supera
- devuelve cargas útiles y metadatos de uso
4. `subscribeEmbeddedPiSession` conecta los eventos de pi-agent-core al stream `agent` de OpenClaw:
- eventos de herramienta => `stream: "tool"`
- devuelve payloads + metadatos de uso
4. `subscribeEmbeddedPiSession` conecta los eventos de pi-agent-core con el flujo `agent` de OpenClaw:
- eventos de herramientas => `stream: "tool"`
- deltas del asistente => `stream: "assistant"`
- eventos de ciclo de vida => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
5. `agent.wait` usa `waitForAgentRun`:
- espera **lifecycle end/error** para `runId`
- devuelve `{ status: ok|error|timeout, startedAt, endedAt, error? }`
## Colas y concurrencia
## Cola + concurrencia
- Las ejecuciones se serializan por clave de sesión (carril de sesión) y, opcionalmente, mediante un carril global.
- Esto evita condiciones de carrera de herramientas o sesiones y mantiene coherente el historial de la sesión.
- Las ejecuciones se serializan por clave de sesión (carril de sesión) y, opcionalmente, a través de un carril global.
- Esto evita condiciones de carrera de herramientas/sesión y mantiene coherente el historial de la sesión.
- Los canales de mensajería pueden elegir modos de cola (collect/steer/followup) que alimentan este sistema de carriles.
Consulta [Command Queue](/concepts/queue).
Consulta [Cola de comandos](/es/concepts/queue).
## Preparación de sesión y espacio de trabajo
## Preparación de sesión + espacio de trabajo
- El espacio de trabajo se resuelve y se crea; las ejecuciones en sandbox pueden redirigirse a una raíz de espacio de trabajo aislada.
- Se cargan Skills (o se reutilizan desde una instantánea) y se inyectan en el entorno y en el prompt.
- Los archivos de bootstrap/contexto se resuelven y se inyectan en el informe del prompt del sistema.
- El espacio de trabajo se resuelve y se crea; las ejecuciones en sandbox pueden redirigirse a una raíz de espacio de trabajo en sandbox.
- Las Skills se cargan (o se reutilizan desde una instantánea) y se inyectan en el entorno y en el prompt.
- Los archivos de bootstrap/contexto se resuelven y se inyectan en el informe del system prompt.
- Se adquiere un bloqueo de escritura de sesión; `SessionManager` se abre y se prepara antes del streaming.
## Ensamblaje del prompt y prompt del sistema
## Ensamblaje del prompt + system prompt
- El prompt del sistema se construye a partir del prompt base de OpenClaw, el prompt de Skills, el contexto de bootstrap y las anulaciones por ejecución.
- Se aplican límites específicos del modelo y reservas de tokens para compactación.
- Consulta [System prompt](/concepts/system-prompt) para ver lo que ve el modelo.
- El system prompt se construye a partir del prompt base de OpenClaw, el prompt de Skills, el contexto de bootstrap y las anulaciones por ejecución.
- Se aplican los límites específicos del modelo y los tokens reservados para compactación.
- Consulta [System prompt](/es/concepts/system-prompt) para ver lo que ve el modelo.
## Puntos de hook (donde puedes interceptar)
OpenClaw tiene dos sistemas de hooks:
- **Hooks internos** (hooks del Gateway): scripts controlados por eventos para comandos y eventos del ciclo de vida.
- **Hooks de plugin**: puntos de extensión dentro del ciclo de vida del agente o herramienta y de la canalización del gateway.
- **Hooks internos** (hooks del gateway): scripts impulsados por eventos para comandos y eventos del ciclo de vida.
- **Hooks de plugin**: puntos de extensión dentro del ciclo de vida del agente/herramientas y del pipeline del gateway.
### Hooks internos (hooks del Gateway)
### Hooks internos (hooks del gateway)
- **`agent:bootstrap`**: se ejecuta mientras se construyen archivos de bootstrap antes de que el prompt del sistema se finalice.
Úsalo para añadir o eliminar archivos de contexto de bootstrap.
- **Hooks de comandos**: `/new`, `/reset`, `/stop` y otros eventos de comandos (consulta la documentación de Hooks).
- **`agent:bootstrap`**: se ejecuta mientras se construyen los archivos de bootstrap antes de que se finalice el system prompt.
Úsalo para agregar o eliminar archivos de contexto de bootstrap.
- **Hooks de comandos**: `/new`, `/reset`, `/stop` y otros eventos de comandos (consulta el documento de Hooks).
Consulta [Hooks](/automation/hooks) para ver configuración y ejemplos.
Consulta [Hooks](/es/automation/hooks) para la configuración y ejemplos.
### Hooks de plugin (ciclo de vida del agente y del gateway)
### Hooks de plugin (ciclo de vida del agente + gateway)
Se ejecutan dentro del bucle del agente o de la canalización del gateway:
Estos se ejecutan dentro del bucle del agente o del pipeline del gateway:
- **`before_model_resolve`**: se ejecuta antes de la sesión (sin `messages`) para anular de forma determinista el proveedor o modelo antes de la resolución del modelo.
- **`before_prompt_build`**: se ejecuta después de cargar la sesión (con `messages`) para inyectar `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` antes del envío del prompt. Usa `prependContext` para texto dinámico por turno y campos de contexto del sistema para guía estable que deba situarse en el espacio del prompt del sistema.
- **`before_agent_start`**: hook heredado de compatibilidad que puede ejecutarse en cualquiera de las fases; prefiere los hooks explícitos anteriores.
- **`before_agent_reply`**: se ejecuta después de las acciones en línea y antes de la llamada al LLM, permitiendo que un plugin reclame el turno y devuelva una respuesta sintética o silencie completamente el turno.
- **`agent_end`**: inspecciona la lista final de mensajes y los metadatos de la ejecución tras completarse.
- **`before_compaction` / `after_compaction`**: observan o anotan ciclos de compactación.
- **`before_tool_call` / `after_tool_call`**: interceptan parámetros y resultados de herramientas.
- **`before_install`**: inspecciona hallazgos del análisis integrado y, opcionalmente, bloquea instalaciones de Skills o plugins.
- **`tool_result_persist`**: transforma sincrónicamente resultados de herramientas antes de que se escriban en la transcripción de la sesión.
- **`message_received` / `message_sending` / `message_sent`**: hooks de mensajes entrantes y salientes.
- **`before_model_resolve`**: se ejecuta antes de la sesión (sin `messages`) para anular de forma determinista el proveedor/modelo antes de la resolución del modelo.
- **`before_prompt_build`**: se ejecuta después de cargar la sesión (con `messages`) para inyectar `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` antes de enviar el prompt. Usa `prependContext` para texto dinámico por turno y los campos de contexto del sistema para guía estable que deba ubicarse en el espacio del system prompt.
- **`before_agent_start`**: hook heredado de compatibilidad que puede ejecutarse en cualquiera de las dos fases; prefiere los hooks explícitos anteriores.
- **`before_agent_reply`**: se ejecuta después de las acciones en línea y antes de la llamada al LLM, permitiendo que un plugin reclame el turno y devuelva una respuesta sintética o silencie el turno por completo.
- **`agent_end`**: inspecciona la lista final de mensajes y los metadatos de ejecución tras completarse.
- **`before_compaction` / `after_compaction`**: observan o anotan los ciclos de compactación.
- **`before_tool_call` / `after_tool_call`**: interceptan los parámetros/resultados de las herramientas.
- **`before_install`**: inspecciona los resultados del análisis integrado y, opcionalmente, bloquea instalaciones de Skills o plugins.
- **`tool_result_persist`**: transforma de forma síncrona los resultados de herramientas antes de que se escriban en la transcripción de la sesión.
- **`message_received` / `message_sending` / `message_sent`**: hooks de mensajes entrantes + salientes.
- **`session_start` / `session_end`**: límites del ciclo de vida de la sesión.
- **`gateway_start` / `gateway_stop`**: eventos del ciclo de vida del gateway.
Reglas de decisión de hooks para controles de salida y herramientas:
Reglas de decisión de hooks para guardas de salida/herramientas:
- `before_tool_call`: `{ block: true }` es terminal y detiene controladores de menor prioridad.
- `before_tool_call`: `{ block: false }` es una operación nula y no elimina un bloqueo previo.
- `before_install`: `{ block: true }` es terminal y detiene controladores de menor prioridad.
- `before_install`: `{ block: false }` es una operación nula y no elimina un bloqueo previo.
- `message_sending`: `{ cancel: true }` es terminal y detiene controladores de menor prioridad.
- `message_sending`: `{ cancel: false }` es una operación nula y no elimina una cancelación previa.
- `before_tool_call`: `{ block: true }` es terminal y detiene los manejadores de menor prioridad.
- `before_tool_call`: `{ block: false }` no hace nada y no elimina un bloqueo previo.
- `before_install`: `{ block: true }` es terminal y detiene los manejadores de menor prioridad.
- `before_install`: `{ block: false }` no hace nada y no elimina un bloqueo previo.
- `message_sending`: `{ cancel: true }` es terminal y detiene los manejadores de menor prioridad.
- `message_sending`: `{ cancel: false }` no hace nada y no elimina una cancelación previa.
Consulta [Plugin hooks](/plugins/architecture#provider-runtime-hooks) para ver la API de hooks y los detalles de registro.
Consulta [Hooks de plugin](/es/plugins/architecture#provider-runtime-hooks) para la API de hooks y los detalles de registro.
## Streaming y respuestas parciales
## Streaming + respuestas parciales
- Los deltas del asistente se transmiten desde pi-agent-core y se emiten como eventos `assistant`.
- El streaming por bloques puede emitir respuestas parciales en `text_end` o `message_end`.
- El streaming de razonamiento puede emitirse como un stream separado o como respuestas por bloques.
- Consulta [Streaming](/concepts/streaming) para ver el comportamiento de fragmentación y respuestas por bloques.
- El streaming por bloques puede emitir respuestas parciales en `text_end` o en `message_end`.
- El streaming de razonamiento puede emitirse como un flujo independiente o como respuestas por bloques.
- Consulta [Streaming](/es/concepts/streaming) para el comportamiento de fragmentación y respuestas por bloques.
## Ejecución de herramientas y herramientas de mensajería
## Ejecución de herramientas + herramientas de mensajería
- Los eventos de inicio, actualización y fin de herramientas se emiten en el stream `tool`.
- Los resultados de herramientas se sanean en cuanto a tamaño y cargas útiles de imágenes antes de registrarse o emitirse.
- Los eventos de inicio/actualización/fin de herramientas se emiten en el flujo `tool`.
- Los resultados de herramientas se sanean por tamaño y payloads de imagen antes de registrarlos/emitirlos.
- Los envíos de herramientas de mensajería se rastrean para suprimir confirmaciones duplicadas del asistente.
## Modelado de la respuesta y supresión
## Modelado de respuestas + supresión
- Las cargas útiles finales se ensamblan a partir de:
- Los payloads finales se ensamblan a partir de:
- texto del asistente (y razonamiento opcional)
- resúmenes de herramientas en línea (cuando verbose + allowed)
- texto de error del asistente cuando el modelo falla
- El token silencioso exacto `NO_REPLY` / `no_reply` se filtra de las
cargas útiles salientes.
- Los duplicados de herramientas de mensajería se eliminan de la lista final de cargas útiles.
- Si no quedan cargas útiles representables y una herramienta falló, se emite
una respuesta alternativa de error de herramienta (a menos que una herramienta de mensajería ya haya enviado una respuesta visible para el usuario).
- resúmenes de herramientas en línea (cuando verbose + permitido)
- texto de error del asistente cuando falla el modelo
- El token silencioso exacto `NO_REPLY` / `no_reply` se filtra de los
payloads salientes.
- Los duplicados de herramientas de mensajería se eliminan de la lista final de payloads.
- Si no quedan payloads renderizables y una herramienta falló, se emite
una respuesta de error de herramienta de respaldo
(a menos que una herramienta de mensajería ya haya enviado una respuesta visible para el usuario).
## Compactación y reintentos
## Compactación + reintentos
- La compactación automática emite eventos de stream `compaction` y puede activar un reintento.
- En el reintento, se restablecen los búferes en memoria y los resúmenes de herramientas para evitar salida duplicada.
- Consulta [Compaction](/concepts/compaction) para ver la canalización de compactación.
- La compactación automática emite eventos de flujo `compaction` y puede activar un reintento.
- En un reintento, los búferes en memoria y los resúmenes de herramientas se restablecen para evitar salida duplicada.
- Consulta [Compactación](/es/concepts/compaction) para el pipeline de compactación.
## Streams de eventos (actualmente)
## Flujos de eventos (hoy)
- `lifecycle`: emitido por `subscribeEmbeddedPiSession` (y como respaldo por `agentCommand`)
- `assistant`: deltas transmitidos desde pi-agent-core
- `tool`: eventos de herramientas transmitidos desde pi-agent-core
- `assistant`: deltas en streaming desde pi-agent-core
- `tool`: eventos de herramientas en streaming desde pi-agent-core
## Manejo del canal de chat
- Los deltas del asistente se almacenan en búfer en mensajes `delta` del chat.
- Se emite un `final` del chat en **lifecycle end/error**.
- Se emite un `final` de chat en **lifecycle end/error**.
## Tiempos de espera
- Predeterminado de `agent.wait`: 30 s (solo la espera). El parámetro `timeoutMs` lo sustituye.
- Tiempo de ejecución del agente: valor predeterminado de `agents.defaults.timeoutSeconds` 172800 s (48 horas); se aplica en el temporizador de aborto de `runEmbeddedPiAgent`.
- Valor predeterminado de `agent.wait`: 30 s (solo la espera). El parámetro `timeoutMs` lo reemplaza.
- Runtime del agente: `agents.defaults.timeoutSeconds`, valor predeterminado 172800 s (48 horas); se aplica en el temporizador de aborto de `runEmbeddedPiAgent`.
- Tiempo de espera inactivo del LLM: `agents.defaults.llm.idleTimeoutSeconds` aborta una solicitud al modelo cuando no llegan fragmentos de respuesta antes de la ventana de inactividad. Establécelo explícitamente para modelos locales lentos o proveedores de razonamiento/llamadas a herramientas; establécelo en 0 para desactivarlo. Si no se establece, OpenClaw usa `agents.defaults.timeoutSeconds` cuando está configurado; de lo contrario, 60 s. Las ejecuciones activadas por cron sin tiempo de espera explícito del LLM o del agente desactivan el watchdog de inactividad y dependen del tiempo de espera externo del cron.
## Dónde puede terminar antes de tiempo
## Dónde las cosas pueden terminar antes de tiempo
- Tiempo de espera del agente (aborto)
- AbortSignal (cancelación)
- Desconexión del gateway o tiempo de espera de RPC
- Tiempo de espera de `agent.wait` (solo espera, no detiene al agente)
- Tiempo de espera de `agent.wait` (solo de espera, no detiene al agente)
## Relacionado
- [Tools](/tools) — herramientas disponibles del agente
- [Hooks](/automation/hooks) — scripts controlados por eventos activados por eventos del ciclo de vida del agente
- [Compaction](/concepts/compaction) — cómo se resumen las conversaciones largas
- [Exec Approvals](/tools/exec-approvals) — puertas de aprobación para comandos de shell
- [Thinking](/tools/thinking) — configuración del nivel de thinking/razonamiento
- [Herramientas](/es/tools) — herramientas disponibles del agente
- [Hooks](/es/automation/hooks) — scripts impulsados por eventos activados por eventos del ciclo de vida del agente
- [Compactación](/es/concepts/compaction) — cómo se resumen las conversaciones largas
- [Aprobaciones de Exec](/es/tools/exec-approvals) — puertas de aprobación para comandos de shell
- [Thinking](/es/tools/thinking) — configuración del nivel de thinking/razonamiento

129
docs/es/concepts/dreaming.md
View File

@ -2,32 +2,32 @@
read_when:
- Quieres que la promoción de memoria se ejecute automáticamente
- Quieres entender qué hace cada fase de dreaming
- Quieres ajustar la consolidación sin contaminar MEMORY.md
- Quieres ajustar la consolidación sin contaminar `MEMORY.md`
summary: Consolidación de memoria en segundo plano con fases ligera, profunda y REM, además de un Diario de Sueños
title: Dreaming (experimental)
x-i18n:
generated_at: "2026-04-06T05:12:22Z"
generated_at: "2026-04-09T01:27:48Z"
model: gpt-5.4
provider: openai
source_hash: 36c4b1e70801d662090dc8ce20608c2f141c23cd7ce53c54e3dcf332c801fd4e
source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef
source_path: concepts/dreaming.md
workflow: 15
---
# Dreaming (experimental)
Dreaming es el sistema de consolidación de memoria en segundo plano de `memory-core`.
Ayuda a OpenClaw a mover señales fuertes de corto plazo a memoria duradera, mientras
Dreaming es el sistema de consolidación de memoria en segundo plano en `memory-core`.
Ayuda a OpenClaw a mover señales sólidas de corto plazo a memoria duradera mientras
mantiene el proceso explicable y revisable.
Dreaming es **optativo** y está desactivado de forma predeterminada.
Dreaming es **optativo** y está deshabilitado de forma predeterminada.
## Qué escribe dreaming
Dreaming mantiene dos tipos de salida:
- **Estado de máquina** en `memory/.dreams/` (almacén de recuperación, señales de fase, puntos de control de ingestión, bloqueos).
- **Salida legible por humanos** en `DREAMS.md` (o `dreams.md` existente) y archivos opcionales de informes de fase en `memory/dreaming/<phase>/YYYY-MM-DD.md`.
- **Estado de máquina** en `memory/.dreams/` (almacén de recuperación, señales de fase, puntos de control de ingesta, bloqueos).
- **Salida legible por humanos** en `DREAMS.md` (o `dreams.md` existente) y archivos opcionales de informe de fase en `memory/dreaming/<phase>/YYYY-MM-DD.md`.
La promoción a largo plazo sigue escribiendo solo en `MEMORY.md`.
@ -35,33 +35,33 @@ La promoción a largo plazo sigue escribiendo solo en `MEMORY.md`.
Dreaming usa tres fases cooperativas:
| Fase | Propósito | Escritura duradera |
| ----- | --------- | ------------------ |
| Ligera | Ordenar y preparar material reciente de corto plazo | No |
| Profunda | Puntuar y promover candidatos duraderos | Sí (`MEMORY.md`) |
| REM | Reflexionar sobre temas e ideas recurrentes | No |
| Fase | Propósito | Escritura duradera |
| ----- | ----------------------------------------- | ------------------ |
| Light | Ordenar y preparar material reciente de corto plazo | No |
| Deep | Puntuar y promover candidatos duraderos | Sí (`MEMORY.md`) |
| REM | Reflexionar sobre temas e ideas recurrentes | No |
Estas fases son detalles internos de implementación, no "modos"
separados configurados por el usuario.
configurables por el usuario por separado.
### Fase ligera
### Fase Light
La fase ligera ingiere señales recientes de memoria diaria y rastros de recuperación, los deduplica
La fase Light ingiere señales recientes de memoria diaria y rastros de recuperación, los deduplica
y prepara líneas candidatas.
- Lee del estado de recuperación a corto plazo y de archivos recientes de memoria diaria.
- Lee del estado de recuperación de corto plazo, archivos recientes de memoria diaria y transcripciones de sesión redactadas cuando están disponibles.
- Escribe un bloque administrado `## Light Sleep` cuando el almacenamiento incluye salida en línea.
- Registra señales de refuerzo para una clasificación profunda posterior.
- Nunca escribe en `MEMORY.md`.
### Fase profunda
### Fase Deep
La fase profunda decide qué se convierte en memoria a largo plazo.
La fase Deep decide qué pasa a convertirse en memoria a largo plazo.
- Clasifica candidatos usando puntuación ponderada y umbrales de acceso.
- Clasifica los candidatos usando puntuación ponderada y umbrales de validación.
- Requiere que `minScore`, `minRecallCount` y `minUniqueQueries` se cumplan.
- Rehidrata fragmentos desde archivos diarios activos antes de escribir, por lo que se omiten los fragmentos obsoletos o eliminados.
- Agrega entradas promovidas a `MEMORY.md`.
- Agrega las entradas promovidas a `MEMORY.md`.
- Escribe un resumen `## Deep Sleep` en `DREAMS.md` y, opcionalmente, escribe `memory/dreaming/deep/YYYY-MM-DD.md`.
### Fase REM
@ -73,40 +73,62 @@ La fase REM extrae patrones y señales reflexivas.
- Registra señales de refuerzo REM usadas por la clasificación profunda.
- Nunca escribe en `MEMORY.md`.
## Ingesta de transcripciones de sesión
Dreaming puede ingerir transcripciones de sesión redactadas en el corpus de dreaming. Cuando
las transcripciones están disponibles, se incorporan en la fase Light junto con señales de
memoria diaria y rastros de recuperación. El contenido personal y sensible se redacta
antes de la ingesta.
## Diario de Sueños
Dreaming también mantiene un **Diario de Sueños** narrativo en `DREAMS.md`.
Después de que cada fase tiene suficiente material, `memory-core` ejecuta un turno
de subagente en segundo plano de mejor esfuerzo (usando el modelo de runtime predeterminado) y agrega una entrada breve al diario.
de subagente en segundo plano de mejor esfuerzo (usando el modelo de runtime predeterminado)
y agrega una entrada breve del diario.
Este diario es para lectura humana en la UI de Dreams, no una fuente de promoción.
Este diario es para lectura humana en la IU de Dreams, no una fuente de promoción.
También existe una vía de relleno histórico fundamentado para trabajo de revisión y recuperación:
- `memory rem-harness --path ... --grounded` previsualiza la salida del diario fundamentado a partir de notas históricas `YYYY-MM-DD.md`.
- `memory rem-backfill --path ...` escribe entradas fundamentadas reversibles del diario en `DREAMS.md`.
- `memory rem-backfill --path ... --stage-short-term` prepara candidatos duraderos fundamentados en el mismo almacén de evidencias de corto plazo que la fase Deep normal ya usa.
- `memory rem-backfill --rollback` y `--rollback-short-term` eliminan esos artefactos de relleno preparados sin tocar las entradas normales del diario ni la recuperación activa de corto plazo.
La IU de Control expone el mismo flujo de relleno/restablecimiento del diario para que puedas inspeccionar
los resultados en la escena de Dreams antes de decidir si los candidatos fundamentados
merecen promoción. La escena también muestra una vía fundamentada distinta para que puedas ver
qué entradas preparadas de corto plazo provinieron de la reproducción histórica, qué elementos promovidos
fueron impulsados por la vía fundamentada, y borrar solo las entradas preparadas exclusivamente fundamentadas sin
tocar el estado normal activo de corto plazo.
## Señales de clasificación profunda
La clasificación profunda usa seis señales base ponderadas más refuerzo de fase:
| Señal | Peso | Descripción |
| ------ | ---- | ----------- |
| Frecuencia | 0.24 | Cuántas señales de corto plazo acumuló la entrada |
| Relevancia | 0.30 | Calidad media de recuperación de la entrada |
| Señal | Peso | Descripción |
| ------------------- | ---- | ------------------------------------------------- |
| Frecuencia | 0.24 | Cuántas señales de corto plazo acumuló la entrada |
| Relevancia | 0.30 | Calidad media de recuperación de la entrada |
| Diversidad de consultas | 0.15 | Contextos distintos de consulta/día en que apareció |
| Recencia | 0.15 | Puntuación de frescura con decaimiento temporal |
| Consolidación | 0.10 | Fuerza de recurrencia en varios días |
| Riqueza conceptual | 0.06 | Densidad de etiquetas conceptuales del fragmento/ruta |
| Recencia | 0.15 | Puntuación de frescura con decaimiento temporal |
| Consolidación | 0.10 | Fuerza de recurrencia en varios días |
| Riqueza conceptual | 0.06 | Densidad de etiquetas conceptuales del fragmento/ruta |
Los aciertos de las fases ligera y REM añaden un pequeño refuerzo con decaimiento por recencia desde
Los aciertos de las fases Light y REM agregan un pequeño impulso con decaimiento por recencia desde
`memory/.dreams/phase-signals.json`.
## Programación
Cuando está habilitado, `memory-core` administra automáticamente una tarea cron para un barrido
completo de dreaming. Cada barrido ejecuta las fases en orden: ligera -> REM -> profunda.
Cuando está habilitado, `memory-core` administra automáticamente un trabajo cron para un barrido
completo de dreaming. Cada barrido ejecuta las fases en orden: light -> REM -> deep.
Comportamiento predeterminado de la cadencia:
| Configuración | Predeterminado |
| ------------- | -------------- |
| `dreaming.frequency` | `0 3 * * *` |
| Ajuste | Predeterminado |
| -------------------- | -------------- |
| `dreaming.frequency` | `0 3 * * *` |
## Inicio rápido
@ -148,7 +170,7 @@ Habilitar dreaming con una cadencia de barrido personalizada:
}
```
## Comando de barra
## Comando de barra inclinada
```
/dreaming status
@ -159,7 +181,7 @@ Habilitar dreaming con una cadencia de barrido personalizada:
## Flujo de trabajo de la CLI
Usa la promoción de la CLI para vista previa o aplicación manual:
Usa la promoción de la CLI para previsualizar o aplicar manualmente:
```bash
openclaw memory promote
@ -168,8 +190,8 @@ openclaw memory promote --limit 5
openclaw memory status --deep
```
La ejecución manual de `memory promote` usa los umbrales de la fase profunda de forma predeterminada, salvo que se sobrescriban
con flags de la CLI.
`memory promote` manual usa umbrales de la fase Deep de forma predeterminada, a menos que se reemplacen
con banderas de la CLI.
Explica por qué un candidato específico se promovería o no:
@ -178,7 +200,7 @@ openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
```
Obtén una vista previa de reflexiones REM, verdades candidatas y salida de promoción profunda sin
Previsualiza reflexiones REM, verdades candidatas y salida de promoción profunda sin
escribir nada:
```bash
@ -188,28 +210,29 @@ openclaw memory rem-harness --json
## Valores predeterminados clave
Todas las configuraciones viven en `plugins.entries.memory-core.config.dreaming`.
Todos los ajustes están en `plugins.entries.memory-core.config.dreaming`.
| Clave | Predeterminado |
| ----- | -------------- |
| `enabled` | `false` |
| `frequency` | `0 3 * * *` |
| Clave | Predeterminado |
| ----------- | -------------- |
| `enabled` | `false` |
| `frequency` | `0 3 * * *` |
La política de fases, los umbrales y el comportamiento de almacenamiento son detalles internos de implementación
(no son configuración orientada al usuario).
(no configuración orientada al usuario).
Consulta la [referencia de configuración de Memory](/es/reference/memory-config#dreaming-experimental)
para ver la lista completa de claves.
## UI de Dreams
## IU de Dreams
Cuando está habilitada, la pestaña **Dreams** del Gateway muestra:
Cuando está habilitada, la pestaña **Dreams** de Gateway muestra:
- estado actual de habilitación de dreaming
- estado actual de dreaming habilitado
- estado a nivel de fase y presencia de barrido administrado
- recuentos de corto plazo, largo plazo y promovidos hoy
- hora de la siguiente ejecución programada
- un lector expandible del Diario de Sueños respaldado por `doctor.memory.dreamDiary`
- recuentos de corto plazo, fundamentados, de señales y promovidos hoy
- hora de la próxima ejecución programada
- una vía de escena fundamentada distinta para entradas preparadas de reproducción histórica
- un lector expandible de Diario de Sueños respaldado por `doctor.memory.dreamDiary`
## Relacionado

165
docs/es/concepts/memory.md
View File

@ -5,10 +5,10 @@ read_when:
summary: Cómo OpenClaw recuerda cosas entre sesiones
title: Descripción general de la memoria
x-i18n:
generated_at: "2026-04-08T05:03:03Z"
generated_at: "2026-04-09T01:27:44Z"
model: gpt-5.4
provider: openai
source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af
source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059
source_path: concepts/memory.md
workflow: 15
---
@ -28,76 +28,80 @@ Tu agente tiene tres archivos relacionados con la memoria:
- **`memory/YYYY-MM-DD.md`** -- notas diarias. Contexto y observaciones en
curso. Las notas de hoy y de ayer se cargan automáticamente.
- **`DREAMS.md`** (experimental, opcional) -- Diario de sueños y resúmenes de
barridos de sueño para revisión humana.
barridos de sueño para revisión humana, incluidas entradas de relleno
histórico fundamentado.
Estos archivos viven en el espacio de trabajo del agente (predeterminado `~/.openclaw/workspace`).
<Tip>
Si quieres que tu agente recuerde algo, solo pídeselo: "Recuerda que prefiero
TypeScript." Lo escribirá en el archivo adecuado.
TypeScript". Lo escribirá en el archivo adecuado.
</Tip>
## Herramientas de memoria
El agente tiene dos herramientas para trabajar con la memoria:
- **`memory_search`** -- encuentra notas relevantes mediante búsqueda
semántica, incluso cuando la redacción difiere de la original.
- **`memory_get`** -- lee un archivo de memoria específico o un intervalo de
líneas.
- **`memory_search`** -- encuentra notas relevantes usando búsqueda semántica,
incluso cuando la redacción difiere del original.
- **`memory_get`** -- lee un archivo de memoria específico o un rango de líneas.
Ambas herramientas las proporciona el plugin de memoria activo (predeterminado: `memory-core`).
Ambas herramientas las proporciona el plugin de memoria activo
(predeterminado: `memory-core`).
## Plugin complementario Memory Wiki
## Plugin complementario de Wiki de memoria
Si quieres que la memoria duradera se comporte más como una base de conocimiento mantenida que
como simples notas sin procesar, usa el plugin integrado `memory-wiki`.
Si quieres que la memoria duradera se comporte más como una base de
conocimiento mantenida que como simples notas sin procesar, usa el plugin
incluido `memory-wiki`.
`memory-wiki` compila el conocimiento duradero en una bóveda wiki con:
- estructura de páginas determinista
- afirmaciones y evidencia estructuradas
- seguimiento de contradicciones y vigencia
- afirmaciones y evidencias estructuradas
- seguimiento de contradicciones y actualidad
- paneles generados
- resúmenes compilados para consumidores del agente/runtime
- resúmenes compilados para consumidores de agente/runtime
- herramientas nativas de wiki como `wiki_search`, `wiki_get`, `wiki_apply` y `wiki_lint`
No reemplaza al plugin de memoria activo. El plugin de memoria activo sigue
encargándose de la recuperación, la promoción y el sueño. `memory-wiki` añade una
capa de conocimiento rica en procedencia a su lado.
siendo responsable de la recuperación, la promoción y el sueño. `memory-wiki`
añade una capa de conocimiento rica en procedencia junto a él.
Consulta [Memory Wiki](/es/plugins/memory-wiki).
## Búsqueda en memoria
## Búsqueda de memoria
Cuando hay configurado un proveedor de embeddings, `memory_search` usa
**búsqueda híbrida** -- combinando similitud vectorial (significado semántico) con coincidencia por palabras clave
(términos exactos como ID y símbolos de código). Esto funciona de inmediato en cuanto tengas
una clave de API para cualquier proveedor compatible.
Cuando se configura un proveedor de embeddings, `memory_search` usa **búsqueda
híbrida**: combina similitud vectorial (significado semántico) con coincidencia
por palabras clave (términos exactos como identificadores y símbolos de código).
Esto funciona de inmediato en cuanto tengas una clave de API para cualquier
proveedor compatible.
<Info>
OpenClaw detecta automáticamente tu proveedor de embeddings a partir de las claves de API disponibles. Si
tienes configurada una clave de OpenAI, Gemini, Voyage o Mistral, la búsqueda en memoria se
habilita automáticamente.
OpenClaw detecta automáticamente tu proveedor de embeddings a partir de las
claves de API disponibles. Si tienes configurada una clave de OpenAI, Gemini,
Voyage o Mistral, la búsqueda de memoria se habilita automáticamente.
</Info>
Para obtener detalles sobre cómo funciona la búsqueda, las opciones de ajuste y la configuración del proveedor, consulta
Para obtener detalles sobre cómo funciona la búsqueda, las opciones de ajuste y
la configuración del proveedor, consulta
[Memory Search](/es/concepts/memory-search).
## Backends de memoria
<CardGroup cols={3}>
<Card title="Integrado (predeterminado)" icon="database" href="/es/concepts/memory-builtin">
Basado en SQLite. Funciona de inmediato con búsqueda por palabras clave, similitud vectorial y
búsqueda híbrida. Sin dependencias adicionales.
Basado en SQLite. Funciona de inmediato con búsqueda por palabras clave,
similitud vectorial y búsqueda híbrida. Sin dependencias adicionales.
</Card>
<Card title="QMD" icon="search" href="/es/concepts/memory-qmd">
Sidecar local-first con reranking, expansión de consultas y la capacidad de indexar
directorios fuera del espacio de trabajo.
Sidecar local-first con reranking, expansión de consultas y la capacidad de
indexar directorios fuera del espacio de trabajo.
</Card>
<Card title="Honcho" icon="brain" href="/es/concepts/memory-honcho">
Memoria entre sesiones nativa para IA con modelado de usuario, búsqueda semántica y
conocimiento de múltiples agentes. Instalación mediante plugin.
Memoria nativa de IA entre sesiones con modelado de usuario, búsqueda semántica
y conocimiento multiagente. Requiere instalación del plugin.
</Card>
</CardGroup>
@ -105,59 +109,100 @@ conocimiento de múltiples agentes. Instalación mediante plugin.
<CardGroup cols={1}>
<Card title="Memory Wiki" icon="book" href="/es/plugins/memory-wiki">
Compila la memoria duradera en una bóveda wiki rica en procedencia con afirmaciones,
paneles, modo puente y flujos de trabajo compatibles con Obsidian.
Compila la memoria duradera en una bóveda wiki rica en procedencia con
afirmaciones, paneles, modo puente y flujos de trabajo compatibles con Obsidian.
</Card>
</CardGroup>
## Vaciado automático de memoria
Antes de que la [compactación](/es/concepts/compaction) resuma tu conversación, OpenClaw
ejecuta un turno silencioso que recuerda al agente que guarde el contexto importante en archivos
de memoria. Esto está activado de forma predeterminada; no necesitas configurar nada.
Antes de que la [compactación](/es/concepts/compaction) resuma tu conversación,
OpenClaw ejecuta un turno silencioso que recuerda al agente que guarde el
contexto importante en archivos de memoria. Esto está activado de forma
predeterminada; no necesitas configurar nada.
<Tip>
El vaciado de memoria evita la pérdida de contexto durante la compactación. Si tu agente tiene
hechos importantes en la conversación que todavía no se han escrito en un archivo,
se guardarán automáticamente antes de que ocurra el resumen.
El vaciado de memoria evita la pérdida de contexto durante la compactación. Si
tu agente tiene hechos importantes en la conversación que todavía no están
escritos en un archivo, se guardarán automáticamente antes de que ocurra el
resumen.
</Tip>
## Sueño (experimental)
El sueño es un proceso opcional de consolidación en segundo plano para la memoria. Recopila
señales a corto plazo, puntúa candidatos y promueve solo los elementos que cumplen los requisitos a la
memoria a largo plazo (`MEMORY.md`).
El sueño es un proceso opcional de consolidación de memoria en segundo plano.
Recopila señales a corto plazo, puntúa candidatos y promueve solo los elementos
que cumplen los requisitos a la memoria a largo plazo (`MEMORY.md`).
Está diseñado para mantener alta la relación señal-ruido de la memoria a largo plazo:
Está diseñado para mantener la memoria a largo plazo con alta señal:
- **Optativo**: desactivado de forma predeterminada.
- **Programado**: cuando está activado, `memory-core` gestiona automáticamente un trabajo cron recurrente
para un barrido completo de sueño.
- **Con umbrales**: las promociones deben superar filtros de puntuación, frecuencia de recuperación y
diversidad de consultas.
- **Revisable**: los resúmenes de fase y las entradas del diario se escriben en `DREAMS.md`
para revisión humana.
- **Participación voluntaria**: desactivado de forma predeterminada.
- **Programado**: cuando está activado, `memory-core` gestiona automáticamente
un trabajo cron recurrente para un barrido completo de sueño.
- **Con umbrales**: las promociones deben superar filtros de puntuación,
frecuencia de recuperación y diversidad de consultas.
- **Revisable**: los resúmenes de fase y las entradas del diario se escriben en
`DREAMS.md` para revisión humana.
Para conocer el comportamiento por fases, las señales de puntuación y los detalles del Diario de sueños, consulta
[Sueño (experimental)](/es/concepts/dreaming).
Para el comportamiento de las fases, las señales de puntuación y los detalles
del Diario de sueños, consulta [Dreaming (experimental)](/es/concepts/dreaming).
## Relleno fundamentado y promoción en vivo
El sistema de sueño ahora tiene dos vías de revisión estrechamente
relacionadas:
- **Sueño en vivo** funciona a partir del almacén de sueño a corto plazo en
`memory/.dreams/` y es lo que usa la fase profunda normal al decidir qué
puede graduarse a `MEMORY.md`.
- **Relleno fundamentado** lee notas históricas `memory/YYYY-MM-DD.md` como
archivos de día independientes y escribe una salida de revisión estructurada
en `DREAMS.md`.
El relleno fundamentado es útil cuando quieres volver a procesar notas antiguas
e inspeccionar lo que el sistema considera duradero sin editar manualmente
`MEMORY.md`.
Cuando usas:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
los candidatos duraderos fundamentados no se promueven directamente. Se preparan
en el mismo almacén de sueño a corto plazo que la fase profunda normal ya usa.
Eso significa que:
- `DREAMS.md` sigue siendo la superficie de revisión humana.
- el almacén a corto plazo sigue siendo la superficie de clasificación orientada a máquinas.
- `MEMORY.md` sigue siendo escrito solo por la promoción profunda.
Si decides que la repetición no fue útil, puedes eliminar los artefactos
preparados sin tocar las entradas normales del diario ni el estado normal de
recuperación:
```bash
openclaw memory rem-backfill --rollback
openclaw memory rem-backfill --rollback-short-term
```
## CLI
```bash
openclaw memory status # Check index status and provider
openclaw memory search "query" # Search from the command line
openclaw memory index --force # Rebuild the index
openclaw memory status # Comprobar el estado del índice y el proveedor
openclaw memory search "query" # Buscar desde la línea de comandos
openclaw memory index --force # Reconstruir el índice
```
## Más información
## Lecturas adicionales
- [Builtin Memory Engine](/es/concepts/memory-builtin) -- backend SQLite predeterminado
- [Builtin Memory Engine](/es/concepts/memory-builtin) -- backend predeterminado de SQLite
- [QMD Memory Engine](/es/concepts/memory-qmd) -- sidecar local-first avanzado
- [Honcho Memory](/es/concepts/memory-honcho) -- memoria entre sesiones nativa para IA
- [Honcho Memory](/es/concepts/memory-honcho) -- memoria nativa de IA entre sesiones
- [Memory Wiki](/es/plugins/memory-wiki) -- bóveda de conocimiento compilada y herramientas nativas de wiki
- [Memory Search](/es/concepts/memory-search) -- canalización de búsqueda, proveedores y
ajuste
- [Dreaming (experimental)](/es/concepts/dreaming) -- promoción en segundo plano
de la recuperación a corto plazo a la memoria a largo plazo
desde la recuperación a corto plazo hasta la memoria a largo plazo
- [Memory configuration reference](/es/reference/memory-config) -- todas las opciones de configuración
- [Compaction](/es/concepts/compaction) -- cómo interactúa la compactación con la memoria

496
docs/es/concepts/model-providers.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Necesitas una referencia de configuración de modelos proveedor por proveedor
- Quieres configuraciones de ejemplo o comandos de incorporación de la CLI para proveedores de modelos
summary: Descripción general de los proveedores de modelos con configuraciones de ejemplo + flujos de la CLI
- Quieres configuraciones de ejemplo o comandos de incorporación por CLI para proveedores de modelos
summary: Resumen de proveedores de modelos con configuraciones de ejemplo + flujos de CLI
title: Proveedores de modelos
x-i18n:
generated_at: "2026-04-08T05:04:33Z"
generated_at: "2026-04-09T01:29:09Z"
model: gpt-5.4
provider: openai
source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9
source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b
source_path: concepts/model-providers.md
workflow: 15
---
@ -20,21 +20,22 @@ Para las reglas de selección de modelos, consulta [/concepts/models](/es/concep
## Reglas rápidas
- Las referencias de modelo usan `provider/model` (ejemplo: `opencode/claude-opus-4-6`).
- Si configuras `agents.defaults.models`, se convierte en la lista permitida.
- Ayudantes de la CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
- Las reglas de runtime de fallback, las sondas de enfriamiento y la persistencia de las anulaciones de sesión
se documentan en [/concepts/model-failover](/es/concepts/model-failover).
- Las referencias de modelos usan `provider/model` (ejemplo: `opencode/claude-opus-4-6`).
- Si configuras `agents.defaults.models`, se convierte en la lista de permitidos.
- Ayudantes de CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
- Las reglas de tiempo de ejecución de respaldo, las sondas de enfriamiento y la persistencia de anulaciones por sesión
están documentadas en [/concepts/model-failover](/es/concepts/model-failover).
- `models.providers.*.models[].contextWindow` son metadatos nativos del modelo;
`models.providers.*.models[].contextTokens` es el límite efectivo del runtime.
- Los plugins de proveedor pueden inyectar catálogos de modelos mediante `registerProvider({ catalog })`;
`models.providers.*.models[].contextTokens` es el límite efectivo en tiempo de ejecución.
- Los plugins de proveedores pueden inyectar catálogos de modelos mediante `registerProvider({ catalog })`;
OpenClaw fusiona esa salida en `models.providers` antes de escribir
`models.json`.
- Los manifiestos de proveedor pueden declarar `providerAuthEnvVars` para que las
sondas genéricas de autenticación basadas en variables de entorno no necesiten cargar el runtime del plugin. El mapa restante de variables de entorno del núcleo
ahora es solo para proveedores no plugin/del núcleo y algunos casos de precedencia genérica
como la incorporación de Anthropic priorizando la API key.
- Los plugins de proveedor también pueden encargarse del comportamiento de runtime del proveedor mediante
- Los manifiestos de proveedores pueden declarar `providerAuthEnvVars` y
`providerAuthAliases` para que las sondas genéricas de autenticación basadas en variables de entorno y las variantes de proveedores
no necesiten cargar el tiempo de ejecución del plugin. El mapa restante de variables de entorno del núcleo ahora
es solo para proveedores no basados en plugins/del núcleo y unos pocos casos de precedencia genérica
como la incorporación con prioridad de clave API de Anthropic.
- Los plugins de proveedores también pueden encargarse del comportamiento en tiempo de ejecución del proveedor mediante
`normalizeModelId`, `normalizeTransport`, `normalizeConfig`,
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
`resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
@ -50,200 +51,200 @@ Para las reglas de selección de modelos, consulta [/concepts/models](/es/concep
`isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`,
`augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`,
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`,
`prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, y
`prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and
`onModelSelected`.
- Nota: `capabilities` del runtime del proveedor son metadatos compartidos del ejecutor (familia del proveedor,
peculiaridades de transcripción/herramientas, sugerencias de transporte/caché). No es lo
mismo que el [modelo de capacidades público](/es/plugins/architecture#public-capability-model)
- Nota: `capabilities` del tiempo de ejecución del proveedor son metadatos compartidos del ejecutor (familia del proveedor,
particularidades de transcripción/herramientas, pistas 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.).
## Comportamiento de proveedor controlado por plugins
## Comportamiento del proveedor propiedad del plugin
Los plugins de proveedor ahora pueden encargarse de la mayor parte de la lógica específica de cada proveedor mientras OpenClaw mantiene
el bucle de inferencia genérico.
Los plugins de proveedores ahora pueden encargarse de la mayor parte de la lógica específica del proveedor mientras OpenClaw mantiene
el bucle genérico de inferencia.
División típica:
- `auth[].run` / `auth[].runNonInteractive`: el proveedor se encarga de los flujos de incorporación/inicio de sesión
para `openclaw onboard`, `openclaw models auth` y la configuración sin interfaz
- `wizard.setup` / `wizard.modelPicker`: el proveedor se encarga de las etiquetas de elección de autenticación,
alias heredados, sugerencias de listas permitidas para incorporación y entradas de configuración en los selectores de incorporación/modelo
alias heredados, pistas de lista de permitidos para incorporación y entradas de configuración en los selectores de incorporación/modelos
- `catalog`: el proveedor aparece en `models.providers`
- `normalizeModelId`: el proveedor normaliza ids de modelo heredados/de vista previa antes de
la búsqueda o canonicalización
- `normalizeTransport`: el proveedor normaliza `api` / `baseUrl` de la familia de transporte
- `normalizeModelId`: el proveedor normaliza identificadores de modelos heredados/de vista previa antes de
la búsqueda o la canonicalización
- `normalizeTransport`: el proveedor normaliza la familia de transporte `api` / `baseUrl`
antes del ensamblaje genérico del modelo; OpenClaw comprueba primero el proveedor coincidente,
luego otros plugins de proveedor con capacidad de hook hasta que uno cambie realmente el
luego otros plugins de proveedores con capacidad de hook hasta que uno realmente cambie el
transporte
- `normalizeConfig`: el proveedor normaliza la configuración `models.providers.<id>` antes de
que el runtime la use; OpenClaw comprueba primero el proveedor coincidente, luego otros
plugins de proveedor con capacidad de hook hasta que uno cambie realmente la configuración. Si ningún
hook de proveedor reescribe la configuración, los ayudantes agrupados de la familia Google siguen
normalizando las entradas de proveedor Google compatibles.
- `normalizeConfig`: el proveedor normaliza la configuración `models.providers.<id>` antes de que
el tiempo de ejecución la use; OpenClaw comprueba primero el proveedor coincidente, luego otros
plugins de proveedores con capacidad de hook hasta que uno realmente cambie la configuración. Si ningún
hook de proveedor reescribe la configuración, los ayudantes integrados de la familia Google siguen
normalizando las entradas de proveedores Google admitidas.
- `applyNativeStreamingUsageCompat`: el proveedor aplica reescrituras de compatibilidad de uso de streaming nativo impulsadas por el endpoint para proveedores configurados
- `resolveConfigApiKey`: el proveedor resuelve la autenticación con marcador de entorno para proveedores configurados
sin forzar la carga completa de la autenticación del runtime. `amazon-bedrock` también tiene un
resolvedor integrado de marcador de entorno de AWS aquí, aunque la autenticación de runtime de Bedrock usa
- `resolveConfigApiKey`: el proveedor resuelve la autenticación de marcadores de variables de entorno para proveedores configurados
sin forzar la carga completa de la autenticación en tiempo de ejecución. `amazon-bedrock` también tiene aquí un
resolvedor integrado de marcadores de variables de entorno de AWS, aunque la autenticación en tiempo de ejecución de Bedrock usa
la cadena predeterminada del SDK de AWS.
- `resolveSyntheticAuth`: el proveedor puede exponer disponibilidad de autenticación local/alojada por uno mismo u otra
autenticación basada en configuración sin persistir secretos en texto sin formato
- `resolveSyntheticAuth`: el proveedor puede exponer disponibilidad de autenticación
local/alojada por el usuario u otra basada en configuración sin persistir secretos en texto plano
- `shouldDeferSyntheticProfileAuth`: el proveedor puede marcar marcadores de posición de perfiles sintéticos almacenados
como de menor precedencia que la autenticación basada en entorno/configuración
- `resolveDynamicModel`: el proveedor acepta ids de modelo que todavía no están presentes en el
con menor precedencia que la autenticación basada en variables de entorno/configuración
- `resolveDynamicModel`: el proveedor acepta identificadores de modelos que aún no están presentes en el
catálogo estático local
- `prepareDynamicModel`: el proveedor necesita una actualización de metadatos antes de volver a intentar
- `prepareDynamicModel`: el proveedor necesita una actualización de metadatos antes de reintentar
la resolución dinámica
- `normalizeResolvedModel`: el proveedor necesita reescrituras de transporte o URL base
- `contributeResolvedModelCompat`: el proveedor aporta banderas de compatibilidad para sus
modelos del proveedor incluso cuando llegan mediante otro transporte compatible
- `capabilities`: el proveedor publica peculiaridades de transcripción/herramientas/familia de proveedor
modelos del proveedor incluso cuando llegan a través de otro transporte compatible
- `capabilities`: el proveedor publica particularidades de transcripción/herramientas/familia de proveedor
- `normalizeToolSchemas`: el proveedor limpia los esquemas de herramientas antes de que el
ejecutor integrado los vea
- `inspectToolSchemas`: el proveedor expone advertencias de esquemas específicas del transporte
- `inspectToolSchemas`: el proveedor muestra advertencias de esquemas específicas del transporte
después de la normalización
- `resolveReasoningOutputMode`: el proveedor elige contratos de salida de razonamiento
nativos frente a etiquetados
- `prepareExtraParams`: el proveedor establece valores predeterminados o normaliza parámetros de solicitud por modelo
- `createStreamFn`: el proveedor reemplaza la ruta normal de streaming por un
transporte totalmente personalizado
- `wrapStreamFn`: el proveedor aplica envoltorios de compatibilidad de encabezados/cuerpo/modelo de solicitud
- `resolveTransportTurnState`: el proveedor suministra encabezados nativos o metadatos
por turno para el transporte
- `resolveWebSocketSessionPolicy`: el proveedor suministra encabezados de sesión WebSocket nativos
o política de enfriamiento de sesión
- `createEmbeddingProvider`: el proveedor se encarga del comportamiento de embedding de memoria cuando
corresponde al plugin del proveedor en lugar del selector central de embeddings
- `formatApiKey`: el proveedor formatea perfiles de autenticación almacenados en la cadena
`apiKey` de runtime esperada por el transporte
- `refreshOAuth`: el proveedor se encarga de la actualización de OAuth cuando los actualizadores compartidos de `pi-ai`
no son suficientes
- `buildAuthDoctorHint`: el proveedor agrega orientación de reparación cuando falla la
actualización de OAuth
- `resolveReasoningOutputMode`: el proveedor elige contratos nativos o etiquetados
para la salida de razonamiento
- `prepareExtraParams`: el proveedor aplica valores predeterminados o normaliza parámetros de solicitud por modelo
- `createStreamFn`: el proveedor reemplaza la ruta normal de stream por un transporte
completamente personalizado
- `wrapStreamFn`: el proveedor aplica envoltorios de compatibilidad para encabezados/cuerpo/modelo de la solicitud
- `resolveTransportTurnState`: el proveedor suministra encabezados o metadatos
nativos de transporte por turno
- `resolveWebSocketSessionPolicy`: el proveedor suministra encabezados nativos de sesión WebSocket
o una política de enfriamiento de sesión
- `createEmbeddingProvider`: el proveedor se encarga del comportamiento de embeddings de memoria cuando
corresponde al plugin del proveedor en lugar del conmutador central de embeddings
- `formatApiKey`: el proveedor formatea los perfiles de autenticación almacenados en la cadena
`apiKey` esperada por el transporte en tiempo de ejecución
- `refreshOAuth`: el proveedor se encarga de la actualización de OAuth cuando los
actualizadores compartidos `pi-ai` no son suficientes
- `buildAuthDoctorHint`: el proveedor agrega orientación de reparación cuando falla la actualización de OAuth
- `matchesContextOverflowError`: el proveedor reconoce errores específicos del proveedor
de desbordamiento de ventana de contexto que las heurísticas genéricas pasarían por alto
- `classifyFailoverReason`: el proveedor asigna errores sin procesar específicos del proveedor del transporte/API
a motivos de failover como límite de tasa o sobrecarga
- `isCacheTtlEligible`: el proveedor decide qué ids de modelo del upstream admiten TTL de caché de prompt
por desbordamiento de ventana de contexto que las heurísticas genéricas no detectarían
- `classifyFailoverReason`: el proveedor asigna errores sin procesar específicos del proveedor de transporte/API
a motivos de failover como límite de velocidad o sobrecarga
- `isCacheTtlEligible`: el proveedor decide qué identificadores de modelos ascendentes admiten TTL de caché de prompt
- `buildMissingAuthMessage`: el proveedor reemplaza el error genérico del almacén de autenticación
por una sugerencia de recuperación específica del proveedor
- `suppressBuiltInModel`: el proveedor oculta filas obsoletas del upstream y puede devolver un
error controlado por el proveedor para fallos de resolución directa
- `augmentModelCatalog`: el proveedor agrega filas sintéticas/finales al catálogo después de
la detección y fusión de configuración
- `isBinaryThinking`: el proveedor se encarga de la UX de razonamiento binario activado/desactivado
- `supportsXHighThinking`: el proveedor habilita `xhigh` para los modelos seleccionados
por una pista de recuperación específica del proveedor
- `suppressBuiltInModel`: el proveedor oculta filas ascendentes obsoletas y puede devolver un
error propiedad del proveedor para fallos de resolución directa
- `augmentModelCatalog`: el proveedor agrega filas sintéticas/finales del catálogo después del
descubrimiento y la fusión de configuración
- `isBinaryThinking`: el proveedor se encarga de la UX binaria de activado/desactivado para thinking
- `supportsXHighThinking`: el proveedor habilita `xhigh` para modelos seleccionados
- `resolveDefaultThinkingLevel`: el proveedor se encarga de la política predeterminada de `/think` para una
familia de modelos
- `applyConfigDefaults`: el proveedor aplica valores globales predeterminados específicos del proveedor
durante la materialización de la configuración según el modo de autenticación, el entorno o la familia del modelo
- `isModernModelRef`: el proveedor se encarga de la coincidencia de modelos preferidos en vivo/smoke
- `prepareRuntimeAuth`: el proveedor convierte una credencial configurada en un token de runtime
de corta duración
- `applyConfigDefaults`: el proveedor aplica valores predeterminados globales específicos del proveedor
durante la materialización de la configuración según el modo de autenticación, el entorno o la familia de modelos
- `isModernModelRef`: el proveedor se encarga de la coincidencia de modelos preferidos para live/smoke
- `prepareRuntimeAuth`: el proveedor convierte una credencial configurada en un token
de tiempo de ejecución de corta duración
- `resolveUsageAuth`: el proveedor resuelve credenciales de uso/cuota para `/usage`
y superficies relacionadas de estado/informes
- `fetchUsageSnapshot`: el proveedor se encarga de obtener/analizar el endpoint de uso mientras
el núcleo sigue encargándose de la estructura del resumen y el formato
- `fetchUsageSnapshot`: el proveedor se encarga de la obtención/análisis del endpoint de uso mientras
el núcleo sigue encargándose de la carcasa de resumen y el formato
- `onModelSelected`: el proveedor ejecuta efectos secundarios posteriores a la selección, como
telemetría o gestión de sesión controlada por el proveedor
telemetría o mantenimiento de sesión propiedad del proveedor
Ejemplos agrupados actuales:
Ejemplos integrados actuales:
- `anthropic`: fallback de compatibilidad futura de Claude 4.6, sugerencias de reparación de autenticación, obtención de endpoint
de uso, metadatos de TTL de caché/familia de proveedor y valores globales predeterminados de configuración
conscientes de la autenticación
- `amazon-bedrock`: coincidencia de desbordamiento de contexto controlada por el proveedor y clasificación
de motivos de failover para errores específicos de Bedrock de limitación/no listo, además
de la familia compartida de repetición `anthropic-by-model` para protecciones de política de repetición exclusivas de Claude
de uso, metadatos de TTL de caché/familia de proveedor, y valores predeterminados globales
de configuración conscientes de la autenticación
- `amazon-bedrock`: coincidencia de desbordamiento de contexto propiedad del proveedor y clasificación de motivos
de failover para errores de Bedrock específicos de limitación/no listo, además de
la familia compartida de reproducción `anthropic-by-model` para protecciones de política de reproducción solo de Claude
en tráfico de Anthropic
- `anthropic-vertex`: protecciones de política de repetición exclusivas de Claude en tráfico
de mensajes de Anthropic
- `openrouter`: ids de modelo pass-through, envoltorios de solicitud, sugerencias de capacidades
del proveedor, saneamiento de firmas de pensamiento de Gemini en tráfico Gemini por proxy,
inyección de razonamiento de proxy mediante la familia de stream `openrouter-thinking`,
reenvío de metadatos de enrutamiento y política de TTL de caché
- `github-copilot`: incorporación/inicio de sesión del dispositivo, fallback de modelo de compatibilidad futura,
sugerencias de transcripción de razonamiento de Claude, intercambio de token de runtime y obtención de endpoint
de uso
- `openai`: fallback de compatibilidad futura de GPT-5.4, normalización directa del transporte de OpenAI,
sugerencias de autenticación faltante adaptadas a Codex, supresión de Spark, filas sintéticas
de catálogo OpenAI/Codex, política de razonamiento/modelos en vivo, normalización de alias
de token de uso (`input` / `output` y familias `prompt` / `completion`), la
familia compartida de stream `openai-responses-defaults` para envoltorios nativos de OpenAI/Codex,
metadatos de familia de proveedor, registro agrupado de proveedor de generación de imágenes
para `gpt-image-1` y registro agrupado de proveedor de generación de video
- `anthropic-vertex`: protecciones de política de reproducción solo de Claude en tráfico
de mensajes Anthropic
- `openrouter`: identificadores de modelo pass-through, envoltorios de solicitudes, sugerencias de capacidades
del proveedor, saneamiento de firmas de pensamiento Gemini en tráfico proxy Gemini,
inyección de razonamiento por proxy a través de la familia de stream `openrouter-thinking`, reenvío de metadatos
de enrutamiento y política de TTL de caché
- `github-copilot`: incorporación/inicio de sesión del dispositivo, fallback de compatibilidad futura de modelos,
sugerencias de transcripción de thinking de Claude, intercambio de tokens en tiempo de ejecución y obtención
de endpoint de uso
- `openai`: fallback de compatibilidad futura de GPT-5.4, normalización de transporte
directo de OpenAI, sugerencias de autenticación faltante conscientes de Codex, supresión de Spark, filas
sintéticas del catálogo OpenAI/Codex, política de thinking/modelos live, normalización de alias de tokens
de uso (`input` / `output` y familias `prompt` / `completion`), la familia compartida de stream
`openai-responses-defaults` para envoltorios nativos de OpenAI/Codex,
metadatos de familia del proveedor, registro integrado del proveedor de generación de imágenes
para `gpt-image-1`, y registro integrado del proveedor de generación de video
para `sora-2`
- `google` y `google-gemini-cli`: fallback de compatibilidad futura de Gemini 3.1,
validación nativa de repetición de Gemini, saneamiento de repetición de bootstrap, modo
de salida de razonamiento etiquetado, coincidencia de modelos modernos, registro agrupado de proveedor de generación de imágenes
para modelos Gemini image-preview y registro agrupado
de proveedor de generación de video para modelos Veo; Gemini CLI OAuth también
se encarga del formato de token de perfiles de autenticación, del análisis de token de uso y de la obtención
de endpoint de cuota para superficies de uso
- `moonshot`: transporte compartido, normalización de payload de razonamiento controlada por plugin
- `kilocode`: transporte compartido, encabezados de solicitud controlados por plugin, normalización del payload de razonamiento,
saneamiento de firmas de pensamiento de Gemini por proxy y política de TTL de caché
validación nativa de reproducción de Gemini, saneamiento de reproducción en bootstrap, modo etiquetado
de salida de razonamiento, coincidencia de modelos modernos, registro integrado del proveedor de generación de imágenes
para modelos Gemini image-preview, y registro integrado
del proveedor de generación de video para modelos Veo; Gemini CLI OAuth también
se encarga del formateo de tokens de perfiles de autenticación, análisis de tokens de uso y
obtención del endpoint de cuota para superficies de uso
- `moonshot`: transporte compartido, normalización de payload de thinking propiedad del plugin
- `kilocode`: transporte compartido, encabezados de solicitud propiedad del plugin, normalización de payload
de razonamiento, saneamiento de firmas de pensamiento de Gemini por proxy y política
de TTL de caché
- `zai`: fallback de compatibilidad futura de GLM-5, valores predeterminados de `tool_stream`, política de TTL de caché,
política de razonamiento binario/modelos en vivo y autenticación de uso + obtención de cuota;
ids desconocidos `glm-5*` se sintetizan a partir de la plantilla agrupada `glm-4.7`
política binaria de thinking/modelos live, y autenticación de uso + obtención de cuota;
los identificadores desconocidos `glm-5*` se sintetizan a partir de la plantilla integrada `glm-4.7`
- `xai`: normalización nativa del transporte Responses, reescrituras de alias `/fast` para
variantes rápidas de Grok, valor predeterminado de `tool_stream`, limpieza de esquemas de herramientas /
payload de razonamiento específica de xAI y registro agrupado de proveedor de generación de video
variantes rápidas de Grok, `tool_stream` predeterminado, limpieza específica de xAI de esquemas de herramientas /
payload de razonamiento, y registro integrado del proveedor de generación de video
para `grok-imagine-video`
- `mistral`: metadatos de capacidades controlados por plugin
- `opencode` y `opencode-go`: metadatos de capacidades controlados por plugin más
saneamiento de firmas de pensamiento de Gemini por proxy
- `alibaba`: catálogo de generación de video controlado por plugin para referencias directas a modelos Wan
- `mistral`: metadatos de capacidades propiedad del plugin
- `opencode` y `opencode-go`: metadatos de capacidades propiedad del plugin más saneamiento
de firmas de pensamiento Gemini por proxy
- `alibaba`: catálogo de generación de video propiedad del plugin para referencias directas de modelos Wan
como `alibaba/wan2.6-t2v`
- `byteplus`: catálogos controlados por plugin más registro agrupado de proveedor de generación de video
- `byteplus`: catálogos propiedad del plugin más registro integrado del proveedor de generación de video
para modelos Seedance de texto a video/imagen a video
- `fal`: registro agrupado de proveedor de generación de video para terceros alojados
registro agrupado de proveedor de generación de imágenes para modelos de imagen FLUX más registro agrupado
de proveedor de generación de video para modelos de video de terceros alojados
- `fal`: registro integrado del proveedor de generación de video para proveedores de terceros alojados y
registro del proveedor de generación de imágenes para modelos de imagen FLUX, además de registro integrado
del proveedor de generación de video para modelos de video de terceros alojados
- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`,
`stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` y `volcengine`:
solo catálogos controlados por plugin
- `qwen`: catálogos controlados por plugin para modelos de texto más registros compartidos
`stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, y `volcengine`:
solo catálogos propiedad del plugin
- `qwen`: catálogos propiedad del plugin para modelos de texto más registros compartidos
de proveedores de comprensión multimedia y generación de video para sus
superficies multimodales; la generación de video de Qwen usa los endpoints de video DashScope Standard
con modelos Wan agrupados como `wan2.6-t2v` y `wan2.7-r2v`
- `runway`: registro de proveedor de generación de video controlado por plugin para modelos nativos
basados en tareas de Runway como `gen4.5`
- `minimax`: catálogos controlados por plugin, registro agrupado de proveedor de generación de video
para modelos de video Hailuo, registro agrupado de proveedor de generación de imágenes
para `image-01`, selección híbrida de política de repetición Anthropic/OpenAI
y lógica de autenticación/instantánea de uso
- `together`: catálogos controlados por plugin más registro agrupado de proveedor de generación de video
superficies multimodales; la generación de video de Qwen usa los endpoints de video Standard DashScope
con modelos Wan integrados como `wan2.6-t2v` y `wan2.7-r2v`
- `runway`: registro de proveedor de generación de video propiedad del plugin para modelos
nativos de Runway basados en tareas como `gen4.5`
- `minimax`: catálogos propiedad del plugin, registro integrado del proveedor de generación de video
para modelos de video Hailuo, registro integrado del proveedor de generación de imágenes
para `image-01`, selección híbrida de política de reproducción Anthropic/OpenAI,
y lógica de autenticación/snapshot de uso
- `together`: catálogos propiedad del plugin más registro integrado del proveedor de generación de video
para modelos de video Wan
- `xiaomi`: catálogos controlados por plugin más lógica de autenticación/instantánea de uso
- `xiaomi`: catálogos propiedad del plugin más lógica de autenticación/snapshot de uso
El plugin agrupado `openai` ahora se encarga de ambos ids de proveedor: `openai` y
El plugin integrado `openai` ahora se encarga de ambos identificadores de proveedor: `openai` y
`openai-codex`.
Eso cubre los proveedores que aún encajan en los transportes normales de OpenClaw. Un proveedor
que necesita un ejecutor de solicitudes totalmente personalizado es una superficie de extensión
Eso cubre los proveedores que todavía encajan en los transportes normales de OpenClaw. Un proveedor
que necesita un ejecutor de solicitudes completamente personalizado es una superficie de extensión
separada y más profunda.
## Rotación de API keys
## Rotación de claves API
- Admite rotación genérica del proveedor para proveedores seleccionados.
- Admite rotación genérica de proveedores para proveedores seleccionados.
- Configura varias claves mediante:
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (anulación única en vivo, máxima prioridad)
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (anulación única live, máxima prioridad)
- `<PROVIDER>_API_KEYS` (lista separada por comas o punto y coma)
- `<PROVIDER>_API_KEY` (clave principal)
- `<PROVIDER>_API_KEY_*` (lista numerada, por ejemplo `<PROVIDER>_API_KEY_1`)
- `<PROVIDER>_API_KEY_*` (lista numerada, p. ej. `<PROVIDER>_API_KEY_1`)
- Para los proveedores de Google, `GOOGLE_API_KEY` también se incluye como fallback.
- El orden de selección de claves preserva la prioridad y elimina duplicados.
- Las solicitudes se reintentan con la siguiente clave solo en respuestas de límite de tasa (por
- Las solicitudes se reintentan con la siguiente clave solo ante respuestas de límite de velocidad (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 de límite de tasa fallan inmediatamente; no se intenta rotación de claves.
- Cuando fallan todas las claves candidatas, se devuelve el error final del último intento.
`workers_ai ... quota limit exceeded`, o mensajes periódicos de límite de uso).
- Los fallos que no son de límite de velocidad fallan inmediatamente; no se intenta rotación de claves.
- Cuando todas las claves candidatas fallan, 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 `models.providers`; solo configura la autenticación y elige un modelo.
OpenClaw incluye el catálogo pi‑ai. Estos proveedores no requieren configuración de
`models.providers`; solo configura la autenticación y elige un modelo.
### OpenAI
@ -252,18 +253,18 @@ configuración `models.providers`; solo configura la autenticación y elige un m
- Rotación opcional: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, además de `OPENCLAW_LIVE_OPENAI_KEY` (anulación única)
- Modelos de ejemplo: `openai/gpt-5.4`, `openai/gpt-5.4-pro`
- CLI: `openclaw onboard --auth-choice openai-api-key`
- El transporte predeterminado es `auto` (primero WebSocket, fallback a SSE)
- Anulación por modelo mediante `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` o `"auto"`)
- El precalentamiento de WebSocket de OpenAI Responses está habilitado de forma predeterminada mediante `params.openaiWsWarmup` (`true`/`false`)
- El transporte predeterminado es `auto` (WebSocket primero, fallback a SSE)
- Anula por modelo mediante `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"`, o `"auto"`)
- El calentamiento de WebSocket de OpenAI Responses está habilitado de forma predeterminada mediante `params.openaiWsWarmup` (`true`/`false`)
- El procesamiento prioritario de OpenAI puede habilitarse mediante `agents.defaults.models["openai/<model>"].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 selector compartido `/fast`
- `/fast` y `params.fastMode` asignan las 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 conmutador compartido `/fast`
- Los encabezados de atribución ocultos de OpenClaw (`originator`, `version`,
`User-Agent`) se aplican solo en tráfico nativo de OpenAI hacia `api.openai.com`, no
en proxies genéricos compatibles con OpenAI
- Las rutas nativas de OpenAI también mantienen `store` de Responses, sugerencias de caché de prompt y
conformación de payload de compatibilidad de razonamiento de OpenAI; las rutas por proxy no
- `openai/gpt-5.3-codex-spark` está intencionalmente suprimido en OpenClaw porque la API en vivo de OpenAI lo rechaza; Spark se trata solo como Codex
modelado de payload de compatibilidad de razonamiento de OpenAI; las rutas proxy no
- `openai/gpt-5.3-codex-spark` se suprime intencionalmente en OpenClaw porque la API live de OpenAI lo rechaza; Spark se trata solo como Codex
```json5
{
@ -278,9 +279,9 @@ configuración `models.providers`; solo configura la autenticación y elige un m
- Rotación opcional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, además de `OPENCLAW_LIVE_ANTHROPIC_KEY` (anulación única)
- Modelo de ejemplo: `anthropic/claude-opus-4-6`
- CLI: `openclaw onboard --auth-choice apiKey`
- Las solicitudes públicas directas de Anthropic admiten el selector compartido `/fast` y `params.fastMode`, incluido el tráfico autenticado con API key y OAuth enviado a `api.anthropic.com`; OpenClaw lo asigna a Anthropic `service_tier` (`auto` frente a `standard_only`)
- Nota sobre Anthropic: el personal de Anthropic nos dijo que el uso estilo Claude CLI de OpenClaw vuelve a estar permitido, por lo que OpenClaw considera autorizados para esta integración tanto la reutilización de Claude CLI como el uso de `claude -p`, salvo que Anthropic publique una nueva política.
- El token de configuración de Anthropic sigue disponible como ruta de token compatible con OpenClaw, pero OpenClaw ahora prefiere la reutilización de Claude CLI y `claude -p` cuando están disponibles.
- Las solicitudes directas a Anthropic público admiten el conmutador compartido `/fast` y `params.fastMode`, incluido el tráfico autenticado con clave API y OAuth enviado a `api.anthropic.com`; OpenClaw lo asigna a Anthropic `service_tier` (`auto` vs `standard_only`)
- Nota de Anthropic: el personal de Anthropic nos dijo que el uso al estilo Claude CLI de 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, a menos que Anthropic publique una política nueva.
- El token de configuración de Anthropic sigue disponible como ruta de token admitida por OpenClaw, pero OpenClaw ahora prefiere reutilizar Claude CLI y `claude -p` cuando están disponibles.
```json5
{
@ -294,16 +295,16 @@ configuración `models.providers`; solo configura la autenticación y elige un m
- Autenticación: OAuth (ChatGPT)
- Modelo de ejemplo: `openai-codex/gpt-5.4`
- 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)
- Anulación por modelo mediante `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` o `"auto"`)
- El transporte predeterminado es `auto` (WebSocket primero, fallback a SSE)
- Anula por modelo mediante `agents.defaults.models["openai-codex/<model>"].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 de atribución ocultos 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 selector `/fast` y la misma configuración `params.fastMode` que `openai/*` directo; OpenClaw lo asigna a `service_tier=priority`
- Comparte el mismo conmutador `/fast` y la misma configuración `params.fastMode` que `openai/*` directo; OpenClaw lo asigna a `service_tier=priority`
- `openai-codex/gpt-5.3-codex-spark` sigue disponible cuando el catálogo OAuth de Codex lo expone; depende de la autorización
- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo y un `contextTokens = 272000` de runtime predeterminado; anula el límite de runtime 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.
- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo y un `contextTokens = 272000` de tiempo de ejecución predeterminado; 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 con herramientas/flujos de trabajo externos como OpenClaw.
```json5
{
@ -326,14 +327,14 @@ configuración `models.providers`; solo configura la autenticación y elige un m
### 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 API key a MiniMax Coding Plan
- [GLM Models](/es/providers/glm): endpoints de Z.AI Coding Plan o API general
- [MiniMax](/es/providers/minimax): acceso por OAuth o clave API de MiniMax Coding Plan
- [GLM Models](/es/providers/glm): Z.AI Coding Plan o endpoints generales de API
### OpenCode
- Autenticación: `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`)
- Proveedor de runtime Zen: `opencode`
- Proveedor de runtime Go: `opencode-go`
- Proveedor de tiempo de ejecución Zen: `opencode`
- Proveedor de tiempo de ejecución Go: `opencode-go`
- Modelos de ejemplo: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5`
- CLI: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`
@ -343,35 +344,35 @@ configuración `models.providers`; solo configura la autenticación y elige un m
}
```
### Google Gemini (API key)
### Google Gemini (clave API)
- Proveedor: `google`
- Autenticación: `GEMINI_API_KEY`
- Rotación opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `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 a `GOOGLE_API_KEY`, y `OPENCLAW_LIVE_GEMINI_KEY` (anulación única)
- 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/<model>"].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
`cachedContents/...`; los aciertos de caché de Gemini aparecen 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 OAuth
- Precaución: Gemini CLI OAuth 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 las condiciones de Google y usa una cuenta no crítica si decides continuar.
- Gemini CLI OAuth se distribuye como parte del plugin agrupado `google`.
- Instala Gemini CLI primero:
- Precaución: Gemini CLI OAuth en OpenClaw es una integración no oficial. Algunos usuarios han informado de restricciones en sus cuentas de Google después de usar clientes de terceros. Revisa las condiciones de Google y usa una cuenta no crítica si decides continuar.
- Gemini CLI OAuth se distribuye como parte del plugin integrado `google`.
- 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** pegues un client id ni un secret en `openclaw.json`. El flujo de inicio de sesión de la CLI almacena
- Nota: **no** pegas un client id ni un secreto en `openclaw.json`. El flujo de inicio de sesión de CLI almacena
tokens en perfiles de autenticación en el host de la gateway.
- Si las solicitudes fallan después de iniciar sesión, configura `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host de la gateway.
- Las respuestas JSON de Gemini CLI se analizan desde `response`; el uso recurre a
`stats`, con `stats.cached` normalizado a `cacheRead` de OpenClaw.
`stats`, con `stats.cached` normalizado en `cacheRead` de OpenClaw.
### Z.AI (GLM)
@ -380,7 +381,7 @@ configuración `models.providers`; solo configura la autenticación y elige un m
- Modelo de ejemplo: `zai/glm-5.1`
- CLI: `openclaw onboard --auth-choice zai-api-key`
- Alias: `z.ai/*` y `z-ai/*` se normalizan a `zai/*`
- `zai-api-key` detecta automáticamente el endpoint de Z.AI coincidente; `zai-coding-global`, `zai-coding-cn`, `zai-global` y `zai-cn` fuerzan una superficie específica
- `zai-api-key` detecta automáticamente el endpoint Z.AI coincidente; `zai-coding-global`, `zai-coding-cn`, `zai-global` y `zai-cn` fuerzan una superficie específica
### Vercel AI Gateway
@ -396,44 +397,45 @@ configuración `models.providers`; solo configura la autenticación y elige un m
- 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 en vivo en
- El catálogo estático de fallback incluye `kilocode/kilo/auto`; el descubrimiento live en
`https://api.kilo.ai/api/gateway/models` puede ampliar aún más el catálogo
de runtime.
- El enrutamiento exacto del upstream detrás de `kilocode/kilo/auto` es responsabilidad de Kilo Gateway,
no está codificado de forma rígida en OpenClaw.
en tiempo de ejecución.
- El enrutamiento ascendente exacto detrás de `kilocode/kilo/auto` es propiedad de Kilo Gateway,
no está codificado de forma fija en OpenClaw.
Consulta [/providers/kilocode](/es/providers/kilocode) para los detalles de configuración.
Consulta [/providers/kilocode](/es/providers/kilocode) para obtener detalles de configuración.
### Otros plugins de proveedor agrupados
### Otros plugins integrados de proveedores
- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
- Modelo de ejemplo: `openrouter/auto`
- OpenClaw aplica los encabezados documentados de atribución de aplicación de OpenRouter solo cuando
- OpenClaw aplica los encabezados de atribución de aplicación documentados por OpenRouter solo cuando
la solicitud realmente apunta a `openrouter.ai`
- Los marcadores `cache_control` específicos de Anthropic para OpenRouter también están restringidos a
rutas OpenRouter verificadas, no a URLs arbitrarias de proxy
- OpenRouter permanece en la ruta de estilo proxy compatible con OpenAI, por lo que la conformación de solicitudes solo nativa de OpenAI (`serviceTier`, `store` de Responses,
- Los marcadores `cache_control` específicos de Anthropic de OpenRouter también están restringidos a
rutas OpenRouter verificadas, no a URL proxy arbitrarias
- OpenRouter sigue en la ruta de estilo proxy compatible con OpenAI, por lo que el modelado nativo
de solicitudes exclusivo de OpenAI (`serviceTier`, `store` de Responses,
sugerencias de caché de prompt, payloads de compatibilidad de razonamiento de OpenAI) no se reenvía
- Las referencias de OpenRouter respaldadas por Gemini solo mantienen el saneamiento de firmas de pensamiento de Gemini por proxy;
la validación nativa de repetición de Gemini y las reescrituras de bootstrap permanecen desactivadas
- Las referencias OpenRouter respaldadas por Gemini mantienen solo el saneamiento de firmas de pensamiento Gemini por proxy;
la validación nativa de reproducción de Gemini y las reescrituras de bootstrap siguen desactivadas
- Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`)
- Modelo de ejemplo: `kilocode/kilo/auto`
- Las referencias de Kilo respaldadas por Gemini mantienen la misma ruta de saneamiento
de firmas de pensamiento de Gemini por proxy; `kilocode/kilo/auto` y otras sugerencias
de razonamiento por proxy no compatible omiten la inyección de razonamiento por proxy
- MiniMax: `minimax` (API key) y `minimax-portal` (OAuth)
de firmas de pensamiento Gemini por proxy; `kilocode/kilo/auto` y otras
sugerencias no admitidas de razonamiento por proxy omiten la inyección de razonamiento por proxy
- MiniMax: `minimax` (clave API) y `minimax-portal` (OAuth)
- Autenticación: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` para `minimax-portal`
- Modelo de ejemplo: `minimax/MiniMax-M2.7` o `minimax-portal/MiniMax-M2.7`
- La incorporación/configuración con API key de MiniMax escribe definiciones explícitas del modelo M2.7 con
`input: ["text", "image"]`; el catálogo agrupado del proveedor mantiene las referencias de chat
solo texto hasta que se materializa la configuración de ese proveedor
- La incorporación/configuración con clave API de MiniMax escribe definiciones explícitas del modelo M2.7 con
`input: ["text", "image"]`; el catálogo integrado del proveedor mantiene las referencias de chat
solo de texto hasta que se materializa esa configuración del proveedor
- Moonshot: `moonshot` (`MOONSHOT_API_KEY`)
- Modelo de ejemplo: `moonshot/kimi-k2.5`
- Kimi Coding: `kimi` (`KIMI_API_KEY` o `KIMICODE_API_KEY`)
- Modelo de ejemplo: `kimi/kimi-code`
- Qianfan: `qianfan` (`QIANFAN_API_KEY`)
- Modelo de ejemplo: `qianfan/deepseek-v3.2`
- Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY` o `DASHSCOPE_API_KEY`)
- Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, o `DASHSCOPE_API_KEY`)
- Modelo de ejemplo: `qwen/qwen3.5-plus`
- NVIDIA: `nvidia` (`NVIDIA_API_KEY`)
- Modelo de ejemplo: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct`
@ -452,9 +454,9 @@ Consulta [/providers/kilocode](/es/providers/kilocode) para los detalles de conf
- BytePlus: `byteplus` (`BYTEPLUS_API_KEY`)
- Modelo de ejemplo: `byteplus-plan/ark-code-latest`
- xAI: `xai` (`XAI_API_KEY`)
- Las solicitudes nativas agrupadas de xAI usan la ruta xAI Responses
- Las solicitudes xAI nativas integradas usan la ruta xAI Responses
- `/fast` o `params.fastMode: true` reescriben `grok-3`, `grok-3-mini`,
`grok-4` y `grok-4-0709` a sus variantes `*-fast`
`grok-4`, y `grok-4-0709` a sus variantes `*-fast`
- `tool_stream` está activado de forma predeterminada; configura
`agents.defaults.models["xai/<model>"].params.tool_stream` en `false` para
desactivarlo
@ -463,24 +465,24 @@ Consulta [/providers/kilocode](/es/providers/kilocode) para los detalles de conf
- CLI: `openclaw onboard --auth-choice mistral-api-key`
- Groq: `groq` (`GROQ_API_KEY`)
- Cerebras: `cerebras` (`CEREBRAS_API_KEY`)
- Los modelos GLM en Cerebras usan los ids `zai-glm-4.7` y `zai-glm-4.6`.
- Los modelos GLM en Cerebras usan los identificadores `zai-glm-4.7` y `zai-glm-4.6`.
- URL base compatible con OpenAI: `https://api.cerebras.ai/v1`.
- GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`)
- Modelo de ejemplo de Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Consulta [Hugging Face (Inference)](/es/providers/huggingface).
## Proveedores mediante `models.providers` (personalizado/URL base)
## Proveedores mediante `models.providers` (personalizados/URL base)
Usa `models.providers` (o `models.json`) para agregar proveedores **personalizados** o
proxies compatibles con OpenAI/Anthropic.
Muchos de los plugins de proveedor agrupados a continuación ya publican un catálogo predeterminado.
Usa entradas explícitas `models.providers.<id>` solo cuando quieras anular la
Muchos de los plugins integrados de proveedores a continuación ya publican un catálogo predeterminado.
Usa entradas explícitas de `models.providers.<id>` 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 agrupado. Usa el proveedor integrado de
forma predeterminada y agrega una entrada explícita `models.providers.moonshot` solo cuando
Moonshot se distribuye como un plugin integrado de proveedor. Usa el proveedor integrado de forma
predeterminada y agrega una entrada explícita `models.providers.moonshot` solo cuando
necesites anular la URL base o los metadatos del modelo:
- Proveedor: `moonshot`
@ -488,7 +490,7 @@ necesites anular la URL base o los metadatos del modelo:
- Modelo de ejemplo: `moonshot/kimi-k2.5`
- CLI: `openclaw onboard --auth-choice moonshot-api-key` o `openclaw onboard --auth-choice moonshot-api-key-cn`
Ids de modelo Kimi K2:
Identificadores de modelo Kimi K2:
[//]: # "moonshot-kimi-k2-model-refs:start"
@ -535,7 +537,7 @@ Kimi Coding usa el endpoint compatible con Anthropic de Moonshot AI:
}
```
El heredado `kimi/k2p5` sigue aceptándose como id de modelo de compatibilidad.
El heredado `kimi/k2p5` sigue aceptándose como identificador de modelo de compatibilidad.
### Volcano Engine (Doubao)
@ -554,13 +556,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/*`
La incorporación usa por defecto la superficie de coding, pero el catálogo general `volcengine/*`
se registra al mismo tiempo.
En los selectores de modelos de incorporación/configuración, la opción de autenticación de Volcengine prefiere tanto las filas
`volcengine/*` como `volcengine-plan/*`. Si esos modelos aún no se han cargado,
En los selectores de incorporación/configuración de modelos, la opción de autenticación de Volcengine prefiere tanto
las filas `volcengine/*` como `volcengine-plan/*`. Si esos modelos aún no se han cargado,
OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector
vacío limitado al proveedor.
de ámbito de proveedor vacío.
Modelos disponibles:
@ -578,7 +580,7 @@ Modelos de coding (`volcengine-plan`):
- `volcengine-plan/kimi-k2-thinking`
- `volcengine-plan/glm-4.7`
### BytePlus (Internacional)
### BytePlus (internacional)
BytePlus ARK proporciona acceso a los mismos modelos que Volcano Engine para usuarios internacionales.
@ -595,13 +597,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/*`
La incorporación usa por defecto la superficie de coding, pero el catálogo general `byteplus/*`
se registra al mismo tiempo.
En los selectores de modelos de incorporación/configuración, la opción de autenticación de BytePlus prefiere tanto las filas
`byteplus/*` como `byteplus-plan/*`. Si esos modelos aún no se han cargado,
En los selectores de incorporación/configuración de modelos, la opción de autenticación de BytePlus prefiere tanto
las filas `byteplus/*` como `byteplus-plan/*`. Si esos modelos aún no se han cargado,
OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector
vacío limitado al proveedor.
de ámbito de proveedor vacío.
Modelos disponibles:
@ -649,29 +651,29 @@ Synthetic proporciona modelos compatibles con Anthropic detrás del proveedor `s
MiniMax se configura mediante `models.providers` porque usa endpoints personalizados:
- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth`
- MiniMax OAuth (global): `--auth-choice minimax-global-oauth`
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
- MiniMax API key (Global): `--auth-choice minimax-global-api`
- MiniMax API key (CN): `--auth-choice minimax-cn-api`
- Clave API de MiniMax (global): `--auth-choice minimax-global-api`
- Clave 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`
Consulta [/providers/minimax](/es/providers/minimax) para detalles de configuración, opciones de modelo y fragmentos de configuración.
Consulta [/providers/minimax](/es/providers/minimax) para obtener detalles de configuración, opciones de modelo y fragmentos de configuración.
En la ruta de streaming compatible con Anthropic de MiniMax, OpenClaw desactiva el razonamiento de
forma predeterminada a menos que lo configures explícitamente, y `/fast on` reescribe
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`.
División de capacidades controlada por plugins:
División de capacidades propiedad del plugin:
- Los valores predeterminados de texto/chat permanecen en `minimax/MiniMax-M2.7`
- Los valores predeterminados de texto/chat siguen en `minimax/MiniMax-M2.7`
- La generación de imágenes es `minimax/image-01` o `minimax-portal/image-01`
- 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`
- La comprensión de imágenes es `MiniMax-VL-01` propiedad del plugin en ambas rutas de autenticación de MiniMax
- La búsqueda web permanece en el identificador de proveedor `minimax`
### Ollama
Ollama se incluye como plugin de proveedor agrupado y usa la API nativa de Ollama:
Ollama se distribuye como un plugin integrado de proveedor y usa la API nativa de Ollama:
- Proveedor: `ollama`
- Autenticación: no se requiere (servidor local)
@ -691,27 +693,27 @@ ollama pull llama3.3
}
```
Ollama se detecta localmente en `http://127.0.0.1:11434` cuando activas la opción con
`OLLAMA_API_KEY`, y el plugin de proveedor agrupado añade Ollama directamente a
Ollama se detecta localmente en `http://127.0.0.1:11434` cuando participas mediante
`OLLAMA_API_KEY`, y el plugin integrado del proveedor agrega Ollama directamente a
`openclaw onboard` y al selector de modelos. Consulta [/providers/ollama](/es/providers/ollama)
para la incorporación, el modo en la nube/local y la configuración personalizada.
para incorporación, modo local/en la nube y configuración personalizada.
### vLLM
vLLM se incluye como plugin de proveedor agrupado para servidores
compatibles con OpenAI locales/alojados por uno mismo:
vLLM se distribuye como un plugin integrado de proveedor para servidores
compatibles con OpenAI locales/alojados por el usuario:
- Proveedor: `vllm`
- Autenticación: opcional (depende de tu servidor)
- URL base predeterminada: `http://127.0.0.1:8000/v1`
Para activar la detección automática localmente (cualquier valor sirve si tu servidor no exige autenticación):
Para participar en 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 (sustitúyelo por uno de los identificadores devueltos por `/v1/models`):
```json5
{
@ -725,21 +727,21 @@ Consulta [/providers/vllm](/es/providers/vllm) para más detalles.
### SGLang
SGLang se incluye como plugin de proveedor agrupado para servidores
compatibles con OpenAI autoalojados de alto rendimiento:
SGLang se distribuye como un plugin integrado de proveedor para servidores
compatibles con OpenAI autohospedados y rápidos:
- Proveedor: `sglang`
- Autenticación: opcional (depende de tu servidor)
- URL base predeterminada: `http://127.0.0.1:30000/v1`
Para activar la detección automática localmente (cualquier valor sirve si tu servidor no
Para participar en 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 (sustitúyelo por uno de los identificadores devueltos por `/v1/models`):
```json5
{
@ -788,7 +790,7 @@ Ejemplo (compatible con OpenAI):
Notas:
- Para proveedores personalizados, `reasoning`, `input`, `cost`, `contextWindow` y `maxTokens` son opcionales.
- Para proveedores personalizados, `reasoning`, `input`, `cost`, `contextWindow`, y `maxTokens` son opcionales.
Cuando se omiten, OpenClaw usa estos valores predeterminados:
- `reasoning: false`
- `input: ["text"]`
@ -797,14 +799,14 @@ Notas:
- `maxTokens: 8192`
- Recomendado: 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 de estilo proxy compatibles con OpenAI también omiten la conformación de solicitudes solo nativa de OpenAI:
no `service_tier`, no `store` de Responses, no sugerencias de caché de prompt, no
conformación de payload de compatibilidad de razonamiento de OpenAI y no encabezados
ocultos de atribución de OpenClaw.
- Si `baseUrl` está vacío o se omite, OpenClaw mantiene el comportamiento predeterminado de OpenAI (que resuelve a `api.openai.com`).
- Por seguridad, un `compat.supportsDeveloperRole: true` explícito sigue siendo reemplazado en endpoints no nativos de `openai-completions`.
- Las rutas proxy de estilo compatible con OpenAI también omiten el modelado nativo de solicitudes exclusivo de OpenAI:
no hay `service_tier`, no hay `store` de Responses, no hay sugerencias de caché de prompt, no hay
modelado de payload de compatibilidad de razonamiento de OpenAI y no hay encabezados ocultos
de atribución de OpenClaw.
- Si `baseUrl` está vacío/se omite, OpenClaw mantiene el comportamiento predeterminado de OpenAI (que se resuelve en `api.openai.com`).
- Por seguridad, una opción explícita `compat.supportsDeveloperRole: true` sigue siendo anulada en endpoints no nativos `openai-completions`.
## Ejemplos de la CLI
## Ejemplos de CLI
```bash
openclaw onboard --auth-choice opencode-zen
@ -812,7 +814,7 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
Consulta también: [/gateway/configuration](/es/gateway/configuration) para ejemplos completos de configuración.
Consulta también: [/gateway/configuration](/es/gateway/configuration) para ver ejemplos completos de configuración.
## Relacionado

93
docs/es/concepts/qa-e2e-automation.md
View File

@ -2,50 +2,50 @@
read_when:
- Ampliar qa-lab o qa-channel
- Agregar escenarios de QA respaldados por el repositorio
- Crear una automatización de QA con mayor realismo alrededor del panel del Gateway
- Crear automatización de QA de mayor realismo alrededor del panel del Gateway
summary: Estructura de automatización de QA privada para qa-lab, qa-channel, escenarios sembrados e informes de protocolo
title: Automatización E2E de QA
x-i18n:
generated_at: "2026-04-08T05:02:50Z"
generated_at: "2026-04-09T01:27:42Z"
model: gpt-5.4
provider: openai
source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99
source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# Automatización E2E de QA
La pila de QA privada está pensada para ejercitar OpenClaw de una forma más realista,
La pila de QA privada está pensada para ejercitar OpenClaw de una manera más realista,
con forma de canal, de lo que puede hacerlo una sola prueba unitaria.
Partes actuales:
- `extensions/qa-channel`: canal de mensajes sintético con superficies de DM, canal, hilo,
- `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo,
reacción, edición y eliminación.
- `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción,
inyectar mensajes entrantes y exportar un informe en Markdown.
- `qa/`: recursos semilla respaldados por el repositorio para la tarea inicial y los
escenarios de QA de referencia.
escenarios base de QA.
El flujo actual del operador de QA es un sitio de QA de dos paneles:
- Izquierda: panel del Gateway (Control UI) con el agente.
- Derecha: QA Lab, que muestra la transcripción tipo Slack y el plan del escenario.
Ejecútalo con:
Ejecuta esto con:
```bash
pnpm qa:lab:up
```
Eso compila el sitio de QA, inicia la vía del gateway respaldada por Docker y expone la
página de QA Lab donde un operador o un bucle de automatización puede darle al agente una
Eso compila el sitio de QA, inicia la ruta del gateway respaldada por Docker y expone la
página de QA Lab donde un operador o un bucle de automatización puede dar al agente una
misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o
qué siguió bloqueado.
Para una iteración más rápida de la interfaz de QA Lab sin reconstruir la imagen de Docker cada vez,
inicia la pila con un paquete de QA Lab montado mediante bind mount:
Para iterar más rápido en la UI de QA Lab sin reconstruir la imagen de Docker cada vez,
inicia la pila con un paquete de QA Lab montado mediante bind:
```bash
pnpm openclaw qa docker-build-image
@ -54,7 +54,7 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta mediante bind mount
`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta mediante bind
`extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch`
recompila ese paquete cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash
de recursos de QA Lab.
@ -67,21 +67,21 @@ Los recursos semilla viven en `qa/`:
- `qa/scenarios/*.md`
Estos están intencionalmente en git para que el plan de QA sea visible tanto para las personas como para el
agente. La lista de referencia debe seguir siendo lo bastante amplia como para cubrir:
agente. La lista base debe seguir siendo lo bastante amplia como para cubrir:
- chat de DM y de canal
- chat por MD y por canal
- comportamiento de hilos
- ciclo de vida de las acciones de mensajes
- ciclo de vida de acciones de mensajes
- callbacks de cron
- recuperación de memoria
- cambio de modelo
- transferencia a subagentes
- transferencia a subagente
- lectura del repositorio y de la documentación
- una pequeña tarea de compilación como Lobster Invaders
## Informes
`qa-lab` exporta un informe de protocolo en Markdown a partir de la línea temporal del bus observado.
`qa-lab` exporta un informe de protocolo en Markdown a partir de la línea de tiempo observada del bus.
El informe debe responder:
- Qué funcionó
@ -89,8 +89,61 @@ El informe debe responder:
- Qué siguió bloqueado
- Qué escenarios de seguimiento vale la pena agregar
Para comprobaciones de carácter y estilo, ejecuta el mismo escenario en múltiples refs de modelos en vivo
y escribe un informe en Markdown evaluado:
```bash
pnpm openclaw qa character-eval \
--model openai/gpt-5.4,thinking=xhigh \
--model openai/gpt-5.2,thinking=xhigh \
--model openai/gpt-5,thinking=xhigh \
--model anthropic/claude-opus-4-6,thinking=high \
--model anthropic/claude-sonnet-4-6,thinking=high \
--model zai/glm-5.1,thinking=high \
--model moonshot/kimi-k2.5,thinking=high \
--model google/gemini-3.1-pro-preview,thinking=high \
--judge-model openai/gpt-5.4,thinking=xhigh,fast \
--judge-model anthropic/claude-opus-4-6,thinking=high \
--blind-judge-models \
--concurrency 16 \
--judge-concurrency 16
```
El comando ejecuta procesos hijo locales del gateway de QA, no Docker. Los escenarios de evaluación de carácter
deben establecer la persona mediante `SOUL.md`, y luego ejecutar turnos de usuario normales
como chat, ayuda del espacio de trabajo y pequeñas tareas de archivos. No se le debe decir al modelo
candidato que está siendo evaluado. El comando conserva cada transcripción completa,
registra estadísticas básicas de ejecución y luego pide a los modelos juez en modo fast con
razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor.
Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo
cada transcripción y estado de ejecución, pero las refs candidatas se sustituyen por
etiquetas neutras como `candidate-01`; el informe vuelve a asignar las clasificaciones a las refs reales después
del análisis.
Las ejecuciones candidatas usan de forma predeterminada pensamiento `high`, con `xhigh` para los modelos de OpenAI que
lo admiten. Sustituye un candidato específico en línea con
`--model provider/model,thinking=<level>`. `--thinking <level>` sigue estableciendo un
respaldo global, y la forma anterior `--model-thinking <provider/model=level>` se
mantiene por compatibilidad.
Las refs candidatas de OpenAI usan de forma predeterminada el modo fast para que se use el procesamiento prioritario allí
donde el proveedor lo admita. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando un
solo candidato o juez necesite una sustitución. Pasa `--fast` solo cuando quieras
forzar el modo fast para todos los modelos candidatos. Las duraciones de candidatos y jueces se
registran en el informe para el análisis comparativo, pero los prompts de los jueces dicen explícitamente que
no clasifiquen por velocidad.
Tanto las ejecuciones de modelos candidatos como las de jueces usan por defecto una concurrencia de 16. Reduce
`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión del gateway local
hagan que una ejecución sea demasiado ruidosa.
Cuando no se pasa ningún `--model` candidato, la evaluación de carácter usa por defecto
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
`moonshot/kimi-k2.5` y
`google/gemini-3.1-pro-preview` cuando no se pasa `--model`.
Cuando no se pasa `--judge-model`, los jueces usan por defecto
`openai/gpt-5.4,thinking=xhigh,fast` y
`anthropic/claude-opus-4-6,thinking=high`.
## Documentación relacionada
- [Pruebas](/es/help/testing)
- [Canal de QA](/es/channels/qa-channel)
- [Panel](/web/dashboard)
- [Testing](/es/help/testing)
- [QA Channel](/es/channels/qa-channel)
- [Dashboard](/web/dashboard)

159
docs/es/gateway/cli-backends.md
View File

@ -1,34 +1,34 @@
---
read_when:
- Quieres una alternativa confiable cuando fallen los proveedores de API
- Estás ejecutando Codex CLI u otros CLI de IA locales y quieres reutilizarlos
- Quieres entender el puente loopback de MCP para el acceso a herramientas del backend de CLI
summary: 'Backends de CLI: alternativa local de CLI de IA con puente de herramientas MCP opcional'
- Quieres un respaldo confiable cuando fallen los proveedores de API
- Estás ejecutando Codex CLI u otras CLI de IA locales y quieres reutilizarlas
- Quieres comprender el puente loopback de MCP para el acceso a herramientas del backend de CLI
summary: 'Backends de CLI: respaldo con CLI de IA local con puente de herramientas MCP opcional'
title: Backends de CLI
x-i18n:
generated_at: "2026-04-08T02:14:38Z"
generated_at: "2026-04-09T01:27:53Z"
model: gpt-5.4
provider: openai
source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414
source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20
source_path: gateway/cli-backends.md
workflow: 15
---
# Backends de CLI (runtime alternativo)
# Backends de CLI (entorno de ejecución de respaldo)
OpenClaw puede ejecutar **CLI de IA locales** como una **alternativa solo de texto** cuando los proveedores de API no están disponibles,
están limitados por tasa o se comportan mal temporalmente. Esto es intencionalmente conservador:
OpenClaw puede ejecutar **CLI de IA locales** como **respaldo solo de texto** cuando los proveedores de API no están disponibles,
tienen límite de tasa o presentan un comportamiento incorrecto temporal. Esto es intencionalmente conservador:
- **Las herramientas de OpenClaw no se inyectan directamente**, pero los backends con `bundleMcp: true`
pueden recibir herramientas del gateway mediante un puente MCP loopback.
- **Streaming JSONL** para los CLI que lo admiten.
- **Se admiten sesiones** (para que los turnos de seguimiento sigan siendo coherentes).
- **Las imágenes pueden pasarse** si el CLI acepta rutas de imágenes.
pueden recibir herramientas del gateway mediante un puente loopback de MCP.
- **Streaming JSONL** para las CLI que lo admiten.
- **Se admiten sesiones** (para que los turnos de seguimiento mantengan la coherencia).
- **Las imágenes pueden pasarse** si la CLI acepta rutas de imágenes.
Esto está diseñado como una **red de seguridad** más que como una ruta principal. Úsalo cuando
quieras respuestas de texto de “siempre funciona” sin depender de API externas.
Esto está diseñado como una **red de seguridad** en lugar de una ruta principal. Úsalo cuando
quieras respuestas de texto que “siempre funcionen” sin depender de APIs externas.
Si quieres un runtime de arnés completo con controles de sesión ACP, tareas en segundo plano,
Si quieres un entorno de ejecución completo con controles de sesión ACP, tareas en segundo plano,
vinculación de hilo/conversación y sesiones externas de programación persistentes, usa
[ACP Agents](/es/tools/acp-agents) en su lugar. Los backends de CLI no son ACP.
@ -58,16 +58,16 @@ ruta del comando:
}
```
Eso es todo. No se necesitan claves ni configuración de autenticación adicional más allá del propio CLI.
Eso es todo. No se necesitan claves ni configuración de autenticación extra más allá de la propia CLI.
Si usas un backend de CLI incluido como **proveedor principal de mensajes** en un
host de gateway, OpenClaw ahora carga automáticamente el plugin incluido propietario cuando tu configuración
hace referencia explícita a ese backend en una referencia de modelo o en
`agents.defaults.cliBackends`.
## Uso como alternativa
## Uso como respaldo
Agrega un backend de CLI a tu lista de alternativas para que solo se ejecute cuando fallen los modelos principales:
Agrega un backend de CLI a tu lista de respaldo para que solo se ejecute cuando fallen los modelos principales:
```json5
{
@ -88,9 +88,9 @@ Agrega un backend de CLI a tu lista de alternativas para que solo se ejecute cua
Notas:
- Si usas `agents.defaults.models` (lista permitida), también debes incluir ahí los modelos de tu backend de CLI.
- Si usas `agents.defaults.models` (lista de permitidos), también debes incluir allí los modelos de tu backend de CLI.
- Si falla el proveedor principal (autenticación, límites de tasa, tiempos de espera), OpenClaw
probará después el backend de CLI.
probará luego el backend de CLI.
## Resumen de configuración
@ -100,8 +100,8 @@ Todos los backends de CLI viven en:
agents.defaults.cliBackends
```
Cada entrada se identifica con un **id de proveedor** (por ejemplo, `codex-cli`, `my-cli`).
El id del proveedor se convierte en la parte izquierda de tu referencia de modelo:
Cada entrada está indexada por un **id de proveedor** (por ejemplo, `codex-cli`, `my-cli`).
El id de proveedor pasa a ser el lado izquierdo de tu referencia de modelo:
```
<provider>/<model>
@ -131,6 +131,9 @@ El id del proveedor se convierte en la parte izquierda de tu referencia de model
sessionMode: "existing",
sessionIdFields: ["session_id", "conversation_id"],
systemPromptArg: "--system",
// Las CLI de estilo Codex pueden apuntar a un archivo de prompt en su lugar:
// systemPromptFileConfigArg: "-c",
// systemPromptFileConfigKey: "model_instructions_file",
systemPromptWhen: "first",
imageArg: "--image",
imageMode: "repeat",
@ -145,65 +148,71 @@ El id del proveedor se convierte en la parte izquierda de tu referencia de model
## Cómo funciona
1. **Selecciona un backend** según el prefijo del proveedor (`codex-cli/...`).
2. **Construye un prompt del sistema** usando el mismo prompt de OpenClaw + contexto del espacio de trabajo.
3. **Ejecuta el CLI** con un id de sesión (si se admite) para que el historial siga siendo consistente.
4. **Analiza la salida** (JSON o texto sin formato) y devuelve el texto final.
5. **Persiste los id de sesión** por backend, para que los seguimientos reutilicen la misma sesión del CLI.
2. **Construye un prompt de sistema** usando el mismo prompt de OpenClaw + contexto del espacio de trabajo.
3. **Ejecuta la CLI** con un id de sesión (si se admite) para que el historial se mantenga consistente.
4. **Analiza la salida** (JSON o texto plano) y devuelve el texto final.
5. **Persiste los id de sesión** por backend, para que los seguimientos reutilicen la misma sesión de la CLI.
<Note>
El backend incluido `claude-cli` de Anthropic vuelve a ser compatible. El personal de Anthropic
nos dijo que el uso de Claude CLI al estilo de OpenClaw vuelve a estar permitido, por lo que OpenClaw trata
El backend `claude-cli` incluido de Anthropic vuelve a ser compatible. El personal de Anthropic
nos dijo que el uso de Claude CLI al estilo OpenClaw vuelve a estar permitido, por lo que OpenClaw trata
el uso de `claude -p` como autorizado para esta integración, a menos que Anthropic publique
una nueva política.
</Note>
El backend `codex-cli` incluido de OpenAI pasa el prompt de sistema de OpenClaw a través de
la anulación de configuración `model_instructions_file` de Codex (`-c
model_instructions_file="..."`). Codex no expone una bandera de estilo Claude
`--append-system-prompt`, por lo que OpenClaw escribe el prompt ensamblado en un
archivo temporal para cada sesión nueva de Codex CLI.
## Sesiones
- Si el CLI admite sesiones, configura `sessionArg` (por ejemplo, `--session-id`) o
- Si la CLI admite sesiones, establece `sessionArg` (por ejemplo, `--session-id`) o
`sessionArgs` (marcador `{sessionId}`) cuando el ID deba insertarse
en varias banderas.
- Si el CLI usa un **subcomando de reanudación** con banderas diferentes, configura
`resumeArgs` (reemplaza `args` al reanudar) y, opcionalmente, `resumeOutput`
(para reanudaciones no JSON).
- Si la CLI usa un **subcomando de reanudación** con banderas diferentes, establece
`resumeArgs` (reemplaza `args` al reanudar) y opcionalmente `resumeOutput`
(para reanudaciones que no son JSON).
- `sessionMode`:
- `always`: siempre envía un id de sesión (un UUID nuevo si no hay ninguno almacenado).
- `existing`: solo envía un id de sesión si ya se había almacenado antes.
- `none`: nunca envía un id de sesión.
- `always`: envía siempre un id de sesión (UUID nuevo si no hay ninguno almacenado).
- `existing`: envía un id de sesión solo si ya había uno almacenado.
- `none`: no envía nunca un id de sesión.
Notas sobre serialización:
- `serialize: true` mantiene ordenadas las ejecuciones del mismo carril.
- La mayoría de los CLI serializan en un carril de proveedor.
- OpenClaw descarta la reutilización de sesiones de CLI almacenadas cuando cambia el estado de autenticación del backend, incluido relogin, rotación de tokens o un cambio en las credenciales del perfil de autenticación.
- `serialize: true` mantiene ordenadas las ejecuciones en la misma vía.
- La mayoría de las CLI serializan en una vía de proveedor.
- OpenClaw descarta la reutilización de sesión almacenada de la CLI cuando cambia el estado de autenticación del backend, lo que incluye volver a iniciar sesión, rotación de tokens o un cambio en la credencial del perfil de autenticación.
## Imágenes (paso directo)
Si tu CLI acepta rutas de imágenes, configura `imageArg`:
Si tu CLI acepta rutas de imágenes, establece `imageArg`:
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw escribirá las imágenes base64 en archivos temporales. Si `imageArg` está configurado, esas
rutas se pasan como argumentos del CLI. Si falta `imageArg`, OpenClaw agrega las
rutas de archivo al prompt (inyección de ruta), lo que es suficiente para los CLI que cargan automáticamente
archivos locales a partir de rutas simples.
OpenClaw escribirá las imágenes base64 en archivos temporales. Si `imageArg` está establecido, esas
rutas se pasan como argumentos de CLI. Si falta `imageArg`, OpenClaw agrega las
rutas de archivo al prompt (inyección de ruta), lo cual es suficiente para las CLI que cargan
automáticamente archivos locales desde rutas simples.
## Entradas / salidas
- `output: "json"` (predeterminado) intenta analizar JSON y extraer texto + id de sesión.
- Para la salida JSON de Gemini CLI, OpenClaw lee el texto de respuesta de `response` y
el uso de `stats` cuando falta `usage` o está vacío.
- `output: "jsonl"` analiza streams JSONL (por ejemplo Codex CLI `--json`) y extrae el mensaje final del agente, además de los identificadores de sesión
cuando están presentes.
- Para la salida JSON de Gemini CLI, OpenClaw lee el texto de respuesta desde `response` y
el uso desde `stats` cuando falta `usage` o está vacío.
- `output: "jsonl"` analiza flujos JSONL (por ejemplo Codex CLI `--json`) y extrae el mensaje final del agente más los identificadores
de sesión cuando están presentes.
- `output: "text"` trata stdout como la respuesta final.
Modos de entrada:
- `input: "arg"` (predeterminado) pasa el prompt como el último argumento del CLI.
- `input: "stdin"` envía el prompt mediante stdin.
- Si el prompt es muy largo y `maxPromptArgChars` está configurado, se usa stdin.
- `input: "arg"` (predeterminado) pasa el prompt como el último argumento de CLI.
- `input: "stdin"` envía el prompt por stdin.
- Si el prompt es muy largo y se establece `maxPromptArgChars`, se usa stdin.
## Valores predeterminados (propiedad del plugin)
@ -229,31 +238,31 @@ El plugin Google incluido también registra un valor predeterminado para `google
- `sessionMode: "existing"`
- `sessionIdFields: ["session_id", "sessionId"]`
Requisito previo: el Gemini CLI local debe estar instalado y disponible como
Requisito previo: la Gemini CLI local debe estar instalada y disponible como
`gemini` en `PATH` (`brew install gemini-cli` o
`npm install -g @google/gemini-cli`).
Notas sobre JSON de Gemini CLI:
- El texto de respuesta se lee del campo JSON `response`.
- El uso recurre a `stats` cuando `usage` está ausente o vacío.
- `stats.cached` se normaliza en OpenClaw como `cacheRead`.
- Si falta `stats.input`, OpenClaw deriva los tokens de entrada de
- El uso recurre a `stats` cuando `usage` no está presente o está vacío.
- `stats.cached` se normaliza como `cacheRead` en OpenClaw.
- Si falta `stats.input`, OpenClaw deriva los tokens de entrada a partir de
`stats.input_tokens - stats.cached`.
Sobrescribe esto solo si es necesario (lo más común: ruta absoluta de `command`).
Anúlalo solo si es necesario (algo común: ruta `command` absoluta).
## Valores predeterminados propiedad del plugin
Los valores predeterminados de los backends de CLI ahora forman parte de la superficie del plugin:
Los valores predeterminados del backend de CLI ahora forman parte de la superficie del plugin:
- Los plugins los registran con `api.registerCliBackend(...)`.
- El `id` del backend se convierte en el prefijo del proveedor en las referencias de modelo.
- La configuración de usuario en `agents.defaults.cliBackends.<id>` sigue sobrescribiendo el valor predeterminado del plugin.
- El `id` del backend pasa a ser el prefijo de proveedor en las referencias de modelo.
- La configuración del usuario en `agents.defaults.cliBackends.<id>` sigue anulando el valor predeterminado del plugin.
- La limpieza de configuración específica del backend sigue siendo propiedad del plugin mediante el hook opcional
`normalizeConfig`.
## Superposiciones Bundle MCP
## Superposiciones de MCP incluidas
Los backends de CLI **no** reciben llamadas de herramientas de OpenClaw directamente, pero un backend puede
optar por una superposición de configuración MCP generada con `bundleMcp: true`.
@ -261,37 +270,37 @@ optar por una superposición de configuración MCP generada con `bundleMcp: true
Comportamiento incluido actual:
- `claude-cli`: archivo de configuración MCP estricto generado
- `codex-cli`: sobrescrituras de configuración en línea para `mcp_servers`
- `codex-cli`: anulaciones de configuración en línea para `mcp_servers`
- `google-gemini-cli`: archivo de configuración del sistema Gemini generado
Cuando Bundle MCP está habilitado, OpenClaw:
Cuando bundle MCP está habilitado, OpenClaw:
- genera un servidor HTTP MCP loopback que expone herramientas del gateway al proceso del CLI
- inicia un servidor HTTP MCP loopback que expone herramientas del gateway al proceso de CLI
- autentica el puente con un token por sesión (`OPENCLAW_MCP_TOKEN`)
- limita el acceso a herramientas a la sesión, cuenta y contexto de canal actuales
- limita el acceso a herramientas a la sesión, cuenta y contexto del canal actuales
- carga los servidores bundle-MCP habilitados para el espacio de trabajo actual
- los combina con cualquier forma existente de configuración/ajustes MCP del backend
- los fusiona con cualquier forma existente de configuración/ajustes MCP del backend
- reescribe la configuración de inicio usando el modo de integración propiedad del backend desde la extensión propietaria
Si no hay servidores MCP habilitados, OpenClaw sigue inyectando una configuración estricta cuando un
backend opta por Bundle MCP para que las ejecuciones en segundo plano permanezcan aisladas.
Si no hay servidores MCP habilitados, OpenClaw igualmente inyecta una configuración estricta cuando un
backend opta por bundle MCP para que las ejecuciones en segundo plano sigan aisladas.
## Limitaciones
- **No hay llamadas directas a herramientas de OpenClaw.** OpenClaw no inyecta llamadas de herramientas en
el protocolo del backend de CLI. Los backends solo ven herramientas del gateway cuando optan por
`bundleMcp: true`.
- **El streaming es específico del backend.** Algunos backends transmiten JSONL; otros almacenan
en búfer hasta la salida.
- **Las salidas estructuradas** dependen del formato JSON del CLI.
- **Las sesiones de Codex CLI** se reanudan mediante salida de texto (sin JSONL), lo que está menos
- **El streaming es específico del backend.** Algunos backends transmiten JSONL; otros almacenan en búfer
hasta salir.
- **Las salidas estructuradas** dependen del formato JSON de la CLI.
- **Las sesiones de Codex CLI** se reanudan mediante salida de texto (sin JSONL), lo que es menos
estructurado que la ejecución inicial con `--json`. Las sesiones de OpenClaw siguen funcionando
normalmente.
## Solución de problemas
- **CLI no encontrado**: configura `command` con una ruta completa.
- **Nombre de modelo incorrecto**: usa `modelAliases` para mapear `provider/model` → modelo del CLI.
- **Sin continuidad de sesión**: asegúrate de que `sessionArg` esté configurado y que `sessionMode` no sea
- **CLI no encontrada**: establece `command` en una ruta completa.
- **Nombre de modelo incorrecto**: usa `modelAliases` para asignar `provider/model` → modelo de CLI.
- **Sin continuidad de sesión**: asegúrate de que `sessionArg` esté establecido y de que `sessionMode` no sea
`none` (actualmente Codex CLI no puede reanudarse con salida JSON).
- **Imágenes ignoradas**: configura `imageArg` (y verifica que el CLI admita rutas de archivo).
- **Imágenes ignoradas**: establece `imageArg` (y verifica que la CLI admita rutas de archivo).

1109
docs/es/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

460
docs/es/gateway/doctor.md
View File

@ -1,22 +1,23 @@
---
read_when:
- Agregar o modificar migraciones de Doctor
- Introducir cambios de configuración incompatibles
- Agregar o modificar migraciones de doctor
- Introducir cambios incompatibles de configuración
summary: 'Comando Doctor: comprobaciones de estado, migraciones de configuración y pasos de reparación'
title: Doctor
x-i18n:
generated_at: "2026-04-08T02:15:35Z"
generated_at: "2026-04-09T01:29:12Z"
model: gpt-5.4
provider: openai
source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6
source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce
source_path: gateway/doctor.md
workflow: 15
---
# Doctor
`openclaw doctor` es la herramienta de reparación y migración de OpenClaw. Corrige
configuración/estado obsoletos, comprueba el estado y proporciona pasos de reparación accionables.
`openclaw doctor` es la herramienta de reparación + migración de OpenClaw. Corrige
configuración/estado obsoletos, comprueba el estado y proporciona pasos de
reparación accionables.
## Inicio rápido
@ -24,19 +25,19 @@ configuración/estado obsoletos, comprueba el estado y proporciona pasos de repa
openclaw doctor
```
### Sin interfaz / automatización
### Modo sin interfaz / automatización
```bash
openclaw doctor --yes
```
Acepta los valores predeterminados sin solicitar confirmación (incluidos los pasos de reparación de reinicio/servicio/sandbox cuando corresponda).
Acepta los valores predeterminados sin preguntar (incluidos los pasos de reparación de reinicio/servicio/sandbox cuando corresponda).
```bash
openclaw doctor --repair
```
Aplica las reparaciones recomendadas sin solicitar confirmación (reparaciones + reinicios cuando sea seguro).
Aplica las reparaciones recomendadas sin preguntar (reparaciones + reinicios cuando sea seguro).
```bash
openclaw doctor --repair --force
@ -48,7 +49,7 @@ Aplica también reparaciones agresivas (sobrescribe configuraciones personalizad
openclaw doctor --non-interactive
```
Se ejecuta sin solicitudes y solo aplica migraciones seguras (normalización de configuración + movimientos de estado en disco). Omite acciones de reinicio/servicio/sandbox que requieren confirmación humana.
Se ejecuta sin preguntas y solo aplica migraciones seguras (normalización de configuración + movimientos de estado en disco). Omite acciones de reinicio/servicio/sandbox que requieren confirmación humana.
Las migraciones de estado heredado se ejecutan automáticamente cuando se detectan.
```bash
@ -57,7 +58,7 @@ openclaw doctor --deep
Analiza los servicios del sistema para detectar instalaciones adicionales del gateway (launchd/systemd/schtasks).
Si quiere revisar los cambios antes de escribirlos, abra primero el archivo de configuración:
Si quieres revisar los cambios antes de escribir, abre primero el archivo de configuración:
```bash
cat ~/.openclaw/openclaw.json
@ -66,61 +67,95 @@ cat ~/.openclaw/openclaw.json
## Qué hace (resumen)
- Actualización previa opcional para instalaciones de git (solo interactivo).
- Comprobación de actualización del protocolo de la UI (reconstruye Control UI cuando el esquema del protocolo es más reciente).
- Comprobación de estado + solicitud de reinicio.
- Resumen del estado de Skills (aptas/faltantes/bloqueadas) y estado de plugins.
- Comprobación de vigencia del protocolo de IU (reconstruye la Control UI cuando el esquema del protocolo es más reciente).
- Comprobación de estado + aviso para reiniciar.
- Resumen del estado de Skills (aptas/faltantes/bloqueadas) y estado de los plugins.
- Normalización de configuración para valores heredados.
- Migración de la configuración de Talk desde los campos planos heredados `talk.*` a `talk.provider` + `talk.providers.<provider>`.
- Migración de configuración de Talk desde campos planos heredados `talk.*` hacia `talk.provider` + `talk.providers.<provider>`.
- Comprobaciones de migración del navegador para configuraciones heredadas de la extensión de Chrome y preparación de Chrome MCP.
- Advertencias de sobrescritura del proveedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Advertencias de enmascaramiento de OAuth de Codex (`models.providers.openai-codex`).
- Comprobación de requisitos previos de TLS para perfiles OAuth de OpenAI Codex.
- Migración de estado heredado en disco (sesiones/directorio de agente/autenticación de WhatsApp).
- Migración de claves de contrato heredadas del manifiesto de plugins (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migración del almacén cron heredado (`jobId`, `schedule.cron`, campos de entrega/carga útil de nivel superior, `provider` en la carga útil, trabajos de respaldo webhook simples con `notify: true`).
- Advertencias de anulaciones del proveedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Advertencias de sombreado de OAuth de Codex (`models.providers.openai-codex`).
- Comprobación de requisitos previos de TLS de OAuth para perfiles de OAuth de OpenAI Codex.
- Migración heredada de estado en disco (sesiones/directorio del agente/autenticación de WhatsApp).
- Migración heredada de claves de contrato en manifiestos de plugins (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migración heredada del almacén cron (`jobId`, `schedule.cron`, campos de entrega/carga útil de nivel superior, `provider` en la carga útil, trabajos simples de respaldo webhook con `notify: true`).
- Inspección de archivos de bloqueo de sesión y limpieza de bloqueos obsoletos.
- Comprobaciones de integridad y permisos del estado (sesiones, transcripciones, directorio de estado).
- Comprobaciones de permisos del archivo de configuración (`chmod 600`) cuando se ejecuta localmente.
- Estado de autenticación de modelos: comprueba el vencimiento de OAuth, puede renovar tokens próximos a vencer y reporta estados de enfriamiento/deshabilitación de perfiles de autenticación.
- Estado de autenticación del modelo: comprueba vencimiento de OAuth, puede actualizar tokens próximos a vencer e informa de estados de enfriamiento/desactivación del perfil de autenticación.
- Detección de directorio de espacio de trabajo adicional (`~/openclaw`).
- Reparación de imagen de sandbox cuando el aislamiento está habilitado.
- Migración de servicios heredados y detección de gateways adicionales.
- Migración de estado heredado del canal Matrix (en modo `--fix` / `--repair`).
- Comprobaciones del tiempo de ejecución del gateway (servicio instalado pero no en ejecución; etiqueta launchd en caché).
- Reparación de imagen de sandbox cuando el sandbox está habilitado.
- Migración de servicio heredado y detección de gateways adicionales.
- Migración heredada del estado del canal Matrix (en modo `--fix` / `--repair`).
- Comprobaciones del runtime del gateway (servicio instalado pero no en ejecución; etiqueta launchd en caché).
- Advertencias de estado de canales (sondeadas desde el gateway en ejecución).
- Auditoría de configuración del supervisor (launchd/systemd/schtasks) con reparación opcional.
- Comprobaciones de buenas prácticas del tiempo de ejecución del gateway (Node frente a Bun, rutas de gestores de versiones).
- Diagnóstico de colisiones de puerto del gateway (predeterminado `18789`).
- Advertencias de seguridad para políticas de DM abiertas.
- Comprobaciones de autenticación del gateway para el modo de token local (ofrece generar un token cuando no existe una fuente de token; no sobrescribe configuraciones de token con SecretRef).
- Comprobación de linger de systemd en Linux.
- Comprobación del tamaño de archivos de arranque del espacio de trabajo (advertencias de truncamiento o cercanía al límite para archivos de contexto).
- Comprobación del estado del autocompletado del shell e instalación/actualización automática.
- Comprobaciones de buenas prácticas del runtime del gateway (Node frente a Bun, rutas de gestores de versiones).
- Diagnósticos de colisión de puertos del gateway (predeterminado `18789`).
- Advertencias de seguridad para políticas de MD abiertas.
- Comprobaciones de autenticación del gateway para modo de token local (ofrece generar un token cuando no existe una fuente de token; no sobrescribe configuraciones de token SecretRef).
- Comprobación de systemd linger en Linux.
- Comprobación del tamaño de archivos bootstrap del espacio de trabajo (advertencias por truncamiento/cercanía al límite para archivos de contexto).
- Comprobación del estado de autocompletado del shell e instalación/actualización automática.
- Comprobación de preparación del proveedor de embeddings para búsqueda en memoria (modelo local, clave de API remota o binario QMD).
- Comprobaciones de instalación desde código fuente (desajuste del espacio de trabajo pnpm, recursos de UI faltantes, binario tsx faltante).
- Comprobaciones de instalación desde código fuente (desajuste de espacio de trabajo pnpm, recursos de IU faltantes, binario tsx faltante).
- Escribe la configuración actualizada + metadatos del asistente.
## Comportamiento detallado y fundamento
## Backfill y restablecimiento de la IU de Dreams
La escena Dreams de la Control UI incluye acciones de **Backfill**, **Reset** y **Clear Grounded**
para el flujo de trabajo de sueños fundamentados. Estas acciones usan métodos RPC
de estilo doctor del gateway, pero **no** forman parte de la reparación/migración
de la CLI `openclaw doctor`.
Qué hacen:
- **Backfill** analiza archivos históricos `memory/YYYY-MM-DD.md` en el espacio
de trabajo activo, ejecuta el proceso fundamentado del diario REM y escribe
entradas reversibles de backfill en `DREAMS.md`.
- **Reset** elimina solo esas entradas del diario de backfill marcadas de `DREAMS.md`.
- **Clear Grounded** elimina solo las entradas preparadas a corto plazo de tipo
grounded-only que provinieron de una reproducción histórica y que aún no han
acumulado recuperación en vivo ni soporte diario.
Qué **no** hacen por sí solas:
- no editan `MEMORY.md`
- no ejecutan migraciones completas de doctor
- no preparan automáticamente candidatos fundamentados en el almacén de promoción
activa a corto plazo a menos que ejecutes explícitamente primero la ruta de la CLI preparada
Si quieres que la reproducción histórica fundamentada influya en la vía normal
de promoción profunda, usa en su lugar el flujo de CLI:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Eso prepara candidatos duraderos fundamentados en el almacén de sueños a corto plazo,
manteniendo `DREAMS.md` como la superficie de revisión.
## Comportamiento detallado y justificación
### 0) Actualización opcional (instalaciones de git)
Si esto es una extracción de git y doctor se está ejecutando de forma interactiva, ofrece
Si esto es un checkout de git y doctor se ejecuta de forma interactiva, ofrece
actualizar (fetch/rebase/build) antes de ejecutar doctor.
### 1) Normalización de configuración
Si la configuración contiene formas de valores heredados (por ejemplo `messages.ackReaction`
sin una sobrescritura específica del canal), doctor los normaliza al esquema actual.
Si la configuración contiene formas heredadas de valores (por ejemplo `messages.ackReaction`
sin una anulación específica por canal), doctor las normaliza al esquema actual.
Eso incluye los campos planos heredados de Talk. La configuración pública actual de Talk es
Eso incluye campos planos heredados de Talk. La configuración pública actual de Talk es
`talk.provider` + `talk.providers.<provider>`. Doctor reescribe las formas antiguas
`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` en el mapa de proveedores.
`talk.apiKey` en el mapa del proveedor.
### 2) Migraciones de claves de configuración heredadas
### 2) Migraciones de claves heredadas de configuración
Cuando la configuración contiene claves obsoletas, otros comandos se niegan a ejecutarse y piden
que ejecute `openclaw doctor`.
Cuando la configuración contiene claves obsoletas, otros comandos se niegan a ejecutarse y te piden
que ejecutes `openclaw doctor`.
Doctor hará lo siguiente:
@ -128,8 +163,8 @@ Doctor hará lo siguiente:
- Mostrar la migración que aplicó.
- Reescribir `~/.openclaw/openclaw.json` con el esquema actualizado.
El Gateway también ejecuta automáticamente las migraciones de doctor al iniciarse cuando detecta un
formato de configuración heredado, por lo que las configuraciones obsoletas se reparan sin intervención manual.
El Gateway también ejecuta automáticamente las migraciones de doctor al iniciarse cuando detecta
un formato heredado de configuración, de modo que las configuraciones obsoletas se reparan sin intervención manual.
Las migraciones del almacén de trabajos cron se gestionan con `openclaw doctor --fix`.
Migraciones actuales:
@ -141,7 +176,7 @@ Migraciones actuales:
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` de nivel superior
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` heredados → `talk.provider` + `talk.providers.<provider>`
- heredado `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -154,7 +189,7 @@ Migraciones actuales:
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
→ `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Para canales con `accounts` con nombre pero con valores de canal de cuenta única aún presentes en el nivel superior, mover esos valores con alcance de cuenta a la cuenta promovida elegida para ese canal (`accounts.default` para la mayoría de los canales; Matrix puede conservar un destino coincidente con nombre/predeterminado existente)
- Para canales con `accounts` con nombre pero con valores persistentes de canal de cuenta única en el nivel superior, mover esos valores con alcance de cuenta a la cuenta promovida elegida para ese canal (`accounts.default` para la mayoría de los canales; Matrix puede conservar un destino con nombre/predeterminado coincidente ya existente)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
@ -163,74 +198,75 @@ Migraciones actuales:
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- eliminar `browser.relayBindHost` (configuración heredada del relay de la extensión)
Las advertencias de Doctor también incluyen orientación sobre cuentas predeterminadas para canales con varias cuentas:
Las advertencias de doctor también incluyen orientación sobre cuentas predeterminadas para canales con varias cuentas:
- Si se configuran dos o más entradas `channels.<channel>.accounts` sin `channels.<channel>.defaultAccount` o `accounts.default`, doctor advierte que el enrutamiento de respaldo puede elegir una cuenta inesperada.
- Si `channels.<channel>.defaultAccount` está configurado con un ID de cuenta desconocido, doctor advierte y enumera los ID de cuenta configurados.
- Si se configuran dos o más entradas `channels.<channel>.accounts` sin `channels.<channel>.defaultAccount` ni `accounts.default`, doctor advierte que el enrutamiento de respaldo puede elegir una cuenta inesperada.
- Si `channels.<channel>.defaultAccount` está establecido en un ID de cuenta desconocido, doctor advierte y enumera los ID de cuenta configurados.
### 2b) Sobrescrituras del proveedor OpenCode
### 2b) Anulaciones del proveedor OpenCode
Si agregó manualmente `models.providers.opencode`, `opencode-zen` u `opencode-go`,
sobrescribe el catálogo integrado de OpenCode de `@mariozechner/pi-ai`.
Eso puede forzar modelos a la API incorrecta o dejar los costos en cero. Doctor advierte para que
pueda eliminar la sobrescritura y restaurar el enrutamiento por modelo + costos.
Si agregaste manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`,
eso sobrescribe el catálogo integrado de OpenCode de `@mariozechner/pi-ai`.
Eso puede forzar modelos a la API equivocada o poner los costos a cero. Doctor advierte
para que puedas eliminar la anulación y restaurar el enrutamiento por modelo + costos.
### 2c) Migración del navegador y preparación de Chrome MCP
Si su configuración del navegador aún apunta a la ruta eliminada de la extensión de Chrome, doctor
la normaliza al modelo actual de conexión de Chrome MCP local al host:
Si tu configuración del navegador aún apunta a la ruta eliminada de la extensión de Chrome, doctor
la normaliza al modelo actual de conexión host-local de Chrome MCP:
- `browser.profiles.*.driver: "extension"` pasa a ser `"existing-session"`
- se elimina `browser.relayBindHost`
Doctor también audita la ruta de Chrome MCP local al host cuando usa `defaultProfile:
Doctor también audita la ruta host-local de Chrome MCP cuando usas `defaultProfile:
"user"` o un perfil `existing-session` configurado:
- comprueba si Google Chrome está instalado en el mismo host para perfiles predeterminados
de conexión automática
- comprueba si Google Chrome está instalado en el mismo host para perfiles de
conexión automática predeterminados
- comprueba la versión detectada de Chrome y advierte cuando es inferior a Chrome 144
- recuerda habilitar la depuración remota en la página de inspección del navegador (por
ejemplo `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
o `edge://inspect/#remote-debugging`)
Doctor no puede habilitar la configuración del lado de Chrome por usted. El Chrome MCP
local al host aún requiere:
Doctor no puede habilitar la configuración del lado de Chrome por ti. Chrome MCP host-local
todavía requiere:
- un navegador basado en Chromium 144+ en el host gateway/nodo
- un navegador basado en Chromium 144+ en el host del gateway/nodo
- el navegador ejecutándose localmente
- depuración remota habilitada en ese navegador
- aprobar la primera solicitud de consentimiento de conexión en el navegador
- aprobar el primer aviso de consentimiento de conexión en el navegador
La preparación aquí solo se refiere a los requisitos previos de conexión local. Existing-session mantiene
los límites de ruta actuales de Chrome MCP; las rutas avanzadas como `responsebody`, exportación PDF,
intercepción de descargas y acciones por lotes siguen requiriendo un navegador gestionado
o un perfil CDP sin procesar.
La preparación aquí se refiere solo a los requisitos previos de conexión local. Existing-session mantiene
los límites actuales de rutas de Chrome MCP; rutas avanzadas como `responsebody`, exportación
a PDF, interceptación de descargas y acciones por lotes siguen requiriendo un
navegador gestionado o un perfil CDP sin procesar.
Esta comprobación **no** se aplica a Docker, sandbox, remote-browser ni a otros
Esta comprobación **no** se aplica a Docker, sandbox, remote-browser ni otros
flujos sin interfaz. Esos siguen usando CDP sin procesar.
### 2d) Requisitos previos de TLS para OAuth
Cuando se configura un perfil OAuth de OpenAI Codex, doctor sondea el endpoint de autorización de OpenAI
para verificar que la pila TLS local de Node/OpenSSL pueda validar la cadena de certificados. Si el sondeo falla con un error de certificado (por
Cuando se configura un perfil de OAuth de OpenAI Codex, doctor sondea el endpoint de autorización de OpenAI
para verificar que la pila TLS local de Node/OpenSSL pueda validar la cadena de certificados.
Si el sondeo falla con un error de certificado (por
ejemplo `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado vencido o certificado autofirmado),
doctor muestra orientación de corrección específica para cada plataforma. En macOS con Node de Homebrew, la
doctor imprime orientación de corrección específica de la plataforma. En macOS con un Node de Homebrew, la
corrección suele ser `brew postinstall ca-certificates`. Con `--deep`, el sondeo se ejecuta
incluso si el gateway está en buen estado.
### 2c) Sobrescrituras del proveedor OAuth de Codex
### 2c) Anulaciones del proveedor OAuth de Codex
Si anteriormente agregó configuraciones heredadas de transporte OpenAI en
`models.providers.openai-codex`, pueden enmascarar la ruta integrada del
proveedor OAuth de Codex que las versiones más recientes usan automáticamente. Doctor advierte cuando ve
esas configuraciones antiguas de transporte junto con OAuth de Codex para que pueda eliminar o reescribir
la sobrescritura de transporte obsoleta y recuperar el comportamiento integrado de enrutamiento/respaldo.
Los proxies personalizados y las sobrescrituras solo de encabezados siguen siendo compatibles y no
activan esta advertencia.
Si anteriormente agregaste configuraciones heredadas de transporte de OpenAI en
`models.providers.openai-codex`, estas pueden ocultar la ruta integrada del
proveedor OAuth de Codex que las versiones más recientes usan automáticamente. Doctor
advierte cuando ve esas configuraciones antiguas de transporte junto con OAuth de Codex
para que puedas eliminar o reescribir la anulación obsoleta de transporte y recuperar
el comportamiento integrado de enrutamiento/respaldo. Los proxies personalizados y las anulaciones
solo de encabezados siguen siendo compatibles y no activan esta advertencia.
### 3) Migraciones de estado heredado (diseño en disco)
### 3) Migraciones heredadas de estado (disposición en disco)
Doctor puede migrar diseños antiguos en disco a la estructura actual:
Doctor puede migrar disposiciones antiguas en disco a la estructura actual:
- Almacén de sesiones + transcripciones:
- de `~/.openclaw/sessions/` a `~/.openclaw/agents/<agentId>/sessions/`
@ -238,34 +274,34 @@ Doctor puede migrar diseños antiguos en disco a la estructura actual:
- de `~/.openclaw/agent/` a `~/.openclaw/agents/<agentId>/agent/`
- Estado de autenticación de WhatsApp (Baileys):
- desde `~/.openclaw/credentials/*.json` heredado (excepto `oauth.json`)
- hacia `~/.openclaw/credentials/whatsapp/<accountId>/...` (id de cuenta predeterminada: `default`)
- a `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID de cuenta predeterminado: `default`)
Estas migraciones son de mejor esfuerzo e idempotentes; doctor emitirá advertencias cuando
Estas migraciones son por mejor esfuerzo e idempotentes; doctor emitirá advertencias cuando
deje carpetas heredadas como copias de seguridad. El Gateway/CLI también migra automáticamente
las sesiones heredadas + el directorio del agente al iniciarse, de modo que el historial/autenticación/modelos
terminen en la ruta por agente sin ejecutar doctor manualmente. La autenticación de WhatsApp se migra intencionalmente solo
mediante `openclaw doctor`. La normalización del proveedor/mapa de proveedores de Talk ahora
compara por igualdad estructural, por lo que las diferencias solo en el orden de las claves ya no activan
cambios repetidos de `doctor --fix` sin efecto.
las sesiones heredadas + el directorio del agente al iniciarse, para que el historial/autenticación/modelos
terminen en la ruta por agente sin una ejecución manual de doctor. La autenticación de WhatsApp se migra
intencionalmente solo mediante `openclaw doctor`. La normalización de proveedor/mapa de proveedores de Talk ahora
compara por igualdad estructural, por lo que las diferencias solo en el orden de claves ya no provocan
cambios repetidos sin efecto de `doctor --fix`.
### 3a) Migraciones heredadas del manifiesto de plugins
### 3a) Migraciones heredadas de manifiestos de plugins
Doctor analiza todos los manifiestos de plugins instalados para detectar claves obsoletas de capacidades
de nivel superior (`speechProviders`, `realtimeTranscriptionProviders`,
Doctor analiza todos los manifiestos de plugins instalados en busca de claves
obsoletas de capacidades de nivel superior (`speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
`webSearchProviders`). Cuando las encuentra, ofrece moverlas al objeto `contracts`
y reescribir el archivo de manifiesto in situ. Esta migración es idempotente;
y reescribir el archivo del manifiesto in situ. Esta migración es idempotente;
si la clave `contracts` ya tiene los mismos valores, la clave heredada se elimina
sin duplicar los datos.
### 3b) Migraciones heredadas del almacén cron
Doctor también comprueba el almacén de trabajos cron (`~/.openclaw/cron/jobs.json` de forma predeterminada,
o `cron.store` cuando se sobrescribe) para detectar formas antiguas de trabajos que el planificador aún
o `cron.store` si se ha sobrescrito) en busca de formas antiguas de trabajos que el planificador aún
acepta por compatibilidad.
Las limpiezas cron actuales incluyen:
Las limpiezas actuales de cron incluyen:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
@ -275,130 +311,133 @@ Las limpiezas cron actuales incluyen:
- trabajos heredados simples de respaldo webhook con `notify: true` → `delivery.mode="webhook"` explícito con `delivery.to=cron.webhook`
Doctor solo migra automáticamente trabajos `notify: true` cuando puede hacerlo sin
cambiar el comportamiento. Si un trabajo combina el respaldo heredado de notify con un modo de entrega
existente no webhook, doctor advierte y deja ese trabajo para revisión manual.
cambiar el comportamiento. Si un trabajo combina un respaldo notify heredado con un modo de
entrega existente no webhook, doctor advierte y deja ese trabajo para revisión manual.
### 3c) Limpieza de bloqueos de sesión
Doctor analiza cada directorio de sesión de agente para detectar archivos de bloqueo de escritura obsoletos:
archivos que quedaron atrás cuando una sesión salió de forma anómala. Para cada archivo de bloqueo encontrado informa:
Doctor analiza cada directorio de sesiones de agente en busca de archivos obsoletos de bloqueo de escritura:
archivos que quedan cuando una sesión salió de forma anómala. Para cada archivo de bloqueo encontrado informa:
la ruta, el PID, si el PID sigue activo, la antigüedad del bloqueo y si se
considera obsoleto (PID muerto o más de 30 minutos). En modo `--fix` / `--repair`
elimina automáticamente los archivos de bloqueo obsoletos; en caso contrario, muestra una nota y
le indica volver a ejecutar con `--fix`.
considera obsoleto (PID muerto o con más de 30 minutos). En modo `--fix` / `--repair`
elimina automáticamente los archivos de bloqueo obsoletos; de lo contrario imprime una nota e
indica que lo vuelvas a ejecutar con `--fix`.
### 4) Comprobaciones de integridad del estado (persistencia de sesión, enrutamiento y seguridad)
El directorio de estado es el tronco encefálico operativo. Si desaparece, pierde
sesiones, credenciales, registros y configuración (a menos que tenga copias de seguridad en otro lugar).
El directorio de estado es el tronco operativo principal. Si desaparece, pierdes
sesiones, credenciales, registros y configuración (a menos que tengas copias de seguridad en otro lugar).
Doctor comprueba:
- **Falta el directorio de estado**: advierte sobre una pérdida catastrófica del estado, solicita volver a crear
el directorio y recuerda que no puede recuperar los datos faltantes.
- **Permisos del directorio de estado**: verifica que se pueda escribir; ofrece reparar permisos
(y emite una sugerencia de `chown` cuando detecta discrepancia de propietario/grupo).
- **Directorio de estado sincronizado en la nube de macOS**: advierte cuando el estado se resuelve bajo iCloud Drive
- **Falta el directorio de estado**: advierte sobre pérdida catastrófica de estado, ofrece recrear
el directorio y recuerda que no puede recuperar datos faltantes.
- **Permisos del directorio de estado**: verifica que sea escribible; ofrece reparar permisos
(y emite una sugerencia de `chown` cuando detecta desajuste de propietario/grupo).
- **Directorio de estado sincronizado en la nube en macOS**: advierte cuando el estado se resuelve bajo iCloud Drive
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o
`~/Library/CloudStorage/...` porque las rutas respaldadas por sincronización pueden causar E/S más lentas
y condiciones de carrera de bloqueo/sincronización.
- **Directorio de estado en SD o eMMC de Linux**: advierte cuando el estado se resuelve a una fuente de montaje `mmcblk*`,
porque la E/S aleatoria respaldada por SD o eMMC puede ser más lenta y desgastarse
más rápido con las escrituras de sesión y credenciales.
- **Directorio de estado en SD o eMMC en Linux**: advierte cuando el estado se resuelve a un origen de montaje `mmcblk*`,
porque la E/S aleatoria respaldada por SD o eMMC puede ser más lenta y desgastarse más rápido con escrituras de sesiones y credenciales.
- **Faltan directorios de sesión**: `sessions/` y el directorio del almacén de sesiones son
necesarios para persistir el historial y evitar fallos `ENOENT`.
- **Desajuste de transcripción**: advierte cuando las entradas recientes de sesión tienen
archivos de transcripción faltantes.
- **Sesión principal con “JSONL de 1 línea”**: marca cuando la transcripción principal solo tiene una
necesarios para conservar el historial y evitar fallos `ENOENT`.
- **Desajuste de transcripciones**: advierte cuando entradas recientes de sesión tienen archivos
de transcripción faltantes.
- **Sesión principal “JSONL de 1 línea”**: marca cuando la transcripción principal tiene solo una
línea (el historial no se está acumulando).
- **Varios directorios de estado**: advierte cuando existen varias carpetas `~/.openclaw` entre
directorios de inicio o cuando `OPENCLAW_STATE_DIR` apunta a otro lugar (el historial puede
dividirse entre instalaciones).
directorios personales o cuando `OPENCLAW_STATE_DIR` apunta a otro sitio (el historial puede dividirse entre instalaciones).
- **Recordatorio de modo remoto**: si `gateway.mode=remote`, doctor recuerda ejecutarlo en
el host remoto (el estado vive allí).
- **Permisos del archivo de configuración**: advierte si `~/.openclaw/openclaw.json` es
legible por grupo/mundo y ofrece restringirlo a `600`.
### 5) Estado de autenticación de modelos (vencimiento de OAuth)
### 5) Estado de autenticación del modelo (vencimiento de OAuth)
Doctor inspecciona los perfiles OAuth en el almacén de autenticación, advierte cuando los tokens están
próximos a vencer o vencidos, y puede renovarlos cuando es seguro. Si el perfil OAuth/token
de Anthropic está obsoleto, sugiere una clave de API de Anthropic o la
ruta de token de configuración de Anthropic.
Las solicitudes de renovación solo aparecen cuando se ejecuta de forma interactiva (TTY); `--non-interactive`
omite los intentos de renovación.
Doctor inspecciona perfiles OAuth en el almacén de autenticación, advierte cuando los tokens
están por vencer o vencidos, y puede actualizarlos cuando sea seguro. Si el perfil
de OAuth/token de Anthropic está obsoleto, sugiere una clave de API de Anthropic o la
ruta de setup-token de Anthropic.
Los avisos de actualización solo aparecen cuando se ejecuta de forma interactiva (TTY); `--non-interactive`
omite los intentos de actualización.
Doctor también informa perfiles de autenticación que están temporalmente inutilizables debido a:
Cuando una actualización de OAuth falla de forma permanente (por ejemplo `refresh_token_reused`,
`invalid_grant` o un proveedor te indica que vuelvas a iniciar sesión), doctor informa
que se requiere reautenticación e imprime el comando exacto `openclaw models auth login --provider ...`
que debes ejecutar.
- enfriamientos breves (límites de velocidad/tiempos de espera/fallos de autenticación)
- deshabilitaciones más largas (fallos de facturación/crédito)
Doctor también informa de perfiles de autenticación temporalmente inutilizables debido a:
### 6) Validación del modelo de hooks
- enfriamientos cortos (límites de tasa/tiempos de espera/fallos de autenticación)
- desactivaciones más largas (fallos de facturación/crédito)
Si `hooks.gmail.model` está configurado, doctor valida la referencia del modelo con el
### 6) Validación del modelo de Hooks
Si `hooks.gmail.model` está configurado, doctor valida la referencia del modelo frente al
catálogo y la lista de permitidos y advierte cuando no se resolverá o no está permitido.
### 7) Reparación de imagen de sandbox
Cuando el aislamiento está habilitado, doctor comprueba las imágenes de Docker y ofrece compilar o
Cuando el sandbox está habilitado, doctor comprueba las imágenes de Docker y ofrece compilar o
cambiar a nombres heredados si falta la imagen actual.
### 7b) Dependencias de tiempo de ejecución de plugins integrados
### 7b) Dependencias de runtime de plugins incluidos
Doctor verifica que las dependencias de tiempo de ejecución de plugins integrados (por ejemplo, los
paquetes de tiempo de ejecución del plugin de Discord) estén presentes en la raíz de instalación de OpenClaw.
Si falta alguna, doctor informa los paquetes y los instala en
modo `openclaw doctor --fix` / `openclaw doctor --repair`.
Doctor verifica que las dependencias de runtime de los plugins incluidos (por ejemplo los
paquetes de runtime del plugin de Discord) estén presentes en la raíz de instalación de OpenClaw.
Si falta alguna, doctor informa de los paquetes y los instala en modo
`openclaw doctor --fix` / `openclaw doctor --repair`.
### 8) Migraciones de servicios del gateway y sugerencias de limpieza
Doctor detecta servicios heredados del gateway (launchd/systemd/schtasks) y
ofrece eliminarlos e instalar el servicio de OpenClaw usando el puerto actual del gateway.
También puede buscar servicios adicionales similares al gateway y mostrar sugerencias de limpieza.
Los servicios de gateway de OpenClaw con nombre de perfil se consideran de primera clase y no
se marcan como “adicionales”.
También puede buscar servicios adicionales similares al gateway e imprimir sugerencias de limpieza.
Los servicios de gateway de OpenClaw con nombre de perfil se consideran de primera clase y no se
marcan como "adicionales".
### 8b) Migración de Matrix al inicio
### 8b) Migración de Matrix al iniciar
Cuando una cuenta del canal Matrix tiene una migración de estado heredado pendiente o procesable,
Cuando una cuenta del canal Matrix tiene una migración heredada de estado pendiente o aplicable,
doctor (en modo `--fix` / `--repair`) crea una instantánea previa a la migración y luego
ejecuta los pasos de migración de mejor esfuerzo: migración del estado heredado de Matrix y preparación
del estado cifrado heredado. Ambos pasos no son fatales; los errores se registran y el
inicio continúa. En modo de solo lectura (`openclaw doctor` sin `--fix`) esta comprobación
ejecuta los pasos de migración por mejor esfuerzo: migración heredada del estado de Matrix
y preparación heredada del estado cifrado. Ambos pasos no son fatales; los errores se registran y
el inicio continúa. En modo de solo lectura (`openclaw doctor` sin `--fix`) esta comprobación
se omite por completo.
### 9) Advertencias de seguridad
Doctor emite advertencias cuando un proveedor está abierto a DM sin una lista de permitidos, o
Doctor emite advertencias cuando un proveedor está abierto a MD sin lista de permitidos, o
cuando una política está configurada de forma peligrosa.
### 10) Linger de systemd (Linux)
### 10) systemd linger (Linux)
Si se ejecuta como servicio de usuario de systemd, doctor asegura que linger esté habilitado para que el
gateway siga activo después de cerrar sesión.
Si se ejecuta como servicio de usuario systemd, doctor se asegura de que lingering esté habilitado para que el
gateway siga activo después del cierre de sesión.
### 11) Estado del espacio de trabajo (Skills, plugins y directorios heredados)
Doctor muestra un resumen del estado del espacio de trabajo para el agente predeterminado:
Doctor imprime un resumen del estado del espacio de trabajo para el agente predeterminado:
- **Estado de Skills**: cuenta las Skills aptas, con requisitos faltantes y bloqueadas por lista de permitidos.
- **Directorios heredados del espacio de trabajo**: advierte cuando `~/openclaw` u otros directorios heredados del espacio de trabajo
existen junto al espacio de trabajo actual.
- **Estado de plugins**: cuenta plugins cargados/deshabilitados/con error; enumera los ID de plugins con
errores; informa las capacidades de plugins integrados.
- **Estado de Skills**: cuenta Skills aptas, con requisitos faltantes y bloqueadas por la lista de permitidos.
- **Directorios heredados del espacio de trabajo**: advierte cuando existen `~/openclaw` u otros directorios heredados del espacio de trabajo
junto al espacio de trabajo actual.
- **Estado de plugins**: cuenta plugins cargados/deshabilitados/con errores; enumera los ID de plugin para cualquier
error; informa de las capacidades de los plugins del bundle.
- **Advertencias de compatibilidad de plugins**: marca plugins que tienen problemas de compatibilidad con
el tiempo de ejecución actual.
- **Diagnóstico de plugins**: muestra cualquier advertencia o error en tiempo de carga emitido por el
el runtime actual.
- **Diagnósticos de plugins**: muestra cualquier advertencia o error de carga emitido por el
registro de plugins.
### 11b) Tamaño del archivo de arranque
### 11b) Tamaño del archivo bootstrap
Doctor comprueba si los archivos de arranque del espacio de trabajo (por ejemplo `AGENTS.md`,
`CLAUDE.md` u otros archivos de contexto inyectados) están cerca o por encima del presupuesto de
caracteres configurado. Informa por archivo los recuentos de caracteres sin procesar frente a inyectados, el
porcentaje de truncamiento, la causa del truncamiento (`max/file` o `max/total`) y el total de caracteres inyectados
como fracción del presupuesto total. Cuando los archivos están truncados o cerca
del límite, doctor muestra consejos para ajustar `agents.defaults.bootstrapMaxChars`
Doctor comprueba si los archivos bootstrap del espacio de trabajo (por ejemplo `AGENTS.md`,
`CLAUDE.md` u otros archivos de contexto inyectados) están cerca o por encima del presupuesto
configurado de caracteres. Informa por archivo del recuento de caracteres sin procesar frente al inyectado, el porcentaje
de truncamiento, la causa del truncamiento (`max/file` o `max/total`) y el total de caracteres
inyectados como fracción del presupuesto total. Cuando los archivos están truncados o cerca
del límite, doctor imprime sugerencias para ajustar `agents.defaults.bootstrapMaxChars`
y `agents.defaults.bootstrapTotalMaxChars`.
### 11c) Autocompletado del shell
@ -408,103 +447,102 @@ Doctor comprueba si el autocompletado con tabulador está instalado para el shel
- Si el perfil del shell usa un patrón lento de autocompletado dinámico
(`source <(openclaw completion ...)`), doctor lo actualiza a la variante más rápida
de archivo en caché.
con archivo en caché.
- Si el autocompletado está configurado en el perfil pero falta el archivo de caché,
doctor regenera automáticamente la caché.
- Si no hay ningún autocompletado configurado, doctor solicita instalarlo
doctor regenera la caché automáticamente.
- Si no hay ningún autocompletado configurado, doctor ofrece instalarlo
(solo en modo interactivo; se omite con `--non-interactive`).
Ejecute `openclaw completion --write-state` para regenerar manualmente la caché.
Ejecuta `openclaw completion --write-state` para regenerar la caché manualmente.
### 12) Comprobaciones de autenticación del gateway (token local)
Doctor comprueba la preparación de la autenticación por token del gateway local.
Doctor comprueba la preparación de autenticación por token del gateway local.
- Si el modo de token necesita un token y no existe una fuente de token, doctor ofrece generar uno.
- Si `gateway.auth.token` está gestionado por SecretRef pero no está disponible, doctor advierte y no lo sobrescribe con texto sin formato.
- `openclaw doctor --generate-gateway-token` fuerza la generación solo cuando no hay ningún token SecretRef configurado.
- Si el modo token necesita un token y no existe una fuente de token, doctor ofrece generar uno.
- Si `gateway.auth.token` está gestionado por SecretRef pero no disponible, doctor advierte y no lo sobrescribe con texto sin formato.
- `openclaw doctor --generate-gateway-token` fuerza la generación solo cuando no hay un token SecretRef configurado.
### 12b) Reparaciones de solo lectura con reconocimiento de SecretRef
### 12b) Reparaciones de solo lectura compatibles con SecretRef
Algunos flujos de reparación necesitan inspeccionar las credenciales configuradas sin debilitar el comportamiento de fallo rápido del tiempo de ejecución.
Algunos flujos de reparación necesitan inspeccionar credenciales configuradas sin debilitar el comportamiento fail-fast del runtime.
- `openclaw doctor --fix` ahora usa el mismo modelo resumido de SecretRef de solo lectura que la familia de comandos de estado para reparaciones de configuración específicas.
- Ejemplo: la reparación de `@username` en Telegram para `allowFrom` / `groupAllowFrom` intenta usar credenciales del bot configuradas cuando están disponibles.
- Si el token del bot de Telegram está configurado mediante SecretRef pero no está disponible en la ruta actual del comando, doctor informa que la credencial está configurada-pero-no-disponible y omite la resolución automática en lugar de fallar o informar erróneamente que falta el token.
- `openclaw doctor --fix` ahora usa el mismo modelo resumido de SecretRef de solo lectura que los comandos de la familia status para reparaciones específicas de configuración.
- Ejemplo: la reparación de Telegram `allowFrom` / `groupAllowFrom` con `@username` intenta usar credenciales configuradas del bot cuando están disponibles.
- Si el token del bot de Telegram está configurado mediante SecretRef pero no está disponible en la ruta actual del comando, doctor informa que la credencial está configurada pero no disponible y omite la resolución automática en lugar de fallar o informar incorrectamente que falta el token.
### 13) Comprobación de estado del gateway + reinicio
Doctor ejecuta una comprobación de estado y ofrece reiniciar el gateway cuando parece
no estar en buen estado.
### 13b) Preparación de búsqueda en memoria
### 13b) Preparación de la búsqueda en memoria
Doctor comprueba si el proveedor de embeddings configurado para búsqueda en memoria está preparado
Doctor comprueba si el proveedor de embeddings configurado para búsqueda en memoria está listo
para el agente predeterminado. El comportamiento depende del backend y del proveedor configurados:
- **Backend QMD**: sondea si el binario `qmd` está disponible y puede iniciarse.
Si no, muestra orientación de corrección, incluido el paquete npm y una opción manual de ruta binaria.
- **Proveedor local explícito**: comprueba si existe un archivo de modelo local o una URL
reconocida de modelo remoto/descargable. Si falta, sugiere cambiar a un proveedor remoto.
Si no, imprime orientación para corregirlo, incluido el paquete npm y una opción manual de ruta al binario.
- **Proveedor local explícito**: comprueba si hay un archivo de modelo local o una URL de modelo remota/descargable reconocida. Si falta, sugiere cambiar a un proveedor remoto.
- **Proveedor remoto explícito** (`openai`, `voyage`, etc.): verifica que haya una clave de API
presente en el entorno o en el almacén de autenticación. Muestra sugerencias de corrección accionables si falta.
- **Proveedor automático**: comprueba primero la disponibilidad de modelos locales y luego prueba cada proveedor remoto
en el orden de selección automática.
presente en el entorno o en el almacén de autenticación. Imprime sugerencias de corrección accionables si falta.
- **Proveedor automático**: comprueba primero la disponibilidad del modelo local y luego prueba cada
proveedor remoto en orden de selección automática.
Cuando hay disponible un resultado de sondeo del gateway (el gateway estaba en buen estado en el momento de la
comprobación), doctor cruza ese resultado con la configuración visible desde la CLI y señala
Cuando hay disponible un resultado del sondeo del gateway (el gateway estaba en buen estado en el momento de la
comprobación), doctor lo cruza con la configuración visible desde la CLI y señala
cualquier discrepancia.
Use `openclaw memory status --deep` para verificar la preparación de embeddings en tiempo de ejecución.
Usa `openclaw memory status --deep` para verificar en runtime la preparación de embeddings.
### 14) Advertencias de estado de canales
### 14) Advertencias de estado de los canales
Si el gateway está en buen estado, doctor ejecuta un sondeo de estado de los canales e informa
Si el gateway está en buen estado, doctor ejecuta un sondeo de estado de canales e informa
advertencias con correcciones sugeridas.
### 15) Auditoría + reparación de configuración del supervisor
Doctor comprueba si la configuración del supervisor instalado (launchd/systemd/schtasks) tiene
valores predeterminados faltantes u obsoletos (por ejemplo, dependencias de systemd network-online y
Doctor comprueba la configuración instalada del supervisor (launchd/systemd/schtasks) en busca de
valores predeterminados ausentes o desactualizados (p. ej., dependencias de systemd network-online y
retraso de reinicio). Cuando encuentra una discrepancia, recomienda una actualización y puede
reescribir el archivo de servicio/tarea a los valores predeterminados actuales.
Notas:
- `openclaw doctor` solicita confirmación antes de reescribir la configuración del supervisor.
- `openclaw doctor --yes` acepta las solicitudes de reparación predeterminadas.
- `openclaw doctor --repair` aplica las correcciones recomendadas sin solicitudes.
- `openclaw doctor` pregunta antes de reescribir la configuración del supervisor.
- `openclaw doctor --yes` acepta los avisos de reparación predeterminados.
- `openclaw doctor --repair` aplica las correcciones recomendadas sin preguntas.
- `openclaw doctor --repair --force` sobrescribe configuraciones personalizadas del supervisor.
- Si la autenticación por token requiere un token y `gateway.auth.token` está gestionado por SecretRef, la instalación/reparación del servicio de doctor valida el SecretRef, pero no persiste valores resueltos de token en texto sin formato en los metadatos de entorno del servicio supervisor.
- Si la autenticación por token requiere un token y `gateway.auth.token` está gestionado por SecretRef, la instalación/reparación del servicio valida el SecretRef pero no conserva valores de token resueltos en texto sin formato en los metadatos del entorno del servicio del supervisor.
- Si la autenticación por token requiere un token y el token SecretRef configurado no está resuelto, doctor bloquea la ruta de instalación/reparación con orientación accionable.
- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados y `gateway.auth.mode` no está definido, doctor bloquea la instalación/reparación hasta que el modo se establezca explícitamente.
- Para unidades user-systemd de Linux, las comprobaciones de deriva de token de doctor ahora incluyen tanto fuentes `Environment=` como `EnvironmentFile=` al comparar metadatos de autenticación del servicio.
- Siempre puede forzar una reescritura completa mediante `openclaw gateway install --force`.
- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados y `gateway.auth.mode` no está establecido, doctor bloquea la instalación/reparación hasta que el modo se configure explícitamente.
- Para unidades user-systemd en Linux, las comprobaciones de divergencia del token de doctor ahora incluyen tanto las fuentes `Environment=` como `EnvironmentFile=` al comparar metadatos de autenticación del servicio.
- Siempre puedes forzar una reescritura completa mediante `openclaw gateway install --force`.
### 16) Diagnóstico del tiempo de ejecución del gateway + puerto
### 16) Diagnósticos del runtime del gateway + puerto
Doctor inspecciona el tiempo de ejecución del servicio (PID, último estado de salida) y advierte cuando el
Doctor inspecciona el runtime del servicio (PID, último estado de salida) y advierte cuando el
servicio está instalado pero en realidad no se está ejecutando. También comprueba colisiones
de puerto en el puerto del gateway (predeterminado `18789`) e informa causas probables (gateway ya
de puertos en el puerto del gateway (predeterminado `18789`) e informa causas probables (gateway ya
en ejecución, túnel SSH).
### 17) Buenas prácticas del tiempo de ejecución del gateway
### 17) Buenas prácticas del runtime del gateway
Doctor advierte cuando el servicio del gateway se ejecuta con Bun o con una ruta de Node gestionada por versiones
Doctor advierte cuando el servicio del gateway se ejecuta con Bun o una ruta de Node gestionada por versiones
(`nvm`, `fnm`, `volta`, `asdf`, etc.). Los canales de WhatsApp + Telegram requieren Node,
y las rutas de gestores de versiones pueden fallar después de actualizaciones porque el servicio no
carga la inicialización de su shell. Doctor ofrece migrar a una instalación de Node del sistema cuando
carga la inicialización de tu shell. Doctor ofrece migrar a una instalación de Node del sistema cuando
está disponible (Homebrew/apt/choco).
### 18) Escritura de configuración + metadatos del asistente
Doctor conserva cualquier cambio de configuración y marca metadatos del asistente para registrar la
ejecución de doctor.
Doctor guarda cualquier cambio de configuración y registra metadatos del asistente para anotar la ejecución
de doctor.
### 19) Consejos del espacio de trabajo (copia de seguridad + sistema de memoria)
### 19) Sugerencias del espacio de trabajo (copia de seguridad + sistema de memoria)
Doctor sugiere un sistema de memoria del espacio de trabajo cuando falta y muestra un consejo de copia de seguridad
si el espacio de trabajo todavía no está bajo git.
Doctor sugiere un sistema de memoria para el espacio de trabajo cuando falta y muestra una sugerencia de copia de seguridad
si el espacio de trabajo aún no está bajo git.
Consulte [/concepts/agent-workspace](/es/concepts/agent-workspace) para ver una guía completa sobre
la estructura del espacio de trabajo y la copia de seguridad con git (se recomienda GitHub o GitLab privados).
Consulta [/concepts/agent-workspace](/es/concepts/agent-workspace) para obtener una guía completa sobre la
estructura del espacio de trabajo y la copia de seguridad con git (se recomienda GitHub o GitLab privados).

606
docs/es/help/testing.md
View File

File diff suppressed because it is too large Load Diff

584
docs/es/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md
View File

@ -1,584 +0,0 @@
---
date: 2026-04-05T00:00:00Z
status: active
title: 'refactor: Convertir plugin-sdk en un paquete real del workspace de forma incremental'
type: refactor
x-i18n:
generated_at: "2026-04-07T05:04:02Z"
model: gpt-5.4
provider: openai
source_hash: ea1ca41846363c506a0db6dbca746e840d7c71ca82bbfc5277af9e2ae7f6b070
source_path: plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md
workflow: 15
---
# refactor: Convertir plugin-sdk en un paquete real del workspace de forma incremental
## Descripción general
Este plan introduce un paquete real del workspace para el SDK de plugins en
`packages/plugin-sdk` y lo usa para incorporar una pequeña primera ola de extensiones a
límites de paquetes aplicados por el compilador. El objetivo es hacer que las
importaciones relativas no permitidas fallen bajo `tsc` normal para un conjunto seleccionado de extensiones
de proveedor empaquetadas, sin forzar una migración en todo el repositorio ni una enorme
superficie de conflictos de fusión.
El movimiento incremental clave es ejecutar dos modos en paralelo durante un tiempo:
| Modo legado | Forma de importación | Quién lo usa | Aplicación |
| ----------- | -------------------------- | ------------------------------------ | --------------------------------------------- |
| Modo legado | `openclaw/plugin-sdk/*` | todas las extensiones existentes no incorporadas | se mantiene el comportamiento permisivo actual |
| Modo opt-in | `@openclaw/plugin-sdk/*` | solo las extensiones de la primera ola | `rootDir` local al paquete + referencias de proyecto |
## Planteamiento del problema
El repositorio actual exporta una gran superficie pública del SDK de plugins, pero no es un
paquete real del workspace. En su lugar:
- el `tsconfig.json` raíz asigna `openclaw/plugin-sdk/*` directamente a
`src/plugin-sdk/*.ts`
- las extensiones que no se incorporaron al experimento anterior siguen compartiendo ese
comportamiento global de alias de origen
- agregar `rootDir` solo funciona cuando las importaciones permitidas del SDK dejan de resolverse hacia código fuente
sin procesar del repositorio
Eso significa que el repositorio puede describir la política de límites deseada, pero TypeScript
no la aplica limpiamente para la mayoría de las extensiones.
Quieres una ruta incremental que:
- convierta `plugin-sdk` en algo real
- mueva el SDK hacia un paquete del workspace llamado `@openclaw/plugin-sdk`
- cambie solo alrededor de 10 extensiones en el primer PR
- deje el resto del árbol de extensiones en el esquema antiguo hasta una limpieza posterior
- evite el flujo de trabajo `tsconfig.plugin-sdk.dts.json` + declaraciones generadas en postinstall
como mecanismo principal para el despliegue de la primera ola
## Trazabilidad de requisitos
- R1. Crear un paquete real del workspace para el SDK bajo `packages/`.
- R2. Nombrar el nuevo paquete `@openclaw/plugin-sdk`.
- R3. Dar al nuevo paquete SDK su propio `package.json` y `tsconfig.json`.
- R4. Mantener las importaciones heredadas `openclaw/plugin-sdk/*` funcionando para las extensiones
no incorporadas durante la ventana de migración.
- R5. Incorporar solo una pequeña primera ola de extensiones en el primer PR.
- R6. Las extensiones de la primera ola deben fallar de forma cerrada para las importaciones relativas que salgan
de la raíz de su paquete.
- R7. Las extensiones de la primera ola deben consumir el SDK mediante una
dependencia de paquete y una referencia de proyecto de TS, no mediante alias `paths` de la raíz.
- R8. El plan debe evitar un paso obligatorio de generación en postinstall para todo el repositorio
para la corrección en el editor.
- R9. El despliegue de la primera ola debe ser revisable e integrable como un PR moderado,
no como una refactorización de más de 300 archivos en todo el repositorio.
## Límites del alcance
- No migrar completamente todas las extensiones empaquetadas en el primer PR.
- No es necesario eliminar `src/plugin-sdk` en el primer PR.
- No es necesario reconfigurar inmediatamente cada ruta de compilación o prueba raíz para usar el nuevo paquete.
- No se intenta forzar errores visuales de VS Code para todas las extensiones no incorporadas.
- No hay limpieza amplia de lint para el resto del árbol de extensiones.
- No hay cambios grandes en el comportamiento en tiempo de ejecución más allá de la resolución de importaciones, la
propiedad del paquete y la aplicación de límites para las extensiones incorporadas.
## Contexto e investigación
### Código y patrones relevantes
- `pnpm-workspace.yaml` ya incluye `packages/*` y `extensions/*`, por lo que un
nuevo paquete del workspace bajo `packages/plugin-sdk` encaja en el diseño existente del
repositorio.
- Los paquetes existentes del workspace, como `packages/memory-host-sdk/package.json`
y `packages/plugin-package-contract/package.json`, ya usan mapas `exports` locales al paquete
enraizados en `src/*.ts`.
- El `package.json` raíz actualmente publica la superficie del SDK mediante `./plugin-sdk`
y `./plugin-sdk/*` exports respaldados por `dist/plugin-sdk/*.js` y
`dist/plugin-sdk/*.d.ts`.
- `src/plugin-sdk/entrypoints.ts` y `scripts/lib/plugin-sdk-entrypoints.json`
ya actúan como el inventario canónico de entrypoints para la superficie del SDK.
- El `tsconfig.json` raíz actualmente asigna:
- `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts`
- `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts`
- El experimento anterior de límites mostró que `rootDir` local al paquete funciona para
importaciones relativas no permitidas solo después de que las importaciones permitidas del SDK dejan de resolverse hacia código fuente
sin procesar fuera del paquete de extensión.
### Conjunto de extensiones de la primera ola
Este plan asume que la primera ola es el conjunto con muchos proveedores que tiene menos probabilidades
de arrastrar casos límite complejos del tiempo de ejecución de canales:
- `extensions/anthropic`
- `extensions/exa`
- `extensions/firecrawl`
- `extensions/groq`
- `extensions/mistral`
- `extensions/openai`
- `extensions/perplexity`
- `extensions/tavily`
- `extensions/together`
- `extensions/xai`
### Inventario de superficie del SDK de la primera ola
Las extensiones de la primera ola actualmente importan un subconjunto manejable de subrutas del SDK.
El paquete inicial `@openclaw/plugin-sdk` solo necesita cubrir estas:
- `agent-runtime`
- `cli-runtime`
- `config-runtime`
- `core`
- `image-generation`
- `media-runtime`
- `media-understanding`
- `plugin-entry`
- `plugin-runtime`
- `provider-auth`
- `provider-auth-api-key`
- `provider-auth-login`
- `provider-auth-runtime`
- `provider-catalog-shared`
- `provider-entry`
- `provider-http`
- `provider-model-shared`
- `provider-onboard`
- `provider-stream-family`
- `provider-stream-shared`
- `provider-tools`
- `provider-usage`
- `provider-web-fetch`
- `provider-web-search`
- `realtime-transcription`
- `realtime-voice`
- `runtime-env`
- `secret-input`
- `security-runtime`
- `speech`
- `testing`
### Aprendizajes institucionales
- No había entradas relevantes en `docs/solutions/` en este árbol de trabajo.
### Referencias externas
- No fue necesaria investigación externa para este plan. El repositorio ya contiene los
patrones relevantes de paquete del workspace y exportación del SDK.
## Decisiones técnicas clave
- Introducir `@openclaw/plugin-sdk` como un nuevo paquete del workspace mientras se mantiene activa la
superficie heredada raíz `openclaw/plugin-sdk/*` durante la migración.
Justificación: esto permite que un conjunto de extensiones de la primera ola pase a una resolución real de paquetes
sin forzar que todas las extensiones y todas las rutas de compilación raíz cambien
de una sola vez.
- Usar una configuración base dedicada de límites opt-in, como
`extensions/tsconfig.package-boundary.base.json`, en lugar de reemplazar la
base existente de extensiones para todos.
Justificación: el repositorio necesita admitir simultáneamente tanto el modo heredado como el opt-in para extensiones
durante la migración.
- Usar referencias de proyecto de TS desde las extensiones de la primera ola hacia
`packages/plugin-sdk/tsconfig.json` y establecer
`disableSourceOfProjectReferenceRedirect` para el modo opt-in de límites.
Justificación: esto da a `tsc` un grafo real de paquetes mientras desalienta al editor y
al compilador de recurrir al recorrido del código fuente sin procesar.
- Mantener `@openclaw/plugin-sdk` como privado en la primera ola.
Justificación: el objetivo inmediato es la aplicación interna de límites y la seguridad de migración,
no publicar un segundo contrato externo del SDK antes de que la superficie sea
estable.
- Mover solo las subrutas del SDK de la primera ola en el primer corte de implementación, y
mantener puentes de compatibilidad para el resto.
Justificación: mover físicamente los 315 archivos `src/plugin-sdk/*.ts` en un solo PR es
exactamente la superficie de conflicto de fusión que este plan intenta evitar.
- No depender de `scripts/postinstall-bundled-plugins.mjs` para construir
declaraciones del SDK para la primera ola.
Justificación: los flujos explícitos de compilación/referencia son más fáciles de razonar y mantienen
el comportamiento del repositorio más predecible.
## Preguntas abiertas
### Resueltas durante la planificación
- ¿Qué extensiones deben estar en la primera ola?
Usar las 10 extensiones de proveedor/búsqueda web enumeradas arriba porque están más
aisladas estructuralmente que los paquetes de canal más pesados.
- ¿Debe el primer PR reemplazar todo el árbol de extensiones?
No. El primer PR debe admitir dos modos en paralelo e incorporar solo la
primera ola.
- ¿Debe la primera ola requerir una compilación de declaraciones en postinstall?
No. El grafo de paquete/referencia debe ser explícito, y CI debe ejecutar
intencionalmente la verificación de tipos local al paquete correspondiente.
### Aplazadas para la implementación
- Si el paquete de la primera ola puede apuntar directamente a `src/*.ts` local al paquete
solo mediante referencias de proyecto, o si aún se requiere un pequeño paso de emisión de declaraciones
para el paquete `@openclaw/plugin-sdk`.
Esta es una cuestión de validación del grafo de TS propia de la implementación.
- Si el paquete raíz `openclaw` debe redirigir inmediatamente las subrutas del SDK de la primera ola a
las salidas de `packages/plugin-sdk` o seguir usando shims de compatibilidad generados bajo `src/plugin-sdk`.
Este es un detalle de compatibilidad y forma de compilación que depende de la
ruta mínima de implementación que mantenga CI en verde.
## Diseño técnico de alto nivel
> Esto ilustra el enfoque previsto y sirve como guía direccional para la revisión, no como especificación de implementación. El agente encargado de implementar debe tratarlo como contexto, no como código para reproducir.
```mermaid
flowchart TB
subgraph Legacy["Extensiones heredadas (sin cambios)"]
L1["extensions/*\nopenclaw/plugin-sdk/*"]
L2["root tsconfig paths"]
L1 --> L2
L2 --> L3["src/plugin-sdk/*"]
end
subgraph OptIn["Extensiones de la primera ola"]
O1["10 extensiones incorporadas"]
O2["extensions/tsconfig.package-boundary.base.json"]
O3["rootDir = '.'\nproject reference"]
O4["@openclaw/plugin-sdk"]
O1 --> O2
O2 --> O3
O3 --> O4
end
subgraph SDK["Nuevo paquete del workspace"]
P1["packages/plugin-sdk/package.json"]
P2["packages/plugin-sdk/tsconfig.json"]
P3["packages/plugin-sdk/src/<first-wave-subpaths>.ts"]
P1 --> P2
P2 --> P3
end
O4 --> SDK
```
## Unidades de implementación
- [ ] **Unidad 1: Introducir el paquete real del workspace `@openclaw/plugin-sdk`**
**Objetivo:** Crear un paquete real del workspace para el SDK que pueda ser propietario de la
superficie de subrutas de la primera ola sin forzar una migración en todo el repositorio.
**Requisitos:** R1, R2, R3, R8, R9
**Dependencias:** Ninguna
**Archivos:**
- Crear: `packages/plugin-sdk/package.json`
- Crear: `packages/plugin-sdk/tsconfig.json`
- Crear: `packages/plugin-sdk/src/index.ts`
- Crear: `packages/plugin-sdk/src/*.ts` para las subrutas del SDK de la primera ola
- Modificar: `pnpm-workspace.yaml` solo si se necesitan ajustes en los globs de paquetes
- Modificar: `package.json`
- Modificar: `src/plugin-sdk/entrypoints.ts`
- Modificar: `scripts/lib/plugin-sdk-entrypoints.json`
- Probar: `src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts`
**Enfoque:**
- Agregar un nuevo paquete del workspace llamado `@openclaw/plugin-sdk`.
- Comenzar solo con las subrutas del SDK de la primera ola, no con todo el árbol de 315 archivos.
- Si mover directamente un entrypoint de la primera ola creara un diff demasiado grande, el
primer PR puede introducir primero esa subruta en `packages/plugin-sdk/src` como un wrapper
delgado del paquete y luego cambiar la fuente de verdad al paquete en un PR de seguimiento
para ese grupo de subrutas.
- Reutilizar la maquinaria existente de inventario de entrypoints para que la superficie del paquete de la primera ola
se declare en un único lugar canónico.
- Mantener activas las exportaciones del paquete raíz para los usuarios heredados mientras el paquete del workspace
se convierte en el nuevo contrato opt-in.
**Patrones a seguir:**
- `packages/memory-host-sdk/package.json`
- `packages/plugin-package-contract/package.json`
- `src/plugin-sdk/entrypoints.ts`
**Escenarios de prueba:**
- Caso satisfactorio: el paquete del workspace exporta cada subruta de la primera ola enumerada
en el plan y no falta ninguna exportación requerida de la primera ola.
- Caso límite: los metadatos de exportación del paquete permanecen estables cuando la lista de entradas de la primera ola
se vuelve a generar o se compara con el inventario canónico.
- Integración: las exportaciones heredadas del SDK en el paquete raíz siguen presentes tras introducir
el nuevo paquete del workspace.
**Verificación:**
- El repositorio contiene un paquete válido del workspace `@openclaw/plugin-sdk` con un
mapa estable de exportaciones de la primera ola y sin regresión de exportaciones heredadas en el
`package.json` raíz.
- [ ] **Unidad 2: Agregar un modo opt-in de límites de TS para extensiones con aplicación por paquete**
**Objetivo:** Definir el modo de configuración de TS que usarán las extensiones incorporadas,
mientras se deja sin cambios el comportamiento existente de TS para extensiones del resto.
**Requisitos:** R4, R6, R7, R8, R9
**Dependencias:** Unidad 1
**Archivos:**
- Crear: `extensions/tsconfig.package-boundary.base.json`
- Crear: `tsconfig.boundary-optin.json`
- Modificar: `extensions/xai/tsconfig.json`
- Modificar: `extensions/openai/tsconfig.json`
- Modificar: `extensions/anthropic/tsconfig.json`
- Modificar: `extensions/mistral/tsconfig.json`
- Modificar: `extensions/groq/tsconfig.json`
- Modificar: `extensions/together/tsconfig.json`
- Modificar: `extensions/perplexity/tsconfig.json`
- Modificar: `extensions/tavily/tsconfig.json`
- Modificar: `extensions/exa/tsconfig.json`
- Modificar: `extensions/firecrawl/tsconfig.json`
- Probar: `src/plugins/contracts/extension-package-project-boundaries.test.ts`
- Probar: `test/extension-package-tsc-boundary.test.ts`
**Enfoque:**
- Dejar `extensions/tsconfig.base.json` en su lugar para las extensiones heredadas.
- Agregar una nueva configuración base opt-in que:
- establezca `rootDir: "."`
- haga referencia a `packages/plugin-sdk`
- habilite `composite`
- deshabilite la redirección de fuente de referencia de proyecto cuando sea necesario
- Agregar una configuración de solución dedicada para el grafo de typecheck de la primera ola en lugar de
reformar el proyecto TS raíz del repositorio en el mismo PR.
**Nota de ejecución:** comenzar con una comprobación canaria fallida de typecheck local al paquete para una
extensión incorporada antes de aplicar el patrón a las 10.
**Patrones a seguir:**
- Patrón existente de `tsconfig.json` local a extensiones del trabajo anterior
de límites
- Patrón de paquete del workspace de `packages/memory-host-sdk`
**Escenarios de prueba:**
- Caso satisfactorio: cada extensión incorporada supera correctamente el typecheck mediante la
configuración TS de límites de paquete.
- Ruta de error: una importación relativa canaria desde `../../src/cli/acp-cli.ts` falla
con `TS6059` para una extensión incorporada.
- Integración: las extensiones no incorporadas permanecen intactas y no necesitan
participar todavía en la nueva configuración de solución.
**Verificación:**
- Existe un grafo de typecheck dedicado para las 10 extensiones incorporadas, y las
malas importaciones relativas desde una de ellas fallan mediante `tsc` normal.
- [ ] **Unidad 3: Migrar las extensiones de la primera ola a `@openclaw/plugin-sdk`**
**Objetivo:** Cambiar las extensiones de la primera ola para que consuman el paquete real del SDK
mediante metadatos de dependencia, referencias de proyecto e importaciones por nombre de paquete.
**Requisitos:** R5, R6, R7, R9
**Dependencias:** Unidad 2
**Archivos:**
- Modificar: `extensions/anthropic/package.json`
- Modificar: `extensions/exa/package.json`
- Modificar: `extensions/firecrawl/package.json`
- Modificar: `extensions/groq/package.json`
- Modificar: `extensions/mistral/package.json`
- Modificar: `extensions/openai/package.json`
- Modificar: `extensions/perplexity/package.json`
- Modificar: `extensions/tavily/package.json`
- Modificar: `extensions/together/package.json`
- Modificar: `extensions/xai/package.json`
- Modificar: las importaciones de producción y prueba bajo cada una de las 10 raíces de extensión que
actualmente hacen referencia a `openclaw/plugin-sdk/*`
**Enfoque:**
- Agregar `@openclaw/plugin-sdk: workspace:*` a `devDependencies` de las extensiones
de la primera ola.
- Reemplazar las importaciones `openclaw/plugin-sdk/*` en esos paquetes por
`@openclaw/plugin-sdk/*`.
- Mantener las importaciones internas locales de la extensión en barriles locales como `./api.ts` y
`./runtime-api.ts`.
- No cambiar las extensiones no incorporadas en este PR.
**Patrones a seguir:**
- Barriles existentes de importación local de extensiones (`api.ts`, `runtime-api.ts`)
- Forma de dependencia de paquete usada por otros paquetes del workspace `@openclaw/*`
**Escenarios de prueba:**
- Caso satisfactorio: cada extensión migrada sigue registrándose/cargándose mediante sus pruebas
existentes del plugin después de la reescritura de importaciones.
- Caso límite: las importaciones del SDK solo para pruebas en el conjunto de extensiones incorporadas siguen resolviéndose
correctamente mediante el nuevo paquete.
- Integración: las extensiones migradas no requieren alias raíz `openclaw/plugin-sdk/*`
para el typechecking.
**Verificación:**
- Las extensiones de la primera ola compilan y se prueban contra `@openclaw/plugin-sdk`
sin necesitar la ruta heredada de alias del SDK en la raíz.
- [ ] **Unidad 4: Preservar la compatibilidad heredada mientras la migración es parcial**
**Objetivo:** Mantener el resto del repositorio funcionando mientras el SDK existe tanto en forma heredada
como en forma de nuevo paquete durante la migración.
**Requisitos:** R4, R8, R9
**Dependencias:** Unidades 1-3
**Archivos:**
- Modificar: `src/plugin-sdk/*.ts` para shims de compatibilidad de la primera ola según sea necesario
- Modificar: `package.json`
- Modificar: la infraestructura de compilación o exportación que ensambla los artefactos del SDK
- Probar: `src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts`
- Probar: `src/plugins/contracts/plugin-sdk-index.bundle.test.ts`
**Enfoque:**
- Mantener `openclaw/plugin-sdk/*` en la raíz como superficie de compatibilidad para las
extensiones heredadas y para consumidores externos que aún no se están moviendo.
- Usar ya sea shims generados o cableado de proxy de exportación raíz para las subrutas
de la primera ola que se hayan movido a `packages/plugin-sdk`.
- No intentar retirar la superficie del SDK en la raíz en esta fase.
**Patrones a seguir:**
- Generación existente de exportaciones del SDK raíz mediante `src/plugin-sdk/entrypoints.ts`
- Compatibilidad existente de exportación de paquetes en el `package.json` raíz
**Escenarios de prueba:**
- Caso satisfactorio: una importación heredada del SDK raíz sigue resolviéndose para una extensión
no incorporada después de que exista el nuevo paquete.
- Caso límite: una subruta de la primera ola funciona tanto mediante la superficie heredada raíz como
mediante la nueva superficie del paquete durante la ventana de migración.
- Integración: las pruebas de contrato del índice/bundle de plugin-sdk siguen viendo una
superficie pública coherente.
**Verificación:**
- El repositorio admite tanto modos heredados como modos opt-in de consumo del SDK sin
romper las extensiones no modificadas.
- [ ] **Unidad 5: Agregar aplicación acotada y documentar el contrato de migración**
**Objetivo:** Incorporar CI y una guía para contribuidores que apliquen el nuevo comportamiento para la
primera ola sin fingir que todo el árbol de extensiones ya está migrado.
**Requisitos:** R5, R6, R8, R9
**Dependencias:** Unidades 1-4
**Archivos:**
- Modificar: `package.json`
- Modificar: los archivos de workflow de CI que deben ejecutar el typecheck opt-in de límites
- Modificar: `AGENTS.md`
- Modificar: `docs/plugins/sdk-overview.md`
- Modificar: `docs/plugins/sdk-entrypoints.md`
- Modificar: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md`
**Enfoque:**
- Agregar una compuerta explícita para la primera ola, como una ejecución dedicada de `tsc -b` para
`packages/plugin-sdk` más las 10 extensiones incorporadas.
- Documentar que el repositorio ahora admite tanto modos heredados como modos opt-in de extensiones,
y que el nuevo trabajo de límites de extensiones debe preferir la nueva ruta de paquete.
- Registrar la regla de migración de la siguiente ola para que PR posteriores puedan agregar más extensiones
sin volver a debatir la arquitectura.
**Patrones a seguir:**
- Pruebas de contrato existentes bajo `src/plugins/contracts/`
- Actualizaciones existentes de documentación que explican migraciones por etapas
**Escenarios de prueba:**
- Caso satisfactorio: la nueva compuerta de typecheck de la primera ola pasa para el paquete del workspace
y las extensiones incorporadas.
- Ruta de error: introducir una nueva importación relativa no permitida en una
extensión incorporada hace fallar la compuerta de typecheck acotada.
- Integración: CI aún no exige que las extensiones no incorporadas satisfagan el nuevo
modo de límites de paquete.
**Verificación:**
- La ruta de aplicación de la primera ola está documentada, probada y se puede ejecutar sin
obligar a migrar todo el árbol de extensiones.
## Impacto en todo el sistema
- **Grafo de interacción:** este trabajo toca la fuente de verdad del SDK, las
exportaciones del paquete raíz, los metadatos de paquetes de extensiones, el diseño del grafo de TS y la verificación en CI.
- **Propagación de errores:** el modo principal de fallo previsto pasa a ser errores de TS en tiempo de compilación
(`TS6059`) en extensiones incorporadas en lugar de fallos solo de scripts personalizados.
- **Riesgos del ciclo de vida del estado:** la migración de doble superficie introduce riesgo de divergencia entre
las exportaciones de compatibilidad raíz y el nuevo paquete del workspace.
- **Paridad de superficie de API:** las subrutas de la primera ola deben seguir siendo semánticamente idénticas
tanto a través de `openclaw/plugin-sdk/*` como de `@openclaw/plugin-sdk/*` durante la
transición.
- **Cobertura de integración:** las pruebas unitarias no son suficientes; se requieren typechecks
acotados del grafo de paquetes para demostrar el límite.
- **Invariantes sin cambios:** las extensiones no incorporadas mantienen su comportamiento actual
en el PR 1. Este plan no afirma una aplicación de límites de importación en todo el repositorio.
## Riesgos y dependencias
| Riesgo | Mitigación |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| El paquete de la primera ola sigue resolviéndose hacia código fuente sin procesar y `rootDir` en realidad no falla de forma cerrada | Hacer que el primer paso de implementación sea un canario de referencia de paquete sobre una extensión incorporada antes de ampliarlo al conjunto completo |
| Mover demasiado código fuente del SDK de una vez recrea el problema original de conflictos de fusión | Mover solo las subrutas de la primera ola en el primer PR y mantener puentes de compatibilidad en la raíz |
| Las superficies heredadas y nuevas del SDK divergen semánticamente | Mantener un único inventario de entrypoints, agregar pruebas de contrato de compatibilidad y hacer explícita la paridad de doble superficie |
| Las rutas de compilación/prueba del repositorio raíz empiezan accidentalmente a depender del nuevo paquete de formas no controladas | Usar una configuración de solución opt-in dedicada y mantener fuera del primer PR los cambios de topología TS para todo el repositorio |
## Entrega por fases
### Fase 1
- Introducir `@openclaw/plugin-sdk`
- Definir la superficie de subrutas de la primera ola
- Demostrar que una extensión incorporada puede fallar de forma cerrada mediante `rootDir`
### Fase 2
- Incorporar las 10 extensiones de la primera ola
- Mantener activa la compatibilidad en la raíz para todos los demás
### Fase 3
- Agregar más extensiones en PR posteriores
- Mover más subrutas del SDK al paquete del workspace
- Retirar la compatibilidad en la raíz solo después de que desaparezca el conjunto heredado de extensiones
## Notas operativas / de documentación
- El primer PR debe describirse explícitamente como una migración de modo dual, no como la
finalización de la aplicación en todo el repositorio.
- La guía de migración debe facilitar que PR posteriores agreguen más extensiones
siguiendo el mismo patrón de paquete/dependencia/referencia.
## Fuentes y referencias
- Plan previo: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md`
- Configuración del workspace: `pnpm-workspace.yaml`
- Inventario existente de entrypoints del SDK: `src/plugin-sdk/entrypoints.ts`
- Exportaciones existentes del SDK raíz: `package.json`
- Patrones existentes de paquetes del workspace:
- `packages/memory-host-sdk/package.json`
- `packages/plugin-package-contract/package.json`

1175
docs/es/plugins/architecture.md
View File

File diff suppressed because it is too large Load Diff

311
docs/es/plugins/manifest.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Estás creando un plugin de OpenClaw
- Necesitas distribuir un esquema de configuración del plugin o depurar errores de validación del plugin
- Necesitas distribuir un esquema de configuración de plugin o depurar errores de validación de plugins
summary: Manifiesto del plugin + requisitos del esquema JSON (validación estricta de configuración)
title: Manifiesto del plugin
x-i18n:
generated_at: "2026-04-07T05:04:40Z"
generated_at: "2026-04-09T01:28:54Z"
model: gpt-5.4
provider: openai
source_hash: 22d41b9f8748b1b1b066ee856be4a8f41e88b9a8bc073d74fc79d2bb0982f01a
source_hash: 9a7ee4b621a801d2a8f32f8976b0e1d9433c7810eb360aca466031fc0ffb286a
source_path: plugins/manifest.md
workflow: 15
---
@ -19,7 +19,7 @@ Esta página es solo para el **manifiesto nativo de plugins de OpenClaw**.
Para diseños de paquetes compatibles, consulta [Paquetes de plugins](/es/plugins/bundles).
Los formatos de paquetes compatibles usan archivos de manifiesto distintos:
Los formatos de paquetes compatibles usan archivos de manifiesto diferentes:
- Paquete Codex: `.codex-plugin/plugin.json`
- Paquete Claude: `.claude-plugin/plugin.json` o el diseño predeterminado de componentes de Claude
@ -27,20 +27,20 @@ Los formatos de paquetes compatibles usan archivos de manifiesto distintos:
- Paquete Cursor: `.cursor-plugin/plugin.json`
OpenClaw también detecta automáticamente esos diseños de paquetes, pero no se validan
contra el esquema `openclaw.plugin.json` descrito aquí.
con el esquema `openclaw.plugin.json` descrito aquí.
Para los paquetes compatibles, OpenClaw actualmente lee los metadatos del paquete más las raíces de
Skills declaradas, las raíces de comandos de Claude, los valores predeterminados de `settings.json` del paquete Claude,
los valores predeterminados de LSP del paquete Claude y los paquetes de hooks compatibles cuando el diseño coincide
con las expectativas de ejecución de OpenClaw.
Para los paquetes compatibles, OpenClaw actualmente lee los metadatos del paquete más las
raíces de Skills declaradas, las raíces de comandos de Claude, los valores predeterminados de `settings.json` del paquete Claude,
los valores predeterminados de LSP del paquete Claude y los paquetes de hooks compatibles cuando el diseño coincide con
las expectativas del entorno de ejecución de OpenClaw.
Todo plugin nativo de OpenClaw **debe** incluir un archivo `openclaw.plugin.json` en la
**raíz del plugin**. OpenClaw usa este manifiesto para validar la configuración
**sin ejecutar código del plugin**. Los manifiestos ausentes o no válidos se tratan como
errores del plugin y bloquean la validación de la configuración.
**sin ejecutar el código del plugin**. Los manifiestos faltantes o no válidos se tratan como
errores del plugin y bloquean la validación de configuración.
Consulta la guía completa del sistema de plugins: [Plugins](/es/tools/plugin).
Para el modelo de capacidades nativas y la guía actual de compatibilidad externa:
Para el modelo nativo de capacidades y la guía actual de compatibilidad externa:
[Modelo de capacidades](/es/plugins/architecture#public-capability-model).
## Qué hace este archivo
@ -52,24 +52,24 @@ código de tu plugin.
- identidad del plugin
- validación de configuración
- metadatos de autenticación e incorporación que deban estar disponibles sin iniciar el
tiempo de ejecución del plugin
- metadatos de alias y activación automática que deban resolverse antes de que se cargue el tiempo de ejecución del plugin
- metadatos abreviados de propiedad de familias de modelos que deban activar automáticamente el
plugin antes de que se cargue el tiempo de ejecución
- instantáneas estáticas de propiedad de capacidades usadas para el cableado de compatibilidad integrado y
- metadatos de autenticación e incorporación que deben estar disponibles sin iniciar el
entorno de ejecución del plugin
- metadatos de alias y autoactivación que deben resolverse antes de que se cargue el entorno de ejecución del plugin
- metadatos abreviados de pertenencia de familias de modelos que deben activar automáticamente el
plugin antes de que se cargue el entorno de ejecución
- instantáneas estáticas de pertenencia de capacidades usadas para el cableado de compatibilidad incluido y
la cobertura de contratos
- metadatos de configuración específicos del canal que deban fusionarse en las superficies
de catálogo y validación sin cargar el tiempo de ejecución
- pistas de UI de configuración
- metadatos de configuración específicos del canal que deben fusionarse en el catálogo y las superficies de validación
sin cargar el entorno de ejecución
- sugerencias de UI de configuración
No lo uses para:
- registrar comportamiento en tiempo de ejecución
- declarar entrypoints de código
- metadatos de instalación npm
- declarar puntos de entrada de código
- metadatos de instalación de npm
Eso corresponde al código de tu plugin y a `package.json`.
Eso pertenece al código de tu plugin y a `package.json`.
## Ejemplo mínimo
@ -90,7 +90,7 @@ Eso corresponde al código de tu plugin y a `package.json`.
{
"id": "openrouter",
"name": "OpenRouter",
"description": "Plugin de proveedor de OpenRouter",
"description": "Plugin de proveedor OpenRouter",
"version": "1.0.0",
"providers": ["openrouter"],
"modelSupport": {
@ -100,6 +100,9 @@ Eso corresponde al código de tu plugin y a `package.json`.
"providerAuthEnvVars": {
"openrouter": ["OPENROUTER_API_KEY"]
},
"providerAuthAliases": {
"openrouter-coding": "openrouter"
},
"channelEnvVars": {
"openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
},
@ -108,19 +111,19 @@ Eso corresponde al código de tu plugin y a `package.json`.
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
"choiceLabel": "Clave de API de OpenRouter",
"choiceLabel": "Clave API de OpenRouter",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key <key>",
"cliDescription": "Clave de API de OpenRouter",
"cliDescription": "Clave API de OpenRouter",
"onboardingScopes": ["text-inference"]
}
],
"uiHints": {
"apiKey": {
"label": "Clave de API",
"label": "Clave API",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@ -141,61 +144,62 @@ Eso corresponde al código de tu plugin y a `package.json`.
| Field | Required | Type | What it means |
| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Sí | `string` | ID canónico del plugin. Este es el ID usado en `plugins.entries.<id>`. |
| `id` | Sí | `string` | Id canónico del plugin. Este es el id usado en `plugins.entries.<id>`. |
| `configSchema` | Sí | `object` | JSON Schema en línea para la configuración de este plugin. |
| `enabledByDefault` | No | `true` | Marca un plugin integrado como habilitado de forma predeterminada. Omítelo, o establece cualquier valor distinto de `true`, para dejar el plugin deshabilitado de forma predeterminada. |
| `legacyPluginIds` | No | `string[]` | IDs heredados que se normalizan a este ID canónico del plugin. |
| `autoEnableWhenConfiguredProviders` | No | `string[]` | IDs de proveedor que deberían habilitar automáticamente este plugin cuando la autenticación, la configuración o las referencias de modelo los mencionen. |
| `kind` | No | `"memory"` \| `"context-engine"` | Declara un tipo exclusivo de plugin usado por `plugins.slots.*`. |
| `channels` | No | `string[]` | IDs de canal controlados por este plugin. Se usan para descubrimiento y validación de configuración. |
| `providers` | No | `string[]` | IDs de proveedor controlados por este plugin. |
| `modelSupport` | No | `object` | Metadatos abreviados de familia de modelos controlados por el manifiesto usados para cargar automáticamente el plugin antes del tiempo de ejecución. |
| `cliBackends` | No | `string[]` | IDs de backend de inferencia de CLI controlados por este plugin. Se usan para la activación automática al inicio a partir de referencias explícitas de configuración. |
| `providerAuthEnvVars` | No | `Record<string, string[]>` | Metadatos ligeros de autenticación de proveedor en variables de entorno que OpenClaw puede inspeccionar sin cargar el código del plugin. |
| `channelEnvVars` | No | `Record<string, string[]>` | Metadatos ligeros de variables de entorno del canal que OpenClaw puede inspeccionar sin cargar el código del plugin. Usa esto para superficies de configuración o autenticación de canal basadas en entorno que los ayudantes genéricos de inicio/configuración deberían ver. |
| `providerAuthChoices` | No | `object[]` | Metadatos ligeros de opciones de autenticación para selectores de incorporación, resolución de proveedor preferido y cableado simple de flags de CLI. |
| `contracts` | No | `object` | Instantánea estática de capacidades integradas para voz, transcripción en tiempo real, voz en tiempo real, comprensión multimedia, generación de imágenes, generación de música, generación de video, web-fetch, búsqueda web y propiedad de herramientas. |
| `channelConfigs` | No | `Record<string, object>` | Metadatos de configuración de canal controlados por el manifiesto que se fusionan en las superficies de descubrimiento y validación antes de que se cargue el tiempo de ejecución. |
| `skills` | No | `string[]` | Directorios de Skills que se deben cargar, relativos a la raíz del plugin. |
| `name` | No | `string` | Nombre legible del plugin. |
| `description` | No | `string` | Resumen breve mostrado en las superficies del plugin. |
| `version` | No | `string` | Versión informativa del plugin. |
| `uiHints` | No | `Record<string, object>` | Etiquetas de UI, placeholders y pistas de sensibilidad para campos de configuración. |
| `enabledByDefault` | No | `true` | Marca un plugin incluido como habilitado de forma predeterminada. Omítelo, o establece cualquier valor distinto de `true`, para dejar el plugin deshabilitado de forma predeterminada. |
| `legacyPluginIds` | No | `string[]` | Id heredados que se normalizan a este id canónico de plugin. |
| `autoEnableWhenConfiguredProviders` | No | `string[]` | Id de proveedores que deben autohabilitar este plugin cuando la autenticación, la configuración o las referencias de modelos los mencionan. |
| `kind` | No | `"memory"` \| `"context-engine"` | Declara un tipo exclusivo de plugin usado por `plugins.slots.*`. |
| `channels` | No | `string[]` | Id de canales propiedad de este plugin. Se usan para descubrimiento y validación de configuración. |
| `providers` | No | `string[]` | Id de proveedores propiedad de este plugin. |
| `modelSupport` | No | `object` | Metadatos abreviados de familias de modelos propiedad del manifiesto usados para cargar automáticamente el plugin antes del entorno de ejecución. |
| `cliBackends` | No | `string[]` | Id de backends de inferencia por CLI propiedad de este plugin. Se usan para la autoactivación al inicio a partir de referencias explícitas en la configuración. |
| `providerAuthEnvVars` | No | `Record<string, string[]>` | Metadatos ligeros de autenticación del proveedor mediante variables de entorno que OpenClaw puede inspeccionar sin cargar el código del plugin. |
| `providerAuthAliases` | No | `Record<string, string>` | Id de proveedores que deben reutilizar otro id de proveedor para la búsqueda de autenticación, por ejemplo un proveedor de programación que comparte la clave API y los perfiles de autenticación del proveedor base. |
| `channelEnvVars` | No | `Record<string, string[]>` | Metadatos ligeros de variables de entorno del canal que OpenClaw puede inspeccionar sin cargar el código del plugin. Usa esto para configuraciones de canal guiadas por entorno o superficies de autenticación que los ayudantes genéricos de inicio/configuración deberían ver. |
| `providerAuthChoices` | No | `object[]` | Metadatos ligeros de opciones de autenticación para selectores de incorporación, resolución de proveedores preferidos y cableado sencillo de banderas CLI. |
| `contracts` | No | `object` | Instantánea estática de capacidades incluidas para voz, transcripción en tiempo real, voz en tiempo real, comprensión de medios, generación de imágenes, generación musical, generación de video, web-fetch, búsqueda web y propiedad de herramientas. |
| `channelConfigs` | No | `Record<string, object>` | Metadatos de configuración de canal propiedad del manifiesto fusionados en las superficies de descubrimiento y validación antes de que se cargue el entorno de ejecución. |
| `skills` | No | `string[]` | Directorios de Skills que se cargarán, relativos a la raíz del plugin. |
| `name` | No | `string` | Nombre legible del plugin. |
| `description` | No | `string` | Resumen corto mostrado en superficies del plugin. |
| `version` | No | `string` | Versión informativa del plugin. |
| `uiHints` | No | `Record<string, object>` | Etiquetas de UI, marcadores de posición y sugerencias de sensibilidad para campos de configuración. |
## Referencia de `providerAuthChoices`
Cada entrada de `providerAuthChoices` describe una opción de incorporación o autenticación.
OpenClaw la lee antes de que se cargue el tiempo de ejecución del proveedor.
OpenClaw la lee antes de que se cargue el entorno de ejecución del proveedor.
| Field | Required | Type | What it means |
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `provider` | Sí | `string` | ID del proveedor al que pertenece esta opción. |
| `method` | Sí | `string` | ID del método de autenticación al que se enviará. |
| `choiceId` | Sí | `string` | ID estable de opción de autenticación usado por los flujos de incorporación y CLI. |
| `choiceLabel` | No | `string` | Etiqueta visible para el usuario. Si se omite, OpenClaw usa `choiceId` como respaldo. |
| `choiceHint` | No | `string` | Texto de ayuda breve para el selector. |
| `assistantPriority` | No | `number` | Los valores más bajos se ordenan antes en los selectores interactivos guiados por el asistente. |
| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción en los selectores del asistente, pero sigue permitiendo la selección manual por CLI. |
| `deprecatedChoiceIds` | No | `string[]` | IDs heredados de opciones que deberían redirigir a los usuarios a esta opción de reemplazo. |
| `groupId` | No | `string` | ID de grupo opcional para agrupar opciones relacionadas. |
| `provider` | Sí | `string` | Id del proveedor al que pertenece esta opción. |
| `method` | Sí | `string` | Id del método de autenticación al que se enviará. |
| `choiceId` | Sí | `string` | Id estable de opción de autenticación usado por los flujos de incorporación y CLI. |
| `choiceLabel` | No | `string` | Etiqueta visible para el usuario. Si se omite, OpenClaw usa `choiceId` como valor alternativo. |
| `choiceHint` | No | `string` | Texto de ayuda corto para el selector. |
| `assistantPriority` | No | `number` | Los valores más bajos se ordenan antes en los selectores interactivos controlados por el asistente. |
| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Oculta la opción de los selectores del asistente, pero sigue permitiendo la selección manual por CLI. |
| `deprecatedChoiceIds` | No | `string[]` | Id heredados de opciones que deben redirigir a los usuarios a esta opción de reemplazo. |
| `groupId` | No | `string` | Id de grupo opcional para agrupar opciones relacionadas. |
| `groupLabel` | No | `string` | Etiqueta visible para el usuario de ese grupo. |
| `groupHint` | No | `string` | Texto de ayuda breve para el grupo. |
| `optionKey` | No | `string` | Clave de opción interna para flujos simples de autenticación con un solo flag. |
| `cliFlag` | No | `string` | Nombre del flag de CLI, como `--openrouter-api-key`. |
| `cliOption` | No | `string` | Forma completa de la opción de CLI, como `--openrouter-api-key <key>`. |
| `cliDescription` | No | `string` | Descripción usada en la ayuda de CLI. |
| `groupHint` | No | `string` | Texto de ayuda corto para el grupo. |
| `optionKey` | No | `string` | Clave interna de opción para flujos de autenticación simples de una sola bandera. |
| `cliFlag` | No | `string` | Nombre de la bandera CLI, como `--openrouter-api-key`. |
| `cliOption` | No | `string` | Forma completa de la opción CLI, como `--openrouter-api-key <key>`. |
| `cliDescription` | No | `string` | Descripción usada en la ayuda de la CLI. |
| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | En qué superficies de incorporación debe aparecer esta opción. Si se omite, el valor predeterminado es `["text-inference"]`. |
## Referencia de `uiHints`
`uiHints` es un mapa de nombres de campos de configuración a pequeñas pistas de renderizado.
`uiHints` es un mapa de nombres de campos de configuración a pequeñas sugerencias de representación.
```json
{
"uiHints": {
"apiKey": {
"label": "Clave de API",
"help": "Se usa para solicitudes de OpenRouter",
"label": "Clave API",
"help": "Se usa para solicitudes a OpenRouter",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@ -203,21 +207,21 @@ OpenClaw la lee antes de que se cargue el tiempo de ejecución del proveedor.
}
```
Cada pista de campo puede incluir:
Cada sugerencia de campo puede incluir:
| Field | Type | What it means |
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | Etiqueta del campo visible para el usuario. |
| `help` | `string` | Texto de ayuda breve. |
| `help` | `string` | Texto de ayuda corto. |
| `tags` | `string[]` | Etiquetas opcionales de UI. |
| `advanced` | `boolean` | Marca el campo como avanzado. |
| `sensitive` | `boolean` | Marca el campo como secreto o sensible. |
| `placeholder` | `string` | Texto de placeholder para entradas de formularios. |
| `placeholder` | `string` | Texto de marcador de posición para entradas de formulario. |
## Referencia de `contracts`
Usa `contracts` solo para metadatos estáticos de propiedad de capacidades que OpenClaw pueda
leer sin importar el tiempo de ejecución del plugin.
Usa `contracts` solo para metadatos estáticos de propiedad de capacidades que OpenClaw puede
leer sin importar el entorno de ejecución del plugin.
```json
{
@ -239,20 +243,20 @@ Cada lista es opcional:
| Field | Type | What it means |
| -------------------------------- | ---------- | -------------------------------------------------------------- |
| `speechProviders` | `string[]` | IDs de proveedor de voz que controla este plugin. |
| `realtimeTranscriptionProviders` | `string[]` | IDs de proveedor de transcripción en tiempo real que controla este plugin. |
| `realtimeVoiceProviders` | `string[]` | IDs de proveedor de voz en tiempo real que controla este plugin. |
| `mediaUnderstandingProviders` | `string[]` | IDs de proveedor de comprensión multimedia que controla este plugin. |
| `imageGenerationProviders` | `string[]` | IDs de proveedor de generación de imágenes que controla este plugin. |
| `videoGenerationProviders` | `string[]` | IDs de proveedor de generación de video que controla este plugin. |
| `webFetchProviders` | `string[]` | IDs de proveedor de web-fetch que controla este plugin. |
| `webSearchProviders` | `string[]` | IDs de proveedor de búsqueda web que controla este plugin. |
| `tools` | `string[]` | Nombres de herramientas del agente que controla este plugin para comprobaciones integradas de contratos. |
| `speechProviders` | `string[]` | Id de proveedores de voz propiedad de este plugin. |
| `realtimeTranscriptionProviders` | `string[]` | Id de proveedores de transcripción en tiempo real propiedad de este plugin. |
| `realtimeVoiceProviders` | `string[]` | Id de proveedores de voz en tiempo real propiedad de este plugin. |
| `mediaUnderstandingProviders` | `string[]` | Id de proveedores de comprensión de medios propiedad de este plugin. |
| `imageGenerationProviders` | `string[]` | Id de proveedores de generación de imágenes propiedad de este plugin. |
| `videoGenerationProviders` | `string[]` | Id de proveedores de generación de video propiedad de este plugin. |
| `webFetchProviders` | `string[]` | Id de proveedores de web-fetch propiedad de este plugin. |
| `webSearchProviders` | `string[]` | Id de proveedores de búsqueda web propiedad de este plugin. |
| `tools` | `string[]` | Nombres de herramientas del agente propiedad de este plugin para verificaciones de contratos incluidos. |
## Referencia de `channelConfigs`
Usa `channelConfigs` cuando un plugin de canal necesite metadatos de configuración ligeros antes de que
se cargue el tiempo de ejecución.
Usa `channelConfigs` cuando un plugin de canal necesita metadatos ligeros de configuración antes de que
se cargue el entorno de ejecución.
```json
{
@ -283,16 +287,16 @@ Cada entrada de canal puede incluir:
| Field | Type | What it means |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON Schema para `channels.<id>`. Obligatorio para cada entrada de configuración de canal declarada. |
| `uiHints` | `Record<string, object>` | Etiquetas/placeholders/pistas de sensibilidad de UI opcionales para esa sección de configuración del canal. |
| `label` | `string` | Etiqueta del canal fusionada en superficies de selector e inspección cuando los metadatos de tiempo de ejecución no están listos. |
| `description` | `string` | Descripción breve del canal para superficies de inspección y catálogo. |
| `preferOver` | `string[]` | IDs heredados o de menor prioridad de plugins que este canal debe superar en las superficies de selección. |
| `schema` | `object` | JSON Schema para `channels.<id>`. Obligatorio para cada entrada declarada de configuración de canal. |
| `uiHints` | `Record<string, object>` | Etiquetas/placeholders/sugerencias de sensibilidad opcionales de UI para esa sección de configuración del canal. |
| `label` | `string` | Etiqueta del canal fusionada en las superficies de selector e inspección cuando los metadatos del entorno de ejecución no están listos. |
| `description` | `string` | Descripción corta del canal para las superficies de inspección y catálogo. |
| `preferOver` | `string[]` | Id de plugins heredados o de menor prioridad que este canal debe superar en las superficies de selección. |
## Referencia de `modelSupport`
Usa `modelSupport` cuando OpenClaw deba inferir tu plugin de proveedor a partir de
IDs abreviados de modelo como `gpt-5.4` o `claude-sonnet-4.6` antes de que se cargue el tiempo de ejecución del plugin.
id abreviados de modelos como `gpt-5.4` o `claude-sonnet-4.6` antes de que se cargue el entorno de ejecución del plugin.
```json
{
@ -305,73 +309,74 @@ IDs abreviados de modelo como `gpt-5.4` o `claude-sonnet-4.6` antes de que se ca
OpenClaw aplica esta precedencia:
- las referencias explícitas `provider/model` usan los metadatos de manifiesto `providers` del propietario
- las referencias explícitas `provider/model` usan los metadatos del manifiesto `providers` propietario
- `modelPatterns` tienen prioridad sobre `modelPrefixes`
- si coinciden un plugin no integrado y uno integrado, gana el plugin no integrado
- la ambigüedad restante se ignora hasta que el usuario o la configuración especifiquen un proveedor
- si coinciden un plugin no incluido y un plugin incluido, el plugin no incluido
gana
- la ambigüedad restante se ignora hasta que el usuario o la configuración especifique un proveedor
Campos:
| Field | Type | What it means |
| --------------- | ---------- | ------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | Prefijos comparados con `startsWith` frente a IDs abreviados de modelo. |
| `modelPatterns` | `string[]` | Fuentes regex comparadas con IDs abreviados de modelo después de eliminar el sufijo del perfil. |
| `modelPrefixes` | `string[]` | Prefijos comparados con `startsWith` frente a id abreviados de modelos. |
| `modelPatterns` | `string[]` | Fuentes regex comparadas con id abreviados de modelos tras eliminar el sufijo del perfil. |
Las claves heredadas de capacidades de nivel superior están obsoletas. Usa `openclaw doctor --fix` para
mover `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
`webFetchProviders` y `webSearchProviders` bajo `contracts`; la carga normal
del manifiesto ya no trata esos campos de nivel superior como propiedad
de capacidades.
del manifiesto ya no trata esos campos de nivel superior como
propiedad de capacidades.
## Manifiesto frente a package.json
Los dos archivos tienen funciones distintas:
Los dos archivos cumplen funciones distintas:
| File | Use it for |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Descubrimiento, validación de configuración, metadatos de opciones de autenticación y pistas de UI que deben existir antes de que se ejecute el código del plugin |
| `package.json` | Metadatos npm, instalación de dependencias y el bloque `openclaw` usado para entrypoints, control de instalación, configuración o metadatos de catálogo |
| `openclaw.plugin.json` | Descubrimiento, validación de configuración, metadatos de opciones de autenticación y sugerencias de UI que deben existir antes de que se ejecute el código del plugin |
| `package.json` | Metadatos de npm, instalación de dependencias y el bloque `openclaw` usado para puntos de entrada, control de instalación, configuración o metadatos de catálogo |
Si no tienes claro dónde debe ir un dato, usa esta regla:
Si no estás seguro de dónde debe ir un dato, usa esta regla:
- si OpenClaw debe conocerlo antes de cargar el código del plugin, colócalo en `openclaw.plugin.json`
- si trata sobre empaquetado, archivos de entrada o comportamiento de instalación npm, colócalo en `package.json`
- si OpenClaw debe conocerlo antes de cargar el código del plugin, ponlo en `openclaw.plugin.json`
- si trata sobre empaquetado, archivos de entrada o comportamiento de instalación de npm, ponlo en `package.json`
### Campos de package.json que afectan al descubrimiento
Algunos metadatos del plugin previos al tiempo de ejecución viven intencionadamente en `package.json` dentro del
Algunos metadatos del plugin previos al entorno de ejecución viven intencionalmente en `package.json` bajo el
bloque `openclaw` en lugar de `openclaw.plugin.json`.
Ejemplos importantes:
| Field | What it means |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Declara entrypoints nativos del plugin. |
| `openclaw.setupEntry` | Entrypoint ligero solo de configuración usado durante la incorporación y el inicio diferido de canales. |
| `openclaw.extensions` | Declara puntos de entrada nativos del plugin. |
| `openclaw.setupEntry` | Punto de entrada ligero solo para configuración usado durante la incorporación y el arranque diferido del canal. |
| `openclaw.channel` | Metadatos ligeros del catálogo de canales, como etiquetas, rutas de documentación, alias y texto de selección. |
| `openclaw.channel.configuredState` | Metadatos ligeros del comprobador de estado configurado que pueden responder a "¿ya existe una configuración solo con entorno?" sin cargar el tiempo de ejecución completo del canal. |
| `openclaw.channel.persistedAuthState` | Metadatos ligeros del comprobador de autenticación persistida que pueden responder a "¿ya hay algo con sesión iniciada?" sin cargar el tiempo de ejecución completo del canal. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Pistas de instalación/actualización para plugins integrados y publicados externamente. |
| `openclaw.install.defaultChoice` | Ruta de instalación preferida cuando hay varias fuentes de instalación disponibles. |
| `openclaw.install.minHostVersion` | Versión mínima compatible del host de OpenClaw, usando un piso semver como `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Permite una ruta de recuperación de reinstalación limitada para plugins integrados cuando la configuración no es válida. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies del canal solo de configuración se carguen antes del plugin completo del canal durante el inicio. |
| `openclaw.channel.configuredState` | Metadatos ligeros del verificador de estado configurado que pueden responder “¿ya existe una configuración solo por entorno?” sin cargar el entorno de ejecución completo del canal. |
| `openclaw.channel.persistedAuthState` | Metadatos ligeros del verificador de autenticación persistida que pueden responder “¿ya hay algo con sesión iniciada?” sin cargar el entorno de ejecución completo del canal. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Sugerencias de instalación/actualización para plugins incluidos y publicados externamente. |
| `openclaw.install.defaultChoice` | Ruta de instalación preferida cuando hay varias fuentes de instalación disponibles. |
| `openclaw.install.minHostVersion` | Versión mínima compatible del host de OpenClaw, usando un umbral semver como `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Permite una ruta limitada de recuperación por reinstalación de plugins incluidos cuando la configuración no es válida. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que las superficies de canal solo de configuración se carguen antes que el plugin de canal completo durante el arranque. |
`openclaw.install.minHostVersion` se aplica durante la instalación y la carga del registro
del manifiesto. Los valores no válidos se rechazan; los valores válidos pero más recientes omiten el
`openclaw.install.minHostVersion` se aplica durante la instalación y la carga del
registro de manifiestos. Los valores no válidos se rechazan; los valores válidos pero más recientes omiten el
plugin en hosts más antiguos.
`openclaw.install.allowInvalidConfigRecovery` es intencionadamente limitado. No
hace instalables configuraciones rotas arbitrarias. Hoy solo permite que los flujos de instalación
se recuperen de fallos concretos de actualización de plugins integrados obsoletos, como una
ruta faltante del plugin integrado o una entrada obsoleta `channels.<id>` para ese mismo
plugin integrado. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores
`openclaw.install.allowInvalidConfigRecovery` es intencionalmente limitado. No
permite instalar configuraciones arbitrariamente rotas. Actualmente solo permite que los flujos de instalación
se recuperen de errores concretos de actualización obsoleta de plugins incluidos, como una
ruta faltante del plugin incluido o una entrada obsoleta `channels.<id>` para ese mismo
plugin incluido. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores
a `openclaw doctor --fix`.
`openclaw.channel.persistedAuthState` es un metadato de paquete para un módulo
comprobador diminuto:
`openclaw.channel.persistedAuthState` son metadatos de paquete para un módulo
verificador diminuto:
```json
{
@ -387,13 +392,13 @@ comprobador diminuto:
}
```
Úsalo cuando los flujos de configuración, doctor o estado configurado necesiten una sonda de autenticación
ligera de sí/no antes de que se cargue el plugin completo del canal. La exportación de destino debe ser una
función pequeña que lea solo el estado persistido; no la encamines a través del barrel completo
de tiempo de ejecución del canal.
Úsalo cuando los flujos de configuración, doctor o estado configurado necesiten una sonda barata de autenticación sí/no
antes de que se cargue el plugin completo del canal. La exportación de destino debe ser una función pequeña
que lea solo el estado persistido; no la enrutes a través del barrel completo del entorno de ejecución
del canal.
`openclaw.channel.configuredState` sigue la misma forma para comprobaciones ligeras
de estado configurado solo con entorno:
`openclaw.channel.configuredState` sigue la misma forma para verificaciones ligeras
de estado configurado solo por entorno:
```json
{
@ -409,10 +414,9 @@ de estado configurado solo con entorno:
}
```
Úsalo cuando un canal pueda responder al estado configurado desde el entorno u otras entradas
mínimas no relacionadas con el tiempo de ejecución. Si la comprobación necesita resolución completa de configuración o el
tiempo de ejecución real del canal, mantén esa lógica en el hook `config.hasConfiguredState`
del plugin.
Úsalo cuando un canal pueda responder el estado configurado desde el entorno u otras
entradas mínimas ajenas al entorno de ejecución. Si la verificación necesita la resolución completa de configuración o el
entorno de ejecución real del canal, deja esa lógica en el hook del plugin `config.hasConfiguredState`.
## Requisitos de JSON Schema
@ -422,49 +426,52 @@ del plugin.
## Comportamiento de validación
- Las claves desconocidas `channels.*` son **errores**, salvo que el ID del canal esté declarado por
- Las claves desconocidas `channels.*` son **errores**, a menos que el id del canal esté declarado por
un manifiesto de plugin.
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` y `plugins.slots.*`
deben hacer referencia a IDs de plugin **detectables**. Los IDs desconocidos son **errores**.
- Si un plugin está instalado pero tiene un manifiesto o esquema roto o ausente,
deben hacer referencia a id de plugins **detectables**. Los id desconocidos son **errores**.
- Si un plugin está instalado pero tiene un manifiesto o esquema roto o faltante,
la validación falla y Doctor informa del error del plugin.
- Si existe configuración del plugin pero el plugin está **deshabilitado**, la configuración se conserva y
se muestra una **advertencia** en Doctor + los registros.
se muestra una **advertencia** en Doctor + registros.
Consulta [Referencia de configuración](/es/gateway/configuration) para ver el esquema completo de `plugins.*`.
## Notas
- El manifiesto es **obligatorio para los plugins nativos de OpenClaw**, incluidas las cargas desde el sistema de archivos local.
- El tiempo de ejecución sigue cargando el módulo del plugin por separado; el manifiesto es solo para
- El entorno de ejecución sigue cargando el módulo del plugin por separado; el manifiesto es solo para
descubrimiento + validación.
- Los manifiestos nativos se analizan con JSON5, por lo que se aceptan comentarios, comas finales y
claves sin comillas siempre que el valor final siga siendo un objeto.
- El cargador de manifiestos solo lee los campos de manifiesto documentados. Evita añadir
- El cargador de manifiestos solo lee los campos documentados del manifiesto. Evita agregar
aquí claves personalizadas de nivel superior.
- `providerAuthEnvVars` es la ruta ligera de metadatos para sondas de autenticación, validación
de marcadores de entorno y superficies similares de autenticación de proveedor que no deberían iniciar el
tiempo de ejecución del plugin solo para inspeccionar nombres de variables de entorno.
- `channelEnvVars` es la ruta ligera de metadatos para respaldo de variables de entorno del shell, prompts
de configuración y superficies similares de canal que no deberían iniciar el tiempo de ejecución del plugin
solo para inspeccionar nombres de variables de entorno.
- `providerAuthChoices` es la ruta ligera de metadatos para selectores de opciones de autenticación,
resolución de `--auth-choice`, asignación de proveedor preferido y registro simple
de flags de CLI de incorporación antes de que se cargue el tiempo de ejecución del proveedor. Para metadatos
del asistente en tiempo de ejecución que requieran código del proveedor, consulta
[Hooks de tiempo de ejecución del proveedor](/es/plugins/architecture#provider-runtime-hooks).
- Los tipos exclusivos de plugins se seleccionan mediante `plugins.slots.*`.
- `providerAuthEnvVars` es la ruta de metadatos ligera para sondeos de autenticación, validación
de marcadores de entorno y superficies similares de autenticación del proveedor que no deberían iniciar el entorno de ejecución del plugin
solo para inspeccionar nombres de entorno.
- `providerAuthAliases` permite que variantes de proveedores reutilicen la autenticación
por variables de entorno, perfiles de autenticación, autenticación respaldada por configuración y la opción de incorporación
por clave API de otro proveedor sin codificar esa relación en el núcleo.
- `channelEnvVars` es la ruta de metadatos ligera para fallback de entorno de shell, prompts
de configuración y superficies de canal similares que no deberían iniciar el entorno de ejecución del plugin
solo para inspeccionar nombres de entorno.
- `providerAuthChoices` es la ruta de metadatos ligera para selectores de opciones de autenticación,
resolución de `--auth-choice`, mapeo de proveedores preferidos y registro simple
de banderas CLI de incorporación antes de que se cargue el entorno de ejecución del proveedor. Para metadatos de asistente en tiempo de ejecución
que requieren código del proveedor, consulta
[Hooks de runtime del proveedor](/es/plugins/architecture#provider-runtime-hooks).
- Los tipos exclusivos de plugin se seleccionan mediante `plugins.slots.*`.
- `kind: "memory"` se selecciona mediante `plugins.slots.memory`.
- `kind: "context-engine"` se selecciona mediante `plugins.slots.contextEngine`
(predeterminado: `legacy` integrado).
- `channels`, `providers`, `cliBackends` y `skills` pueden omitirse cuando un
plugin no los necesite.
plugin no los necesita.
- Si tu plugin depende de módulos nativos, documenta los pasos de compilación y cualquier
requisito de lista permitida del gestor de paquetes (por ejemplo, pnpm `allow-build-scripts`
requisito de lista de permitidos del administrador de paquetes (por ejemplo, pnpm `allow-build-scripts`
- `pnpm rebuild <package>`).
## Relacionado
- [Building Plugins](/es/plugins/building-plugins) — primeros pasos con plugins
- [Plugin Architecture](/es/plugins/architecture) — arquitectura interna
- [SDK Overview](/es/plugins/sdk-overview) — referencia del SDK de plugins
- [Creación de plugins](/es/plugins/building-plugins) — introducción a los plugins
- [Arquitectura de plugins](/es/plugins/architecture) — arquitectura interna
- [Resumen del SDK](/es/plugins/sdk-overview) — referencia del SDK de plugins

444
docs/es/plugins/sdk-migration.md
View File

@ -5,40 +5,40 @@ read_when:
- Estás actualizando un plugin a la arquitectura moderna de plugins
- Mantienes un plugin externo de OpenClaw
sidebarTitle: Migrate to SDK
summary: Migra desde la capa heredada de compatibilidad hacia atrás al moderno plugin SDK
title: Migración del Plugin SDK
summary: Migra desde la capa heredada de compatibilidad retroactiva al SDK de plugins moderno
title: Migración del SDK de plugins
x-i18n:
generated_at: "2026-04-08T02:17:07Z"
generated_at: "2026-04-09T01:30:19Z"
model: gpt-5.4
provider: openai
source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad
source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07
source_path: plugins/sdk-migration.md
workflow: 15
---
# Migración del Plugin SDK
# Migración del SDK de plugins
OpenClaw ha pasado de una amplia capa de compatibilidad hacia atrás a una arquitectura
moderna de plugins con importaciones enfocadas y documentadas. Si tu plugin se creó antes
de la nueva arquitectura, esta guía te ayuda a migrarlo.
OpenClaw ha pasado de una capa amplia de compatibilidad retroactiva a una arquitectura moderna de plugins
con importaciones específicas y documentadas. Si tu plugin se creó antes de
la nueva arquitectura, esta guía te ayudará a migrarlo.
## Qué está cambiando
El sistema anterior de plugins proporcionaba dos superficies muy abiertas que permitían a los plugins importar
cualquier cosa que necesitaran desde un único punto de entrada:
todo lo que necesitaran desde un único punto de entrada:
- **`openclaw/plugin-sdk/compat`** — una sola importación que reexportaba decenas de
helpers. Se introdujo para mantener en funcionamiento plugins más antiguos basados en hooks mientras se
ayudantes. Se introdujo para mantener funcionando los plugins basados en hooks más antiguos mientras se
construía la nueva arquitectura de plugins.
- **`openclaw/extension-api`** — un puente que daba a los plugins acceso directo a
helpers del lado del host, como el ejecutor de agente embebido.
ayudantes del lado del host, como el ejecutor de agentes integrado.
Ambas superficies ahora están **obsoletas**. Siguen funcionando en tiempo de ejecución, pero los
plugins nuevos no deben usarlas, y los plugins existentes deberían migrar antes de que la próxima
Ambas superficies ahora están **obsoletas**. Siguen funcionando en tiempo de ejecución, pero los plugins
nuevos no deben usarlas, y los plugins existentes deberían migrar antes de que la próxima
versión principal las elimine.
<Warning>
La capa de compatibilidad hacia atrás se eliminará en una futura versión principal.
La capa de compatibilidad retroactiva se eliminará en una futura versión principal.
Los plugins que sigan importando desde estas superficies dejarán de funcionar cuando eso ocurra.
</Warning>
@ -46,64 +46,63 @@ versión principal las elimine.
El enfoque anterior causaba problemas:
- **Inicio lento** — importar un helper cargaba decenas de módulos no relacionados
- **Inicio lento** — importar un ayudante cargaba decenas de módulos no relacionados
- **Dependencias circulares** — las reexportaciones amplias facilitaban la creación de ciclos de importación
- **Superficie API poco clara** — no había forma de saber qué exportaciones eran estables y cuáles eran internas
- **Superficie de API poco clara** — no había forma de saber qué exportaciones eran estables y cuáles eran internas
El moderno plugin SDK soluciona esto: cada ruta de importación (`openclaw/plugin-sdk/\<subpath\>`)
es un módulo pequeño, autocontenido, con un propósito claro y un contrato documentado.
El SDK de plugins moderno corrige esto: cada ruta de importación (`openclaw/plugin-sdk/\<subpath\>`)
es un módulo pequeño, autónomo, con un propósito claro y un contrato documentado.
Las superficies heredadas de conveniencia para proveedores de canales empaquetados también han desaparecido. Las importaciones
Las uniones heredadas de conveniencia para proveedores de canales incluidos también han desaparecido. Importaciones
como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
las superficies helper con marca de canal y
las uniones de ayudantes con marca de canal y
`openclaw/plugin-sdk/telegram-core` eran atajos privados del monorepo, no
contratos estables para plugins. Usa en su lugar subrutas genéricas y específicas del SDK. Dentro del
espacio de trabajo de plugins empaquetados, mantén los helpers propiedad del proveedor en el propio
contratos estables de plugins. Usa en su lugar subrutas genéricas y estrechas del SDK. Dentro del
espacio de trabajo de plugins incluidos, conserva los ayudantes propios del proveedor en el
`api.ts` o `runtime-api.ts` de ese plugin.
Ejemplos actuales de proveedores empaquetados:
Ejemplos actuales de proveedores incluidos:
- Anthropic mantiene helpers de flujo específicos de Claude en su propia superficie `api.ts` /
- Anthropic mantiene los ayudantes de streaming específicos de Claude en su propia unión `api.ts` /
`contract-api.ts`
- OpenAI mantiene constructores de proveedores, helpers de modelos predeterminados y constructores de proveedores
realtime en su propio `api.ts`
- OpenRouter mantiene el constructor del proveedor y los helpers de onboarding/configuración en su propio
- OpenAI mantiene los constructores de proveedores, los ayudantes de modelos predeterminados y los constructores
de proveedores en tiempo real en su propio `api.ts`
- OpenRouter mantiene el constructor del proveedor y los ayudantes de incorporación/configuración en su propio
`api.ts`
## Cómo migrar
<Steps>
<Step title="Migra los handlers nativos de aprobación a hechos de capacidad">
<Step title="Migra los controladores nativos de aprobación a hechos de capacidad">
Los plugins de canal con capacidad de aprobación ahora exponen el comportamiento nativo de aprobación mediante
`approvalCapability.nativeRuntime` más el registro compartido de contexto de runtime.
`approvalCapability.nativeRuntime` más el registro compartido de contexto de ejecución.
Cambios clave:
Cambios principales:
- Reemplaza `approvalCapability.handler.loadRuntime(...)` por
`approvalCapability.nativeRuntime`
- Mueve la autenticación/entrega específica de aprobación fuera del cableado heredado `plugin.auth` /
`plugin.approvals` y colócalo en `approvalCapability`
- `ChannelPlugin.approvals` se ha eliminado del contrato público
de plugins de canal; mueve los campos delivery/native/render a `approvalCapability`
- `plugin.auth` se mantiene solo para flujos de login/logout del canal; los hooks de autenticación
de aprobación allí ya no son leídos por el núcleo
- Registra objetos de runtime propiedad del canal, como clientes, tokens o apps Bolt,
mediante `openclaw/plugin-sdk/channel-runtime-context`
- No envíes avisos de redirección propiedad del plugin desde handlers nativos de aprobación;
el núcleo ahora se encarga de los avisos de enrutado a otro lugar a partir de resultados reales de entrega
- Mueve la autenticación/entrega específica de aprobaciones fuera del cableado heredado `plugin.auth` /
`plugin.approvals` y hacia `approvalCapability`
- `ChannelPlugin.approvals` se eliminó del contrato público de
plugin de canal; mueve los campos delivery/native/render a `approvalCapability`
- `plugin.auth` permanece solo para los flujos de inicio/cierre de sesión del canal; los hooks
de autenticación de aprobación ahí ya no son leídos por el núcleo
- Registra objetos de entorno de ejecución propiedad del canal, como clientes, tokens o aplicaciones
Bolt, mediante `openclaw/plugin-sdk/channel-runtime-context`
- No envíes avisos de redirección propiedad del plugin desde controladores nativos de aprobación;
el núcleo ahora es propietario de los avisos de “enrutado a otro lugar” a partir de los resultados reales de entrega
- Al pasar `channelRuntime` a `createChannelManager(...)`, proporciona una
superficie real `createPluginRuntime().channel`. Los stubs parciales se rechazan.
superficie real de `createPluginRuntime().channel`. Los stubs parciales se rechazan.
Consulta `/plugins/sdk-channel-plugins` para ver el diseño actual de
capacidades de aprobación.
Consulta `/plugins/sdk-channel-plugins` para ver el diseño actual
de la capacidad de aprobación.
</Step>
<Step title="Audita el comportamiento de respaldo del wrapper de Windows">
Si tu plugin usa `openclaw/plugin-sdk/windows-spawn`, los wrappers `.cmd`/`.bat`
no resueltos de Windows ahora fallan en modo cerrado, a menos que pases explícitamente
`allowShellFallback: true`.
<Step title="Audita el comportamiento de fallback del wrapper de Windows">
Si tu plugin usa `openclaw/plugin-sdk/windows-spawn`, los wrappers `.cmd`/`.bat` de Windows no resueltos ahora fallan de forma cerrada a menos que pases
explícitamente `allowShellFallback: true`.
```typescript
// Antes
@ -112,19 +111,19 @@ Ejemplos actuales de proveedores empaquetados:
// Después
const program = applyWindowsSpawnProgramPolicy({
candidate,
// Establece esto solo para llamantes de compatibilidad de confianza que
// aceptan intencionalmente el respaldo mediado por shell.
// Establece esto solo para llamadores de compatibilidad de confianza que
// aceptan intencionalmente el fallback mediado por shell.
allowShellFallback: true,
});
```
Si tu llamante no depende intencionalmente del respaldo por shell, no establezcas
`allowShellFallback` y maneja el error lanzado en su lugar.
Si tu llamador no depende intencionalmente del fallback de shell, no establezcas
`allowShellFallback` y maneja en su lugar el error lanzado.
</Step>
<Step title="Encuentra importaciones obsoletas">
Busca en tu plugin importaciones desde cualquiera de estas dos superficies obsoletas:
<Step title="Busca importaciones obsoletas">
Busca en tu plugin importaciones desde cualquiera de las dos superficies obsoletas:
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -133,24 +132,24 @@ Ejemplos actuales de proveedores empaquetados:
</Step>
<Step title="Reemplázalas por importaciones enfocadas">
Cada exportación de la superficie antigua se corresponde con una ruta de importación moderna específica:
<Step title="Reemplázalas por importaciones específicas">
Cada exportación de la superficie anterior se asigna a una ruta de importación moderna específica:
```typescript
// Antes (capa obsoleta de compatibilidad hacia atrás)
// Antes (capa obsoleta de compatibilidad retroactiva)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// Después (importaciones modernas y enfocadas)
// Después (importaciones modernas específicas)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
Para helpers del lado del host, usa el runtime de plugin inyectado en lugar de importar
Para los ayudantes del lado del host, usa el entorno de ejecución del plugin inyectado en lugar de importar
directamente:
```typescript
@ -158,11 +157,11 @@ Ejemplos actuales de proveedores empaquetados:
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// Después (runtime inyectado)
// Después (entorno de ejecución inyectado)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
El mismo patrón se aplica a otros helpers heredados del puente:
El mismo patrón se aplica a otros ayudantes heredados del puente:
| Importación antigua | Equivalente moderno |
| --- | --- |
@ -172,7 +171,7 @@ Ejemplos actuales de proveedores empaquetados:
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
| helpers del almacén de sesiones | `api.runtime.agent.session.*` |
| ayudantes de almacén de sesiones | `api.runtime.agent.session.*` |
</Step>
@ -189,178 +188,181 @@ Ejemplos actuales de proveedores empaquetados:
<Accordion title="Tabla común de rutas de importación">
| Ruta de importación | Propósito | Exportaciones clave |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | Helper canónico de entrada de plugin | `definePluginEntry` |
| `plugin-sdk/plugin-entry` | Ayudante canónico de entrada de plugin | `definePluginEntry` |
| `plugin-sdk/core` | Reexportación paraguas heredada para definiciones/constructores de entrada de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Exportación del esquema raíz de configuración | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper de entrada de proveedor único | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Definiciones y constructores enfocados de entrada de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helpers compartidos del asistente de configuración | Prompts de listas de permitidos, constructores de estado de configuración |
| `plugin-sdk/setup-runtime` | Helpers de runtime en tiempo de configuración | Adaptadores de parches de configuración seguros para importación, helpers de notas de búsqueda, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies delegados de configuración |
| `plugin-sdk/setup-adapter-runtime` | Helpers del adaptador de configuración | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Helpers de herramientas de configuración | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helpers de múltiples cuentas | Helpers de lista/configuración/compuertas de acciones de cuenta |
| `plugin-sdk/account-id` | Helpers de id de cuenta | `DEFAULT_ACCOUNT_ID`, normalización de id de cuenta |
| `plugin-sdk/account-resolution` | Helpers de búsqueda de cuenta | Helpers de búsqueda de cuenta + respaldo predeterminado |
| `plugin-sdk/account-helpers` | Helpers de cuenta específicos | Helpers de lista de cuentas/acción de cuenta |
| `plugin-sdk/config-schema` | Exportación del esquema de configuración raíz | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Ayudante de entrada de proveedor único | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Definiciones y constructores específicos de entrada de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Ayudantes compartidos del asistente de configuración | Prompts de lista de permitidos, constructores de estado de configuración |
| `plugin-sdk/setup-runtime` | Ayudantes de entorno de ejecución en tiempo de configuración | Adaptadores de parcheo de configuración seguros para importación, ayudantes de notas de búsqueda, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuración delegados |
| `plugin-sdk/setup-adapter-runtime` | Ayudantes del adaptador de configuración | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Ayudantes de herramientas de configuración | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Ayudantes de múltiples cuentas | Ayudantes de lista/configuración/puerta de acciones de cuenta |
| `plugin-sdk/account-id` | Ayudantes de id de cuenta | `DEFAULT_ACCOUNT_ID`, normalización de id de cuenta |
| `plugin-sdk/account-resolution` | Ayudantes de búsqueda de cuentas | Ayudantes de búsqueda de cuentas + fallback predeterminado |
| `plugin-sdk/account-helpers` | Ayudantes de cuenta específicos | Ayudantes de lista de cuentas/acciones de cuenta |
| `plugin-sdk/channel-setup` | Adaptadores del asistente de configuración | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, además de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitivas de emparejamiento de DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Cableado de prefijo de respuesta + escritura | `createChannelReplyPipeline` |
| `plugin-sdk/channel-pairing` | Primitivas de emparejamiento DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Cableado de prefijo de respuesta + indicador de escritura | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | Fábricas de adaptadores de configuración | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Constructores de esquema de configuración | Tipos de esquema de configuración de canal |
| `plugin-sdk/telegram-command-config` | Helpers de configuración de comandos de Telegram | Normalización de nombres de comando, recorte de descripciones, validación de duplicados/conflictos |
| `plugin-sdk/channel-config-schema` | Constructores de esquemas de configuración | Tipos de esquema de configuración de canal |
| `plugin-sdk/telegram-command-config` | Ayudantes de configuración de comandos de Telegram | Normalización de nombres de comandos, recorte de descripciones, validación de duplicados/conflictos |
| `plugin-sdk/channel-policy` | Resolución de políticas de grupo/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Seguimiento del estado de cuenta | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helpers de envoltorio entrante | Helpers compartidos de ruta + construcción de envoltorio |
| `plugin-sdk/inbound-reply-dispatch` | Helpers de respuesta entrante | Helpers compartidos de registro y despacho |
| `plugin-sdk/messaging-targets` | Análisis de objetivos de mensajería | Helpers de análisis/coincidencia de objetivos |
| `plugin-sdk/outbound-media` | Helpers de medios salientes | Carga compartida de medios salientes |
| `plugin-sdk/outbound-runtime` | Helpers de runtime saliente | Helpers delegados de identidad/envío saliente |
| `plugin-sdk/thread-bindings-runtime` | Helpers de bindings de hilo | Ciclo de vida de bindings de hilo y helpers de adaptador |
| `plugin-sdk/agent-media-payload` | Helpers heredados de carga útil de medios | Constructor de carga útil de medios de agente para diseños heredados de campos |
| `plugin-sdk/channel-runtime` | Shim obsoleto de compatibilidad | Solo utilidades heredadas de runtime de canal |
| `plugin-sdk/channel-lifecycle` | Seguimiento de estado de cuenta | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Ayudantes de envelope de entrada | Ayudantes compartidos de enrutamiento + construcción de envelope |
| `plugin-sdk/inbound-reply-dispatch` | Ayudantes de respuesta entrante | Ayudantes compartidos de registro y despacho |
| `plugin-sdk/messaging-targets` | Análisis de destinos de mensajería | Ayudantes de análisis/coincidencia de destinos |
| `plugin-sdk/outbound-media` | Ayudantes de medios salientes | Carga compartida de medios salientes |
| `plugin-sdk/outbound-runtime` | Ayudantes de entorno de ejecución saliente | Ayudantes de identidad saliente/delegados de envío |
| `plugin-sdk/thread-bindings-runtime` | Ayudantes de asociación de hilos | Ciclo de vida y ayudantes de adaptadores de asociación de hilos |
| `plugin-sdk/agent-media-payload` | Ayudantes heredados de payload de medios | Constructor de payload de medios del agente para diseños heredados de campos |
| `plugin-sdk/channel-runtime` | Shim de compatibilidad obsoleto | Solo utilidades heredadas de entorno de ejecución de canal |
| `plugin-sdk/channel-send-result` | Tipos de resultado de envío | Tipos de resultado de respuesta |
| `plugin-sdk/runtime-store` | Almacenamiento persistente del plugin | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helpers amplios de runtime | Helpers de runtime/logging/backup/instalación de plugins |
| `plugin-sdk/runtime-env` | Helpers específicos de entorno de runtime | Logger/entorno de runtime, timeout, retry y helpers de backoff |
| `plugin-sdk/plugin-runtime` | Helpers compartidos de runtime de plugin | Helpers de comandos/hooks/http/interactivos de plugin |
| `plugin-sdk/hook-runtime` | Helpers de pipeline de hooks | Helpers compartidos del pipeline de hooks webhook/internos |
| `plugin-sdk/lazy-runtime` | Helpers de runtime diferido | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helpers de proceso | Helpers compartidos de exec |
| `plugin-sdk/cli-runtime` | Helpers de runtime de CLI | Formato de comandos, esperas, helpers de versión |
| `plugin-sdk/gateway-runtime` | Helpers del Gateway | Cliente Gateway y helpers de parcheo de estado de canal |
| `plugin-sdk/config-runtime` | Helpers de configuración | Helpers de carga/escritura de configuración |
| `plugin-sdk/telegram-command-config` | Helpers de comandos de Telegram | Helpers de validación de comandos de Telegram estables como respaldo cuando la superficie de contrato empaquetada de Telegram no está disponible |
| `plugin-sdk/approval-runtime` | Helpers de prompts de aprobación | Carga útil de aprobación de exec/plugin, helpers de capacidad/perfil de aprobación, helpers nativos de routing/runtime de aprobación |
| `plugin-sdk/approval-auth-runtime` | Helpers de auth de aprobación | Resolución del aprobador, auth de acción en el mismo chat |
| `plugin-sdk/approval-client-runtime` | Helpers de cliente de aprobación | Helpers de perfil/filtro nativos de aprobación de exec |
| `plugin-sdk/approval-delivery-runtime` | Helpers de entrega de aprobación | Adaptadores nativos de capacidad/entrega de aprobación |
| `plugin-sdk/approval-gateway-runtime` | Helpers de Gateway de aprobación | Helper compartido de resolución de gateway de aprobación |
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers de adaptador de aprobación | Helpers ligeros de carga de adaptadores nativos de aprobación para puntos de entrada de canal activos |
| `plugin-sdk/approval-handler-runtime` | Helpers de handler de aprobación | Helpers más amplios de runtime de handlers de aprobación; prefiere las superficies más específicas de adaptador/gateway cuando sean suficientes |
| `plugin-sdk/approval-native-runtime` | Helpers de objetivos de aprobación | Helpers nativos de binding de objetivo/cuenta de aprobación |
| `plugin-sdk/approval-reply-runtime` | Helpers de respuesta de aprobación | Helpers de carga útil de respuesta de aprobación de exec/plugin |
| `plugin-sdk/channel-runtime-context` | Helpers de contexto de runtime de canal | Helpers genéricos de registro/obtención/observación del contexto de runtime de canal |
| `plugin-sdk/security-runtime` | Helpers de seguridad | Helpers compartidos de confianza, restricción de DM, contenido externo y recopilación de secretos |
| `plugin-sdk/ssrf-policy` | Helpers de política SSRF | Helpers de lista de permitidos de hosts y política de red privada |
| `plugin-sdk/ssrf-runtime` | Helpers de runtime SSRF | Helpers de dispatcher fijado, fetch protegido y política SSRF |
| `plugin-sdk/collection-runtime` | Helpers de caché limitada | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Helpers de restricción diagnóstica | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helpers de formato de errores | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de grafo de errores |
| `plugin-sdk/fetch-runtime` | Helpers envueltos de fetch/proxy | `resolveFetch`, helpers de proxy |
| `plugin-sdk/host-runtime` | Helpers de normalización del host | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Helpers de retry | `RetryConfig`, `retryAsync`, ejecutores de políticas |
| `plugin-sdk/allow-from` | Formateo de lista de permitidos | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mapeo de entradas de lista de permitidos | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Restricción de comandos y helpers de superficie de comandos | `resolveControlCommandGate`, helpers de autorización de remitente, helpers de registro de comandos |
| `plugin-sdk/secret-input` | Análisis de entrada secreta | Helpers de entrada secreta |
| `plugin-sdk/webhook-ingress` | Helpers de solicitud webhook | Utilidades de objetivo webhook |
| `plugin-sdk/webhook-request-guards` | Helpers de guardas de cuerpo webhook | Helpers de lectura/límite del cuerpo de solicitud |
| `plugin-sdk/reply-runtime` | Runtime compartido de respuesta | Despacho entrante, heartbeat, planificador de respuesta, fragmentación |
| `plugin-sdk/reply-dispatch-runtime` | Helpers específicos de despacho de respuesta | Helpers de finalización + despacho de proveedor |
| `plugin-sdk/reply-history` | Helpers de historial de respuesta | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/runtime-store` | Almacenamiento persistente de plugins | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Ayudantes amplios de entorno de ejecución | Ayudantes de entorno de ejecución/logs/backup/instalación de plugins |
| `plugin-sdk/runtime-env` | Ayudantes específicos de entorno de ejecución | Logger/entorno de ejecución, tiempo de espera, reintentos y ayudantes de backoff |
| `plugin-sdk/plugin-runtime` | Ayudantes compartidos de entorno de ejecución de plugins | Ayudantes de comandos/hooks/http/interactividad de plugins |
| `plugin-sdk/hook-runtime` | Ayudantes de canalización de hooks | Ayudantes compartidos de canalización de webhooks/hooks internos |
| `plugin-sdk/lazy-runtime` | Ayudantes de entorno de ejecución perezoso | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Ayudantes de procesos | Ayudantes compartidos de exec |
| `plugin-sdk/cli-runtime` | Ayudantes de entorno de ejecución de CLI | Formateo de comandos, esperas, ayudantes de versión |
| `plugin-sdk/gateway-runtime` | Ayudantes de gateway | Cliente de gateway y ayudantes de parcheo de estado de canal |
| `plugin-sdk/config-runtime` | Ayudantes de configuración | Ayudantes de carga/escritura de configuración |
| `plugin-sdk/telegram-command-config` | Ayudantes de comandos de Telegram | Ayudantes de validación de comandos de Telegram con fallback estable cuando la superficie contractual incluida de Telegram no está disponible |
| `plugin-sdk/approval-runtime` | Ayudantes de prompts de aprobación | Payload de aprobación de exec/plugin, ayudantes de capacidad/perfil de aprobación, ayudantes nativos de enrutamiento/entorno de ejecución de aprobaciones |
| `plugin-sdk/approval-auth-runtime` | Ayudantes de autenticación de aprobación | Resolución de aprobadores, autenticación de acciones en el mismo chat |
| `plugin-sdk/approval-client-runtime` | Ayudantes de cliente de aprobación | Ayudantes nativos de perfil/filtro de aprobación de exec |
| `plugin-sdk/approval-delivery-runtime` | Ayudantes de entrega de aprobación | Adaptadores nativos de capacidad/entrega de aprobación |
| `plugin-sdk/approval-gateway-runtime` | Ayudantes de gateway de aprobación | Ayudante compartido de resolución de gateway de aprobación |
| `plugin-sdk/approval-handler-adapter-runtime` | Ayudantes de adaptador de aprobación | Ayudantes ligeros de carga de adaptadores nativos de aprobación para puntos de entrada de canal activos |
| `plugin-sdk/approval-handler-runtime` | Ayudantes de controlador de aprobación | Ayudantes más amplios del entorno de ejecución del controlador de aprobación; prefiere las uniones más específicas de adaptador/gateway cuando sean suficientes |
| `plugin-sdk/approval-native-runtime` | Ayudantes de destino de aprobación | Ayudantes nativos de asociación de destino/cuenta de aprobación |
| `plugin-sdk/approval-reply-runtime` | Ayudantes de respuesta de aprobación | Ayudantes de payload de respuesta de aprobación de exec/plugin |
| `plugin-sdk/channel-runtime-context` | Ayudantes de contexto de entorno de ejecución de canal | Ayudantes genéricos de registro/obtención/observación de contexto de entorno de ejecución de canal |
| `plugin-sdk/security-runtime` | Ayudantes de seguridad | Ayudantes compartidos de confianza, control DM, contenido externo y recopilación de secretos |
| `plugin-sdk/ssrf-policy` | Ayudantes de políticas SSRF | Ayudantes de lista de permitidos de hosts y políticas de red privada |
| `plugin-sdk/ssrf-runtime` | Ayudantes de entorno de ejecución SSRF | Dispatcher fijado, fetch protegido, ayudantes de políticas SSRF |
| `plugin-sdk/collection-runtime` | Ayudantes de caché acotada | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Ayudantes de control de diagnósticos | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Ayudantes de formato de errores | `formatUncaughtError`, `isApprovalNotFoundError`, ayudantes de grafo de errores |
| `plugin-sdk/fetch-runtime` | Ayudantes de fetch/proxy envueltos | `resolveFetch`, ayudantes de proxy |
| `plugin-sdk/host-runtime` | Ayudantes de normalización del host | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Ayudantes de reintento | `RetryConfig`, `retryAsync`, ejecutores de políticas |
| `plugin-sdk/allow-from` | Formateo de listas de permitidos | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mapeo de entrada de listas de permitidos | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Control de comandos y ayudantes de superficie de comandos | `resolveControlCommandGate`, ayudantes de autorización de remitente, ayudantes de registro de comandos |
| `plugin-sdk/command-status` | Renderizadores de estado/ayuda de comandos | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Análisis de entrada de secretos | Ayudantes de entrada de secretos |
| `plugin-sdk/webhook-ingress` | Ayudantes de solicitudes webhook | Utilidades de destino webhook |
| `plugin-sdk/webhook-request-guards` | Ayudantes de protección de solicitudes webhook | Ayudantes de lectura/límite de cuerpo de solicitud |
| `plugin-sdk/reply-runtime` | Entorno de ejecución compartido de respuestas | Despacho entrante, heartbeat, planificador de respuestas, fragmentación |
| `plugin-sdk/reply-dispatch-runtime` | Ayudantes específicos de despacho de respuestas | Ayudantes de finalización + despacho de proveedor |
| `plugin-sdk/reply-history` | Ayudantes de historial de respuestas | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | Planificación de referencias de respuesta | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helpers de fragmentación de respuesta | Helpers de fragmentación de texto/markdown |
| `plugin-sdk/session-store-runtime` | Helpers de almacén de sesiones | Ruta del almacén + helpers de updated-at |
| `plugin-sdk/state-paths` | Helpers de rutas de estado | Helpers de directorios de estado y OAuth |
| `plugin-sdk/routing` | Helpers de routing/clave de sesión | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalización de clave de sesión |
| `plugin-sdk/status-helpers` | Helpers de estado de canal | Constructores de resúmenes de estado de canal/cuenta, valores predeterminados de estado de runtime, helpers de metadatos de incidencias |
| `plugin-sdk/target-resolver-runtime` | Helpers de resolución de objetivos | Helpers compartidos de resolución de objetivos |
| `plugin-sdk/string-normalization-runtime` | Helpers de normalización de cadenas | Helpers de normalización de slug/cadenas |
| `plugin-sdk/request-url` | Helpers de URL de solicitud | Extrae URLs de cadena de entradas similares a solicitudes |
| `plugin-sdk/run-command` | Helpers de comandos temporizados | Ejecutor de comandos temporizados con stdout/stderr normalizados |
| `plugin-sdk/reply-chunking` | Ayudantes de fragmentación de respuestas | Ayudantes de fragmentación de texto/Markdown |
| `plugin-sdk/session-store-runtime` | Ayudantes de almacén de sesiones | Ayudantes de ruta de almacén + updated-at |
| `plugin-sdk/state-paths` | Ayudantes de rutas de estado | Ayudantes de directorios de estado y OAuth |
| `plugin-sdk/routing` | Ayudantes de enrutamiento/clave de sesión | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, ayudantes de normalización de claves de sesión |
| `plugin-sdk/status-helpers` | Ayudantes de estado de canal | Constructores de resúmenes de estado de canal/cuenta, valores predeterminados de estado de entorno de ejecución, ayudantes de metadatos de incidencias |
| `plugin-sdk/target-resolver-runtime` | Ayudantes de resolución de destino | Ayudantes compartidos de resolución de destino |
| `plugin-sdk/string-normalization-runtime` | Ayudantes de normalización de cadenas | Ayudantes de normalización de slug/cadenas |
| `plugin-sdk/request-url` | Ayudantes de URL de solicitud | Extrae URL de cadena de entradas tipo solicitud |
| `plugin-sdk/run-command` | Ayudantes de comandos temporizados | Ejecutor de comandos temporizados con stdout/stderr normalizados |
| `plugin-sdk/param-readers` | Lectores de parámetros | Lectores comunes de parámetros de herramientas/CLI |
| `plugin-sdk/tool-send` | Extracción de envío de herramientas | Extrae campos canónicos de objetivo de envío desde argumentos de herramientas |
| `plugin-sdk/temp-path` | Helpers de ruta temporal | Helpers compartidos de ruta temporal de descarga |
| `plugin-sdk/logging-core` | Helpers de logging | Logger de subsistema y helpers de redacción |
| `plugin-sdk/markdown-table-runtime` | Helpers de tablas Markdown | Helpers de modo de tabla Markdown |
| `plugin-sdk/reply-payload` | Tipos de respuesta de mensaje | Tipos de carga útil de respuesta |
| `plugin-sdk/provider-setup` | Helpers seleccionados de configuración de proveedores locales/autohospedados | Helpers de descubrimiento/configuración de proveedores autohospedados |
| `plugin-sdk/self-hosted-provider-setup` | Helpers enfocados de configuración de proveedores autohospedados compatibles con OpenAI | Los mismos helpers de descubrimiento/configuración de proveedores autohospedados |
| `plugin-sdk/provider-auth-runtime` | Helpers de auth de runtime del proveedor | Helpers de resolución de API key en runtime |
| `plugin-sdk/provider-auth-api-key` | Helpers de configuración de API key del proveedor | Helpers de onboarding/escritura de perfil de API key |
| `plugin-sdk/provider-auth-result` | Helpers de resultado de auth del proveedor | Constructor estándar de resultado de auth OAuth |
| `plugin-sdk/provider-auth-login` | Helpers de login interactivo del proveedor | Helpers compartidos de login interactivo |
| `plugin-sdk/provider-env-vars` | Helpers de variables de entorno del proveedor | Helpers de búsqueda de variables de entorno de auth del proveedor |
| `plugin-sdk/provider-model-shared` | Helpers compartidos de modelo/repetición del proveedor | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, helpers de endpoints del proveedor y helpers de normalización de id de modelo |
| `plugin-sdk/provider-catalog-shared` | Helpers compartidos de catálogo del proveedor | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Parches de onboarding del proveedor | Helpers de configuración de onboarding |
| `plugin-sdk/provider-http` | Helpers HTTP del proveedor | Helpers genéricos de HTTP/capacidades de endpoint del proveedor |
| `plugin-sdk/provider-web-fetch` | Helpers de web-fetch del proveedor | Helpers de registro/caché del proveedor web-fetch |
| `plugin-sdk/provider-web-search-contract` | Helpers de contrato de búsqueda web del proveedor | Helpers específicos de contrato de configuración/credenciales de búsqueda web como `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance |
| `plugin-sdk/provider-web-search` | Helpers de búsqueda web del proveedor | Helpers de registro/caché/runtime del proveedor de búsqueda web |
| `plugin-sdk/provider-tools` | Helpers de compatibilidad de herramientas/esquema del proveedor | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquema Gemini y helpers de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helpers de uso del proveedor | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` y otros helpers de uso del proveedor |
| `plugin-sdk/provider-stream` | Helpers de wrapper de flujo del proveedor | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de flujo y helpers compartidos de wrappers Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/keyed-async-queue` | Cola async ordenada | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Helpers compartidos de medios | Helpers de obtención/transformación/almacenamiento de medios más constructores de carga útil de medios |
| `plugin-sdk/media-generation-runtime` | Helpers compartidos de generación de medios | Helpers compartidos de failover, selección de candidatos y mensajes de modelo ausente para generación de imagen/video/música |
| `plugin-sdk/media-understanding` | Helpers de comprensión de medios | Tipos de proveedor de comprensión de medios más exportaciones de helpers de imagen/audio orientados al proveedor |
| `plugin-sdk/text-runtime` | Helpers compartidos de texto | Eliminación de texto visible para el asistente, helpers de renderizado/fragmentación/tablas Markdown, helpers de redacción, helpers de etiquetas de directiva, utilidades de texto seguro y helpers relacionados de texto/logging |
| `plugin-sdk/text-chunking` | Helpers de fragmentación de texto | Helper de fragmentación de texto saliente |
| `plugin-sdk/speech` | Helpers de voz | Tipos de proveedor de voz más helpers orientados al proveedor para directivas, registro y validación |
| `plugin-sdk/speech-core` | Núcleo compartido de voz | Tipos de proveedor de voz, registro, directivas, normalización |
| `plugin-sdk/realtime-transcription` | Helpers de transcripción en tiempo real | Tipos de proveedor y helpers de registro |
| `plugin-sdk/realtime-voice` | Helpers de voz en tiempo real | Tipos de proveedor y helpers de registro |
| `plugin-sdk/image-generation-core` | Núcleo compartido de generación de imágenes | Tipos de generación de imágenes, failover, auth y helpers de registro |
| `plugin-sdk/music-generation` | Helpers de generación musical | Tipos de proveedor/solicitud/resultado de generación musical |
| `plugin-sdk/music-generation-core` | Núcleo compartido de generación musical | Tipos de generación musical, helpers de failover, búsqueda de proveedor y análisis de model-ref |
| `plugin-sdk/video-generation` | Helpers de generación de video | Tipos de proveedor/solicitud/resultado de generación de video |
| `plugin-sdk/video-generation-core` | Núcleo compartido de generación de video | Tipos de generación de video, helpers de failover, búsqueda de proveedor y análisis de model-ref |
| `plugin-sdk/interactive-runtime` | Helpers de respuesta interactiva | Normalización/reducción de carga útil de respuesta interactiva |
| `plugin-sdk/tool-payload` | Extracción de payload de herramientas | Extrae payloads normalizados de objetos de resultado de herramientas |
| `plugin-sdk/tool-send` | Extracción de envío de herramientas | Extrae campos canónicos de destino de envío desde argumentos de herramientas |
| `plugin-sdk/temp-path` | Ayudantes de rutas temporales | Ayudantes compartidos de rutas temporales de descarga |
| `plugin-sdk/logging-core` | Ayudantes de logging | Logger de subsistema y ayudantes de redacción |
| `plugin-sdk/markdown-table-runtime` | Ayudantes de tablas Markdown | Ayudantes de modo de tabla Markdown |
| `plugin-sdk/reply-payload` | Tipos de respuesta de mensajes | Tipos de payload de respuesta |
| `plugin-sdk/provider-setup` | Ayudantes curados de configuración de proveedores locales/autohospedados | Ayudantes de detección/configuración de proveedores autohospedados |
| `plugin-sdk/self-hosted-provider-setup` | Ayudantes específicos de configuración de proveedores autohospedados compatibles con OpenAI | Los mismos ayudantes de detección/configuración de proveedores autohospedados |
| `plugin-sdk/provider-auth-runtime` | Ayudantes de autenticación de proveedores en tiempo de ejecución | Ayudantes de resolución de claves API en tiempo de ejecución |
| `plugin-sdk/provider-auth-api-key` | Ayudantes de configuración de claves API de proveedores | Ayudantes de incorporación/escritura de perfil de clave API |
| `plugin-sdk/provider-auth-result` | Ayudantes de resultado de autenticación de proveedores | Constructor estándar de resultado de autenticación OAuth |
| `plugin-sdk/provider-auth-login` | Ayudantes de inicio de sesión interactivo de proveedores | Ayudantes compartidos de inicio de sesión interactivo |
| `plugin-sdk/provider-env-vars` | Ayudantes de variables de entorno de proveedores | Ayudantes de búsqueda de variables de entorno de autenticación del proveedor |
| `plugin-sdk/provider-model-shared` | Ayudantes compartidos de modelos/replay de proveedores | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de replay, ayudantes de endpoints de proveedores y ayudantes de normalización de id de modelos |
| `plugin-sdk/provider-catalog-shared` | Ayudantes compartidos de catálogo de proveedores | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Parches de incorporación de proveedores | Ayudantes de configuración de incorporación |
| `plugin-sdk/provider-http` | Ayudantes HTTP de proveedores | Ayudantes genéricos de HTTP/capacidades de endpoints de proveedores |
| `plugin-sdk/provider-web-fetch` | Ayudantes de web-fetch de proveedores | Ayudantes de registro/caché de proveedores web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Ayudantes de configuración de búsqueda web de proveedores | Ayudantes específicos de configuración/credenciales de búsqueda web para proveedores que no necesitan cableado de habilitación del plugin |
| `plugin-sdk/provider-web-search-contract` | Ayudantes contractuales de búsqueda web de proveedores | Ayudantes contractuales específicos de configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance |
| `plugin-sdk/provider-web-search` | Ayudantes de búsqueda web de proveedores | Ayudantes de registro/caché/entorno de ejecución de proveedores de búsqueda web |
| `plugin-sdk/provider-tools` | Ayudantes de compatibilidad de herramientas/esquemas de proveedores | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquemas Gemini y ayudantes de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Ayudantes de uso de proveedores | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` y otros ayudantes de uso de proveedores |
| `plugin-sdk/provider-stream` | Ayudantes de envoltorio de streams de proveedores | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorios de streams y ayudantes compartidos de envoltorios Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/keyed-async-queue` | Cola asíncrona ordenada | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Ayudantes compartidos de medios | Ayudantes de fetch/transformación/almacenamiento de medios más constructores de payload de medios |
| `plugin-sdk/media-generation-runtime` | Ayudantes compartidos de generación de medios | Ayudantes compartidos de failover, selección de candidatos y mensajes de modelo faltante para generación de imágenes/video/música |
| `plugin-sdk/media-understanding` | Ayudantes de comprensión de medios | Tipos de proveedores de comprensión de medios más exportaciones de ayudantes de imagen/audio orientados a proveedores |
| `plugin-sdk/text-runtime` | Ayudantes compartidos de texto | Eliminación de texto visible para el asistente, renderizado/fragmentación/tablas Markdown, ayudantes de redacción, ayudantes de etiquetas de directivas, utilidades de texto seguro y ayudantes relacionados de texto/logging |
| `plugin-sdk/text-chunking` | Ayudantes de fragmentación de texto | Ayudante de fragmentación de texto saliente |
| `plugin-sdk/speech` | Ayudantes de voz | Tipos de proveedores de voz más exportaciones orientadas a proveedores de directivas, registro y validación |
| `plugin-sdk/speech-core` | Núcleo compartido de voz | Tipos de proveedores de voz, registro, directivas, normalización |
| `plugin-sdk/realtime-transcription` | Ayudantes de transcripción en tiempo real | Tipos de proveedores y ayudantes de registro |
| `plugin-sdk/realtime-voice` | Ayudantes de voz en tiempo real | Tipos de proveedores y ayudantes de registro |
| `plugin-sdk/image-generation-core` | Núcleo compartido de generación de imágenes | Tipos de generación de imágenes, failover, autenticación y ayudantes de registro |
| `plugin-sdk/music-generation` | Ayudantes de generación musical | Tipos de proveedor/solicitud/resultado de generación musical |
| `plugin-sdk/music-generation-core` | Núcleo compartido de generación musical | Tipos de generación musical, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos |
| `plugin-sdk/video-generation` | Ayudantes de generación de video | Tipos de proveedor/solicitud/resultado de generación de video |
| `plugin-sdk/video-generation-core` | Núcleo compartido de generación de video | Tipos de generación de video, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos |
| `plugin-sdk/interactive-runtime` | Ayudantes de respuestas interactivas | Normalización/reducción de payload de respuestas interactivas |
| `plugin-sdk/channel-config-primitives` | Primitivas de configuración de canal | Primitivas específicas de esquema de configuración de canal |
| `plugin-sdk/channel-config-writes` | Helpers de escritura de configuración de canal | Helpers de autorización de escritura de configuración de canal |
| `plugin-sdk/channel-plugin-common` | Preludio compartido de canal | Exportaciones compartidas del preludio de plugin de canal |
| `plugin-sdk/channel-status` | Helpers de estado de canal | Helpers compartidos de instantánea/resumen de estado de canal |
| `plugin-sdk/allowlist-config-edit` | Helpers de configuración de lista de permitidos | Helpers de edición/lectura de configuración de lista de permitidos |
| `plugin-sdk/group-access` | Helpers de acceso a grupos | Helpers compartidos de decisión de acceso a grupos |
| `plugin-sdk/direct-dm` | Helpers de DM directo | Helpers compartidos de auth/protección para DM directo |
| `plugin-sdk/extension-shared` | Helpers compartidos de extensiones | Primitivas de canal pasivo/estado y helper de proxy ambiental |
| `plugin-sdk/webhook-targets` | Helpers de objetivos webhook | Registro de objetivos webhook y helpers de instalación de rutas |
| `plugin-sdk/webhook-path` | Helpers de ruta webhook | Helpers de normalización de ruta webhook |
| `plugin-sdk/web-media` | Helpers compartidos de medios web | Helpers de carga de medios remotos/locales |
| `plugin-sdk/zod` | Reexportación de Zod | `zod` reexportado para consumidores del plugin SDK |
| `plugin-sdk/memory-core` | Helpers empaquetados de memory-core | Superficie helper de administrador/configuración/archivo/CLI de memoria |
| `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime del motor de memoria | Fachada de runtime de índice/búsqueda de memoria |
| `plugin-sdk/channel-config-writes` | Ayudantes de escritura de configuración de canal | Ayudantes de autorización de escritura de configuración de canal |
| `plugin-sdk/channel-plugin-common` | Preludio compartido de canal | Exportaciones compartidas de preludio de plugin de canal |
| `plugin-sdk/channel-status` | Ayudantes de estado de canal | Ayudantes compartidos de instantáneas/resúmenes de estado de canal |
| `plugin-sdk/allowlist-config-edit` | Ayudantes de configuración de lista de permitidos | Ayudantes de edición/lectura de lista de permitidos |
| `plugin-sdk/group-access` | Ayudantes de acceso a grupos | Ayudantes compartidos de decisiones de acceso a grupos |
| `plugin-sdk/direct-dm` | Ayudantes de DM directo | Ayudantes compartidos de autenticación/protección de DM directo |
| `plugin-sdk/extension-shared` | Ayudantes compartidos de extensiones | Primitivas de canal/estado pasivo y ayudantes de proxy ambiental |
| `plugin-sdk/webhook-targets` | Ayudantes de destino webhook | Registro de destinos webhook y ayudantes de instalación de rutas |
| `plugin-sdk/webhook-path` | Ayudantes de ruta webhook | Ayudantes de normalización de rutas webhook |
| `plugin-sdk/web-media` | Ayudantes compartidos de medios web | Ayudantes de carga de medios remotos/locales |
| `plugin-sdk/zod` | Reexportación de Zod | Reexportación de `zod` para consumidores del SDK de plugins |
| `plugin-sdk/memory-core` | Ayudantes incluidos de memory-core | Superficie de ayudantes de gestor/configuración/archivo/CLI de memoria |
| `plugin-sdk/memory-core-engine-runtime` | Fachada de entorno de ejecución del motor de memoria | Fachada de entorno de ejecución de índice/búsqueda de memoria |
| `plugin-sdk/memory-core-host-engine-foundation` | Motor base del host de memoria | Exportaciones del motor base del host de memoria |
| `plugin-sdk/memory-core-host-engine-embeddings` | Motor de embeddings del host de memoria | Exportaciones del motor de embeddings del host de memoria |
| `plugin-sdk/memory-core-host-engine-qmd` | Motor QMD del host de memoria | Exportaciones del motor QMD del host de memoria |
| `plugin-sdk/memory-core-host-engine-storage` | Motor de almacenamiento del host de memoria | Exportaciones del motor de almacenamiento del host de memoria |
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodales del host de memoria | Helpers multimodales del host de memoria |
| `plugin-sdk/memory-core-host-query` | Helpers de consultas del host de memoria | Helpers de consultas del host de memoria |
| `plugin-sdk/memory-core-host-secret` | Helpers de secretos del host de memoria | Helpers de secretos del host de memoria |
| `plugin-sdk/memory-core-host-events` | Helpers de diario de eventos del host de memoria | Helpers de diario de eventos del host de memoria |
| `plugin-sdk/memory-core-host-status` | Helpers de estado del host de memoria | Helpers de estado del host de memoria |
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI del host de memoria | Helpers de runtime CLI del host de memoria |
| `plugin-sdk/memory-core-host-runtime-core` | Runtime principal del host de memoria | Helpers de runtime principal del host de memoria |
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de archivos/runtime del host de memoria | Helpers de archivos/runtime del host de memoria |
| `plugin-sdk/memory-host-core` | Alias de runtime principal del host de memoria | Alias neutral de proveedor para helpers del runtime principal del host de memoria |
| `plugin-sdk/memory-host-events` | Alias del diario de eventos del host de memoria | Alias neutral de proveedor para helpers del diario de eventos del host de memoria |
| `plugin-sdk/memory-host-files` | Alias de archivos/runtime del host de memoria | Alias neutral de proveedor para helpers de archivos/runtime del host de memoria |
| `plugin-sdk/memory-host-markdown` | Helpers de markdown gestionado | Helpers compartidos de markdown gestionado para plugins adyacentes a memoria |
| `plugin-sdk/memory-host-search` | Fachada activa de búsqueda en memoria | Fachada lazy del runtime del administrador de búsqueda de memoria activa |
| `plugin-sdk/memory-host-status` | Alias de estado del host de memoria | Alias neutral de proveedor para helpers de estado del host de memoria |
| `plugin-sdk/memory-lancedb` | Helpers empaquetados de memory-lancedb | Superficie helper de memory-lancedb |
| `plugin-sdk/testing` | Utilidades de prueba | Helpers y mocks de prueba |
| `plugin-sdk/memory-core-host-multimodal` | Ayudantes multimodales del host de memoria | Ayudantes multimodales del host de memoria |
| `plugin-sdk/memory-core-host-query` | Ayudantes de consultas del host de memoria | Ayudantes de consultas del host de memoria |
| `plugin-sdk/memory-core-host-secret` | Ayudantes de secretos del host de memoria | Ayudantes de secretos del host de memoria |
| `plugin-sdk/memory-core-host-events` | Ayudantes de registro de eventos del host de memoria | Ayudantes de registro de eventos del host de memoria |
| `plugin-sdk/memory-core-host-status` | Ayudantes de estado del host de memoria | Ayudantes de estado del host de memoria |
| `plugin-sdk/memory-core-host-runtime-cli` | Entorno de ejecución CLI del host de memoria | Ayudantes de entorno de ejecución CLI del host de memoria |
| `plugin-sdk/memory-core-host-runtime-core` | Entorno de ejecución central del host de memoria | Ayudantes del entorno de ejecución central del host de memoria |
| `plugin-sdk/memory-core-host-runtime-files` | Ayudantes de archivos/entorno de ejecución del host de memoria | Ayudantes de archivos/entorno de ejecución del host de memoria |
| `plugin-sdk/memory-host-core` | Alias de entorno de ejecución central del host de memoria | Alias neutral respecto al proveedor para ayudantes del entorno de ejecución central del host de memoria |
| `plugin-sdk/memory-host-events` | Alias de registro de eventos del host de memoria | Alias neutral respecto al proveedor para ayudantes del registro de eventos del host de memoria |
| `plugin-sdk/memory-host-files` | Alias de archivos/entorno de ejecución del host de memoria | Alias neutral respecto al proveedor para ayudantes de archivos/entorno de ejecución del host de memoria |
| `plugin-sdk/memory-host-markdown` | Ayudantes de Markdown gestionado | Ayudantes compartidos de Markdown gestionado para plugins cercanos a la memoria |
| `plugin-sdk/memory-host-search` | Fachada de búsqueda activa de memoria | Fachada perezosa del entorno de ejecución del gestor de búsqueda de memoria activa |
| `plugin-sdk/memory-host-status` | Alias de estado del host de memoria | Alias neutral respecto al proveedor para ayudantes de estado del host de memoria |
| `plugin-sdk/memory-lancedb` | Ayudantes incluidos de memory-lancedb | Superficie de ayudantes de memory-lancedb |
| `plugin-sdk/testing` | Utilidades de prueba | Ayudantes y mocks de prueba |
</Accordion>
Esta tabla es intencionalmente el subconjunto común de migración, no toda la
superficie del SDK. La lista completa de más de 200 puntos de entrada está en
Esta tabla es intencionalmente el subconjunto común de migración, no la superficie completa del SDK.
La lista completa de más de 200 puntos de entrada se encuentra en
`scripts/lib/plugin-sdk-entrypoints.json`.
Esa lista todavía incluye algunas superficies helper de plugins empaquetados como
Esa lista sigue incluyendo algunas uniones de ayudantes de plugins incluidos como
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup` y `plugin-sdk/matrix*`. Siguen exportándose para
mantenimiento y compatibilidad de plugins empaquetados, pero se omiten intencionalmente
mantenimiento y compatibilidad de plugins incluidos, pero se omiten intencionalmente
de la tabla común de migración y no son el objetivo recomendado para
código nuevo de plugins.
La misma regla se aplica a otras familias de helpers empaquetados como:
La misma regla se aplica a otras familias de ayudantes incluidos como:
- helpers de compatibilidad con navegador: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- ayudantes de soporte de navegador: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- Matrix: `plugin-sdk/matrix*`
- LINE: `plugin-sdk/line*`
- IRC: `plugin-sdk/irc*`
- superficies de helpers/plugins empaquetados como `plugin-sdk/googlechat`,
- superficies de ayudantes/plugins incluidos como `plugin-sdk/googlechat`,
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
@ -369,39 +371,39 @@ La misma regla se aplica a otras familias de helpers empaquetados como:
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
`plugin-sdk/thread-ownership` y `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` expone actualmente la superficie específica de helpers de token
`plugin-sdk/github-copilot-token` actualmente expone la superficie específica de ayudantes de token
`DEFAULT_COPILOT_API_BASE_URL`,
`deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken`.
Usa la importación más específica que se ajuste a la tarea. Si no encuentras una exportación,
consulta el código fuente en `src/plugin-sdk/` o pregunta en Discord.
Usa la importación más específica que se ajuste al trabajo. Si no puedes encontrar una exportación,
revisa el código fuente en `src/plugin-sdk/` o pregunta en Discord.
## Cronograma de eliminación
| Cuándo | Qué ocurre |
| -------------------- | --------------------------------------------------------------------- |
| **Ahora** | Las superficies obsoletas emiten advertencias en tiempo de ejecución |
| Cuándo | Qué ocurre |
| ---------------------- | ----------------------------------------------------------------------- |
| **Ahora** | Las superficies obsoletas emiten advertencias en tiempo de ejecución |
| **Próxima versión principal** | Las superficies obsoletas se eliminarán; los plugins que sigan usándolas fallarán |
Todos los plugins principales ya se han migrado. Los plugins externos deberían migrar
antes de la próxima versión principal.
## Suprimir temporalmente las advertencias
## Cómo suprimir temporalmente las advertencias
Configura estas variables de entorno mientras trabajas en la migración:
Establece estas variables de entorno mientras trabajas en la migración:
```bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
Esto es una vía de escape temporal, no una solución permanente.
Esta es una vía de escape temporal, no una solución permanente.
## Relacionado
- [Primeros pasos](/es/plugins/building-plugins) — crea tu primer plugin
- [Resumen del SDK](/es/plugins/sdk-overview) — referencia completa de importación por subrutas
- [Plugins de canal](/es/plugins/sdk-channel-plugins) — crear plugins de canal
- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — crear plugins de proveedor
- [Internals de plugins](/es/plugins/architecture) — análisis profundo de la arquitectura
- [Resumen del SDK](/es/plugins/sdk-overview) — referencia completa de importaciones por subruta
- [Plugins de canal](/es/plugins/sdk-channel-plugins) — creación de plugins de canal
- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — creación de plugins de proveedor
- [Aspectos internos de plugins](/es/plugins/architecture) — análisis detallado de la arquitectura
- [Manifiesto del plugin](/es/plugins/manifest) — referencia del esquema del manifiesto

563
docs/es/plugins/sdk-overview.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Necesita saber desde qué subruta del SDK importar
- Quiere una referencia de todos los métodos de registro en OpenClawPluginApi
- Está buscando una exportación específica del SDK
- Necesitas saber desde qué subruta del SDK importar
- Quieres una referencia de todos los métodos de registro en OpenClawPluginApi
- Estás buscando una exportación específica del SDK
sidebarTitle: SDK Overview
summary: Mapa de importaciones, referencia de la API de registro y arquitectura del SDK
title: Descripción general del Plugin SDK
summary: Mapa de importación, referencia de la API de registro y arquitectura del SDK
title: Resumen del Plugin SDK
x-i18n:
generated_at: "2026-04-08T02:18:05Z"
generated_at: "2026-04-09T01:30:49Z"
model: gpt-5.4
provider: openai
source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30
source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381
source_path: plugins/sdk-overview.md
workflow: 15
---
# Descripción general del Plugin SDK
# Resumen del Plugin SDK
El Plugin SDK es el contrato tipado entre los plugins y el núcleo. Esta página es la
referencia de **qué importar** y **qué se puede registrar**.
El plugin SDK es el contrato tipado entre los plugins y el núcleo. Esta página es la
referencia para **qué importar** y **qué puedes registrar**.
<Tip>
**¿Busca una guía práctica?**
- ¿Su primer plugin? Empiece con [Primeros pasos](/es/plugins/building-plugins)
- ¿Plugin de canal? Vea [Plugins de canal](/es/plugins/sdk-channel-plugins)
- ¿Plugin de proveedor? Vea [Plugins de proveedor](/es/plugins/sdk-provider-plugins)
**¿Buscas una guía práctica?**
- ¿Tu primer plugin? Empieza con [Getting Started](/es/plugins/building-plugins)
- ¿Plugin de canal? Consulta [Channel Plugins](/es/plugins/sdk-channel-plugins)
- ¿Plugin de proveedor? Consulta [Provider Plugins](/es/plugins/sdk-provider-plugins)
</Tip>
## Convención de importación
Importe siempre desde una subruta específica:
Importa siempre desde una subruta específica:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -37,35 +37,36 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Cada subruta es un módulo pequeño y autocontenido. Esto mantiene un inicio rápido y
evita problemas de dependencias circulares. Para los auxiliares específicos de entrada/compilación de canales,
prefiera `openclaw/plugin-sdk/channel-core`; reserve `openclaw/plugin-sdk/core` para
la superficie paraguas más amplia y auxiliares compartidos como
evita problemas de dependencias circulares. Para ayudantes de entrada/construcción específicos de canal,
prefiere `openclaw/plugin-sdk/channel-core`; conserva `openclaw/plugin-sdk/core` para
la superficie paraguas más amplia y ayudantes compartidos como
`buildChannelConfigSchema`.
No agregue ni dependa de capas de conveniencia con nombre de proveedor como
No agregues ni dependas de puntos de acceso de conveniencia con nombre de proveedor como
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de
capas auxiliares con marca de canal. Los plugins integrados deben componer subrutas
genéricas del SDK dentro de sus propios archivos barril `api.ts` o `runtime-api.ts`, y el núcleo
debe usar esos barriles locales del plugin o agregar un contrato del SDK genérico y acotado
cuando la necesidad sea realmente transversal a varios canales.
puntos de acceso auxiliares con marca de canal. Los plugins integrados deben componer subrutas
genéricas del SDK dentro de sus propios barrels `api.ts` o `runtime-api.ts`, y el núcleo
debe usar esos barrels locales del plugin o agregar un contrato genérico y acotado del SDK
cuando la necesidad sea realmente entre canales.
El mapa de exportaciones generado aún contiene un pequeño conjunto de
capas auxiliares para plugins integrados como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` y `plugin-sdk/matrix*`. Esas
El mapa de exportación generado todavía contiene un pequeño conjunto de puntos de acceso auxiliares
de plugins integrados como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, y `plugin-sdk/matrix*`. Esas
subrutas existen solo para mantenimiento y compatibilidad de plugins integrados; se
omiten intencionalmente de la tabla común a continuación y no son la ruta de importación recomendada para plugins nuevos de terceros.
omiten intencionalmente de la tabla común a continuación y no son la ruta de
importación recomendada para nuevos plugins de terceros.
## Referencia de subrutas
Las subrutas de uso más común, agrupadas por propósito. La lista completa generada de
Las subrutas más utilizadas, agrupadas por propósito. La lista completa generada de
más de 200 subrutas está en `scripts/lib/plugin-sdk-entrypoints.json`.
Las subrutas auxiliares reservadas para plugins integrados siguen apareciendo en esa lista generada.
Trátelas como detalles de implementación o superficies de compatibilidad, a menos que una página de documentación
Trátalas como superficies de detalle de implementación/compatibilidad a menos que una página de documentación
promocione explícitamente una como pública.
### Entrada de plugin
### Entrada del plugin
| Subruta | Exportaciones clave |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
@ -81,226 +82,229 @@ promocione explícitamente una como pública.
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Exportación del esquema Zod raíz de `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, además de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Auxiliares compartidos para el asistente de configuración, prompts de lista de permitidos y constructores de estado de configuración |
| `plugin-sdk/setup` | Ayudantes compartidos del asistente de configuración, prompts de lista de permitidos, constructores de estado de configuración |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Auxiliares de configuración/múltiples cuentas/bloqueo de acciones, y auxiliares de respaldo para cuenta predeterminada |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, auxiliares de normalización de id de cuenta |
| `plugin-sdk/account-resolution` | Búsqueda de cuentas + auxiliares de respaldo predeterminado |
| `plugin-sdk/account-helpers` | Auxiliares acotados para lista de cuentas/acciones de cuenta |
| `plugin-sdk/account-core` | Ayudantes de configuración de múltiples cuentas/puerta de acciones, ayudantes de fallback de cuenta predeterminada |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, ayudantes de normalización de id de cuenta |
| `plugin-sdk/account-resolution` | Búsqueda de cuentas + ayudantes de fallback predeterminado |
| `plugin-sdk/account-helpers` | Ayudantes acotados para lista de cuentas/acciones de cuenta |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Tipos de esquema de configuración de canal |
| `plugin-sdk/telegram-command-config` | Auxiliares de normalización/validación de comandos personalizados de Telegram con respaldo de contrato integrado |
| `plugin-sdk/telegram-command-config` | Ayudantes de normalización/validación de comandos personalizados de Telegram con fallback de contrato integrado |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Auxiliares compartidos para rutas entrantes y construcción de sobres |
| `plugin-sdk/inbound-reply-dispatch` | Auxiliares compartidos para registrar y despachar entradas |
| `plugin-sdk/messaging-targets` | Auxiliares de análisis/coincidencia de destinos |
| `plugin-sdk/outbound-media` | Auxiliares compartidos para carga de medios salientes |
| `plugin-sdk/outbound-runtime` | Auxiliares de identidad saliente y delegado de envío |
| `plugin-sdk/thread-bindings-runtime` | Auxiliares de ciclo de vida y adaptadores para enlaces de hilos |
| `plugin-sdk/agent-media-payload` | Constructor heredado de carga útil multimedia del agente |
| `plugin-sdk/conversation-runtime` | Auxiliares de enlaces de conversación/hilo, pairing y enlaces configurados |
| `plugin-sdk/runtime-config-snapshot` | Auxiliar de instantánea de configuración en tiempo de ejecución |
| `plugin-sdk/runtime-group-policy` | Auxiliares de resolución de políticas de grupo en tiempo de ejecución |
| `plugin-sdk/channel-status` | Auxiliares compartidos para instantáneas/resúmenes de estado del canal |
| `plugin-sdk/inbound-envelope` | Ayudantes compartidos de ruta entrante + construcción de sobre |
| `plugin-sdk/inbound-reply-dispatch` | Ayudantes compartidos de registro y despacho entrante |
| `plugin-sdk/messaging-targets` | Ayudantes de análisis/coincidencia de destinos |
| `plugin-sdk/outbound-media` | Ayudantes compartidos de carga de medios salientes |
| `plugin-sdk/outbound-runtime` | Ayudantes de identidad saliente/delegado de envío |
| `plugin-sdk/thread-bindings-runtime` | Ayudantes de ciclo de vida y adaptador de vinculaciones de hilo |
| `plugin-sdk/agent-media-payload` | Constructor heredado de payload de medios del agente |
| `plugin-sdk/conversation-runtime` | Ayudantes de vinculación de conversación/hilo, emparejamiento y vinculación configurada |
| `plugin-sdk/runtime-config-snapshot` | Ayudante de snapshot de configuración en tiempo de ejecución |
| `plugin-sdk/runtime-group-policy` | Ayudantes de resolución de políticas de grupo en tiempo de ejecución |
| `plugin-sdk/channel-status` | Ayudantes compartidos de snapshot/resumen del estado del canal |
| `plugin-sdk/channel-config-primitives` | Primitivas acotadas de esquema de configuración de canal |
| `plugin-sdk/channel-config-writes` | Auxiliares de autorización para escritura de configuración de canal |
| `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas para plugins de canal |
| `plugin-sdk/allowlist-config-edit` | Auxiliares para leer/editar configuración de listas de permitidos |
| `plugin-sdk/group-access` | Auxiliares compartidos para decisiones de acceso a grupos |
| `plugin-sdk/direct-dm` | Auxiliares compartidos de autenticación/protección de DM directos |
| `plugin-sdk/interactive-runtime` | Auxiliares de normalización/reducción de cargas útiles de respuestas interactivas |
| `plugin-sdk/channel-inbound` | Auxiliares para debounce de entrada, coincidencia de menciones, políticas de mención y sobres |
| `plugin-sdk/channel-send-result` | Tipos de resultados de respuesta |
| `plugin-sdk/channel-config-writes` | Ayudantes de autorización para escrituras de configuración de canal |
| `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas de plugins de canal |
| `plugin-sdk/allowlist-config-edit` | Ayudantes de edición/lectura de configuración de lista de permitidos |
| `plugin-sdk/group-access` | Ayudantes compartidos de decisión de acceso a grupos |
| `plugin-sdk/direct-dm` | Ayudantes compartidos de autenticación/protección de DM directa |
| `plugin-sdk/interactive-runtime` | Ayudantes de normalización/reducción de payload de respuesta interactiva |
| `plugin-sdk/channel-inbound` | Ayudantes de debounce entrante, coincidencia de menciones, política de menciones y sobres |
| `plugin-sdk/channel-send-result` | Tipos de resultado de respuesta |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | Auxiliares de análisis/coincidencia de destinos |
| `plugin-sdk/channel-contract` | Tipos de contratos de canal |
| `plugin-sdk/channel-targets` | Ayudantes de análisis/coincidencia de destinos |
| `plugin-sdk/channel-contract` | Tipos de contrato de canal |
| `plugin-sdk/channel-feedback` | Cableado de feedback/reacciones |
| `plugin-sdk/channel-secret-runtime` | Auxiliares acotados de contrato de secretos como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` y tipos de destino de secretos |
| `plugin-sdk/channel-secret-runtime` | Ayudantes acotados de contrato de secretos como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, y tipos de destino de secretos |
</Accordion>
<Accordion title="Subrutas de proveedor">
| Subruta | Exportaciones clave |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Auxiliares seleccionados para configurar proveedores locales/autohospedados |
| `plugin-sdk/self-hosted-provider-setup` | Auxiliares centrados en la configuración de proveedores autohospedados compatibles con OpenAI |
| `plugin-sdk/cli-backend` | Valores predeterminados del backend de CLI + constantes de watchdog |
| `plugin-sdk/provider-auth-runtime` | Auxiliares de resolución de claves de API en tiempo de ejecución para plugins de proveedor |
| `plugin-sdk/provider-auth-api-key` | Auxiliares de incorporación/escritura de perfiles de claves de API como `upsertApiKeyProfile` |
| `plugin-sdk/provider-setup` | Ayudantes curados de configuración de proveedores locales/autohospedados |
| `plugin-sdk/self-hosted-provider-setup` | Ayudantes centrados en la configuración de proveedores autohospedados compatibles con OpenAI |
| `plugin-sdk/cli-backend` | Valores predeterminados del backend CLI + constantes watchdog |
| `plugin-sdk/provider-auth-runtime` | Ayudantes de resolución de claves API en tiempo de ejecución para plugins de proveedores |
| `plugin-sdk/provider-auth-api-key` | Ayudantes de incorporación/escritura de perfiles para claves API como `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Constructor estándar de resultados de autenticación OAuth |
| `plugin-sdk/provider-auth-login` | Auxiliares interactivos compartidos de inicio de sesión para plugins de proveedor |
| `plugin-sdk/provider-env-vars` | Auxiliares de búsqueda de variables de entorno para autenticación de proveedor |
| `plugin-sdk/provider-auth-login` | Ayudantes compartidos de inicio de sesión interactivo para plugins de proveedores |
| `plugin-sdk/provider-env-vars` | Ayudantes de búsqueda de variables de entorno de autenticación de proveedor |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, auxiliares de endpoint de proveedor y normalización de id de modelo como `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de política de reproducción, ayudantes de endpoints de proveedor, y ayudantes de normalización de identificadores de modelo como `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Auxiliares genéricos de HTTP/capacidades de endpoint para proveedores |
| `plugin-sdk/provider-web-fetch-contract` | Auxiliares acotados para contratos de configuración/selección de web fetch como `enablePluginInConfig` y `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Auxiliares de registro/caché de proveedores de web fetch |
| `plugin-sdk/provider-web-search-contract` | Auxiliares acotados para contratos de configuración/credenciales de búsqueda web como `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance |
| `plugin-sdk/provider-web-search` | Auxiliares de registro/caché/tiempo de ejecución para proveedores de búsqueda web |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquemas Gemini y auxiliares de compatibilidad de xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-http` | Ayudantes genéricos de capacidades HTTP/endpoint para proveedores |
| `plugin-sdk/provider-web-fetch-contract` | Ayudantes acotados de contrato para configuración/selección de web-fetch como `enablePluginInConfig` y `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Ayudantes de registro/caché de proveedores web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Ayudantes acotados de configuración/credenciales de búsqueda web para proveedores que no necesitan cableado de habilitación del plugin |
| `plugin-sdk/provider-web-search-contract` | Ayudantes acotados de contrato para configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, y setters/getters de credenciales con ámbito |
| `plugin-sdk/provider-web-search` | Ayudantes de registro/caché/tiempo de ejecución de proveedores de búsqueda web |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquemas Gemini, y ayudantes de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` y similares |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorios de streaming y auxiliares compartidos de envoltorios para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | Auxiliares de parches de configuración para onboarding |
| `plugin-sdk/global-singleton` | Auxiliares de singleton/mapa/caché locales al proceso |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de envoltorios de stream, y ayudantes compartidos de envoltorios para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | Ayudantes de parcheo de configuración para onboarding |
| `plugin-sdk/global-singleton` | Ayudantes de singleton/mapa/caché locales al proceso |
</Accordion>
<Accordion title="Subrutas de autenticación y seguridad">
| Subruta | Exportaciones clave |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, auxiliares de registro de comandos, auxiliares de autorización de remitentes |
| `plugin-sdk/approval-auth-runtime` | Resolución de aprobadores y auxiliares de autenticación de acciones en el mismo chat |
| `plugin-sdk/approval-client-runtime` | Auxiliares nativos de perfiles/filtros de aprobación de exec |
| `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidad/entrega de aprobaciones |
| `plugin-sdk/approval-gateway-runtime` | Auxiliar compartido de resolución del gateway de aprobaciones |
| `plugin-sdk/approval-handler-adapter-runtime` | Auxiliares ligeros de carga de adaptadores nativos de aprobación para puntos de entrada de canales de acceso frecuente |
| `plugin-sdk/approval-handler-runtime` | Auxiliares más amplios de tiempo de ejecución para controladores de aprobación; prefiera las capas más acotadas de adaptador/gateway cuando sean suficientes |
| `plugin-sdk/approval-native-runtime` | Auxiliares nativos de destino de aprobación y enlace de cuentas |
| `plugin-sdk/approval-reply-runtime` | Auxiliares de cargas útiles de respuesta para aprobaciones de exec/plugin |
| `plugin-sdk/command-auth-native` | Autenticación nativa de comandos + auxiliares nativos de destino de sesión |
| `plugin-sdk/command-detection` | Auxiliares compartidos de detección de comandos |
| `plugin-sdk/command-surface` | Auxiliares de normalización del cuerpo del comando y de superficie de comandos |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, ayudantes de registro de comandos, ayudantes de autorización del remitente |
| `plugin-sdk/command-status` | Constructores de mensajes de comando/ayuda como `buildCommandsMessagePaginated` y `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Resolución de aprobadores y ayudantes de autenticación de acciones en el mismo chat |
| `plugin-sdk/approval-client-runtime` | Ayudantes de perfiles/filtros de aprobación nativa de ejecución |
| `plugin-sdk/approval-delivery-runtime` | Adaptadores compartidos de capacidad/entrega de aprobación nativa |
| `plugin-sdk/approval-gateway-runtime` | Ayudante compartido de resolución de gateway de aprobación |
| `plugin-sdk/approval-handler-adapter-runtime` | Ayudantes ligeros de carga de adaptadores de aprobación nativa para entrypoints rápidos de canal |
| `plugin-sdk/approval-handler-runtime` | Ayudantes más amplios del tiempo de ejecución del manejador de aprobación; prefiere los puntos de acceso más acotados de adaptador/gateway cuando sean suficientes |
| `plugin-sdk/approval-native-runtime` | Ayudantes de destino de aprobación nativa + vinculación de cuenta |
| `plugin-sdk/approval-reply-runtime` | Ayudantes de payload de respuesta de aprobación de exec/plugin |
| `plugin-sdk/command-auth-native` | Ayudantes de autenticación de comandos nativos + destinos de sesión nativa |
| `plugin-sdk/command-detection` | Ayudantes compartidos de detección de comandos |
| `plugin-sdk/command-surface` | Ayudantes de normalización del cuerpo de comandos y superficie de comandos |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Auxiliares acotados de recopilación de contratos de secretos para superficies de secretos de canales/plugins |
| `plugin-sdk/secret-ref-runtime` | Auxiliares acotados `coerceSecretRef` y de tipado de SecretRef para análisis de contratos/configuración de secretos |
| `plugin-sdk/security-runtime` | Auxiliares compartidos de confianza, control de DM, contenido externo y recopilación de secretos |
| `plugin-sdk/ssrf-policy` | Auxiliares de lista de permitidos de hosts y política SSRF de red privada |
| `plugin-sdk/ssrf-runtime` | Dispatcher fijado, fetch protegido por SSRF y auxiliares de política SSRF |
| `plugin-sdk/secret-input` | Auxiliares de análisis de entradas secretas |
| `plugin-sdk/webhook-ingress` | Auxiliares para solicitudes/destinos de webhook |
| `plugin-sdk/webhook-request-guards` | Auxiliares para tamaño de cuerpo/tiempo de espera de solicitudes |
| `plugin-sdk/channel-secret-runtime` | Ayudantes acotados de recopilación de contratos de secretos para superficies secretas de canal/plugin |
| `plugin-sdk/secret-ref-runtime` | Ayudantes acotados `coerceSecretRef` y de tipado SecretRef para análisis de contratos/configuración de secretos |
| `plugin-sdk/security-runtime` | Ayudantes compartidos de confianza, protección de DM, contenido externo y recopilación de secretos |
| `plugin-sdk/ssrf-policy` | Ayudantes de lista de permitidos de hosts y política SSRF de red privada |
| `plugin-sdk/ssrf-runtime` | Ayudantes de dispatcher fijado, fetch protegido con SSRF y política SSRF |
| `plugin-sdk/secret-input` | Ayudantes de análisis de entradas secretas |
| `plugin-sdk/webhook-ingress` | Ayudantes de solicitudes/destinos de webhook |
| `plugin-sdk/webhook-request-guards` | Ayudantes de tamaño del cuerpo de la solicitud/timeout |
</Accordion>
<Accordion title="Subrutas de tiempo de ejecución y almacenamiento">
| Subruta | Exportaciones clave |
| --- | --- |
| `plugin-sdk/runtime` | Auxiliares amplios de tiempo de ejecución/registro/copias de seguridad/instalación de plugins |
| `plugin-sdk/runtime-env` | Auxiliares acotados de entorno de ejecución, logger, timeout, retry y backoff |
| `plugin-sdk/channel-runtime-context` | Auxiliares genéricos de registro y búsqueda de contexto de tiempo de ejecución del canal |
| `plugin-sdk/runtime` | Ayudantes amplios de tiempo de ejecución/logging/copias de seguridad/instalación de plugins |
| `plugin-sdk/runtime-env` | Ayudantes acotados de entorno de ejecución, logger, timeout, reintento y backoff |
| `plugin-sdk/channel-runtime-context` | Ayudantes genéricos de registro y búsqueda de contexto de tiempo de ejecución de canal |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Auxiliares compartidos para comandos/hooks/http/elementos interactivos del plugin |
| `plugin-sdk/hook-runtime` | Auxiliares compartidos del flujo de webhook/hooks internos |
| `plugin-sdk/lazy-runtime` | Auxiliares de importación/vinculación diferida del tiempo de ejecución como `createLazyRuntimeModule`, `createLazyRuntimeMethod` y `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Auxiliares para ejecución de procesos |
| `plugin-sdk/cli-runtime` | Auxiliares de formato, espera y versión para CLI |
| `plugin-sdk/gateway-runtime` | Cliente del gateway y auxiliares de parches para estado de canales |
| `plugin-sdk/config-runtime` | Auxiliares para cargar/escribir configuración |
| `plugin-sdk/telegram-command-config` | Normalización de nombre/descripción de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato integrada de Telegram no está disponible |
| `plugin-sdk/approval-runtime` | Auxiliares de aprobación de exec/plugin, constructores de capacidades de aprobación, auxiliares de autenticación/perfiles y auxiliares nativos de enrutamiento/tiempo de ejecución |
| `plugin-sdk/reply-runtime` | Auxiliares compartidos para entradas/respuestas en tiempo de ejecución, fragmentación, despacho, heartbeat y planificador de respuestas |
| `plugin-sdk/reply-dispatch-runtime` | Auxiliares acotados para despacho/finalización de respuestas |
| `plugin-sdk/reply-history` | Auxiliares compartidos para historial de respuestas en ventanas cortas como `buildHistoryContext`, `recordPendingHistoryEntry` y `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/plugin-runtime` | Ayudantes compartidos de comandos/hooks/http/interacción de plugins |
| `plugin-sdk/hook-runtime` | Ayudantes compartidos de pipeline de hooks webhook/internos |
| `plugin-sdk/lazy-runtime` | Ayudantes de importación/vinculación lazy en tiempo de ejecución como `createLazyRuntimeModule`, `createLazyRuntimeMethod`, y `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Ayudantes de ejecución de procesos |
| `plugin-sdk/cli-runtime` | Ayudantes de formato CLI, espera y versión |
| `plugin-sdk/gateway-runtime` | Ayudantes de cliente de gateway y parcheo de estado de canal |
| `plugin-sdk/config-runtime` | Ayudantes de carga/escritura de configuración |
| `plugin-sdk/telegram-command-config` | Normalización de nombres/descripciones de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato integrada de Telegram no está disponible |
| `plugin-sdk/approval-runtime` | Ayudantes de aprobación de exec/plugin, constructores de capacidad de aprobación, ayudantes de autenticación/perfiles, y ayudantes nativos de enrutamiento/tiempo de ejecución |
| `plugin-sdk/reply-runtime` | Ayudantes compartidos de tiempo de ejecución para entrada/respuesta, fragmentación, despacho, heartbeat, planificador de respuestas |
| `plugin-sdk/reply-dispatch-runtime` | Ayudantes acotados para despacho/finalización de respuestas |
| `plugin-sdk/reply-history` | Ayudantes compartidos de historial de respuestas de ventana corta como `buildHistoryContext`, `recordPendingHistoryEntry`, y `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Auxiliares acotados de fragmentación de texto/Markdown |
| `plugin-sdk/session-store-runtime` | Auxiliares de rutas del almacén de sesiones + `updated-at` |
| `plugin-sdk/state-paths` | Auxiliares de rutas de directorios de estado/OAuth |
| `plugin-sdk/routing` | Auxiliares de ruta/clave de sesión/enlace de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Auxiliares compartidos para resúmenes de estado de canal/cuenta, valores predeterminados del estado de ejecución y auxiliares de metadatos de incidencias |
| `plugin-sdk/target-resolver-runtime` | Auxiliares compartidos de resolución de destinos |
| `plugin-sdk/string-normalization-runtime` | Auxiliares de normalización de slug/cadenas |
| `plugin-sdk/request-url` | Extrae URL en cadena de entradas tipo fetch/request |
| `plugin-sdk/run-command` | Ejecutor de comandos temporizado con resultados normalizados de stdout/stderr |
| `plugin-sdk/param-readers` | Lectores comunes de parámetros de herramientas/CLI |
| `plugin-sdk/tool-send` | Extrae campos canónicos de destino de envío a partir de argumentos de herramientas |
| `plugin-sdk/temp-path` | Auxiliares compartidos para rutas temporales de descarga |
| `plugin-sdk/logging-core` | Logger de subsistema y auxiliares de redacción |
| `plugin-sdk/markdown-table-runtime` | Auxiliares del modo de tablas Markdown |
| `plugin-sdk/json-store` | Auxiliares pequeños para leer/escribir estado JSON |
| `plugin-sdk/file-lock` | Auxiliares reentrantes de bloqueo de archivos |
| `plugin-sdk/persistent-dedupe` | Auxiliares de caché de deduplicación respaldada por disco |
| `plugin-sdk/acp-runtime` | Auxiliares de tiempo de ejecución/sesión ACP y despacho de respuestas |
| `plugin-sdk/reply-chunking` | Ayudantes acotados de fragmentación de texto/markdown |
| `plugin-sdk/session-store-runtime` | Ayudantes de ruta de almacén de sesiones + `updated-at` |
| `plugin-sdk/state-paths` | Ayudantes de rutas de directorios de estado/OAuth |
| `plugin-sdk/routing` | Ayudantes de vinculación de rutas/claves de sesión/cuentas como `resolveAgentRoute`, `buildAgentSessionKey`, y `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Ayudantes compartidos de resumen de estado de canal/cuenta, valores predeterminados de estado de tiempo de ejecución y ayudantes de metadatos de incidencias |
| `plugin-sdk/target-resolver-runtime` | Ayudantes compartidos de resolución de destinos |
| `plugin-sdk/string-normalization-runtime` | Ayudantes de normalización de slug/cadenas |
| `plugin-sdk/request-url` | Extrae URL de cadena desde entradas tipo fetch/request |
| `plugin-sdk/run-command` | Ejecutor de comandos temporizado con resultados stdout/stderr normalizados |
| `plugin-sdk/param-readers` | Lectores comunes de parámetros para herramientas/CLI |
| `plugin-sdk/tool-payload` | Extrae payloads normalizados desde objetos de resultado de herramientas |
| `plugin-sdk/tool-send` | Extrae campos de destino de envío canónicos desde argumentos de herramientas |
| `plugin-sdk/temp-path` | Ayudantes compartidos de rutas temporales de descarga |
| `plugin-sdk/logging-core` | Logger de subsistema y ayudantes de redacción |
| `plugin-sdk/markdown-table-runtime` | Ayudantes de modo de tabla Markdown |
| `plugin-sdk/json-store` | Pequeños ayudantes de lectura/escritura de estado JSON |
| `plugin-sdk/file-lock` | Ayudantes reentrantes de bloqueo de archivos |
| `plugin-sdk/persistent-dedupe` | Ayudantes de caché de deduplicación persistente en disco |
| `plugin-sdk/acp-runtime` | Ayudantes de tiempo de ejecución/sesión ACP y de despacho de respuestas |
| `plugin-sdk/agent-config-primitives` | Primitivas acotadas de esquema de configuración de tiempo de ejecución del agente |
| `plugin-sdk/boolean-param` | Lector flexible de parámetros booleanos |
| `plugin-sdk/dangerous-name-runtime` | Auxiliares de resolución para coincidencias de nombres peligrosos |
| `plugin-sdk/device-bootstrap` | Auxiliares de arranque de dispositivos y tokens de pairing |
| `plugin-sdk/extension-shared` | Primitivas auxiliares compartidas para canales pasivos, estado y proxy ambiental |
| `plugin-sdk/models-provider-runtime` | Auxiliares de comandos `/models` y respuestas de proveedor |
| `plugin-sdk/skill-commands-runtime` | Auxiliares para listados de comandos de Skills |
| `plugin-sdk/native-command-registry` | Auxiliares nativos de registro/construcción/serialización de comandos |
| `plugin-sdk/provider-zai-endpoint` | Auxiliares de detección de endpoints de Z.AI |
| `plugin-sdk/infra-runtime` | Auxiliares de eventos del sistema/heartbeat |
| `plugin-sdk/collection-runtime` | Auxiliares pequeños de caché acotada |
| `plugin-sdk/diagnostic-runtime` | Auxiliares de indicadores y eventos de diagnóstico |
| `plugin-sdk/error-runtime` | Grafo de errores, formato, auxiliares compartidos de clasificación de errores, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Fetch envuelto, proxy y auxiliares de búsqueda fijada |
| `plugin-sdk/host-runtime` | Auxiliares de normalización de hostname y host SCP |
| `plugin-sdk/retry-runtime` | Auxiliares de configuración y ejecución de retry |
| `plugin-sdk/agent-runtime` | Auxiliares de directorio/identidad/espacio de trabajo del agente |
| `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorios respaldadas por configuración |
| `plugin-sdk/dangerous-name-runtime` | Ayudantes de resolución para coincidencia de nombres peligrosos |
| `plugin-sdk/device-bootstrap` | Ayudantes de bootstrap del dispositivo y tokens de emparejamiento |
| `plugin-sdk/extension-shared` | Primitivas auxiliares compartidas para canal pasivo, estado y proxy ambiental |
| `plugin-sdk/models-provider-runtime` | Ayudantes del comando `/models` y de respuesta de proveedores |
| `plugin-sdk/skill-commands-runtime` | Ayudantes de listado de comandos de Skills |
| `plugin-sdk/native-command-registry` | Ayudantes de registro/construcción/serialización de comandos nativos |
| `plugin-sdk/provider-zai-endpoint` | Ayudantes de detección de endpoints de Z.AI |
| `plugin-sdk/infra-runtime` | Ayudantes de eventos del sistema/heartbeat |
| `plugin-sdk/collection-runtime` | Pequeños ayudantes de caché acotada |
| `plugin-sdk/diagnostic-runtime` | Ayudantes de indicadores y eventos de diagnóstico |
| `plugin-sdk/error-runtime` | Grafo de errores, formato, ayudantes compartidos de clasificación de errores, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Ayudantes de fetch envuelto, proxy y búsquedas fijadas |
| `plugin-sdk/host-runtime` | Ayudantes de normalización de hostname y host SCP |
| `plugin-sdk/retry-runtime` | Ayudantes de configuración y ejecución de reintentos |
| `plugin-sdk/agent-runtime` | Ayudantes de directorio/identidad/workspace del agente |
| `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorios respaldada por configuración |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Subrutas de capacidades y pruebas">
| Subruta | Exportaciones clave |
| --- | --- |
| `plugin-sdk/media-runtime` | Auxiliares compartidos para obtener/transformar/almacenar medios, además de constructores de cargas útiles multimedia |
| `plugin-sdk/media-generation-runtime` | Auxiliares compartidos para failover de generación multimedia, selección de candidatos y mensajes de falta de modelo |
| `plugin-sdk/media-understanding` | Tipos de proveedores de comprensión multimedia más exportaciones orientadas a proveedores para auxiliares de imagen/audio |
| `plugin-sdk/text-runtime` | Auxiliares compartidos para texto/Markdown/registro como eliminación de texto visible para el asistente, renderizado/fragmentación/tablas Markdown, auxiliares de redacción, auxiliares de etiquetas de directivas y utilidades de texto seguro |
| `plugin-sdk/text-chunking` | Auxiliar de fragmentación de texto saliente |
| `plugin-sdk/speech` | Tipos de proveedores de voz más auxiliares orientados a proveedores para directivas, registro y validación |
| `plugin-sdk/speech-core` | Tipos compartidos de proveedores de voz, registro, directivas y auxiliares de normalización |
| `plugin-sdk/realtime-transcription` | Tipos de proveedores de transcripción en tiempo real y auxiliares de registro |
| `plugin-sdk/realtime-voice` | Tipos de proveedores de voz en tiempo real y auxiliares de registro |
| `plugin-sdk/image-generation` | Tipos de proveedores de generación de imágenes |
| `plugin-sdk/image-generation-core` | Tipos compartidos de generación de imágenes, failover, autenticación y auxiliares de registro |
| `plugin-sdk/music-generation` | Tipos de proveedores/solicitudes/resultados de generación musical |
| `plugin-sdk/music-generation-core` | Tipos compartidos de generación musical, auxiliares de failover, búsqueda de proveedores y análisis de referencias de modelos |
| `plugin-sdk/video-generation` | Tipos de proveedores/solicitudes/resultados de generación de video |
| `plugin-sdk/video-generation-core` | Tipos compartidos de generación de video, auxiliares de failover, búsqueda de proveedores y análisis de referencias de modelos |
| `plugin-sdk/webhook-targets` | Registro de destinos de webhook y auxiliares de instalación de rutas |
| `plugin-sdk/webhook-path` | Auxiliares de normalización de rutas de webhook |
| `plugin-sdk/web-media` | Auxiliares compartidos para carga de medios remotos/locales |
| `plugin-sdk/zod` | Reexportación de `zod` para consumidores del Plugin SDK |
| `plugin-sdk/media-runtime` | Ayudantes compartidos de obtención/transformación/almacenamiento de medios más constructores de payload de medios |
| `plugin-sdk/media-generation-runtime` | Ayudantes compartidos de failover en generación de medios, selección de candidatos y mensajes de modelo ausente |
| `plugin-sdk/media-understanding` | Tipos de proveedor de comprensión de medios más exportaciones auxiliares de imagen/audio para proveedores |
| `plugin-sdk/text-runtime` | Ayudantes compartidos de texto/markdown/logging como eliminación de texto visible para el asistente, renderizado/fragmentación/tablas de markdown, ayudantes de redacción, ayudantes de etiquetas de directivas y utilidades de texto seguro |
| `plugin-sdk/text-chunking` | Ayudante de fragmentación de texto saliente |
| `plugin-sdk/speech` | Tipos de proveedor de voz más exportaciones auxiliares de directivas, registro y validación para proveedores |
| `plugin-sdk/speech-core` | Tipos compartidos de proveedor de voz, registro, directivas y ayudantes de normalización |
| `plugin-sdk/realtime-transcription` | Tipos de proveedor de transcripción en tiempo real y ayudantes de registro |
| `plugin-sdk/realtime-voice` | Tipos de proveedor de voz en tiempo real y ayudantes de registro |
| `plugin-sdk/image-generation` | Tipos de proveedor de generación de imágenes |
| `plugin-sdk/image-generation-core` | Tipos compartidos de generación de imágenes, failover, autenticación y ayudantes de registro |
| `plugin-sdk/music-generation` | Tipos de proveedor/solicitud/resultado de generación musical |
| `plugin-sdk/music-generation-core` | Tipos compartidos de generación musical, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos |
| `plugin-sdk/video-generation` | Tipos de proveedor/solicitud/resultado de generación de video |
| `plugin-sdk/video-generation-core` | Tipos compartidos de generación de video, ayudantes de failover, búsqueda de proveedores y análisis de referencias de modelos |
| `plugin-sdk/webhook-targets` | Registro de destinos webhook y ayudantes de instalación de rutas |
| `plugin-sdk/webhook-path` | Ayudantes de normalización de rutas webhook |
| `plugin-sdk/web-media` | Ayudantes compartidos de carga de medios remotos/locales |
| `plugin-sdk/zod` | `zod` reexportado para consumidores del plugin SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Subrutas de memoria">
| Subruta | Exportaciones clave |
| --- | --- |
| `plugin-sdk/memory-core` | Superficie auxiliar integrada de memory-core para auxiliares de administrador/configuración/archivos/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Fachada de tiempo de ejecución para indexación/búsqueda en memoria |
| `plugin-sdk/memory-core` | Superficie auxiliar integrada memory-core para ayudantes de manager/config/archivos/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Fachada de tiempo de ejecución para índice/búsqueda de memoria |
| `plugin-sdk/memory-core-host-engine-foundation` | Exportaciones del motor base del host de memoria |
| `plugin-sdk/memory-core-host-engine-embeddings` | Exportaciones del motor de embeddings del host de memoria |
| `plugin-sdk/memory-core-host-engine-qmd` | Exportaciones del motor QMD del host de memoria |
| `plugin-sdk/memory-core-host-engine-storage` | Exportaciones del motor de almacenamiento del host de memoria |
| `plugin-sdk/memory-core-host-multimodal` | Auxiliares multimodales del host de memoria |
| `plugin-sdk/memory-core-host-query` | Auxiliares de consulta del host de memoria |
| `plugin-sdk/memory-core-host-secret` | Auxiliares de secretos del host de memoria |
| `plugin-sdk/memory-core-host-events` | Auxiliares del diario de eventos del host de memoria |
| `plugin-sdk/memory-core-host-status` | Auxiliares de estado del host de memoria |
| `plugin-sdk/memory-core-host-runtime-cli` | Auxiliares de tiempo de ejecución CLI del host de memoria |
| `plugin-sdk/memory-core-host-runtime-core` | Auxiliares principales de tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-core-host-runtime-files` | Auxiliares de archivos/tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-host-core` | Alias neutral respecto al proveedor para auxiliares principales de tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-host-events` | Alias neutral respecto al proveedor para auxiliares del diario de eventos del host de memoria |
| `plugin-sdk/memory-host-files` | Alias neutral respecto al proveedor para auxiliares de archivos/tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-host-markdown` | Auxiliares compartidos de Markdown administrado para plugins adyacentes a memoria |
| `plugin-sdk/memory-host-search` | Fachada de tiempo de ejecución activa de memoria para acceso al administrador de búsqueda |
| `plugin-sdk/memory-host-status` | Alias neutral respecto al proveedor para auxiliares de estado del host de memoria |
| `plugin-sdk/memory-lancedb` | Superficie auxiliar integrada de memory-lancedb |
| `plugin-sdk/memory-core-host-multimodal` | Ayudantes multimodales del host de memoria |
| `plugin-sdk/memory-core-host-query` | Ayudantes de consulta del host de memoria |
| `plugin-sdk/memory-core-host-secret` | Ayudantes de secretos del host de memoria |
| `plugin-sdk/memory-core-host-events` | Ayudantes del diario de eventos del host de memoria |
| `plugin-sdk/memory-core-host-status` | Ayudantes de estado del host de memoria |
| `plugin-sdk/memory-core-host-runtime-cli` | Ayudantes de tiempo de ejecución CLI del host de memoria |
| `plugin-sdk/memory-core-host-runtime-core` | Ayudantes centrales de tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-core-host-runtime-files` | Ayudantes de archivos/tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-host-core` | Alias neutral respecto al proveedor para los ayudantes centrales de tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-host-events` | Alias neutral respecto al proveedor para los ayudantes del diario de eventos del host de memoria |
| `plugin-sdk/memory-host-files` | Alias neutral respecto al proveedor para los ayudantes de archivos/tiempo de ejecución del host de memoria |
| `plugin-sdk/memory-host-markdown` | Ayudantes compartidos de markdown administrado para plugins adyacentes a memoria |
| `plugin-sdk/memory-host-search` | Fachada activa de tiempo de ejecución de memoria para acceso al gestor de búsquedas |
| `plugin-sdk/memory-host-status` | Alias neutral respecto al proveedor para los ayudantes de estado del host de memoria |
| `plugin-sdk/memory-lancedb` | Superficie auxiliar integrada memory-lancedb |
</Accordion>
<Accordion title="Subrutas reservadas de auxiliares integrados">
<Accordion title="Subrutas reservadas de ayudas integradas">
| Familia | Subrutas actuales | Uso previsto |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Auxiliares de soporte del plugin Browser integrado (`browser-support` sigue siendo el barril de compatibilidad) |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Ayudantes de soporte para el plugin integrado de navegador (`browser-support` sigue siendo el barrel de compatibilidad) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie auxiliar/de tiempo de ejecución integrada de Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie auxiliar/de tiempo de ejecución integrada de LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie auxiliar integrada de IRC |
| Auxiliares específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Capas auxiliares/de compatibilidad para canales integrados |
| Auxiliares específicos de autenticación/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Capas auxiliares para funciones/plugins integrados; `plugin-sdk/github-copilot-token` actualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` |
| Ayudantes específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Puntos de acceso de compatibilidad/ayuda para canales integrados |
| Ayudantes específicos de auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Puntos de acceso auxiliares de funciones/plugins integrados; `plugin-sdk/github-copilot-token` exporta actualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, y `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## API de registro
La devolución de llamada `register(api)` recibe un objeto `OpenClawPluginApi` con estos
El callback `register(api)` recibe un objeto `OpenClawPluginApi` con estos
métodos:
### Registro de capacidades
@ -308,42 +312,42 @@ métodos:
| Método | Qué registra |
| ------------------------------------------------ | ------------------------------- |
| `api.registerProvider(...)` | Inferencia de texto (LLM) |
| `api.registerCliBackend(...)` | Backend de inferencia CLI local |
| `api.registerCliBackend(...)` | Backend local de inferencia CLI |
| `api.registerChannel(...)` | Canal de mensajería |
| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real por streaming |
| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex |
| `api.registerRealtimeVoiceProvider(...)` | Sesiones dúplex de voz en tiempo real |
| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video |
| `api.registerImageGenerationProvider(...)` | Generación de imágenes |
| `api.registerMusicGenerationProvider(...)` | Generación musical |
| `api.registerMusicGenerationProvider(...)` | Generación de música |
| `api.registerVideoGenerationProvider(...)` | Generación de video |
| `api.registerWebFetchProvider(...)` | Proveedor de obtención / scraping web |
| `api.registerWebFetchProvider(...)` | Proveedor de obtención/scraping web |
| `api.registerWebSearchProvider(...)` | Búsqueda web |
### Herramientas y comandos
| Método | Qué registra |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Herramienta del agente (obligatoria o `{ optional: true }`) |
| `api.registerCommand(def)` | Comando personalizado (omite el LLM) |
| Método | Qué registra |
| ------------------------------- | -------------------------------------------- |
| `api.registerTool(tool, opts?)` | Herramienta del agente (requerida o `{ optional: true }`) |
| `api.registerCommand(def)` | Comando personalizado (omite el LLM) |
### Infraestructura
| Método | Qué registra |
| ---------------------------------------------- | -------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook de eventos |
| `api.registerHttpRoute(params)` | Endpoint HTTP del gateway |
| `api.registerGatewayMethod(name, handler)` | Método RPC del gateway |
| `api.registerCli(registrar, opts?)` | Subcomando CLI |
| `api.registerHttpRoute(params)` | Endpoint HTTP de la gateway |
| `api.registerGatewayMethod(name, handler)` | Método RPC de la gateway |
| `api.registerCli(registrar, opts?)` | Subcomando de CLI |
| `api.registerService(service)` | Servicio en segundo plano |
| `api.registerInteractiveHandler(registration)` | Controlador interactivo |
| `api.registerMemoryPromptSupplement(builder)` | Sección aditiva del prompt adyacente a memoria |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de lectura/búsqueda de memoria |
| `api.registerInteractiveHandler(registration)` | Manejador interactivo |
| `api.registerMemoryPromptSupplement(builder)` | Sección de prompt aditiva adyacente a memoria |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de búsqueda/lectura de memoria |
Los espacios de nombres administrativos reservados del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) siempre permanecen como `operator.admin`, incluso si un plugin intenta asignar
un alcance más restringido a un método del gateway. Prefiera prefijos específicos del plugin para
los métodos propiedad del plugin.
`update.*`) siempre permanecen como `operator.admin`, incluso si un plugin intenta asignar un
ámbito más restringido a un método de gateway. Prefiere prefijos específicos del plugin para
métodos propiedad del plugin.
### Metadatos de registro de CLI
@ -351,10 +355,10 @@ los métodos propiedad del plugin.
- `commands`: raíces de comandos explícitas propiedad del registrador
- `descriptors`: descriptores de comandos en tiempo de análisis usados para la ayuda del CLI raíz,
el enrutamiento y el registro diferido del CLI del plugin
enrutamiento y registro lazy del CLI del plugin
Si quiere que un comando del plugin siga cargándose de forma diferida en la ruta normal del CLI raíz,
proporcione `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese
Si quieres que un comando de plugin permanezca con lazy-loading en la ruta normal del CLI raíz,
proporciona `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese
registrador.
```typescript
@ -367,7 +371,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "Administrar cuentas, verificación, dispositivos y estado de perfil de Matrix",
description: "Administra cuentas, verificación, dispositivos y estado de perfil de Matrix",
hasSubcommands: true,
},
],
@ -375,88 +379,87 @@ api.registerCli(
);
```
Use `commands` por sí solo únicamente cuando no necesite registro diferido en el CLI raíz.
Esa ruta de compatibilidad ansiosa sigue siendo compatible, pero no instala
marcadores respaldados por descriptores para la carga diferida en tiempo de análisis.
Usa `commands` por sí solo solo cuando no necesites registro lazy del CLI raíz.
Esa ruta de compatibilidad eager sigue siendo compatible, pero no instala
marcadores de posición respaldados por descriptores para lazy loading en tiempo de análisis.
### Registro de backends de CLI
### Registro de backend CLI
`api.registerCliBackend(...)` permite que un plugin posea la configuración predeterminada de un
backend de CLI de IA local como `codex-cli`.
`api.registerCliBackend(...)` permite que un plugin se encargue de la configuración predeterminada de un
backend CLI local de IA como `codex-cli`.
- El `id` del backend se convierte en el prefijo del proveedor en referencias de modelo como `codex-cli/gpt-5`.
- El `id` del backend se convierte en el prefijo del proveedor en referencias de modelos como `codex-cli/gpt-5`.
- La `config` del backend usa la misma forma que `agents.defaults.cliBackends.<id>`.
- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.<id>` sobre el
valor predeterminado del plugin antes de ejecutar la CLI.
- Use `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión
- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.<id>` sobre la
predeterminada del plugin antes de ejecutar el CLI.
- Usa `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión
(por ejemplo, normalizar formas antiguas de flags).
### Ranuras exclusivas
| Método | Qué registra |
| ------------------------------------------ | -------------------------------------- |
| `api.registerContextEngine(id, factory)` | Motor de contexto (uno activo a la vez) |
| `api.registerMemoryCapability(capability)` | Capacidad de memoria unificada |
| `api.registerMemoryPromptSection(builder)` | Constructor de secciones de prompts de memoria |
| `api.registerMemoryFlushPlan(resolver)` | Resolutor del plan de vaciado de memoria |
| `api.registerMemoryRuntime(runtime)` | Adaptador de tiempo de ejecución de memoria |
| Método | Qué registra |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Motor de contexto (solo uno activo a la vez). El callback `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar las adiciones al prompt. |
| `api.registerMemoryCapability(capability)` | Capacidad unificada de memoria |
| `api.registerMemoryPromptSection(builder)` | Constructor de sección de prompt de memoria |
| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plan de vaciado de memoria |
| `api.registerMemoryRuntime(runtime)` | Adaptador de tiempo de ejecución de memoria |
### Adaptadores de embeddings de memoria
| Método | Qué registra |
| ---------------------------------------------- | ------------------------------------------------ |
| Método | Qué registra |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embeddings de memoria para el plugin activo |
- `registerMemoryCapability` es la API exclusiva preferida para plugins de memoria.
- `registerMemoryCapability` es la API exclusiva de plugin de memoria preferida.
- `registerMemoryCapability` también puede exponer `publicArtifacts.listArtifacts(...)`
para que plugins complementarios consuman artefactos de memoria exportados a través de
`openclaw/plugin-sdk/memory-host-core` en lugar de acceder al diseño privado
de un plugin de memoria específico.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` y
`registerMemoryRuntime` son API exclusivas de plugins de memoria compatibles con versiones heredadas.
para que los plugins complementarios consuman artefactos de memoria exportados mediante
`openclaw/plugin-sdk/memory-host-core` en lugar de acceder al diseño privado de un
plugin de memoria específico.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, y
`registerMemoryRuntime` son API exclusivas de plugin de memoria compatibles con el legado.
- `registerMemoryEmbeddingProvider` permite que el plugin de memoria activo registre uno
o más id de adaptadores de embeddings (por ejemplo `openai`, `gemini` o un id
personalizado definido por el plugin).
o más ids de adaptadores de embeddings (por ejemplo `openai`, `gemini`, o un id personalizado definido por el plugin).
- La configuración del usuario, como `agents.defaults.memorySearch.provider` y
`agents.defaults.memorySearch.fallback`, se resuelve contra esos id de adaptadores registrados.
`agents.defaults.memorySearch.fallback`, se resuelve contra esos ids de adaptadores registrados.
### Eventos y ciclo de vida
| Método | Qué hace |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Hook tipado del ciclo de vida |
| `api.onConversationBindingResolved(handler)` | Devolución de llamada de enlace de conversación |
| Método | Qué hace |
| -------------------------------------------- | --------------------------- |
| `api.on(hookName, handler, opts?)` | Hook de ciclo de vida tipado |
| `api.onConversationBindingResolved(handler)` | Callback de vinculación de conversación |
### Semántica de decisión de hooks
- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
- `before_tool_call`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación.
- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
- `before_install`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación.
- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier controlador reclama el despacho, se omiten los controladores de menor prioridad y la ruta predeterminada de despacho del modelo.
- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
- `message_sending`: devolver `{ cancel: false }` se trata como ausencia de decisión (igual que omitir `cancel`), no como una anulación.
- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
- `before_tool_call`: devolver `{ block: false }` se trata como sin decisión (igual que omitir `block`), no como una anulación.
- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
- `before_install`: devolver `{ block: false }` se trata como sin decisión (igual que omitir `block`), no como una anulación.
- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier manejador reclama el despacho, se omiten los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo.
- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
- `message_sending`: devolver `{ cancel: false }` se trata como sin decisión (igual que omitir `cancel`), no como una anulación.
### Campos del objeto API
| Campo | Tipo | Descripción |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
| `api.id` | `string` | Id del plugin |
| `api.name` | `string` | Nombre visible |
| `api.version` | `string?` | Versión del plugin (opcional) |
| `api.description` | `string?` | Descripción del plugin (opcional) |
| `api.source` | `string` | Ruta de origen del plugin |
| `api.rootDir` | `string?` | Directorio raíz del plugin (opcional) |
| `api.config` | `OpenClawConfig` | Instantánea actual de configuración (instantánea activa en memoria del tiempo de ejecución cuando está disponible) |
| `api.pluginConfig` | `Record<string, unknown>` | Configuración específica del plugin desde `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Auxiliares de tiempo de ejecución](/es/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger con alcance (`debug`, `info`, `warn`, `error`) |
| Campo | Tipo | Descripción |
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Id del plugin |
| `api.name` | `string` | Nombre para mostrar |
| `api.version` | `string?` | Versión del plugin (opcional) |
| `api.description` | `string?` | Descripción del plugin (opcional) |
| `api.source` | `string` | Ruta de origen del plugin |
| `api.rootDir` | `string?` | Directorio raíz del plugin (opcional) |
| `api.config` | `OpenClawConfig` | Snapshot actual de configuración (snapshot activo en memoria del tiempo de ejecución cuando está disponible) |
| `api.pluginConfig` | `Record<string, unknown>` | Configuración específica del plugin desde `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Ayudantes de tiempo de ejecución](/es/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger con ámbito (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Modo de carga actual; `"setup-runtime"` es la ventana ligera de inicio/configuración previa a la entrada completa |
| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin |
| `api.resolvePath(input)` | `(string) => string` | Resuelve la ruta relativa a la raíz del plugin |
## Convención de módulos internos
Dentro de su plugin, use archivos barril locales para las importaciones internas:
Dentro de tu plugin, usa archivos barrel locales para las importaciones internas:
```
my-plugin/
@ -467,36 +470,42 @@ my-plugin/
```
<Warning>
Nunca importe su propio plugin mediante `openclaw/plugin-sdk/<your-plugin>`
desde código de producción. Encamine las importaciones internas mediante `./api.ts` o
Nunca importes tu propio plugin mediante `openclaw/plugin-sdk/<your-plugin>`
desde código de producción. Dirige las importaciones internas a través de `./api.ts` o
`./runtime-api.ts`. La ruta del SDK es solo el contrato externo.
</Warning>
Las superficies públicas cargadas mediante fachada de plugins integrados (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` y archivos de entrada pública similares) ahora prefieren la
instantánea de configuración activa del tiempo de ejecución cuando OpenClaw ya está en ejecución. Si todavía no existe una instantánea de tiempo de ejecución, recurren al archivo de configuración resuelto en disco.
Las superficies públicas de plugins integrados cargadas por fachada (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`, y archivos de entrada pública similares) ahora prefieren el
snapshot activo de configuración en tiempo de ejecución cuando OpenClaw ya se está ejecutando. Si todavía
no existe un snapshot en tiempo de ejecución, recurren al archivo de configuración resuelto en disco.
Los plugins de proveedor también pueden exponer un barril de contrato local del plugin y de alcance limitado cuando un auxiliar es intencionalmente específico del proveedor y aún no pertenece a una subruta genérica del SDK. Ejemplo integrado actual: el proveedor Anthropic mantiene sus auxiliares de streaming de Claude en su propia capa pública `api.ts` / `contract-api.ts` en lugar de promover la lógica del encabezado beta de Anthropic y `service_tier` a un contrato genérico `plugin-sdk/*`.
Los plugins de proveedores también pueden exponer un barrel local del plugin con un contrato acotado cuando un
ayudante es intencionalmente específico del proveedor y aún no pertenece a una subruta genérica
del SDK. Ejemplo integrado actual: el proveedor Anthropic conserva sus
ayudantes de stream Claude en su propio punto de acceso público `api.ts` / `contract-api.ts` en lugar de
promover la lógica de encabezado beta de Anthropic y `service_tier` a un contrato genérico
`plugin-sdk/*`.
Otros ejemplos integrados actuales:
- `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedores,
auxiliares de modelos predeterminados y constructores de proveedores en tiempo real
ayudantes de modelo predeterminado y constructores de proveedores realtime
- `@openclaw/openrouter-provider`: `api.ts` exporta el constructor del proveedor más
auxiliares de onboarding/configuración
ayudantes de onboarding/configuración
<Warning>
El código de producción de extensiones también debe evitar importaciones desde `openclaw/plugin-sdk/<other-plugin>`.
Si un auxiliar se comparte realmente, promuévalo a una subruta neutral del SDK
como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` u otra
superficie orientada a capacidades, en lugar de acoplar dos plugins entre sí.
El código de producción de extensiones también debe evitar las importaciones
`openclaw/plugin-sdk/<other-plugin>`. Si un ayudante es realmente compartido, promuévelo a una subruta neutra del SDK
como `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, u otra
superficie orientada a capacidades en lugar de acoplar dos plugins entre sí.
</Warning>
## Relacionado
- [Puntos de entrada](/es/plugins/sdk-entrypoints) — opciones de `definePluginEntry` y `defineChannelPluginEntry`
- [Auxiliares de tiempo de ejecución](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime`
- [Configuración y config](/es/plugins/sdk-setup) — empaquetado, manifiestos y esquemas de configuración
- [Pruebas](/es/plugins/sdk-testing) — utilidades de prueba y reglas de lint
- [Migración del SDK](/es/plugins/sdk-migration) — migración desde superficies obsoletas
- [Internos de plugins](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades
- [Entry Points](/es/plugins/sdk-entrypoints) — opciones de `definePluginEntry` y `defineChannelPluginEntry`
- [Runtime Helpers](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime`
- [Setup and Config](/es/plugins/sdk-setup) — empaquetado, manifiestos, esquemas de configuración
- [Testing](/es/plugins/sdk-testing) — utilidades de prueba y reglas de lint
- [SDK Migration](/es/plugins/sdk-migration) — migración desde superficies obsoletas
- [Plugin Internals](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades

322
docs/es/plugins/sdk-provider-plugins.md
View File

@ -1,30 +1,30 @@
---
read_when:
- Estás creando un nuevo plugin de proveedor de modelos
- Quieres añadir un proxy compatible con OpenAI o un LLM personalizado a OpenClaw
- Necesitas entender la autenticación del proveedor, los catálogos y los hooks de tiempo de ejecución
- Quieres añadir a OpenClaw un proxy compatible con OpenAI o un LLM personalizado
- Necesitas entender la autenticación del proveedor, los catálogos y los hooks de runtime
sidebarTitle: Provider Plugins
summary: Guía paso a paso para crear un plugin de proveedor de modelos para OpenClaw
title: Creación de plugins de proveedor
title: Crear plugins de proveedor
x-i18n:
generated_at: "2026-04-07T05:06:01Z"
generated_at: "2026-04-09T01:30:35Z"
model: gpt-5.4
provider: openai
source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990
source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1
source_path: plugins/sdk-provider-plugins.md
workflow: 15
---
# Creación de plugins de proveedor
# Crear plugins de proveedor
Esta guía explica cómo crear un plugin de proveedor que añada un proveedor de modelos
Esta guía explica cómo crear un plugin de proveedor que añade un proveedor de modelos
(LLM) a OpenClaw. Al final tendrás un proveedor con un catálogo de modelos,
autenticación por clave de API y resolución dinámica de modelos.
autenticación mediante clave de API y resolución dinámica de modelos.
<Info>
Si todavía no has creado ningún plugin de OpenClaw, lee primero
[Primeros pasos](/es/plugins/building-plugins) para ver la estructura básica del
paquete y la configuración del manifiesto.
Si aún no has creado ningún plugin de OpenClaw, lee primero
[Getting Started](/es/plugins/building-plugins) para conocer la estructura básica
del paquete y la configuración del manifiesto.
</Info>
## Tutorial
@ -57,7 +57,7 @@ autenticación por clave de API y resolución dinámica de modelos.
{
"id": "acme-ai",
"name": "Acme AI",
"description": "Proveedor de modelos Acme AI",
"description": "Acme AI model provider",
"providers": ["acme-ai"],
"modelSupport": {
"modelPrefixes": ["acme-"]
@ -65,17 +65,20 @@ autenticación por clave de API y resolución dinámica de modelos.
"providerAuthEnvVars": {
"acme-ai": ["ACME_AI_API_KEY"]
},
"providerAuthAliases": {
"acme-ai-coding": "acme-ai"
},
"providerAuthChoices": [
{
"provider": "acme-ai",
"method": "api-key",
"choiceId": "acme-ai-api-key",
"choiceLabel": "Clave de API de Acme AI",
"choiceLabel": "Acme AI API key",
"groupId": "acme-ai",
"groupLabel": "Acme AI",
"cliFlag": "--acme-ai-api-key",
"cliOption": "--acme-ai-api-key <key>",
"cliDescription": "Clave de API de Acme AI"
"cliDescription": "Acme AI API key"
}
],
"configSchema": {
@ -87,16 +90,17 @@ autenticación por clave de API y resolución dinámica de modelos.
</CodeGroup>
El manifiesto declara `providerAuthEnvVars` para que OpenClaw pueda detectar
credenciales sin cargar el tiempo de ejecución de tu plugin. `modelSupport` es opcional
y permite que OpenClaw cargue automáticamente tu plugin de proveedor a partir de IDs abreviados de modelo
como `acme-large` antes de que existan hooks de tiempo de ejecución. Si publicas el
credenciales sin cargar el runtime de tu plugin. Añade `providerAuthAliases`
cuando una variante del proveedor deba reutilizar la autenticación de otro id de proveedor. `modelSupport`
es opcional y permite que OpenClaw cargue automáticamente tu plugin de proveedor a partir de ids
abreviados de modelo como `acme-large` antes de que existan hooks de runtime. Si publicas el
proveedor en ClawHub, esos campos `openclaw.compat` y `openclaw.build`
son obligatorios en `package.json`.
</Step>
<Step title="Registrar el proveedor">
Un proveedor mínimo necesita `id`, `label`, `auth` y `catalog`:
Un proveedor mínimo necesita un `id`, `label`, `auth` y `catalog`:
```typescript index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -167,13 +171,14 @@ autenticación por clave de API y resolución dinámica de modelos.
});
```
Ese es un proveedor funcional. Los usuarios ahora pueden ejecutar
`openclaw onboard --acme-ai-api-key <key>` y seleccionar
`acme-ai/acme-large` como modelo.
Ese es un proveedor funcional. Ahora los usuarios pueden
ejecutar `openclaw onboard --acme-ai-api-key <key>` y seleccionar
`acme-ai/acme-large` como su modelo.
Para proveedores integrados que solo registran un proveedor de texto con
autenticación por clave de API más un único tiempo de ejecución respaldado por catálogo, prefiere el helper
más específico `defineSingleProviderPluginEntry(...)`:
Para proveedores incluidos que solo registran un proveedor de texto con
autenticación por clave de API más un único runtime respaldado por catálogo, es preferible
usar el helper más específico
`defineSingleProviderPluginEntry(...)`:
```typescript
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
@ -208,25 +213,25 @@ autenticación por clave de API y resolución dinámica de modelos.
});
```
Si tu flujo de autenticación también necesita modificar `models.providers.*`, alias y
el modelo predeterminado del agente durante la incorporación, usa los helpers predefinidos de
Si tu flujo de autenticación también necesita aplicar parches a `models.providers.*`, alias y
al modelo predeterminado del agente durante la incorporación, usa los helpers predefinidos de
`openclaw/plugin-sdk/provider-onboard`. Los helpers más específicos son
`createDefaultModelPresetAppliers(...)`,
`createDefaultModelsPresetAppliers(...)` y
`createModelCatalogPresetAppliers(...)`.
Cuando el endpoint nativo de un proveedor admite bloques de uso en streaming en el
transporte normal `openai-completions`, prefiere los helpers compartidos de catálogo en
transporte normal `openai-completions`, es preferible usar los helpers compartidos de catálogo en
`openclaw/plugin-sdk/provider-catalog-shared` en lugar de codificar comprobaciones
de ID de proveedor. `supportsNativeStreamingUsageCompat(...)` y
`applyProviderNativeStreamingUsageCompat(...)` detectan la compatibilidad a partir del mapa
de capacidades del endpoint, por lo que los endpoints nativos de estilo Moonshot/DashScope siguen
pudiendo activarse incluso cuando un plugin usa un ID de proveedor personalizado.
del id del proveedor. `supportsNativeStreamingUsageCompat(...)` y
`applyProviderNativeStreamingUsageCompat(...)` detectan la compatibilidad a partir del mapa de capacidades
del endpoint, de modo que los endpoints nativos tipo Moonshot/DashScope sigan
activándose incluso cuando un plugin esté usando un id de proveedor personalizado.
</Step>
<Step title="Añadir resolución dinámica de modelos">
Si tu proveedor acepta IDs arbitrarios de modelo (como un proxy o router),
Si tu proveedor acepta ids de modelo arbitrarios (como un proxy o router),
añade `resolveDynamicModel`:
```typescript
@ -249,17 +254,17 @@ autenticación por clave de API y resolución dinámica de modelos.
```
Si la resolución requiere una llamada de red, usa `prepareDynamicModel` para el
calentamiento asíncrono: `resolveDynamicModel` se vuelve a ejecutar después de que se complete.
calentamiento asíncrono; `resolveDynamicModel` se ejecuta de nuevo cuando se completa.
</Step>
<Step title="Añadir hooks de tiempo de ejecución (según sea necesario)">
<Step title="Añadir hooks de runtime (según sea necesario)">
La mayoría de los proveedores solo necesitan `catalog` + `resolveDynamicModel`. Añade hooks
de forma incremental a medida que tu proveedor los necesite.
de forma incremental según lo requiera tu proveedor.
Los constructores de helpers compartidos ahora cubren las familias más comunes de
compatibilidad de repetición/herramientas, por lo que normalmente los plugins no necesitan conectar
manualmente cada hook uno por uno:
Los generadores de helpers compartidos ahora cubren las familias más habituales de
reproducción/compatibilidad con herramientas, así que normalmente los plugins no necesitan
conectar manualmente cada hook uno por uno:
```typescript
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@ -279,17 +284,17 @@ autenticación por clave de API y resolución dinámica de modelos.
});
```
Familias de repetición disponibles actualmente:
Familias de reproducción disponibles actualmente:
| Family | What it wires in |
| --- | --- |
| `openai-compatible` | Política compartida de repetición estilo OpenAI para transportes compatibles con OpenAI, incluido el saneamiento de IDs de llamadas a herramientas, correcciones del orden con el asistente primero y validación genérica de turnos Gemini cuando el transporte lo necesita |
| `anthropic-by-model` | Política de repetición compatible con Claude elegida por `modelId`, para que los transportes `anthropic-message` solo apliquen limpieza de bloques de pensamiento específica de Claude cuando el modelo resuelto sea realmente un ID de Claude |
| `google-gemini` | Política nativa de repetición de Gemini más saneamiento de repetición de arranque y modo de salida de razonamiento etiquetado |
| `passthrough-gemini` | Saneamiento de firmas de pensamiento de Gemini para modelos Gemini que se ejecutan a través de transportes proxy compatibles con OpenAI; no habilita la validación nativa de repetición de Gemini ni las reescrituras de arranque |
| `hybrid-anthropic-openai` | Política híbrida para proveedores que mezclan superficies de modelo `anthropic-message` y compatibles con OpenAI en un solo plugin; la eliminación opcional de bloques de pensamiento solo para Claude sigue limitada al lado Anthropic |
| `openai-compatible` | Política compartida de reproducción de estilo OpenAI para transportes compatibles con OpenAI, incluida la limpieza de `tool-call-id`, correcciones de orden con el asistente primero y validación genérica de turnos de Gemini cuando el transporte lo necesita |
| `anthropic-by-model` | Política de reproducción compatible con Claude elegida por `modelId`, de modo que los transportes `anthropic-message` solo reciban limpieza de bloques de razonamiento específica de Claude cuando el modelo resuelto sea realmente un id de Claude |
| `google-gemini` | Política nativa de reproducción de Gemini más saneamiento de reproducción bootstrap y modo etiquetado de salida de razonamiento |
| `passthrough-gemini` | Saneamiento de firmas de pensamiento de Gemini para modelos Gemini que se ejecutan mediante transportes proxy compatibles con OpenAI; no habilita validación nativa de reproducción de Gemini ni reescrituras de bootstrap |
| `hybrid-anthropic-openai` | Política híbrida para proveedores que mezclan superficies de modelos `anthropic-message` y compatibles con OpenAI en un solo plugin; la eliminación opcional de bloques de razonamiento solo para Claude permanece limitada al lado Anthropic |
Ejemplos integrados reales:
Ejemplos reales incluidos:
- `google` y `google-gemini-cli`: `google-gemini`
- `openrouter`, `kilocode`, `opencode` y `opencode-go`: `passthrough-gemini`
@ -297,19 +302,19 @@ autenticación por clave de API y resolución dinámica de modelos.
- `minimax`: `hybrid-anthropic-openai`
- `moonshot`, `ollama`, `xai` y `zai`: `openai-compatible`
Familias de streaming disponibles actualmente:
Familias de stream disponibles actualmente:
| Family | What it wires in |
| --- | --- |
| `google-thinking` | Normalización de la carga útil de pensamiento de Gemini en la ruta de streaming compartida |
| `kilocode-thinking` | Envoltorio de razonamiento de Kilo en la ruta de streaming proxy compartida, con `kilo/auto` e IDs de razonamiento proxy no compatibles omitiendo el pensamiento inyectado |
| `moonshot-thinking` | Asignación de carga útil de pensamiento nativo binario de Moonshot a partir de la configuración + nivel de `/think` |
| `minimax-fast-mode` | Reescritura de modelo de modo rápido de MiniMax en la ruta de streaming compartida |
| `openai-responses-defaults` | Envoltorios compartidos de Responses nativas de OpenAI/Codex: encabezados de atribución, `/fast`/`serviceTier`, verbosidad del texto, búsqueda web nativa de Codex, conformación de carga útil de compatibilidad de razonamiento y gestión del contexto de Responses |
| `openrouter-thinking` | Envoltorio de razonamiento de OpenRouter para rutas proxy, con los saltos de modelo no compatible/`auto` gestionados de forma centralizada |
| `google-thinking` | Normalización de carga útil de pensamiento de Gemini en la ruta de stream compartida |
| `kilocode-thinking` | Envoltorio de razonamiento de Kilo en la ruta de stream proxy compartida, con `kilo/auto` e ids de razonamiento proxy no compatibles omitiendo el pensamiento inyectado |
| `moonshot-thinking` | Asignación de carga útil binaria nativa de pensamiento de Moonshot a partir de la configuración y del nivel `/think` |
| `minimax-fast-mode` | Reescritura de modelos de modo rápido de MiniMax en la ruta de stream compartida |
| `openai-responses-defaults` | Envoltorios compartidos de Responses nativas de OpenAI/Codex: encabezados de atribución, `/fast`/`serviceTier`, verbosidad del texto, búsqueda web nativa de Codex, ajuste de carga útil compatible con razonamiento y gestión de contexto de Responses |
| `openrouter-thinking` | Envoltorio de razonamiento de OpenRouter para rutas proxy, con omisiones para modelos no compatibles/`auto` gestionadas de forma centralizada |
| `tool-stream-default-on` | Envoltorio `tool_stream` activado por defecto para proveedores como Z.AI que quieren streaming de herramientas salvo que se desactive explícitamente |
Ejemplos integrados reales:
Ejemplos reales incluidos:
- `google` y `google-gemini-cli`: `google-thinking`
- `kilocode`: `kilocode-thinking`
@ -319,25 +324,25 @@ autenticación por clave de API y resolución dinámica de modelos.
- `openrouter`: `openrouter-thinking`
- `zai`: `tool-stream-default-on`
`openclaw/plugin-sdk/provider-model-shared` también exporta el enum de familia
de repetición más los helpers compartidos sobre los que se construyen esas familias. Las
exportaciones públicas más comunes incluyen:
`openclaw/plugin-sdk/provider-model-shared` también exporta el enum de familias de reproducción
junto con los helpers compartidos sobre los que se construyen esas familias. Las
exportaciones públicas habituales incluyen:
- `ProviderReplayFamily`
- `buildProviderReplayFamilyHooks(...)`
- constructores compartidos de repetición como `buildOpenAICompatibleReplayPolicy(...)`,
- generadores compartidos de reproducción como `buildOpenAICompatibleReplayPolicy(...)`,
`buildAnthropicReplayPolicyForModel(...)`,
`buildGoogleGeminiReplayPolicy(...)` y
`buildHybridAnthropicOrOpenAIReplayPolicy(...)`
- helpers de repetición de Gemini como `sanitizeGoogleGeminiReplayHistory(...)`
- helpers de reproducción de Gemini como `sanitizeGoogleGeminiReplayHistory(...)`
y `resolveTaggedReasoningOutputMode()`
- helpers de endpoint/modelo como `resolveProviderEndpoint(...)`,
`normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` y
`normalizeNativeXaiModelId(...)`
`openclaw/plugin-sdk/provider-stream` expone tanto el constructor de familias como
los helpers públicos de envoltorio que esas familias reutilizan. Las exportaciones públicas
más comunes incluyen:
`openclaw/plugin-sdk/provider-stream` expone tanto el generador de familias como
los helpers públicos de envoltorio que reutilizan esas familias. Las
exportaciones públicas habituales incluyen:
- `ProviderStreamFamily`
- `buildProviderStreamFamilyHooks(...)`
@ -351,44 +356,44 @@ autenticación por clave de API y resolución dinámica de modelos.
- envoltorios compartidos de proxy/proveedor como `createOpenRouterWrapper(...)`,
`createToolStreamWrapper(...)` y `createMinimaxFastModeWrapper(...)`
Algunos helpers de streaming permanecen intencionadamente locales al proveedor. Ejemplo
integrado actual: `@openclaw/anthropic-provider` exporta
Algunos helpers de stream se mantienen locales al proveedor de forma intencionada. Ejemplo
actual incluido: `@openclaw/anthropic-provider` exporta
`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier` y los
constructores de envoltorios Anthropic de nivel inferior desde su interfaz pública `api.ts` /
generadores de envoltorio Anthropic de nivel inferior desde su punto de unión público `api.ts` /
`contract-api.ts`. Esos helpers siguen siendo específicos de Anthropic porque
también codifican el manejo de betas de Claude OAuth y la restricción de `context1m`.
también codifican el manejo beta de OAuth de Claude y el control de `context1m`.
Otros proveedores integrados también mantienen locales los envoltorios específicos del transporte cuando
Otros proveedores incluidos también mantienen envoltorios específicos de transporte como locales cuando
el comportamiento no se comparte limpiamente entre familias. Ejemplo actual: el
plugin integrado de xAI mantiene en su propio
`wrapStreamFn` la conformación nativa de xAI Responses, incluidas las reescrituras de alias `/fast`, el valor predeterminado de `tool_stream`,
la limpieza de herramientas estrictas no compatibles y la eliminación
de carga útil de razonamiento específica de xAI.
plugin xAI incluido mantiene el ajuste nativo de Responses de xAI en su propio
`wrapStreamFn`, incluyendo reescrituras de alias `/fast`, `tool_stream` predeterminado,
limpieza estricta de herramientas no compatibles y eliminación de carga útil
de razonamiento específica de xAI.
`openclaw/plugin-sdk/provider-tools` actualmente expone una familia compartida
de esquemas de herramientas más helpers compartidos de esquema/compatibilidad:
- `ProviderToolCompatFamily` documenta el inventario actual de familias compartidas.
- `buildProviderToolCompatFamilyHooks("gemini")` conecta la
limpieza + diagnóstico de esquemas de Gemini para proveedores que necesitan esquemas de herramientas seguros para Gemini.
- `normalizeGeminiToolSchemas(...)` e `inspectGeminiToolSchemas(...)`
son los helpers públicos subyacentes del esquema Gemini.
- `resolveXaiModelCompatPatch()` devuelve el parche de compatibilidad integrado de xAI:
`toolSchemaProfile: "xai"`, palabras clave de esquema no compatibles, compatibilidad
nativa con `web_search` y decodificación de argumentos de llamadas a herramientas con entidades HTML.
- `applyXaiModelCompat(model)` aplica ese mismo parche de compatibilidad de xAI a un
- `ProviderToolCompatFamily` documenta hoy el inventario de familias compartidas.
- `buildProviderToolCompatFamilyHooks("gemini")` conecta limpieza de esquemas Gemini
+ diagnósticos para proveedores que necesitan esquemas de herramientas seguros para Gemini.
- `normalizeGeminiToolSchemas(...)` y `inspectGeminiToolSchemas(...)`
son los helpers públicos subyacentes para esquemas Gemini.
- `resolveXaiModelCompatPatch()` devuelve el parche de compatibilidad xAI incluido:
`toolSchemaProfile: "xai"`, palabras clave de esquema no compatibles, compatibilidad nativa con
`web_search` y decodificación de argumentos de llamadas a herramientas con entidades HTML.
- `applyXaiModelCompat(model)` aplica ese mismo parche de compatibilidad xAI a un
modelo resuelto antes de que llegue al ejecutor.
Ejemplo integrado real: el plugin de xAI usa `normalizeResolvedModel` más
`contributeResolvedModelCompat` para que esos metadatos de compatibilidad sigan siendo propiedad del
proveedor en lugar de codificar reglas de xAI en el núcleo.
Ejemplo real incluido: el plugin xAI usa `normalizeResolvedModel` más
`contributeResolvedModelCompat` para mantener esos metadatos de compatibilidad bajo
propiedad del proveedor en lugar de codificar reglas xAI en el núcleo.
El mismo patrón de raíz de paquete también sustenta otros proveedores integrados:
El mismo patrón de raíz de paquete también respalda otros proveedores incluidos:
- `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedor,
helpers de modelos predeterminados y constructores de proveedores en tiempo real
- `@openclaw/openrouter-provider`: `api.ts` exporta el constructor de proveedor
- `@openclaw/openai-provider`: `api.ts` exporta generadores de proveedor,
helpers de modelo predeterminado y generadores de proveedores realtime
- `@openclaw/openrouter-provider`: `api.ts` exporta el generador de proveedor
más helpers de incorporación/configuración
<Tabs>
@ -424,7 +429,7 @@ autenticación por clave de API y resolución dinámica de modelos.
},
```
</Tab>
<Tab title="Identidad de transporte nativo">
<Tab title="Identidad de transporte nativa">
Para proveedores que necesitan encabezados o metadatos nativos de solicitud/sesión en
transportes HTTP o WebSocket genéricos:
@ -462,73 +467,72 @@ autenticación por clave de API y resolución dinámica de modelos.
</Tabs>
<Accordion title="Todos los hooks de proveedor disponibles">
OpenClaw llama a los hooks en este orden. La mayoría de los proveedores solo usan 2-3:
OpenClaw llama a los hooks en este orden. La mayoría de los proveedores solo usan 2 o 3:
| # | Hook | Cuándo usarlo |
| --- | --- | --- |
| 1 | `catalog` | Catálogo de modelos o valores predeterminados de URL base |
| 2 | `applyConfigDefaults` | Valores globales predeterminados controlados por el proveedor durante la materialización de la configuración |
| 3 | `normalizeModelId` | Limpieza de alias de IDs de modelo heredados/de vista previa antes de la búsqueda |
| 4 | `normalizeTransport` | Limpieza de `api` / `baseUrl` de la familia de proveedor antes del ensamblado genérico del modelo |
| 5 | `normalizeConfig` | Normalizar la configuración `models.providers.<id>` |
| 6 | `applyNativeStreamingUsageCompat` | Reescrituras de compatibilidad de uso de streaming nativo para proveedores configurados |
| 7 | `resolveConfigApiKey` | Resolución de autenticación de marcador de entorno controlada por el proveedor |
| 1 | `catalog` | Catálogo de modelos o valores predeterminados de `baseUrl` |
| 2 | `applyConfigDefaults` | Valores predeterminados globales propiedad del proveedor durante la materialización de la configuración |
| 3 | `normalizeModelId` | Limpieza de alias heredados/de vista previa de ids de modelo antes de la búsqueda |
| 4 | `normalizeTransport` | Limpieza de familia del proveedor `api` / `baseUrl` antes del ensamblado genérico del modelo |
| 5 | `normalizeConfig` | Normalizar configuración `models.providers.<id>` |
| 6 | `applyNativeStreamingUsageCompat` | Reescrituras de compatibilidad de uso nativo en streaming para proveedores de configuración |
| 7 | `resolveConfigApiKey` | Resolución de autenticación de marcadores de entorno propiedad del proveedor |
| 8 | `resolveSyntheticAuth` | Autenticación sintética local/autohospedada o basada en configuración |
| 9 | `shouldDeferSyntheticProfileAuth` | Colocar marcadores de posición sintéticos de perfiles almacenados por detrás de la autenticación de entorno/configuración |
| 10 | `resolveDynamicModel` | Aceptar IDs arbitrarios de modelo ascendente |
| 9 | `shouldDeferSyntheticProfileAuth` | Rebajar placeholders sintéticos de perfiles almacenados por detrás de autenticación env/config |
| 10 | `resolveDynamicModel` | Aceptar ids de modelo arbitrarios del upstream |
| 11 | `prepareDynamicModel` | Obtención asíncrona de metadatos antes de resolver |
| 12 | `normalizeResolvedModel` | Reescrituras de transporte antes del ejecutor |
Notas sobre el comportamiento de respaldo en tiempo de ejecución:
Notas sobre el fallback en runtime:
- `normalizeConfig` comprueba primero el proveedor coincidente y después otros
plugins de proveedor con capacidad de hook hasta que uno cambie realmente la configuración.
Si ningún hook de proveedor reescribe una entrada de configuración compatible de la familia Google,
se sigue aplicando el normalizador integrado de configuración de Google.
- `resolveConfigApiKey` usa el hook del proveedor cuando está expuesto. La ruta integrada
`amazon-bedrock` también tiene aquí un resolvedor integrado de marcadores
de entorno de AWS, aunque la autenticación en tiempo de ejecución de Bedrock siga usando la
cadena predeterminada del SDK de AWS.
| 13 | `contributeResolvedModelCompat` | Banderas de compatibilidad para modelos del proveedor detrás de otro transporte compatible |
| 14 | `capabilities` | Bolsa heredada de capacidades estáticas; solo para compatibilidad |
| 15 | `normalizeToolSchemas` | Limpieza de esquemas de herramientas controlada por el proveedor antes del registro |
| 16 | `inspectToolSchemas` | Diagnóstico de esquemas de herramientas controlado por el proveedor |
- `normalizeConfig` primero comprueba el proveedor coincidente y después otros
plugins de proveedor con capacidad de hooks hasta que uno realmente cambie la configuración.
Si ningún hook de proveedor reescribe una entrada de configuración compatible de la familia Google,
se sigue aplicando el normalizador de configuración de Google incluido.
- `resolveConfigApiKey` usa el hook del proveedor cuando se expone. La ruta incluida
de `amazon-bedrock` también tiene aquí un resolvedor integrado de marcadores de entorno AWS,
aunque la autenticación de runtime de Bedrock siga usando la cadena predeterminada del SDK de AWS.
| 13 | `contributeResolvedModelCompat` | Indicadores de compatibilidad para modelos de proveedor detrás de otro transporte compatible |
| 14 | `capabilities` | Bolsa estática heredada de capacidades; solo compatibilidad |
| 15 | `normalizeToolSchemas` | Limpieza de esquemas de herramientas propiedad del proveedor antes del registro |
| 16 | `inspectToolSchemas` | Diagnósticos de esquemas de herramientas propiedad del proveedor |
| 17 | `resolveReasoningOutputMode` | Contrato de salida de razonamiento etiquetado frente a nativo |
| 18 | `prepareExtraParams` | Parámetros de solicitud predeterminados |
| 19 | `createStreamFn` | Transporte `StreamFn` totalmente personalizado |
| 20 | `wrapStreamFn` | Envoltorios personalizados de encabezados/cuerpo en la ruta normal de streaming |
| 18 | `prepareExtraParams` | Parámetros predeterminados de la solicitud |
| 19 | `createStreamFn` | Transporte `StreamFn` completamente personalizado |
| 20 | `wrapStreamFn` | Envoltorios personalizados de encabezados/cuerpo en la ruta de stream normal |
| 21 | `resolveTransportTurnState` | Encabezados/metadatos nativos por turno |
| 22 | `resolveWebSocketSessionPolicy` | Encabezados nativos de sesión WS/enfriamiento |
| 23 | `formatApiKey` | Forma personalizada del token en tiempo de ejecución |
| 24 | `refreshOAuth` | Actualización personalizada de OAuth |
| 25 | `buildAuthDoctorHint` | Orientación para reparar autenticación |
| 26 | `matchesContextOverflowError` | Detección de desbordamiento controlada por el proveedor |
| 27 | `classifyFailoverReason` | Clasificación de límite de velocidad/sobrecarga controlada por el proveedor |
| 28 | `isCacheTtlEligible` | Control de TTL de la caché de prompts |
| 29 | `buildMissingAuthMessage` | Pista personalizada para autenticación faltante |
| 30 | `suppressBuiltInModel` | Ocultar filas ascendentes obsoletas |
| 31 | `augmentModelCatalog` | Filas sintéticas de compatibilidad anticipada |
| 22 | `resolveWebSocketSessionPolicy` | Encabezados/enfriamiento de sesión WS nativos |
| 23 | `formatApiKey` | Forma personalizada del token de runtime |
| 24 | `refreshOAuth` | Actualización OAuth personalizada |
| 25 | `buildAuthDoctorHint` | Orientación de reparación de autenticación |
| 26 | `matchesContextOverflowError` | Detección de desbordamiento propiedad del proveedor |
| 27 | `classifyFailoverReason` | Clasificación propiedad del proveedor de límite de tasa/sobrecarga |
| 28 | `isCacheTtlEligible` | Control TTL de la caché de prompts |
| 29 | `buildMissingAuthMessage` | Sugerencia personalizada de autenticación faltante |
| 30 | `suppressBuiltInModel` | Ocultar filas upstream obsoletas |
| 31 | `augmentModelCatalog` | Filas sintéticas de compatibilidad futura |
| 32 | `isBinaryThinking` | Pensamiento binario activado/desactivado |
| 33 | `supportsXHighThinking` | Compatibilidad de razonamiento `xhigh` |
| 33 | `supportsXHighThinking` | Compatibilidad con razonamiento `xhigh` |
| 34 | `resolveDefaultThinkingLevel` | Política predeterminada de `/think` |
| 35 | `isModernModelRef` | Coincidencia de modelos live/smoke |
| 36 | `prepareRuntimeAuth` | Intercambio de tokens antes de la inferencia |
| 37 | `resolveUsageAuth` | Análisis personalizado de credenciales de uso |
| 38 | `fetchUsageSnapshot` | Endpoint de uso personalizado |
| 39 | `createEmbeddingProvider` | Adaptador de embeddings controlado por el proveedor para memoria/búsqueda |
| 40 | `buildReplayPolicy` | Política personalizada de repetición/compactación de transcripciones |
| 41 | `sanitizeReplayHistory` | Reescrituras de repetición específicas del proveedor después de la limpieza genérica |
| 42 | `validateReplayTurns` | Validación estricta de turnos de repetición antes del ejecutor integrado |
| 43 | `onModelSelected` | Callback posterior a la selección (por ejemplo, telemetría) |
| 38 | `fetchUsageSnapshot` | Endpoint personalizado de uso |
| 39 | `createEmbeddingProvider` | Adaptador de embeddings propiedad del proveedor para memoria/búsqueda |
| 40 | `buildReplayPolicy` | Política personalizada de reproducción/compactación de transcripciones |
| 41 | `sanitizeReplayHistory` | Reescrituras de reproducción específicas del proveedor tras la limpieza genérica |
| 42 | `validateReplayTurns` | Validación estricta de turnos de reproducción antes del ejecutor embebido |
| 43 | `onModelSelected` | Callback posterior a la selección (p. ej., telemetría) |
Nota sobre ajuste de prompts:
- `resolveSystemPromptContribution` permite que un proveedor inyecte
orientación de system prompt consciente de la caché para una familia de modelos. Prefiérelo frente a
`before_prompt_build` cuando el comportamiento pertenezca a un proveedor/familia de modelos
y deba preservar la división estable/dinámica de la caché.
orientación de system prompt consciente de la caché para una familia de modelos. Es preferible usarlo en lugar de
`before_prompt_build` cuando el comportamiento pertenece a una familia de proveedor/modelo
y debe conservar la división estable/dinámica de la caché.
Para descripciones detalladas y ejemplos reales, consulta
Para descripciones detalladas y ejemplos del mundo real, consulta
[Internals: Provider Runtime Hooks](/es/plugins/architecture#provider-runtime-hooks).
</Accordion>
@ -536,9 +540,9 @@ autenticación por clave de API y resolución dinámica de modelos.
<Step title="Añadir capacidades adicionales (opcional)">
<a id="step-5-add-extra-capabilities"></a>
Un plugin de proveedor puede registrar voz, transcripción en tiempo real, voz
en tiempo real, comprensión multimedia, generación de imágenes, generación de video, web fetch
y búsqueda web junto con inferencia de texto:
Un plugin de proveedor puede registrar speech, transcripción realtime, voz
realtime, comprensión multimedia, generación de imágenes, generación de video, web fetch
y búsqueda web junto con la inferencia de texto:
```typescript
register(api) {
@ -650,16 +654,16 @@ autenticación por clave de API y resolución dinámica de modelos.
patrón recomendado para plugins de empresa (un plugin por proveedor). Consulta
[Internals: Capability Ownership](/es/plugins/architecture#capability-ownership-model).
Para la generación de video, prefiere la forma de capacidades consciente del modo que se muestra arriba:
Para la generación de video, es preferible usar la forma de capacidades con reconocimiento de modo que se muestra arriba:
`generate`, `imageToVideo` y `videoToVideo`. Los campos agregados planos como
`maxInputImages`, `maxInputVideos` y `maxDurationSeconds` no
bastan para anunciar claramente compatibilidad con modos de transformación o modos deshabilitados.
`maxInputImages`, `maxInputVideos` y `maxDurationSeconds` no son
suficientes para anunciar limpiamente compatibilidad con modo de transformación o modos deshabilitados.
Los proveedores de generación musical deben seguir el mismo patrón:
`generate` para generación solo con prompt y `edit` para generación basada en imagen
de referencia. Los campos agregados planos como `maxInputImages`,
`supportsLyrics` y `supportsFormat` no bastan para anunciar compatibilidad
con edición; los bloques explícitos `generate` / `edit` son el contrato esperado.
Los proveedores de generación de música deben seguir el mismo patrón:
`generate` para generación solo a partir de prompt y `edit` para generación
basada en imagen de referencia. Los campos agregados planos como `maxInputImages`,
`supportsLyrics` y `supportsFormat` no son suficientes para anunciar compatibilidad
con edición; el contrato esperado son bloques explícitos `generate` / `edit`.
</Step>
@ -714,29 +718,29 @@ No uses aquí el alias heredado de publicación solo para Skills; los paquetes d
```
<bundled-plugin-root>/acme-ai/
├── package.json # openclaw.providers metadata
├── openclaw.plugin.json # Manifest with providerAuthEnvVars
├── package.json # metadatos de openclaw.providers
├── openclaw.plugin.json # manifiesto con metadatos de autenticación del proveedor
├── index.ts # definePluginEntry + registerProvider
└── src/
├── provider.test.ts # Tests
└── usage.ts # Usage endpoint (optional)
├── provider.test.ts # pruebas
└── usage.ts # endpoint de uso (opcional)
```
## Referencia del orden del catálogo
`catalog.order` controla cuándo se fusiona tu catálogo respecto a los proveedores
integrados:
`catalog.order` controla cuándo se fusiona tu catálogo en relación con los
proveedores integrados:
| Order | When | Use case |
| --------- | ------------- | ----------------------------------------------- |
| `simple` | Primera pasada | Proveedores simples con clave de API |
| `profile` | Después de simple | Proveedores condicionados por perfiles de autenticación |
| `paired` | Después de profile | Sintetizar varias entradas relacionadas |
| `late` | Última pasada | Sobrescribir proveedores existentes (gana en caso de colisión) |
| `simple` | Primer paso | Proveedores sencillos con clave de API |
| `profile` | Después de simple | Proveedores condicionados a perfiles de autenticación |
| `paired` | Después de profile | Sintetizar varias entradas relacionadas |
| `late` | Último paso | Sobrescribir proveedores existentes (gana en colisión) |
## Siguientes pasos
## Próximos pasos
- [Plugins de canal](/es/plugins/sdk-channel-plugins) — si tu plugin también proporciona un canal
- [SDK Runtime](/es/plugins/sdk-runtime) — helpers de `api.runtime` (TTS, búsqueda, subagente)
- [Channel Plugins](/es/plugins/sdk-channel-plugins) — si tu plugin también proporciona un canal
- [SDK Runtime](/es/plugins/sdk-runtime) — helpers `api.runtime` (TTS, búsqueda, subagent)
- [SDK Overview](/es/plugins/sdk-overview) — referencia completa de importaciones por subruta
- [Plugin Internals](/es/plugins/architecture#provider-runtime-hooks) — detalles de hooks y ejemplos integrados
- [Plugin Internals](/es/plugins/architecture#provider-runtime-hooks) — detalles de hooks y ejemplos incluidos

89
docs/es/providers/google.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Quieres usar modelos Google Gemini con OpenClaw
- Necesitas el flujo de autenticación con clave API u OAuth
summary: Configuración de Google Gemini (clave API + OAuth, generación de imágenes, comprensión de medios, búsqueda web)
- Necesitas el flujo de autenticación con clave de API u OAuth
summary: Configuración de Google Gemini (clave de API + OAuth, generación de imágenes, comprensión de medios, búsqueda web)
title: Google (Gemini)
x-i18n:
generated_at: "2026-04-08T02:17:24Z"
generated_at: "2026-04-09T01:29:49Z"
model: gpt-5.4
provider: openai
source_hash: e9e558f5ce35c853e0240350be9a1890460c5f7f7fd30b05813a656497dee516
source_hash: fad2ff68987301bd86145fa6e10de8c7b38d5bd5dbcd13db9c883f7f5b9a4e01
source_path: providers/google.md
workflow: 15
---
@ -26,13 +26,13 @@ Gemini Grounding.
## Inicio rápido
1. Define la clave API:
1. Establece la clave de API:
```bash
openclaw onboard --auth-choice gemini-api-key
```
2. Define un modelo predeterminado:
2. Establece un modelo predeterminado:
```json5
{
@ -55,13 +55,13 @@ openclaw onboard --non-interactive \
## OAuth (Gemini CLI)
Un proveedor alternativo `google-gemini-cli` usa OAuth PKCE en lugar de una
clave API. Esta es una integración no oficial; algunos usuarios informan
restricciones en la cuenta. Úsala bajo tu propia responsabilidad.
Un proveedor alternativo `google-gemini-cli` usa OAuth con PKCE en lugar de una clave de
API. Esta es una integración no oficial; algunos usuarios informan
restricciones de cuenta. Úsalo bajo tu propia responsabilidad.
- Modelo predeterminado: `google-gemini-cli/gemini-3-flash-preview`
- Alias: `gemini-cli`
- Requisito de instalación: Gemini CLI local disponible como `gemini`
- Requisito previo de instalación: Gemini CLI local disponible como `gemini`
- Homebrew: `brew install gemini-cli`
- npm: `npm install -g @google/gemini-cli`
- Inicio de sesión:
@ -77,46 +77,49 @@ Variables de entorno:
(O las variantes `GEMINI_CLI_*`).
Si las solicitudes de OAuth de Gemini CLI fallan después de iniciar sesión, define
`GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host de la gateway e
inténtalo de nuevo.
Si las solicitudes OAuth de Gemini CLI fallan después del inicio de sesión, establece
`GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` en el host de la gateway y
vuelve a intentarlo.
Si el inicio de sesión falla antes de que comience el flujo del navegador, asegúrate de que el comando local `gemini`
esté instalado y disponible en `PATH`. OpenClaw admite tanto instalaciones con Homebrew
como instalaciones globales de npm, incluidos diseños comunes de Windows/npm.
esté instalado y en `PATH`. OpenClaw admite tanto instalaciones con Homebrew
como instalaciones globales con npm, incluidos diseños comunes de Windows/npm.
Notas de uso JSON de Gemini CLI:
Notas sobre el uso de JSON de Gemini CLI:
- El texto de la respuesta proviene del campo JSON `response` de CLI.
- El uso recurre a `stats` cuando CLI deja `usage` vacío.
- `stats.cached` se normaliza a `cacheRead` de OpenClaw.
- Si falta `stats.input`, OpenClaw deriva los tokens de entrada de
- El texto de respuesta proviene del campo `response` del JSON de CLI.
- El uso vuelve a `stats` cuando la CLI deja `usage` vacío.
- `stats.cached` se normaliza en `cacheRead` de OpenClaw.
- Si falta `stats.input`, OpenClaw deriva los tokens de entrada a partir de
`stats.input_tokens - stats.cached`.
## Capacidades
| Capacidad | Compatible |
| ---------------------- | ----------------- |
| Finalizaciones de chat | Sí |
| Finalización de chat | Sí |
| Generación de imágenes | Sí |
| Generación de música | Sí |
| Comprensión de imagen | Sí |
| Comprensión de imágenes| Sí |
| Transcripción de audio | Sí |
| Comprensión de video | Sí |
| Búsqueda web (Grounding) | Sí |
| Pensamiento/razonamiento | Sí (Gemini 3.1+) |
| Thinking/reasoning | Sí (Gemini 3.1+) |
| Modelos Gemma 4 | Sí |
Los modelos Gemma 4 (por ejemplo `gemma-4-26b-a4b-it`) admiten el modo thinking. OpenClaw reescribe `thinkingBudget` a un `thinkingLevel` de Google compatible para Gemma 4. Establecer thinking en `off` mantiene thinking desactivado en lugar de asignarlo a `MINIMAL`.
## Reutilización directa de caché de Gemini
Para ejecuciones directas de la API de Gemini (`api: "google-generative-ai"`), OpenClaw ahora
pasa un identificador configurado `cachedContent` a las solicitudes de Gemini.
Para ejecuciones directas con la API de Gemini (`api: "google-generative-ai"`), OpenClaw ahora
pasa un identificador `cachedContent` configurado a las solicitudes de Gemini.
- Configura parámetros por modelo o globales con
`cachedContent` o el heredado `cached_content`
- Si ambos están presentes, `cachedContent` tiene prioridad
- Valor de ejemplo: `cachedContents/prebuilt-context`
- El uso por acierto de caché de Gemini se normaliza a `cacheRead` en OpenClaw a partir de
`cachedContentTokenCount` ascendente
- El uso con aciertos de caché de Gemini se normaliza en `cacheRead` de OpenClaw a partir de
`cachedContentTokenCount` upstream
Ejemplo:
@ -138,17 +141,17 @@ Ejemplo:
## Generación de imágenes
El proveedor integrado de generación de imágenes `google` usa de forma predeterminada
El proveedor empaquetado de generación de imágenes `google` usa de forma predeterminada
`google/gemini-3.1-flash-image-preview`.
- También admite `google/gemini-3-pro-image-preview`
- Generación: hasta 4 imágenes por solicitud
- Modo de edición: habilitado, hasta 5 imágenes de entrada
- Modo edición: habilitado, hasta 5 imágenes de entrada
- Controles de geometría: `size`, `aspectRatio` y `resolution`
El proveedor `google-gemini-cli`, solo con OAuth, es una superficie separada
de inferencia de texto. La generación de imágenes, la comprensión de medios y Gemini Grounding permanecen en
el identificador de proveedor `google`.
El proveedor `google-gemini-cli`, solo con OAuth, es una superficie independiente
de inferencia de texto. La generación de imágenes, la comprensión de medios y Gemini Grounding siguen en
el ID de proveedor `google`.
Para usar Google como proveedor de imágenes predeterminado:
@ -164,18 +167,18 @@ Para usar Google como proveedor de imágenes predeterminado:
}
```
Consulta [Image Generation](/es/tools/image-generation) para conocer los
parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de failover.
Consulta [Image Generation](/es/tools/image-generation) para ver los parámetros
compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error.
## Generación de video
El plugin integrado `google` también registra generación de video mediante la herramienta compartida
El plugin empaquetado `google` también registra la generación de video mediante la herramienta compartida
`video_generate`.
- Modelo de video predeterminado: `google/veo-3.1-fast-generate-preview`
- Modos: texto a video, imagen a video y flujos de referencia de un solo video
- Admite `aspectRatio`, `resolution` y `audio`
- Límite actual de duración: **4 a 8 segundos**
- Límite actual de duración: **de 4 a 8 segundos**
Para usar Google como proveedor de video predeterminado:
@ -191,17 +194,17 @@ Para usar Google como proveedor de video predeterminado:
}
```
Consulta [Video Generation](/es/tools/video-generation) para conocer los
parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de failover.
Consulta [Video Generation](/es/tools/video-generation) para ver los parámetros
compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error.
## Generación de música
El plugin integrado `google` también registra generación de música mediante la herramienta compartida
El plugin empaquetado `google` también registra la generación de música mediante la herramienta compartida
`music_generate`.
- Modelo de música predeterminado: `google/lyria-3-clip-preview`
- También admite `google/lyria-3-pro-preview`
- Controles de prompt: `lyrics` e `instrumental`
- Controles del prompt: `lyrics` e `instrumental`
- Formato de salida: `mp3` de forma predeterminada, además de `wav` en `google/lyria-3-pro-preview`
- Entradas de referencia: hasta 10 imágenes
- Las ejecuciones respaldadas por sesión se desacoplan mediante el flujo compartido de tarea/estado, incluido `action: "status"`
@ -220,11 +223,11 @@ Para usar Google como proveedor de música predeterminado:
}
```
Consulta [Music Generation](/es/tools/music-generation) para conocer los
parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de failover.
Consulta [Music Generation](/es/tools/music-generation) para ver los parámetros
compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error.
## Nota sobre el entorno
Si la gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `GEMINI_API_KEY`
Si la Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `GEMINI_API_KEY`
esté disponible para ese proceso (por ejemplo, en `~/.openclaw/.env` o mediante
`env.shellEnv`).

62
docs/es/providers/inferrs.md
View File

@ -6,10 +6,10 @@ read_when:
summary: Ejecuta OpenClaw mediante inferrs (servidor local compatible con OpenAI)
title: inferrs
x-i18n:
generated_at: "2026-04-08T02:17:25Z"
generated_at: "2026-04-09T01:30:07Z"
model: gpt-5.4
provider: openai
source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6
source_hash: 03b9d5a9935c75fd369068bacb7807a5308cd0bd74303b664227fb664c3a2098
source_path: providers/inferrs.md
workflow: 15
---
@ -17,11 +17,11 @@ x-i18n:
# inferrs
[inferrs](https://github.com/ericcurtin/inferrs) puede servir modelos locales detrás de una
API `/v1` compatible con OpenAI. OpenClaw funciona con `inferrs` mediante la ruta genérica
API `/v1` compatible con OpenAI. OpenClaw funciona con `inferrs` a través de la ruta genérica
`openai-completions`.
Actualmente, lo mejor es tratar `inferrs` como un backend personalizado autoalojado
compatible con OpenAI, no como un plugin de proveedor dedicado de OpenClaw.
Actualmente, lo mejor es tratar `inferrs` como un backend personalizado autohospedado compatible con OpenAI,
no como un plugin de proveedor dedicado de OpenClaw.
## Inicio rápido
@ -30,20 +30,20 @@ compatible con OpenAI, no como un plugin de proveedor dedicado de OpenClaw.
Ejemplo:
```bash
inferrs serve gg-hf-gg/gemma-4-E2B-it \
inferrs serve google/gemma-4-E2B-it \
--host 127.0.0.1 \
--port 8080 \
--device metal
```
2. Verifica que se pueda acceder al servidor.
2. Verifica que el servidor sea accesible.
```bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models
```
3. Añade una entrada explícita de proveedor de OpenClaw y apunta tu modelo predeterminado a ella.
3. Añade una entrada de proveedor explícita de OpenClaw y apunta tu modelo predeterminado a ella.
## Ejemplo completo de configuración
@ -53,9 +53,9 @@ Este ejemplo usa Gemma 4 en un servidor local de `inferrs`.
{
agents: {
defaults: {
model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" },
model: { primary: "inferrs/google/gemma-4-E2B-it" },
models: {
"inferrs/gg-hf-gg/gemma-4-E2B-it": {
"inferrs/google/gemma-4-E2B-it": {
alias: "Gemma 4 (inferrs)",
},
},
@ -70,7 +70,7 @@ Este ejemplo usa Gemma 4 en un servidor local de `inferrs`.
api: "openai-completions",
models: [
{
id: "gg-hf-gg/gemma-4-E2B-it",
id: "google/gemma-4-E2B-it",
name: "Gemma 4 E2B (inferrs)",
reasoning: false,
input: ["text"],
@ -88,12 +88,12 @@ Este ejemplo usa Gemma 4 en un servidor local de `inferrs`.
}
```
## Por qué importa `requiresStringContent`
## Por qué `requiresStringContent` es importante
Algunas rutas Chat Completions de `inferrs` aceptan solo
`messages[].content` de tipo cadena, no matrices estructuradas de partes de contenido.
Algunas rutas de Chat Completions de `inferrs` aceptan solo
`messages[].content` como cadena, no matrices estructuradas de partes de contenido.
Si las ejecuciones de OpenClaw fallan con un error como:
Si las ejecuciones de OpenClaw fallan con un error como este:
```text
messages[1].content: invalid type: sequence, expected a string
@ -112,8 +112,8 @@ la solicitud.
## Advertencia sobre Gemma y el esquema de herramientas
Algunas combinaciones actuales de `inferrs` + Gemma aceptan solicitudes directas pequeñas a
`/v1/chat/completions`, pero aun así fallan en turnos completos del entorno de ejecución de agentes de OpenClaw.
Algunas combinaciones actuales de `inferrs` + Gemma aceptan solicitudes pequeñas directas a
`/v1/chat/completions`, pero aun así fallan en turnos completos del runtime de agente de OpenClaw.
Si eso ocurre, prueba primero esto:
@ -124,30 +124,30 @@ compat: {
}
```
Eso desactiva la superficie de esquema de herramientas de OpenClaw para el modelo y puede reducir la
Eso desactiva la superficie del esquema de herramientas de OpenClaw para el modelo y puede reducir la
presión del prompt en backends locales más estrictos.
Si las solicitudes directas pequeñas siguen funcionando, pero los turnos normales de agentes de OpenClaw continúan
fallando dentro de `inferrs`, el problema restante suele estar en el comportamiento ascendente del modelo/servidor
y no en la capa de transporte de OpenClaw.
Si las solicitudes directas pequeñas siguen funcionando pero los turnos normales del agente de OpenClaw continúan
fallando dentro de `inferrs`, el problema restante suele ser un comportamiento upstream del modelo/servidor
más que de la capa de transporte de OpenClaw.
## Prueba manual rápida
## Prueba manual básica
Una vez configurado, prueba ambas capas:
```bash
curl http://127.0.0.1:8080/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'
-d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'
openclaw infer model run \
--model inferrs/gg-hf-gg/gemma-4-E2B-it \
--model inferrs/google/gemma-4-E2B-it \
--prompt "What is 2 + 2? Reply with one short sentence." \
--json
```
Si el primer comando funciona pero el segundo falla, usa las notas de solución de problemas
de abajo.
que aparecen a continuación.
## Solución de problemas
@ -158,22 +158,22 @@ de abajo.
- Las llamadas directas pequeñas a `/v1/chat/completions` funcionan, pero `openclaw infer model run`
falla: prueba `compat.supportsTools: false`.
- OpenClaw ya no recibe errores de esquema, pero `inferrs` sigue fallando en turnos de
agentes más grandes: trátalo como una limitación ascendente de `inferrs` o del modelo y reduce la
agente más grandes: trátalo como una limitación upstream de `inferrs` o del modelo, y reduce la
presión del prompt o cambia de backend/modelo local.
## Comportamiento de estilo proxy
## Comportamiento de tipo proxy
`inferrs` se trata como un backend `/v1` compatible con OpenAI de estilo proxy, no como un
`inferrs` se trata como un backend `/v1` compatible con OpenAI de tipo proxy, no como un
endpoint nativo de OpenAI.
- aquí no se aplica el modelado de solicitudes exclusivo de OpenAI nativo
- no hay `service_tier`, ni `store` de Responses, ni sugerencias de caché de prompts, ni
modelado de payload de compatibilidad de razonamiento de OpenAI
- no hay `service_tier`, no hay `store` de Responses, no hay sugerencias de caché de prompt ni
modelado de carga útil de compatibilidad de reasoning de OpenAI
- los encabezados ocultos de atribución de OpenClaw (`originator`, `version`, `User-Agent`)
no se inyectan en URLs base personalizadas de `inferrs`
## Ver también
- [Modelos locales](/es/gateway/local-models)
- [Solución de problemas del gateway](/es/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
- [Solución de problemas de Gateway](/es/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
- [Proveedores de modelos](/es/concepts/model-providers)

84
docs/es/providers/ollama.md
View File

@ -1,39 +1,39 @@
---
read_when:
- Quieres ejecutar OpenClaw con modelos en la nube o locales mediante Ollama
- Necesitas orientación de configuración y puesta en marcha de Ollama
- Necesitas orientación para la configuración y puesta en marcha de Ollama
summary: Ejecuta OpenClaw con Ollama (modelos en la nube y locales)
title: Ollama
x-i18n:
generated_at: "2026-04-08T02:18:01Z"
generated_at: "2026-04-09T01:30:28Z"
model: gpt-5.4
provider: openai
source_hash: 222ec68f7d4bb29cc7796559ddef1d5059f5159e7a51e2baa3a271ddb3abb716
source_hash: d3295a7c879d3636a2ffdec05aea6e670e54a990ef52bd9b0cae253bc24aa3f7
source_path: providers/ollama.md
workflow: 15
---
# Ollama
Ollama es un runtime de LLM local que facilita ejecutar modelos de código abierto en tu equipo. OpenClaw se integra con la API nativa de Ollama (`/api/chat`), admite streaming y llamadas a herramientas, y puede detectar automáticamente modelos locales de Ollama cuando optas por usar `OLLAMA_API_KEY` (o un perfil de autenticación) y no defines una entrada explícita `models.providers.ollama`.
Ollama es un entorno de ejecución local de LLM que facilita ejecutar modelos de código abierto en tu equipo. OpenClaw se integra con la API nativa de Ollama (`/api/chat`), admite streaming y tool calling, y puede detectar automáticamente modelos locales de Ollama cuando lo habilitas con `OLLAMA_API_KEY` (o un perfil de autenticación) y no defines una entrada explícita `models.providers.ollama`.
<Warning>
**Usuarios de Ollama remoto**: No uses la URL compatible con OpenAI `/v1` (`http://host:11434/v1`) con OpenClaw. Esto rompe las llamadas a herramientas y los modelos pueden generar JSON de herramientas sin procesar como texto plano. Usa en su lugar la URL de la API nativa de Ollama: `baseUrl: "http://host:11434"` (sin `/v1`).
**Usuarios de Ollama remoto**: No uses la URL compatible con OpenAI `/v1` (`http://host:11434/v1`) con OpenClaw. Esto rompe el tool calling y los modelos pueden producir JSON de herramientas sin procesar como texto sin formato. Usa en su lugar la URL de la API nativa de Ollama: `baseUrl: "http://host:11434"` (sin `/v1`).
</Warning>
## Inicio rápido
### Onboarding (recomendado)
### Incorporación guiada (recomendado)
La forma más rápida de configurar Ollama es mediante el onboarding:
La forma más rápida de configurar Ollama es mediante la incorporación guiada:
```bash
openclaw onboard
```
Selecciona **Ollama** en la lista de proveedores. El onboarding hará lo siguiente:
Selecciona **Ollama** en la lista de proveedores. La incorporación guiada hará lo siguiente:
1. Pedirá la URL base de Ollama donde se puede acceder a tu instancia (valor predeterminado `http://127.0.0.1:11434`).
1. Te pedirá la URL base de Ollama en la que se puede acceder a tu instancia (predeterminada: `http://127.0.0.1:11434`).
2. Te permitirá elegir **Cloud + Local** (modelos en la nube y modelos locales) o **Local** (solo modelos locales).
3. Abrirá un flujo de inicio de sesión en el navegador si eliges **Cloud + Local** y no has iniciado sesión en ollama.com.
4. Detectará los modelos disponibles y sugerirá valores predeterminados.
@ -77,7 +77,7 @@ ollama pull llama3.3
ollama signin
```
4. Ejecuta el onboarding y elige `Ollama`:
4. Ejecuta la incorporación guiada y elige `Ollama`:
```bash
openclaw onboard
@ -92,7 +92,7 @@ OpenClaw sugiere actualmente:
- valor predeterminado local: `gemma4`
- valores predeterminados en la nube: `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`
5. Si prefieres una configuración manual, habilita Ollama para OpenClaw directamente (cualquier valor funciona; Ollama no requiere una clave real):
5. Si prefieres la configuración manual, habilita Ollama directamente para OpenClaw (cualquier valor funciona; Ollama no requiere una clave real):
```bash
# Establecer variable de entorno
@ -123,11 +123,12 @@ openclaw models set ollama/gemma4
## Detección de modelos (proveedor implícito)
Cuando estableces `OLLAMA_API_KEY` (o un perfil de autenticación) y **no** defines `models.providers.ollama`, OpenClaw detecta modelos de la instancia local de Ollama en `http://127.0.0.1:11434`:
Cuando estableces `OLLAMA_API_KEY` (o un perfil de autenticación) y **no** defines `models.providers.ollama`, OpenClaw detecta modelos desde la instancia local de Ollama en `http://127.0.0.1:11434`:
- Consulta `/api/tags`
- Usa búsquedas `/api/show` en modo best-effort para leer `contextWindow` cuando está disponible
- Marca `reasoning` con una heurística basada en el nombre del modelo (`r1`, `reasoning`, `think`)
- Usa búsquedas de `/api/show` con mejor esfuerzo para leer `contextWindow` y detectar capacidades (incluida visión) cuando estén disponibles
- Los modelos con una capacidad `vision` informada por `/api/show` se marcan como compatibles con imágenes (`input: ["text", "image"]`), por lo que OpenClaw inyecta automáticamente imágenes en el prompt para esos modelos
- Marca `reasoning` mediante una heurística por nombre de modelo (`r1`, `reasoning`, `think`)
- Establece `maxTokens` en el límite máximo predeterminado de tokens de Ollama usado por OpenClaw
- Establece todos los costos en `0`
@ -146,9 +147,9 @@ Para añadir un modelo nuevo, simplemente haz `pull` con Ollama:
ollama pull mistral
```
El nuevo modelo se detectará automáticamente y estará disponible para usar.
El modelo nuevo se detectará automáticamente y estará disponible para usarse.
Si configuras `models.providers.ollama` explícitamente, la detección automática se omite y debes definir los modelos manualmente (ver más abajo).
Si defines `models.providers.ollama` de forma explícita, se omite la detección automática y debes definir los modelos manualmente (ver más abajo).
## Configuración
@ -164,9 +165,9 @@ export OLLAMA_API_KEY="ollama-local"
Usa configuración explícita cuando:
- Ollama se ejecuta en otro host/puerto.
- Ollama se ejecuta en otro host o puerto.
- Quieres forzar ventanas de contexto o listas de modelos específicas.
- Quieres definiciones de modelos completamente manuales.
- Quieres definiciones de modelos totalmente manuales.
```json5
{
@ -193,11 +194,11 @@ Usa configuración explícita cuando:
}
```
Si `OLLAMA_API_KEY` está establecido, puedes omitir `apiKey` en la entrada del proveedor y OpenClaw lo completará para las comprobaciones de disponibilidad.
Si `OLLAMA_API_KEY` está configurada, puedes omitir `apiKey` en la entrada del proveedor y OpenClaw la completará para las comprobaciones de disponibilidad.
### URL base personalizada (configuración explícita)
Si Ollama se está ejecutando en un host o puerto diferente (la configuración explícita desactiva la detección automática, así que define los modelos manualmente):
Si Ollama se está ejecutando en un host o puerto distintos (la configuración explícita desactiva la detección automática, por lo que debes definir los modelos manualmente):
```json5
{
@ -205,8 +206,8 @@ Si Ollama se está ejecutando en un host o puerto diferente (la configuración e
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // Sin /v1: usa la URL nativa de la API de Ollama
api: "ollama", // Establécelo explícitamente para garantizar el comportamiento nativo de llamadas a herramientas
baseUrl: "http://ollama-host:11434", // Sin /v1: usa la URL de la API nativa de Ollama
api: "ollama", // Establécelo explícitamente para garantizar el comportamiento nativo de tool calling
},
},
},
@ -214,10 +215,10 @@ Si Ollama se está ejecutando en un host o puerto diferente (la configuración e
```
<Warning>
No añadas `/v1` a la URL. La ruta `/v1` usa el modo compatible con OpenAI, donde las llamadas a herramientas no son fiables. Usa la URL base de Ollama sin un sufijo de ruta.
No añadas `/v1` a la URL. La ruta `/v1` usa el modo compatible con OpenAI, donde el tool calling no es fiable. Usa la URL base de Ollama sin sufijo de ruta.
</Warning>
### Selección de modelos
### Selección de modelo
Una vez configurado, todos tus modelos de Ollama estarán disponibles:
@ -238,22 +239,19 @@ Una vez configurado, todos tus modelos de Ollama estarán disponibles:
Los modelos en la nube te permiten ejecutar modelos alojados en la nube (por ejemplo, `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`) junto con tus modelos locales.
Para usar modelos en la nube, selecciona el modo **Cloud + Local** durante la configuración. El asistente comprueba si has iniciado sesión y abre un flujo de inicio de sesión en el navegador cuando es necesario. Si no se puede verificar la autenticación, el asistente vuelve a los valores predeterminados de modelos locales.
Para usar modelos en la nube, selecciona el modo **Cloud + Local** durante la configuración. El asistente comprueba si has iniciado sesión y abre un flujo de inicio de sesión en el navegador cuando es necesario. Si no se puede verificar la autenticación, el asistente recurre a los valores predeterminados de modelos locales.
También puedes iniciar sesión directamente en [ollama.com/signin](https://ollama.com/signin).
## Búsqueda web de Ollama
## Ollama Web Search
OpenClaw también es compatible con **Ollama Web Search** como proveedor
empaquetado de `web_search`.
OpenClaw también admite **Ollama Web Search** como proveedor integrado de `web_search`.
- Usa tu host de Ollama configurado (`models.providers.ollama.baseUrl` cuando
está configurado; de lo contrario `http://127.0.0.1:11434`).
- Usa tu host de Ollama configurado (`models.providers.ollama.baseUrl` cuando está definido; de lo contrario, `http://127.0.0.1:11434`).
- No requiere clave.
- Requiere que Ollama esté en ejecución y que hayas iniciado sesión con `ollama signin`.
Elige **Ollama Web Search** durante `openclaw onboard` o
`openclaw configure --section web`, o configura:
Elige **Ollama Web Search** durante `openclaw onboard` o `openclaw configure --section web`, o establece:
```json5
{
@ -267,30 +265,30 @@ Elige **Ollama Web Search** durante `openclaw onboard` o
}
```
Para ver la configuración completa y los detalles del comportamiento, consulta [Ollama Web Search](/es/tools/ollama-search).
Para conocer todos los detalles de configuración y comportamiento, consulta [Ollama Web Search](/es/tools/ollama-search).
## Avanzado
### Modelos de razonamiento
OpenClaw trata de forma predeterminada los modelos con nombres como `deepseek-r1`, `reasoning` o `think` como modelos con capacidad de razonamiento:
OpenClaw trata de forma predeterminada como compatibles con razonamiento a los modelos con nombres como `deepseek-r1`, `reasoning` o `think`:
```bash
ollama pull deepseek-r1:32b
```
### Costos de modelos
### Costos del modelo
Ollama es gratuito y se ejecuta localmente, por lo que todos los costos de los modelos se establecen en $0.
Ollama es gratuito y se ejecuta localmente, por lo que todos los costos de modelo se establecen en $0.
### Configuración de streaming
La integración de Ollama en OpenClaw usa la **API nativa de Ollama** (`/api/chat`) de forma predeterminada, que admite completamente streaming y llamadas a herramientas al mismo tiempo. No se necesita ninguna configuración especial.
La integración de Ollama en OpenClaw usa de forma predeterminada la **API nativa de Ollama** (`/api/chat`), que admite completamente streaming y tool calling al mismo tiempo. No se necesita ninguna configuración especial.
#### Modo heredado compatible con OpenAI
<Warning>
**Las llamadas a herramientas no son fiables en el modo compatible con OpenAI.** Usa este modo solo si necesitas el formato de OpenAI para un proxy y no dependes del comportamiento nativo de llamadas a herramientas.
**El tool calling no es fiable en el modo compatible con OpenAI.** Usa este modo solo si necesitas el formato OpenAI para un proxy y no dependes del comportamiento nativo de tool calling.
</Warning>
Si necesitas usar en su lugar el endpoint compatible con OpenAI (por ejemplo, detrás de un proxy que solo admite formato OpenAI), establece `api: "openai-completions"` explícitamente:
@ -311,9 +309,9 @@ Si necesitas usar en su lugar el endpoint compatible con OpenAI (por ejemplo, de
}
```
Es posible que este modo no admita streaming + llamadas a herramientas simultáneamente. Puede que necesites desactivar el streaming con `params: { streaming: false }` en la configuración del modelo.
Es posible que este modo no admita streaming + tool calling simultáneamente. Puede que necesites desactivar el streaming con `params: { streaming: false }` en la configuración del modelo.
Cuando se usa `api: "openai-completions"` con Ollama, OpenClaw inyecta `options.num_ctx` de forma predeterminada para que Ollama no vuelva silenciosamente a una ventana de contexto de 4096. Si tu proxy/upstream rechaza campos `options` desconocidos, desactiva este comportamiento:
Cuando se usa `api: "openai-completions"` con Ollama, OpenClaw inyecta `options.num_ctx` de forma predeterminada para que Ollama no vuelva silenciosamente a una ventana de contexto de 4096. Si tu proxy o servicio ascendente rechaza campos `options` desconocidos, desactiva este comportamiento:
```json5
{
@ -337,15 +335,15 @@ Para los modelos detectados automáticamente, OpenClaw usa la ventana de context
## Solución de problemas
### No se detecta Ollama
### Ollama no se detecta
Asegúrate de que Ollama se está ejecutando, de que estableciste `OLLAMA_API_KEY` (o un perfil de autenticación) y de que **no** definiste una entrada explícita `models.providers.ollama`:
Asegúrate de que Ollama esté en ejecución, de que hayas configurado `OLLAMA_API_KEY` (o un perfil de autenticación) y de que **no** hayas definido una entrada explícita `models.providers.ollama`:
```bash
ollama serve
```
Y de que la API sea accesible:
Y de que se pueda acceder a la API:
```bash
curl http://localhost:11434/api/tags

116
docs/es/providers/qwen.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Quieres usar Qwen con OpenClaw
- Antes usabas OAuth de Qwen
summary: Usa Qwen Cloud mediante el proveedor `qwen` empaquetado de OpenClaw
- Antes usabas Qwen OAuth
summary: Usa Qwen Cloud mediante el proveedor qwen empaquetado de OpenClaw
title: Qwen
x-i18n:
generated_at: "2026-04-06T03:11:04Z"
generated_at: "2026-04-09T01:30:31Z"
model: gpt-5.4
provider: openai
source_hash: f175793693ab6a4c3f1f4d42040e673c15faf7603a500757423e9e06977c989d
source_hash: 4786df2cb6ec1ab29d191d012c61dcb0e5468bf0f8561fbbb50eed741efad325
source_path: providers/qwen.md
workflow: 15
---
@ -17,7 +17,7 @@ x-i18n:
<Warning>
**Se eliminó OAuth de Qwen.** La integración OAuth del nivel gratuito
**Qwen OAuth ha sido eliminado.** La integración OAuth de nivel gratuito
(`qwen-portal`) que usaba endpoints de `portal.qwen.ai` ya no está disponible.
Consulta [Issue #49557](https://github.com/openclaw/openclaw/issues/49557) para
obtener contexto.
@ -26,10 +26,10 @@ obtener contexto.
## Recomendado: Qwen Cloud
OpenClaw ahora trata a Qwen como un proveedor empaquetado de primera clase con el id canónico
OpenClaw ahora trata Qwen como un proveedor empaquetado de primera clase con el id canónico
`qwen`. El proveedor empaquetado apunta a los endpoints de Qwen Cloud / Alibaba DashScope y
Coding Plan, y mantiene los id heredados `modelstudio` funcionando como alias
de compatibilidad.
Coding Plan, y mantiene los ids heredados `modelstudio` funcionando como alias de
compatibilidad.
- Proveedor: `qwen`
- Variable de entorno preferida: `QWEN_API_KEY`
@ -43,21 +43,21 @@ La compatibilidad con Coding Plan puede ir por detrás del catálogo público.
# Endpoint global de Coding Plan
openclaw onboard --auth-choice qwen-api-key
# Endpoint de Coding Plan para China
# Endpoint de Coding Plan en China
openclaw onboard --auth-choice qwen-api-key-cn
# Endpoint global Standard (pay-as-you-go)
openclaw onboard --auth-choice qwen-standard-api-key
# Endpoint para China Standard (pay-as-you-go)
# Endpoint Standard (pay-as-you-go) en China
openclaw onboard --auth-choice qwen-standard-api-key-cn
```
Los id heredados de `auth-choice` `modelstudio-*` y las referencias de modelo `modelstudio/...` todavía
funcionan como alias de compatibilidad, pero los nuevos flujos de configuración deben preferir los id canónicos
de `auth-choice` `qwen-*` y las referencias de modelo `qwen/...`.
Los ids heredados `modelstudio-*` para `auth-choice` y las referencias de modelo `modelstudio/...` siguen
funcionando como alias de compatibilidad, pero los nuevos flujos de configuración deberían preferir los ids canónicos
`qwen-*` para `auth-choice` y las referencias de modelo `qwen/...`.
Después del onboarding, establece un modelo predeterminado:
Después de la configuración inicial, establece un modelo predeterminado:
```json5
{
@ -79,12 +79,12 @@ Después del onboarding, establece un modelo predeterminado:
| Coding Plan (subscription) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` |
El proveedor selecciona automáticamente el endpoint según tu `auth choice`. Las opciones canónicas
usan la familia `qwen-*`; `modelstudio-*` sigue siendo solo de compatibilidad.
Puedes sobrescribirlo con un `baseUrl` personalizado en la configuración.
usan la familia `qwen-*`; `modelstudio-*` queda solo para compatibilidad.
Puedes reemplazarlo con un `baseUrl` personalizado en la configuración.
Los endpoints nativos de Model Studio anuncian compatibilidad de uso de streaming en el
transporte compartido `openai-completions`. OpenClaw ahora basa esto en las capacidades del endpoint,
por lo que los id personalizados de proveedores compatibles con DashScope que apunten a los
transporte compartido `openai-completions`. OpenClaw ahora basa eso en las capacidades del endpoint,
por lo que los ids de proveedor personalizados compatibles con DashScope que apunten a los
mismos hosts nativos heredan el mismo comportamiento de uso de streaming en lugar de
requerir específicamente el id del proveedor integrado `qwen`.
@ -95,25 +95,27 @@ requerir específicamente el id del proveedor integrado `qwen`.
## Catálogo integrado
OpenClaw actualmente incluye este catálogo empaquetado de Qwen:
Actualmente, OpenClaw incluye este catálogo Qwen empaquetado. El catálogo configurado
tiene en cuenta el endpoint: las configuraciones de Coding Plan omiten modelos que solo se sabe que funcionan en
el endpoint Standard.
| Referencia de modelo | Entrada | Contexto | Notas |
| --------------------------- | ----------- | --------- | -------------------------------------------------- |
| `qwen/qwen3.5-plus` | texto, imagen | 1,000,000 | Modelo predeterminado |
| `qwen/qwen3.6-plus` | texto, imagen | 1,000,000 | Prefiere endpoints Standard cuando necesites este modelo |
| `qwen/qwen3-max-2026-01-23` | texto | 262,144 | Línea Qwen Max |
| `qwen/qwen3-coder-next` | texto | 262,144 | Código |
| `qwen/qwen3-coder-plus` | texto | 1,000,000 | Código |
| `qwen/MiniMax-M2.5` | texto | 1,000,000 | Razonamiento habilitado |
| `qwen/glm-5` | texto | 202,752 | GLM |
| `qwen/glm-4.7` | texto | 202,752 | GLM |
| `qwen/kimi-k2.5` | texto, imagen | 262,144 | Moonshot AI a través de Alibaba |
| Referencia de modelo | Entrada | Contexto | Notas |
| -------------------------- | ----------- | --------- | -------------------------------------------------- |
| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Modelo predeterminado |
| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Prefiere endpoints Standard cuando necesites este modelo |
| `qwen/qwen3-max-2026-01-23`| text | 262,144 | Línea Qwen Max |
| `qwen/qwen3-coder-next` | text | 262,144 | Coding |
| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding |
| `qwen/MiniMax-M2.5` | text | 1,000,000 | Reasoning habilitado |
| `qwen/glm-5` | text | 202,752 | GLM |
| `qwen/glm-4.7` | text | 202,752 | GLM |
| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI mediante Alibaba |
La disponibilidad aún puede variar según el endpoint y el plan de facturación incluso cuando un modelo
está presente en el catálogo empaquetado.
La disponibilidad puede seguir variando según el endpoint y el plan de facturación, incluso cuando un modelo
esté presente en el catálogo empaquetado.
La compatibilidad de uso de streaming nativo se aplica tanto a los hosts de Coding Plan como a
los hosts Standard compatibles con DashScope:
La compatibilidad de uso de streaming nativo se aplica tanto a los hosts de Coding Plan como a los
hosts Standard compatibles con DashScope:
- `https://coding.dashscope.aliyuncs.com/v1`
- `https://coding-intl.dashscope.aliyuncs.com/v1`
@ -122,7 +124,7 @@ los hosts Standard compatibles con DashScope:
## Disponibilidad de Qwen 3.6 Plus
`qwen3.6-plus` está disponible en los endpoints de Model Studio Standard (pay-as-you-go):
`qwen3.6-plus` está disponible en los endpoints Model Studio Standard (pay-as-you-go):
- China: `dashscope.aliyuncs.com/compatible-mode/v1`
- Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1`
@ -133,16 +135,16 @@ endpoint/clave de Coding Plan.
## Plan de capacidades
La extensión `qwen` se está posicionando como el hogar del proveedor para toda la superficie de Qwen
Cloud, no solo para modelos de código/texto.
La extensión `qwen` se está posicionando como la base del proveedor para toda la superficie de Qwen
Cloud, no solo para modelos de coding/texto.
- Modelos de texto/chat: ya incluidos
- Llamada de herramientas, salida estructurada, thinking: heredados del transporte compatible con OpenAI
- Generación de imágenes: planificada en la capa de plugins de proveedor
- Comprensión de imágenes/video: ya incluida en el endpoint Standard
- Voz/audio: planificada en la capa de plugins de proveedor
- Embeddings/reranking de memoria: planificados a través de la superficie del adaptador de embeddings
- Generación de video: ya incluida mediante la capacidad compartida de generación de video
- Modelos de texto/chat: empaquetados ahora
- Llamadas a herramientas, salida estructurada, thinking: heredados del transporte compatible con OpenAI
- Generación de imágenes: planificada en la capa del plugin de proveedor
- Comprensión de imagen/video: empaquetada ahora en el endpoint Standard
- Voz/audio: planificada en la capa del plugin de proveedor
- Embeddings/reranking de memoria: planificados mediante la superficie del adaptador de embeddings
- Generación de video: empaquetada ahora mediante la capacidad compartida de generación de video
## Complementos multimodales
@ -159,17 +161,17 @@ La extensión `qwen` ahora también expone:
Estas superficies multimodales usan los endpoints DashScope **Standard**, no los
endpoints de Coding Plan.
- URL base de Standard global/intl: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
- URL base de Standard China: `https://dashscope.aliyuncs.com/compatible-mode/v1`
- URL base Standard global/internacional: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
- URL base Standard de China: `https://dashscope.aliyuncs.com/compatible-mode/v1`
Para la generación de video, OpenClaw asigna la región de Qwen configurada al host
AIGC de DashScope correspondiente antes de enviar el trabajo:
Para la generación de video, OpenClaw asigna la región de Qwen configurada al host AIGC de
DashScope correspondiente antes de enviar el trabajo:
- Global/Intl: `https://dashscope-intl.aliyuncs.com`
- Global/internacional: `https://dashscope-intl.aliyuncs.com`
- China: `https://dashscope.aliyuncs.com`
Eso significa que un `models.providers.qwen.baseUrl` normal que apunte a cualquiera de los
hosts de Qwen de Coding Plan o Standard sigue manteniendo la generación de video en el endpoint
hosts Qwen de Coding Plan o Standard sigue manteniendo la generación de video en el endpoint
regional correcto de video de DashScope.
Para la generación de video, establece explícitamente un modelo predeterminado:
@ -184,22 +186,22 @@ Para la generación de video, establece explícitamente un modelo predeterminado
}
```
Límites actuales de generación de video del Qwen empaquetado:
Límites actuales empaquetados de generación de video de Qwen:
- Hasta **1** video de salida por solicitud
- Hasta **1** imagen de entrada
- Hasta **4** videos de entrada
- Hasta **10 segundos** de duración
- Admite `size`, `aspectRatio`, `resolution`, `audio` y `watermark`
- El modo de imagen/video de referencia actualmente requiere **URLs remotas http(s)**. Las
rutas de archivos locales se rechazan de entrada porque el endpoint de video de DashScope no
acepta buffers locales subidos para esas referencias.
- El modo de imagen/video de referencia actualmente requiere **URLs http(s) remotas**. Las
rutas de archivo locales se rechazan de entrada porque el endpoint de video de DashScope no
acepta buffers locales cargados para esas referencias.
Consulta [Generación de video](/tools/video-generation) para ver los parámetros
compartidos de la herramienta, la selección de proveedor y el comportamiento de failover.
Consulta [Video Generation](/es/tools/video-generation) para ver los parámetros
compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error.
## Nota sobre el entorno
Si el Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `QWEN_API_KEY` esté
Si la Gateway se ejecuta como daemon (launchd/systemd), asegúrate de que `QWEN_API_KEY` esté
disponible para ese proceso (por ejemplo, en `~/.openclaw/.env` o mediante
`env.shellEnv`).