chore(i18n): refresh es translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
1d07fbb4c0
commit
cfa2d9c970
@ -5,10 +5,10 @@ read_when:
|
||||
summary: 'Espacio de trabajo del agente: ubicación, diseño y estrategia de copia de seguridad'
|
||||
title: Espacio de trabajo del agente
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:39:30Z"
|
||||
generated_at: "2026-04-18T04:59:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3735633f1098c733415369f9836fdbbc0bf869636a24ed42e95e6784610d964a
|
||||
source_hash: dd2e74614d8d45df04b1bbda48e2224e778b621803d774d38e4b544195eb234e
|
||||
source_path: concepts/agent-workspace.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,24 +16,24 @@ x-i18n:
|
||||
# Espacio de trabajo del agente
|
||||
|
||||
El espacio de trabajo es el hogar del agente. Es el único directorio de trabajo usado para
|
||||
herramientas de archivos y para el contexto del espacio de trabajo. Mantenlo privado y trátalo como memoria.
|
||||
las herramientas de archivos y para el contexto del espacio de trabajo. Mantenlo privado y trátalo como memoria.
|
||||
|
||||
Esto es independiente de `~/.openclaw/`, que almacena configuración, credenciales y
|
||||
sesiones.
|
||||
|
||||
**Importante:** el espacio de trabajo es el **cwd predeterminado**, no un sandbox estricto. Las herramientas
|
||||
resuelven rutas relativas con respecto al espacio de trabajo, pero las rutas absolutas aún pueden llegar
|
||||
a otras ubicaciones del host a menos que el sandboxing esté habilitado. Si necesitas aislamiento, usa
|
||||
[`agents.defaults.sandbox`](/gateway/sandboxing) (y/o configuración de sandbox por agente).
|
||||
Cuando el sandboxing está habilitado y `workspaceAccess` no es `"rw"`, las herramientas operan
|
||||
dentro de un espacio de trabajo aislado bajo `~/.openclaw/sandboxes`, no en el espacio de trabajo del host.
|
||||
**Importante:** el espacio de trabajo es el **cwd predeterminado**, no un sandbox rígido. Las herramientas
|
||||
resuelven las rutas relativas contra el espacio de trabajo, pero las rutas absolutas aún pueden llegar
|
||||
a otras ubicaciones del host a menos que el sandbox esté habilitado. Si necesitas aislamiento, usa
|
||||
[`agents.defaults.sandbox`](/es/gateway/sandboxing) (y/o la configuración de sandbox por agente).
|
||||
Cuando el sandbox está habilitado y `workspaceAccess` no es `"rw"`, las herramientas operan
|
||||
dentro de un espacio de trabajo aislado bajo `~/.openclaw/sandboxes`, no en tu espacio de trabajo del host.
|
||||
|
||||
## Ubicación predeterminada
|
||||
|
||||
- Predeterminado: `~/.openclaw/workspace`
|
||||
- Si `OPENCLAW_PROFILE` está establecido y no es `"default"`, el valor predeterminado pasa a ser
|
||||
`~/.openclaw/workspace-<profile>`.
|
||||
- Sobrescríbelo en `~/.openclaw/openclaw.json`:
|
||||
- Puedes sobrescribirlo en `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -44,12 +44,11 @@ dentro de un espacio de trabajo aislado bajo `~/.openclaw/sandboxes`, no en el e
|
||||
```
|
||||
|
||||
`openclaw onboard`, `openclaw configure` o `openclaw setup` crearán el
|
||||
espacio de trabajo y sembrarán los archivos bootstrap si faltan.
|
||||
Las copias semilla del sandbox solo aceptan archivos normales dentro del espacio de trabajo; los
|
||||
alias de symlink/hardlink que se resuelven fuera del espacio de trabajo de origen se ignoran.
|
||||
espacio de trabajo y sembrarán los archivos de arranque si faltan.
|
||||
Las copias de siembra del sandbox solo aceptan archivos regulares dentro del espacio de trabajo;
|
||||
los alias de enlaces simbólicos/enlaces físicos que se resuelven fuera del espacio de trabajo de origen se ignoran.
|
||||
|
||||
Si ya gestionas tú mismo los archivos del espacio de trabajo, puedes desactivar la
|
||||
creación de archivos bootstrap:
|
||||
Si ya administras tú mismo los archivos del espacio de trabajo, puedes deshabilitar la creación de archivos de arranque:
|
||||
|
||||
```json5
|
||||
{ agent: { skipBootstrap: true } }
|
||||
@ -58,15 +57,15 @@ creación de archivos bootstrap:
|
||||
## Carpetas adicionales del espacio de trabajo
|
||||
|
||||
Las instalaciones antiguas pueden haber creado `~/openclaw`. Mantener varios directorios de espacio de trabajo
|
||||
puede causar confusión por desajustes de autenticación o de estado, porque solo un
|
||||
puede causar deriva confusa de autenticación o estado, porque solo un
|
||||
espacio de trabajo está activo a la vez.
|
||||
|
||||
**Recomendación:** mantén un único espacio de trabajo activo. Si ya no usas las
|
||||
carpetas extra, archívalas o muévelas a la Papelera (por ejemplo `trash ~/openclaw`).
|
||||
Si intencionadamente mantienes varios espacios de trabajo, asegúrate de que
|
||||
carpetas adicionales, archívalas o muévelas a la Papelera (por ejemplo `trash ~/openclaw`).
|
||||
Si intencionalmente mantienes varios espacios de trabajo, asegúrate de que
|
||||
`agents.defaults.workspace` apunte al activo.
|
||||
|
||||
`openclaw doctor` avisa cuando detecta directorios adicionales de espacio de trabajo.
|
||||
`openclaw doctor` advierte cuando detecta directorios adicionales del espacio de trabajo.
|
||||
|
||||
## Mapa de archivos del espacio de trabajo (qué significa cada archivo)
|
||||
|
||||
@ -75,88 +74,88 @@ Estos son los archivos estándar que OpenClaw espera dentro del espacio de traba
|
||||
- `AGENTS.md`
|
||||
- Instrucciones operativas para el agente y cómo debe usar la memoria.
|
||||
- Se carga al inicio de cada sesión.
|
||||
- Buen lugar para reglas, prioridades y detalles de "cómo comportarse".
|
||||
- Buen lugar para reglas, prioridades y detalles sobre "cómo comportarse".
|
||||
|
||||
- `SOUL.md`
|
||||
- Personalidad, tono y límites.
|
||||
- Se carga en cada sesión.
|
||||
- Guía: [Guía de personalidad de SOUL.md](/concepts/soul)
|
||||
- Guía: [Guía de personalidad de SOUL.md](/es/concepts/soul)
|
||||
|
||||
- `USER.md`
|
||||
- Quién es el usuario y cómo dirigirse a él.
|
||||
- Se carga en cada sesión.
|
||||
|
||||
- `IDENTITY.md`
|
||||
- El nombre, estilo y emoji del agente.
|
||||
- Se crea/actualiza durante el ritual de bootstrap.
|
||||
- El nombre, la vibra y el emoji del agente.
|
||||
- Se crea/actualiza durante el ritual de arranque.
|
||||
|
||||
- `TOOLS.md`
|
||||
- Notas sobre tus herramientas y convenciones locales.
|
||||
- Notas sobre tus herramientas locales y convenciones.
|
||||
- No controla la disponibilidad de herramientas; es solo orientación.
|
||||
|
||||
- `HEARTBEAT.md`
|
||||
- Lista de comprobación opcional y pequeña para ejecuciones de heartbeat.
|
||||
- Mantenla breve para evitar gastar tokens.
|
||||
- Lista de verificación opcional y pequeña para ejecuciones de Heartbeat.
|
||||
- Mantenla breve para evitar gasto de tokens.
|
||||
|
||||
- `BOOT.md`
|
||||
- Lista de comprobación opcional de arranque ejecutada al reiniciar la gateway cuando los hooks internos están habilitados.
|
||||
- Lista de verificación opcional de inicio ejecutada al reiniciar el Gateway cuando los hooks internos están habilitados.
|
||||
- Mantenla breve; usa la herramienta de mensajes para envíos salientes.
|
||||
|
||||
- `BOOTSTRAP.md`
|
||||
- Ritual único de la primera ejecución.
|
||||
- Ritual único de primera ejecución.
|
||||
- Solo se crea para un espacio de trabajo completamente nuevo.
|
||||
- Elimínalo cuando el ritual haya terminado.
|
||||
- Elimínalo una vez que el ritual esté completo.
|
||||
|
||||
- `memory/YYYY-MM-DD.md`
|
||||
- Registro diario de memoria (un archivo por día).
|
||||
- Se recomienda leer el de hoy y el de ayer al inicio de la sesión.
|
||||
- Se recomienda leer el de hoy y el de ayer al iniciar la sesión.
|
||||
|
||||
- `MEMORY.md` (opcional)
|
||||
- Memoria de largo plazo curada.
|
||||
- Cárgala solo en la sesión principal y privada (no en contextos compartidos/de grupo).
|
||||
|
||||
Consulta [Memory](/concepts/memory) para ver el flujo de trabajo y el vaciado automático de memoria.
|
||||
Consulta [Memory](/es/concepts/memory) para el flujo de trabajo y el volcado automático de memoria.
|
||||
|
||||
- `skills/` (opcional)
|
||||
- Skills específicas del espacio de trabajo.
|
||||
- Skills específicos del espacio de trabajo.
|
||||
- Ubicación de Skills de mayor precedencia para ese espacio de trabajo.
|
||||
- Sobrescribe Skills de agentes del proyecto, Skills de agentes personales, Skills gestionadas, Skills integradas y `skills.load.extraDirs` cuando los nombres colisionan.
|
||||
- Sobrescribe Skills del agente del proyecto, Skills personales del agente, Skills administrados, Skills incluidos y `skills.load.extraDirs` cuando los nombres coinciden.
|
||||
|
||||
- `canvas/` (opcional)
|
||||
- Archivos de UI de canvas para pantallas de nodo (por ejemplo `canvas/index.html`).
|
||||
- Archivos de la interfaz Canvas para visualizaciones de nodos (por ejemplo `canvas/index.html`).
|
||||
|
||||
Si falta cualquier archivo bootstrap, OpenClaw inyecta un marcador de "archivo faltante" en
|
||||
la sesión y continúa. Los archivos bootstrap grandes se truncan al inyectarse;
|
||||
ajusta los límites con `agents.defaults.bootstrapMaxChars` (predeterminado: 20000) y
|
||||
`agents.defaults.bootstrapTotalMaxChars` (predeterminado: 150000).
|
||||
`openclaw setup` puede recrear los valores predeterminados que falten sin sobrescribir
|
||||
Si falta algún archivo de arranque, OpenClaw inserta un marcador de "archivo faltante" en
|
||||
la sesión y continúa. Los archivos de arranque grandes se truncan al insertarse;
|
||||
ajusta los límites con `agents.defaults.bootstrapMaxChars` (predeterminado: 12000) y
|
||||
`agents.defaults.bootstrapTotalMaxChars` (predeterminado: 60000).
|
||||
`openclaw setup` puede recrear los valores predeterminados faltantes sin sobrescribir los
|
||||
archivos existentes.
|
||||
|
||||
## Lo que NO está en el espacio de trabajo
|
||||
|
||||
Esto vive bajo `~/.openclaw/` y NO debe confirmarse en el repositorio del espacio de trabajo:
|
||||
Estos elementos viven bajo `~/.openclaw/` y NO deben confirmarse en el repositorio del espacio de trabajo:
|
||||
|
||||
- `~/.openclaw/openclaw.json` (configuración)
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (perfiles de autenticación de modelos: OAuth + API keys)
|
||||
- `~/.openclaw/credentials/` (estado de canal/proveedor más datos heredados de importación OAuth)
|
||||
- `~/.openclaw/agents/<agentId>/sessions/` (transcripciones de sesión + metadatos)
|
||||
- `~/.openclaw/skills/` (Skills gestionadas)
|
||||
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (perfiles de autenticación del modelo: OAuth + claves API)
|
||||
- `~/.openclaw/credentials/` (estado de canal/proveedor más datos de importación heredados de OAuth)
|
||||
- `~/.openclaw/agents/<agentId>/sessions/` (transcripciones de sesiones + metadatos)
|
||||
- `~/.openclaw/skills/` (Skills administrados)
|
||||
|
||||
Si necesitas migrar sesiones o configuración, cópialas por separado y mantenlas
|
||||
fuera del control de versiones.
|
||||
|
||||
## Copia de seguridad con Git (recomendada, privada)
|
||||
|
||||
Trata el espacio de trabajo como memoria privada. Ponlo en un repositorio git **privado** para que esté
|
||||
Trata el espacio de trabajo como memoria privada. Ponlo en un repositorio de git **privado** para que esté
|
||||
respaldado y sea recuperable.
|
||||
|
||||
Ejecuta estos pasos en la máquina donde se ejecuta la Gateway (ahí es donde vive el
|
||||
Ejecuta estos pasos en la máquina donde se ejecuta el Gateway (ahí es donde vive el
|
||||
espacio de trabajo).
|
||||
|
||||
### 1) Inicializar el repositorio
|
||||
### 1) Inicializa el repositorio
|
||||
|
||||
Si git está instalado, los espacios de trabajo completamente nuevos se inicializan automáticamente. Si este
|
||||
espacio de trabajo todavía no es un repositorio, ejecuta:
|
||||
espacio de trabajo aún no es un repositorio, ejecuta:
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace
|
||||
@ -165,12 +164,12 @@ git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
|
||||
git commit -m "Add agent workspace"
|
||||
```
|
||||
|
||||
### 2) Añadir un remoto privado (opciones sencillas para principiantes)
|
||||
### 2) Añade un remoto privado (opciones amigables para principiantes)
|
||||
|
||||
Opción A: interfaz web de GitHub
|
||||
|
||||
1. Crea un nuevo repositorio **privado** en GitHub.
|
||||
2. No lo inicialices con un README (evita conflictos de merge).
|
||||
1. Crea un repositorio **privado** nuevo en GitHub.
|
||||
2. No lo inicialices con un README (evita conflictos de fusión).
|
||||
3. Copia la URL remota HTTPS.
|
||||
4. Añade el remoto y haz push:
|
||||
|
||||
@ -189,8 +188,8 @@ gh repo create openclaw-workspace --private --source . --remote origin --push
|
||||
|
||||
Opción C: interfaz web de GitLab
|
||||
|
||||
1. Crea un nuevo repositorio **privado** en GitLab.
|
||||
2. No lo inicialices con un README (evita conflictos de merge).
|
||||
1. Crea un repositorio **privado** nuevo en GitLab.
|
||||
2. No lo inicialices con un README (evita conflictos de fusión).
|
||||
3. Copia la URL remota HTTPS.
|
||||
4. Añade el remoto y haz push:
|
||||
|
||||
@ -213,14 +212,14 @@ git push
|
||||
|
||||
Incluso en un repositorio privado, evita almacenar secretos en el espacio de trabajo:
|
||||
|
||||
- API keys, tokens OAuth, contraseñas o credenciales privadas.
|
||||
- Claves API, tokens OAuth, contraseñas o credenciales privadas.
|
||||
- Cualquier cosa bajo `~/.openclaw/`.
|
||||
- Volcados sin procesar de chats o adjuntos sensibles.
|
||||
- Volcados sin procesar de chats o archivos adjuntos sensibles.
|
||||
|
||||
Si debes almacenar referencias sensibles, usa placeholders y guarda el secreto
|
||||
real en otro lugar (gestor de contraseñas, variables de entorno o `~/.openclaw/`).
|
||||
Si debes almacenar referencias sensibles, usa marcadores de posición y guarda el secreto real en otra parte
|
||||
(administrador de contraseñas, variables de entorno o `~/.openclaw/`).
|
||||
|
||||
Inicio sugerido para `.gitignore`:
|
||||
Plantilla sugerida para `.gitignore`:
|
||||
|
||||
```gitignore
|
||||
.DS_Store
|
||||
@ -230,24 +229,24 @@ Inicio sugerido para `.gitignore`:
|
||||
**/secrets*
|
||||
```
|
||||
|
||||
## Mover el espacio de trabajo a una nueva máquina
|
||||
## Mover el espacio de trabajo a una máquina nueva
|
||||
|
||||
1. Clona el repositorio en la ruta deseada (predeterminada `~/.openclaw/workspace`).
|
||||
2. Establece `agents.defaults.workspace` en esa ruta dentro de `~/.openclaw/openclaw.json`.
|
||||
3. Ejecuta `openclaw setup --workspace <path>` para sembrar cualquier archivo faltante.
|
||||
4. Si necesitas sesiones, copia `~/.openclaw/agents/<agentId>/sessions/` desde la
|
||||
máquina antigua por separado.
|
||||
4. Si necesitas las sesiones, copia `~/.openclaw/agents/<agentId>/sessions/` desde la
|
||||
máquina anterior por separado.
|
||||
|
||||
## Notas avanzadas
|
||||
|
||||
- El enrutamiento multiagente puede usar distintos espacios de trabajo por agente. Consulta
|
||||
[Enrutamiento de canales](/channels/channel-routing) para la configuración de enrutamiento.
|
||||
- Si `agents.defaults.sandbox` está habilitado, las sesiones no principales pueden usar
|
||||
espacios de trabajo aislados por sesión bajo `agents.defaults.sandbox.workspaceRoot`.
|
||||
- El enrutamiento de múltiples agentes puede usar diferentes espacios de trabajo por agente. Consulta
|
||||
[Enrutamiento de canales](/es/channels/channel-routing) para la configuración de enrutamiento.
|
||||
- Si `agents.defaults.sandbox` está habilitado, las sesiones no principales pueden usar espacios de trabajo
|
||||
aislados por sesión bajo `agents.defaults.sandbox.workspaceRoot`.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Órdenes permanentes](/automation/standing-orders) — instrucciones persistentes en archivos del espacio de trabajo
|
||||
- [Heartbeat](/gateway/heartbeat) — archivo de espacio de trabajo HEARTBEAT.md
|
||||
- [Sesión](/concepts/session) — rutas de almacenamiento de sesiones
|
||||
- [Sandboxing](/gateway/sandboxing) — acceso al espacio de trabajo en entornos aislados
|
||||
- [Standing Orders](/es/automation/standing-orders) — instrucciones persistentes en archivos del espacio de trabajo
|
||||
- [Heartbeat](/es/gateway/heartbeat) — archivo `HEARTBEAT.md` del espacio de trabajo
|
||||
- [Session](/es/concepts/session) — rutas de almacenamiento de sesiones
|
||||
- [Sandboxing](/es/gateway/sandboxing) — acceso al espacio de trabajo en entornos con sandbox
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Quieres entender qué significa “contexto” en OpenClaw
|
||||
- Estás depurando por qué el modelo “sabe” algo (o por qué lo olvidó)
|
||||
- Estás depurando por qué el modelo “sabe” algo (o lo olvidó)
|
||||
- Quieres reducir la sobrecarga de contexto (`/context`, `/status`, `/compact`)
|
||||
summary: 'Contexto: lo que ve el modelo, cómo se construye y cómo inspeccionarlo'
|
||||
summary: 'Contexto: qué ve el modelo, cómo se construye y cómo inspeccionarlo'
|
||||
title: Contexto
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T23:28:13Z"
|
||||
generated_at: "2026-04-18T04:59:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d
|
||||
source_hash: 477ccb1d9654968d0e904b6846b32b8c14db6b6c0d3d2ec2b7409639175629f9
|
||||
source_path: concepts/context.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -20,21 +20,21 @@ x-i18n:
|
||||
|
||||
Modelo mental para principiantes:
|
||||
|
||||
- **Prompt del sistema** (construido por OpenClaw): reglas, herramientas, lista de Skills, hora/entorno de ejecución y archivos del espacio de trabajo inyectados.
|
||||
- **Historial de la conversación**: tus mensajes + los mensajes del asistente de esta sesión.
|
||||
- **Prompt del sistema** (construido por OpenClaw): reglas, herramientas, lista de Skills, tiempo/runtime y archivos del espacio de trabajo inyectados.
|
||||
- **Historial de la conversación**: tus mensajes + los mensajes del asistente para esta sesión.
|
||||
- **Llamadas/resultados de herramientas + adjuntos**: salida de comandos, lecturas de archivos, imágenes/audio, etc.
|
||||
|
||||
El contexto _no es lo mismo_ que la “memoria”: la memoria puede almacenarse en disco y recargarse más tarde; el contexto es lo que está dentro de la ventana actual del modelo.
|
||||
El contexto _no es lo mismo_ que la “memoria”: la memoria puede almacenarse en disco y volver a cargarse más tarde; el contexto es lo que está dentro de la ventana actual del modelo.
|
||||
|
||||
## Inicio rápido (inspeccionar el contexto)
|
||||
|
||||
- `/status` → vista rápida de “¿qué tan llena está mi ventana?” + configuración de la sesión.
|
||||
- `/context list` → qué está inyectado + tamaños aproximados (por archivo + totales).
|
||||
- `/context detail` → desglose más profundo: por archivo, tamaños de esquema de herramientas, tamaños de entradas de Skills y tamaño del prompt del sistema.
|
||||
- `/usage tokens` → agrega un pie de uso por respuesta a las respuestas normales.
|
||||
- `/compact` → resume el historial más antiguo en una entrada compacta para liberar espacio en la ventana.
|
||||
- `/context detail` → desglose más profundo: por archivo, tamaños de esquema por herramienta, tamaños de entrada por skill y tamaño del prompt del sistema.
|
||||
- `/usage tokens` → añade un pie de uso por respuesta a las respuestas normales.
|
||||
- `/compact` → resume el historial anterior en una entrada compacta para liberar espacio en la ventana.
|
||||
|
||||
Consulta también: [Comandos con barra](/es/tools/slash-commands), [Uso de tokens y costos](/es/reference/token-use), [Compaction](/es/concepts/compaction).
|
||||
Consulta también: [Comandos de barra](/es/tools/slash-commands), [Uso de tokens y costos](/es/reference/token-use), [Compaction](/es/concepts/compaction).
|
||||
|
||||
## Salida de ejemplo
|
||||
|
||||
@ -43,44 +43,44 @@ Los valores varían según el modelo, el proveedor, la política de herramientas
|
||||
### `/context list`
|
||||
|
||||
```
|
||||
🧠 Desglose del contexto
|
||||
Espacio de trabajo: <workspaceDir>
|
||||
Máximo de bootstrap/archivo: 20,000 caracteres
|
||||
🧠 Context breakdown
|
||||
Workspace: <workspaceDir>
|
||||
Bootstrap max/file: 12,000 chars
|
||||
Sandbox: mode=non-main sandboxed=false
|
||||
Prompt del sistema (ejecución): 38,412 caracteres (~9,603 tokens) (Contexto del proyecto 23,901 caracteres (~5,976 tokens))
|
||||
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
|
||||
|
||||
Archivos del espacio de trabajo inyectados:
|
||||
- AGENTS.md: OK | bruto 1,742 caracteres (~436 tokens) | inyectado 1,742 caracteres (~436 tokens)
|
||||
- SOUL.md: OK | bruto 912 caracteres (~228 tokens) | inyectado 912 caracteres (~228 tokens)
|
||||
- TOOLS.md: TRUNCATED | bruto 54,210 caracteres (~13,553 tokens) | inyectado 20,962 caracteres (~5,241 tokens)
|
||||
- IDENTITY.md: OK | bruto 211 caracteres (~53 tokens) | inyectado 211 caracteres (~53 tokens)
|
||||
- USER.md: OK | bruto 388 caracteres (~97 tokens) | inyectado 388 caracteres (~97 tokens)
|
||||
- HEARTBEAT.md: MISSING | bruto 0 | inyectado 0
|
||||
- BOOTSTRAP.md: OK | 0 caracteres (~0 tokens) | inyectado 0 caracteres (~0 tokens)
|
||||
Injected workspace files:
|
||||
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
|
||||
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
|
||||
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
|
||||
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
|
||||
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
|
||||
- HEARTBEAT.md: MISSING | raw 0 | injected 0
|
||||
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
|
||||
|
||||
Lista de Skills (texto del prompt del sistema): 2,184 caracteres (~546 tokens) (12 Skills)
|
||||
Herramientas: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Lista de herramientas (texto del prompt del sistema): 1,032 caracteres (~258 tokens)
|
||||
Esquemas de herramientas (JSON): 31,988 caracteres (~7,997 tokens) (cuentan para el contexto; no se muestran como texto)
|
||||
Herramientas: (igual que arriba)
|
||||
Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
|
||||
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Tool list (system prompt text): 1,032 chars (~258 tok)
|
||||
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
|
||||
Tools: (same as above)
|
||||
|
||||
Tokens de sesión (en caché): 14,250 total / ctx=32,000
|
||||
Session tokens (cached): 14,250 total / ctx=32,000
|
||||
```
|
||||
|
||||
### `/context detail`
|
||||
|
||||
```
|
||||
🧠 Desglose del contexto (detallado)
|
||||
🧠 Context breakdown (detailed)
|
||||
…
|
||||
Principales Skills (tamaño de entrada del prompt):
|
||||
- frontend-design: 412 caracteres (~103 tokens)
|
||||
- oracle: 401 caracteres (~101 tokens)
|
||||
… (+10 más Skills)
|
||||
Top skills (prompt entry size):
|
||||
- frontend-design: 412 chars (~103 tok)
|
||||
- oracle: 401 chars (~101 tok)
|
||||
… (+10 more skills)
|
||||
|
||||
Principales herramientas (tamaño del esquema):
|
||||
- browser: 9,812 caracteres (~2,453 tokens)
|
||||
- exec: 6,240 caracteres (~1,560 tokens)
|
||||
… (+N más herramientas)
|
||||
Top tools (schema size):
|
||||
- browser: 9,812 chars (~2,453 tok)
|
||||
- exec: 6,240 chars (~1,560 tok)
|
||||
… (+N more tools)
|
||||
```
|
||||
|
||||
## Qué cuenta para la ventana de contexto
|
||||
@ -91,25 +91,25 @@ Todo lo que recibe el modelo cuenta, incluido:
|
||||
- Historial de la conversación.
|
||||
- Llamadas de herramientas + resultados de herramientas.
|
||||
- Adjuntos/transcripciones (imágenes/audio/archivos).
|
||||
- Resúmenes de Compaction y artefactos de poda.
|
||||
- “Wrappers” del proveedor o encabezados ocultos (no visibles, pero igualmente cuentan).
|
||||
- Resúmenes de Compaction y artefactos de pruning.
|
||||
- “Wrappers” del proveedor o encabezados ocultos (no visibles, pero aun así cuentan).
|
||||
|
||||
## Cómo OpenClaw construye el prompt del sistema
|
||||
|
||||
El prompt del sistema es **propiedad de OpenClaw** y se reconstruye en cada ejecución. Incluye:
|
||||
El prompt del sistema **pertenece a OpenClaw** y se reconstruye en cada ejecución. Incluye:
|
||||
|
||||
- Lista de herramientas + descripciones breves.
|
||||
- Lista de Skills (solo metadatos; ver abajo).
|
||||
- Ubicación del espacio de trabajo.
|
||||
- Hora (UTC + hora del usuario convertida, si está configurada).
|
||||
- Metadatos del entorno de ejecución (host/SO/modelo/thinking).
|
||||
- Archivos bootstrap del espacio de trabajo inyectados bajo **Contexto del proyecto**.
|
||||
- Hora (UTC + hora del usuario convertida si está configurada).
|
||||
- Metadatos del runtime (host/OS/modelo/thinking).
|
||||
- Archivos bootstrap del espacio de trabajo inyectados bajo **Project Context**.
|
||||
|
||||
Desglose completo: [Prompt del sistema](/es/concepts/system-prompt).
|
||||
|
||||
## Archivos del espacio de trabajo inyectados (Contexto del proyecto)
|
||||
## Archivos del espacio de trabajo inyectados (Project Context)
|
||||
|
||||
De forma predeterminada, OpenClaw inyecta un conjunto fijo de archivos del espacio de trabajo (si existen):
|
||||
De forma predeterminada, OpenClaw inyecta un conjunto fijo de archivos del espacio de trabajo (si están presentes):
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -117,17 +117,17 @@ De forma predeterminada, OpenClaw inyecta un conjunto fijo de archivos del espac
|
||||
- `IDENTITY.md`
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (solo en la primera ejecución)
|
||||
- `BOOTSTRAP.md` (solo la primera ejecución)
|
||||
|
||||
Los archivos grandes se truncan por archivo usando `agents.defaults.bootstrapMaxChars` (valor predeterminado: `20000` caracteres). OpenClaw también aplica un límite total de inyección bootstrap entre archivos con `agents.defaults.bootstrapTotalMaxChars` (valor predeterminado: `150000` caracteres). `/context` muestra los tamaños **bruto vs. inyectado** y si hubo truncamiento.
|
||||
Los archivos grandes se truncan por archivo usando `agents.defaults.bootstrapMaxChars` (predeterminado `12000` caracteres). OpenClaw también aplica un límite total de inyección bootstrap entre archivos con `agents.defaults.bootstrapTotalMaxChars` (predeterminado `60000` caracteres). `/context` muestra los tamaños **sin procesar vs inyectados** y si ocurrió truncamiento.
|
||||
|
||||
Cuando ocurre truncamiento, el entorno de ejecución puede inyectar un bloque de advertencia dentro del prompt en Contexto del proyecto. Configúralo con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; valor predeterminado: `once`).
|
||||
Cuando ocurre truncamiento, el runtime puede inyectar un bloque de advertencia dentro del prompt en Project Context. Configura esto con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; predeterminado `once`).
|
||||
|
||||
## Skills: inyectadas vs. cargadas bajo demanda
|
||||
## Skills: inyectadas vs cargadas bajo demanda
|
||||
|
||||
El prompt del sistema incluye una lista compacta de **Skills** (nombre + descripción + ubicación). Esta lista tiene una sobrecarga real.
|
||||
El prompt del sistema incluye una **lista de Skills** compacta (nombre + descripción + ubicación). Esta lista tiene una sobrecarga real.
|
||||
|
||||
Las instrucciones de Skills _no_ se incluyen de forma predeterminada. Se espera que el modelo use `read` para leer el `SKILL.md` de la Skill **solo cuando sea necesario**.
|
||||
Las instrucciones de Skill _no_ se incluyen de forma predeterminada. Se espera que el modelo haga `read` del `SKILL.md` de la skill **solo cuando sea necesario**.
|
||||
|
||||
## Herramientas: hay dos costos
|
||||
|
||||
@ -140,37 +140,37 @@ Las herramientas afectan al contexto de dos maneras:
|
||||
|
||||
## Comandos, directivas y "atajos en línea"
|
||||
|
||||
Los comandos con barra los gestiona el Gateway. Hay algunos comportamientos diferentes:
|
||||
Los comandos de barra son manejados por el Gateway. Hay algunos comportamientos diferentes:
|
||||
|
||||
- **Comandos independientes**: un mensaje que es solo `/...` se ejecuta como comando.
|
||||
- **Directivas**: `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` se eliminan antes de que el modelo vea el mensaje.
|
||||
- Los mensajes que contienen solo directivas conservan la configuración de la sesión.
|
||||
- Las directivas en línea dentro de un mensaje normal actúan como sugerencias por mensaje.
|
||||
- **Atajos en línea** (solo remitentes en allowlist): ciertos tokens `/...` dentro de un mensaje normal pueden ejecutarse inmediatamente (ejemplo: “hey /status”), y se eliminan antes de que el modelo vea el texto restante.
|
||||
- Los mensajes compuestos solo por directivas conservan la configuración de la sesión.
|
||||
- Las directivas en línea en un mensaje normal actúan como sugerencias por mensaje.
|
||||
- **Atajos en línea** (solo remitentes permitidos): ciertos tokens `/...` dentro de un mensaje normal pueden ejecutarse inmediatamente (ejemplo: “hey /status”), y se eliminan antes de que el modelo vea el texto restante.
|
||||
|
||||
Detalles: [Comandos con barra](/es/tools/slash-commands).
|
||||
Detalles: [Comandos de barra](/es/tools/slash-commands).
|
||||
|
||||
## Sesiones, Compaction y poda (qué persiste)
|
||||
## Sesiones, Compaction y pruning (qué persiste)
|
||||
|
||||
Lo que persiste entre mensajes depende del mecanismo:
|
||||
|
||||
- El **historial normal** persiste en la transcripción de la sesión hasta que la política lo compacte o pode.
|
||||
- **Compaction** conserva un resumen dentro de la transcripción y mantiene intactos los mensajes recientes.
|
||||
- La **poda** elimina resultados antiguos de herramientas del prompt _en memoria_ para una ejecución, pero no reescribe la transcripción.
|
||||
- **El historial normal** persiste en la transcripción de la sesión hasta que la política lo compacta/poda.
|
||||
- **Compaction** conserva un resumen en la transcripción y mantiene intactos los mensajes recientes.
|
||||
- **Pruning** elimina resultados antiguos de herramientas del prompt _en memoria_ para una ejecución, pero no reescribe la transcripción.
|
||||
|
||||
Documentación: [Session](/es/concepts/session), [Compaction](/es/concepts/compaction), [Poda de sesión](/es/concepts/session-pruning).
|
||||
Documentación: [Sesión](/es/concepts/session), [Compaction](/es/concepts/compaction), [Poda de sesión](/es/concepts/session-pruning).
|
||||
|
||||
De forma predeterminada, OpenClaw usa el motor de contexto `legacy` integrado para el ensamblaje y la compactación. Si instalas un Plugin que proporciona `kind: "context-engine"` y lo seleccionas con `plugins.slots.contextEngine`, OpenClaw delega el ensamblaje de contexto, `/compact` y los hooks relacionados del ciclo de vida del contexto de subagentes a ese motor. `ownsCompaction: false` no hace fallback automático al motor legacy; el motor activo igualmente debe implementar `compact()` correctamente. Consulta
|
||||
De forma predeterminada, OpenClaw usa el motor de contexto `legacy` integrado para el ensamblaje y la compacción. Si instalas un Plugin que proporciona `kind: "context-engine"` y lo seleccionas con `plugins.slots.contextEngine`, OpenClaw delega en ese motor el ensamblaje del contexto, `/compact` y los hooks relacionados del ciclo de vida del contexto del subagente. `ownsCompaction: false` no vuelve automáticamente al motor legacy; el motor activo debe seguir implementando `compact()` correctamente. Consulta
|
||||
[Context Engine](/es/concepts/context-engine) para ver la interfaz conectable completa, los hooks del ciclo de vida y la configuración.
|
||||
|
||||
## Qué informa realmente `/context`
|
||||
|
||||
`/context` prefiere el informe más reciente del prompt del sistema **construido en una ejecución** cuando está disponible:
|
||||
`/context` prefiere el informe más reciente del prompt del sistema **construido durante la ejecución** cuando está disponible:
|
||||
|
||||
- `System prompt (run)` = capturado de la última ejecución embebida (con capacidad de herramientas) y persistido en el almacén de sesiones.
|
||||
- `System prompt (estimate)` = calculado sobre la marcha cuando no existe un informe de ejecución (o cuando se ejecuta mediante un backend de CLI que no genera el informe).
|
||||
- `System prompt (run)` = capturado de la última ejecución embebida (con capacidad de herramientas) y persistido en el almacenamiento de la sesión.
|
||||
- `System prompt (estimate)` = calculado sobre la marcha cuando no existe un informe de ejecución (o al ejecutarse mediante un backend de CLI que no genera el informe).
|
||||
|
||||
En ambos casos, informa tamaños y los principales contribuyentes; no vuelca el prompt completo del sistema ni los esquemas de herramientas.
|
||||
En cualquier caso, informa tamaños y principales contribuyentes; **no** muestra el prompt completo del sistema ni los esquemas de herramientas.
|
||||
|
||||
## Relacionado
|
||||
|
||||
|
||||
@ -1,28 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Ampliación de qa-lab o qa-channel
|
||||
- Ampliar qa-lab o qa-channel
|
||||
- Agregar escenarios de QA respaldados por el repositorio
|
||||
- Crear una automatización de QA de mayor realismo en torno al panel de Gateway
|
||||
summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con semillas e informes de protocolo
|
||||
summary: Forma de la automatización privada de QA para qa-lab, qa-channel, escenarios con seed e informes de protocolo
|
||||
title: Automatización E2E de QA
|
||||
x-i18n:
|
||||
generated_at: "2026-04-17T05:13:50Z"
|
||||
generated_at: "2026-04-18T04:59:15Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0
|
||||
source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automatización E2E de QA
|
||||
|
||||
La pila privada de QA está pensada para ejercitar OpenClaw de una forma más realista y con forma de canal que la que puede ofrecer una sola prueba unitaria.
|
||||
La pila privada de QA está pensada para ejercitar OpenClaw de una manera más realista,
|
||||
con forma de canal, que la que puede cubrir una sola prueba unitaria.
|
||||
|
||||
Componentes actuales:
|
||||
Piezas actuales:
|
||||
|
||||
- `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo, reacción, edición y eliminación.
|
||||
- `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción, inyectar mensajes entrantes y exportar un informe en Markdown.
|
||||
- `qa/`: recursos semilla respaldados por el repositorio para la tarea de inicio y los escenarios base de QA.
|
||||
- `extensions/qa-channel`: canal de mensajes sintético con superficies de MD, canal, hilo,
|
||||
reacción, edición y eliminación.
|
||||
- `extensions/qa-lab`: interfaz de depuración y bus de QA para observar la transcripción,
|
||||
inyectar mensajes entrantes y exportar un informe en Markdown.
|
||||
- `qa/`: recursos seed respaldados por el repositorio para la tarea inicial y los
|
||||
escenarios base de QA.
|
||||
|
||||
El flujo actual del operador de QA es un sitio de QA de dos paneles:
|
||||
|
||||
@ -35,9 +39,13 @@ Ejecútalo con:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Eso compila el sitio de QA, inicia la ruta de Gateway respaldada por Docker y expone la página de QA Lab donde un operador o un bucle de automatización puede dar al agente una misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o qué siguió bloqueado.
|
||||
Eso compila el sitio de QA, inicia el carril de Gateway respaldado por Docker y expone la
|
||||
página de QA Lab, donde un operador o un bucle de automatización puede darle al agente una
|
||||
misión de QA, observar el comportamiento real del canal y registrar qué funcionó, qué falló o
|
||||
qué siguió bloqueado.
|
||||
|
||||
Para una iteración más rápida de la interfaz de QA Lab sin recompilar la imagen de Docker cada vez, inicia la pila con un bundle de QA Lab montado con bind mount:
|
||||
Para una iteración más rápida de la UI de QA Lab sin reconstruir la imagen de Docker cada vez,
|
||||
inicia la pila con un bundle de QA Lab montado por enlace:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -46,100 +54,144 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta con bind mount `extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch` recompila ese bundle cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash de recursos de QA Lab.
|
||||
`qa:lab:up:fast` mantiene los servicios de Docker sobre una imagen precompilada y monta por enlace
|
||||
`extensions/qa-lab/web/dist` dentro del contenedor `qa-lab`. `qa:lab:watch`
|
||||
recompila ese bundle cuando hay cambios, y el navegador se recarga automáticamente cuando cambia el hash
|
||||
de recursos de QA Lab.
|
||||
|
||||
Para una ruta de smoke real de transporte para Matrix, ejecuta:
|
||||
Para un carril smoke de Matrix con transporte real, ejecuta:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa matrix
|
||||
```
|
||||
|
||||
Esa ruta aprovisiona un homeserver Tuwunel desechable en Docker, registra usuarios temporales para driver, SUT y observador, crea una sala privada y luego ejecuta el Plugin real de Matrix dentro de un proceso hijo de Gateway de QA. La ruta de transporte en vivo mantiene la configuración hija limitada al transporte bajo prueba, por lo que Matrix se ejecuta sin `qa-channel` en la configuración hija. Escribe los artefactos del informe estructurado y un registro combinado de stdout/stderr en el directorio de salida de QA de Matrix seleccionado. Para capturar también la salida externa de compilación/lanzamiento de `scripts/run-node.mjs`, establece `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` en un archivo de registro local del repositorio.
|
||||
Ese carril aprovisiona un homeserver Tuwunel desechable en Docker, registra usuarios temporales
|
||||
de controlador, SUT y observador, crea una sala privada y luego ejecuta el Plugin real de Matrix dentro
|
||||
de un proceso hijo de Gateway de QA. El carril de transporte en vivo mantiene la configuración del proceso hijo
|
||||
limitada al transporte bajo prueba, por lo que Matrix se ejecuta sin `qa-channel` en la configuración
|
||||
del proceso hijo. Escribe los artefactos de informe estructurado y un registro combinado de stdout/stderr
|
||||
en el directorio de salida de Matrix QA seleccionado. Para capturar también la salida externa de compilación/lanzamiento
|
||||
de `scripts/run-node.mjs`, establece `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` en un archivo de registro local del repositorio.
|
||||
|
||||
Para una ruta de smoke real de transporte para Telegram, ejecuta:
|
||||
Para un carril smoke de Telegram con transporte real, ejecuta:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
Esa ruta apunta a un grupo privado real de Telegram en lugar de aprovisionar un servidor desechable. Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación bot a bot funciona mejor cuando ambos bots tienen habilitado Bot-to-Bot Communication Mode en `@BotFather`.
|
||||
Ese carril apunta a un grupo privado real de Telegram en lugar de aprovisionar un servidor desechable.
|
||||
Requiere `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
|
||||
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` y
|
||||
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, además de dos bots distintos en el mismo
|
||||
grupo privado. El bot SUT debe tener un nombre de usuario de Telegram, y la observación bot a bot
|
||||
funciona mejor cuando ambos bots tienen habilitado el modo de comunicación Bot-to-Bot
|
||||
en `@BotFather`.
|
||||
|
||||
Las rutas de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada una invente su propia forma de lista de escenarios:
|
||||
Los carriles de transporte en vivo ahora comparten un contrato más pequeño en lugar de que cada uno invente
|
||||
su propia forma de lista de escenarios.
|
||||
|
||||
`qa-channel` sigue siendo la suite amplia de comportamiento sintético del producto y no forma parte de la matriz de cobertura de transporte en vivo.
|
||||
`qa-channel` sigue siendo la amplia suite sintética de comportamiento del producto y no forma parte
|
||||
de la matriz de cobertura de transporte en vivo.
|
||||
|
||||
| Ruta | Canary | Restricción por mención | Bloqueo por allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando de ayuda |
|
||||
| -------- | ------ | ----------------------- | --------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ---------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
| Carril | Canary | Puerta por mención | Bloqueo por allowlist | Respuesta de nivel superior | Reanudación tras reinicio | Seguimiento en hilo | Aislamiento de hilo | Observación de reacciones | Comando help |
|
||||
| -------- | ------ | ------------------ | --------------------- | --------------------------- | ------------------------- | ------------------- | ------------------- | ------------------------- | ------------ |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
|
||||
Esto mantiene a `qa-channel` como la suite amplia de comportamiento del producto, mientras que Matrix, Telegram y futuros transportes en vivo comparten una lista explícita de comprobaciones de contrato de transporte.
|
||||
Esto mantiene `qa-channel` como la amplia suite de comportamiento del producto, mientras que Matrix,
|
||||
Telegram y futuros transportes en vivo comparten una lista explícita de comprobación del contrato
|
||||
de transporte.
|
||||
|
||||
Para una ruta de VM Linux desechable sin incorporar Docker en la ruta de QA, ejecuta:
|
||||
Para un carril de VM Linux desechable sin incorporar Docker en la ruta de QA, ejecuta:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Esto arranca un invitado fresco de Multipass, instala dependencias, compila OpenClaw dentro del invitado, ejecuta `qa suite` y luego copia el informe y el resumen normales de QA de vuelta a `.artifacts/qa-e2e/...` en el host.
|
||||
Esto inicia un huésped nuevo de Multipass, instala dependencias, compila OpenClaw
|
||||
dentro del huésped, ejecuta `qa suite` y luego copia el informe y resumen normales de QA de vuelta a
|
||||
`.artifacts/qa-e2e/...` en el host.
|
||||
Reutiliza el mismo comportamiento de selección de escenarios que `qa suite` en el host.
|
||||
Las ejecuciones de la suite en host y en Multipass ejecutan en paralelo varios escenarios seleccionados con workers de Gateway aislados de forma predeterminada, hasta 64 workers o la cantidad de escenarios seleccionados. Usa `--concurrency <count>` para ajustar la cantidad de workers, o `--concurrency 1` para ejecución en serie.
|
||||
Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que resultan prácticas para el invitado: claves de proveedor basadas en env, la ruta de configuración del proveedor en vivo de QA y `CODEX_HOME` cuando está presente. Mantén `--output-dir` bajo la raíz del repositorio para que el invitado pueda escribir de vuelta a través del espacio de trabajo montado.
|
||||
Las ejecuciones del host y de Multipass ejecutan varios escenarios seleccionados en paralelo
|
||||
con workers de Gateway aislados de forma predeterminada, hasta 64 workers o la cantidad de escenarios
|
||||
seleccionados. Usa `--concurrency <count>` para ajustar la cantidad de workers, o
|
||||
`--concurrency 1` para ejecución en serie.
|
||||
Las ejecuciones en vivo reenvían las entradas de autenticación de QA compatibles que son prácticas para el
|
||||
huésped: claves de proveedor basadas en variables de entorno, la ruta de configuración del proveedor en vivo de QA y
|
||||
`CODEX_HOME` cuando esté presente. Mantén `--output-dir` bajo la raíz del repositorio para que el huésped
|
||||
pueda escribir de vuelta a través del espacio de trabajo montado.
|
||||
|
||||
## Semillas respaldadas por el repositorio
|
||||
## Seeds respaldados por el repositorio
|
||||
|
||||
Los recursos semilla viven en `qa/`:
|
||||
Los recursos seed viven en `qa/`:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
Estos están intencionalmente en git para que el plan de QA sea visible tanto para humanos como para el agente.
|
||||
Estos están intencionalmente en git para que el plan de QA sea visible tanto para las personas como para el
|
||||
agente.
|
||||
|
||||
`qa-lab` debe seguir siendo un ejecutor genérico de Markdown. Cada archivo Markdown de escenario es la fuente de verdad para una ejecución de prueba y debe definir:
|
||||
`qa-lab` debe seguir siendo un ejecutor genérico de Markdown. Cada archivo Markdown de escenario es
|
||||
la fuente de verdad para una ejecución de prueba y debe definir:
|
||||
|
||||
- metadatos del escenario
|
||||
- referencias a documentación y código
|
||||
- metadatos opcionales de categoría, capacidad, carril y riesgo
|
||||
- referencias de documentación y código
|
||||
- requisitos opcionales de Plugin
|
||||
- parche opcional de configuración de Gateway
|
||||
- el `qa-flow` ejecutable
|
||||
|
||||
La superficie de ejecución reutilizable que respalda `qa-flow` puede seguir siendo genérica y transversal. Por ejemplo, los escenarios en Markdown pueden combinar helpers del lado del transporte con helpers del lado del navegador que controlan la Control UI integrada a través de la interfaz `browser.request` de Gateway sin añadir un ejecutor de caso especial.
|
||||
La superficie de ejecución reutilizable que respalda `qa-flow` puede seguir siendo genérica
|
||||
y transversal. Por ejemplo, los escenarios Markdown pueden combinar ayudantes del lado del transporte
|
||||
con ayudantes del lado del navegador que controlan la Control UI integrada a través de la
|
||||
interfaz `browser.request` de Gateway sin agregar un ejecutor de caso especial.
|
||||
|
||||
La lista base debe seguir siendo lo bastante amplia para cubrir:
|
||||
Los archivos de escenario deben agruparse por capacidad del producto en lugar de por carpeta del árbol
|
||||
de código fuente. Mantén estables los ID de escenario cuando los archivos se muevan; usa `docsRefs` y `codeRefs`
|
||||
para la trazabilidad de implementación.
|
||||
|
||||
- chat por MD y por canal
|
||||
La lista base debe seguir siendo lo suficientemente amplia como para cubrir:
|
||||
|
||||
- chat por MD y canal
|
||||
- comportamiento de hilos
|
||||
- ciclo de vida de acciones de mensajes
|
||||
- callbacks de Cron
|
||||
- recuperación de memoria
|
||||
- cambio de modelo
|
||||
- traspaso a subagente
|
||||
- transferencia a subagente
|
||||
- lectura del repositorio y de la documentación
|
||||
- una pequeña tarea de compilación, como Lobster Invaders
|
||||
- una pequeña tarea de compilación como Lobster Invaders
|
||||
|
||||
## Rutas de proveedor simulado
|
||||
## Carriles de proveedor simulado
|
||||
|
||||
`qa suite` tiene dos rutas locales de proveedor simulado:
|
||||
`qa suite` tiene dos carriles locales de proveedor simulado:
|
||||
|
||||
- `mock-openai` es el simulador de OpenClaw consciente del escenario. Sigue siendo la ruta simulada determinista predeterminada para QA respaldado por el repositorio y compuertas de paridad.
|
||||
- `aimock` inicia un servidor de proveedor respaldado por AIMock para cobertura experimental de protocolo, fixtures, grabación/reproducción y caos. Es aditivo y no reemplaza al despachador de escenarios `mock-openai`.
|
||||
- `mock-openai` es el simulador de OpenClaw consciente del escenario. Sigue siendo el
|
||||
carril simulado determinista predeterminado para QA respaldado por el repositorio y compuertas de paridad.
|
||||
- `aimock` inicia un servidor de proveedor respaldado por AIMock para cobertura experimental de protocolo,
|
||||
fixtures, grabación/reproducción y caos. Es complementario y no reemplaza al despachador de escenarios
|
||||
`mock-openai`.
|
||||
|
||||
La implementación de rutas de proveedor vive en `extensions/qa-lab/src/providers/`.
|
||||
Cada proveedor es dueño de sus valores predeterminados, el arranque de su servidor local, la configuración del modelo de Gateway, las necesidades de preparación del perfil de autenticación y las capacidades en vivo/simuladas. El código compartido de suite y Gateway debe enrutar a través del registro de proveedores en lugar de ramificarse por nombres de proveedor.
|
||||
La implementación del carril de proveedor vive en `extensions/qa-lab/src/providers/`.
|
||||
Cada proveedor es dueño de sus valores predeterminados, el arranque del servidor local, la configuración
|
||||
del modelo de Gateway, las necesidades de preparación del perfil de autenticación y los indicadores de capacidad
|
||||
live/mock. El código compartido de suite y Gateway debe enrutar a través del registro de proveedores
|
||||
en lugar de ramificarse según los nombres de proveedor.
|
||||
|
||||
## Adaptadores de transporte
|
||||
|
||||
`qa-lab` es dueño de una interfaz genérica de transporte para escenarios de QA en Markdown.
|
||||
`qa-channel` es el primer adaptador sobre esa interfaz, pero el objetivo del diseño es más amplio:
|
||||
los futuros canales reales o sintéticos deberían conectarse al mismo ejecutor de suite en lugar de añadir un ejecutor de QA específico de transporte.
|
||||
`qa-lab` es dueño de una interfaz genérica de transporte para escenarios Markdown de QA.
|
||||
`qa-channel` es el primer adaptador sobre esa interfaz, pero el objetivo de diseño es más amplio:
|
||||
canales futuros, reales o sintéticos, deberían integrarse en el mismo ejecutor de suite en lugar
|
||||
de agregar un ejecutor de QA específico para cada transporte.
|
||||
|
||||
A nivel de arquitectura, la división es:
|
||||
|
||||
- `qa-lab` es dueño de la ejecución genérica de escenarios, la concurrencia de workers, la escritura de artefactos y los informes.
|
||||
- el adaptador de transporte es dueño de la configuración de Gateway, la preparación, la observación entrante y saliente, las acciones de transporte y el estado de transporte normalizado.
|
||||
- los archivos de escenarios en Markdown bajo `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de ejecución reutilizable que los ejecuta.
|
||||
- el adaptador de transporte es dueño de la configuración de Gateway, la preparación, la observación de entrada y salida, las acciones de transporte y el estado de transporte normalizado.
|
||||
- los archivos Markdown de escenarios bajo `qa/scenarios/` definen la ejecución de prueba; `qa-lab` proporciona la superficie de ejecución reutilizable que los ejecuta.
|
||||
|
||||
La guía de adopción orientada a mantenedores para nuevos adaptadores de canal se encuentra en
|
||||
La guía de adopción dirigida a mantenedores para nuevos adaptadores de canal se encuentra en
|
||||
[Testing](/es/help/testing#adding-a-channel-to-qa).
|
||||
|
||||
## Informes
|
||||
@ -150,9 +202,10 @@ El informe debe responder:
|
||||
- Qué funcionó
|
||||
- Qué falló
|
||||
- Qué siguió bloqueado
|
||||
- Qué escenarios de seguimiento vale la pena añadir
|
||||
- Qué escenarios de seguimiento vale la pena agregar
|
||||
|
||||
Para comprobaciones de carácter y estilo, ejecuta el mismo escenario en varias referencias de modelos en vivo y escribe un informe evaluado en Markdown:
|
||||
Para comprobaciones de carácter y estilo, ejecuta el mismo escenario con múltiples referencias de modelos en vivo
|
||||
y escribe un informe Markdown evaluado:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -171,13 +224,30 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
El comando ejecuta procesos hijo locales de Gateway de QA, no Docker. Los escenarios de evaluación de carácter deben establecer la persona mediante `SOUL.md` y luego ejecutar turnos de usuario normales, como chat, ayuda del espacio de trabajo y pequeñas tareas sobre archivos. No se debe informar al modelo candidato de que está siendo evaluado. El comando conserva cada transcripción completa, registra estadísticas básicas de ejecución y luego pide a los modelos jueces en modo rápido con razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibe y humor.
|
||||
Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo cada transcripción y estado de ejecución, pero las referencias candidatas se sustituyen por etiquetas neutrales como `candidate-01`; el informe vuelve a asociar las clasificaciones con las referencias reales después del análisis.
|
||||
Las ejecuciones candidatas usan `high` thinking de forma predeterminada, con `xhigh` para los modelos de OpenAI que lo admiten. Sustituye un candidato específico en línea con
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` sigue estableciendo un valor de respaldo global, y la forma anterior `--model-thinking <provider/model=level>` se mantiene por compatibilidad.
|
||||
Las referencias candidatas de OpenAI usan el modo rápido de forma predeterminada para que se use el procesamiento con prioridad cuando el proveedor lo admita. Añade `,fast`, `,no-fast` o `,fast=false` en línea cuando un candidato o juez concreto necesite una sustitución. Pasa `--fast` solo cuando quieras forzar el modo rápido para todos los modelos candidatos. Las duraciones de candidatos y jueces se registran en el informe para análisis comparativos, pero los prompts de los jueces indican explícitamente que no deben clasificar por velocidad.
|
||||
Tanto las ejecuciones de modelos candidatos como las de modelos jueces usan concurrencia 16 de forma predeterminada. Reduce
|
||||
`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión sobre Gateway local hagan que una ejecución sea demasiado ruidosa.
|
||||
El comando ejecuta procesos hijo locales de Gateway de QA, no Docker. Los escenarios de evaluación de carácter
|
||||
deben establecer la personalidad mediante `SOUL.md`, y luego ejecutar turnos de usuario normales
|
||||
como chat, ayuda del espacio de trabajo y pequeñas tareas con archivos. No se le debe decir al
|
||||
modelo candidato que está siendo evaluado. El comando conserva cada transcripción completa,
|
||||
registra estadísticas básicas de ejecución y luego pide a los modelos jueces en modo fast con
|
||||
razonamiento `xhigh` que clasifiquen las ejecuciones por naturalidad, vibra y humor.
|
||||
Usa `--blind-judge-models` al comparar proveedores: el prompt del juez sigue recibiendo
|
||||
cada transcripción y estado de ejecución, pero las referencias candidatas se reemplazan por
|
||||
etiquetas neutras como `candidate-01`; el informe vuelve a mapear las clasificaciones a las referencias reales
|
||||
después del análisis.
|
||||
Las ejecuciones candidatas usan `high` thinking de forma predeterminada, con `xhigh` para los modelos de OpenAI
|
||||
que lo admiten. Sustituye un candidato específico en línea con
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` sigue estableciendo una
|
||||
alternativa global, y la forma antigua `--model-thinking <provider/model=level>` se
|
||||
mantiene por compatibilidad.
|
||||
Las referencias candidatas de OpenAI usan el modo fast de forma predeterminada para que se use procesamiento prioritario
|
||||
cuando el proveedor lo admita. Agrega `,fast`, `,no-fast` o `,fast=false` en línea cuando
|
||||
un solo candidato o juez necesite una sustitución. Pasa `--fast` solo cuando quieras
|
||||
forzar el modo fast para todos los modelos candidatos. Las duraciones de candidatos y jueces se
|
||||
registran en el informe para análisis comparativo, pero los prompts de los jueces indican explícitamente
|
||||
que no se clasifique por velocidad.
|
||||
Tanto las ejecuciones de modelos candidatos como las de los jueces usan concurrencia 16 de forma predeterminada. Reduce
|
||||
`--concurrency` o `--judge-concurrency` cuando los límites del proveedor o la presión del Gateway local
|
||||
hagan que una ejecución sea demasiado ruidosa.
|
||||
Cuando no se pasa ningún `--model` candidato, la evaluación de carácter usa por defecto
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Editar el texto del prompt del sistema, la lista de herramientas o las secciones de tiempo/Heartbeat
|
||||
- Cambiar el comportamiento de arranque del espacio de trabajo o de inyección de Skills
|
||||
- Edición del texto del prompt del sistema, la lista de herramientas o las secciones de hora/Heartbeat
|
||||
- Cambio del comportamiento de arranque del espacio de trabajo o de inyección de Skills
|
||||
summary: Qué contiene el prompt del sistema de OpenClaw y cómo se ensambla
|
||||
title: Prompt del sistema
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T19:41:57Z"
|
||||
generated_at: "2026-04-18T04:59:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
|
||||
source_hash: e60705994cebdd9768926168cb1c6d17ab717d7ff02353a5d5e7478ba8191cab
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,61 +19,80 @@ OpenClaw crea un prompt del sistema personalizado para cada ejecución del agent
|
||||
|
||||
El prompt es ensamblado por OpenClaw e inyectado en cada ejecución del agente.
|
||||
|
||||
Los plugins de proveedor pueden aportar guía de prompt compatible con caché sin reemplazar el prompt completo propiedad de OpenClaw. El runtime del proveedor puede:
|
||||
Los plugins de proveedores pueden aportar guía de prompt consciente de la caché sin reemplazar el prompt completo propiedad de OpenClaw. El runtime del proveedor puede:
|
||||
|
||||
- reemplazar un pequeño conjunto de secciones principales con nombre (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- inyectar un **prefijo estable** por encima del límite de caché del prompt
|
||||
- inyectar un **sufijo dinámico** por debajo del límite de caché del prompt
|
||||
|
||||
Usa contribuciones propiedad del proveedor para ajustes específicos de familias de modelos. Mantén la mutación heredada del prompt `before_prompt_build` para compatibilidad o para cambios de prompt verdaderamente globales, no para el comportamiento normal del proveedor.
|
||||
Usa aportes propiedad del proveedor para ajustes específicos de familias de modelos. Mantén la mutación de prompt heredada de `before_prompt_build` para compatibilidad o para cambios de prompt realmente globales, no para el comportamiento normal del proveedor.
|
||||
|
||||
## Estructura
|
||||
|
||||
El prompt es intencionalmente compacto y usa secciones fijas:
|
||||
|
||||
- **Herramientas**: recordatorio de la fuente de verdad de herramientas estructuradas más la guía de uso de herramientas en runtime.
|
||||
- **Seguridad**: breve recordatorio de barreras de protección para evitar conductas de búsqueda de poder o eludir la supervisión.
|
||||
- **Skills** (cuando están disponibles): le indica al modelo cómo cargar instrucciones de Skills bajo demanda.
|
||||
- **Autoactualización de OpenClaw**: cómo inspeccionar la configuración de forma segura con `config.schema.lookup`, modificar la configuración con `config.patch`, reemplazar la configuración completa con `config.apply`, y ejecutar `update.run` solo a solicitud explícita del usuario. La herramienta `gateway`, solo para propietarios, también rechaza reescribir `tools.exec.ask` / `tools.exec.security`, incluidas las alias heredadas `tools.bash.*` que se normalizan a esas rutas protegidas de exec.
|
||||
- **Herramientas**: recordatorio de la fuente de verdad de herramientas estructuradas más guía de uso de herramientas en tiempo de ejecución.
|
||||
- **Seguridad**: recordatorio breve de barreras de protección para evitar conductas de búsqueda de poder o evasión de supervisión.
|
||||
- **Skills** (cuando están disponibles): le dice al modelo cómo cargar instrucciones de Skills bajo demanda.
|
||||
- **Autoactualización de OpenClaw**: cómo inspeccionar la configuración de forma segura con
|
||||
`config.schema.lookup`, parchear la configuración con `config.patch`, reemplazar la configuración completa con `config.apply` y ejecutar `update.run` solo cuando el usuario lo solicite explícitamente. La herramienta `gateway`, solo para propietarios, también se niega a reescribir
|
||||
`tools.exec.ask` / `tools.exec.security`, incluidas las alias heredadas `tools.bash.*`
|
||||
que se normalizan a esas rutas de ejecución protegidas.
|
||||
- **Espacio de trabajo**: directorio de trabajo (`agents.defaults.workspace`).
|
||||
- **Documentación**: ruta local a la documentación de OpenClaw (repositorio o paquete npm) y cuándo leerla.
|
||||
- **Archivos del espacio de trabajo (inyectados)**: indica que los archivos de arranque se incluyen más abajo.
|
||||
- **Sandbox** (cuando está habilitado): indica el runtime aislado, las rutas del sandbox y si exec elevado está disponible.
|
||||
- **Archivos del espacio de trabajo (inyectados)**: indica que los archivos de arranque están incluidos más abajo.
|
||||
- **Sandbox** (cuando está habilitado): indica el runtime aislado, las rutas del sandbox y si la ejecución con privilegios elevados está disponible.
|
||||
- **Fecha y hora actuales**: hora local del usuario, zona horaria y formato de hora.
|
||||
- **Etiquetas de respuesta**: sintaxis opcional de etiquetas de respuesta para proveedores compatibles.
|
||||
- **Heartbeats**: prompt de Heartbeat y comportamiento de acuse de recibo, cuando Heartbeats están habilitados para el agente predeterminado.
|
||||
- **Heartbeats**: prompt de Heartbeat y comportamiento de confirmación, cuando los Heartbeats están habilitados para el agente predeterminado.
|
||||
- **Runtime**: host, SO, node, modelo, raíz del repositorio (cuando se detecta), nivel de razonamiento (una línea).
|
||||
- **Razonamiento**: nivel de visibilidad actual + pista para alternar con /reasoning.
|
||||
- **Razonamiento**: nivel de visibilidad actual + sugerencia para alternar con /reasoning.
|
||||
|
||||
La sección de Herramientas también incluye guía de runtime para trabajos de larga duración:
|
||||
La sección Herramientas también incluye guía de runtime para trabajo de larga duración:
|
||||
|
||||
- usa cron para seguimientos futuros (`check back later`, recordatorios, trabajo recurrente) en lugar de bucles de espera con `exec`, trucos de retraso con `yieldMs` o sondeo repetido de `process`
|
||||
- usa `exec` / `process` solo para comandos que comienzan ahora y siguen ejecutándose en segundo plano
|
||||
- cuando la reactivación automática por finalización está habilitada, inicia el comando una sola vez y confía en la ruta de reactivación basada en push cuando emita salida o falle
|
||||
- usa `process` para registros, estado, entrada o intervención cuando necesites inspeccionar un comando en ejecución
|
||||
- si la tarea es más grande, prefiere `sessions_spawn`; la finalización del subagente se basa en push y se anuncia automáticamente al solicitante
|
||||
- no sondees `subagents list` / `sessions_list` en un bucle solo para esperar la finalización
|
||||
- usar Cron para seguimientos futuros (`check back later`, recordatorios, trabajo recurrente)
|
||||
en lugar de bucles de suspensión con `exec`, trucos de retraso con `yieldMs` o sondeos repetidos de `process`
|
||||
- usar `exec` / `process` solo para comandos que empiezan ahora y continúan ejecutándose
|
||||
en segundo plano
|
||||
- cuando el despertar automático al completarse está habilitado, iniciar el comando una sola vez y confiar en
|
||||
la vía de despertar basada en push cuando emita salida o falle
|
||||
- usar `process` para registros, estado, entrada o intervención cuando necesites
|
||||
inspeccionar un comando en ejecución
|
||||
- si la tarea es más grande, preferir `sessions_spawn`; la finalización de subagentes está
|
||||
basada en push y se anuncia automáticamente de vuelta al solicitante
|
||||
- no sondear `subagents list` / `sessions_list` en un bucle solo para esperar
|
||||
la finalización
|
||||
|
||||
Cuando la herramienta experimental `update_plan` está habilitada, Herramientas también le indica al modelo que la use solo para trabajo no trivial de varios pasos, que mantenga exactamente un paso `in_progress` y que evite repetir el plan completo después de cada actualización.
|
||||
Cuando la herramienta experimental `update_plan` está habilitada, Herramientas también le dice al
|
||||
modelo que la use solo para trabajo no trivial de varios pasos, que mantenga exactamente un
|
||||
paso `in_progress` y que evite repetir el plan completo después de cada actualización.
|
||||
|
||||
Las barreras de protección de Seguridad en el prompt del sistema son de carácter orientativo. Guían el comportamiento del modelo, pero no aplican políticas. Usa la política de herramientas, aprobaciones de exec, sandboxing y listas permitidas de canales para una aplicación estricta; los operadores pueden deshabilitarlas por diseño.
|
||||
Las barreras de seguridad del prompt del sistema son orientativas. Guían el comportamiento del modelo, pero no aplican la política. Usa la política de herramientas, las aprobaciones de ejecución, el sandboxing y las listas de permitidos de canales para la aplicación estricta; los operadores pueden desactivarlas por diseño.
|
||||
|
||||
En los canales con tarjetas o botones de aprobación nativos, el prompt de runtime ahora le indica al agente que primero confíe en esa IU de aprobación nativa. Solo debe incluir un comando manual `/approve` cuando el resultado de la herramienta diga que las aprobaciones en el chat no están disponibles o que la aprobación manual es la única opción.
|
||||
En canales con tarjetas o botones de aprobación nativos, el prompt de runtime ahora le dice al
|
||||
agente que confíe primero en esa interfaz de aprobación nativa. Solo debe incluir un comando manual
|
||||
`/approve` cuando el resultado de la herramienta diga que las aprobaciones en el chat no están disponibles o
|
||||
que la aprobación manual es la única vía.
|
||||
|
||||
## Modos de prompt
|
||||
## Modos del prompt
|
||||
|
||||
OpenClaw puede renderizar prompts del sistema más pequeños para subagentes. El runtime establece un `promptMode` para cada ejecución (no es una configuración orientada al usuario):
|
||||
OpenClaw puede renderizar prompts del sistema más pequeños para subagentes. El runtime establece un
|
||||
`promptMode` para cada ejecución (no es una configuración orientada al usuario):
|
||||
|
||||
- `full` (predeterminado): incluye todas las secciones anteriores.
|
||||
- `minimal`: se usa para subagentes; omite **Skills**, **Memory Recall**, **Autoactualización de OpenClaw**, **Alias de modelos**, **Identidad del usuario**, **Etiquetas de respuesta**, **Mensajería**, **Respuestas silenciosas** y **Heartbeats**. Herramientas, **Seguridad**, Espacio de trabajo, Sandbox, Fecha y hora actuales (cuando se conocen), Runtime y el contexto inyectado siguen disponibles.
|
||||
- `minimal`: se usa para subagentes; omite **Skills**, **Recuperación de memoria**, **Autoactualización de OpenClaw**, **Alias de modelos**, **Identidad del usuario**, **Etiquetas de respuesta**,
|
||||
**Mensajería**, **Respuestas silenciosas** y **Heartbeats**. Herramientas, **Seguridad**,
|
||||
Espacio de trabajo, Sandbox, Fecha y hora actuales (cuando se conocen), Runtime y el
|
||||
contexto inyectado siguen estando disponibles.
|
||||
- `none`: devuelve solo la línea base de identidad.
|
||||
|
||||
Cuando `promptMode=minimal`, los prompts adicionales inyectados se etiquetan como **Contexto del subagente** en lugar de **Contexto de chat grupal**.
|
||||
Cuando `promptMode=minimal`, los prompts inyectados adicionales se etiquetan como **Contexto del subagente**
|
||||
en lugar de **Contexto del chat grupal**.
|
||||
|
||||
## Inyección de arranque del espacio de trabajo
|
||||
## Inyección del arranque del espacio de trabajo
|
||||
|
||||
Los archivos de arranque se recortan y se anexan en **Contexto del proyecto** para que el modelo vea la identidad y el contexto del perfil sin necesidad de lecturas explícitas:
|
||||
Los archivos de arranque se recortan y se agregan bajo **Contexto del proyecto** para que el modelo vea el contexto de identidad y perfil sin necesitar lecturas explícitas:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -82,40 +101,68 @@ Los archivos de arranque se recortan y se anexan en **Contexto del proyecto** pa
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (solo en espacios de trabajo completamente nuevos)
|
||||
- `MEMORY.md` cuando está presente; de lo contrario, `memory.md` como alternativa en minúsculas
|
||||
- `MEMORY.md` cuando está presente; en caso contrario, `memory.md` como alternativa en minúsculas
|
||||
|
||||
Todos estos archivos se **inyectan en la ventana de contexto** en cada turno, a menos que se aplique una condición específica del archivo. `HEARTBEAT.md` se omite en ejecuciones normales cuando Heartbeats están deshabilitados para el agente predeterminado o `agents.defaults.heartbeat.includeSystemPromptSection` es false. Mantén los archivos inyectados concisos, especialmente `MEMORY.md`, que puede crecer con el tiempo y provocar un uso de contexto inesperadamente alto y una Compaction más frecuente.
|
||||
Todos estos archivos se **inyectan en la ventana de contexto** en cada turno, a menos que
|
||||
se aplique una compuerta específica del archivo. `HEARTBEAT.md` se omite en ejecuciones normales cuando
|
||||
los Heartbeats están deshabilitados para el agente predeterminado o
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` es false. Mantén los archivos inyectados concisos,
|
||||
especialmente `MEMORY.md`, que puede crecer con el tiempo y provocar un uso de contexto inesperadamente alto y una Compaction más frecuente.
|
||||
|
||||
> **Nota:** los archivos diarios `memory/*.md` **no** forman parte del Contexto del proyecto de arranque normal. En turnos normales se accede a ellos bajo demanda mediante las herramientas `memory_search` y `memory_get`, por lo que no cuentan contra la ventana de contexto a menos que el modelo los lea explícitamente. Los turnos simples `/new` y `/reset` son la excepción: el runtime puede anteponer memoria diaria reciente como un bloque único de contexto de inicio para ese primer turno.
|
||||
> **Nota:** los archivos diarios `memory/*.md` **no** forman parte del Contexto del proyecto de arranque normal.
|
||||
> En turnos normales, se accede a ellos bajo demanda mediante las herramientas
|
||||
> `memory_search` y `memory_get`, por lo que no cuentan contra la ventana de
|
||||
> contexto a menos que el modelo los lea explícitamente. Los turnos simples `/new` y
|
||||
> `/reset` son la excepción: el runtime puede anteponer memoria diaria reciente
|
||||
> como un bloque único de contexto de inicio para ese primer turno.
|
||||
|
||||
Los archivos grandes se truncan con un marcador. El tamaño máximo por archivo está controlado por `agents.defaults.bootstrapMaxChars` (predeterminado: 20000). El contenido total de arranque inyectado entre archivos está limitado por `agents.defaults.bootstrapTotalMaxChars` (predeterminado: 150000). Los archivos ausentes inyectan un marcador breve de archivo faltante. Cuando se produce truncamiento, OpenClaw puede inyectar un bloque de advertencia en Contexto del proyecto; contrólalo con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; predeterminado: `once`).
|
||||
Los archivos grandes se truncan con un marcador. El tamaño máximo por archivo está controlado por
|
||||
`agents.defaults.bootstrapMaxChars` (predeterminado: 12000). El contenido total de arranque inyectado
|
||||
entre archivos está limitado por `agents.defaults.bootstrapTotalMaxChars`
|
||||
(predeterminado: 60000). Los archivos ausentes inyectan un marcador corto de archivo faltante. Cuando ocurre truncamiento,
|
||||
OpenClaw puede inyectar un bloque de advertencia en Contexto del proyecto; controla esto con
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
|
||||
predeterminado: `once`).
|
||||
|
||||
Las sesiones de subagentes solo inyectan `AGENTS.md` y `TOOLS.md` (los demás archivos de arranque se filtran para mantener pequeño el contexto del subagente).
|
||||
Las sesiones de subagentes solo inyectan `AGENTS.md` y `TOOLS.md` (los demás archivos de arranque
|
||||
se filtran para mantener pequeño el contexto del subagente).
|
||||
|
||||
Los hooks internos pueden interceptar este paso mediante `agent:bootstrap` para mutar o reemplazar los archivos de arranque inyectados (por ejemplo, cambiar `SOUL.md` por una personalidad alternativa).
|
||||
Los hooks internos pueden interceptar este paso mediante `agent:bootstrap` para mutar o reemplazar
|
||||
los archivos de arranque inyectados (por ejemplo, reemplazando `SOUL.md` por una persona alternativa).
|
||||
|
||||
Si quieres que el agente suene menos genérico, empieza con la [Guía de personalidad de SOUL.md](/es/concepts/soul).
|
||||
Si quieres que el agente suene menos genérico, empieza con
|
||||
[Guía de personalidad de SOUL.md](/es/concepts/soul).
|
||||
|
||||
Para inspeccionar cuánto aporta cada archivo inyectado (sin procesar frente a inyectado, truncamiento, además de la sobrecarga del esquema de herramientas), usa `/context list` o `/context detail`. Consulta [Contexto](/es/concepts/context).
|
||||
|
||||
## Manejo del tiempo
|
||||
|
||||
El prompt del sistema incluye una sección dedicada de **Fecha y hora actuales** cuando se conoce la zona horaria del usuario. Para mantener estable la caché del prompt, ahora solo incluye la **zona horaria** (sin reloj dinámico ni formato de hora).
|
||||
El prompt del sistema incluye una sección dedicada de **Fecha y hora actuales** cuando se conoce la
|
||||
zona horaria del usuario. Para mantener estable la caché del prompt, ahora solo incluye la
|
||||
**zona horaria** (sin reloj dinámico ni formato de hora).
|
||||
|
||||
Usa `session_status` cuando el agente necesite la hora actual; la tarjeta de estado incluye una línea de marca de tiempo. La misma herramienta también puede establecer opcionalmente una anulación de modelo por sesión (`model=default` la borra).
|
||||
Usa `session_status` cuando el agente necesite la hora actual; la tarjeta de estado
|
||||
incluye una línea de marca de tiempo. La misma herramienta también puede establecer opcionalmente una
|
||||
anulación de modelo por sesión (`model=default` la borra).
|
||||
|
||||
Configura con:
|
||||
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
Consulta [Fecha y hora](/es/date-time) para ver los detalles completos del comportamiento.
|
||||
Consulta [Fecha y hora](/es/date-time) para ver todos los detalles del comportamiento.
|
||||
|
||||
## Skills
|
||||
|
||||
Cuando existen Skills aptas, OpenClaw inyecta una **lista compacta de Skills disponibles** (`formatSkillsForPrompt`) que incluye la **ruta del archivo** para cada Skill. El prompt le indica al modelo que use `read` para cargar el SKILL.md en la ubicación indicada (espacio de trabajo, administrado o incluido). Si no hay Skills aptas, se omite la sección Skills.
|
||||
Cuando existen Skills elegibles, OpenClaw inyecta una **lista compacta de Skills disponibles**
|
||||
(`formatSkillsForPrompt`) que incluye la **ruta del archivo** para cada Skill. El
|
||||
prompt le indica al modelo que use `read` para cargar el SKILL.md en la ubicación
|
||||
indicada (espacio de trabajo, administrado o empaquetado). Si no hay Skills elegibles, se omite la sección
|
||||
Skills.
|
||||
|
||||
La aptitud incluye condiciones de metadatos de Skills, comprobaciones del entorno/configuración de runtime y la lista permitida efectiva de Skills del agente cuando `agents.defaults.skills` o `agents.list[].skills` está configurado.
|
||||
La elegibilidad incluye compuertas de metadatos de Skills, comprobaciones del entorno/configuración de runtime
|
||||
y la lista de permitidos efectiva de Skills del agente cuando `agents.defaults.skills` o
|
||||
`agents.list[].skills` está configurado.
|
||||
|
||||
```
|
||||
<available_skills>
|
||||
@ -127,20 +174,25 @@ La aptitud incluye condiciones de metadatos de Skills, comprobaciones del entorn
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
Esto mantiene pequeño el prompt base y, al mismo tiempo, permite el uso dirigido de Skills.
|
||||
Esto mantiene pequeño el prompt base mientras sigue permitiendo el uso dirigido de Skills.
|
||||
|
||||
El presupuesto de la lista de Skills pertenece al subsistema de Skills:
|
||||
|
||||
- Predeterminado global: `skills.limits.maxSkillsPromptChars`
|
||||
- Anulación por agente: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Los extractos genéricos acotados de runtime usan una superficie distinta:
|
||||
Los extractos de runtime genéricos limitados usan una superficie diferente:
|
||||
|
||||
- `agents.defaults.contextLimits.*`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
Esa división mantiene el dimensionamiento de Skills separado del dimensionamiento de lectura/inyección en runtime, como `memory_get`, resultados de herramientas en vivo y actualizaciones de `AGENTS.md` posteriores a Compaction.
|
||||
Esa separación mantiene el dimensionamiento de Skills separado del dimensionamiento de lectura/inyección del runtime, como
|
||||
`memory_get`, resultados de herramientas en vivo y actualizaciones de AGENTS.md posteriores a la Compaction.
|
||||
|
||||
## Documentación
|
||||
|
||||
Cuando está disponible, el prompt del sistema incluye una sección de **Documentación** que apunta al directorio local de documentación de OpenClaw (ya sea `docs/` en el espacio de trabajo del repositorio o la documentación incluida en el paquete npm) y también menciona el espejo público, el repositorio fuente, el Discord de la comunidad y ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descubrir Skills. El prompt le indica al modelo que consulte primero la documentación local para el comportamiento, los comandos, la configuración o la arquitectura de OpenClaw, y que ejecute `openclaw status` por sí mismo cuando sea posible (preguntando al usuario solo cuando no tenga acceso).
|
||||
Cuando está disponible, el prompt del sistema incluye una sección de **Documentación** que apunta al
|
||||
directorio local de documentación de OpenClaw (ya sea `docs/` en el espacio de trabajo del repositorio o la documentación del paquete npm empaquetado) y también menciona la réplica pública, el repositorio fuente, el Discord de la comunidad y
|
||||
ClawHub ([https://clawhub.ai](https://clawhub.ai)) para el descubrimiento de Skills. El prompt le indica al modelo que consulte primero la documentación local
|
||||
para el comportamiento, los comandos, la configuración o la arquitectura de OpenClaw, y que ejecute
|
||||
`openclaw status` por sí mismo cuando sea posible (preguntando al usuario solo cuando no tenga acceso).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Implementación o actualización de clientes WS del Gateway
|
||||
- Depuración de incompatibilidades del protocolo o fallos de conexión
|
||||
- Implementación o actualización de clientes WS de Gateway
|
||||
- Depuración de discrepancias de protocolo o fallos de conexión
|
||||
- Regeneración del esquema/modelos del protocolo
|
||||
summary: 'Protocolo WebSocket del Gateway: saludo inicial, tramas, control de versiones'
|
||||
title: Protocolo Gateway
|
||||
summary: 'Protocolo WebSocket de Gateway: handshake, tramas, control de versiones'
|
||||
title: Protocolo de Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-16T05:15:09Z"
|
||||
generated_at: "2026-04-18T04:59:13Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3
|
||||
source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Protocolo Gateway (WebSocket)
|
||||
# Protocolo de Gateway (WebSocket)
|
||||
|
||||
El protocolo WS del Gateway es el **plano de control único + transporte de nodos** para
|
||||
El protocolo WS de Gateway es el **único plano de control + transporte de nodos** para
|
||||
OpenClaw. Todos los clientes (CLI, interfaz web, app de macOS, nodos iOS/Android,
|
||||
nodos sin interfaz) se conectan mediante WebSocket y declaran su **rol** + **alcance** en el
|
||||
momento del saludo inicial.
|
||||
nodos sin interfaz) se conectan por WebSocket y declaran su **rol** + **alcance** en el
|
||||
momento del handshake.
|
||||
|
||||
## Transporte
|
||||
|
||||
- WebSocket, tramas de texto con cargas útiles JSON.
|
||||
- La primera trama **debe** ser una solicitud `connect`.
|
||||
|
||||
## Saludo inicial (`connect`)
|
||||
## Handshake (`connect`)
|
||||
|
||||
Gateway → Cliente (desafío previo a la conexión):
|
||||
|
||||
@ -96,7 +96,21 @@ Gateway → Cliente:
|
||||
```
|
||||
|
||||
`server`, `features`, `snapshot` y `policy` son obligatorios según el esquema
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` y `canvasHostUrl` son opcionales.
|
||||
(`src/gateway/protocol/schema/frames.ts`). `canvasHostUrl` es opcional. `auth`
|
||||
informa el rol/alcances negociados cuando están disponibles, e incluye `deviceToken`
|
||||
cuando el gateway emite uno.
|
||||
|
||||
Cuando no se emite ningún token de dispositivo, `hello-ok.auth` todavía puede informar los
|
||||
permisos negociados:
|
||||
|
||||
```json
|
||||
{
|
||||
"auth": {
|
||||
"role": "operator",
|
||||
"scopes": ["operator.read", "operator.write"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cuando se emite un token de dispositivo, `hello-ok` también incluye:
|
||||
|
||||
@ -110,8 +124,8 @@ Cuando se emite un token de dispositivo, `hello-ok` también incluye:
|
||||
}
|
||||
```
|
||||
|
||||
Durante la transferencia de arranque confiable, `hello-ok.auth` también puede incluir
|
||||
entradas de rol acotadas adicionales en `deviceTokens`:
|
||||
Durante la transferencia de arranque confiable, `hello-ok.auth` también puede incluir entradas de rol
|
||||
adicionales acotadas en `deviceTokens`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -130,13 +144,12 @@ entradas de rol acotadas adicionales en `deviceTokens`:
|
||||
}
|
||||
```
|
||||
|
||||
Para el flujo integrado de arranque nodo/operador, el token principal del nodo mantiene
|
||||
`scopes: []` y cualquier token de operador transferido sigue estando acotado a la lista
|
||||
permitida del operador de arranque (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Las comprobaciones de alcance de arranque
|
||||
siguen teniendo prefijo de rol: las entradas de operador solo satisfacen solicitudes de
|
||||
operador, y los roles que no son de operador siguen necesitando alcances bajo el prefijo
|
||||
de su propio rol.
|
||||
Para el flujo de arranque integrado de nodo/operador, el token principal del nodo sigue siendo
|
||||
`scopes: []` y cualquier token de operador transferido sigue acotado a la lista de permisos del operador
|
||||
de arranque (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Las comprobaciones de alcance de arranque siguen con prefijo de rol:
|
||||
las entradas de operador solo satisfacen solicitudes de operador, y los roles que no son de operador
|
||||
siguen necesitando alcances bajo el prefijo de su propio rol.
|
||||
|
||||
### Ejemplo de nodo
|
||||
|
||||
@ -173,22 +186,22 @@ de su propio rol.
|
||||
}
|
||||
```
|
||||
|
||||
## Estructura de tramas
|
||||
## Enmarcado
|
||||
|
||||
- **Solicitud**: `{type:"req", id, method, params}`
|
||||
- **Respuesta**: `{type:"res", id, ok, payload|error}`
|
||||
- **Evento**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
Los métodos con efectos secundarios requieren **claves de idempotencia** (véase el esquema).
|
||||
Los métodos con efectos secundarios requieren **claves de idempotencia** (ver esquema).
|
||||
|
||||
## Roles + alcances
|
||||
|
||||
### Roles
|
||||
|
||||
- `operator` = cliente del plano de control (CLI/interfaz de usuario/automatización).
|
||||
- `node` = host de capacidades (camera/screen/canvas/system.run).
|
||||
- `operator` = cliente del plano de control (CLI/UI/automatización).
|
||||
- `node` = host de capacidades (`camera`/`screen`/`canvas`/`system.run`).
|
||||
|
||||
### Alcances (operator)
|
||||
### Alcances (`operator`)
|
||||
|
||||
Alcances comunes:
|
||||
|
||||
@ -202,69 +215,69 @@ Alcances comunes:
|
||||
`talk.config` con `includeSecrets: true` requiere `operator.talk.secrets`
|
||||
(o `operator.admin`).
|
||||
|
||||
Los métodos RPC del Gateway registrados por Plugin pueden solicitar su propio alcance de operador, pero
|
||||
los prefijos reservados de administración del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
Los métodos RPC de Gateway registrados por Plugin pueden solicitar su propio alcance de operador, pero
|
||||
los prefijos administrativos centrales reservados (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) siempre se resuelven como `operator.admin`.
|
||||
|
||||
El alcance del método es solo la primera puerta de control. Algunos comandos con barra a los que se accede mediante
|
||||
`chat.send` aplican comprobaciones más estrictas a nivel de comando además de eso. Por ejemplo, las escrituras persistentes de
|
||||
`/config set` y `/config unset` requieren `operator.admin`.
|
||||
El alcance del método es solo el primer filtro. Algunos comandos slash alcanzados mediante
|
||||
`chat.send` aplican comprobaciones más estrictas a nivel de comando además de eso. Por ejemplo, las escrituras
|
||||
persistentes de `/config set` y `/config unset` requieren `operator.admin`.
|
||||
|
||||
`node.pair.approve` también tiene una comprobación adicional de alcance en el momento de aprobación además del
|
||||
`node.pair.approve` también tiene una comprobación adicional de alcance en el momento de la aprobación además del
|
||||
alcance base del método:
|
||||
|
||||
- solicitudes sin comando: `operator.pairing`
|
||||
- solicitudes con comandos de nodo que no son exec: `operator.pairing` + `operator.write`
|
||||
- solicitudes con comandos de nodo que no son `exec`: `operator.pairing` + `operator.write`
|
||||
- solicitudes que incluyen `system.run`, `system.run.prepare` o `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Capacidades/comandos/permisos (node)
|
||||
### `caps`/`commands`/`permissions` (`node`)
|
||||
|
||||
Los nodos declaran capacidades reclamadas en el momento de conectarse:
|
||||
Los nodos declaran reclamaciones de capacidad en el momento de conectarse:
|
||||
|
||||
- `caps`: categorías de capacidades de alto nivel.
|
||||
- `commands`: lista permitida de comandos para `invoke`.
|
||||
- `permissions`: controles detallados (por ejemplo, `screen.record`, `camera.capture`).
|
||||
- `caps`: categorías de capacidad de alto nivel.
|
||||
- `commands`: lista permitida de comandos para invocación.
|
||||
- `permissions`: controles granulares (por ejemplo, `screen.record`, `camera.capture`).
|
||||
|
||||
El Gateway las trata como **reclamaciones** y aplica listas permitidas del lado del servidor.
|
||||
Gateway los trata como **reclamaciones** y aplica listas permitidas del lado del servidor.
|
||||
|
||||
## Presencia
|
||||
|
||||
- `system-presence` devuelve entradas indexadas por identidad del dispositivo.
|
||||
- Las entradas de presencia incluyen `deviceId`, `roles` y `scopes` para que las interfaces puedan mostrar una sola fila por dispositivo
|
||||
incluso cuando se conecta como **operator** y **node** al mismo tiempo.
|
||||
- `system-presence` devuelve entradas indexadas por identidad de dispositivo.
|
||||
- Las entradas de presencia incluyen `deviceId`, `roles` y `scopes` para que las UI puedan mostrar una sola fila por dispositivo
|
||||
incluso cuando se conecta tanto como **operator** como **node**.
|
||||
|
||||
## Familias comunes de métodos RPC
|
||||
|
||||
Esta página no es un volcado completo generado, pero la superficie WS pública es más amplia
|
||||
que los ejemplos de saludo inicial/autenticación anteriores. Estas son las principales familias de métodos que el
|
||||
que los ejemplos de handshake/autenticación anteriores. Estas son las principales familias de métodos que
|
||||
Gateway expone hoy.
|
||||
|
||||
`hello-ok.features.methods` es una lista de descubrimiento conservadora construida a partir de
|
||||
`hello-ok.features.methods` es una lista conservadora de descubrimiento construida a partir de
|
||||
`src/gateway/server-methods-list.ts` más las exportaciones de métodos de plugins/canales cargados.
|
||||
Trátela como descubrimiento de funcionalidades, no como un volcado generado de cada helper invocable
|
||||
Trátela como descubrimiento de funciones, no como un volcado generado de cada helper invocable
|
||||
implementado en `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### Sistema e identidad
|
||||
|
||||
- `health` devuelve la instantánea de estado del Gateway almacenada en caché o recién sondeada.
|
||||
- `status` devuelve el resumen del Gateway estilo `/status`; los campos sensibles
|
||||
se incluyen solo para clientes operator con alcance de administrador.
|
||||
- `gateway.identity.get` devuelve la identidad del dispositivo Gateway usada por los flujos
|
||||
de retransmisión y emparejamiento.
|
||||
- `system-presence` devuelve la instantánea de presencia actual de los dispositivos
|
||||
operator/node conectados.
|
||||
- `health` devuelve la instantánea de estado del gateway almacenada en caché o recién sondeada.
|
||||
- `status` devuelve el resumen del gateway al estilo `/status`; los campos sensibles se
|
||||
incluyen solo para clientes `operator` con alcance de administrador.
|
||||
- `gateway.identity.get` devuelve la identidad del dispositivo del gateway usada por los flujos de relay y
|
||||
emparejamiento.
|
||||
- `system-presence` devuelve la instantánea de presencia actual para los dispositivos
|
||||
`operator`/`node` conectados.
|
||||
- `system-event` agrega un evento del sistema y puede actualizar/transmitir el contexto
|
||||
de presencia.
|
||||
- `last-heartbeat` devuelve el evento Heartbeat persistido más reciente.
|
||||
- `set-heartbeats` activa o desactiva el procesamiento de Heartbeat en el Gateway.
|
||||
- `set-heartbeats` activa o desactiva el procesamiento de Heartbeat en el gateway.
|
||||
|
||||
### Modelos y uso
|
||||
|
||||
- `models.list` devuelve el catálogo de modelos permitido en tiempo de ejecución.
|
||||
- `usage.status` devuelve resúmenes de ventanas de uso/restante de cuota del proveedor.
|
||||
- `usage.cost` devuelve resúmenes agregados de uso de costo para un intervalo de fechas.
|
||||
- `doctor.memory.status` devuelve la preparación de memoria vectorial / incrustación para el
|
||||
- `doctor.memory.status` devuelve la preparación de memoria vectorial/embeddings para el
|
||||
espacio de trabajo del agente predeterminado activo.
|
||||
- `sessions.usage` devuelve resúmenes de uso por sesión.
|
||||
- `sessions.usage.timeseries` devuelve series temporales de uso para una sesión.
|
||||
@ -272,108 +285,107 @@ implementado en `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### Canales y helpers de inicio de sesión
|
||||
|
||||
- `channels.status` devuelve resúmenes de estado de canales/plugins integrados y empaquetados.
|
||||
- `channels.logout` cierra la sesión de un canal/cuenta específico donde el canal
|
||||
- `channels.status` devuelve resúmenes de estado de canales/plugins integrados + empaquetados.
|
||||
- `channels.logout` cierra la sesión de un canal/cuenta específicos cuando el canal
|
||||
admite cierre de sesión.
|
||||
- `web.login.start` inicia un flujo de inicio de sesión QR/web para el proveedor de canal web
|
||||
- `web.login.start` inicia un flujo de inicio de sesión por QR/web para el proveedor del canal web
|
||||
actual compatible con QR.
|
||||
- `web.login.wait` espera a que ese flujo de inicio de sesión QR/web se complete e inicia el
|
||||
canal si tiene éxito.
|
||||
- `web.login.wait` espera a que ese flujo de inicio de sesión por QR/web finalice y arranca el
|
||||
canal si se completa con éxito.
|
||||
- `push.test` envía una notificación push APNs de prueba a un nodo iOS registrado.
|
||||
- `voicewake.get` devuelve los activadores de palabra de activación almacenados.
|
||||
- `voicewake.set` actualiza los activadores de palabra de activación y transmite el cambio.
|
||||
- `voicewake.get` devuelve los disparadores de palabras de activación almacenados.
|
||||
- `voicewake.set` actualiza los disparadores de palabras de activación y transmite el cambio.
|
||||
|
||||
### Mensajería y registros
|
||||
|
||||
- `send` es el RPC de entrega saliente directa para envíos dirigidos a canal/cuenta/hilo
|
||||
fuera del ejecutor de chat.
|
||||
- `logs.tail` devuelve el final del registro de archivos configurado del Gateway con cursor/límite y
|
||||
controles máximos de bytes.
|
||||
- `logs.tail` devuelve la cola del archivo de registros configurado del gateway con cursor/límite y
|
||||
controles de bytes máximos.
|
||||
|
||||
### Talk y TTS
|
||||
|
||||
- `talk.config` devuelve la carga útil efectiva de configuración de Talk; `includeSecrets`
|
||||
- `talk.config` devuelve la carga útil de configuración efectiva de Talk; `includeSecrets`
|
||||
requiere `operator.talk.secrets` (o `operator.admin`).
|
||||
- `talk.mode` establece/transmite el estado actual del modo Talk para clientes
|
||||
de WebChat/Control UI.
|
||||
- `talk.speak` sintetiza voz mediante el proveedor de voz Talk activo.
|
||||
- `talk.mode` establece/transmite el estado actual del modo Talk para los clientes de WebChat/Control UI.
|
||||
- `talk.speak` sintetiza voz a través del proveedor de voz activo de Talk.
|
||||
- `tts.status` devuelve el estado de activación de TTS, el proveedor activo, los proveedores de respaldo
|
||||
y el estado de configuración del proveedor.
|
||||
- `tts.providers` devuelve el inventario visible de proveedores TTS.
|
||||
- `tts.enable` y `tts.disable` activan o desactivan el estado de preferencias de TTS.
|
||||
- `tts.enable` y `tts.disable` activan y desactivan el estado de preferencias de TTS.
|
||||
- `tts.setProvider` actualiza el proveedor TTS preferido.
|
||||
- `tts.convert` ejecuta una conversión puntual de texto a voz.
|
||||
|
||||
### Secretos, configuración, actualización y asistente
|
||||
|
||||
- `secrets.reload` vuelve a resolver las SecretRef activas e intercambia el estado de secretos en tiempo de ejecución
|
||||
- `secrets.reload` vuelve a resolver los SecretRef activos e intercambia el estado de secretos en tiempo de ejecución
|
||||
solo si todo se completa correctamente.
|
||||
- `secrets.resolve` resuelve asignaciones de secretos dirigidas a comandos para un conjunto
|
||||
específico de comando/destino.
|
||||
- `secrets.resolve` resuelve asignaciones de secretos dirigidas a comandos para un conjunto específico
|
||||
de comandos/objetivos.
|
||||
- `config.get` devuelve la instantánea y el hash de la configuración actual.
|
||||
- `config.set` escribe una carga útil de configuración validada.
|
||||
- `config.patch` fusiona una actualización parcial de configuración.
|
||||
- `config.apply` valida y reemplaza la carga útil completa de configuración.
|
||||
- `config.patch` fusiona una actualización parcial de la configuración.
|
||||
- `config.apply` valida y reemplaza la carga útil de configuración completa.
|
||||
- `config.schema` devuelve la carga útil del esquema de configuración en vivo usada por Control UI y
|
||||
herramientas CLI: esquema, `uiHints`, versión y metadatos de generación, incluidos
|
||||
metadatos de esquema de plugins + canales cuando el runtime puede cargarlos. El esquema
|
||||
las herramientas CLI: esquema, `uiHints`, versión y metadatos de generación, incluidos
|
||||
metadatos de esquema de plugins + canales cuando el entorno de ejecución puede cargarlos. El esquema
|
||||
incluye metadatos de campo `title` / `description` derivados de las mismas etiquetas
|
||||
y texto de ayuda usados por la interfaz, incluidas ramas anidadas de objeto, comodín,
|
||||
elemento de matriz y composición `anyOf` / `oneOf` / `allOf` cuando existe documentación
|
||||
de campo coincidente.
|
||||
- `config.schema.lookup` devuelve una carga útil de búsqueda con alcance a ruta para una ruta de configuración:
|
||||
ruta normalizada, un nodo de esquema superficial, la sugerencia coincidente + `hintPath`, y
|
||||
resúmenes inmediatos de elementos secundarios para exploración en interfaz/CLI.
|
||||
- Los nodos de esquema de búsqueda conservan la documentación orientada al usuario y los campos de validación comunes:
|
||||
y el mismo texto de ayuda usados por la UI, incluidas las ramas anidadas de composición de objetos, comodines,
|
||||
elementos de array y `anyOf` / `oneOf` / `allOf` cuando existe documentación de campo
|
||||
coincidente.
|
||||
- `config.schema.lookup` devuelve una carga útil de búsqueda acotada a ruta para una ruta de configuración:
|
||||
ruta normalizada, un nodo superficial del esquema, `hint` + `hintPath` coincidentes y
|
||||
resúmenes inmediatos de hijos para la exploración detallada en UI/CLI.
|
||||
- Los nodos de esquema de búsqueda conservan la documentación orientada al usuario y los campos comunes de validación:
|
||||
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
|
||||
límites numéricos/de cadena/de matriz/de objeto, y marcas booleanas como
|
||||
límites numéricos/de cadenas/de arrays/de objetos y banderas booleanas como
|
||||
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
|
||||
- Los resúmenes de elementos secundarios exponen `key`, `path` normalizada, `type`, `required`,
|
||||
- Los resúmenes de hijos exponen `key`, `path` normalizada, `type`, `required`,
|
||||
`hasChildren`, además de `hint` / `hintPath` coincidentes.
|
||||
- `update.run` ejecuta el flujo de actualización del Gateway y programa un reinicio solo cuando
|
||||
la actualización en sí se completó correctamente.
|
||||
- `update.run` ejecuta el flujo de actualización del gateway y programa un reinicio solo cuando
|
||||
la propia actualización se completó correctamente.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` y `wizard.cancel` exponen el
|
||||
asistente de incorporación mediante WS RPC.
|
||||
asistente de incorporación a través de WS RPC.
|
||||
|
||||
### Familias principales existentes
|
||||
|
||||
#### Helpers de agente y espacio de trabajo
|
||||
#### Agente y helpers de espacio de trabajo
|
||||
|
||||
- `agents.list` devuelve entradas de agentes configuradas.
|
||||
- `agents.create`, `agents.update` y `agents.delete` administran registros de agentes y
|
||||
- `agents.list` devuelve las entradas de agente configuradas.
|
||||
- `agents.create`, `agents.update` y `agents.delete` administran los registros de agentes y
|
||||
la conexión del espacio de trabajo.
|
||||
- `agents.files.list`, `agents.files.get` y `agents.files.set` administran los
|
||||
archivos del espacio de trabajo de arranque expuestos para un agente.
|
||||
- `agent.identity.get` devuelve la identidad efectiva del asistente para un agente o
|
||||
sesión.
|
||||
- `agent.wait` espera a que una ejecución finalice y devuelve la instantánea terminal cuando
|
||||
- `agent.wait` espera a que una ejecución termine y devuelve la instantánea terminal cuando
|
||||
está disponible.
|
||||
|
||||
#### Control de sesión
|
||||
|
||||
- `sessions.list` devuelve el índice actual de sesiones.
|
||||
- `sessions.list` devuelve el índice de sesión actual.
|
||||
- `sessions.subscribe` y `sessions.unsubscribe` activan o desactivan las suscripciones a eventos de cambio de sesión
|
||||
para el cliente WS actual.
|
||||
- `sessions.messages.subscribe` y `sessions.messages.unsubscribe` activan o desactivan
|
||||
las suscripciones a eventos de transcripción/mensajes para una sesión.
|
||||
las suscripciones a eventos de transcripción/mensaje para una sesión.
|
||||
- `sessions.preview` devuelve vistas previas acotadas de la transcripción para claves de sesión
|
||||
específicas.
|
||||
- `sessions.resolve` resuelve o canoniza un destino de sesión.
|
||||
- `sessions.resolve` resuelve o canonicaliza un destino de sesión.
|
||||
- `sessions.create` crea una nueva entrada de sesión.
|
||||
- `sessions.send` envía un mensaje a una sesión existente.
|
||||
- `sessions.steer` es la variante de interrumpir y redirigir para una sesión activa.
|
||||
- `sessions.abort` aborta el trabajo activo de una sesión.
|
||||
- `sessions.patch` actualiza metadatos/sobrescrituras de la sesión.
|
||||
- `sessions.reset`, `sessions.delete` y `sessions.compact` realizan mantenimiento de
|
||||
sesión.
|
||||
- `sessions.patch` actualiza metadatos/anulaciones de la sesión.
|
||||
- `sessions.reset`, `sessions.delete` y `sessions.compact` realizan tareas de
|
||||
mantenimiento de la sesión.
|
||||
- `sessions.get` devuelve la fila completa de la sesión almacenada.
|
||||
- la ejecución de chat sigue usando `chat.history`, `chat.send`, `chat.abort` y
|
||||
- la ejecución del chat sigue usando `chat.history`, `chat.send`, `chat.abort` y
|
||||
`chat.inject`.
|
||||
- `chat.history` está normalizado para visualización para clientes de UI: las etiquetas de directivas en línea se
|
||||
eliminan del texto visible, las cargas útiles XML de llamadas a herramientas en texto plano (incluidas
|
||||
- `chat.history` está normalizado para visualización para clientes UI: las etiquetas de directiva en línea se
|
||||
eliminan del texto visible, las cargas útiles XML de llamada de herramienta en texto plano (incluidas
|
||||
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, y
|
||||
bloques truncados de llamadas a herramientas) y los tokens de control del modelo filtrados en ASCII/ancho completo
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` y
|
||||
bloques de llamada de herramienta truncados) y los tokens de control del modelo filtrados en ASCII/ancho completo
|
||||
se eliminan, las filas del asistente compuestas únicamente por tokens silenciosos como `NO_REPLY` /
|
||||
`no_reply` exactos se omiten, y las filas sobredimensionadas pueden reemplazarse por marcadores de posición.
|
||||
|
||||
@ -382,8 +394,8 @@ implementado en `src/gateway/server-methods/*.ts`.
|
||||
- `device.pair.list` devuelve los dispositivos emparejados pendientes y aprobados.
|
||||
- `device.pair.approve`, `device.pair.reject` y `device.pair.remove` administran
|
||||
los registros de emparejamiento de dispositivos.
|
||||
- `device.token.rotate` rota un token de dispositivo emparejado dentro de los límites
|
||||
aprobados de su rol y alcances.
|
||||
- `device.token.rotate` rota un token de dispositivo emparejado dentro de sus límites aprobados de rol
|
||||
y alcance.
|
||||
- `device.token.revoke` revoca un token de dispositivo emparejado.
|
||||
|
||||
#### Emparejamiento de nodos, invocación y trabajo pendiente
|
||||
@ -392,26 +404,26 @@ implementado en `src/gateway/server-methods/*.ts`.
|
||||
`node.pair.reject` y `node.pair.verify` cubren el emparejamiento de nodos y la
|
||||
verificación de arranque.
|
||||
- `node.list` y `node.describe` devuelven el estado de nodos conocidos/conectados.
|
||||
- `node.rename` actualiza la etiqueta de un nodo emparejado.
|
||||
- `node.rename` actualiza una etiqueta de nodo emparejado.
|
||||
- `node.invoke` reenvía un comando a un nodo conectado.
|
||||
- `node.invoke.result` devuelve el resultado de una solicitud de invocación.
|
||||
- `node.event` transporta eventos originados en el nodo de vuelta al Gateway.
|
||||
- `node.canvas.capability.refresh` actualiza tokens de capacidad de canvas con alcance limitado.
|
||||
- `node.event` transporta eventos originados en el nodo de vuelta al gateway.
|
||||
- `node.canvas.capability.refresh` actualiza tokens acotados de capacidad de canvas.
|
||||
- `node.pending.pull` y `node.pending.ack` son las API de cola para nodos conectados.
|
||||
- `node.pending.enqueue` y `node.pending.drain` administran trabajo pendiente duradero
|
||||
para nodos sin conexión/desconectados.
|
||||
para nodos desconectados o fuera de línea.
|
||||
|
||||
#### Familias de aprobación
|
||||
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` y
|
||||
`exec.approval.resolve` cubren solicitudes puntuales de aprobación de exec además de
|
||||
búsqueda/repetición de aprobaciones pendientes.
|
||||
- `exec.approval.waitDecision` espera una aprobación exec pendiente y devuelve
|
||||
la decisión final (o `null` por tiempo de espera agotado).
|
||||
`exec.approval.resolve` cubren solicitudes puntuales de aprobación de `exec` más
|
||||
la búsqueda/repetición de aprobaciones pendientes.
|
||||
- `exec.approval.waitDecision` espera una aprobación `exec` pendiente y devuelve
|
||||
la decisión final (o `null` en caso de tiempo de espera agotado).
|
||||
- `exec.approvals.get` y `exec.approvals.set` administran instantáneas de la política
|
||||
de aprobación exec del Gateway.
|
||||
- `exec.approvals.node.get` y `exec.approvals.node.set` administran la política local del nodo para exec
|
||||
mediante comandos de retransmisión del nodo.
|
||||
de aprobación `exec` del gateway.
|
||||
- `exec.approvals.node.get` y `exec.approvals.node.set` administran la política local de aprobación `exec`
|
||||
del nodo mediante comandos de relay del nodo.
|
||||
- `plugin.approval.request`, `plugin.approval.list`,
|
||||
`plugin.approval.waitDecision` y `plugin.approval.resolve` cubren
|
||||
flujos de aprobación definidos por Plugin.
|
||||
@ -426,46 +438,44 @@ implementado en `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### Familias comunes de eventos
|
||||
|
||||
- `chat`: actualizaciones de chat de UI como `chat.inject` y otros eventos de chat
|
||||
solo de transcripción.
|
||||
- `chat`: actualizaciones de chat de la UI, como `chat.inject` y otros
|
||||
eventos de chat solo de transcripción.
|
||||
- `session.message` y `session.tool`: actualizaciones de transcripción/flujo de eventos para una
|
||||
sesión suscrita.
|
||||
- `sessions.changed`: cambió el índice de sesiones o los metadatos.
|
||||
- `presence`: actualizaciones de instantáneas de presencia del sistema.
|
||||
- `tick`: evento periódico de keepalive/vivacidad.
|
||||
- `health`: actualización de instantánea de estado del Gateway.
|
||||
- `sessions.changed`: cambió el índice de sesión o sus metadatos.
|
||||
- `presence`: actualizaciones de la instantánea de presencia del sistema.
|
||||
- `tick`: evento periódico de keepalive / actividad.
|
||||
- `health`: actualización de la instantánea de estado del gateway.
|
||||
- `heartbeat`: actualización del flujo de eventos Heartbeat.
|
||||
- `cron`: evento de cambio de ejecución/trabajo Cron.
|
||||
- `shutdown`: notificación de apagado del Gateway.
|
||||
- `cron`: evento de cambio de ejecución/trabajo de Cron.
|
||||
- `shutdown`: notificación de apagado del gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: ciclo de vida del emparejamiento de nodos.
|
||||
- `node.invoke.request`: difusión de solicitud de invocación de nodo.
|
||||
- `device.pair.requested` / `device.pair.resolved`: ciclo de vida del dispositivo emparejado.
|
||||
- `voicewake.changed`: cambió la configuración de activadores de palabra de activación.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida de la
|
||||
aprobación exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida de la
|
||||
aprobación de Plugin.
|
||||
- `voicewake.changed`: cambió la configuración de disparadores de palabra de activación.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida de aprobación de `exec`.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida de aprobación de Plugin.
|
||||
|
||||
### Métodos helper de nodo
|
||||
|
||||
- Los nodos pueden llamar a `skills.bins` para obtener la lista actual de ejecutables de Skills
|
||||
para comprobaciones de permiso automático.
|
||||
|
||||
### Métodos helper de operator
|
||||
### Métodos helper de operador
|
||||
|
||||
- Los operadores pueden llamar a `commands.list` (`operator.read`) para obtener el inventario
|
||||
de comandos en tiempo de ejecución de un agente.
|
||||
- Los operadores pueden llamar a `commands.list` (`operator.read`) para obtener el inventario de comandos en tiempo de ejecución para un
|
||||
agente.
|
||||
- `agentId` es opcional; omítalo para leer el espacio de trabajo del agente predeterminado.
|
||||
- `scope` controla a qué superficie apunta el `name` principal:
|
||||
- `text` devuelve el token principal del comando de texto sin la `/` inicial
|
||||
- `native` y la ruta predeterminada `both` devuelven nombres nativos sensibles al proveedor
|
||||
- `text` devuelve el token principal de comando de texto sin la `/` inicial
|
||||
- `native` y la ruta predeterminada `both` devuelven nombres nativos compatibles con proveedor
|
||||
cuando están disponibles
|
||||
- `textAliases` contiene alias exactos con barra como `/model` y `/m`.
|
||||
- `nativeName` contiene el nombre de comando nativo sensible al proveedor cuando existe.
|
||||
- `provider` es opcional y solo afecta al nombre nativo además de la disponibilidad de comandos
|
||||
nativos del Plugin.
|
||||
- `includeArgs=false` omite metadatos de argumentos serializados de la respuesta.
|
||||
- Los operadores pueden llamar a `tools.catalog` (`operator.read`) para obtener el catálogo de herramientas en tiempo de ejecución de un
|
||||
- `textAliases` contiene alias slash exactos como `/model` y `/m`.
|
||||
- `nativeName` contiene el nombre de comando nativo compatible con el proveedor cuando existe.
|
||||
- `provider` es opcional y solo afecta el nombre nativo más la disponibilidad de comandos nativos
|
||||
del Plugin.
|
||||
- `includeArgs=false` omite del resultado los metadatos serializados de argumentos.
|
||||
- Los operadores pueden llamar a `tools.catalog` (`operator.read`) para obtener el catálogo de herramientas en tiempo de ejecución para un
|
||||
agente. La respuesta incluye herramientas agrupadas y metadatos de procedencia:
|
||||
- `source`: `core` o `plugin`
|
||||
- `pluginId`: propietario del Plugin cuando `source="plugin"`
|
||||
@ -473,10 +483,10 @@ implementado en `src/gateway/server-methods/*.ts`.
|
||||
- Los operadores pueden llamar a `tools.effective` (`operator.read`) para obtener el inventario efectivo de herramientas en tiempo de ejecución
|
||||
para una sesión.
|
||||
- `sessionKey` es obligatorio.
|
||||
- El Gateway deriva el contexto confiable de tiempo de ejecución del lado del servidor a partir de la sesión en lugar de aceptar
|
||||
autenticación o contexto de entrega proporcionados por el llamador.
|
||||
- La respuesta tiene alcance de sesión y refleja lo que la conversación activa puede usar ahora mismo,
|
||||
incluidas herramientas core, de Plugin y de canal.
|
||||
- El gateway deriva el contexto confiable de tiempo de ejecución del lado del servidor a partir de la sesión en lugar de aceptar
|
||||
autenticación o contexto de entrega proporcionados por quien llama.
|
||||
- La respuesta está acotada a la sesión y refleja lo que la conversación activa puede usar en este momento,
|
||||
incluidas herramientas de núcleo, Plugin y canal.
|
||||
- Los operadores pueden llamar a `skills.status` (`operator.read`) para obtener el inventario visible
|
||||
de Skills para un agente.
|
||||
- `agentId` es opcional; omítalo para leer el espacio de trabajo del agente predeterminado.
|
||||
@ -487,151 +497,152 @@ implementado en `src/gateway/server-methods/*.ts`.
|
||||
- Los operadores pueden llamar a `skills.install` (`operator.admin`) en dos modos:
|
||||
- Modo ClawHub: `{ source: "clawhub", slug, version?, force? }` instala una
|
||||
carpeta de skill en el directorio `skills/` del espacio de trabajo del agente predeterminado.
|
||||
- Modo instalador del Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
ejecuta una acción declarada `metadata.openclaw.install` en el host del Gateway.
|
||||
- Modo instalador de gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
ejecuta una acción declarada `metadata.openclaw.install` en el host del gateway.
|
||||
- Los operadores pueden llamar a `skills.update` (`operator.admin`) en dos modos:
|
||||
- El modo ClawHub actualiza un slug rastreado o todas las instalaciones rastreadas de ClawHub en
|
||||
- El modo ClawHub actualiza un `slug` rastreado o todas las instalaciones rastreadas de ClawHub en
|
||||
el espacio de trabajo del agente predeterminado.
|
||||
- El modo de configuración aplica un parche a valores `skills.entries.<skillKey>` como `enabled`,
|
||||
- El modo configuración aplica un parche a valores `skills.entries.<skillKey>` como `enabled`,
|
||||
`apiKey` y `env`.
|
||||
|
||||
## Aprobaciones exec
|
||||
## Aprobaciones de `exec`
|
||||
|
||||
- Cuando una solicitud exec necesita aprobación, el Gateway difunde `exec.approval.requested`.
|
||||
- Los clientes operator resuelven llamando a `exec.approval.resolve` (requiere alcance `operator.approvals`).
|
||||
- Cuando una solicitud `exec` necesita aprobación, el gateway difunde `exec.approval.requested`.
|
||||
- Los clientes operador resuelven llamando a `exec.approval.resolve` (requiere alcance `operator.approvals`).
|
||||
- Para `host=node`, `exec.approval.request` debe incluir `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadatos de sesión canónicos). Las solicitudes sin `systemRunPlan` se rechazan.
|
||||
- Después de la aprobación, las llamadas reenviadas `node.invoke system.run` reutilizan ese
|
||||
`systemRunPlan` canónico como el contexto autoritativo de comando/cwd/sesión.
|
||||
- Si un llamador modifica `command`, `rawCommand`, `cwd`, `agentId` o
|
||||
`sessionKey` entre prepare y el reenvío final aprobado de `system.run`, el
|
||||
Gateway rechaza la ejecución en lugar de confiar en la carga útil modificada.
|
||||
`systemRunPlan` canónico como contexto autoritativo de comando/cwd/sesión.
|
||||
- Si quien llama modifica `command`, `rawCommand`, `cwd`, `agentId` o
|
||||
`sessionKey` entre `prepare` y el reenvío final aprobado de `system.run`, el
|
||||
gateway rechaza la ejecución en lugar de confiar en la carga útil modificada.
|
||||
|
||||
## Respaldo de entrega del agente
|
||||
|
||||
- Las solicitudes `agent` pueden incluir `deliver=true` para solicitar entrega saliente.
|
||||
- `bestEffortDeliver=false` mantiene el comportamiento estricto: los destinos de entrega no resueltos o solo internos devuelven `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` permite recurrir a ejecución solo de sesión cuando no se puede resolver ninguna ruta de entrega externa (por ejemplo, sesiones internas/de webchat o configuraciones ambiguas de múltiples canales).
|
||||
- `bestEffortDeliver=false` mantiene un comportamiento estricto: los destinos de entrega no resueltos o solo internos devuelven `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` permite recurrir a ejecución solo de sesión cuando no puede resolverse ninguna ruta externa entregable (por ejemplo, sesiones internas/webchat o configuraciones ambiguas de múltiples canales).
|
||||
|
||||
## Control de versiones
|
||||
|
||||
- `PROTOCOL_VERSION` vive en `src/gateway/protocol/schema/protocol-schemas.ts`.
|
||||
- Los clientes envían `minProtocol` + `maxProtocol`; el servidor rechaza incompatibilidades.
|
||||
- `PROTOCOL_VERSION` se encuentra en `src/gateway/protocol/schema/protocol-schemas.ts`.
|
||||
- Los clientes envían `minProtocol` + `maxProtocol`; el servidor rechaza discrepancias.
|
||||
- Los esquemas + modelos se generan a partir de definiciones TypeBox:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
|
||||
### Constantes de cliente
|
||||
### Constantes del cliente
|
||||
|
||||
El cliente de referencia en `src/gateway/client.ts` usa estos valores predeterminados. Los valores son
|
||||
estables en todo el protocolo v3 y son la línea base esperada para clientes de terceros.
|
||||
|
||||
| Constante | Predeterminado | Fuente |
|
||||
| Constant | Default | Source |
|
||||
| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| Tiempo de espera de solicitud (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Tiempo de espera previo a autenticación / desafío de conexión | `10_000` ms | `src/gateway/handshake-timeouts.ts` (límite `250`–`10_000`) |
|
||||
| Retroceso inicial de reconexión | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Retroceso máximo de reconexión | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Límite de reintento rápido después de cierre por token de dispositivo | `250` ms | `src/gateway/client.ts` |
|
||||
| Gracia de parada forzada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Tiempo de espera predeterminado de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Intervalo `tick` predeterminado (antes de `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Cierre por tiempo de espera de `tick` | código `4000` cuando el silencio supera `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| Tiempo de espera de solicitud (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Tiempo de espera de preautorización / desafío de conexión | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) |
|
||||
| Retroceso inicial de reconexión | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Retroceso máximo de reconexión | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Límite de reintento rápido tras cierre por token de dispositivo | `250` ms | `src/gateway/client.ts` |
|
||||
| Período de gracia de parada forzada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Tiempo de espera predeterminado de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Intervalo `tick` predeterminado (antes de `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Cierre por tiempo de espera de `tick` | código `4000` cuando el silencio supera `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
|
||||
El servidor anuncia los valores efectivos `policy.tickIntervalMs`, `policy.maxPayload`
|
||||
y `policy.maxBufferedBytes` en `hello-ok`; los clientes deben respetar esos valores
|
||||
en lugar de los predeterminados previos al saludo inicial.
|
||||
en lugar de los valores predeterminados previos al handshake.
|
||||
|
||||
## Autenticación
|
||||
|
||||
- La autenticación del Gateway con secreto compartido usa `connect.params.auth.token` o
|
||||
- La autenticación del gateway con secreto compartido usa `connect.params.auth.token` o
|
||||
`connect.params.auth.password`, según el modo de autenticación configurado.
|
||||
- Los modos con identidad, como Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"` sin loopback,
|
||||
satisfacen la comprobación de autenticación de conexión a partir de los
|
||||
(`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"`
|
||||
en interfaces que no son de loopback, satisfacen la comprobación de autenticación de `connect` a partir de
|
||||
encabezados de la solicitud en lugar de `connect.params.auth.*`.
|
||||
- `gateway.auth.mode: "none"` para ingreso privado omite por completo la autenticación de conexión con secreto compartido; no exponga ese modo en ingresos públicos/no confiables.
|
||||
- Después del emparejamiento, el Gateway emite un **token de dispositivo** con alcance limitado al rol + alcances
|
||||
- `gateway.auth.mode: "none"` para ingreso privado omite por completo la autenticación `connect` con secreto compartido;
|
||||
no exponga ese modo en ingresos públicos o no confiables.
|
||||
- Después del emparejamiento, Gateway emite un **token de dispositivo** limitado al rol + alcances
|
||||
de la conexión. Se devuelve en `hello-ok.auth.deviceToken` y el cliente debe
|
||||
persistirlo para conexiones futuras.
|
||||
- Los clientes deben persistir el `hello-ok.auth.deviceToken` principal después de cualquier
|
||||
conexión satisfactoria.
|
||||
- Al reconectar con ese token de dispositivo **almacenado**, también se debe reutilizar el conjunto de alcances
|
||||
aprobados almacenado para ese token. Esto conserva el acceso de lectura/sondeo/estado
|
||||
que ya se había concedido y evita reducir silenciosamente las reconexiones a un
|
||||
alcance implícito más limitado de solo administrador.
|
||||
- Ensamblaje de autenticación de conexión del lado del cliente (`selectConnectAuth` en
|
||||
conexión exitosa.
|
||||
- Al reconectarse con ese token de dispositivo **almacenado**, también se debe reutilizar el conjunto de alcances aprobados
|
||||
almacenado para ese token. Esto preserva el acceso de lectura/sondeo/estado
|
||||
que ya se concedió y evita que las reconexiones colapsen silenciosamente a un
|
||||
alcance implícito más estrecho de solo administrador.
|
||||
- Ensamblado de autenticación `connect` del lado del cliente (`selectConnectAuth` en
|
||||
`src/gateway/client.ts`):
|
||||
- `auth.password` es ortogonal y siempre se reenvía cuando está establecido.
|
||||
- `auth.token` se completa en orden de prioridad: primero un token compartido explícito,
|
||||
luego un `deviceToken` explícito, y después un token por dispositivo almacenado (indexado por
|
||||
- `auth.token` se completa en este orden de prioridad: primero el token compartido explícito,
|
||||
luego un `deviceToken` explícito y, después, un token almacenado por dispositivo (indexado por
|
||||
`deviceId` + `role`).
|
||||
- `auth.bootstrapToken` se envía solo cuando ninguna de las opciones anteriores resolvió un
|
||||
`auth.token`. Un token compartido o cualquier token de dispositivo resuelto lo suprime.
|
||||
- La autopromoción de un token de dispositivo almacenado en el reintento puntual
|
||||
`AUTH_TOKEN_MISMATCH` está restringida a **endpoints confiables únicamente** —
|
||||
loopback, o `wss://` con `tlsFingerprint` fijado. Un `wss://` público
|
||||
sin fijación no cumple ese requisito.
|
||||
`AUTH_TOKEN_MISMATCH` está restringida **solo a endpoints confiables**:
|
||||
loopback, o `wss://` con `tlsFingerprint` fijado. `wss://` público
|
||||
sin fijación no califica.
|
||||
- Las entradas adicionales `hello-ok.auth.deviceTokens` son tokens de transferencia de arranque.
|
||||
Persístalos solo cuando la conexión haya usado autenticación de arranque sobre un transporte confiable
|
||||
Persístalos solo cuando la conexión haya usado autenticación de arranque en un transporte confiable
|
||||
como `wss://` o loopback/emparejamiento local.
|
||||
- Si un cliente proporciona un `deviceToken` **explícito** o `scopes` explícitos, ese
|
||||
conjunto de alcances solicitado por el llamador sigue siendo el autoritativo; los alcances en caché solo
|
||||
se reutilizan cuando el cliente está reutilizando el token por dispositivo almacenado.
|
||||
- Los tokens de dispositivo se pueden rotar/revocar mediante `device.token.rotate` y
|
||||
`device.token.revoke` (requiere el alcance `operator.pairing`).
|
||||
- La emisión/rotación de tokens sigue limitada al conjunto de roles aprobados registrado en
|
||||
la entrada de emparejamiento de ese dispositivo; rotar un token no puede expandir el dispositivo a un
|
||||
conjunto de alcances solicitado por el llamador sigue siendo autoritativo; los alcances en caché solo
|
||||
se reutilizan cuando el cliente está reutilizando el token almacenado por dispositivo.
|
||||
- Los tokens de dispositivo pueden rotarse/revocarse mediante `device.token.rotate` y
|
||||
`device.token.revoke` (requiere alcance `operator.pairing`).
|
||||
- La emisión/rotación de tokens se mantiene limitada al conjunto de roles aprobado registrado en
|
||||
la entrada de emparejamiento de ese dispositivo; rotar un token no puede ampliar el dispositivo a un
|
||||
rol que la aprobación de emparejamiento nunca concedió.
|
||||
- Para las sesiones de tokens de dispositivos emparejados, la administración del dispositivo tiene alcance propio salvo que el
|
||||
llamador también tenga `operator.admin`: los llamadores que no son administradores solo pueden eliminar/revocar/rotar
|
||||
- Para sesiones de token de dispositivo emparejado, la administración del dispositivo está autocontenida salvo que el
|
||||
llamador también tenga `operator.admin`: quienes no son administradores solo pueden quitar/revocar/rotar
|
||||
su **propia** entrada de dispositivo.
|
||||
- `device.token.rotate` también comprueba el conjunto solicitado de alcances de operador frente a los
|
||||
alcances actuales de la sesión del llamador. Los llamadores que no son administradores no pueden rotar un token a
|
||||
un conjunto más amplio de alcances de operador que el que ya poseen.
|
||||
- Los fallos de autenticación incluyen `error.details.code` además de sugerencias de recuperación:
|
||||
- `device.token.rotate` también verifica el conjunto solicitado de alcances de operador frente a los
|
||||
alcances de la sesión actual del llamador. Quienes no son administradores no pueden rotar un token a
|
||||
un conjunto de alcances de operador más amplio del que ya tienen.
|
||||
- Los fallos de autenticación incluyen `error.details.code` más sugerencias de recuperación:
|
||||
- `error.details.canRetryWithDeviceToken` (booleano)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- Comportamiento del cliente para `AUTH_TOKEN_MISMATCH`:
|
||||
- Los clientes confiables pueden intentar un reintento limitado con un token por dispositivo en caché.
|
||||
- Si ese reintento falla, los clientes deben detener los bucles automáticos de reconexión y mostrar orientación para que el operador actúe.
|
||||
- Los clientes confiables pueden intentar un reintento acotado con un token almacenado por dispositivo.
|
||||
- Si ese reintento falla, los clientes deben detener los bucles automáticos de reconexión y mostrar orientación de acción al operador.
|
||||
|
||||
## Identidad del dispositivo + emparejamiento
|
||||
|
||||
- Los nodos deben incluir una identidad estable de dispositivo (`device.id`) derivada de una
|
||||
huella digital de par de claves.
|
||||
- Los Gateways emiten tokens por dispositivo + rol.
|
||||
- Las aprobaciones de emparejamiento son necesarias para nuevos ID de dispositivo, salvo que la aprobación automática local
|
||||
- Los nodos deben incluir una identidad de dispositivo estable (`device.id`) derivada de la huella digital
|
||||
de un par de claves.
|
||||
- Los gateways emiten tokens por dispositivo + rol.
|
||||
- Las aprobaciones de emparejamiento son necesarias para nuevos ID de dispositivo, a menos que la aprobación automática local
|
||||
esté habilitada.
|
||||
- La aprobación automática de emparejamiento se centra en conexiones directas locales por loopback.
|
||||
- OpenClaw también tiene una ruta estrecha de autoconexión local de backend/contenedor para
|
||||
flujos helper confiables con secreto compartido.
|
||||
- Las conexiones tailnet o LAN del mismo host siguen tratándose como remotas para el emparejamiento y
|
||||
- La aprobación automática de emparejamiento se centra en conexiones directas de loopback local.
|
||||
- OpenClaw también tiene una ruta estrecha de autoconexión local al backend/contenedor para
|
||||
flujos auxiliares confiables con secreto compartido.
|
||||
- Las conexiones tailnet o LAN del mismo host se siguen tratando como remotas para el emparejamiento y
|
||||
requieren aprobación.
|
||||
- Todos los clientes WS deben incluir identidad `device` durante `connect` (operator + node).
|
||||
- Todos los clientes WS deben incluir identidad `device` durante `connect` (`operator` + `node`).
|
||||
Control UI puede omitirla solo en estos modos:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` para compatibilidad con HTTP inseguro solo en localhost.
|
||||
- autenticación satisfactoria de operator de Control UI con `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (medida de emergencia, degradación grave de seguridad).
|
||||
- autenticación exitosa de Control UI de operador con `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (medida extrema, degradación grave de seguridad).
|
||||
- Todas las conexiones deben firmar el nonce `connect.challenge` proporcionado por el servidor.
|
||||
|
||||
### Diagnósticos de migración de autenticación del dispositivo
|
||||
### Diagnósticos de migración de autenticación de dispositivo
|
||||
|
||||
Para clientes heredados que siguen usando el comportamiento de firma previo al desafío, `connect` ahora devuelve
|
||||
Para clientes heredados que todavía usan el comportamiento de firma previo al desafío, `connect` ahora devuelve
|
||||
códigos de detalle `DEVICE_AUTH_*` en `error.details.code` con un `error.details.reason` estable.
|
||||
|
||||
Fallos comunes de migración:
|
||||
|
||||
| Mensaje | details.code | details.reason | Significado |
|
||||
| Message | details.code | details.reason | Meaning |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | El cliente omitió `device.nonce` (o lo envió vacío). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | El cliente firmó con un nonce obsoleto/incorrecto. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La carga útil de la firma no coincide con la carga útil v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | La marca de tiempo firmada está fuera de la desviación permitida. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` no coincide con la huella de la clave pública. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Falló el formato/canonización de la clave pública. |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | El cliente omitió `device.nonce` (o lo envió vacío). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | El cliente firmó con un nonce obsoleto o incorrecto. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | La carga útil de la firma no coincide con la carga útil v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | La marca de tiempo firmada está fuera del desfase permitido. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` no coincide con la huella digital de la clave pública. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | El formato/canonicalización de la clave pública falló. |
|
||||
|
||||
Objetivo de la migración:
|
||||
|
||||
@ -641,16 +652,16 @@ Objetivo de la migración:
|
||||
- La carga útil de firma preferida es `v3`, que vincula `platform` y `deviceFamily`
|
||||
además de los campos de dispositivo/cliente/rol/alcances/token/nonce.
|
||||
- Las firmas heredadas `v2` siguen aceptándose por compatibilidad, pero la fijación de metadatos
|
||||
de dispositivos emparejados sigue controlando la política de comandos al reconectar.
|
||||
de dispositivos emparejados sigue controlando la política de comandos al reconectarse.
|
||||
|
||||
## TLS + fijación
|
||||
|
||||
- TLS es compatible con conexiones WS.
|
||||
- Los clientes pueden fijar opcionalmente la huella digital del certificado del Gateway (véase la configuración `gateway.tls`
|
||||
además de `gateway.remote.tlsFingerprint` o la CLI `--tls-fingerprint`).
|
||||
- Los clientes pueden fijar opcionalmente la huella digital del certificado del gateway (consulte la configuración `gateway.tls`
|
||||
más `gateway.remote.tlsFingerprint` o la CLI `--tls-fingerprint`).
|
||||
|
||||
## Alcance
|
||||
|
||||
Este protocolo expone la **API completa del Gateway** (estado, canales, modelos, chat,
|
||||
Este protocolo expone la **API completa del gateway** (estado, canales, modelos, chat,
|
||||
agente, sesiones, nodos, aprobaciones, etc.). La superficie exacta está definida por los
|
||||
esquemas TypeBox en `src/gateway/protocol/schema.ts`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,76 +1,76 @@
|
||||
---
|
||||
read_when:
|
||||
- Implementando funciones de la app de macOS
|
||||
- Cambiando el ciclo de vida del gateway o el puente de nodos en macOS
|
||||
summary: App complementaria de OpenClaw para macOS (barra de menús + broker del gateway)
|
||||
title: App de macOS
|
||||
- Implementación de funciones de la aplicación para macOS
|
||||
- Cambio del ciclo de vida del Gateway o del puenteo de nodos en macOS
|
||||
summary: Aplicación complementaria de OpenClaw para macOS (barra de menús + intermediario del Gateway)
|
||||
title: Aplicación para macOS
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:49:00Z"
|
||||
generated_at: "2026-04-18T04:59:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135
|
||||
source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0
|
||||
source_path: platforms/macos.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Complemento de OpenClaw para macOS (barra de menús + broker del gateway)
|
||||
# Complemento de OpenClaw para macOS (barra de menús + intermediario del Gateway)
|
||||
|
||||
La app de macOS es el **complemento de barra de menús** de OpenClaw. Gestiona permisos,
|
||||
administra/se conecta al Gateway localmente (launchd o manual) y expone capacidades
|
||||
de macOS al agente como un nodo.
|
||||
La aplicación de macOS es el **complemento de barra de menús** para OpenClaw. Se encarga de los permisos,
|
||||
administra/se conecta al Gateway localmente (launchd o manual) y expone capacidades de macOS
|
||||
al agente como un Node.
|
||||
|
||||
## Qué hace
|
||||
|
||||
- Muestra notificaciones nativas y estado en la barra de menús.
|
||||
- Gestiona los prompts de TCC (Notificaciones, Accesibilidad, Grabación de Pantalla, Micrófono,
|
||||
Reconocimiento de Voz, Automatización/AppleScript).
|
||||
- Gestiona los avisos de TCC (Notificaciones, Accesibilidad, Grabación de pantalla, Micrófono,
|
||||
Reconocimiento de voz, Automatización/AppleScript).
|
||||
- Ejecuta o se conecta al Gateway (local o remoto).
|
||||
- Expone herramientas exclusivas de macOS (Canvas, Cámara, Grabación de Pantalla, `system.run`).
|
||||
- Inicia el servicio local de node host en modo **remoto** (launchd), y lo detiene en modo **local**.
|
||||
- Opcionalmente aloja **PeekabooBridge** para automatización de UI.
|
||||
- Instala la CLI global (`openclaw`) bajo demanda mediante npm, pnpm o bun (la app prefiere npm, luego pnpm y después bun; Node sigue siendo el tiempo de ejecución recomendado para el Gateway).
|
||||
- Expone herramientas exclusivas de macOS (Canvas, Camera, Screen Recording, `system.run`).
|
||||
- Inicia el servicio local del host de Node en modo **remoto** (launchd) y lo detiene en modo **local**.
|
||||
- Puede alojar opcionalmente **PeekabooBridge** para automatización de UI.
|
||||
- Instala la CLI global (`openclaw`) a pedido mediante npm, pnpm o bun (la aplicación prefiere npm, luego pnpm y luego bun; Node sigue siendo el entorno de ejecución recomendado para Gateway).
|
||||
|
||||
## Modo local vs remoto
|
||||
## Modo local vs. remoto
|
||||
|
||||
- **Local** (predeterminado): la app se conecta a un Gateway local ya en ejecución si existe;
|
||||
en caso contrario habilita el servicio launchd mediante `openclaw gateway install`.
|
||||
- **Remoto**: la app se conecta a un Gateway por SSH/Tailscale y nunca inicia
|
||||
- **Local** (predeterminado): la aplicación se conecta a un Gateway local en ejecución si existe;
|
||||
de lo contrario, habilita el servicio launchd mediante `openclaw gateway install`.
|
||||
- **Remoto**: la aplicación se conecta a un Gateway a través de SSH/Tailscale y nunca inicia
|
||||
un proceso local.
|
||||
La app inicia el **servicio local de node host** para que el Gateway remoto pueda alcanzar este Mac.
|
||||
La app no inicia el Gateway como proceso hijo.
|
||||
El descubrimiento del Gateway ahora prefiere nombres MagicDNS de Tailscale frente a IP tailnet sin procesar,
|
||||
de modo que la app de Mac se recupera con más fiabilidad cuando cambian las IP tailnet.
|
||||
La aplicación inicia el **servicio local del host de Node** para que el Gateway remoto pueda acceder a esta Mac.
|
||||
La aplicación no genera el Gateway como un proceso hijo.
|
||||
La detección del Gateway ahora prioriza los nombres MagicDNS de Tailscale sobre las IP sin procesar de la tailnet,
|
||||
por lo que la aplicación para Mac se recupera de forma más confiable cuando cambian las IP de la tailnet.
|
||||
|
||||
## Control de launchd
|
||||
|
||||
La app gestiona un LaunchAgent por usuario con la etiqueta `ai.openclaw.gateway`
|
||||
(o `ai.openclaw.<profile>` al usar `--profile`/`OPENCLAW_PROFILE`; el heredado `com.openclaw.*` sigue descargándose).
|
||||
La aplicación administra un LaunchAgent por usuario con la etiqueta `ai.openclaw.gateway`
|
||||
(o `ai.openclaw.<profile>` cuando se usa `--profile`/`OPENCLAW_PROFILE`; el legado `com.openclaw.*` todavía se descarga).
|
||||
|
||||
```bash
|
||||
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
|
||||
launchctl bootout gui/$UID/ai.openclaw.gateway
|
||||
```
|
||||
|
||||
Sustituye la etiqueta por `ai.openclaw.<profile>` cuando ejecutes un profile con nombre.
|
||||
Reemplaza la etiqueta por `ai.openclaw.<profile>` cuando ejecutes un perfil con nombre.
|
||||
|
||||
Si el LaunchAgent no está instalado, actívalo desde la app o ejecuta
|
||||
Si el LaunchAgent no está instalado, habilítalo desde la aplicación o ejecuta
|
||||
`openclaw gateway install`.
|
||||
|
||||
## Capacidades del nodo (mac)
|
||||
## Capacidades del Node (mac)
|
||||
|
||||
La app de macOS se presenta como un nodo. Comandos habituales:
|
||||
La aplicación de macOS se presenta como un Node. Comandos comunes:
|
||||
|
||||
- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
|
||||
- Cámara: `camera.snap`, `camera.clip`
|
||||
- Pantalla: `screen.record`
|
||||
- Camera: `camera.snap`, `camera.clip`
|
||||
- Pantalla: `screen.snapshot`, `screen.record`
|
||||
- Sistema: `system.run`, `system.notify`
|
||||
|
||||
El nodo informa un mapa `permissions` para que los agentes puedan decidir qué está permitido.
|
||||
El Node informa un mapa `permissions` para que los agentes puedan decidir qué está permitido.
|
||||
|
||||
Servicio de nodo + IPC de la app:
|
||||
Servicio de Node + IPC de la aplicación:
|
||||
|
||||
- Cuando el servicio headless de node host está en ejecución (modo remoto), se conecta al WS del Gateway como un nodo.
|
||||
- `system.run` se ejecuta en la app de macOS (contexto UI/TCC) mediante un socket Unix local; los prompts y la salida permanecen en la app.
|
||||
- Cuando el servicio sin interfaz del host de Node está en ejecución (modo remoto), se conecta al Gateway WS como un Node.
|
||||
- `system.run` se ejecuta en la aplicación de macOS (contexto UI/TCC) a través de un socket Unix local; los avisos y la salida permanecen dentro de la aplicación.
|
||||
|
||||
Diagrama (SCI):
|
||||
|
||||
@ -81,10 +81,10 @@ Gateway -> Node Service (WS)
|
||||
Mac App (UI + TCC + system.run)
|
||||
```
|
||||
|
||||
## Aprobaciones de exec (`system.run`)
|
||||
## Aprobaciones de ejecución (`system.run`)
|
||||
|
||||
`system.run` está controlado por **Exec approvals** en la app de macOS (Settings → Exec approvals).
|
||||
Security + ask + allowlist se almacenan localmente en el Mac en:
|
||||
`system.run` está controlado por las **aprobaciones de ejecución** en la aplicación de macOS (Ajustes → Aprobaciones de ejecución).
|
||||
La seguridad + solicitud + lista de permitidos se almacenan localmente en la Mac en:
|
||||
|
||||
```
|
||||
~/.openclaw/exec-approvals.json
|
||||
@ -112,15 +112,15 @@ Ejemplo:
|
||||
Notas:
|
||||
|
||||
- Las entradas de `allowlist` son patrones glob para rutas resueltas de binarios.
|
||||
- El texto bruto del comando de shell que contiene sintaxis de control o expansión del shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) se trata como un fallo de allowlist y requiere aprobación explícita (o incluir el binario del shell en la allowlist).
|
||||
- Elegir “Always Allow” en el prompt agrega ese comando a la allowlist.
|
||||
- Las sobrescrituras del entorno en `system.run` se filtran (elimina `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) y luego se fusionan con el entorno de la app.
|
||||
- Para wrappers de shell (`bash|sh|zsh ... -c/-lc`), las sobrescrituras del entorno con alcance de solicitud se reducen a una pequeña allowlist explícita (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
- Para decisiones de permitir siempre en modo allowlist, los wrappers de despacho conocidos (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persisten rutas internas del ejecutable en lugar de rutas del wrapper. Si el desempaquetado no es seguro, no se persiste automáticamente ninguna entrada de allowlist.
|
||||
- El texto de comandos de shell sin procesar que contiene sintaxis de control o expansión del shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) se trata como una ausencia en la lista de permitidos y requiere aprobación explícita (o añadir el binario del shell a la lista de permitidos).
|
||||
- Elegir “Permitir siempre” en el aviso añade ese comando a la lista de permitidos.
|
||||
- Las anulaciones de entorno de `system.run` se filtran (elimina `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) y luego se fusionan con el entorno de la aplicación.
|
||||
- Para envoltorios de shell (`bash|sh|zsh ... -c/-lc`), las anulaciones de entorno con alcance de solicitud se reducen a una pequeña lista de permitidos explícita (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
- Para decisiones de permitir siempre en modo de lista de permitidos, los envoltorios de despacho conocidos (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) conservan las rutas del ejecutable interno en lugar de las rutas del envoltorio. Si desenvolverlo no es seguro, no se conserva automáticamente ninguna entrada en la lista de permitidos.
|
||||
|
||||
## Deep links
|
||||
## Enlaces profundos
|
||||
|
||||
La app registra el esquema de URL `openclaw://` para acciones locales.
|
||||
La aplicación registra el esquema de URL `openclaw://` para acciones locales.
|
||||
|
||||
### `openclaw://agent`
|
||||
|
||||
@ -133,90 +133,90 @@ Parámetros de consulta:
|
||||
- `thinking` (opcional)
|
||||
- `deliver` / `to` / `channel` (opcional)
|
||||
- `timeoutSeconds` (opcional)
|
||||
- `key` (opcional, clave de modo unattended)
|
||||
- `key` (opcional, clave para modo no supervisado)
|
||||
|
||||
Seguridad:
|
||||
|
||||
- Sin `key`, la app solicita confirmación.
|
||||
- Sin `key`, la app aplica un límite corto de mensaje para el prompt de confirmación e ignora `deliver` / `to` / `channel`.
|
||||
- Con una `key` válida, la ejecución es unattended (pensado para automatizaciones personales).
|
||||
- Sin `key`, la aplicación solicita confirmación.
|
||||
- Sin `key`, la aplicación aplica un límite corto al mensaje para el aviso de confirmación e ignora `deliver` / `to` / `channel`.
|
||||
- Con una `key` válida, la ejecución no es supervisada (pensado para automatizaciones personales).
|
||||
|
||||
## Flujo de onboarding (típico)
|
||||
## Flujo de incorporación (típico)
|
||||
|
||||
1. Instala e inicia **OpenClaw.app**.
|
||||
2. Completa la lista de comprobación de permisos (prompts de TCC).
|
||||
3. Asegúrate de que el modo **Local** esté activo y el Gateway esté en ejecución.
|
||||
4. Instala la CLI si quieres acceso desde terminal.
|
||||
1. Instala y abre **OpenClaw.app**.
|
||||
2. Completa la lista de comprobación de permisos (avisos de TCC).
|
||||
3. Asegúrate de que el modo **Local** esté activo y de que el Gateway esté en ejecución.
|
||||
4. Instala la CLI si quieres acceso desde la terminal.
|
||||
|
||||
## Ubicación del directorio de state (macOS)
|
||||
## Ubicación del directorio de estado (macOS)
|
||||
|
||||
Evita poner tu directorio de state de OpenClaw en iCloud u otras carpetas sincronizadas con la nube.
|
||||
Las rutas respaldadas por sincronización pueden añadir latencia y ocasionalmente provocar carreras de bloqueo/sincronización de archivos para
|
||||
Evita colocar el directorio de estado de OpenClaw en iCloud u otras carpetas sincronizadas con la nube.
|
||||
Las rutas respaldadas por sincronización pueden añadir latencia y, ocasionalmente, provocar condiciones de carrera de bloqueo/sincronización de archivos para
|
||||
sesiones y credenciales.
|
||||
|
||||
Prefiere una ruta local no sincronizada como:
|
||||
Prefiere una ruta de estado local no sincronizada, como:
|
||||
__OC_I18N_900005__
|
||||
Si `openclaw doctor` detecta state bajo:
|
||||
Si `openclaw doctor` detecta el estado en:
|
||||
|
||||
- `~/Library/Mobile Documents/com~apple~CloudDocs/...`
|
||||
- `~/Library/CloudStorage/...`
|
||||
|
||||
advertirá y recomendará volver a una ruta local.
|
||||
mostrará una advertencia y recomendará volver a una ruta local.
|
||||
|
||||
## Flujo de compilación y desarrollo (nativo)
|
||||
|
||||
- `cd apps/macos && swift build`
|
||||
- `swift run OpenClaw` (o Xcode)
|
||||
- Empaquetar la app: `scripts/package-mac-app.sh`
|
||||
- Empaquetar la aplicación: `scripts/package-mac-app.sh`
|
||||
|
||||
## Depurar conectividad con el gateway (CLI de macOS)
|
||||
## Depurar la conectividad del Gateway (CLI de macOS)
|
||||
|
||||
Usa la CLI de depuración para ejercitar el mismo handshake WebSocket y la lógica de descubrimiento del Gateway
|
||||
que usa la app de macOS, sin iniciar la app.
|
||||
Usa la CLI de depuración para probar el mismo protocolo de enlace WebSocket del Gateway y la misma lógica de detección
|
||||
que usa la aplicación de macOS, sin abrir la aplicación.
|
||||
__OC_I18N_900006__
|
||||
Opciones de conexión:
|
||||
|
||||
- `--url <ws://host:port>`: sobrescribe la configuración
|
||||
- `--mode <local|remote>`: resuelve desde la configuración (predeterminado: configuración o local)
|
||||
- `--probe`: fuerza una sonda nueva de estado
|
||||
- `--url <ws://host:port>`: anula la configuración
|
||||
- `--mode <local|remote>`: resuelve desde la configuración (predeterminado: config o local)
|
||||
- `--probe`: fuerza una nueva comprobación de estado
|
||||
- `--timeout <ms>`: tiempo de espera de la solicitud (predeterminado: `15000`)
|
||||
- `--json`: salida estructurada para comparar diferencias
|
||||
|
||||
Opciones de descubrimiento:
|
||||
Opciones de detección:
|
||||
|
||||
- `--include-local`: incluye gateways que normalmente se filtrarían como “local”
|
||||
- `--timeout <ms>`: ventana total de descubrimiento (predeterminado: `2000`)
|
||||
- `--include-local`: incluye Gateways que se filtrarían como “locales”
|
||||
- `--timeout <ms>`: ventana total de detección (predeterminada: `2000`)
|
||||
- `--json`: salida estructurada para comparar diferencias
|
||||
|
||||
Consejo: compáralo con `openclaw gateway discover --json` para ver si la
|
||||
canalización de descubrimiento de la app de macOS (`local.` más el dominio amplio configurado, con
|
||||
respaldo de wide-area y Tailscale Serve) difiere del descubrimiento basado en `dns-sd`
|
||||
de la CLI de Node.
|
||||
canalización de detección de la aplicación de macOS (`local.` más el dominio de área amplia configurado, con
|
||||
área amplia y Tailscale Serve como alternativas)
|
||||
difiere de la detección basada en `dns-sd` de la CLI de Node.
|
||||
|
||||
## Infraestructura de conexión remota (túneles SSH)
|
||||
|
||||
Cuando la app de macOS se ejecuta en modo **remoto**, abre un túnel SSH para que los componentes de UI locales
|
||||
puedan comunicarse con un Gateway remoto como si estuviera en localhost.
|
||||
Cuando la aplicación de macOS se ejecuta en modo **Remoto**, abre un túnel SSH para que los componentes
|
||||
de UI locales puedan comunicarse con un Gateway remoto como si estuviera en localhost.
|
||||
|
||||
### Túnel de control (puerto WebSocket del Gateway)
|
||||
|
||||
- **Propósito:** comprobaciones de estado, status, Web Chat, configuración y otras llamadas del plano de control.
|
||||
- **Propósito:** comprobaciones de estado, estado, Web Chat, configuración y otras llamadas del plano de control.
|
||||
- **Puerto local:** el puerto del Gateway (predeterminado `18789`), siempre estable.
|
||||
- **Puerto remoto:** el mismo puerto del Gateway en el host remoto.
|
||||
- **Comportamiento:** no hay puerto local aleatorio; la app reutiliza un túnel saludable existente
|
||||
- **Comportamiento:** no se usa un puerto local aleatorio; la aplicación reutiliza un túnel saludable existente
|
||||
o lo reinicia si es necesario.
|
||||
- **Forma de SSH:** `ssh -N -L <local>:127.0.0.1:<remote>` con opciones BatchMode +
|
||||
ExitOnForwardFailure + keepalive.
|
||||
- **Informe de IP:** el túnel SSH usa loopback, así que el gateway verá la
|
||||
IP del nodo como `127.0.0.1`. Usa transporte **Direct (ws/wss)** si quieres que aparezca la IP
|
||||
real del cliente (consulta [acceso remoto en macOS](/platforms/mac/remote)).
|
||||
- **Informe de IP:** el túnel SSH usa loopback, por lo que el gateway verá la IP del node
|
||||
como `127.0.0.1`. Usa el transporte **Direct (ws/wss)** si quieres que aparezca la IP real
|
||||
del cliente (consulta [acceso remoto en macOS](/es/platforms/mac/remote)).
|
||||
|
||||
Para los pasos de configuración, consulta [acceso remoto en macOS](/platforms/mac/remote). Para
|
||||
detalles del protocolo, consulta [Gateway protocol](/gateway/protocol).
|
||||
Para ver los pasos de configuración, consulta [acceso remoto en macOS](/es/platforms/mac/remote). Para detalles
|
||||
del protocolo, consulta [protocolo del Gateway](/es/gateway/protocol).
|
||||
|
||||
## Documentación relacionada
|
||||
|
||||
- [Gateway runbook](/gateway)
|
||||
- [Gateway (macOS)](/platforms/mac/bundled-gateway)
|
||||
- [permisos de macOS](/platforms/mac/permissions)
|
||||
- [Canvas](/platforms/mac/canvas)
|
||||
- [Guía operativa del Gateway](/es/gateway)
|
||||
- [Gateway (macOS)](/es/platforms/mac/bundled-gateway)
|
||||
- [Permisos de macOS](/es/platforms/mac/permissions)
|
||||
- [Canvas](/es/platforms/mac/canvas)
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Está creando un nuevo Plugin de canal de mensajería.
|
||||
- Quiere conectar OpenClaw a una plataforma de mensajería.
|
||||
- Necesita comprender la superficie del adaptador `ChannelPlugin`.
|
||||
- Estás creando un nuevo Plugin de canal de mensajería
|
||||
- Quieres conectar OpenClaw a una plataforma de mensajería
|
||||
- Necesitas comprender la superficie del adaptador `ChannelPlugin`
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: Guía paso a paso para crear un Plugin de canal de mensajería para OpenClaw
|
||||
title: Crear Plugins de canal
|
||||
title: Creación de Plugins de canal
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T19:41:53Z"
|
||||
generated_at: "2026-04-18T04:59:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
|
||||
source_hash: 3dda53c969bc7356a450c2a5bf49fb82bf1283c23e301dec832d8724b11e724b
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Crear Plugins de canal
|
||||
# Creación de Plugins de canal
|
||||
|
||||
Esta guía recorre la creación de un Plugin de canal que conecta OpenClaw a una
|
||||
plataforma de mensajería. Al final tendrá un canal funcional con seguridad en MD,
|
||||
Esta guía recorre la creación de un Plugin de canal que conecta OpenClaw con una
|
||||
plataforma de mensajería. Al final tendrás un canal funcional con seguridad en MD,
|
||||
emparejamiento, encadenamiento de respuestas y mensajería saliente.
|
||||
|
||||
<Info>
|
||||
Si todavía no ha creado ningún Plugin de OpenClaw, lea primero
|
||||
Si todavía no has creado ningún Plugin de OpenClaw, lee primero
|
||||
[Primeros pasos](/es/plugins/building-plugins) para conocer la estructura básica
|
||||
del paquete y la configuración del manifiesto.
|
||||
</Info>
|
||||
@ -30,85 +30,84 @@ emparejamiento, encadenamiento de respuestas y mensajería saliente.
|
||||
## Cómo funcionan los Plugins de canal
|
||||
|
||||
Los Plugins de canal no necesitan sus propias herramientas de enviar/editar/reaccionar. OpenClaw mantiene una
|
||||
herramienta `message` compartida en el núcleo. Su Plugin es responsable de:
|
||||
única herramienta `message` compartida en el núcleo. Tu Plugin gestiona:
|
||||
|
||||
- **Configuración** — resolución de cuentas y asistente de configuración
|
||||
- **Seguridad** — política de MD y listas de permitidos
|
||||
- **Emparejamiento** — flujo de aprobación de MD
|
||||
- **Gramática de sesión** — cómo los identificadores de conversación específicos del proveedor se asignan a chats base, identificadores de hilo y alternativas del elemento superior
|
||||
- **Salida** — envío de texto, medios y encuestas a la plataforma
|
||||
- **Gramática de sesión** — cómo los id. de conversación específicos del proveedor se asignan a chats base, id. de hilo y alternativas de respaldo de padre
|
||||
- **Salida** — envío de texto, contenido multimedia y encuestas a la plataforma
|
||||
- **Encadenamiento** — cómo se encadenan las respuestas
|
||||
|
||||
El núcleo es responsable de la herramienta de mensajes compartida, el cableado del prompt, la forma externa de la clave de sesión,
|
||||
la contabilidad genérica `:thread:` y el despacho.
|
||||
El núcleo gestiona la herramienta compartida de mensajes, la conexión del prompt, la forma externa de la clave de sesión,
|
||||
la contabilidad genérica de `:thread:` y el despacho.
|
||||
|
||||
Si su canal agrega parámetros a la herramienta de mensajes que transportan fuentes de medios, exponga esos
|
||||
Si tu canal añade parámetros a la herramienta de mensajes que transportan fuentes multimedia, expón esos
|
||||
nombres de parámetros mediante `describeMessageTool(...).mediaSourceParams`. El núcleo usa
|
||||
esa lista explícita para la normalización de rutas del sandbox y la política de acceso a medios salientes,
|
||||
por lo que los Plugins no necesitan casos especiales en el núcleo compartido para parámetros específicos del proveedor
|
||||
como avatar, adjunto o imagen de portada.
|
||||
Prefiera devolver un mapa indexado por acción, como
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }`, para que acciones no relacionadas no
|
||||
hereden los argumentos de medios de otra acción. Un arreglo plano también funciona para parámetros que
|
||||
así que los Plugins no necesitan casos especiales en el núcleo compartido para parámetros específicos del proveedor como
|
||||
avatar, adjunto o imagen de portada.
|
||||
Prefiere devolver un mapa por acción como
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }` para que acciones no relacionadas no
|
||||
hereden los argumentos multimedia de otra acción. Un arreglo plano sigue funcionando para parámetros que
|
||||
se comparten intencionalmente entre todas las acciones expuestas.
|
||||
|
||||
Si su plataforma almacena alcance adicional dentro de los identificadores de conversación, mantenga ese análisis
|
||||
en el Plugin con `messaging.resolveSessionConversation(...)`. Ese es el gancho canónico para asignar
|
||||
`rawId` al identificador de conversación base, identificador de hilo opcional,
|
||||
`baseConversationId` explícito y cualquier `parentConversationCandidates`.
|
||||
Cuando devuelva `parentConversationCandidates`, manténgalos ordenados desde el
|
||||
elemento superior más específico hasta la conversación base o más amplia.
|
||||
Si tu plataforma almacena alcance adicional dentro de los id. de conversación, mantén ese análisis
|
||||
en el Plugin con `messaging.resolveSessionConversation(...)`. Ese es el hook canónico para mapear
|
||||
`rawId` al id. base de conversación, id. opcional de hilo, `baseConversationId`
|
||||
explícito y cualquier `parentConversationCandidates`.
|
||||
Cuando devuelvas `parentConversationCandidates`, mantenlos ordenados desde el
|
||||
padre más específico hasta la conversación base más amplia.
|
||||
|
||||
Los Plugins incluidos que necesitan el mismo análisis antes de que se inicie el registro de canales
|
||||
también pueden exponer un archivo `session-key-api.ts` de nivel superior con una exportación
|
||||
`resolveSessionConversation(...)` coincidente. El núcleo usa esa superficie segura para el arranque
|
||||
`resolveSessionConversation(...)` equivalente. El núcleo usa esa superficie segura para el arranque
|
||||
solo cuando el registro de Plugins en tiempo de ejecución todavía no está disponible.
|
||||
|
||||
`messaging.resolveParentConversationCandidates(...)` sigue disponible como una
|
||||
alternativa heredada de compatibilidad cuando un Plugin solo necesita alternativas del elemento superior
|
||||
además del identificador genérico o sin procesar. Si existen ambos ganchos, el núcleo usa primero
|
||||
`resolveSessionConversation(...).parentConversationCandidates` y solo recurre a
|
||||
`resolveParentConversationCandidates(...)` cuando el gancho canónico
|
||||
`messaging.resolveParentConversationCandidates(...)` sigue disponible como alternativa heredada de compatibilidad
|
||||
cuando un Plugin solo necesita padres alternativos además del id. genérico/sin procesar. Si existen ambos hooks, el núcleo usa
|
||||
primero `resolveSessionConversation(...).parentConversationCandidates` y solo
|
||||
recurre a `resolveParentConversationCandidates(...)` cuando el hook canónico
|
||||
los omite.
|
||||
|
||||
## Aprobaciones y capacidades del canal
|
||||
|
||||
La mayoría de los Plugins de canal no necesitan código específico de aprobaciones.
|
||||
La mayoría de los Plugins de canal no necesitan código específico para aprobaciones.
|
||||
|
||||
- El núcleo es responsable de `/approve` en el mismo chat, de las cargas útiles compartidas de botones de aprobación y de la entrega genérica de respaldo.
|
||||
- Prefiera un solo objeto `approvalCapability` en el Plugin del canal cuando el canal necesite comportamiento específico de aprobación.
|
||||
- `ChannelPlugin.approvals` se eliminó. Coloque los datos de entrega/aprobación nativa/renderizado/autenticación en `approvalCapability`.
|
||||
- `plugin.auth` es solo para login/logout; el núcleo ya no lee ganchos de autenticación de aprobación desde ese objeto.
|
||||
- `approvalCapability.authorizeActorAction` y `approvalCapability.getActionAvailabilityState` son la unión canónica para autenticación de aprobación.
|
||||
- Use `approvalCapability.getActionAvailabilityState` para la disponibilidad de autenticación de aprobación en el mismo chat.
|
||||
- Si su canal expone aprobaciones nativas de ejecución, use `approvalCapability.getExecInitiatingSurfaceState` para el estado de la superficie iniciadora/cliente nativo cuando difiera de la autenticación de aprobación en el mismo chat. El núcleo usa ese gancho específico de ejecución para distinguir `enabled` frente a `disabled`, decidir si el canal iniciador admite aprobaciones nativas de ejecución e incluir el canal en la guía de respaldo del cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` completa esto para el caso común.
|
||||
- Use `outbound.shouldSuppressLocalPayloadPrompt` o `outbound.beforeDeliverPayload` para el comportamiento específico del canal en el ciclo de vida de la carga útil, como ocultar prompts locales de aprobación duplicados o enviar indicadores de escritura antes de la entrega.
|
||||
- Use `approvalCapability.delivery` solo para el enrutamiento de aprobaciones nativas o la supresión de respaldo.
|
||||
- Use `approvalCapability.nativeRuntime` para datos de aprobación nativa que pertenezcan al canal. Manténgalo diferido en puntos de entrada críticos del canal con `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que puede importar su módulo de tiempo de ejecución bajo demanda y aun así permitir que el núcleo ensamble el ciclo de vida de aprobación.
|
||||
- Use `approvalCapability.render` solo cuando un canal realmente necesite cargas útiles de aprobación personalizadas en lugar del renderizador compartido.
|
||||
- Use `approvalCapability.describeExecApprovalSetup` cuando el canal quiera que la respuesta de ruta deshabilitada explique los ajustes exactos de configuración necesarios para habilitar aprobaciones nativas de ejecución. El gancho recibe `{ channel, channelLabel, accountId }`; los canales con cuentas con nombre deben renderizar rutas con alcance por cuenta, como `channels.<channel>.accounts.<id>.execApprovals.*`, en lugar de valores predeterminados de nivel superior.
|
||||
- Si un canal puede inferir identidades estables tipo propietario en MD a partir de la configuración existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` en el mismo chat sin agregar lógica específica de aprobación en el núcleo.
|
||||
- Si un canal necesita entrega de aprobación nativa, mantenga el código del canal enfocado en la normalización del destino más los datos de transporte/presentación. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` y `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque los datos específicos del canal detrás de `approvalCapability.nativeRuntime`, idealmente mediante `createChannelApprovalNativeRuntimeAdapter(...)` o `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que el núcleo pueda ensamblar el controlador y encargarse del filtrado de solicitudes, enrutamiento, deduplicación, expiración, suscripción al Gateway y avisos de redirección. `nativeRuntime` se divide en algunas uniones más pequeñas:
|
||||
- `availability` — si la cuenta está configurada y si se debe manejar una solicitud
|
||||
- `presentation` — asigna el modelo de vista de aprobación compartido a cargas útiles nativas pendientes/resueltas/expiradas o acciones finales
|
||||
- `transport` — prepara destinos y envía/actualiza/elimina mensajes de aprobación nativa
|
||||
- `interactions` — ganchos opcionales de asociar/desasociar/borrar acción para botones o reacciones nativos
|
||||
- `observe` — ganchos opcionales de diagnóstico de entrega
|
||||
- Si el canal necesita objetos que pertenecen al tiempo de ejecución, como un cliente, token, app Bolt o receptor de Webhook, regístrelos mediante `openclaw/plugin-sdk/channel-runtime-context`. El registro genérico de contexto de tiempo de ejecución permite que el núcleo inicialice controladores impulsados por capacidades a partir del estado de inicio del canal sin agregar lógica de envoltura específica de aprobación.
|
||||
- Recurra a `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` de nivel inferior solo cuando la unión guiada por capacidades todavía no sea lo bastante expresiva.
|
||||
- Los canales de aprobación nativa deben enrutar tanto `accountId` como `approvalKind` a través de esos helpers. `accountId` mantiene la política de aprobación multicuenta dentro del alcance de la cuenta de bot correcta, y `approvalKind` mantiene disponible para el canal el comportamiento de aprobación de ejecución frente al de Plugin sin ramas codificadas en el núcleo.
|
||||
- El núcleo ahora también es responsable de los avisos de redirección de aprobación. Los Plugins de canal no deben enviar sus propios mensajes de seguimiento de “la aprobación fue a los MD / a otro canal” desde `createChannelNativeApprovalRuntime`; en su lugar, exponga un enrutamiento preciso del origen y del MD del aprobador mediante los helpers de capacidad de aprobación compartida y deje que el núcleo agregue las entregas reales antes de publicar cualquier aviso de vuelta en el chat iniciador.
|
||||
- Preserve de extremo a extremo el tipo de identificador de aprobación entregado. Los clientes nativos no deben
|
||||
inferir ni reescribir el enrutamiento de aprobación de ejecución frente al de Plugin a partir del estado local del canal.
|
||||
- Distintos tipos de aprobación pueden exponer intencionalmente superficies nativas diferentes.
|
||||
- El núcleo gestiona `/approve` en el mismo chat, las cargas útiles compartidas de botones de aprobación y la entrega genérica de respaldo.
|
||||
- Prefiere un único objeto `approvalCapability` en el Plugin del canal cuando el canal necesite comportamiento específico de aprobación.
|
||||
- `ChannelPlugin.approvals` se eliminó. Coloca los datos de entrega/aprobación nativa/renderizado/autenticación en `approvalCapability`.
|
||||
- `plugin.auth` es solo para inicio y cierre de sesión; el núcleo ya no lee hooks de autenticación de aprobación desde ese objeto.
|
||||
- `approvalCapability.authorizeActorAction` y `approvalCapability.getActionAvailabilityState` son la separación canónica para la autenticación de aprobaciones.
|
||||
- Usa `approvalCapability.getActionAvailabilityState` para la disponibilidad de autenticación de aprobaciones en el mismo chat.
|
||||
- Si tu canal expone aprobaciones nativas de ejecución, usa `approvalCapability.getExecInitiatingSurfaceState` para el estado de la superficie iniciadora/cliente nativo cuando difiera de la autenticación de aprobación en el mismo chat. El núcleo usa ese hook específico de ejecución para distinguir `enabled` de `disabled`, decidir si el canal iniciador admite aprobaciones nativas de ejecución e incluir el canal en la guía de respaldo del cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` lo completa para el caso común.
|
||||
- Usa `outbound.shouldSuppressLocalPayloadPrompt` o `outbound.beforeDeliverPayload` para comportamiento específico del canal en el ciclo de vida de la carga útil, como ocultar prompts locales duplicados de aprobación o enviar indicadores de escritura antes de la entrega.
|
||||
- Usa `approvalCapability.delivery` solo para enrutamiento de aprobaciones nativas o supresión del respaldo.
|
||||
- Usa `approvalCapability.nativeRuntime` para datos nativos de aprobación gestionados por el canal. Mantenlo diferido en puntos de entrada calientes del canal con `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que puede importar tu módulo de tiempo de ejecución bajo demanda y aun así permitir que el núcleo ensamble el ciclo de vida de la aprobación.
|
||||
- Usa `approvalCapability.render` solo cuando un canal realmente necesite cargas útiles de aprobación personalizadas en lugar del renderizador compartido.
|
||||
- Usa `approvalCapability.describeExecApprovalSetup` cuando el canal quiera que la respuesta de ruta deshabilitada explique los parámetros exactos de configuración necesarios para habilitar aprobaciones nativas de ejecución. El hook recibe `{ channel, channelLabel, accountId }`; los canales con cuentas nombradas deben renderizar rutas con alcance por cuenta como `channels.<channel>.accounts.<id>.execApprovals.*` en lugar de valores predeterminados de nivel superior.
|
||||
- Si un canal puede inferir identidades de MD estables de tipo propietario a partir de la configuración existente, usa `createResolvedApproverActionAuthAdapter` desde `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` en el mismo chat sin añadir lógica de aprobación específica al núcleo.
|
||||
- Si un canal necesita entrega de aprobación nativa, mantén el código del canal enfocado en la normalización del destino más los datos de transporte/presentación. Usa `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` y `createApproverRestrictedNativeApprovalCapability` desde `openclaw/plugin-sdk/approval-runtime`. Coloca los datos específicos del canal detrás de `approvalCapability.nativeRuntime`, idealmente mediante `createChannelApprovalNativeRuntimeAdapter(...)` o `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que el núcleo pueda ensamblar el controlador y gestionar el filtrado de solicitudes, el enrutamiento, la eliminación de duplicados, la expiración, la suscripción al Gateway y los avisos de redirección. `nativeRuntime` se divide en algunas separaciones más pequeñas:
|
||||
- `availability` — si la cuenta está configurada y si una solicitud debe gestionarse
|
||||
- `presentation` — asigna el modelo de vista compartido de aprobación a cargas útiles nativas pendientes/resueltas/expiradas o acciones finales
|
||||
- `transport` — prepara destinos más envío/actualización/eliminación de mensajes nativos de aprobación
|
||||
- `interactions` — hooks opcionales para enlazar/desenlazar/borrar acciones de botones o reacciones nativas
|
||||
- `observe` — hooks opcionales de diagnóstico de entrega
|
||||
- Si el canal necesita objetos gestionados por el tiempo de ejecución como un cliente, token, app Bolt o receptor de Webhook, regístralos mediante `openclaw/plugin-sdk/channel-runtime-context`. El registro genérico de contexto de tiempo de ejecución permite que el núcleo inicialice controladores guiados por capacidades a partir del estado de arranque del canal sin añadir pegamento contenedor específico de aprobación.
|
||||
- Recurre a `createChannelApprovalHandler` o `createChannelNativeApprovalRuntime` de nivel inferior solo cuando la separación guiada por capacidades todavía no sea lo bastante expresiva.
|
||||
- Los canales de aprobación nativa deben enrutar tanto `accountId` como `approvalKind` a través de esos helpers. `accountId` mantiene la política de aprobación multicuenta con el alcance correcto para la cuenta del bot, y `approvalKind` mantiene disponible para el canal el comportamiento de aprobación de ejecución frente al de Plugin sin ramas codificadas en el núcleo.
|
||||
- El núcleo ahora también gestiona los avisos de redirección de aprobación. Los Plugins de canal no deben enviar sus propios mensajes de seguimiento de "la aprobación fue a MD / a otro canal" desde `createChannelNativeApprovalRuntime`; en su lugar, expón un enrutamiento preciso del origen + MD del aprobador mediante los helpers compartidos de capacidad de aprobación y deja que el núcleo agregue las entregas reales antes de publicar cualquier aviso en el chat iniciador.
|
||||
- Conserva de extremo a extremo el tipo de id. de aprobación entregado. Los clientes nativos no deben
|
||||
adivinar ni reescribir el enrutamiento de aprobaciones de ejecución frente a Plugin a partir del estado local del canal.
|
||||
- Distintos tipos de aprobación pueden exponer intencionalmente distintas superficies nativas.
|
||||
Ejemplos actuales incluidos:
|
||||
- Slack mantiene disponible el enrutamiento de aprobación nativa tanto para identificadores de ejecución como de Plugin.
|
||||
- Matrix mantiene el mismo enrutamiento nativo de MD/canal y la misma UX de reacciones para aprobaciones de ejecución
|
||||
y de Plugin, a la vez que permite que la autenticación difiera según el tipo de aprobación.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` sigue existiendo como envoltorio de compatibilidad, pero el código nuevo debe preferir el generador de capacidades y exponer `approvalCapability` en el Plugin.
|
||||
- Slack mantiene disponible el enrutamiento de aprobación nativa tanto para id. de ejecución como de Plugin.
|
||||
- Matrix mantiene el mismo enrutamiento nativo de MD/canal y la misma experiencia de reacciones para aprobaciones de ejecución
|
||||
y de Plugin, al tiempo que sigue permitiendo que la autenticación difiera según el tipo de aprobación.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` sigue existiendo como contenedor de compatibilidad, pero el código nuevo debe preferir el constructor de capacidades y exponer `approvalCapability` en el Plugin.
|
||||
|
||||
Para puntos de entrada críticos del canal, prefiera las subrutas de tiempo de ejecución más específicas cuando solo
|
||||
necesite una parte de esa familia:
|
||||
Para puntos de entrada calientes del canal, prefiere las subrutas de tiempo de ejecución más estrechas cuando solo
|
||||
necesites una parte de esa familia:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -120,46 +119,47 @@ necesite una parte de esa familia:
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
- `openclaw/plugin-sdk/channel-runtime-context`
|
||||
|
||||
De igual manera, prefiera `openclaw/plugin-sdk/setup-runtime`,
|
||||
Del mismo modo, prefiere `openclaw/plugin-sdk/setup-runtime`,
|
||||
`openclaw/plugin-sdk/setup-adapter-runtime`,
|
||||
`openclaw/plugin-sdk/reply-runtime`,
|
||||
`openclaw/plugin-sdk/reply-dispatch-runtime`,
|
||||
`openclaw/plugin-sdk/reply-reference` y
|
||||
`openclaw/plugin-sdk/reply-chunking` cuando no necesite la superficie
|
||||
paraguas más amplia.
|
||||
`openclaw/plugin-sdk/reply-chunking` cuando no necesites la
|
||||
superficie paraguas más amplia.
|
||||
|
||||
Para la configuración específicamente:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` cubre los helpers de configuración seguros para tiempo de ejecución:
|
||||
adaptadores de parcheo de configuración seguros para importación (`createPatchedAccountSetupAdapter`,
|
||||
adaptadores de parche de configuración seguros para importación (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`), salida de notas de búsqueda,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` y los constructores
|
||||
delegados de proxy de configuración
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` es la unión de adaptador
|
||||
específica y acotada para entorno para `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` es la separación estrecha de adaptador
|
||||
consciente del entorno para `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` cubre los constructores de configuración de instalación opcional
|
||||
más algunas primitivas seguras para configuración:
|
||||
más algunos primitivos seguros para configuración:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
|
||||
Si su canal admite configuración o autenticación impulsadas por variables de entorno y los
|
||||
flujos genéricos de inicio/configuración deben conocer esos nombres de variables de entorno antes de que se cargue el tiempo de ejecución,
|
||||
declárelos en el manifiesto del Plugin con `channelEnvVars`. Mantenga `envVars` del tiempo de ejecución del canal o constantes locales solo para el texto dirigido a operadores.
|
||||
Si tu canal admite configuración o autenticación basada en variables de entorno y los flujos genéricos de inicio/configuración
|
||||
deben conocer esos nombres de variables antes de que cargue el tiempo de ejecución, decláralos en el
|
||||
manifiesto del Plugin con `channelEnvVars`. Mantén `envVars` del tiempo de ejecución del canal o
|
||||
constantes locales solo para el texto dirigido al operador.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` y
|
||||
`splitSetupEntries`
|
||||
|
||||
- use la unión más amplia `openclaw/plugin-sdk/setup` solo cuando también necesite los
|
||||
helpers compartidos más pesados de configuración/configuración, como
|
||||
- usa la separación más amplia `openclaw/plugin-sdk/setup` solo cuando también necesites los
|
||||
helpers compartidos más pesados de configuración/configuración como
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Si su canal solo quiere anunciar “instale primero este Plugin” en las
|
||||
superficies de configuración, prefiera `createOptionalChannelSetupSurface(...)`. El
|
||||
Si tu canal solo quiere anunciar "instala primero este Plugin" en las
|
||||
superficies de configuración, prefiere `createOptionalChannelSetupSurface(...)`. El
|
||||
adaptador/asistente generado falla de forma cerrada en escrituras de configuración y finalización, y reutiliza
|
||||
el mismo mensaje de instalación requerida en la validación, finalización y el texto
|
||||
del enlace a la documentación.
|
||||
el mismo mensaje de instalación requerida en la validación, finalización y texto
|
||||
de enlace a la documentación.
|
||||
|
||||
Para otras rutas críticas del canal, prefiera los helpers específicos en lugar de las
|
||||
Para otras rutas calientes del canal, prefiere los helpers estrechos en lugar de las
|
||||
superficies heredadas más amplias:
|
||||
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
@ -168,52 +168,52 @@ superficies heredadas más amplias:
|
||||
`openclaw/plugin-sdk/account-helpers` para configuración multicuenta y
|
||||
respaldo de cuenta predeterminada
|
||||
- `openclaw/plugin-sdk/inbound-envelope` y
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` para cableado de ruta/sobre entrante y
|
||||
registrar-y-despachar
|
||||
- `openclaw/plugin-sdk/messaging-targets` para análisis y coincidencia de destinos
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` para el cableado de ruta/sobre de entrada y
|
||||
registro y despacho
|
||||
- `openclaw/plugin-sdk/messaging-targets` para análisis/coincidencia de destinos
|
||||
- `openclaw/plugin-sdk/outbound-media` y
|
||||
`openclaw/plugin-sdk/outbound-runtime` para carga de medios más delegados de identidad/envío
|
||||
salientes
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` para el ciclo de vida de asociaciones de hilo
|
||||
`openclaw/plugin-sdk/outbound-runtime` para carga de medios más delegados de
|
||||
identidad/envío salientes
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` para el ciclo de vida de los vínculos de hilo
|
||||
y el registro de adaptadores
|
||||
- `openclaw/plugin-sdk/agent-media-payload` solo cuando siga siendo necesario un diseño heredado de campos
|
||||
de carga útil de agente/medios
|
||||
- `openclaw/plugin-sdk/telegram-command-config` para normalización de comandos personalizados de Telegram,
|
||||
validación de duplicados/conflictos y un contrato de configuración de comandos
|
||||
estable como respaldo
|
||||
- `openclaw/plugin-sdk/agent-media-payload` solo cuando todavía se requiera una disposición heredada
|
||||
de campos de carga útil de agente/medios
|
||||
- `openclaw/plugin-sdk/telegram-command-config` para normalización de comandos personalizados de Telegram, validación de duplicados/conflictos y un contrato de configuración de comandos estable para respaldo
|
||||
|
||||
Los canales solo de autenticación normalmente pueden quedarse en la ruta predeterminada: el núcleo se encarga de las aprobaciones y el Plugin solo expone capacidades de salida/autenticación. Los canales de aprobación nativa, como Matrix, Slack, Telegram y transportes de chat personalizados, deben usar los helpers nativos compartidos en lugar de implementar su propio ciclo de vida de aprobación.
|
||||
Los canales solo de autenticación normalmente pueden detenerse en la ruta predeterminada: el núcleo gestiona las aprobaciones y el Plugin solo expone capacidades de salida/autenticación. Los canales de aprobación nativa como Matrix, Slack, Telegram y transportes de chat personalizados deben usar los helpers nativos compartidos en lugar de crear su propio ciclo de vida de aprobación.
|
||||
|
||||
## Política de menciones entrantes
|
||||
|
||||
Mantenga el manejo de menciones entrantes dividido en dos capas:
|
||||
Mantén el manejo de menciones entrantes dividido en dos capas:
|
||||
|
||||
- recopilación de evidencia que pertenece al Plugin
|
||||
- recopilación de evidencias gestionada por el Plugin
|
||||
- evaluación de políticas compartidas
|
||||
|
||||
Use `openclaw/plugin-sdk/channel-inbound` para la capa compartida.
|
||||
Usa `openclaw/plugin-sdk/channel-mention-gating` para decisiones de política de menciones.
|
||||
Usa `openclaw/plugin-sdk/channel-inbound` solo cuando necesites el barrel
|
||||
más amplio de helpers de entrada.
|
||||
|
||||
Buen ajuste para lógica local del Plugin:
|
||||
Buen encaje para lógica local del Plugin:
|
||||
|
||||
- detección de respuesta al bot
|
||||
- detección de cita del bot
|
||||
- comprobaciones de participación en el hilo
|
||||
- comprobaciones de participación en hilos
|
||||
- exclusiones de mensajes de servicio/sistema
|
||||
- cachés nativos de la plataforma necesarios para demostrar participación del bot
|
||||
- cachés nativos de la plataforma necesarios para demostrar la participación del bot
|
||||
|
||||
Buen ajuste para el helper compartido:
|
||||
Buen encaje para el helper compartido:
|
||||
|
||||
- `requireMention`
|
||||
- resultado de mención explícita
|
||||
- lista de permitidos de mención implícita
|
||||
- lista de permitidos de menciones implícitas
|
||||
- omisión de comandos
|
||||
- decisión final de omitir
|
||||
|
||||
Flujo recomendado:
|
||||
Flujo preferido:
|
||||
|
||||
1. Calcule los datos locales de mención.
|
||||
2. Pase esos datos a `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. Use `decision.effectiveWasMentioned`, `decision.shouldBypassMention` y `decision.shouldSkip` en su compuerta de entrada.
|
||||
1. Calcula los datos locales de mención.
|
||||
2. Pasa esos datos a `resolveInboundMentionDecision({ facts, policy })`.
|
||||
3. Usa `decision.effectiveWasMentioned`, `decision.shouldBypassMention` y `decision.shouldSkip` en tu compuerta de entrada.
|
||||
|
||||
```typescript
|
||||
import {
|
||||
@ -252,8 +252,8 @@ const decision = resolveInboundMentionDecision({
|
||||
if (decision.shouldSkip) return;
|
||||
```
|
||||
|
||||
`api.runtime.channel.mentions` expone los mismos helpers de mención compartidos para
|
||||
los Plugins de canal incluidos que ya dependen de la inyección en tiempo de ejecución:
|
||||
`api.runtime.channel.mentions` expone los mismos helpers compartidos de menciones para
|
||||
los Plugins de canal incluidos que ya dependen de inyección en tiempo de ejecución:
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -261,7 +261,12 @@ los Plugins de canal incluidos que ya dependen de la inyección en tiempo de eje
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
Los helpers antiguos `resolveMentionGating*` siguen estando en
|
||||
Si solo necesitas `implicitMentionKindWhen` y
|
||||
`resolveInboundMentionDecision`, importa desde
|
||||
`openclaw/plugin-sdk/channel-mention-gating` para evitar cargar helpers de tiempo de ejecución
|
||||
de entrada no relacionados.
|
||||
|
||||
Los antiguos helpers `resolveMentionGating*` siguen estando en
|
||||
`openclaw/plugin-sdk/channel-inbound` solo como exportaciones de compatibilidad. El código nuevo
|
||||
debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
@ -270,9 +275,9 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Paquete y manifiesto">
|
||||
Cree los archivos estándar del Plugin. El campo `channel` en `package.json` es
|
||||
lo que hace que este sea un Plugin de canal. Para conocer toda la superficie de metadatos del paquete,
|
||||
consulte [Configuración y Setup del Plugin](/es/plugins/sdk-setup#openclaw-channel):
|
||||
Crea los archivos estándar del Plugin. El campo `channel` en `package.json` es
|
||||
lo que convierte esto en un Plugin de canal. Para la superficie completa de metadatos del paquete,
|
||||
consulta [Configuración y Setup del Plugin](/es/plugins/sdk-setup#openclaw-channel):
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -286,7 +291,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
"channel": {
|
||||
"id": "acme-chat",
|
||||
"label": "Acme Chat",
|
||||
"blurb": "Connect OpenClaw to Acme Chat."
|
||||
"blurb": "Conecta OpenClaw con Acme Chat."
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -298,7 +303,7 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
"kind": "channel",
|
||||
"channels": ["acme-chat"],
|
||||
"name": "Acme Chat",
|
||||
"description": "Acme Chat channel plugin",
|
||||
"description": "Plugin de canal de Acme Chat",
|
||||
"configSchema": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
@ -321,11 +326,11 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Construir el objeto del Plugin de canal">
|
||||
La interfaz `ChannelPlugin` tiene muchas superficies de adaptador opcionales. Empiece con
|
||||
lo mínimo — `id` y `setup` — y agregue adaptadores según los necesite.
|
||||
<Step title="Construye el objeto del Plugin de canal">
|
||||
La interfaz `ChannelPlugin` tiene muchas superficies opcionales de adaptador. Comienza con
|
||||
lo mínimo — `id` y `setup` — y añade adaptadores según los necesites.
|
||||
|
||||
Cree `src/channel.ts`:
|
||||
Crea `src/channel.ts`:
|
||||
|
||||
```typescript src/channel.ts
|
||||
import {
|
||||
@ -418,25 +423,25 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
});
|
||||
```
|
||||
|
||||
<Accordion title="Qué hace `createChatChannelPlugin` por usted">
|
||||
En lugar de implementar manualmente interfaces de adaptador de bajo nivel, usted pasa
|
||||
<Accordion title="Qué hace `createChatChannelPlugin` por ti">
|
||||
En lugar de implementar manualmente interfaces de adaptador de bajo nivel, pasas
|
||||
opciones declarativas y el constructor las compone:
|
||||
|
||||
| Opción | Qué conecta |
|
||||
| --- | --- |
|
||||
| `security.dm` | Resolutor de seguridad de MD con alcance desde campos de configuración |
|
||||
| `pairing.text` | Flujo de emparejamiento por texto en MD con intercambio de código |
|
||||
| `threading` | Resolutor de modo de respuesta (fijo, con alcance por cuenta o personalizado) |
|
||||
| `outbound.attachedResults` | Funciones de envío que devuelven metadatos del resultado (IDs de mensaje) |
|
||||
| `pairing.text` | Flujo de emparejamiento por MD basado en texto con intercambio de código |
|
||||
| `threading` | Resolutor del modo de respuesta (fijo, con alcance por cuenta o personalizado) |
|
||||
| `outbound.attachedResults` | Funciones de envío que devuelven metadatos del resultado (id. de mensaje) |
|
||||
|
||||
También puede pasar objetos de adaptador sin procesar en lugar de opciones declarativas
|
||||
si necesita control total.
|
||||
También puedes pasar objetos de adaptador sin procesar en lugar de las opciones declarativas
|
||||
si necesitas control total.
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Conectar el punto de entrada">
|
||||
Cree `index.ts`:
|
||||
<Step title="Conecta el punto de entrada">
|
||||
Crea `index.ts`:
|
||||
|
||||
```typescript index.ts
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -471,22 +476,22 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
});
|
||||
```
|
||||
|
||||
Coloque los descriptores de CLI que pertenecen al canal en `registerCliMetadata(...)` para que OpenClaw
|
||||
Coloca los descriptores de CLI gestionados por el canal en `registerCliMetadata(...)` para que OpenClaw
|
||||
pueda mostrarlos en la ayuda raíz sin activar el tiempo de ejecución completo del canal,
|
||||
mientras que las cargas completas normales siguen recogiendo los mismos descriptores para el registro real
|
||||
de comandos. Mantenga `registerFull(...)` para trabajo exclusivo de tiempo de ejecución.
|
||||
Si `registerFull(...)` registra métodos RPC del Gateway, use un
|
||||
mientras que las cargas completas normales sigan recogiendo los mismos descriptores para el registro
|
||||
real de comandos. Mantén `registerFull(...)` para trabajo exclusivo de tiempo de ejecución.
|
||||
Si `registerFull(...)` registra métodos RPC del Gateway, usa un
|
||||
prefijo específico del Plugin. Los espacios de nombres administrativos del núcleo (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) permanecen reservados y siempre
|
||||
se resuelven en `operator.admin`.
|
||||
`defineChannelPluginEntry` maneja automáticamente la división del modo de registro. Consulte
|
||||
se resuelven a `operator.admin`.
|
||||
`defineChannelPluginEntry` gestiona automáticamente la división del modo de registro. Consulta
|
||||
[Puntos de entrada](/es/plugins/sdk-entrypoints#definechannelpluginentry) para ver todas las
|
||||
opciones.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Agregar una entrada de configuración">
|
||||
Cree `setup-entry.ts` para carga ligera durante la incorporación:
|
||||
<Step title="Añade una entrada de configuración">
|
||||
Crea `setup-entry.ts` para una carga ligera durante la incorporación:
|
||||
|
||||
```typescript setup-entry.ts
|
||||
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -496,20 +501,20 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
```
|
||||
|
||||
OpenClaw carga esto en lugar de la entrada completa cuando el canal está deshabilitado
|
||||
o no está configurado. Evita cargar código pesado de tiempo de ejecución durante los flujos de configuración.
|
||||
Consulte [Setup y Configuración](/es/plugins/sdk-setup#setup-entry) para más detalles.
|
||||
o sin configurar. Evita cargar código pesado de tiempo de ejecución durante los flujos de configuración.
|
||||
Consulta [Setup y Configuración](/es/plugins/sdk-setup#setup-entry) para más detalles.
|
||||
|
||||
Los canales de workspace incluidos que dividen exportaciones seguras para configuración en módulos
|
||||
auxiliares pueden usar `defineBundledChannelSetupEntry(...)` de
|
||||
Los canales incluidos del espacio de trabajo que dividen las exportaciones seguras para configuración en módulos
|
||||
auxiliares pueden usar `defineBundledChannelSetupEntry(...)` desde
|
||||
`openclaw/plugin-sdk/channel-entry-contract` cuando también necesitan un
|
||||
setter explícito de tiempo de ejecución para configuración.
|
||||
setter explícito de tiempo de ejecución para el momento de configuración.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Manejar mensajes entrantes">
|
||||
Su Plugin necesita recibir mensajes de la plataforma y reenviarlos a
|
||||
<Step title="Gestiona los mensajes entrantes">
|
||||
Tu Plugin necesita recibir mensajes desde la plataforma y reenviarlos a
|
||||
OpenClaw. El patrón típico es un Webhook que verifica la solicitud y
|
||||
la despacha a través del controlador entrante de su canal:
|
||||
la despacha a través del controlador de entrada de tu canal:
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
@ -533,23 +538,23 @@ debe usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
```
|
||||
|
||||
<Note>
|
||||
El manejo de mensajes entrantes es específico de cada canal. Cada Plugin de canal es responsable de
|
||||
su propia canalización de entrada. Revise los Plugins de canal incluidos
|
||||
(por ejemplo, el paquete de Plugin de Microsoft Teams o Google Chat) para ver patrones reales.
|
||||
El manejo de mensajes entrantes es específico de cada canal. Cada Plugin de canal gestiona
|
||||
su propia canalización de entrada. Mira los Plugins de canal incluidos
|
||||
(por ejemplo, el paquete Plugin de Microsoft Teams o Google Chat) para ver patrones reales.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="Prueba">
|
||||
Escriba pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
Escribe pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { acmeChatPlugin } from "./channel.js";
|
||||
|
||||
describe("acme-chat plugin", () => {
|
||||
it("resolves account from config", () => {
|
||||
describe("plugin acme-chat", () => {
|
||||
it("resuelve la cuenta desde la configuración", () => {
|
||||
const cfg = {
|
||||
channels: {
|
||||
"acme-chat": { token: "test-token", allowFrom: ["user1"] },
|
||||
@ -559,7 +564,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
expect(account.token).toBe("test-token");
|
||||
});
|
||||
|
||||
it("inspects account without materializing secrets", () => {
|
||||
it("inspecciona la cuenta sin materializar secretos", () => {
|
||||
const cfg = {
|
||||
channels: { "acme-chat": { token: "test-token" } },
|
||||
} as any;
|
||||
@ -568,7 +573,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
expect(result.tokenStatus).toBe("available");
|
||||
});
|
||||
|
||||
it("reports missing config", () => {
|
||||
it("informa de configuración faltante", () => {
|
||||
const cfg = { channels: {} } as any;
|
||||
const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
|
||||
expect(result.configured).toBe(false);
|
||||
@ -580,7 +585,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
Para los helpers de prueba compartidos, consulte [Pruebas](/es/plugins/sdk-testing).
|
||||
Para los helpers de pruebas compartidos, consulta [Pruebas](/es/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -589,17 +594,17 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/acme-chat/
|
||||
├── package.json # openclaw.channel metadata
|
||||
├── openclaw.plugin.json # Manifest with config schema
|
||||
├── package.json # metadatos de openclaw.channel
|
||||
├── openclaw.plugin.json # Manifiesto con esquema de configuración
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # Public exports (optional)
|
||||
├── runtime-api.ts # Internal runtime exports (optional)
|
||||
├── api.ts # Exportaciones públicas (opcional)
|
||||
├── runtime-api.ts # Exportaciones internas de tiempo de ejecución (opcional)
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin via createChatChannelPlugin
|
||||
├── channel.test.ts # Tests
|
||||
├── client.ts # Platform API client
|
||||
└── runtime.ts # Runtime store (if needed)
|
||||
├── channel.ts # ChannelPlugin mediante createChatChannelPlugin
|
||||
├── channel.test.ts # Pruebas
|
||||
├── client.ts # Cliente API de la plataforma
|
||||
└── runtime.ts # Almacén de tiempo de ejecución (si es necesario)
|
||||
```
|
||||
|
||||
## Temas avanzados
|
||||
@ -608,7 +613,7 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
<Card title="Opciones de encadenamiento" icon="git-branch" href="/es/plugins/sdk-entrypoints#registration-mode">
|
||||
Modos de respuesta fijos, con alcance por cuenta o personalizados
|
||||
</Card>
|
||||
<Card title="Integración con la herramienta de mensajes" icon="puzzle" href="/es/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
<Card title="Integración de la herramienta de mensajes" icon="puzzle" href="/es/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool y descubrimiento de acciones
|
||||
</Card>
|
||||
<Card title="Resolución de destino" icon="crosshair" href="/es/plugins/architecture#channel-target-resolution">
|
||||
@ -620,15 +625,15 @@ Escriba pruebas colocadas junto al código en `src/channel.test.ts`:
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Algunas uniones auxiliares incluidas siguen existiendo para el mantenimiento y la
|
||||
compatibilidad de Plugins incluidos. No son el patrón recomendado para nuevos Plugins de canal;
|
||||
prefiera las subrutas genéricas de canal/configuración/respuesta/tiempo de ejecución de la superficie común del SDK
|
||||
a menos que esté manteniendo directamente esa familia de Plugins incluidos.
|
||||
Todavía existen algunas separaciones auxiliares incluidas para mantenimiento y
|
||||
compatibilidad de Plugins incluidos. No son el patrón recomendado para Plugins de canal nuevos;
|
||||
prefiere las subrutas genéricas de channel/setup/reply/runtime de la superficie común del SDK
|
||||
salvo que estés manteniendo directamente esa familia de Plugins incluidos.
|
||||
</Note>
|
||||
|
||||
## Siguientes pasos
|
||||
|
||||
- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — si su Plugin también proporciona modelos
|
||||
- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) — si tu Plugin también proporciona modelos
|
||||
- [Resumen del SDK](/es/plugins/sdk-overview) — referencia completa de importaciones por subruta
|
||||
- [Pruebas del SDK](/es/plugins/sdk-testing) — utilidades de prueba y pruebas de contrato
|
||||
- [Manifiesto del Plugin](/es/plugins/manifest) — esquema completo del manifiesto
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Necesitas saber desde qué subruta del SDK importar
|
||||
- Quieres una referencia de todos los métodos de registro en `OpenClawPluginApi`
|
||||
- Quieres una referencia de todos los métodos de registro en OpenClawPluginApi
|
||||
- Estás buscando una exportación específica del SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Mapa de importación, referencia de la API de registro y arquitectura del SDK
|
||||
title: Descripción general del SDK de Plugin
|
||||
title: Resumen del SDK de Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-17T05:13:51Z"
|
||||
generated_at: "2026-04-18T04:59:38Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a
|
||||
source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Descripción general del SDK de Plugin
|
||||
# Resumen del SDK de Plugin
|
||||
|
||||
El SDK de plugin es el contrato tipado entre los plugins y el núcleo. Esta página es la
|
||||
El SDK de Plugin es el contrato tipado entre los plugins y el núcleo. Esta página es la
|
||||
referencia para **qué importar** y **qué puedes registrar**.
|
||||
|
||||
<Tip>
|
||||
**¿Buscas una guía práctica?**
|
||||
- ¿Primer plugin? Empieza con [Primeros pasos](/es/plugins/building-plugins)
|
||||
- ¿Tu primer plugin? Empieza con [Primeros pasos](/es/plugins/building-plugins)
|
||||
- ¿Plugin de canal? Consulta [Plugins de canal](/es/plugins/sdk-channel-plugins)
|
||||
- ¿Plugin de proveedor? Consulta [Plugins de proveedor](/es/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
@ -37,43 +37,43 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Cada subruta es un módulo pequeño y autocontenido. Esto mantiene un inicio rápido y
|
||||
evita problemas de dependencias circulares. Para los helpers de entrada/compilación específicos
|
||||
de canal, prefiere `openclaw/plugin-sdk/channel-core`; reserva `openclaw/plugin-sdk/core` para
|
||||
la superficie paraguas más amplia y los helpers compartidos como
|
||||
evita problemas de dependencia circular. Para los helpers de entrada/construcción específicos de canal,
|
||||
prefiere `openclaw/plugin-sdk/channel-core`; reserva `openclaw/plugin-sdk/core` para
|
||||
la superficie paraguas más amplia y los helpers compartidos, como
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
No agregues ni dependas de interfaces de conveniencia nombradas por proveedor como
|
||||
No añadas ni dependas de superficies de conveniencia con nombre de proveedor como
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ni de
|
||||
interfaces helper con marca de canal. Los plugins incluidos deberían componer subrutas
|
||||
genéricas del SDK dentro de sus propios barrels `api.ts` o `runtime-api.ts`, y el núcleo
|
||||
debería usar esos barrels locales del plugin o agregar un contrato genérico y estrecho del SDK
|
||||
cuando la necesidad sea realmente entre canales.
|
||||
superficies helper con marca de canal. Los plugins empaquetados deben componer
|
||||
subrutas genéricas del SDK dentro de sus propios barrels `api.ts` o `runtime-api.ts`, y el núcleo
|
||||
debe usar esos barrels locales del plugin o añadir un contrato SDK genérico y estrecho
|
||||
cuando la necesidad sea realmente transversal a varios canales.
|
||||
|
||||
El mapa de exportación generado todavía contiene un pequeño conjunto de interfaces helper
|
||||
de plugins incluidos, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
El mapa de exportación generado todavía contiene un pequeño conjunto de
|
||||
superficies helper de plugins empaquetados como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` y `plugin-sdk/matrix*`. Esas
|
||||
subrutas existen solo para el mantenimiento y la compatibilidad de plugins incluidos; se
|
||||
subrutas existen solo para mantenimiento y compatibilidad de plugins empaquetados; se
|
||||
omiten intencionalmente de la tabla común de abajo y no son la ruta de importación
|
||||
recomendada para nuevos plugins de terceros.
|
||||
|
||||
## Referencia de subrutas
|
||||
|
||||
Las subrutas más usadas habitualmente, agrupadas por propósito. La lista completa generada de
|
||||
más de 200 subrutas se encuentra en `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
más de 200 subrutas vive en `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Las subrutas helper reservadas para plugins incluidos siguen apareciendo en esa lista generada.
|
||||
Las subrutas helper reservadas para plugins empaquetados siguen apareciendo en esa lista generada.
|
||||
Trátalas como superficies de detalle de implementación/compatibilidad a menos que una página de documentación
|
||||
promocione explícitamente una como pública.
|
||||
promueva explícitamente una como pública.
|
||||
|
||||
### Entrada de plugin
|
||||
### Entrada de Plugin
|
||||
|
||||
| Subruta | Exportaciones clave |
|
||||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| Subruta | Exportaciones clave |
|
||||
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Subrutas de canal">
|
||||
@ -82,273 +82,287 @@ promocione explícitamente una como pública.
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Exportación del esquema Zod raíz de `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, además de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Helpers compartidos del asistente de configuración, prompts de allowlist, constructores de estado de configuración |
|
||||
| `plugin-sdk/setup` | Helpers compartidos para asistentes de configuración, prompts de allowlist y constructores de estado de configuración |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Helpers de configuración/puerta de acciones para múltiples cuentas, helpers de fallback de cuenta predeterminada |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalización de ID de cuenta |
|
||||
| `plugin-sdk/account-resolution` | Helpers de búsqueda de cuentas y fallback predeterminado |
|
||||
| `plugin-sdk/account-helpers` | Helpers acotados de lista de cuentas/acciones de cuenta |
|
||||
| `plugin-sdk/account-core` | Helpers de compuertas de acción/configuración para múltiples cuentas, y helpers de fallback de cuenta predeterminada |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalización de id de cuenta |
|
||||
| `plugin-sdk/account-resolution` | Helpers de búsqueda de cuenta + fallback predeterminado |
|
||||
| `plugin-sdk/account-helpers` | Helpers específicos para lista de cuentas/acciones de cuenta |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Tipos de esquema de configuración de canal |
|
||||
| `plugin-sdk/telegram-command-config` | Helpers de normalización/validación de comandos personalizados de Telegram con fallback de contrato incluido |
|
||||
| `plugin-sdk/telegram-command-config` | Helpers de normalización/validación de comandos personalizados de Telegram con fallback de contrato empaquetado |
|
||||
| `plugin-sdk/command-gating` | Helpers específicos para compuertas de autorización de comandos |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Helpers compartidos de enrutamiento entrante y construcción de sobres |
|
||||
| `plugin-sdk/inbound-envelope` | Helpers compartidos para rutas de entrada + construcción de sobres |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helpers compartidos para registrar y despachar entradas |
|
||||
| `plugin-sdk/messaging-targets` | Helpers de análisis/coincidencia de objetivos |
|
||||
| `plugin-sdk/outbound-media` | Helpers compartidos de carga de medios salientes |
|
||||
| `plugin-sdk/outbound-runtime` | Helpers de identidad saliente y delegado de envío |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helpers de adaptador y ciclo de vida de vinculaciones de hilos |
|
||||
| `plugin-sdk/messaging-targets` | Helpers de análisis/coincidencia de destinos |
|
||||
| `plugin-sdk/outbound-media` | Helpers compartidos para carga de medios salientes |
|
||||
| `plugin-sdk/outbound-runtime` | Helpers de delegación de envío/identidad saliente |
|
||||
| `plugin-sdk/poll-runtime` | Helpers específicos de normalización de encuestas |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helpers para el ciclo de vida de vinculaciones de hilos y adaptadores |
|
||||
| `plugin-sdk/agent-media-payload` | Constructor heredado de payload de medios del agente |
|
||||
| `plugin-sdk/conversation-runtime` | Helpers de conversación/vinculación de hilos, emparejamiento y vinculaciones configuradas |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper de instantánea de configuración en tiempo de ejecución |
|
||||
| `plugin-sdk/runtime-group-policy` | Helpers de resolución de políticas de grupo en tiempo de ejecución |
|
||||
| `plugin-sdk/channel-status` | Helpers compartidos de instantánea/resumen de estado de canal |
|
||||
| `plugin-sdk/channel-config-primitives` | Primitivas acotadas de esquema de configuración de canal |
|
||||
| `plugin-sdk/channel-config-writes` | Helpers de autorización de escritura de configuración de canal |
|
||||
| `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas de plugins de canal |
|
||||
| `plugin-sdk/conversation-runtime` | Helpers para vinculaciones de conversación/hilo, pairing y binding configurado |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper de instantánea de configuración de runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Helpers de resolución de políticas de grupo en runtime |
|
||||
| `plugin-sdk/channel-status` | Helpers compartidos para instantáneas/resúmenes de estado del canal |
|
||||
| `plugin-sdk/channel-config-primitives` | Primitivas específicas de esquema de configuración de canal |
|
||||
| `plugin-sdk/channel-config-writes` | Helpers de autorización para escritura de configuración de canal |
|
||||
| `plugin-sdk/channel-plugin-common` | Exportaciones de preludio compartidas para plugins de canal |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helpers de lectura/edición de configuración de allowlist |
|
||||
| `plugin-sdk/group-access` | Helpers compartidos de decisión de acceso a grupos |
|
||||
| `plugin-sdk/direct-dm` | Helpers compartidos de autenticación/protección para mensajes directos |
|
||||
| `plugin-sdk/group-access` | Helpers compartidos para decisiones de acceso a grupos |
|
||||
| `plugin-sdk/direct-dm` | Helpers compartidos de autenticación/protección para DM directos |
|
||||
| `plugin-sdk/interactive-runtime` | Helpers de normalización/reducción de payloads de respuesta interactiva |
|
||||
| `plugin-sdk/channel-inbound` | Helpers de debounce de entrada, coincidencia de menciones, política de menciones y sobres |
|
||||
| `plugin-sdk/channel-inbound` | Barrel de compatibilidad para debounce de entrada, coincidencia de menciones, helpers de política de menciones y helpers de sobres |
|
||||
| `plugin-sdk/channel-mention-gating` | Helpers específicos de política de menciones sin la superficie más amplia de runtime de entrada |
|
||||
| `plugin-sdk/channel-location` | Helpers de contexto y formato de ubicación del canal |
|
||||
| `plugin-sdk/channel-logging` | Helpers de registro del canal para descartes de entrada y fallos de typing/ack |
|
||||
| `plugin-sdk/channel-send-result` | Tipos de resultado de respuesta |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | Helpers de análisis/coincidencia de objetivos |
|
||||
| `plugin-sdk/channel-targets` | Helpers de análisis/coincidencia de destinos |
|
||||
| `plugin-sdk/channel-contract` | Tipos de contrato de canal |
|
||||
| `plugin-sdk/channel-feedback` | Integración de feedback/reacciones |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers acotados de contrato de secretos como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` y tipos de destino de secretos |
|
||||
| `plugin-sdk/channel-feedback` | Cableado de feedback/reacciones |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers específicos de contrato de secretos, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, y tipos de destino de secretos |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subrutas de proveedor">
|
||||
| Subruta | Exportaciones clave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | Helpers curados de configuración de proveedores locales/autohospedados |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Helpers enfocados de configuración de proveedores autohospedados compatibles con OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Valores predeterminados del backend de CLI y constantes de watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helpers de resolución de claves API en tiempo de ejecución para plugins de proveedor |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helpers de onboarding/escritura de perfiles de clave API como `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-setup` | Helpers de configuración seleccionados para proveedores locales/autohospedados |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Helpers específicos de configuración para proveedores autohospedados compatibles con OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Valores predeterminados del backend de CLI + constantes watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helpers de runtime para resolución de claves API en plugins de proveedor |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helpers de incorporación/escritura de perfiles de claves API como `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Constructor estándar de resultados de autenticación OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Helpers interactivos compartidos de inicio de sesión para plugins de proveedor |
|
||||
| `plugin-sdk/provider-auth-login` | Helpers compartidos de inicio de sesión interactivo para plugins de proveedor |
|
||||
| `plugin-sdk/provider-env-vars` | Helpers de búsqueda de variables de entorno de autenticación del proveedor |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, helpers de endpoint de proveedor y helpers de normalización de ID de modelo como `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, constructores compartidos de políticas de repetición, helpers de endpoint del proveedor y helpers de normalización de id de modelo como `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Helpers genéricos de capacidad HTTP/endpoint de proveedor |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Helpers acotados de contrato de configuración/selección de web-fetch como `enablePluginInConfig` y `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Helpers de registro/caché de proveedor web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Helpers acotados de configuración/credenciales de búsqueda web para proveedores que no necesitan integración de habilitación de plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Helpers acotados de contrato de configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance |
|
||||
| `plugin-sdk/provider-web-search` | Helpers de registro/caché/tiempo de ejecución de proveedor de búsqueda web |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza de esquemas Gemini y diagnósticos, y helpers de compatibilidad de xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-http` | Helpers genéricos de HTTP/capacidades de endpoint del proveedor |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Helpers específicos de contrato para configuración/selección de web-fetch, como `enablePluginInConfig` y `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Helpers de registro/caché para proveedores web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Helpers específicos de configuración/credenciales de búsqueda web para proveedores que no necesitan cableado de habilitación del plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Helpers específicos de contrato para configuración/credenciales de búsqueda web como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` y setters/getters de credenciales con alcance |
|
||||
| `plugin-sdk/provider-web-search` | Helpers de registro/caché/runtime para proveedores de búsqueda web |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpieza + diagnósticos de esquema Gemini, y helpers de compatibilidad xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` y similares |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de streams y helpers compartidos de wrapper para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Helpers de parcheo de configuración de onboarding |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream y helpers compartidos de wrapper para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Helpers de parcheo de configuración de incorporación |
|
||||
| `plugin-sdk/global-singleton` | Helpers de singleton/mapa/caché locales al proceso |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subrutas de autenticación y seguridad">
|
||||
| Subruta | Exportaciones clave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registro de comandos, helpers de autorización del remitente |
|
||||
| `plugin-sdk/command-status` | Constructores de mensajes de comandos/ayuda como `buildCommandsMessagePaginated` y `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helpers de resolución de aprobadores y autenticación de acciones en el mismo chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprobación de ejecución nativa |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidad/entrega de aprobación |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers del registro de comandos, helpers de autorización de remitente |
|
||||
| `plugin-sdk/command-status` | Constructores de mensajes de comando/ayuda como `buildCommandsMessagePaginated` y `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helpers de resolución de aprobadores y de autenticación de acciones en el mismo chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprobación para exec nativo |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Adaptadores de capacidad/entrega de aprobación nativa |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Helper compartido de resolución de Gateway de aprobación |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers ligeros de carga de adaptadores de aprobación nativa para puntos de entrada de canal críticos |
|
||||
| `plugin-sdk/approval-handler-runtime` | Helpers más amplios de tiempo de ejecución del manejador de aprobación; prefiere las interfaces más acotadas de adaptador/Gateway cuando sean suficientes |
|
||||
| `plugin-sdk/approval-native-runtime` | Helpers nativos de objetivo de aprobación y vinculación de cuenta |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helpers de payload de respuesta para aprobaciones de ejecución/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Helpers de autenticación de comandos nativos y de objetivos de sesión nativa |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers ligeros de carga de adaptadores de aprobación nativa para entrypoints de canal de alta frecuencia |
|
||||
| `plugin-sdk/approval-handler-runtime` | Helpers más amplios de runtime para manejadores de aprobación; prefiere las superficies más específicas de adaptador/Gateway cuando sean suficientes |
|
||||
| `plugin-sdk/approval-native-runtime` | Helpers nativos de destino de aprobación + binding de cuenta |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helpers de payload de respuesta para aprobación de exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Helpers de autenticación de comandos nativos + de destino de sesión nativa |
|
||||
| `plugin-sdk/command-detection` | Helpers compartidos de detección de comandos |
|
||||
| `plugin-sdk/command-surface` | Helpers de normalización del cuerpo del comando y de superficie de comando |
|
||||
| `plugin-sdk/command-surface` | Helpers de normalización del cuerpo del comando y de la superficie de comandos |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers acotados de recopilación de contratos de secretos para superficies de secretos de canal/plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Helpers acotados de `coerceSecretRef` y tipado de SecretRef para el análisis de contrato/configuración de secretos |
|
||||
| `plugin-sdk/security-runtime` | Helpers compartidos de confianza, restricción de mensajes directos, contenido externo y recopilación de secretos |
|
||||
| `plugin-sdk/ssrf-policy` | Helpers de política SSRF para allowlist de hosts y red privada |
|
||||
| `plugin-sdk/ssrf-runtime` | Helpers de despachador fijado, `fetch` protegido por SSRF y política SSRF |
|
||||
| `plugin-sdk/secret-input` | Helpers de análisis de entrada de secretos |
|
||||
| `plugin-sdk/webhook-ingress` | Helpers de solicitud/objetivo de Webhook |
|
||||
| `plugin-sdk/channel-secret-runtime` | Helpers específicos de recopilación de contratos de secretos para superficies de secretos de canal/plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Helpers específicos de tipado de `coerceSecretRef` y SecretRef para análisis de contrato/configuración de secretos |
|
||||
| `plugin-sdk/security-runtime` | Helpers compartidos de confianza, compuerta de DM, contenido externo y recopilación de secretos |
|
||||
| `plugin-sdk/ssrf-policy` | Helpers de allowlist de hosts y de política SSRF de red privada |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Helpers específicos de dispatcher fijado sin la amplia superficie de runtime de infraestructura |
|
||||
| `plugin-sdk/ssrf-runtime` | Helpers de dispatcher fijado, fetch protegido contra SSRF y política SSRF |
|
||||
| `plugin-sdk/secret-input` | Helpers de análisis de entrada secreta |
|
||||
| `plugin-sdk/webhook-ingress` | Helpers de solicitud/destino de Webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Helpers de tamaño de cuerpo/timeout de solicitud |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subrutas de tiempo de ejecución y almacenamiento">
|
||||
<Accordion title="Subrutas de runtime y almacenamiento">
|
||||
| Subruta | Exportaciones clave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Helpers amplios de tiempo de ejecución, logging, respaldo e instalación de plugins |
|
||||
| `plugin-sdk/runtime-env` | Helpers acotados de entorno de ejecución, logger, timeout, reintento y backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Helpers genéricos de registro y búsqueda de contexto de tiempo de ejecución de canal |
|
||||
| `plugin-sdk/runtime` | Helpers amplios de runtime/logging/copias de seguridad/instalación de plugins |
|
||||
| `plugin-sdk/runtime-env` | Helpers específicos de entorno de runtime, logger, timeout, retry y backoff |
|
||||
| `plugin-sdk/channel-runtime-context` | Helpers genéricos de registro y búsqueda de contexto de runtime de canal |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Helpers compartidos de comandos, hooks, HTTP e interacción del plugin |
|
||||
| `plugin-sdk/hook-runtime` | Helpers compartidos del pipeline de Webhook y hooks internos |
|
||||
| `plugin-sdk/lazy-runtime` | Helpers de importación/vinculación lazy en tiempo de ejecución como `createLazyRuntimeModule`, `createLazyRuntimeMethod` y `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/plugin-runtime` | Helpers compartidos de plugin para comandos/hooks/http/interactivos |
|
||||
| `plugin-sdk/hook-runtime` | Helpers compartidos del pipeline de hooks internos/Webhook |
|
||||
| `plugin-sdk/lazy-runtime` | Helpers de importación/binding diferido de runtime como `createLazyRuntimeModule`, `createLazyRuntimeMethod` y `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Helpers de ejecución de procesos |
|
||||
| `plugin-sdk/cli-runtime` | Helpers de formato, espera y versión de CLI |
|
||||
| `plugin-sdk/gateway-runtime` | Helpers del cliente de Gateway y de parcheo de estado del canal |
|
||||
| `plugin-sdk/gateway-runtime` | Helpers de cliente de Gateway y de parche de estado del canal |
|
||||
| `plugin-sdk/config-runtime` | Helpers de carga/escritura de configuración |
|
||||
| `plugin-sdk/telegram-command-config` | Normalización de nombres/descripciones de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato incluida de Telegram no está disponible |
|
||||
| `plugin-sdk/approval-runtime` | Helpers de aprobación de ejecución/plugin, constructores de capacidad de aprobación, helpers de autenticación/perfil, helpers nativos de enrutamiento/tiempo de ejecución |
|
||||
| `plugin-sdk/reply-runtime` | Helpers compartidos de tiempo de ejecución para entrada/respuesta, fragmentación, despacho, Heartbeat, planificador de respuestas |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Helpers acotados de despacho/finalización de respuestas |
|
||||
| `plugin-sdk/telegram-command-config` | Helpers de normalización de nombre/descripción de comandos de Telegram y comprobaciones de duplicados/conflictos, incluso cuando la superficie de contrato empaquetada de Telegram no está disponible |
|
||||
| `plugin-sdk/text-autolink-runtime` | Detección de autolinks de referencias de archivo sin el amplio barrel `text-runtime` |
|
||||
| `plugin-sdk/approval-runtime` | Helpers de aprobación de exec/plugin, constructores de capacidad de aprobación, helpers de auth/perfil, helpers de routing/runtime nativo |
|
||||
| `plugin-sdk/reply-runtime` | Helpers compartidos de runtime de entrada/respuesta, chunking, despacho, Heartbeat, planificador de respuestas |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Helpers específicos de despacho/finalización de respuestas |
|
||||
| `plugin-sdk/reply-history` | Helpers compartidos de historial de respuestas de ventana corta como `buildHistoryContext`, `recordPendingHistoryEntry` y `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Helpers acotados de fragmentación de texto/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helpers de ruta de almacenamiento de sesiones y `updated-at` |
|
||||
| `plugin-sdk/state-paths` | Helpers de ruta para directorios de estado/OAuth |
|
||||
| `plugin-sdk/routing` | Helpers de ruta/clave de sesión/vinculación de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Helpers compartidos de resumen de estado de canal/cuenta, valores predeterminados del estado de ejecución y helpers de metadatos de incidencias |
|
||||
| `plugin-sdk/target-resolver-runtime` | Helpers compartidos de resolución de objetivos |
|
||||
| `plugin-sdk/reply-chunking` | Helpers específicos de fragmentación de texto/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helpers de ruta de almacenamiento de sesión + updated-at |
|
||||
| `plugin-sdk/state-paths` | Helpers de rutas de directorio de estado/OAuth |
|
||||
| `plugin-sdk/routing` | Helpers de ruta/clave de sesión/binding de cuenta como `resolveAgentRoute`, `buildAgentSessionKey` y `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Helpers compartidos de resumen de estado de canal/cuenta, valores predeterminados de estado de runtime y helpers de metadatos de incidencias |
|
||||
| `plugin-sdk/target-resolver-runtime` | Helpers compartidos de resolución de destino |
|
||||
| `plugin-sdk/string-normalization-runtime` | Helpers de normalización de slug/cadenas |
|
||||
| `plugin-sdk/request-url` | Extrae URL de cadena de entradas tipo fetch/solicitud |
|
||||
| `plugin-sdk/request-url` | Extraer URL de cadena de entradas tipo fetch/request |
|
||||
| `plugin-sdk/run-command` | Ejecutor de comandos temporizado con resultados normalizados de stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Lectores comunes de parámetros de herramientas/CLI |
|
||||
| `plugin-sdk/tool-payload` | Extrae payloads normalizados de objetos de resultado de herramientas |
|
||||
| `plugin-sdk/tool-send` | Extrae campos canónicos de objetivo de envío desde argumentos de herramientas |
|
||||
| `plugin-sdk/param-readers` | Lectores comunes de parámetros de herramienta/CLI |
|
||||
| `plugin-sdk/tool-payload` | Extraer payloads normalizados de objetos de resultado de herramientas |
|
||||
| `plugin-sdk/tool-send` | Extraer campos de destino de envío canónicos de argumentos de herramienta |
|
||||
| `plugin-sdk/temp-path` | Helpers compartidos de rutas temporales de descarga |
|
||||
| `plugin-sdk/logging-core` | Helpers de logger de subsistema y redacción |
|
||||
| `plugin-sdk/markdown-table-runtime` | Helpers de modo de tablas Markdown |
|
||||
| `plugin-sdk/json-store` | Helpers pequeños de lectura/escritura de estado JSON |
|
||||
| `plugin-sdk/file-lock` | Helpers de bloqueo de archivos reentrantes |
|
||||
| `plugin-sdk/persistent-dedupe` | Helpers de caché de desduplicación respaldada en disco |
|
||||
| `plugin-sdk/acp-runtime` | Helpers de tiempo de ejecución/sesión de ACP y de despacho de respuestas |
|
||||
| `plugin-sdk/agent-config-primitives` | Primitivas acotadas del esquema de configuración de tiempo de ejecución del agente |
|
||||
| `plugin-sdk/markdown-table-runtime` | Helpers de modo de tabla Markdown |
|
||||
| `plugin-sdk/json-store` | Pequeños helpers de lectura/escritura de estado JSON |
|
||||
| `plugin-sdk/file-lock` | Helpers de bloqueo de archivos reentrante |
|
||||
| `plugin-sdk/persistent-dedupe` | Helpers de caché de deduplicación respaldada por disco |
|
||||
| `plugin-sdk/acp-runtime` | Helpers de runtime/sesión ACP y despacho de respuestas |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Resolución de binding ACP de solo lectura sin importaciones de inicio del ciclo de vida |
|
||||
| `plugin-sdk/agent-config-primitives` | Primitivas específicas de esquema de configuración de runtime del agente |
|
||||
| `plugin-sdk/boolean-param` | Lector flexible de parámetros booleanos |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helpers de resolución de coincidencias de nombres peligrosos |
|
||||
| `plugin-sdk/device-bootstrap` | Helpers de bootstrap de dispositivo y token de emparejamiento |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helpers de resolución de coincidencia de nombres peligrosos |
|
||||
| `plugin-sdk/device-bootstrap` | Helpers de bootstrap del dispositivo y token de pairing |
|
||||
| `plugin-sdk/extension-shared` | Primitivas helper compartidas para canal pasivo, estado y proxy ambiental |
|
||||
| `plugin-sdk/models-provider-runtime` | Helpers del comando `/models` y de respuesta de proveedor |
|
||||
| `plugin-sdk/models-provider-runtime` | Helpers de respuesta de proveedor/comando `/models` |
|
||||
| `plugin-sdk/skill-commands-runtime` | Helpers de listado de comandos de Skills |
|
||||
| `plugin-sdk/native-command-registry` | Helpers nativos de registro/creación/serialización de comandos |
|
||||
| `plugin-sdk/agent-harness` | Superficie experimental de plugin confiable para harnesses de agente de bajo nivel: tipos de harness, helpers de dirección/abortado de ejecución activa, helpers del puente de herramientas de OpenClaw y utilidades de resultados de intentos |
|
||||
| `plugin-sdk/native-command-registry` | Helpers de registro/construcción/serialización de comandos nativos |
|
||||
| `plugin-sdk/agent-harness` | Superficie experimental de plugin confiable para harnesses de agente de bajo nivel: tipos de harness, helpers de steering/abort de ejecución activa, helpers de puente de herramientas de OpenClaw y utilidades de resultados de intentos |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Helpers de detección de endpoint de Z.A.I |
|
||||
| `plugin-sdk/infra-runtime` | Helpers de eventos del sistema/Heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Helpers pequeños de caché acotada |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helpers de marcas y eventos de diagnóstico |
|
||||
| `plugin-sdk/error-runtime` | Helpers de grafo de errores, formato, clasificación compartida de errores, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/collection-runtime` | Pequeños helpers de caché acotada |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helpers de flags y eventos de diagnóstico |
|
||||
| `plugin-sdk/error-runtime` | Grafo de errores, formato, helpers compartidos de clasificación de errores, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Helpers de fetch envuelto, proxy y búsqueda fijada |
|
||||
| `plugin-sdk/host-runtime` | Helpers de normalización de hostname y host SCP |
|
||||
| `plugin-sdk/retry-runtime` | Helpers de configuración y ejecución de reintentos |
|
||||
| `plugin-sdk/agent-runtime` | Helpers de directorio/identidad/workspace del agente |
|
||||
| `plugin-sdk/directory-runtime` | Consulta/desduplicación de directorios respaldada por configuración |
|
||||
| `plugin-sdk/runtime-fetch` | Fetch de runtime con reconocimiento de dispatcher sin importaciones de proxy/fetch protegido |
|
||||
| `plugin-sdk/response-limit-runtime` | Lector acotado del cuerpo de la respuesta sin la amplia superficie de runtime de medios |
|
||||
| `plugin-sdk/session-binding-runtime` | Estado actual del binding de conversación sin routing de binding configurado ni almacenes de pairing |
|
||||
| `plugin-sdk/session-store-runtime` | Helpers de lectura del almacenamiento de sesión sin importaciones amplias de escritura/mantenimiento de configuración |
|
||||
| `plugin-sdk/context-visibility-runtime` | Resolución de visibilidad de contexto y filtrado de contexto suplementario sin importaciones amplias de configuración/seguridad |
|
||||
| `plugin-sdk/string-coerce-runtime` | Helpers específicos de coerción y normalización de cadenas/registros primitivos sin importaciones de markdown/logging |
|
||||
| `plugin-sdk/host-runtime` | Helpers de hostname y normalización de host SCP |
|
||||
| `plugin-sdk/retry-runtime` | Helpers de configuración de retry y ejecutor de retry |
|
||||
| `plugin-sdk/agent-runtime` | Helpers de directorio/identidad/espacio de trabajo del agente |
|
||||
| `plugin-sdk/directory-runtime` | Consulta/deduplicación de directorio respaldada por configuración |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subrutas de capacidades y pruebas">
|
||||
| Subruta | Exportaciones clave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Helpers compartidos para obtener/transformar/almacenar medios, además de constructores de payload de medios |
|
||||
| `plugin-sdk/media-generation-runtime` | Helpers compartidos de failover de generación de medios, selección de candidatos y mensajes de modelo faltante |
|
||||
| `plugin-sdk/media-understanding` | Tipos de proveedor para comprensión de medios, además de exportaciones helper orientadas al proveedor para imagen/audio |
|
||||
| `plugin-sdk/text-runtime` | Helpers compartidos de texto/Markdown/logging como eliminación de texto visible para el asistente, helpers de renderizado/fragmentación/tablas Markdown, helpers de redacción, helpers de etiquetas de directivas y utilidades de texto seguro |
|
||||
| `plugin-sdk/media-runtime` | Helpers compartidos de fetch/transformación/almacenamiento de medios, además de constructores de payload de medios |
|
||||
| `plugin-sdk/media-generation-runtime` | Helpers compartidos de failover de generación de medios, selección de candidatos y mensajería de modelo faltante |
|
||||
| `plugin-sdk/media-understanding` | Tipos de proveedor de comprensión de medios, además de exportaciones helper orientadas al proveedor para imagen/audio |
|
||||
| `plugin-sdk/text-runtime` | Helpers compartidos de texto/markdown/logging como eliminación de texto visible para el asistente, helpers de render/chunking/tabla Markdown, helpers de redacción, helpers de etiquetas de directivas y utilidades de texto seguro |
|
||||
| `plugin-sdk/text-chunking` | Helper de fragmentación de texto saliente |
|
||||
| `plugin-sdk/speech` | Tipos de proveedor de voz, además de helpers orientados al proveedor para directivas, registro y validación |
|
||||
| `plugin-sdk/speech-core` | Helpers compartidos de tipos de proveedor de voz, registro, directivas y normalización |
|
||||
| `plugin-sdk/speech` | Tipos de proveedor de speech, además de helpers orientados al proveedor para directivas, registro y validación |
|
||||
| `plugin-sdk/speech-core` | Tipos compartidos de proveedor de speech, helpers de registro, directivas y normalización |
|
||||
| `plugin-sdk/realtime-transcription` | Tipos de proveedor de transcripción en tiempo real y helpers de registro |
|
||||
| `plugin-sdk/realtime-voice` | Tipos de proveedor de voz en tiempo real y helpers de registro |
|
||||
| `plugin-sdk/image-generation` | Tipos de proveedor de generación de imágenes |
|
||||
| `plugin-sdk/image-generation-core` | Helpers compartidos de tipos de generación de imágenes, failover, autenticación y registro |
|
||||
| `plugin-sdk/music-generation` | Tipos de proveedor/solicitud/resultado para generación musical |
|
||||
| `plugin-sdk/music-generation-core` | Helpers compartidos de tipos de generación musical, failover, búsqueda de proveedores y análisis de model-ref |
|
||||
| `plugin-sdk/video-generation` | Tipos de proveedor/solicitud/resultado para generación de video |
|
||||
| `plugin-sdk/video-generation-core` | Helpers compartidos de tipos de generación de video, failover, búsqueda de proveedores y análisis de model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Helpers de registro de objetivos de Webhook e instalación de rutas |
|
||||
| `plugin-sdk/webhook-path` | Helpers de normalización de rutas de Webhook |
|
||||
| `plugin-sdk/image-generation-core` | Tipos compartidos de generación de imágenes, helpers de failover, auth y registro |
|
||||
| `plugin-sdk/music-generation` | Tipos de proveedor/solicitud/resultado de generación de música |
|
||||
| `plugin-sdk/music-generation-core` | Tipos compartidos de generación de música, helpers de failover, búsqueda de proveedores y análisis de model-ref |
|
||||
| `plugin-sdk/video-generation` | Tipos de proveedor/solicitud/resultado de generación de video |
|
||||
| `plugin-sdk/video-generation-core` | Tipos compartidos de generación de video, helpers de failover, búsqueda de proveedores y análisis de model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Helpers de registro de destinos de Webhook e instalación de rutas |
|
||||
| `plugin-sdk/webhook-path` | Helpers de normalización de ruta de Webhook |
|
||||
| `plugin-sdk/web-media` | Helpers compartidos de carga de medios remotos/locales |
|
||||
| `plugin-sdk/zod` | `zod` reexportado para consumidores del SDK de plugin |
|
||||
| `plugin-sdk/zod` | `zod` reexportado para consumidores del SDK de Plugin |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subrutas de memoria">
|
||||
| Subruta | Exportaciones clave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Superficie helper incluida de memory-core para helpers de administrador/configuración/archivos/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Fachada de tiempo de ejecución de índice/búsqueda de memoria |
|
||||
| `plugin-sdk/memory-core` | Superficie helper empaquetada de memory-core para helpers de administrador/configuración/archivo/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime de índice/búsqueda de memoria |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Exportaciones del motor base del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Contratos de embeddings del host de memoria, acceso al registro, proveedor local y helpers genéricos por lotes/remotos |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Exportaciones del motor QMD del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Exportaciones del motor de almacenamiento del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodales del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-query` | Helpers de consultas del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-query` | Helpers de consulta del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helpers de secretos del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-events` | Helpers de diario de eventos del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-events` | Helpers del diario de eventos del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-status` | Helpers de estado del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Helpers de tiempo de ejecución de CLI del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helpers de tiempo de ejecución central del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de archivos/tiempo de ejecución del host de memoria |
|
||||
| `plugin-sdk/memory-host-core` | Alias neutral respecto del proveedor para helpers de tiempo de ejecución central del host de memoria |
|
||||
| `plugin-sdk/memory-host-events` | Alias neutral respecto del proveedor para helpers de diario de eventos del host de memoria |
|
||||
| `plugin-sdk/memory-host-files` | Alias neutral respecto del proveedor para helpers de archivos/tiempo de ejecución del host de memoria |
|
||||
| `plugin-sdk/memory-host-markdown` | Helpers compartidos de Markdown administrado para plugins adyacentes a memoria |
|
||||
| `plugin-sdk/memory-host-search` | Fachada de tiempo de ejecución de Active Memory para acceso al administrador de búsqueda |
|
||||
| `plugin-sdk/memory-host-status` | Alias neutral respecto del proveedor para helpers de estado del host de memoria |
|
||||
| `plugin-sdk/memory-lancedb` | Superficie helper incluida de memory-lancedb |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime de CLI del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime del núcleo del host de memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de archivos/runtime del host de memoria |
|
||||
| `plugin-sdk/memory-host-core` | Alias neutral respecto al proveedor para los helpers de runtime del núcleo del host de memoria |
|
||||
| `plugin-sdk/memory-host-events` | Alias neutral respecto al proveedor para los helpers del diario de eventos del host de memoria |
|
||||
| `plugin-sdk/memory-host-files` | Alias neutral respecto al proveedor para los helpers de archivos/runtime del host de memoria |
|
||||
| `plugin-sdk/memory-host-markdown` | Helpers compartidos de markdown gestionado para plugins adyacentes a memoria |
|
||||
| `plugin-sdk/memory-host-search` | Fachada de runtime de Active Memory para acceso al administrador de búsqueda |
|
||||
| `plugin-sdk/memory-host-status` | Alias neutral respecto al proveedor para los helpers de estado del host de memoria |
|
||||
| `plugin-sdk/memory-lancedb` | Superficie helper empaquetada de memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Subrutas helper reservadas para plugins incluidos">
|
||||
<Accordion title="Subrutas helper empaquetadas reservadas">
|
||||
| Familia | Subrutas actuales | Uso previsto |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de soporte del plugin Browser incluido (`browser-support` sigue siendo el barrel de compatibilidad) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/de tiempo de ejecución de Matrix incluida |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/de tiempo de ejecución de LINE incluida |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper de IRC incluida |
|
||||
| Helpers específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Interfaces de compatibilidad/helper de canales incluidos |
|
||||
| Helpers específicos de autenticación/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Interfaces helper de funciones/plugins incluidos; `plugin-sdk/github-copilot-token` exporta actualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de soporte del Plugin Browser empaquetado (`browser-support` sigue siendo el barrel de compatibilidad) |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/runtime empaquetada de Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime empaquetada de LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper empaquetada de IRC |
|
||||
| Helpers específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Superficies de compatibilidad/helper de canales empaquetados |
|
||||
| Helpers específicos de autenticación/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Superficies helper de funciones/plugins empaquetados; `plugin-sdk/github-copilot-token` actualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` y `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## API de registro
|
||||
|
||||
La callback `register(api)` recibe un objeto `OpenClawPluginApi` con estos
|
||||
La devolución de llamada `register(api)` recibe un objeto `OpenClawPluginApi` con estos
|
||||
métodos:
|
||||
|
||||
### Registro de capacidades
|
||||
|
||||
| Método | Qué registra |
|
||||
| ------------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerProvider(...)` | Inferencia de texto (LLM) |
|
||||
| Método | Qué registra |
|
||||
| ------------------------------------------------ | ------------------------------------------ |
|
||||
| `api.registerProvider(...)` | Inferencia de texto (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Ejecutor experimental de agente de bajo nivel |
|
||||
| `api.registerCliBackend(...)` | Backend de inferencia de CLI local |
|
||||
| `api.registerChannel(...)` | Canal de mensajería |
|
||||
| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real por streaming |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video |
|
||||
| `api.registerImageGenerationProvider(...)` | Generación de imágenes |
|
||||
| `api.registerMusicGenerationProvider(...)` | Generación musical |
|
||||
| `api.registerVideoGenerationProvider(...)` | Generación de video |
|
||||
| `api.registerWebFetchProvider(...)` | Proveedor de obtención / scraping web |
|
||||
| `api.registerWebSearchProvider(...)` | Búsqueda web |
|
||||
| `api.registerCliBackend(...)` | Backend local de inferencia de CLI |
|
||||
| `api.registerChannel(...)` | Canal de mensajería |
|
||||
| `api.registerSpeechProvider(...)` | Síntesis de texto a voz / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Transcripción en tiempo real en streaming |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Sesiones de voz en tiempo real dúplex |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Análisis de imagen/audio/video |
|
||||
| `api.registerImageGenerationProvider(...)` | Generación de imágenes |
|
||||
| `api.registerMusicGenerationProvider(...)` | Generación de música |
|
||||
| `api.registerVideoGenerationProvider(...)` | Generación de video |
|
||||
| `api.registerWebFetchProvider(...)` | Proveedor de fetch / scraping web |
|
||||
| `api.registerWebSearchProvider(...)` | Búsqueda web |
|
||||
|
||||
### Herramientas y comandos
|
||||
|
||||
| Método | Qué registra |
|
||||
| ------------------------------- | -------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Herramienta de agente (obligatoria o `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Comando personalizado (omite el LLM) |
|
||||
| Método | Qué registra |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Herramienta del agente (obligatoria o `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Comando personalizado (omite el LLM) |
|
||||
|
||||
### Infraestructura
|
||||
|
||||
| Método | Qué registra |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook de evento |
|
||||
| `api.registerHttpRoute(params)` | Endpoint HTTP de Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Método RPC de Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Subcomando de CLI |
|
||||
| `api.registerService(service)` | Servicio en segundo plano |
|
||||
| `api.registerInteractiveHandler(registration)` | Manejador interactivo |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Sección adicional del prompt adyacente a memoria |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus adicional de búsqueda/lectura de memoria |
|
||||
| Método | Qué registra |
|
||||
| ---------------------------------------------- | ------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook de evento |
|
||||
| `api.registerHttpRoute(params)` | Endpoint HTTP de Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Método RPC de Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Subcomando de CLI |
|
||||
| `api.registerService(service)` | Servicio en segundo plano |
|
||||
| `api.registerInteractiveHandler(registration)` | Manejador interactivo |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Sección de prompt aditiva adyacente a memoria |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de búsqueda/lectura de memoria |
|
||||
|
||||
Los espacios de nombres administrativos reservados del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
Los espacios de nombres de administración reservados del núcleo (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) siempre permanecen como `operator.admin`, incluso si un plugin intenta asignar un
|
||||
alcance más limitado a un método de Gateway. Prefiere prefijos específicos del plugin para
|
||||
alcance más estrecho a un método de Gateway. Prefiere prefijos específicos del plugin para
|
||||
métodos propiedad del plugin.
|
||||
|
||||
### Metadatos de registro de CLI
|
||||
@ -357,9 +371,9 @@ métodos propiedad del plugin.
|
||||
|
||||
- `commands`: raíces de comandos explícitas propiedad del registrador
|
||||
- `descriptors`: descriptores de comandos en tiempo de análisis usados para la ayuda de la CLI raíz,
|
||||
el enrutamiento y el registro lazy de CLI del plugin
|
||||
el routing y el registro diferido de CLI del plugin
|
||||
|
||||
Si quieres que un comando de plugin permanezca con carga lazy en la ruta normal de la CLI raíz,
|
||||
Si quieres que un comando de plugin permanezca con carga diferida en la ruta normal de la CLI raíz,
|
||||
proporciona `descriptors` que cubran cada raíz de comando de nivel superior expuesta por ese
|
||||
registrador.
|
||||
|
||||
@ -373,7 +387,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "Administra cuentas, verificación, dispositivos y estado del perfil de Matrix",
|
||||
description: "Administra cuentas de Matrix, verificación, dispositivos y estado del perfil",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -381,19 +395,19 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Usa `commands` por sí solo solo cuando no necesites registro lazy de la CLI raíz.
|
||||
Esa ruta de compatibilidad eager sigue siendo compatible, pero no instala
|
||||
placeholders respaldados por descriptores para la carga lazy en tiempo de análisis.
|
||||
Usa `commands` por sí solo solo cuando no necesites registro diferido en la CLI raíz.
|
||||
Esa ruta de compatibilidad ansiosa sigue siendo compatible, pero no instala
|
||||
placeholders respaldados por descriptores para la carga diferida en tiempo de análisis.
|
||||
|
||||
### Registro de backend de CLI
|
||||
|
||||
`api.registerCliBackend(...)` permite que un plugin sea propietario de la configuración predeterminada de un
|
||||
backend de CLI de IA local como `codex-cli`.
|
||||
backend local de CLI de IA como `codex-cli`.
|
||||
|
||||
- El `id` del backend se convierte en el prefijo del proveedor en referencias de modelo como `codex-cli/gpt-5`.
|
||||
- La `config` del backend usa la misma forma que `agents.defaults.cliBackends.<id>`.
|
||||
- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.<id>` sobre el
|
||||
valor predeterminado del plugin antes de ejecutar la CLI.
|
||||
- La configuración del usuario sigue teniendo prioridad. OpenClaw fusiona `agents.defaults.cliBackends.<id>` sobre la
|
||||
predeterminada del plugin antes de ejecutar la CLI.
|
||||
- Usa `normalizeConfig` cuando un backend necesite reescrituras de compatibilidad después de la fusión
|
||||
(por ejemplo, para normalizar formas antiguas de flags).
|
||||
|
||||
@ -401,65 +415,65 @@ backend de CLI de IA local como `codex-cli`.
|
||||
|
||||
| Método | Qué registra |
|
||||
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Motor de contexto (uno activo a la vez). La callback `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar las adiciones al prompt. |
|
||||
| `api.registerContextEngine(id, factory)` | Motor de contexto (solo uno activo a la vez). La devolución de llamada `assemble()` recibe `availableTools` y `citationsMode` para que el motor pueda adaptar adiciones al prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Capacidad de memoria unificada |
|
||||
| `api.registerMemoryPromptSection(builder)` | Constructor de sección de prompt de memoria |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolutor del plan de vaciado de memoria |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adaptador de tiempo de ejecución de memoria |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolutor de plan de vaciado de memoria |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memoria |
|
||||
|
||||
### Adaptadores de embeddings de memoria
|
||||
|
||||
| Método | Qué registra |
|
||||
| ---------------------------------------------- | --------------------------------------------- |
|
||||
| Método | Qué registra |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embeddings de memoria para el plugin activo |
|
||||
|
||||
- `registerMemoryCapability` es la API exclusiva preferida para plugins de memoria.
|
||||
- `registerMemoryCapability` también puede exponer `publicArtifacts.listArtifacts(...)`
|
||||
para que los plugins complementarios puedan consumir artefactos de memoria exportados mediante
|
||||
`openclaw/plugin-sdk/memory-host-core` en lugar de acceder al diseño privado de un
|
||||
`openclaw/plugin-sdk/memory-host-core` en lugar de acceder al layout privado de un
|
||||
plugin de memoria específico.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` y
|
||||
`registerMemoryRuntime` son APIs exclusivas heredadas compatibles para plugins de memoria.
|
||||
`registerMemoryRuntime` son API exclusivas compatibles con versiones heredadas para plugins de memoria.
|
||||
- `registerMemoryEmbeddingProvider` permite que el plugin de memoria activo registre uno
|
||||
o más ID de adaptadores de embeddings (por ejemplo `openai`, `gemini` o un ID personalizado
|
||||
o más ids de adaptador de embeddings (por ejemplo `openai`, `gemini` o un id personalizado
|
||||
definido por el plugin).
|
||||
- La configuración del usuario, como `agents.defaults.memorySearch.provider` y
|
||||
`agents.defaults.memorySearch.fallback`, se resuelve contra esos ID de adaptadores
|
||||
`agents.defaults.memorySearch.fallback`, se resuelve respecto de esos ids de adaptador
|
||||
registrados.
|
||||
|
||||
### Eventos y ciclo de vida
|
||||
|
||||
| Método | Qué hace |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback de vinculación de conversación |
|
||||
| Método | Qué hace |
|
||||
| -------------------------------------------- | --------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida |
|
||||
| `api.onConversationBindingResolved(handler)` | Devolución de llamada de binding de conversación |
|
||||
|
||||
### Semántica de decisión de hooks
|
||||
|
||||
- `before_tool_call`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
|
||||
- `before_tool_call`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación.
|
||||
- `before_install`: devolver `{ block: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
|
||||
- `before_install`: devolver `{ block: false }` se trata como ausencia de decisión (igual que omitir `block`), no como una anulación.
|
||||
- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. Una vez que cualquier manejador reclama el despacho, se omiten los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo.
|
||||
- `message_sending`: devolver `{ cancel: true }` es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
|
||||
- `message_sending`: devolver `{ cancel: false }` se trata como ausencia de decisión (igual que omitir `cancel`), no como una anulación.
|
||||
- `before_tool_call`: devolver `{ block: true }` es terminal. En cuanto cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
|
||||
- `before_tool_call`: devolver `{ block: false }` se trata como si no hubiera decisión (igual que omitir `block`), no como una anulación.
|
||||
- `before_install`: devolver `{ block: true }` es terminal. En cuanto cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
|
||||
- `before_install`: devolver `{ block: false }` se trata como si no hubiera decisión (igual que omitir `block`), no como una anulación.
|
||||
- `reply_dispatch`: devolver `{ handled: true, ... }` es terminal. En cuanto cualquier manejador reclama el despacho, se omiten los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo.
|
||||
- `message_sending`: devolver `{ cancel: true }` es terminal. En cuanto cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
|
||||
- `message_sending`: devolver `{ cancel: false }` se trata como si no hubiera decisión (igual que omitir `cancel`), no como una anulación.
|
||||
|
||||
### Campos del objeto API
|
||||
|
||||
| Campo | Tipo | Descripción |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `api.id` | `string` | ID del plugin |
|
||||
| `api.name` | `string` | Nombre para mostrar |
|
||||
| `api.version` | `string?` | Versión del plugin (opcional) |
|
||||
| `api.description` | `string?` | Descripción del plugin (opcional) |
|
||||
| `api.source` | `string` | Ruta de origen del plugin |
|
||||
| `api.rootDir` | `string?` | Directorio raíz del plugin (opcional) |
|
||||
| `api.config` | `OpenClawConfig` | Instantánea de configuración actual (instantánea activa en memoria del tiempo de ejecución cuando está disponible) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Configuración específica del plugin desde `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Helpers de tiempo de ejecución](/es/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger con alcance (`debug`, `info`, `warn`, `error`) |
|
||||
| Campo | Tipo | Descripción |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Id del Plugin |
|
||||
| `api.name` | `string` | Nombre para mostrar |
|
||||
| `api.version` | `string?` | Versión del Plugin (opcional) |
|
||||
| `api.description` | `string?` | Descripción del Plugin (opcional) |
|
||||
| `api.source` | `string` | Ruta de origen del Plugin |
|
||||
| `api.rootDir` | `string?` | Directorio raíz del Plugin (opcional) |
|
||||
| `api.config` | `OpenClawConfig` | Instantánea actual de la configuración (instantánea activa del runtime en memoria cuando esté disponible) |
|
||||
| `api.pluginConfig` | `Record<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 inicio/configuración previa a la entrada completa |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Resuelve una ruta relativa a la raíz del plugin |
|
||||
|
||||
## Convención de módulos internos
|
||||
|
||||
@ -468,48 +482,48 @@ Dentro de tu plugin, usa archivos barrel locales para las importaciones internas
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Exportaciones públicas para consumidores externos
|
||||
runtime-api.ts # Exportaciones internas solo para tiempo de ejecución
|
||||
runtime-api.ts # Exportaciones internas solo para runtime
|
||||
index.ts # Punto de entrada del plugin
|
||||
setup-entry.ts # Entrada ligera solo para configuración (opcional)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Nunca importes tu propio plugin mediante `openclaw/plugin-sdk/<your-plugin>`
|
||||
desde código de producción. Enruta las importaciones internas mediante `./api.ts` o
|
||||
desde código de producción. Enruta las importaciones internas por `./api.ts` o
|
||||
`./runtime-api.ts`. La ruta del SDK es solo el contrato externo.
|
||||
</Warning>
|
||||
|
||||
Las superficies públicas de plugins incluidos cargadas mediante fachada (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` y archivos de entrada públicos similares) ahora prefieren la
|
||||
instantánea activa de configuración en tiempo de ejecución cuando OpenClaw ya se está ejecutando. Si aún no
|
||||
existe una instantánea de tiempo de ejecución, recurren a la configuración resuelta en disco.
|
||||
Las superficies públicas de plugins empaquetados cargadas mediante fachada (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` y archivos públicos de entrada similares) ahora prefieren la
|
||||
instantánea activa de configuración del runtime cuando OpenClaw ya está en ejecución. Si aún no existe ninguna
|
||||
instantánea de runtime, vuelven a la configuración resuelta en disco.
|
||||
|
||||
Los plugins de proveedor también pueden exponer un barrel de contrato local y acotado del plugin cuando un
|
||||
Los plugins de proveedor también pueden exponer un barrel de contrato local del plugin y más específico cuando un
|
||||
helper es intencionalmente específico del proveedor y todavía no pertenece a una subruta genérica del SDK.
|
||||
Ejemplo actual incluido: el proveedor Anthropic mantiene sus helpers de stream de Claude
|
||||
en su propia interfaz pública `api.ts` / `contract-api.ts` en lugar de
|
||||
Ejemplo empaquetado actual: el proveedor Anthropic mantiene sus helpers de stream de Claude
|
||||
en su propia superficie pública `api.ts` / `contract-api.ts` en lugar de
|
||||
promover la lógica de encabezados beta de Anthropic y `service_tier` a un contrato genérico
|
||||
`plugin-sdk/*`.
|
||||
|
||||
Otros ejemplos actuales incluidos:
|
||||
Otros ejemplos empaquetados actuales:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` exporta constructores de proveedor,
|
||||
helpers de modelos predeterminados y constructores de proveedores realtime
|
||||
helpers de modelo predeterminado y constructores de proveedor en tiempo real
|
||||
- `@openclaw/openrouter-provider`: `api.ts` exporta el constructor del proveedor además de
|
||||
helpers de onboarding/configuración
|
||||
helpers de incorporación/configuración
|
||||
|
||||
<Warning>
|
||||
El código de producción de extensiones también debería evitar importaciones de `openclaw/plugin-sdk/<other-plugin>`.
|
||||
El código de producción de extensiones también debe evitar las importaciones `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Si un helper es realmente compartido, promuévelo a una subruta neutral del SDK
|
||||
como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` u otra
|
||||
superficie orientada a capacidades, en lugar de acoplar dos plugins entre sí.
|
||||
superficie orientada a capacidades en lugar de acoplar dos plugins entre sí.
|
||||
</Warning>
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Puntos de entrada](/es/plugins/sdk-entrypoints) — opciones de `definePluginEntry` y `defineChannelPluginEntry`
|
||||
- [Helpers de tiempo de ejecución](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime`
|
||||
- [Configuración y config](/es/plugins/sdk-setup) — empaquetado, manifests, esquemas de configuración
|
||||
- [Helpers de runtime](/es/plugins/sdk-runtime) — referencia completa del espacio de nombres `api.runtime`
|
||||
- [Configuración y setup](/es/plugins/sdk-setup) — empaquetado, manifiestos, esquemas de configuración
|
||||
- [Pruebas](/es/plugins/sdk-testing) — utilidades de prueba y reglas de lint
|
||||
- [Migración del SDK](/es/plugins/sdk-migration) — migración desde superficies obsoletas
|
||||
- [Internos del plugin](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades
|
||||
- [Internals del Plugin](/es/plugins/architecture) — arquitectura profunda y modelo de capacidades
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T05:03:29Z"
|
||||
generated_at: "2026-04-18T04:59:38Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd
|
||||
source_hash: dbb2c70c82da7f6f12d90e25666635ff4147c52e8a94135e902d1de4f5cbccca
|
||||
source_path: refactor/qa.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Refactorización de QA
|
||||
|
||||
Estado: migración fundacional completada.
|
||||
Estado: se consolidó la migración fundacional.
|
||||
|
||||
## Objetivo
|
||||
|
||||
@ -18,17 +18,17 @@ Mover QA de OpenClaw de un modelo de definición dividida a una única fuente de
|
||||
|
||||
- metadatos de escenarios
|
||||
- prompts enviados al modelo
|
||||
- configuración y limpieza
|
||||
- lógica del harness
|
||||
- configuración y desmontaje
|
||||
- lógica del arnés
|
||||
- aserciones y criterios de éxito
|
||||
- artefactos e indicaciones para informes
|
||||
|
||||
El estado final deseado es un harness de QA genérico que cargue archivos potentes de definición de escenarios en lugar de codificar la mayor parte del comportamiento en TypeScript.
|
||||
El estado final deseado es un arnés de QA genérico que cargue archivos potentes de definición de escenarios en lugar de codificar la mayor parte del comportamiento en TypeScript.
|
||||
|
||||
## Estado actual
|
||||
|
||||
La fuente principal de verdad ahora vive en `qa/scenarios/index.md` más un archivo por
|
||||
escenario en `qa/scenarios/*.md`.
|
||||
escenario en `qa/scenarios/<theme>/*.md`.
|
||||
|
||||
Implementado:
|
||||
|
||||
@ -36,56 +36,56 @@ Implementado:
|
||||
- metadatos canónicos del paquete de QA
|
||||
- identidad del operador
|
||||
- misión inicial
|
||||
- `qa/scenarios/*.md`
|
||||
- un archivo Markdown por escenario
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
- un archivo markdown por escenario
|
||||
- metadatos del escenario
|
||||
- vinculaciones de handlers
|
||||
- enlaces de handlers
|
||||
- configuración de ejecución específica del escenario
|
||||
- `extensions/qa-lab/src/scenario-catalog.ts`
|
||||
- analizador del paquete Markdown + validación con zod
|
||||
- analizador del paquete markdown + validación con zod
|
||||
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
|
||||
- renderizado del plan a partir del paquete Markdown
|
||||
- renderizado del plan a partir del paquete markdown
|
||||
- `extensions/qa-lab/src/qa-agent-workspace.ts`
|
||||
- genera archivos de compatibilidad sembrados más `QA_SCENARIOS.md`
|
||||
- siembra archivos de compatibilidad generados más `QA_SCENARIOS.md`
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- selecciona escenarios ejecutables mediante vinculaciones de handlers definidas en Markdown
|
||||
- Protocolo del bus de QA + UI
|
||||
- selecciona escenarios ejecutables mediante enlaces de handlers definidos en markdown
|
||||
- Protocolo de bus de QA + UI
|
||||
- adjuntos en línea genéricos para renderizado de imagen/video/audio/archivo
|
||||
|
||||
Superficies divididas restantes:
|
||||
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- todavía posee la mayor parte de la lógica ejecutable de handlers personalizados
|
||||
- todavía mantiene la mayor parte de la lógica ejecutable personalizada de handlers
|
||||
- `extensions/qa-lab/src/report.ts`
|
||||
- todavía deriva la estructura del informe a partir de las salidas de tiempo de ejecución
|
||||
- todavía deriva la estructura del informe a partir de las salidas del runtime
|
||||
|
||||
Así que la división de la fuente de verdad está solucionada, pero la ejecución sigue estando mayormente respaldada por handlers en lugar de ser completamente declarativa.
|
||||
Así que la división de la fuente de verdad está resuelta, pero la ejecución sigue dependiendo en gran medida de handlers en lugar de ser totalmente declarativa.
|
||||
|
||||
## Cómo es la superficie real de escenarios
|
||||
## Cómo es realmente la superficie de escenarios
|
||||
|
||||
Al leer la suite actual se observan algunas clases distintas de escenarios.
|
||||
Leer la suite actual muestra algunas clases distintas de escenarios.
|
||||
|
||||
### Interacción simple
|
||||
|
||||
- línea base de canal
|
||||
- línea base de DM
|
||||
- línea base del canal
|
||||
- línea base de MD
|
||||
- seguimiento en hilo
|
||||
- cambio de modelo
|
||||
- continuación de aprobación
|
||||
- reacción/edición/eliminación
|
||||
|
||||
### Mutación de configuración y tiempo de ejecución
|
||||
### Mutación de configuración y runtime
|
||||
|
||||
- desactivación de Skills mediante parche de configuración
|
||||
- activación tras reinicio con aplicación de configuración
|
||||
- deshabilitación de Skill mediante parche de configuración
|
||||
- reactivación tras reinicio con config apply
|
||||
- cambio de capacidad tras reinicio de configuración
|
||||
- verificación de deriva del inventario de tiempo de ejecución
|
||||
- comprobación de deriva del inventario del runtime
|
||||
|
||||
### Aserciones de sistema de archivos y repositorio
|
||||
|
||||
- informe de descubrimiento de código/documentación
|
||||
- informe de descubrimiento de source/docs
|
||||
- compilar Lobster Invaders
|
||||
- búsqueda de artefactos de imagen generada
|
||||
- búsqueda de artefacto de imagen generado
|
||||
|
||||
### Orquestación de memoria
|
||||
|
||||
@ -93,57 +93,56 @@ Al leer la suite actual se observan algunas clases distintas de escenarios.
|
||||
- herramientas de memoria en contexto de canal
|
||||
- fallback ante fallo de memoria
|
||||
- clasificación de memoria de sesión
|
||||
- aislamiento de memoria de hilos
|
||||
- barrido de memory dreaming
|
||||
- aislamiento de memoria por hilo
|
||||
- barrido de Dreaming de memoria
|
||||
|
||||
### Integración de herramientas y plugins
|
||||
|
||||
- llamada MCP plugin-tools
|
||||
- visibilidad de Skills
|
||||
- instalación en caliente de Skills
|
||||
- generación de imágenes nativa
|
||||
- ida y vuelta de imágenes
|
||||
- comprensión de imágenes a partir de adjuntos
|
||||
- instalación dinámica de Skills
|
||||
- generación nativa de imágenes
|
||||
- roundtrip de imagen
|
||||
- comprensión de imagen desde adjunto
|
||||
|
||||
### Múltiples turnos y múltiples actores
|
||||
### Multiturno y multiactor
|
||||
|
||||
- transferencia a subagentes
|
||||
- síntesis fanout de subagentes
|
||||
- flujos tipo recuperación tras reinicio
|
||||
- transferencia a subagente
|
||||
- síntesis con fanout de subagentes
|
||||
- flujos de estilo de recuperación tras reinicio
|
||||
|
||||
Estas categorías importan porque impulsan los requisitos del DSL. Una lista plana de prompt + texto esperado no es suficiente.
|
||||
Estas categorías importan porque determinan los requisitos del DSL. Una lista plana de prompt + texto esperado no es suficiente.
|
||||
|
||||
## Dirección
|
||||
|
||||
### Fuente única de verdad
|
||||
|
||||
Usar `qa/scenarios/index.md` más `qa/scenarios/*.md` como la fuente de verdad
|
||||
creada.
|
||||
Usar `qa/scenarios/index.md` más `qa/scenarios/<theme>/*.md` como fuente de verdad redactada.
|
||||
|
||||
El paquete debe seguir siendo:
|
||||
|
||||
- legible por humanos en revisión
|
||||
- interpretable por máquinas
|
||||
- legible para humanos en revisión
|
||||
- interpretable por máquina
|
||||
- lo bastante rico para impulsar:
|
||||
- ejecución de la suite
|
||||
- bootstrap del espacio de trabajo de QA
|
||||
- arranque del espacio de trabajo de QA
|
||||
- metadatos de la UI de QA Lab
|
||||
- prompts de documentación/descubrimiento
|
||||
- generación de informes
|
||||
|
||||
### Formato de autoría preferido
|
||||
|
||||
Usar Markdown como formato de nivel superior, con YAML estructurado dentro de él.
|
||||
Usar markdown como formato de nivel superior, con YAML estructurado dentro.
|
||||
|
||||
Forma recomendada:
|
||||
|
||||
- frontmatter YAML
|
||||
- id
|
||||
- título
|
||||
- superficie
|
||||
- title
|
||||
- surface
|
||||
- tags
|
||||
- referencias de documentación
|
||||
- referencias de código
|
||||
- referencias a docs
|
||||
- referencias a código
|
||||
- anulaciones de modelo/proveedor
|
||||
- prerrequisitos
|
||||
- secciones en prosa
|
||||
@ -156,13 +155,13 @@ Forma recomendada:
|
||||
- assertions
|
||||
- cleanup
|
||||
|
||||
Esto proporciona:
|
||||
Esto aporta:
|
||||
|
||||
- mejor legibilidad en PR que un JSON gigante
|
||||
- contexto más rico que YAML puro
|
||||
- análisis estricto y validación con zod
|
||||
|
||||
El JSON sin procesar es aceptable solo como forma intermedia generada.
|
||||
El JSON sin procesar es aceptable solo como forma generada intermedia.
|
||||
|
||||
## Forma propuesta del archivo de escenario
|
||||
|
||||
@ -187,11 +186,11 @@ codeRefs:
|
||||
- src/gateway/chat-attachments.ts
|
||||
---
|
||||
|
||||
# Objetivo
|
||||
# Objective
|
||||
|
||||
Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimiento.
|
||||
Verify generated media is reattached on the follow-up turn.
|
||||
|
||||
# Configuración
|
||||
# Setup
|
||||
|
||||
```yaml scenario.setup
|
||||
- action: config.patch
|
||||
@ -204,7 +203,7 @@ Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimie
|
||||
key: agent:qa:image-roundtrip
|
||||
```
|
||||
|
||||
# Pasos
|
||||
# Steps
|
||||
|
||||
```yaml scenario.steps
|
||||
- action: agent.send
|
||||
@ -223,7 +222,7 @@ Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimie
|
||||
- fromArtifact: lighthouseImage
|
||||
```
|
||||
|
||||
# Expectativa
|
||||
# Expect
|
||||
|
||||
```yaml scenario.expect
|
||||
- assert: outbound.textIncludes
|
||||
@ -237,9 +236,9 @@ Verificar que los medios generados se vuelvan a adjuntar en el turno de seguimie
|
||||
```
|
||||
````
|
||||
|
||||
## Capacidades del runner que debe cubrir el DSL
|
||||
## Capacidades del ejecutor que el DSL debe cubrir
|
||||
|
||||
Según la suite actual, el runner genérico necesita más que ejecución de prompts.
|
||||
Basándose en la suite actual, el ejecutor genérico necesita más que ejecución de prompts.
|
||||
|
||||
### Acciones de entorno y configuración
|
||||
|
||||
@ -250,14 +249,14 @@ Según la suite actual, el runner genérico necesita más que ejecución de prom
|
||||
- `thread.create`
|
||||
- `workspace.writeSkill`
|
||||
|
||||
### Acciones de turnos del agente
|
||||
### Acciones de turno del agente
|
||||
|
||||
- `agent.send`
|
||||
- `agent.wait`
|
||||
- `bus.injectInbound`
|
||||
- `bus.injectOutbound`
|
||||
|
||||
### Acciones de configuración y tiempo de ejecución
|
||||
### Acciones de configuración y runtime
|
||||
|
||||
- `config.get`
|
||||
- `config.patch`
|
||||
@ -275,7 +274,7 @@ Según la suite actual, el runner genérico necesita más que ejecución de prom
|
||||
- `artifact.captureGeneratedImage`
|
||||
- `artifact.capturePath`
|
||||
|
||||
### Acciones de memoria y cron
|
||||
### Acciones de memoria y Cron
|
||||
|
||||
- `memory.indexForce`
|
||||
- `memory.searchCli`
|
||||
@ -314,48 +313,48 @@ Ejemplos de la suite actual:
|
||||
- crear un hilo y luego reutilizar `threadId`
|
||||
- crear una sesión y luego reutilizar `sessionKey`
|
||||
- generar una imagen y luego adjuntar el archivo en el siguiente turno
|
||||
- generar una cadena de marcador de activación y luego afirmar que aparece más tarde
|
||||
- generar una cadena de marcador de activación y luego afirmar que aparezca después
|
||||
|
||||
Capacidades necesarias:
|
||||
|
||||
- `saveAs`
|
||||
- `${vars.name}`
|
||||
- `${artifacts.name}`
|
||||
- referencias tipadas para rutas, claves de sesión, ids de hilos, marcadores y salidas de herramientas
|
||||
- referencias tipadas para rutas, claves de sesión, ids de hilo, marcadores, salidas de herramientas
|
||||
|
||||
Sin soporte para variables, el harness seguirá filtrando la lógica de los escenarios de vuelta a TypeScript.
|
||||
Sin soporte para variables, el arnés seguirá filtrando la lógica del escenario de vuelta a TypeScript.
|
||||
|
||||
## Qué debería permanecer como escape hatches
|
||||
## Qué debería mantenerse como vías de escape
|
||||
|
||||
Un runner declarativo completamente puro no es realista en la fase 1.
|
||||
Un ejecutor declarativo completamente puro no es realista en la fase 1.
|
||||
|
||||
Algunos escenarios son inherentemente intensivos en orquestación:
|
||||
Algunos escenarios son intrínsecamente intensivos en orquestación:
|
||||
|
||||
- barrido de memory dreaming
|
||||
- activación tras reinicio con aplicación de configuración
|
||||
- barrido de Dreaming de memoria
|
||||
- reactivación tras reinicio con config apply
|
||||
- cambio de capacidad tras reinicio de configuración
|
||||
- resolución de artefactos de imagen generada por marca de tiempo/ruta
|
||||
- resolución de artefactos de imagen generados por marca de tiempo/ruta
|
||||
- evaluación de informes de descubrimiento
|
||||
|
||||
Por ahora, estos deberían usar handlers personalizados explícitos.
|
||||
|
||||
Regla recomendada:
|
||||
|
||||
- 85-90% declarativo
|
||||
- pasos de `customHandler` explícitos para el resto difícil
|
||||
- 85-90 % declarativo
|
||||
- pasos `customHandler` explícitos para la parte difícil restante
|
||||
- solo handlers personalizados con nombre y documentados
|
||||
- nada de código en línea anónimo en el archivo de escenario
|
||||
- nada de código en línea anónimo en el archivo del escenario
|
||||
|
||||
Eso mantiene limpio el motor genérico y al mismo tiempo permite seguir avanzando.
|
||||
Eso mantiene limpio el motor genérico y aun así permite avanzar.
|
||||
|
||||
## Cambio de arquitectura
|
||||
|
||||
### Actual
|
||||
|
||||
El Markdown de escenarios ya es la fuente de verdad para:
|
||||
El markdown de escenarios ya es la fuente de verdad para:
|
||||
|
||||
- ejecución de la suite
|
||||
- archivos de bootstrap del espacio de trabajo
|
||||
- archivos de arranque del espacio de trabajo
|
||||
- catálogo de escenarios de la UI de QA Lab
|
||||
- metadatos de informes
|
||||
- prompts de descubrimiento
|
||||
@ -372,11 +371,11 @@ Compatibilidad generada:
|
||||
|
||||
Hecho.
|
||||
|
||||
- se agregó `qa/scenarios/index.md`
|
||||
- se dividieron los escenarios en `qa/scenarios/*.md`
|
||||
- se agregó un analizador para el contenido del paquete Markdown YAML con nombre
|
||||
- se añadió `qa/scenarios/index.md`
|
||||
- se dividieron los escenarios en `qa/scenarios/<theme>/*.md`
|
||||
- se añadió un analizador para el contenido nombrado del paquete markdown YAML
|
||||
- se validó con zod
|
||||
- se cambiaron los consumidores al paquete analizado
|
||||
- se cambiaron los consumidores para usar el paquete analizado
|
||||
- se eliminaron `qa/seed-scenarios.json` y `qa/QA_KICKOFF_TASK.md` a nivel de repositorio
|
||||
|
||||
### Fase 2: motor genérico
|
||||
@ -393,49 +392,49 @@ Entregable:
|
||||
|
||||
- el motor ejecuta escenarios declarativos simples
|
||||
|
||||
Comenzar con escenarios que son principalmente prompt + espera + aserción:
|
||||
Empezar con escenarios que son mayormente prompt + espera + aserción:
|
||||
|
||||
- seguimiento en hilo
|
||||
- comprensión de imágenes a partir de adjuntos
|
||||
- comprensión de imagen desde adjunto
|
||||
- visibilidad e invocación de Skills
|
||||
- línea base de canal
|
||||
- línea base del canal
|
||||
|
||||
Entregable:
|
||||
|
||||
- los primeros escenarios reales definidos en Markdown funcionando a través del motor genérico
|
||||
- primeros escenarios reales definidos en markdown enviados a producción a través del motor genérico
|
||||
|
||||
### Fase 4: migrar escenarios intermedios
|
||||
|
||||
- ida y vuelta de generación de imágenes
|
||||
- roundtrip de generación de imagen
|
||||
- herramientas de memoria en contexto de canal
|
||||
- clasificación de memoria de sesión
|
||||
- transferencia a subagentes
|
||||
- síntesis fanout de subagentes
|
||||
- transferencia a subagente
|
||||
- síntesis con fanout de subagentes
|
||||
|
||||
Entregable:
|
||||
|
||||
- variables, artefactos, aserciones de herramientas y aserciones de logs de solicitudes demostradas
|
||||
- variables, artefactos, aserciones de herramientas y aserciones de request-log demostradas
|
||||
|
||||
### Fase 5: mantener los escenarios difíciles en handlers personalizados
|
||||
|
||||
- barrido de memory dreaming
|
||||
- activación tras reinicio con aplicación de configuración
|
||||
- barrido de Dreaming de memoria
|
||||
- reactivación tras reinicio con config apply
|
||||
- cambio de capacidad tras reinicio de configuración
|
||||
- deriva del inventario de tiempo de ejecución
|
||||
- deriva del inventario del runtime
|
||||
|
||||
Entregable:
|
||||
|
||||
- el mismo formato de autoría, pero con bloques explícitos de pasos personalizados donde sea necesario
|
||||
- mismo formato de autoría, pero con bloques de pasos personalizados explícitos donde sea necesario
|
||||
|
||||
### Fase 6: eliminar el mapa de escenarios codificado
|
||||
|
||||
Una vez que la cobertura del paquete sea lo bastante buena:
|
||||
|
||||
- eliminar la mayor parte de la ramificación TypeScript específica por escenario de `extensions/qa-lab/src/suite.ts`
|
||||
- eliminar la mayor parte del branching específico de escenarios en TypeScript de `extensions/qa-lab/src/suite.ts`
|
||||
|
||||
## Slack falso / soporte para contenido multimedia enriquecido
|
||||
## Soporte de Fake Slack / medios enriquecidos
|
||||
|
||||
El bus de QA actual está orientado primero al texto.
|
||||
El bus de QA actual está orientado principalmente a texto.
|
||||
|
||||
Archivos relevantes:
|
||||
|
||||
@ -455,7 +454,7 @@ Todavía no modela adjuntos multimedia en línea.
|
||||
|
||||
### Contrato de transporte necesario
|
||||
|
||||
Agregar un modelo genérico de adjuntos del bus de QA:
|
||||
Añadir un modelo genérico de adjuntos del bus de QA:
|
||||
|
||||
```ts
|
||||
type QaBusAttachment = {
|
||||
@ -474,7 +473,7 @@ type QaBusAttachment = {
|
||||
};
|
||||
```
|
||||
|
||||
Luego agregar `attachments?: QaBusAttachment[]` a:
|
||||
Luego añadir `attachments?: QaBusAttachment[]` a:
|
||||
|
||||
- `QaBusMessage`
|
||||
- `QaBusInboundMessageInput`
|
||||
@ -482,15 +481,15 @@ Luego agregar `attachments?: QaBusAttachment[]` a:
|
||||
|
||||
### Por qué genérico primero
|
||||
|
||||
No construir un modelo de multimedia solo para Slack.
|
||||
No construyas un modelo de medios solo para Slack.
|
||||
|
||||
En su lugar:
|
||||
|
||||
- un modelo genérico de transporte de QA
|
||||
- múltiples renderizadores sobre él
|
||||
- el chat actual de QA Lab
|
||||
- un futuro Slack falso web
|
||||
- cualquier otra vista de transporte falsa
|
||||
- un modelo de transporte de QA genérico
|
||||
- múltiples renderizadores encima de él
|
||||
- chat actual de QA Lab
|
||||
- futuro fake Slack web
|
||||
- cualquier otra vista de transporte simulado
|
||||
|
||||
Esto evita lógica duplicada y permite que los escenarios multimedia sigan siendo agnósticos al transporte.
|
||||
|
||||
@ -501,15 +500,15 @@ Actualizar la UI de QA para renderizar:
|
||||
- vista previa de imagen en línea
|
||||
- reproductor de audio en línea
|
||||
- reproductor de video en línea
|
||||
- chip de adjunto de archivo
|
||||
- chip de archivo adjunto
|
||||
|
||||
La UI actual ya puede renderizar hilos y reacciones, por lo que el renderizado de adjuntos debería integrarse sobre el mismo modelo de tarjeta de mensaje.
|
||||
La UI actual ya puede renderizar hilos y reacciones, así que el renderizado de adjuntos debería añadirse sobre el mismo modelo de tarjeta de mensaje.
|
||||
|
||||
### Trabajo de escenarios habilitado por el transporte multimedia
|
||||
|
||||
Una vez que los adjuntos fluyan por el bus de QA, podremos agregar escenarios de chat falso más ricos:
|
||||
Una vez que los adjuntos fluyan por el bus de QA, podremos añadir escenarios de chat simulado más ricos:
|
||||
|
||||
- respuesta con imagen en línea en Slack falso
|
||||
- respuesta con imagen en línea en fake Slack
|
||||
- comprensión de adjuntos de audio
|
||||
- comprensión de adjuntos de video
|
||||
- orden mixto de adjuntos
|
||||
@ -519,22 +518,22 @@ Una vez que los adjuntos fluyan por el bus de QA, podremos agregar escenarios de
|
||||
|
||||
El siguiente bloque de implementación debería ser:
|
||||
|
||||
1. agregar el cargador de escenarios Markdown + esquema zod
|
||||
2. generar el catálogo actual a partir de Markdown
|
||||
1. añadir cargador de escenarios markdown + esquema zod
|
||||
2. generar el catálogo actual a partir de markdown
|
||||
3. migrar primero algunos escenarios simples
|
||||
4. agregar compatibilidad genérica con adjuntos del bus de QA
|
||||
5. renderizar imágenes en línea en la UI de QA
|
||||
4. añadir soporte genérico para adjuntos en el bus de QA
|
||||
5. renderizar imagen en línea en la UI de QA
|
||||
6. luego ampliar a audio y video
|
||||
|
||||
Este es el camino más pequeño que demuestra ambos objetivos:
|
||||
|
||||
- QA genérico definido en Markdown
|
||||
- superficies de mensajería falsa más ricas
|
||||
- QA genérico definido en markdown
|
||||
- superficies de mensajería simulada más ricas
|
||||
|
||||
## Preguntas abiertas
|
||||
|
||||
- si los archivos de escenarios deberían permitir plantillas de prompts Markdown incrustadas con interpolación de variables
|
||||
- si setup/cleanup deberían ser secciones con nombre o simplemente listas ordenadas de acciones
|
||||
- si los archivos de escenarios deberían permitir plantillas de prompt markdown incrustadas con interpolación de variables
|
||||
- si setup/cleanup deberían ser secciones con nombre o simplemente listas de acciones ordenadas
|
||||
- si las referencias a artefactos deberían estar fuertemente tipadas en el esquema o basadas en cadenas
|
||||
- si los handlers personalizados deberían vivir en un único registro o en registros por superficie
|
||||
- si los handlers personalizados deberían vivir en un solo registro o en registros por superficie
|
||||
- si el archivo de compatibilidad JSON generado debería seguir versionado durante la migración
|
||||
|
||||
Loading…
Reference in New Issue
Block a user