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

chore(i18n): refresh es translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-04 18:26:05 +00:00
parent 9da996e409
commit b522d331b5
11 changed files with 1085 additions and 999 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
docs/es/channels/zalouser.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Configurar Zalo Personal para OpenClaw
- Configuración de Zalo Personal para OpenClaw
- Depuración del inicio de sesión o del flujo de mensajes de Zalo Personal
summary: Soporte para cuentas personales de Zalo mediante zca-js nativo (inicio de sesión con QR), capacidades y configuración
summary: Compatibilidad con cuentas personales de Zalo mediante zca-js nativo (inicio de sesión con QR), capacidades y configuración
title: Zalo personal
x-i18n:
generated_at: "2026-05-02T22:17:12Z"
generated_at: "2026-05-04T18:23:40Z"
model: gpt-5.5
provider: openai
source_hash: 0096775e0017e504130f2e19e05ab8114eadb873a9e11f79ea8f0dd91297567f
source_hash: 0f6d27f0ca502e6426abe21d609efd0a168a0b6b0fafe8d52d59f1a717da1ed5
source_path: channels/zalouser.md
workflow: 16
---
@ -16,31 +16,31 @@ x-i18n:
Estado: experimental. Esta integración automatiza una **cuenta personal de Zalo** mediante `zca-js` nativo dentro de OpenClaw.
<Warning>
Esta es una integración no oficial y puede provocar la suspensión o prohibición de la cuenta. Úsala bajo tu propio riesgo.
Esta es una integración no oficial y puede provocar la suspensión o el bloqueo de la cuenta. Úsela bajo su propia responsabilidad.
</Warning>
## Plugin incluido
Zalo Personal se distribuye como un Plugin incluido en las versiones actuales de OpenClaw, por lo que las compilaciones empaquetadas normales no necesitan una instalación separada.
Si usas una compilación anterior o una instalación personalizada que excluye Zalo Personal, instala directamente el paquete de npm:
Si usa una compilación anterior o una instalación personalizada que excluye Zalo Personal, instale el paquete npm directamente:
- Instalar mediante CLI: `openclaw plugins install @openclaw/zalouser`
- Instalar mediante la CLI: `openclaw plugins install @openclaw/zalouser`
- Versión fijada: `openclaw plugins install @openclaw/zalouser@2026.5.2`
- O desde un checkout de código fuente: `openclaw plugins install ./path/to/local/zalouser-plugin`
- O desde una copia local del código fuente: `openclaw plugins install ./path/to/local/zalouser-plugin`
- Detalles: [Plugins](/es/tools/plugin)
No se requiere ningún binario externo de CLI `zca`/`openzca`.
No se requiere ningún binario externo de la CLI `zca`/`openzca`.
## Configuración rápida (principiante)
1. Asegúrate de que el Plugin Zalo Personal esté disponible.
1. Asegúrese de que el Plugin Zalo Personal esté disponible.
- Las versiones empaquetadas actuales de OpenClaw ya lo incluyen.
- Las instalaciones anteriores/personalizadas pueden añadirlo manualmente con los comandos anteriores.
2. Inicia sesión (QR, en la máquina del Gateway):
2. Inicie sesión (QR, en la máquina del Gateway):
- `openclaw channels login --channel zalouser`
- Escanea el código QR con la aplicación móvil de Zalo.
3. Habilita el canal:
- Escanee el código QR con la aplicación móvil de Zalo.
3. Habilite el canal:
```json5
{
@ -53,23 +53,23 @@ No se requiere ningún binario externo de CLI `zca`/`openzca`.
}
```
4. Reinicia el Gateway (o finaliza la configuración).
5. El acceso por DM usa pairing de forma predeterminada; aprueba el código de pairing en el primer contacto.
4. Reinicie el Gateway (o finalice la configuración).
5. El acceso por MD usa emparejamiento de forma predeterminada; apruebe el código de emparejamiento en el primer contacto.
## Qué es
- Se ejecuta completamente en proceso mediante `zca-js`.
- Usa listeners de eventos nativos para recibir mensajes entrantes.
- Envía respuestas directamente a través de la API de JS (texto/medios/enlace).
- Está diseñado para casos de uso de “cuenta personal” donde la API de Zalo Bot no está disponible.
- Se ejecuta completamente dentro del proceso mediante `zca-js`.
- Usa escuchadores de eventos nativos para recibir mensajes entrantes.
- Envía respuestas directamente mediante la API de JS (texto/medios/enlace).
- Diseñado para casos de uso de “cuenta personal” en los que la API de Zalo Bot no está disponible.
## Nomenclatura
El id de canal es `zalouser` para dejar explícito que esto automatiza una **cuenta personal de usuario de Zalo** (no oficial). Mantenemos `zalo` reservado para una posible integración futura oficial con la API de Zalo.
El id de canal es `zalouser` para dejar explícito que esto automatiza una **cuenta personal de usuario de Zalo** (no oficial). Mantenemos `zalo` reservado para una posible integración futura con la API oficial de Zalo.
## Buscar IDs (directorio)
Usa la CLI de directorio para descubrir pares/grupos y sus IDs:
Use la CLI de directorio para descubrir pares/grupos y sus IDs:
```bash
openclaw directory self --channel zalouser
@ -82,31 +82,33 @@ openclaw directory groups list --channel zalouser --query "work"
- El texto saliente se divide en fragmentos de ~2000 caracteres (límites del cliente de Zalo).
- El streaming está bloqueado de forma predeterminada.
## Control de acceso (DMs)
## Control de acceso (MD)
`channels.zalouser.dmPolicy` admite: `pairing | allowlist | open | disabled` (predeterminado: `pairing`).
`channels.zalouser.allowFrom` acepta IDs o nombres de usuario. Durante la configuración, los nombres se resuelven a IDs usando la búsqueda de contactos en proceso del Plugin.
`channels.zalouser.allowFrom` debe usar IDs de usuario de Zalo estables. Durante la configuración interactiva, los nombres introducidos pueden resolverse a IDs mediante la búsqueda de contactos en proceso del Plugin.
Aprobar mediante:
Si un nombre sin procesar permanece en la configuración, el arranque solo lo resuelve cuando `channels.zalouser.dangerouslyAllowNameMatching: true` está habilitado. Sin esa aceptación explícita, las comprobaciones de remitente en tiempo de ejecución solo usan IDs y los nombres sin procesar se ignoran para la autorización.
Apruebe mediante:
- `openclaw pairing list zalouser`
- `openclaw pairing approve zalouser <code>`
## Acceso a grupos (opcional)
- Predeterminado: `channels.zalouser.groupPolicy = "open"` (grupos permitidos). Usa `channels.defaults.groupPolicy` para sobrescribir el valor predeterminado cuando no esté definido.
- Restringe a una allowlist con:
- Predeterminado: `channels.zalouser.groupPolicy = "open"` (grupos permitidos). Use `channels.defaults.groupPolicy` para sobrescribir el valor predeterminado cuando no esté definido.
- Restrinja a una lista de permitidos con:
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups` (las claves deben ser IDs de grupo estables; los nombres se resuelven a IDs al iniciar cuando es posible)
- `channels.zalouser.groups` (las claves deben ser IDs de grupo estables; los nombres se resuelven a IDs al arrancar solo cuando `channels.zalouser.dangerouslyAllowNameMatching: true` está habilitado)
- `channels.zalouser.groupAllowFrom` (controla qué remitentes en grupos permitidos pueden activar el bot)
- Bloquea todos los grupos: `channels.zalouser.groupPolicy = "disabled"`.
- El asistente de configuración puede solicitar allowlists de grupos.
- Al iniciar, OpenClaw resuelve los nombres de grupos/usuarios en allowlists a IDs y registra el mapeo.
- La coincidencia de allowlist de grupos se basa solo en ID de forma predeterminada. Los nombres no resueltos se ignoran para la autenticación salvo que `channels.zalouser.dangerouslyAllowNameMatching: true` esté habilitado.
- `channels.zalouser.dangerouslyAllowNameMatching: true` es un modo de compatibilidad de emergencia que vuelve a habilitar la coincidencia mutable por nombre de grupo.
- Si `groupAllowFrom` no está definido, el runtime recurre a `allowFrom` para las comprobaciones de remitentes de grupo.
- Las comprobaciones de remitente se aplican tanto a mensajes normales de grupo como a comandos de control (por ejemplo, `/new`, `/reset`).
- Bloquear todos los grupos: `channels.zalouser.groupPolicy = "disabled"`.
- El asistente de configuración puede solicitar listas de permitidos para grupos.
- Al arrancar, OpenClaw resuelve los nombres de grupos/usuarios en listas de permitidos a IDs y registra la asignación solo cuando `channels.zalouser.dangerouslyAllowNameMatching: true` está habilitado.
- La coincidencia de listas de permitidos de grupos usa solo IDs de forma predeterminada. Los nombres no resueltos se ignoran para la autenticación, salvo que `channels.zalouser.dangerouslyAllowNameMatching: true` esté habilitado.
- `channels.zalouser.dangerouslyAllowNameMatching: true` es un modo de compatibilidad de emergencia que vuelve a habilitar la resolución de nombres mutable al arranque y la coincidencia de nombres de grupo en tiempo de ejecución.
- Si `groupAllowFrom` no está definido, el tiempo de ejecución recurre a `allowFrom` para las comprobaciones de remitente de grupo.
- Las comprobaciones de remitente se aplican tanto a mensajes de grupo normales como a comandos de control (por ejemplo `/new`, `/reset`).
Ejemplo:
@ -125,15 +127,15 @@ Ejemplo:
}
```
### Control de menciones en grupos
### Control por mención en grupos
- `channels.zalouser.groups.<group>.requireMention` controla si las respuestas de grupo requieren una mención.
- Orden de resolución: id/nombre exacto del grupo -> slug de grupo normalizado -> `*` -> predeterminado (`true`).
- Esto se aplica tanto a grupos en allowlist como al modo de grupo abierto.
- Citar un mensaje del bot cuenta como una mención implícita para activar el grupo.
- Los comandos de control autorizados (por ejemplo, `/new`) pueden omitir el control de menciones.
- Cuando se omite un mensaje de grupo porque se requiere una mención, OpenClaw lo almacena como historial de grupo pendiente y lo incluye en el siguiente mensaje de grupo procesado.
- El límite de historial de grupo usa `messages.groupChat.historyLimit` de forma predeterminada (fallback `50`). Puedes sobrescribirlo por cuenta con `channels.zalouser.historyLimit`.
- Orden de resolución: id/nombre de grupo exacto -> slug de grupo normalizado -> `*` -> predeterminado (`true`).
- Esto se aplica tanto a grupos en la lista de permitidos como al modo de grupo abierto.
- Citar un mensaje del bot cuenta como una mención implícita para la activación en grupo.
- Los comandos de control autorizados (por ejemplo `/new`) pueden omitir el control por mención.
- Cuando se omite un mensaje de grupo porque se requiere mención, OpenClaw lo almacena como historial de grupo pendiente y lo incluye en el siguiente mensaje de grupo procesado.
- El límite de historial de grupo usa `messages.groupChat.historyLimit` de forma predeterminada (respaldo `50`). Puede sobrescribirlo por cuenta con `channels.zalouser.historyLimit`.
Ejemplo:
@ -153,7 +155,7 @@ Ejemplo:
## Varias cuentas
Las cuentas se mapean a perfiles `zalouser` en el estado de OpenClaw. Ejemplo:
Las cuentas se asignan a perfiles `zalouser` en el estado de OpenClaw. Ejemplo:
```json5
{
@ -169,34 +171,34 @@ Las cuentas se mapean a perfiles `zalouser` en el estado de OpenClaw. Ejemplo:
}
```
## Escritura, reacciones y acuses de entrega
## Escritura, reacciones y confirmaciones de entrega
- OpenClaw envía un evento de escritura antes de despachar una respuesta (mejor esfuerzo).
- La acción de reacción a mensajes `react` es compatible con `zalouser` en las acciones de canal.
- Usa `remove: true` para quitar un emoji de reacción específico de un mensaje.
- La acción de reacción a mensaje `react` es compatible con `zalouser` en acciones de canal.
- Use `remove: true` para eliminar un emoji de reacción específico de un mensaje.
- Semántica de reacciones: [Reacciones](/es/tools/reactions)
- Para mensajes entrantes que incluyen metadatos de evento, OpenClaw envía acuses de entregado + visto (mejor esfuerzo).
- Para los mensajes entrantes que incluyen metadatos de evento, OpenClaw envía confirmaciones de entregado + visto (mejor esfuerzo).
## Solución de problemas
**El inicio de sesión no persiste:**
**El inicio de sesión no se conserva:**
- `openclaw channels status --probe`
- Volver a iniciar sesión: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
- Vuelva a iniciar sesión: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
**El nombre de allowlist/grupo no se resolvió:**
**La lista de permitidos/el nombre de grupo no se resolvió:**
- Usa IDs numéricos en `allowFrom`/`groupAllowFrom`/`groups`, o nombres exactos de amigos/grupos.
- Use IDs numéricos en `allowFrom`/`groupAllowFrom` e IDs de grupo estables en `groups`. Si necesita intencionadamente nombres exactos de amigos/grupos, habilite `channels.zalouser.dangerouslyAllowNameMatching: true`.
**Actualizaste desde una configuración antigua basada en CLI:**
**Actualizado desde una configuración antigua basada en CLI:**
- Elimina cualquier suposición antigua sobre un proceso externo `zca`.
- El canal ahora se ejecuta completamente en OpenClaw sin binarios externos de CLI.
- Elimine cualquier suposición antigua sobre procesos externos `zca`.
- El canal ahora se ejecuta completamente en OpenClaw sin binarios externos de la CLI.
## Relacionado
- [Resumen de canales](/es/channels) — todos los canales compatibles
- [Pairing](/es/channels/pairing) — autenticación por DM y flujo de pairing
- [Grupos](/es/channels/groups) — comportamiento de chats de grupo y control de menciones
- [Descripción general de canales](/es/channels) — todos los canales compatibles
- [Emparejamiento](/es/channels/pairing) — autenticación por MD y flujo de emparejamiento
- [Grupos](/es/channels/groups) — comportamiento de chat grupal y control por mención
- [Enrutamiento de canales](/es/channels/channel-routing) — enrutamiento de sesiones para mensajes
- [Seguridad](/es/gateway/security) — modelo de acceso y endurecimiento

39
docs/es/cli/daemon.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Aún usas `openclaw daemon ...` en scripts
- Necesitas comandos de ciclo de vida del servicio (install/start/stop/restart/status)
summary: Referencia de CLI para `openclaw daemon` (alias heredado para la gestión del servicio Gateway)
- Aún usas `openclaw daemon ...` en los scripts
- Necesitas comandos del ciclo de vida del servicio (install/start/stop/restart/status)
summary: Referencia de CLI para `openclaw daemon` (alias heredado para la administración del servicio Gateway)
title: Demonio
x-i18n:
generated_at: "2026-05-02T22:17:22Z"
generated_at: "2026-05-04T18:23:50Z"
model: gpt-5.5
provider: openai
source_hash: 3f11b75bf2781e69f6f59b23364f06cf359f9f24407f25f19b9d2186f7158512
source_hash: f84e11fc50bdf38da518a8fcf415ae461a2688c2299f996eee384357c0d04a05
source_path: cli/daemon.md
workflow: 16
---
# `openclaw daemon`
Alias heredado para los comandos de administración del servicio Gateway.
Alias heredado para los comandos de gestión del servicio Gateway.
`openclaw daemon ...` se asigna a la misma superficie de control de servicio que los comandos de servicio `openclaw gateway ...`.
@ -32,7 +32,7 @@ openclaw daemon uninstall
## Subcomandos
- `status`: muestra el estado de instalación del servicio y sondea el estado de Gateway
- `status`: muestra el estado de instalación del servicio y comprueba el estado de Gateway
- `install`: instala el servicio (`launchd`/`systemd`/`schtasks`)
- `uninstall`: elimina el servicio
- `start`: inicia el servicio
@ -43,23 +43,24 @@ openclaw daemon uninstall
- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
- `restart`: `--force`, `--wait <duration>`, `--json`
- `restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
- ciclo de vida (`uninstall|start|stop`): `--json`
Notas:
- `status` resuelve los SecretRefs de autenticación configurados para la autenticación del sondeo cuando es posible.
- `status` resuelve los SecretRefs de autenticación configurados para la autenticación de sondeo cuando es posible.
- Si un SecretRef de autenticación requerido no se resuelve en esta ruta de comando, `daemon status --json` informa `rpc.authWarning` cuando falla la conectividad/autenticación del sondeo; pasa `--token`/`--password` explícitamente o resuelve primero el origen del secreto.
- Si el sondeo se realiza correctamente, las advertencias de referencias de autenticación sin resolver se suprimen para evitar falsos positivos.
- `status --deep` agrega un escaneo del servicio a nivel de sistema de mejor esfuerzo. Cuando encuentra otros servicios similares a Gateway, la salida legible para humanos imprime consejos de limpieza y advierte que un Gateway por máquina sigue siendo la recomendación normal.
- En instalaciones de Linux systemd, las comprobaciones de deriva de token de `status` incluyen fuentes de unidad tanto `Environment=` como `EnvironmentFile=`.
- Si el sondeo se realiza correctamente, las advertencias de referencia de autenticación no resuelta se suprimen para evitar falsos positivos.
- `status --deep` añade un análisis de servicio a nivel de sistema de mejor esfuerzo. Cuando encuentra otros servicios similares a Gateway, la salida para humanos imprime sugerencias de limpieza y advierte que la recomendación normal sigue siendo un Gateway por máquina.
- En instalaciones systemd de Linux, las comprobaciones de deriva de token de `status` incluyen tanto fuentes de unidad `Environment=` como `EnvironmentFile=`.
- Las comprobaciones de deriva resuelven los SecretRefs de `gateway.auth.token` usando el entorno de ejecución combinado (primero el entorno del comando de servicio y luego el entorno del proceso como alternativa).
- Si la autenticación por token no está activa de forma efectiva (`gateway.auth.mode` explícito de `password`/`none`/`trusted-proxy`, o modo sin definir cuando la contraseña puede prevalecer y ningún candidato de token puede prevalecer), las comprobaciones de deriva de token omiten la resolución del token de configuración.
- Cuando la autenticación por token requiere un token y `gateway.auth.token` está administrado por SecretRef, `install` valida que el SecretRef se pueda resolver, pero no conserva el token resuelto en los metadatos del entorno del servicio.
- Si la autenticación por token requiere un token y el SecretRef de token configurado no se resuelve, la instalación falla de forma cerrada.
- Si `gateway.auth.token` y `gateway.auth.password` están configurados y `gateway.auth.mode` no está definido, la instalación se bloquea hasta que el modo se establezca explícitamente.
- En macOS, `install` mantiene los plists de LaunchAgent solo para el propietario y carga los valores del entorno del servicio administrado mediante un archivo y envoltorio solo para el propietario, en lugar de serializar claves de API o referencias de entorno de perfiles de autenticación en `EnvironmentVariables`.
- Si ejecutas intencionalmente varios gateways en un mismo host, aísla los puertos, la configuración/estado y los espacios de trabajo; consulta [/gateway#multiple-gateways-same-host](/es/gateway#multiple-gateways-same-host).
- Si la autenticación con token no está activa de forma efectiva (`gateway.auth.mode` explícito de `password`/`none`/`trusted-proxy`, o modo no definido donde la contraseña puede ganar y ningún candidato de token puede ganar), las comprobaciones de deriva de token omiten la resolución del token de configuración.
- Cuando la autenticación con token requiere un token y `gateway.auth.token` está gestionado por SecretRef, `install` valida que el SecretRef se pueda resolver, pero no persiste el token resuelto en los metadatos del entorno del servicio.
- Si la autenticación con token requiere un token y el SecretRef del token configurado no está resuelto, la instalación falla de forma cerrada.
- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados y `gateway.auth.mode` no está definido, la instalación se bloquea hasta que el modo se defina explícitamente.
- En macOS, `install` mantiene los plists de LaunchAgent solo para el propietario y carga los valores del entorno del servicio gestionado mediante un archivo y un contenedor solo para el propietario, en lugar de serializar claves de API o referencias de entorno de perfiles de autenticación en `EnvironmentVariables`.
- Si ejecutas intencionadamente varios Gateways en un host, aísla puertos, configuración/estado y espacios de trabajo; consulta [/gateway#multiple-gateways-same-host](/es/gateway#multiple-gateways-same-host).
- `restart --safe` pide al Gateway en ejecución que haga una comprobación previa del trabajo activo y programe un único reinicio combinado después de que el trabajo activo se vacíe. `restart` simple mantiene el comportamiento existente del gestor de servicios; `--force` sigue siendo la ruta de anulación inmediata.
## Preferir
@ -68,4 +69,4 @@ Usa [`openclaw gateway`](/es/cli/gateway) para la documentación y los ejemplos
## Relacionado
- [Referencia de CLI](/es/cli)
- [Guía operativa de Gateway](/es/gateway)
- [Manual de operaciones de Gateway](/es/gateway)

269
docs/es/cli/gateway.md
View File

@ -2,15 +2,15 @@
read_when:
- Ejecución del Gateway desde la CLI (desarrollo o servidores)
- Depuración de la autenticación del Gateway, los modos de enlace y la conectividad
- Descubrimiento de Gateway mediante Bonjour (DNS-SD local y de área amplia)
- Descubrir Gateways mediante Bonjour (DNS-SD local y de área amplia)
sidebarTitle: Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — ejecuta, consulta y descubre instancias de Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — ejecutar, consultar y descubrir instancias de Gateway
title: Gateway
x-i18n:
generated_at: "2026-05-02T22:17:38Z"
generated_at: "2026-05-04T18:24:04Z"
model: gpt-5.5
provider: openai
source_hash: f7f948a8f0ee6e065afa02f354e690ad5cc4f71bdb8b8674f1b0396c439ab242
source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
source_path: cli/gateway.md
workflow: 16
---
@ -19,9 +19,9 @@ El Gateway es el servidor WebSocket de OpenClaw (canales, nodos, sesiones, hooks
<CardGroup cols={3}>
<Card title="Descubrimiento Bonjour" href="/es/gateway/bonjour">
Configuración de mDNS local + DNS-SD de área amplia.
Configuración local de mDNS + DNS-SD de área amplia.
</Card>
<Card title="Resumen del descubrimiento" href="/es/gateway/discovery">
<Card title="Descripción general del descubrimiento" href="/es/gateway/discovery">
Cómo OpenClaw anuncia y encuentra gateways.
</Card>
<Card title="Configuración" href="/es/gateway/configuration">
@ -31,7 +31,7 @@ El Gateway es el servidor WebSocket de OpenClaw (canales, nodos, sesiones, hooks
## Ejecutar el Gateway
Ejecuta un proceso Gateway local:
Ejecuta un proceso de Gateway local:
```bash
openclaw gateway
@ -45,12 +45,12 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="Comportamiento de inicio">
- De forma predeterminada, el Gateway se niega a iniciarse a menos que `gateway.mode=local` esté definido en `~/.openclaw/openclaw.json`. Usa `--allow-unconfigured` para ejecuciones ad hoc/de desarrollo.
- De forma predeterminada, el Gateway se niega a iniciar a menos que `gateway.mode=local` esté definido en `~/.openclaw/openclaw.json`. Usa `--allow-unconfigured` para ejecuciones ad hoc/de desarrollo.
- Se espera que `openclaw onboard --mode local` y `openclaw setup` escriban `gateway.mode=local`. Si el archivo existe pero falta `gateway.mode`, trátalo como una configuración rota o sobrescrita y repárala en lugar de asumir implícitamente el modo local.
- Si el archivo existe y falta `gateway.mode`, el Gateway lo trata como un daño de configuración sospechoso y se niega a "adivinar local" por ti.
- Si el archivo existe y falta `gateway.mode`, el Gateway lo trata como daño sospechoso en la configuración y se niega a "adivinar local" por ti.
- Se bloquea el enlace más allá de loopback sin autenticación (barrera de seguridad).
- `SIGUSR1` activa un reinicio dentro del proceso cuando está autorizado (`commands.restart` está habilitado de forma predeterminada; define `commands.restart: false` para bloquear el reinicio manual, mientras que la aplicación/actualización de herramientas/configuración del gateway sigue permitida).
- Los manejadores de `SIGINT`/`SIGTERM` detienen el proceso del gateway, pero no restauran ningún estado personalizado de la terminal. Si envuelves la CLI con una TUI o entrada en modo raw, restaura la terminal antes de salir.
- `SIGUSR1` activa un reinicio dentro del proceso cuando está autorizado (`commands.restart` está habilitado de forma predeterminada; establece `commands.restart: false` para bloquear el reinicio manual, mientras que la aplicación/actualización de herramientas/configuración del gateway sigue permitida).
- Los manejadores de `SIGINT`/`SIGTERM` detienen el proceso del gateway, pero no restauran ningún estado personalizado del terminal. Si envuelves la CLI con una TUI o entrada en modo sin procesar, restaura el terminal antes de salir.
</Accordion>
</AccordionGroup>
@ -67,7 +67,7 @@ openclaw gateway run
Anulación del modo de autenticación.
</ParamField>
<ParamField path="--token <token>" type="string">
Anulación del token (también define `OPENCLAW_GATEWAY_TOKEN` para el proceso).
Anulación del token (también establece `OPENCLAW_GATEWAY_TOKEN` para el proceso).
</ParamField>
<ParamField path="--password <password>" type="string">
Anulación de la contraseña.
@ -76,13 +76,13 @@ openclaw gateway run
Lee la contraseña del gateway desde un archivo.
</ParamField>
<ParamField path="--tailscale <off|serve|funnel>" type="string">
Expón el Gateway mediante Tailscale.
Expone el Gateway mediante Tailscale.
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
Restablece la configuración serve/funnel de Tailscale al apagar.
Restablece la configuración de serve/funnel de Tailscale al apagar.
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
Permite iniciar el gateway sin `gateway.mode=local` en la configuración. Omite la protección de inicio solo para arranques ad hoc/de desarrollo; no escribe ni repara el archivo de configuración.
Permite iniciar el gateway sin `gateway.mode=local` en la configuración. Omite la protección de inicio solo para arranque ad hoc/de desarrollo; no escribe ni repara el archivo de configuración.
</ParamField>
<ParamField path="--dev" type="boolean">
Crea una configuración de desarrollo + workspace si faltan (omite BOOTSTRAP.md).
@ -91,7 +91,7 @@ openclaw gateway run
Restablece la configuración de desarrollo + credenciales + sesiones + workspace (requiere `--dev`).
</ParamField>
<ParamField path="--force" type="boolean">
Termina cualquier listener existente en el puerto seleccionado antes de iniciar.
Mata cualquier listener existente en el puerto seleccionado antes de iniciar.
</ParamField>
<ParamField path="--verbose" type="boolean">
Registros detallados.
@ -100,27 +100,37 @@ openclaw gateway run
Muestra solo los registros del backend de la CLI en la consola (y habilita stdout/stderr).
</ParamField>
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
Estilo de registro de WebSocket.
Estilo de registro de Websocket.
</ParamField>
<ParamField path="--compact" type="boolean">
Alias de `--ws-log compact`.
</ParamField>
<ParamField path="--raw-stream" type="boolean">
Registra eventos raw del stream del modelo en jsonl.
Registra eventos sin procesar del flujo del modelo en jsonl.
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
Ruta jsonl del stream raw.
Ruta de jsonl del flujo sin procesar.
</ParamField>
## Reiniciar el Gateway
```bash
openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --force
```
`openclaw gateway restart --safe` pide al Gateway en ejecución que haga una comprobación previa del trabajo activo de OpenClaw antes de reiniciar. Si hay operaciones en cola, entrega de respuestas, ejecuciones incrustadas o ejecuciones de tareas activas, el Gateway informa de los bloqueos, fusiona solicitudes duplicadas de reinicio seguro y reinicia una vez que se drena el trabajo activo. `restart` sin opciones mantiene el comportamiento existente del gestor de servicios por compatibilidad. Usa `--force` solo cuando quieras explícitamente la ruta de anulación inmediata.
<Warning>
`--password` en línea puede quedar expuesto en los listados de procesos locales. Prefiere `--password-file`, env o un `gateway.auth.password` respaldado por SecretRef.
`--password` en línea puede exponerse en los listados de procesos locales. Prefiere `--password-file`, env o un `gateway.auth.password` respaldado por SecretRef.
</Warning>
### Perfilado de inicio
- Define `OPENCLAW_GATEWAY_STARTUP_TRACE=1` para registrar los tiempos de las fases durante el inicio del Gateway, incluido el retraso `eventLoopMax` por fase y los tiempos de las tablas de búsqueda de plugins para el índice instalado, el registro de manifiestos, la planificación de inicio y el trabajo del mapa de propietarios.
- Define `OPENCLAW_DIAGNOSTICS=timeline` con `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` para escribir una línea de tiempo de diagnósticos de inicio JSONL de mejor esfuerzo para arneses de QA externos. También puedes habilitar la marca con `diagnostics.flags: ["timeline"]` en la configuración; la ruta sigue proporcionándose mediante env. Añade `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` para incluir muestras del bucle de eventos.
- Ejecuta `pnpm test:startup:gateway -- --runs 5 --warmup 1` para medir el inicio del Gateway. La medición registra la primera salida del proceso, `/healthz`, `/readyz`, los tiempos de trazas de inicio, el retraso del bucle de eventos y los detalles de tiempos de la tabla de búsqueda de plugins.
- Establece `OPENCLAW_GATEWAY_STARTUP_TRACE=1` para registrar los tiempos de las fases durante el inicio del Gateway, incluido el retraso `eventLoopMax` por fase y los tiempos de las tablas de búsqueda de plugins para el índice instalado, el registro de manifiestos, la planificación de inicio y el trabajo del mapa de propietarios.
- Establece `OPENCLAW_DIAGNOSTICS=timeline` con `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` para escribir una línea temporal de diagnósticos de inicio JSONL de mejor esfuerzo para arneses externos de QA. También puedes habilitar la marca con `diagnostics.flags: ["timeline"]` en la configuración; la ruta sigue proporcionándose mediante env. Añade `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` para incluir muestras del event loop.
- Ejecuta `pnpm test:startup:gateway -- --runs 5 --warmup 1` para medir el inicio del Gateway. El benchmark registra la primera salida del proceso, `/healthz`, `/readyz`, tiempos de traza de inicio, retraso del event loop y detalles de tiempos de la tabla de búsqueda de plugins.
## Consultar un Gateway en ejecución
@ -128,23 +138,23 @@ Todos los comandos de consulta usan RPC por WebSocket.
<Tabs>
<Tab title="Modos de salida">
- Predeterminado: legible para humanos (con color en TTY).
- Predeterminado: legible por humanos (con color en TTY).
- `--json`: JSON legible por máquina (sin estilos/spinner).
- `--no-color` (o `NO_COLOR=1`): deshabilita ANSI manteniendo el diseño humano.
- `--no-color` (o `NO_COLOR=1`): deshabilita ANSI y conserva el diseño para humanos.
</Tab>
<Tab title="Opciones compartidas">
- `--url <url>`: URL WebSocket del Gateway.
- `--token <token>`: token del Gateway.
- `--password <password>`: contraseña del Gateway.
- `--timeout <ms>`: timeout/presupuesto (varía por comando).
- `--expect-final`: espera una respuesta "final" (llamadas de agente).
- `--timeout <ms>`: tiempo de espera/presupuesto (varía según el comando).
- `--expect-final`: espera una respuesta "final" (llamadas de agentes).
</Tab>
</Tabs>
<Note>
Cuando defines `--url`, la CLI no recurre a credenciales de configuración o entorno. Pasa `--token` o `--password` explícitamente. La falta de credenciales explícitas es un error.
Cuando estableces `--url`, la CLI no recurre a credenciales de configuración ni de entorno. Pasa `--token` o `--password` explícitamente. La falta de credenciales explícitas es un error.
</Note>
### `gateway health`
@ -153,11 +163,11 @@ Cuando defines `--url`, la CLI no recurre a credenciales de configuración o ent
openclaw gateway health --url ws://127.0.0.1:18789
```
El endpoint HTTP `/healthz` es una sonda de vivacidad: responde cuando el servidor puede contestar HTTP. El endpoint HTTP `/readyz` es más estricto y permanece en rojo mientras los sidecars de plugins de inicio, los canales o los hooks configurados todavía se están estabilizando. Las respuestas detalladas de preparación locales o autenticadas incluyen un bloque de diagnóstico `eventLoop` con retraso del bucle de eventos, utilización del bucle de eventos, proporción de núcleos de CPU y una marca `degraded`.
El endpoint HTTP `/healthz` es una sonda de actividad: devuelve respuesta cuando el servidor puede responder HTTP. El endpoint HTTP `/readyz` es más estricto y permanece en rojo mientras los sidecars de plugins de inicio, los canales o los hooks configurados aún se están estabilizando. Las respuestas detalladas de preparación locales o autenticadas incluyen un bloque de diagnóstico `eventLoop` con retraso del event loop, utilización del event loop, proporción de núcleos de CPU y una marca `degraded`.
### `gateway usage-cost`
Obtén resúmenes de coste de uso desde los registros de sesión.
Obtén resúmenes de costo de uso desde los registros de sesión.
```bash
openclaw gateway usage-cost
@ -191,26 +201,26 @@ openclaw gateway stability --json
Incluye solo eventos posteriores a un número de secuencia de diagnóstico.
</ParamField>
<ParamField path="--bundle [path]" type="string">
Lee un paquete de estabilidad persistido en lugar de llamar al Gateway en ejecución. Usa `--bundle latest` (o solo `--bundle`) para el paquete más reciente bajo el directorio de estado, o pasa directamente una ruta JSON del paquete.
Lee un paquete de estabilidad persistido en lugar de llamar al Gateway en ejecución. Usa `--bundle latest` (o simplemente `--bundle`) para el paquete más nuevo bajo el directorio de estado, o pasa directamente una ruta JSON de paquete.
</ParamField>
<ParamField path="--export" type="boolean">
Escribe un zip de diagnósticos de soporte compartible en lugar de imprimir los detalles de estabilidad.
Escribe un zip de diagnósticos de soporte compartible en lugar de imprimir detalles de estabilidad.
</ParamField>
<ParamField path="--output <path>" type="string">
Ruta de salida para `--export`.
</ParamField>
<AccordionGroup>
<Accordion title="Privacidad y comportamiento del paquete">
- Los registros conservan metadatos operativos: nombres de eventos, conteos, tamaños en bytes, lecturas de memoria, estado de colas/sesiones, nombres de canales/plugins y resúmenes de sesión redactados. No conservan texto de chat, cuerpos de webhook, salidas de herramientas, cuerpos raw de solicitudes o respuestas, tokens, cookies, valores secretos, nombres de host ni ids raw de sesión. Define `diagnostics.enabled: false` para deshabilitar por completo el registrador.
- En salidas fatales del Gateway, timeouts de apagado y fallos de inicio tras reinicio, OpenClaw escribe la misma instantánea de diagnóstico en `~/.openclaw/logs/stability/openclaw-stability-*.json` cuando el registrador tiene eventos. Inspecciona el paquete más reciente con `openclaw gateway stability --bundle latest`; `--limit`, `--type` y `--since-seq` también se aplican a la salida del paquete.
<Accordion title="Privacidad y comportamiento de los paquetes">
- Los registros conservan metadatos operativos: nombres de eventos, recuentos, tamaños en bytes, lecturas de memoria, estado de colas/sesiones, nombres de canales/plugins y resúmenes de sesiones redactados. No conservan texto de chat, cuerpos de webhook, salidas de herramientas, cuerpos sin procesar de solicitudes o respuestas, tokens, cookies, valores secretos, nombres de host ni ids de sesión sin procesar. Establece `diagnostics.enabled: false` para deshabilitar el registrador por completo.
- En salidas fatales del Gateway, tiempos de espera de apagado y fallos de inicio tras reinicio, OpenClaw escribe la misma instantánea de diagnóstico en `~/.openclaw/logs/stability/openclaw-stability-*.json` cuando el registrador tiene eventos. Inspecciona el paquete más nuevo con `openclaw gateway stability --bundle latest`; `--limit`, `--type` y `--since-seq` también se aplican a la salida del paquete.
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
Escribe un zip local de diagnósticos diseñado para adjuntarse a informes de errores. Para el modelo de privacidad y el contenido del paquete, consulta [Exportación de diagnósticos](/es/gateway/diagnostics).
Escribe un zip de diagnósticos local diseñado para adjuntarse a informes de errores. Para el modelo de privacidad y el contenido del paquete, consulta [Exportación de diagnósticos](/es/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@ -219,13 +229,13 @@ openclaw gateway diagnostics export --json
```
<ParamField path="--output <path>" type="string">
Ruta del zip de salida. El valor predeterminado es una exportación de soporte bajo el directorio de estado.
Ruta del zip de salida. De forma predeterminada, es una exportación de soporte bajo el directorio de estado.
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
Máximo de líneas de registro saneadas que se incluirán.
Número máximo de líneas de registro saneadas que se incluirán.
</ParamField>
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
Máximo de bytes de registro que se inspeccionarán.
Número máximo de bytes de registro que se inspeccionarán.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket del Gateway para la instantánea de salud.
@ -237,22 +247,22 @@ openclaw gateway diagnostics export --json
Contraseña del Gateway para la instantánea de salud.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="3000">
Timeout de la instantánea de estado/salud.
Tiempo de espera de la instantánea de estado/salud.
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
Omite la búsqueda del paquete de estabilidad persistido.
Omite la búsqueda de paquetes de estabilidad persistidos.
</ParamField>
<ParamField path="--json" type="boolean">
Imprime la ruta escrita, el tamaño y el manifiesto como JSON.
</ParamField>
La exportación contiene un manifiesto, un resumen en Markdown, la forma de la configuración, detalles de configuración saneados, resúmenes de registros saneados, instantáneas saneadas de estado/salud del Gateway y el paquete de estabilidad más reciente cuando existe.
La exportación contiene un manifiesto, un resumen en Markdown, la forma de la configuración, detalles de configuración saneados, resúmenes de registros saneados, instantáneas saneadas de estado/salud del Gateway y el paquete de estabilidad más nuevo cuando existe uno.
Está pensada para compartirse. Conserva detalles operativos que ayudan a depurar, como campos seguros de registros de OpenClaw, nombres de subsistemas, códigos de estado, duraciones, modos configurados, puertos, ids de plugins, ids de proveedores, ajustes de funciones no secretos y mensajes de registro operativos redactados. Omite o redacta texto de chat, cuerpos de webhook, salidas de herramientas, credenciales, cookies, identificadores de cuenta/mensaje, texto de prompts/instrucciones, nombres de host y valores secretos. Cuando un mensaje de estilo LogTape parece texto de payload de usuario/chat/herramienta, la exportación conserva solo que se omitió un mensaje y su conteo de bytes.
Está pensada para compartirse. Conserva detalles operativos que ayudan a depurar, como campos seguros de registros de OpenClaw, nombres de subsistemas, códigos de estado, duraciones, modos configurados, puertos, ids de plugins, ids de proveedores, ajustes de funciones no secretos y mensajes de registro operativos redactados. Omite o redacta texto de chat, cuerpos de webhook, salidas de herramientas, credenciales, cookies, identificadores de cuentas/mensajes, texto de prompts/instrucciones, nombres de host y valores secretos. Cuando un mensaje de estilo LogTape parece texto de carga útil de usuario/chat/herramienta, la exportación conserva solo que se omitió un mensaje más su recuento de bytes.
### `gateway status`
`gateway status` muestra el servicio Gateway (launchd/systemd/schtasks) más una sonda opcional de conectividad/capacidad de autenticación.
`gateway status` muestra el servicio Gateway (launchd/systemd/schtasks) más una sonda opcional de capacidad de conectividad/autenticación.
```bash
openclaw gateway status
@ -261,63 +271,63 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
Añade un destino de sonda explícito. El remoto configurado + localhost siguen sondeándose.
Añade un objetivo de sondeo explícito. El remoto configurado + localhost se siguen sondeando.
</ParamField>
<ParamField path="--token <token>" type="string">
Autenticación por token para la sonda.
Autenticación por token para el sondeo.
</ParamField>
<ParamField path="--password <password>" type="string">
Autenticación por contraseña para la sonda.
Autenticación por contraseña para el sondeo.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
Timeout de la sonda.
Tiempo de espera del sondeo.
</ParamField>
<ParamField path="--no-probe" type="boolean">
Omite la sonda de conectividad (vista solo del servicio).
Omite el sondeo de conectividad (vista solo de servicio).
</ParamField>
<ParamField path="--deep" type="boolean">
Escanea también servicios de nivel de sistema.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
Actualiza la sonda de conectividad predeterminada a una sonda de lectura y sale con código distinto de cero cuando esa sonda de lectura falla. No se puede combinar con `--no-probe`.
Actualiza el sondeo de conectividad predeterminado a un sondeo de lectura y sale con un valor distinto de cero cuando ese sondeo de lectura falla. No se puede combinar con `--no-probe`.
</ParamField>
<AccordionGroup>
<Accordion title="Status semantics">
- `gateway status` permanece disponible para diagnósticos incluso cuando falta la configuración local de la CLI o no es válida.
- El `gateway status` predeterminado comprueba el estado del servicio, la conexión WebSocket y la capacidad de autenticación visible en el momento del handshake. No comprueba operaciones de lectura/escritura/administración.
- Las sondas de diagnóstico no mutan la autenticación de dispositivos por primera vez: reutilizan un token de dispositivo almacenado en caché existente cuando existe, pero no crean una nueva identidad de dispositivo de la CLI ni un registro de emparejamiento de dispositivo de solo lectura solo para comprobar el estado.
- `gateway status` resuelve los SecretRefs de autenticación configurados para la autenticación de la sonda cuando es posible.
- Si un SecretRef de autenticación requerido no se resuelve en esta ruta de comando, `gateway status --json` informa `rpc.authWarning` cuando la conectividad/autenticación de la sonda falla; pasa `--token`/`--password` explícitamente o resuelve primero el origen del secreto.
- Si la sonda se completa correctamente, las advertencias de referencias de autenticación sin resolver se suprimen para evitar falsos positivos.
- Usa `--require-rpc` en scripts y automatización cuando un servicio en escucha no sea suficiente y también necesites que las llamadas RPC con alcance de lectura estén saludables.
- `--deep` añade un escaneo de mejor esfuerzo en busca de instalaciones launchd/systemd/schtasks adicionales. Cuando se detectan varios servicios similares a gateway, la salida para humanos imprime sugerencias de limpieza y advierte que la mayoría de las configuraciones deberían ejecutar un gateway por máquina.
- La salida para humanos incluye la ruta resuelta del registro de archivo más una instantánea de las rutas/validez de configuración entre la CLI y el servicio para ayudar a diagnosticar desviaciones de perfil o directorio de estado.
<Accordion title="Semántica de estado">
- `gateway status` sigue estando disponible para diagnósticos incluso cuando la configuración local de la CLI falta o no es válida.
- `gateway status` predeterminado demuestra el estado del servicio, la conexión WebSocket y la capacidad de autenticación visible en el momento del handshake. No demuestra operaciones de lectura/escritura/administración.
- Los sondeos de diagnóstico no realizan mutaciones para la autenticación de dispositivos por primera vez: reutilizan un token de dispositivo almacenado en caché existente cuando existe uno, pero no crean una nueva identidad de dispositivo de la CLI ni un registro de emparejamiento de dispositivo de solo lectura solo para comprobar el estado.
- `gateway status` resuelve SecretRefs de autenticación configurados para la autenticación del sondeo cuando es posible.
- Si un SecretRef de autenticación requerido no se resuelve en esta ruta de comando, `gateway status --json` informa `rpc.authWarning` cuando la conectividad/autenticación del sondeo falla; pasa `--token`/`--password` explícitamente o resuelve primero el origen del secreto.
- Si el sondeo se completa correctamente, se suprimen las advertencias de referencias de autenticación no resueltas para evitar falsos positivos.
- Usa `--require-rpc` en scripts y automatización cuando un servicio en escucha no sea suficiente y necesites que las llamadas RPC con alcance de lectura también estén en buen estado.
- `--deep` añade un escaneo de mejor esfuerzo para instalaciones launchd/systemd/schtasks adicionales. Cuando se detectan varios servicios similares a Gateway, la salida legible imprime sugerencias de limpieza y advierte que la mayoría de las configuraciones deberían ejecutar un Gateway por máquina.
- La salida legible incluye la ruta resuelta del archivo de registro más una instantánea de rutas/validez de configuración CLI frente a servicio para ayudar a diagnosticar desviaciones de perfil o de directorio de estado.
</Accordion>
<Accordion title="Linux systemd auth-drift checks">
- En instalaciones Linux systemd, las comprobaciones de desviación de autenticación del servicio leen los valores `Environment=` y `EnvironmentFile=` de la unidad (incluidos `%h`, rutas entre comillas, varios archivos y archivos opcionales con `-`).
- Las comprobaciones de desviación resuelven los SecretRefs de `gateway.auth.token` usando el entorno de runtime combinado (primero el entorno del comando del servicio y luego el entorno del proceso como alternativa).
- Si la autenticación por token no está activa de forma efectiva (`gateway.auth.mode` explícito de `password`/`none`/`trusted-proxy`, o modo no definido donde la contraseña puede ganar y ningún candidato de token puede ganar), las comprobaciones de desviación de token omiten la resolución del token de configuración.
<Accordion title="Comprobaciones de desviación de autenticación de Linux systemd">
- En instalaciones Linux systemd, las comprobaciones de desviación de autenticación del servicio leen tanto valores `Environment=` como `EnvironmentFile=` de la unidad (incluidos `%h`, rutas entrecomilladas, múltiples archivos y archivos opcionales `-`).
- Las comprobaciones de desviación resuelven SecretRefs de `gateway.auth.token` usando el entorno de runtime fusionado (primero el entorno del comando de servicio, luego el entorno del proceso como alternativa).
- Si la autenticación por token no está efectivamente activa (`gateway.auth.mode` explícito de `password`/`none`/`trusted-proxy`, o modo sin definir donde la contraseña puede ganar y ningún candidato de token puede ganar), las comprobaciones de desviación de token omiten la resolución del token de configuración.
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` es el comando para "depurarlo todo". Siempre sondea:
`gateway probe` es el comando para "depurar todo". Siempre sondea:
- tu gateway remoto configurado (si está definido), y
- localhost (loopback) **incluso si el remoto está configurado**.
- tu Gateway remoto configurado (si está definido), y
- localhost (loopback) **aunque el remoto esté configurado**.
Si pasas `--url`, ese destino explícito se añade antes de ambos. La salida para humanos etiqueta los destinos como:
Si pasas `--url`, ese objetivo explícito se añade antes de ambos. La salida legible etiqueta los objetivos como:
- `URL (explicit)`
- `Remote (configured)` o `Remote (configured, inactive)`
- `Local loopback`
<Note>
Si se puede acceder a varios gateways, los imprime todos. Se admiten varios gateways cuando usas perfiles/puertos aislados (por ejemplo, un bot de rescate), pero la mayoría de las instalaciones siguen ejecutando un único gateway.
Si varios Gateways son accesibles, los imprime todos. Se admiten varios Gateways cuando usas perfiles/puertos aislados (por ejemplo, un bot de rescate), pero la mayoría de las instalaciones siguen ejecutando un único Gateway.
</Note>
```bash
@ -326,52 +336,52 @@ openclaw gateway probe --json
```
<AccordionGroup>
<Accordion title="Interpretation">
- `Reachable: yes` significa que al menos un destino aceptó una conexión WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` informa lo que la sonda pudo comprobar sobre la autenticación. Es independiente de la accesibilidad.
<Accordion title="Interpretación">
- `Reachable: yes` significa que al menos un objetivo aceptó una conexión WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` informa lo que el sondeo pudo demostrar sobre la autenticación. Es independiente de la accesibilidad.
- `Read probe: ok` significa que las llamadas RPC de detalle con alcance de lectura (`health`/`status`/`system-presence`/`config.get`) también se completaron correctamente.
- `Read probe: limited - missing scope: operator.read` significa que la conexión se completó correctamente, pero el RPC con alcance de lectura está limitado. Esto se informa como accesibilidad **degradada**, no como fallo completo.
- `Read probe: failed` después de `Connect: ok` significa que el Gateway aceptó la conexión WebSocket, pero los diagnósticos de lectura posteriores agotaron el tiempo o fallaron. Esto también es accesibilidad **degradada**, no un Gateway inaccesible.
- Como `gateway status`, la sonda reutiliza la autenticación de dispositivo almacenada en caché existente, pero no crea una identidad de dispositivo por primera vez ni estado de emparejamiento.
- El código de salida solo es distinto de cero cuando no se puede acceder a ningún destino sondeado.
- `Read probe: limited - missing scope: operator.read` significa que la conexión se completó correctamente pero el RPC con alcance de lectura está limitado. Esto se informa como accesibilidad **degradada**, no como fallo completo.
- `Read probe: failed` después de `Connect: ok` significa que el Gateway aceptó la conexión WebSocket, pero los diagnósticos de lectura posteriores agotaron el tiempo de espera o fallaron. Esto también es accesibilidad **degradada**, no un Gateway inaccesible.
- Igual que `gateway status`, el sondeo reutiliza la autenticación de dispositivo en caché existente, pero no crea identidad de dispositivo por primera vez ni estado de emparejamiento.
- El código de salida es distinto de cero solo cuando ningún objetivo sondeado es accesible.
</Accordion>
<Accordion title="JSON output">
<Accordion title="Salida JSON">
Nivel superior:
- `ok`: se puede acceder a al menos un destino.
- `degraded`: al menos un destino aceptó una conexión pero no completó todos los diagnósticos RPC de detalle.
- `capability`: mejor capacidad observada entre los destinos accesibles (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` o `unknown`).
- `primaryTargetId`: mejor destino para tratar como ganador activo en este orden: URL explícita, túnel SSH, remoto configurado y luego local loopback.
- `warnings[]`: registros de advertencia de mejor esfuerzo con `code`, `message` y `targetIds` opcional.
- `ok`: al menos un objetivo es accesible.
- `degraded`: al menos un objetivo aceptó una conexión pero no completó todos los diagnósticos RPC de detalle.
- `capability`: mejor capacidad vista entre objetivos accesibles (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` o `unknown`).
- `primaryTargetId`: mejor objetivo para tratar como ganador activo en este orden: URL explícita, túnel SSH, remoto configurado y luego local loopback.
- `warnings[]`: registros de advertencia de mejor esfuerzo con `code`, `message` y `targetIds` opcionales.
- `network`: sugerencias de URL de local loopback/tailnet derivadas de la configuración actual y la red del host.
- `discovery.timeoutMs` y `discovery.count`: el presupuesto de descubrimiento real/recuento de resultados usado para esta pasada de sondeo.
Por destino (`targets[].connect`):
Por objetivo (`targets[].connect`):
- `ok`: accesibilidad después de la conexión + clasificación degradada.
- `ok`: accesibilidad después de conexión + clasificación degradada.
- `rpcOk`: éxito completo de RPC de detalle.
- `scopeLimited`: el RPC de detalle falló por falta de alcance de operador.
- `scopeLimited`: RPC de detalle fallido por falta de alcance de operador.
Por destino (`targets[].auth`):
Por objetivo (`targets[].auth`):
- `role`: rol de autenticación informado en `hello-ok` cuando está disponible.
- `scopes`: alcances concedidos informados en `hello-ok` cuando están disponibles.
- `capability`: la clasificación de capacidad de autenticación expuesta para ese destino.
- `capability`: la clasificación de capacidad de autenticación expuesta para ese objetivo.
</Accordion>
<Accordion title="Common warning codes">
- `ssh_tunnel_failed`: falló la configuración del túnel SSH; el comando recurrió a sondas directas.
- `multiple_gateways`: se pudo acceder a más de un destino; esto es inusual salvo que ejecutes intencionalmente perfiles aislados, como un bot de rescate.
- `auth_secretref_unresolved`: no se pudo resolver un SecretRef de autenticación configurado para un destino fallido.
- `probe_scope_limited`: la conexión WebSocket se completó correctamente, pero la sonda de lectura quedó limitada por la falta de `operator.read`.
<Accordion title="Códigos de advertencia comunes">
- `ssh_tunnel_failed`: falló la configuración del túnel SSH; el comando volvió a sondeos directos.
- `multiple_gateways`: más de un objetivo fue accesible; esto es inusual salvo que ejecutes intencionalmente perfiles aislados, como un bot de rescate.
- `auth_secretref_unresolved`: no se pudo resolver un SecretRef de autenticación configurado para un objetivo fallido.
- `probe_scope_limited`: la conexión WebSocket se completó correctamente, pero el sondeo de lectura quedó limitado por la falta de `operator.read`.
</Accordion>
</AccordionGroup>
#### Remoto por SSH (paridad con la app de Mac)
#### Remoto por SSH (paridad de la app de Mac)
El modo "Remote over SSH" de la app de macOS usa un reenvío de puerto local para que el gateway remoto (que puede estar enlazado solo a loopback) sea accesible en `ws://127.0.0.1:<port>`.
El modo "Remote over SSH" de la app macOS usa un reenvío de puerto local para que el Gateway remoto (que puede estar vinculado solo a loopback) sea accesible en `ws://127.0.0.1:<port>`.
Equivalente de la CLI:
@ -386,7 +396,7 @@ openclaw gateway probe --ssh user@gateway-host
Archivo de identidad.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
Elige el primer host de gateway descubierto como destino SSH desde el endpoint de descubrimiento resuelto (`local.` más el dominio de área amplia configurado, si existe). Las sugerencias solo TXT se ignoran.
Elige el primer host de Gateway descubierto como objetivo SSH desde el endpoint de descubrimiento resuelto (`local.` más el dominio de área amplia configurado, si existe). Se ignoran las sugerencias solo TXT.
</ParamField>
Configuración (opcional, usada como valores predeterminados):
@ -419,17 +429,17 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Presupuesto de tiempo de espera.
</ParamField>
<ParamField path="--expect-final" type="boolean">
Principalmente para RPCs de estilo agente que transmiten eventos intermedios antes de una carga útil final.
Principalmente para RPCs de estilo agente que emiten eventos intermedios antes de una carga útil final.
</ParamField>
<ParamField path="--json" type="boolean">
Salida JSON legible por máquinas.
Salida JSON legible por máquina.
</ParamField>
<Note>
`--params` debe ser JSON válido.
</Note>
## Gestionar el servicio Gateway
## Administrar el servicio Gateway
```bash
openclaw gateway install
@ -439,11 +449,11 @@ openclaw gateway restart
openclaw gateway uninstall
```
### Instalar con un wrapper
### Instalar con un contenedor
Usa `--wrapper` cuando el servicio gestionado deba iniciarse mediante otro ejecutable, por ejemplo una
capa de gestor de secretos o un ayudante de ejecución como otro usuario. El wrapper recibe los argumentos normales del Gateway y es
responsable de ejecutar finalmente `openclaw` o Node con esos argumentos.
Usa `--wrapper` cuando el servicio administrado deba iniciarse a través de otro ejecutable, por ejemplo una
capa de administrador de secretos o un ayudante para ejecutar como otro usuario. El contenedor recibe los argumentos normales del Gateway y es
responsable de finalmente ejecutar `openclaw` o Node con esos argumentos.
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -457,17 +467,16 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
También puedes definir el wrapper mediante el entorno. `gateway install` valida que la ruta sea
un archivo ejecutable, escribe el wrapper en `ProgramArguments` del servicio y conserva
`OPENCLAW_WRAPPER` en el entorno del servicio para reinstalaciones forzadas, actualizaciones y reparaciones de doctor
posteriores.
También puedes definir el contenedor mediante el entorno. `gateway install` valida que la ruta sea
un archivo ejecutable, escribe el contenedor en `ProgramArguments` del servicio y conserva
`OPENCLAW_WRAPPER` en el entorno del servicio para reinstalaciones forzadas, actualizaciones y reparaciones de doctor posteriores.
```bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
```
Para eliminar un wrapper persistido, borra `OPENCLAW_WRAPPER` al reinstalar:
Para eliminar un contenedor persistido, borra `OPENCLAW_WRAPPER` al reinstalar:
```bash
OPENCLAW_WRAPPER= openclaw gateway install --force
@ -475,45 +484,45 @@ openclaw gateway restart
```
<AccordionGroup>
<Accordion title="Command options">
<Accordion title="Opciones de comando">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--force`, `--wait <duration>`, `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="Lifecycle behavior">
- Usa `gateway restart` para reiniciar un servicio gestionado. No encadenes `gateway stop` y `gateway start` como sustituto de reinicio; en macOS, `gateway stop` deshabilita intencionalmente el LaunchAgent antes de detenerlo.
- `gateway restart --wait 30s` reemplaza el presupuesto de drenaje de reinicio configurado para ese reinicio. Los números sin unidad son milisegundos; se aceptan unidades como `s`, `m` y `h`. `--wait 0` espera indefinidamente.
- `gateway restart --force` omite el drenaje de trabajo activo y reinicia inmediatamente. Úsalo cuando un operador ya haya inspeccionado los bloqueadores de tareas enumerados y quiera recuperar el gateway ahora.
<Accordion title="Comportamiento del ciclo de vida">
- Usa `gateway restart` para reiniciar un servicio administrado. No encadenes `gateway stop` y `gateway start` como sustituto de reinicio; en macOS, `gateway stop` deshabilita intencionalmente el LaunchAgent antes de detenerlo.
- `gateway restart --wait 30s` anula el presupuesto configurado de drenaje de reinicio para ese reinicio. Los números sin unidad son milisegundos; se aceptan unidades como `s`, `m` y `h`. `--wait 0` espera indefinidamente.
- `gateway restart --force` omite el drenaje de trabajo activo y reinicia de inmediato. Úsalo cuando un operador ya haya inspeccionado los bloqueadores de tareas enumerados y quiera recuperar el Gateway ahora.
- Los comandos de ciclo de vida aceptan `--json` para scripting.
</Accordion>
<Accordion title="Auth and SecretRefs at install time">
- Cuando la autenticación por token requiere un token y `gateway.auth.token` está gestionado por SecretRef, `gateway install` valida que el SecretRef se pueda resolver, pero no conserva el token resuelto en los metadatos del entorno del servicio.
- Si la autenticación por token requiere un token y el SecretRef de token configurado no se resuelve, la instalación falla de forma cerrada en lugar de conservar texto plano alternativo.
- Para autenticación por contraseña en `gateway run`, prefiere `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` o un `gateway.auth.password` respaldado por SecretRef en lugar de `--password` inline.
- En modo de autenticación inferido, `OPENCLAW_GATEWAY_PASSWORD` solo en shell no relaja los requisitos de token de instalación; usa configuración duradera (`gateway.auth.password` o `env` de configuración) al instalar un servicio gestionado.
- Si `gateway.auth.token` y `gateway.auth.password` están configurados y `gateway.auth.mode` no está definido, la instalación queda bloqueada hasta que el modo se defina explícitamente.
<Accordion title="Autenticación y SecretRefs en el momento de instalación">
- Cuando la autenticación por token requiere un token y `gateway.auth.token` está administrado por SecretRef, `gateway install` valida que el SecretRef se pueda resolver, pero no conserva el token resuelto en los metadatos del entorno del servicio.
- Si la autenticación por token requiere un token y el SecretRef de token configurado no se resuelve, la instalación falla de forma cerrada en lugar de persistir texto plano alternativo.
- Para autenticación por contraseña en `gateway run`, prefiere `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` o un `gateway.auth.password` respaldado por SecretRef en lugar de `--password` en línea.
- En modo de autenticación inferida, `OPENCLAW_GATEWAY_PASSWORD` solo de shell no relaja los requisitos de token de instalación; usa configuración duradera (`gateway.auth.password` o `env` de configuración) al instalar un servicio administrado.
- Si tanto `gateway.auth.token` como `gateway.auth.password` están configurados y `gateway.auth.mode` no está definido, la instalación se bloquea hasta que el modo se establezca explícitamente.
</Accordion>
</AccordionGroup>
## Descubrir gateways (Bonjour)
## Descubrir Gateways (Bonjour)
`gateway discover` escanea beacons del Gateway (`_openclaw-gw._tcp`).
`gateway discover` escanea balizas de Gateway (`_openclaw-gw._tcp`).
- DNS-SD multicast: `local.`
- DNS-SD unicast (Bonjour de área amplia): elige un dominio (ejemplo: `openclaw.internal.`) y configura DNS dividido + un servidor DNS; consulta [Bonjour](/es/gateway/bonjour).
Solo los gateways con descubrimiento Bonjour habilitado (predeterminado) anuncian el beacon.
Solo los Gateway con descubrimiento Bonjour habilitado (predeterminado) anuncian la baliza.
Los registros de descubrimiento de área amplia incluyen (TXT):
- `role` (sugerencia de rol de gateway)
- `transport` (sugerencia de transporte, por ejemplo `gateway`)
- `role` (sugerencia de rol del Gateway)
- `transport` (sugerencia de transporte, p. ej., `gateway`)
- `gatewayPort` (puerto WebSocket, normalmente `18789`)
- `sshPort` (opcional; los clientes usan por defecto destinos SSH en `22` cuando está ausente)
- `sshPort` (opcional; los clientes usan `22` como destino SSH predeterminado cuando está ausente)
- `tailnetDns` (nombre de host MagicDNS, cuando está disponible)
- `gatewayTls` / `gatewayTlsSha256` (TLS habilitado + huella digital del certificado)
- `cliPath` (sugerencia de instalación remota escrita en la zona de área amplia)
@ -525,10 +534,10 @@ openclaw gateway discover
```
<ParamField path="--timeout <ms>" type="number" default="2000">
Tiempo de espera por comando (exploración/resolución).
Tiempo de espera por comando (explorar/resolver).
</ParamField>
<ParamField path="--json" type="boolean">
Salida legible por máquina (también desactiva el estilo/spinner).
Salida legible por máquina (también deshabilita el estilo y el indicador de actividad).
</ParamField>
Ejemplos:
@ -539,13 +548,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- La CLI analiza `local.` además del dominio de área amplia configurado cuando hay uno habilitado.
- `wsUrl` en la salida JSON se deriva del extremo de servicio resuelto, no de indicaciones solo de TXT como `lanHost` o `tailnetDns`.
- En mDNS `local.`, `sshPort` y `cliPath` solo se anuncian cuando `discovery.mdns.mode` es `full`. DNS-SD de área amplia sigue escribiendo `cliPath`; `sshPort` también sigue siendo opcional allí.
- La CLI escanea `local.` más el dominio de área amplia configurado cuando hay uno habilitado.
- `wsUrl` en la salida JSON se deriva del endpoint de servicio resuelto, no de sugerencias solo TXT como `lanHost` o `tailnetDns`.
- En mDNS `local.`, `sshPort` y `cliPath` solo se transmiten cuando `discovery.mdns.mode` es `full`. DNS-SD de área amplia sigue escribiendo `cliPath`; `sshPort` también permanece opcional allí.
</Note>
## Relacionado
- [Referencia de la CLI](/es/cli)
- [Manual operativo de Gateway](/es/gateway)
- [Runbook del Gateway](/es/gateway)

127
docs/es/cli/models.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Desea cambiar los modelos predeterminados o ver el estado de autenticación del proveedor
- Quieres examinar los modelos/proveedores disponibles y depurar perfiles de autenticación
summary: Referencia de CLI para `openclaw models` (status/list/set/scan, alias, alternativas, autenticación)
- Quieres examinar los modelos/proveedores disponibles y depurar los perfiles de autenticación
summary: Referencia de CLI para `openclaw models` (status/list/set/scan, alias, alternativas de reserva, auth)
title: Modelos
x-i18n:
generated_at: "2026-05-01T05:30:12Z"
generated_at: "2026-05-04T18:23:53Z"
model: gpt-5.5
provider: openai
source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1
source_hash: dc7842f02e29aa0ac2ae88f3d42bba71f1890a58ab22d818dbee0585bc562fea
source_path: cli/models.md
workflow: 16
---
# `openclaw models`
Descubrimiento, escaneo y configuración de modelos (modelo predeterminado, alternativas, perfiles de autenticación).
Detección, escaneo y configuración de modelos (modelo predeterminado, alternativas y perfiles de autenticación).
Relacionado:
@ -32,21 +32,21 @@ openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` muestra el valor predeterminado/las alternativas resueltas junto con un resumen de autenticación.
`openclaw models status` muestra el valor predeterminado/las alternativas resueltos, además de un resumen de autenticación.
Cuando hay instantáneas de uso de proveedores disponibles, la sección de estado de OAuth/clave de API incluye
ventanas de uso del proveedor e instantáneas de cuota.
Proveedores actuales de ventanas de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Proveedores actuales con ventanas de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi y z.ai. La autenticación de uso proviene de hooks específicos del proveedor
cuando están disponibles; de lo contrario, OpenClaw recurre a credenciales OAuth/clave de API coincidentes
de perfiles de autenticación, el entorno o la configuración.
En la salida `--json`, `auth.providers` es el resumen de proveedores consciente de entorno/configuración/almacén,
mientras que `auth.oauth` es solo la salud de los perfiles del almacén de autenticación.
Agrega `--probe` para ejecutar sondeos de autenticación en vivo contra cada perfil de proveedor configurado.
Los sondeos son solicitudes reales (pueden consumir tokens y activar límites de tasa).
cuando están disponibles; de lo contrario, OpenClaw recurre a credenciales
OAuth/clave de API coincidentes desde perfiles de autenticación, env o configuración.
En la salida `--json`, `auth.providers` es el resumen de proveedores que tiene en cuenta
env/config/almacén, mientras que `auth.oauth` es solo el estado de salud del perfil del almacén de autenticación.
Agrega `--probe` para ejecutar pruebas de autenticación en vivo contra cada perfil de proveedor configurado.
Las pruebas son solicitudes reales (pueden consumir tokens y activar límites de frecuencia).
Usa `--agent <id>` para inspeccionar el estado de modelo/autenticación de un agente configurado. Cuando se omite,
el comando usa `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` si están definidos; de lo contrario, usa el
agente predeterminado configurado.
Las filas de sondeo pueden provenir de perfiles de autenticación, credenciales de entorno o `models.json`.
Las filas de prueba pueden provenir de perfiles de autenticación, credenciales de env o `models.json`.
Notas:
@ -54,51 +54,51 @@ Notas:
- `models list` es de solo lectura: lee la configuración, los perfiles de autenticación, el estado existente del catálogo
y las filas de catálogo propiedad del proveedor, pero no reescribe
`models.json`.
- La columna `Auth` es de nivel de proveedor y de solo lectura. Se calcula a partir de metadatos locales
de perfiles de autenticación, marcadores de entorno, claves de proveedor configuradas, marcadores de proveedor local,
marcadores de entorno/perfil de AWS Bedrock y metadatos de autenticación sintética de plugins;
no carga el runtime del proveedor, no lee secretos del llavero, no llama a APIs del proveedor
ni prueba la preparación exacta de ejecución por modelo.
- `models list --all --provider <id>` puede incluir filas estáticas de catálogo propiedad del proveedor
desde manifiestos de Plugin o metadatos de catálogo de proveedores incluidos, incluso cuando todavía
no te has autenticado con ese proveedor. Esas filas siguen mostrándose como
no disponibles hasta que se configure la autenticación coincidente.
- `models list` mantiene el plano de control responsivo mientras el descubrimiento de catálogos del proveedor
es lento. Las vistas predeterminada y configurada recurren a filas de modelo configuradas o
sintéticas después de una espera breve y dejan que el descubrimiento termine en segundo plano.
Usa `--all` cuando necesites el catálogo descubierto completo y exacto y
estés dispuesto a esperar al descubrimiento del proveedor.
- Un `models list --all` amplio fusiona filas de catálogo del manifiesto sobre filas del registro
- La columna `Auth` está a nivel de proveedor y es de solo lectura. Se calcula a partir de metadatos
de perfiles de autenticación locales, marcadores de env, claves de proveedor configuradas, marcadores
de proveedores locales, marcadores de env/perfil de AWS Bedrock y metadatos de autenticación sintética de Plugin;
no carga el runtime del proveedor, no lee secretos del llavero, no llama a las API del proveedor
ni demuestra la preparación exacta de ejecución por modelo.
- `models list --all --provider <id>` puede incluir filas de catálogo estático propiedad del proveedor
desde manifiestos de Plugin o metadatos de catálogo de proveedores incluidos, incluso cuando
aún no te has autenticado con ese proveedor. Esas filas siguen apareciendo como
no disponibles hasta que se configura la autenticación correspondiente.
- `models list` mantiene el plano de control con capacidad de respuesta mientras la detección del catálogo del proveedor
es lenta. Las vistas predeterminada y configurada recurren a filas de modelos configuradas o
sintéticas tras una breve espera y dejan que la detección termine en
segundo plano. Usa `--all` cuando necesites el catálogo descubierto completo y exacto
y estés dispuesto a esperar la detección del proveedor.
- El `models list --all` amplio fusiona filas de catálogo de manifiesto sobre filas de registro
sin cargar hooks suplementarios del runtime del proveedor. Las rutas rápidas de manifiesto filtradas por proveedor
usan solo proveedores marcados como `static`; los proveedores marcados como `refreshable`
se mantienen respaldados por registro/caché y agregan filas de manifiesto como suplementos, mientras
que los proveedores marcados como `runtime` se mantienen en descubrimiento de registro/runtime.
- `models list` mantiene distintos los metadatos nativos del modelo y los límites del runtime. En la salida de tabla,
permanecen respaldados por registro/caché y agregan filas de manifiesto como suplementos, mientras que
los proveedores marcados como `runtime` permanecen en detección de registro/runtime.
- `models list` mantiene separados los metadatos nativos del modelo y los límites del runtime. En la salida de tabla,
`Ctx` muestra `contextTokens/contextWindow` cuando un límite efectivo del runtime
difiere de la ventana de contexto nativa; las filas JSON incluyen `contextTokens`
cuando un proveedor expone ese límite.
- `models list --provider <id>` filtra por id de proveedor, como `moonshot` u
`openai-codex`. No acepta etiquetas de visualización de selectores interactivos de proveedor,
`openai-codex`. No acepta etiquetas visibles de selectores interactivos de proveedores,
como `Moonshot AI`.
- Las referencias de modelo se analizan dividiendo por el **primer** `/`. Si el ID del modelo incluye `/` (estilo OpenRouter), incluye el prefijo del proveedor (ejemplo: `openrouter/moonshotai/kimi-k2`).
- Si omites el proveedor, OpenClaw resuelve la entrada primero como un alias, luego
como una coincidencia única de proveedor configurado para ese id de modelo exacto, y solo entonces
recurre al proveedor predeterminado configurado con una advertencia de obsolescencia.
Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw
recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado
obsoleto de un proveedor eliminado.
recurre al primer proveedor/modelo configurado en lugar de mostrar un
valor predeterminado obsoleto de un proveedor eliminado.
- `models status` puede mostrar `marker(<value>)` en la salida de autenticación para marcadores de posición no secretos (por ejemplo `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) en lugar de enmascararlos como secretos.
### Escaneo de modelos
`models scan` lee el catálogo público `:free` de OpenRouter y clasifica candidatos para
uso como alternativas. El catálogo en sí es público, así que los escaneos solo de metadatos no necesitan
uso como alternativa. El catálogo en sí es público, por lo que los escaneos solo de metadatos no necesitan
una clave de OpenRouter.
De forma predeterminada, OpenClaw intenta sondear el soporte de herramientas e imágenes con llamadas a modelos en vivo.
De forma predeterminada, OpenClaw intenta probar la compatibilidad con herramientas e imágenes mediante llamadas a modelos en vivo.
Si no hay una clave de OpenRouter configurada, el comando recurre a una salida solo de metadatos
y explica que los modelos `:free` aún requieren `OPENROUTER_API_KEY` para
sondeos e inferencia.
pruebas e inferencia.
Opciones:
@ -107,7 +107,7 @@ Opciones:
- `--max-age-days <days>`
- `--provider <name>`
- `--max-candidates <n>`
- `--timeout <ms>` (tiempo de espera de solicitud de catálogo y por sondeo)
- `--timeout <ms>` (solicitud de catálogo y timeout por prueba)
- `--concurrency <n>`
- `--yes`
- `--no-input`
@ -115,7 +115,7 @@ Opciones:
- `--set-image`
- `--json`
`--set-default` y `--set-image` requieren sondeos en vivo; los resultados de escaneo
`--set-default` y `--set-image` requieren pruebas en vivo; los resultados de escaneo
solo de metadatos son informativos y no se aplican a la configuración.
### Estado de modelos
@ -125,8 +125,8 @@ Opciones:
- `--json`
- `--plain`
- `--check` (salida 1=expirado/faltante, 2=por expirar)
- `--probe` (sondeo en vivo de perfiles de autenticación configurados)
- `--probe-provider <name>` (sondear un proveedor)
- `--probe` (prueba en vivo de perfiles de autenticación configurados)
- `--probe-provider <name>` (probar un proveedor)
- `--probe-profile <id>` (ids de perfil repetidos o separados por comas)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
@ -134,10 +134,10 @@ Opciones:
- `--agent <id>` (id de agente configurado; anula `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
`--json` mantiene stdout reservado para la carga JSON. Los diagnósticos de perfil de autenticación, proveedor
e inicio se enrutan a stderr para que los scripts puedan canalizar stdout directamente
e inicio se envían a stderr para que los scripts puedan canalizar stdout directamente
a herramientas como `jq`.
Grupos de estado de sondeo:
Categorías de estado de prueba:
- `ok`
- `auth`
@ -148,15 +148,15 @@ Grupos de estado de sondeo:
- `unknown`
- `no_model`
Casos esperados de detalle/código de motivo de sondeo:
Casos de detalle/código de motivo de prueba que puedes esperar:
- `excluded_by_auth_order`: existe un perfil almacenado, pero `auth.order.<provider>`
explícito lo omitió, así que el sondeo informa la exclusión en lugar de
- `excluded_by_auth_order`: existe un perfil almacenado, pero `auth.order.<provider>` explícito
lo omitió, por lo que la prueba informa la exclusión en lugar de
intentarlo.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
el perfil está presente, pero no es elegible/resoluble.
- `no_model`: existe autenticación del proveedor, pero OpenClaw no pudo resolver un candidato
de modelo sondeable para ese proveedor.
el perfil está presente pero no es elegible/resoluble.
- `no_model`: existe autenticación del proveedor, pero OpenClaw no pudo resolver un
candidato de modelo que se pueda probar para ese proveedor.
## Alias + alternativas
@ -169,42 +169,49 @@ openclaw models fallbacks list
```bash
openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add` es el asistente interactivo de autenticación. Puede iniciar un flujo de autenticación
del proveedor (OAuth/clave de API) o guiarte para pegar manualmente un token, según el
del proveedor (OAuth/clave de API) o guiarte al pegado manual de tokens, según el
proveedor que elijas.
`models auth list` enumera los perfiles de autenticación guardados para el agente seleccionado sin
imprimir tokens, claves de API ni material secreto de OAuth. Usa `--provider <id>` para
filtrar a un proveedor, como `openai-codex`, y `--json` para scripting.
`models auth login` ejecuta el flujo de autenticación de un Plugin de proveedor (OAuth/clave de API). Usa
`openclaw plugins list` para ver qué proveedores están instalados.
Usa `openclaw models auth --agent <id> <subcommand>` para escribir resultados de autenticación en un
almacén de agente configurado específico. La marca principal `--agent` es respetada por
`add`, `login`, `setup-token`, `paste-token` y `login-github-copilot`.
almacén de agente configurado específico. La bandera principal `--agent` es respetada por
`add`, `list`, `login`, `setup-token`, `paste-token` y
`login-github-copilot`.
Ejemplos:
```bash
openclaw models auth login --provider openai-codex --set-default
openclaw models auth list --provider openai-codex
```
Notas:
- `setup-token` y `paste-token` siguen siendo comandos genéricos de tokens para proveedores
que exponen métodos de autenticación con token.
- `setup-token` requiere una TTY interactiva y ejecuta el método de autenticación con token del proveedor
(usando de forma predeterminada el método `setup-token` de ese proveedor cuando expone
- `setup-token` y `paste-token` siguen siendo comandos genéricos de token para proveedores
que exponen métodos de autenticación por token.
- `setup-token` requiere un TTY interactivo y ejecuta el método de autenticación por token del proveedor
(de forma predeterminada, el método `setup-token` de ese proveedor cuando expone
uno).
- `paste-token` acepta una cadena de token generada en otro lugar o desde automatización.
- `paste-token` requiere `--provider`, solicita el valor del token y lo escribe
en el id de perfil predeterminado `<provider>:manual` salvo que pases
en el id de perfil predeterminado `<provider>:manual`, salvo que pases
`--profile-id`.
- `paste-token --expires-in <duration>` almacena una expiración absoluta del token a partir de una
duración relativa como `365d` o `12h`.
- Nota sobre Anthropic: el personal de Anthropic nos dijo que el uso de Claude CLI al estilo de OpenClaw vuelve a estar permitido, así que OpenClaw trata la reutilización de Claude CLI y el uso de `claude -p` como autorizados para esta integración salvo que Anthropic publique una nueva política.
- Anthropic `setup-token` / `paste-token` siguen disponibles como una ruta de token compatible de OpenClaw, pero OpenClaw ahora prefiere reutilizar Claude CLI y `claude -p` cuando están disponibles.
- Nota de Anthropic: el personal de Anthropic nos dijo que el uso de Claude CLI al estilo OpenClaw vuelve a estar permitido, por lo que OpenClaw trata la reutilización de Claude CLI y el uso de `claude -p` como sancionados para esta integración salvo que Anthropic publique una nueva política.
- Anthropic `setup-token` / `paste-token` siguen disponibles como una ruta de token de OpenClaw compatible, pero OpenClaw ahora prefiere reutilizar Claude CLI y `claude -p` cuando estén disponibles.
## Relacionado

57
docs/es/cli/proxy.md
View File

@ -1,36 +1,36 @@
---
read_when:
- Debe validar el enrutamiento del proxy gestionado por el operador antes del despliegue
- Debe capturar el tráfico de transporte de OpenClaw localmente para depuración
- Quieres inspeccionar sesiones de proxy de depuración, blobs o preajustes de consulta integrados
summary: Referencia de CLI para `openclaw proxy`, incluida la validación del proxy administrado por el operador y el inspector de captura del proxy de depuración local
title: Proxy
- Debe validar el enrutamiento de proxy gestionado por el operador antes de la implementación
- Debes capturar localmente el tráfico de transporte de OpenClaw para depuración
- Quieres inspeccionar sesiones del proxy de depuración, blobs o preajustes de consulta integrados
summary: Referencia de CLI para `openclaw proxy`, incluida la validación del proxy gestionado por el operador y el inspector local de capturas del proxy de depuración
title: Servidor proxy
x-i18n:
generated_at: "2026-05-04T05:27:49Z"
generated_at: "2026-05-04T18:23:57Z"
model: gpt-5.5
provider: openai
source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
source_hash: 092c4e946dcab5e78e37d6fc77bb067b7a649368f8571fa127e462a85fa14ce5
source_path: cli/proxy.md
workflow: 16
---
# `openclaw proxy`
Valida el enrutamiento de proxy administrado por el operador, o ejecuta el proxy
explícito de depuración local e inspecciona el tráfico capturado.
Valida el enrutamiento de proxy gestionado por el operador, o ejecuta el proxy de depuración explícito local
e inspecciona el tráfico capturado.
Usa `validate` para comprobar de antemano un proxy de reenvío administrado por el operador antes de habilitar
el enrutamiento de proxy de OpenClaw. Los demás comandos son herramientas de depuración para la
investigación a nivel de transporte: pueden iniciar un proxy local, ejecutar un comando secundario
con la captura habilitada, listar sesiones de captura, consultar patrones de tráfico comunes, leer
blobs capturados y purgar datos de captura locales.
Usa `validate` para comprobar previamente un proxy de reenvío gestionado por el operador antes de habilitar
el enrutamiento de proxy de OpenClaw. Los demás comandos son herramientas de depuración para
la investigación a nivel de transporte: pueden iniciar un proxy local, ejecutar un comando hijo
con captura habilitada, listar sesiones de captura, consultar patrones de tráfico comunes, leer
blobs capturados y purgar datos locales de captura.
## Comandos
```bash
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--timeout-ms <ms>]
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
openclaw proxy coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
@ -40,14 +40,17 @@ openclaw proxy purge
## Validar
`openclaw proxy validate` comprueba la URL efectiva del proxy administrado por el operador desde
`openclaw proxy validate` comprueba la URL efectiva del proxy gestionado por el operador desde
`--proxy-url`, la configuración o `OPENCLAW_PROXY_URL`. Informa de un problema de configuración cuando
no hay ningún proxy habilitado y configurado; usa `--proxy-url` para una comprobación puntual
antes de cambiar la configuración. De forma predeterminada, verifica que un destino público funcione
a través del proxy y que el proxy no pueda llegar a un canario temporal de loopback.
Los destinos denegados personalizados fallan en modo cerrado: las respuestas HTTP y los fallos
de transporte ambiguos fallan salvo que puedas verificar por separado una señal de denegación
específica de la implementación.
no hay ningún proxy habilitado y configurado; usa `--proxy-url` para una comprobación previa puntual
antes de cambiar la configuración. De forma predeterminada, verifica que un destino público funciona
a través del proxy y que el proxy no puede alcanzar un canary de loopback temporal.
Los destinos denegados personalizados fallan de forma cerrada: las respuestas HTTP y los fallos
de transporte ambiguos fallan a menos que puedas verificar por separado una señal de denegación
específica del despliegue. Añade `--apns-reachable` para abrir también un túnel CONNECT HTTP/2 de APNs
a través del proxy y confirmar que APNs sandbox responde; la prueba usa un token de proveedor
intencionadamente no válido, por lo que una respuesta de APNs `403 InvalidProviderToken`
es una señal correcta de alcanzabilidad.
Opciones:
@ -55,9 +58,11 @@ Opciones:
- `--proxy-url <url>`: valida esta URL de proxy en lugar de la configuración o el entorno.
- `--allowed-url <url>`: añade un destino que se espera que funcione a través del proxy. Repite para comprobar varios destinos.
- `--denied-url <url>`: añade un destino que se espera que el proxy bloquee. Repite para comprobar varios destinos.
- `--apns-reachable`: verifica también que APNs sandbox HTTP/2 sea alcanzable a través del proxy.
- `--apns-authority <url>`: autoridad de APNs que se probará con `--apns-reachable` (`https://api.sandbox.push.apple.com` de forma predeterminada; producción es `https://api.push.apple.com`).
- `--timeout-ms <ms>`: tiempo de espera por solicitud en milisegundos.
Consulta [Proxy de red](/es/security/network-proxy) para obtener orientación sobre la implementación y la semántica
Consulta [Proxy de red](/es/security/network-proxy) para obtener orientación de despliegue y semántica
de denegación.
## Preajustes de consulta
@ -73,11 +78,11 @@ de denegación.
## Notas
- `start` usa `127.0.0.1` de forma predeterminada salvo que se establezca `--host`.
- `start` usa `127.0.0.1` de forma predeterminada, salvo que se defina `--host`.
- `run` inicia un proxy de depuración local y luego ejecuta el comando después de `--`.
- El reenvío directo al origen del proxy de depuración abre sockets ascendentes para diagnósticos. Cuando el modo de proxy administrado de OpenClaw está activo, el reenvío directo para solicitudes de proxy y túneles CONNECT está deshabilitado de forma predeterminada; establece `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` solo para diagnósticos locales aprobados.
- El reenvío upstream directo del proxy de depuración abre sockets upstream para diagnóstico. Cuando el modo de proxy gestionado de OpenClaw está activo, el reenvío directo para solicitudes de proxy y túneles CONNECT está deshabilitado de forma predeterminada; define `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` solo para diagnósticos locales aprobados.
- `validate` sale con código 1 cuando fallan la configuración del proxy o las comprobaciones de destino.
- Las capturas son datos locales de depuración; usa `openclaw proxy purge` cuando termines.
- Las capturas son datos de depuración locales; usa `openclaw proxy purge` cuando termines.
## Relacionado

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

@ -1,33 +1,33 @@
---
read_when:
- Quieres una alternativa confiable cuando fallan los proveedores de API
- Estás ejecutando Codex CLI u otras CLI de IA locales y quieres reutilizarlas
- Quieres entender el puente de loopback MCP para el acceso a herramientas del backend de la CLI
summary: 'Backends de CLI: alternativa local de CLI de IA con puente opcional de herramientas MCP'
title: Backends de CLI
- Quieres una alternativa fiable cuando fallen los proveedores de API
- Estás ejecutando Codex CLI u otras CLI locales de IA y quieres reutilizarlas
- Quieres entender el puente de loopback de MCP para el acceso a herramientas del backend de la CLI
summary: 'Motores de CLI: alternativa de CLI de IA local con puente opcional de herramientas MCP'
title: Motores de la CLI
x-i18n:
generated_at: "2026-05-02T20:46:50Z"
generated_at: "2026-05-04T18:24:03Z"
model: gpt-5.5
provider: openai
source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16
source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1
source_path: gateway/cli-backends.md
workflow: 16
---
OpenClaw puede ejecutar **CLI de IA locales** como **respaldo solo de texto** cuando los proveedores de API están caídos,
limitados por tasa o se comportan mal temporalmente. Esto es intencionalmente conservador:
OpenClaw puede ejecutar **CLI locales de IA** como **fallback solo de texto** cuando los proveedores de API están caídos,
limitados por cuota o se comportan mal temporalmente. Esto es deliberadamente conservador:
- **Las herramientas de OpenClaw no se inyectan directamente**, pero los backends con `bundleMcp: true`
pueden recibir herramientas del Gateway mediante un puente MCP de loopback.
- **Streaming JSONL** para CLI que lo admiten.
- **Las sesiones son compatibles** (por lo que los turnos de seguimiento se mantienen coherentes).
- **Las imágenes pueden pasarse directamente** si la CLI acepta rutas de imagen.
- **Las sesiones son compatibles** (para que los turnos de seguimiento mantengan coherencia).
- **Las imágenes se pueden pasar** si la CLI acepta rutas de imagen.
Esto está diseñado como una **red de seguridad** en lugar de una ruta principal. Úsalo cuando
quieras respuestas de texto que “siempre funcionen” sin depender de API externas.
Esto está diseñado como una **red de seguridad** más que como una ruta principal. Úsalo cuando quieras
respuestas de texto que “siempre funcionan” sin depender de API externas.
Si quieres un runtime de arnés completo con controles de sesión ACP, tareas en segundo plano,
vinculación de hilos/conversaciones y sesiones persistentes externas de programación, usa
vinculación de hilo/conversación y sesiones persistentes externas de programación, usa
[Agentes ACP](/es/tools/acp-agents) en su lugar. Los backends de CLI no son ACP.
## Inicio rápido para principiantes
@ -39,7 +39,7 @@ registra un backend predeterminado):
openclaw agent --message "hi" --model codex-cli/gpt-5.5
```
Si tu gateway se ejecuta bajo launchd/systemd y PATH es mínimo, añade solo la
Si tu Gateway se ejecuta bajo launchd/systemd y PATH es mínimo, agrega solo la
ruta del comando:
```json5
@ -59,13 +59,13 @@ ruta del comando:
Eso es todo. No se necesitan claves ni configuración de autenticación adicional más allá de la propia CLI.
Si usas un backend de CLI incluido como **proveedor principal de mensajes** en un
host de gateway, OpenClaw ahora carga automáticamente el Plugin incluido propietario cuando tu configuración
host de Gateway, OpenClaw ahora carga automáticamente el Plugin incluido propietario cuando tu configuración
hace referencia explícita a ese backend en una referencia de modelo o bajo
`agents.defaults.cliBackends`.
## Usarlo como respaldo
## Uso como fallback
Añade un backend de CLI a tu lista de respaldos para que solo se ejecute cuando fallen los modelos principales:
Agrega un backend de CLI a tu lista de fallbacks para que solo se ejecute cuando fallen los modelos principales:
```json5
{
@ -86,9 +86,9 @@ Añade un backend de CLI a tu lista de respaldos para que solo se ejecute cuando
Notas:
- Si usas `agents.defaults.models` (lista de permitidos), también debes incluir ahí tus modelos de backend de CLI.
- Si el proveedor principal falla (autenticación, límites de tasa, tiempos de espera), OpenClaw
probará después el backend de CLI.
- Si usas `agents.defaults.models` (lista permitida), también debes incluir ahí tus modelos de backend de CLI.
- Si el proveedor principal falla (autenticación, límites de cuota, tiempos de espera), OpenClaw intentará
después el backend de CLI.
## Resumen de configuración
@ -98,7 +98,7 @@ Todos los backends de CLI viven bajo:
agents.defaults.cliBackends
```
Cada entrada está indexada por un **id de proveedor** (por ejemplo, `codex-cli`, `my-cli`).
Cada entrada se identifica por un **id de proveedor** (por ejemplo, `codex-cli`, `my-cli`).
El id de proveedor se convierte en el lado izquierdo de tu referencia de modelo:
```
@ -148,42 +148,48 @@ El id de proveedor se convierte en el lado izquierdo de tu referencia de modelo:
## Cómo funciona
1. **Selecciona un backend** según el prefijo del proveedor (`codex-cli/...`).
2. **Construye un prompt de sistema** usando el mismo prompt de OpenClaw y el contexto del espacio de trabajo.
3. **Ejecuta la CLI** con un id de sesión (si es compatible) para que el historial se mantenga coherente.
2. **Construye un prompt de sistema** usando el mismo prompt de OpenClaw + contexto del espacio de trabajo.
3. **Ejecuta la CLI** con un id de sesión (si es compatible) para que el historial se mantenga consistente.
El backend `claude-cli` incluido mantiene vivo un proceso stdio de Claude por
sesión de OpenClaw y envía turnos de seguimiento mediante stdin stream-json.
4. **Analiza la salida** (JSON o texto sin formato) y devuelve el texto final.
5. **Persiste ids de sesión** por backend, de modo que los seguimientos reutilicen la misma sesión de CLI.
sesión de OpenClaw y envía los turnos de seguimiento por stdin stream-json.
4. **Analiza la salida** (JSON o texto plano) y devuelve el texto final.
5. **Persiste ids de sesión** por backend, para que los seguimientos reutilicen la misma sesión de CLI.
<Note>
El backend `claude-cli` de Anthropic incluido vuelve a ser compatible. El personal de Anthropic
nos dijo que el uso de Claude CLI al estilo de OpenClaw está permitido de nuevo, por lo que OpenClaw trata
el uso de `claude -p` como sancionado para esta integración salvo que Anthropic publique
una política nueva.
El backend Anthropic `claude-cli` incluido vuelve a estar admitido. Personal de Anthropic
nos dijo que el uso de Claude CLI al estilo OpenClaw vuelve a estar permitido, así que OpenClaw trata
el uso de `claude -p` como autorizado para esta integración salvo que Anthropic publique
una nueva política.
</Note>
El backend `codex-cli` de OpenAI incluido pasa el prompt de sistema de OpenClaw mediante
la anulación de configuración `model_instructions_file` de Codex (`-c
model_instructions_file="..."`). Codex no expone una marca
`--append-system-prompt` al estilo de Claude, por lo que OpenClaw escribe el prompt ensamblado en un
El backend OpenAI `codex-cli` incluido pasa el prompt de sistema de OpenClaw mediante
la sobrescritura de configuración `model_instructions_file` de Codex (`-c
model_instructions_file="..."`). Codex no expone una bandera al estilo Claude
`--append-system-prompt`, así que OpenClaw escribe el prompt ensamblado en un
archivo temporal para cada sesión nueva de Codex CLI.
El backend `claude-cli` de Anthropic incluido recibe la instantánea de Skills de OpenClaw
de dos maneras: el catálogo compacto de Skills de OpenClaw en el prompt de sistema anexado, y
El backend Anthropic `claude-cli` incluido recibe la instantánea de Skills de OpenClaw
de dos maneras: el catálogo compacto de Skills de OpenClaw en el prompt de sistema agregado, y
un Plugin temporal de Claude Code pasado con `--plugin-dir`. El Plugin contiene
solo las Skills elegibles para ese agente/sesión, por lo que el resolvedor nativo de Skills
de Claude Code ve el mismo conjunto filtrado que OpenClaw anunciaría de otro modo en
el prompt. OpenClaw sigue aplicando las anulaciones de entorno/clave de API de Skills al
solo las Skills elegibles para ese agente/sesión, así que el resolvedor nativo de Skills de Claude Code
ve el mismo conjunto filtrado que OpenClaw anunciaría de otro modo en
el prompt. Las sobrescrituras de entorno/API key de Skills siguen siendo aplicadas por OpenClaw al
entorno del proceso hijo para la ejecución.
Claude CLI también tiene su propio modo de permisos no interactivo. OpenClaw lo asigna
a la política de exec existente en lugar de añadir configuración específica de Claude: cuando la
Claude CLI también tiene su propio modo de permisos no interactivo. OpenClaw asigna eso
a la política de exec existente en lugar de agregar configuración específica de Claude: cuando la
política efectiva de exec solicitada es YOLO (`tools.exec.security: "full"` y
`tools.exec.ask: "off"`), OpenClaw añade `--permission-mode bypassPermissions`.
La configuración por agente `agents.list[].tools.exec` anula `tools.exec` global para
ese agente. Para forzar un modo de Claude distinto, configura argumentos backend sin procesar explícitos
`tools.exec.ask: "off"`), OpenClaw agrega `--permission-mode bypassPermissions`.
La configuración por agente `agents.list[].tools.exec` sobrescribe `tools.exec` global para
ese agente. Para forzar un modo de Claude distinto, define argumentos raw explícitos del backend
como `--permission-mode default` o `--permission-mode acceptEdits` bajo
`agents.defaults.cliBackends.claude-cli.args` y los `resumeArgs` correspondientes.
`agents.defaults.cliBackends.claude-cli.args` y `resumeArgs` coincidente.
El backend Anthropic `claude-cli` incluido también asigna los niveles `/think` de OpenClaw
a la bandera nativa `--effort` de Claude Code para niveles que no estén desactivados. `minimal` y
`low` se asignan a `low`, `adaptive` y `medium` se asignan a `medium`, y `high`,
`xhigh` y `max` se asignan directamente. Otros backends de CLI necesitan que su Plugin propietario
declare un mapeador argv equivalente antes de que `/think` pueda afectar la CLI generada.
Antes de que OpenClaw pueda usar el backend `claude-cli` incluido, Claude Code
ya debe haber iniciado sesión en el mismo host:
@ -195,96 +201,96 @@ openclaw models auth login --provider anthropic --method cli --set-default
```
Usa `agents.defaults.cliBackends.claude-cli.command` solo cuando el binario `claude`
no esté ya en `PATH`.
aún no esté en `PATH`.
## Sesiones
- Si la CLI admite sesiones, configura `sessionArg` (por ejemplo, `--session-id`) o
`sessionArgs` (marcador `{sessionId}`) cuando el ID deba insertarse
en varias marcas.
- Si la CLI usa un **subcomando de reanudación** con marcas distintas, configura
`resumeArgs` (reemplaza `args` al reanudar) y, opcionalmente, `resumeOutput`
(para reanudaciones que no sean JSON).
- Si la CLI admite sesiones, define `sessionArg` (por ejemplo, `--session-id`) o
`sessionArgs` (placeholder `{sessionId}`) cuando el ID deba insertarse
en varias banderas.
- Si la CLI usa un **subcomando de reanudación** con banderas diferentes, define
`resumeArgs` (reemplaza `args` al reanudar) y opcionalmente `resumeOutput`
(para reanudaciones que no son JSON).
- `sessionMode`:
- `always`: siempre envía un id de sesión (UUID nuevo si no hay ninguno almacenado).
- `existing`: solo envía un id de sesión si ya había uno almacenado.
- `none`: nunca envía un id de sesión.
- `claude-cli` tiene como valores predeterminados `liveSession: "claude-stdio"`, `output: "jsonl"`,
- `always`: enviar siempre un id de sesión (UUID nuevo si no hay ninguno almacenado).
- `existing`: enviar un id de sesión solo si ya se almacenó uno antes.
- `none`: no enviar nunca un id de sesión.
- `claude-cli` usa de forma predeterminada `liveSession: "claude-stdio"`, `output: "jsonl"`,
e `input: "stdin"` para que los turnos de seguimiento reutilicen el proceso vivo de Claude mientras
esté activo. Stdio caliente es ahora el valor predeterminado, incluso para configuraciones personalizadas
esté activo. Stdio en caliente es ahora el valor predeterminado, incluso para configuraciones personalizadas
que omiten campos de transporte. Si el Gateway se reinicia o el proceso inactivo
sale, OpenClaw reanuda desde el id de sesión almacenado de Claude. Los ids de sesión
sale, OpenClaw reanuda desde el id de sesión de Claude almacenado. Los ids de sesión
almacenados se verifican contra una transcripción de proyecto existente y legible antes de
reanudar, por lo que las vinculaciones fantasma se limpian con `reason=transcript-missing`
reanudar, así que las vinculaciones fantasma se limpian con `reason=transcript-missing`
en lugar de iniciar silenciosamente una sesión nueva de Claude CLI bajo `--resume`.
- Las sesiones vivas de Claude mantienen protecciones acotadas de salida JSONL. Los valores predeterminados permiten hasta
8 MiB y 20.000 líneas JSONL sin procesar por turno. Los turnos de Claude con muchas herramientas pueden elevar
esos límites por backend con
8 MiB y 20.000 líneas JSONL raw por turno. Los turnos de Claude con muchas herramientas pueden aumentarlos
por backend con
`agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars`
y `maxTurnLines`; OpenClaw limita esos ajustes a 64 MiB y 100.000
líneas.
- Las sesiones de CLI almacenadas son continuidad propiedad del proveedor. El reinicio diario
implícito de sesión no las corta; `/reset` y las políticas explícitas `session.reset` todavía
- Las sesiones de CLI almacenadas son continuidad propiedad del proveedor. El reinicio diario implícito de sesión
no las corta; `/reset` y las políticas explícitas `session.reset` todavía
lo hacen.
Notas de serialización:
- `serialize: true` mantiene ordenadas las ejecuciones del mismo carril.
- La mayoría de las CLI serializan en un carril de proveedor.
- OpenClaw deja de reutilizar la sesión de CLI almacenada cuando cambia la identidad de autenticación seleccionada,
incluido un cambio de id de perfil de autenticación, clave de API estática, token estático o identidad
de cuenta OAuth cuando la CLI expone una. La rotación de tokens de acceso y actualización
OAuth no corta la sesión de CLI almacenada. Si una CLI no expone un
id estable de cuenta OAuth, OpenClaw deja que esa CLI aplique los permisos de reanudación.
- OpenClaw descarta la reutilización de sesiones de CLI almacenadas cuando cambia la identidad de autenticación seleccionada,
incluido un id de perfil de autenticación cambiado, API key estática, token estático o identidad de
cuenta OAuth cuando la CLI expone una. La rotación de tokens OAuth de acceso y actualización
no corta la sesión de CLI almacenada. Si una CLI no expone un id estable de cuenta
OAuth, OpenClaw deja que esa CLI haga cumplir los permisos de reanudación.
## Preludio de respaldo desde sesiones claude-cli
## Preludio de fallback desde sesiones claude-cli
Cuando un intento de `claude-cli` falla y pasa a un candidato que no es CLI en
Cuando un intento de `claude-cli` conmuta por error a un candidato que no es CLI en
[`agents.defaults.model.fallbacks`](/es/concepts/model-failover), OpenClaw siembra
el siguiente intento con un preludio de contexto cosechado de la transcripción JSONL local
de Claude Code en `~/.claude/projects/`. Sin esta semilla, el proveedor de respaldo
empezaría en frío porque la propia transcripción de sesión de OpenClaw está vacía
para las ejecuciones de `claude-cli`.
el siguiente intento con un preludio de contexto obtenido de la transcripción JSONL local de Claude Code
en `~/.claude/projects/`. Sin esta semilla, el proveedor de fallback
comenzaría en frío porque la propia transcripción de sesión de OpenClaw está vacía
para ejecuciones de `claude-cli`.
- El preludio prefiere el resumen `/compact` más reciente o el marcador `compact_boundary`,
y luego anexa los turnos posteriores al límite más recientes hasta un presupuesto de caracteres.
- El preludio prefiere el último resumen `/compact` o marcador `compact_boundary`,
luego agrega los turnos posteriores al límite más recientes hasta un presupuesto de caracteres.
Los turnos previos al límite se descartan porque el resumen ya los representa.
- Los bloques de herramientas se fusionan en pistas compactas `(tool call: name)` y
- Los bloques de herramientas se combinan en pistas compactas `(tool call: name)` y
`(tool result: …)` para mantener honesto el presupuesto del prompt. El resumen se
etiqueta como `(truncated)` si se desborda.
- Los respaldos de `claude-cli` a `claude-cli` del mismo proveedor se basan en el propio
- Los fallbacks de mismo proveedor de `claude-cli` a `claude-cli` dependen del propio
`--resume` de Claude y omiten el preludio.
- La semilla reutiliza la validación existente de rutas de archivos de sesión de Claude, por lo que
- La semilla reutiliza la validación existente de la ruta del archivo de sesión de Claude, así que
no se pueden leer rutas arbitrarias.
## Imágenes (paso directo)
Si tu CLI acepta rutas de imagen, configura `imageArg`:
Si tu CLI acepta rutas de imagen, define `imageArg`:
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw escribirá imágenes base64 en archivos temporales. Si `imageArg` está configurado, esas
rutas se pasan como argumentos de CLI. Si falta `imageArg`, OpenClaw anexa las
rutas de archivo al prompt (inyección de ruta), lo que basta para CLI que cargan automáticamente
archivos locales desde rutas en texto sin formato.
OpenClaw escribirá imágenes base64 en archivos temporales. Si `imageArg` está definido, esas
rutas se pasan como argumentos de CLI. Si falta `imageArg`, OpenClaw agrega las
rutas de archivo al prompt (inyección de ruta), lo cual basta para CLI que cargan automáticamente
archivos locales desde rutas en texto plano.
## Entradas / salidas
- `output: "json"` (predeterminado) intenta analizar JSON y extraer texto + id de sesión.
- Para la salida JSON de Gemini CLI, OpenClaw lee el texto de respuesta desde `response` y
- Para salida JSON de Gemini CLI, OpenClaw lee el texto de respuesta desde `response` y
el uso desde `stats` cuando `usage` falta o está vacío.
- `output: "jsonl"` analiza streams JSONL (por ejemplo, Codex CLI `--json`) y extrae el mensaje final del agente más identificadores
de sesión cuando están presentes.
- `output: "jsonl"` analiza streams JSONL (por ejemplo, Codex CLI `--json`) y extrae el mensaje final del agente más identificadores de sesión
cuando están presentes.
- `output: "text"` trata stdout como la respuesta final.
Modos de entrada:
- `input: "arg"` (predeterminado) pasa el prompt como el último argumento de CLI.
- `input: "stdin"` envía el prompt mediante stdin.
- Si el prompt es muy largo y `maxPromptArgChars` está configurado, se usa stdin.
- `input: "stdin"` envía el prompt por stdin.
- Si el prompt es muy largo y `maxPromptArgChars` está definido, se usa stdin.
## Valores predeterminados (propiedad del Plugin)
@ -314,27 +320,27 @@ Requisito previo: la Gemini CLI local debe estar instalada y disponible como
`gemini` en `PATH` (`brew install gemini-cli` o
`npm install -g @google/gemini-cli`).
Notas de JSON de Gemini CLI:
Notas JSON de Gemini CLI:
- El texto de respuesta se lee desde el campo JSON `response`.
- El uso recurre a `stats` cuando `usage` no existe o está vacío.
- El texto de respuesta se lee del campo JSON `response`.
- El uso recurre a `stats` cuando `usage` está ausente o vacío.
- `stats.cached` se normaliza como `cacheRead` de OpenClaw.
- Si falta `stats.input`, OpenClaw deriva los tokens de entrada de
`stats.input_tokens - stats.cached`.
Anula solo si es necesario (común: ruta absoluta de `command`).
Sobrescribe solo si es necesario (común: ruta absoluta de `command`).
## Valores predeterminados propiedad del Plugin
Los valores predeterminados de backend de CLI ahora forman parte de la superficie del Plugin:
Los valores predeterminados del backend de CLI ahora forman parte de la superficie del Plugin:
- Los plugins los registran con `api.registerCliBackend(...)`.
- Los Plugins los registran con `api.registerCliBackend(...)`.
- El `id` del backend se convierte en el prefijo del proveedor en las referencias de modelo.
- La configuración de usuario en `agents.defaults.cliBackends.<id>` sigue sobrescribiendo el valor predeterminado del plugin.
- La limpieza de configuración específica del backend sigue siendo propiedad del plugin mediante el hook opcional
- La configuración de usuario en `agents.defaults.cliBackends.<id>` todavía sobrescribe el valor predeterminado del Plugin.
- La limpieza de configuración específica del backend sigue siendo propiedad del Plugin mediante el hook opcional
`normalizeConfig`.
Los plugins que necesiten pequeños shims de compatibilidad de prompts/mensajes pueden declarar
Los Plugins que necesiten pequeños adaptadores de compatibilidad de prompts/mensajes pueden declarar
transformaciones de texto bidireccionales sin reemplazar un proveedor ni un backend de CLI:
```typescript
@ -352,11 +358,11 @@ api.registerTextTransforms({
});
```
`input` reescribe el prompt del sistema y el prompt del usuario pasados a la CLI. `output`
reescribe los deltas del asistente transmitidos y el texto final analizado antes de que OpenClaw gestione
sus propios marcadores de control y la entrega al canal.
`input` reescribe el prompt del sistema y el prompt del usuario que se pasan a la CLI. `output`
reescribe los deltas transmitidos del asistente y el texto final analizado antes de que OpenClaw gestione
sus propios marcadores de control y la entrega del canal.
Para las CLI que emiten JSONL compatible con Claude Code stream-json, establece
Para las CLI que emiten JSONL compatible con Claude Code stream-json, configura
`jsonlDialect: "claude-stream-json"` en la configuración de ese backend.
## Superposiciones MCP empaquetadas
@ -368,47 +374,47 @@ Comportamiento empaquetado actual:
- `claude-cli`: archivo de configuración MCP estricto generado
- `codex-cli`: sobrescrituras de configuración en línea para `mcp_servers`; el servidor
local loopback generado de OpenClaw se marca con el modo de aprobación de herramientas por servidor de Codex
para que las llamadas MCP no se queden bloqueadas en prompts de aprobación locales
- `google-gemini-cli`: archivo de configuración del sistema de Gemini generado
loopback generado de OpenClaw se marca con el modo de aprobación de herramientas por servidor de Codex
para que las llamadas MCP no puedan bloquearse en prompts de aprobación locales
- `google-gemini-cli`: archivo de configuración del sistema Gemini generado
Cuando el MCP empaquetado está habilitado, OpenClaw:
Cuando MCP empaquetado está habilitado, OpenClaw:
- inicia un servidor HTTP MCP de loopback que expone herramientas de gateway al proceso de CLI
- inicia un servidor HTTP MCP de loopback que expone herramientas de Gateway al proceso de la CLI
- autentica el puente con un token por sesión (`OPENCLAW_MCP_TOKEN`)
- limita el acceso a herramientas al contexto de la sesión, cuenta y canal actuales
- carga los servidores bundle-MCP habilitados para el workspace actual
- los combina con cualquier forma existente de configuración/ajustes MCP del backend
- reescribe la configuración de lanzamiento usando el modo de integración propiedad del backend desde la extensión propietaria
- limita el acceso a herramientas al contexto de la sesión, la cuenta y el canal actuales
- carga los servidores bundle-MCP habilitados para el espacio de trabajo actual
- los fusiona con cualquier forma de configuración/ajustes MCP existente del backend
- reescribe la configuración de inicio usando el modo de integración propiedad del backend desde la extensión propietaria
Si no hay servidores MCP habilitados, OpenClaw igualmente inyecta una configuración estricta cuando un
backend opta por el MCP empaquetado para que las ejecuciones en segundo plano permanezcan aisladas.
backend opta por MCP empaquetado para que las ejecuciones en segundo plano permanezcan aisladas.
Los runtimes MCP empaquetados con alcance de sesión se almacenan en caché para reutilizarlos dentro de una sesión y luego
se eliminan tras `mcp.sessionIdleTtlMs` milisegundos de inactividad (10
minutos de forma predeterminada; establece `0` para deshabilitarlo). Las ejecuciones integradas de un solo uso, como sondeos de autenticación,
generación de slugs y solicitudes de recuperación de Active Memory, limpian al final de la ejecución para que los procesos secundarios
stdio y los streams HTTP/SSE transmisibles no sobrevivan a la ejecución.
se eliminan después de `mcp.sessionIdleTtlMs` milisegundos de inactividad (predeterminado: 10
minutos; configura `0` para deshabilitarlo). Las ejecuciones incrustadas de una sola vez, como comprobaciones de autenticación,
generación de slugs y recuperación de Active Memory, solicitan limpieza al final de la ejecución para que los hijos stdio
y los flujos Streamable HTTP/SSE no sobrevivan a la ejecución.
## Limitaciones
- **Sin llamadas directas a herramientas de OpenClaw.** OpenClaw no inyecta llamadas a herramientas en
el protocolo del backend de CLI. Los backends solo ven herramientas de gateway cuando optan por
el protocolo del backend de CLI. Los backends solo ven herramientas de Gateway cuando optan por
`bundleMcp: true`.
- **El streaming es específico del backend.** Algunos backends transmiten JSONL; otros almacenan en búfer
hasta salir.
- **Las salidas estructuradas** dependen del formato JSON de la CLI.
- **Las sesiones de Codex CLI** se reanudan mediante salida de texto (sin JSONL), lo que es menos
estructurado que la ejecución inicial con `--json`. Las sesiones de OpenClaw siguen funcionando
con normalidad.
normalmente.
## Solución de problemas
- **CLI no encontrada**: establece `command` en una ruta completa.
- **No se encuentra la CLI**: configura `command` con una ruta completa.
- **Nombre de modelo incorrecto**: usa `modelAliases` para asignar `provider/model` → modelo de CLI.
- **Sin continuidad de sesión**: asegúrate de que `sessionArg` esté establecido y que `sessionMode` no sea
`none` (Codex CLI actualmente no puede reanudar con salida JSON).
- **Imágenes ignoradas**: establece `imageArg` (y verifica que la CLI admita rutas de archivo).
- **Sin continuidad de sesión**: asegúrate de que `sessionArg` esté configurado y de que `sessionMode` no sea
`none` (Codex CLI actualmente no puede reanudarse con salida JSON).
- **Imágenes ignoradas**: configura `imageArg` (y verifica que la CLI admita rutas de archivo).
## Relacionado

375
docs/es/help/testing-live.md
View File

@ -1,29 +1,29 @@
---
read_when:
- Ejecución de pruebas de humo de la matriz de modelos en vivo / backend de CLI / ACP / media-provider
- Ejecución de pruebas de humo de la matriz de modelos en vivo / servidor de CLI / ACP / media-provider
- Depuración de la resolución de credenciales de pruebas en vivo
- Agregar una nueva prueba en vivo específica del proveedor
sidebarTitle: Live tests
summary: 'Pruebas en vivo (que interactúan con la red): matriz de modelos, backends de la CLI, ACP, proveedores de medios, credenciales'
title: 'Pruebas: conjuntos de pruebas en vivo'
summary: 'Pruebas en vivo (que acceden a la red): matriz de modelos, backends de CLI, ACP, proveedores de medios, credenciales'
title: 'Pruebas: suites en vivo'
x-i18n:
generated_at: "2026-05-03T05:28:36Z"
generated_at: "2026-05-04T18:24:00Z"
model: gpt-5.5
provider: openai
source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00
source_hash: 03b8ca6348137a55c8d5f67c9c166a130a75a744f6a433cb00496756b29d7016
source_path: help/testing-live.md
workflow: 16
---
Para el inicio rápido, los ejecutores de QA, las suites unitarias/de integración y los flujos de Docker, consulta
[Pruebas](/es/help/testing). Esta página cubre las suites de prueba **live** (que tocan la red):
matriz de modelos, backends de CLI, ACP y pruebas live de proveedores de medios, además del
Para inicio rápido, ejecutores de QA, suites unitarias/de integración y flujos de Docker, consulta
[Pruebas](/es/help/testing). Esta página cubre las suites de pruebas **en vivo** (con acceso a red):
matriz de modelos, backends de CLI, ACP y pruebas en vivo de proveedores de medios, además del
manejo de credenciales.
## Live: comandos smoke de perfil local
## En vivo: comandos smoke de perfil local
Carga `~/.profile` antes de las comprobaciones live ad hoc para que las claves de proveedor y las rutas de herramientas
locales coincidan con tu shell:
Carga `~/.profile` antes de las comprobaciones en vivo ad hoc para que las claves de proveedor y las rutas
de herramientas locales coincidan con tu shell:
```bash
source ~/.profile
@ -37,102 +37,102 @@ pnpm openclaw infer tts convert --local --json \
--output /tmp/openclaw-live-smoke.mp3
```
Smoke seguro de preparación de llamada de voz:
Smoke seguro de preparación para llamadas de voz:
```bash
pnpm openclaw voicecall setup --json
pnpm openclaw voicecall smoke --to "+15555550123"
```
`voicecall smoke` es un ensayo en seco salvo que `--yes` también esté presente. Usa `--yes` solo
cuando quieras intencionadamente realizar una llamada de notificación real. Para Twilio, Telnyx y
Plivo, una comprobación de preparación correcta requiere una URL pública de webhook; las alternativas
locales de solo loopback/privadas se rechazan por diseño.
`voicecall smoke` es una ejecución de prueba salvo que también esté presente `--yes`. Usa `--yes` solo
cuando quieras realizar intencionadamente una llamada de notificación real. Para Twilio, Telnyx y
Plivo, una comprobación de preparación correcta requiere una URL de webhook pública; las alternativas de
respaldo de solo local loopback/privadas se rechazan por diseño.
## Live: barrido de capacidades de nodo Android
## En vivo: barrido de capacidades de Node Android
- Prueba: `src/gateway/android-node.capabilities.live.test.ts`
- Script: `pnpm android:test:integration`
- Objetivo: invocar **cada comando anunciado actualmente** por un nodo Android conectado y verificar el comportamiento del contrato de comandos.
- Objetivo: invocar **cada comando anunciado actualmente** por un Node Android conectado y comprobar el comportamiento del contrato de comandos.
- Alcance:
- Configuración previa/manual (la suite no instala/ejecuta/empareja la aplicación).
- Validación comando por comando de `node.invoke` del gateway para el nodo Android seleccionado.
- Preconfiguración requerida:
- Aplicación Android ya conectada y emparejada con el gateway.
- Aplicación mantenida en primer plano.
- Configuración previa/manual requerida (la suite no instala/ejecuta/empareja la app).
- Validación comando por comando de `node.invoke` del Gateway para el Node Android seleccionado.
- Configuración previa requerida:
- App Android ya conectada y emparejada con el Gateway.
- App mantenida en primer plano.
- Permisos/consentimiento de captura concedidos para las capacidades que esperas que pasen.
- Sobrescrituras de destino opcionales:
- Sobrescrituras opcionales de destino:
- `OPENCLAW_ANDROID_NODE_ID` u `OPENCLAW_ANDROID_NODE_NAME`.
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`.
- Detalles completos de configuración de Android: [Aplicación Android](/es/platforms/android)
- Detalles completos de configuración de Android: [App Android](/es/platforms/android)
## Live: smoke de modelos (claves de perfil)
## En vivo: smoke de modelos (claves de perfil)
Las pruebas live se dividen en dos capas para poder aislar fallos:
Las pruebas en vivo se dividen en dos capas para poder aislar fallos:
- “Modelo directo” indica si el proveedor/modelo puede responder con la clave dada.
- “Smoke de Gateway” indica si toda la canalización gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.).
- “Modelo directo” nos indica que el proveedor/modelo puede responder con la clave dada.
- “Smoke de Gateway” nos indica que toda la canalización gateway+agente funciona para ese modelo (sesiones, historial, herramientas, política de sandbox, etc.).
### Capa 1: finalización directa de modelo (sin gateway)
### Capa 1: finalización directa de modelo (sin Gateway)
- Prueba: `src/agents/models.profiles.live.test.ts`
- Objetivo:
- Enumerar los modelos descubiertos
- Enumerar modelos descubiertos
- Usar `getApiKeyForModel` para seleccionar modelos para los que tienes credenciales
- Ejecutar una finalización pequeña por modelo (y regresiones dirigidas cuando sea necesario)
- Cómo habilitar:
- `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente)
- Define `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` enfocado en el smoke de gateway
- Define `OPENCLAW_LIVE_MODELS=modern` (o `all`, alias de modern) para ejecutar realmente esta suite; de lo contrario se omite para mantener `pnpm test:live` centrado en el smoke de Gateway
- Cómo seleccionar modelos:
- `OPENCLAW_LIVE_MODELS=modern` para ejecutar la lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_MODELS=all` es un alias de la lista permitida moderna
- o `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (lista permitida separada por comas)
- Los barridos modern/all usan por defecto un límite seleccionado de alta señal; define `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor.
- Los barridos exhaustivos usan `OPENCLAW_LIVE_TEST_TIMEOUT_MS` para el tiempo de espera completo de la prueba de modelo directo. Predeterminado: 60 minutos.
- Los barridos modern/all usan de forma predeterminada un límite curado de alta señal; define `OPENCLAW_LIVE_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor.
- Los barridos exhaustivos usan `OPENCLAW_LIVE_TEST_TIMEOUT_MS` para el tiempo de espera de toda la prueba de modelo directo. Predeterminado: 60 minutos.
- Las sondas de modelo directo se ejecutan con paralelismo de 20 vías de forma predeterminada; define `OPENCLAW_LIVE_MODEL_CONCURRENCY` para sobrescribirlo.
- Cómo seleccionar proveedores:
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (lista permitida separada por comas)
- De dónde vienen las claves:
- De forma predeterminada: almacén de perfiles y alternativas de entorno
- Define `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir solo **almacén de perfiles**
- De forma predeterminada: almacén de perfiles y alternativas de respaldo de entorno
- Define `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir solo el **almacén de perfiles**
- Por qué existe:
- Separa “la API del proveedor está rota / la clave no es válida” de “la canalización de agente de gateway está rota”
- Contiene regresiones pequeñas y aisladas (ejemplo: reproducción de razonamiento de OpenAI Responses/Codex Responses + flujos de llamadas de herramientas)
- Separa “la API del proveedor está rota / la clave no es válida” de “la canalización del agente Gateway está rota”
- Contiene regresiones pequeñas y aisladas (ejemplo: reproducción de razonamiento de OpenAI Responses/Codex Responses + flujos de llamadas a herramientas)
### Capa 2: smoke de Gateway + agente de desarrollo (lo que "@openclaw" hace realmente)
### Capa 2: smoke de Gateway + agente dev (lo que realmente hace "@openclaw")
- Prueba: `src/gateway/gateway-models.profiles.live.test.ts`
- Objetivo:
- Iniciar un gateway en proceso
- Iniciar un Gateway en proceso
- Crear/parchear una sesión `agent:dev:*` (sobrescritura de modelo por ejecución)
- Iterar modelos con claves y verificar:
- Iterar por modelos con claves y comprobar:
- respuesta “significativa” (sin herramientas)
- funciona una invocación de herramienta real (sonda de lectura)
- sondas de herramienta adicionales opcionales (sonda exec+read)
- las rutas de regresión de OpenAI (solo llamada de herramienta → seguimiento) siguen funcionando
- Detalles de sondas (para poder explicar fallos rápidamente):
- sonda `read`: la prueba escribe un archivo con nonce en el espacio de trabajo y pide al agente que lo lea con `read` y devuelva el nonce.
- sonda `exec+read`: la prueba pide al agente que escriba con `exec` un nonce en un archivo temporal y luego lo lea con `read`.
- sonda de imagen: la prueba adjunta un PNG generado (gato + código aleatorio) y espera que el modelo devuelva `cat <CODE>`.
- una invocación real de herramienta funciona (sonda de lectura)
- sondas de herramientas extra opcionales (sonda exec+read)
- las rutas de regresión de OpenAI (solo llamada a herramienta → seguimiento) siguen funcionando
- Detalles de sondas (para que puedas explicar fallos rápidamente):
- Sonda `read`: la prueba escribe un archivo con nonce en el workspace y pide al agente que lo lea con `read` y devuelva el nonce.
- Sonda `exec+read`: la prueba pide al agente que escriba con `exec` un nonce en un archivo temporal y luego lo lea con `read`.
- Sonda de imagen: la prueba adjunta un PNG generado (gato + código aleatorio) y espera que el modelo devuelva `cat <CODE>`.
- Referencia de implementación: `src/gateway/gateway-models.profiles.live.test.ts` y `src/gateway/live-image-probe.ts`.
- Cómo habilitar:
- `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente)
- Cómo seleccionar modelos:
- Predeterminado: lista permitida moderna (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` es un alias de la lista permitida moderna
- O define `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o lista separada por comas) para acotar
- Los barridos de gateway modern/all usan por defecto un límite seleccionado de alta señal; define `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor.
- Cómo seleccionar proveedores (evitar “todo OpenRouter”):
- O define `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (o una lista separada por comas) para acotar
- Los barridos de Gateway modern/all usan de forma predeterminada un límite curado de alta señal; define `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para un barrido moderno exhaustivo o un número positivo para un límite menor.
- Cómo seleccionar proveedores (evita “todo OpenRouter”):
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (lista permitida separada por comas)
- Las sondas de herramientas + imagen siempre están activadas en esta prueba live:
- sonda `read` + sonda `exec+read` (estrés de herramientas)
- la sonda de imagen se ejecuta cuando el modelo anuncia soporte para entrada de imágenes
- Las sondas de herramientas + imagen siempre están activadas en esta prueba en vivo:
- Sonda `read` + sonda `exec+read` (estrés de herramientas)
- La sonda de imagen se ejecuta cuando el modelo anuncia compatibilidad con entrada de imagen
- Flujo (alto nivel):
- La prueba genera un PNG pequeño con “CAT” + código aleatorio (`src/gateway/live-image-probe.ts`)
- Lo envía mediante `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]`
- Gateway analiza adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
- El agente integrado reenvía al modelo un mensaje de usuario multimodal
- Verificación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores)
- Gateway analiza los adjuntos en `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
- El agente incrustado reenvía un mensaje de usuario multimodal al modelo
- Comprobación: la respuesta contiene `cat` + el código (tolerancia OCR: se permiten errores menores)
<Tip>
Para ver qué puedes probar en tu máquina (y los ids exactos `provider/model`), ejecuta:
@ -144,27 +144,27 @@ openclaw models list --json
</Tip>
## Live: smoke de backend CLI (Claude, Codex, Gemini u otras CLI locales)
## En vivo: smoke de backend CLI (Claude, Codex, Gemini u otras CLI locales)
- Prueba: `src/gateway/gateway-cli-backend.live.test.ts`
- Objetivo: validar la canalización Gateway + agente usando un backend CLI local, sin tocar tu configuración predeterminada.
- Los valores predeterminados de smoke específicos del backend viven con la definición `cli-backend.ts` del plugin propietario.
- Objetivo: validar la canalización Gateway + agente usando un backend de CLI local, sin tocar tu configuración predeterminada.
- Los valores predeterminados de smoke específicos de backend viven con la definición `cli-backend.ts` del plugin propietario.
- Habilitar:
- `pnpm test:live` (o `OPENCLAW_LIVE_TEST=1` si invocas Vitest directamente)
- `OPENCLAW_LIVE_CLI_BACKEND=1`
- Valores predeterminados:
- Proveedor/modelo predeterminado: `claude-cli/claude-sonnet-4-6`
- El comportamiento de comando/args/imagen proviene de los metadatos del plugin de backend CLI propietario.
- El comportamiento de comando/args/imagen viene de los metadatos del plugin de backend CLI propietario.
- Sobrescrituras (opcionales):
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar un adjunto de imagen real (las rutas se inyectan en el prompt). Las recetas de Docker lo desactivan de forma predeterminada salvo que se solicite explícitamente.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivo de imagen como args de CLI en lugar de inyectarlas en el prompt.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para pasar rutas de archivo de imagen como args de CLI en lugar de inyección en el prompt.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (o `"list"`) para controlar cómo se pasan los args de imagen cuando `IMAGE_ARG` está definido.
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar un segundo turno y validar el flujo de reanudación.
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` para optar por la sonda de continuidad en la misma sesión Claude Sonnet -> Opus cuando el modelo seleccionado admite un destino de cambio. Las recetas de Docker lo desactivan de forma predeterminada para la fiabilidad agregada.
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` para optar por la sonda de MCP/herramienta de loopback. Las recetas de Docker lo desactivan de forma predeterminada salvo que se solicite explícitamente.
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` para optar por la sonda de loopback MCP/herramienta. Las recetas de Docker lo desactivan de forma predeterminada salvo que se solicite explícitamente.
Ejemplo:
@ -174,16 +174,16 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \
pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
```
Smoke económico de configuración MCP de Gemini:
Smoke barato de configuración MCP de Gemini:
```bash
OPENCLAW_LIVE_TEST=1 \
pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
```
Esto no pide a Gemini que genere una respuesta. Escribe la misma configuración de sistema
que OpenClaw le da a Gemini, luego ejecuta `gemini --debug mcp list` para demostrar que un
servidor `transport: "streamable-http"` guardado se normaliza a la forma HTTP MCP de Gemini
Esto no pide a Gemini que genere una respuesta. Escribe la misma configuración del sistema
que OpenClaw da a Gemini y luego ejecuta `gemini --debug mcp list` para demostrar que un
servidor `transport: "streamable-http"` guardado se normaliza a la forma MCP HTTP de Gemini
y puede conectarse a un servidor MCP streamable-HTTP local.
Receta de Docker:
@ -192,7 +192,7 @@ Receta de Docker:
pnpm test:docker:live-cli-backend
```
Recetas de Docker de proveedor único:
Recetas de Docker de un solo proveedor:
```bash
pnpm test:docker:live-cli-backend:claude
@ -204,18 +204,27 @@ pnpm test:docker:live-cli-backend:gemini
Notas:
- El ejecutor de Docker vive en `scripts/test-live-cli-backend-docker.sh`.
- Ejecuta el smoke live de backend CLI dentro de la imagen Docker del repo como el usuario no root `node`.
- Resuelve metadatos de smoke de CLI desde el plugin propietario y luego instala el paquete CLI de Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo escribible en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`).
- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portátil de suscripción de Claude Code mediante `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primero demuestra `claude -p` directo en Docker y luego ejecuta dos turnos de backend CLI de Gateway sin preservar variables de entorno de clave de API de Anthropic. Este carril de suscripción desactiva por defecto las sondas de MCP/herramienta e imagen de Claude porque Claude actualmente enruta el uso de aplicaciones de terceros mediante facturación por uso adicional en lugar de los límites normales del plan de suscripción.
- El smoke live de backend CLI ahora ejercita el mismo flujo de extremo a extremo para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada de herramienta MCP `cron` verificada mediante la CLI de gateway.
- El smoke predeterminado de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada todavía recuerda una nota anterior.
- Ejecuta el smoke en vivo de backend CLI dentro de la imagen Docker del repo como el usuario no root `node`.
- Resuelve los metadatos de smoke de CLI desde el plugin propietario y luego instala el paquete CLI de Linux correspondiente (`@anthropic-ai/claude-code`, `@openai/codex` o `@google/gemini-cli`) en un prefijo escribible en caché en `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (predeterminado: `~/.cache/openclaw/docker-cli-tools`).
- `pnpm test:docker:live-cli-backend:claude-subscription` requiere OAuth portable de suscripción de Claude Code mediante `~/.claude/.credentials.json` con `claudeAiOauth.subscriptionType` o `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primero demuestra `claude -p` directo en Docker y luego ejecuta dos turnos de backend CLI de Gateway sin conservar variables de entorno de clave API de Anthropic. Esta vía de suscripción desactiva por defecto las sondas MCP/herramienta e imagen de Claude porque Claude actualmente enruta el uso de apps de terceros mediante facturación de uso extra en lugar de los límites normales del plan de suscripción.
- El smoke en vivo de backend CLI ahora ejercita el mismo flujo de extremo a extremo para Claude, Codex y Gemini: turno de texto, turno de clasificación de imagen y luego llamada a herramienta MCP `cron` verificada a través de la CLI de Gateway.
- El smoke predeterminado de Claude también parchea la sesión de Sonnet a Opus y verifica que la sesión reanudada aún recuerde una nota anterior.
## Live: smoke de enlace ACP (`/acp spawn ... --bind here`)
## En vivo: alcanzabilidad del proxy HTTP/2 de APNs
- Prueba: `src/infra/push-apns-http2.live.test.ts`
- Objetivo: tunelizar a través de un proxy HTTP CONNECT local hacia el endpoint APNs sandbox de Apple, enviar la solicitud de validación HTTP/2 de APNs y comprobar que la respuesta real `403 InvalidProviderToken` de Apple vuelve por la ruta del proxy.
- Habilitar:
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts`
- Tiempo de espera opcional:
- `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000`
## En vivo: smoke de bind ACP (`/acp spawn ... --bind here`)
- Prueba: `src/gateway/gateway-acp-bind.live.test.ts`
- Objetivo: validar el flujo real de vinculación de conversación ACP con un agente ACP en vivo:
- enviar `/acp spawn <agent> --bind here`
- vincular en el lugar una conversación sintética de canal de mensajes
- vincular en su lugar una conversación sintética de canal de mensajes
- enviar un seguimiento normal en esa misma conversación
- verificar que el seguimiento llegue a la transcripción de la sesión ACP vinculada
- Habilitar:
@ -224,9 +233,9 @@ Notas:
- Valores predeterminados:
- Agentes ACP en Docker: `claude,codex,gemini`
- Agente ACP para `pnpm test:live ...` directo: `claude`
- Canal sintético: contexto de conversación estilo Slack DM
- Canal sintético: contexto de conversación estilo DM de Slack
- Backend ACP: `acpx`
- Sobrescrituras:
- Sustituciones:
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
- `OPENCLAW_LIVE_ACP_BIND_AGENT=codex`
- `OPENCLAW_LIVE_ACP_BIND_AGENT=droid`
@ -240,9 +249,9 @@ Notas:
- `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
- Notas:
- Este carril usa la superficie `chat.send` del gateway con campos de ruta de origen sintética solo para administración, para que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir una entrega externa.
- Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está definido, la prueba usa el registro de agentes integrado del Plugin `acpx` embebido para el agente de arnés ACP seleccionado.
- La creación de MCP de Cron de sesión vinculada es de mejor esfuerzo de forma predeterminada porque los arneses ACP externos pueden cancelar llamadas MCP después de que la prueba de vinculación/imagen haya pasado; establece `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` para hacer estricta esa sonda de Cron posterior a la vinculación.
- Esta vía usa la superficie `chat.send` del Gateway con campos de ruta de origen sintética solo para administradores, de modo que las pruebas puedan adjuntar contexto de canal de mensajes sin fingir una entrega externa.
- Cuando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` no está definido, la prueba usa el registro de agentes integrado del Plugin `acpx` incorporado para el agente de arnés ACP seleccionado.
- La creación de MCP Cron de sesión vinculada es de mejor esfuerzo de forma predeterminada porque los arneses ACP externos pueden cancelar llamadas MCP después de que la prueba de vinculación/imagen haya pasado; define `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` para hacer estricta esa comprobación Cron posterior a la vinculación.
Ejemplo:
@ -258,7 +267,7 @@ Receta de Docker:
pnpm test:docker:live-acp-bind
```
Recetas Docker de un solo agente:
Recetas de Docker para un solo agente:
```bash
pnpm test:docker:live-acp-bind:claude
@ -270,38 +279,32 @@ pnpm test:docker:live-acp-bind:opencode
Notas de Docker:
- El ejecutor Docker está en `scripts/test-live-acp-bind-docker.sh`.
- El ejecutor de Docker está en `scripts/test-live-acp-bind-docker.sh`.
- De forma predeterminada, ejecuta el smoke de vinculación ACP contra los agentes CLI en vivo agregados en secuencia: `claude`, `codex` y luego `gemini`.
- Usa `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` u `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` para acotar la matriz.
- Carga `~/.profile`, prepara el material de autenticación CLI correspondiente dentro del contenedor y luego instala la CLI en vivo solicitada (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid mediante `https://app.factory.ai/cli`, `@google/gemini-cli` u `opencode-ai`) si falta. El backend ACP en sí es el paquete `acpx/runtime` embebido del Plugin oficial `acpx`.
- La variante Docker de Droid prepara `~/.factory` para la configuración, reenvía `FACTORY_API_KEY` y requiere esa clave API porque la autenticación local de Factory OAuth/keyring no es portable al contenedor. Usa la entrada de registro integrada de ACPX `droid exec --output-format acp`.
- La variante Docker de OpenCode es un carril de regresión estricto de un solo agente. Escribe un modelo predeterminado temporal `OPENCODE_CONFIG_CONTENT` desde `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (predeterminado `opencode/kimi-k2.6`) después de cargar `~/.profile`, y `pnpm test:docker:live-acp-bind:opencode` requiere una transcripción de asistente vinculada en lugar de aceptar la omisión genérica posterior a la vinculación.
- Las llamadas directas a la CLI `acpx` son solo una ruta manual/de solución alternativa para comparar comportamiento fuera del Gateway. El smoke Docker de vinculación ACP ejercita el backend de runtime `acpx` embebido de OpenClaw.
- Carga `~/.profile`, prepara el material de autenticación CLI correspondiente en el contenedor y luego instala la CLI en vivo solicitada (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid mediante `https://app.factory.ai/cli`, `@google/gemini-cli` u `opencode-ai`) si falta. El backend ACP en sí es el paquete `acpx/runtime` incorporado desde el Plugin oficial `acpx`.
- La variante de Docker Droid prepara `~/.factory` para la configuración, reenvía `FACTORY_API_KEY` y requiere esa clave de API porque la autenticación local de Factory OAuth/keyring no es portable al contenedor. Usa la entrada de registro integrada de ACPX `droid exec --output-format acp`.
- La variante de Docker OpenCode es una vía de regresión estricta de un solo agente. Escribe un modelo predeterminado temporal `OPENCODE_CONFIG_CONTENT` desde `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (predeterminado `opencode/kimi-k2.6`) después de cargar `~/.profile`, y `pnpm test:docker:live-acp-bind:opencode` requiere una transcripción de asistente vinculada en lugar de aceptar el salto genérico posterior a la vinculación.
- Las llamadas directas a la CLI `acpx` son solo una ruta manual/de solución alternativa para comparar el comportamiento fuera del Gateway. El smoke de vinculación ACP de Docker ejercita el backend de runtime `acpx` incorporado de OpenClaw.
## En vivo: smoke del arnés de servidor de aplicación de Codex
## En vivo: smoke del arnés de servidor de aplicaciones Codex
- Objetivo: validar el arnés Codex propiedad del Plugin a través del método normal
`agent` del gateway:
- cargar el Plugin incluido `codex`
- Objetivo: validar el arnés Codex propiedad del Plugin mediante el método normal
`agent` del Gateway:
- cargar el Plugin `codex` incluido
- seleccionar `OPENCLAW_AGENT_RUNTIME=codex`
- enviar un primer turno de agente del gateway a `openai/gpt-5.5` con el arnés Codex forzado
- enviar un segundo turno a la misma sesión de OpenClaw y verificar que el hilo del servidor de aplicación
pueda reanudarse
- ejecutar `/codex status` y `/codex models` a través de la misma ruta de comandos del gateway
- opcionalmente ejecutar dos sondas de shell escaladas revisadas por Guardian: un comando benigno
que debería aprobarse y una carga de secreto falso que debería denegarse para que el agente
responda con una pregunta
- enviar un primer turno de agente de Gateway a `openai/gpt-5.5` con el arnés Codex forzado
- enviar un segundo turno a la misma sesión de OpenClaw y verificar que el hilo de servidor de aplicaciones pueda reanudarse
- ejecutar `/codex status` y `/codex models` mediante la misma ruta de comandos del Gateway
- opcionalmente ejecutar dos comprobaciones de shell escaladas revisadas por Guardian: un comando benigno que debería aprobarse y una carga de secreto falso que debería denegarse para que el agente vuelva a preguntar
- Prueba: `src/gateway/gateway-codex-harness.live.test.ts`
- Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1`
- Modelo predeterminado: `openai/gpt-5.5`
- Sonda de imagen opcional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- Sonda MCP/herramienta opcional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- Sonda Guardian opcional: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- El smoke usa `agentRuntime.id: "codex"` para que un arnés Codex roto no pueda
pasar al recurrir silenciosamente a PI.
- Autenticación: autenticación de servidor de aplicación de Codex desde el inicio de sesión local de suscripción a Codex. Los
smokes de Docker también pueden proporcionar `OPENAI_API_KEY` para sondas no Codex cuando corresponda,
además de `~/.codex/auth.json` y `~/.codex/config.toml` copiados opcionalmente.
- Comprobación opcional de imagen: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
- Comprobación opcional de MCP/herramienta: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
- Comprobación opcional de Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
- El smoke usa `agentRuntime.id: "codex"` para que un arnés Codex roto no pueda pasar al volver silenciosamente a PI.
- Autenticación: autenticación de servidor de aplicaciones Codex desde el inicio de sesión de suscripción local de Codex. Los smokes de Docker también pueden proporcionar `OPENAI_API_KEY` para comprobaciones que no sean Codex cuando corresponda, además de `~/.codex/auth.json` y `~/.codex/config.toml` copiados opcionales.
Receta local:
@ -324,58 +327,52 @@ pnpm test:docker:live-codex-harness
Notas de Docker:
- El ejecutor Docker está en `scripts/test-live-codex-harness-docker.sh`.
- Carga el `~/.profile` montado, pasa `OPENAI_API_KEY`, copia los archivos de autenticación de la CLI de Codex
cuando están presentes, instala `@openai/codex` en un prefijo npm montado escribible,
prepara el árbol de código fuente y luego ejecuta solo la prueba en vivo del arnés Codex.
- Docker habilita las sondas de imagen, MCP/herramienta y Guardian de forma predeterminada. Establece
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` o
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` o
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` cuando necesites una ejecución de depuración más acotada.
- Docker usa la misma configuración explícita de runtime de Codex, por lo que los alias heredados o el
fallback de PI no pueden ocultar una regresión del arnés Codex.
- El ejecutor de Docker está en `scripts/test-live-codex-harness-docker.sh`.
- Carga el `~/.profile` montado, pasa `OPENAI_API_KEY`, copia los archivos de autenticación de la CLI Codex cuando están presentes, instala `@openai/codex` en un prefijo npm montado con permisos de escritura, prepara el árbol de código fuente y luego ejecuta solo la prueba en vivo del arnés Codex.
- Docker habilita las comprobaciones de imagen, MCP/herramienta y Guardian de forma predeterminada. Define `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`, `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` u `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` cuando necesites una ejecución de depuración más acotada.
- Docker usa la misma configuración explícita de runtime Codex, por lo que los alias heredados o la reserva a PI no pueden ocultar una regresión del arnés Codex.
### Recetas en vivo recomendadas
Las listas de permitidos acotadas y explícitas son las más rápidas y menos inestables:
- Un solo modelo, directo (sin gateway):
- Un solo modelo, directo (sin Gateway):
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`
- Un solo modelo, smoke de gateway:
- Un solo modelo, smoke de Gateway:
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Llamadas a herramientas entre varios proveedores:
- Llamadas a herramientas en varios proveedores:
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Enfoque en Google (clave API de Gemini + Antigravity):
- Gemini (clave API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Enfoque en Google (clave de API de Gemini + Antigravity):
- Gemini (clave de API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Smoke de razonamiento adaptativo de Google:
- Si las claves locales están en el perfil del shell: `source ~/.profile`
- Smoke de pensamiento adaptativo de Google:
- Si las claves locales están en el perfil de shell: `source ~/.profile`
- Valor predeterminado dinámico de Gemini 3: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
- Presupuesto dinámico de Gemini 2.5: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
Notas:
- `google/...` usa la API de Gemini (clave API).
- `google/...` usa la API de Gemini (clave de API).
- `google-antigravity/...` usa el puente OAuth de Antigravity (endpoint de agente estilo Cloud Code Assist).
- `google-gemini-cli/...` usa la CLI local de Gemini en tu máquina (autenticación separada + particularidades de herramientas).
- API de Gemini frente a CLI de Gemini:
- API: OpenClaw llama a la API alojada de Gemini de Google por HTTP (clave API / autenticación de perfil); esto es lo que la mayoría de usuarios quiere decir con “Gemini”.
- CLI: OpenClaw invoca un binario local `gemini`; tiene su propia autenticación y puede comportarse de forma diferente (streaming/soporte de herramientas/desfase de versiones).
- API: OpenClaw llama a la API Gemini alojada de Google por HTTP (clave de API / autenticación de perfil); esto es lo que la mayoría de los usuarios quiere decir con “Gemini”.
- CLI: OpenClaw invoca un binario local `gemini` mediante shell; tiene su propia autenticación y puede comportarse de forma distinta (streaming/soporte de herramientas/desfase de versiones).
## En vivo: matriz de modelos (lo que cubrimos)
No hay una “lista de modelos de CI” fija (en vivo es opt-in), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves.
No hay una “lista de modelos de CI” fija (en vivo es opcional), pero estos son los modelos **recomendados** para cubrir regularmente en una máquina de desarrollo con claves.
### Conjunto de smoke moderno (llamadas a herramientas + imagen)
Esta es la ejecución de “modelos comunes” que esperamos mantener funcionando:
- OpenAI (no Codex): `openai/gpt-5.5`
- OAuth de OpenAI Codex: `openai-codex/gpt-5.5`
- OpenAI Codex OAuth: `openai-codex/gpt-5.5`
- Anthropic: `anthropic/claude-opus-4-6` (o `anthropic/claude-sonnet-4-6`)
- Google (API de Gemini): `google/gemini-3.1-pro-preview` y `google/gemini-3-flash-preview` (evita modelos Gemini 2.x más antiguos)
- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` y `google-antigravity/gemini-3-flash`
@ -383,7 +380,7 @@ Esta es la ejecución de “modelos comunes” que esperamos mantener funcionand
- Z.AI (GLM): `zai/glm-5.1`
- MiniMax: `minimax/MiniMax-M2.7`
Ejecuta el smoke de gateway con herramientas + imagen:
Ejecuta el smoke de Gateway con herramientas + imagen:
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
### Línea base: llamadas a herramientas (Read + Exec opcional)
@ -397,16 +394,16 @@ Elige al menos uno por familia de proveedores:
- Z.AI (GLM): `zai/glm-5.1`
- MiniMax: `minimax/MiniMax-M2.7`
Cobertura adicional opcional (deseable):
Cobertura adicional opcional (útil tenerla):
- xAI: `xai/grok-4.3` (o el más reciente disponible)
- Mistral: `mistral/`… (elige un modelo capaz de usar “tools” que tengas habilitado)
- xAI: `xai/grok-4.3` (o el último disponible)
- Mistral: `mistral/`… (elige un modelo con capacidad de “herramientas” que tengas habilitado)
- Cerebras: `cerebras/`… (si tienes acceso)
- LM Studio: `lmstudio/`… (local; las llamadas a herramientas dependen del modo API)
- LM Studio: `lmstudio/`… (local; las llamadas a herramientas dependen del modo de API)
### Visión: envío de imagen (adjunto → mensaje multimodal)
Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes de Claude/Gemini/OpenAI con capacidad de visión, etc.) para ejercitar la sonda de imagen.
Incluye al menos un modelo con capacidad de imagen en `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes con visión de Claude/Gemini/OpenAI, etc.) para ejercitar la comprobación de imagen.
### Agregadores / gateways alternativos
@ -421,52 +418,52 @@ Más proveedores que puedes incluir en la matriz en vivo (si tienes credenciales
- Mediante `models.providers` (endpoints personalizados): `minimax` (nube/API), además de cualquier proxy compatible con OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, etc.)
<Tip>
No codifiques "all models" de forma fija en la documentación. La lista autoritativa es lo que devuelva `discoverModels(...)` en tu máquina más las claves que estén disponibles.
No codifiques de forma rígida "todos los modelos" en la documentación. La lista autoritativa es lo que `discoverModels(...)` devuelva en tu máquina más las claves que estén disponibles.
</Tip>
## Credenciales (nunca confirmar en git)
## Credenciales (nunca confirmar)
Las pruebas en vivo descubren credenciales de la misma forma que lo hace la CLI. Implicaciones prácticas:
- Si la CLI funciona, las pruebas live deberían encontrar las mismas claves.
- Si una prueba live dice “sin credenciales”, depura del mismo modo que depurarías `openclaw models list` / la selección de modelo.
- Si la CLI funciona, las pruebas en vivo deberían encontrar las mismas claves.
- Si una prueba en vivo dice “no creds”, depura de la misma forma que depurarías `openclaw models list` / la selección de modelo.
- Perfiles de autenticación por agente: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (esto es lo que significa “claves de perfil” en las pruebas live)
- Perfiles de autenticación por agente: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (esto es lo que significa “profile keys” en las pruebas en vivo)
- Configuración: `~/.openclaw/openclaw.json` (o `OPENCLAW_CONFIG_PATH`)
- Directorio de estado heredado: `~/.openclaw/credentials/` (se copia en el home live preparado cuando está presente, pero no es el almacén principal de claves de perfil)
- Las ejecuciones live locales copian la configuración activa, los archivos `auth-profiles.json` por agente, `credentials/` heredado y los directorios de autenticación de CLI externas compatibles en un home de prueba temporal de forma predeterminada; los homes live preparados omiten `workspace/` y `sandboxes/`, y las sobrescrituras de ruta `agents.*.workspace` / `agentDir` se eliminan para que las sondas no toquen tu workspace real del host.
- Directorio de estado heredado: `~/.openclaw/credentials/` (se copia al home en vivo preparado cuando está presente, pero no es el almacén principal de claves de perfil)
- Las ejecuciones locales en vivo copian la configuración activa, los archivos `auth-profiles.json` por agente, `credentials/` heredado y los directorios de autenticación de CLI externos compatibles en un home temporal de prueba de forma predeterminada; los homes en vivo preparados omiten `workspace/` y `sandboxes/`, y las sobrescrituras de rutas `agents.*.workspace` / `agentDir` se eliminan para que las sondas no toquen tu espacio de trabajo real del host.
Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores Docker de abajo (pueden montar `~/.profile` en el contenedor).
Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.profile`), ejecuta las pruebas locales después de `source ~/.profile`, o usa los ejecutores de Docker de abajo (pueden montar `~/.profile` en el contenedor).
## Deepgram live (transcripción de audio)
## Deepgram en vivo (transcripción de audio)
- Prueba: `extensions/deepgram/audio.live.test.ts`
- Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
- Activar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
## Plan de codificación BytePlus live
## Plan de codificación en vivo de BytePlus
- Prueba: `extensions/byteplus/live.test.ts`
- Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
- Sobrescritura opcional del modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest`
- Activar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
- Sobrescritura opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest`
## Medios de flujo de trabajo ComfyUI live
## Medios de flujo de trabajo de ComfyUI en vivo
- Prueba: `extensions/comfy/comfy.live.test.ts`
- Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
- Activar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
- Alcance:
- Ejercita las rutas incluidas de imagen, video y `music_generate` de comfy
- Omite cada capacidad a menos que `plugins.entries.comfy.config.<capability>` esté configurado
- Útil después de cambiar el envío de flujos de trabajo comfy, el sondeo, las descargas o el registro del Plugin
- Omite cada capacidad salvo que `plugins.entries.comfy.config.<capability>` esté configurado
- Útil después de cambiar el envío de flujos de trabajo de comfy, el sondeo, las descargas o el registro de Plugin
## Generación de imágenes live
## Generación de imágenes en vivo
- Prueba: `test/image-generation.runtime.live.test.ts`
- Comando: `pnpm test:live test/image-generation.runtime.live.test.ts`
- Arnés: `pnpm test:live:media image`
- Arnes: `pnpm test:live:media image`
- Alcance:
- Enumera todos los Plugins proveedores de generación de imágenes registrados
- Enumera cada Plugin proveedor de generación de imágenes registrado
- Carga las variables de entorno faltantes del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear
- Usa claves de API live/de entorno antes que los perfiles de autenticación almacenados de forma predeterminada, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell
- Usa claves de API en vivo/de entorno antes que perfiles de autenticación almacenados de forma predeterminada, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell
- Omite proveedores sin autenticación/perfil/modelo utilizable
- Ejecuta cada proveedor configurado mediante el runtime compartido de generación de imágenes:
- `<provider>:generate`
@ -480,7 +477,7 @@ Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.prof
- `openrouter`
- `vydra`
- `xai`
- Restricción opcional:
- Acotación opcional:
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="deepinfra"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
@ -488,7 +485,7 @@ Si quieres depender de claves de entorno (por ejemplo, exportadas en tu `~/.prof
- Comportamiento de autenticación opcional:
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación del almacén de perfiles e ignorar sobrescrituras solo de entorno
Para la ruta de la CLI distribuida, añade un smoke `infer` después de que pase la prueba live del proveedor/runtime:
Para la ruta de CLI publicada, agrega una smoke de `infer` después de que pase la prueba en vivo del proveedor/runtime:
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
@ -500,75 +497,75 @@ openclaw infer image generate \
--json
```
Esto cubre el análisis de argumentos de la CLI, la resolución de configuración/agente predeterminado, la activación de Plugins incluidos, el runtime compartido de generación de imágenes y la solicitud live al proveedor. Se espera que las dependencias del Plugin estén presentes antes de cargar el runtime.
Esto cubre el análisis de argumentos de CLI, la resolución de configuración/agente predeterminado, la activación de Plugin incluidos, el runtime compartido de generación de imágenes y la solicitud en vivo al proveedor. Se espera que las dependencias del Plugin estén presentes antes de cargar el runtime.
## Generación de música live
## Generación de música en vivo
- Prueba: `extensions/music-generation-providers.live.test.ts`
- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- Arnés: `pnpm test:live:media music`
- Activar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- Arnes: `pnpm test:live:media music`
- Alcance:
- Ejercita la ruta compartida incluida del proveedor de generación de música
- Ejercita la ruta compartida del proveedor incluido de generación de música
- Actualmente cubre Google y MiniMax
- Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear
- Usa claves de API live/de entorno antes que los perfiles de autenticación almacenados de forma predeterminada, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell
- Usa claves de API en vivo/de entorno antes que perfiles de autenticación almacenados de forma predeterminada, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell
- Omite proveedores sin autenticación/perfil/modelo utilizable
- Ejecuta ambos modos de runtime declarados cuando están disponibles:
- `generate` con entrada solo de prompt
- `edit` cuando el proveedor declara `capabilities.edit.enabled`
- Cobertura actual de la ruta compartida:
- Cobertura actual del carril compartido:
- `google`: `generate`, `edit`
- `minimax`: `generate`
- `comfy`: archivo live de Comfy separado, no este barrido compartido
- Restricción opcional:
- `comfy`: archivo en vivo de Comfy separado, no este barrido compartido
- Acotación opcional:
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
- Comportamiento de autenticación opcional:
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación del almacén de perfiles e ignorar sobrescrituras solo de entorno
## Generación de video live
## Generación de video en vivo
- Prueba: `extensions/video-generation-providers.live.test.ts`
- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- Arnés: `pnpm test:live:media video`
- Activar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- Arnes: `pnpm test:live:media video`
- Alcance:
- Ejercita la ruta compartida incluida del proveedor de generación de video
- Usa de forma predeterminada la ruta smoke segura para releases: proveedores que no sean FAL, una solicitud de texto a video por proveedor, prompt de langosta de un segundo y un límite de operación por proveedor desde `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` de forma predeterminada)
- Ejercita la ruta compartida del proveedor incluido de generación de video
- De forma predeterminada usa la ruta smoke segura para releases: proveedores que no sean FAL, una solicitud de texto a video por proveedor, prompt de langosta de un segundo y un límite de operación por proveedor desde `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` de forma predeterminada)
- Omite FAL de forma predeterminada porque la latencia de cola del lado del proveedor puede dominar el tiempo de release; pasa `--video-providers fal` o `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para ejecutarlo explícitamente
- Carga las variables de entorno del proveedor desde tu shell de inicio de sesión (`~/.profile`) antes de sondear
- Usa claves de API live/de entorno antes que los perfiles de autenticación almacenados de forma predeterminada, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell
- Usa claves de API en vivo/de entorno antes que perfiles de autenticación almacenados de forma predeterminada, para que las claves de prueba obsoletas en `auth-profiles.json` no oculten las credenciales reales del shell
- Omite proveedores sin autenticación/perfil/modelo utilizable
- Ejecuta solo `generate` de forma predeterminada
- Establece `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para ejecutar también los modos de transformación declarados cuando estén disponibles:
- `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por búfer en el barrido compartido
- `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local respaldada por búfer en el barrido compartido
- Proveedores `imageToVideo` declarados pero omitidos actualmente en el barrido compartido:
- Establece `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para ejecutar también modos de transformación declarados cuando estén disponibles:
- `imageToVideo` cuando el proveedor declara `capabilities.imageToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de imagen local respaldada por buffer en el barrido compartido
- `videoToVideo` cuando el proveedor declara `capabilities.videoToVideo.enabled` y el proveedor/modelo seleccionado acepta entrada de video local respaldada por buffer en el barrido compartido
- Proveedores `imageToVideo` actualmente declarados pero omitidos en el barrido compartido:
- `vydra` porque el `veo3` incluido es solo texto y el `kling` incluido requiere una URL de imagen remota
- Cobertura específica de Vydra por proveedor:
- Cobertura específica del proveedor Vydra:
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- ese archivo ejecuta `veo3` de texto a video más una ruta `kling` que usa de forma predeterminada una fixture de URL de imagen remota
- Cobertura live actual de `videoToVideo`:
- ese archivo ejecuta `veo3` de texto a video más un carril `kling` que usa de forma predeterminada un fixture de URL de imagen remota
- Cobertura en vivo actual de `videoToVideo`:
- `runway` solo cuando el modelo seleccionado es `runway/gen4_aleph`
- Proveedores `videoToVideo` declarados pero omitidos actualmente en el barrido compartido:
- `alibaba`, `qwen`, `xai` porque esas rutas actualmente requieren URL de referencia remotas `http(s)` / MP4
- `google` porque la ruta compartida actual Gemini/Veo usa entrada local respaldada por búfer y esa ruta no se acepta en el barrido compartido
- `openai` porque la ruta compartida actual carece de garantías de acceso específicas de organización a inpainting/remix de video
- Restricción opcional:
- Proveedores `videoToVideo` actualmente declarados pero omitidos en el barrido compartido:
- `alibaba`, `qwen`, `xai` porque esas rutas actualmente requieren URLs de referencia remotas `http(s)` / MP4
- `google` porque el carril Gemini/Veo compartido actual usa entrada local respaldada por buffer y esa ruta no se acepta en el barrido compartido
- `openai` porque el carril compartido actual carece de garantías de acceso específicas de la organización a video inpaint/remix
- Acotación opcional:
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos los proveedores en el barrido predeterminado, incluido FAL
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reducir el límite de operación de cada proveedor para una ejecución smoke agresiva
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reducir el límite de cada operación de proveedor en una smoke agresiva
- Comportamiento de autenticación opcional:
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forzar la autenticación del almacén de perfiles e ignorar sobrescrituras solo de entorno
## Arnés live de medios
## Arnes de medios en vivo
- Comando: `pnpm test:live:media`
- Propósito:
- Ejecuta las suites live compartidas de imagen, música y video mediante un único punto de entrada nativo del repo
- Carga automáticamente las variables de entorno faltantes del proveedor desde `~/.profile`
- Restringe automáticamente cada suite a los proveedores que actualmente tienen autenticación utilizable de forma predeterminada
- Reutiliza `scripts/test-live.mjs`, por lo que el comportamiento de Heartbeat y del modo silencioso se mantiene consistente
- Ejecuta las suites en vivo compartidas de imagen, música y video mediante un único punto de entrada nativo del repositorio
- Carga automáticamente las variables de entorno faltantes de los proveedores desde `~/.profile`
- Acota automáticamente cada suite a proveedores que actualmente tienen autenticación utilizable de forma predeterminada
- Reutiliza `scripts/test-live.mjs`, por lo que el comportamiento de Heartbeat y modo silencioso se mantiene coherente
- Ejemplos:
- `pnpm test:live:media`
- `pnpm test:live:media image video --providers openai,google,minimax`

276
docs/es/plugins/hooks.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Estás creando un Plugin que necesita before_tool_call, before_agent_reply, ganchos de mensaje o ganchos de ciclo de vida
- Debes bloquear, reescribir o requerir aprobación para las llamadas a herramientas de un Plugin
- Estás decidiendo entre hooks internos y hooks de Plugin
summary: 'Hooks de Plugin: interceptan eventos del ciclo de vida del agente, la herramienta, el mensaje, la sesión y el Gateway'
- Está creando un Plugin que necesita before_tool_call, before_agent_reply, ganchos de mensajes o ganchos de ciclo de vida
- Necesitas bloquear, reescribir o requerir aprobación para las llamadas a herramientas desde un Plugin
- Estás decidiendo entre ganchos internos y ganchos de Plugin
summary: 'Ganchos de Plugin: interceptan eventos del ciclo de vida del agente, la herramienta, el mensaje, la sesión y el Gateway'
title: Ganchos de Plugin
x-i18n:
generated_at: "2026-05-03T21:36:07Z"
generated_at: "2026-05-04T18:24:06Z"
model: gpt-5.5
provider: openai
source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591
source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b
source_path: plugins/hooks.md
workflow: 16
---
Los hooks de Plugin son puntos de extensión en proceso para plugins de OpenClaw. Úsalos
cuando un plugin necesite inspeccionar o cambiar ejecuciones de agentes, llamadas a herramientas, flujo de mensajes,
ciclo de vida de sesiones, enrutamiento de subagentes, instalaciones o arranque del Gateway.
ciclo de vida de sesiones, enrutamiento de subagentes, instalaciones o el inicio del Gateway.
Usa [hooks internos](/es/automation/hooks) en su lugar cuando quieras un pequeño
script `HOOK.md` instalado por el operador para eventos de comandos y Gateway como
script `HOOK.md` instalado por el operador para eventos de comandos y del Gateway como
`/new`, `/reset`, `/stop`, `agent:bootstrap` o `gateway:startup`.
## Inicio rápido
@ -56,19 +56,19 @@ export default definePluginEntry({
});
```
Los manejadores de hooks se ejecutan secuencialmente en orden descendente de `priority`. Los hooks
con la misma prioridad conservan el orden de registro.
Los manejadores de hooks se ejecutan secuencialmente en orden descendente de `priority`. Los hooks con la misma prioridad
mantienen el orden de registro.
`api.on(name, handler, opts?)` acepta:
- `priority` — orden de manejadores (los valores más altos se ejecutan primero).
- `timeoutMs` — presupuesto opcional por hook. Cuando se define, el ejecutor de hooks aborta ese
manejador después de que transcurre el presupuesto y continúa con el siguiente, en lugar de
permitir que una configuración lenta o el trabajo de recuperación consuman el tiempo de espera
de modelo configurado por el llamador. Omítelo para usar el tiempo de espera predeterminado de observación/decisión que el
- `priority` — orden del manejador (los valores más altos se ejecutan primero).
- `timeoutMs` — presupuesto opcional por hook. Cuando se establece, el ejecutor de hooks aborta ese
manejador después de que el presupuesto transcurre y continúa con el siguiente, en vez de
permitir que una configuración lenta o trabajo de recuperación consuma el tiempo de espera de modelo
configurado por el llamador. Omítelo para usar el tiempo de espera predeterminado de observación/decisión que el
ejecutor de hooks aplica de forma genérica.
Los operadores también pueden definir presupuestos de hooks sin parchear el código del plugin:
Los operadores también pueden establecer presupuestos de hooks sin parchear el código del plugin:
```json
{
@ -88,71 +88,71 @@ Los operadores también pueden definir presupuestos de hooks sin parchear el có
}
```
`hooks.timeouts.<hookName>` anula `hooks.timeoutMs`, que anula el valor
`api.on(..., { timeoutMs })` escrito por el plugin. Cada valor configurado debe
ser un entero positivo no mayor de 600000 milisegundos. Prefiere las
anulaciones por hook para hooks lentos conocidos, de modo que un plugin no reciba un presupuesto más largo
`hooks.timeouts.<hookName>` reemplaza a `hooks.timeoutMs`, que reemplaza el valor
`api.on(..., { timeoutMs })` definido por el plugin. Cada valor configurado debe
ser un entero positivo no mayor que 600000 milisegundos. Prefiere reemplazos por hook
para hooks lentos conocidos, de modo que un plugin no obtenga un presupuesto más largo
en todas partes.
Cada hook recibe `event.context.pluginConfig`, la configuración resuelta para el
plugin que registró ese manejador. Úsala para decisiones de hooks que necesiten
plugin que registró ese manejador. Úsala para decisiones de hook que necesiten
opciones actuales del plugin; OpenClaw la inyecta por manejador sin mutar el
objeto de evento compartido que ven otros plugins.
## Catálogo de hooks
Los hooks se agrupan por la superficie que extienden. Los nombres en **negrita** aceptan un
resultado de decisión (bloquear, cancelar, anular o requerir aprobación); todos los demás son
resultado de decisión (bloquear, cancelar, reemplazar o requerir aprobación); todos los demás son
solo de observación.
**Turno del agente**
- `before_model_resolve` — anular el proveedor o modelo antes de que se carguen los mensajes de sesión
- `agent_turn_prepare` — consumir inyecciones de turno de plugin en cola y agregar contexto del mismo turno antes de los hooks de prompt
- `before_prompt_build` — agregar contexto dinámico o texto de prompt del sistema antes de la llamada al modelo
- `before_model_resolve` — reemplaza el proveedor o el modelo antes de que se carguen los mensajes de sesión
- `agent_turn_prepare` — consume inyecciones de turno de plugin en cola y agrega contexto del mismo turno antes de los hooks de prompt
- `before_prompt_build` — agrega contexto dinámico o texto de prompt de sistema antes de la llamada al modelo
- `before_agent_start` — fase combinada solo por compatibilidad; prefiere los dos hooks anteriores
- **`before_agent_reply`** — interrumpir el turno del modelo con una respuesta sintética o silencio
- **`before_agent_finalize`** — inspeccionar la respuesta final natural y solicitar un pase más del modelo
- `agent_end` — observar mensajes finales, estado de éxito y duración de ejecución
- `heartbeat_prompt_contribution` — agregar contexto solo de Heartbeat para plugins de monitorización en segundo plano y ciclo de vida
- **`before_agent_reply`** — interrumpe el turno del modelo con una respuesta sintética o silencio
- **`before_agent_finalize`** — inspecciona la respuesta final natural y solicita una pasada más del modelo
- `agent_end` — observa mensajes finales, estado de éxito y duración de la ejecución
- `heartbeat_prompt_contribution` — agrega contexto solo de Heartbeat para plugins de monitor en segundo plano y ciclo de vida
**Observación de conversación**
**Observación de la conversación**
- `model_call_started` / `model_call_ended` — observar metadatos saneados de llamadas de proveedor/modelo, temporización, resultado y hashes acotados de id. de solicitud sin contenido de prompt ni respuesta
- `llm_input` — observar la entrada del proveedor (prompt del sistema, prompt, historial)
- `llm_output` — observar la salida del proveedor
- `model_call_started` / `model_call_ended` — observa metadatos saneados de llamadas a proveedor/modelo, tiempos, resultado y hashes acotados de ID de solicitud sin contenido de prompt ni de respuesta
- `llm_input` — observa la entrada del proveedor (prompt de sistema, prompt, historial)
- `llm_output` — observa la salida del proveedor
**Herramientas**
- **`before_tool_call`** — reescribir parámetros de herramienta, bloquear la ejecución o requerir aprobación
- `after_tool_call` — observar resultados de herramienta, errores y duración
- **`tool_result_persist`** — reescribir el mensaje del asistente producido a partir de un resultado de herramienta
- **`before_message_write`** — inspeccionar o bloquear la escritura de un mensaje en curso (poco frecuente)
- **`before_tool_call`** — reescribe parámetros de herramienta, bloquea la ejecución o requiere aprobación
- `after_tool_call` — observa resultados de herramientas, errores y duración
- **`tool_result_persist`** — reescribe el mensaje del asistente producido a partir de un resultado de herramienta
- **`before_message_write`** — inspecciona o bloquea una escritura de mensaje en curso (raro)
**Mensajes y entrega**
- **`inbound_claim`** — reclamar un mensaje entrante antes del enrutamiento del agente (respuestas sintéticas)
- `message_received` — observar contenido entrante, remitente, hilo y metadatos
- **`message_sending`** — reescribir contenido saliente o cancelar la entrega
- `message_sent` — observar éxito o fallo de entrega saliente
- **`before_dispatch`** — inspeccionar o reescribir un despacho saliente antes de la entrega al canal
- **`reply_dispatch`** — participar en la canalización final de despacho de respuesta
- **`inbound_claim`** — reclama un mensaje entrante antes del enrutamiento del agente (respuestas sintéticas)
- `message_received` — observa contenido entrante, remitente, hilo y metadatos
- **`message_sending`** — reescribe contenido saliente o cancela la entrega
- `message_sent` — observa el éxito o fallo de la entrega saliente
- **`before_dispatch`** — inspecciona o reescribe un despacho saliente antes de la entrega al canal
- **`reply_dispatch`** — participa en la canalización final de despacho de respuestas
**Sesiones y Compaction**
- `session_start` / `session_end` — rastrear límites del ciclo de vida de sesión
- `before_compaction` / `after_compaction` — observar o anotar ciclos de Compaction
- `before_reset` — observar eventos de restablecimiento de sesión (`/reset`, restablecimientos programáticos)
- `session_start` / `session_end` — rastrea límites del ciclo de vida de la sesión
- `before_compaction` / `after_compaction` — observa o anota ciclos de Compaction
- `before_reset` — observa eventos de restablecimiento de sesión (`/reset`, restablecimientos programáticos)
**Subagentes**
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — coordinar el enrutamiento de subagentes y la entrega de finalización
- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — coordina el enrutamiento de subagentes y la entrega de finalización
**Ciclo de vida**
- `gateway_start` / `gateway_stop` — iniciar o detener servicios propiedad del plugin con el Gateway
- `cron_changed` — observar cambios del ciclo de vida de cron propiedad del gateway (agregado, actualizado, eliminado, iniciado, finalizado, programado)
- **`before_install`** — inspeccionar escaneos de instalación de skill o plugin y bloquear opcionalmente
- `gateway_start` / `gateway_stop` — inicia o detiene servicios propiedad del plugin con el Gateway
- `cron_changed` — observa cambios de ciclo de vida de Cron propiedad del gateway (agregado, actualizado, eliminado, iniciado, finalizado, programado)
- **`before_install`** — inspecciona análisis de instalación de Skill o plugin y bloquea opcionalmente
## Política de llamadas a herramientas
@ -163,7 +163,7 @@ solo de observación.
- `event.runId` opcional
- `event.toolCallId` opcional
- campos de contexto como `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`,
`ctx.runId`, `ctx.jobId` (definido en ejecuciones impulsadas por cron) y `ctx.trace` de diagnóstico
`ctx.runId`, `ctx.jobId` (establecido en ejecuciones impulsadas por cron) y `ctx.trace` de diagnóstico
Puede devolver:
@ -189,18 +189,18 @@ type BeforeToolCallResult = {
Reglas:
- `block: true` es terminal y omite los manejadores de menor prioridad.
- `block: false` se trata como si no hubiera decisión.
- `params` reescribe los parámetros de herramienta para la ejecución.
- `block: false` se trata como ausencia de decisión.
- `params` reescribe los parámetros de la herramienta para la ejecución.
- `requireApproval` pausa la ejecución del agente y pregunta al usuario mediante aprobaciones de plugin. El comando `/approve` puede aprobar tanto aprobaciones de exec como de plugin.
- Un `block: true` de menor prioridad todavía puede bloquear después de que un hook de mayor prioridad
- Un `block: true` de menor prioridad aún puede bloquear después de que un hook de mayor prioridad
haya solicitado aprobación.
- `onResolution` recibe la decisión de aprobación resuelta — `allow-once`,
- `onResolution` recibe la decisión de aprobación resuelta: `allow-once`,
`allow-always`, `deny`, `timeout` o `cancelled`.
Los plugins incluidos que necesiten políticas a nivel de host pueden registrar políticas de herramientas de confianza
con `api.registerTrustedToolPolicy(...)`. Estas se ejecutan antes de los hooks
`before_tool_call` ordinarios y antes de decisiones de plugins externos. Úsalas solo
para barreras de confianza del host, como política del espacio de trabajo, aplicación de presupuesto o
Los plugins incluidos que necesitan política a nivel de host pueden registrar políticas de herramientas de confianza
con `api.registerTrustedToolPolicy(...)`. Estas se ejecutan antes que los hooks
`before_tool_call` ordinarios y antes que las decisiones de plugins externos. Úsalas solo
para controles de confianza del host como política de espacio de trabajo, cumplimiento de presupuesto o
seguridad de flujos de trabajo reservados. Los plugins externos deben usar hooks `before_tool_call`
normales.
@ -212,27 +212,27 @@ no como contenido de prompt:
- OpenClaw elimina `toolResult.details` antes de la reproducción del proveedor y la entrada de Compaction
para que los metadatos no se conviertan en contexto del modelo.
- Las entradas de sesión persistidas conservan solo `details` acotados. Los detalles sobredimensionados se
- Las entradas de sesión persistidas conservan solo `details` acotados. Los detalles demasiado grandes se
reemplazan por un resumen compacto y `persistedDetailsTruncated: true`.
- `tool_result_persist` y `before_message_write` se ejecutan antes del límite final
de persistencia. Aun así, los hooks deben mantener pequeños los `details` devueltos y evitar
colocar texto relevante para el prompt solo en `details`; coloca la salida de herramienta visible para el modelo
colocar texto relevante para el prompt solo en `details`; pon la salida de herramienta visible para el modelo
en `content`.
## Hooks de prompt y modelo
Usa los hooks específicos de fase para plugins nuevos:
- `before_model_resolve`: recibe solo el prompt actual y metadatos de adjuntos.
- `before_model_resolve`: recibe solo el prompt actual y los metadatos de adjuntos.
Devuelve `providerOverride` o `modelOverride`.
- `agent_turn_prepare`: recibe el prompt actual, mensajes de sesión preparados
y cualquier inyección en cola exactamente una vez drenada para esta sesión. Devuelve
- `agent_turn_prepare`: recibe el prompt actual, los mensajes de sesión preparados
y cualquier inyección en cola de exactamente una vez drenada para esta sesión. Devuelve
`prependContext` o `appendContext`.
- `before_prompt_build`: recibe el prompt actual y los mensajes de sesión.
Devuelve `prependContext`, `appendContext`, `systemPrompt`,
`prependSystemContext` o `appendSystemContext`.
- `heartbeat_prompt_contribution`: se ejecuta solo para turnos de Heartbeat y devuelve
`prependContext` o `appendContext`. Está pensado para monitores en segundo plano
`prependContext` o `appendContext`. Está destinado a monitores en segundo plano
que necesitan resumir el estado actual sin cambiar turnos iniciados por el usuario.
`before_agent_start` permanece por compatibilidad. Prefiere los hooks explícitos anteriores
@ -240,37 +240,53 @@ para que tu plugin no dependa de una fase combinada heredada.
`before_agent_start` y `agent_end` incluyen `event.runId` cuando OpenClaw puede
identificar la ejecución activa. El mismo valor también está disponible en `ctx.runId`.
Las ejecuciones impulsadas por Cron también exponen `ctx.jobId` (el id del trabajo cron de origen) para que
los hooks de plugin puedan delimitar métricas, efectos secundarios o estado a un trabajo programado
Las ejecuciones impulsadas por Cron también exponen `ctx.jobId` (el ID del trabajo cron de origen) para que
los hooks de plugin puedan limitar métricas, efectos secundarios o estado a un trabajo programado
específico.
Para ejecuciones originadas en canales, `ctx.messageProvider` es la superficie de proveedor, como
Para ejecuciones originadas por canal, `ctx.messageProvider` es la superficie del proveedor, como
`discord` o `telegram`, mientras que `ctx.channelId` es el identificador de destino de la conversación
cuando OpenClaw puede derivar uno de la clave de sesión o los metadatos
de entrega.
cuando OpenClaw puede derivarlo de la clave de sesión o de los metadatos de entrega.
`agent_end` es un hook de observación y se ejecuta de forma fire-and-forget después del turno. El
ejecutor de hooks aplica un tiempo de espera de 30 segundos para que un plugin o endpoint
de embeddings bloqueado no pueda dejar la promesa del hook pendiente para siempre. Un tiempo de espera se registra y
OpenClaw continúa; no cancela el trabajo de red propiedad del plugin salvo que el
`agent_end` es un hook de observación y se ejecuta sin esperar resultado después del turno. El
ejecutor de hooks aplica un tiempo de espera de 30 segundos para que un plugin bloqueado o un endpoint de embeddings
no pueda dejar la promesa del hook pendiente para siempre. Se registra un tiempo de espera y
OpenClaw continúa; no cancela trabajo de red propiedad del plugin a menos que el
plugin también use su propia señal de aborto.
Usa `model_call_started` y `model_call_ended` para telemetría de llamadas de proveedor
que no debería recibir prompts, historial, respuestas, encabezados, cuerpos de solicitud ni id. de solicitud de proveedor en bruto. Estos hooks incluyen metadatos estables como
`runId`, `callId`, `provider`, `model`, `api`/`transport` opcional,
`durationMs`/`outcome` terminal y `upstreamRequestIdHash` cuando OpenClaw puede derivar un
hash acotado de id. de solicitud de proveedor.
Usa `model_call_started` y `model_call_ended` para telemetría de llamadas a proveedor
que no debe recibir prompts sin procesar, historial, respuestas, encabezados, cuerpos de solicitud
ni IDs de solicitud del proveedor. Estos hooks incluyen metadatos estables como
`runId`, `callId`, `provider`, `model`, `api`/`transport` opcionales, `durationMs`/`outcome`
terminales y `upstreamRequestIdHash` cuando OpenClaw puede derivar un hash acotado de ID de solicitud
del proveedor.
`before_agent_finalize` se ejecuta solo cuando un arnés está a punto de aceptar una
respuesta final natural del asistente. No es la ruta de cancelación de `/stop` y no
se ejecuta cuando el usuario aborta un turno. Devuelve `{ action: "revise", reason }` para pedir
al arnés un pase más del modelo antes de la finalización, `{ action:
respuesta final natural del asistente. No es la ruta de cancelación de `/stop` y no se
ejecuta cuando el usuario aborta un turno. Devuelve `{ action: "revise", reason }` para pedirle
al arnés una pasada más del modelo antes de la finalización, `{ action:
"finalize", reason? }` para forzar la finalización, u omite un resultado para continuar.
Los hooks nativos `Stop` de Codex se retransmiten a este hook como decisiones
Los hooks `Stop` nativos de Codex se retransmiten a este hook como decisiones
`before_agent_finalize` de OpenClaw.
Los plugins no incluidos que necesiten `llm_input`, `llm_output`,
`before_agent_finalize` o `agent_end` deben definir:
Al devolver `action: "revise"`, los plugins pueden incluir metadatos `retry` para hacer
que la pasada adicional del modelo sea acotada y segura para reproducción:
```typescript
type BeforeAgentFinalizeRetry = {
instruction: string;
idempotencyKey?: string;
maxAttempts?: number;
};
```
`instruction` se agrega al motivo de revisión enviado al arnés.
`idempotencyKey` permite al host contar reintentos para la misma solicitud de plugin a través de
decisiones de finalización equivalentes, y `maxAttempts` limita cuántas pasadas adicionales el
host permitirá antes de continuar con la respuesta final natural.
Los plugins no incluidos que necesitan `llm_input`, `llm_output`,
`before_agent_finalize` o `agent_end` deben establecer:
```json
{
@ -286,43 +302,42 @@ Los plugins no incluidos que necesiten `llm_input`, `llm_output`,
}
```
Los hooks que mutan prompts y las inyecciones duraderas de siguiente turno pueden deshabilitarse por plugin
Los hooks que mutan prompts y las inyecciones duraderas para el siguiente turno pueden deshabilitarse por plugin
con `plugins.entries.<id>.hooks.allowPromptInjection=false`.
### Extensiones de sesión e inyecciones de siguiente turno
### Extensiones de sesión e inyecciones para el siguiente turno
Los plugins de flujo de trabajo pueden persistir un estado de sesión pequeño compatible con JSON con
Los plugins de flujo de trabajo pueden persistir un pequeño estado de sesión compatible con JSON con
`api.registerSessionExtension(...)` y actualizarlo mediante el método
`sessions.pluginPatch` del Gateway. Las filas de sesión proyectan el estado de extensión registrado
mediante `pluginExtensions`, lo que permite que Control UI y otros clientes rendericen
estado propiedad del plugin sin conocer los detalles internos del plugin.
mediante `pluginExtensions`, lo que permite que Control UI y otros clientes representen
el estado propiedad del plugin sin conocer los componentes internos del plugin.
Usa `api.enqueueNextTurnInjection(...)` cuando un plugin necesite contexto duradero para
llegar al siguiente turno del modelo exactamente una vez. OpenClaw vacía las inyecciones en cola antes de
los hooks de prompt, descarta las inyecciones vencidas y deduplica por `idempotencyKey`
por plugin. Esta es la interfaz adecuada para reanudaciones de aprobación, resúmenes de políticas,
Usa `api.enqueueNextTurnInjection(...)` cuando un plugin necesite que el contexto duradero
llegue al siguiente turno del modelo exactamente una vez. OpenClaw drena las inyecciones en cola antes de
los hooks de prompt, descarta las inyecciones caducadas y deduplica por `idempotencyKey`
por plugin. Este es el seam correcto para reanudaciones de aprobación, resúmenes de políticas,
deltas de monitores en segundo plano y continuaciones de comandos que deben ser visibles para
el modelo en el siguiente turno, pero no deben convertirse en texto permanente del prompt del sistema.
La semántica de limpieza forma parte del contrato. La limpieza de extensión de sesión y
las callbacks de limpieza del ciclo de vida del runtime reciben `reset`, `delete`, `disable` o
`restart`. El host elimina el estado persistente de extensión de sesión del plugin propietario
y las inyecciones pendientes para el siguiente turno en reset/delete/disable; restart conserva
el estado duradero de la sesión, mientras que las callbacks de limpieza permiten que los plugins liberen tareas
del planificador, contexto de ejecución y otros recursos fuera de banda de la generación anterior
del runtime.
Las semánticas de limpieza forman parte del contrato. La limpieza de extensión de sesión y
los callbacks de limpieza del ciclo de vida de runtime reciben `reset`, `delete`, `disable` o
`restart`. El host elimina el estado persistente de extensión de sesión
del plugin propietario y las inyecciones pendientes del siguiente turno para reset/delete/disable; restart conserva
el estado duradero de sesión mientras los callbacks de limpieza permiten que los plugins liberen trabajos del planificador,
contexto de ejecución y otros recursos fuera de banda de la antigua generación de runtime.
## Hooks de mensajes
Usa hooks de mensajes para enrutamiento a nivel de canal y políticas de entrega:
Usa hooks de mensajes para el enrutamiento a nivel de canal y la política de entrega:
- `message_received`: observa contenido entrante, remitente, `threadId`, `messageId`,
- `message_received`: observa el contenido entrante, remitente, `threadId`, `messageId`,
`senderId`, correlación opcional de ejecución/sesión y metadatos.
- `message_sending`: reescribe `content` o devuelve `{ cancel: true }`.
- `message_sent`: observa el éxito o fallo final.
Para respuestas TTS solo de audio, `content` puede contener la transcripción hablada oculta
aunque la carga útil del canal no tenga texto/subtítulo visible. Reescribir ese
incluso cuando la carga útil del canal no tiene texto/subtítulo visible. Reescribir ese
`content` actualiza solo la transcripción visible para el hook; no se renderiza como
subtítulo multimedia.
@ -331,42 +346,43 @@ Los contextos de hooks de mensajes exponen campos de correlación estables cuand
`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` y `ctx.callDepth`. Prefiere
estos campos de primera clase antes de leer metadatos heredados.
Prefiere los campos tipados `threadId` y `replyToId` antes de usar metadatos específicos
del canal.
Prefiere los campos tipados `threadId` y `replyToId` antes de usar metadatos
específicos del canal.
Reglas de decisión:
- `message_sending` con `cancel: true` es terminal.
- `message_sending` con `cancel: false` se trata como sin decisión.
- El `content` reescrito continúa hacia hooks de menor prioridad salvo que un hook posterior
- El `content` reescrito continúa hacia hooks de menor prioridad a menos que un hook posterior
cancele la entrega.
## Hooks de instalación
`before_install` se ejecuta después del escaneo integrado para instalaciones de Skills y plugins.
`before_install` se ejecuta después del análisis integrado de instalaciones de Skills y plugins.
Devuelve hallazgos adicionales o `{ block: true, blockReason }` para detener la
instalación.
`block: true` es terminal. `block: false` se trata como sin decisión.
## Ciclo de vida de Gateway
## Ciclo de vida del Gateway
Usa `gateway_start` para servicios de plugin que necesitan estado propiedad de Gateway. El
Usa `gateway_start` para servicios de plugins que necesitan estado propiedad del Gateway. El
contexto expone `ctx.config`, `ctx.workspaceDir` y `ctx.getCron?.()` para
inspección y actualizaciones de Cron. Usa `gateway_stop` para limpiar recursos
inspección y actualizaciones de cron. Usa `gateway_stop` para limpiar recursos
de larga duración.
No dependas del hook interno `gateway:startup` para servicios de runtime propiedad del plugin.
No dependas del hook interno `gateway:startup` para servicios de runtime
propiedad del plugin.
`cron_changed` se dispara para eventos del ciclo de vida de Cron propiedad de Gateway con una carga útil
de evento tipada que cubre motivos `added`, `updated`, `removed`, `started`, `finished`
`cron_changed` se activa para eventos del ciclo de vida de cron propiedad del gateway con una carga útil
de evento tipada que cubre los motivos `added`, `updated`, `removed`, `started`, `finished`
y `scheduled`. El evento lleva una instantánea `PluginHookGatewayCronJob`
(incluidos `state.nextRunAtMs`, `state.lastRunStatus` y
`state.lastError` cuando está presente), además de un `PluginHookGatewayCronDeliveryStatus`
de `not-requested` | `delivered` | `not-delivered` | `unknown`. Los eventos
removed aún llevan la instantánea del trabajo eliminado para que los planificadores externos puedan
`state.lastError` cuando están presentes), además de un `PluginHookGatewayCronDeliveryStatus`
de `not-requested` | `delivered` | `not-delivered` | `unknown`. Los eventos eliminados
siguen llevando la instantánea del trabajo eliminado para que los planificadores externos puedan
reconciliar el estado. Usa `ctx.getCron?.()` y `ctx.config` del contexto de runtime
al sincronizar planificadores de activación externos, y mantén OpenClaw como la
al sincronizar planificadores externos de activación, y conserva OpenClaw como
fuente de verdad para comprobaciones de vencimiento y ejecución.
## Próximas obsolescencias
@ -374,27 +390,27 @@ fuente de verdad para comprobaciones de vencimiento y ejecución.
Algunas superficies adyacentes a hooks están obsoletas, pero siguen siendo compatibles. Migra
antes de la próxima versión mayor:
- **Sobres de canal en texto plano** en handlers `inbound_claim` y `message_received`.
- **Sobres de canal en texto sin formato** en controladores `inbound_claim` y `message_received`.
Lee `BodyForAgent` y los bloques estructurados de contexto de usuario
en lugar de analizar texto de sobre plano. Consulta
[Sobres de canal en texto plano → BodyForAgent](/es/plugins/sdk-migration#active-deprecations).
- **`before_agent_start`** se mantiene por compatibilidad. Los plugins nuevos deben usar
en lugar de analizar texto plano de sobre. Consulta
[Sobres de canal en texto sin formato → BodyForAgent](/es/plugins/sdk-migration#active-deprecations).
- **`before_agent_start`** se mantiene por compatibilidad. Los nuevos plugins deben usar
`before_model_resolve` y `before_prompt_build` en lugar de la fase
combinada.
- **`onResolution` en `before_tool_call`** ahora usa la unión tipada
`PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` /
`timeout` / `cancelled`) en lugar de un `string` de formato libre.
Para la lista completa — registro de capacidad de memoria, perfil de razonamiento del proveedor,
proveedores de autenticación externos, tipos de descubrimiento de proveedores, accesores del runtime
de tareas y el cambio de nombre `command-auth` → `command-status` — consulta
[Migración de Plugin SDK → Obsolescencias activas](/es/plugins/sdk-migration#active-deprecations).
Para la lista completa — registro de capacidad de memoria, perfil de pensamiento
del proveedor, proveedores de autenticación externos, tipos de descubrimiento de proveedor, accesores de runtime
de tareas y el cambio de nombre de `command-auth` → `command-status` — consulta
[Migración del SDK de Plugin → Obsolescencias activas](/es/plugins/sdk-migration#active-deprecations).
## Relacionado
- [Migración de Plugin SDK](/es/plugins/sdk-migration) — obsolescencias activas y calendario de eliminación
- [Creación de plugins](/es/plugins/building-plugins)
- [Resumen de Plugin SDK](/es/plugins/sdk-overview)
- [Migración del SDK de Plugin](/es/plugins/sdk-migration) — obsolescencias activas y cronograma de eliminación
- [Crear plugins](/es/plugins/building-plugins)
- [Resumen del SDK de Plugin](/es/plugins/sdk-overview)
- [Puntos de entrada de Plugin](/es/plugins/sdk-entrypoints)
- [Hooks internos](/es/automation/hooks)
- [Detalles internos de la arquitectura de Plugin](/es/plugins/architecture-internals)
- [Componentes internos de la arquitectura de Plugin](/es/plugins/architecture-internals)

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

@ -1,32 +1,32 @@
---
read_when:
- Debe saber desde qué subruta del SDK importar
- Quieres una referencia de todos los métodos de registro en OpenClawPluginApi
- Quieres una referencia de todos los métodos de registro de OpenClawPluginApi
- Estás buscando una exportación específica del SDK
sidebarTitle: Plugin SDK overview
summary: Mapa de importaciones, referencia de la API de registro y arquitectura del SDK
title: Descripción general del SDK de Plugin
x-i18n:
generated_at: "2026-05-02T05:33:10Z"
generated_at: "2026-05-04T18:24:51Z"
model: gpt-5.5
provider: openai
source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69
source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127
source_path: plugins/sdk-overview.md
workflow: 16
---
El SDK de plugins es el contrato tipado entre los plugins y el núcleo. Esta página es la
El SDK de Plugin es el contrato tipado entre plugins y el núcleo. Esta página es la
referencia de **qué importar** y **qué puedes registrar**.
<Note>
Esta página es para autores de plugins que usan `openclaw/plugin-sdk/*` dentro de
OpenClaw. Para apps externas, scripts, paneles, trabajos de CI y extensiones de IDE
que quieren ejecutar agentes a través del Gateway, usa en su lugar el
[SDK de apps de OpenClaw](/es/concepts/openclaw-sdk) y el paquete `@openclaw/sdk`.
que quieran ejecutar agentes a través del Gateway, usa en su lugar el
[SDK de OpenClaw App](/es/concepts/openclaw-sdk) y el paquete `@openclaw/sdk`.
</Note>
<Tip>
¿Buscas una guía práctica? Empieza con [Crear plugins](/es/plugins/building-plugins), usa [Plugins de canal](/es/plugins/sdk-channel-plugins) para plugins de canal, [Plugins de proveedor](/es/plugins/sdk-provider-plugins) para plugins de proveedor y [Hooks de Plugin](/es/plugins/hooks) para plugins de herramientas o hooks de ciclo de vida.
¿Buscas una guía práctica? Empieza con [Crear plugins](/es/plugins/building-plugins), usa [Plugins de canal](/es/plugins/sdk-channel-plugins) para plugins de canal, [Plugins de proveedor](/es/plugins/sdk-provider-plugins) para plugins de proveedor y [Hooks de Plugin](/es/plugins/hooks) para plugins de hooks de herramienta o de ciclo de vida.
</Tip>
## Convención de importación
@ -39,139 +39,139 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Cada subruta es un módulo pequeño y autónomo. Esto mantiene el arranque rápido y
evita problemas de dependencias circulares. Para ayudantes de entrada/compilación
específicos de canal, prefiere `openclaw/plugin-sdk/channel-core`; reserva
`openclaw/plugin-sdk/core` para la superficie general más amplia y los ayudantes
compartidos como `buildChannelConfigSchema`.
evita problemas de dependencias circulares. Para helpers de entrada/compilación específicos de canal,
prefiere `openclaw/plugin-sdk/channel-core`; reserva `openclaw/plugin-sdk/core` para
la superficie general más amplia y helpers compartidos como
`buildChannelConfigSchema`.
Para la configuración de canal, publica el JSON Schema propiedad del canal mediante
`openclaw.plugin.json#channelConfigs`. La subruta `plugin-sdk/channel-config-schema`
es para primitivas de esquema compartidas y el constructor genérico. Los plugins
incluidos de OpenClaw usan `plugin-sdk/bundled-channel-config-schema` para esquemas
conservados de canales incluidos. Las exportaciones de compatibilidad obsoletas
permanecen en `plugin-sdk/channel-config-schema-legacy`; ninguna subruta de esquema
incluido es un patrón para plugins nuevos.
retenidos de canales incluidos. Las exportaciones de compatibilidad obsoletas permanecen en
`plugin-sdk/channel-config-schema-legacy`; ninguna subruta de esquema incluido es un
patrón para plugins nuevos.
<Warning>
No importes costuras de conveniencia con marca de proveedor o canal (por ejemplo
No importes costuras de conveniencia con marca de proveedor o canal (por ejemplo,
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
Los plugins incluidos componen subrutas genéricas del SDK dentro de sus propios
barriles `api.ts` / `runtime-api.ts`; los consumidores del núcleo deben usar esos
barriles locales del Plugin o añadir un contrato genérico estrecho del SDK cuando
la necesidad sea realmente transversal entre canales.
Los plugins incluidos componen subrutas genéricas del SDK dentro de sus propios barrels
`api.ts` / `runtime-api.ts`; los consumidores del núcleo deberían usar esos barrels locales
del Plugin o añadir un contrato genérico estrecho del SDK cuando la necesidad sea realmente
multicanal.
Un conjunto pequeño de costuras auxiliares de plugins incluidos todavía aparece en
el mapa de exportación generado cuando tienen uso rastreado por el propietario.
Existen solo para mantenimiento de plugins incluidos y no se recomiendan como rutas
de importación para nuevos plugins de terceros.
Un pequeño conjunto de costuras auxiliares de plugins incluidos todavía aparece en el mapa de exportación
generado cuando tienen uso rastreado por el propietario. Existen solo para el mantenimiento de plugins
incluidos y no son rutas de importación recomendadas para nuevos plugins de terceros.
`openclaw/plugin-sdk/discord` y `openclaw/plugin-sdk/telegram-account` también se
conservan como fachadas de compatibilidad obsoletas para uso rastreado por el
propietario. No copies esas rutas de importación en plugins nuevos; usa en su lugar
ayudantes de runtime inyectados y subrutas genéricas del SDK de canal.
conservan como fachadas de compatibilidad obsoletas para uso rastreado por el propietario. No copies
esas rutas de importación en plugins nuevos; usa helpers de runtime inyectados y
subrutas genéricas del SDK de canal en su lugar.
</Warning>
## Referencia de subrutas
El SDK de plugins se expone como un conjunto de subrutas estrechas agrupadas por área
(entrada de Plugin, canal, proveedor, autenticación, runtime, capacidad, memoria y
ayudantes reservados de plugins incluidos). Para ver el catálogo completo, agrupado y
enlazado, consulta [Subrutas del SDK de plugins](/es/plugins/sdk-subpaths).
El SDK de Plugin se expone como un conjunto de subrutas estrechas agrupadas por área (entrada de Plugin,
canal, proveedor, autenticación, runtime, capacidad, memoria y helpers reservados
para plugins incluidos). Para el catálogo completo, agrupado y enlazado, consulta
[Subrutas del SDK de Plugin](/es/plugins/sdk-subpaths).
La lista generada de más de 200 subrutas vive en `scripts/lib/plugin-sdk-entrypoints.json`.
## API de registro
La devolución de llamada `register(api)` recibe un objeto `OpenClawPluginApi` con estos
El callback `register(api)` recibe un objeto `OpenClawPluginApi` con estos
métodos:
### Registro de capacidades
| Método | Qué registra |
| ------------------------------------------------ | --------------------------------------- |
| `api.registerProvider(...)` | Inferencia de texto (LLM) |
| Método | Qué registra |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Inferencia de texto (LLM) |
| `api.registerAgentHarness(...)` | Ejecutor de agente experimental de bajo nivel |
| `api.registerCliBackend(...)` | Backend de inferencia de CLI local |
| `api.registerChannel(...)` | Canal de mensajería |
| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT |
| `api.registerCliBackend(...)` | Backend local de inferencia de CLI |
| `api.registerChannel(...)` | Canal de mensajería |
| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real por streaming |
| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex |
| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video |
| `api.registerImageGenerationProvider(...)` | Generación de imágenes |
| `api.registerMusicGenerationProvider(...)` | Generación de música |
| `api.registerVideoGenerationProvider(...)` | Generación de video |
| `api.registerWebFetchProvider(...)` | Proveedor de obtención / extracción web |
| `api.registerWebSearchProvider(...)` | Búsqueda web |
| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz dúplex en tiempo real |
| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video |
| `api.registerImageGenerationProvider(...)` | Generación de imágenes |
| `api.registerMusicGenerationProvider(...)` | Generación de música |
| `api.registerVideoGenerationProvider(...)` | Generación de video |
| `api.registerWebFetchProvider(...)` | Proveedor de obtención / scraping web |
| `api.registerWebSearchProvider(...)` | Búsqueda web |
### Herramientas y comandos
| Método | Qué registra |
| ------------------------------ | ------------------------------------------------- |
| Método | Qué registra |
| ------------------------------ | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Herramienta de agente (requerida o `{ optional: true }`) |
| `api.registerCommand(def)` | Comando personalizado (omite el LLM) |
| `api.registerCommand(def)` | Comando personalizado (omite el LLM) |
Los comandos de Plugin pueden establecer `agentPromptGuidance` cuando el agente necesita una pista breve de enrutamiento propiedad del comando. Mantén ese texto sobre el comando en sí; no añadas política específica de proveedor o Plugin a los constructores de prompts del núcleo.
Los comandos de Plugin pueden establecer `agentPromptGuidance` cuando el agente necesita una
pista breve de enrutamiento propiedad del comando. Mantén ese texto centrado en el propio comando; no añadas
política específica de proveedor o Plugin a los constructores de prompts del núcleo.
### Infraestructura
| Método | Qué registra |
| ---------------------------------------------- | -------------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook de evento |
| `api.registerHttpRoute(params)` | Endpoint HTTP del Gateway |
| `api.registerGatewayMethod(name, handler)` | Método RPC del Gateway |
| `api.registerGatewayDiscoveryService(service)` | Anunciante de descubrimiento del Gateway local |
| `api.registerCli(registrar, opts?)` | Subcomando de CLI |
| `api.registerService(service)` | Servicio en segundo plano |
| `api.registerInteractiveHandler(registration)` | Manejador interactivo |
| `api.registerAgentToolResultMiddleware(...)` | Middleware de resultado de herramienta en runtime |
| Método | Qué registra |
| ---------------------------------------------- | ----------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook de evento |
| `api.registerHttpRoute(params)` | Endpoint HTTP del Gateway |
| `api.registerGatewayMethod(name, handler)` | Método RPC del Gateway |
| `api.registerGatewayDiscoveryService(service)` | Anunciador local de descubrimiento del Gateway |
| `api.registerCli(registrar, opts?)` | Subcomando de CLI |
| `api.registerService(service)` | Servicio en segundo plano |
| `api.registerInteractiveHandler(registration)` | Manejador interactivo |
| `api.registerAgentToolResultMiddleware(...)` | Middleware de runtime para resultados de herramientas |
| `api.registerMemoryPromptSupplement(builder)` | Sección aditiva de prompt adyacente a memoria |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de búsqueda/lectura de memoria |
### Hooks de host para plugins de flujo de trabajo
Los hooks de host son las costuras del SDK para plugins que necesitan participar en el
ciclo de vida del host en lugar de limitarse a añadir un proveedor, canal o herramienta. Son
contratos genéricos; el modo Plan puede usarlos, pero también los flujos de trabajo de
aprobación, puertas de política de espacio de trabajo, monitores en segundo plano,
asistentes de configuración y plugins complementarios de UI.
Los hooks de host son las costuras del SDK para plugins que necesitan participar en el ciclo de vida del host
en lugar de solo añadir un proveedor, canal o herramienta. Son
contratos genéricos; Plan Mode puede usarlos, pero también pueden hacerlo flujos de aprobación,
compuertas de política de workspace, monitores en segundo plano, asistentes de configuración y plugins complementarios de UI.
| Método | Contrato que posee |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerSessionExtension(...)` | Estado de sesión propiedad del Plugin, compatible con JSON y proyectado mediante sesiones del Gateway |
| Método | Contrato que posee |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerSessionExtension(...)` | Estado de sesión propiedad del Plugin, compatible con JSON, proyectado mediante sesiones del Gateway |
| `api.enqueueNextTurnInjection(...)` | Contexto duradero exactamente una vez inyectado en el siguiente turno del agente para una sesión |
| `api.registerTrustedToolPolicy(...)` | Política de herramientas previa al Plugin incluida/de confianza que puede bloquear o reescribir parámetros de herramienta |
| `api.registerToolMetadata(...)` | Metadatos de visualización del catálogo de herramientas sin cambiar la implementación de la herramienta |
| `api.registerCommand(...)` | Comandos de Plugin con alcance; los resultados de comando pueden establecer `continueAgent: true`; los comandos nativos de Discord admiten `descriptionLocalizations` |
| `api.registerControlUiDescriptor(...)` | Descriptores de contribución de Control UI para superficies de sesión, herramienta, ejecución o configuración |
| `api.registerRuntimeLifecycle(...)` | Devoluciones de llamada de limpieza para recursos de runtime propiedad del Plugin en rutas de reinicio/eliminación/recarga |
| `api.registerAgentEventSubscription(...)` | Suscripciones saneadas a eventos para estado de flujo de trabajo y monitores |
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Estado temporal de Plugin por ejecución limpiado en el ciclo de vida terminal de la ejecución |
| `api.registerSessionSchedulerJob(...)` | Registros de trabajos del programador de sesiones propiedad del Plugin con limpieza determinista |
| `api.registerTrustedToolPolicy(...)` | Política de herramientas pre-Plugin incluida/de confianza que puede bloquear o reescribir parámetros de herramientas |
| `api.registerToolMetadata(...)` | Metadatos de visualización del catálogo de herramientas sin cambiar la implementación de la herramienta |
| `api.registerCommand(...)` | Comandos de Plugin con ámbito; los resultados de comandos pueden establecer `continueAgent: true`; los comandos nativos de Discord admiten `descriptionLocalizations` |
| `api.registerControlUiDescriptor(...)` | Descriptores de contribución de Control UI para superficies de sesión, herramienta, ejecución o ajustes |
| `api.registerRuntimeLifecycle(...)` | Callbacks de limpieza para recursos de runtime propiedad del Plugin en rutas de restablecimiento/eliminación/recarga |
| `api.registerAgentEventSubscription(...)` | Suscripciones saneadas a eventos para estado de flujo de trabajo y monitores |
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Estado temporal de Plugin por ejecución que se limpia en el ciclo de vida terminal de la ejecución |
| `api.registerSessionSchedulerJob(...)` | Registros de trabajos del programador de sesiones propiedad del Plugin con limpieza determinista |
Los contratos dividen la autoridad intencionalmente:
- Los plugins externos pueden poseer extensiones de sesión, descriptores de UI, comandos, metadatos de herramientas, inyecciones del siguiente turno y hooks normales.
- Las políticas de herramientas de confianza se ejecutan antes de los hooks ordinarios `before_tool_call` y son solo para plugins incluidos porque participan en la política de seguridad del host.
- La propiedad de comandos reservados es solo para plugins incluidos. Los plugins externos deben usar sus propios nombres de comando o alias.
- `allowPromptInjection=false` desactiva hooks que mutan prompts, incluidos `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, campos de prompt del `before_agent_start` heredado y `enqueueNextTurnInjection`.
- Los plugins externos pueden poseer extensiones de sesión, descriptores de UI, comandos, metadatos de herramientas, inyecciones de siguiente turno y hooks normales.
- Las políticas de herramientas de confianza se ejecutan antes de los hooks ordinarios `before_tool_call` y son solo para incluidos porque participan en la política de seguridad del host.
- La propiedad de comandos reservados es solo para incluidos. Los plugins externos deberían usar sus propios nombres de comando o alias.
- `allowPromptInjection=false` desactiva hooks que mutan prompts, incluidos `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, campos de prompt de `before_agent_start` heredado y `enqueueNextTurnInjection`.
Ejemplos de consumidores que no son de Plan:
| Arquetipo de Plugin | Hooks usados |
| Arquetipo de Plugin | Hooks usados |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Flujo de trabajo de aprobación | Extensión de sesión, continuación de comando, inyección del siguiente turno, descriptor de UI |
| Puerta de política de presupuesto/espacio de trabajo | Política de herramientas de confianza, metadatos de herramientas, proyección de sesión |
| Monitor de ciclo de vida en segundo plano | Limpieza de ciclo de vida de runtime, suscripción a eventos de agente, propiedad/limpieza del programador de sesiones, contribución de prompt de heartbeat, descriptor de UI |
| Asistente de configuración u onboarding | Extensión de sesión, comandos con alcance, descriptor de Control UI |
| Flujo de aprobación | Extensión de sesión, continuación de comando, inyección de siguiente turno, descriptor de UI |
| Compuerta de política de presupuesto/workspace | Política de herramienta de confianza, metadatos de herramienta, proyección de sesión |
| Monitor de ciclo de vida en segundo plano | Limpieza de ciclo de vida de runtime, suscripción a eventos de agente, propiedad/limpieza del programador de sesiones, contribución al prompt de heartbeat, descriptor de UI |
| Asistente de configuración u onboarding | Extensión de sesión, comandos con ámbito, descriptor de Control UI |
<Note>
Los espacios de nombres reservados de administración del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) siempre permanecen como `operator.admin`, incluso si un Plugin intenta asignar un
alcance de método del Gateway más estrecho. Prefiere prefijos específicos de Plugin para
ámbito más estrecho de método de Gateway. Prefiere prefijos específicos de Plugin para
métodos propiedad del Plugin.
</Note>
<Accordion title="Cuándo usar middleware de resultado de herramienta">
<Accordion title="Cuándo usar middleware de resultados de herramientas">
Los plugins incluidos pueden usar `api.registerAgentToolResultMiddleware(...)` cuando
necesitan reescribir un resultado de herramienta después de la ejecución y antes de que el runtime
devuelva ese resultado al modelo. Esta es la costura de confianza y neutral respecto al runtime
@ -179,14 +179,18 @@ Ejemplos de consumidores que no son de Plan:
Los plugins incluidos deben declarar `contracts.agentToolResultMiddleware` para cada
runtime objetivo, por ejemplo `["pi", "codex"]`. Los plugins externos
no pueden registrar este middleware; conserva los hooks normales de plugins de OpenClaw para trabajo
que no necesite temporización de resultado de herramienta previa al modelo. La antigua ruta de
registro de fábrica de extensión integrada solo para Pi se eliminó.
no pueden registrar este middleware; conserva los hooks normales de OpenClaw Plugin para trabajo
que no necesite temporización de resultado de herramienta previa al modelo. La antigua ruta de registro de fábrica de
extensión integrada solo de Pi se ha eliminado.
</Accordion>
### Registro de descubrimiento del Gateway
`api.registerGatewayDiscoveryService(...)` permite que un plugin anuncie el Gateway activo en un transporte de descubrimiento local como mDNS/Bonjour. OpenClaw llama al servicio durante el inicio del Gateway cuando el descubrimiento local está habilitado, pasa los puertos actuales del Gateway y datos de pista TXT no secretos, y llama al controlador `stop` devuelto durante el apagado del Gateway.
`api.registerGatewayDiscoveryService(...)` permite que un plugin anuncie el Gateway activo
en un transporte de descubrimiento local como mDNS/Bonjour. OpenClaw llama al
servicio durante el arranque del Gateway cuando el descubrimiento local está habilitado, pasa los
puertos actuales del Gateway y datos de sugerencia TXT no secretos, y llama al manejador
`stop` devuelto durante el apagado del Gateway.
```typescript
api.registerGatewayDiscoveryService({
@ -202,16 +206,21 @@ api.registerGatewayDiscoveryService({
});
```
Los plugins de descubrimiento de Gateway no deben tratar los valores TXT anunciados como secretos ni como autenticación. El descubrimiento es una pista de enrutamiento; la autenticación del Gateway y la fijación de TLS siguen siendo responsables de la confianza.
Los plugins de descubrimiento del Gateway no deben tratar los valores TXT anunciados como secretos ni
autenticación. El descubrimiento es una sugerencia de enrutamiento; la autenticación del Gateway y la fijación de TLS
siguen siendo responsables de la confianza.
### Metadatos de registro de la CLI
`api.registerCli(registrar, opts?)` acepta dos tipos de metadatos de nivel superior:
- `commands`: raíces de comandos explícitas propiedad del registrador
- `descriptors`: descriptores de comandos en tiempo de análisis usados para la ayuda de la CLI raíz, el enrutamiento y el registro diferido de la CLI del plugin
- `descriptors`: descriptores de comandos en tiempo de análisis usados para la ayuda de la CLI raíz,
el enrutamiento y el registro diferido de la CLI del plugin
Si quieres que un comando de plugin se mantenga con carga diferida en la ruta normal de la CLI raíz, proporciona `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese registrador.
Si quieres que un comando de plugin permanezca cargado de forma diferida en la ruta normal de la CLI raíz,
proporciona `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese
registrador.
```typescript
api.registerCli(
@ -231,79 +240,95 @@ api.registerCli(
);
```
Usa `commands` por sí solo únicamente cuando no necesites el registro diferido en la CLI raíz. Esa ruta de compatibilidad inmediata sigue estando soportada, pero no instala marcadores de posición respaldados por descriptores para la carga diferida en tiempo de análisis.
Usa `commands` por sí solo únicamente cuando no necesites el registro diferido de la CLI raíz.
Esa ruta de compatibilidad inmediata sigue siendo compatible, pero no instala
marcadores de posición respaldados por descriptores para la carga diferida en tiempo de análisis.
### Registro de backend de CLI
### Registro de backend de la CLI
`api.registerCliBackend(...)` permite que un plugin sea propietario de la configuración predeterminada de un backend local de CLI de IA como `codex-cli`.
`api.registerCliBackend(...)` permite que un plugin sea propietario de la configuración predeterminada de un backend local
de CLI de IA como `codex-cli`.
- El `id` del backend se convierte en el prefijo del proveedor en referencias de modelo como `codex-cli/gpt-5`.
- El `id` del backend se convierte en el prefijo de proveedor en referencias de modelo como `codex-cli/gpt-5`.
- La `config` del backend usa la misma forma que `agents.defaults.cliBackends.<id>`.
- La configuración del usuario sigue ganando. OpenClaw fusiona `agents.defaults.cliBackends.<id>` sobre el valor predeterminado del plugin antes de ejecutar la CLI.
- Usa `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión (por ejemplo, normalizar formas antiguas de flags).
- La configuración de usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.<id>` sobre el
valor predeterminado del plugin antes de ejecutar la CLI.
- Usa `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión
(por ejemplo, normalizar formas antiguas de flags).
- Usa `resolveExecutionArgs` para reescrituras de argv con alcance de solicitud que pertenezcan
al dialecto de la CLI, como asignar los niveles de pensamiento de OpenClaw a un flag nativo de esfuerzo.
### Slots exclusivos
| Método | Qué registra |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Motor de contexto (uno activo a la vez). El callback `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar añadidos al prompt. |
| `api.registerMemoryCapability(capability)` | Capacidad de memoria unificada |
| `api.registerMemoryPromptSection(builder)` | Constructor de sección de prompt de memoria |
| `api.registerMemoryFlushPlan(resolver)` | Resolver de plan de vaciado de memoria |
| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memoria |
| Método | Qué registra |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Motor de contexto (uno activo a la vez). El callback `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar las adiciones al prompt. |
| `api.registerMemoryCapability(capability)` | Capacidad de memoria unificada |
| `api.registerMemoryPromptSection(builder)` | Constructor de sección de prompt de memoria |
| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plan de vaciado de memoria |
| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memoria |
### Adaptadores de embedding de memoria
### Adaptadores de embeddings de memoria
| Método | Qué registra |
| ---------------------------------------------- | ------------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embedding de memoria para el plugin activo |
| Método | Qué registra |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embeddings de memoria para el plugin activo |
- `registerMemoryCapability` es la API exclusiva preferida para plugins de memoria.
- `registerMemoryCapability` también puede exponer `publicArtifacts.listArtifacts(...)` para que los plugins complementarios puedan consumir artefactos de memoria exportados mediante `openclaw/plugin-sdk/memory-host-core` en vez de acceder al diseño privado de un plugin de memoria específico.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` y `registerMemoryRuntime` son API exclusivas de plugins de memoria compatibles con legado.
- `MemoryFlushPlan.model` puede fijar el turno de vaciado a una referencia exacta de `provider/model`, como `ollama/qwen3:8b`, sin heredar la cadena de fallback activa.
- `registerMemoryEmbeddingProvider` permite que el plugin de memoria activo registre uno o más ids de adaptadores de embedding (por ejemplo `openai`, `gemini` o un id personalizado definido por el plugin).
- La configuración del usuario, como `agents.defaults.memorySearch.provider` y `agents.defaults.memorySearch.fallback`, se resuelve contra esos ids de adaptador registrados.
- `registerMemoryCapability` también puede exponer `publicArtifacts.listArtifacts(...)`
para que los plugins complementarios puedan consumir artefactos de memoria exportados mediante
`openclaw/plugin-sdk/memory-host-core` en lugar de acceder al diseño privado de un
plugin de memoria específico.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` y
`registerMemoryRuntime` son API exclusivas de plugins de memoria compatibles con legado.
- `MemoryFlushPlan.model` puede fijar el turno de vaciado a una referencia exacta de `provider/model`
como `ollama/qwen3:8b`, sin heredar la cadena de fallback activa.
- `registerMemoryEmbeddingProvider` permite que el plugin de memoria activo registre uno
o más ids de adaptador de embeddings (por ejemplo `openai`, `gemini` o un id personalizado
definido por el plugin).
- La configuración de usuario como `agents.defaults.memorySearch.provider` y
`agents.defaults.memorySearch.fallback` se resuelve contra esos ids de adaptador
registrados.
### Eventos y ciclo de vida
| Método | Qué hace |
| Método | Qué hace |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Hook de ciclo de vida tipado |
| `api.on(hookName, handler, opts?)` | Hook de ciclo de vida tipado |
| `api.onConversationBindingResolved(handler)` | Callback de enlace de conversación |
Consulta [hooks de Plugin](/es/plugins/hooks) para ver ejemplos, nombres de hooks comunes y semántica de protección.
Consulta [Hooks de Plugin](/es/plugins/hooks) para ver ejemplos, nombres de hooks comunes y semánticas de protección.
### Semántica de decisión de hooks
### Semántica de decisiones de hooks
- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
- `before_tool_call`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una sobrescritura.
- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
- `before_install`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una sobrescritura.
- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier controlador reclama el despacho, se omiten los controladores de menor prioridad y la ruta predeterminada de despacho del modelo.
- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier controlador lo establece, se omiten los controladores de menor prioridad.
- `message_sending`: devolver `{ cancel: false }` se trata como ausencia de decisión (igual que omitir `cancel`), no como una sobrescritura.
- `message_received`: usa el campo tipado `threadId` cuando necesites enrutamiento entrante de hilo/tema. Mantén `metadata` para extras específicos del canal.
- `message_sending`: usa los campos de enrutamiento tipados `replyToId` / `threadId` antes de recurrir a `metadata` específico del canal.
- `gateway_start`: usa `ctx.config`, `ctx.workspaceDir` y `ctx.getCron?.()` para el estado de inicio propiedad del gateway en vez de depender de hooks internos `gateway:startup`.
- `cron_changed`: observa los cambios del ciclo de vida de cron propiedad del gateway. Usa `event.job?.state?.nextRunAtMs` y `ctx.getCron?.()` al sincronizar planificadores externos de activación, y mantén OpenClaw como fuente de verdad para las comprobaciones de vencimiento y la ejecución.
- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, los manejadores de menor prioridad se omiten.
- `before_tool_call`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación.
- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, los manejadores de menor prioridad se omiten.
- `before_install`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación.
- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier manejador reclama el despacho, los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo se omiten.
- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier manejador lo establece, los manejadores de menor prioridad se omiten.
- `message_sending`: devolver `{ cancel: false }` se trata como ausencia de decisión (igual que omitir `cancel`), no como una anulación.
- `message_received`: usa el campo tipado `threadId` cuando necesites enrutamiento entrante por hilo/tema. Mantén `metadata` para extras específicos del canal.
- `message_sending`: usa los campos tipados de enrutamiento `replyToId` / `threadId` antes de recurrir a `metadata` específico del canal.
- `gateway_start`: usa `ctx.config`, `ctx.workspaceDir` y `ctx.getCron?.()` para el estado de arranque propiedad del gateway en lugar de depender de hooks internos `gateway:startup`.
- `cron_changed`: observa los cambios de ciclo de vida de Cron propiedad del gateway. Usa `event.job?.state?.nextRunAtMs` y `ctx.getCron?.()` al sincronizar programadores de activación externos, y mantén OpenClaw como la fuente de verdad para las comprobaciones de vencimiento y la ejecución.
### Campos del objeto API
| Campo | Tipo | Descripción |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Id del Plugin |
| `api.name` | `string` | Nombre para mostrar |
| `api.version` | `string?` | Versión del Plugin (opcional) |
| `api.description` | `string?` | Descripción del Plugin (opcional) |
| `api.source` | `string` | Ruta de origen del Plugin |
| `api.rootDir` | `string?` | Directorio raíz del Plugin (opcional) |
| `api.config` | `OpenClawConfig` | Instantánea de configuración actual (instantánea activa de runtime en memoria cuando esté disponible) |
| `api.pluginConfig` | `Record<string, unknown>` | Configuración específica del Plugin desde `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/es/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger acotado (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Modo de carga actual; `"setup-runtime"` es la ventana ligera de inicio/configuración previa a la entrada completa |
| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin |
| `api.id` | `string` | Id del plugin |
| `api.name` | `string` | Nombre visible |
| `api.version` | `string?` | Versión del plugin (opcional) |
| `api.description` | `string?` | Descripción del plugin (opcional) |
| `api.source` | `string` | Ruta de origen del plugin |
| `api.rootDir` | `string?` | Directorio raíz del plugin (opcional) |
| `api.config` | `OpenClawConfig` | Snapshot de configuración actual (snapshot de runtime en memoria activo cuando esté disponible) |
| `api.pluginConfig` | `Record<string, unknown>` | Configuración específica del plugin desde `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/es/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger con alcance (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Modo de carga actual; `"setup-runtime"` es la ventana ligera de arranque/configuración previa a la entrada completa |
| `api.resolvePath(input)` | `(string) => string` | Resuelve la ruta relativa a la raíz del plugin |
## Convención de módulos internos
@ -323,19 +348,30 @@ my-plugin/
`./runtime-api.ts`. La ruta del SDK es solo el contrato externo.
</Warning>
Las superficies públicas de plugins incluidos cargadas por fachada (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` y archivos de entrada públicos similares) prefieren la instantánea de configuración de runtime activa cuando OpenClaw ya se está ejecutando. Si aún no existe ninguna instantánea de runtime, recurren al archivo de configuración resuelto en disco. Las fachadas de plugins incluidos empaquetados deben cargarse mediante los cargadores de fachadas de plugins de OpenClaw; las importaciones directas desde `dist/extensions/...` omiten el manifiesto y las comprobaciones del sidecar de runtime que las instalaciones empaquetadas usan para el código propiedad del plugin.
Las superficies públicas de plugins incluidos cargadas por fachada (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` y archivos de entrada públicos similares) prefieren el
snapshot de configuración de runtime activo cuando OpenClaw ya se está ejecutando. Si todavía no existe ningún snapshot
de runtime, recurren al archivo de configuración resuelto en disco.
Las fachadas de plugins incluidos empaquetados deben cargarse mediante los cargadores de fachadas de plugins de
OpenClaw; las importaciones directas desde `dist/extensions/...` omiten el manifiesto
y las comprobaciones de sidecar de runtime que las instalaciones empaquetadas usan para código propiedad del plugin.
Los plugins de proveedor pueden exponer un barrel de contrato local y estrecho del plugin cuando un helper es intencionadamente específico del proveedor y aún no pertenece a una subruta genérica del SDK. Ejemplos incluidos:
Los plugins de proveedor pueden exponer un barrel de contrato estrecho y local al plugin cuando un
helper es intencionalmente específico del proveedor y aún no pertenece a una subruta genérica del SDK.
Ejemplos incluidos:
- **Anthropic**: superficie pública `api.ts` / `contract-api.ts` para helpers de beta-header de Claude y streaming de `service_tier`.
- **`@openclaw/openai-provider`**: `api.ts` exporta constructores de proveedor, helpers de modelo predeterminado y constructores de proveedor en tiempo real.
- **`@openclaw/openrouter-provider`**: `api.ts` exporta el constructor de proveedor más helpers de onboarding/configuración.
- **Anthropic**: superficie pública `api.ts` / `contract-api.ts` para helpers de streaming de
beta-header de Claude y `service_tier`.
- **`@openclaw/openai-provider`**: `api.ts` exporta constructores de proveedor,
helpers de modelo predeterminado y constructores de proveedor en tiempo real.
- **`@openclaw/openrouter-provider`**: `api.ts` exporta el constructor de proveedor
junto con helpers de onboarding/configuración.
<Warning>
El código de producción de extensiones también debe evitar importaciones de `openclaw/plugin-sdk/<other-plugin>`.
Si un helper realmente es compartido, promuévelo a una subruta neutral del SDK
Si un helper es realmente compartido, promuévelo a una subruta neutral del SDK
como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` u otra
superficie orientada a capacidades en vez de acoplar dos plugins entre sí.
superficie orientada a capacidades en lugar de acoplar dos plugins entre sí.
</Warning>
## Relacionado
@ -344,7 +380,7 @@ Los plugins de proveedor pueden exponer un barrel de contrato local y estrecho d
<Card title="Puntos de entrada" icon="door-open" href="/es/plugins/sdk-entrypoints">
Opciones de `definePluginEntry` y `defineChannelPluginEntry`.
</Card>
<Card title="Ayudantes de runtime" icon="gears" href="/es/plugins/sdk-runtime">
<Card title="Ayudantes de tiempo de ejecución" icon="gears" href="/es/plugins/sdk-runtime">
Referencia completa del espacio de nombres `api.runtime`.
</Card>
<Card title="Configuración inicial y configuración" icon="sliders" href="/es/plugins/sdk-setup">
@ -357,6 +393,6 @@ Los plugins de proveedor pueden exponer un barrel de contrato local y estrecho d
Migración desde superficies obsoletas.
</Card>
<Card title="Aspectos internos de Plugin" icon="diagram-project" href="/es/plugins/architecture">
Arquitectura profunda y modelo de capacidades.
Arquitectura detallada y modelo de capacidades.
</Card>
</CardGroup>

128
docs/es/security/network-proxy.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Quieres defensa en profundidad contra ataques SSRF y de reenlace DNS
- Desea contar con defensa en profundidad contra ataques SSRF y de revinculación de DNS
- Configuración de un proxy de reenvío externo para el tráfico en tiempo de ejecución de OpenClaw
summary: Cómo enrutar el tráfico HTTP y WebSocket del entorno de ejecución de OpenClaw a través de un proxy de filtrado gestionado por el operador
summary: Cómo enrutar el tráfico HTTP y WebSocket en tiempo de ejecución de OpenClaw a través de un proxy de filtrado administrado por el operador
title: Proxy de red
x-i18n:
generated_at: "2026-05-04T05:29:05Z"
generated_at: "2026-05-04T18:24:34Z"
model: gpt-5.5
provider: openai
source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
source_path: security/network-proxy.md
workflow: 16
---
# Proxy de red
OpenClaw puede enrutar el tráfico HTTP y WebSocket en tiempo de ejecución a través de un proxy de reenvío administrado por el operador. Esta es una defensa opcional en profundidad para despliegues que quieren control centralizado de salida, protección SSRF más sólida y mejor auditabilidad de red.
OpenClaw puede enrutar el tráfico HTTP y WebSocket en tiempo de ejecución a través de un proxy de reenvío administrado por el operador. Esto es una defensa en profundidad opcional para despliegues que quieren control central de egreso, protección SSRF más fuerte y mejor auditabilidad de red.
OpenClaw no incluye, descarga, inicia, configura ni certifica ningún proxy. Tú ejecutas la tecnología de proxy que encaja con tu entorno, y OpenClaw enruta los clientes HTTP y WebSocket normales locales al proceso a través de él.
OpenClaw no incluye, descarga, inicia, configura ni certifica un proxy. Tú ejecutas la tecnología de proxy que se ajuste a tu entorno, y OpenClaw enruta los clientes HTTP y WebSocket normales locales al proceso a través de él.
## ¿Por qué usar un proxy?
Un proxy da a los operadores un único punto de control de red para el tráfico HTTP y WebSocket saliente. Eso puede ser útil incluso más allá del refuerzo contra SSRF:
Un proxy ofrece a los operadores un único punto de control de red para el tráfico HTTP y WebSocket saliente. Eso puede ser útil incluso fuera del endurecimiento contra SSRF:
- Política central: mantén una única política de salida en lugar de depender de que cada punto de llamada HTTP de la aplicación aplique correctamente las reglas de red.
- Comprobaciones en el momento de conexión: evalúa el destino después de la resolución DNS e inmediatamente antes de que el proxy abra la conexión ascendente.
- Defensa contra DNS rebinding: reduce la brecha entre una comprobación DNS a nivel de aplicación y la conexión saliente real.
- Cobertura más amplia de JavaScript: enruta clientes ordinarios como `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch y similares por la misma ruta.
- Auditabilidad: registra destinos permitidos y denegados en el límite de salida.
- Control operativo: aplica reglas de destino, segmentación de red, límites de tasa o listas de permitidos salientes sin reconstruir OpenClaw.
- Política central: mantener una sola política de egreso en lugar de depender de que cada punto de llamada HTTP de la aplicación aplique correctamente las reglas de red.
- Comprobaciones en tiempo de conexión: evaluar el destino después de la resolución DNS e inmediatamente antes de que el proxy abra la conexión ascendente.
- Defensa contra DNS rebinding: reducir la brecha entre una comprobación DNS a nivel de aplicación y la conexión saliente real.
- Cobertura más amplia de JavaScript: enrutar clientes ordinarios de `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch y similares por la misma ruta.
- Auditabilidad: registrar destinos permitidos y denegados en el límite de egreso.
- Control operativo: aplicar reglas de destino, segmentación de red, límites de tasa o listas de permitidos salientes sin reconstruir OpenClaw.
El enrutamiento por proxy es una barrera a nivel de proceso para la salida HTTP y WebSocket normal. Da a los operadores una ruta cerrada ante fallos para enrutar clientes HTTP JavaScript compatibles a través de su propio proxy filtrante, pero no es un sandbox de red a nivel de sistema operativo y no hace que OpenClaw certifique la política de destinos del proxy.
El enrutamiento por proxy es una barandilla a nivel de proceso para el egreso HTTP y WebSocket normal. Ofrece a los operadores una ruta de cierre ante fallos para enrutar clientes HTTP de JavaScript compatibles a través de su propio proxy de filtrado, pero no es un sandbox de red a nivel de sistema operativo y no hace que OpenClaw certifique la política de destinos del proxy.
## Cómo OpenClaw enruta el tráfico
Cuando `proxy.enabled=true` y se configura una URL de proxy, los procesos protegidos en tiempo de ejecución, como `openclaw gateway run`, `openclaw node run` y `openclaw agent --local`, enrutan la salida HTTP y WebSocket normal a través del proxy configurado:
Cuando `proxy.enabled=true` y se configura una URL de proxy, los procesos en tiempo de ejecución protegidos como `openclaw gateway run`, `openclaw node run` y `openclaw agent --local` enrutan el egreso HTTP y WebSocket normal a través del proxy configurado:
```text
OpenClaw process
@ -43,27 +43,27 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
El contrato público es el comportamiento de enrutamiento, no los hooks internos de Node usados para implementarlo. Los clientes WebSocket del plano de control de OpenClaw Gateway usan una ruta directa estrecha para el tráfico RPC de Gateway de local loopback cuando la URL del Gateway usa `localhost` o una IP de loopback literal como `127.0.0.1` o `[::1]`. Esa ruta del plano de control debe poder alcanzar Gateways de loopback incluso cuando el proxy del operador bloquea destinos de loopback. Las solicitudes HTTP y WebSocket normales en tiempo de ejecución siguen usando el proxy configurado.
El contrato público es el comportamiento de enrutamiento, no los hooks internos de Node utilizados para implementarlo. Los clientes WebSocket del plano de control de OpenClaw Gateway usan una ruta directa estrecha para el tráfico RPC de Gateway con local loopback cuando la URL del Gateway usa `localhost` o una IP literal de loopback como `127.0.0.1` o `[::1]`. Esa ruta del plano de control debe poder alcanzar Gateways de loopback incluso cuando el proxy del operador bloquea destinos de loopback. Las solicitudes HTTP y WebSocket normales en tiempo de ejecución siguen usando el proxy configurado.
Internamente, OpenClaw usa dos hooks de enrutamiento a nivel de proceso para esta función:
- El enrutamiento del despachador de Undici cubre `fetch`, clientes respaldados por undici y transportes que proporcionan su propio despachador de undici.
- El enrutamiento de `global-agent` cubre llamadores del núcleo de Node `node:http` y `node:https`, incluidas muchas bibliotecas construidas sobre `http.request`, `https.request`, `http.get` y `https.get`. El modo de proxy administrado fuerza ese agente global para que los agentes HTTP explícitos de Node no omitan accidentalmente el proxy del operador.
- El enrutamiento de `global-agent` cubre llamadores del núcleo de Node `node:http` y `node:https`, incluidas muchas bibliotecas construidas sobre `http.request`, `https.request`, `http.get` y `https.get`. El modo de proxy administrado fuerza ese agente global para que los agentes HTTP explícitos de Node no eviten accidentalmente el proxy del operador.
Algunos plugins poseen transportes personalizados que necesitan cableado explícito del proxy incluso cuando existe enrutamiento a nivel de proceso. Por ejemplo, el transporte de Bot API de Telegram usa su propio despachador HTTP/1 de undici y, por lo tanto, respeta las variables de entorno de proxy del proceso más el fallback administrado `OPENCLAW_PROXY_URL` en esa ruta de transporte específica del propietario.
Algunos plugins poseen transportes personalizados que necesitan cableado explícito de proxy incluso cuando existe enrutamiento a nivel de proceso. Por ejemplo, el transporte de la Bot API de Telegram usa su propio despachador HTTP/1 de undici y por lo tanto respeta el entorno de proxy del proceso más el respaldo administrado `OPENCLAW_PROXY_URL` en esa ruta de transporte específica del propietario.
La URL del proxy en sí debe usar `http://`. Los destinos HTTPS siguen siendo compatibles a través del proxy con HTTP `CONNECT`; esto solo significa que OpenClaw espera un listener de proxy de reenvío HTTP plano como `http://127.0.0.1:3128`.
La propia URL del proxy debe usar `http://`. Los destinos HTTPS siguen siendo compatibles a través del proxy con HTTP `CONNECT`; esto solo significa que OpenClaw espera un listener de proxy de reenvío HTTP plano como `http://127.0.0.1:3128`.
Mientras el proxy está activo, OpenClaw limpia `no_proxy`, `NO_PROXY` y `GLOBAL_AGENT_NO_PROXY`. Esas listas de omisión se basan en destino, así que dejar `localhost` o `127.0.0.1` allí permitiría que objetivos SSRF de alto riesgo se saltaran el proxy filtrante.
Mientras el proxy está activo, OpenClaw limpia `no_proxy`, `NO_PROXY` y `GLOBAL_AGENT_NO_PROXY`. Esas listas de omisión están basadas en destinos, así que dejar `localhost` o `127.0.0.1` allí permitiría que objetivos SSRF de alto riesgo se saltaran el proxy de filtrado.
Al apagarse, OpenClaw restaura el entorno de proxy anterior y restablece el estado de enrutamiento de proceso en caché.
## Términos de proxy relacionados
- `proxy.enabled` / `proxy.proxyUrl`: enrutamiento saliente mediante proxy de reenvío para la salida en tiempo de ejecución de OpenClaw. Esta página documenta esa función.
- `gateway.auth.mode: "trusted-proxy"`: autenticación entrante mediante proxy inverso con identidad para el acceso al Gateway. Consulta [Autenticación de proxy de confianza](/es/gateway/trusted-proxy-auth).
- `proxy.enabled` / `proxy.proxyUrl`: enrutamiento por proxy de reenvío saliente para el egreso en tiempo de ejecución de OpenClaw. Esta página documenta esa función.
- `gateway.auth.mode: "trusted-proxy"`: autenticación entrante de proxy inverso consciente de identidad para acceso al Gateway. Consulta [Autenticación de proxy de confianza](/es/gateway/trusted-proxy-auth).
- `openclaw proxy`: proxy local de depuración e inspector de captura para desarrollo y soporte. Consulta [openclaw proxy](/es/cli/proxy).
- Configuraciones de proxy específicas de canal o proveedor: anulaciones específicas del propietario para un transporte particular. Prefiere el proxy de red administrado cuando el objetivo sea el control centralizado de salida en todo el runtime.
- Configuraciones de proxy específicas de canal o proveedor: sobrescrituras específicas del propietario para un transporte particular. Prefiere el proxy de red administrado cuando el objetivo sea el control central de egreso en todo el runtime.
## Configuración
@ -81,7 +81,7 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` tiene precedencia sobre `OPENCLAW_PROXY_URL`.
Si `enabled=true` pero no se configura una URL de proxy válida, los comandos protegidos fallan al iniciar en lugar de volver al acceso directo a la red.
Si `enabled=true` pero no se configura una URL de proxy válida, los comandos protegidos fallan al iniciar en lugar de recurrir al acceso directo a la red.
Para servicios de gateway administrados iniciados con `openclaw gateway start`, prefiere almacenar la URL en la configuración:
@ -92,9 +92,9 @@ openclaw gateway install --force
openclaw gateway start
```
El fallback de entorno es mejor para ejecuciones en primer plano. Si lo usas con un servicio instalado, coloca `OPENCLAW_PROXY_URL` en el entorno persistente del servicio, como `$OPENCLAW_STATE_DIR/.env` o `~/.openclaw/.env`, y luego reinstala el servicio para que launchd, systemd o Scheduled Tasks inicie el gateway con ese valor.
El respaldo de entorno es mejor para ejecuciones en primer plano. Si lo usas con un servicio instalado, coloca `OPENCLAW_PROXY_URL` en el entorno durable del servicio, como `$OPENCLAW_STATE_DIR/.env` o `~/.openclaw/.env`, y luego reinstala el servicio para que launchd, systemd o Scheduled Tasks inicie el gateway con ese valor.
Para comandos `openclaw --container ...`, OpenClaw reenvía `OPENCLAW_PROXY_URL` a la CLI hija dirigida al contenedor cuando está establecida. La URL debe ser accesible desde dentro del contenedor; `127.0.0.1` se refiere al propio contenedor, no al host. OpenClaw rechaza URL de proxy de loopback para comandos dirigidos a contenedores a menos que anules explícitamente esa comprobación de seguridad.
Para comandos `openclaw --container ...`, OpenClaw reenvía `OPENCLAW_PROXY_URL` al CLI hijo dirigido al contenedor cuando está definido. La URL debe ser alcanzable desde dentro del contenedor; `127.0.0.1` se refiere al propio contenedor, no al host. OpenClaw rechaza URLs de proxy de loopback para comandos dirigidos a contenedores a menos que sobrescribas explícitamente esa comprobación de seguridad.
## Requisitos del proxy
@ -102,41 +102,41 @@ La política del proxy es el límite de seguridad. OpenClaw no puede verificar q
Configura el proxy para:
- Enlazarse solo a loopback o a una interfaz privada de confianza.
- Vincularse solo a loopback o a una interfaz privada de confianza.
- Restringir el acceso para que solo el proceso, host, contenedor o cuenta de servicio de OpenClaw pueda usarlo.
- Resolver los destinos por sí mismo y bloquear las IP de destino después de la resolución DNS.
- Aplicar la política en el momento de conexión tanto para solicitudes HTTP planas como para túneles HTTPS `CONNECT`.
- Resolver destinos por sí mismo y bloquear IPs de destino después de la resolución DNS.
- Aplicar la política en tiempo de conexión tanto para solicitudes HTTP planas como para túneles HTTPS `CONNECT`.
- Rechazar omisiones basadas en destino para rangos de loopback, privados, link-local, metadatos, multicast, reservados o de documentación.
- Evitar listas de permitidos por nombre de host a menos que confíes plenamente en la ruta de resolución DNS.
- Evitar listas de permitidos de nombres de host a menos que confíes plenamente en la ruta de resolución DNS.
- Registrar destino, decisión, estado y motivo sin registrar cuerpos de solicitud, encabezados de autorización, cookies u otros secretos.
- Mantener la política del proxy bajo control de versiones y revisar los cambios como configuración sensible a la seguridad.
## Destinos bloqueados recomendados
Usa esta lista de denegación como punto de partida para cualquier proxy de reenvío, firewall o política de salida.
Usa esta lista de denegación como punto de partida para cualquier proxy de reenvío, firewall o política de egreso.
La lógica de clasificación a nivel de aplicación de OpenClaw vive en `src/infra/net/ssrf.ts` y `src/shared/net/ip.ts`. Los hooks de paridad relevantes son `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` y el manejo del centinela IPv4 integrado para NAT64, 6to4, Teredo, ISATAP y formas IPv4-mapped. Esos archivos son referencias útiles al mantener una política externa de proxy, pero OpenClaw no exporta ni aplica automáticamente esas reglas en tu proxy.
La lógica de clasificación a nivel de aplicación de OpenClaw vive en `src/infra/net/ssrf.ts` y `src/shared/net/ip.ts`. Los hooks de paridad relevantes son `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` y el manejo centinela IPv4 incrustado para NAT64, 6to4, Teredo, ISATAP y formas mapeadas a IPv4. Esos archivos son referencias útiles al mantener una política de proxy externa, pero OpenClaw no exporta ni aplica automáticamente esas reglas en tu proxy.
| Rango o host | Por qué bloquear |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 |
| `::1/128` | Loopback IPv6 |
| `0.0.0.0/8`, `::/128` | Direcciones no especificadas y de esta red |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Redes privadas RFC1918 |
| Rango o host | Por qué bloquear |
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 |
| `::1/128` | Loopback IPv6 |
| `0.0.0.0/8`, `::/128` | Direcciones no especificadas y de esta red |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Redes privadas RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | Direcciones link-local y rutas comunes de metadatos en la nube |
| `169.254.169.254`, `metadata.google.internal` | Servicios de metadatos en la nube |
| `100.64.0.0/10` | Espacio de direcciones compartido de NAT de grado operador |
| `198.18.0.0/15`, `2001:2::/48` | Rangos de benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Rangos de uso especial y documentación |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 reservado |
| `fc00::/7`, `fec0::/10` | Rangos IPv6 locales/privados |
| `100::/64`, `2001:20::/28` | Rangos IPv6 discard y ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefijos NAT64 con IPv4 integrado |
| `2002::/16`, `2001::/32` | 6to4 y Teredo con IPv4 integrado |
| `::/96`, `::ffff:0:0/96` | IPv6 compatible con IPv4 e IPv6 IPv4-mapped |
| `169.254.169.254`, `metadata.google.internal` | Servicios de metadatos en la nube |
| `100.64.0.0/10` | Espacio de direcciones compartidas de NAT de grado operador |
| `198.18.0.0/15`, `2001:2::/48` | Rangos de benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Rangos de uso especial y documentación |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 reservado |
| `fc00::/7`, `fec0::/10` | Rangos IPv6 locales/privados |
| `100::/64`, `2001:20::/28` | Rangos IPv6 de descarte y ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefijos NAT64 con IPv4 incrustado |
| `2002::/16`, `2001::/32` | 6to4 y Teredo con IPv4 incrustado |
| `::/96`, `::ffff:0:0/96` | IPv6 compatible con IPv4 y mapeado a IPv4 |
Si tu proveedor de nube o plataforma de red documenta hosts de metadatos o rangos reservados adicionales, añádelos también.
Si tu proveedor de nube o plataforma de red documenta hosts de metadatos o rangos reservados adicionales, agrégalos también.
## Validación
@ -146,9 +146,9 @@ Valida el proxy desde el mismo host, contenedor o cuenta de servicio que ejecuta
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
De forma predeterminada, cuando no se proporcionan destinos personalizados, el comando comprueba que `https://example.com/` tenga éxito e inicia un canario temporal de loopback que el proxy no debe alcanzar. La comprobación denegada predeterminada pasa cuando el proxy devuelve una respuesta de denegación que no sea 2xx o bloquea el canario con un fallo de transporte; falla si una respuesta correcta llega al canario. Si no hay ningún proxy habilitado y configurado, la validación informa de un problema de configuración; usa `--proxy-url` para una comprobación preliminar puntual antes de cambiar la configuración. Usa `--allowed-url` y `--denied-url` para probar expectativas específicas del despliegue. Los destinos denegados personalizados son cerrados ante fallos: cualquier respuesta HTTP significa que el destino fue accesible a través del proxy, y cualquier error de transporte se informa como inconcluso porque OpenClaw no puede demostrar que el proxy bloqueó un origen accesible. Si la validación falla, el comando sale con código 1.
De forma predeterminada, cuando no se proporcionan destinos personalizados, el comando comprueba que `https://example.com/` tenga éxito e inicia un canario temporal de loopback que el proxy no debe alcanzar. La comprobación denegada predeterminada pasa cuando el proxy devuelve una respuesta de denegación no 2xx o bloquea el canario con un fallo de transporte; falla si una respuesta correcta llega al canario. Si no hay un proxy habilitado y configurado, la validación informa un problema de configuración; usa `--proxy-url` para una comprobación previa puntual antes de cambiar la configuración. Usa `--allowed-url` y `--denied-url` para probar expectativas específicas del despliegue. Agrega `--apns-reachable` para verificar también que la entrega directa HTTP/2 de APNs pueda abrir un túnel CONNECT a través del proxy y recibir una respuesta APNs de sandbox; la prueba usa un token de proveedor intencionalmente inválido, por lo que se espera `403 InvalidProviderToken` y cuenta como alcanzable. Los destinos denegados personalizados cierran ante fallos: cualquier respuesta HTTP significa que el destino fue alcanzable a través del proxy, y cualquier error de transporte se informa como no concluyente porque OpenClaw no puede demostrar que el proxy bloqueó un origen alcanzable. Si la validación falla, el comando sale con código 1.
Usa `--json` para automatización. La salida JSON contiene el resultado global, la fuente efectiva de configuración del proxy, cualquier error de configuración y cada comprobación de destino. Las credenciales de la URL del proxy se redactan en la salida de texto y JSON:
Usa `--json` para automatización. La salida JSON contiene el resultado general, la fuente efectiva de configuración del proxy, cualquier error de configuración y cada comprobación de destino. Las credenciales de URL de proxy se redactan en la salida de texto y JSON:
```json
{
@ -165,6 +165,12 @@ Usa `--json` para automatización. La salida JSON contiene el resultado global,
"url": "https://example.com/",
"ok": true,
"status": 200
},
{
"kind": "apns",
"url": "https://api.sandbox.push.apple.com",
"ok": true,
"status": 403
}
]
}
@ -178,9 +184,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
La solicitud pública debería completarse correctamente. Las solicitudes de loopback y de metadatos deberían ser bloqueadas por el proxy. Para `openclaw proxy validate`, el canario de loopback integrado puede distinguir una denegación del proxy de un origen accesible. Las comprobaciones personalizadas con `--denied-url` no tienen ese canario, así que trata tanto las respuestas HTTP como los fallos de transporte ambiguos como fallos de validación, salvo que tu proxy exponga una señal de denegación específica del despliegue que puedas verificar por separado.
La solicitud pública debería realizarse correctamente. El proxy debería bloquear las solicitudes de loopback y de metadatos. Para `openclaw proxy validate`, la comprobación de loopback integrada puede distinguir una denegación del proxy de un origen alcanzable. Las comprobaciones personalizadas de `--denied-url` no tienen esa comprobación, así que trata tanto las respuestas HTTP como los fallos de transporte ambiguos como fallos de validación, a menos que tu proxy exponga una señal de denegación específica del despliegue que puedas verificar por separado.
Luego habilita el enrutamiento de proxy de OpenClaw:
Luego habilita el enrutamiento por proxy de OpenClaw:
```bash
openclaw config set proxy.enabled true
@ -188,7 +194,7 @@ openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run
```
o configura:
o establece:
```yaml
proxy:
@ -198,11 +204,11 @@ proxy:
## Límites
- El proxy mejora la cobertura para clientes HTTP y WebSocket de JavaScript locales al proceso, pero no es un sandbox de red a nivel del sistema operativo.
- Los sockets sin procesar de `net`, `tls` y `http2`, los complementos nativos y los procesos secundarios pueden omitir el enrutamiento de proxy a nivel de Node, salvo que hereden y respeten las variables de entorno del proxy.
- IRC es un canal TCP/TLS sin procesar fuera del enrutamiento de proxy directo administrado por el operador. En despliegues que requieren que todo el tráfico de salida pase por ese proxy directo, configura `channels.irc.enabled=false`, salvo que el tráfico de salida directo de IRC esté aprobado explícitamente.
- El proxy de depuración local es una herramienta de diagnóstico, y su reenvío ascendente directo para solicitudes de proxy y túneles CONNECT está deshabilitado de forma predeterminada mientras el modo de proxy administrado está activo; habilita el reenvío directo solo para diagnósticos locales aprobados.
- Las WebUI locales del usuario y los servidores de modelos locales deberían incluirse en la lista de permitidos de la política de proxy del operador cuando sea necesario; OpenClaw no expone una omisión general de la red local para ellos.
- La omisión del proxy del plano de control del Gateway está limitada intencionalmente a `localhost` y a URL de IP de loopback literales. Usa `ws://127.0.0.1:18789`, `ws://[::1]:18789` o `ws://localhost:18789` para conexiones directas locales al plano de control del Gateway; otros nombres de host se enrutan como tráfico ordinario basado en nombres de host.
- El proxy mejora la cobertura para clientes HTTP y WebSocket de JavaScript locales al proceso, pero no es un sandbox de red a nivel de sistema operativo.
- Los sockets sin procesar `net`, `tls` y `http2`, los addons nativos y los procesos secundarios pueden omitir el enrutamiento por proxy a nivel de Node, a menos que hereden y respeten las variables de entorno del proxy.
- IRC es un canal TCP/TLS sin procesar fuera del enrutamiento por proxy de reenvío gestionado por el operador. En despliegues que requieren que todo el tráfico saliente pase por ese proxy de reenvío, establece `channels.irc.enabled=false` a menos que el tráfico saliente directo de IRC esté aprobado explícitamente.
- El proxy de depuración local es una herramienta de diagnóstico, y su reenvío ascendente directo para solicitudes de proxy y túneles CONNECT está deshabilitado de forma predeterminada mientras el modo de proxy gestionado está activo; habilita el reenvío directo solo para diagnósticos locales aprobados.
- Las WebUIs locales del usuario y los servidores de modelos locales deben incluirse en la lista de permitidos de la política de proxy del operador cuando sea necesario; OpenClaw no expone una omisión general de red local para ellos.
- La omisión del proxy del plano de control del Gateway se limita intencionalmente a `localhost` y a URL con IP de loopback literales. Usa `ws://127.0.0.1:18789`, `ws://[::1]:18789` o `ws://localhost:18789` para conexiones locales directas al plano de control del Gateway; otros nombres de host se enrutan como tráfico ordinario basado en nombres de host.
- OpenClaw no inspecciona, prueba ni certifica tu política de proxy.
- Trata los cambios en la política de proxy como cambios operativos sensibles para la seguridad.

111
docs/es/tools/thinking.md
View File

@ -1,13 +1,13 @@
---
read_when:
- Ajuste del razonamiento, fast-mode o el análisis sintáctico o los valores predeterminados de la directiva verbose
- Ajustar el razonamiento, el modo rápido o el análisis sintáctico o los valores predeterminados de directivas detalladas
summary: Sintaxis de directivas para /think, /fast, /verbose, /trace y visibilidad del razonamiento
title: Niveles de pensamiento
title: Niveles de razonamiento
x-i18n:
generated_at: "2026-05-04T02:26:04Z"
generated_at: "2026-05-04T18:24:45Z"
model: gpt-5.5
provider: openai
source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
source_path: tools/thinking.md
workflow: 16
---
@ -20,124 +20,125 @@ x-i18n:
- low → “think hard”
- medium → “think harder”
- high → “ultrathink” (presupuesto máximo)
- xhigh → “ultrathink+” (modelos GPT-5.2+ y Codex, además del esfuerzo de Anthropic Claude Opus 4.7)
- adaptive → pensamiento adaptativo administrado por el proveedor (compatible con Claude 4.6 en Anthropic/Bedrock, Anthropic Claude Opus 4.7 y el pensamiento dinámico de Google Gemini)
- max → razonamiento máximo del proveedor (Anthropic Claude Opus 4.7; Ollama lo asigna a su esfuerzo nativo `think` más alto)
- xhigh → “ultrathink+” (modelos GPT-5.2+ y Codex, más esfuerzo de Anthropic Claude Opus 4.7)
- adaptive → pensamiento adaptativo gestionado por el proveedor (compatible con Claude 4.6 en Anthropic/Bedrock, Anthropic Claude Opus 4.7 y el pensamiento dinámico de Google Gemini)
- max → razonamiento máximo del proveedor (Anthropic Claude Opus 4.7; Ollama lo asigna a su esfuerzo `think` nativo más alto)
- `x-high`, `x_high`, `extra-high`, `extra high` y `extra_high` se asignan a `xhigh`.
- `highest` se asigna a `high`.
- Notas del proveedor:
- Los menús y selectores de pensamiento se controlan mediante perfiles de proveedor. Los plugins de proveedor declaran el conjunto exacto de niveles para el modelo seleccionado, incluidas etiquetas como el binario `on`.
- Los menús y selectores de pensamiento se controlan mediante perfiles de proveedor. Los plugins de proveedor declaran el conjunto exacto de niveles para el modelo seleccionado, incluidas etiquetas como el valor binario `on`.
- `adaptive`, `xhigh` y `max` solo se anuncian para perfiles de proveedor/modelo que los admiten. Las directivas escritas para niveles no compatibles se rechazan con las opciones válidas de ese modelo.
- Los niveles no compatibles almacenados existentes se reasignan según el rango del perfil del proveedor. `adaptive` retrocede a `medium` en modelos no adaptativos, mientras que `xhigh` y `max` retroceden al mayor nivel no `off` compatible para el modelo seleccionado.
- Los modelos Anthropic Claude 4.6 usan `adaptive` de forma predeterminada cuando no se define ningún nivel de pensamiento explícito.
- Anthropic Claude Opus 4.7 no usa pensamiento adaptativo de forma predeterminada. El valor predeterminado de esfuerzo de su API sigue siendo propiedad del proveedor, salvo que definas explícitamente un nivel de pensamiento.
- Los niveles no compatibles almacenados existentes se reasignan según el rango del perfil de proveedor. `adaptive` vuelve a `medium` en modelos no adaptativos, mientras que `xhigh` y `max` vuelven al nivel no `off` más alto compatible con el modelo seleccionado.
- Los modelos Anthropic Claude 4.6 usan `adaptive` de forma predeterminada cuando no se establece ningún nivel de pensamiento explícito.
- Anthropic Claude Opus 4.7 no usa pensamiento adaptativo de forma predeterminada. El valor predeterminado de esfuerzo de su API sigue siendo propiedad del proveedor, a menos que establezcas explícitamente un nivel de pensamiento.
- Anthropic Claude Opus 4.7 asigna `/think xhigh` a pensamiento adaptativo más `output_config.effort: "xhigh"`, porque `/think` es una directiva de pensamiento y `xhigh` es la configuración de esfuerzo de Opus 4.7.
- Anthropic Claude Opus 4.7 también expone `/think max`; se asigna a la misma ruta de esfuerzo máximo propiedad del proveedor.
- Los modelos DeepSeek V4 exponen `/think xhigh|max`; ambos se asignan a DeepSeek `reasoning_effort: "max"`, mientras que los niveles inferiores no `off` se asignan a `high`.
- Los modelos de Ollama con capacidad de pensamiento exponen `/think low|medium|high|max`; `max` se asigna al nativo `think: "high"` porque la API nativa de Ollama acepta las cadenas de esfuerzo `low`, `medium` y `high`.
- Los modelos OpenAI GPT asignan `/think` mediante el soporte de esfuerzo específico del modelo de la Responses API. `/think off` envía `reasoning.effort: "none"` solo cuando el modelo de destino lo admite; de lo contrario, OpenClaw omite la carga útil de razonamiento deshabilitado en lugar de enviar un valor no compatible.
- Las entradas de catálogo personalizadas compatibles con OpenAI pueden optar por `/think xhigh` configurando `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Esto usa los mismos metadatos de compatibilidad que asignan las cargas útiles salientes de esfuerzo de razonamiento de OpenAI, por lo que los menús, la validación de sesión, el CLI del agente y `llm-task` coinciden con el comportamiento de transporte.
- Las referencias obsoletas configuradas de OpenRouter Hunter Alpha omiten la inyección de razonamiento por proxy porque esa ruta retirada podía devolver texto de respuesta final mediante campos de razonamiento.
- Los modelos de Ollama con capacidad de pensamiento exponen `/think low|medium|high|max`; `max` se asigna al valor nativo `think: "high"` porque la API nativa de Ollama acepta las cadenas de esfuerzo `low`, `medium` y `high`.
- Los modelos OpenAI GPT asignan `/think` mediante la compatibilidad de esfuerzo específica del modelo en la Responses API. `/think off` envía `reasoning.effort: "none"` solo cuando el modelo de destino lo admite; de lo contrario, OpenClaw omite la carga de razonamiento deshabilitada en lugar de enviar un valor no compatible.
- Las entradas de catálogo personalizadas compatibles con OpenAI pueden optar por `/think xhigh` estableciendo `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Esto usa los mismos metadatos de compatibilidad que asignan las cargas de esfuerzo de razonamiento salientes de OpenAI, por lo que los menús, la validación de sesión, la CLI del agente y `llm-task` concuerdan con el comportamiento de transporte.
- Las referencias configuradas obsoletas de OpenRouter Hunter Alpha omiten la inyección de razonamiento del proxy porque esa ruta retirada podía devolver texto de respuesta final mediante campos de razonamiento.
- Google Gemini asigna `/think adaptive` al pensamiento dinámico propiedad del proveedor de Gemini. Las solicitudes de Gemini 3 omiten un `thinkingLevel` fijo, mientras que las solicitudes de Gemini 2.5 envían `thinkingBudget: -1`; los niveles fijos siguen asignándose al `thinkingLevel` o presupuesto de Gemini más cercano para esa familia de modelos.
- MiniMax (`minimax/*`) en la ruta de streaming compatible con Anthropic usa de forma predeterminada `thinking: { type: "disabled" }`, salvo que definas explícitamente pensamiento en parámetros de modelo o parámetros de solicitud. Esto evita deltas filtrados de `reasoning_content` desde el formato de stream no nativo de Anthropic de MiniMax.
- MiniMax (`minimax/*`) en la ruta de streaming compatible con Anthropic usa de forma predeterminada `thinking: { type: "disabled" }`, a menos que establezcas explícitamente el pensamiento en parámetros de modelo o de solicitud. Esto evita deltas filtrados de `reasoning_content` desde el formato de streaming no nativo de Anthropic de MiniMax.
- Z.AI (`zai/*`) solo admite pensamiento binario (`on`/`off`). Cualquier nivel que no sea `off` se trata como `on` (asignado a `low`).
- Moonshot (`moonshot/*`) asigna `/think off` a `thinking: { type: "disabled" }` y cualquier nivel que no sea `off` a `thinking: { type: "enabled" }`. Cuando el pensamiento está habilitado, Moonshot solo acepta `tool_choice` `auto|none`; OpenClaw normaliza los valores incompatibles a `auto`.
- Moonshot (`moonshot/*`) asigna `/think off` a `thinking: { type: "disabled" }` y cualquier nivel que no sea `off` a `thinking: { type: "enabled" }`. Cuando el pensamiento está habilitado, Moonshot solo acepta `tool_choice` `auto|none`; OpenClaw normaliza valores incompatibles a `auto`.
## Orden de resolución
1. Directiva en línea en el mensaje (se aplica solo a ese mensaje).
2. Anulación de sesión (definida al enviar un mensaje que solo contiene la directiva).
2. Sobrescritura de sesión (establecida al enviar un mensaje que contiene solo la directiva).
3. Valor predeterminado por agente (`agents.list[].thinkingDefault` en la configuración).
4. Valor predeterminado global (`agents.defaults.thinkingDefault` en la configuración).
5. Reserva: valor predeterminado declarado por el proveedor cuando está disponible; de lo contrario, los modelos con capacidad de razonamiento se resuelven a `medium` o al nivel no `off` compatible más cercano para ese modelo, y los modelos sin razonamiento permanecen en `off`.
5. Respaldo: valor predeterminado declarado por el proveedor cuando esté disponible; de lo contrario, los modelos con capacidad de razonamiento se resuelven a `medium` o al nivel no `off` compatible más cercano para ese modelo, y los modelos sin razonamiento permanecen en `off`.
## Configurar un valor predeterminado de sesión
## Establecer un valor predeterminado de sesión
- Envía un mensaje que sea **solo** la directiva (se permiten espacios en blanco), por ejemplo, `/think:medium` o `/t high`.
- Eso queda fijado para la sesión actual (por remitente de forma predeterminada); se borra con `/think:off` o con el restablecimiento por inactividad de la sesión.
- Se envía una respuesta de confirmación (`Thinking level set to high.` / `Thinking disabled.`). Si el nivel no es válido (por ejemplo, `/thinking big`), el comando se rechaza con una sugerencia y el estado de la sesión no cambia.
- Envía un mensaje que sea **solo** la directiva (se permiten espacios en blanco), por ejemplo `/think:medium` o `/t high`.
- Eso se conserva para la sesión actual (por remitente de forma predeterminada); se borra con `/think:off` o con el reinicio por inactividad de la sesión.
- Se envía una respuesta de confirmación (`Thinking level set to high.` / `Thinking disabled.`). Si el nivel no es válido (por ejemplo, `/thinking big`), el comando se rechaza con una sugerencia y el estado de la sesión queda sin cambios.
- Envía `/think` (o `/think:`) sin argumento para ver el nivel de pensamiento actual.
## Aplicación por agente
- **Pi integrado**: el nivel resuelto se pasa al runtime del agente Pi en proceso.
- **Backend de CLI Claude**: los niveles que no son off se pasan a Claude Code como `--effort` cuando se usa `claude-cli`; consulta [backends de CLI](/es/gateway/cli-backends).
## Modo rápido (/fast)
- Niveles: `on|off`.
- Un mensaje que solo contiene la directiva alterna una anulación de modo rápido de sesión y responde `Fast mode enabled.` / `Fast mode disabled.`.
- Un mensaje que solo contiene la directiva alterna una sobrescritura de modo rápido de sesión y responde `Fast mode enabled.` / `Fast mode disabled.`.
- Envía `/fast` (o `/fast status`) sin modo para ver el estado efectivo actual del modo rápido.
- OpenClaw resuelve el modo rápido en este orden:
1. `/fast on|off` en línea o como única directiva
2. Anulación de sesión
1. `/fast on|off` en línea/solo directiva
2. Sobrescritura de sesión
3. Valor predeterminado por agente (`agents.list[].fastModeDefault`)
4. Configuración por modelo: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Reserva: `off`
5. Respaldo: `off`
- Para `openai/*`, el modo rápido se asigna al procesamiento prioritario de OpenAI enviando `service_tier=priority` en solicitudes Responses compatibles.
- Para `openai-codex/*`, el modo rápido envía la misma marca `service_tier=priority` en Codex Responses. OpenClaw mantiene un único conmutador `/fast` compartido entre ambas rutas de autenticación.
- Para solicitudes públicas directas `anthropic/*`, incluido el tráfico autenticado con OAuth enviado a `api.anthropic.com`, el modo rápido se asigna a los niveles de servicio de Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `openai-codex/*`, el modo rápido envía el mismo indicador `service_tier=priority` en Codex Responses. OpenClaw mantiene un único interruptor `/fast` compartido entre ambas rutas de autenticación.
- Para solicitudes públicas directas `anthropic/*`, incluido el tráfico autenticado con OAuth enviado a `api.anthropic.com`, el modo rápido se asigna a los niveles de servicio de Anthropic: `/fast on` establece `service_tier=auto`, `/fast off` establece `service_tier=standard_only`.
- Para `minimax/*` en la ruta compatible con Anthropic, `/fast on` (o `params.fastMode: true`) reescribe `MiniMax-M2.7` como `MiniMax-M2.7-highspeed`.
- Los parámetros de modelo explícitos Anthropic `serviceTier` / `service_tier` anulan el valor predeterminado de modo rápido cuando ambos están configurados. OpenClaw sigue omitiendo la inyección de nivel de servicio de Anthropic para URL base de proxy que no sean Anthropic.
- Los parámetros de modelo Anthropic explícitos `serviceTier` / `service_tier` sobrescriben el valor predeterminado del modo rápido cuando ambos están establecidos. OpenClaw sigue omitiendo la inyección de nivel de servicio de Anthropic para URL base de proxy que no sean de Anthropic.
- `/status` muestra `Fast` solo cuando el modo rápido está habilitado.
## Directivas detalladas (/verbose o /v)
- Niveles: `on` (mínimo) | `full` | `off` (predeterminado).
- Un mensaje que solo contiene la directiva alterna el modo detallado de sesión y responde `Verbose logging enabled.` / `Verbose logging disabled.`; los niveles no válidos devuelven una sugerencia sin cambiar el estado.
- `/verbose off` almacena una anulación de sesión explícita; bórrala mediante la UI de sesiones eligiendo `inherit`.
- La directiva en línea afecta solo a ese mensaje; en los demás casos se aplican los valores predeterminados de sesión/globales.
- `/verbose off` almacena una sobrescritura de sesión explícita; bórrala mediante la UI de Sessions eligiendo `inherit`.
- La directiva en línea afecta solo a ese mensaje; los valores predeterminados de sesión/globales se aplican en los demás casos.
- Envía `/verbose` (o `/verbose:`) sin argumento para ver el nivel detallado actual.
- Cuando el modo detallado está activado, los agentes que emiten resultados de herramientas estructurados (Pi, otros agentes JSON) devuelven cada llamada de herramienta como su propio mensaje solo de metadatos, con el prefijo `<emoji> <tool-name>: <arg>` cuando está disponible. Estos resúmenes de herramientas se envían en cuanto se inicia cada herramienta (burbujas separadas), no como deltas de streaming.
- Los resúmenes de fallos de herramientas permanecen visibles en modo normal, pero los sufijos de detalle de error sin procesar se ocultan salvo que el modo detallado sea `on` o `full`.
- Cuando el modo detallado está en `full`, las salidas de herramientas también se reenvían después de completarse (burbuja separada, truncada a una longitud segura). Si alternas `/verbose on|full|off` mientras una ejecución está en curso, las burbujas de herramientas posteriores respetan la nueva configuración.
- `agents.defaults.toolProgressDetail` controla la forma de los resúmenes de herramientas de `/verbose` y las líneas de herramientas de borrador de progreso. Usa `"explain"` (predeterminado) para etiquetas humanas compactas como `🛠️ Exec: checking JS syntax`; usa `"raw"` cuando también quieras anexar el comando/detalle sin procesar para depuración. `agents.list[].toolProgressDetail` por agente anula el valor predeterminado.
- Cuando el modo detallado está activado, los agentes que emiten resultados de herramientas estructurados (Pi, otros agentes JSON) envían cada llamada de herramienta como su propio mensaje solo de metadatos, con el prefijo `<emoji> <tool-name>: <arg>` cuando está disponible. Estos resúmenes de herramientas se envían tan pronto como cada herramienta se inicia (burbujas separadas), no como deltas de streaming.
- Los resúmenes de fallos de herramientas permanecen visibles en modo normal, pero los sufijos con detalle de error sin procesar se ocultan a menos que el modo detallado sea `on` o `full`.
- Cuando el modo detallado es `full`, las salidas de herramientas también se reenvían después de completarse (burbuja separada, truncada a una longitud segura). Si alternas `/verbose on|full|off` mientras una ejecución está en curso, las burbujas de herramientas posteriores respetan la nueva configuración.
- `agents.defaults.toolProgressDetail` controla la forma de los resúmenes de herramientas de `/verbose` y las líneas de herramientas de borrador de progreso. Usa `"explain"` (predeterminado) para etiquetas humanas compactas como `🛠️ Exec: checking JS syntax`; usa `"raw"` cuando también quieras anexar el comando/detalle sin procesar para depuración. `agents.list[].toolProgressDetail` por agente sobrescribe el valor predeterminado.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## Directivas de traza de Plugin (/trace)
- Niveles: `on` | `off` (predeterminado).
- Un mensaje que solo contiene la directiva alterna la salida de traza de plugin de sesión y responde `Plugin trace enabled.` / `Plugin trace disabled.`.
- La directiva en línea afecta solo a ese mensaje; en los demás casos se aplican los valores predeterminados de sesión/globales.
- Un mensaje que solo contiene la directiva alterna la salida de traza de Plugin de sesión y responde `Plugin trace enabled.` / `Plugin trace disabled.`.
- La directiva en línea afecta solo a ese mensaje; los valores predeterminados de sesión/globales se aplican en los demás casos.
- Envía `/trace` (o `/trace:`) sin argumento para ver el nivel de traza actual.
- `/trace` es más estrecho que `/verbose`: solo expone líneas de traza/depuración propiedad del plugin, como resúmenes de depuración de Active Memory.
- Las líneas de traza pueden aparecer en `/status` y como un mensaje de diagnóstico de seguimiento después de la respuesta normal del asistente.
- `/trace` es más limitado que `/verbose`: solo expone líneas de traza/depuración propiedad del plugin, como resúmenes de depuración de Active Memory.
- Las líneas de traza pueden aparecer en `/status` y como un mensaje de diagnóstico posterior después de la respuesta normal del asistente.
## Visibilidad del razonamiento (/reasoning)
- Niveles: `on|off|stream`.
- Un mensaje que solo contiene la directiva alterna si los bloques de pensamiento se muestran en las respuestas.
- Cuando está habilitado, el razonamiento se envía como un **mensaje separado** con el prefijo `Reasoning:`.
- `stream` (solo Telegram): transmite el razonamiento en la burbuja de borrador de Telegram mientras se genera la respuesta, y luego envía la respuesta final sin razonamiento.
- `stream` (solo Telegram): transmite el razonamiento a la burbuja de borrador de Telegram mientras se genera la respuesta y luego envía la respuesta final sin razonamiento.
- Alias: `/reason`.
- Envía `/reasoning` (o `/reasoning:`) sin argumento para ver el nivel de razonamiento actual.
- Orden de resolución: directiva en línea, luego anulación de sesión, luego valor predeterminado por agente (`agents.list[].reasoningDefault`), luego reserva (`off`).
- Orden de resolución: directiva en línea, luego sobrescritura de sesión, luego valor predeterminado por agente (`agents.list[].reasoningDefault`), luego respaldo (`off`).
Las etiquetas de razonamiento de modelos locales mal formadas se manejan de forma conservadora. Los bloques cerrados `<think>...</think>` permanecen ocultos en respuestas normales, y el razonamiento sin cerrar después de texto ya visible también se oculta. Si una respuesta está completamente envuelta en una única etiqueta de apertura sin cerrar y de otro modo se entregaría como texto vacío, OpenClaw elimina la etiqueta de apertura mal formada y entrega el texto restante.
Las etiquetas de razonamiento de modelos locales con formato incorrecto se manejan de forma conservadora. Los bloques cerrados `<think>...</think>` permanecen ocultos en respuestas normales, y el razonamiento no cerrado después de texto ya visible también se oculta. Si una respuesta está totalmente envuelta en una sola etiqueta de apertura no cerrada y, de otro modo, se entregaría como texto vacío, OpenClaw elimina la etiqueta de apertura con formato incorrecto y entrega el texto restante.
## Relacionado
- La documentación del modo elevado está en [Modo elevado](/es/tools/elevated).
- La documentación del modo elevado está en [modo elevado](/es/tools/elevated).
## Heartbeats
- El cuerpo de la sonda Heartbeat es el prompt de Heartbeat configurado (predeterminado: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Las directivas en línea en un mensaje de Heartbeat se aplican como de costumbre (pero evita cambiar valores predeterminados de sesión desde Heartbeats).
- La entrega de Heartbeat se limita de forma predeterminada a la carga útil final. Para enviar también el mensaje `Reasoning:` separado (cuando esté disponible), define `agents.defaults.heartbeat.includeReasoning: true` o `agents.list[].heartbeat.includeReasoning: true` por agente.
- El cuerpo del sondeo Heartbeat es el prompt de Heartbeat configurado (predeterminado: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Las directivas en línea en un mensaje de Heartbeat se aplican como de costumbre (pero evita cambiar valores predeterminados de sesión desde Heartbeats).
- La entrega de Heartbeat usa de forma predeterminada solo la carga final. Para enviar también el mensaje separado `Reasoning:` (cuando esté disponible), establece `agents.defaults.heartbeat.includeReasoning: true` o `agents.list[].heartbeat.includeReasoning: true` por agente.
## UI de chat web
- El selector de pensamiento del chat web refleja el nivel almacenado de la sesión desde el almacén/configuración de sesión entrante cuando se carga la página.
- Elegir otro nivel escribe la anulación de sesión inmediatamente mediante `sessions.patch`; no espera al siguiente envío y no es una anulación `thinkingOnce` de un solo uso.
- La primera opción siempre es `Default (<resolved level>)`, donde el valor predeterminado resuelto proviene del perfil de pensamiento del proveedor del modelo de la sesión activa más la misma lógica de reserva que usan `/status` y `session_status`.
- El selector usa `thinkingLevels` devuelto por la fila/valores predeterminados de sesión del Gateway, con `thinkingOptions` conservado como lista heredada de etiquetas. La UI del navegador no mantiene su propia lista regex de proveedores; los plugins son propietarios de los conjuntos de niveles específicos de modelo.
- `/think:<level>` sigue funcionando y actualiza el mismo nivel almacenado de sesión, por lo que las directivas del chat y el selector permanecen sincronizados.
- Elegir otro nivel escribe la sobrescritura de sesión inmediatamente mediante `sessions.patch`; no espera al siguiente envío y no es una sobrescritura `thinkingOnce` de un solo uso.
- La primera opción siempre es `Default (<resolved level>)`, donde el valor predeterminado resuelto proviene del perfil de pensamiento del proveedor del modelo activo de la sesión más la misma lógica de respaldo que usan `/status` y `session_status`.
- El selector usa `thinkingLevels` devuelto por la fila/valores predeterminados de sesión del gateway, con `thinkingOptions` conservado como una lista de etiquetas heredada. La UI del navegador no conserva su propia lista de regex de proveedor; los plugins poseen los conjuntos de niveles específicos de modelo.
- `/think:<level>` sigue funcionando y actualiza el mismo nivel de sesión almacenado, por lo que las directivas de chat y el selector permanecen sincronizados.
## Perfiles de proveedor
- Los plugins de proveedor pueden exponer `resolveThinkingProfile(ctx)` para definir los niveles admitidos y el valor predeterminado del modelo.
- Los plugins de proveedor que actúan como proxy de modelos Claude deben reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que los catálogos directos de Anthropic y de proxy permanezcan alineados.
- Los plugins de proveedor pueden exponer `resolveThinkingProfile(ctx)` para definir los niveles admitidos por el modelo y el valor predeterminado.
- Los plugins de proveedor que actúen como proxy para modelos Claude deben reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que los catálogos directos de Anthropic y de proxy permanezcan alineados.
- Cada nivel de perfil tiene un `id` canónico almacenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` o `max`) y puede incluir una `label` de visualización. Los proveedores binarios usan `{ id: "low", label: "on" }`.
- Los plugins de herramientas que necesiten validar una anulación explícita del razonamiento deben usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` junto con `api.runtime.agent.normalizeThinkingLevel(...)`; no deben mantener sus propias listas de niveles de proveedor/modelo.
- Los plugins de herramientas con acceso a metadatos configurados de modelos personalizados pueden pasar `catalog` a `resolveThinkingPolicy` para que las suscripciones de `compat.supportedReasoningEfforts` se reflejen en la validación del lado del plugin.
- Los plugins de herramientas que necesiten validar una anulación explícita de razonamiento deben usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` junto con `api.runtime.agent.normalizeThinkingLevel(...)`; no deben mantener sus propias listas de niveles por proveedor/modelo.
- Los plugins de herramientas con acceso a metadatos configurados de modelos personalizados pueden pasar `catalog` a `resolveThinkingPolicy` para que las suscripciones voluntarias de `compat.supportedReasoningEfforts` se reflejen en la validación del lado del plugin.
- Los hooks heredados publicados (`supportsXHighThinking`, `isBinaryThinking` y `resolveDefaultThinkingLevel`) permanecen como adaptadores de compatibilidad, pero los nuevos conjuntos de niveles personalizados deben usar `resolveThinkingProfile`.
- Las filas/valores predeterminados del Gateway exponen `thinkingLevels`, `thinkingOptions` y `thinkingDefault` para que los clientes ACP/chat representen los mismos identificadores y etiquetas de perfil que usa la validación en tiempo de ejecución.
- Las filas/valores predeterminados del Gateway exponen `thinkingLevels`, `thinkingOptions` y `thinkingDefault` para que los clientes de ACP/chat representen los mismos ids y etiquetas de perfil que usa la validación en tiempo de ejecución.