chore(i18n): refresh es translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
6a065927f0
commit
5d962d1e67
File diff suppressed because it is too large
Load Diff
@ -1,47 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurar Slack o depurar el modo socket/HTTP de Slack
|
||||
summary: Configuración de Slack y comportamiento en tiempo de ejecución (Socket Mode + URLs de solicitud HTTP)
|
||||
- Configurar Slack o depurar el modo de socket/HTTP de Slack
|
||||
summary: Configuración de Slack y comportamiento en tiempo de ejecución (modo Socket + URL de solicitudes HTTP)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:22:11Z"
|
||||
generated_at: "2026-05-04T07:02:47Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b
|
||||
source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228
|
||||
source_path: channels/slack.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Listo para producción para MD y canales mediante integraciones de aplicaciones de Slack. El modo predeterminado es Socket Mode; también se admiten las URL de solicitud HTTP.
|
||||
Listo para producción para DM y canales mediante integraciones de aplicaciones de Slack. El modo predeterminado es Socket Mode; también se admiten URLs de solicitud HTTP.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/es/channels/pairing">
|
||||
Los MD de Slack usan el modo de emparejamiento de forma predeterminada.
|
||||
<Card title="Emparejamiento" icon="link" href="/es/channels/pairing">
|
||||
Los DM de Slack usan el modo de emparejamiento de forma predeterminada.
|
||||
</Card>
|
||||
<Card title="Slash commands" icon="terminal" href="/es/tools/slash-commands">
|
||||
Comportamiento de comandos nativos y catálogo de comandos.
|
||||
<Card title="Comandos slash" icon="terminal" href="/es/tools/slash-commands">
|
||||
Comportamiento nativo de comandos y catálogo de comandos.
|
||||
</Card>
|
||||
<Card title="Channel troubleshooting" icon="wrench" href="/es/channels/troubleshooting">
|
||||
Diagnósticos multicanal y guías de reparación.
|
||||
<Card title="Solución de problemas de canales" icon="wrench" href="/es/channels/troubleshooting">
|
||||
Diagnósticos entre canales y manuales de reparación.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Configuración rápida
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (default)">
|
||||
<Tab title="Socket Mode (predeterminado)">
|
||||
<Steps>
|
||||
<Step title="Create a new Slack app">
|
||||
<Step title="Crea una nueva aplicación de Slack">
|
||||
En la configuración de la aplicación de Slack, pulsa el botón **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- elige **from a manifest** y selecciona un espacio de trabajo para tu aplicación
|
||||
- pega el [manifiesto de ejemplo](#manifest-and-scope-checklist) de abajo y continúa para crearlo
|
||||
- pega el [manifiesto de ejemplo](#manifest-and-scope-checklist) de abajo y continúa para crearla
|
||||
- genera un **App-Level Token** (`xapp-...`) con `connections:write`
|
||||
- instala la aplicación y copia el **Bot Token** (`xoxb-...`) que se muestra
|
||||
- instala la aplicación y copia el **Bot Token** (`xoxb-...`) mostrado
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure OpenClaw">
|
||||
<Step title="Configura OpenClaw">
|
||||
|
||||
Configuración recomendada de SecretRef:
|
||||
|
||||
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
|
||||
openclaw config patch --file ./slack.socket.patch.json5
|
||||
```
|
||||
|
||||
Respaldo con env (solo cuenta predeterminada):
|
||||
Respaldo con variables de entorno (solo cuenta predeterminada):
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway">
|
||||
<Step title="Inicia Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -84,19 +84,19 @@ openclaw gateway
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="HTTP Request URLs">
|
||||
<Tab title="URLs de solicitud HTTP">
|
||||
<Steps>
|
||||
<Step title="Create a new Slack app">
|
||||
<Step title="Crea una nueva aplicación de Slack">
|
||||
En la configuración de la aplicación de Slack, pulsa el botón **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- elige **from a manifest** y selecciona un espacio de trabajo para tu aplicación
|
||||
- pega el [manifiesto de ejemplo](#manifest-and-scope-checklist) y actualiza las URL antes de crear
|
||||
- guarda el **Signing Secret** para la verificación de solicitudes
|
||||
- instala la aplicación y copia el **Bot Token** (`xoxb-...`) que se muestra
|
||||
- pega el [manifiesto de ejemplo](#manifest-and-scope-checklist) y actualiza las URLs antes de crearla
|
||||
- guarda el **Signing Secret** para verificar solicitudes
|
||||
- instala la aplicación y copia el **Bot Token** (`xoxb-...`) mostrado
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure OpenClaw">
|
||||
<Step title="Configura OpenClaw">
|
||||
|
||||
Configuración recomendada de SecretRef:
|
||||
|
||||
@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5
|
||||
```
|
||||
|
||||
<Note>
|
||||
Usa rutas de webhook únicas para HTTP multicuenta
|
||||
Usa rutas de Webhook únicas para HTTP con varias cuentas
|
||||
|
||||
Dale a cada cuenta un `webhookPath` distinto (predeterminado `/slack/events`) para que los registros no colisionen.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway">
|
||||
<Step title="Inicia Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -142,7 +142,7 @@ openclaw gateway
|
||||
|
||||
## Ajuste del transporte de Socket Mode
|
||||
|
||||
OpenClaw establece de forma predeterminada el tiempo de espera de pong del cliente SDK de Slack en 15 segundos para Socket Mode. Sobrescribe la configuración de transporte solo cuando necesites ajustes específicos del espacio de trabajo o del host:
|
||||
OpenClaw establece de forma predeterminada el tiempo de espera de pong del cliente del SDK de Slack en 15 segundos para Socket Mode. Sobrescribe la configuración de transporte solo cuando necesites ajustes específicos del espacio de trabajo o del host:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,11 +159,11 @@ OpenClaw establece de forma predeterminada el tiempo de espera de pong del clien
|
||||
}
|
||||
```
|
||||
|
||||
Usa esto solo para espacios de trabajo de Socket Mode que registren tiempos de espera de pong/websocket o server-ping de Slack, o que se ejecuten en hosts con inanición conocida del bucle de eventos. `clientPingTimeout` es la espera de pong después de que el SDK envía un ping de cliente; `serverPingTimeout` es la espera de pings del servidor de Slack. Los mensajes y eventos de la aplicación siguen siendo estado de la aplicación, no señales de vivacidad del transporte.
|
||||
Úsalo solo para espacios de trabajo de Socket Mode que registren tiempos de espera de pong/websocket de Slack o de ping del servidor, o que se ejecuten en hosts con inanición conocida del bucle de eventos. `clientPingTimeout` es la espera de pong después de que el SDK envía un ping de cliente; `serverPingTimeout` es la espera para los pings del servidor de Slack. Los mensajes y eventos de la aplicación siguen siendo estado de la aplicación, no señales de vivacidad del transporte.
|
||||
|
||||
## Lista de comprobación de manifiesto y ámbitos
|
||||
## Lista de comprobación de manifiesto y alcances
|
||||
|
||||
El manifiesto base de la aplicación de Slack es el mismo para Socket Mode y las URL de solicitud HTTP. Solo difiere el bloque `settings` (y la `url` del comando slash).
|
||||
El manifiesto base de la aplicación de Slack es el mismo para Socket Mode y las URLs de solicitud HTTP. Solo difiere el bloque `settings` (y la `url` del comando slash).
|
||||
|
||||
Manifiesto base (Socket Mode predeterminado):
|
||||
|
||||
@ -240,7 +240,7 @@ Manifiesto base (Socket Mode predeterminado):
|
||||
}
|
||||
```
|
||||
|
||||
Para el modo **URL de solicitud HTTP**, sustituye `settings` por la variante HTTP y añade `url` a cada comando slash. Se requiere una URL pública:
|
||||
Para el **modo de URLs de solicitud HTTP**, reemplaza `settings` con la variante HTTP y añade `url` a cada comando slash. Se requiere una URL pública:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -286,20 +286,20 @@ Para el modo **URL de solicitud HTTP**, sustituye `settings` por la variante HTT
|
||||
|
||||
Expón distintas funciones que amplían los valores predeterminados anteriores.
|
||||
|
||||
El manifiesto predeterminado habilita la pestaña **Home** de Slack App Home y se suscribe a `app_home_opened`. Cuando un miembro del espacio de trabajo abre la pestaña Home, OpenClaw publica una vista Home predeterminada segura con `views.publish`; no se incluye ninguna carga de conversación ni configuración privada. La pestaña **Messages** permanece habilitada para los MD de Slack.
|
||||
El manifiesto predeterminado habilita la pestaña **Inicio** de Slack App Home y se suscribe a `app_home_opened`. Cuando un miembro del espacio de trabajo abre la pestaña Inicio, OpenClaw publica una vista de Inicio predeterminada y segura con `views.publish`; no se incluye ninguna carga útil de conversación ni configuración privada. La pestaña **Mensajes** permanece habilitada para los DM de Slack.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Optional native slash commands">
|
||||
<Accordion title="Comandos slash nativos opcionales">
|
||||
|
||||
Se pueden usar varios [comandos slash nativos](#commands-and-slash-behavior) en lugar de un único comando configurado, con algunos matices:
|
||||
|
||||
- Usa `/agentstatus` en lugar de `/status` porque el comando `/status` está reservado.
|
||||
- No se pueden poner a disposición más de 25 comandos slash a la vez.
|
||||
|
||||
Sustituye tu sección `features.slash_commands` existente por un subconjunto de [comandos disponibles](/es/tools/slash-commands#command-list):
|
||||
Reemplaza tu sección existente `features.slash_commands` con un subconjunto de los [comandos disponibles](/es/tools/slash-commands#command-list):
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (default)">
|
||||
<Tab title="Socket Mode (predeterminado)">
|
||||
|
||||
```json
|
||||
{
|
||||
@ -422,8 +422,8 @@ El manifiesto predeterminado habilita la pestaña **Home** de Slack App Home y s
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="HTTP Request URLs">
|
||||
Usa la misma lista `slash_commands` que en Socket Mode arriba y añade `"url": "https://gateway-host.example.com/slack/events"` a cada entrada. Ejemplo:
|
||||
<Tab title="URLs de solicitud HTTP">
|
||||
Usa la misma lista `slash_commands` que Socket Mode arriba y añade `"url": "https://gateway-host.example.com/slack/events"` a cada entrada. Ejemplo:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -450,13 +450,13 @@ El manifiesto predeterminado habilita la pestaña **Home** de Slack App Home y s
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ámbitos opcionales de autoría (operaciones de escritura)">
|
||||
Agrega el ámbito de bot `chat:write.customize` si quieres que los mensajes salientes usen la identidad del agente activo (nombre de usuario e icono personalizados) en lugar de la identidad predeterminada de la aplicación de Slack.
|
||||
Agrega el ámbito de bot `chat:write.customize` si quieres que los mensajes salientes usen la identidad del agente activo (nombre de usuario e icono personalizados) en lugar de la identidad predeterminada de la app de Slack.
|
||||
|
||||
Si usas un icono de emoji, Slack espera la sintaxis `:emoji_name:`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ámbitos opcionales de token de usuario (operaciones de lectura)">
|
||||
Si configuras `channels.slack.userToken`, los ámbitos de lectura típicos son:
|
||||
Si configuras `channels.slack.userToken`, los ámbitos de lectura habituales son:
|
||||
|
||||
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
|
||||
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
|
||||
@ -464,7 +464,7 @@ El manifiesto predeterminado habilita la pestaña **Home** de Slack App Home y s
|
||||
- `reactions:read`
|
||||
- `pins:read`
|
||||
- `emoji:read`
|
||||
- `search:read` (si dependes de lecturas de búsqueda de Slack)
|
||||
- `search:read` (si dependes de las lecturas de búsqueda de Slack)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -475,23 +475,23 @@ El manifiesto predeterminado habilita la pestaña **Home** de Slack App Home y s
|
||||
- El modo HTTP requiere `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` y `userToken` aceptan cadenas de texto sin formato
|
||||
u objetos SecretRef.
|
||||
- Los tokens de configuración anulan el fallback de env.
|
||||
- El fallback de env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica solo a la cuenta predeterminada.
|
||||
- `userToken` (`xoxp-...`) solo se configura mediante config (sin fallback de env) y usa de forma predeterminada un comportamiento de solo lectura (`userTokenReadOnly: true`).
|
||||
- Los tokens de configuración anulan la alternativa de env.
|
||||
- La alternativa de env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica solo a la cuenta predeterminada.
|
||||
- `userToken` (`xoxp-...`) solo se configura mediante config (sin alternativa de env) y usa de forma predeterminada comportamiento de solo lectura (`userTokenReadOnly: true`).
|
||||
|
||||
Comportamiento de la instantánea de estado:
|
||||
|
||||
- La inspección de cuentas de Slack rastrea los campos `*Source` y `*Status`
|
||||
- La inspección de cuentas de Slack rastrea campos `*Source` y `*Status`
|
||||
por credencial (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- El estado es `available`, `configured_unavailable` o `missing`.
|
||||
- `configured_unavailable` significa que la cuenta está configurada mediante SecretRef
|
||||
u otra fuente de secreto no inline, pero la ruta actual de comando/runtime
|
||||
u otra fuente secreta no insertada en línea, pero la ruta actual de comando/runtime
|
||||
no pudo resolver el valor real.
|
||||
- En modo HTTP, se incluye `signingSecretStatus`; en Socket Mode, el
|
||||
par requerido es `botTokenStatus` + `appTokenStatus`.
|
||||
|
||||
<Tip>
|
||||
Para acciones/lecturas de directorio, se puede preferir el token de usuario cuando está configurado. Para escrituras, se sigue prefiriendo el token de bot; las escrituras con token de usuario solo se permiten cuando `userTokenReadOnly: false` y el token de bot no está disponible.
|
||||
Para acciones/lecturas de directorio, se puede preferir el token de usuario cuando esté configurado. Para escrituras, se sigue prefiriendo el token de bot; las escrituras con token de usuario solo se permiten cuando `userTokenReadOnly: false` y el token de bot no está disponible.
|
||||
</Tip>
|
||||
|
||||
## Acciones y controles
|
||||
@ -501,32 +501,32 @@ Las acciones de Slack se controlan mediante `channels.slack.actions.*`.
|
||||
Grupos de acciones disponibles en las herramientas actuales de Slack:
|
||||
|
||||
| Grupo | Predeterminado |
|
||||
| ---------- | -------------- |
|
||||
| messages | habilitado |
|
||||
| reactions | habilitado |
|
||||
| pins | habilitado |
|
||||
| memberInfo | habilitado |
|
||||
| emojiList | habilitado |
|
||||
| ---------- | ------- |
|
||||
| messages | habilitado |
|
||||
| reactions | habilitado |
|
||||
| pins | habilitado |
|
||||
| memberInfo | habilitado |
|
||||
| emojiList | habilitado |
|
||||
|
||||
Las acciones actuales de mensajes de Slack incluyen `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` y `emoji-list`. `download-file` acepta IDs de archivo de Slack mostrados en placeholders de archivos entrantes y devuelve vistas previas de imagen para imágenes o metadatos de archivo local para otros tipos de archivo.
|
||||
Las acciones actuales de mensajes de Slack incluyen `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` y `emoji-list`. `download-file` acepta IDs de archivos de Slack mostrados en los marcadores de posición de archivos entrantes y devuelve vistas previas de imagen para imágenes o metadatos de archivos locales para otros tipos de archivo.
|
||||
|
||||
## Control de acceso y enrutamiento
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Política de MD">
|
||||
`channels.slack.dmPolicy` controla el acceso por MD. `channels.slack.allowFrom` es la lista de permitidos canónica para MD.
|
||||
<Tab title="Política de DM">
|
||||
`channels.slack.dmPolicy` controla el acceso a DM. `channels.slack.allowFrom` es la lista de permitidos canónica para DM.
|
||||
|
||||
- `pairing` (predeterminado)
|
||||
- `allowlist`
|
||||
- `open` (requiere que `channels.slack.allowFrom` incluya `"*"`)
|
||||
- `disabled`
|
||||
|
||||
Flags de MD:
|
||||
Flags de DM:
|
||||
|
||||
- `dm.enabled` (predeterminado true)
|
||||
- `dm.enabled` (true de forma predeterminada)
|
||||
- `channels.slack.allowFrom`
|
||||
- `dm.allowFrom` (heredado)
|
||||
- `dm.groupEnabled` (MD grupales predeterminado false)
|
||||
- `dm.groupEnabled` (DM de grupo false de forma predeterminada)
|
||||
- `dm.groupChannels` (lista de permitidos MPIM opcional)
|
||||
|
||||
Precedencia de varias cuentas:
|
||||
@ -535,33 +535,33 @@ Las acciones actuales de mensajes de Slack incluyen `send`, `upload-file`, `down
|
||||
- Las cuentas con nombre heredan `channels.slack.allowFrom` cuando su propio `allowFrom` no está definido.
|
||||
- Las cuentas con nombre no heredan `channels.slack.accounts.default.allowFrom`.
|
||||
|
||||
Los valores heredados `channels.slack.dm.policy` y `channels.slack.dm.allowFrom` aún se leen por compatibilidad. `openclaw doctor --fix` los migra a `dmPolicy` y `allowFrom` cuando puede hacerlo sin cambiar el acceso.
|
||||
`channels.slack.dm.policy` y `channels.slack.dm.allowFrom` heredados se siguen leyendo por compatibilidad. `openclaw doctor --fix` los migra a `dmPolicy` y `allowFrom` cuando puede hacerlo sin cambiar el acceso.
|
||||
|
||||
El emparejamiento en MD usa `openclaw pairing approve slack <code>`.
|
||||
El emparejamiento en DM usa `openclaw pairing approve slack <code>`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Política de canales">
|
||||
`channels.slack.groupPolicy` controla la gestión de canales:
|
||||
`channels.slack.groupPolicy` controla el manejo de canales:
|
||||
|
||||
- `open`
|
||||
- `allowlist`
|
||||
- `disabled`
|
||||
|
||||
La lista de permitidos de canales vive en `channels.slack.channels` y **debe usar IDs estables de canal de Slack** (por ejemplo `C12345678`) como claves de configuración.
|
||||
La lista de permitidos de canales vive bajo `channels.slack.channels` y **debe usar IDs estables de canales de Slack** (por ejemplo, `C12345678`) como claves de configuración.
|
||||
|
||||
Nota de runtime: si falta completamente `channels.slack` (configuración solo con env), el runtime hace fallback a `groupPolicy="allowlist"` y registra una advertencia (incluso si `channels.defaults.groupPolicy` está definido).
|
||||
Nota de runtime: si falta por completo `channels.slack` (configuración solo con env), runtime recurre a `groupPolicy="allowlist"` y registra una advertencia (incluso si `channels.defaults.groupPolicy` está definido).
|
||||
|
||||
Resolución de nombre/ID:
|
||||
|
||||
- las entradas de la lista de permitidos de canales y de la lista de permitidos de MD se resuelven al inicio cuando el acceso por token lo permite
|
||||
- las entradas de nombre de canal sin resolver se conservan como están configuradas, pero se ignoran para el enrutamiento de forma predeterminada
|
||||
- la autorización entrante y el enrutamiento de canales priorizan el ID de forma predeterminada; la coincidencia directa por nombre de usuario/slug requiere `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- las entradas de lista de permitidos de canales y de lista de permitidos de DM se resuelven al inicio cuando el acceso al token lo permite
|
||||
- las entradas de nombres de canal sin resolver se conservan tal como están configuradas, pero se ignoran para el enrutamiento de forma predeterminada
|
||||
- la autorización entrante y el enrutamiento de canales priorizan el ID de forma predeterminada; la coincidencia directa de nombre de usuario/slug requiere `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
<Warning>
|
||||
Las claves basadas en nombre (`#channel-name` o `channel-name`) **no** coinciden bajo `groupPolicy: "allowlist"`. La búsqueda de canal prioriza el ID de forma predeterminada, por lo que una clave basada en nombre nunca se enrutará correctamente y todos los mensajes en ese canal se bloquearán silenciosamente. Esto difiere de `groupPolicy: "open"`, donde la clave de canal no es necesaria para el enrutamiento y una clave basada en nombre parece funcionar.
|
||||
Las claves basadas en nombre (`#channel-name` o `channel-name`) **no** coinciden bajo `groupPolicy: "allowlist"`. La búsqueda del canal prioriza el ID de forma predeterminada, por lo que una clave basada en nombre nunca se enrutará correctamente y todos los mensajes en ese canal se bloquearán silenciosamente. Esto difiere de `groupPolicy: "open"`, donde la clave de canal no es necesaria para el enrutamiento y una clave basada en nombre parece funcionar.
|
||||
|
||||
Usa siempre el ID de canal de Slack como clave. Para encontrarlo: haz clic derecho en el canal en Slack → **Copiar enlace** — el ID (`C...`) aparece al final de la URL.
|
||||
Usa siempre el ID del canal de Slack como clave. Para encontrarlo: haz clic derecho en el canal en Slack → **Copiar enlace** — el ID (`C...`) aparece al final de la URL.
|
||||
|
||||
Correcto:
|
||||
|
||||
@ -596,17 +596,17 @@ Las acciones actuales de mensajes de Slack incluyen `send`, `upload-file`, `down
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Menciones y usuarios de canal">
|
||||
Los mensajes de canal requieren mención de forma predeterminada.
|
||||
<Tab title="Mentions and channel users">
|
||||
Los mensajes de canal requieren una mención de forma predeterminada.
|
||||
|
||||
Fuentes de mención:
|
||||
|
||||
- mención explícita de la aplicación (`<@botId>`)
|
||||
- mención de grupo de usuarios de Slack (`<!subteam^S...>`) cuando el usuario bot es miembro de ese grupo de usuarios; requiere `usergroups:read`
|
||||
- patrones regex de mención (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
|
||||
- comportamiento implícito de hilo de respuesta al bot (deshabilitado cuando `thread.requireExplicitMention` es `true`)
|
||||
- patrones regex de mención (`agents.list[].groupChat.mentionPatterns`, alternativa `messages.groupChat.mentionPatterns`)
|
||||
- comportamiento implícito de respuesta a un hilo del bot (deshabilitado cuando `thread.requireExplicitMention` es `true`)
|
||||
|
||||
Controles por canal (`channels.slack.channels.<id>`; nombres solo mediante resolución de inicio o `dangerouslyAllowNameMatching`):
|
||||
Controles por canal (`channels.slack.channels.<id>`; nombres solo mediante resolución al inicio o `dangerouslyAllowNameMatching`):
|
||||
|
||||
- `requireMention`
|
||||
- `users` (lista de permitidos)
|
||||
@ -614,38 +614,38 @@ Las acciones actuales de mensajes de Slack incluyen `send`, `upload-file`, `down
|
||||
- `skills`
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- formato de clave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:` o comodín `"*"`
|
||||
(las claves heredadas sin prefijo aún se asignan solo a `id:`)
|
||||
- formato de clave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, o comodín `"*"`
|
||||
(las claves heredadas sin prefijo siguen asignándose solo a `id:`)
|
||||
|
||||
`allowBots` es conservador para canales y canales privados: los mensajes de sala escritos por bots se aceptan solo cuando el bot remitente está listado explícitamente en la lista de permitidos `users` de esa sala, o cuando al menos un ID explícito de propietario de Slack de `channels.slack.allowFrom` es actualmente miembro de la sala. Los comodines y las entradas de propietario por nombre visible no satisfacen la presencia de propietario. La presencia de propietario usa Slack `conversations.members`; asegúrate de que la aplicación tenga el ámbito de lectura correspondiente para el tipo de sala (`channels:read` para canales públicos, `groups:read` para canales privados). Si falla la búsqueda de miembros, OpenClaw descarta el mensaje de sala escrito por bot.
|
||||
`allowBots` es conservador para canales y canales privados: los mensajes de sala escritos por bots solo se aceptan cuando el bot emisor está incluido explícitamente en la lista de permitidos `users` de esa sala, o cuando al menos un ID de propietario explícito de Slack de `channels.slack.allowFrom` es actualmente miembro de la sala. Los comodines y las entradas de propietario por nombre visible no satisfacen la presencia del propietario. La presencia del propietario usa `conversations.members` de Slack; asegúrate de que la aplicación tenga el alcance de lectura correspondiente para el tipo de sala (`channels:read` para canales públicos, `groups:read` para canales privados). Si falla la búsqueda de miembros, OpenClaw descarta el mensaje de sala escrito por el bot.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Hilos, sesiones y etiquetas de respuesta
|
||||
|
||||
- Los MD se enrutan como `direct`; los canales como `channel`; los MPIM como `group`.
|
||||
- Los enlaces de ruta de Slack aceptan IDs de pares sin procesar y formas de destino de Slack como `channel:C12345678`, `user:U12345678` y `<@U12345678>`.
|
||||
- Con el valor predeterminado `session.dmScope=main`, los MD de Slack se colapsan a la sesión principal del agente.
|
||||
- Los DM se enrutan como `direct`; los canales como `channel`; los MPIM como `group`.
|
||||
- Las vinculaciones de rutas de Slack aceptan IDs de pares sin procesar además de formas de destino de Slack como `channel:C12345678`, `user:U12345678` y `<@U12345678>`.
|
||||
- Con `session.dmScope=main` predeterminado, los DM de Slack se agrupan en la sesión principal del agente.
|
||||
- Sesiones de canal: `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- Las respuestas en hilo pueden crear sufijos de sesión de hilo (`:thread:<threadTs>`) cuando corresponda.
|
||||
- Las respuestas de hilo pueden crear sufijos de sesión de hilo (`:thread:<threadTs>`) cuando corresponda.
|
||||
- El valor predeterminado de `channels.slack.thread.historyScope` es `thread`; el valor predeterminado de `thread.inheritParent` es `false`.
|
||||
- `channels.slack.thread.initialHistoryLimit` controla cuántos mensajes de hilo existentes se recuperan cuando comienza una nueva sesión de hilo (predeterminado `20`; establece `0` para deshabilitar).
|
||||
- `channels.slack.thread.requireExplicitMention` (predeterminado `false`): cuando es `true`, suprime las menciones implícitas en hilos para que el bot solo responda a menciones explícitas `@bot` dentro de hilos, incluso cuando el bot ya participó en el hilo. Sin esto, las respuestas en un hilo donde participó el bot omiten el control `requireMention`.
|
||||
- `channels.slack.thread.initialHistoryLimit` controla cuántos mensajes existentes del hilo se recuperan cuando inicia una nueva sesión de hilo (predeterminado `20`; establece `0` para deshabilitarlo).
|
||||
- `channels.slack.thread.requireExplicitMention` (predeterminado `false`): cuando es `true`, suprime las menciones implícitas de hilo para que el bot solo responda a menciones explícitas `@bot` dentro de hilos, incluso cuando el bot ya participó en el hilo. Sin esto, las respuestas en un hilo en el que participó el bot omiten la protección de `requireMention`.
|
||||
|
||||
Controles de hilos de respuesta:
|
||||
|
||||
- `channels.slack.replyToMode`: `off|first|all|batched` (predeterminado `off`)
|
||||
- `channels.slack.replyToModeByChatType`: por `direct|group|channel`
|
||||
- fallback heredado para chats directos: `channels.slack.dm.replyToMode`
|
||||
- alternativa heredada para chats directos: `channels.slack.dm.replyToMode`
|
||||
|
||||
Se admiten etiquetas manuales de respuesta:
|
||||
Se admiten etiquetas de respuesta manuales:
|
||||
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
<Note>
|
||||
`replyToMode="off"` deshabilita **todos** los hilos de respuesta en Slack, incluidas las etiquetas explícitas `[[reply_to_*]]`. Esto difiere de Telegram, donde las etiquetas explícitas aún se respetan en modo `"off"`. Los hilos de Slack ocultan los mensajes del canal, mientras que las respuestas de Telegram siguen visibles inline.
|
||||
`replyToMode="off"` deshabilita **todos** los hilos de respuesta en Slack, incluidas las etiquetas explícitas `[[reply_to_*]]`. Esto difiere de Telegram, donde las etiquetas explícitas siguen respetándose en modo `"off"`. Los hilos de Slack ocultan mensajes del canal, mientras que las respuestas de Telegram permanecen visibles en línea.
|
||||
</Note>
|
||||
|
||||
## Reacciones de confirmación
|
||||
@ -657,7 +657,7 @@ Orden de resolución:
|
||||
- `channels.slack.accounts.<accountId>.ackReaction`
|
||||
- `channels.slack.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback de emoji de identidad del agente (`agents.list[].identity.emoji`, si no "👀")
|
||||
- alternativa de emoji de identidad del agente (`agents.list[].identity.emoji`, si no "👀")
|
||||
|
||||
Notas:
|
||||
|
||||
@ -670,18 +670,37 @@ Notas:
|
||||
|
||||
- `off`: deshabilita el streaming de vista previa en vivo.
|
||||
- `partial` (predeterminado): reemplaza el texto de vista previa con la salida parcial más reciente.
|
||||
- `block`: agrega actualizaciones de vista previa en fragmentos.
|
||||
- `block`: agrega actualizaciones de vista previa por fragmentos.
|
||||
- `progress`: muestra texto de estado de progreso mientras se genera y luego envía el texto final.
|
||||
- `streaming.preview.toolProgress`: cuando la vista previa de borrador está activa, enruta las actualizaciones de herramienta/progreso al mismo mensaje de vista previa editado (predeterminado: `true`). Establece `false` para mantener mensajes de herramienta/progreso separados.
|
||||
- `streaming.preview.toolProgress`: cuando la vista previa de borrador está activa, enruta las actualizaciones de herramientas/progreso al mismo mensaje de vista previa editado (predeterminado: `true`). Establece `false` para conservar mensajes de herramientas/progreso separados.
|
||||
- `streaming.preview.commandText` / `streaming.progress.commandText`: establece en `status` para conservar líneas compactas de progreso de herramientas mientras se oculta el texto sin procesar de comandos/ejecución (predeterminado: `raw`).
|
||||
|
||||
Oculta el texto sin procesar de comandos/ejecución mientras conservas líneas compactas de progreso:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"slack": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`channels.slack.streaming.nativeTransport` controla el streaming de texto nativo de Slack cuando `channels.slack.streaming.mode` es `partial` (predeterminado: `true`).
|
||||
|
||||
- Debe haber un hilo de respuesta disponible para que aparezcan el streaming de texto nativo y el estado de hilo de asistente de Slack. La selección de hilo sigue respetando `replyToMode`.
|
||||
- Los canales, chats grupales y raíces de MD de nivel superior aún pueden usar la vista previa de borrador normal cuando el streaming nativo no está disponible o no existe ningún hilo de respuesta.
|
||||
- Los MD de Slack de nivel superior permanecen fuera de hilo de forma predeterminada, por lo que no muestran la vista previa de streaming/estado nativo con estilo de hilo de Slack; OpenClaw publica y edita una vista previa de borrador en el MD en su lugar.
|
||||
- Los payloads multimedia y que no son de texto hacen fallback a la entrega normal.
|
||||
- Los finales multimedia/de error cancelan las ediciones de vista previa pendientes; los finales de texto/bloque elegibles solo se vacían cuando pueden editar la vista previa in situ.
|
||||
- Si el streaming falla a mitad de respuesta, OpenClaw hace fallback a la entrega normal para los payloads restantes.
|
||||
- Los canales, chats grupales y raíces de DM de nivel superior aún pueden usar la vista previa de borrador normal cuando el streaming nativo no está disponible o no existe un hilo de respuesta.
|
||||
- Los DM de Slack de nivel superior permanecen fuera de hilo de forma predeterminada, por lo que no muestran la vista previa de streaming/estado nativa de estilo hilo de Slack; OpenClaw publica y edita una vista previa de borrador en el DM en su lugar.
|
||||
- Los medios y las cargas que no son texto vuelven a la entrega normal.
|
||||
- Los finales de medios/error cancelan las ediciones de vista previa pendientes; los finales de texto/bloque aptos solo se vacían cuando pueden editar la vista previa en el lugar.
|
||||
- Si el streaming falla a mitad de la respuesta, OpenClaw vuelve a la entrega normal para las cargas restantes.
|
||||
|
||||
Usa la vista previa de borrador en lugar del streaming de texto nativo de Slack:
|
||||
|
||||
@ -701,12 +720,12 @@ Usa la vista previa de borrador en lugar del streaming de texto nativo de Slack:
|
||||
Claves heredadas:
|
||||
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) se migra automáticamente a `channels.slack.streaming.mode`.
|
||||
- el valor booleano `channels.slack.streaming` se migra automáticamente a `channels.slack.streaming.mode` y `channels.slack.streaming.nativeTransport`.
|
||||
- el booleano `channels.slack.streaming` se migra automáticamente a `channels.slack.streaming.mode` y `channels.slack.streaming.nativeTransport`.
|
||||
- `channels.slack.nativeStreaming` heredado se migra automáticamente a `channels.slack.streaming.nativeTransport`.
|
||||
|
||||
## Fallback de reacción de escritura
|
||||
## Alternativa de reacción de escritura
|
||||
|
||||
`typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras OpenClaw procesa una respuesta y luego la elimina cuando la ejecución termina. Esto es más útil fuera de respuestas en hilo, que usan un indicador de estado predeterminado "está escribiendo...".
|
||||
`typingReaction` agrega una reacción temporal al mensaje entrante de Slack mientras OpenClaw procesa una respuesta y luego la elimina cuando finaliza la ejecución. Esto resulta más útil fuera de las respuestas en hilos, que usan un indicador de estado predeterminado "is typing...".
|
||||
|
||||
Orden de resolución:
|
||||
|
||||
@ -715,43 +734,43 @@ Orden de resolución:
|
||||
|
||||
Notas:
|
||||
|
||||
- Slack espera códigos cortos (por ejemplo `"hourglass_flowing_sand"`).
|
||||
- La reacción es de mejor esfuerzo y la limpieza se intenta automáticamente después de que se completa la respuesta o la ruta de fallo.
|
||||
- Slack espera shortcodes (por ejemplo `"hourglass_flowing_sand"`).
|
||||
- La reacción es de mejor esfuerzo y la limpieza se intenta automáticamente después de que se completa la respuesta o la ruta de error.
|
||||
|
||||
## Medios, fragmentación y entrega
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Inbound attachments">
|
||||
Los archivos adjuntos de Slack se descargan desde URL privadas alojadas por Slack (flujo de solicitud autenticada con token) y se escriben en el almacén de medios cuando la recuperación se realiza correctamente y los límites de tamaño lo permiten. Los marcadores de posición de archivo incluyen el `fileId` de Slack para que los agentes puedan recuperar el archivo original con `download-file`.
|
||||
<Accordion title="Adjuntos entrantes">
|
||||
Los adjuntos de archivos de Slack se descargan desde URL privadas alojadas en Slack (flujo de solicitud autenticada con token) y se escriben en el almacén de medios cuando la obtención se realiza correctamente y los límites de tamaño lo permiten. Los marcadores de posición de archivo incluyen el `fileId` de Slack para que los agentes puedan obtener el archivo original con `download-file`.
|
||||
|
||||
Las descargas usan tiempos de espera acotados de inactividad y total. Si la recuperación de archivos de Slack se detiene o falla, OpenClaw continúa procesando el mensaje y recurre al marcador de posición del archivo.
|
||||
Las descargas usan tiempos de espera acotados de inactividad y totales. Si la recuperación de archivos de Slack se detiene o falla, OpenClaw sigue procesando el mensaje y recurre al marcador de posición del archivo.
|
||||
|
||||
El límite de tamaño entrante en tiempo de ejecución es `20MB` de forma predeterminada, salvo que `channels.slack.mediaMaxMb` lo sobrescriba.
|
||||
El límite de tamaño entrante en tiempo de ejecución tiene un valor predeterminado de `20MB` salvo que `channels.slack.mediaMaxMb` lo sobrescriba.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Outbound text and files">
|
||||
<Accordion title="Texto y archivos salientes">
|
||||
- los fragmentos de texto usan `channels.slack.textChunkLimit` (valor predeterminado 4000)
|
||||
- `channels.slack.chunkMode="newline"` habilita la división con prioridad por párrafos
|
||||
- `channels.slack.chunkMode="newline"` habilita la división priorizando párrafos
|
||||
- los envíos de archivos usan las API de carga de Slack y pueden incluir respuestas en hilos (`thread_ts`)
|
||||
- el límite de medios salientes sigue `channels.slack.mediaMaxMb` cuando está configurado; de lo contrario, los envíos del canal usan los valores predeterminados por tipo MIME de la canalización de medios
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Delivery targets">
|
||||
<Accordion title="Destinos de entrega">
|
||||
Destinos explícitos preferidos:
|
||||
|
||||
- `user:<id>` para mensajes directos
|
||||
- `user:<id>` para DM
|
||||
- `channel:<id>` para canales
|
||||
|
||||
Los mensajes directos de Slack solo de texto/bloques pueden publicarse directamente en ID de usuario; las cargas de archivos y los envíos en hilos abren primero el mensaje directo mediante las API de conversaciones de Slack porque esas rutas requieren un ID de conversación concreto.
|
||||
Los DM de Slack solo de texto/bloques pueden publicarse directamente en ID de usuario; las cargas de archivos y los envíos en hilos abren primero el DM mediante las API de conversaciones de Slack porque esas rutas requieren un ID de conversación concreto.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Comandos y comportamiento de barra diagonal
|
||||
## Comandos y comportamiento slash
|
||||
|
||||
Los comandos de barra diagonal aparecen en Slack como un único comando configurado o como varios comandos nativos. Configura `channels.slack.slashCommand` para cambiar los valores predeterminados de los comandos:
|
||||
Los comandos slash aparecen en Slack como un único comando configurado o como varios comandos nativos. Configura `channels.slack.slashCommand` para cambiar los valores predeterminados de comandos:
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -762,7 +781,7 @@ Los comandos de barra diagonal aparecen en Slack como un único comando configur
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
Los comandos nativos requieren [configuración adicional del manifiesto](#additional-manifest-settings) en tu aplicación de Slack y se habilitan con `channels.slack.commands.native: true` o, en su lugar, `commands.native: true` en configuraciones globales.
|
||||
Los comandos nativos requieren [configuraciones adicionales del manifiesto](#additional-manifest-settings) en tu aplicación de Slack y se habilitan con `channels.slack.commands.native: true` o `commands.native: true` en configuraciones globales.
|
||||
|
||||
- El modo automático de comandos nativos está **desactivado** para Slack, por lo que `commands.native: "auto"` no habilita los comandos nativos de Slack.
|
||||
|
||||
@ -770,18 +789,18 @@ Los comandos nativos requieren [configuración adicional del manifiesto](#additi
|
||||
/help
|
||||
```
|
||||
|
||||
Los menús de argumentos nativos usan una estrategia de renderizado adaptativo que muestra un modal de confirmación antes de despachar un valor de opción seleccionado:
|
||||
Los menús de argumentos nativos usan una estrategia de renderización adaptativa que muestra un modal de confirmación antes de despachar el valor de una opción seleccionada:
|
||||
|
||||
- hasta 5 opciones: bloques de botones
|
||||
- 6-100 opciones: menú de selección estático
|
||||
- más de 100 opciones: selección externa con filtrado asincrónico de opciones cuando hay controladores de opciones de interactividad disponibles
|
||||
- límites de Slack excedidos: los valores de opción codificados recurren a botones
|
||||
- 6-100 opciones: menú de selección estática
|
||||
- más de 100 opciones: selección externa con filtrado asíncrono de opciones cuando los controladores de opciones de interactividad están disponibles
|
||||
- límites de Slack superados: los valores de opciones codificados vuelven a botones
|
||||
|
||||
```txt
|
||||
/think
|
||||
```
|
||||
|
||||
Las sesiones de barra diagonal usan claves aisladas como `agent:<agentId>:slack:slash:<userId>` y aun así enrutan las ejecuciones de comandos a la sesión de conversación de destino mediante `CommandTargetSessionKey`.
|
||||
Las sesiones slash usan claves aisladas como `agent:<agentId>:slack:slash:<userId>` y aun así enrutan las ejecuciones de comandos a la sesión de conversación de destino mediante `CommandTargetSessionKey`.
|
||||
|
||||
## Respuestas interactivas
|
||||
|
||||
@ -824,26 +843,26 @@ Cuando está habilitada, los agentes pueden emitir directivas de respuesta solo
|
||||
- `[[slack_buttons: Approve:approve, Reject:reject]]`
|
||||
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
|
||||
|
||||
Estas directivas se compilan en Slack Block Kit y enrutan clics o selecciones de vuelta a través de la ruta de eventos de interacción de Slack existente.
|
||||
Estas directivas se compilan en Slack Block Kit y enrutan clics o selecciones de vuelta por la ruta existente de eventos de interacción de Slack.
|
||||
|
||||
Notas:
|
||||
|
||||
- Esta interfaz de usuario es específica de Slack. Otros canales no traducen las directivas de Slack Block Kit a sus propios sistemas de botones.
|
||||
- Los valores de callback interactivos son tokens opacos generados por OpenClaw, no valores sin procesar creados por el agente.
|
||||
- Si los bloques interactivos generados excedieran los límites de Slack Block Kit, OpenClaw recurre a la respuesta de texto original en lugar de enviar una carga de bloques no válida.
|
||||
- Esta es una interfaz de usuario específica de Slack. Otros canales no traducen las directivas de Slack Block Kit a sus propios sistemas de botones.
|
||||
- Los valores de callback interactivo son tokens opacos generados por OpenClaw, no valores sin procesar creados por el agente.
|
||||
- Si los bloques interactivos generados superaran los límites de Slack Block Kit, OpenClaw recurre a la respuesta de texto original en lugar de enviar una carga útil de bloques no válida.
|
||||
|
||||
## Aprobaciones de exec en Slack
|
||||
|
||||
Slack puede actuar como cliente de aprobación nativo con botones e interacciones, en lugar de recurrir a la interfaz web o a la terminal.
|
||||
Slack puede actuar como cliente de aprobación nativo con botones e interacciones, en lugar de recurrir a la interfaz web o al terminal.
|
||||
|
||||
- Las aprobaciones de exec usan `channels.slack.execApprovals.*` para el enrutamiento nativo de mensajes directos/canales.
|
||||
- Las aprobaciones de Plugin aún pueden resolverse a través de la misma superficie de botones nativa de Slack cuando la solicitud ya llega a Slack y el tipo de id de aprobación es `plugin:`.
|
||||
- La autorización de aprobadores sigue aplicándose: solo los usuarios identificados como aprobadores pueden aprobar o denegar solicitudes a través de Slack.
|
||||
- Las aprobaciones de exec usan `channels.slack.execApprovals.*` para enrutamiento nativo por DM/canal.
|
||||
- Las aprobaciones de Plugin aún pueden resolverse mediante la misma superficie de botones nativa de Slack cuando la solicitud ya llega a Slack y el tipo de ID de aprobación es `plugin:`.
|
||||
- La autorización de aprobadores sigue aplicándose: solo los usuarios identificados como aprobadores pueden aprobar o denegar solicitudes mediante Slack.
|
||||
|
||||
Esto usa la misma superficie compartida de botones de aprobación que otros canales. Cuando `interactivity` está habilitado en la configuración de tu aplicación de Slack, las solicitudes de aprobación se renderizan como botones de Block Kit directamente en la conversación.
|
||||
Cuando esos botones están presentes, son la experiencia principal de aprobación; OpenClaw
|
||||
solo debe 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 ruta.
|
||||
Cuando esos botones están presentes, son la UX 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 ruta.
|
||||
|
||||
Ruta de configuración:
|
||||
|
||||
@ -852,9 +871,9 @@ Ruta de configuración:
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, valor predeterminado: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Slack habilita automáticamente las aprobaciones de exec nativas cuando `enabled` no está definido o es `"auto"` y se resuelve al menos un
|
||||
aprobador. Define `enabled: false` para deshabilitar explícitamente Slack como cliente de aprobación nativo.
|
||||
Define `enabled: true` para forzar las aprobaciones nativas cuando se resuelven aprobadores.
|
||||
Slack habilita automáticamente las aprobaciones nativas de exec cuando `enabled` no está definido o es `"auto"` y se resuelve al menos un
|
||||
aprobador. Configura `enabled: false` para deshabilitar explícitamente Slack como cliente de aprobación nativo.
|
||||
Configura `enabled: true` para forzar las aprobaciones nativas cuando se resuelvan aprobadores.
|
||||
|
||||
Comportamiento predeterminado sin configuración explícita de aprobación de exec de Slack:
|
||||
|
||||
@ -866,7 +885,7 @@ Comportamiento predeterminado sin configuración explícita de aprobación de ex
|
||||
}
|
||||
```
|
||||
|
||||
La configuración explícita nativa de Slack solo es necesaria cuando quieres sobrescribir aprobadores, agregar filtros u
|
||||
La configuración nativa de Slack explícita solo es necesaria cuando quieres sobrescribir aprobadores, agregar filtros u
|
||||
optar por la entrega en el chat de origen:
|
||||
|
||||
```json5
|
||||
@ -883,35 +902,35 @@ optar por la entrega en el chat de origen:
|
||||
}
|
||||
```
|
||||
|
||||
El reenvío compartido `approvals.exec` es independiente. Úsalo solo cuando las solicitudes de aprobación de exec también deban
|
||||
enrutarse a otros chats o destinos explícitos fuera de banda. El reenvío compartido `approvals.plugin` también es
|
||||
El reenvío compartido de `approvals.exec` es independiente. Úsalo solo cuando las solicitudes de aprobación de exec también deban
|
||||
enrutarse a otros chats o a destinos explícitos fuera de banda. El reenvío compartido de `approvals.plugin` también es
|
||||
independiente; los botones nativos de Slack aún pueden resolver aprobaciones de Plugin cuando esas solicitudes ya llegan
|
||||
a Slack.
|
||||
|
||||
`/approve` en el mismo chat también funciona en canales y mensajes directos de Slack que ya admiten comandos. Consulta [Aprobaciones de exec](/es/tools/exec-approvals) para ver el modelo completo de reenvío de aprobaciones.
|
||||
`/approve` en el mismo chat también funciona en canales de Slack y DM que ya admiten comandos. Consulta [Aprobaciones de exec](/es/tools/exec-approvals) para ver el modelo completo de reenvío de aprobaciones.
|
||||
|
||||
## Eventos y comportamiento operativo
|
||||
|
||||
- Las ediciones/eliminaciones de mensajes se asignan a eventos del sistema.
|
||||
- Las difusiones de hilos (respuestas de hilo con "Also send to channel") se procesan como mensajes normales de usuario.
|
||||
- Las difusiones de hilos (respuestas en hilos con "Also send to channel") se procesan como mensajes normales de usuario.
|
||||
- Los eventos de agregar/eliminar reacciones se asignan a eventos del sistema.
|
||||
- Los eventos de entrada/salida de miembros, canal creado/renombrado y agregar/eliminar fijación se asignan a eventos del sistema.
|
||||
- `channel_id_changed` puede migrar claves de configuración de canal cuando `configWrites` está habilitado.
|
||||
- Los eventos de unión/salida de miembros, canal creado/renombrado y agregar/eliminar pin se asignan a eventos del sistema.
|
||||
- `channel_id_changed` puede migrar claves de configuración de canales cuando `configWrites` está habilitado.
|
||||
- Los metadatos de tema/propósito del canal se tratan como contexto no confiable y pueden inyectarse en el contexto de enrutamiento.
|
||||
- El iniciador del hilo y la inicialización del contexto del historial inicial del hilo se filtran por listas de remitentes permitidos configuradas cuando corresponde.
|
||||
- Las acciones de bloque y las interacciones modales emiten eventos del sistema estructurados `Slack interaction: ...` con campos de carga enriquecidos:
|
||||
- acciones de bloque: valores seleccionados, etiquetas, valores de selector y metadatos `workflow_*`
|
||||
- El iniciador del hilo y la siembra del contexto de historial inicial del hilo se filtran por las listas de remitentes permitidos configuradas cuando corresponde.
|
||||
- Las acciones de bloque y las interacciones modales emiten eventos del sistema estructurados `Slack interaction: ...` con campos de carga útil enriquecidos:
|
||||
- acciones de bloque: valores seleccionados, etiquetas, valores de selectores y metadatos `workflow_*`
|
||||
- eventos modales `view_submission` y `view_closed` con metadatos de canal enrutados y entradas de formulario
|
||||
|
||||
## Referencia de configuración
|
||||
|
||||
Referencia principal: [Referencia de configuración - Slack](/es/gateway/config-channels#slack).
|
||||
|
||||
<Accordion title="High-signal Slack fields">
|
||||
<Accordion title="Campos de Slack de alta señal">
|
||||
|
||||
- modo/autenticación: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- acceso a mensajes directos: `dm.enabled`, `dmPolicy`, `allowFrom` (heredado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- conmutador de compatibilidad: `dangerouslyAllowNameMatching` (emergencia; mantenlo desactivado salvo que sea necesario)
|
||||
- acceso a DM: `dm.enabled`, `dmPolicy`, `allowFrom` (heredado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- alternador de compatibilidad: `dangerouslyAllowNameMatching` (break-glass; mantener desactivado salvo que sea necesario)
|
||||
- acceso a canales: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- hilos/historial: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
@ -922,11 +941,11 @@ Referencia principal: [Referencia de configuración - Slack](/es/gateway/config-
|
||||
## Solución de problemas
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="No replies in channels">
|
||||
<Accordion title="No hay respuestas en canales">
|
||||
Comprueba, en orden:
|
||||
|
||||
- `groupPolicy`
|
||||
- lista de canales permitidos (`channels.slack.channels`) — **las claves deben ser ID de canal** (`C12345678`), no nombres (`#channel-name`). Las claves basadas en nombres fallan silenciosamente con `groupPolicy: "allowlist"` porque el enrutamiento de canales usa ID primero de forma predeterminada. Para encontrar un ID: haz clic derecho en el canal en Slack → **Copy link** — el valor `C...` al final de la URL es el ID del canal.
|
||||
- lista de canales permitidos (`channels.slack.channels`) — **las claves deben ser ID de canal** (`C12345678`), no nombres (`#channel-name`). Las claves basadas en nombres fallan silenciosamente con `groupPolicy: "allowlist"` porque el enrutamiento de canales prioriza los ID de forma predeterminada. Para encontrar un ID: haz clic derecho en el canal en Slack → **Copy link** — el valor `C...` al final de la URL es el ID del canal.
|
||||
- `requireMention`
|
||||
- lista de `users` permitidos por canal
|
||||
|
||||
@ -940,14 +959,14 @@ openclaw doctor
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="DM messages ignored">
|
||||
<Accordion title="Mensajes de DM ignorados">
|
||||
Comprueba:
|
||||
|
||||
- `channels.slack.dm.enabled`
|
||||
- `channels.slack.dmPolicy` (o el heredado `channels.slack.dm.policy`)
|
||||
- aprobaciones de emparejamiento / entradas de lista permitida
|
||||
- eventos de mensajes directos de Slack Assistant: los registros detallados que mencionan `drop message_changed`
|
||||
normalmente significan que Slack envió un evento editado de hilo de Assistant sin un
|
||||
- aprobaciones de emparejamiento / entradas de lista de permitidos
|
||||
- eventos de DM de Slack Assistant: los logs detallados que mencionan `drop message_changed`
|
||||
normalmente significan que Slack envió un evento de hilo de Assistant editado sin un
|
||||
remitente humano recuperable en los metadatos del mensaje
|
||||
|
||||
```bash
|
||||
@ -956,53 +975,54 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Socket mode not connecting">
|
||||
Valida los tokens de bot y aplicación y la habilitación de Socket Mode en la configuración de la aplicación de Slack.
|
||||
<Accordion title="Socket Mode no se conecta">
|
||||
Valida los tokens de bot y aplicación, y la habilitación de Socket Mode en la configuración de la aplicación de Slack.
|
||||
|
||||
Si `openclaw channels status --probe --json` muestra `botTokenStatus` o
|
||||
`appTokenStatus: "configured_unavailable"`, la cuenta de Slack está
|
||||
configurada, pero el tiempo de ejecución actual no pudo resolver el valor respaldado por SecretRef.
|
||||
configurada, pero el tiempo de ejecución actual no pudo resolver el valor
|
||||
respaldado por SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="HTTP mode not receiving events">
|
||||
<Accordion title="El modo HTTP no recibe eventos">
|
||||
Valida:
|
||||
|
||||
- secreto de firma
|
||||
- ruta del Webhook
|
||||
- URL de solicitud de Slack (Eventos + Interactividad + Comandos de barra diagonal)
|
||||
- ruta de Webhook
|
||||
- URL de solicitud de Slack (Events + Interactivity + Slash Commands)
|
||||
- `webhookPath` único por cuenta HTTP
|
||||
|
||||
Si `signingSecretStatus: "configured_unavailable"` aparece en las instantáneas
|
||||
Si `signingSecretStatus: "configured_unavailable"` aparece en instantáneas
|
||||
de cuenta, la cuenta HTTP está configurada, pero el tiempo de ejecución actual no pudo
|
||||
resolver el secreto de firma respaldado por SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Native/slash commands not firing">
|
||||
<Accordion title="Los comandos nativos/slash no se activan">
|
||||
Verifica qué pretendías usar:
|
||||
|
||||
- modo de comando nativo (`channels.slack.commands.native: true`) con comandos de barra diagonal coincidentes registrados en Slack
|
||||
- o modo de comando de barra diagonal único (`channels.slack.slashCommand.enabled: true`)
|
||||
- modo de comando nativo (`channels.slack.commands.native: true`) con comandos slash correspondientes registrados en Slack
|
||||
- o modo de comando slash único (`channels.slack.slashCommand.enabled: true`)
|
||||
|
||||
Comprueba también `commands.useAccessGroups` y las listas de canales/usuarios permitidos.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Referencia de visión de adjuntos
|
||||
## Referencia de visión para adjuntos
|
||||
|
||||
Slack puede adjuntar medios descargados al turno del agente cuando las descargas de archivos de Slack se realizan correctamente y los límites de tamaño lo permiten. Los archivos de imagen pueden pasarse por la ruta de comprensión de medios o directamente a un modelo de respuesta con capacidad de visión; otros archivos se conservan como contexto de archivo descargable en lugar de tratarse como entrada de imagen.
|
||||
Slack puede adjuntar medios descargados al turno del agente cuando las descargas de archivos de Slack se realizan correctamente y los límites de tamaño lo permiten. Los archivos de imagen pueden pasarse por la ruta de comprensión de medios o directamente a un modelo de respuesta compatible con visión; otros archivos se conservan como contexto de archivo descargable en lugar de tratarse como entrada de imagen.
|
||||
|
||||
### Tipos de medios admitidos
|
||||
### Tipos de medios compatibles
|
||||
|
||||
| Tipo de medio | Origen | Comportamiento actual | Notas |
|
||||
| ----------------------------- | ------------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| Imágenes JPEG / PNG / GIF / WebP | URL de archivo de Slack | Se descargan y se adjuntan al turno para manejo compatible con visión | Límite por archivo: `channels.slack.mediaMaxMb` (predeterminado 20 MB) |
|
||||
| Archivos PDF | URL de archivo de Slack | Se descargan y se exponen como contexto de archivo para herramientas como `download-file` o `pdf` | La entrada de Slack no convierte PDFs automáticamente en entrada de visión por imagen |
|
||||
| Otros archivos | URL de archivo de Slack | Se descargan cuando es posible y se exponen como contexto de archivo | Los archivos binarios no se tratan como entrada de imagen |
|
||||
| Respuestas de hilo | Archivos del mensaje inicial del hilo | Los archivos del mensaje raíz pueden hidratarse como contexto cuando la respuesta no tiene medios directos | Los mensajes iniciales solo con archivos usan un marcador de posición de adjunto |
|
||||
| Mensajes con varias imágenes | Varios archivos de Slack | Cada archivo se evalúa de forma independiente | El procesamiento de Slack está limitado a ocho archivos por mensaje |
|
||||
| Tipo de medio | Origen | Comportamiento actual | Notas |
|
||||
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Imágenes JPEG / PNG / GIF / WebP | URL de archivo de Slack | Descargadas y adjuntadas al turno para gestión compatible con visión | Límite por archivo: `channels.slack.mediaMaxMb` (predeterminado 20 MB) |
|
||||
| Archivos PDF | URL de archivo de Slack | Descargados y expuestos como contexto de archivo para herramientas como `download-file` o `pdf` | La entrada de Slack no convierte los PDF automáticamente en entrada de visión por imagen |
|
||||
| Otros archivos | URL de archivo de Slack | Descargados cuando es posible y expuestos como contexto de archivo | Los archivos binarios no se tratan como entrada de imagen |
|
||||
| Respuestas de hilo | Archivos del inicio del hilo | Los archivos del mensaje raíz pueden hidratarse como contexto cuando la respuesta no tiene medios directos | Los inicios solo con archivos usan un marcador de posición de adjunto |
|
||||
| Mensajes con varias imágenes | Varios archivos de Slack | Cada archivo se evalúa de forma independiente | El procesamiento de Slack está limitado a ocho archivos por mensaje |
|
||||
|
||||
### Canalización de entrada
|
||||
|
||||
@ -1010,70 +1030,70 @@ Cuando llega un mensaje de Slack con archivos adjuntos:
|
||||
|
||||
1. OpenClaw descarga el archivo desde la URL privada de Slack usando el token del bot (`xoxb-...`).
|
||||
2. El archivo se escribe en el almacén de medios si la operación se completa correctamente.
|
||||
3. Las rutas de medios descargados y los tipos de contenido se agregan al contexto de entrada.
|
||||
4. Las rutas de modelos/herramientas con capacidad de imagen pueden usar adjuntos de imagen desde ese contexto.
|
||||
5. Los archivos que no son imágenes permanecen disponibles como metadatos de archivo o referencias de medios para las herramientas que pueden manejarlos.
|
||||
3. Las rutas de medios descargados y los tipos de contenido se añaden al contexto de entrada.
|
||||
4. Las rutas de modelos/herramientas compatibles con imágenes pueden usar adjuntos de imagen de ese contexto.
|
||||
5. Los archivos que no son imágenes siguen disponibles como metadatos de archivo o referencias de medios para las herramientas que pueden gestionarlos.
|
||||
|
||||
### Herencia de adjuntos del mensaje raíz del hilo
|
||||
### Herencia de adjuntos de la raíz del hilo
|
||||
|
||||
Cuando llega un mensaje en un hilo (tiene un padre `thread_ts`):
|
||||
|
||||
- Si la respuesta no tiene medios directos y el mensaje raíz incluido tiene archivos, Slack puede hidratar los archivos raíz como contexto del mensaje inicial del hilo.
|
||||
- Si la propia respuesta no tiene medios directos y el mensaje raíz incluido tiene archivos, Slack puede hidratar los archivos raíz como contexto del inicio del hilo.
|
||||
- Los adjuntos directos de la respuesta tienen prioridad sobre los adjuntos del mensaje raíz.
|
||||
- Un mensaje raíz que solo tiene archivos y no texto se representa con un marcador de posición de adjunto para que la alternativa aún pueda incluir sus archivos.
|
||||
|
||||
### Manejo de varios adjuntos
|
||||
### Gestión de varios adjuntos
|
||||
|
||||
Cuando un único mensaje de Slack contiene varios archivos adjuntos:
|
||||
Cuando un solo mensaje de Slack contiene varios archivos adjuntos:
|
||||
|
||||
- Cada adjunto se procesa de forma independiente a través de la canalización de medios.
|
||||
- Cada adjunto se procesa de forma independiente mediante la canalización de medios.
|
||||
- Las referencias de medios descargados se agregan al contexto del mensaje.
|
||||
- El orden de procesamiento sigue el orden de archivos de Slack en la carga útil del evento.
|
||||
- El orden de procesamiento sigue el orden de archivos de Slack en la carga del evento.
|
||||
- Un fallo en la descarga de un adjunto no bloquea los demás.
|
||||
|
||||
### Límites de tamaño, descarga y modelo
|
||||
|
||||
- **Límite de tamaño**: 20 MB por archivo de forma predeterminada. Configurable mediante `channels.slack.mediaMaxMb`.
|
||||
- **Fallos de descarga**: Los archivos que Slack no puede servir, las URLs caducadas, los archivos inaccesibles, los archivos demasiado grandes y las respuestas HTML de autenticación/inicio de sesión de Slack se omiten en lugar de notificarse como formatos no compatibles.
|
||||
- **Límite de tamaño**: Predeterminado de 20 MB por archivo. Configurable mediante `channels.slack.mediaMaxMb`.
|
||||
- **Fallos de descarga**: Los archivos que Slack no puede servir, las URL caducadas, los archivos inaccesibles, los archivos demasiado grandes y las respuestas HTML de autenticación/inicio de sesión de Slack se omiten en lugar de notificarse como formatos no compatibles.
|
||||
- **Modelo de visión**: El análisis de imágenes usa el modelo de respuesta activo cuando admite visión, o el modelo de imagen configurado en `agents.defaults.imageModel`.
|
||||
|
||||
### Límites conocidos
|
||||
|
||||
| Escenario | Comportamiento actual | Solución alternativa |
|
||||
| -------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| URL de archivo de Slack caducada | Se omite el archivo; no se muestra ningún error | Vuelve a cargar el archivo en Slack |
|
||||
| Escenario | Comportamiento actual | Solución alternativa |
|
||||
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| URL de archivo de Slack caducada | El archivo se omite; no se muestra ningún error | Vuelve a subir el archivo en Slack |
|
||||
| Modelo de visión no configurado | Los adjuntos de imagen se almacenan como referencias de medios, pero no se analizan como imágenes | Configura `agents.defaults.imageModel` o usa un modelo de respuesta compatible con visión |
|
||||
| Imágenes muy grandes (> 20 MB de forma predeterminada) | Se omiten según el límite de tamaño | Aumenta `channels.slack.mediaMaxMb` si Slack lo permite |
|
||||
| Adjuntos reenviados/compartidos | El texto y los medios de imagen/archivo alojados en Slack se manejan con el mejor esfuerzo | Vuelve a compartirlos directamente en el hilo de OpenClaw |
|
||||
| Adjuntos PDF | Se almacenan como contexto de archivo/medios, no se enrutan automáticamente mediante visión de imagen | Usa `download-file` para metadatos de archivo o la herramienta `pdf` para análisis de PDF |
|
||||
| Imágenes muy grandes (> 20 MB de forma predeterminada) | Se omiten según el límite de tamaño | Aumenta `channels.slack.mediaMaxMb` si Slack lo permite |
|
||||
| Adjuntos reenviados/compartidos | El texto y los medios de imagen/archivo alojados en Slack se gestionan de la mejor manera posible | Vuelve a compartirlos directamente en el hilo de OpenClaw |
|
||||
| Adjuntos PDF | Se almacenan como contexto de archivo/medio, no se enrutan automáticamente por visión de imágenes | Usa `download-file` para metadatos de archivo o la herramienta `pdf` para análisis de PDF |
|
||||
|
||||
### Documentación relacionada
|
||||
|
||||
- [Canalización de comprensión de medios](/es/nodes/media-understanding)
|
||||
- [Herramienta PDF](/es/tools/pdf)
|
||||
- Épica: [#51349](https://github.com/openclaw/openclaw/issues/51349) — habilitación de visión para adjuntos de Slack
|
||||
- Épica: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Habilitación de visión para adjuntos de Slack
|
||||
- Pruebas de regresión: [#51353](https://github.com/openclaw/openclaw/issues/51353)
|
||||
- Verificación en vivo: [#51354](https://github.com/openclaw/openclaw/issues/51354)
|
||||
|
||||
## Relacionado
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pairing" icon="link" href="/es/channels/pairing">
|
||||
<Card title="Emparejamiento" icon="link" href="/es/channels/pairing">
|
||||
Empareja un usuario de Slack con el Gateway.
|
||||
</Card>
|
||||
<Card title="Groups" icon="users" href="/es/channels/groups">
|
||||
<Card title="Grupos" icon="users" href="/es/channels/groups">
|
||||
Comportamiento de canales y mensajes directos de grupo.
|
||||
</Card>
|
||||
<Card title="Channel routing" icon="route" href="/es/channels/channel-routing">
|
||||
<Card title="Enrutamiento de canales" icon="route" href="/es/channels/channel-routing">
|
||||
Enruta mensajes de entrada a agentes.
|
||||
</Card>
|
||||
<Card title="Security" icon="shield" href="/es/gateway/security">
|
||||
<Card title="Seguridad" icon="shield" href="/es/gateway/security">
|
||||
Modelo de amenazas y refuerzo.
|
||||
</Card>
|
||||
<Card title="Configuration" icon="sliders" href="/es/gateway/configuration">
|
||||
Diseño de configuración y precedencia.
|
||||
<Card title="Configuración" icon="sliders" href="/es/gateway/configuration">
|
||||
Diseño y precedencia de la configuración.
|
||||
</Card>
|
||||
<Card title="Slash commands" icon="terminal" href="/es/tools/slash-commands">
|
||||
<Card title="Comandos slash" icon="terminal" href="/es/tools/slash-commands">
|
||||
Catálogo y comportamiento de comandos.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -4,24 +4,24 @@ read_when:
|
||||
summary: Estado de soporte, capacidades y configuración del bot de Telegram
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:14Z"
|
||||
generated_at: "2026-05-04T07:02:50Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Listo para producción para mensajes directos y grupos de bot mediante grammY. El sondeo largo es el modo predeterminado; el modo Webhook es opcional.
|
||||
Listo para producción para MD y grupos de bots mediante grammY. El modo predeterminado es long polling; el modo Webhook es opcional.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/es/channels/pairing">
|
||||
La política predeterminada de mensajes directos para Telegram es el emparejamiento.
|
||||
<Card title="Emparejamiento" icon="link" href="/es/channels/pairing">
|
||||
La política predeterminada de MD para Telegram es el emparejamiento.
|
||||
</Card>
|
||||
<Card title="Channel troubleshooting" icon="wrench" href="/es/channels/troubleshooting">
|
||||
Diagnósticos entre canales y manuales de reparación.
|
||||
<Card title="Solución de problemas de canales" icon="wrench" href="/es/channels/troubleshooting">
|
||||
Diagnósticos entre canales y guías de reparación.
|
||||
</Card>
|
||||
<Card title="Gateway configuration" icon="settings" href="/es/gateway/configuration">
|
||||
<Card title="Configuración de Gateway" icon="settings" href="/es/gateway/configuration">
|
||||
Patrones y ejemplos completos de configuración de canales.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -29,14 +29,14 @@ Listo para producción para mensajes directos y grupos de bot mediante grammY. E
|
||||
## Configuración rápida
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the bot token in BotFather">
|
||||
<Step title="Crea el token del bot en BotFather">
|
||||
Abre Telegram y chatea con **@BotFather** (confirma que el identificador sea exactamente `@BotFather`).
|
||||
|
||||
Ejecuta `/newbot`, sigue las indicaciones y guarda el token.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure token and DM policy">
|
||||
<Step title="Configura el token y la política de MD">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -51,12 +51,12 @@ Listo para producción para mensajes directos y grupos de bot mediante grammY. E
|
||||
}
|
||||
```
|
||||
|
||||
Alternativa de entorno: `TELEGRAM_BOT_TOKEN=...` (solo cuenta predeterminada).
|
||||
Telegram **no** usa `openclaw channels login telegram`; configura el token en config/env y luego inicia el Gateway.
|
||||
Respaldo por entorno: `TELEGRAM_BOT_TOKEN=...` (solo cuenta predeterminada).
|
||||
Telegram **no** usa `openclaw channels login telegram`; configura el token en la configuración o el entorno y luego inicia el gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway and approve first DM">
|
||||
<Step title="Inicia el gateway y aprueba el primer MD">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -68,40 +68,40 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Add the bot to a group">
|
||||
<Step title="Agrega el bot a un grupo">
|
||||
Agrega el bot a tu grupo y luego configura `channels.telegram.groups` y `groupPolicy` para que coincidan con tu modelo de acceso.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
El orden de resolución de tokens tiene en cuenta la cuenta. En la práctica, los valores de configuración prevalecen sobre la alternativa de entorno, y `TELEGRAM_BOT_TOKEN` solo se aplica a la cuenta predeterminada.
|
||||
El orden de resolución de tokens es consciente de la cuenta. En la práctica, los valores de configuración tienen prioridad sobre el respaldo por entorno, y `TELEGRAM_BOT_TOKEN` solo se aplica a la cuenta predeterminada.
|
||||
</Note>
|
||||
|
||||
## Configuración del lado de Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Privacy mode and group visibility">
|
||||
Los bots de Telegram usan **Modo de privacidad** de forma predeterminada, lo que limita qué mensajes de grupo reciben.
|
||||
<Accordion title="Modo de privacidad y visibilidad en grupos">
|
||||
Los bots de Telegram usan de forma predeterminada el **Modo de privacidad**, que limita qué mensajes de grupo reciben.
|
||||
|
||||
Si el bot debe ver todos los mensajes de grupo, haz una de estas dos cosas:
|
||||
Si el bot debe ver todos los mensajes de grupo:
|
||||
|
||||
- desactiva el modo de privacidad mediante `/setprivacy`, o
|
||||
- convierte al bot en administrador del grupo.
|
||||
- convierte el bot en administrador del grupo.
|
||||
|
||||
Al alternar el modo de privacidad, elimina y vuelve a agregar el bot en cada grupo para que Telegram aplique el cambio.
|
||||
Al cambiar el modo de privacidad, elimina y vuelve a agregar el bot en cada grupo para que Telegram aplique el cambio.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Group permissions">
|
||||
<Accordion title="Permisos de grupo">
|
||||
El estado de administrador se controla en la configuración del grupo de Telegram.
|
||||
|
||||
Los bots administradores reciben todos los mensajes de grupo, lo que resulta útil para comportamientos de grupo siempre activos.
|
||||
Los bots administradores reciben todos los mensajes de grupo, lo que resulta útil para comportamiento de grupo siempre activo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Helpful BotFather toggles">
|
||||
<Accordion title="Opciones útiles de BotFather">
|
||||
|
||||
- `/setjoingroups` para permitir o denegar adiciones a grupos
|
||||
- `/setjoingroups` para permitir o denegar que se agregue a grupos
|
||||
- `/setprivacy` para el comportamiento de visibilidad en grupos
|
||||
|
||||
</Accordion>
|
||||
@ -110,39 +110,39 @@ El orden de resolución de tokens tiene en cuenta la cuenta. En la práctica, lo
|
||||
## Control de acceso y activación
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM policy">
|
||||
`channels.telegram.dmPolicy` controla el acceso a mensajes directos:
|
||||
<Tab title="Política de MD">
|
||||
`channels.telegram.dmPolicy` controla el acceso por mensaje directo:
|
||||
|
||||
- `pairing` (predeterminado)
|
||||
- `allowlist` (requiere al menos un ID de remitente en `allowFrom`)
|
||||
- `open` (requiere que `allowFrom` incluya `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` con `allowFrom: ["*"]` permite que cualquier cuenta de Telegram que encuentre o adivine el nombre de usuario del bot lo controle. Úsalo solo para bots intencionalmente públicos con herramientas estrictamente restringidas; los bots de un solo propietario deben usar `allowlist` con IDs de usuario numéricos.
|
||||
`dmPolicy: "open"` con `allowFrom: ["*"]` permite que cualquier cuenta de Telegram que encuentre o adivine el nombre de usuario del bot envíe comandos al bot. Úsalo solo para bots intencionalmente públicos con herramientas estrictamente restringidas; los bots de un solo propietario deben usar `allowlist` con ID numéricos de usuario.
|
||||
|
||||
`channels.telegram.allowFrom` acepta IDs de usuario numéricos de Telegram. Se aceptan y normalizan los prefijos `telegram:` / `tg:`.
|
||||
En configuraciones de varias cuentas, un `channels.telegram.allowFrom` restrictivo de nivel superior se trata como un límite de seguridad: las entradas `allowFrom: ["*"]` a nivel de cuenta no hacen pública esa cuenta a menos que la lista de permitidos efectiva de la cuenta siga conteniendo un comodín explícito después de la fusión.
|
||||
`dmPolicy: "allowlist"` con `allowFrom` vacío bloquea todos los mensajes directos y la validación de configuración lo rechaza.
|
||||
La configuración solicita solo IDs de usuario numéricos.
|
||||
`channels.telegram.allowFrom` acepta ID numéricos de usuario de Telegram. Los prefijos `telegram:` / `tg:` se aceptan y normalizan.
|
||||
En configuraciones de varias cuentas, un `channels.telegram.allowFrom` restrictivo de nivel superior se trata como un límite de seguridad: las entradas de nivel de cuenta `allowFrom: ["*"]` no hacen pública esa cuenta a menos que la lista efectiva de permitidos de la cuenta todavía contenga un comodín explícito después de la fusión.
|
||||
`dmPolicy: "allowlist"` con `allowFrom` vacío bloquea todos los MD y la validación de configuración lo rechaza.
|
||||
La configuración solicita solo ID numéricos de usuario.
|
||||
Si actualizaste y tu configuración contiene entradas de lista de permitidos `@username`, ejecuta `openclaw doctor --fix` para resolverlas (mejor esfuerzo; requiere un token de bot de Telegram).
|
||||
Si antes dependías de archivos de lista de permitidos del almacén de emparejamiento, `openclaw doctor --fix` puede recuperar entradas en `channels.telegram.allowFrom` en flujos de lista de permitidos (por ejemplo, cuando `dmPolicy: "allowlist"` aún no tiene IDs explícitos).
|
||||
Si antes dependías de archivos de lista de permitidos del almacén de emparejamiento, `openclaw doctor --fix` puede recuperar entradas en `channels.telegram.allowFrom` en flujos de lista de permitidos (por ejemplo, cuando `dmPolicy: "allowlist"` aún no tiene ID explícitos).
|
||||
|
||||
Para bots de un solo propietario, prefiere `dmPolicy: "allowlist"` con IDs numéricos explícitos en `allowFrom` para mantener la política de acceso duradera en la configuración (en lugar de depender de aprobaciones de emparejamiento anteriores).
|
||||
Para bots de un solo propietario, prefiere `dmPolicy: "allowlist"` con ID numéricos explícitos en `allowFrom` para mantener la política de acceso duradera en la configuración (en lugar de depender de aprobaciones de emparejamiento anteriores).
|
||||
|
||||
Confusión común: la aprobación de emparejamiento por mensaje directo no significa "este remitente está autorizado en todas partes".
|
||||
El emparejamiento concede acceso por mensaje directo. Si aún no existe propietario de comandos, el primer emparejamiento aprobado también establece `commands.ownerAllowFrom` para que los comandos exclusivos del propietario y las aprobaciones de ejecución tengan una cuenta de operador explícita.
|
||||
La autorización de remitentes de grupo sigue viniendo de listas de permitidos explícitas en la configuración.
|
||||
Si quieres "me autorizo una vez y funcionan tanto los mensajes directos como los comandos de grupo", coloca tu ID de usuario numérico de Telegram en `channels.telegram.allowFrom`; para comandos exclusivos del propietario, asegúrate de que `commands.ownerAllowFrom` contenga `telegram:<your user id>`.
|
||||
Confusión común: la aprobación de emparejamiento por MD no significa "este remitente está autorizado en todas partes".
|
||||
El emparejamiento concede acceso por MD. Si aún no existe un propietario de comandos, el primer emparejamiento aprobado también establece `commands.ownerAllowFrom` para que los comandos solo para propietarios y las aprobaciones de ejecución tengan una cuenta de operador explícita.
|
||||
La autorización de remitentes en grupos sigue proviniendo de listas de permitidos explícitas en la configuración.
|
||||
Si quieres "estoy autorizado una vez y funcionan tanto los MD como los comandos de grupo", coloca tu ID numérico de usuario de Telegram en `channels.telegram.allowFrom`; para comandos solo para propietarios, asegúrate de que `commands.ownerAllowFrom` contenga `telegram:<your user id>`.
|
||||
|
||||
### Encontrar tu ID de usuario de Telegram
|
||||
|
||||
Más seguro (sin bot de terceros):
|
||||
|
||||
1. Envía un mensaje directo a tu bot.
|
||||
1. Envía un MD a tu bot.
|
||||
2. Ejecuta `openclaw logs --follow`.
|
||||
3. Lee `from.id`.
|
||||
|
||||
Método oficial de la Bot API:
|
||||
Método oficial de la API de Bot:
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
@ -152,29 +152,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Group policy and allowlists">
|
||||
<Tab title="Política de grupo y listas de permitidos">
|
||||
Dos controles se aplican juntos:
|
||||
|
||||
1. **Qué grupos están permitidos** (`channels.telegram.groups`)
|
||||
- sin configuración de `groups`:
|
||||
- con `groupPolicy: "open"`: cualquier grupo puede superar las comprobaciones de ID de grupo
|
||||
- con `groupPolicy: "allowlist"` (predeterminado): los grupos se bloquean hasta que agregues entradas en `groups` (o `"*"`)
|
||||
- `groups` configurado: actúa como lista de permitidos (IDs explícitos o `"*"`)
|
||||
- con `groupPolicy: "open"`: cualquier grupo puede pasar las comprobaciones de ID de grupo
|
||||
- con `groupPolicy: "allowlist"` (predeterminado): los grupos quedan bloqueados hasta que agregues entradas de `groups` (o `"*"`)
|
||||
- `groups` configurado: actúa como lista de permitidos (ID explícitos o `"*"`)
|
||||
|
||||
2. **Qué remitentes están permitidos en grupos** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
- `allowlist` (predeterminado)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` se usa para filtrar remitentes de grupo. Si no se define, Telegram recurre a `allowFrom`.
|
||||
Las entradas de `groupAllowFrom` deben ser IDs de usuario numéricos de Telegram (los prefijos `telegram:` / `tg:` se normalizan).
|
||||
No pongas IDs de chat de grupos o supergrupos de Telegram en `groupAllowFrom`. Los IDs de chat negativos van en `channels.telegram.groups`.
|
||||
`groupAllowFrom` se usa para filtrar remitentes de grupo. Si no está definido, Telegram recurre a `allowFrom`.
|
||||
Las entradas de `groupAllowFrom` deben ser ID numéricos de usuario de Telegram (los prefijos `telegram:` / `tg:` se normalizan).
|
||||
No pongas ID de chat de grupos o supergrupos de Telegram en `groupAllowFrom`. Los ID de chat negativos pertenecen bajo `channels.telegram.groups`.
|
||||
Las entradas no numéricas se ignoran para la autorización de remitentes.
|
||||
Límite de seguridad (`2026.2.25+`): la autenticación de remitentes de grupo **no** hereda aprobaciones del almacén de emparejamiento de mensajes directos.
|
||||
El emparejamiento sigue siendo solo para mensajes directos. Para grupos, configura `groupAllowFrom` o `allowFrom` por grupo o por tema.
|
||||
Si `groupAllowFrom` no está definido, Telegram recurre a la configuración `allowFrom`, no al almacén de emparejamiento.
|
||||
Patrón práctico para bots de un solo propietario: configura tu ID de usuario en `channels.telegram.allowFrom`, deja `groupAllowFrom` sin definir y permite los grupos de destino en `channels.telegram.groups`.
|
||||
Nota de runtime: si `channels.telegram` falta por completo, el runtime usa de forma predeterminada `groupPolicy="allowlist"` con cierre seguro, a menos que `channels.defaults.groupPolicy` esté definido explícitamente.
|
||||
Límite de seguridad (`2026.2.25+`): la autenticación de remitentes de grupo **no** hereda aprobaciones del almacén de emparejamiento de MD.
|
||||
El emparejamiento sigue siendo solo para MD. Para grupos, configura `groupAllowFrom` o `allowFrom` por grupo o por tema.
|
||||
Si `groupAllowFrom` no está definido, Telegram recurre a `allowFrom` de configuración, no al almacén de emparejamiento.
|
||||
Patrón práctico para bots de un solo propietario: configura tu ID de usuario en `channels.telegram.allowFrom`, deja `groupAllowFrom` sin definir y permite los grupos de destino bajo `channels.telegram.groups`.
|
||||
Nota de ejecución: si `channels.telegram` falta por completo, el entorno de ejecución usa de forma predeterminada `groupPolicy="allowlist"` con cierre seguro, a menos que `channels.defaults.groupPolicy` esté definido explícitamente.
|
||||
|
||||
Ejemplo: permitir cualquier miembro en un grupo específico:
|
||||
|
||||
@ -213,30 +213,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Error común: `groupAllowFrom` no es una lista de permitidos de grupos de Telegram.
|
||||
|
||||
- Coloca IDs de chat negativos de grupos o supergrupos de Telegram como `-1001234567890` en `channels.telegram.groups`.
|
||||
- Coloca IDs de usuario de Telegram como `8734062810` en `groupAllowFrom` cuando quieras limitar qué personas dentro de un grupo permitido pueden activar el bot.
|
||||
- Coloca los ID de chat negativos de grupos o supergrupos de Telegram, como `-1001234567890`, bajo `channels.telegram.groups`.
|
||||
- Coloca los ID de usuario de Telegram, como `8734062810`, bajo `groupAllowFrom` cuando quieras limitar qué personas dentro de un grupo permitido pueden activar el bot.
|
||||
- Usa `groupAllowFrom: ["*"]` solo cuando quieras que cualquier miembro de un grupo permitido pueda hablar con el bot.
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Mention behavior">
|
||||
Las respuestas en grupo requieren mención de forma predeterminada.
|
||||
<Tab title="Comportamiento de menciones">
|
||||
Las respuestas en grupos requieren mención de forma predeterminada.
|
||||
|
||||
La mención puede venir de:
|
||||
|
||||
- una mención nativa `@botusername`, o
|
||||
- mención nativa `@botusername`, o
|
||||
- patrones de mención en:
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Alternancias de comandos a nivel de sesión:
|
||||
Alternadores de comandos a nivel de sesión:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Estas actualizan solo el estado de la sesión. Usa la configuración para persistencia.
|
||||
Estos solo actualizan el estado de sesión. Usa la configuración para persistencia.
|
||||
|
||||
Ejemplo de configuración persistente:
|
||||
|
||||
@ -252,31 +252,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Obtener el ID del chat de grupo:
|
||||
Obtener el ID de chat del grupo:
|
||||
|
||||
- reenvía un mensaje de grupo a `@userinfobot` / `@getidsbot`
|
||||
- o lee `chat.id` desde `openclaw logs --follow`
|
||||
- o inspecciona `getUpdates` de la Bot API
|
||||
- o inspecciona `getUpdates` de la API de Bot
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Comportamiento de runtime
|
||||
## Comportamiento en tiempo de ejecución
|
||||
|
||||
- Telegram pertenece al proceso del Gateway.
|
||||
- Telegram pertenece al proceso de Gateway.
|
||||
- El enrutamiento es determinista: las entradas de Telegram responden de vuelta a Telegram (el modelo no elige canales).
|
||||
- Los mensajes entrantes se normalizan en el sobre de canal compartido con metadatos de respuesta y marcadores de posición de medios.
|
||||
- Las sesiones de grupo se aíslan por ID de grupo. Los temas de foro agregan `:topic:<threadId>` para mantener aislados los temas.
|
||||
- Los mensajes directos pueden llevar `message_thread_id`; OpenClaw conserva el ID de hilo para las respuestas, pero mantiene los mensajes directos en la sesión plana de forma predeterminada. Configura `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` o una configuración de tema coincidente cuando intencionalmente quieras aislamiento de sesiones de tema en mensajes directos.
|
||||
- El sondeo largo usa el runner de grammY con secuenciación por chat y por hilo. La concurrencia general del receptor del runner usa `agents.defaults.maxConcurrent`.
|
||||
- El sondeo largo está protegido dentro de cada proceso de Gateway para que solo un sondeador activo pueda usar un token de bot a la vez. Si todavía ves conflictos 409 de `getUpdates`, probablemente otro Gateway de OpenClaw, script o sondeador externo esté usando el mismo token.
|
||||
- Los reinicios del watchdog de sondeo largo se activan de forma predeterminada después de 120 segundos sin actividad completada de `getUpdates`. Aumenta `channels.telegram.pollingStallThresholdMs` solo si tu despliegue sigue viendo reinicios falsos por estancamiento de sondeo durante trabajos de larga duración. El valor está en milisegundos y se permite de `30000` a `600000`; se admiten sobrescrituras por cuenta.
|
||||
- La Bot API de Telegram no admite confirmaciones de lectura (`sendReadReceipts` no se aplica).
|
||||
- Las sesiones de grupo se aíslan por ID de grupo. Los temas de foro agregan `:topic:<threadId>` para mantener los temas aislados.
|
||||
- Los mensajes de MD pueden llevar `message_thread_id`; OpenClaw conserva el ID del hilo para las respuestas, pero mantiene los MD en la sesión plana de forma predeterminada. Configura `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` o una configuración de tema coincidente cuando quieras intencionalmente aislamiento de sesión por tema en MD.
|
||||
- Long polling usa el ejecutor de grammY con secuenciación por chat y por hilo. La concurrencia general del sumidero del ejecutor usa `agents.defaults.maxConcurrent`.
|
||||
- Long polling está protegido dentro de cada proceso de Gateway para que solo un encuestador activo pueda usar un token de bot a la vez. Si sigues viendo conflictos `getUpdates` 409, probablemente otro Gateway de OpenClaw, script o encuestador externo esté usando el mismo token.
|
||||
- Los reinicios del watchdog de long polling se activan después de 120 segundos sin vivacidad completada de `getUpdates` de forma predeterminada. Aumenta `channels.telegram.pollingStallThresholdMs` solo si tu despliegue sigue viendo reinicios falsos por bloqueo de sondeo durante trabajos de larga duración. El valor está en milisegundos y se permite de `30000` a `600000`; se admiten sobrescrituras por cuenta.
|
||||
- La API de Bot de Telegram no admite confirmaciones de lectura (`sendReadReceipts` no aplica).
|
||||
|
||||
## Referencia de funciones
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Live stream preview (message edits)">
|
||||
<Accordion title="Vista previa de transmisión en vivo (ediciones de mensaje)">
|
||||
OpenClaw puede transmitir respuestas parciales en tiempo real:
|
||||
|
||||
- chats directos: mensaje de vista previa + `editMessageText`
|
||||
@ -287,9 +287,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.streaming` es `off | partial | block | progress` (predeterminado: `partial`)
|
||||
- `progress` mantiene un borrador de estado editable y lo actualiza con el progreso de herramientas hasta la entrega final
|
||||
- `streaming.preview.toolProgress` controla si las actualizaciones de herramientas/progreso reutilizan el mismo mensaje de vista previa editado (predeterminado: `true` cuando la transmisión de vista previa está activa)
|
||||
- se detectan `channels.telegram.streamMode` heredado y valores booleanos de `streaming`; ejecuta `openclaw doctor --fix` para migrarlos a `channels.telegram.streaming.mode`
|
||||
- `streaming.preview.commandText` controla el detalle de comandos/ejecución dentro de esas líneas de progreso de herramientas: `raw` (predeterminado, conserva el comportamiento publicado) o `status` (solo etiqueta de herramienta)
|
||||
- los valores heredados `channels.telegram.streamMode` y booleanos de `streaming` se detectan; ejecuta `openclaw doctor --fix` para migrarlos a `channels.telegram.streaming.mode`
|
||||
|
||||
Las actualizaciones de vista previa de progreso de herramientas son las líneas de estado breves que se muestran mientras se ejecutan herramientas, por ejemplo ejecución de comandos, lecturas de archivos, actualizaciones de planificación o resúmenes de parches. Telegram las mantiene habilitadas de forma predeterminada para coincidir con el comportamiento publicado de OpenClaw desde `v2026.4.22` y versiones posteriores. Para conservar la vista previa editada para el texto de respuesta, pero ocultar las líneas de progreso de herramientas, configura:
|
||||
Las actualizaciones de vista previa de progreso de herramientas son las líneas breves de estado que se muestran mientras se ejecutan las herramientas, por ejemplo ejecución de comandos, lecturas de archivos, actualizaciones de planificación o resúmenes de parches. Telegram las mantiene activadas de forma predeterminada para coincidir con el comportamiento publicado de OpenClaw desde `v2026.4.22` y versiones posteriores. Para mantener la vista previa editada para el texto de la respuesta pero ocultar las líneas de progreso de herramientas, configura:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,37 +307,73 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Usa `streaming.mode: "off"` solo cuando quieras entrega solo final: las ediciones de vista previa de Telegram se desactivan y la charla genérica de herramientas/progreso se suprime en lugar de enviarse como mensajes de estado independientes. Las solicitudes de aprobación, las cargas multimedia y los errores siguen encaminándose por la entrega final normal. Usa `streaming.preview.toolProgress: false` cuando solo quieras conservar las ediciones de vista previa de la respuesta mientras ocultas las líneas de estado de progreso de herramientas.
|
||||
Para mantener visible el progreso de herramientas pero ocultar el texto de comandos/ejecución, configura:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Para el modo de borrador de progreso, coloca la misma política de texto de comando bajo `streaming.progress`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Usa `streaming.mode: "off"` solo cuando quieras una entrega únicamente final: las ediciones de vista previa de Telegram se desactivan y la charla genérica de herramientas/progreso se suprime en lugar de enviarse como mensajes de estado independientes. Las solicitudes de aprobación, las cargas multimedia y los errores siguen enrutándose mediante la entrega final normal. Usa `streaming.preview.toolProgress: false` cuando solo quieras mantener las ediciones de vista previa de la respuesta y ocultar las líneas de estado de progreso de herramientas.
|
||||
|
||||
<Note>
|
||||
Las respuestas con cita seleccionada de Telegram son la excepción. Cuando `replyToMode` es `"first"`, `"all"` o `"batched"` y el mensaje entrante incluye texto de cita seleccionado, OpenClaw envía la respuesta final por la ruta nativa de respuesta con cita de Telegram en lugar de editar la vista previa de la respuesta, por lo que `streaming.preview.toolProgress` no puede mostrar las líneas breves de estado para ese turno. Las respuestas al mensaje actual sin texto de cita seleccionado siguen conservando el streaming de vista previa. Establece `replyToMode: "off"` cuando la visibilidad del progreso de herramientas sea más importante que las respuestas nativas con cita, o establece `streaming.preview.toolProgress: false` para aceptar la compensación.
|
||||
Las respuestas de cita seleccionada de Telegram son la excepción. Cuando `replyToMode` es `"first"`, `"all"` o `"batched"` y el mensaje entrante incluye texto de cita seleccionado, OpenClaw envía la respuesta final mediante la ruta nativa de respuesta con cita de Telegram en lugar de editar la vista previa de la respuesta, por lo que `streaming.preview.toolProgress` no puede mostrar las líneas de estado breves para ese turno. Las respuestas al mensaje actual sin texto de cita seleccionado siguen manteniendo el streaming de vista previa. Define `replyToMode: "off"` cuando la visibilidad del progreso de herramientas importe más que las respuestas nativas con cita, o define `streaming.preview.toolProgress: false` para aceptar la compensación.
|
||||
</Note>
|
||||
|
||||
Para respuestas solo de texto:
|
||||
|
||||
- vistas previas breves en DM/grupo/tema: OpenClaw conserva el mismo mensaje de vista previa y realiza una edición final en el mismo lugar, a menos que se haya enviado un mensaje visible que no sea de vista previa después de que apareciera la vista previa
|
||||
- vistas previas seguidas de salida visible que no es de vista previa: OpenClaw envía la respuesta completada como un nuevo mensaje final y limpia la vista previa anterior, de modo que la respuesta final aparece después de la salida intermedia
|
||||
- vistas previas con más de aproximadamente un minuto: OpenClaw envía la respuesta completada como un nuevo mensaje final y luego limpia la vista previa, de modo que la marca de tiempo visible de Telegram refleja la hora de finalización en lugar de la hora de creación de la vista previa
|
||||
- vistas previas cortas de DM/grupo/tema: OpenClaw mantiene el mismo mensaje de vista previa y realiza una edición final en el lugar, a menos que se haya enviado un mensaje visible que no sea de vista previa después de que apareció la vista previa
|
||||
- vistas previas seguidas de salida visible que no es de vista previa: OpenClaw envía la respuesta completada como un mensaje final nuevo y limpia la vista previa anterior, para que la respuesta final aparezca después de la salida intermedia
|
||||
- vistas previas con más de aproximadamente un minuto de antigüedad: OpenClaw envía la respuesta completada como un mensaje final nuevo y luego limpia la vista previa, para que la marca de tiempo visible de Telegram refleje la hora de finalización en lugar de la hora de creación de la vista previa
|
||||
|
||||
Para respuestas complejas (por ejemplo, cargas multimedia), OpenClaw recurre a la entrega final normal y luego limpia el mensaje de vista previa.
|
||||
Para respuestas complejas (por ejemplo, cargas multimedia), OpenClaw vuelve a la entrega final normal y luego limpia el mensaje de vista previa.
|
||||
|
||||
El streaming de vista previa está separado del streaming por bloques. Cuando el streaming por bloques está habilitado explícitamente para Telegram, OpenClaw omite el flujo de vista previa para evitar doble streaming.
|
||||
El streaming de vista previa es independiente del streaming por bloques. Cuando el streaming por bloques está habilitado explícitamente para Telegram, OpenClaw omite el stream de vista previa para evitar doble streaming.
|
||||
|
||||
Flujo de razonamiento solo de Telegram:
|
||||
Stream de razonamiento solo para Telegram:
|
||||
|
||||
- `/reasoning stream` envía razonamiento a la vista previa en vivo mientras genera
|
||||
- `/reasoning stream` envía el razonamiento a la vista previa en vivo mientras se genera
|
||||
- la vista previa de razonamiento se elimina después de la entrega final; usa `/reasoning on` cuando el razonamiento deba permanecer visible
|
||||
- la respuesta final se envía sin texto de razonamiento
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Formato y alternativa HTML">
|
||||
<Accordion title="Formato y reserva HTML">
|
||||
El texto saliente usa Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- El texto similar a Markdown se renderiza como HTML seguro para Telegram.
|
||||
- El HTML bruto del modelo se escapa para reducir los fallos de análisis de Telegram.
|
||||
- El HTML sin procesar del modelo se escapa para reducir fallos de análisis de Telegram.
|
||||
- Si Telegram rechaza el HTML analizado, OpenClaw reintenta como texto sin formato.
|
||||
|
||||
Las vistas previas de enlaces están habilitadas de forma predeterminada y se pueden desactivar con `channels.telegram.linkPreview: false`.
|
||||
Las vistas previas de enlaces están habilitadas de forma predeterminada y se pueden deshabilitar con `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -347,7 +384,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `commands.native: "auto"` habilita comandos nativos para Telegram
|
||||
|
||||
Añade entradas personalizadas al menú de comandos:
|
||||
Agrega entradas de menú de comandos personalizados:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -366,38 +403,38 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- los nombres se normalizan (se elimina el `/` inicial, minúsculas)
|
||||
- patrón válido: `a-z`, `0-9`, `_`, longitud `1..32`
|
||||
- los comandos personalizados no pueden sobrescribir comandos nativos
|
||||
- los comandos personalizados no pueden reemplazar comandos nativos
|
||||
- los conflictos/duplicados se omiten y se registran
|
||||
|
||||
Notas:
|
||||
|
||||
- los comandos personalizados son solo entradas de menú; no implementan comportamiento automáticamente
|
||||
- los comandos de plugin/Skills pueden seguir funcionando al escribirse aunque no se muestren en el menú de Telegram
|
||||
- los comandos de plugin/skill pueden seguir funcionando al escribirse aunque no se muestren en el menú de Telegram
|
||||
|
||||
Si los comandos nativos están deshabilitados, se eliminan los integrados. Los comandos personalizados/de plugin aún pueden registrarse si están configurados.
|
||||
|
||||
Errores comunes de configuración:
|
||||
Fallos de configuración comunes:
|
||||
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú de Telegram aún se desbordó después de recortarlo; reduce los comandos de plugin/Skills/personalizados o deshabilita `channels.telegram.commands.native`.
|
||||
- El fallo de `deleteWebhook`, `deleteMyCommands` o `setMyCommands` con `404: Not Found` mientras los comandos directos de curl de Bot API funcionan puede significar que `channels.telegram.apiRoot` se estableció en el endpoint completo `/bot<TOKEN>`. `apiRoot` debe ser solo la raíz de Bot API, y `openclaw doctor --fix` elimina un `/bot<TOKEN>` final accidental.
|
||||
- `getMe returned 401` significa que Telegram rechazó el token de bot configurado. Actualiza `botToken`, `tokenFile` o `TELEGRAM_BOT_TOKEN` con el token actual de BotFather; OpenClaw se detiene antes del polling, por lo que esto no se informa como un fallo de limpieza de Webhook.
|
||||
- `setMyCommands failed` con errores de red/fetch normalmente significa que DNS/HTTPS saliente hacia `api.telegram.org` está bloqueado.
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú de Telegram siguió excediendo el límite después del recorte; reduce comandos de plugin/skill/personalizados o deshabilita `channels.telegram.commands.native`.
|
||||
- Que `deleteWebhook`, `deleteMyCommands` o `setMyCommands` fallen con `404: Not Found` mientras los comandos curl directos de Bot API funcionan puede significar que `channels.telegram.apiRoot` se definió como el endpoint completo `/bot<TOKEN>`. `apiRoot` debe ser solo la raíz de Bot API, y `openclaw doctor --fix` elimina un `/bot<TOKEN>` final accidental.
|
||||
- `getMe returned 401` significa que Telegram rechazó el token de bot configurado. Actualiza `botToken`, `tokenFile` o `TELEGRAM_BOT_TOKEN` con el token actual de BotFather; OpenClaw se detiene antes del sondeo, así que esto no se informa como un fallo de limpieza de Webhook.
|
||||
- `setMyCommands failed` con errores de red/fetch normalmente significa que el DNS/HTTPS saliente hacia `api.telegram.org` está bloqueado.
|
||||
|
||||
### Comandos de emparejamiento de dispositivo (Plugin `device-pair`)
|
||||
### Comandos de emparejamiento de dispositivos (plugin `device-pair`)
|
||||
|
||||
Cuando el Plugin `device-pair` está instalado:
|
||||
Cuando el plugin `device-pair` está instalado:
|
||||
|
||||
1. `/pair` genera un código de configuración
|
||||
2. pega el código en la app iOS
|
||||
3. `/pair pending` lista las solicitudes pendientes (incluidos rol/alcances)
|
||||
1. `/pair` genera el código de configuración
|
||||
2. pega el código en la app de iOS
|
||||
3. `/pair pending` lista solicitudes pendientes (incluidos rol/ámbitos)
|
||||
4. aprueba la solicitud:
|
||||
- `/pair approve <requestId>` para aprobación explícita
|
||||
- `/pair approve` cuando solo hay una solicitud pendiente
|
||||
- `/pair approve latest` para la más reciente
|
||||
|
||||
El código de configuración transporta un token de bootstrap de corta duración. La entrega bootstrap integrada mantiene el token de nodo principal en `scopes: []`; cualquier token de operador entregado queda limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` y `operator.write`. Las comprobaciones de alcance de bootstrap tienen prefijo de rol, por lo que esa lista de permisos de operador solo satisface solicitudes de operador; los roles que no sean de operador siguen necesitando alcances bajo su propio prefijo de rol.
|
||||
El código de configuración contiene un token de arranque de corta duración. La entrega de arranque integrada mantiene el token del nodo principal en `scopes: []`; cualquier token de operador entregado permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` y `operator.write`. Las comprobaciones de ámbito de arranque tienen prefijo de rol, por lo que esa lista de permitidos de operador solo satisface solicitudes de operador; los roles que no son de operador siguen necesitando ámbitos bajo su propio prefijo de rol.
|
||||
|
||||
Si un dispositivo reintenta con detalles de autenticación cambiados (por ejemplo, rol/alcances/clave pública), la solicitud pendiente anterior se reemplaza y la nueva solicitud usa un `requestId` diferente. Vuelve a ejecutar `/pair pending` antes de aprobar.
|
||||
Si un dispositivo reintenta con detalles de autenticación cambiados (por ejemplo, rol/ámbitos/clave pública), la solicitud pendiente anterior se reemplaza y la nueva solicitud usa un `requestId` diferente. Vuelve a ejecutar `/pair pending` antes de aprobar.
|
||||
|
||||
Más detalles: [Emparejamiento](/es/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
@ -418,7 +455,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Sobrescritura por cuenta:
|
||||
Reemplazo por cuenta:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -444,7 +481,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (predeterminado)
|
||||
|
||||
`capabilities: ["inlineButtons"]` heredado se asigna a `inlineButtons: "all"`.
|
||||
El valor heredado `capabilities: ["inlineButtons"]` se asigna a `inlineButtons: "all"`.
|
||||
|
||||
Ejemplo de acción de mensaje:
|
||||
|
||||
@ -472,23 +509,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Acciones de mensajes de Telegram para agentes y automatización">
|
||||
Las acciones de herramientas de Telegram incluyen:
|
||||
|
||||
- `sendMessage` (`to`, `content`, opcional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, `mediaUrl` opcional, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, opcional `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, `iconColor` opcional, `iconCustomEmojiId`)
|
||||
|
||||
Las acciones de mensajes de canal exponen alias ergonómicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Controles de compuerta:
|
||||
Controles de activación:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (predeterminado: deshabilitado)
|
||||
|
||||
Nota: `edit` y `topic-create` actualmente están habilitados de forma predeterminada y no tienen conmutadores `channels.telegram.actions.*` separados.
|
||||
Los envíos en tiempo de ejecución usan la instantánea activa de configuración/secretos (inicio/recarga), por lo que las rutas de acción no realizan una nueva resolución ad hoc de SecretRef por cada envío.
|
||||
Nota: `edit` y `topic-create` actualmente están habilitados de forma predeterminada y no tienen interruptores `channels.telegram.actions.*` separados.
|
||||
Los envíos en tiempo de ejecución usan la instantánea activa de configuración/secretos (inicio/recarga), por lo que las rutas de acción no realizan una nueva resolución SecretRef ad hoc por cada envío.
|
||||
|
||||
Semántica de eliminación de reacciones: [/tools/reactions](/es/tools/reactions)
|
||||
|
||||
@ -497,7 +534,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Etiquetas de hilos de respuesta">
|
||||
Telegram admite etiquetas explícitas de hilos de respuesta en la salida generada:
|
||||
|
||||
- `[[reply_to_current]]` responde al mensaje que activa la acción
|
||||
- `[[reply_to_current]]` responde al mensaje desencadenante
|
||||
- `[[reply_to:<id>]]` responde a un ID de mensaje específico de Telegram
|
||||
|
||||
`channels.telegram.replyToMode` controla el manejo:
|
||||
@ -506,29 +543,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Cuando los hilos de respuesta están habilitados y el texto o pie de foto original de Telegram está disponible, OpenClaw incluye automáticamente un extracto de cita nativo de Telegram. Telegram limita el texto de cita nativo a 1024 unidades de código UTF-16, por lo que los mensajes más largos se citan desde el inicio y recurren a una respuesta sin formato si Telegram rechaza la cita.
|
||||
Cuando el hilo de respuesta está habilitado y el texto o pie de foto original de Telegram está disponible, OpenClaw incluye automáticamente un extracto de cita nativa de Telegram. Telegram limita el texto de cita nativa a 1024 unidades de código UTF-16, por lo que los mensajes más largos se citan desde el inicio y recurren a una respuesta sin formato si Telegram rechaza la cita.
|
||||
|
||||
Nota: `off` deshabilita los hilos de respuesta implícitos. Las etiquetas explícitas `[[reply_to_*]]` se siguen respetando.
|
||||
Nota: `off` deshabilita el hilo de respuesta implícito. Las etiquetas explícitas `[[reply_to_*]]` se siguen respetando.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Temas de foro y comportamiento de hilos">
|
||||
Supergrupos de foro:
|
||||
|
||||
- las claves de sesión de tema añaden `:topic:<threadId>`
|
||||
- las respuestas y la escritura se dirigen al hilo del tema
|
||||
- las claves de sesión de tema agregan `:topic:<threadId>`
|
||||
- las respuestas y la escritura tienen como destino el hilo del tema
|
||||
- ruta de configuración de tema:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso especial del tema General (`threadId=1`):
|
||||
Caso especial del tema general (`threadId=1`):
|
||||
|
||||
- los envíos de mensajes omiten `message_thread_id` (Telegram rechaza `sendMessage(...thread_id=1)`)
|
||||
- las acciones de escritura aún incluyen `message_thread_id`
|
||||
|
||||
Herencia de temas: las entradas de tema heredan la configuración de grupo a menos que se sobrescriban (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` es solo de tema y no hereda de los valores predeterminados del grupo.
|
||||
Herencia de temas: las entradas de tema heredan la configuración de grupo a menos que se reemplacen (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` es exclusivo del tema y no hereda de los valores predeterminados del grupo.
|
||||
|
||||
**Enrutamiento de agentes por tema**: Cada tema puede enrutar a un agente diferente estableciendo `agentId` en la configuración del tema. Esto da a cada tema su propio espacio de trabajo, memoria y sesión aislados. Ejemplo:
|
||||
**Enrutamiento de agente por tema**: Cada tema puede enrutarse a un agente diferente definiendo `agentId` en la configuración del tema. Esto da a cada tema su propio espacio de trabajo, memoria y sesión aislados. Ejemplo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -548,24 +585,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Cada tema tiene entonces su propia clave de sesión: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Luego cada tema tiene su propia clave de sesión: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Vinculación persistente de temas ACP**: Los temas de foro pueden fijar sesiones de arnés ACP mediante vinculaciones ACP tipadas de nivel superior (`bindings[]` con `type: "acp"` y `match.channel: "telegram"`, `peer.kind: "group"` y un id calificado por tema como `-1001234567890:topic:42`). Actualmente está limitado a temas de foro en grupos/supergrupos. Consulta [Agentes ACP](/es/tools/acp-agents).
|
||||
|
||||
**Spawn de ACP vinculado a hilo desde chat**: `/acp spawn <agent> --thread here|auto` vincula el tema actual a una nueva sesión ACP; los seguimientos se enrutan allí directamente. OpenClaw fija la confirmación de spawn en el tema. Requiere que `channels.telegram.threadBindings.spawnSessions` permanezca habilitado (predeterminado: `true`).
|
||||
**Generación ACP vinculada a hilo desde el chat**: `/acp spawn <agent> --thread here|auto` vincula el tema actual a una nueva sesión ACP; los seguimientos se enrutan allí directamente. OpenClaw fija la confirmación de generación en el tema. Requiere que `channels.telegram.threadBindings.spawnSessions` permanezca habilitado (predeterminado: `true`).
|
||||
|
||||
El contexto de plantilla expone `MessageThreadId` e `IsForum`. Los chats DM con `message_thread_id` mantienen el enrutamiento de DM y los metadatos de respuesta en sesiones planas de forma predeterminada; solo usan claves de sesión conscientes de hilos cuando se configuran con `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` o una configuración de tema coincidente. Usa `channels.telegram.dm.threadReplies` de nivel superior para el valor predeterminado de la cuenta, o `direct.<chatId>.threadReplies` para un DM.
|
||||
El contexto de plantilla expone `MessageThreadId` e `IsForum`. Los chats de DM con `message_thread_id` conservan de forma predeterminada el enrutamiento de DM y los metadatos de respuesta en sesiones planas; solo usan claves de sesión con conocimiento de hilos cuando se configuran con `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` o una configuración de tema coincidente. Usa `channels.telegram.dm.threadReplies` de nivel superior para el valor predeterminado de la cuenta, o `direct.<chatId>.threadReplies` para un DM.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Audio, video y stickers">
|
||||
### Mensajes de audio
|
||||
|
||||
Telegram distingue notas de voz frente a archivos de audio.
|
||||
Telegram distingue entre notas de voz y archivos de audio.
|
||||
|
||||
- predeterminado: comportamiento de archivo de audio
|
||||
- etiqueta `[[audio_as_voice]]` en la respuesta del agente para forzar el envío como nota de voz
|
||||
- las transcripciones entrantes de notas de voz se enmarcan como texto generado por máquina y no confiable en el contexto del agente; la detección de menciones aún usa la transcripción sin procesar, por lo que los mensajes de voz con compuerta por mención siguen funcionando.
|
||||
- las transcripciones de notas de voz entrantes se enmarcan como texto generado por máquina
|
||||
y no confiable en el contexto del agente; la detección de menciones sigue usando la
|
||||
transcripción sin procesar, por lo que los mensajes de voz condicionados a mención siguen funcionando.
|
||||
|
||||
Ejemplo de acción de mensaje:
|
||||
|
||||
@ -581,7 +620,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Mensajes de video
|
||||
|
||||
Telegram distingue archivos de video de notas de video.
|
||||
Telegram distingue entre archivos de video y notas de video.
|
||||
|
||||
Ejemplo de acción de mensaje:
|
||||
|
||||
@ -595,17 +634,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Las notas de video no admiten subtítulos; el texto de mensaje proporcionado se envía por separado.
|
||||
Las notas de video no admiten pies de foto; el texto de mensaje proporcionado se envía por separado.
|
||||
|
||||
### Stickers
|
||||
|
||||
Manejo de stickers entrantes:
|
||||
|
||||
- WEBP estático: descargado y procesado (marcador `<media:sticker>`)
|
||||
- TGS animado: omitido
|
||||
- WEBM de video: omitido
|
||||
- WEBP estático: se descarga y se procesa (marcador de posición `<media:sticker>`)
|
||||
- TGS animado: se omite
|
||||
- WEBM de video: se omite
|
||||
|
||||
Campos de contexto de sticker:
|
||||
Campos de contexto de stickers:
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -617,9 +656,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Los stickers se describen una vez (cuando es posible) y se almacenan en caché para reducir las llamadas de visión repetidas.
|
||||
Los stickers se describen una vez (cuando es posible) y se almacenan en caché para reducir las llamadas repetidas de visión.
|
||||
|
||||
Habilitar acciones de sticker:
|
||||
Habilitar acciones de stickers:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -658,7 +697,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Notificaciones de reacción">
|
||||
Las reacciones de Telegram llegan como actualizaciones `message_reaction` (separadas de las cargas útiles de mensajes).
|
||||
Las reacciones de Telegram llegan como actualizaciones `message_reaction` (separadas de las cargas de mensajes).
|
||||
|
||||
Cuando está habilitado, OpenClaw encola eventos del sistema como:
|
||||
|
||||
@ -671,17 +710,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Notas:
|
||||
|
||||
- `own` significa solo reacciones de usuarios a mensajes enviados por el bot (mejor esfuerzo mediante la caché de mensajes enviados).
|
||||
- `own` significa solo reacciones de usuarios a mensajes enviados por el bot (mejor esfuerzo mediante caché de mensajes enviados).
|
||||
- Los eventos de reacción siguen respetando los controles de acceso de Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); los remitentes no autorizados se descartan.
|
||||
- Telegram no proporciona ID de hilo en las actualizaciones de reacción.
|
||||
- los grupos que no son foros se enrutan a la sesión de chat del grupo
|
||||
- los grupos que no son foros se enrutan a la sesión del chat de grupo
|
||||
- los grupos de foro se enrutan a la sesión del tema general del grupo (`:topic:1`), no al tema exacto de origen
|
||||
|
||||
`allowed_updates` para polling/webhook incluye `message_reaction` automáticamente.
|
||||
`allowed_updates` para sondeo/Webhook incluye `message_reaction` automáticamente.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reacciones de confirmación">
|
||||
<Accordion title="Reacciones ack">
|
||||
`ackReaction` envía un emoji de confirmación mientras OpenClaw procesa un mensaje entrante.
|
||||
|
||||
Orden de resolución:
|
||||
@ -689,7 +728,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- respaldo de emoji de identidad del agente (`agents.list[].identity.emoji`, de lo contrario "👀")
|
||||
- alternativa de emoji de identidad del agente (`agents.list[].identity.emoji`, si no, "👀")
|
||||
|
||||
Notas:
|
||||
|
||||
@ -720,32 +759,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling frente a webhook">
|
||||
El valor predeterminado es long polling. Para el modo webhook, define `channels.telegram.webhookUrl` y `channels.telegram.webhookSecret`; `webhookPath`, `webhookHost`, `webhookPort` son opcionales (valores predeterminados `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Sondeo largo frente a Webhook">
|
||||
El valor predeterminado es sondeo largo. Para el modo Webhook, define `channels.telegram.webhookUrl` y `channels.telegram.webhookSecret`; opcionales `webhookPath`, `webhookHost`, `webhookPort` (predeterminados `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
El listener local se vincula a `127.0.0.1:8787`. Para entrada pública, coloca un proxy inverso delante del puerto local o define `webhookHost: "0.0.0.0"` de forma intencional.
|
||||
El listener local se enlaza a `127.0.0.1:8787`. Para entrada pública, pon un proxy inverso delante del puerto local o define `webhookHost: "0.0.0.0"` intencionalmente.
|
||||
|
||||
El modo webhook valida las protecciones de solicitud, el token secreto de Telegram y el cuerpo JSON antes de devolver `200` a Telegram.
|
||||
Luego OpenClaw procesa la actualización de forma asíncrona mediante los mismos carriles de bot por chat/por tema usados por long polling, de modo que los turnos lentos del agente no retengan el ACK de entrega de Telegram.
|
||||
El modo Webhook valida las protecciones de solicitud, el token secreto de Telegram y el cuerpo JSON antes de devolver `200` a Telegram.
|
||||
Luego OpenClaw procesa la actualización de forma asíncrona mediante los mismos carriles de bot por chat/por tema que usa el sondeo largo, por lo que los turnos lentos del agente no retienen el ACK de entrega de Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Límites, reintento y destinos de CLI">
|
||||
<Accordion title="Límites, reintentos y destinos de CLI">
|
||||
- El valor predeterminado de `channels.telegram.textChunkLimit` es 4000.
|
||||
- `channels.telegram.chunkMode="newline"` prefiere límites de párrafo (líneas en blanco) antes de dividir por longitud.
|
||||
- `channels.telegram.mediaMaxMb` (predeterminado 100) limita el tamaño de medios entrantes y salientes de Telegram.
|
||||
- `channels.telegram.mediaGroupFlushMs` (predeterminado 500) controla cuánto tiempo se almacenan en búfer los álbumes/grupos de medios de Telegram antes de que OpenClaw los despache como un solo mensaje entrante. Auméntalo si las partes del álbum llegan tarde; redúcelo para disminuir la latencia de respuesta del álbum.
|
||||
- `channels.telegram.timeoutSeconds` anula el tiempo de espera del cliente de la API de Telegram (si no está definido, se aplica el valor predeterminado de grammY). Los clientes de bot limitan los valores configurados por debajo de la protección de solicitud de texto/tecleo saliente de 60 segundos para que grammY no aborte la entrega de respuestas visibles antes de que puedan ejecutarse la protección de transporte y el respaldo de OpenClaw. Long polling sigue usando una protección de solicitud `getUpdates` de 45 segundos para que los sondeos inactivos no se abandonen indefinidamente.
|
||||
- `channels.telegram.pollingStallThresholdMs` tiene como valor predeterminado `120000`; ajústalo entre `30000` y `600000` solo para reinicios por bloqueo de polling que sean falsos positivos.
|
||||
- `channels.telegram.mediaGroupFlushMs` (predeterminado 500) controla cuánto tiempo se almacenan en búfer los álbumes/grupos de medios de Telegram antes de que OpenClaw los despache como un único mensaje entrante. Auméntalo si las partes del álbum llegan tarde; redúcelo para disminuir la latencia de respuesta a álbumes.
|
||||
- `channels.telegram.timeoutSeconds` anula el tiempo de espera del cliente de API de Telegram (si no se define, se aplica el valor predeterminado de grammY). Los clientes de bot limitan los valores configurados por debajo de la protección de solicitud de texto/escritura saliente de 60 segundos para que grammY no aborte la entrega visible de respuestas antes de que puedan ejecutarse la protección de transporte y la alternativa de OpenClaw. El sondeo largo sigue usando una protección de solicitud `getUpdates` de 45 segundos para que los sondeos inactivos no se abandonen indefinidamente.
|
||||
- `channels.telegram.pollingStallThresholdMs` tiene como valor predeterminado `120000`; ajusta entre `30000` y `600000` solo para reinicios por estancamiento de sondeo con falsos positivos.
|
||||
- el historial de contexto de grupo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (predeterminado 50); `0` lo deshabilita.
|
||||
- el contexto suplementario de respuesta/cita/reenvío actualmente se pasa tal como se recibe.
|
||||
- las listas de permitidos de Telegram controlan principalmente quién puede activar el agente, no son un límite completo de censura de contexto suplementario.
|
||||
- el contexto complementario de respuesta/cita/reenvío actualmente se pasa tal como se recibe.
|
||||
- las listas de permitidos de Telegram controlan principalmente quién puede activar al agente, no un límite completo de redacción de contexto complementario.
|
||||
- Controles de historial de DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- La configuración `channels.telegram.retry` se aplica a los helpers de envío de Telegram (CLI/herramientas/acciones) para errores recuperables de API saliente. La entrega de respuesta final entrante también usa un reintento acotado de envío seguro para fallas de preconexión de Telegram, pero no reintenta envolturas de red ambiguas posteriores al envío que podrían duplicar mensajes visibles.
|
||||
- La configuración `channels.telegram.retry` se aplica a los helpers de envío de Telegram (CLI/herramientas/acciones) para errores recuperables de API saliente. La entrega de la respuesta final entrante también usa un reintento de envío seguro limitado para fallos de preconexión de Telegram, pero no reintenta envolturas de red ambiguas posteriores al envío que podrían duplicar mensajes visibles.
|
||||
|
||||
El destino de envío de CLI puede ser un ID de chat numérico o un nombre de usuario:
|
||||
El destino de envío de CLI puede ser un ID numérico de chat o un nombre de usuario:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -762,7 +801,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Flags de sondeo solo para Telegram:
|
||||
Flags de sondeo solo de Telegram:
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
@ -771,9 +810,9 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
El envío de Telegram también admite:
|
||||
|
||||
- `--presentation` con bloques `buttons` para teclados inline cuando `channels.telegram.capabilities.inlineButtons` lo permite
|
||||
- `--presentation` con bloques `buttons` para teclados en línea cuando `channels.telegram.capabilities.inlineButtons` lo permite
|
||||
- `--pin` o `--delivery '{"pin":true}'` para solicitar entrega fijada cuando el bot puede fijar en ese chat
|
||||
- `--force-document` para enviar imágenes y GIF salientes como documentos en lugar de cargas de foto comprimida o medios animados
|
||||
- `--force-document` para enviar imágenes y GIF salientes como documentos en vez de cargas de foto comprimida o medios animados
|
||||
|
||||
Control de acciones:
|
||||
|
||||
@ -783,20 +822,20 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Aprobaciones de exec en Telegram">
|
||||
Telegram admite aprobaciones de exec en DM de aprobadores y opcionalmente puede publicar prompts en el chat o tema de origen. Los aprobadores deben ser ID numéricos de usuario de Telegram.
|
||||
Telegram admite aprobaciones de exec en DM de aprobadores y, opcionalmente, puede publicar avisos en el chat o tema de origen. Los aprobadores deben ser ID numéricos de usuario de Telegram.
|
||||
|
||||
Ruta de configuración:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (se habilita automáticamente cuando al menos un aprobador puede resolverse)
|
||||
- `channels.telegram.execApprovals.enabled` (se habilita automáticamente cuando al menos un aprobador se puede resolver)
|
||||
- `channels.telegram.execApprovals.approvers` (recurre a ID numéricos de propietarios desde `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (predeterminado) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` y `defaultTo` controlan quién puede hablar con el bot y dónde envía respuestas normales. No convierten a alguien en aprobador de exec. El primer emparejamiento de DM aprobado inicializa `commands.ownerAllowFrom` cuando aún no existe propietario de comandos, de modo que la configuración con un solo propietario sigue funcionando sin duplicar ID en `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` y `defaultTo` controlan quién puede hablar con el bot y dónde envía respuestas normales. No convierten a alguien en aprobador de exec. El primer emparejamiento de DM aprobado inicializa `commands.ownerAllowFrom` cuando aún no existe propietario de comandos, por lo que la configuración de un único propietario sigue funcionando sin duplicar ID bajo `execApprovals.approvers`.
|
||||
|
||||
La entrega por canal muestra el texto del comando en el chat; habilita `channel` o `both` solo en grupos/temas de confianza. Cuando el prompt llega a un tema de foro, OpenClaw conserva el tema para el prompt de aprobación y el seguimiento. Las aprobaciones de exec caducan después de 30 minutos de forma predeterminada.
|
||||
La entrega en canal muestra el texto del comando en el chat; habilita `channel` o `both` solo en grupos/temas de confianza. Cuando el aviso llega a un tema de foro, OpenClaw conserva el tema para el aviso de aprobación y el seguimiento. Las aprobaciones de exec caducan después de 30 minutos de forma predeterminada.
|
||||
|
||||
Los botones de aprobación inline también requieren que `channels.telegram.capabilities.inlineButtons` permita la superficie de destino (`dm`, `group` o `all`). Los ID de aprobación con prefijo `plugin:` se resuelven mediante aprobaciones de plugin; los demás se resuelven primero mediante aprobaciones de exec.
|
||||
Los botones de aprobación en línea también requieren que `channels.telegram.capabilities.inlineButtons` permita la superficie de destino (`dm`, `group` o `all`). Los ID de aprobación con prefijo `plugin:` se resuelven mediante aprobaciones de plugin; los demás se resuelven primero mediante aprobaciones de exec.
|
||||
|
||||
Consulta [Aprobaciones de exec](/es/tools/exec-approvals).
|
||||
|
||||
@ -807,8 +846,8 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
Cuando el agente encuentra un error de entrega o de proveedor, Telegram puede responder con el texto del error o suprimirlo. Dos claves de configuración controlan este comportamiento:
|
||||
|
||||
| Clave | Valores | Predeterminado | Descripción |
|
||||
| ----------------------------------- | ----------------- | -------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| Clave | Valores | Predeterminado | Descripción |
|
||||
| ----------------------------------- | ----------------- | -------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envía un mensaje de error amable al chat. `silent` suprime por completo las respuestas de error. |
|
||||
| `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tiempo mínimo entre respuestas de error al mismo chat. Evita spam de errores durante interrupciones. |
|
||||
|
||||
@ -837,51 +876,51 @@ Se admiten anulaciones por cuenta, por grupo y por tema (la misma herencia que o
|
||||
|
||||
- Si `requireMention=false`, el modo de privacidad de Telegram debe permitir visibilidad completa.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- luego elimina y vuelve a agregar el bot al grupo
|
||||
- luego elimina y vuelve a añadir el bot al grupo
|
||||
- `openclaw channels status` advierte cuando la configuración espera mensajes de grupo sin mención.
|
||||
- `openclaw channels status --probe` puede comprobar ID numéricos explícitos de grupo; el comodín `"*"` no puede comprobarse por pertenencia.
|
||||
- `openclaw channels status --probe` puede comprobar ID numéricos explícitos de grupo; el comodín `"*"` no puede sondearse por pertenencia.
|
||||
- prueba rápida de sesión: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="El bot no ve ningún mensaje de grupo">
|
||||
|
||||
- cuando `channels.telegram.groups` existe, el grupo debe estar listado (o incluir `"*"`)
|
||||
- verifica la pertenencia del bot al grupo
|
||||
- revisa los logs: `openclaw logs --follow` para ver motivos de omisión
|
||||
- cuando existe `channels.telegram.groups`, el grupo debe figurar en la lista (o incluir `"*"`)
|
||||
- verifica que el bot pertenezca al grupo
|
||||
- revisa los registros: `openclaw logs --follow` para ver los motivos de omisión
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Los comandos funcionan parcialmente o no funcionan">
|
||||
<Accordion title="Los comandos funcionan parcialmente o no funcionan en absoluto">
|
||||
|
||||
- autoriza tu identidad de remitente (emparejamiento y/o `allowFrom` numérico)
|
||||
- la autorización de comandos sigue aplicándose incluso cuando la política de grupo es `open`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú nativo tiene demasiadas entradas; reduce los comandos de plugin/skill/personalizados o deshabilita los menús nativos
|
||||
- las llamadas de inicio `deleteMyCommands` / `setMyCommands` y las llamadas de tecleo `sendChatAction` están acotadas y se reintentan una vez mediante el respaldo de transporte de Telegram al agotarse el tiempo de espera de la solicitud. Los errores persistentes de red/fetch suelen indicar problemas de alcanzabilidad DNS/HTTPS hacia `api.telegram.org`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa que el menú nativo tiene demasiadas entradas; reduce los comandos de Plugin/Skills/personalizados o desactiva los menús nativos
|
||||
- las llamadas de arranque `deleteMyCommands` / `setMyCommands` y las llamadas de escritura `sendChatAction` están acotadas y reintentan una vez mediante el respaldo de transporte de Telegram cuando se agota el tiempo de espera de la solicitud. Los errores persistentes de red/fetch suelen indicar problemas de alcance DNS/HTTPS hacia `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="El inicio informa token no autorizado">
|
||||
<Accordion title="El arranque informa un token no autorizado">
|
||||
|
||||
- `getMe returned 401` es un fallo de autenticación de Telegram para el token del bot configurado.
|
||||
- Vuelve a copiar o regenera el token del bot en BotFather, luego actualiza `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` o `TELEGRAM_BOT_TOKEN` para la cuenta predeterminada.
|
||||
- `deleteWebhook 401 Unauthorized` durante el inicio también es un fallo de autenticación; tratarlo como "no existe ningún Webhook" solo aplazaría el mismo fallo por token incorrecto a llamadas posteriores de la API.
|
||||
- `getMe returned 401` es un fallo de autenticación de Telegram para el token de bot configurado.
|
||||
- Vuelve a copiar o regenera el token de bot en BotFather y luego actualiza `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` o `TELEGRAM_BOT_TOKEN` para la cuenta predeterminada.
|
||||
- `deleteWebhook 401 Unauthorized` durante el arranque también es un fallo de autenticación; tratarlo como "no existe ningún Webhook" solo aplazaría el mismo fallo de token incorrecto a llamadas de API posteriores.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Inestabilidad de sondeo o red">
|
||||
<Accordion title="Inestabilidad de sondeo o de red">
|
||||
|
||||
- Node 22+ + fetch/proxy personalizado puede provocar un comportamiento de cancelación inmediata si los tipos de AbortSignal no coinciden.
|
||||
- Algunos hosts resuelven `api.telegram.org` primero a IPv6; una salida IPv6 defectuosa puede causar fallos intermitentes de la API de Telegram.
|
||||
- Si los registros incluyen `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ahora reintenta estos casos como errores de red recuperables.
|
||||
- Durante el inicio del sondeo, OpenClaw reutiliza la prueba `getMe` de inicio correcta para grammY, de modo que el ejecutor no necesite un segundo `getMe` antes del primer `getUpdates`.
|
||||
- Si `deleteWebhook` falla con un error de red transitorio durante el inicio del sondeo, OpenClaw continúa con long polling en lugar de hacer otra llamada previa al sondeo al plano de control. Un Webhook aún activo aparece como un conflicto de `getUpdates`; entonces OpenClaw reconstruye el transporte de Telegram y reintenta la limpieza del Webhook.
|
||||
- Si los sockets de Telegram se reciclan en una cadencia fija corta, comprueba si `channels.telegram.timeoutSeconds` es bajo; los clientes de bot limitan los valores configurados por debajo de las protecciones de solicitudes salientes y de `getUpdates`, pero las versiones anteriores podían cancelar cada sondeo o respuesta cuando esto se configuraba por debajo de esas protecciones.
|
||||
- Si los registros incluyen `Polling stall detected`, OpenClaw reinicia el sondeo y reconstruye el transporte de Telegram después de 120 segundos sin actividad de long polling completada de forma predeterminada.
|
||||
- `openclaw channels status --probe` y `openclaw doctor` advierten cuando una cuenta de sondeo en ejecución no ha completado `getUpdates` después de la gracia de inicio, cuando una cuenta Webhook en ejecución no ha completado `setWebhook` después de la gracia de inicio, o cuando la última actividad correcta del transporte de sondeo está obsoleta.
|
||||
- Aumenta `channels.telegram.pollingStallThresholdMs` solo cuando las llamadas `getUpdates` de larga duración están sanas pero tu host todavía informa falsos reinicios por bloqueo de sondeo. Los bloqueos persistentes suelen apuntar a problemas de proxy, DNS, IPv6 o salida TLS entre el host y `api.telegram.org`.
|
||||
- Telegram también respeta las variables de entorno de proxy del proceso para el transporte de Bot API, incluidas `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` y sus variantes en minúsculas. `NO_PROXY` / `no_proxy` aún puede omitir `api.telegram.org`.
|
||||
- Si el proxy administrado de OpenClaw está configurado mediante `OPENCLAW_PROXY_URL` para un entorno de servicio y no hay variables de entorno de proxy estándar presentes, Telegram también usa esa URL para el transporte de Bot API.
|
||||
- Node 22+ + fetch/proxy personalizado puede provocar comportamiento de aborto inmediato si los tipos de AbortSignal no coinciden.
|
||||
- Algunos hosts resuelven `api.telegram.org` primero a IPv6; una salida IPv6 rota puede causar fallos intermitentes de la API de Telegram.
|
||||
- Si los registros incluyen `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ahora los reintenta como errores de red recuperables.
|
||||
- Durante el arranque del sondeo, OpenClaw reutiliza la prueba `getMe` de arranque exitosa para grammY, de modo que el ejecutor no necesite un segundo `getMe` antes del primer `getUpdates`.
|
||||
- Si `deleteWebhook` falla con un error de red transitorio durante el arranque del sondeo, OpenClaw continúa con sondeo largo en lugar de hacer otra llamada previa al sondeo al plano de control. Un Webhook que siga activo aparece como un conflicto de `getUpdates`; OpenClaw entonces reconstruye el transporte de Telegram y reintenta la limpieza del Webhook.
|
||||
- Si los sockets de Telegram se reciclan con una cadencia fija corta, comprueba si `channels.telegram.timeoutSeconds` es bajo; los clientes de bot elevan los valores configurados que quedan por debajo de las protecciones de solicitudes salientes y de `getUpdates`, pero las versiones anteriores podían abortar cada sondeo o respuesta cuando este valor estaba configurado por debajo de esas protecciones.
|
||||
- Si los registros incluyen `Polling stall detected`, OpenClaw reinicia el sondeo y reconstruye el transporte de Telegram después de 120 segundos sin una comprobación de actividad completada del sondeo largo de forma predeterminada.
|
||||
- `openclaw channels status --probe` y `openclaw doctor` advierten cuando una cuenta de sondeo en ejecución no ha completado `getUpdates` después del período de gracia de arranque, cuando una cuenta de Webhook en ejecución no ha completado `setWebhook` después del período de gracia de arranque, o cuando la última actividad exitosa del transporte de sondeo está obsoleta.
|
||||
- Aumenta `channels.telegram.pollingStallThresholdMs` solo cuando las llamadas `getUpdates` de larga duración están sanas pero tu host sigue informando falsos reinicios por bloqueo de sondeo. Los bloqueos persistentes suelen apuntar a problemas de proxy, DNS, IPv6 o salida TLS entre el host y `api.telegram.org`.
|
||||
- Telegram también respeta las variables de entorno de proxy del proceso para el transporte de Bot API, incluidas `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` y sus variantes en minúsculas. `NO_PROXY` / `no_proxy` todavía puede hacer que se omita `api.telegram.org`.
|
||||
- Si el proxy gestionado por OpenClaw está configurado mediante `OPENCLAW_PROXY_URL` para un entorno de servicio y no hay variables de entorno de proxy estándar presentes, Telegram también usa esa URL para el transporte de Bot API.
|
||||
- En hosts VPS con salida directa/TLS inestable, enruta las llamadas de la API de Telegram mediante `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
@ -890,7 +929,7 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ usa `autoSelectFamily=true` de forma predeterminada (excepto WSL2). El orden de resultados DNS de Telegram respeta `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, luego `channels.telegram.network.dnsResultOrder`, luego el valor predeterminado del proceso, como `NODE_OPTIONS=--dns-result-order=ipv4first`; si no aplica ninguno, Node 22+ recurre a `ipv4first`.
|
||||
- Node 22+ usa `autoSelectFamily=true` de forma predeterminada (excepto WSL2). El orden de resultados DNS de Telegram respeta `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, luego `channels.telegram.network.dnsResultOrder`, luego el valor predeterminado del proceso como `NODE_OPTIONS=--dns-result-order=ipv4first`; si no aplica ninguno, Node 22+ recurre a `ipv4first`.
|
||||
- Si tu host es WSL2 o funciona explícitamente mejor con comportamiento solo IPv4, fuerza la selección de familia:
|
||||
|
||||
```yaml
|
||||
@ -900,11 +939,11 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Las respuestas de rango de referencia RFC 2544 (`198.18.0.0/15`) ya se permiten
|
||||
para descargas de medios de Telegram de forma predeterminada. Si una IP falsa de confianza o
|
||||
un proxy transparente reescribe `api.telegram.org` a alguna otra
|
||||
dirección privada/interna/de uso especial durante las descargas de medios, puedes
|
||||
optar por la omisión solo para Telegram:
|
||||
- Las respuestas del rango de referencia RFC 2544 (`198.18.0.0/15`) ya se permiten
|
||||
para descargas de medios de Telegram de forma predeterminada. Si una IP falsa
|
||||
de confianza o un proxy transparente reescribe `api.telegram.org` a alguna otra
|
||||
dirección privada/interna/de uso especial durante descargas de medios, puedes optar
|
||||
por activar la excepción solo para Telegram:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -915,19 +954,20 @@ channels:
|
||||
|
||||
- La misma opción está disponible por cuenta en
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Si tu proxy resuelve hosts de medios de Telegram en `198.18.x.x`, deja la
|
||||
marca peligrosa desactivada primero. Los medios de Telegram ya permiten el rango
|
||||
de referencia RFC 2544 de forma predeterminada.
|
||||
- Si tu proxy resuelve hosts de medios de Telegram en `198.18.x.x`, deja primero
|
||||
desactivada la marca peligrosa. Los medios de Telegram ya permiten el rango de
|
||||
referencia RFC 2544 de forma predeterminada.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` debilita las protecciones
|
||||
SSRF de medios de Telegram. Úsalo solo para entornos de proxy de confianza
|
||||
controlados por el operador, como enrutamiento de IP falsa de Clash, Mihomo o Surge, cuando
|
||||
sinteticen respuestas privadas o de uso especial fuera del rango de referencia
|
||||
RFC 2544. Déjalo desactivado para el acceso normal a Telegram por internet público.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` debilita las
|
||||
protecciones SSRF de medios de Telegram. Úsalo solo en entornos de proxy
|
||||
de confianza controlados por el operador, como enrutamiento de IP falsa
|
||||
de Clash, Mihomo o Surge, cuando sinteticen respuestas privadas o de uso
|
||||
especial fuera del rango de referencia RFC 2544. Déjalo desactivado para
|
||||
el acceso normal a Telegram por internet público.
|
||||
</Warning>
|
||||
|
||||
- Anulaciones de entorno (temporales):
|
||||
- Sobrescrituras de entorno (temporales):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
@ -947,14 +987,14 @@ Más ayuda: [Solución de problemas de canales](/es/channels/troubleshooting).
|
||||
|
||||
Referencia principal: [Referencia de configuración - Telegram](/es/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Campos de Telegram de alta señal">
|
||||
<Accordion title="Campos clave de Telegram">
|
||||
|
||||
- inicio/autenticación: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` debe apuntar a un archivo regular; los enlaces simbólicos se rechazan)
|
||||
- arranque/autenticación: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` debe apuntar a un archivo regular; se rechazan los enlaces simbólicos)
|
||||
- control de acceso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nivel superior (`type: "acp"`)
|
||||
- aprobaciones de ejecución: `execApprovals`, `accounts.*.execApprovals`
|
||||
- comando/menú: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- comandos/menú: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- hilos/respuestas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- streaming: `streaming` (vista previa), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- transmisión: `streaming` (versión preliminar), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- formato/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- medios/red: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- raíz de API personalizada: `apiRoot` (solo raíz de Bot API; no incluyas `/bot<TOKEN>`)
|
||||
@ -967,7 +1007,7 @@ Referencia principal: [Referencia de configuración - Telegram](/es/gateway/conf
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Precedencia multicuenta: cuando se configuran dos o más IDs de cuenta, define `channels.telegram.defaultAccount` (o incluye `channels.telegram.accounts.default`) para hacer explícito el enrutamiento predeterminado. De lo contrario, OpenClaw recurre al primer ID de cuenta normalizado y `openclaw doctor` advierte. Las cuentas con nombre heredan `channels.telegram.allowFrom` / `groupAllowFrom`, pero no los valores de `accounts.default.*`.
|
||||
Precedencia multicuenta: cuando se configuran dos o más IDs de cuenta, establece `channels.telegram.defaultAccount` (o incluye `channels.telegram.accounts.default`) para que el enrutamiento predeterminado sea explícito. De lo contrario, OpenClaw recurre al primer ID de cuenta normalizado y `openclaw doctor` advierte. Las cuentas con nombre heredan `channels.telegram.allowFrom` / `groupAllowFrom`, pero no los valores de `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Relacionado
|
||||
@ -977,7 +1017,7 @@ Precedencia multicuenta: cuando se configuran dos o más IDs de cuenta, define `
|
||||
Empareja un usuario de Telegram con el Gateway.
|
||||
</Card>
|
||||
<Card title="Grupos" icon="users" href="/es/channels/groups">
|
||||
Comportamiento de listas de permitidos de grupos y temas.
|
||||
Comportamiento de lista de permitidos de grupos y temas.
|
||||
</Card>
|
||||
<Card title="Enrutamiento de canales" icon="route" href="/es/channels/channel-routing">
|
||||
Enruta mensajes entrantes a agentes.
|
||||
@ -989,6 +1029,6 @@ Precedencia multicuenta: cuando se configuran dos o más IDs de cuenta, define `
|
||||
Asigna grupos y temas a agentes.
|
||||
</Card>
|
||||
<Card title="Solución de problemas" icon="wrench" href="/es/channels/troubleshooting">
|
||||
Diagnósticos entre canales.
|
||||
Diagnóstico entre canales.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,22 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Quieres listar las sesiones almacenadas y ver la actividad reciente
|
||||
summary: Referencia de la CLI para `openclaw sessions` (listar sesiones almacenadas + uso)
|
||||
summary: Referencia de CLI para `openclaw sessions` (listar sesiones almacenadas + uso)
|
||||
title: Sesiones
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:44:16Z"
|
||||
generated_at: "2026-05-04T07:02:44Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f
|
||||
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
|
||||
source_path: cli/sessions.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw sessions`
|
||||
|
||||
Lista las sesiones de conversación almacenadas.
|
||||
Enumera las sesiones de conversación almacenadas.
|
||||
|
||||
Las listas de sesiones no son comprobaciones de disponibilidad de canales/proveedores. Muestran filas de conversación persistidas desde los almacenes de sesiones. Un Discord, Slack, Telegram u otro canal inactivo puede volver a conectarse correctamente sin crear una nueva fila de sesión hasta que se procese un mensaje. Usa `openclaw channels status --probe`, `openclaw status --deep` u `openclaw health --verbose` cuando necesites conectividad activa del canal.
|
||||
Las listas de sesiones no son comprobaciones de disponibilidad de canales/proveedores. Muestran filas de conversación persistidas desde almacenes de sesiones. Un Discord, Slack, Telegram u otro canal en silencio puede reconectarse correctamente sin crear una nueva fila de sesión hasta que se procese un mensaje. Usa `openclaw channels status --probe`, `openclaw status --deep` u `openclaw health --verbose` cuando necesites conectividad de canal en vivo.
|
||||
|
||||
Las respuestas `sessions.list` del Gateway están limitadas de forma predeterminada para que los almacenes grandes y de larga duración no puedan monopolizar el bucle de eventos del Gateway. Pasa un `limit` positivo explícito desde clientes RPC cuando se necesite una ventana de resultados diferente; las respuestas incluyen `totalCount`, `limitApplied` y `hasMore` cuando los llamadores necesitan mostrar que existen más filas.
|
||||
|
||||
```bash
|
||||
openclaw sessions
|
||||
@ -42,11 +44,11 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
|
||||
```
|
||||
|
||||
Esta es la ruta de comando que usa el comando de barra `/export-trajectory` después de que el propietario aprueba la solicitud de ejecución. El directorio de salida siempre se resuelve dentro de `.openclaw/trajectory-exports/` bajo el espacio de trabajo seleccionado.
|
||||
Esta es la ruta de comando que usa el comando slash `/export-trajectory` después de que el propietario aprueba la solicitud de ejecución. El directorio de salida siempre se resuelve dentro de `.openclaw/trajectory-exports/` bajo el espacio de trabajo seleccionado.
|
||||
|
||||
`openclaw sessions --all-agents` lee los almacenes de agentes configurados. La detección de sesiones de Gateway y ACP es más amplia: también incluye almacenes que solo existen en disco encontrados bajo la raíz `agents/` predeterminada o una raíz `session.store` con plantilla. Esos almacenes detectados deben resolverse como archivos `sessions.json` normales dentro de la raíz del agente; los enlaces simbólicos y las rutas fuera de la raíz se omiten.
|
||||
`openclaw sessions --all-agents` lee los almacenes de agentes configurados. El descubrimiento de sesiones de Gateway y ACP es más amplio: también incluye almacenes que solo existen en disco encontrados bajo la raíz predeterminada `agents/` o una raíz `session.store` con plantilla. Esos almacenes descubiertos deben resolverse como archivos `sessions.json` normales dentro de la raíz del agente; se omiten los enlaces simbólicos y las rutas fuera de la raíz.
|
||||
|
||||
Ejemplos de JSON:
|
||||
Ejemplos JSON:
|
||||
|
||||
`openclaw sessions --all-agents --json`:
|
||||
|
||||
@ -80,21 +82,21 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123
|
||||
openclaw sessions cleanup --json
|
||||
```
|
||||
|
||||
`openclaw sessions cleanup` usa la configuración de `session.maintenance` de la configuración:
|
||||
`openclaw sessions cleanup` usa los ajustes `session.maintenance` de la configuración:
|
||||
|
||||
- Nota de alcance: `openclaw sessions cleanup` mantiene almacenes de sesiones, transcripciones y archivos complementarios de trayectoria. No depura los registros de ejecuciones de cron (`cron/runs/<jobId>.jsonl`), que se gestionan mediante `cron.runLog.maxBytes` y `cron.runLog.keepLines` en [Configuración de Cron](/es/automation/cron-jobs#configuration) y se explican en [Mantenimiento de Cron](/es/automation/cron-jobs#maintenance).
|
||||
- Nota de alcance: `openclaw sessions cleanup` mantiene almacenes de sesiones, transcripciones y archivos complementarios de trayectorias. No depura registros de ejecuciones de Cron (`cron/runs/<jobId>.jsonl`), que se gestionan mediante `cron.runLog.maxBytes` y `cron.runLog.keepLines` en [Configuración de Cron](/es/automation/cron-jobs#configuration) y se explican en [Mantenimiento de Cron](/es/automation/cron-jobs#maintenance).
|
||||
|
||||
- `--dry-run`: previsualiza cuántas entradas se depurarían o limitarían sin escribir.
|
||||
- En modo de texto, la simulación imprime una tabla de acciones por sesión (`Action`, `Key`, `Age`, `Model`, `Flags`) para que puedas ver qué se conservaría frente a qué se eliminaría.
|
||||
- `--dry-run`: previsualiza cuántas entradas se podarían/limitarían sin escribir.
|
||||
- En modo texto, dry-run imprime una tabla de acciones por sesión (`Action`, `Key`, `Age`, `Model`, `Flags`) para que puedas ver qué se conservaría frente a qué se eliminaría.
|
||||
- `--enforce`: aplica el mantenimiento incluso cuando `session.maintenance.mode` es `warn`.
|
||||
- `--fix-missing`: elimina entradas cuyos archivos de transcripción faltan, incluso si normalmente aún no se eliminarían por antigüedad o recuento.
|
||||
- `--active-key <key>`: protege una clave activa específica frente a la expulsión por presupuesto de disco. Los punteros duraderos a conversaciones externas, como las sesiones de grupo y las sesiones de chat con alcance de hilo, también se conservan mediante el mantenimiento por antigüedad, recuento y presupuesto de disco.
|
||||
- `--fix-missing`: elimina entradas cuyos archivos de transcripción faltan, aunque normalmente todavía no quedarían fuera por antigüedad/cantidad.
|
||||
- `--active-key <key>`: protege una clave activa específica contra expulsión por presupuesto de disco. Los punteros duraderos a conversaciones externas, como sesiones de grupo y sesiones de chat con alcance de hilo, también se conservan durante el mantenimiento por antigüedad/cantidad/presupuesto de disco.
|
||||
- `--agent <id>`: ejecuta la limpieza para un almacén de agente configurado.
|
||||
- `--all-agents`: ejecuta la limpieza para todos los almacenes de agentes configurados.
|
||||
- `--store <path>`: ejecuta contra un archivo `sessions.json` específico.
|
||||
- `--json`: imprime un resumen JSON. Con `--all-agents`, la salida incluye un resumen por almacén.
|
||||
|
||||
Cuando se puede acceder a un Gateway, la limpieza que no es simulada para almacenes de agentes configurados se envía a través del Gateway para que comparta el mismo escritor de almacén de sesiones que el tráfico de ejecución. Usa `--store <path>` para reparar explícitamente sin conexión un archivo de almacén.
|
||||
Cuando se puede acceder a un Gateway, la limpieza que no sea dry-run para almacenes de agentes configurados se envía a través del Gateway para que comparta el mismo escritor del almacén de sesiones que el tráfico de ejecución. Usa `--store <path>` para la reparación sin conexión explícita de un archivo de almacén.
|
||||
|
||||
`openclaw sessions cleanup --all-agents --dry-run --json`:
|
||||
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Explicación de cómo los mensajes entrantes se convierten en respuestas
|
||||
- Aclaración de sesiones, modos de puesta en cola o comportamiento de transmisión
|
||||
- Aclarar las sesiones, los modos de puesta en cola o el comportamiento de transmisión
|
||||
- Documentación de la visibilidad del razonamiento y las implicaciones de uso
|
||||
summary: Flujo de mensajes, sesiones, puesta en cola y visibilidad del razonamiento
|
||||
title: Mensajes
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T16:27:58Z"
|
||||
generated_at: "2026-05-04T07:03:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
|
||||
source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f
|
||||
source_path: concepts/messages.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -19,30 +19,30 @@ OpenClaw gestiona los mensajes entrantes mediante una canalización de resoluci
|
||||
## Flujo de mensajes (alto nivel)
|
||||
|
||||
```
|
||||
Inbound message
|
||||
-> routing/bindings -> session key
|
||||
-> queue (if a run is active)
|
||||
-> agent run (streaming + tools)
|
||||
-> outbound replies (channel limits + chunking)
|
||||
Mensaje entrante
|
||||
-> routing/bindings -> clave de sesión
|
||||
-> cola (si hay una ejecución activa)
|
||||
-> ejecución del agente (streaming + herramientas)
|
||||
-> respuestas salientes (límites del canal + fragmentación)
|
||||
```
|
||||
|
||||
Los controles clave están en la configuración:
|
||||
|
||||
- `messages.*` para prefijos, puesta en cola y comportamiento de grupos.
|
||||
- `agents.defaults.*` para valores predeterminados de streaming por bloques y fragmentación.
|
||||
- Sobrescrituras de canales (`channels.whatsapp.*`, `channels.telegram.*`, etc.) para límites y conmutadores de streaming.
|
||||
- Sobrescrituras de canal (`channels.whatsapp.*`, `channels.telegram.*`, etc.) para límites y conmutadores de streaming.
|
||||
|
||||
Consulta [Configuración](/es/gateway/configuration) para ver el esquema completo.
|
||||
|
||||
## Deduplicación entrante
|
||||
|
||||
Los canales pueden volver a entregar el mismo mensaje después de reconexiones. OpenClaw mantiene una caché de corta duración basada en canal/cuenta/par/sesión/id de mensaje para que las entregas duplicadas no activen otra ejecución del agente.
|
||||
Los canales pueden volver a entregar el mismo mensaje después de reconexiones. OpenClaw mantiene una caché de corta duración con clave por canal/cuenta/par/sesión/id de mensaje para que las entregas duplicadas no activen otra ejecución del agente.
|
||||
|
||||
## Antirrebote entrante
|
||||
|
||||
Los mensajes consecutivos rápidos del **mismo remitente** pueden agruparse en un único turno del agente mediante `messages.inbound`. El antirrebote tiene alcance por canal + conversación y usa el mensaje más reciente para el hilado/los ID de respuesta.
|
||||
Los mensajes consecutivos rápidos del **mismo remitente** pueden agruparse en un solo turno del agente mediante `messages.inbound`. El antirrebote se delimita por canal + conversación y usa el mensaje más reciente para el encadenamiento/IDs de respuesta.
|
||||
|
||||
Configuración (valor predeterminado global + sobrescrituras por canal):
|
||||
Configuración (valor global predeterminado + sobrescrituras por canal):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -61,38 +61,38 @@ Configuración (valor predeterminado global + sobrescrituras por canal):
|
||||
|
||||
Notas:
|
||||
|
||||
- El antirrebote se aplica a mensajes **solo de texto**; los medios/adjuntos se despachan inmediatamente.
|
||||
- Los comandos de control omiten el antirrebote para permanecer independientes, **excepto** cuando un canal opta explícitamente por la coalescencia de DM del mismo remitente (por ejemplo, [BlueBubbles `coalesceSameSenderDms`](/es/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), donde los comandos de DM esperan dentro de la ventana de antirrebote para que una carga útil enviada en partes pueda unirse al mismo turno del agente.
|
||||
- El antirrebote se aplica a mensajes **solo de texto**; los medios/adjuntos se envían inmediatamente.
|
||||
- Los comandos de control omiten el antirrebote para mantenerse independientes, **excepto** cuando un canal opta explícitamente por fusionar MD del mismo remitente (por ejemplo, [BlueBubbles `coalesceSameSenderDms`](/es/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), donde los comandos de MD esperan dentro de la ventana de antirrebote para que una carga útil enviada por partes pueda unirse al mismo turno del agente.
|
||||
|
||||
## Sesiones y dispositivos
|
||||
|
||||
Las sesiones pertenecen al Gateway, no a los clientes.
|
||||
|
||||
- Los chats directos se colapsan en la clave de sesión principal del agente.
|
||||
- Los chats directos se condensan en la clave de sesión principal del agente.
|
||||
- Los grupos/canales obtienen sus propias claves de sesión.
|
||||
- El almacén de sesiones y las transcripciones viven en el host del Gateway.
|
||||
|
||||
Varios dispositivos/canales pueden asignarse a la misma sesión, pero el historial no se sincroniza completamente de vuelta a todos los clientes. Recomendación: usa un dispositivo principal para conversaciones largas a fin de evitar contexto divergente. La interfaz de control y la TUI siempre muestran la transcripción de sesión respaldada por el Gateway, por lo que son la fuente de la verdad.
|
||||
Varios dispositivos/canales pueden asignarse a la misma sesión, pero el historial no se sincroniza por completo de vuelta a cada cliente. Recomendación: usa un dispositivo principal para conversaciones largas a fin de evitar contextos divergentes. La UI de Control y la TUI siempre muestran la transcripción de sesión respaldada por el Gateway, por lo que son la fuente de verdad.
|
||||
|
||||
Detalles: [Gestión de sesiones](/es/concepts/session).
|
||||
|
||||
## Metadatos de resultados de herramientas
|
||||
|
||||
El `content` del resultado de una herramienta es el resultado visible para el modelo. Los `details` del resultado de una herramienta son metadatos de runtime para renderizado de la interfaz, diagnósticos, entrega de medios y plugins.
|
||||
El `content` del resultado de herramienta es el resultado visible para el modelo. El `details` del resultado de herramienta son metadatos de tiempo de ejecución para renderizado de UI, diagnósticos, entrega de medios y plugins.
|
||||
|
||||
OpenClaw mantiene explícito ese límite:
|
||||
|
||||
- `toolResult.details` se elimina antes de la repetición del proveedor y la entrada de Compaction.
|
||||
- Las transcripciones de sesión persistidas conservan solo `details` acotados; los metadatos sobredimensionados se reemplazan por un resumen compacto marcado con `persistedDetailsTruncated: true`.
|
||||
- Los plugins y las herramientas deben poner el texto que el modelo debe leer en `content`, no solo en `details`.
|
||||
- `toolResult.details` se elimina antes de la reproducción del proveedor y la entrada de Compaction.
|
||||
- Las transcripciones de sesión persistidas conservan solo `details` acotados; los metadatos sobredimensionados se reemplazan por un resumen compacto marcado como `persistedDetailsTruncated: true`.
|
||||
- Los plugins y herramientas deben poner el texto que el modelo debe leer en `content`, no solo en `details`.
|
||||
|
||||
## Cuerpos entrantes y contexto de historial
|
||||
|
||||
OpenClaw separa el **cuerpo del prompt** del **cuerpo del comando**:
|
||||
|
||||
- `BodyForAgent`: texto principal orientado al modelo para el mensaje actual. Los plugins de canal deben mantenerlo centrado en el texto actual del remitente que contiene el prompt.
|
||||
- `Body`: alternativa heredada para el prompt. Puede incluir envoltorios de canal y envoltorios opcionales de historial, pero los canales actuales no deben depender de él como entrada principal del modelo cuando `BodyForAgent` está disponible.
|
||||
- `CommandBody`: texto bruto del usuario para análisis de directivas/comandos.
|
||||
- `BodyForAgent`: texto principal orientado al modelo para el mensaje actual. Los plugins de canal deben mantener esto centrado en el texto actual del remitente que contiene el prompt.
|
||||
- `Body`: respaldo heredado del prompt. Esto puede incluir envoltorios de canal y envoltorios de historial opcionales, pero los canales actuales no deben depender de él como entrada principal del modelo cuando `BodyForAgent` está disponible.
|
||||
- `CommandBody`: texto de usuario sin procesar para el análisis de directivas/comandos.
|
||||
- `RawBody`: alias heredado de `CommandBody` (conservado por compatibilidad).
|
||||
|
||||
Cuando un canal proporciona historial, usa un envoltorio compartido:
|
||||
@ -100,12 +100,12 @@ Cuando un canal proporciona historial, usa un envoltorio compartido:
|
||||
- `[Mensajes de chat desde tu última respuesta - para contexto]`
|
||||
- `[Mensaje actual - responde a esto]`
|
||||
|
||||
Para **chats no directos** (grupos/canales/salas), el **cuerpo del mensaje actual** tiene como prefijo la etiqueta del remitente (el mismo estilo usado para entradas de historial). Esto mantiene coherentes los mensajes en tiempo real y los mensajes en cola/historial en el prompt del agente.
|
||||
Para **chats no directos** (grupos/canales/salas), el **cuerpo del mensaje actual** lleva como prefijo la etiqueta del remitente (el mismo estilo usado para entradas de historial). Esto mantiene coherentes en el prompt del agente los mensajes en tiempo real y los mensajes en cola/historial.
|
||||
|
||||
Los búferes de historial son **solo pendientes**: incluyen mensajes de grupo que _no_ activaron una ejecución (por ejemplo, mensajes filtrados por mención) y **excluyen** mensajes que ya están en la transcripción de sesión.
|
||||
Los búferes de historial son **solo pendientes**: incluyen mensajes de grupo que _no_ activaron una ejecución (por ejemplo, mensajes filtrados por mención) y **excluyen** mensajes que ya están en la transcripción de la sesión.
|
||||
|
||||
La eliminación de directivas solo se aplica a la sección del **mensaje actual** para que el historial permanezca intacto. Los canales que envuelven historial deben establecer `CommandBody` (o `RawBody`) en el texto original del mensaje y mantener `Body` como el prompt combinado. El historial estructurado, las respuestas, los mensajes reenviados y los metadatos de canal se renderizan como bloques de contexto no confiable con rol de usuario durante el ensamblado del prompt.
|
||||
Los búferes de historial se pueden configurar mediante `messages.groupChat.historyLimit` (valor predeterminado global) y sobrescrituras por canal como `channels.slack.historyLimit` o `channels.telegram.accounts.<id>.historyLimit` (establece `0` para deshabilitar).
|
||||
La eliminación de directivas solo se aplica a la sección del **mensaje actual**, de modo que el historial permanece intacto. Los canales que envuelven historial deben establecer `CommandBody` (o `RawBody`) en el texto original del mensaje y conservar `Body` como el prompt combinado. El historial estructurado, las respuestas, los mensajes reenviados y los metadatos de canal se renderizan como bloques de contexto no confiable con rol de usuario durante el ensamblaje del prompt.
|
||||
Los búferes de historial son configurables mediante `messages.groupChat.historyLimit` (valor global predeterminado) y sobrescrituras por canal como `channels.slack.historyLimit` o `channels.telegram.accounts.<id>.historyLimit` (establece `0` para deshabilitar).
|
||||
|
||||
## Puesta en cola y seguimientos
|
||||
|
||||
@ -119,13 +119,13 @@ Detalles: [Cola de comandos](/es/concepts/queue) y [Cola de direccionamiento](/e
|
||||
|
||||
## Propiedad de ejecución del canal
|
||||
|
||||
Los plugins de canal pueden preservar el orden, aplicar antirrebote a la entrada y aplicar contrapresión de transporte antes de que un mensaje entre en la cola de sesión. No deben imponer un tiempo de espera independiente alrededor del turno del agente en sí. Una vez que un mensaje se enruta a una sesión, el trabajo de larga duración se rige por el ciclo de vida de la sesión, la herramienta y el runtime para que todos los canales informen y se recuperen de turnos lentos de forma coherente.
|
||||
Los plugins de canal pueden preservar el orden, aplicar antirrebote a la entrada y aplicar contrapresión de transporte antes de que un mensaje entre en la cola de sesión. No deben imponer un tiempo de espera separado alrededor del propio turno del agente. Una vez que un mensaje se enruta a una sesión, el trabajo de larga duración se rige por el ciclo de vida de la sesión, la herramienta y el tiempo de ejecución para que todos los canales informen y se recuperen de turnos lentos de forma coherente.
|
||||
|
||||
## Streaming, fragmentación y agrupación por lotes
|
||||
## Streaming, fragmentación y agrupación
|
||||
|
||||
El streaming por bloques envía respuestas parciales a medida que el modelo produce bloques de texto. La fragmentación respeta los límites de texto del canal y evita dividir código delimitado.
|
||||
El streaming por bloques envía respuestas parciales a medida que el modelo produce bloques de texto. La fragmentación respeta los límites de texto del canal y evita dividir código cercado.
|
||||
|
||||
Configuraciones clave:
|
||||
Ajustes clave:
|
||||
|
||||
- `agents.defaults.blockStreamingDefault` (`on|off`, desactivado de forma predeterminada)
|
||||
- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
|
||||
@ -142,38 +142,38 @@ OpenClaw puede exponer u ocultar el razonamiento del modelo:
|
||||
|
||||
- `/reasoning on|off|stream` controla la visibilidad.
|
||||
- El contenido de razonamiento sigue contando para el uso de tokens cuando lo produce el modelo.
|
||||
- Telegram admite streaming de razonamiento en la burbuja de borrador.
|
||||
- Telegram admite el stream de razonamiento en una burbuja de borrador transitoria que se elimina después de la entrega final; usa `/reasoning on` para una salida de razonamiento persistente.
|
||||
|
||||
Detalles: [Directivas de pensamiento + razonamiento](/es/tools/thinking) y [Uso de tokens](/es/reference/token-use).
|
||||
|
||||
## Prefijos, hilado y respuestas
|
||||
## Prefijos, encadenamiento y respuestas
|
||||
|
||||
El formato de mensajes salientes se centraliza en `messages`:
|
||||
|
||||
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` y `channels.<channel>.accounts.<id>.responsePrefix` (cascada de prefijos salientes), además de `channels.whatsapp.messagePrefix` (prefijo entrante de WhatsApp)
|
||||
- Hilado de respuestas mediante `replyToMode` y valores predeterminados por canal
|
||||
- Encadenamiento de respuestas mediante `replyToMode` y valores predeterminados por canal
|
||||
|
||||
Detalles: [Configuración](/es/gateway/config-agents#messages) y documentación de canales.
|
||||
Detalles: [Configuración](/es/gateway/config-agents#messages) y la documentación de canales.
|
||||
|
||||
## Respuestas silenciosas
|
||||
|
||||
El token silencioso exacto `NO_REPLY` / `no_reply` significa “no entregues una respuesta visible para el usuario”.
|
||||
Cuando un turno también tiene medios de herramienta pendientes, como audio TTS generado, OpenClaw elimina el texto silencioso pero aun así entrega el adjunto multimedia.
|
||||
OpenClaw resuelve ese comportamiento por tipo de conversación:
|
||||
El token silencioso exacto `NO_REPLY` / `no_reply` significa “no entregar una respuesta visible para el usuario”.
|
||||
Cuando un turno también tiene medios de herramienta pendientes, como audio TTS generado, OpenClaw elimina el texto silencioso pero sigue entregando el adjunto multimedia.
|
||||
OpenClaw resuelve ese comportamiento según el tipo de conversación:
|
||||
|
||||
- Las conversaciones directas no permiten silencio de forma predeterminada y reescriben una respuesta silenciosa desnuda como una alternativa visible breve.
|
||||
- Las conversaciones directas no permiten silencio de forma predeterminada y reescriben una respuesta silenciosa desnuda como un respaldo breve visible.
|
||||
- Los grupos/canales permiten silencio de forma predeterminada.
|
||||
- La orquestación interna permite silencio de forma predeterminada.
|
||||
|
||||
OpenClaw también usa respuestas silenciosas para fallos internos del ejecutor que ocurren antes de cualquier respuesta del asistente en chats no directos, para que los grupos/canales no vean texto genérico de error del Gateway. Los chats directos muestran texto de fallo compacto de forma predeterminada; los detalles brutos del ejecutor se muestran solo cuando `/verbose` está `on` o `full`.
|
||||
OpenClaw también usa respuestas silenciosas para fallos internos del runner que ocurren antes de cualquier respuesta del asistente en chats no directos, de modo que los grupos/canales no vean texto repetitivo de error del Gateway. Los chats directos muestran una copia compacta del fallo de forma predeterminada; los detalles sin procesar del runner solo se muestran cuando `/verbose` está `on` o `full`.
|
||||
|
||||
Los valores predeterminados viven bajo `agents.defaults.silentReply` y `agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` y `surfaces.<id>.silentReplyRewrite` pueden sobrescribirlos por superficie.
|
||||
|
||||
Cuando la sesión padre tiene una o más ejecuciones pendientes de subagentes generados, las respuestas silenciosas desnudas se descartan en todas las superficies en lugar de reescribirse, por lo que el padre permanece en silencio hasta que el evento de finalización del hijo entrega la respuesta real.
|
||||
Cuando la sesión padre tiene una o más ejecuciones pendientes de subagentes generados, las respuestas silenciosas desnudas se descartan en todas las superficies en lugar de reescribirse, de modo que el padre permanece en silencio hasta que el evento de finalización del hijo entregue la respuesta real.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Streaming](/es/concepts/streaming) — entrega de mensajes en tiempo real
|
||||
- [Reintento](/es/concepts/retry) — comportamiento de reintento de entrega de mensajes
|
||||
- [Cola](/es/concepts/queue) — cola de procesamiento de mensajes
|
||||
- [Canales](/es/channels) — integraciones con plataformas de mensajería
|
||||
- [Canales](/es/channels) — integraciones de plataformas de mensajería
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Explicación de cómo funcionan la transmisión por secuencias o la fragmentación en los canales
|
||||
- Cambiar el comportamiento de streaming de bloques o de fragmentación de canales
|
||||
- Explicación de cómo funciona la transmisión en tiempo real o la fragmentación en los canales
|
||||
- Cambiar el comportamiento de transmisión de bloques o de fragmentación en canales
|
||||
- Depuración de respuestas de bloque duplicadas/prematuras o de la transmisión de vista previa del canal
|
||||
summary: Comportamiento de streaming y fragmentación (respuestas en bloque, streaming de vista previa del canal, asignación de modos)
|
||||
title: Transmisión y fragmentación
|
||||
summary: Comportamiento de transmisión y fragmentación (respuestas en bloque, transmisión de vista previa del canal, asignación de modos)
|
||||
title: Transmisión continua y fragmentación
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:52Z"
|
||||
generated_at: "2026-05-04T07:03:12Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
|
||||
source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1
|
||||
source_path: concepts/streaming.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -19,11 +19,11 @@ OpenClaw tiene dos capas de streaming separadas:
|
||||
- **Streaming de bloques (canales):** emite **bloques** completados mientras el asistente escribe. Son mensajes de canal normales (no deltas de tokens).
|
||||
- **Streaming de vista previa (Telegram/Discord/Slack):** actualiza un **mensaje de vista previa** temporal durante la generación.
|
||||
|
||||
Actualmente **no hay verdadero streaming de deltas de tokens** hacia los mensajes de canal. El streaming de vista previa se basa en mensajes (envío + ediciones/adiciones).
|
||||
Actualmente **no hay streaming real de deltas de tokens** hacia los mensajes de canal. El streaming de vista previa se basa en mensajes (envío + ediciones/anexos).
|
||||
|
||||
## Streaming de bloques (mensajes de canal)
|
||||
|
||||
El streaming de bloques envía la salida del asistente en fragmentos grandes a medida que está disponible.
|
||||
El streaming de bloques envía la salida del asistente en fragmentos gruesos a medida que está disponible.
|
||||
|
||||
```
|
||||
Model output
|
||||
@ -38,7 +38,7 @@ Model output
|
||||
Leyenda:
|
||||
|
||||
- `text_delta/events`: eventos de stream del modelo (pueden ser escasos en modelos sin streaming).
|
||||
- `chunker`: `EmbeddedBlockChunker` que aplica límites mín./máx. + preferencia de corte.
|
||||
- `chunker`: `EmbeddedBlockChunker` que aplica límites mínimos/máximos + preferencia de corte.
|
||||
- `channel send`: mensajes salientes reales (respuestas por bloques).
|
||||
|
||||
**Controles:**
|
||||
@ -47,66 +47,65 @@ Leyenda:
|
||||
- Sobrescrituras de canal: `*.blockStreaming` (y variantes por cuenta) para forzar `"on"`/`"off"` por canal.
|
||||
- `agents.defaults.blockStreamingBreak`: `"text_end"` o `"message_end"`.
|
||||
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (fusiona bloques transmitidos antes de enviarlos).
|
||||
- Límite estricto del canal: `*.textChunkLimit` (por ejemplo, `channels.whatsapp.textChunkLimit`).
|
||||
- Modo de fragmentación del canal: `*.chunkMode` (`length` predeterminado, `newline` divide en líneas en blanco (límites de párrafo) antes de fragmentar por longitud).
|
||||
- Límite flexible de Discord: `channels.discord.maxLinesPerMessage` (predeterminado 17) divide respuestas altas para evitar recortes en la UI.
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (fusiona bloques transmitidos antes del envío).
|
||||
- Límite estricto de canal: `*.textChunkLimit` (por ejemplo, `channels.whatsapp.textChunkLimit`).
|
||||
- Modo de fragmentación de canal: `*.chunkMode` (`length` predeterminado, `newline` divide en líneas en blanco (límites de párrafo) antes de fragmentar por longitud).
|
||||
- Límite flexible de Discord: `channels.discord.maxLinesPerMessage` (predeterminado 17) divide respuestas altas para evitar recortes en la interfaz.
|
||||
|
||||
**Semántica de límites:**
|
||||
|
||||
- `text_end`: transmite bloques en cuanto el fragmentador los emite; vacía en cada `text_end`.
|
||||
- `text_end`: transmite bloques en cuanto el fragmentador emite; vacía en cada `text_end`.
|
||||
- `message_end`: espera hasta que termine el mensaje del asistente y luego vacía la salida almacenada.
|
||||
|
||||
`message_end` sigue usando el fragmentador si el texto almacenado supera `maxChars`, por lo que puede emitir varios fragmentos al final.
|
||||
|
||||
### Entrega de medios con streaming de bloques
|
||||
|
||||
Las directivas `MEDIA:` son metadatos de entrega normales. Cuando el streaming de bloques envía un bloque multimedia temprano, OpenClaw recuerda esa entrega durante el turno. Si la carga final del asistente repite la misma URL multimedia, la entrega final elimina el medio duplicado en lugar de enviar el adjunto otra vez.
|
||||
Las directivas `MEDIA:` son metadatos de entrega normales. Cuando el streaming de bloques envía un bloque multimedia anticipadamente, OpenClaw recuerda esa entrega para el turno. Si la carga final del asistente repite la misma URL multimedia, la entrega final elimina el medio duplicado en lugar de volver a enviar el adjunto.
|
||||
|
||||
Las cargas finales exactamente duplicadas se suprimen. Si la carga final agrega texto distinto alrededor de medios que ya se transmitieron, OpenClaw sigue enviando el texto nuevo y mantiene el medio con una sola entrega. Esto evita notas de voz o archivos duplicados en canales como Telegram cuando un agente emite `MEDIA:` durante el streaming y el proveedor también lo incluye en la respuesta completada.
|
||||
Las cargas finales duplicadas exactas se suprimen. Si la carga final añade texto distinto alrededor de un medio que ya se transmitió, OpenClaw sigue enviando el texto nuevo y mantiene el medio con entrega única. Esto evita notas de voz o archivos duplicados en canales como Telegram cuando un agente emite `MEDIA:` durante el streaming y el proveedor también lo incluye en la respuesta completada.
|
||||
|
||||
## Algoritmo de fragmentación (límites bajo/alto)
|
||||
|
||||
La fragmentación de bloques se implementa mediante `EmbeddedBlockChunker`:
|
||||
La fragmentación de bloques la implementa `EmbeddedBlockChunker`:
|
||||
|
||||
- **Límite bajo:** no emitir hasta que el búfer >= `minChars` (salvo que se fuerce).
|
||||
- **Límite alto:** prefiere dividir antes de `maxChars`; si se fuerza, divide en `maxChars`.
|
||||
- **Preferencia de corte:** `paragraph` → `newline` → `sentence` → `whitespace` → corte forzado.
|
||||
- **Bloques de código:** nunca divide dentro de bloques; cuando se fuerza en `maxChars`, cierra y reabre el bloque para mantener Markdown válido.
|
||||
- **Límite bajo:** no emitir hasta que el búfer sea >= `minChars` (salvo que se fuerce).
|
||||
- **Límite alto:** preferir divisiones antes de `maxChars`; si se fuerza, dividir en `maxChars`.
|
||||
- **Preferencia de corte:** `paragraph` → `newline` → `sentence` → `whitespace` → corte duro.
|
||||
- **Cercas de código:** nunca dividir dentro de cercas; cuando se fuerza en `maxChars`, cerrar + reabrir la cerca para mantener Markdown válido.
|
||||
|
||||
`maxChars` se limita al `textChunkLimit` del canal, así que no puedes superar los topes por canal.
|
||||
`maxChars` se limita al `textChunkLimit` del canal, por lo que no puedes superar los límites por canal.
|
||||
|
||||
## Coalescencia (fusionar bloques transmitidos)
|
||||
|
||||
Cuando el streaming de bloques está activado, OpenClaw puede **fusionar fragmentos de bloques consecutivos** antes de enviarlos. Esto reduce el “spam de una sola línea” sin dejar de ofrecer salida progresiva.
|
||||
Cuando el streaming de bloques está habilitado, OpenClaw puede **fusionar fragmentos de bloque consecutivos** antes de enviarlos. Esto reduce el “spam de líneas sueltas” y aun así proporciona salida progresiva.
|
||||
|
||||
- La coalescencia espera **intervalos de inactividad** (`idleMs`) antes de vaciar.
|
||||
- La coalescencia espera **pausas de inactividad** (`idleMs`) antes de vaciar.
|
||||
- Los búferes están limitados por `maxChars` y se vacían si lo superan.
|
||||
- `minChars` evita que se envíen fragmentos diminutos hasta que se acumule suficiente texto (el vaciado final siempre envía el texto restante).
|
||||
- El separador se deriva de `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espacio).
|
||||
- Hay sobrescrituras de canal disponibles mediante `*.blockStreamingCoalesce` (incluidas configuraciones por cuenta).
|
||||
- El `minChars` predeterminado de coalescencia se sube a 1500 para Signal/Slack/Discord salvo que se sobrescriba.
|
||||
- Las sobrescrituras de canal están disponibles mediante `*.blockStreamingCoalesce` (incluidas configuraciones por cuenta).
|
||||
- El `minChars` predeterminado de coalescencia sube a 1500 para Signal/Slack/Discord salvo que se sobrescriba.
|
||||
|
||||
## Ritmo similar al humano entre bloques
|
||||
## Ritmo humano entre bloques
|
||||
|
||||
Cuando el streaming de bloques está activado, puedes agregar una **pausa aleatoria** entre respuestas por bloques (después del primer bloque). Esto hace que las respuestas de varias burbujas se sientan más naturales.
|
||||
Cuando el streaming de bloques está habilitado, puedes añadir una **pausa aleatoria** entre respuestas por bloques (después del primer bloque). Esto hace que las respuestas de varias burbujas se sientan más naturales.
|
||||
|
||||
- Configuración: `agents.defaults.humanDelay` (se sobrescribe por agente mediante `agents.list[].humanDelay`).
|
||||
- Modos: `off` (predeterminado), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`).
|
||||
- Configuración: `agents.defaults.humanDelay` (sobrescribir por agente mediante `agents.list[].humanDelay`).
|
||||
- Modos: `off` (predeterminado), `natural` (800–2500 ms), `custom` (`minMs`/`maxMs`).
|
||||
- Se aplica solo a **respuestas por bloques**, no a respuestas finales ni resúmenes de herramientas.
|
||||
|
||||
## "Transmitir fragmentos o todo"
|
||||
|
||||
Esto corresponde a:
|
||||
|
||||
- **Transmitir fragmentos:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emite sobre la marcha). Los canales que no sean Telegram también necesitan `*.blockStreaming: true`.
|
||||
- **Transmitir todo al final:** `blockStreamingBreak: "message_end"` (vaciado una vez, posiblemente varios fragmentos si es muy largo).
|
||||
- **Transmitir fragmentos:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emitir sobre la marcha). Los canales que no sean Telegram también necesitan `*.blockStreaming: true`.
|
||||
- **Transmitir todo al final:** `blockStreamingBreak: "message_end"` (vaciar una vez, posiblemente en varios fragmentos si es muy largo).
|
||||
- **Sin streaming de bloques:** `blockStreamingDefault: "off"` (solo respuesta final).
|
||||
|
||||
**Nota sobre canales:** El streaming de bloques está **desactivado salvo que**
|
||||
`*.blockStreaming` se establezca explícitamente en `true`. Los canales pueden transmitir una vista previa en vivo (`channels.<channel>.streaming`) sin respuestas por bloques.
|
||||
**Nota de canal:** El streaming de bloques está **desactivado salvo que** `*.blockStreaming` esté establecido explícitamente en `true`. Los canales pueden transmitir una vista previa en vivo (`channels.<channel>.streaming`) sin respuestas por bloques.
|
||||
|
||||
Recordatorio de ubicación de configuración: los valores predeterminados de `blockStreaming*` viven bajo `agents.defaults`, no en la configuración raíz.
|
||||
Recordatorio de ubicación de configuración: los valores predeterminados de `blockStreaming*` están bajo `agents.defaults`, no en la configuración raíz.
|
||||
|
||||
## Modos de streaming de vista previa
|
||||
|
||||
@ -114,14 +113,14 @@ Clave canónica: `channels.<channel>.streaming`
|
||||
|
||||
Modos:
|
||||
|
||||
- `off`: desactiva el streaming de vista previa.
|
||||
- `partial`: vista previa única que se reemplaza con el texto más reciente.
|
||||
- `block`: la vista previa se actualiza en pasos fragmentados/agregados.
|
||||
- `progress`: vista previa de progreso/estado durante la generación, respuesta final al completarse.
|
||||
- `off`: deshabilita el streaming de vista previa.
|
||||
- `partial`: una única vista previa que se reemplaza con el texto más reciente.
|
||||
- `block`: la vista previa se actualiza en pasos fragmentados/anexados.
|
||||
- `progress`: vista previa de progreso/estado durante la generación, respuesta final al completar.
|
||||
|
||||
`streaming.mode: "block"` es un modo de streaming de vista previa para canales con capacidad de edición como Discord y Telegram. No habilita allí la entrega de bloques del canal. Usa `streaming.block.enabled` o la clave de canal heredada `blockStreaming` cuando quieras respuestas normales por bloques. Microsoft Teams es la excepción: no tiene transporte de bloques de borrador/vista previa, por lo que `streaming.mode: "block"` se asigna a la entrega de bloques de Teams en lugar de streaming parcial/de progreso nativo.
|
||||
`streaming.mode: "block"` es un modo de streaming de vista previa para canales con capacidad de edición como Discord y Telegram. No habilita allí la entrega de bloques de canal. Usa `streaming.block.enabled` o la clave de canal heredada `blockStreaming` cuando quieras respuestas por bloques normales. Microsoft Teams es la excepción: no tiene transporte de bloques de vista previa de borrador, por lo que `streaming.mode: "block"` se asigna a la entrega de bloques de Teams en lugar de streaming parcial/progreso nativo.
|
||||
|
||||
### Mapeo de canales
|
||||
### Asignación por canal
|
||||
|
||||
| Canal | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ----------------------- |
|
||||
@ -133,65 +132,65 @@ Modos:
|
||||
|
||||
Solo Slack:
|
||||
|
||||
- `channels.slack.streaming.nativeTransport` alterna las llamadas a la API de streaming nativo de Slack cuando `channels.slack.streaming.mode="partial"` (predeterminado: `true`).
|
||||
- El streaming nativo de Slack y el estado de hilo de asistente de Slack requieren un destino de hilo de respuesta. Los DM de nivel superior no muestran esa vista previa con estilo de hilo, pero aún pueden usar publicaciones de vista previa de borrador de Slack y ediciones.
|
||||
- `channels.slack.streaming.nativeTransport` alterna las llamadas a la API de streaming nativa de Slack cuando `channels.slack.streaming.mode="partial"` (predeterminado: `true`).
|
||||
- El streaming nativo de Slack y el estado de hilo de asistente de Slack requieren un destino de hilo de respuesta. Los mensajes directos de nivel superior no muestran esa vista previa con estilo de hilo, pero aun así pueden usar publicaciones y ediciones de vista previa de borrador de Slack.
|
||||
|
||||
Migración de claves heredadas:
|
||||
|
||||
- Telegram: los valores heredados `streamMode` y escalares/booleanos de `streaming` se detectan y migran mediante rutas de compatibilidad de doctor/config a `streaming.mode`.
|
||||
- Discord: `streamMode` + `streaming` booleano se migran automáticamente al enum `streaming`.
|
||||
- Slack: `streamMode` se migra automáticamente a `streaming.mode`; `streaming` booleano se migra automáticamente a `streaming.mode` más `streaming.nativeTransport`; `nativeStreaming` heredado se migra automáticamente a `streaming.nativeTransport`.
|
||||
- Telegram: los valores heredados `streamMode` y los valores escalares/booleanos `streaming` se detectan y migran mediante rutas de compatibilidad de doctor/config a `streaming.mode`.
|
||||
- Discord: `streamMode` + `streaming` booleano migran automáticamente al enum `streaming`.
|
||||
- Slack: `streamMode` migra automáticamente a `streaming.mode`; `streaming` booleano migra automáticamente a `streaming.mode` más `streaming.nativeTransport`; `nativeStreaming` heredado migra automáticamente a `streaming.nativeTransport`.
|
||||
|
||||
### Comportamiento en tiempo de ejecución
|
||||
|
||||
Telegram:
|
||||
|
||||
- Usa `sendMessage` + actualizaciones de vista previa con `editMessageText` en DM y grupos/temas.
|
||||
- Envía un mensaje final nuevo en lugar de editar en el mismo lugar cuando una vista previa ha estado visible durante aproximadamente un minuto, y luego limpia la vista previa para que la marca de tiempo de Telegram refleje la finalización de la respuesta.
|
||||
- Usa `sendMessage` + actualizaciones de vista previa con `editMessageText` en mensajes directos y grupos/temas.
|
||||
- Envía un mensaje final nuevo en lugar de editar en el mismo lugar cuando una vista previa ha estado visible durante alrededor de un minuto, y luego limpia la vista previa para que la marca de tiempo de Telegram refleje la finalización de la respuesta.
|
||||
- El streaming de vista previa se omite cuando el streaming de bloques de Telegram está habilitado explícitamente (para evitar doble streaming).
|
||||
- `/reasoning stream` puede escribir razonamiento en la vista previa.
|
||||
- `/reasoning stream` puede escribir razonamiento en una vista previa transitoria que se elimina después de la entrega final.
|
||||
|
||||
Discord:
|
||||
|
||||
- Usa mensajes de vista previa con envío + edición.
|
||||
- Usa mensajes de vista previa de envío + edición.
|
||||
- El modo `block` usa fragmentación de borrador (`draftChunk`).
|
||||
- El streaming de vista previa se omite cuando el streaming de bloques de Discord está habilitado explícitamente.
|
||||
- Los medios finales, errores y cargas de respuesta explícita cancelan vistas previas pendientes sin vaciar un borrador nuevo, y luego usan la entrega normal.
|
||||
- Las cargas finales de medios, errores y respuestas explícitas cancelan las vistas previas pendientes sin vaciar un borrador nuevo, y luego usan la entrega normal.
|
||||
|
||||
Slack:
|
||||
|
||||
- `partial` puede usar streaming nativo de Slack (`chat.startStream`/`append`/`stop`) cuando está disponible.
|
||||
- `block` usa vistas previas de borrador con estilo de adición.
|
||||
- `progress` usa texto de vista previa de estado, luego la respuesta final.
|
||||
- Los DM de nivel superior sin hilo de respuesta usan publicaciones de vista previa de borrador y ediciones en lugar de streaming nativo de Slack.
|
||||
- El streaming nativo y de vista previa de borrador suprimen las respuestas por bloques para ese turno, por lo que una respuesta de Slack se transmite por una sola ruta de entrega.
|
||||
- `block` usa vistas previas de borrador de estilo anexo.
|
||||
- `progress` usa texto de vista previa de estado y luego la respuesta final.
|
||||
- Los mensajes directos de nivel superior sin un hilo de respuesta usan publicaciones y ediciones de vista previa de borrador en lugar de streaming nativo de Slack.
|
||||
- El streaming de vista previa nativo y de borrador suprime las respuestas por bloques para ese turno, por lo que una respuesta de Slack se transmite por una sola ruta de entrega.
|
||||
- Las cargas finales de medios/error y los finales de progreso no crean mensajes de borrador desechables; solo los finales de texto/bloque que pueden editar la vista previa vacían el texto de borrador pendiente.
|
||||
|
||||
Mattermost:
|
||||
|
||||
- Transmite pensamiento, actividad de herramientas y texto parcial de respuesta en una sola publicación de vista previa de borrador que se finaliza en el mismo lugar cuando la respuesta final es segura para enviar.
|
||||
- Recurre al envío de una publicación final nueva si la publicación de vista previa se eliminó o no está disponible al momento de finalizar.
|
||||
- Las cargas finales de medios/error cancelan las actualizaciones de vista previa pendientes antes de la entrega normal, en lugar de vaciar una publicación de vista previa temporal.
|
||||
- Recurre a enviar una publicación final nueva si la publicación de vista previa se eliminó o no está disponible al momento de finalizar.
|
||||
- Las cargas finales de medios/error cancelan las actualizaciones de vista previa pendientes antes de la entrega normal en lugar de vaciar una publicación de vista previa temporal.
|
||||
|
||||
Matrix:
|
||||
|
||||
- Las vistas previas de borrador se finalizan en el mismo lugar cuando el texto final puede reutilizar el evento de vista previa.
|
||||
- Los finales solo de medios, errores y con discrepancia de destino de respuesta cancelan las actualizaciones de vista previa pendientes antes de la entrega normal; una vista previa obsoleta que ya está visible se redacta.
|
||||
- Los finales solo multimedia, de error y con discrepancia de destino de respuesta cancelan las actualizaciones de vista previa pendientes antes de la entrega normal; una vista previa obsoleta ya visible se redacta.
|
||||
|
||||
### Actualizaciones de vista previa de progreso de herramientas
|
||||
|
||||
El streaming de vista previa también puede incluir actualizaciones de **progreso de herramientas**: líneas de estado breves como "buscando en la web", "leyendo archivo" o "llamando herramienta", que aparecen en el mismo mensaje de vista previa mientras las herramientas se ejecutan, antes de la respuesta final. Esto mantiene visualmente vivos los turnos de herramientas de varios pasos, en lugar de dejarlos en silencio entre la primera vista previa de pensamiento y la respuesta final.
|
||||
El streaming de vista previa también puede incluir actualizaciones de **progreso de herramientas**: líneas de estado breves como "buscando en la web", "leyendo archivo" o "llamando herramienta", que aparecen en el mismo mensaje de vista previa mientras las herramientas se ejecutan, antes de la respuesta final. Esto mantiene visualmente vivos los turnos de herramientas de varios pasos en lugar de silenciosos entre la primera vista previa de pensamiento y la respuesta final.
|
||||
|
||||
Superficies admitidas:
|
||||
Superficies compatibles:
|
||||
|
||||
- **Discord**, **Slack**, **Telegram** y **Matrix** transmiten progreso de herramientas en la edición de vista previa en vivo de forma predeterminada cuando el streaming de vista previa está activo. Microsoft Teams usa su stream de progreso nativo en chats personales.
|
||||
- Telegram se lanzó con actualizaciones de vista previa de progreso de herramientas habilitadas desde `v2026.4.22`; mantenerlas habilitadas conserva ese comportamiento publicado.
|
||||
- **Discord**, **Slack**, **Telegram** y **Matrix** transmiten el progreso de herramientas a la edición de vista previa en vivo de forma predeterminada cuando el streaming de vista previa está activo. Microsoft Teams usa su stream de progreso nativo en chats personales.
|
||||
- Telegram se ha publicado con actualizaciones de vista previa de progreso de herramientas habilitadas desde `v2026.4.22`; mantenerlas habilitadas preserva ese comportamiento publicado.
|
||||
- **Mattermost** ya integra la actividad de herramientas en su única publicación de vista previa de borrador (ver arriba).
|
||||
- Las ediciones de progreso de herramientas siguen el modo de streaming de vista previa activo; se omiten cuando el streaming de vista previa está `off` o cuando el streaming de bloques ha tomado el control del mensaje. En Telegram, `streaming.mode: "off"` es solo final: la charla de progreso genérica también se suprime en lugar de entregarse como mensajes de estado independientes, mientras que las solicitudes de aprobación, las cargas multimedia y los errores siguen enrutándose normalmente.
|
||||
- Para mantener el streaming de vista previa pero ocultar las líneas de progreso de herramientas, establece `streaming.preview.toolProgress` en `false` para ese canal. Para desactivar por completo las ediciones de vista previa, establece `streaming.mode` en `off`.
|
||||
- Las respuestas de cita seleccionada de Telegram son una excepción: cuando `replyToMode` no es `"off"` y hay texto de cita seleccionada, OpenClaw omite el stream de vista previa de la respuesta para ese turno, por lo que las líneas de vista previa de progreso de herramientas no pueden renderizarse. Las respuestas al mensaje actual sin texto de cita seleccionada siguen manteniendo el streaming de vista previa. Consulta la [documentación del canal Telegram](/es/channels/telegram) para obtener detalles.
|
||||
- Las ediciones de progreso de herramientas siguen el modo de streaming de vista previa activo; se omiten cuando el streaming de vista previa está `off` o cuando el streaming de bloques se ha hecho cargo del mensaje. En Telegram, `streaming.mode: "off"` es solo final: la charla genérica de progreso también se suprime en lugar de entregarse como mensajes de estado independientes, mientras que las solicitudes de aprobación, las cargas multimedia y los errores siguen enrutándose normalmente.
|
||||
- Para mantener el streaming de vista previa pero ocultar las líneas de progreso de herramientas, establece `streaming.preview.toolProgress` en `false` para ese canal. Para mantener visibles las líneas de progreso de herramientas mientras ocultas el texto de comando/ejecución, establece `streaming.preview.commandText` en `"status"` o `streaming.progress.commandText` en `"status"`; el valor predeterminado es `"raw"` para preservar el comportamiento publicado. Esta política la comparten los canales de borrador/progreso que usan el renderizador compacto de progreso de OpenClaw, incluidos Discord, Matrix, Microsoft Teams, Mattermost, vistas previas de borrador de Slack y Telegram. Para deshabilitar completamente las ediciones de vista previa, establece `streaming.mode` en `off`.
|
||||
- Las respuestas con cita seleccionada de Telegram son una excepción: cuando `replyToMode` no es `"off"` y hay texto de cita seleccionada presente, OpenClaw omite el stream de vista previa de respuesta para ese turno, por lo que las líneas de vista previa de progreso de herramientas no pueden renderizarse. Las respuestas al mensaje actual sin texto de cita seleccionada siguen manteniendo el streaming de vista previa. Consulta la [documentación del canal de Telegram](/es/channels/telegram) para obtener detalles.
|
||||
|
||||
Ejemplo:
|
||||
Mantén visibles las líneas de progreso, pero oculta el texto sin procesar de comandos/ejecución:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -200,7 +199,26 @@ Ejemplo:
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"toolProgress": false
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Usa la misma estructura bajo otra clave de canal de progreso compacto, por ejemplo `channels.discord`, `channels.matrix`, `channels.msteams`, `channels.mattermost` o las vistas previas de borradores de Slack. Para el modo de borrador de progreso, coloca la misma política bajo `streaming.progress`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -213,4 +231,4 @@ Ejemplo:
|
||||
- [Borradores de progreso](/es/concepts/progress-drafts) — mensajes visibles de trabajo en curso que se actualizan durante turnos largos
|
||||
- [Mensajes](/es/concepts/messages) — ciclo de vida y entrega de mensajes
|
||||
- [Reintento](/es/concepts/retry) — comportamiento de reintento ante fallos de entrega
|
||||
- [Canales](/es/channels) — soporte de streaming por canal
|
||||
- [Canales](/es/channels) — compatibilidad de streaming por canal
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Actualizar OpenClaw
|
||||
- Algo deja de funcionar después de una actualización
|
||||
summary: Actualizar OpenClaw de forma segura (instalación global o desde el código fuente), además de estrategia de reversión
|
||||
- Algo se rompe después de una actualización
|
||||
summary: Actualizar OpenClaw de forma segura (instalación global o desde el código fuente), junto con una estrategia de reversión
|
||||
title: Actualización
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:35:01Z"
|
||||
generated_at: "2026-05-04T07:02:55Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f9e26ea71748dfd1573cdca01126bf29ebc56be56eac604e2b6a009b463820d1
|
||||
source_hash: 3c9ff1d70d74f45efea3c148718e5cbc74001ce3d924b760edc4d68622d23714
|
||||
source_path: install/updating.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -33,21 +33,21 @@ openclaw update --dry-run # preview without applying
|
||||
```
|
||||
|
||||
`openclaw update` no acepta `--verbose`. Para diagnósticos de actualización, usa
|
||||
`--dry-run` para previsualizar las acciones planificadas, `--json` para resultados estructurados, o
|
||||
`openclaw update status --json` para inspeccionar el canal y el estado de disponibilidad. El
|
||||
`--dry-run` para previsualizar las acciones planificadas, `--json` para obtener resultados estructurados o
|
||||
`openclaw update status --json` para inspeccionar el estado del canal y la disponibilidad. El
|
||||
instalador tiene su propia marca `--verbose`, pero esa marca no forma parte de
|
||||
`openclaw update`.
|
||||
|
||||
`--channel beta` prefiere beta, pero el runtime recurre a stable/latest cuando
|
||||
falta la etiqueta beta o es más antigua que la versión estable más reciente. Usa `--tag beta`
|
||||
si quieres el dist-tag beta sin procesar de npm para una actualización puntual del paquete.
|
||||
falta la etiqueta beta o es anterior a la versión estable más reciente. Usa `--tag beta`
|
||||
si quieres el dist-tag beta sin procesar de npm para una actualización puntual de paquete.
|
||||
|
||||
Consulta [Canales de desarrollo](/es/install/development-channels) para la semántica de los canales.
|
||||
Consulta [Canales de desarrollo](/es/install/development-channels) para conocer la semántica de los canales.
|
||||
|
||||
## Cambiar entre instalaciones npm y git
|
||||
|
||||
Usa canales cuando quieras cambiar el tipo de instalación. El actualizador conserva tu
|
||||
estado, configuración, credenciales y área de trabajo en `~/.openclaw`; solo cambia
|
||||
estado, configuración, credenciales y workspace en `~/.openclaw`; solo cambia
|
||||
qué instalación de código de OpenClaw usan la CLI y el Gateway.
|
||||
|
||||
```bash
|
||||
@ -58,7 +58,7 @@ openclaw update --channel dev
|
||||
openclaw update --channel stable
|
||||
```
|
||||
|
||||
Ejecútalo primero con `--dry-run` para previsualizar el cambio exacto de modo de instalación:
|
||||
Ejecuta primero con `--dry-run` para previsualizar el cambio exacto de modo de instalación:
|
||||
|
||||
```bash
|
||||
openclaw update --channel dev --dry-run
|
||||
@ -76,19 +76,19 @@ y lo reinicia, salvo que pases `--no-restart`.
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
Añade `--no-onboard` para omitir la incorporación. Para forzar un tipo de instalación específico mediante
|
||||
Añade `--no-onboard` para omitir el onboarding. Para forzar un tipo de instalación específico mediante
|
||||
el instalador, pasa `--install-method git --no-onboard` o
|
||||
`--install-method npm --no-onboard`.
|
||||
|
||||
Si `openclaw update` falla después de la fase de instalación del paquete npm, vuelve a ejecutar el
|
||||
instalador. El instalador no llama al actualizador antiguo; ejecuta directamente la instalación del
|
||||
paquete global y puede recuperar una instalación npm parcialmente actualizada.
|
||||
instalador. El instalador no llama al actualizador anterior; ejecuta directamente la instalación
|
||||
del paquete global y puede recuperar una instalación npm parcialmente actualizada.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
|
||||
```
|
||||
|
||||
Para fijar la recuperación a una versión o dist-tag específicos, añade `--version`:
|
||||
Para fijar la recuperación a una versión o dist-tag específico, añade `--version`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
|
||||
@ -100,12 +100,17 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --ve
|
||||
npm i -g openclaw@latest
|
||||
```
|
||||
|
||||
Prefiere `openclaw update` para instalaciones supervisadas porque puede coordinar el
|
||||
cambio de paquete con el servicio Gateway en ejecución. Si actualizas manualmente mientras se
|
||||
ejecuta un Gateway gestionado, reinicia el Gateway inmediatamente después de que termine el gestor de paquetes
|
||||
para que el proceso anterior no siga sirviendo desde archivos de paquete reemplazados.
|
||||
|
||||
Cuando `openclaw update` gestiona una instalación npm global, primero instala el destino en
|
||||
un prefijo npm temporal, verifica el inventario `dist` empaquetado y luego intercambia
|
||||
el árbol de paquetes limpio al prefijo global real. Eso evita que npm superponga un
|
||||
el árbol de paquetes limpio en el prefijo global real. Eso evita que npm superponga un
|
||||
paquete nuevo sobre archivos obsoletos del paquete anterior. Si el comando de instalación falla,
|
||||
OpenClaw lo reintenta una vez con `--omit=optional`. Ese reintento ayuda en hosts donde las
|
||||
dependencias opcionales nativas no pueden compilarse, al tiempo que mantiene visible el fallo original
|
||||
OpenClaw reintenta una vez con `--omit=optional`. Ese reintento ayuda en hosts donde las
|
||||
dependencias opcionales nativas no pueden compilarse, mientras mantiene visible el fallo original
|
||||
si la alternativa también falla.
|
||||
|
||||
```bash
|
||||
@ -119,22 +124,22 @@ bun add -g openclaw@latest
|
||||
### Temas avanzados de instalación npm
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Árbol de paquetes de solo lectura">
|
||||
OpenClaw trata las instalaciones globales empaquetadas como de solo lectura en runtime, incluso cuando el directorio global de paquetes es escribible por el usuario actual. Las instalaciones de paquetes de Plugin viven en raíces npm/git propiedad de OpenClaw bajo el directorio de configuración del usuario, y el inicio del Gateway no muta el árbol de paquetes de OpenClaw.
|
||||
<Accordion title="Read-only package tree">
|
||||
OpenClaw trata las instalaciones globales empaquetadas como de solo lectura en runtime, incluso cuando el directorio global de paquetes es escribible por el usuario actual. Las instalaciones de paquetes de Plugin viven en raíces npm/git propiedad de OpenClaw bajo el directorio de configuración del usuario, y el inicio del Gateway no modifica el árbol de paquetes de OpenClaw.
|
||||
|
||||
Algunas configuraciones npm de Linux instalan paquetes globales bajo directorios propiedad de root, como `/usr/lib/node_modules/openclaw`. OpenClaw admite ese diseño porque los comandos de instalación/actualización de Plugin escriben fuera de ese directorio global de paquetes.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Unidades systemd reforzadas">
|
||||
Concede a OpenClaw acceso de escritura a sus raíces de configuración/estado para que las instalaciones explícitas de Plugin, las actualizaciones de Plugin y la limpieza de doctor puedan persistir sus cambios:
|
||||
<Accordion title="Hardened systemd units">
|
||||
Da a OpenClaw acceso de escritura a sus raíces de configuración/estado para que las instalaciones explícitas de Plugin, las actualizaciones de Plugin y la limpieza de doctor puedan persistir sus cambios:
|
||||
|
||||
```ini
|
||||
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Comprobación previa de espacio en disco">
|
||||
Antes de las actualizaciones de paquetes y las instalaciones explícitas de Plugin, OpenClaw intenta una comprobación de espacio en disco de mejor esfuerzo para el volumen de destino. El espacio bajo produce una advertencia con la ruta comprobada, pero no bloquea la actualización porque las cuotas del sistema de archivos, las instantáneas y los volúmenes de red pueden cambiar después de la comprobación. La instalación real del gestor de paquetes y la verificación posterior a la instalación siguen siendo autoritativas.
|
||||
<Accordion title="Disk-space preflight">
|
||||
Antes de las actualizaciones de paquetes y las instalaciones explícitas de Plugin, OpenClaw intenta una comprobación de espacio en disco de mejor esfuerzo para el volumen de destino. Poco espacio produce una advertencia con la ruta comprobada, pero no bloquea la actualización porque las cuotas del sistema de archivos, las snapshots y los volúmenes de red pueden cambiar después de la comprobación. La instalación real del gestor de paquetes y la verificación posterior a la instalación siguen siendo la autoridad.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -157,18 +162,18 @@ El actualizador automático está desactivado de forma predeterminada. Actívalo
|
||||
```
|
||||
|
||||
| Canal | Comportamiento |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Espera `stableDelayHours` y luego aplica con jitter determinista a lo largo de `stableJitterHours` (despliegue distribuido). |
|
||||
| `beta` | Comprueba cada `betaCheckIntervalHours` (predeterminado: cada hora) y aplica de inmediato. |
|
||||
| `dev` | Sin aplicación automática. Usa `openclaw update` manualmente. |
|
||||
| -------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Espera `stableDelayHours` y luego aplica con jitter determinista durante `stableJitterHours` (despliegue distribuido). |
|
||||
| `beta` | Comprueba cada `betaCheckIntervalHours` (predeterminado: cada hora) y aplica inmediatamente. |
|
||||
| `dev` | Sin aplicación automática. Usa `openclaw update` manualmente. |
|
||||
|
||||
El Gateway también registra una sugerencia de actualización al iniciar (desactívala con `update.checkOnStart: false`).
|
||||
Para una degradación de versión o recuperación ante incidentes, configura `OPENCLAW_NO_AUTO_UPDATE=1` en el entorno del Gateway para bloquear las aplicaciones automáticas incluso cuando `update.auto.enabled` esté configurado. Las sugerencias de actualización al inicio aún pueden ejecutarse salvo que `update.checkOnStart` también esté desactivado.
|
||||
Para recuperación ante downgrade o incidente, define `OPENCLAW_NO_AUTO_UPDATE=1` en el entorno del Gateway para bloquear las aplicaciones automáticas aunque `update.auto.enabled` esté configurado. Las sugerencias de actualización al iniciar aún pueden ejecutarse salvo que `update.checkOnStart` también esté desactivado.
|
||||
|
||||
Las actualizaciones del gestor de paquetes solicitadas mediante el manejador del plano de control del Gateway en vivo
|
||||
fuerzan un reinicio de actualización sin diferimiento ni enfriamiento después del intercambio de paquetes. Eso
|
||||
evita dejar un proceso antiguo en memoria durante suficiente tiempo como para cargar perezosamente fragmentos
|
||||
desde un árbol de paquetes que ya ha sido reemplazado. El `openclaw update` de shell
|
||||
Las actualizaciones del gestor de paquetes solicitadas a través del handler en vivo del plano de control del Gateway
|
||||
fuerzan un reinicio de actualización sin diferimiento ni cooldown después del intercambio de paquetes. Eso
|
||||
evita dejar un proceso antiguo en memoria el tiempo suficiente para cargar de forma diferida chunks
|
||||
desde un árbol de paquetes que ya se reemplazó. El shell `openclaw update`
|
||||
sigue siendo la ruta preferida para instalaciones supervisadas porque puede detener y
|
||||
reiniciar el servicio alrededor de la actualización.
|
||||
|
||||
@ -221,17 +226,17 @@ pnpm install && pnpm build
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Para volver a la versión más reciente: `git checkout main && git pull`.
|
||||
Para volver a la más reciente: `git checkout main && git pull`.
|
||||
|
||||
## Si te quedas bloqueado
|
||||
|
||||
- Ejecuta `openclaw doctor` de nuevo y lee la salida con atención.
|
||||
- Para `openclaw update --channel dev` en checkouts de código fuente, el actualizador inicia automáticamente `pnpm` cuando es necesario. Si ves un error de bootstrap de pnpm/corepack, instala `pnpm` manualmente (o vuelve a activar `corepack`) y vuelve a ejecutar la actualización.
|
||||
- Revisa: [Solución de problemas](/es/gateway/troubleshooting)
|
||||
- Ejecuta `openclaw doctor` otra vez y lee cuidadosamente la salida.
|
||||
- Para `openclaw update --channel dev` en checkouts de código fuente, el actualizador autoarranca `pnpm` cuando hace falta. Si ves un error de arranque de pnpm/corepack, instala `pnpm` manualmente (o vuelve a activar `corepack`) y ejecuta de nuevo la actualización.
|
||||
- Consulta: [Solución de problemas](/es/gateway/troubleshooting)
|
||||
- Pregunta en Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Resumen de instalación](/es/install): todos los métodos de instalación.
|
||||
- [Doctor](/es/gateway/doctor): comprobaciones de salud después de las actualizaciones.
|
||||
- [Migración](/es/install/migrating): guías de migración de versiones principales.
|
||||
- [Migración](/es/install/migrating): guías de migración de versiones mayores.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,31 +1,31 @@
|
||||
---
|
||||
read_when:
|
||||
- Quieres usar texto a voz de ElevenLabs en OpenClaw
|
||||
- Quieres usar el reconocimiento de voz a texto Scribe de ElevenLabs para archivos adjuntos de audio
|
||||
- Quieres usar la transcripción en tiempo real de ElevenLabs para Voice Call
|
||||
- Quieres usar la conversión de texto a voz de ElevenLabs en OpenClaw
|
||||
- Quieres la conversión de voz a texto de ElevenLabs Scribe para los archivos adjuntos de audio
|
||||
- Quieres la transcripción en tiempo real de ElevenLabs para Llamada de voz o Google Meet
|
||||
summary: Usa la voz de ElevenLabs, Scribe STT y la transcripción en tiempo real con OpenClaw
|
||||
title: ElevenLabs
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T13:54:56Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T07:03:51Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a
|
||||
source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b
|
||||
source_path: providers/elevenlabs.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw usa ElevenLabs para texto a voz, voz a texto por lotes con Scribe
|
||||
v2 y STT en streaming para Voice Call con Scribe v2 Realtime.
|
||||
v2 y STT en streaming con Scribe v2 Realtime.
|
||||
|
||||
| Capacidad | Superficie de OpenClaw | Predeterminado |
|
||||
| ----------------------- | --------------------------------------------- | ------------------------ |
|
||||
| Texto a voz | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Voz a texto por lotes | `tools.media.audio` | `scribe_v2` |
|
||||
| Voz a texto en streaming | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` |
|
||||
| Capacidad | Superficie de OpenClaw | Predeterminado |
|
||||
| ------------------------ | -------------------------------------------------------------------- | ------------------------ |
|
||||
| Texto a voz | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Voz a texto por lotes | `tools.media.audio` | `scribe_v2` |
|
||||
| Voz a texto en streaming | Streaming de Voice Call o `realtime.transcriptionProvider` de Google Meet | `scribe_v2_realtime` |
|
||||
|
||||
## Autenticación
|
||||
|
||||
Establece `ELEVENLABS_API_KEY` en el entorno. `XI_API_KEY` también se acepta por
|
||||
Define `ELEVENLABS_API_KEY` en el entorno. `XI_API_KEY` también se acepta por
|
||||
compatibilidad con las herramientas existentes de ElevenLabs.
|
||||
|
||||
```bash
|
||||
@ -50,12 +50,12 @@ export ELEVENLABS_API_KEY="..."
|
||||
}
|
||||
```
|
||||
|
||||
Establece `modelId` en `eleven_v3` para usar TTS v3 de ElevenLabs. OpenClaw mantiene
|
||||
`eleven_multilingual_v2` como valor predeterminado para las instalaciones existentes.
|
||||
Define `modelId` como `eleven_v3` para usar TTS v3 de ElevenLabs. OpenClaw mantiene
|
||||
`eleven_multilingual_v2` como predeterminado para las instalaciones existentes.
|
||||
|
||||
## Voz a texto
|
||||
|
||||
Usa Scribe v2 para archivos adjuntos de audio entrantes y segmentos cortos de voz grabada:
|
||||
Usa Scribe v2 para archivos adjuntos de audio entrante y segmentos cortos de voz grabada:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -70,22 +70,22 @@ Usa Scribe v2 para archivos adjuntos de audio entrantes y segmentos cortos de vo
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw envía audio multiparte a ElevenLabs `/v1/speech-to-text` con
|
||||
OpenClaw envía audio multipart a `/v1/speech-to-text` de ElevenLabs con
|
||||
`model_id: "scribe_v2"`. Las sugerencias de idioma se asignan a `language_code` cuando están presentes.
|
||||
|
||||
## STT en streaming para Voice Call
|
||||
## STT en streaming
|
||||
|
||||
El Plugin `elevenlabs` incluido registra Scribe v2 Realtime para la
|
||||
transcripción en streaming de Voice Call.
|
||||
El Plugin `elevenlabs` incluido registra Scribe v2 Realtime para la transcripción
|
||||
en streaming de Voice Call y Google Meet en modo agente.
|
||||
|
||||
| Ajuste | Ruta de configuración | Predeterminado |
|
||||
| ----------------- | ------------------------------------------------------------------------ | -------------------------------------------------- |
|
||||
| Clave API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Usa `ELEVENLABS_API_KEY` / `XI_API_KEY` como respaldo |
|
||||
| Modelo | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Formato de audio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Frecuencia de muestreo | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Estrategia de confirmación | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Idioma | `...elevenlabs.languageCode` | (sin establecer) |
|
||||
| Ajuste | Ruta de configuración | Predeterminado |
|
||||
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| Clave de API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Recurre a `ELEVENLABS_API_KEY` / `XI_API_KEY` |
|
||||
| Modelo | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Formato de audio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Frecuencia de muestreo | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Estrategia de confirmación | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Idioma | `...elevenlabs.languageCode` | (sin definir) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,12 +113,18 @@ transcripción en streaming de Voice Call.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Voice Call recibe medios de Twilio como G.711 u-law de 8 kHz. El proveedor en tiempo real de ElevenLabs
|
||||
usa `ulaw_8000` de forma predeterminada, por lo que los fotogramas de telefonía pueden reenviarse sin
|
||||
Voice Call recibe medios de Twilio como G.711 u-law a 8 kHz. El proveedor en tiempo real
|
||||
de ElevenLabs usa `ulaw_8000` de forma predeterminada, por lo que los marcos de telefonía se pueden reenviar sin
|
||||
transcodificación.
|
||||
</Note>
|
||||
|
||||
Para el modo agente de Google Meet, define
|
||||
`plugins.entries.google-meet.config.realtime.transcriptionProvider` como
|
||||
`"elevenlabs"` y configura el mismo bloque de proveedor en
|
||||
`plugins.entries.google-meet.config.realtime.providers.elevenlabs`.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Texto a voz](/es/tools/tts)
|
||||
- [Selección de modelo](/es/concepts/model-providers)
|
||||
- [Google Meet](/es/plugins/google-meet)
|
||||
- [Selección de modelos](/es/concepts/model-providers)
|
||||
|
||||
@ -3,255 +3,174 @@ read_when:
|
||||
- Buscando definiciones de canales de lanzamiento públicos
|
||||
- Ejecutar la validación de lanzamiento o la aceptación de paquetes
|
||||
- Buscando la nomenclatura y la cadencia de versiones
|
||||
summary: Canales de lanzamiento, lista de verificación del operador, cajas de validación, nomenclatura de versiones y cadencia
|
||||
title: Política de lanzamientos
|
||||
summary: Canales de lanzamiento, lista de verificación del operador, entornos de validación, nomenclatura de versiones y cadencia
|
||||
title: Política de lanzamiento
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:36:58Z"
|
||||
generated_at: "2026-05-04T07:04:05Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba
|
||||
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
|
||||
source_path: reference/RELEASING.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw tiene tres canales públicos de publicación:
|
||||
OpenClaw tiene tres vías de lanzamiento públicas:
|
||||
|
||||
- stable: publicaciones etiquetadas que se publican en npm `beta` de forma predeterminada, o en npm `latest` cuando se solicita explícitamente
|
||||
- beta: etiquetas de versión preliminar que se publican en npm `beta`
|
||||
- dev: la cabecera móvil de `main`
|
||||
- stable: lanzamientos etiquetados que publican en npm `beta` de forma predeterminada, o en npm `latest` cuando se solicita explícitamente
|
||||
- beta: etiquetas de prelanzamiento que publican en npm `beta`
|
||||
- dev: la cabeza móvil de `main`
|
||||
|
||||
## Nomenclatura de versiones
|
||||
|
||||
- Versión de publicación estable: `YYYY.M.D`
|
||||
- Versión de lanzamiento estable: `YYYY.M.D`
|
||||
- Etiqueta de Git: `vYYYY.M.D`
|
||||
- Versión de corrección estable: `YYYY.M.D-N`
|
||||
- Versión de lanzamiento de corrección estable: `YYYY.M.D-N`
|
||||
- Etiqueta de Git: `vYYYY.M.D-N`
|
||||
- Versión preliminar beta: `YYYY.M.D-beta.N`
|
||||
- Versión de prelanzamiento beta: `YYYY.M.D-beta.N`
|
||||
- Etiqueta de Git: `vYYYY.M.D-beta.N`
|
||||
- No rellenes con ceros el mes ni el día
|
||||
- `latest` significa la publicación estable actual promocionada en npm
|
||||
- No agregues ceros a la izquierda al mes ni al día
|
||||
- `latest` significa el lanzamiento estable actual promovido en npm
|
||||
- `beta` significa el destino actual de instalación beta
|
||||
- Las publicaciones estables y de corrección estable se publican en npm `beta` de forma predeterminada; los operadores de publicación pueden dirigirlas explícitamente a `latest`, o promocionar más tarde una compilación beta revisada
|
||||
- Cada publicación estable de OpenClaw entrega el paquete npm y la app de macOS juntos;
|
||||
las publicaciones beta normalmente validan y publican primero la ruta de npm/paquete, con
|
||||
- Los lanzamientos estables y de corrección estable publican en npm `beta` de forma predeterminada; los operadores de lanzamiento pueden apuntar explícitamente a `latest`, o promover más adelante una compilación beta revisada
|
||||
- Cada lanzamiento estable de OpenClaw distribuye juntos el paquete npm y la app de macOS;
|
||||
los lanzamientos beta normalmente validan y publican primero la ruta npm/paquete, con
|
||||
la compilación/firma/notarización de la app de Mac reservada para estable salvo que se solicite explícitamente
|
||||
|
||||
## Cadencia de publicación
|
||||
## Cadencia de lanzamiento
|
||||
|
||||
- Las publicaciones avanzan primero por beta
|
||||
- Estable viene solo después de validar la beta más reciente
|
||||
- Los mantenedores normalmente cortan publicaciones desde una rama `release/YYYY.M.D` creada
|
||||
desde el `main` actual, para que la validación y las correcciones de publicación no bloqueen el nuevo
|
||||
- Los lanzamientos avanzan primero por beta
|
||||
- Estable sigue solo después de validar la beta más reciente
|
||||
- Los mantenedores normalmente cortan lanzamientos desde una rama `release/YYYY.M.D` creada
|
||||
a partir del `main` actual, para que la validación y las correcciones del lanzamiento no bloqueen el nuevo
|
||||
desarrollo en `main`
|
||||
- Si una etiqueta beta se ha enviado o publicado y necesita una corrección, los mantenedores cortan
|
||||
la siguiente etiqueta `-beta.N` en lugar de eliminar o recrear la etiqueta beta anterior
|
||||
- El procedimiento detallado de publicación, aprobaciones, credenciales y notas de recuperación es
|
||||
- El procedimiento detallado de lanzamiento, las aprobaciones, credenciales y notas de recuperación son
|
||||
solo para mantenedores
|
||||
|
||||
## Lista de verificación del operador de publicación
|
||||
## Lista de verificación del operador de lanzamiento
|
||||
|
||||
Esta lista de verificación es la forma pública del flujo de publicación. Las credenciales privadas,
|
||||
la firma, la notarización, la recuperación de dist-tags y los detalles de reversión de emergencia permanecen en
|
||||
el runbook de publicación solo para mantenedores.
|
||||
Esta lista de verificación es la forma pública del flujo de lanzamiento. Las credenciales privadas,
|
||||
la firma, la notarización, la recuperación de dist-tag y los detalles de reversión de emergencia permanecen en
|
||||
el manual de lanzamiento solo para mantenedores.
|
||||
|
||||
1. Empieza desde el `main` actual: trae lo último, confirma que el commit objetivo se haya enviado,
|
||||
y confirma que el CI actual de `main` esté lo bastante verde como para crear una rama desde él.
|
||||
1. Empieza desde el `main` actual: trae lo más reciente, confirma que el commit de destino se haya enviado
|
||||
y confirma que el CI del `main` actual esté lo suficientemente verde como para crear una rama desde él.
|
||||
2. Reescribe la sección superior de `CHANGELOG.md` a partir del historial real de commits con
|
||||
`/changelog`, mantén las entradas orientadas al usuario, confírmala, envíala, y haz rebase/pull
|
||||
`/changelog`, mantén las entradas orientadas al usuario, confírmala, envíala y haz rebase/pull
|
||||
una vez más antes de crear la rama.
|
||||
3. Revisa los registros de compatibilidad de publicación en
|
||||
3. Revisa los registros de compatibilidad de lanzamiento en
|
||||
`src/plugins/compat/registry.ts` y
|
||||
`src/commands/doctor/shared/deprecation-compat.ts`. Elimina la
|
||||
compatibilidad expirada solo cuando la ruta de actualización siga cubierta, o registra por qué se
|
||||
conserva intencionadamente.
|
||||
4. Crea `release/YYYY.M.D` desde el `main` actual; no hagas el trabajo normal de publicación
|
||||
`src/commands/doctor/shared/deprecation-compat.ts`. Elimina la compatibilidad expirada
|
||||
solo cuando la ruta de actualización siga cubierta, o registra por qué se conserva
|
||||
intencionalmente.
|
||||
4. Crea `release/YYYY.M.D` desde el `main` actual; no hagas trabajo normal de lanzamiento
|
||||
directamente en `main`.
|
||||
5. Incrementa cada ubicación de versión requerida para la etiqueta prevista, ejecuta
|
||||
`pnpm plugins:sync` para que los paquetes de Plugin publicables compartan la versión de publicación
|
||||
`pnpm plugins:sync` para que los paquetes Plugin publicables compartan la versión de lanzamiento
|
||||
y los metadatos de compatibilidad, y luego ejecuta la preflight determinista local:
|
||||
`pnpm check:test-types`, `pnpm check:architecture`,
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, y
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` y
|
||||
`pnpm release:check`.
|
||||
6. Ejecuta `OpenClaw NPM Release` con `preflight_only=true`. Antes de que exista una etiqueta,
|
||||
se permite un SHA completo de 40 caracteres de la rama de publicación para una preflight
|
||||
solo de validación. Guarda el `preflight_run_id` exitoso.
|
||||
7. Inicia todas las pruebas previas a la publicación con `Full Release Validation` para la
|
||||
rama de publicación, la etiqueta o el SHA completo del commit. Este es el único punto de entrada manual
|
||||
para las cuatro grandes cajas de prueba de publicación: Vitest, Docker, QA Lab y Package.
|
||||
8. Si la validación falla, corrige en la rama de publicación y vuelve a ejecutar el archivo, canal,
|
||||
job de workflow, perfil de paquete, proveedor o lista de permitidos de modelos más pequeño que
|
||||
demuestre la corrección. Vuelve a ejecutar el paraguas completo solo cuando la superficie cambiada haga
|
||||
que la evidencia previa quede obsoleta.
|
||||
9. Para beta, etiqueta `vYYYY.M.D-beta.N`, luego ejecuta `OpenClaw Release Publish` desde
|
||||
se permite un SHA completo de 40 caracteres de la rama de lanzamiento solo para la validación
|
||||
preflight. Guarda el `preflight_run_id` exitoso.
|
||||
7. Inicia todas las pruebas previas al lanzamiento con `Full Release Validation` para la
|
||||
rama de lanzamiento, la etiqueta o el SHA completo del commit. Este es el único punto de entrada manual
|
||||
para los cuatro grandes entornos de prueba de lanzamiento: Vitest, Docker, QA Lab y Package.
|
||||
8. Si la validación falla, corrige en la rama de lanzamiento y vuelve a ejecutar el archivo, vía,
|
||||
job de workflow, perfil de paquete, proveedor o allowlist de modelo fallido más pequeño que
|
||||
demuestre la corrección. Vuelve a ejecutar todo el paraguas solo cuando la superficie cambiada vuelva obsoleta
|
||||
la evidencia anterior.
|
||||
9. Para beta, etiqueta `vYYYY.M.D-beta.N` y luego ejecuta `OpenClaw Release Publish` desde
|
||||
la rama `release/YYYY.M.D` correspondiente. Verifica `pnpm plugins:sync:check`,
|
||||
publica primero todos los paquetes de Plugin publicables en npm, publica después el mismo
|
||||
conjunto en ClawHub como tarballs npm-pack de ClawPack, y luego promociona el
|
||||
artefacto de preflight npm de OpenClaw preparado con el dist-tag correspondiente. Después de
|
||||
publicar, ejecuta la aceptación de paquetes posterior a la publicación
|
||||
contra el paquete publicado `openclaw@YYYY.M.D-beta.N` o
|
||||
`openclaw@beta`. Si una versión preliminar enviada o publicada necesita una corrección,
|
||||
corta el siguiente número de versión preliminar correspondiente; no elimines ni reescribas la
|
||||
versión preliminar anterior.
|
||||
10. Para estable, continúa solo después de que la beta revisada o el candidato de publicación tenga la
|
||||
evidencia de validación requerida. La publicación estable en npm también pasa por
|
||||
`OpenClaw Release Publish`, reutilizando el artefacto de preflight exitoso mediante
|
||||
`preflight_run_id`; la preparación de la publicación estable para macOS también requiere el
|
||||
publica primero en npm todos los paquetes Plugin publicables, publica el mismo
|
||||
conjunto en ClawHub en segundo lugar como tarballs npm-pack de ClawPack, y luego promueve el
|
||||
artefacto preflight npm preparado de OpenClaw con el dist-tag correspondiente. Después de
|
||||
publicar, ejecuta la aceptación de paquete posterior a la publicación
|
||||
contra el paquete `openclaw@YYYY.M.D-beta.N` u
|
||||
`openclaw@beta` publicado. Si un prelanzamiento enviado o publicado necesita una corrección,
|
||||
corta el siguiente número de prelanzamiento correspondiente; no elimines ni reescribas el
|
||||
prelanzamiento anterior.
|
||||
10. Para estable, continúa solo después de que la beta revisada o el candidato de lanzamiento tenga la
|
||||
evidencia de validación requerida. La publicación npm estable también pasa por
|
||||
`OpenClaw Release Publish`, reutilizando el artefacto preflight exitoso mediante
|
||||
`preflight_run_id`; la preparación del lanzamiento estable de macOS también requiere el
|
||||
`.zip`, `.dmg`, `.dSYM.zip` empaquetados y el `appcast.xml` actualizado en `main`.
|
||||
11. Después de publicar, ejecuta el verificador npm posterior a la publicación, el E2E opcional independiente
|
||||
de Telegram con npm publicado cuando necesites prueba del canal posterior a la publicación,
|
||||
la promoción de dist-tag cuando sea necesario, las notas de publicación/versión preliminar de GitHub desde la
|
||||
sección completa correspondiente de `CHANGELOG.md`, y los pasos de anuncio de la publicación.
|
||||
11. Después de publicar, ejecuta el verificador npm posterior a la publicación, el E2E opcional de Telegram
|
||||
con npm publicado independiente cuando necesites prueba de canal posterior a la publicación,
|
||||
la promoción de dist-tag cuando sea necesario, las notas de lanzamiento/prelanzamiento de GitHub a partir de la
|
||||
sección completa correspondiente de `CHANGELOG.md`, y los pasos de anuncio del lanzamiento.
|
||||
|
||||
## Preflight de publicación
|
||||
## Preflight de lanzamiento
|
||||
|
||||
- Ejecuta `pnpm check:test-types` antes del preflight de lanzamiento para que el TypeScript de pruebas siga
|
||||
cubierto fuera de la puerta local más rápida `pnpm check`
|
||||
- Ejecuta `pnpm check:architecture` antes del preflight de lanzamiento para que las comprobaciones más amplias de ciclos de
|
||||
importación y límites de arquitectura estén en verde fuera de la puerta local más rápida
|
||||
- Ejecuta `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que los artefactos de lanzamiento esperados
|
||||
`dist/*` y el paquete de Control UI existan para el paso de validación
|
||||
del paquete
|
||||
- Ejecuta `pnpm plugins:sync` después del incremento de versión raíz y antes de etiquetar. Actualiza las versiones de paquetes de Plugin publicables, los metadatos de compatibilidad de pares/API de OpenClaw, los metadatos de compilación y los stubs de changelog de Plugin para que coincidan con la versión de lanzamiento del núcleo. `pnpm plugins:sync:check` es la guarda de lanzamiento no mutante;
|
||||
el flujo de trabajo de publicación falla antes de cualquier mutación del registro si este paso se
|
||||
olvidó.
|
||||
- Ejecuta manualmente el flujo de trabajo `Full Release Validation` antes de aprobar el lanzamiento para
|
||||
iniciar todos los entornos de prueba de prelanzamiento desde un único punto de entrada. Acepta una rama,
|
||||
etiqueta o SHA completo de commit, despacha `CI` manual y despacha
|
||||
`OpenClaw Release Checks` para smoke de instalación, aceptación de paquete, suites de ruta de lanzamiento de Docker, live/E2E, OpenWebUI, paridad de QA Lab, Matrix y carriles de Telegram. Con `release_profile=full` y `rerun_group=all`, también ejecuta E2E de paquete Telegram contra el artefacto `release-package-under-test` de las comprobaciones de lanzamiento. Proporciona `npm_telegram_package_spec` después de publicar cuando el mismo E2E de Telegram también deba probar el paquete npm publicado. Proporciona `package_acceptance_package_spec` después de publicar cuando Package Acceptance deba ejecutar su matriz de paquete/actualización contra el paquete npm enviado en lugar del artefacto compilado desde el SHA. Proporciona
|
||||
`evidence_package_spec` cuando el informe privado de evidencia deba probar que la
|
||||
validación coincide con un paquete npm publicado sin forzar E2E de Telegram.
|
||||
Ejemplo:
|
||||
- Ejecuta `pnpm check:test-types` antes de la verificación previa de la versión para que el TypeScript de pruebas siga cubierto fuera de la puerta local más rápida `pnpm check`
|
||||
- Ejecuta `pnpm check:architecture` antes de la verificación previa de la versión para que las comprobaciones más amplias de ciclos de importación y límites de arquitectura estén en verde fuera de la puerta local más rápida
|
||||
- Ejecuta `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que los artefactos de versión esperados `dist/*` y el paquete de la UI de Control existan para el paso de validación del paquete
|
||||
- Ejecuta `pnpm plugins:sync` después del incremento de versión raíz y antes de etiquetar. Actualiza las versiones de paquetes de plugins publicables, los metadatos de compatibilidad de pares/API de OpenClaw, los metadatos de compilación y los stubs de changelog de plugins para que coincidan con la versión core. `pnpm plugins:sync:check` es la guarda de versión no mutante; el flujo de publicación falla antes de cualquier mutación del registro si se olvidó este paso.
|
||||
- Ejecuta el workflow manual `Full Release Validation` antes de aprobar la versión para iniciar todos los bancos de pruebas previos a la versión desde un único punto de entrada. Acepta una rama, etiqueta o SHA completo de commit, despacha `CI` manual y despacha `OpenClaw Release Checks` para install smoke, aceptación de paquetes, suites de ruta de publicación de Docker, live/E2E, OpenWebUI, paridad de QA Lab, Matrix y canales de Telegram. Con `release_profile=full` y `rerun_group=all`, también ejecuta Telegram E2E de paquete contra el artefacto `release-package-under-test` de las comprobaciones de versión. Proporciona `npm_telegram_package_spec` después de publicar cuando el mismo Telegram E2E también deba probar el paquete npm publicado. Proporciona `package_acceptance_package_spec` después de publicar cuando Package Acceptance deba ejecutar su matriz de paquetes/actualizaciones contra el paquete npm enviado en lugar del artefacto compilado desde el SHA. Proporciona `evidence_package_spec` cuando el informe privado de evidencia deba probar que la validación coincide con un paquete npm publicado sin forzar Telegram E2E. Ejemplo:
|
||||
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- Ejecuta manualmente el flujo de trabajo `Package Acceptance` cuando quieras prueba de canal lateral
|
||||
para un candidato de paquete mientras continúa el trabajo de lanzamiento. Usa `source=npm` para
|
||||
`openclaw@beta`, `openclaw@latest` o una versión de lanzamiento exacta; `source=ref`
|
||||
para empaquetar una rama/etiqueta/SHA `package_ref` de confianza con el arnés `workflow_ref` actual; `source=url` para un tarball HTTPS con un
|
||||
SHA-256 obligatorio; o `source=artifact` para un tarball subido por otra ejecución de GitHub
|
||||
Actions. El flujo de trabajo resuelve el candidato a
|
||||
`package-under-test`, reutiliza el planificador de lanzamiento Docker E2E contra ese
|
||||
tarball y puede ejecutar QA de Telegram contra el mismo tarball con
|
||||
`telegram_mode=mock-openai` o `telegram_mode=live-frontier`. Cuando los carriles de Docker seleccionados incluyen `published-upgrade-survivor`, el artefacto de paquete es el candidato y `published_upgrade_survivor_baseline` selecciona la línea base publicada.
|
||||
- Ejecuta el workflow manual `Package Acceptance` cuando quieras una prueba de canal lateral para un candidato de paquete mientras continúa el trabajo de versión. Usa `source=npm` para `openclaw@beta`, `openclaw@latest` o una versión exacta de publicación; `source=ref` para empaquetar una rama/etiqueta/SHA `package_ref` de confianza con el arnés `workflow_ref` actual; `source=url` para un tarball HTTPS con un SHA-256 obligatorio; o `source=artifact` para un tarball subido por otra ejecución de GitHub Actions. El workflow resuelve el candidato a `package-under-test`, reutiliza el programador de publicación Docker E2E contra ese tarball y puede ejecutar QA de Telegram contra el mismo tarball con `telegram_mode=mock-openai` o `telegram_mode=live-frontier`. Cuando los canales Docker seleccionados incluyen `published-upgrade-survivor`, el artefacto de paquete es el candidato y `published_upgrade_survivor_baseline` selecciona la línea base publicada.
|
||||
Ejemplo: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
|
||||
Perfiles comunes:
|
||||
- `smoke`: carriles de instalación/canal/agente, red de Gateway y recarga de configuración
|
||||
- `package`: carriles nativos de artefacto para paquete/actualización/Plugin sin OpenWebUI ni ClawHub live
|
||||
- `product`: perfil de paquete más canales MCP, limpieza de cron/subagente,
|
||||
búsqueda web de OpenAI y OpenWebUI
|
||||
- `full`: fragmentos de ruta de lanzamiento de Docker con OpenWebUI
|
||||
- `custom`: selección exacta de `docker_lanes` para una reejecución enfocada
|
||||
- Ejecuta manualmente el flujo de trabajo `CI` directamente cuando solo necesites cobertura completa de CI normal
|
||||
para el candidato de lanzamiento. Los despachos manuales de CI omiten el alcance por cambios
|
||||
y fuerzan los shards de Linux Node, shards de plugins incluidos, contratos de canal, compatibilidad con Node 22, `check`, `check-additional`, smoke de compilación,
|
||||
comprobaciones de docs, Skills de Python, Windows, macOS, Android y carriles de i18n de Control UI.
|
||||
- `smoke`: canales de instalación/canal/agente, red de Gateway y recarga de configuración
|
||||
- `package`: canales nativos de artefacto para paquete/actualización/plugin sin OpenWebUI ni ClawHub en vivo
|
||||
- `product`: perfil de paquete más canales MCP, limpieza de cron/subagente, búsqueda web de OpenAI y OpenWebUI
|
||||
- `full`: fragmentos de ruta de publicación Docker con OpenWebUI
|
||||
- `custom`: selección exacta de `docker_lanes` para una repetición enfocada
|
||||
- Ejecuta directamente el workflow manual `CI` cuando solo necesites cobertura completa de CI normal para el candidato de versión. Los despachos manuales de CI omiten el alcance por cambios y fuerzan los shards Linux Node, shards de plugins incluidos, contratos de canales, compatibilidad con Node 22, `check`, `check-additional`, smoke de compilación, comprobaciones de docs, Skills de Python, Windows, macOS, Android y canales de i18n de la UI de Control.
|
||||
Ejemplo: `gh workflow run ci.yml --ref release/YYYY.M.D`
|
||||
- Ejecuta `pnpm qa:otel:smoke` al validar la telemetría de lanzamiento. Ejercita
|
||||
QA-lab mediante un receptor OTLP/HTTP local y verifica los nombres de spans de traza exportados, atributos acotados y redacción de contenido/identificadores sin
|
||||
requerir Opik, Langfuse ni otro colector externo.
|
||||
- Ejecuta `pnpm release:check` antes de cada lanzamiento etiquetado
|
||||
- Ejecuta `OpenClaw Release Publish` para la secuencia de publicación mutante después de que la
|
||||
etiqueta exista. Despáchalo desde `release/YYYY.M.D` (o `main` al publicar una
|
||||
etiqueta alcanzable desde main), pasa la etiqueta de lanzamiento y el `preflight_run_id` exitoso de npm de OpenClaw, y conserva el alcance predeterminado de publicación de Plugin
|
||||
`all-publishable` salvo que estés ejecutando deliberadamente una reparación enfocada. El
|
||||
flujo de trabajo serializa la publicación npm de Plugin, la publicación de Plugin en ClawHub y la publicación npm de OpenClaw para que el paquete principal no se publique antes de sus
|
||||
plugins externalizados.
|
||||
- Las comprobaciones de lanzamiento ahora se ejecutan en un flujo de trabajo manual separado:
|
||||
- Ejecuta `pnpm qa:otel:smoke` al validar la telemetría de versión. Ejercita QA-lab mediante un receptor OTLP/HTTP local y verifica los nombres de spans de trazas exportadas, los atributos acotados y la redacción de contenido/identificadores sin requerir Opik, Langfuse u otro recopilador externo.
|
||||
- Ejecuta `pnpm release:check` antes de cada versión etiquetada
|
||||
- Ejecuta `OpenClaw Release Publish` para la secuencia de publicación mutante después de que exista la etiqueta. Despáchalo desde `release/YYYY.M.D` (o `main` al publicar una etiqueta alcanzable desde main), pasa la etiqueta de versión y el `preflight_run_id` exitoso de npm de OpenClaw, y conserva el alcance predeterminado de publicación de plugins `all-publishable` salvo que estés ejecutando deliberadamente una reparación enfocada. El workflow serializa la publicación npm de plugins, la publicación en ClawHub de plugins y la publicación npm de OpenClaw para que el paquete core no se publique antes que sus plugins externalizados.
|
||||
- Las comprobaciones de versión ahora se ejecutan en un workflow manual separado:
|
||||
`OpenClaw Release Checks`
|
||||
- `OpenClaw Release Checks` también ejecuta el carril de paridad mock de QA Lab más el perfil live rápido de Matrix y el carril de QA de Telegram antes de la aprobación del lanzamiento. Los carriles live usan el entorno `qa-live-shared`; Telegram también usa concesiones de credenciales de Convex CI. Ejecuta manualmente el flujo de trabajo `QA-Lab - All Lanes` con
|
||||
`matrix_profile=all` y `matrix_shards=true` cuando quieras en paralelo el inventario completo de transporte, medios y E2EE de Matrix.
|
||||
- La validación en tiempo de ejecución de instalación y actualización entre sistemas operativos forma parte de
|
||||
`OpenClaw Release Checks` y `Full Release Validation` públicos, que llaman directamente al
|
||||
flujo de trabajo reutilizable
|
||||
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Esta división es intencional: mantiene la ruta real de lanzamiento npm corta,
|
||||
determinista y enfocada en artefactos, mientras que las comprobaciones live más lentas permanecen en su
|
||||
propio carril para que no detengan ni bloqueen la publicación
|
||||
- Las comprobaciones de lanzamiento que contienen secretos deben despacharse mediante `Full Release
|
||||
Validation` o desde la referencia de flujo de trabajo `main`/release para que la lógica del flujo de trabajo y
|
||||
los secretos permanezcan controlados
|
||||
- `OpenClaw Release Checks` acepta una rama, etiqueta o SHA completo de commit siempre que
|
||||
el commit resuelto sea alcanzable desde una rama de OpenClaw o una etiqueta de lanzamiento
|
||||
- El preflight solo de validación de `OpenClaw NPM Release` también acepta el SHA completo actual de 40 caracteres del commit de la rama de flujo de trabajo sin requerir una etiqueta enviada
|
||||
- Esa ruta SHA es solo de validación y no puede promoverse a una publicación real
|
||||
- En modo SHA, el flujo de trabajo sintetiza `v<package.json version>` solo para la
|
||||
comprobación de metadatos del paquete; la publicación real aún requiere una etiqueta de lanzamiento real
|
||||
- Ambos flujos de trabajo mantienen la ruta real de publicación y promoción en runners hospedados en GitHub,
|
||||
mientras que la ruta de validación no mutante puede usar los runners Linux más grandes de Blacksmith
|
||||
- Ese flujo de trabajo ejecuta
|
||||
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
|
||||
usando los secretos de flujo de trabajo `OPENAI_API_KEY` y `ANTHROPIC_API_KEY`
|
||||
- El preflight de lanzamiento npm ya no espera el carril separado de comprobaciones de lanzamiento
|
||||
- Ejecuta `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
|
||||
(o la etiqueta beta/corrección correspondiente) antes de la aprobación
|
||||
- Después de publicar en npm, ejecuta
|
||||
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
|
||||
(o la versión beta/corrección correspondiente) para verificar la ruta de instalación del registro publicado
|
||||
en un prefijo temporal limpio
|
||||
- Después de una publicación beta, ejecuta `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
|
||||
para verificar la incorporación del paquete instalado, la configuración de Telegram y E2E real de Telegram
|
||||
contra el paquete npm publicado usando el grupo compartido de credenciales Telegram concedidas. Las ejecuciones locales puntuales de mantenedores pueden omitir las variables de Convex y pasar directamente las tres credenciales de entorno `OPENCLAW_QA_TELEGRAM_*`.
|
||||
- Los mantenedores pueden ejecutar la misma comprobación posterior a la publicación desde GitHub Actions mediante el
|
||||
flujo de trabajo manual `NPM Telegram Beta E2E`. Es intencionalmente solo manual y
|
||||
no se ejecuta en cada merge.
|
||||
- La automatización de lanzamiento para mantenedores ahora usa preflight-y-luego-promoción:
|
||||
- la publicación npm real debe pasar un `preflight_run_id` npm exitoso
|
||||
- la publicación npm real debe despacharse desde la misma rama `main` o
|
||||
`release/YYYY.M.D` que la ejecución de preflight exitosa
|
||||
- los lanzamientos npm estables predeterminan a `beta`
|
||||
- la publicación npm estable puede apuntar explícitamente a `latest` mediante entrada del flujo de trabajo
|
||||
- la mutación de dist-tag de npm basada en token ahora vive en
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
por seguridad, porque `npm dist-tag add` todavía necesita `NPM_TOKEN` mientras el
|
||||
repo público mantiene publicación solo con OIDC
|
||||
- `macOS Release` público es solo de validación; cuando una etiqueta existe solo en una
|
||||
rama de lanzamiento pero el flujo de trabajo se despacha desde `main`, configura
|
||||
`public_release_branch=release/YYYY.M.D`
|
||||
- la publicación privada real de Mac debe pasar `preflight_run_id` y
|
||||
`validate_run_id` privados de Mac exitosos
|
||||
- las rutas reales de publicación promueven artefactos preparados en lugar de reconstruirlos
|
||||
de nuevo
|
||||
- Para lanzamientos estables de corrección como `YYYY.M.D-N`, el verificador posterior a la publicación
|
||||
también comprueba la misma ruta de actualización en prefijo temporal de `YYYY.M.D` a `YYYY.M.D-N`
|
||||
para que las correcciones de lanzamiento no puedan dejar silenciosamente instalaciones globales antiguas en la
|
||||
carga estable base
|
||||
- El preflight de lanzamiento npm falla cerrado salvo que el tarball incluya tanto
|
||||
`dist/control-ui/index.html` como una carga no vacía `dist/control-ui/assets/`
|
||||
para que no volvamos a enviar un panel de navegador vacío
|
||||
- La verificación posterior a la publicación también comprueba que los entrypoints de Plugin publicados y
|
||||
los metadatos del paquete estén presentes en el diseño de registro instalado. Un lanzamiento que
|
||||
envía cargas de runtime de Plugin faltantes falla el verificador postpublish y
|
||||
no puede promoverse a `latest`.
|
||||
- `pnpm test:install:smoke` también aplica el presupuesto `unpackedSize` de npm pack en
|
||||
el tarball de actualización candidato, de modo que el e2e del instalador detecte crecimiento accidental del paquete
|
||||
antes de la ruta de publicación de lanzamiento
|
||||
- Si el trabajo de lanzamiento tocó la planificación de CI, manifiestos de tiempos de extensión o
|
||||
matrices de pruebas de extensión, regenera y revisa las salidas de matriz
|
||||
`plugin-prerelease-extension-shard` propiedad del planificador desde
|
||||
`.github/workflows/plugin-prerelease.yml` antes de la aprobación para que las notas de lanzamiento no
|
||||
describan un diseño de CI obsoleto
|
||||
- La preparación para el lanzamiento estable de macOS también incluye las superficies del actualizador:
|
||||
- el lanzamiento de GitHub debe terminar con los paquetes `.zip`, `.dmg` y `.dSYM.zip`
|
||||
- `OpenClaw Release Checks` también ejecuta el canal de paridad mock de QA Lab, además del perfil rápido live de Matrix y el canal de QA de Telegram antes de aprobar la versión. Los canales live usan el entorno `qa-live-shared`; Telegram también usa arrendamientos de credenciales de CI de Convex. Ejecuta el workflow manual `QA-Lab - All Lanes` con `matrix_profile=all` y `matrix_shards=true` cuando quieras el inventario completo de transporte, medios y E2EE de Matrix en paralelo.
|
||||
- La validación de instalación y actualización runtime entre sistemas operativos forma parte de los workflows públicos `OpenClaw Release Checks` y `Full Release Validation`, que llaman directamente al workflow reutilizable `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Esta separación es intencional: mantiene la ruta real de publicación npm corta, determinista y centrada en artefactos, mientras las comprobaciones live más lentas permanecen en su propio canal para no atascar ni bloquear la publicación
|
||||
- Las comprobaciones de versión con secretos deben despacharse mediante `Full Release Validation` o desde la referencia de workflow `main`/release para que la lógica del workflow y los secretos permanezcan controlados
|
||||
- `OpenClaw Release Checks` acepta una rama, etiqueta o SHA completo de commit siempre que el commit resuelto sea alcanzable desde una rama o etiqueta de versión de OpenClaw
|
||||
- La verificación previa solo de validación de `OpenClaw NPM Release` también acepta el SHA completo actual de 40 caracteres del commit de la rama del workflow sin requerir una etiqueta subida
|
||||
- Esa ruta de SHA es solo de validación y no se puede promover a una publicación real
|
||||
- En modo SHA, el workflow sintetiza `v<package.json version>` solo para la comprobación de metadatos del paquete; la publicación real aún requiere una etiqueta de versión real
|
||||
- Ambos workflows mantienen la ruta real de publicación y promoción en runners hospedados por GitHub, mientras la ruta de validación no mutante puede usar los runners Linux más grandes de Blacksmith
|
||||
- Ese workflow ejecuta `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` usando los secretos de workflow `OPENAI_API_KEY` y `ANTHROPIC_API_KEY`
|
||||
- La verificación previa de publicación npm ya no espera al canal separado de comprobaciones de versión
|
||||
- Ejecuta `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (o la etiqueta beta/corrección correspondiente) antes de la aprobación
|
||||
- Después de publicar en npm, ejecuta `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (o la versión beta/corrección correspondiente) para verificar la ruta de instalación del registro publicado en un prefijo temporal nuevo
|
||||
- Después de publicar una beta, ejecuta `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` para verificar el onboarding del paquete instalado, la configuración de Telegram y Telegram E2E real contra el paquete npm publicado usando el pool compartido de credenciales arrendadas de Telegram. Los mantenedores pueden omitir las variables de Convex en ejecuciones locales puntuales y pasar directamente las tres credenciales de entorno `OPENCLAW_QA_TELEGRAM_*`.
|
||||
- Para ejecutar el smoke beta completo posterior a la publicación desde una máquina de mantenedor, usa `pnpm release:beta-smoke -- --beta betaN`. El helper ejecuta validación de actualización npm/fresh-target de Parallels, despacha `NPM Telegram Beta E2E`, sondea la ejecución exacta del workflow, descarga el artefacto e imprime el informe de Telegram.
|
||||
- Los mantenedores pueden ejecutar la misma comprobación posterior a la publicación desde GitHub Actions mediante el workflow manual `NPM Telegram Beta E2E`. Es intencionalmente solo manual y no se ejecuta en cada merge.
|
||||
- La automatización de versiones de mantenedores ahora usa verificación previa y luego promoción:
|
||||
- la publicación npm real debe pasar un `preflight_run_id` de npm exitoso
|
||||
- la publicación npm real debe despacharse desde la misma rama `main` o `release/YYYY.M.D` que la ejecución de verificación previa exitosa
|
||||
- las versiones npm estables usan `beta` de forma predeterminada
|
||||
- la publicación npm estable puede apuntar explícitamente a `latest` mediante una entrada de workflow
|
||||
- la mutación basada en token de dist-tag de npm ahora vive en `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` por seguridad, porque `npm dist-tag add` todavía necesita `NPM_TOKEN` mientras el repositorio público mantiene la publicación solo con OIDC
|
||||
- `macOS Release` público es solo de validación; cuando una etiqueta existe solo en una rama de versión pero el workflow se despacha desde `main`, establece `public_release_branch=release/YYYY.M.D`
|
||||
- la publicación privada real de mac debe pasar un `preflight_run_id` y un `validate_run_id` privados de mac exitosos
|
||||
- las rutas de publicación reales promueven artefactos preparados en lugar de reconstruirlos otra vez
|
||||
- Para versiones estables de corrección como `YYYY.M.D-N`, el verificador posterior a la publicación también comprueba la misma ruta de actualización de prefijo temporal desde `YYYY.M.D` a `YYYY.M.D-N` para que las correcciones de versión no puedan dejar silenciosamente instalaciones globales antiguas en la carga base estable
|
||||
- La verificación previa de publicación npm falla cerrada salvo que el tarball incluya tanto `dist/control-ui/index.html` como una carga no vacía `dist/control-ui/assets/`, para no volver a enviar un panel de navegador vacío
|
||||
- La verificación posterior a la publicación también comprueba que los entrypoints de plugins publicados y los metadatos de paquete estén presentes en el diseño de registro instalado. Una versión que envía cargas runtime de plugins faltantes falla el verificador postpublish y no se puede promover a `latest`.
|
||||
- `pnpm test:install:smoke` también aplica el presupuesto `unpackedSize` del pack npm sobre el tarball candidato de actualización, de modo que installer e2e detecta el aumento accidental del tamaño del paquete antes de la ruta de publicación de versión
|
||||
- Si el trabajo de versión tocó la planificación de CI, los manifiestos de timing de extensiones o las matrices de pruebas de extensiones, regenera y revisa las salidas de matriz `plugin-prerelease-extension-shard`, propiedad del planificador, desde `.github/workflows/plugin-prerelease.yml` antes de aprobar, para que las notas de versión no describan un diseño de CI obsoleto
|
||||
- La preparación de una versión estable de macOS también incluye las superficies del actualizador:
|
||||
- la release de GitHub debe terminar con los paquetes `.zip`, `.dmg` y `.dSYM.zip`
|
||||
- `appcast.xml` en `main` debe apuntar al nuevo zip estable después de publicar
|
||||
- la app empaquetada debe conservar un bundle id no debug, una URL de feed de Sparkle no vacía
|
||||
y un `CFBundleVersion` igual o superior al piso canónico de compilación de Sparkle
|
||||
para esa versión de lanzamiento
|
||||
- la app empaquetada debe conservar un bundle id no debug, una URL de feed de Sparkle no vacía y un `CFBundleVersion` igual o superior al piso canónico de compilación de Sparkle para esa versión de release
|
||||
|
||||
## Entornos de prueba de lanzamiento
|
||||
## Bancos de pruebas de versión
|
||||
|
||||
`Full Release Validation` es la forma en que los operadores inician todas las pruebas de prelanzamiento desde
|
||||
un único punto de entrada. Para una prueba de commit fijado en una rama que se mueve rápido, usa el
|
||||
helper para que cada flujo de trabajo hijo se ejecute desde una rama temporal fijada en el SHA objetivo:
|
||||
`Full Release Validation` es la forma en que los operadores inician todas las pruebas previas a la versión desde un único punto de entrada. Para una prueba de commit fijado en una rama que avanza rápido, usa el helper para que cada workflow hijo se ejecute desde una rama temporal fijada al SHA objetivo:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
El helper envía `release-ci/<sha>-...`, despacha `Full Release Validation`
|
||||
desde esa rama con `ref=<sha>`, verifica que cada `headSha` de flujo de trabajo hijo
|
||||
coincida con el objetivo y luego elimina la rama temporal. Esto evita probar por accidente una
|
||||
ejecución hija de `main` más nueva.
|
||||
El helper sube `release-ci/<sha>-...`, despacha `Full Release Validation` desde esa rama con `ref=<sha>`, verifica que cada `headSha` de workflow hijo coincida con el objetivo y luego elimina la rama temporal. Esto evita probar por accidente una ejecución hija de `main` más nueva.
|
||||
|
||||
Para validar una rama o etiqueta de lanzamiento, ejecútalo desde la referencia de flujo de trabajo `main` de confianza
|
||||
y pasa la rama o etiqueta de lanzamiento como `ref`:
|
||||
Para validar una rama o etiqueta de versión, ejecútalo desde la referencia de workflow `main` de confianza y pasa la rama o etiqueta de versión como `ref`:
|
||||
|
||||
```bash
|
||||
gh workflow run full-release-validation.yml \
|
||||
@ -266,44 +185,52 @@ gh workflow run full-release-validation.yml \
|
||||
El flujo de trabajo resuelve la ref de destino, despacha manualmente `CI` con
|
||||
`target_ref=<release-ref>`, despacha `OpenClaw Release Checks`, prepara un
|
||||
artefacto padre `release-package-under-test` para las comprobaciones orientadas
|
||||
a paquetes, y despacha el E2E independiente del paquete Telegram cuando
|
||||
`release_profile=full` con `rerun_group=all` o cuando se define
|
||||
`npm_telegram_package_spec`. Luego, `OpenClaw Release
|
||||
Checks` se expande a smoke de instalación, comprobaciones de lanzamiento
|
||||
multisistema, cobertura de la ruta de lanzamiento Docker live/E2E, Package Acceptance con QA del paquete Telegram, paridad de QA Lab,
|
||||
Matrix live y Telegram live. Una ejecución completa solo es aceptable cuando el
|
||||
resumen de `Full Release Validation`
|
||||
muestra `normal_ci` y `release_checks` como correctos. En modo full/all,
|
||||
el hijo `npm_telegram` también debe completarse correctamente; fuera de full/all se omite
|
||||
salvo que se haya proporcionado un `npm_telegram_package_spec` publicado. El resumen final
|
||||
del verificador incluye tablas de los trabajos más lentos para cada ejecución hija, de modo que el responsable del lanzamiento pueda ver la ruta crítica actual sin descargar registros.
|
||||
a paquetes, y despacha el E2E independiente del paquete de Telegram cuando
|
||||
`release_profile=full` con `rerun_group=all` o cuando se establece
|
||||
`npm_telegram_package_spec`. Luego `OpenClaw Release
|
||||
Checks` despliega comprobaciones de humo de instalación, comprobaciones de
|
||||
lanzamiento entre sistemas operativos, cobertura de ruta de lanzamiento de
|
||||
Docker en vivo/E2E, Aceptación de paquetes con QA del paquete de Telegram, paridad
|
||||
de QA Lab, Matrix en vivo y Telegram en vivo. Una ejecución completa solo es
|
||||
aceptable cuando el resumen de `Full Release Validation` muestra `normal_ci` y
|
||||
`release_checks` como correctos. En modo full/all, el hijo `npm_telegram` también
|
||||
debe ser correcto; fuera de full/all se omite, salvo que se haya proporcionado
|
||||
un `npm_telegram_package_spec` publicado. El resumen final del verificador incluye
|
||||
tablas de trabajos más lentos para cada ejecución hija, para que el responsable
|
||||
del lanzamiento pueda ver la ruta crítica actual sin descargar registros.
|
||||
Consulta [Validación completa de lanzamiento](/es/reference/full-release-validation) para ver la
|
||||
matriz completa de etapas, los nombres exactos de trabajos del flujo de trabajo, las diferencias
|
||||
entre los perfiles stable y full, los artefactos y los identificadores de reejecución enfocados.
|
||||
Los flujos de trabajo hijos se despachan desde la ref confiable que ejecuta `Full Release
|
||||
Validation`, normalmente `--ref main`, incluso cuando la `ref` de destino apunta a una
|
||||
rama o etiqueta de lanzamiento más antigua. No hay una entrada separada de ref de flujo de trabajo para Full Release Validation; elige el arnés confiable eligiendo la ref de ejecución del flujo de trabajo.
|
||||
No uses `--ref main -f ref=<sha>` como prueba de commit exacto en un `main` móvil;
|
||||
los SHA de commit sin procesar no pueden ser refs de despacho de flujo de trabajo, así que usa
|
||||
`pnpm ci:full-release --sha <sha>` para crear la rama temporal fijada.
|
||||
matriz completa de etapas, los nombres exactos de trabajos de flujo de trabajo,
|
||||
las diferencias entre los perfiles estable y completo, los artefactos y los
|
||||
identificadores de reejecución enfocados.
|
||||
Los flujos de trabajo hijos se despachan desde la ref de confianza que ejecuta
|
||||
`Full Release Validation`, normalmente `--ref main`, incluso cuando la `ref` de
|
||||
destino apunta a una rama o etiqueta de lanzamiento anterior. No hay una entrada
|
||||
separada de ref de flujo de trabajo de Full Release Validation; elige el arnés de
|
||||
confianza eligiendo la ref de ejecución del flujo de trabajo. No uses
|
||||
`--ref main -f ref=<sha>` para prueba de confirmación exacta en un `main` móvil;
|
||||
los SHA de confirmación sin procesar no pueden ser refs de despacho de flujo de
|
||||
trabajo, así que usa `pnpm ci:full-release --sha <sha>` para crear la rama
|
||||
temporal fijada.
|
||||
|
||||
Usa `release_profile` para seleccionar el alcance live/de proveedores:
|
||||
Usa `release_profile` para seleccionar la amplitud en vivo/proveedor:
|
||||
|
||||
- `minimum`: la ruta Docker y live de OpenAI/core crítica para el lanzamiento más rápida
|
||||
- `stable`: mínimo más cobertura estable de proveedor/backend para la aprobación del lanzamiento
|
||||
- `full`: estable más cobertura amplia de proveedor/medios de advertencia
|
||||
- `minimum`: la ruta en vivo y de Docker crítica para lanzamiento más rápida de OpenAI/núcleo
|
||||
- `stable`: minimum más cobertura estable de proveedor/backend para aprobación de lanzamiento
|
||||
- `full`: stable más cobertura amplia de proveedor/medios consultiva
|
||||
|
||||
`OpenClaw Release Checks` usa la ref confiable del flujo de trabajo para resolver la ref de destino
|
||||
una vez como `release-package-under-test` y reutiliza ese artefacto tanto en
|
||||
las comprobaciones Docker de ruta de lanzamiento como en Package Acceptance. Esto mantiene todas las
|
||||
máquinas orientadas a paquetes en los mismos bytes y evita compilaciones repetidas del paquete.
|
||||
El smoke de instalación OpenAI multisistema usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` cuando la
|
||||
variable de repo/org está definida; de lo contrario, `openai/gpt-5.4`, porque este carril
|
||||
prueba la instalación del paquete, el onboarding, el inicio del Gateway y un turno live de agente,
|
||||
en lugar de comparar el modelo predeterminado más lento. La matriz live de proveedores más amplia
|
||||
sigue siendo el lugar para la cobertura específica de modelos.
|
||||
`OpenClaw Release Checks` usa la ref de flujo de trabajo de confianza para
|
||||
resolver la ref de destino una vez como `release-package-under-test` y reutiliza
|
||||
ese artefacto tanto en las comprobaciones de Docker de ruta de lanzamiento como
|
||||
en Aceptación de paquetes. Esto mantiene todas las cajas orientadas a paquetes
|
||||
en los mismos bytes y evita compilaciones repetidas de paquetes. La comprobación
|
||||
de humo de instalación de OpenAI entre sistemas operativos usa
|
||||
`OPENCLAW_CROSS_OS_OPENAI_MODEL` cuando la variable de repo/org está establecida,
|
||||
o `openai/gpt-5.4` en caso contrario, porque esta vía prueba la instalación del
|
||||
paquete, la incorporación, el inicio del Gateway y un turno de agente en vivo,
|
||||
no evalúa el modelo predeterminado más lento. La matriz más amplia de proveedores
|
||||
en vivo sigue siendo el lugar para la cobertura específica de modelos.
|
||||
|
||||
Usa estas variantes según la etapa del lanzamiento:
|
||||
Usa estas variantes según la etapa de lanzamiento:
|
||||
|
||||
```bash
|
||||
# Validate an unpublished release candidate branch.
|
||||
@ -333,36 +260,49 @@ gh workflow run full-release-validation.yml \
|
||||
-f npm_telegram_provider_mode=mock-openai
|
||||
```
|
||||
|
||||
No uses el paraguas completo como primera reejecución después de una corrección enfocada. Si una máquina
|
||||
falla, usa el flujo de trabajo hijo, el trabajo, el carril Docker, el perfil de paquete, el proveedor
|
||||
del modelo o el carril de QA que falló para la siguiente prueba. Ejecuta de nuevo el paraguas completo solo cuando
|
||||
la corrección haya cambiado la orquestación compartida del lanzamiento o haya vuelto obsoleta la evidencia previa
|
||||
de todas las máquinas. El verificador final del paraguas vuelve a comprobar los ids de ejecución de flujos de trabajo hijos registrados, así que después de que un flujo de trabajo hijo se reejecute correctamente, reejecuta solo el trabajo padre `Verify full validation` fallido.
|
||||
No uses el paraguas completo como primera reejecución después de una corrección
|
||||
enfocada. Si una caja falla, usa el flujo de trabajo hijo fallido, el trabajo, la
|
||||
vía de Docker, el perfil de paquete, el proveedor de modelo o la vía de QA para
|
||||
la siguiente prueba. Vuelve a ejecutar el paraguas completo solo cuando la
|
||||
corrección haya cambiado la orquestación compartida de lanzamiento o haya dejado
|
||||
obsoleta la evidencia anterior de todas las cajas. El verificador final del
|
||||
paraguas vuelve a comprobar los ids registrados de ejecución de flujos de
|
||||
trabajo hijos, así que después de que un flujo de trabajo hijo se vuelva a
|
||||
ejecutar correctamente, vuelve a ejecutar solo el trabajo padre fallido
|
||||
`Verify full validation`.
|
||||
|
||||
Para una recuperación acotada, pasa `rerun_group` al paraguas. `all` es la ejecución real
|
||||
de candidato de lanzamiento, `ci` ejecuta solo el hijo de CI normal, `plugin-prerelease`
|
||||
ejecuta solo el hijo de plugin exclusivo del lanzamiento, `release-checks` ejecuta todas las
|
||||
máquinas de lanzamiento, y los grupos de lanzamiento más estrechos son `install-smoke`, `cross-os`,
|
||||
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` y `npm-telegram`.
|
||||
Las reejecuciones enfocadas de `npm-telegram` requieren `npm_telegram_package_spec`; las ejecuciones full/all
|
||||
con `release_profile=full` usan el artefacto de paquete de release-checks.
|
||||
Para recuperación acotada, pasa `rerun_group` al paraguas. `all` es la ejecución
|
||||
real de candidato de lanzamiento, `ci` ejecuta solo el hijo de CI normal,
|
||||
`plugin-prerelease` ejecuta solo el hijo de Plugin exclusivo de lanzamiento,
|
||||
`release-checks` ejecuta todas las cajas de lanzamiento, y los grupos de
|
||||
lanzamiento más estrechos son `install-smoke`, `cross-os`, `live-e2e`,
|
||||
`package`, `qa`, `qa-parity`, `qa-live` y `npm-telegram`. Las reejecuciones
|
||||
enfocadas de `npm-telegram` requieren `npm_telegram_package_spec`; las
|
||||
ejecuciones full/all con `release_profile=full` usan el artefacto de paquete de
|
||||
release-checks.
|
||||
|
||||
### Vitest
|
||||
|
||||
La máquina Vitest es el flujo de trabajo hijo manual `CI`. El CI manual omite intencionalmente
|
||||
el alcance por cambios y fuerza el grafo normal de pruebas para el candidato de lanzamiento: shards Linux Node, shards de plugins incluidos, contratos de canales, compatibilidad con Node 22, `check`, `check-additional`, smoke de compilación, comprobaciones de documentación, Skills de Python, Windows, macOS, Android e i18n de Control UI.
|
||||
La caja de Vitest es el flujo de trabajo hijo manual `CI`. La CI manual omite
|
||||
intencionalmente el alcance por cambios y fuerza el grafo de pruebas normal para
|
||||
el candidato de lanzamiento: shards de Linux Node, shards de Plugins incluidos,
|
||||
contratos de canales, compatibilidad con Node 22, `check`, `check-additional`,
|
||||
comprobación de humo de build, comprobaciones de docs, Skills de Python, Windows,
|
||||
macOS, Android e i18n de Control UI.
|
||||
|
||||
Usa esta máquina para responder "¿el árbol de código fuente aprobó la suite normal completa de pruebas?"
|
||||
No es lo mismo que la validación del producto por la ruta de lanzamiento. Evidencia que conservar:
|
||||
Usa esta caja para responder “¿pasó el árbol de fuentes el conjunto completo de
|
||||
pruebas normales?”. No es lo mismo que la validación de producto de ruta de
|
||||
lanzamiento. Evidencia que se debe conservar:
|
||||
|
||||
- resumen de `Full Release Validation` que muestre la URL de la ejecución `CI` despachada
|
||||
- resumen de `Full Release Validation` que muestra la URL de la ejecución `CI` despachada
|
||||
- ejecución `CI` en verde en el SHA de destino exacto
|
||||
- nombres de shards fallidos o lentos de los trabajos de CI al investigar regresiones
|
||||
- artefactos de tiempos de Vitest como `.artifacts/vitest-shard-timings.json` cuando
|
||||
una ejecución necesita análisis de rendimiento
|
||||
|
||||
Ejecuta CI manual directamente solo cuando el lanzamiento necesite CI normal determinista, pero
|
||||
no las máquinas Docker, QA Lab, live, multisistema o de paquetes:
|
||||
Ejecuta la CI manual directamente solo cuando el lanzamiento necesita CI normal
|
||||
determinista pero no las cajas de Docker, QA Lab, en vivo, entre sistemas
|
||||
operativos o de paquetes:
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
@ -370,104 +310,120 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
|
||||
### Docker
|
||||
|
||||
La máquina Docker reside en `OpenClaw Release Checks` mediante
|
||||
La caja de Docker vive en `OpenClaw Release Checks` mediante
|
||||
`openclaw-live-and-e2e-checks-reusable.yml`, además del flujo de trabajo
|
||||
`install-smoke` en modo lanzamiento. Valida el candidato de lanzamiento mediante entornos Docker empaquetados, en lugar de solo pruebas a nivel de código fuente.
|
||||
`install-smoke` en modo de lanzamiento. Valida el candidato de lanzamiento a
|
||||
través de entornos Docker empaquetados en lugar de solo pruebas a nivel de
|
||||
fuente.
|
||||
|
||||
La cobertura Docker de lanzamiento incluye:
|
||||
La cobertura de Docker de lanzamiento incluye:
|
||||
|
||||
- smoke completo de instalación con el smoke de instalación global Bun lento habilitado
|
||||
- preparación/reutilización de la imagen smoke del Dockerfile raíz por SHA de destino, con trabajos smoke de QR,
|
||||
root/Gateway e instalador/Bun ejecutándose como shards separados de install-smoke
|
||||
- carriles E2E del repositorio
|
||||
- fragmentos Docker de ruta de lanzamiento: `core`, `package-update-openai`,
|
||||
- comprobación de humo de instalación completa con la comprobación de humo lenta de instalación global de Bun habilitada
|
||||
- preparación/reutilización de la imagen de comprobación de humo del Dockerfile raíz por SHA de destino, con trabajos de QR,
|
||||
raíz/Gateway e instalador/Bun ejecutándose como shards separados de install-smoke
|
||||
- vías E2E del repositorio
|
||||
- fragmentos de Docker de ruta de lanzamiento: `core`, `package-update-openai`,
|
||||
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
|
||||
`plugins-runtime-services`,
|
||||
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
|
||||
`plugins-runtime-install-c`, `plugins-runtime-install-d`,
|
||||
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
|
||||
`plugins-runtime-install-g` y `plugins-runtime-install-h`
|
||||
- cobertura OpenWebUI dentro del fragmento `plugins-runtime-services` cuando se solicite
|
||||
- carriles divididos de instalación/desinstalación de plugins incluidos
|
||||
`bundled-plugin-install-uninstall-0` hasta
|
||||
- cobertura de OpenWebUI dentro del fragmento `plugins-runtime-services` cuando se solicita
|
||||
- vías divididas de instalación/desinstalación de Plugins incluidos
|
||||
`bundled-plugin-install-uninstall-0` a
|
||||
`bundled-plugin-install-uninstall-23`
|
||||
- suites live/E2E de proveedores y cobertura de modelos Docker live cuando las comprobaciones de lanzamiento
|
||||
incluyen suites live
|
||||
- suites de proveedor en vivo/E2E y cobertura de modelos en vivo de Docker cuando las comprobaciones de lanzamiento
|
||||
incluyen suites en vivo
|
||||
|
||||
Usa los artefactos Docker antes de reejecutar. El planificador de ruta de lanzamiento sube
|
||||
`.artifacts/docker-tests/` con registros de carriles, `summary.json`, `failures.json`,
|
||||
tiempos de fases, JSON del plan del planificador y comandos de reejecución. Para recuperación enfocada,
|
||||
usa `docker_lanes=<lane[,lane]>` en el flujo de trabajo reutilizable live/E2E en lugar de
|
||||
reejecutar todos los fragmentos de lanzamiento. Los comandos de reejecución generados incluyen el
|
||||
`package_artifact_run_id` anterior y entradas de imágenes Docker preparadas cuando están disponibles, de modo que un
|
||||
carril fallido pueda reutilizar el mismo tarball e imágenes GHCR.
|
||||
Usa los artefactos de Docker antes de volver a ejecutar. El planificador de ruta
|
||||
de lanzamiento sube `.artifacts/docker-tests/` con registros de vías,
|
||||
`summary.json`, `failures.json`, tiempos de fases, JSON del plan del planificador
|
||||
y comandos de reejecución. Para recuperación enfocada, usa
|
||||
`docker_lanes=<lane[,lane]>` en el flujo de trabajo reutilizable en vivo/E2E en
|
||||
lugar de volver a ejecutar todos los fragmentos de lanzamiento. Los comandos de
|
||||
reejecución generados incluyen `package_artifact_run_id` anteriores y entradas
|
||||
de imágenes Docker preparadas cuando están disponibles, por lo que una vía fallida
|
||||
puede reutilizar el mismo tarball y las mismas imágenes GHCR.
|
||||
|
||||
### QA Lab
|
||||
|
||||
La máquina QA Lab también forma parte de `OpenClaw Release Checks`. Es la puerta de lanzamiento de
|
||||
comportamiento agente y nivel de canal, separada de Vitest y de la mecánica de paquetes Docker.
|
||||
La caja QA Lab también forma parte de `OpenClaw Release Checks`. Es la puerta de
|
||||
lanzamiento de comportamiento agéntico y a nivel de canal, separada de Vitest y
|
||||
de la mecánica de paquetes de Docker.
|
||||
|
||||
La cobertura QA Lab de lanzamiento incluye:
|
||||
La cobertura de QA Lab de lanzamiento incluye:
|
||||
|
||||
- carril de paridad mock que compara el carril candidato OpenAI con la línea base Opus 4.6
|
||||
usando el paquete de paridad agente
|
||||
- perfil rápido de QA Matrix live usando el entorno `qa-live-shared`
|
||||
- carril QA de Telegram live usando leases de credenciales de Convex CI
|
||||
- vía de paridad simulada que compara la vía candidata de OpenAI con la línea base de Opus 4.6
|
||||
usando el paquete de paridad agéntica
|
||||
- perfil rápido de QA de Matrix en vivo usando el entorno `qa-live-shared`
|
||||
- vía de QA de Telegram en vivo usando préstamos de credenciales de Convex CI
|
||||
- `pnpm qa:otel:smoke` cuando la telemetría de lanzamiento necesita prueba local explícita
|
||||
|
||||
Usa esta máquina para responder "¿el lanzamiento se comporta correctamente en escenarios de QA y flujos de canales live?" Conserva las URL de artefactos de los carriles de paridad, Matrix y Telegram
|
||||
al aprobar el lanzamiento. La cobertura completa de Matrix sigue disponible como una ejecución manual fragmentada de QA-Lab, en lugar del carril crítico de lanzamiento predeterminado.
|
||||
Usa esta caja para responder “¿se comporta correctamente el lanzamiento en
|
||||
escenarios de QA y flujos de canales en vivo?”. Conserva las URLs de artefactos
|
||||
para las vías de paridad, Matrix y Telegram al aprobar el lanzamiento. La
|
||||
cobertura completa de Matrix sigue disponible como ejecución manual fragmentada
|
||||
de QA-Lab en lugar de la vía crítica de lanzamiento predeterminada.
|
||||
|
||||
### Paquete
|
||||
|
||||
La máquina de paquete es la puerta del producto instalable. Está respaldada por
|
||||
La caja de paquete es la puerta del producto instalable. Está respaldada por
|
||||
`Package Acceptance` y el resolutor
|
||||
`scripts/resolve-openclaw-package-candidate.mjs`. El resolutor normaliza un
|
||||
candidato en el tarball `package-under-test` consumido por Docker E2E, valida
|
||||
el inventario del paquete, registra la versión del paquete y el SHA-256, y mantiene la
|
||||
ref del arnés del flujo de trabajo separada de la ref de origen del paquete.
|
||||
candidato en el tarball `package-under-test` consumido por Docker E2E, valida el
|
||||
inventario del paquete, registra la versión del paquete y el SHA-256, y mantiene
|
||||
separada la ref del arnés de flujo de trabajo de la ref de fuente del paquete.
|
||||
|
||||
Fuentes de candidatos admitidas:
|
||||
Fuentes de candidatos compatibles:
|
||||
|
||||
- `source=npm`: `openclaw@beta`, `openclaw@latest` o una versión exacta de lanzamiento de OpenClaw
|
||||
- `source=ref`: empaquetar una rama, etiqueta o SHA de commit completo `package_ref` confiable
|
||||
- `source=ref`: empaqueta una rama, etiqueta o SHA de confirmación completo de `package_ref` de confianza
|
||||
con el arnés `workflow_ref` seleccionado
|
||||
- `source=url`: descargar un `.tgz` HTTPS con `package_sha256` obligatorio
|
||||
- `source=artifact`: reutilizar un `.tgz` subido por otra ejecución de GitHub Actions
|
||||
- `source=url`: descarga un `.tgz` HTTPS con `package_sha256` requerido
|
||||
- `source=artifact`: reutiliza un `.tgz` subido por otra ejecución de GitHub Actions
|
||||
|
||||
`OpenClaw Release Checks` ejecuta Package Acceptance con `source=artifact`, el
|
||||
artefacto preparado del paquete de lanzamiento, `suite_profile=custom`,
|
||||
`OpenClaw Release Checks` ejecuta Aceptación de paquetes con `source=artifact`,
|
||||
el artefacto de paquete de lanzamiento preparado, `suite_profile=custom`,
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
|
||||
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
|
||||
`published_upgrade_survivor_scenarios=reported-issues` y
|
||||
`telegram_mode=mock-openai`. Package Acceptance mantiene la migración, la actualización, la limpieza de dependencias obsoletas de plugins, los fixtures de plugins offline, la actualización de plugins y la QA del paquete Telegram contra el mismo tarball resuelto. La matriz de actualización cubre todas las líneas base estables publicadas en npm desde `2026.4.23` hasta `latest`; usa
|
||||
Package Acceptance con `source=npm` para un candidato ya enviado, o
|
||||
`source=ref`/`source=artifact` para un tarball npm local respaldado por SHA antes de
|
||||
publicar. Es el reemplazo nativo de GitHub
|
||||
para la mayor parte de la cobertura de paquetes/actualizaciones que antes requería
|
||||
Parallels. Las comprobaciones de lanzamiento multisistema siguen siendo importantes para onboarding,
|
||||
instalador y comportamiento específico de plataforma, pero la validación de producto de paquetes/actualizaciones debería
|
||||
preferir Package Acceptance.
|
||||
`telegram_mode=mock-openai`. Aceptación de paquetes mantiene migración,
|
||||
actualización, limpieza de dependencias obsoletas de Plugin, fixtures de Plugin
|
||||
sin conexión, actualización de Plugin y QA del paquete de Telegram contra el
|
||||
mismo tarball resuelto. La matriz de actualización cubre todas las líneas base estables publicadas en npm desde `2026.4.23` hasta `latest`; usa
|
||||
Aceptación de paquetes con `source=npm` para un candidato ya enviado, o
|
||||
`source=ref`/`source=artifact` para un tarball npm local respaldado por SHA antes
|
||||
de publicar. Es el reemplazo nativo de GitHub para la mayor parte de la cobertura
|
||||
de paquete/actualización que antes requería Parallels. Las comprobaciones de
|
||||
lanzamiento entre sistemas operativos siguen siendo importantes para la
|
||||
incorporación, el instalador y el comportamiento de plataforma específicos de
|
||||
cada sistema operativo, pero la validación de producto de paquete/actualización
|
||||
debería preferir Aceptación de paquetes.
|
||||
|
||||
La lista de verificación canónica para validación de actualizaciones y plugins es
|
||||
[Probar actualizaciones y plugins](/es/help/testing-updates-plugins). Úsala al
|
||||
decidir qué carril local, Docker, Package Acceptance o release-check prueba un
|
||||
cambio de instalación/actualización de plugin, limpieza de doctor o migración de paquete publicado.
|
||||
La migración exhaustiva de actualizaciones publicadas desde cada paquete estable `2026.4.23+` es
|
||||
un flujo de trabajo manual `Update Migration` separado, no parte de Full Release CI.
|
||||
La lista de comprobación canónica para validación de actualizaciones y Plugins es
|
||||
[Pruebas de actualizaciones y Plugins](/es/help/testing-updates-plugins). Úsala al
|
||||
decidir qué vía local, de Docker, de Aceptación de paquetes o de comprobación de
|
||||
lanzamiento prueba una instalación/actualización de Plugin, una limpieza de
|
||||
doctor o un cambio de migración de paquete publicado. La migración exhaustiva de
|
||||
actualización publicada desde cada paquete estable `2026.4.23+` es un flujo de
|
||||
trabajo manual separado `Update Migration`, no forma parte de Full Release CI.
|
||||
|
||||
La tolerancia heredada de package-acceptance está intencionalmente limitada en el tiempo. Los paquetes hasta
|
||||
`2026.4.25` pueden usar la ruta de compatibilidad para brechas de metadatos ya publicadas
|
||||
en npm: entradas privadas de inventario de QA ausentes del tarball, ausencia de
|
||||
`gateway install --wrapper`, ausencia de archivos de parche en el fixture git derivado del tarball,
|
||||
ausencia de `update.channel` persistido, ubicaciones heredadas de registros de instalación de plugins,
|
||||
ausencia de persistencia de registros de instalación del marketplace y migración de metadatos de configuración
|
||||
durante `plugins update`. El paquete `2026.4.26` publicado puede advertir
|
||||
por archivos de sello de metadatos de compilación local que ya se enviaron. Los paquetes posteriores
|
||||
deben satisfacer los contratos de paquete modernos; esas mismas brechas fallan la validación de lanzamiento.
|
||||
La flexibilidad heredada de package-acceptance está intencionalmente limitada en
|
||||
el tiempo. Los paquetes hasta `2026.4.25` pueden usar la ruta de compatibilidad
|
||||
para brechas de metadatos ya publicadas en npm: entradas de inventario privado de
|
||||
QA ausentes en el tarball, ausencia de `gateway install --wrapper`, archivos de
|
||||
parche ausentes en el fixture git derivado del tarball, ausencia de
|
||||
`update.channel` persistido, ubicaciones heredadas de registros de instalación de
|
||||
Plugin, ausencia de persistencia de registros de instalación de marketplace y
|
||||
migración de metadatos de configuración durante `plugins update`. El paquete
|
||||
publicado `2026.4.26` puede advertir por archivos de marca de metadatos de build
|
||||
local que ya se enviaron. Los paquetes posteriores deben satisfacer los contratos
|
||||
modernos de paquetes; esas mismas brechas hacen fallar la validación de
|
||||
lanzamiento.
|
||||
|
||||
Usa perfiles de Package Acceptance más amplios cuando la pregunta de lanzamiento sea sobre un
|
||||
paquete instalable real:
|
||||
Usa perfiles más amplios de Aceptación de paquetes cuando la pregunta de
|
||||
lanzamiento trate de un paquete instalable real:
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -481,29 +437,32 @@ gh workflow run package-acceptance.yml \
|
||||
|
||||
Perfiles comunes de paquete:
|
||||
|
||||
- `smoke`: vías rápidas de instalación de paquete/canal/agente, red de Gateway y recarga de configuración
|
||||
- `package`: contratos de instalación/actualización/paquete de Plugin sin ClawHub en vivo; este es el valor predeterminado de comprobación de lanzamiento
|
||||
- `product`: `package` más canales MCP, limpieza de Cron/subagente, búsqueda web de OpenAI y OpenWebUI
|
||||
- `full`: fragmentos de la ruta de lanzamiento de Docker con OpenWebUI
|
||||
- `smoke`: carriles rápidos de instalación de paquete/canal/agente, red de Gateway y
|
||||
recarga de configuración
|
||||
- `package`: contratos de instalación/actualización/paquete de Plugin sin ClawHub en vivo; este es el valor
|
||||
predeterminado de comprobación de lanzamiento
|
||||
- `product`: `package` más canales MCP, limpieza de cron/subagente, búsqueda web
|
||||
de OpenAI y OpenWebUI
|
||||
- `full`: fragmentos de ruta de lanzamiento de Docker con OpenWebUI
|
||||
- `custom`: lista exacta de `docker_lanes` para repeticiones enfocadas
|
||||
|
||||
Para la prueba de Telegram del paquete candidato, habilita `telegram_mode=mock-openai` o
|
||||
`telegram_mode=live-frontier` en Package Acceptance. El flujo de trabajo pasa el tarball
|
||||
resuelto de `package-under-test` a la vía de Telegram; el flujo de trabajo independiente de
|
||||
Telegram todavía acepta una especificación npm publicada para comprobaciones posteriores a la publicación.
|
||||
`telegram_mode=live-frontier` en Package Acceptance. El flujo de trabajo pasa el
|
||||
tarball resuelto de `package-under-test` al carril de Telegram; el flujo de trabajo
|
||||
independiente de Telegram sigue aceptando una especificación npm publicada para comprobaciones posteriores a la publicación.
|
||||
|
||||
## Automatización de publicación de lanzamiento
|
||||
## Automatización de publicación de lanzamientos
|
||||
|
||||
`OpenClaw Release Publish` es el punto de entrada de publicación mutante normal. Orquesta
|
||||
los flujos de trabajo de publicador de confianza en el orden que necesita el lanzamiento:
|
||||
`OpenClaw Release Publish` es el punto de entrada mutante normal para publicación.
|
||||
Orquesta los flujos de trabajo de publicador de confianza en el orden que necesita el lanzamiento:
|
||||
|
||||
1. Extraer la etiqueta de lanzamiento y resolver su SHA de commit.
|
||||
2. Verificar que la etiqueta sea alcanzable desde `main` o `release/*`.
|
||||
3. Ejecutar `pnpm plugins:sync:check`.
|
||||
4. Despachar `Plugin NPM Release` con `publish_scope=all-publishable` y
|
||||
1. Extrae la etiqueta de lanzamiento y resuelve su SHA de commit.
|
||||
2. Verifica que la etiqueta sea alcanzable desde `main` o `release/*`.
|
||||
3. Ejecuta `pnpm plugins:sync:check`.
|
||||
4. Despacha `Plugin NPM Release` con `publish_scope=all-publishable` y
|
||||
`ref=<release-sha>`.
|
||||
5. Despachar `Plugin ClawHub Release` con el mismo ámbito y SHA.
|
||||
6. Despachar `OpenClaw NPM Release` con la etiqueta de lanzamiento, la etiqueta dist de npm y
|
||||
5. Despacha `Plugin ClawHub Release` con el mismo alcance y SHA.
|
||||
6. Despacha `OpenClaw NPM Release` con la etiqueta de lanzamiento, la dist-tag de npm y
|
||||
el `preflight_run_id` guardado.
|
||||
|
||||
Ejemplo de publicación beta:
|
||||
@ -516,7 +475,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Publicación estable con la etiqueta dist beta predeterminada:
|
||||
Publicación estable a la dist-tag beta predeterminada:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -539,87 +498,88 @@ gh workflow run openclaw-release-publish.yml \
|
||||
Usa los flujos de trabajo de nivel inferior `Plugin NPM Release` y `Plugin ClawHub Release`
|
||||
solo para trabajos enfocados de reparación o republicación. Para una reparación de Plugin seleccionado, pasa
|
||||
`plugin_publish_scope=selected` y `plugins=@openclaw/name` a
|
||||
`OpenClaw Release Publish`, o despacha el flujo de trabajo secundario directamente cuando el
|
||||
paquete OpenClaw no deba publicarse.
|
||||
`OpenClaw Release Publish`, o despacha el flujo de trabajo hijo directamente cuando el
|
||||
paquete de OpenClaw no deba publicarse.
|
||||
|
||||
## Entradas del flujo de trabajo NPM
|
||||
|
||||
`OpenClaw NPM Release` acepta estas entradas controladas por el operador:
|
||||
|
||||
- `tag`: etiqueta de lanzamiento obligatoria como `v2026.4.2`, `v2026.4.2-1` o
|
||||
- `tag`: etiqueta de lanzamiento obligatoria, como `v2026.4.2`, `v2026.4.2-1` o
|
||||
`v2026.4.2-beta.1`; cuando `preflight_only=true`, también puede ser el SHA de commit
|
||||
completo de 40 caracteres de la rama del flujo de trabajo actual para una prueba preliminar solo de validación
|
||||
completo de 40 caracteres de la rama del flujo de trabajo actual para una preflight
|
||||
solo de validación
|
||||
- `preflight_only`: `true` solo para validación/compilación/paquete, `false` para la
|
||||
ruta de publicación real
|
||||
- `preflight_run_id`: obligatorio en la ruta de publicación real para que el flujo de trabajo reutilice
|
||||
el tarball preparado de la ejecución preliminar correcta
|
||||
- `npm_dist_tag`: etiqueta npm de destino para la ruta de publicación; el valor predeterminado es `beta`
|
||||
el tarball preparado de la ejecución de preflight correcta
|
||||
- `npm_dist_tag`: etiqueta de destino npm para la ruta de publicación; el valor predeterminado es `beta`
|
||||
|
||||
`OpenClaw Release Publish` acepta estas entradas controladas por el operador:
|
||||
|
||||
- `tag`: etiqueta de lanzamiento obligatoria; ya debe existir
|
||||
- `preflight_run_id`: id de ejecución preliminar correcta de `OpenClaw NPM Release`;
|
||||
- `preflight_run_id`: id de ejecución de preflight correcta de `OpenClaw NPM Release`;
|
||||
obligatorio cuando `publish_openclaw_npm=true`
|
||||
- `npm_dist_tag`: etiqueta npm de destino para el paquete OpenClaw
|
||||
- `npm_dist_tag`: etiqueta de destino npm para el paquete de OpenClaw
|
||||
- `plugin_publish_scope`: el valor predeterminado es `all-publishable`; usa `selected` solo
|
||||
para trabajos enfocados de reparación
|
||||
- `plugins`: nombres de paquetes `@openclaw/*` separados por comas cuando
|
||||
- `plugins`: nombres de paquete `@openclaw/*` separados por comas cuando
|
||||
`plugin_publish_scope=selected`
|
||||
- `publish_openclaw_npm`: el valor predeterminado es `true`; establece `false` solo cuando uses el
|
||||
flujo de trabajo como orquestador de reparación solo de Plugins
|
||||
flujo de trabajo como orquestador de reparación solo para Plugin
|
||||
|
||||
`OpenClaw Release Checks` acepta estas entradas controladas por el operador:
|
||||
|
||||
- `ref`: rama, etiqueta o SHA de commit completo para validar. Las comprobaciones con secretos
|
||||
requieren que el commit resuelto sea alcanzable desde una rama de OpenClaw o
|
||||
etiqueta de lanzamiento.
|
||||
una etiqueta de lanzamiento.
|
||||
|
||||
Reglas:
|
||||
|
||||
- Las etiquetas estables y de corrección pueden publicarse en `beta` o `latest`
|
||||
- Las etiquetas beta de prelanzamiento solo pueden publicarse en `beta`
|
||||
- Las etiquetas beta preliminares solo pueden publicarse en `beta`
|
||||
- Para `OpenClaw NPM Release`, la entrada de SHA de commit completo solo se permite cuando
|
||||
`preflight_only=true`
|
||||
- `OpenClaw Release Checks` y `Full Release Validation` siempre son
|
||||
solo de validación
|
||||
- La ruta de publicación real debe usar el mismo `npm_dist_tag` usado durante la prueba preliminar;
|
||||
el flujo de trabajo verifica esos metadatos antes de que la publicación continúe
|
||||
- La ruta de publicación real debe usar el mismo `npm_dist_tag` usado durante la preflight;
|
||||
el flujo de trabajo verifica esos metadatos antes de que continúe la publicación
|
||||
|
||||
## Secuencia de lanzamiento estable de npm
|
||||
|
||||
Al preparar un lanzamiento estable de npm:
|
||||
|
||||
1. Ejecuta `OpenClaw NPM Release` con `preflight_only=true`
|
||||
- Antes de que exista una etiqueta, puedes usar el SHA de commit completo de la rama del flujo de trabajo actual
|
||||
para una ejecución de prueba solo de validación del flujo de trabajo preliminar
|
||||
2. Elige `npm_dist_tag=beta` para el flujo normal que publica primero en beta, o `latest` solo
|
||||
- Antes de que exista una etiqueta, puedes usar el SHA de commit completo actual de la rama del flujo de trabajo
|
||||
para un ensayo solo de validación del flujo de trabajo de preflight
|
||||
2. Elige `npm_dist_tag=beta` para el flujo normal de beta primero, o `latest` solo
|
||||
cuando quieras intencionadamente una publicación estable directa
|
||||
3. Ejecuta `Full Release Validation` en la rama de lanzamiento, la etiqueta de lanzamiento o el SHA de commit
|
||||
completo cuando quieras CI normal más caché de prompts en vivo, Docker, QA Lab,
|
||||
Matrix y cobertura de Telegram desde un solo flujo de trabajo manual
|
||||
3. Ejecuta `Full Release Validation` en la rama de lanzamiento, la etiqueta de lanzamiento o el SHA de
|
||||
commit completo cuando quieras CI normal más caché de prompts en vivo, Docker, QA Lab,
|
||||
Matrix y cobertura de Telegram desde un flujo de trabajo manual
|
||||
4. Si intencionadamente solo necesitas el grafo de pruebas normal determinista, ejecuta el
|
||||
flujo de trabajo manual `CI` en la referencia de lanzamiento en su lugar
|
||||
5. Guarda el `preflight_run_id` correcto
|
||||
6. Ejecuta `OpenClaw Release Publish` con el mismo `tag`, el mismo `npm_dist_tag`
|
||||
y el `preflight_run_id` guardado; publica los Plugins externalizados en npm
|
||||
6. Ejecuta `OpenClaw Release Publish` con la misma `tag`, el mismo `npm_dist_tag`
|
||||
y el `preflight_run_id` guardado; publica Plugins externalizados en npm
|
||||
y ClawHub antes de promover el paquete npm de OpenClaw
|
||||
7. Si el lanzamiento llegó a `beta`, usa el flujo de trabajo privado
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
para promover esa versión estable de `beta` a `latest`
|
||||
8. Si el lanzamiento se publicó intencionadamente directamente en `latest` y `beta`
|
||||
debe seguir inmediatamente la misma compilación estable, usa ese mismo flujo de trabajo privado
|
||||
para apuntar ambas etiquetas dist a la versión estable, o deja que su sincronización programada
|
||||
debe seguir de inmediato la misma compilación estable, usa ese mismo flujo de trabajo privado
|
||||
para apuntar ambas dist-tags a la versión estable, o deja que su sincronización programada
|
||||
de autorreparación mueva `beta` más tarde
|
||||
|
||||
La mutación de etiquetas dist vive en el repositorio privado por seguridad porque todavía
|
||||
requiere `NPM_TOKEN`, mientras que el repositorio público mantiene una publicación solo con OIDC.
|
||||
La mutación de dist-tag vive en el repositorio privado por seguridad, porque todavía
|
||||
requiere `NPM_TOKEN`, mientras que el repositorio público mantiene publicación solo con OIDC.
|
||||
|
||||
Eso mantiene tanto la ruta de publicación directa como la ruta de promoción que publica primero en beta
|
||||
Eso mantiene tanto la ruta de publicación directa como la ruta de promoción beta primero
|
||||
documentadas y visibles para el operador.
|
||||
|
||||
Si un mantenedor debe recurrir a la autenticación local de npm, ejecuta cualquier comando de la
|
||||
CLI de 1Password (`op`) solo dentro de una sesión tmux dedicada. No llames a `op`
|
||||
directamente desde la shell principal del agente; mantenerlo dentro de tmux hace que los prompts,
|
||||
Si un mantenedor debe recurrir a la autenticación npm local, ejecuta cualquier comando de CLI
|
||||
de 1Password (`op`) solo dentro de una sesión tmux dedicada. No llames a `op`
|
||||
directamente desde el shell principal del agente; mantenerlo dentro de tmux hace que prompts,
|
||||
alertas y gestión de OTP sean observables y evita alertas repetidas del host.
|
||||
|
||||
## Referencias públicas
|
||||
|
||||
@ -1,47 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Quieres ejecutar trabajo en segundo plano o en paralelo mediante el agente
|
||||
- Estás cambiando sessions_spawn o la política de herramientas de subagentes
|
||||
- Quieres trabajo en segundo plano o en paralelo mediante el agente
|
||||
- Está cambiando sessions_spawn o la política de herramientas de subagentes
|
||||
- Estás implementando o solucionando problemas de sesiones de subagentes vinculadas a hilos
|
||||
sidebarTitle: Sub-agents
|
||||
summary: Inicia ejecuciones aisladas de agentes en segundo plano que anuncian los resultados de vuelta en el chat del solicitante
|
||||
summary: Inicia ejecuciones aisladas de agentes en segundo plano que informan los resultados al chat del solicitante
|
||||
title: Subagentes
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:26:13Z"
|
||||
generated_at: "2026-05-04T07:04:28Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d0df39e06b952def3eb0b296f36c7dc8c0b0a115785d865236a970c5d453fc37
|
||||
source_hash: 65d60bf6813d667b7311aa28109d4bd6be012a16e638c64cfff130831db88cd8
|
||||
source_path: tools/subagents.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Los subagentes son ejecuciones de agentes en segundo plano generadas desde una ejecución de agente existente.
|
||||
Los subagentes son ejecuciones de agente en segundo plano generadas desde una ejecución de agente existente.
|
||||
Se ejecutan en su propia sesión (`agent:<agentId>:subagent:<uuid>`) y,
|
||||
al finalizar, **anuncian** su resultado de vuelta al canal de chat
|
||||
solicitante. Cada ejecución de subagente se rastrea como una
|
||||
solicitante. Cada ejecución de subagente se registra como una
|
||||
[tarea en segundo plano](/es/automation/tasks).
|
||||
|
||||
Objetivos principales:
|
||||
|
||||
- Paralelizar el trabajo de "investigación / tarea larga / herramienta lenta" sin bloquear la ejecución principal.
|
||||
- Mantener los subagentes aislados de forma predeterminada (separación de sesiones + sandboxing opcional).
|
||||
- Mantener la superficie de herramientas difícil de usar incorrectamente: los subagentes **no** reciben herramientas de sesión de forma predeterminada.
|
||||
- Paralelizar trabajo de "investigación / tarea larga / herramienta lenta" sin bloquear la ejecución principal.
|
||||
- Mantener los subagentes aislados por defecto (separación de sesiones + sandboxing opcional).
|
||||
- Mantener la superficie de herramientas difícil de usar indebidamente: los subagentes **no** reciben herramientas de sesión por defecto.
|
||||
- Admitir profundidad de anidamiento configurable para patrones de orquestador.
|
||||
|
||||
<Note>
|
||||
**Nota de costo:** cada subagente tiene su propio contexto y uso de tokens de
|
||||
forma predeterminada. Para tareas pesadas o repetitivas, configura un modelo más económico para los subagentes
|
||||
**Nota de coste:** cada subagente tiene su propio contexto y uso de tokens por
|
||||
defecto. Para tareas pesadas o repetitivas, establece un modelo más barato para los subagentes
|
||||
y mantén tu agente principal en un modelo de mayor calidad. Configura mediante
|
||||
`agents.defaults.subagents.model` o sobrescrituras por agente. Cuando un hijo
|
||||
`agents.defaults.subagents.model` o anulaciones por agente. Cuando un hijo
|
||||
realmente necesita la transcripción actual del solicitante, el agente puede solicitar
|
||||
`context: "fork"` en esa generación concreta. Las sesiones de subagente vinculadas a hilo usan de forma predeterminada
|
||||
`context: "fork"` en esa generación concreta. Las sesiones de subagente vinculadas a hilos tienen por defecto
|
||||
`context: "fork"` porque ramifican la conversación actual en un
|
||||
hilo de seguimiento.
|
||||
</Note>
|
||||
|
||||
## Comando slash
|
||||
## Comando de barra
|
||||
|
||||
Usa `/subagents` para inspeccionar o controlar ejecuciones de subagentes para la **sesión
|
||||
Usa `/subagents` para inspeccionar o controlar ejecuciones de subagente para la **sesión
|
||||
actual**:
|
||||
|
||||
```text
|
||||
@ -54,7 +54,7 @@ actual**:
|
||||
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
|
||||
```
|
||||
|
||||
Usa [`/steer <message>`](/es/tools/steer) de nivel superior para orientar la ejecución activa de la sesión solicitante actual. Usa `/subagents steer <id|#> <message>` cuando el destino sea una ejecución hija.
|
||||
Usa [`/steer <message>`](/es/tools/steer) de nivel superior para dirigir la ejecución activa de la sesión solicitante actual. Usa `/subagents steer <id|#> <message>` cuando el destino sea una ejecución hija.
|
||||
|
||||
`/subagents info` muestra metadatos de ejecución (estado, marcas de tiempo, id de sesión,
|
||||
ruta de transcripción, limpieza). Usa `sessions_history` para una vista de recuperación acotada
|
||||
@ -63,8 +63,8 @@ necesites la transcripción completa sin procesar.
|
||||
|
||||
### Controles de vinculación de hilos
|
||||
|
||||
Estos comandos funcionan en canales que admiten vinculaciones persistentes de hilos.
|
||||
Consulta [Canales compatibles con hilos](#thread-supporting-channels) más abajo.
|
||||
Estos comandos funcionan en canales que admiten vinculaciones de hilos persistentes.
|
||||
Consulta [Canales compatibles con hilos](#thread-supporting-channels) abajo.
|
||||
|
||||
```text
|
||||
/focus <subagent-label|session-key|session-id|session-label>
|
||||
@ -76,121 +76,122 @@ Consulta [Canales compatibles con hilos](#thread-supporting-channels) más abajo
|
||||
|
||||
### Comportamiento de generación
|
||||
|
||||
`/subagents spawn` inicia un subagente en segundo plano como comando de usuario (no un
|
||||
reenvío interno) y envía una actualización final de finalización de vuelta al
|
||||
`/subagents spawn` inicia un subagente en segundo plano como comando de usuario (no como
|
||||
relevo interno) y envía una actualización final de finalización de vuelta al
|
||||
chat solicitante cuando termina la ejecución.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Finalización no bloqueante y basada en inserción">
|
||||
<Accordion title="Finalización no bloqueante basada en push">
|
||||
- El comando de generación no bloquea; devuelve un id de ejecución inmediatamente.
|
||||
- Al finalizar, el subagente anuncia un mensaje de resumen/resultado de vuelta al canal de chat solicitante.
|
||||
- La finalización se basa en inserción. Una vez generado, **no** sondees `/subagents list`, `sessions_list` ni `sessions_history` en un bucle solo para esperar a que termine; inspecciona el estado solo bajo demanda para depuración o intervención.
|
||||
- Al finalizar, OpenClaw cierra con el mejor esfuerzo las pestañas/procesos del navegador rastreados que abrió esa sesión de subagente antes de que continúe el flujo de limpieza del anuncio.
|
||||
- La finalización se basa en push. Una vez generado, **no** sondees `/subagents list`, `sessions_list` ni `sessions_history` en un bucle solo para esperar a que termine; inspecciona el estado solo bajo demanda para depuración o intervención.
|
||||
- Al finalizar, OpenClaw cierra con el mejor esfuerzo las pestañas/procesos de navegador registrados abiertos por esa sesión de subagente antes de que continúe el flujo de limpieza del anuncio.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Resiliencia de entrega de generación manual">
|
||||
- OpenClaw intenta primero la entrega directa de `agent` con una clave de idempotencia estable.
|
||||
- Si la entrega directa falla, recurre al enrutamiento por cola.
|
||||
- Si el enrutamiento por cola aún no está disponible, el anuncio se reintenta con un retroceso exponencial corto antes del abandono final.
|
||||
- La entrega de finalización conserva la ruta resuelta del solicitante: las rutas de finalización vinculadas a hilo o a conversación prevalecen cuando están disponibles; si el origen de finalización solo proporciona un canal, OpenClaw completa el destino/cuenta faltante a partir de la ruta resuelta de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que la entrega directa siga funcionando.
|
||||
- Si el turno de finalización del agente solicitante falla, no produce salida visible o devuelve un prefijo obviamente incompleto del resultado hijo capturado, OpenClaw recurre a la entrega directa de finalización desde el resultado hijo capturado.
|
||||
- Si no se puede usar la entrega directa, recurre al enrutamiento por cola.
|
||||
- Si el enrutamiento por cola todavía no está disponible, el anuncio se reintenta con un breve retroceso exponencial antes de abandonar definitivamente.
|
||||
- La entrega de finalización conserva la ruta del solicitante resuelta: las rutas de finalización vinculadas a hilos o vinculadas a conversaciones prevalecen cuando están disponibles; si el origen de finalización solo proporciona un canal, OpenClaw rellena el destino/cuenta faltante desde la ruta resuelta de la sesión solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que la entrega directa siga funcionando.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Metadatos de traspaso de finalización">
|
||||
El traspaso de finalización a la sesión solicitante es contexto interno generado en tiempo de ejecución
|
||||
(no texto escrito por el usuario) e incluye:
|
||||
El traspaso de finalización a la sesión solicitante es contexto interno generado
|
||||
en tiempo de ejecución (no texto escrito por el usuario) e incluye:
|
||||
|
||||
- `Result` — el texto visible más reciente de respuesta de `assistant`; de lo contrario, el texto más reciente saneado de herramienta/toolResult. Las ejecuciones fallidas terminales no reutilizan texto de respuesta capturado.
|
||||
- `Result` — texto de la última respuesta visible de `assistant`, o en su defecto el último texto saneado de herramienta/toolResult. Las ejecuciones fallidas terminales no reutilizan texto de respuesta capturado.
|
||||
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
|
||||
- Estadísticas compactas de tiempo de ejecución/tokens.
|
||||
- Una instrucción de entrega que indica al agente solicitante que reescriba con voz normal de asistente (no reenviar metadatos internos sin procesar).
|
||||
- Una instrucción de entrega que indica al agente solicitante que reescriba con voz normal de asistente (no que reenvíe metadatos internos sin procesar).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Modos y tiempo de ejecución ACP">
|
||||
- `--model` y `--thinking` sobrescriben los valores predeterminados para esa ejecución específica.
|
||||
- `--model` y `--thinking` anulan los valores por defecto para esa ejecución específica.
|
||||
- Usa `info`/`log` para inspeccionar detalles y salida después de la finalización.
|
||||
- `/subagents spawn` es modo de una sola ejecución (`mode: "run"`). Para sesiones persistentes vinculadas a hilo, usa `sessions_spawn` con `thread: true` y `mode: "session"`.
|
||||
- Para sesiones de arnés ACP (Claude Code, Gemini CLI, OpenCode o Codex ACP/acpx explícito), usa `sessions_spawn` con `runtime: "acp"` cuando la herramienta anuncie ese tiempo de ejecución. Consulta [Modelo de entrega ACP](/es/tools/acp-agents#delivery-model) al depurar finalizaciones o bucles de agente a agente. Cuando el Plugin `codex` está habilitado, el control de chat/hilo de Codex debería preferir `/codex ...` en lugar de ACP salvo que el usuario solicite explícitamente ACP/acpx.
|
||||
- OpenClaw oculta `runtime: "acp"` hasta que ACP esté habilitado, el solicitante no esté en sandbox, y se haya cargado un Plugin de backend como `acpx`. `runtime: "acp"` espera un id de arnés ACP externo, o una entrada `agents.list[]` con `runtime.type="acp"`; usa el tiempo de ejecución predeterminado de subagente para agentes normales de configuración de OpenClaw desde `agents_list`.
|
||||
- `/subagents spawn` es modo de una sola ejecución (`mode: "run"`). Para sesiones persistentes vinculadas a hilos, usa `sessions_spawn` con `thread: true` y `mode: "session"`.
|
||||
- Para sesiones de harness ACP (Claude Code, Gemini CLI, OpenCode o Codex ACP/acpx explícito), usa `sessions_spawn` con `runtime: "acp"` cuando la herramienta anuncie ese tiempo de ejecución. Consulta [Modelo de entrega ACP](/es/tools/acp-agents#delivery-model) al depurar finalizaciones o bucles de agente a agente. Cuando el plugin `codex` está habilitado, el control de chat/hilo de Codex debe preferir `/codex ...` sobre ACP salvo que el usuario pida explícitamente ACP/acpx.
|
||||
- OpenClaw oculta `runtime: "acp"` hasta que ACP esté habilitado, el solicitante no esté en sandbox y se cargue un plugin de backend como `acpx`. `runtime: "acp"` espera un id de harness ACP externo, o una entrada `agents.list[]` con `runtime.type="acp"`; usa el tiempo de ejecución de subagente por defecto para agentes normales de configuración de OpenClaw desde `agents_list`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Modos de contexto
|
||||
|
||||
Los subagentes nativos comienzan aislados salvo que el llamador solicite explícitamente bifurcar
|
||||
Los subagentes nativos comienzan aislados salvo que el llamador pida explícitamente bifurcar
|
||||
la transcripción actual.
|
||||
|
||||
| Modo | Cuándo usarlo | Comportamiento |
|
||||
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `isolated` | Investigación nueva, implementación independiente, trabajo con herramientas lentas, o cualquier cosa que pueda explicarse en el texto de la tarea | Crea una transcripción hija limpia. Este es el valor predeterminado y reduce el uso de tokens. |
|
||||
| `fork` | Trabajo que depende de la conversación actual, resultados previos de herramientas o instrucciones matizadas ya presentes en la transcripción del solicitante | Ramifica la transcripción solicitante en la sesión hija antes de que el hijo comience. |
|
||||
| `isolated` | Investigación nueva, implementación independiente, trabajo con herramientas lentas o cualquier cosa que pueda explicarse en el texto de la tarea | Crea una transcripción hija limpia. Este es el valor por defecto y mantiene más bajo el uso de tokens. |
|
||||
| `fork` | Trabajo que depende de la conversación actual, resultados previos de herramientas o instrucciones matizadas ya presentes en la transcripción del solicitante | Ramifica la transcripción del solicitante en la sesión hija antes de que el hijo comience. |
|
||||
|
||||
Usa `fork` con moderación. Es para delegación sensible al contexto, no un
|
||||
sustituto de escribir una instrucción de tarea clara.
|
||||
sustituto de escribir una indicación de tarea clara.
|
||||
|
||||
## Herramienta: `sessions_spawn`
|
||||
|
||||
Inicia una ejecución de subagente con `deliver: false` en el carril global `subagent`,
|
||||
luego ejecuta un paso de anuncio y publica la respuesta de anuncio en el canal de chat
|
||||
solicitante.
|
||||
luego ejecuta un paso de anuncio y publica la respuesta del anuncio en el canal
|
||||
de chat solicitante.
|
||||
|
||||
La disponibilidad depende de la política efectiva de herramientas del llamador. Los perfiles `coding` y
|
||||
`full` exponen `sessions_spawn` de forma predeterminada. El perfil `messaging`
|
||||
`full` exponen `sessions_spawn` por defecto. El perfil `messaging`
|
||||
no lo hace; añade `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
|
||||
"subagents"]` o usa `tools.profile: "coding"` para agentes que deban delegar
|
||||
trabajo. Las políticas de canal/grupo, proveedor, sandbox y permitir/denegar por agente
|
||||
aún pueden eliminar la herramienta después de la etapa de perfil. Usa `/tools` desde la misma
|
||||
trabajo. Las políticas de canal/grupo, proveedor, sandbox y permisos/denegaciones por agente
|
||||
todavía pueden eliminar la herramienta después de la etapa de perfil. Usa `/tools` desde la misma
|
||||
sesión para confirmar la lista efectiva de herramientas.
|
||||
|
||||
**Valores predeterminados:**
|
||||
**Valores por defecto:**
|
||||
|
||||
- **Modelo:** hereda del llamador salvo que configures `agents.defaults.subagents.model` (o `agents.list[].subagents.model` por agente); un `sessions_spawn.model` explícito sigue prevaleciendo.
|
||||
- **Thinking:** hereda del llamador salvo que configures `agents.defaults.subagents.thinking` (o `agents.list[].subagents.thinking` por agente); un `sessions_spawn.thinking` explícito sigue prevaleciendo.
|
||||
- **Tiempo de espera de ejecución:** si se omite `sessions_spawn.runTimeoutSeconds`, OpenClaw usa `agents.defaults.subagents.runTimeoutSeconds` cuando está configurado; de lo contrario, recurre a `0` (sin tiempo de espera).
|
||||
- **Modelo:** hereda del llamador salvo que establezcas `agents.defaults.subagents.model` (o `agents.list[].subagents.model` por agente); un `sessions_spawn.model` explícito sigue teniendo prioridad.
|
||||
- **Thinking:** hereda del llamador salvo que establezcas `agents.defaults.subagents.thinking` (o `agents.list[].subagents.thinking` por agente); un `sessions_spawn.thinking` explícito sigue teniendo prioridad.
|
||||
- **Tiempo de espera de ejecución:** si se omite `sessions_spawn.runTimeoutSeconds`, OpenClaw usa `agents.defaults.subagents.runTimeoutSeconds` cuando está establecido; de lo contrario, recurre a `0` (sin tiempo de espera).
|
||||
|
||||
### Parámetros de la herramienta
|
||||
### Parámetros de herramienta
|
||||
|
||||
<ParamField path="task" type="string" required>
|
||||
La descripción de la tarea para el subagente.
|
||||
</ParamField>
|
||||
<ParamField path="label" type="string">
|
||||
Etiqueta opcional legible por humanos.
|
||||
Etiqueta opcional legible para humanos.
|
||||
</ParamField>
|
||||
<ParamField path="agentId" type="string">
|
||||
Generar bajo otro id de agente cuando lo permita `subagents.allowAgents`.
|
||||
Genera bajo otro id de agente cuando lo permite `subagents.allowAgents`.
|
||||
</ParamField>
|
||||
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
|
||||
`acp` es solo para arneses ACP externos (`claude`, `droid`, `gemini`, `opencode`, o Codex ACP/acpx solicitado explícitamente) y para entradas `agents.list[]` cuyo `runtime.type` es `acp`.
|
||||
`acp` es solo para harnesses ACP externos (`claude`, `droid`, `gemini`, `opencode` o Codex ACP/acpx solicitado explícitamente) y para entradas `agents.list[]` cuyo `runtime.type` es `acp`.
|
||||
</ParamField>
|
||||
<ParamField path="resumeSessionId" type="string">
|
||||
Solo ACP. Reanuda una sesión existente de arnés ACP cuando `runtime: "acp"`; se ignora para generaciones nativas de subagentes.
|
||||
Solo ACP. Reanuda una sesión de harness ACP existente cuando `runtime: "acp"`; se ignora para generaciones de subagente nativas.
|
||||
</ParamField>
|
||||
<ParamField path="streamTo" type='"parent"'>
|
||||
Solo ACP. Transmite la salida de ejecución ACP a la sesión principal cuando `runtime: "acp"`; omitir para generaciones nativas de subagentes.
|
||||
Solo ACP. Transmite la salida de ejecución ACP a la sesión padre cuando `runtime: "acp"`; omítelo para generaciones de subagente nativas.
|
||||
</ParamField>
|
||||
<ParamField path="model" type="string">
|
||||
Sobrescribe el modelo del subagente. Los valores no válidos se omiten y el subagente se ejecuta con el modelo predeterminado con una advertencia en el resultado de la herramienta.
|
||||
Anula el modelo de subagente. Los valores no válidos se omiten y el subagente se ejecuta en el modelo por defecto con una advertencia en el resultado de la herramienta.
|
||||
</ParamField>
|
||||
<ParamField path="thinking" type="string">
|
||||
Sobrescribe el nivel de thinking para la ejecución del subagente.
|
||||
Anula el nivel de thinking para la ejecución del subagente.
|
||||
</ParamField>
|
||||
<ParamField path="runTimeoutSeconds" type="number">
|
||||
Usa de forma predeterminada `agents.defaults.subagents.runTimeoutSeconds` cuando está configurado; de lo contrario, `0`. Cuando se configura, la ejecución del subagente se cancela después de N segundos.
|
||||
Por defecto es `agents.defaults.subagents.runTimeoutSeconds` cuando está establecido; de lo contrario, `0`. Cuando se establece, la ejecución del subagente se aborta después de N segundos.
|
||||
</ParamField>
|
||||
<ParamField path="thread" type="boolean" default="false">
|
||||
Cuando es `true`, solicita vinculación de hilo de canal para esta sesión de subagente.
|
||||
</ParamField>
|
||||
<ParamField path="mode" type='"run" | "session"' default="run">
|
||||
Si `thread: true` y se omite `mode`, el valor predeterminado pasa a ser `session`. `mode: "session"` requiere `thread: true`.
|
||||
Si `thread: true` y se omite `mode`, el valor por defecto pasa a ser `session`. `mode: "session"` requiere `thread: true`.
|
||||
</ParamField>
|
||||
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
|
||||
`"delete"` archiva inmediatamente después del anuncio (aún conserva la transcripción mediante renombrado).
|
||||
`"delete"` archiva inmediatamente después del anuncio (sigue conservando la transcripción mediante renombrado).
|
||||
</ParamField>
|
||||
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
|
||||
`require` rechaza la generación salvo que el tiempo de ejecución hijo de destino esté en sandbox.
|
||||
</ParamField>
|
||||
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
|
||||
`fork` ramifica la transcripción actual del solicitante en la sesión hija. Solo subagentes nativos. Las generaciones vinculadas a hilo usan `fork` de forma predeterminada; las generaciones no vinculadas a hilo usan `isolated` de forma predeterminada.
|
||||
`fork` ramifica la transcripción actual del solicitante en la sesión hija. Solo subagentes nativos. Las generaciones vinculadas a hilos tienen por defecto `fork`; las generaciones no vinculadas a hilos tienen por defecto `isolated`.
|
||||
</ParamField>
|
||||
|
||||
<Warning>
|
||||
@ -199,7 +200,7 @@ sesión para confirmar la lista efectiva de herramientas.
|
||||
`message`/`sessions_send` desde la ejecución generada.
|
||||
</Warning>
|
||||
|
||||
## Sesiones vinculadas a hilo
|
||||
## Sesiones vinculadas a hilos
|
||||
|
||||
Cuando las vinculaciones de hilos están habilitadas para un canal, un subagente puede permanecer vinculado
|
||||
a un hilo para que los mensajes de seguimiento del usuario en ese hilo sigan enrutándose a la
|
||||
@ -208,18 +209,18 @@ misma sesión de subagente.
|
||||
### Canales compatibles con hilos
|
||||
|
||||
**Discord** es actualmente el único canal compatible. Admite
|
||||
sesiones persistentes de subagente vinculadas a hilo (`sessions_spawn` con
|
||||
sesiones de subagente persistentes vinculadas a hilos (`sessions_spawn` con
|
||||
`thread: true`), controles manuales de hilo (`/focus`, `/unfocus`, `/agents`,
|
||||
`/session idle`, `/session max-age`) y claves de adaptador
|
||||
`channels.discord.threadBindings.enabled`,
|
||||
`channels.discord.threadBindings.idleHours`,
|
||||
`channels.discord.threadBindings.maxAgeHours`, y
|
||||
`channels.discord.threadBindings.maxAgeHours` y
|
||||
`channels.discord.threadBindings.spawnSessions`.
|
||||
|
||||
### Flujo rápido
|
||||
|
||||
<Steps>
|
||||
<Step title="Generar">
|
||||
<Step title="Crear">
|
||||
`sessions_spawn` con `thread: true` (y opcionalmente `mode: "session"`).
|
||||
</Step>
|
||||
<Step title="Vincular">
|
||||
@ -229,7 +230,7 @@ sesiones persistentes de subagente vinculadas a hilo (`sessions_spawn` con
|
||||
Las respuestas y los mensajes de seguimiento en ese hilo se enrutan a la sesión vinculada.
|
||||
</Step>
|
||||
<Step title="Inspeccionar tiempos de espera">
|
||||
Usa `/session idle` para inspeccionar/actualizar el desenfoque automático por inactividad y
|
||||
Usa `/session idle` para inspeccionar/actualizar el autoenfoque por inactividad y
|
||||
`/session max-age` para controlar el límite máximo.
|
||||
</Step>
|
||||
<Step title="Desvincular">
|
||||
@ -239,59 +240,59 @@ sesiones persistentes de subagente vinculadas a hilo (`sessions_spawn` con
|
||||
|
||||
### Controles manuales
|
||||
|
||||
| Comando | Efecto |
|
||||
| Comando | Efecto |
|
||||
| ------------------ | --------------------------------------------------------------------- |
|
||||
| `/focus <target>` | Vincula el hilo actual (o crea uno) a un destino de subagente/sesión |
|
||||
| `/unfocus` | Elimina la vinculación del hilo vinculado actual |
|
||||
| `/agents` | Lista las ejecuciones activas y el estado de vinculación (`thread:<id>` o `unbound`) |
|
||||
| `/session idle` | Inspecciona/actualiza el desenfoque automático por inactividad (solo hilos vinculados enfocados) |
|
||||
| `/session max-age` | Inspecciona/actualiza el límite estricto (solo hilos vinculados enfocados) |
|
||||
| `/unfocus` | Elimina la vinculación del hilo vinculado actual |
|
||||
| `/agents` | Lista ejecuciones activas y estado de vinculación (`thread:<id>` o `unbound`) |
|
||||
| `/session idle` | Inspecciona/actualiza el autoenfoque por inactividad (solo hilos vinculados enfocados) |
|
||||
| `/session max-age` | Inspecciona/actualiza el límite máximo (solo hilos vinculados enfocados) |
|
||||
|
||||
### Interruptores de configuración
|
||||
### Conmutadores de configuración
|
||||
|
||||
- **Valor global predeterminado:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
|
||||
- **Las claves de anulación por canal y de vinculación automática al crear** son específicas del adaptador. Consulta [Canales compatibles con hilos](#thread-supporting-channels) arriba.
|
||||
- **Valor predeterminado global:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
|
||||
- **Las claves de sobrescritura de canal y vinculación automática al crear** son específicas del adaptador. Consulta [Canales compatibles con hilos](#thread-supporting-channels) arriba.
|
||||
|
||||
Consulta la [referencia de configuración](/es/gateway/configuration-reference) y
|
||||
[comandos de barra](/es/tools/slash-commands) para ver los detalles actuales del adaptador.
|
||||
Consulta la [Referencia de configuración](/es/gateway/configuration-reference) y
|
||||
[Comandos slash](/es/tools/slash-commands) para conocer los detalles actuales del adaptador.
|
||||
|
||||
### Lista de permitidos
|
||||
|
||||
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
|
||||
Lista de ids de agente que pueden apuntarse mediante un `agentId` explícito (`["*"]` permite cualquiera). Valor predeterminado: solo el agente solicitante. Si configuras una lista y aun así quieres que el solicitante se genere a sí mismo con `agentId`, incluye el id del solicitante en la lista.
|
||||
Lista de ids de agente que pueden usarse como destino mediante `agentId` explícito (`["*"]` permite cualquiera). Valor predeterminado: solo el agente solicitante. Si defines una lista y aun así quieres que el solicitante se cree a sí mismo con `agentId`, incluye el id del solicitante en la lista.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
|
||||
Lista predeterminada de agentes de destino permitidos que se usa cuando el agente solicitante no define su propio `subagents.allowAgents`.
|
||||
Lista de permitidos predeterminada de agentes de destino usada cuando el agente solicitante no define su propio `subagents.allowAgents`.
|
||||
</ParamField>
|
||||
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
|
||||
Bloquea las llamadas `sessions_spawn` que omiten `agentId` (fuerza la selección explícita de perfil). Anulación por agente: `agents.list[].subagents.requireAgentId`.
|
||||
Bloquea llamadas a `sessions_spawn` que omiten `agentId` (fuerza la selección explícita de perfil). Sobrescritura por agente: `agents.list[].subagents.requireAgentId`.
|
||||
</ParamField>
|
||||
|
||||
Si la sesión solicitante está en sandbox, `sessions_spawn` rechaza destinos
|
||||
que se ejecutarían fuera de sandbox.
|
||||
que se ejecutarían sin sandbox.
|
||||
|
||||
### Descubrimiento
|
||||
|
||||
Usa `agents_list` para ver qué ids de agente están permitidos actualmente para
|
||||
`sessions_spawn`. La respuesta incluye el modelo efectivo de cada agente listado
|
||||
y los metadatos de runtime incrustados para que los llamadores puedan distinguir Pi, servidor de aplicaciones de Codex
|
||||
y metadatos de runtime incrustados para que los llamadores puedan distinguir PI, el servidor de aplicación de Codex
|
||||
y otros runtimes nativos configurados.
|
||||
|
||||
### Archivado automático
|
||||
|
||||
- Las sesiones de subagente se archivan automáticamente después de `agents.defaults.subagents.archiveAfterMinutes` (valor predeterminado `60`).
|
||||
- El archivado usa `sessions.delete` y renombra la transcripción a `*.deleted.<timestamp>` (misma carpeta).
|
||||
- `cleanup: "delete"` archiva inmediatamente después del anuncio (aun así conserva la transcripción mediante el cambio de nombre).
|
||||
- El archivado automático es de mejor esfuerzo; los temporizadores pendientes se pierden si el Gateway se reinicia.
|
||||
- El archivado usa `sessions.delete` y cambia el nombre de la transcripción a `*.deleted.<timestamp>` (misma carpeta).
|
||||
- `cleanup: "delete"` archiva inmediatamente después del anuncio (aun así conserva la transcripción mediante cambio de nombre).
|
||||
- El archivado automático es de mejor esfuerzo; los temporizadores pendientes se pierden si el gateway se reinicia.
|
||||
- `runTimeoutSeconds` **no** archiva automáticamente; solo detiene la ejecución. La sesión permanece hasta el archivado automático.
|
||||
- El archivado automático se aplica por igual a sesiones de profundidad 1 y profundidad 2.
|
||||
- La limpieza del navegador está separada de la limpieza de archivado: las pestañas/procesos del navegador rastreados se cierran con mejor esfuerzo cuando termina la ejecución, incluso si se conserva la transcripción/el registro de sesión.
|
||||
- El archivado automático se aplica por igual a las sesiones de profundidad 1 y profundidad 2.
|
||||
- La limpieza del navegador es independiente de la limpieza de archivado: las pestañas/procesos de navegador rastreados se cierran en modo de mejor esfuerzo cuando termina la ejecución, aunque se conserve el registro de transcripción/sesión.
|
||||
|
||||
## Subagentes anidados
|
||||
|
||||
De forma predeterminada, los subagentes no pueden generar sus propios subagentes
|
||||
De forma predeterminada, los subagentes no pueden crear sus propios subagentes
|
||||
(`maxSpawnDepth: 1`). Define `maxSpawnDepth: 2` para habilitar un nivel de
|
||||
anidación — el **patrón de orquestador**: principal → subagente orquestador →
|
||||
anidamiento: el **patrón de orquestador**: principal → subagente orquestador →
|
||||
subsubagentes trabajadores.
|
||||
|
||||
```json5
|
||||
@ -311,13 +312,13 @@ subsubagentes trabajadores.
|
||||
|
||||
### Niveles de profundidad
|
||||
|
||||
| Profundidad | Forma de clave de sesión | Rol | ¿Puede generar? |
|
||||
| Profundidad | Forma de clave de sesión | Rol | ¿Puede crear? |
|
||||
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
|
||||
| 0 | `agent:<id>:main` | Agente principal | Siempre |
|
||||
| 0 | `agent:<id>:main` | Agente principal | Siempre |
|
||||
| 1 | `agent:<id>:subagent:<uuid>` | Subagente (orquestador cuando se permite profundidad 2) | Solo si `maxSpawnDepth >= 2` |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Subsubagente (trabajador hoja) | Nunca |
|
||||
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Subsubagente (trabajador hoja) | Nunca |
|
||||
|
||||
### Cadena de anuncios
|
||||
### Cadena de anuncio
|
||||
|
||||
Los resultados fluyen de vuelta hacia arriba por la cadena:
|
||||
|
||||
@ -328,31 +329,31 @@ Los resultados fluyen de vuelta hacia arriba por la cadena:
|
||||
Cada nivel solo ve anuncios de sus hijos directos.
|
||||
|
||||
<Note>
|
||||
**Guía operativa:** inicia el trabajo hijo una vez y espera eventos de
|
||||
finalización en lugar de construir bucles de sondeo alrededor de `sessions_list`,
|
||||
`sessions_history`, `/subagents list` o comandos `exec` con espera.
|
||||
`sessions_list` y `/subagents list` mantienen las relaciones de sesiones hijas
|
||||
enfocadas en el trabajo en vivo: los hijos activos permanecen adjuntos, los hijos finalizados siguen
|
||||
visibles durante una ventana reciente corta y los enlaces de hijos obsoletos solo en el almacén se
|
||||
ignoran después de su ventana de frescura. Esto evita que metadatos antiguos de `spawnedBy` /
|
||||
`parentSessionKey` resuciten hijos fantasma después de un
|
||||
reinicio. Si llega un evento de finalización de un hijo después de que ya enviaste la
|
||||
**Guía operativa:** inicia el trabajo hijo una vez y espera los eventos de finalización
|
||||
en lugar de crear bucles de sondeo alrededor de `sessions_list`,
|
||||
`sessions_history`, `/subagents list` o comandos `exec` de pausa.
|
||||
`sessions_list` y `/subagents list` mantienen las relaciones de sesión hija
|
||||
enfocadas en trabajo activo: los hijos activos permanecen adjuntos, los hijos terminados siguen
|
||||
visibles durante una ventana reciente breve, y los enlaces de hijo obsoletos solo del almacén se
|
||||
ignoran después de su ventana de frescura. Esto evita que los metadatos antiguos `spawnedBy` /
|
||||
`parentSessionKey` resuciten hijos fantasma después de
|
||||
reiniciar. Si llega un evento de finalización de hijo después de que ya enviaste la
|
||||
respuesta final, el seguimiento correcto es el token silencioso exacto
|
||||
`NO_REPLY` / `no_reply`.
|
||||
</Note>
|
||||
|
||||
### Política de herramientas por profundidad
|
||||
|
||||
- El rol y el alcance de control se escriben en los metadatos de sesión en el momento de la generación. Eso evita que claves de sesión planas o restauradas recuperen accidentalmente privilegios de orquestador.
|
||||
- **Profundidad 1 (orquestador, cuando `maxSpawnDepth >= 2`):** recibe `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` para poder gestionar sus hijos. Otras herramientas de sesión/sistema permanecen denegadas.
|
||||
- El rol y el alcance de control se escriben en los metadatos de sesión en el momento de creación. Eso evita que claves de sesión planas o restauradas recuperen accidentalmente privilegios de orquestador.
|
||||
- **Profundidad 1 (orquestador, cuando `maxSpawnDepth >= 2`):** obtiene `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` para poder administrar sus hijos. Otras herramientas de sesión/sistema permanecen denegadas.
|
||||
- **Profundidad 1 (hoja, cuando `maxSpawnDepth == 1`):** sin herramientas de sesión (comportamiento predeterminado actual).
|
||||
- **Profundidad 2 (trabajador hoja):** sin herramientas de sesión — `sessions_spawn` siempre se deniega en profundidad 2. No puede generar más hijos.
|
||||
- **Profundidad 2 (trabajador hoja):** sin herramientas de sesión; `sessions_spawn` siempre se deniega en profundidad 2. No puede crear más hijos.
|
||||
|
||||
### Límite de generación por agente
|
||||
### Límite de creación por agente
|
||||
|
||||
Cada sesión de agente (a cualquier profundidad) puede tener como máximo `maxChildrenPerAgent`
|
||||
(valor predeterminado `5`) hijos activos a la vez. Esto evita una expansión descontrolada
|
||||
desde un único orquestador.
|
||||
desde un solo orquestador.
|
||||
|
||||
### Detención en cascada
|
||||
|
||||
@ -366,97 +367,92 @@ Detener un orquestador de profundidad 1 detiene automáticamente todos sus hijos
|
||||
|
||||
La autenticación de subagente se resuelve por **id de agente**, no por tipo de sesión:
|
||||
|
||||
- La clave de sesión del subagente es `agent:<agentId>:subagent:<uuid>`.
|
||||
- La clave de sesión de subagente es `agent:<agentId>:subagent:<uuid>`.
|
||||
- El almacén de autenticación se carga desde el `agentDir` de ese agente.
|
||||
- Los perfiles de autenticación del agente principal se fusionan como **fallback**; los perfiles del agente anulan los perfiles principales en caso de conflicto.
|
||||
- Los perfiles de autenticación del agente principal se combinan como **fallback**; los perfiles de agente sobrescriben los perfiles principales en conflictos.
|
||||
|
||||
La fusión es aditiva, por lo que los perfiles principales siempre están disponibles como
|
||||
fallbacks. La autenticación completamente aislada por agente aún no está soportada.
|
||||
La combinación es aditiva, por lo que los perfiles principales siempre están disponibles como
|
||||
fallbacks. Todavía no se admite autenticación completamente aislada por agente.
|
||||
|
||||
## Anuncio
|
||||
|
||||
Los subagentes informan de vuelta mediante un paso de anuncio:
|
||||
|
||||
- El paso de anuncio se ejecuta dentro de la sesión del subagente (no en la sesión solicitante).
|
||||
- El paso de anuncio se ejecuta dentro de la sesión de subagente (no en la sesión solicitante).
|
||||
- Si el subagente responde exactamente `ANNOUNCE_SKIP`, no se publica nada.
|
||||
- Si el texto más reciente del asistente es el token silencioso exacto `NO_REPLY` / `no_reply`, la salida del anuncio se suprime aunque antes hubiera progreso visible.
|
||||
- Si el texto más reciente del asistente es el token silencioso exacto `NO_REPLY` / `no_reply`, la salida de anuncio se suprime aunque haya existido progreso visible anterior.
|
||||
|
||||
La entrega depende de la profundidad del solicitante:
|
||||
|
||||
- Las sesiones solicitantes de nivel superior usan una llamada de seguimiento `agent` con entrega externa (`deliver=true`).
|
||||
- Las sesiones de subagente solicitantes anidadas reciben una inyección interna de seguimiento (`deliver=false`) para que el orquestador pueda sintetizar los resultados de los hijos dentro de la sesión.
|
||||
- Las sesiones de subagente solicitante anidadas reciben una inyección interna de seguimiento (`deliver=false`) para que el orquestador pueda sintetizar los resultados de hijos en la sesión.
|
||||
- Si una sesión de subagente solicitante anidada ya no existe, OpenClaw recurre al solicitante de esa sesión cuando está disponible.
|
||||
|
||||
Para las sesiones solicitantes de nivel superior, la entrega directa en modo de finalización
|
||||
primero resuelve cualquier ruta de conversación/hilo vinculada y anulación de hook, luego rellena
|
||||
Para las sesiones solicitantes de nivel superior, la entrega directa en modo de finalización primero
|
||||
resuelve cualquier ruta de conversación/hilo vinculada y sobrescritura de hook, luego rellena
|
||||
los campos de destino de canal faltantes desde la ruta almacenada de la sesión solicitante.
|
||||
Eso mantiene las finalizaciones en el chat/tema correcto incluso cuando el origen de la finalización
|
||||
Eso mantiene las finalizaciones en el chat/tema correcto incluso cuando el origen de finalización
|
||||
solo identifica el canal.
|
||||
|
||||
La agregación de finalizaciones de hijos se limita a la ejecución solicitante actual al
|
||||
construir hallazgos de finalización anidados, lo que evita que salidas de hijos de ejecuciones
|
||||
anteriores obsoletas se filtren en el anuncio actual. Las respuestas de anuncio preservan
|
||||
La agregación de finalización de hijos se acota a la ejecución solicitante actual al
|
||||
construir hallazgos de finalización anidados, lo que evita que salidas de hijos
|
||||
de ejecuciones anteriores obsoletas se filtren en el anuncio actual. Las respuestas de anuncio conservan
|
||||
el enrutamiento de hilo/tema cuando está disponible en adaptadores de canal.
|
||||
|
||||
### Contexto de anuncio
|
||||
|
||||
El contexto de anuncio se normaliza a un bloque de evento interno estable:
|
||||
|
||||
| Campo | Fuente |
|
||||
| Campo | Origen |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Origen | `subagent` o `cron` |
|
||||
| Ids de sesión | Clave/id de sesión hija |
|
||||
| Tipo | Tipo de anuncio + etiqueta de tarea |
|
||||
| Estado | Derivado del resultado del runtime (`success`, `error`, `timeout` o `unknown`) — **no** inferido del texto del modelo |
|
||||
| Contenido del resultado | Texto visible más reciente del asistente; si no existe, texto de herramienta/toolResult más reciente sanitizado |
|
||||
| Seguimiento | Instrucción que describe cuándo responder frente a permanecer en silencio |
|
||||
| Ids de sesión | Clave/id de sesión hija |
|
||||
| Tipo | Tipo de anuncio + etiqueta de tarea |
|
||||
| Estado | Derivado del resultado de runtime (`success`, `error`, `timeout` o `unknown`), **no** inferido del texto del modelo |
|
||||
| Contenido de resultado | Texto visible más reciente del asistente; de lo contrario, texto de herramienta/toolResult más reciente saneado |
|
||||
| Seguimiento | Instrucción que describe cuándo responder frente a permanecer en silencio |
|
||||
|
||||
Las ejecuciones fallidas terminales informan el estado de fallo sin reproducir el
|
||||
texto de respuesta capturado. En caso de timeout, si el hijo solo llegó a llamadas de herramientas, el anuncio
|
||||
Las ejecuciones terminales fallidas informan estado de fallo sin reproducir
|
||||
el texto de respuesta capturado. Al agotarse el tiempo de espera, si el hijo solo llegó a ejecutar llamadas a herramientas, el anuncio
|
||||
puede condensar ese historial en un breve resumen de progreso parcial en lugar
|
||||
de reproducir la salida bruta de herramientas.
|
||||
de reproducir la salida sin procesar de la herramienta.
|
||||
|
||||
### Línea de estadísticas
|
||||
|
||||
Las cargas útiles de anuncio incluyen una línea de estadísticas al final (incluso cuando están envueltas):
|
||||
|
||||
- Runtime (por ejemplo, `runtime 5m12s`).
|
||||
- Runtime (p. ej., `runtime 5m12s`).
|
||||
- Uso de tokens (entrada/salida/total).
|
||||
- Costo estimado cuando los precios del modelo están configurados (`models.providers.*.models[].cost`).
|
||||
- `sessionKey`, `sessionId` y ruta de transcripción para que el agente principal pueda obtener el historial mediante `sessions_history` o inspeccionar el archivo en disco.
|
||||
|
||||
Los metadatos internos están destinados solo a la orquestación; las respuestas
|
||||
dirigidas al usuario deben reescribirse con la voz normal del asistente.
|
||||
Los metadatos internos están pensados solo para orquestación; las respuestas orientadas al usuario
|
||||
deben reescribirse con la voz normal del asistente.
|
||||
|
||||
### Por qué preferir `sessions_history`
|
||||
|
||||
`sessions_history` es la ruta de orquestación más segura:
|
||||
|
||||
- El recuerdo del asistente se normaliza primero: se eliminan las etiquetas de pensamiento; se elimina el andamiaje `<relevant-memories>` / `<relevant_memories>`; se eliminan los bloques de carga útil XML de llamadas a herramientas en texto plano (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`), incluidas cargas útiles truncadas que nunca cierran limpiamente; se elimina el andamiaje degradado de llamadas/resultados de herramientas y los marcadores de contexto histórico; se eliminan tokens de control filtrados del modelo (`<|assistant|>`, otros ASCII `<|...|>`, ancho completo `<｜...｜>`); se elimina XML de llamada a herramienta MiniMax malformado.
|
||||
- El texto con apariencia de credencial/token se redacta.
|
||||
- El recuerdo del asistente se normaliza primero: se eliminan las etiquetas de pensamiento; se elimina el andamiaje `<relevant-memories>` / `<relevant_memories>`; se eliminan los bloques de carga útil XML de llamadas a herramientas en texto plano (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`), incluidas cargas truncadas que nunca cierran correctamente; se eliminan el andamiaje degradado de llamada/resultado de herramienta y los marcadores de contexto histórico; se eliminan tokens de control de modelo filtrados (`<|assistant|>`, otros ASCII `<|...|>`, ancho completo `<｜...｜>`); se elimina XML de llamada a herramienta MiniMax mal formado.
|
||||
- El texto similar a credenciales/tokens se redacta.
|
||||
- Los bloques largos pueden truncarse.
|
||||
- Los historiales muy grandes pueden descartar filas antiguas o reemplazar una fila sobredimensionada con `[sessions_history omitted: message too large]`.
|
||||
- La inspección de la transcripción bruta en disco es el fallback cuando necesitas la transcripción completa byte por byte.
|
||||
- Los historiales muy grandes pueden descartar filas antiguas o reemplazar una fila sobredimensionada por `[sessions_history omitted: message too large]`.
|
||||
- La inspección de la transcripción sin procesar en disco es el fallback cuando necesitas la transcripción completa byte por byte.
|
||||
|
||||
## Política de herramientas
|
||||
|
||||
Los subagentes usan primero el mismo perfil y canalización de política de herramientas que el agente padre o
|
||||
de destino. Después de eso, OpenClaw aplica la capa de restricción de subagente.
|
||||
Los subagentes usan primero el mismo perfil y la misma canalización de políticas de herramientas que el agente padre o de destino. Después, OpenClaw aplica la capa de restricciones para subagentes.
|
||||
|
||||
Sin un `tools.profile` restrictivo, los subagentes reciben **todas las herramientas excepto
|
||||
herramientas de sesión** y herramientas del sistema:
|
||||
Sin un `tools.profile` restrictivo, los subagentes reciben **todas las herramientas excepto las herramientas de sesión** y las herramientas del sistema:
|
||||
|
||||
- `sessions_list`
|
||||
- `sessions_history`
|
||||
- `sessions_send`
|
||||
- `sessions_spawn`
|
||||
|
||||
`sessions_history` también sigue siendo aquí una vista de recuerdo acotada y sanitizada;
|
||||
no es un volcado bruto de la transcripción.
|
||||
`sessions_history` también sigue siendo aquí una vista de recuperación delimitada y saneada; no es un volcado sin procesar de la transcripción.
|
||||
|
||||
Cuando `maxSpawnDepth >= 2`, los subagentes orquestadores de profundidad 1 reciben además
|
||||
`sessions_spawn`, `subagents`, `sessions_list` y
|
||||
`sessions_history` para poder gestionar sus hijos.
|
||||
Cuando `maxSpawnDepth >= 2`, los subagentes orquestadores de profundidad 1 reciben además `sessions_spawn`, `subagents`, `sessions_list` y `sessions_history` para que puedan gestionar sus hijos.
|
||||
|
||||
### Anulación mediante configuración
|
||||
|
||||
@ -482,12 +478,7 @@ Cuando `maxSpawnDepth >= 2`, los subagentes orquestadores de profundidad 1 recib
|
||||
}
|
||||
```
|
||||
|
||||
`tools.subagents.tools.allow` es un filtro final solo de permitidos. Puede reducir
|
||||
el conjunto de herramientas ya resuelto, pero no puede **volver a añadir** una herramienta eliminada
|
||||
por `tools.profile`. Por ejemplo, `tools.profile: "coding"` incluye
|
||||
`web_search`/`web_fetch`, pero no la herramienta `browser`. Para permitir que
|
||||
los subagentes con perfil de codificación usen automatización de navegador, añade browser en la
|
||||
etapa de perfil:
|
||||
`tools.subagents.tools.allow` es un filtro final solo de permitidos. Puede reducir el conjunto de herramientas ya resuelto, pero no puede **volver a añadir** una herramienta eliminada por `tools.profile`. Por ejemplo, `tools.profile: "coding"` incluye `web_search`/`web_fetch`, pero no la herramienta `browser`. Para permitir que los subagentes con perfil de codificación usen automatización de navegador, añade browser en la etapa del perfil:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -498,8 +489,7 @@ etapa de perfil:
|
||||
}
|
||||
```
|
||||
|
||||
Usa `agents.list[].tools.alsoAllow: ["browser"]` por agente cuando solo un
|
||||
agente deba obtener automatización de navegador.
|
||||
Usa `agents.list[].tools.alsoAllow: ["browser"]` por agente cuando solo un agente deba recibir automatización de navegador.
|
||||
|
||||
## Concurrencia
|
||||
|
||||
@ -508,47 +498,27 @@ Los subagentes usan un carril de cola dedicado dentro del proceso:
|
||||
- **Nombre del carril:** `subagent`
|
||||
- **Concurrencia:** `agents.defaults.subagents.maxConcurrent` (valor predeterminado `8`)
|
||||
|
||||
## Vivacidad y recuperación
|
||||
## Vitalidad y recuperación
|
||||
|
||||
OpenClaw no trata la ausencia de `endedAt` como prueba permanente de que un
|
||||
subagente sigue activo. Las ejecuciones sin finalizar que son anteriores a la ventana de ejecución obsoleta
|
||||
dejan de contar como activas/pendientes en `/subagents list`, los resúmenes de estado,
|
||||
las compuertas de finalización de descendientes y las comprobaciones de concurrencia por sesión.
|
||||
OpenClaw no trata la ausencia de `endedAt` como prueba permanente de que un subagente sigue activo. Las ejecuciones sin finalizar que sean anteriores a la ventana de ejecución obsoleta dejan de contar como activas/pendientes en `/subagents list`, resúmenes de estado, control de finalización de descendientes y comprobaciones de concurrencia por sesión.
|
||||
|
||||
Después de reiniciar el Gateway, las ejecuciones restauradas obsoletas sin finalizar se podan a menos que
|
||||
su sesión hija esté marcada como `abortedLastRun: true`. Esas
|
||||
sesiones hijas abortadas por reinicio siguen siendo recuperables mediante el flujo de recuperación
|
||||
de huérfanos de subagentes, que envía un mensaje de reanudación sintético antes de
|
||||
limpiar el marcador de abortado.
|
||||
Después de reiniciar el Gateway, las ejecuciones restauradas obsoletas sin finalizar se podan salvo que su sesión hija esté marcada como `abortedLastRun: true`. Esas sesiones hijas abortadas por reinicio siguen siendo recuperables mediante el flujo de recuperación de subagentes huérfanos, que envía un mensaje sintético de reanudación antes de limpiar el marcador de abortado.
|
||||
|
||||
La recuperación automática tras reinicio está limitada por sesión hija. Si el mismo
|
||||
hijo de subagente se acepta para recuperación de huérfanos repetidamente dentro de la
|
||||
ventana de rebloqueo rápido, OpenClaw conserva una lápida de recuperación en esa
|
||||
sesión y deja de reanudarla automáticamente en reinicios posteriores. Ejecuta
|
||||
`openclaw tasks maintenance --apply` para reconciliar el registro de tarea, o
|
||||
`openclaw doctor --fix` para limpiar indicadores obsoletos de recuperación abortada en
|
||||
sesiones con lápida.
|
||||
La recuperación automática tras reinicio está limitada por sesión hija. Si el mismo subagente hijo se acepta para recuperación de huérfanos repetidamente dentro de la ventana rápida de reacuñamiento, OpenClaw conserva una lápida de recuperación en esa sesión y deja de reanudarla automáticamente en reinicios posteriores. Ejecuta `openclaw tasks maintenance --apply` para conciliar el registro de la tarea, o `openclaw doctor --fix` para limpiar indicadores obsoletos de recuperación abortada en sesiones con lápida.
|
||||
|
||||
<Note>
|
||||
Si la generación de un subagente falla con Gateway `PAIRING_REQUIRED` /
|
||||
`scope-upgrade`, revisa el llamador RPC antes de editar el estado de emparejamiento.
|
||||
La coordinación interna de `sessions_spawn` debe conectarse como
|
||||
`client.id: "gateway-client"` con `client.mode: "backend"` mediante autenticación directa
|
||||
de local loopback con token compartido/contraseña; esa ruta no depende de la
|
||||
línea base de alcance de dispositivo emparejado de la CLI. Los llamadores remotos, `deviceIdentity`
|
||||
explícito, rutas explícitas de token de dispositivo y clientes de navegador/Node
|
||||
siguen necesitando aprobación normal de dispositivo para las ampliaciones de alcance.
|
||||
Si una generación de subagente falla con Gateway `PAIRING_REQUIRED` / `scope-upgrade`, revisa el llamador RPC antes de editar el estado de emparejamiento. La coordinación interna de `sessions_spawn` debe conectarse como `client.id: "gateway-client"` con `client.mode: "backend"` mediante autenticación directa de token compartido/contraseña por local loopback; esa ruta no depende de la línea base de alcance de dispositivo emparejado de la CLI. Los llamadores remotos, `deviceIdentity` explícito, rutas explícitas con token de dispositivo y clientes de navegador/Node siguen necesitando la aprobación normal del dispositivo para ampliaciones de alcance.
|
||||
</Note>
|
||||
|
||||
## Detención
|
||||
|
||||
- Enviar `/stop` en el chat solicitante aborta la sesión solicitante y detiene cualquier ejecución activa de subagente generada desde ella, en cascada hasta los hijos anidados.
|
||||
- `/subagents kill <id>` detiene un subagente específico y se propaga en cascada a sus hijos.
|
||||
- Enviar `/stop` en el chat solicitante aborta la sesión solicitante y detiene cualquier ejecución activa de subagente generada desde ella, propagándose a hijos anidados.
|
||||
- `/subagents kill <id>` detiene un subagente específico y se propaga a sus hijos.
|
||||
|
||||
## Limitaciones
|
||||
|
||||
- El anuncio de subagente es de **mejor esfuerzo**. Si el Gateway se reinicia, el trabajo pendiente de "announce back" se pierde.
|
||||
- Los subagentes siguen compartiendo los mismos recursos del proceso de Gateway; trata `maxConcurrent` como una válvula de seguridad.
|
||||
- El anuncio de subagentes es **de mejor esfuerzo**. Si el Gateway se reinicia, el trabajo pendiente de "anunciar de vuelta" se pierde.
|
||||
- Los subagentes siguen compartiendo los mismos recursos del proceso del Gateway; trata `maxConcurrent` como una válvula de seguridad.
|
||||
- `sessions_spawn` siempre es no bloqueante: devuelve `{ status: "accepted", runId, childSessionKey }` inmediatamente.
|
||||
- El contexto de subagente solo inyecta `AGENTS.md` + `TOOLS.md` (sin `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ni `BOOTSTRAP.md`).
|
||||
- La profundidad máxima de anidamiento es 5 (rango de `maxSpawnDepth`: 1-5). Se recomienda la profundidad 2 para la mayoría de los casos de uso.
|
||||
|
||||
@ -1,152 +1,152 @@
|
||||
---
|
||||
read_when:
|
||||
- Quieres operar el Gateway desde un navegador
|
||||
- Quiere acceder a Tailnet sin túneles SSH
|
||||
- Quiere operar el Gateway desde un navegador
|
||||
- Quieres acceso a Tailnet sin túneles SSH
|
||||
sidebarTitle: Control UI
|
||||
summary: Interfaz de control basada en navegador para el Gateway (chat, nodos, configuración)
|
||||
summary: Interfaz de control basada en el navegador para el Gateway (chat, nodos, configuración)
|
||||
title: Interfaz de control
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T05:29:25Z"
|
||||
generated_at: "2026-05-04T07:04:29Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 99a40ab77276fbc3180aefb103c2dd46804829c7b1b6966a8456ed35b85ed644
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
La interfaz de control es una pequeña aplicación de una sola página **Vite + Lit** servida por el Gateway:
|
||||
La interfaz de control es una pequeña aplicación de una sola página de **Vite + Lit** servida por el Gateway:
|
||||
|
||||
- predeterminado: `http://<host>:18789/`
|
||||
- prefijo opcional: define `gateway.controlUi.basePath` (p. ej., `/openclaw`)
|
||||
- prefijo opcional: establece `gateway.controlUi.basePath` (p. ej., `/openclaw`)
|
||||
|
||||
Se comunica **directamente con el WebSocket del Gateway** en el mismo puerto.
|
||||
|
||||
## Apertura rápida (local)
|
||||
|
||||
Si el Gateway se está ejecutando en el mismo equipo, abre:
|
||||
Si el Gateway se ejecuta en el mismo equipo, abre:
|
||||
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (o [http://localhost:18789/](http://localhost:18789/))
|
||||
|
||||
Si la página no se carga, inicia primero el Gateway: `openclaw gateway`.
|
||||
|
||||
La autenticación se proporciona durante el protocolo de enlace de WebSocket mediante:
|
||||
La autenticación se suministra durante el protocolo de enlace de WebSocket mediante:
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- encabezados de identidad de Tailscale Serve cuando `gateway.auth.allowTailscale: true`
|
||||
- encabezados de identidad de proxy de confianza cuando `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
El panel de configuración del tablero conserva un token para la sesión actual de la pestaña del navegador y la URL del Gateway seleccionada; las contraseñas no se persisten. La incorporación normalmente genera un token del Gateway para autenticación por secreto compartido en la primera conexión, pero la autenticación con contraseña también funciona cuando `gateway.auth.mode` es `"password"`.
|
||||
El panel de ajustes del panel de control conserva un token para la sesión actual de la pestaña del navegador y la URL de gateway seleccionada; las contraseñas no se persisten. La incorporación normalmente genera un token de gateway para autenticación con secreto compartido en la primera conexión, pero la autenticación con contraseña también funciona cuando `gateway.auth.mode` es `"password"`.
|
||||
|
||||
## Emparejamiento de dispositivos (primera conexión)
|
||||
|
||||
Cuando te conectas a la interfaz de control desde un navegador o dispositivo nuevo, el Gateway normalmente requiere una **aprobación de emparejamiento de un solo uso**. Esta es una medida de seguridad para evitar el acceso no autorizado.
|
||||
Cuando te conectas a la interfaz de control desde un navegador o dispositivo nuevo, el Gateway normalmente requiere una **aprobación de emparejamiento de un solo uso**. Esta es una medida de seguridad para impedir el acceso no autorizado.
|
||||
|
||||
**Qué verás:** "desconectado (1008): se requiere emparejamiento"
|
||||
**Lo que verás:** "disconnected (1008): pairing required"
|
||||
|
||||
<Steps>
|
||||
<Step title="Listar solicitudes pendientes">
|
||||
<Step title="List pending requests">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Aprobar por ID de solicitud">
|
||||
<Step title="Approve by request ID">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Si el navegador reintenta el emparejamiento con detalles de autenticación modificados (rol/alcances/clave pública), la solicitud pendiente anterior se reemplaza y se crea un nuevo `requestId`. Vuelve a ejecutar `openclaw devices list` antes de aprobar.
|
||||
Si el navegador reintenta el emparejamiento con detalles de autenticación modificados (rol/ámbitos/clave pública), la solicitud pendiente anterior se reemplaza y se crea un nuevo `requestId`. Vuelve a ejecutar `openclaw devices list` antes de aprobar.
|
||||
|
||||
Si el navegador ya está emparejado y lo cambias de acceso de lectura a acceso de escritura/administración, esto se trata como una actualización de aprobación, no como una reconexión silenciosa. OpenClaw mantiene activa la aprobación anterior, bloquea la reconexión más amplia y te pide que apruebes explícitamente el nuevo conjunto de alcances.
|
||||
Si el navegador ya está emparejado y lo cambias de acceso de lectura a acceso de escritura/administrador, esto se trata como una mejora de aprobación, no como una reconexión silenciosa. OpenClaw mantiene activa la aprobación anterior, bloquea la reconexión más amplia y te pide que apruebes explícitamente el nuevo conjunto de ámbitos.
|
||||
|
||||
Una vez aprobado, el dispositivo se recuerda y no requerirá nueva aprobación a menos que lo revoques con `openclaw devices revoke --device <id> --role <role>`. Consulta [CLI de dispositivos](/es/cli/devices) para la rotación y revocación de tokens.
|
||||
Una vez aprobado, el dispositivo se recuerda y no requerirá una nueva aprobación a menos que lo revoques con `openclaw devices revoke --device <id> --role <role>`. Consulta [CLI de dispositivos](/es/cli/devices) para la rotación y revocación de tokens.
|
||||
|
||||
<Note>
|
||||
- Las conexiones directas del navegador mediante local loopback (`127.0.0.1` / `localhost`) se aprueban automáticamente.
|
||||
- Tailscale Serve puede omitir la ida y vuelta de emparejamiento para sesiones de operador de la interfaz de control cuando `gateway.auth.allowTailscale: true`, la identidad de Tailscale se verifica y el navegador presenta su identidad de dispositivo.
|
||||
- Los enlaces directos de Tailnet, las conexiones de navegador por LAN y los perfiles de navegador sin identidad de dispositivo siguen requiriendo aprobación explícita.
|
||||
- Las conexiones directas del navegador por local loopback (`127.0.0.1` / `localhost`) se aprueban automáticamente.
|
||||
- Tailscale Serve puede omitir el viaje de ida y vuelta de emparejamiento para sesiones de operador de la interfaz de control cuando `gateway.auth.allowTailscale: true`, la identidad de Tailscale se verifica y el navegador presenta su identidad de dispositivo.
|
||||
- Los enlaces directos de Tailnet, las conexiones de navegador por LAN y los perfiles de navegador sin identidad de dispositivo aún requieren aprobación explícita.
|
||||
- Cada perfil de navegador genera un ID de dispositivo único, por lo que cambiar de navegador o borrar los datos del navegador requerirá volver a emparejar.
|
||||
|
||||
</Note>
|
||||
|
||||
## Identidad personal (local del navegador)
|
||||
|
||||
La interfaz de control admite una identidad personal por navegador (nombre visible y avatar) adjunta a los mensajes salientes para la atribución en sesiones compartidas. Vive en el almacenamiento del navegador, está limitada al perfil de navegador actual y no se sincroniza con otros dispositivos ni se persiste en el servidor más allá de los metadatos normales de autoría de la transcripción en los mensajes que realmente envías. Borrar los datos del sitio o cambiar de navegador la restablece a vacío.
|
||||
La interfaz de control admite una identidad personal por navegador (nombre para mostrar y avatar) adjunta a los mensajes salientes para atribución en sesiones compartidas. Vive en el almacenamiento del navegador, está limitada al perfil de navegador actual y no se sincroniza con otros dispositivos ni se persiste en el servidor más allá de los metadatos normales de autoría de transcripción en los mensajes que realmente envías. Borrar los datos del sitio o cambiar de navegador la restablece a vacío.
|
||||
|
||||
El mismo patrón local del navegador se aplica a la sustitución del avatar del asistente. Los avatares del asistente cargados se superponen a la identidad resuelta por el Gateway solo en el navegador local y nunca hacen un viaje de ida y vuelta mediante `config.patch`. El campo de configuración compartida `ui.assistant.avatar` sigue estando disponible para clientes que no son de la interfaz de usuario que escriben el campo directamente (como gateways con scripts o tableros personalizados).
|
||||
El mismo patrón local del navegador se aplica a la anulación del avatar del asistente. Los avatares de asistente cargados superponen la identidad resuelta por el gateway solo en el navegador local y nunca hacen un viaje de ida y vuelta mediante `config.patch`. El campo de configuración compartido `ui.assistant.avatar` sigue estando disponible para clientes que no son de UI y escriben el campo directamente (como gateways con scripts o paneles de control personalizados).
|
||||
|
||||
## Endpoint de configuración en tiempo de ejecución
|
||||
|
||||
La interfaz de control obtiene su configuración en tiempo de ejecución desde `/__openclaw/control-ui-config.json`. Ese endpoint está protegido por la misma autenticación del Gateway que el resto de la superficie HTTP: los navegadores no autenticados no pueden obtenerlo, y una obtención correcta requiere un token/contraseña del Gateway ya válido, identidad de Tailscale Serve o una identidad de proxy de confianza.
|
||||
La interfaz de control obtiene sus ajustes en tiempo de ejecución desde `/__openclaw/control-ui-config.json`. Ese endpoint está protegido por la misma autenticación de gateway que el resto de la superficie HTTP: los navegadores no autenticados no pueden obtenerlo, y una obtención correcta requiere un token/contraseña de gateway ya válido, identidad de Tailscale Serve o una identidad de proxy de confianza.
|
||||
|
||||
## Compatibilidad de idiomas
|
||||
|
||||
La interfaz de control puede localizarse en la primera carga según la configuración regional de tu navegador. Para sobrescribirla más tarde, abre **Resumen -> Acceso al Gateway -> Idioma**. El selector de configuración regional vive en la tarjeta Acceso al Gateway, no en Apariencia.
|
||||
La interfaz de control puede localizarse en la primera carga según la configuración regional de tu navegador. Para anularla más tarde, abre **Overview -> Gateway Access -> Language**. El selector de configuración regional está en la tarjeta Gateway Access, no en Appearance.
|
||||
|
||||
- Configuraciones regionales admitidas: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Las traducciones que no están en inglés se cargan de forma diferida en el navegador.
|
||||
- La configuración regional seleccionada se guarda en el almacenamiento del navegador y se reutiliza en visitas futuras.
|
||||
- Las claves de traducción faltantes vuelven al inglés.
|
||||
- Las traducciones que no son al inglés se cargan de forma diferida en el navegador.
|
||||
- La configuración regional seleccionada se guarda en el almacenamiento del navegador y se reutiliza en futuras visitas.
|
||||
- Las claves de traducción faltantes recurren al inglés.
|
||||
|
||||
Las traducciones de la documentación se generan para el mismo conjunto de configuraciones regionales que no están en inglés, pero el selector de idiomas integrado del sitio de documentación de Mintlify está limitado a los códigos de configuración regional que Mintlify acepta. La documentación en tailandés (`th`) y persa (`fa`) se sigue generando en el repositorio de publicación; puede que no aparezca en ese selector hasta que Mintlify admita esos códigos.
|
||||
Las traducciones de la documentación se generan para el mismo conjunto de configuraciones regionales no inglesas, pero el selector de idioma integrado del sitio de documentación de Mintlify está limitado a los códigos de configuración regional que Mintlify acepta. La documentación en tailandés (`th`) y persa (`fa`) aún se genera en el repositorio de publicación; puede que no aparezca en ese selector hasta que Mintlify admita esos códigos.
|
||||
|
||||
## Temas de apariencia
|
||||
|
||||
El panel Apariencia conserva los temas integrados Claw, Knot y Dash, además de una ranura de importación tweakcn local del navegador. Para importar un tema, abre el [editor tweakcn](https://tweakcn.com/editor/theme), elige o crea un tema, haz clic en **Compartir** y pega el enlace del tema copiado en Apariencia. El importador también acepta URL de registro `https://tweakcn.com/r/themes/<id>`, URL de editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, rutas relativas `/themes/<id>`, ID de tema sin procesar y nombres de tema predeterminados como `amethyst-haze`.
|
||||
El panel Appearance conserva los temas integrados Claw, Knot y Dash, además de una ranura de importación tweakcn local del navegador. Para importar un tema, abre [editor tweakcn](https://tweakcn.com/editor/theme), elige o crea un tema, haz clic en **Share** y pega el enlace del tema copiado en Appearance. El importador también acepta URL de registro `https://tweakcn.com/r/themes/<id>`, URL de editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, rutas relativas `/themes/<id>`, ID de tema sin procesar y nombres de tema predeterminados como `amethyst-haze`.
|
||||
|
||||
Los temas importados se almacenan solo en el perfil de navegador actual. No se escriben en la configuración del Gateway y no se sincronizan entre dispositivos. Reemplazar el tema importado actualiza la única ranura local; borrarlo cambia el tema activo de vuelta a Claw si el tema importado estaba seleccionado.
|
||||
Los temas importados se almacenan solo en el perfil de navegador actual. No se escriben en la configuración del gateway y no se sincronizan entre dispositivos. Reemplazar el tema importado actualiza la única ranura local; borrarlo cambia el tema activo de vuelta a Claw si el tema importado estaba seleccionado.
|
||||
|
||||
## Qué puede hacer (hoy)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Chat y voz">
|
||||
<Accordion title="Chat and Talk">
|
||||
- Chatea con el modelo mediante Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Habla mediante sesiones en tiempo real del navegador. OpenAI usa WebRTC directo, Google Live usa un token de navegador restringido de un solo uso mediante WebSocket, y los plugins de voz en tiempo real solo de backend usan el transporte de retransmisión del Gateway. La retransmisión mantiene las credenciales del proveedor en el Gateway mientras el navegador transmite PCM del micrófono mediante RPC `talk.realtime.relay*` y envía llamadas a la herramienta `openclaw_agent_consult` de vuelta mediante `chat.send` para el modelo OpenClaw configurado más grande.
|
||||
- Transmite llamadas a herramientas y tarjetas de salida de herramientas en vivo en el chat (eventos del agente).
|
||||
- Habla mediante sesiones en tiempo real del navegador. OpenAI usa WebRTC directo, Google Live usa un token de navegador de un solo uso restringido sobre WebSocket, y los plugins de voz en tiempo real solo de backend usan el transporte de retransmisión del Gateway. La retransmisión conserva las credenciales del proveedor en el Gateway mientras el navegador transmite PCM del micrófono mediante RPC `talk.realtime.relay*` y envía llamadas de herramienta `openclaw_agent_consult` de vuelta mediante `chat.send` para el modelo de OpenClaw configurado más grande.
|
||||
- Transmite llamadas de herramientas + tarjetas de salida de herramientas en vivo en Chat (eventos de agente).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Canales, instancias, sesiones, sueños">
|
||||
- Canales: estado de canales integrados y de plugins incluidos/externos, inicio de sesión QR y configuración por canal (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Instancias: lista de presencia y actualización (`system-presence`).
|
||||
- Sesiones: lista y sustituciones por sesión de modelo/pensamiento/rápido/detallado/traza/razonamiento (`sessions.list`, `sessions.patch`).
|
||||
- Sueños: estado de Dreaming, alternancia para activar/desactivar y lector de diario de sueños (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
<Accordion title="Channels, instances, sessions, dreams">
|
||||
- Canales: estado de canales integrados más canales de plugins incluidos/externos, inicio de sesión con QR y configuración por canal (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Instancias: lista de presencia + actualización (`system-presence`).
|
||||
- Sesiones: lista + anulaciones por sesión de modelo/pensamiento/rápido/detallado/traza/razonamiento (`sessions.list`, `sessions.patch`).
|
||||
- Sueños: estado de Dreaming, alternancia de activar/desactivar y lector de diario de sueños (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, Skills, nodos, aprobaciones de exec">
|
||||
- Trabajos de Cron: listar/agregar/editar/ejecutar/activar/desactivar e historial de ejecución (`cron.*`).
|
||||
- Skills: estado, activar/desactivar, instalar, actualizaciones de clave de API (`skills.*`).
|
||||
- Nodos: lista y capacidades (`node.list`).
|
||||
- Aprobaciones de exec: editar listas de permitidos del Gateway o nodo y política de solicitud para `exec host=gateway/node` (`exec.approvals.*`).
|
||||
<Accordion title="Cron, skills, nodes, exec approvals">
|
||||
- Trabajos de Cron: listar/agregar/editar/ejecutar/activar/desactivar + historial de ejecuciones (`cron.*`).
|
||||
- Skills: estado, activar/desactivar, instalar, actualizaciones de claves de API (`skills.*`).
|
||||
- Nodos: lista + capacidades (`node.list`).
|
||||
- Aprobaciones de exec: editar listas de permitidos de gateway o nodo + política de solicitud para `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Configuración">
|
||||
<Accordion title="Config">
|
||||
- Ver/editar `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Aplicar y reiniciar con validación (`config.apply`) y activar la última sesión activa.
|
||||
- Las escrituras incluyen una protección de hash base para evitar sobrescribir ediciones concurrentes.
|
||||
- Las escrituras (`config.set`/`config.apply`/`config.patch`) realizan una comprobación previa de resolución de SecretRef activos para las referencias en la carga de configuración enviada; las referencias enviadas activas no resueltas se rechazan antes de escribir.
|
||||
- Esquema y renderizado de formulario (`config.schema` / `config.schema.lookup`, incluidos `title` / `description` del campo, pistas de interfaz coincidentes, resúmenes de hijos inmediatos, metadatos de documentación en nodos de objeto anidado/comodín/matriz/composición, además de esquemas de plugin y canal cuando están disponibles); el editor JSON sin procesar está disponible solo cuando la instantánea tiene una ida y vuelta sin procesar segura.
|
||||
- Si una instantánea no puede hacer una ida y vuelta segura del texto sin procesar, la interfaz de control fuerza el modo Formulario y desactiva el modo Sin procesar para esa instantánea.
|
||||
- "Restablecer a guardado" del editor JSON sin procesar conserva la forma creada en bruto (formato, comentarios, diseño de `$include`) en lugar de volver a renderizar una instantánea aplanada, por lo que las ediciones externas sobreviven a un restablecimiento cuando la instantánea puede hacer una ida y vuelta segura.
|
||||
- Los valores de objeto SecretRef estructurados se renderizan como de solo lectura en entradas de texto de formulario para evitar la corrupción accidental de objeto a cadena.
|
||||
- Aplicar + reiniciar con validación (`config.apply`) y despertar la última sesión activa.
|
||||
- Las escrituras incluyen una protección de hash base para impedir sobrescribir ediciones concurrentes.
|
||||
- Las escrituras (`config.set`/`config.apply`/`config.patch`) comprueban previamente la resolución de SecretRef activos para las referencias en la carga útil de configuración enviada; las referencias enviadas activas sin resolver se rechazan antes de escribir.
|
||||
- Esquema + renderizado de formulario (`config.schema` / `config.schema.lookup`, incluidos `title` / `description` de campo, sugerencias de UI coincidentes, resúmenes de hijos inmediatos, metadatos de documentación en nodos anidados de objeto/comodín/array/composición, además de esquemas de plugin + canal cuando estén disponibles); el editor JSON sin procesar está disponible solo cuando la instantánea tiene un viaje de ida y vuelta sin procesar seguro.
|
||||
- Si una instantánea no puede hacer de forma segura un viaje de ida y vuelta de texto sin procesar, la interfaz de control fuerza el modo Formulario y desactiva el modo Sin procesar para esa instantánea.
|
||||
- El editor JSON sin procesar "Reset to saved" conserva la forma creada sin procesar (formato, comentarios, diseño de `$include`) en lugar de volver a renderizar una instantánea aplanada, por lo que las ediciones externas sobreviven a un restablecimiento cuando la instantánea puede hacer de forma segura el viaje de ida y vuelta.
|
||||
- Los valores de objeto SecretRef estructurados se renderizan como de solo lectura en entradas de texto de formulario para impedir la corrupción accidental de objeto a cadena.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Depuración, registros, actualización">
|
||||
- Depuración: instantáneas de estado/salud/modelos, registro de eventos y llamadas RPC manuales (`status`, `health`, `models.list`).
|
||||
- Registros: seguimiento en vivo de los registros de archivo del Gateway con filtro/exportación (`logs.tail`).
|
||||
- Actualización: ejecutar una actualización de paquete/git y reiniciar (`update.run`) con un informe de reinicio; luego sondear `update.status` después de reconectar para verificar la versión del Gateway en ejecución.
|
||||
<Accordion title="Debug, logs, update">
|
||||
- Depuración: instantáneas de estado/salud/modelos + registro de eventos + llamadas RPC manuales (`status`, `health`, `models.list`).
|
||||
- Registros: seguimiento en vivo de registros de archivo del gateway con filtro/exportación (`logs.tail`).
|
||||
- Actualización: ejecutar una actualización de paquete/git + reiniciar (`update.run`) con un informe de reinicio; luego sondear `update.status` tras reconectar para verificar la versión del gateway en ejecución.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Notas del panel de trabajos de Cron">
|
||||
- Para trabajos aislados, la entrega predeterminada es anunciar resumen. Puedes cambiar a ninguno si quieres ejecuciones solo internas.
|
||||
<Accordion title="Cron jobs panel notes">
|
||||
- Para trabajos aislados, la entrega predeterminada anuncia un resumen. Puedes cambiarla a ninguna si quieres ejecuciones solo internas.
|
||||
- Los campos de canal/destino aparecen cuando se selecciona anunciar.
|
||||
- El modo Webhook usa `delivery.mode = "webhook"` con `delivery.to` definido en una URL de webhook HTTP(S) válida.
|
||||
- El modo Webhook usa `delivery.mode = "webhook"` con `delivery.to` establecido en una URL de webhook HTTP(S) válida.
|
||||
- Para trabajos de sesión principal, están disponibles los modos de entrega webhook y ninguno.
|
||||
- Los controles de edición avanzados incluyen eliminar después de ejecutar, borrar sustitución de agente, opciones exactas/escalonadas de cron, sustituciones de modelo/pensamiento del agente y alternancias de entrega de mejor esfuerzo.
|
||||
- Los controles de edición avanzados incluyen eliminar tras ejecutar, borrar anulación de agente, opciones exactas/escalonadas de cron, anulaciones de modelo/pensamiento de agente y alternancias de entrega de mejor esfuerzo.
|
||||
- La validación del formulario es en línea con errores a nivel de campo; los valores no válidos desactivan el botón de guardar hasta que se corrijan.
|
||||
- Define `cron.webhookToken` para enviar un token bearer dedicado; si se omite, el webhook se envía sin encabezado de autenticación.
|
||||
- Alternativa obsoleta: los trabajos heredados almacenados con `notify: true` aún pueden usar `cron.webhook` hasta que se migren.
|
||||
- Establece `cron.webhookToken` para enviar un token bearer dedicado; si se omite, el webhook se envía sin encabezado de autenticación.
|
||||
- Fallback obsoleto: los trabajos heredados almacenados con `notify: true` aún pueden usar `cron.webhook` hasta migrarse.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -154,63 +154,63 @@ Los temas importados se almacenan solo en el perfil de navegador actual. No se e
|
||||
## Comportamiento del chat
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Semántica de envío e historial">
|
||||
<Accordion title="Send and history semantics">
|
||||
- `chat.send` es **no bloqueante**: confirma inmediatamente con `{ runId, status: "started" }` y la respuesta se transmite mediante eventos `chat`.
|
||||
- Las cargas del chat aceptan imágenes y archivos que no sean de video. Las imágenes conservan la ruta de imagen nativa; los demás archivos se almacenan como medios administrados y se muestran en el historial como enlaces de adjuntos.
|
||||
- Las cargas del chat aceptan imágenes además de archivos que no sean videos. Las imágenes conservan la ruta de imagen nativa; otros archivos se almacenan como medios administrados y se muestran en el historial como enlaces de adjuntos.
|
||||
- Reenviar con el mismo `idempotencyKey` devuelve `{ status: "in_flight" }` mientras está en ejecución, y `{ status: "ok" }` después de completarse.
|
||||
- Las respuestas de `chat.history` tienen límites de tamaño para proteger la UI. Cuando las entradas de la transcripción son demasiado grandes, Gateway puede truncar campos de texto largos, omitir bloques de metadatos pesados y reemplazar mensajes demasiado grandes por un marcador de posición (`[chat.history omitted: message too large]`).
|
||||
- Las imágenes del asistente/generadas se conservan como referencias de medios administrados y se devuelven mediante URLs de medios autenticadas de Gateway, de modo que las recargas no dependan de que las cargas útiles de imágenes base64 sin procesar permanezcan en la respuesta del historial del chat.
|
||||
- `chat.history` también elimina del texto visible del asistente etiquetas de directivas en línea solo de visualización (por ejemplo `[[reply_to_*]]` y `[[audio_as_voice]]`), cargas XML de llamadas a herramientas en texto plano (incluidas `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` y bloques truncados de llamadas a herramientas), y tokens de control de modelo ASCII/ancho completo filtrados, y omite entradas del asistente cuyo texto visible completo sea solo el token silencioso exacto `NO_REPLY` / `no_reply`.
|
||||
- Durante un envío activo y la actualización final del historial, la vista de chat mantiene visibles los mensajes locales optimistas de usuario/asistente si `chat.history` devuelve brevemente una instantánea anterior; la transcripción canónica reemplaza esos mensajes locales cuando el historial de Gateway se actualiza.
|
||||
- Los eventos `chat` en vivo son estado de entrega, mientras que `chat.history` se reconstruye a partir de la transcripción duradera de la sesión. Después de los eventos finales de herramienta, la Control UI recarga el historial y fusiona solo una pequeña cola optimista; el límite de transcripción está documentado en [WebChat](/es/web/webchat).
|
||||
- `chat.inject` agrega una nota del asistente a la transcripción de la sesión y emite un evento `chat` para actualizaciones solo de UI (sin ejecución de agente ni entrega por canal).
|
||||
- Los selectores de modelo y razonamiento del encabezado del chat aplican parches a la sesión activa inmediatamente mediante `sessions.patch`; son sobrescrituras persistentes de sesión, no opciones de envío de un solo turno.
|
||||
- Escribir `/new` en la Control UI crea y cambia a la misma sesión nueva del panel que New Chat. Escribir `/reset` mantiene el restablecimiento explícito in situ de Gateway para la sesión actual.
|
||||
- El selector de modelo del chat solicita la vista de modelos configurada de Gateway. Si `agents.defaults.models` está presente, esa lista permitida controla el selector. De lo contrario, el selector muestra entradas explícitas de `models.providers.*.models` además de proveedores con autenticación utilizable. El catálogo completo sigue disponible mediante el RPC de depuración `models.list` con `view: "all"`.
|
||||
- Cuando los informes nuevos de uso de sesión de Gateway muestran alta presión de contexto, el área del compositor de chat muestra un aviso de contexto y, en niveles de Compaction recomendados, un botón compacto que ejecuta la ruta normal de Compaction de sesión. Las instantáneas de tokens obsoletas se ocultan hasta que Gateway vuelve a informar uso reciente.
|
||||
- Las respuestas de `chat.history` tienen límite de tamaño por seguridad de la UI. Cuando las entradas de transcripción son demasiado grandes, Gateway puede truncar campos de texto largos, omitir bloques de metadatos pesados y reemplazar mensajes demasiado grandes por un marcador de posición (`[chat.history omitted: message too large]`).
|
||||
- Las imágenes generadas por el asistente se conservan como referencias de medios administrados y se devuelven mediante URLs de medios autenticadas de Gateway, por lo que las recargas no dependen de que las cargas útiles de imágenes base64 sin procesar permanezcan en la respuesta del historial de chat.
|
||||
- `chat.history` también elimina de texto visible del asistente las etiquetas de directivas en línea solo para visualización (por ejemplo `[[reply_to_*]]` y `[[audio_as_voice]]`), cargas útiles XML de llamadas a herramientas en texto sin formato (incluidas `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` y bloques truncados de llamadas a herramientas), y tokens de control de modelo ASCII/de ancho completo filtrados, y omite entradas del asistente cuyo texto visible completo es únicamente el token silencioso exacto `NO_REPLY` / `no_reply`.
|
||||
- Durante un envío activo y la actualización final del historial, la vista de chat mantiene visibles los mensajes locales optimistas de usuario/asistente si `chat.history` devuelve brevemente una instantánea anterior; la transcripción canónica reemplaza esos mensajes locales cuando el historial de Gateway se pone al día.
|
||||
- Los eventos `chat` en vivo son estado de entrega, mientras que `chat.history` se reconstruye desde la transcripción duradera de la sesión. Después de eventos finales de herramientas, la interfaz de control recarga el historial y fusiona solo una pequeña cola optimista; el límite de la transcripción está documentado en [WebChat](/es/web/webchat).
|
||||
- `chat.inject` agrega una nota del asistente a la transcripción de la sesión y emite un evento `chat` para actualizaciones solo de UI (sin ejecución de agente, sin entrega por canal).
|
||||
- El modelo del encabezado de chat y los selectores de razonamiento parchean inmediatamente la sesión activa mediante `sessions.patch`; son anulaciones persistentes de sesión, no opciones de envío de un solo turno.
|
||||
- Escribir `/new` en la interfaz de control crea y cambia a la misma sesión nueva del panel que Nuevo chat. Escribir `/reset` mantiene el reinicio explícito in situ de Gateway para la sesión actual.
|
||||
- El selector de modelo de chat solicita la vista de modelos configurada de Gateway. Si `agents.defaults.models` está presente, esa lista permitida controla el selector. De lo contrario, el selector muestra entradas explícitas de `models.providers.*.models` además de proveedores con autenticación utilizable. El catálogo completo permanece disponible mediante el RPC de depuración `models.list` con `view: "all"`.
|
||||
- Cuando informes recientes de uso de sesión de Gateway muestran una presión alta de contexto, el área del compositor de chat muestra un aviso de contexto y, en niveles de Compaction recomendados, un botón compacto que ejecuta la ruta normal de Compaction de sesión. Las instantáneas obsoletas de tokens se ocultan hasta que Gateway vuelve a informar uso reciente.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Modo de conversación (tiempo real en navegador)">
|
||||
El modo de conversación usa un proveedor de voz en tiempo real registrado. Configura OpenAI con `talk.provider: "openai"` más `talk.providers.openai.apiKey`, o configura Google con `talk.provider: "google"` más `talk.providers.google.apiKey`; la configuración del proveedor en tiempo real de Voice Call aún puede reutilizarse como reserva. El navegador nunca recibe una clave de API estándar del proveedor. OpenAI recibe un secreto de cliente Realtime efímero para WebRTC. Google Live recibe un token de autenticación Live API restringido de un solo uso para una sesión WebSocket del navegador, con instrucciones y declaraciones de herramientas bloqueadas en el token por Gateway. Los proveedores que solo exponen un puente en tiempo real de backend se ejecutan mediante el transporte de retransmisión de Gateway, por lo que las credenciales y sockets del proveedor permanecen del lado del servidor mientras el audio del navegador se mueve mediante RPCs autenticados de Gateway. El prompt de sesión Realtime lo ensambla Gateway; `talk.realtime.session` no acepta sobrescrituras de instrucciones proporcionadas por el llamador.
|
||||
<Accordion title="Talk mode (browser realtime)">
|
||||
El modo de conversación usa un proveedor de voz en tiempo real registrado. Configura OpenAI con `talk.provider: "openai"` más `talk.providers.openai.apiKey`, o configura Google con `talk.provider: "google"` más `talk.providers.google.apiKey`; la configuración del proveedor en tiempo real de llamada de voz todavía puede reutilizarse como reserva. El navegador nunca recibe una clave de API estándar de proveedor. OpenAI recibe un secreto efímero de cliente Realtime para WebRTC. Google Live recibe un token de autenticación Live API restringido de un solo uso para una sesión WebSocket del navegador, con instrucciones y declaraciones de herramientas bloqueadas en el token por Gateway. Los proveedores que solo exponen un puente en tiempo real de backend se ejecutan mediante el transporte de retransmisión de Gateway, por lo que las credenciales y los sockets de proveedores permanecen del lado del servidor mientras el audio del navegador se mueve mediante RPC autenticados de Gateway. El prompt de sesión Realtime lo ensambla Gateway; `talk.realtime.session` no acepta anulaciones de instrucciones proporcionadas por el llamador.
|
||||
|
||||
En el compositor de Chat, el control de conversación es el botón de ondas junto al botón de dictado con micrófono. Cuando se inicia la conversación, la fila de estado del compositor muestra `Connecting Talk...`, luego `Talk live` mientras el audio está conectado, o `Asking OpenClaw...` mientras una llamada a herramienta en tiempo real consulta el modelo más grande configurado mediante `chat.send`.
|
||||
En el compositor de chat, el control de conversación es el botón de ondas junto al botón de dictado por micrófono. Cuando se inicia la conversación, la fila de estado del compositor muestra `Connecting Talk...`, luego `Talk live` mientras el audio está conectado, o `Asking OpenClaw...` mientras una llamada a herramienta en tiempo real consulta el modelo más grande configurado mediante `chat.send`.
|
||||
|
||||
Prueba en vivo para mantenedores: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica el intercambio SDP de WebRTC del navegador con OpenAI, la configuración WebSocket de navegador con token restringido de Google Live y el adaptador de navegador de retransmisión de Gateway con medios de micrófono falsos. El comando imprime solo el estado del proveedor y no registra secretos.
|
||||
Smoke en vivo para mantenedores: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica el intercambio SDP WebRTC del navegador con OpenAI, la configuración WebSocket del navegador con token restringido de Google Live y el adaptador de navegador de retransmisión de Gateway con medios de micrófono simulados. El comando imprime solo el estado del proveedor y no registra secretos.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Detener y abortar">
|
||||
- Haz clic en **Stop** (llama a `chat.abort`).
|
||||
- Mientras una ejecución está activa, los seguimientos normales se ponen en cola. Haz clic en **Steer** en un mensaje en cola para inyectar ese seguimiento en el turno en ejecución.
|
||||
- Escribe `/stop` (o frases de aborto independientes como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fuera de banda.
|
||||
- `chat.abort` admite `{ sessionKey }` (sin `runId`) para abortar todas las ejecuciones activas de esa sesión.
|
||||
<Accordion title="Stop and abort">
|
||||
- Haz clic en **Detener** (llama a `chat.abort`).
|
||||
- Mientras una ejecución está activa, los seguimientos normales se ponen en cola. Haz clic en **Dirigir** en un mensaje en cola para inyectar ese seguimiento en el turno en ejecución.
|
||||
- Escribe `/stop` (o frases de cancelación independientes como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para cancelar fuera de banda.
|
||||
- `chat.abort` admite `{ sessionKey }` (sin `runId`) para cancelar todas las ejecuciones activas de esa sesión.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Retención parcial al abortar">
|
||||
- Cuando se aborta una ejecución, el texto parcial del asistente aún puede mostrarse en la UI.
|
||||
- Gateway conserva el texto parcial abortado del asistente en el historial de transcripción cuando existe salida almacenada en búfer.
|
||||
- Las entradas conservadas incluyen metadatos de aborto para que los consumidores de transcripciones puedan distinguir parciales abortados de la salida de finalización normal.
|
||||
<Accordion title="Abort partial retention">
|
||||
- Cuando se cancela una ejecución, todavía puede mostrarse texto parcial del asistente en la UI.
|
||||
- Gateway conserva texto parcial cancelado del asistente en el historial de transcripción cuando existe salida almacenada en búfer.
|
||||
- Las entradas conservadas incluyen metadatos de cancelación para que los consumidores de transcripciones puedan distinguir los parciales cancelados de la salida de finalización normal.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Instalación de PWA y Web Push
|
||||
|
||||
La Control UI incluye un `manifest.webmanifest` y un service worker, por lo que los navegadores modernos pueden instalarla como una PWA independiente. Web Push permite que Gateway despierte la PWA instalada con notificaciones incluso cuando la pestaña o la ventana del navegador no está abierta.
|
||||
La interfaz de control incluye un `manifest.webmanifest` y un service worker, por lo que los navegadores modernos pueden instalarla como una PWA independiente. Web Push permite que Gateway active la PWA instalada con notificaciones incluso cuando la pestaña o la ventana del navegador no está abierta.
|
||||
|
||||
| Superficie | Qué hace |
|
||||
| ------------------------------------------------------ | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Manifiesto de PWA. Los navegadores ofrecen "Install app" cuando es accesible. |
|
||||
| `ui/public/sw.js` | Service worker que gestiona eventos `push` y clics de notificación. |
|
||||
| `push/vapid-keys.json` (bajo el directorio de estado de OpenClaw) | Par de claves VAPID generado automáticamente y usado para firmar cargas Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Endpoints de suscripción de navegador conservados. |
|
||||
| Superficie | Qué hace |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Manifiesto PWA. Los navegadores ofrecen "Instalar app" una vez que es accesible. |
|
||||
| `ui/public/sw.js` | Service worker que maneja eventos `push` y clics en notificaciones. |
|
||||
| `push/vapid-keys.json` (bajo el directorio de estado de OpenClaw) | Par de claves VAPID generado automáticamente que se usa para firmar cargas útiles de Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Endpoints de suscripción del navegador conservados. |
|
||||
|
||||
Sobrescribe el par de claves VAPID mediante variables de entorno en el proceso de Gateway cuando quieras fijar claves (para despliegues multi-host, rotación de secretos o pruebas):
|
||||
Anula el par de claves VAPID mediante variables de entorno en el proceso Gateway cuando quieras fijar claves (para despliegues multihost, rotación de secretos o pruebas):
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (predeterminado: `mailto:openclaw@localhost`)
|
||||
- `OPENCLAW_VAPID_SUBJECT` (por defecto `mailto:openclaw@localhost`)
|
||||
|
||||
La Control UI usa estos métodos de Gateway limitados por alcance para registrar y probar suscripciones de navegador:
|
||||
La interfaz de control usa estos métodos de Gateway limitados por alcance para registrar y probar suscripciones de navegador:
|
||||
|
||||
- `push.web.vapidPublicKey` — obtiene la clave pública VAPID activa.
|
||||
- `push.web.subscribe` — registra un `endpoint` más `keys.p256dh`/`keys.auth`.
|
||||
@ -221,16 +221,16 @@ La Control UI usa estos métodos de Gateway limitados por alcance para registrar
|
||||
Web Push es independiente de la ruta de retransmisión APNS de iOS (consulta [Configuración](/es/gateway/configuration) para push respaldado por retransmisión) y del método existente `push.test`, que apunta al emparejamiento móvil nativo.
|
||||
</Note>
|
||||
|
||||
## Embeds alojados
|
||||
## Inserts alojados
|
||||
|
||||
Los mensajes del asistente pueden renderizar contenido web alojado en línea con el shortcode `[embed ...]`. La política de sandbox del iframe se controla mediante `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Deshabilita la ejecución de scripts dentro de embeds alojados.
|
||||
Deshabilita la ejecución de scripts dentro de inserts alojados.
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
Permite embeds interactivos mientras mantiene el aislamiento de origen; este es el valor predeterminado y suele bastar para juegos/widgets de navegador autónomos.
|
||||
Permite inserts interactivos mientras mantiene el aislamiento de origen; es el valor predeterminado y suele ser suficiente para juegos/widgets de navegador autocontenidos.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Agrega `allow-same-origin` además de `allow-scripts` para documentos del mismo sitio que necesitan intencionalmente privilegios más fuertes.
|
||||
@ -250,14 +250,14 @@ Ejemplo:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Usa `trusted` solo cuando el documento incrustado realmente necesite comportamiento de mismo origen. Para la mayoría de los juegos generados por agentes y lienzos interactivos, `scripts` es la opción más segura.
|
||||
Usa `trusted` solo cuando el documento insertado realmente necesita comportamiento de mismo origen. Para la mayoría de los juegos generados por agentes y lienzos interactivos, `scripts` es la opción más segura.
|
||||
</Warning>
|
||||
|
||||
Las URLs externas absolutas de embeds `http(s)` permanecen bloqueadas de forma predeterminada. Si intencionalmente quieres que `[embed url="https://..."]` cargue páginas de terceros, establece `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Las URLs de inserción externas absolutas `http(s)` permanecen bloqueadas por defecto. Si intencionalmente quieres que `[embed url="https://..."]` cargue páginas de terceros, establece `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Ancho de mensajes del chat
|
||||
## Ancho de mensajes de chat
|
||||
|
||||
Los mensajes agrupados del chat usan un ancho máximo legible predeterminado. Los despliegues en monitores anchos pueden sobrescribirlo sin parchear el CSS incluido estableciendo `gateway.controlUi.chatMessageMaxWidth`:
|
||||
Los mensajes de chat agrupados usan un ancho máximo legible por defecto. Los despliegues con monitores anchos pueden anularlo sin parchear el CSS incluido configurando `gateway.controlUi.chatMessageMaxWidth`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,12 +269,12 @@ Los mensajes agrupados del chat usan un ancho máximo legible predeterminado. Lo
|
||||
}
|
||||
```
|
||||
|
||||
El valor se valida antes de llegar al navegador. Los valores admitidos incluyen longitudes simples y porcentajes como `960px` o `82%`, además de expresiones de ancho restringidas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` y `fit-content(...)`.
|
||||
El valor se valida antes de llegar al navegador. Los valores admitidos incluyen longitudes y porcentajes simples como `960px` o `82%`, además de expresiones de ancho restringidas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` y `fit-content(...)`.
|
||||
|
||||
## Acceso a tailnet (recomendado)
|
||||
## Acceso tailnet (recomendado)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tailscale Serve integrado (preferido)">
|
||||
<Tab title="Integrated Tailscale Serve (preferred)">
|
||||
Mantén Gateway en local loopback y deja que Tailscale Serve lo proxifique con HTTPS:
|
||||
|
||||
```bash
|
||||
@ -285,16 +285,16 @@ El valor se valida antes de llegar al navegador. Los valores admitidos incluyen
|
||||
|
||||
- `https://<magicdns>/` (o tu `gateway.controlUi.basePath` configurado)
|
||||
|
||||
De forma predeterminada, las solicitudes de Control UI/WebSocket Serve pueden autenticarse mediante encabezados de identidad de Tailscale (`tailscale-user-login`) cuando `gateway.auth.allowTailscale` es `true`. OpenClaw verifica la identidad resolviendo la dirección `x-forwarded-for` con `tailscale whois` y comparándola con el encabezado, y solo las acepta cuando la solicitud llega a local loopback con los encabezados `x-forwarded-*` de Tailscale. Para sesiones de operador de Control UI con identidad de dispositivo del navegador, esta ruta Serve verificada también omite la ronda de emparejamiento del dispositivo; los navegadores sin dispositivo y las conexiones con rol de nodo aún siguen las comprobaciones normales de dispositivo. Establece `gateway.auth.allowTailscale: false` si quieres exigir credenciales explícitas de secreto compartido incluso para tráfico Serve. Luego usa `gateway.auth.mode: "token"` o `"password"`.
|
||||
Por defecto, las solicitudes Serve de la interfaz de control/WebSocket pueden autenticarse mediante encabezados de identidad de Tailscale (`tailscale-user-login`) cuando `gateway.auth.allowTailscale` es `true`. OpenClaw verifica la identidad resolviendo la dirección `x-forwarded-for` con `tailscale whois` y comparándola con el encabezado, y solo las acepta cuando la solicitud llega a local loopback con los encabezados `x-forwarded-*` de Tailscale. Para sesiones de operador de la interfaz de control con identidad de dispositivo del navegador, esta ruta Serve verificada también omite el viaje de ida y vuelta de emparejamiento de dispositivo; los navegadores sin dispositivo y las conexiones con rol de nodo siguen siguiendo las comprobaciones normales de dispositivo. Establece `gateway.auth.allowTailscale: false` si quieres exigir credenciales explícitas de secreto compartido incluso para tráfico Serve. Luego usa `gateway.auth.mode: "token"` o `"password"`.
|
||||
|
||||
Para esa ruta asíncrona de identidad Serve, los intentos de autenticación fallidos para la misma IP de cliente y alcance de autenticación se serializan antes de las escrituras de límite de tasa. Por lo tanto, los reintentos erróneos concurrentes desde el mismo navegador pueden mostrar `retry later` en la segunda solicitud en lugar de dos discrepancias simples compitiendo en paralelo.
|
||||
Para esa ruta asíncrona de identidad Serve, los intentos de autenticación fallidos para la misma IP de cliente y alcance de autenticación se serializan antes de escribir límites de tasa. Por tanto, los reintentos incorrectos concurrentes desde el mismo navegador pueden mostrar `retry later` en la segunda solicitud en lugar de dos discrepancias simples compitiendo en paralelo.
|
||||
|
||||
<Warning>
|
||||
La autenticación Serve sin token asume que el host de gateway es de confianza. Si código local no confiable puede ejecutarse en ese host, exige autenticación con token/contraseña.
|
||||
La autenticación Serve sin token asume que el host de Gateway es de confianza. Si puede ejecutarse código local no confiable en ese host, exige autenticación con token/contraseña.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Vincular a tailnet + token">
|
||||
<Tab title="Bind to tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
@ -303,28 +303,28 @@ El valor se valida antes de llegar al navegador. Los valores admitidos incluyen
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (o tu `gateway.controlUi.basePath` configurado)
|
||||
|
||||
Pega el secreto compartido correspondiente en la configuración de la UI (enviado como `connect.params.auth.token` o `connect.params.auth.password`).
|
||||
Pega el secreto compartido coincidente en la configuración de la UI (enviado como `connect.params.auth.token` o `connect.params.auth.password`).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## HTTP inseguro
|
||||
|
||||
Si abres el panel mediante HTTP plano (`http://<lan-ip>` o `http://<tailscale-ip>`), el navegador se ejecuta en un **contexto no seguro** y bloquea WebCrypto. De forma predeterminada, OpenClaw **bloquea** las conexiones de Control UI sin identidad de dispositivo.
|
||||
Si abres el panel mediante HTTP simple (`http://<lan-ip>` o `http://<tailscale-ip>`), el navegador se ejecuta en un **contexto no seguro** y bloquea WebCrypto. Por defecto, OpenClaw **bloquea** conexiones de la interfaz de control sin identidad de dispositivo.
|
||||
|
||||
Excepciones documentadas:
|
||||
|
||||
- compatibilidad HTTP insegura solo para localhost con `gateway.controlUi.allowInsecureAuth=true`
|
||||
- autenticación correcta de Control UI de operador mediante `gateway.auth.mode: "trusted-proxy"`
|
||||
- autenticación correcta de la interfaz de control de operador mediante `gateway.auth.mode: "trusted-proxy"`
|
||||
- emergencia `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Solución recomendada:** usa HTTPS (Tailscale Serve) o abre la interfaz de usuario localmente:
|
||||
**Corrección recomendada:** usa HTTPS (Tailscale Serve) o abre la UI localmente:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (en el host del Gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Insecure-auth toggle behavior">
|
||||
<Accordion title="Comportamiento del interruptor de autenticación insegura">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -335,14 +335,14 @@ Excepciones documentadas:
|
||||
}
|
||||
```
|
||||
|
||||
`allowInsecureAuth` es solo un selector de compatibilidad local:
|
||||
`allowInsecureAuth` es solo un interruptor de compatibilidad local:
|
||||
|
||||
- Permite que las sesiones de la interfaz de Control UI de localhost continúen sin identidad de dispositivo en contextos HTTP no seguros.
|
||||
- Permite que las sesiones de la UI de Control en localhost continúen sin identidad del dispositivo en contextos HTTP no seguros.
|
||||
- No omite las comprobaciones de emparejamiento.
|
||||
- No relaja los requisitos de identidad de dispositivo remota (no localhost).
|
||||
- No relaja los requisitos de identidad de dispositivo remotos (no localhost).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Break-glass only">
|
||||
<Accordion title="Solo para emergencia">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -354,14 +354,14 @@ Excepciones documentadas:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` desactiva las comprobaciones de identidad de dispositivo de Control UI y supone una degradación grave de seguridad. Revierte el cambio rápidamente después del uso de emergencia.
|
||||
`dangerouslyDisableDeviceAuth` desactiva las comprobaciones de identidad de dispositivo de la UI de Control y supone una degradación grave de seguridad. Reviértelo rápidamente después del uso de emergencia.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Trusted-proxy note">
|
||||
- Una autenticación de proxy confiable correcta puede admitir sesiones de Control UI de **operador** sin identidad de dispositivo.
|
||||
- Esto **no** se extiende a las sesiones de Control UI con rol de nodo.
|
||||
- Los proxies inversos de local loopback en el mismo host siguen sin satisfacer la autenticación de proxy confiable; consulta [autenticación de proxy confiable](/es/gateway/trusted-proxy-auth).
|
||||
<Accordion title="Nota sobre proxy de confianza">
|
||||
- La autenticación correcta mediante proxy de confianza puede admitir sesiones de la UI de Control de **operador** sin identidad de dispositivo.
|
||||
- Esto **no** se extiende a las sesiones de la UI de Control con rol de nodo.
|
||||
- Los proxies inversos de loopback en el mismo host siguen sin satisfacer la autenticación de proxy de confianza; consulta [Autenticación de proxy de confianza](/es/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -370,28 +370,38 @@ Consulta [Tailscale](/es/gateway/tailscale) para obtener orientación sobre la c
|
||||
|
||||
## Política de seguridad de contenido
|
||||
|
||||
Control UI se entrega con una política `img-src` estricta: solo se permiten recursos de **mismo origen**, URL `data:` y URL `blob:` generadas localmente. El navegador rechaza las URL de imágenes remotas `http(s)` y relativas al protocolo, y no emite solicitudes de red.
|
||||
La UI de Control se distribuye con una política `img-src` estricta: solo se permiten recursos de **mismo origen**, URL `data:` y URL `blob:` generadas localmente. Las URL de imágenes remotas `http(s)` y relativas al protocolo son rechazadas por el navegador y no generan solicitudes de red.
|
||||
|
||||
Qué significa esto en la práctica:
|
||||
|
||||
- Los avatares e imágenes servidos bajo rutas relativas (por ejemplo `/avatars/<id>`) siguen renderizándose, incluidas las rutas de avatar autenticadas que la interfaz de usuario obtiene y convierte en URL `blob:` locales.
|
||||
- Las URL `data:image/...` en línea siguen renderizándose (útil para cargas de protocolo).
|
||||
- Las URL `blob:` locales creadas por Control UI siguen renderizándose.
|
||||
- Las URL remotas de avatar emitidas por metadatos de canal se eliminan en los helpers de avatar de Control UI y se reemplazan por el logotipo/insignia integrado, por lo que un canal comprometido o malicioso no puede forzar solicitudes arbitrarias de imágenes remotas desde el navegador de un operador.
|
||||
- Los avatares y las imágenes servidos bajo rutas relativas (por ejemplo `/avatars/<id>`) se siguen renderizando, incluidas las rutas de avatar autenticadas que la UI obtiene y convierte en URL `blob:` locales.
|
||||
- Las URL en línea `data:image/...` se siguen renderizando (útil para cargas en protocolo).
|
||||
- Las URL `blob:` locales creadas por la UI de Control se siguen renderizando.
|
||||
- Las URL de avatar remotas emitidas por los metadatos de canal se eliminan en los ayudantes de avatar de la UI de Control y se sustituyen por el logotipo/insignia integrado, por lo que un canal comprometido o malicioso no puede forzar cargas arbitrarias de imágenes remotas desde el navegador de un operador.
|
||||
|
||||
No necesitas cambiar nada para obtener este comportamiento: siempre está activado y no es configurable.
|
||||
|
||||
## Autenticación de ruta de avatar
|
||||
## Autenticación de la ruta de avatar
|
||||
|
||||
Cuando la autenticación del Gateway está configurada, el endpoint de avatar de Control UI requiere el mismo token de Gateway que el resto de la API:
|
||||
Cuando la autenticación del Gateway está configurada, el endpoint de avatar de la UI de Control requiere el mismo token del Gateway que el resto de la API:
|
||||
|
||||
- `GET /avatar/<agentId>` devuelve la imagen del avatar solo a llamadores autenticados. `GET /avatar/<agentId>?meta=1` devuelve los metadatos del avatar bajo la misma regla.
|
||||
- Las solicitudes no autenticadas a cualquiera de las rutas se rechazan (coincidiendo con la ruta hermana assistant-media). Esto evita que la ruta de avatar filtre la identidad del agente en hosts que, por lo demás, están protegidos.
|
||||
- Control UI reenvía el token del Gateway como encabezado bearer al obtener avatares y usa URL blob autenticadas para que la imagen siga renderizándose en los paneles.
|
||||
- `GET /avatar/<agentId>` devuelve la imagen del avatar solo a solicitantes autenticados. `GET /avatar/<agentId>?meta=1` devuelve los metadatos del avatar bajo la misma regla.
|
||||
- Las solicitudes no autenticadas a cualquiera de las rutas se rechazan (igual que la ruta hermana de medios del asistente). Esto evita que la ruta de avatar filtre la identidad del agente en hosts que, por lo demás, están protegidos.
|
||||
- La propia UI de Control reenvía el token del Gateway como encabezado bearer al obtener avatares y usa URL blob autenticadas para que la imagen se siga renderizando en los paneles.
|
||||
|
||||
Si desactivas la autenticación del Gateway (no recomendado en hosts compartidos), la ruta de avatar también pasa a no requerir autenticación, en línea con el resto del Gateway.
|
||||
Si desactivas la autenticación del Gateway (no recomendado en hosts compartidos), la ruta de avatar también deja de requerir autenticación, de acuerdo con el resto del Gateway.
|
||||
|
||||
## Compilar la interfaz de usuario
|
||||
## Autenticación de la ruta de medios del asistente
|
||||
|
||||
Cuando la autenticación del Gateway está configurada, las vistas previas de medios locales del asistente usan una ruta de dos pasos:
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` requiere la autenticación normal de operador de la UI de Control. El navegador envía el token del Gateway como encabezado bearer al comprobar la disponibilidad.
|
||||
- Las respuestas de metadatos correctas incluyen un `mediaTicket` de corta duración limitado a esa ruta de origen exacta.
|
||||
- Las URL de imágenes, audio, vídeo y documentos renderizadas por el navegador usan `mediaTicket=<ticket>` en lugar del token o la contraseña activos del Gateway. El ticket caduca rápidamente y no puede autorizar un origen diferente.
|
||||
|
||||
Esto mantiene la renderización normal de medios compatible con los elementos multimedia nativos del navegador sin poner credenciales reutilizables del Gateway en URL de medios visibles.
|
||||
|
||||
## Compilar la UI
|
||||
|
||||
El Gateway sirve archivos estáticos desde `dist/control-ui`. Compílalos con:
|
||||
|
||||
@ -411,24 +421,24 @@ Para desarrollo local (servidor de desarrollo separado):
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Luego apunta la interfaz de usuario a la URL WS de tu Gateway (por ejemplo, `ws://127.0.0.1:18789`).
|
||||
Después apunta la UI a tu URL WS del Gateway (por ejemplo, `ws://127.0.0.1:18789`).
|
||||
|
||||
## Depuración/pruebas: servidor de desarrollo + Gateway remoto
|
||||
|
||||
Control UI consiste en archivos estáticos; el destino WebSocket es configurable y puede ser distinto del origen HTTP. Esto resulta práctico cuando quieres usar el servidor de desarrollo de Vite localmente, pero el Gateway se ejecuta en otro lugar.
|
||||
La UI de Control son archivos estáticos; el destino WebSocket es configurable y puede ser distinto del origen HTTP. Esto es útil cuando quieres usar el servidor de desarrollo de Vite localmente, pero el Gateway se ejecuta en otro lugar.
|
||||
|
||||
<Steps>
|
||||
<Step title="Start the UI dev server">
|
||||
<Step title="Inicia el servidor de desarrollo de la UI">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
</Step>
|
||||
<Step title="Open with gatewayUrl">
|
||||
<Step title="Abre con gatewayUrl">
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
|
||||
Autenticación opcional de un solo uso (si hace falta):
|
||||
Autenticación opcional de un solo uso (si es necesaria):
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
|
||||
@ -438,18 +448,18 @@ Control UI consiste en archivos estáticos; el destino WebSocket es configurable
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Notes">
|
||||
<Accordion title="Notas">
|
||||
- `gatewayUrl` se almacena en localStorage después de la carga y se elimina de la URL.
|
||||
- Si pasas un endpoint `ws://` o `wss://` completo mediante `gatewayUrl`, codifica en URL el valor de `gatewayUrl` para que el navegador analice correctamente la cadena de consulta.
|
||||
- `token` debe pasarse mediante el fragmento de URL (`#token=...`) siempre que sea posible. Los fragmentos no se envían al servidor, lo que evita filtraciones en registros de solicitudes y Referer. Los parámetros de consulta heredados `?token=` aún se importan una vez por compatibilidad, pero solo como alternativa, y se eliminan inmediatamente después del arranque.
|
||||
- Si pasas un endpoint completo `ws://` o `wss://` mediante `gatewayUrl`, codifica en URL el valor de `gatewayUrl` para que el navegador analice correctamente la cadena de consulta.
|
||||
- `token` debe pasarse mediante el fragmento de URL (`#token=...`) siempre que sea posible. Los fragmentos no se envían al servidor, lo que evita filtraciones en registros de solicitudes y Referer. Los parámetros de consulta heredados `?token=` todavía se importan una vez por compatibilidad, pero solo como alternativa, y se eliminan inmediatamente después del arranque.
|
||||
- `password` se mantiene solo en memoria.
|
||||
- Cuando `gatewayUrl` está configurado, la interfaz de usuario no recurre a credenciales de configuración ni de entorno. Proporciona `token` (o `password`) explícitamente. La falta de credenciales explícitas es un error.
|
||||
- Cuando `gatewayUrl` está definido, la UI no recurre a credenciales de configuración ni de entorno. Proporciona `token` (o `password`) explícitamente. La ausencia de credenciales explícitas es un error.
|
||||
- Usa `wss://` cuando el Gateway esté detrás de TLS (Tailscale Serve, proxy HTTPS, etc.).
|
||||
- `gatewayUrl` solo se acepta en una ventana de nivel superior (no incrustada) para evitar clickjacking.
|
||||
- Los despliegues de Control UI que no sean de loopback deben configurar `gateway.controlUi.allowedOrigins` explícitamente (orígenes completos). Esto incluye configuraciones de desarrollo remotas.
|
||||
- El arranque del Gateway puede sembrar orígenes locales como `http://localhost:<port>` y `http://127.0.0.1:<port>` a partir del enlace y puerto efectivos en tiempo de ejecución, pero los orígenes de navegadores remotos siguen necesitando entradas explícitas.
|
||||
- No uses `gateway.controlUi.allowedOrigins: ["*"]` salvo para pruebas locales estrictamente controladas. Significa permitir cualquier origen de navegador, no “coincidir con cualquier host que esté usando”.
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita el modo de reserva de origen por encabezado Host, pero es un modo de seguridad peligroso.
|
||||
- `gatewayUrl` solo se acepta en una ventana de nivel superior (no incrustada) para prevenir clickjacking.
|
||||
- Los despliegues de la UI de Control que no sean de loopback deben definir `gateway.controlUi.allowedOrigins` explícitamente (orígenes completos). Esto incluye configuraciones de desarrollo remotas.
|
||||
- El arranque del Gateway puede sembrar orígenes locales como `http://localhost:<port>` y `http://127.0.0.1:<port>` a partir del bind y puerto efectivos en tiempo de ejecución, pero los orígenes de navegadores remotos siguen necesitando entradas explícitas.
|
||||
- No uses `gateway.controlUi.allowedOrigins: ["*"]` salvo para pruebas locales estrictamente controladas. Significa permitir cualquier origen de navegador, no "coincidir con cualquier host que esté usando".
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` activa el modo de origen alternativo mediante encabezado Host, pero es un modo de seguridad peligroso.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -466,11 +476,11 @@ Ejemplo:
|
||||
}
|
||||
```
|
||||
|
||||
Detalles de configuración del acceso remoto: [acceso remoto](/es/gateway/remote).
|
||||
Detalles de configuración del acceso remoto: [Acceso remoto](/es/gateway/remote).
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Panel](/es/web/dashboard) — panel del Gateway
|
||||
- [Comprobaciones de estado](/es/gateway/health) — supervisión del estado del Gateway
|
||||
- [Comprobaciones de estado](/es/gateway/health) — supervisión de estado del Gateway
|
||||
- [TUI](/es/web/tui) — interfaz de usuario de terminal
|
||||
- [WebChat](/es/web/webchat) — interfaz de chat basada en navegador
|
||||
|
||||
Loading…
Reference in New Issue
Block a user