From c20291d4dc1fb815dedac35430f72219cb7ad5aa Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 12 Apr 2026 00:21:08 +0000 Subject: [PATCH] chore(i18n): refresh es translations --- docs/es/channels/msteams.md | 577 +++++++++++++++++---------- docs/es/plugins/sdk-agent-harness.md | 196 ++++----- docs/es/providers/openai.md | 260 ++++++------ 3 files changed, 587 insertions(+), 446 deletions(-) diff --git a/docs/es/channels/msteams.md b/docs/es/channels/msteams.md index 5585df544..44787b349 100644 --- a/docs/es/channels/msteams.md +++ b/docs/es/channels/msteams.md @@ -1,44 +1,43 @@ --- read_when: - - Trabajar en funcionalidades del canal de Microsoft Teams -summary: Estado del soporte del bot de Microsoft Teams, capacidades y configuración + - Trabajando en las funciones del canal de Microsoft Teams +summary: Estado de soporte del bot de Microsoft Teams, capacidades y configuración title: Microsoft Teams x-i18n: - generated_at: "2026-04-05T12:37:19Z" + generated_at: "2026-04-12T00:19:02Z" model: gpt-5.4 provider: openai - source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf + source_hash: 3e6841a618fb030e4c2029b3652d45dedd516392e2ae17309ff46b93648ffb79 source_path: channels/msteams.md workflow: 15 --- # Microsoft Teams -> "Abandonad toda esperanza quienes entráis aquí." +> "Abandonad toda esperanza, quienes entráis aquí." -Actualizado: 2026-01-21 +Actualizado: 2026-03-25 -Estado: se admiten texto + archivos adjuntos en MD; el envío de archivos en canales/grupos requiere `sharePointSiteId` + permisos de Graph (consulta [Envío de archivos en chats grupales](#envío-de-archivos-en-chats-grupales)). Las encuestas se envían mediante Adaptive Cards. Las acciones de mensaje exponen `upload-file` explícito para envíos centrados primero en archivos. +Estado: se admiten texto + archivos adjuntos en mensajes directos; el envío de archivos en canales/grupos requiere `sharePointSiteId` + permisos de Graph (consulta [Envío de archivos en chats grupales](#sending-files-in-group-chats)). Las encuestas se envían mediante Adaptive Cards. Las acciones de mensaje exponen `upload-file` explícito para envíos centrados primero en archivos. -## Plugin integrado +## Plugin incluido -Microsoft Teams se incluye como plugin integrado en las versiones actuales de OpenClaw, por lo que no -se requiere una instalación aparte en la compilación empaquetada normal. +Microsoft Teams se distribuye como un plugin incluido en las versiones actuales de OpenClaw, por lo que no se requiere una instalación independiente en la compilación empaquetada normal. -Si estás en una compilación anterior o en una instalación personalizada que excluye Teams integrado, +Si estás en una compilación anterior o en una instalación personalizada que excluye Teams incluido, instálalo manualmente: ```bash openclaw plugins install @openclaw/msteams ``` -Copia local (al ejecutarse desde un repositorio git): +Checkout local (al ejecutarlo desde un repositorio git): ```bash openclaw plugins install ./path/to/local/msteams-plugin ``` -Detalles: [Plugins](/tools/plugin) +Detalles: [Plugins](/es/tools/plugin) ## Configuración rápida (principiante) @@ -47,10 +46,10 @@ Detalles: [Plugins](/tools/plugin) - Las instalaciones antiguas/personalizadas pueden añadirlo manualmente con los comandos anteriores. 2. Crea un **Azure Bot** (App ID + secreto de cliente + tenant ID). 3. Configura OpenClaw con esas credenciales. -4. Expón `/api/messages` (puerto 3978 de forma predeterminada) mediante una URL pública o túnel. +4. Expón `/api/messages` (puerto 3978 de forma predeterminada) mediante una URL pública o un túnel. 5. Instala el paquete de la aplicación de Teams e inicia el gateway. -Configuración mínima: +Configuración mínima (secreto de cliente): ```json5 { @@ -66,13 +65,15 @@ Configuración mínima: } ``` -Nota: los chats grupales están bloqueados de forma predeterminada (`channels.msteams.groupPolicy: "allowlist"`). Para permitir respuestas en grupos, establece `channels.msteams.groupAllowFrom` (o usa `groupPolicy: "open"` para permitir a cualquier miembro, con control por mención). +Para implementaciones de producción, considera usar [autenticación federada](#federated-authentication-certificate--managed-identity) (certificado o identidad administrada) en lugar de secretos de cliente. + +Nota: los chats grupales están bloqueados de forma predeterminada (`channels.msteams.groupPolicy: "allowlist"`). Para permitir respuestas en grupo, establece `channels.msteams.groupAllowFrom` (o usa `groupPolicy: "open"` para permitir cualquier miembro, con restricción por mención). ## Objetivos -- Hablar con OpenClaw mediante MD de Teams, chats grupales o canales. +- Hablar con OpenClaw mediante mensajes directos de Teams, chats grupales o canales. - Mantener el enrutamiento determinista: las respuestas siempre vuelven al canal por el que llegaron. -- Aplicar un comportamiento de canal seguro de forma predeterminada (menciones obligatorias salvo que se configure lo contrario). +- Usar un comportamiento de canal seguro de forma predeterminada (se requieren menciones salvo que se configure lo contrario). ## Escrituras de configuración @@ -86,20 +87,20 @@ Desactívalo con: } ``` -## Control de acceso (MD + grupos) +## Control de acceso (mensajes directos + grupos) -**Acceso por MD** +**Acceso a mensajes directos** - Predeterminado: `channels.msteams.dmPolicy = "pairing"`. Los remitentes desconocidos se ignoran hasta que se aprueban. - `channels.msteams.allowFrom` debe usar IDs de objeto AAD estables. -- Los UPN/nombres para mostrar son mutables; la coincidencia directa está deshabilitada de forma predeterminada y solo se habilita con `channels.msteams.dangerouslyAllowNameMatching: true`. +- Los UPN/nombres para mostrar son mutables; la coincidencia directa está desactivada de forma predeterminada y solo se habilita con `channels.msteams.dangerouslyAllowNameMatching: true`. - El asistente puede resolver nombres a IDs mediante Microsoft Graph cuando las credenciales lo permiten. -**Acceso por grupo** +**Acceso a grupos** -- Predeterminado: `channels.msteams.groupPolicy = "allowlist"` (bloqueado a menos que añadas `groupAllowFrom`). Usa `channels.defaults.groupPolicy` para anular el valor predeterminado cuando no esté establecido. +- Predeterminado: `channels.msteams.groupPolicy = "allowlist"` (bloqueado a menos que añadas `groupAllowFrom`). Usa `channels.defaults.groupPolicy` para sobrescribir el valor predeterminado cuando no esté establecido. - `channels.msteams.groupAllowFrom` controla qué remitentes pueden activar en chats grupales/canales (recurre a `channels.msteams.allowFrom`). -- Establece `groupPolicy: "open"` para permitir a cualquier miembro (aun así, con control por mención de forma predeterminada). +- Establece `groupPolicy: "open"` para permitir cualquier miembro (aun así, con restricción por mención de forma predeterminada). - Para no permitir **ningún canal**, establece `channels.msteams.groupPolicy: "disabled"`. Ejemplo: @@ -115,14 +116,14 @@ Ejemplo: } ``` -**Teams + lista de permitidos de canales** +**Lista de permitidos de Teams + canal** -- Limita las respuestas en grupos/canales enumerando equipos y canales en `channels.msteams.teams`. +- Limita las respuestas de grupo/canal listando equipos y canales en `channels.msteams.teams`. - Las claves deben usar IDs estables de equipo e IDs de conversación de canal. -- Cuando `groupPolicy="allowlist"` y hay una lista de permitidos de equipos, solo se aceptan los equipos/canales enumerados (con control por mención). -- El asistente de configuración acepta entradas `Team/Channel` y las almacena por ti. -- Al iniciarse, OpenClaw resuelve los nombres de equipos/canales y de usuarios de la lista de permitidos a IDs (cuando los permisos de Graph lo permiten) - y registra la asignación; los nombres de equipos/canales no resueltos se conservan tal como se escribieron, pero se ignoran para el enrutamiento de forma predeterminada a menos que `channels.msteams.dangerouslyAllowNameMatching: true` esté habilitado. +- Cuando `groupPolicy="allowlist"` y hay una lista de permitidos de equipos presente, solo se aceptan los equipos/canales listados (con restricción por mención). +- El asistente de configuración acepta entradas `Team/Channel` y las guarda por ti. +- Al iniciar, OpenClaw resuelve nombres de equipo/canal y nombres de usuario de la lista de permitidos a IDs (cuando los permisos de Graph lo permiten) + y registra la asignación; los nombres de equipo/canal no resueltos se conservan tal como se escribieron, pero se ignoran para el enrutamiento de forma predeterminada a menos que `channels.msteams.dangerouslyAllowNameMatching: true` esté habilitado. Ejemplo: @@ -149,36 +150,36 @@ Ejemplo: - Las versiones empaquetadas actuales de OpenClaw ya lo incluyen. - Las instalaciones antiguas/personalizadas pueden añadirlo manualmente con los comandos anteriores. 2. Crea un **Azure Bot** (App ID + secreto + tenant ID). -3. Crea un **paquete de aplicación de Teams** que haga referencia al bot e incluya los permisos RSC indicados a continuación. -4. Carga/instala la aplicación de Teams en un equipo (o en ámbito personal para MD). +3. Crea un **paquete de aplicación de Teams** que haga referencia al bot e incluya los permisos RSC de abajo. +4. Carga/instala la aplicación de Teams en un equipo (o en alcance personal para mensajes directos). 5. Configura `msteams` en `~/.openclaw/openclaw.json` (o variables de entorno) e inicia el gateway. -6. El gateway escucha el tráfico de webhook de Bot Framework en `/api/messages` de forma predeterminada. +6. El gateway escucha el tráfico del webhook de Bot Framework en `/api/messages` de forma predeterminada. ## Configuración de Azure Bot (requisitos previos) -Antes de configurar OpenClaw, necesitas crear un recurso de Azure Bot. +Antes de configurar OpenClaw, necesitas crear un recurso Azure Bot. ### Paso 1: Crear Azure Bot -1. Ve a [Crear Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) -2. Completa la pestaña **Básico**: +1. Ve a [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) +2. Completa la pestaña **Basics**: | Campo | Valor | | ------------------ | -------------------------------------------------------- | - | **Identificador del bot** | El nombre de tu bot, p. ej., `openclaw-msteams` (debe ser único) | - | **Suscripción** | Selecciona tu suscripción de Azure | - | **Grupo de recursos** | Crea uno nuevo o usa uno existente | - | **Plan de precios** | **Gratis** para desarrollo/pruebas | - | **Tipo de aplicación** | **Single Tenant** (recomendado; consulta la nota abajo) | - | **Tipo de creación** | **Create new Microsoft App ID** | + | **Bot handle** | El nombre de tu bot, p. ej., `openclaw-msteams` (debe ser único) | + | **Subscription** | Selecciona tu suscripción de Azure | + | **Resource group** | Crea uno nuevo o usa uno existente | + | **Pricing tier** | **Free** para desarrollo/pruebas | + | **Type of App** | **Single Tenant** (recomendado: consulta la nota abajo) | + | **Creation type** | **Create new Microsoft App ID** | -> **Aviso de retirada:** La creación de nuevos bots multiinquilino quedó obsoleta después del 2025-07-31. Usa **Single Tenant** para bots nuevos. +> **Aviso de retirada:** La creación de nuevos bots multi-tenant quedó obsoleta después del 2025-07-31. Usa **Single Tenant** para bots nuevos. -3. Haz clic en **Revisar + crear** → **Crear** (espera ~1-2 minutos) +3. Haz clic en **Review + create** → **Create** (espera ~1-2 minutos) ### Paso 2: Obtener credenciales -1. Ve a tu recurso de Azure Bot → **Configuración** +1. Ve a tu recurso Azure Bot → **Configuration** 2. Copia **Microsoft App ID** → este es tu `appId` 3. Haz clic en **Manage Password** → ve al registro de la aplicación 4. En **Certificates & secrets** → **New client secret** → copia el **Value** → este es tu `appPassword` @@ -186,26 +187,168 @@ Antes de configurar OpenClaw, necesitas crear un recurso de Azure Bot. ### Paso 3: Configurar el endpoint de mensajería -1. En Azure Bot → **Configuración** -2. Establece **Messaging endpoint** en la URL de tu webhook: +1. En Azure Bot → **Configuration** +2. Establece **Messaging endpoint** en tu URL de webhook: - Producción: `https://your-domain.com/api/messages` - - Desarrollo local: usa un túnel (consulta [Desarrollo local](#desarrollo-local-túneles) abajo) + - Desarrollo local: usa un túnel (consulta [Desarrollo local](#local-development-tunneling) abajo) -### Paso 4: Habilitar el canal Teams +### Paso 4: Habilitar el canal de Teams 1. En Azure Bot → **Channels** -2. Haz clic en **Microsoft Teams** → Configurar → Guardar -3. Acepta los términos del servicio +2. Haz clic en **Microsoft Teams** → Configure → Save +3. Acepta las Condiciones del servicio + +## Autenticación federada (certificado + identidad administrada) + +> Añadido en 2026.3.24 + +Para implementaciones de producción, OpenClaw admite **autenticación federada** como alternativa más segura a los secretos de cliente. Hay dos métodos disponibles: + +### Opción A: autenticación basada en certificado + +Usa un certificado PEM registrado con el registro de tu aplicación de Entra ID. + +**Configuración:** + +1. Genera u obtén un certificado (formato PEM con clave privada). +2. En Entra ID → App Registration → **Certificates & secrets** → **Certificates** → carga el certificado público. + +**Config:** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + certificatePath: "/path/to/cert.pem", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Variables de entorno:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem` + +### Opción B: Azure Managed Identity + +Usa Azure Managed Identity para autenticación sin contraseña. Esto es ideal para implementaciones en infraestructura de Azure (AKS, App Service, máquinas virtuales de Azure) donde hay una identidad administrada disponible. + +**Cómo funciona:** + +1. El pod/VM del bot tiene una identidad administrada (asignada por el sistema o por el usuario). +2. Una **credencial de identidad federada** vincula la identidad administrada con el registro de la aplicación de Entra ID. +3. En tiempo de ejecución, OpenClaw usa `@azure/identity` para adquirir tokens desde el endpoint Azure IMDS (`169.254.169.254`). +4. El token se pasa al SDK de Teams para la autenticación del bot. + +**Requisitos previos:** + +- Infraestructura de Azure con identidad administrada habilitada (identidad de carga de trabajo de AKS, App Service, VM) +- Credencial de identidad federada creada en el registro de la aplicación de Entra ID +- Acceso de red a IMDS (`169.254.169.254:80`) desde el pod/VM + +**Config (identidad administrada asignada por el sistema):** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Config (identidad administrada asignada por el usuario):** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + managedIdentityClientId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Variables de entorno:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_USE_MANAGED_IDENTITY=true` +- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=` (solo para identidades asignadas por el usuario) + +### Configuración de identidad de carga de trabajo de AKS + +Para implementaciones de AKS que usan identidad de carga de trabajo: + +1. **Habilita la identidad de carga de trabajo** en tu clúster de AKS. +2. **Crea una credencial de identidad federada** en el registro de la aplicación de Entra ID: + + ```bash + az ad app federated-credential create --id --parameters '{ + "name": "my-bot-workload-identity", + "issuer": "", + "subject": "system:serviceaccount::", + "audiences": ["api://AzureADTokenExchange"] + }' + ``` + +3. **Anota la cuenta de servicio de Kubernetes** con el client ID de la aplicación: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: my-bot-sa + annotations: + azure.workload.identity/client-id: "" + ``` + +4. **Etiqueta el pod** para la inyección de identidad de carga de trabajo: + + ```yaml + metadata: + labels: + azure.workload.identity/use: "true" + ``` + +5. **Asegura el acceso de red** a IMDS (`169.254.169.254`) — si usas NetworkPolicy, añade una regla de salida que permita tráfico a `169.254.169.254/32` en el puerto 80. + +### Comparación de tipos de autenticación + +| Método | Configuración | Ventajas | Desventajas | +| -------------------- | ---------------------------------------------- | ---------------------------------- | ------------------------------------- | +| **Secreto de cliente** | `appPassword` | Configuración simple | Requiere rotación de secretos, menos seguro | +| **Certificado** | `authType: "federated"` + `certificatePath` | No hay secreto compartido por la red | Sobrecarga de gestión de certificados | +| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | Sin contraseña, sin secretos que gestionar | Requiere infraestructura de Azure | + +**Comportamiento predeterminado:** Cuando `authType` no está establecido, OpenClaw usa autenticación con secreto de cliente de forma predeterminada. Las configuraciones existentes siguen funcionando sin cambios. ## Desarrollo local (túneles) -Teams no puede acceder a `localhost`. Usa un túnel para el desarrollo local: +Teams no puede llegar a `localhost`. Usa un túnel para desarrollo local: **Opción A: ngrok** ```bash ngrok http 3978 -# Copia la URL https, por ejemplo, https://abc123.ngrok.io +# Copia la URL https, p. ej., https://abc123.ngrok.io # Establece el endpoint de mensajería en: https://abc123.ngrok.io/api/messages ``` @@ -213,35 +356,35 @@ ngrok http 3978 ```bash tailscale funnel 3978 -# Usa tu URL de Tailscale Funnel como endpoint de mensajería +# Usa tu URL de funnel de Tailscale como endpoint de mensajería ``` ## Teams Developer Portal (alternativa) -En lugar de crear manualmente un ZIP de manifiesto, puedes usar el [Teams Developer Portal](https://dev.teams.microsoft.com/apps): +En lugar de crear manualmente un ZIP del manifiesto, puedes usar el [Teams Developer Portal](https://dev.teams.microsoft.com/apps): 1. Haz clic en **+ New app** 2. Completa la información básica (nombre, descripción, información del desarrollador) 3. Ve a **App features** → **Bot** -4. Selecciona **Enter a bot ID manually** y pega tu Azure Bot App ID -5. Marca los ámbitos: **Personal**, **Team**, **Group Chat** +4. Selecciona **Enter a bot ID manually** y pega el App ID de tu Azure Bot +5. Marca los alcances: **Personal**, **Team**, **Group Chat** 6. Haz clic en **Distribute** → **Download app package** 7. En Teams: **Apps** → **Manage your apps** → **Upload a custom app** → selecciona el ZIP -Esto suele ser más sencillo que editar manualmente manifiestos JSON. +Esto suele ser más fácil que editar manifiestos JSON a mano. ## Probar el bot **Opción A: Azure Web Chat (verifica primero el webhook)** -1. En Azure Portal → tu recurso de Azure Bot → **Test in Web Chat** -2. Envía un mensaje: deberías ver una respuesta -3. Esto confirma que tu endpoint de webhook funciona antes de la configuración de Teams +1. En Azure Portal → tu recurso Azure Bot → **Test in Web Chat** +2. Envía un mensaje; deberías ver una respuesta +3. Esto confirma que tu endpoint de webhook funciona antes de configurar Teams **Opción B: Teams (después de instalar la aplicación)** 1. Instala la aplicación de Teams (carga lateral o catálogo de la organización) -2. Busca el bot en Teams y envía un MD +2. Encuentra el bot en Teams y envíale un mensaje directo 3. Revisa los registros del gateway para ver la actividad entrante ## Configuración (mínima, solo texto) @@ -250,21 +393,21 @@ Esto suele ser más sencillo que editar manualmente manifiestos JSON. - Las versiones empaquetadas actuales de OpenClaw ya lo incluyen. - Las instalaciones antiguas/personalizadas pueden añadirlo manualmente: - Desde npm: `openclaw plugins install @openclaw/msteams` - - Desde una copia local: `openclaw plugins install ./path/to/local/msteams-plugin` + - Desde un checkout local: `openclaw plugins install ./path/to/local/msteams-plugin` 2. **Registro del bot** - Crea un Azure Bot (consulta arriba) y anota: - App ID - - Secreto de cliente (contraseña de la app) + - Secreto de cliente (contraseña de la aplicación) - Tenant ID (single-tenant) 3. **Manifiesto de la aplicación de Teams** - Incluye una entrada `bot` con `botId = `. - - Ámbitos: `personal`, `team`, `groupChat`. - - `supportsFiles: true` (obligatorio para el manejo de archivos en ámbito personal). + - Alcances: `personal`, `team`, `groupChat`. + - `supportsFiles: true` (obligatorio para el manejo de archivos en el alcance personal). - Añade permisos RSC (abajo). - Crea iconos: `outline.png` (32x32) y `color.png` (192x192). - - Comprime los tres archivos juntos: `manifest.json`, `outline.png`, `color.png`. + - Comprime juntos los tres archivos: `manifest.json`, `outline.png`, `color.png`. 4. **Configura OpenClaw** @@ -286,41 +429,46 @@ Esto suele ser más sencillo que editar manualmente manifiestos JSON. - `MSTEAMS_APP_ID` - `MSTEAMS_APP_PASSWORD` - `MSTEAMS_TENANT_ID` + - `MSTEAMS_AUTH_TYPE` (opcional: `"secret"` o `"federated"`) + - `MSTEAMS_CERTIFICATE_PATH` (federada + certificado) + - `MSTEAMS_CERTIFICATE_THUMBPRINT` (opcional, no requerido para la autenticación) + - `MSTEAMS_USE_MANAGED_IDENTITY` (federada + identidad administrada) + - `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (solo MI asignada por el usuario) 5. **Endpoint del bot** - Establece el Azure Bot Messaging Endpoint en: - - `https://:3978/api/messages` (o la ruta/puerto que hayas elegido). + - `https://:3978/api/messages` (o la ruta/puerto que elijas). 6. **Ejecuta el gateway** - - El canal Teams se inicia automáticamente cuando el plugin integrado o instalado manualmente está disponible y existe configuración `msteams` con credenciales. + - El canal de Teams se inicia automáticamente cuando el plugin incluido o instalado manualmente está disponible y existe configuración `msteams` con credenciales. ## Acción de información de miembro -OpenClaw expone una acción `member-info` respaldada por Graph para Microsoft Teams, de modo que los agentes y las automatizaciones pueden resolver detalles de miembros del canal (nombre para mostrar, correo electrónico, rol) directamente desde Microsoft Graph. +OpenClaw expone una acción `member-info` respaldada por Graph para Microsoft Teams, de modo que los agentes y las automatizaciones puedan resolver directamente desde Microsoft Graph los detalles de miembros del canal (nombre para mostrar, correo electrónico, rol). Requisitos: -- Permiso RSC `Member.Read.Group` (ya incluido en el manifiesto recomendado) +- Permiso RSC `Member.Read.Group` (ya está en el manifiesto recomendado) - Para búsquedas entre equipos: permiso de aplicación Graph `User.Read.All` con consentimiento de administrador -La acción está controlada por `channels.msteams.actions.memberInfo` (habilitada de forma predeterminada cuando hay credenciales de Graph disponibles). +La acción está controlada por `channels.msteams.actions.memberInfo` (predeterminado: habilitada cuando hay credenciales de Graph disponibles). -## Contexto del historial +## Contexto de historial -- `channels.msteams.historyLimit` controla cuántos mensajes recientes de canal/grupo se encapsulan en el prompt. -- Recurre a `messages.groupChat.historyLimit`. Establece `0` para deshabilitarlo (predeterminado 50). -- El historial de hilos recuperado se filtra por las listas de permitidos de remitentes (`allowFrom` / `groupAllowFrom`), de modo que la siembra del contexto del hilo solo incluye mensajes de remitentes permitidos. -- El contexto de archivos adjuntos citados (`ReplyTo*` derivado del HTML de respuesta de Teams) actualmente se transmite tal como se recibe. -- En otras palabras, las listas de permitidos controlan quién puede activar al agente; solo determinadas rutas de contexto suplementario se filtran actualmente. -- El historial de MD puede limitarse con `channels.msteams.dmHistoryLimit` (turnos del usuario). Anulaciones por usuario: `channels.msteams.dms[""].historyLimit`. +- `channels.msteams.historyLimit` controla cuántos mensajes recientes de canal/grupo se incluyen en el prompt. +- Recurre a `messages.groupChat.historyLimit`. Establece `0` para desactivarlo (predeterminado: 50). +- El historial de hilo recuperado se filtra por listas de remitentes permitidos (`allowFrom` / `groupAllowFrom`), por lo que la inicialización del contexto del hilo solo incluye mensajes de remitentes permitidos. +- El contexto de archivos adjuntos citados (`ReplyTo*` derivado del HTML de respuesta de Teams) actualmente se pasa tal como se recibe. +- En otras palabras, las listas de permitidos controlan quién puede activar el agente; hoy solo se filtran determinadas rutas de contexto complementario. +- El historial de mensajes directos puede limitarse con `channels.msteams.dmHistoryLimit` (turnos del usuario). Sobrescrituras por usuario: `channels.msteams.dms[""].historyLimit`. ## Permisos RSC actuales de Teams (manifiesto) Estos son los **permisos resourceSpecific existentes** en nuestro manifiesto de la aplicación de Teams. Solo se aplican dentro del equipo/chat donde la aplicación está instalada. -**Para canales (ámbito de equipo):** +**Para canales (alcance de equipo):** -- `ChannelMessage.Read.Group` (Application) - recibir todos los mensajes del canal sin @mention +- `ChannelMessage.Read.Group` (Application) - recibir todo el contenido de texto de los mensajes de canal sin @mention - `ChannelMessage.Send.Group` (Application) - `Member.Read.Group` (Application) - `Owner.Read.Group` (Application) @@ -332,9 +480,9 @@ Estos son los **permisos resourceSpecific existentes** en nuestro manifiesto de - `ChatMessage.Read.Chat` (Application) - recibir todos los mensajes del chat grupal sin @mention -## Ejemplo de manifiesto de Teams (redactado) +## Ejemplo de manifiesto de Teams (con datos ocultos) -Ejemplo mínimo y válido con los campos obligatorios. Sustituye los IDs y las URL. +Ejemplo mínimo y válido con los campos requeridos. Sustituye los ID y las URL. ```json5 { @@ -382,12 +530,12 @@ Ejemplo mínimo y válido con los campos obligatorios. Sustituye los IDs y las U } ``` -### Advertencias del manifiesto (campos imprescindibles) +### Advertencias sobre el manifiesto (campos obligatorios) - `bots[].botId` **debe** coincidir con el Azure Bot App ID. - `webApplicationInfo.id` **debe** coincidir con el Azure Bot App ID. - `bots[].scopes` debe incluir las superficies que planeas usar (`personal`, `team`, `groupChat`). -- `bots[].supportsFiles: true` es obligatorio para el manejo de archivos en ámbito personal. +- `bots[].supportsFiles: true` es obligatorio para el manejo de archivos en el alcance personal. - `authorization.permissions.resourceSpecific` debe incluir lectura/envío de canal si quieres tráfico de canal. ### Actualizar una aplicación existente @@ -397,27 +545,27 @@ Para actualizar una aplicación de Teams ya instalada (por ejemplo, para añadir 1. Actualiza tu `manifest.json` con la nueva configuración 2. **Incrementa el campo `version`** (por ejemplo, `1.0.0` → `1.1.0`) 3. **Vuelve a comprimir** el manifiesto con los iconos (`manifest.json`, `outline.png`, `color.png`) -4. Carga el nuevo ZIP: +4. Carga el nuevo zip: - **Opción A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → busca tu aplicación → Upload new version - **Opción B (carga lateral):** En Teams → Apps → Manage your apps → Upload a custom app 5. **Para canales de equipo:** reinstala la aplicación en cada equipo para que los nuevos permisos surtan efecto -6. **Cierra Teams por completo y vuelve a iniciarlo** (no basta con cerrar la ventana) para borrar los metadatos de aplicación en caché +6. **Cierra completamente y vuelve a abrir Teams** (no solo cierres la ventana) para borrar los metadatos en caché de la aplicación ## Capacidades: solo RSC frente a Graph -### Con **solo Teams RSC** (aplicación instalada, sin permisos de Graph API) +### Con **solo Teams RSC** (aplicación instalada, sin permisos de la API de Graph) Funciona: -- Leer contenido de **texto** de mensajes de canal. -- Enviar contenido de **texto** de mensajes de canal. -- Recibir archivos adjuntos de **archivos en chats personales (MD)**. +- Leer el contenido de **texto** de mensajes de canal. +- Enviar contenido de **texto** en mensajes de canal. +- Recibir archivos adjuntos en **mensajes directos**. NO funciona: -- Contenido de **imágenes o archivos** de canal/grupo (la carga útil solo incluye un stub HTML). +- Contenido de **imágenes o archivos** en canales/grupos (la carga útil solo incluye un stub HTML). - Descargar archivos adjuntos almacenados en SharePoint/OneDrive. -- Leer el historial de mensajes (más allá del evento del webhook en vivo). +- Leer el historial de mensajes (más allá del evento en vivo del webhook). ### Con **Teams RSC + permisos de aplicación de Microsoft Graph** @@ -427,41 +575,41 @@ Añade: - Descarga de archivos adjuntos almacenados en SharePoint/OneDrive. - Lectura del historial de mensajes de canal/chat mediante Graph. -### RSC frente a Graph API +### RSC frente a la API de Graph -| Capacidad | Permisos RSC | Graph API | -| ---------------------- | -------------------- | ----------------------------------- | -| **Mensajes en tiempo real** | Sí (mediante webhook) | No (solo sondeo) | -| **Mensajes históricos** | No | Sí (puede consultar historial) | -| **Complejidad de configuración** | Solo manifiesto de la aplicación | Requiere consentimiento de administrador + flujo de tokens | -| **Funciona sin conexión** | No (debe estar en ejecución) | Sí (puede consultar en cualquier momento) | +| Capacidad | Permisos RSC | API de Graph | +| ----------------------- | ------------------- | ------------------------------------ | +| **Mensajes en tiempo real** | Sí (mediante webhook) | No (solo sondeo) | +| **Mensajes históricos** | No | Sí (puede consultar el historial) | +| **Complejidad de configuración** | Solo manifiesto de la aplicación | Requiere consentimiento de administrador + flujo de tokens | +| **Funciona sin conexión** | No (debe estar ejecutándose) | Sí (puede consultar en cualquier momento) | -**En resumen:** RSC es para escucha en tiempo real; Graph API es para acceso histórico. Para ponerse al día con mensajes perdidos mientras estabas desconectado, necesitas Graph API con `ChannelMessage.Read.All` (requiere consentimiento de administrador). +**En resumen:** RSC sirve para escucha en tiempo real; la API de Graph es para acceso histórico. Para ponerse al día con mensajes perdidos mientras estabas desconectado, necesitas la API de Graph con `ChannelMessage.Read.All` (requiere consentimiento de administrador). -## Medios + historial con Graph habilitado (obligatorio para canales) +## Medios + historial habilitados con Graph (obligatorio para canales) -Si necesitas imágenes/archivos en **canales** o quieres obtener **historial de mensajes**, debes habilitar permisos de Microsoft Graph y conceder consentimiento de administrador. +Si necesitas imágenes/archivos en **canales** o quieres obtener el **historial de mensajes**, debes habilitar permisos de Microsoft Graph y conceder consentimiento de administrador. 1. En **App Registration** de Entra ID (Azure AD), añade permisos de **Application** de Microsoft Graph: - `ChannelMessage.Read.All` (archivos adjuntos e historial de canal) - `Chat.Read.All` o `ChatMessage.Read.All` (chats grupales) 2. **Concede consentimiento de administrador** para el tenant. 3. Incrementa la **versión del manifiesto** de la aplicación de Teams, vuelve a cargarlo y **reinstala la aplicación en Teams**. -4. **Cierra Teams por completo y vuelve a iniciarlo** para borrar los metadatos de aplicación en caché. +4. **Cierra completamente y vuelve a abrir Teams** para borrar los metadatos en caché de la aplicación. -**Permiso adicional para menciones de usuario:** Las menciones @user funcionan de inmediato para usuarios que están en la conversación. Sin embargo, si quieres buscar y mencionar dinámicamente a usuarios que **no están en la conversación actual**, añade el permiso `User.Read.All` (Application) y concede consentimiento de administrador. +**Permiso adicional para menciones de usuario:** Las @mentions de usuario funcionan de inmediato para usuarios que están en la conversación. Sin embargo, si quieres buscar y mencionar dinámicamente usuarios que **no están en la conversación actual**, añade el permiso de aplicación `User.Read.All` y concede consentimiento de administrador. ## Limitaciones conocidas ### Tiempos de espera del webhook -Teams entrega mensajes mediante webhook HTTP. Si el procesamiento tarda demasiado (por ejemplo, respuestas lentas del LLM), puedes ver: +Teams entrega los mensajes mediante webhook HTTP. Si el procesamiento tarda demasiado (por ejemplo, respuestas lentas del LLM), puedes ver: - Tiempos de espera del gateway -- Teams reintentando el mensaje (provocando duplicados) +- Teams reintentando el mensaje (causando duplicados) - Respuestas descartadas -OpenClaw gestiona esto devolviendo rápidamente y enviando respuestas de forma proactiva, pero las respuestas muy lentas aún pueden causar problemas. +OpenClaw maneja esto devolviendo rápido y enviando respuestas de forma proactiva, pero las respuestas muy lentas pueden seguir causando problemas. ### Formato @@ -469,41 +617,46 @@ El markdown de Teams es más limitado que el de Slack o Discord: - El formato básico funciona: **negrita**, _cursiva_, `code`, enlaces - El markdown complejo (tablas, listas anidadas) puede no renderizarse correctamente -- Adaptive Cards son compatibles para encuestas y envíos arbitrarios de tarjetas (consulta abajo) +- Se admiten Adaptive Cards para encuestas y envíos arbitrarios de tarjetas (consulta abajo) ## Configuración -Ajustes clave (consulta `/gateway/configuration` para patrones de canal compartidos): +Ajustes clave (consulta `/gateway/configuration` para patrones compartidos de canales): -- `channels.msteams.enabled`: habilitar/deshabilitar el canal. +- `channels.msteams.enabled`: habilita/deshabilita el canal. - `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: credenciales del bot. -- `channels.msteams.webhook.port` (predeterminado `3978`) -- `channels.msteams.webhook.path` (predeterminado `/api/messages`) +- `channels.msteams.webhook.port` (predeterminado: `3978`) +- `channels.msteams.webhook.path` (predeterminado: `/api/messages`) - `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (predeterminado: pairing) -- `channels.msteams.allowFrom`: lista de permitidos de MD (se recomiendan IDs de objeto AAD). El asistente resuelve nombres a IDs durante la configuración cuando el acceso a Graph está disponible. -- `channels.msteams.dangerouslyAllowNameMatching`: interruptor de emergencia para volver a habilitar la coincidencia mutable de UPN/nombre para mostrar y el enrutamiento directo por nombre de equipo/canal. -- `channels.msteams.textChunkLimit`: tamaño del fragmento de texto saliente. -- `channels.msteams.chunkMode`: `length` (predeterminado) o `newline` para dividir en líneas en blanco (límites de párrafo) antes de fragmentar por longitud. -- `channels.msteams.mediaAllowHosts`: lista de permitidos de hosts para archivos adjuntos entrantes (predeterminada para dominios de Microsoft/Teams). -- `channels.msteams.mediaAuthAllowHosts`: lista de permitidos para adjuntar encabezados Authorization en reintentos de medios (predeterminada para hosts de Graph + Bot Framework). -- `channels.msteams.requireMention`: exigir @mention en canales/grupos (predeterminado true). -- `channels.msteams.replyStyle`: `thread | top-level` (consulta [Estilo de respuesta](#estilo-de-respuesta-hilos-frente-a-publicaciones)). -- `channels.msteams.teams..replyStyle`: anulación por equipo. -- `channels.msteams.teams..requireMention`: anulación por equipo. -- `channels.msteams.teams..tools`: anulaciones predeterminadas de política de herramientas por equipo (`allow`/`deny`/`alsoAllow`) usadas cuando falta una anulación de canal. -- `channels.msteams.teams..toolsBySender`: anulaciones predeterminadas de política de herramientas por equipo y remitente (`"*"` comodín admitido). -- `channels.msteams.teams..channels..replyStyle`: anulación por canal. -- `channels.msteams.teams..channels..requireMention`: anulación por canal. -- `channels.msteams.teams..channels..tools`: anulaciones de política de herramientas por canal (`allow`/`deny`/`alsoAllow`). -- `channels.msteams.teams..channels..toolsBySender`: anulaciones de política de herramientas por canal y remitente (`"*"` comodín admitido). +- `channels.msteams.allowFrom`: lista de permitidos para mensajes directos (se recomiendan IDs de objeto AAD). El asistente resuelve nombres a IDs durante la configuración cuando hay acceso a Graph disponible. +- `channels.msteams.dangerouslyAllowNameMatching`: interruptor de emergencia para volver a habilitar la coincidencia de UPN/nombre para mostrar mutable y el enrutamiento directo por nombre de equipo/canal. +- `channels.msteams.textChunkLimit`: tamaño de fragmentación del texto saliente. +- `channels.msteams.chunkMode`: `length` (predeterminado) o `newline` para dividir por líneas en blanco (límites de párrafo) antes de fragmentar por longitud. +- `channels.msteams.mediaAllowHosts`: lista de permitidos para hosts de archivos adjuntos entrantes (predeterminado: dominios de Microsoft/Teams). +- `channels.msteams.mediaAuthAllowHosts`: lista de permitidos para adjuntar encabezados Authorization en reintentos de medios (predeterminado: hosts de Graph + Bot Framework). +- `channels.msteams.requireMention`: requiere @mention en canales/grupos (predeterminado: true). +- `channels.msteams.replyStyle`: `thread | top-level` (consulta [Estilo de respuesta](#reply-style-threads-vs-posts)). +- `channels.msteams.teams..replyStyle`: sobrescritura por equipo. +- `channels.msteams.teams..requireMention`: sobrescritura por equipo. +- `channels.msteams.teams..tools`: sobrescrituras predeterminadas de la política de herramientas por equipo (`allow`/`deny`/`alsoAllow`) usadas cuando falta una sobrescritura de canal. +- `channels.msteams.teams..toolsBySender`: sobrescrituras predeterminadas de la política de herramientas por equipo y por remitente (se admite el comodín `"*"`). +- `channels.msteams.teams..channels..replyStyle`: sobrescritura por canal. +- `channels.msteams.teams..channels..requireMention`: sobrescritura por canal. +- `channels.msteams.teams..channels..tools`: sobrescrituras de la política de herramientas por canal (`allow`/`deny`/`alsoAllow`). +- `channels.msteams.teams..channels..toolsBySender`: sobrescrituras de la política de herramientas por canal y por remitente (se admite el comodín `"*"`). - Las claves `toolsBySender` deben usar prefijos explícitos: `id:`, `e164:`, `username:`, `name:` (las claves heredadas sin prefijo siguen asignándose solo a `id:`). -- `channels.msteams.actions.memberInfo`: habilitar o deshabilitar la acción de información de miembro respaldada por Graph (habilitada de forma predeterminada cuando hay credenciales de Graph disponibles). -- `channels.msteams.sharePointSiteId`: ID del sitio de SharePoint para cargas de archivos en chats grupales/canales (consulta [Envío de archivos en chats grupales](#envío-de-archivos-en-chats-grupales)). +- `channels.msteams.actions.memberInfo`: habilita o deshabilita la acción de información de miembro respaldada por Graph (predeterminado: habilitada cuando hay credenciales de Graph disponibles). +- `channels.msteams.authType`: tipo de autenticación — `"secret"` (predeterminado) o `"federated"`. +- `channels.msteams.certificatePath`: ruta al archivo de certificado PEM (federada + autenticación por certificado). +- `channels.msteams.certificateThumbprint`: huella digital del certificado (opcional, no requerida para la autenticación). +- `channels.msteams.useManagedIdentity`: habilita autenticación con identidad administrada (modo federado). +- `channels.msteams.managedIdentityClientId`: client ID para identidad administrada asignada por el usuario. +- `channels.msteams.sharePointSiteId`: ID del sitio de SharePoint para cargas de archivos en chats grupales/canales (consulta [Envío de archivos en chats grupales](#sending-files-in-group-chats)). ## Enrutamiento y sesiones -- Las claves de sesión siguen el formato estándar de agente (consulta [/concepts/session](/concepts/session)): +- Las claves de sesión siguen el formato estándar de agente (consulta [/concepts/session](/es/concepts/session)): - Los mensajes directos comparten la sesión principal (`agent::`). - Los mensajes de canal/grupo usan el ID de conversación: - `agent::msteams:channel:` @@ -513,15 +666,15 @@ Ajustes clave (consulta `/gateway/configuration` para patrones de canal comparti Teams introdujo recientemente dos estilos de interfaz de canal sobre el mismo modelo de datos subyacente: -| Estilo | Descripción | `replyStyle` recomendado | -| ------------------------ | --------------------------------------------------------- | ------------------------ | -| **Posts** (clásico) | Los mensajes aparecen como tarjetas con respuestas en hilo debajo | `thread` (predeterminado) | -| **Threads** (tipo Slack) | Los mensajes fluyen linealmente, más parecido a Slack | `top-level` | +| Estilo | Descripción | `replyStyle` recomendado | +| ----------------------- | -------------------------------------------------------- | ------------------------ | +| **Posts** (clásico) | Los mensajes aparecen como tarjetas con respuestas en hilo debajo | `thread` (predeterminado) | +| **Threads** (tipo Slack) | Los mensajes fluyen linealmente, más parecido a Slack | `top-level` | **El problema:** La API de Teams no expone qué estilo de interfaz usa un canal. Si usas el `replyStyle` incorrecto: - `thread` en un canal con estilo Threads → las respuestas aparecen anidadas de forma extraña -- `top-level` en un canal con estilo Posts → las respuestas aparecen como publicaciones separadas de nivel superior en lugar de en el hilo +- `top-level` en un canal con estilo Posts → las respuestas aparecen como publicaciones independientes de nivel superior en lugar de dentro del hilo **Solución:** Configura `replyStyle` por canal según cómo esté configurado el canal: @@ -548,31 +701,31 @@ Teams introdujo recientemente dos estilos de interfaz de canal sobre el mismo mo **Limitaciones actuales:** -- **MD:** Las imágenes y los archivos adjuntos funcionan mediante las API de archivos del bot de Teams. -- **Canales/grupos:** Los archivos adjuntos residen en el almacenamiento de M365 (SharePoint/OneDrive). La carga útil del webhook solo incluye un stub HTML, no los bytes reales del archivo. **Se requieren permisos de Graph API** para descargar archivos adjuntos de canal. -- Para envíos explícitos centrados primero en archivos, usa `action=upload-file` con `media` / `filePath` / `path`; el `message` opcional se convierte en el texto/comentario adjunto, y `filename` sustituye el nombre cargado. +- **Mensajes directos:** las imágenes y los archivos adjuntos funcionan mediante las API de archivos del bot de Teams. +- **Canales/grupos:** los archivos adjuntos viven en el almacenamiento de M365 (SharePoint/OneDrive). La carga útil del webhook solo incluye un stub HTML, no los bytes reales del archivo. **Se requieren permisos de la API de Graph** para descargar archivos adjuntos de canal. +- Para envíos explícitos centrados primero en archivos, usa `action=upload-file` con `media` / `filePath` / `path`; el `message` opcional pasa a ser el texto/comentario adjunto, y `filename` sobrescribe el nombre cargado. Sin permisos de Graph, los mensajes de canal con imágenes se recibirán solo como texto (el contenido de la imagen no es accesible para el bot). -De forma predeterminada, OpenClaw solo descarga medios desde nombres de host de Microsoft/Teams. Anúlalo con `channels.msteams.mediaAllowHosts` (usa `["*"]` para permitir cualquier host). -Los encabezados Authorization solo se adjuntan para los hosts de `channels.msteams.mediaAuthAllowHosts` (predeterminados para hosts de Graph + Bot Framework). Mantén esta lista estricta (evita sufijos multiinquilino). +De forma predeterminada, OpenClaw solo descarga medios desde nombres de host de Microsoft/Teams. Sobrescribe esto con `channels.msteams.mediaAllowHosts` (usa `["*"]` para permitir cualquier host). +Los encabezados Authorization solo se adjuntan para hosts en `channels.msteams.mediaAuthAllowHosts` (predeterminado: hosts de Graph + Bot Framework). Mantén esta lista estricta (evita sufijos multi-tenant). ## Envío de archivos en chats grupales -Los bots pueden enviar archivos en MD usando el flujo FileConsentCard (integrado). Sin embargo, **enviar archivos en chats grupales/canales** requiere configuración adicional: +Los bots pueden enviar archivos en mensajes directos mediante el flujo FileConsentCard (integrado). Sin embargo, **enviar archivos en chats grupales/canales** requiere configuración adicional: -| Contexto | Cómo se envían los archivos | Configuración necesaria | -| ------------------------ | -------------------------------------------- | ----------------------------------------------- | -| **MD** | FileConsentCard → el usuario acepta → el bot carga | Funciona sin configuración adicional | -| **Chats grupales/canales** | Cargar en SharePoint → compartir enlace | Requiere `sharePointSiteId` + permisos de Graph | -| **Imágenes (cualquier contexto)** | Inline codificado en Base64 | Funciona sin configuración adicional | +| Contexto | Cómo se envían los archivos | Configuración necesaria | +| ------------------------ | ----------------------------------------- | ------------------------------------------------ | +| **Mensajes directos** | FileConsentCard → el usuario acepta → el bot carga | Funciona de inmediato | +| **Chats grupales/canales** | Cargar en SharePoint → compartir enlace | Requiere `sharePointSiteId` + permisos de Graph | +| **Imágenes (cualquier contexto)** | Inline codificado en Base64 | Funciona de inmediato | ### Por qué los chats grupales necesitan SharePoint -Los bots no tienen una unidad personal de OneDrive (el endpoint `/me/drive` de Graph API no funciona para identidades de aplicación). Para enviar archivos en chats grupales/canales, el bot carga el archivo en un **sitio de SharePoint** y crea un enlace para compartir. +Los bots no tienen una unidad personal de OneDrive (el endpoint de la API de Graph `/me/drive` no funciona para identidades de aplicación). Para enviar archivos en chats grupales/canales, el bot carga el archivo en un **sitio de SharePoint** y crea un enlace para compartir. ### Configuración -1. **Añade permisos de Graph API** en Entra ID (Azure AD) → App Registration: +1. **Añade permisos de la API de Graph** en Entra ID (Azure AD) → App Registration: - `Sites.ReadWrite.All` (Application) - cargar archivos en SharePoint - `Chat.Read.All` (Application) - opcional, habilita enlaces para compartir por usuario @@ -607,34 +760,34 @@ Los bots no tienen una unidad personal de OneDrive (el endpoint `/me/drive` de G ### Comportamiento de uso compartido -| Permiso | Comportamiento de uso compartido | -| --------------------------------------- | --------------------------------------------------------- | -| `Sites.ReadWrite.All` solo | Enlace de uso compartido para toda la organización (cualquiera en la organización puede acceder) | -| `Sites.ReadWrite.All` + `Chat.Read.All` | Enlace de uso compartido por usuario (solo los miembros del chat pueden acceder) | +| Permiso | Comportamiento de uso compartido | +| -------------------------------------- | -------------------------------------------------------- | +| `Sites.ReadWrite.All` solo | Enlace para compartir en toda la organización (cualquiera en la organización puede acceder) | +| `Sites.ReadWrite.All` + `Chat.Read.All` | Enlace para compartir por usuario (solo los miembros del chat pueden acceder) | El uso compartido por usuario es más seguro, ya que solo los participantes del chat pueden acceder al archivo. Si falta el permiso `Chat.Read.All`, el bot recurre al uso compartido para toda la organización. ### Comportamiento de respaldo -| Escenario | Resultado | -| ------------------------------------------------- | -------------------------------------------------- | -| Chat grupal + archivo + `sharePointSiteId` configurado | Cargar en SharePoint, enviar enlace para compartir | -| Chat grupal + archivo + sin `sharePointSiteId` | Intentar carga en OneDrive (puede fallar), enviar solo texto | -| Chat personal + archivo | Flujo FileConsentCard (funciona sin SharePoint) | -| Cualquier contexto + imagen | Inline codificado en Base64 (funciona sin SharePoint) | +| Escenario | Resultado | +| ------------------------------------------------- | ------------------------------------------------- | +| Chat grupal + archivo + `sharePointSiteId` configurado | Carga en SharePoint, envía enlace para compartir | +| Chat grupal + archivo + sin `sharePointSiteId` | Intenta cargar en OneDrive (puede fallar), envía solo texto | +| Chat personal + archivo | Flujo FileConsentCard (funciona sin SharePoint) | +| Cualquier contexto + imagen | Inline codificado en Base64 (funciona sin SharePoint) | -### Ubicación de almacenamiento de archivos +### Ubicación donde se almacenan los archivos Los archivos cargados se almacenan en una carpeta `/OpenClawShared/` dentro de la biblioteca de documentos predeterminada del sitio de SharePoint configurado. ## Encuestas (Adaptive Cards) -OpenClaw envía encuestas de Teams como Adaptive Cards (no existe una API nativa de encuestas de Teams). +OpenClaw envía encuestas de Teams como Adaptive Cards (no hay una API nativa de encuestas en Teams). - CLI: `openclaw message poll --channel msteams --target conversation: ...` -- Los votos se registran por el gateway en `~/.openclaw/msteams-polls.json`. +- Los votos los registra el gateway en `~/.openclaw/msteams-polls.json`. - El gateway debe permanecer en línea para registrar votos. -- Las encuestas aún no publican automáticamente resúmenes de resultados (inspecciona el archivo de almacenamiento si es necesario). +- Las encuestas aún no publican automáticamente resúmenes de resultados (inspecciona el archivo de almacenamiento si hace falta). ## Adaptive Cards (arbitrarias) @@ -642,7 +795,7 @@ Envía cualquier JSON de Adaptive Card a usuarios o conversaciones de Teams usan El parámetro `card` acepta un objeto JSON de Adaptive Card. Cuando se proporciona `card`, el texto del mensaje es opcional. -**Herramienta de agente:** +**Herramienta del agente:** ```json5 { @@ -665,18 +818,18 @@ openclaw message send --channel msteams \ --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}' ``` -Consulta la [documentación de Adaptive Cards](https://adaptivecards.io/) para ver el esquema de tarjetas y ejemplos. Para detalles sobre el formato de destino, consulta [Formatos de destino](#formatos-de-destino) abajo. +Consulta la [documentación de Adaptive Cards](https://adaptivecards.io/) para ver el esquema de tarjetas y ejemplos. Para conocer los detalles del formato de destino, consulta [Formatos de destino](#target-formats) abajo. ## Formatos de destino Los destinos de MSTeams usan prefijos para distinguir entre usuarios y conversaciones: -| Tipo de destino | Formato | Ejemplo | -| ------------------- | -------------------------------- | --------------------------------------------------- | -| Usuario (por ID) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | -| Usuario (por nombre) | `user:` | `user:John Smith` (requiere Graph API) | -| Grupo/canal | `conversation:` | `conversation:19:abc123...@thread.tacv2` | -| Grupo/canal (sin procesar) | `` | `19:abc123...@thread.tacv2` (si contiene `@thread`) | +| Tipo de destino | Formato | Ejemplo | +| ---------------------- | -------------------------------- | --------------------------------------------------- | +| Usuario (por ID) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | +| Usuario (por nombre) | `user:` | `user:John Smith` (requiere la API de Graph) | +| Grupo/canal | `conversation:` | `conversation:19:abc123...@thread.tacv2` | +| Grupo/canal (sin procesar) | `` | `19:abc123...@thread.tacv2` (si contiene `@thread`) | **Ejemplos de CLI:** @@ -684,7 +837,7 @@ Los destinos de MSTeams usan prefijos para distinguir entre usuarios y conversac # Enviar a un usuario por ID openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello" -# Enviar a un usuario por nombre para mostrar (activa búsqueda en Graph API) +# Enviar a un usuario por nombre para mostrar (activa la búsqueda con la API de Graph) openclaw message send --channel msteams --target "user:John Smith" --message "Hello" # Enviar a un chat grupal o canal @@ -695,7 +848,7 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread. --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}' ``` -**Ejemplos de herramienta de agente:** +**Ejemplos de herramientas del agente:** ```json5 { @@ -719,56 +872,56 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread. } ``` -Nota: Sin el prefijo `user:`, los nombres se interpretan por defecto como resolución de grupo/equipo. Usa siempre `user:` cuando apuntes a personas por nombre para mostrar. +Nota: Sin el prefijo `user:`, los nombres usan por defecto la resolución de grupo/equipo. Usa siempre `user:` cuando apuntes a personas por nombre para mostrar. ## Mensajería proactiva -- Los mensajes proactivos solo son posibles **después** de que un usuario haya interactuado, porque almacenamos las referencias de conversación en ese momento. -- Consulta `/gateway/configuration` para `dmPolicy` y el control por lista de permitidos. +- Los mensajes proactivos solo son posibles **después** de que un usuario haya interactuado, porque almacenamos referencias de conversación en ese momento. +- Consulta `/gateway/configuration` para `dmPolicy` y el control mediante lista de permitidos. -## IDs de equipo y canal (error habitual) +## IDs de equipo y canal (error común) -El parámetro de consulta `groupId` en las URL de Teams **NO** es el ID de equipo usado para la configuración. Extrae los IDs de la ruta de la URL: +El parámetro de consulta `groupId` en las URL de Teams **NO** es el ID de equipo usado para la configuración. Extrae los IDs de la ruta de la URL en su lugar: -**URL de equipo:** +**URL del equipo:** ``` https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... └────────────────────────────┘ - ID de equipo (decodifica la URL) + ID del equipo (decodifica esta URL) ``` -**URL de canal:** +**URL del canal:** ``` https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=... └─────────────────────────┘ - ID de canal (decodifica la URL) + ID del canal (decodifica esta URL) ``` **Para la configuración:** -- ID de equipo = segmento de ruta después de `/team/` (decodificado de URL, p. ej., `19:Bk4j...@thread.tacv2`) -- ID de canal = segmento de ruta después de `/channel/` (decodificado de URL) +- ID del equipo = segmento de ruta después de `/team/` (URL decodificada, por ejemplo, `19:Bk4j...@thread.tacv2`) +- ID del canal = segmento de ruta después de `/channel/` (URL decodificada) - **Ignora** el parámetro de consulta `groupId` ## Canales privados -Los bots tienen compatibilidad limitada en canales privados: +Los bots tienen soporte limitado en canales privados: -| Función | Canales estándar | Canales privados | -| ---------------------------- | ----------------- | ---------------------- | -| Instalación del bot | Sí | Limitada | -| Mensajes en tiempo real (webhook) | Sí | Puede que no funcione | -| Permisos RSC | Sí | Puede comportarse de forma diferente | -| @mentions | Sí | Si el bot es accesible | -| Historial de Graph API | Sí | Sí (con permisos) | +| Función | Canales estándar | Canales privados | +| --------------------------- | ---------------- | --------------------- | +| Instalación del bot | Sí | Limitada | +| Mensajes en tiempo real (webhook) | Sí | Puede no funcionar | +| Permisos RSC | Sí | Pueden comportarse de forma distinta | +| @mentions | Sí | Si el bot es accesible | +| Historial con la API de Graph | Sí | Sí (con permisos) | -**Soluciones alternativas si los canales privados no funcionan:** +**Soluciones si los canales privados no funcionan:** -1. Usa canales estándar para las interacciones con el bot -2. Usa MD: los usuarios siempre pueden enviar mensajes directos al bot -3. Usa Graph API para acceso histórico (requiere `ChannelMessage.Read.All`) +1. Usa canales estándar para interacciones con el bot +2. Usa mensajes directos: los usuarios siempre pueden enviar mensajes directamente al bot +3. Usa la API de Graph para acceso histórico (requiere `ChannelMessage.Read.All`) ## Solución de problemas @@ -776,37 +929,37 @@ Los bots tienen compatibilidad limitada en canales privados: - **Las imágenes no aparecen en canales:** faltan permisos de Graph o consentimiento de administrador. Reinstala la aplicación de Teams y cierra/reabre Teams por completo. - **No hay respuestas en el canal:** las menciones son obligatorias de forma predeterminada; establece `channels.msteams.requireMention=false` o configúralo por equipo/canal. -- **Incompatibilidad de versión (Teams sigue mostrando el manifiesto antiguo):** elimina y vuelve a añadir la aplicación y cierra Teams por completo para actualizar. -- **401 Unauthorized del webhook:** Esperado al probar manualmente sin JWT de Azure; significa que el endpoint es accesible, pero la autenticación falló. Usa Azure Web Chat para probar correctamente. +- **Desajuste de versión (Teams sigue mostrando el manifiesto anterior):** elimina y vuelve a añadir la aplicación, y cierra Teams por completo para actualizar. +- **401 Unauthorized desde el webhook:** es lo esperado al probar manualmente sin Azure JWT; significa que el endpoint es accesible, pero la autenticación falló. Usa Azure Web Chat para probar correctamente. ### Errores al cargar el manifiesto - **"Icon file cannot be empty":** El manifiesto hace referencia a archivos de icono de 0 bytes. Crea iconos PNG válidos (32x32 para `outline.png`, 192x192 para `color.png`). - **"webApplicationInfo.Id already in use":** La aplicación sigue instalada en otro equipo/chat. Búscala y desinstálala primero, o espera 5-10 minutos para la propagación. -- **"Something went wrong" al cargar:** Cárgalo mediante [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), abre las DevTools del navegador (F12) → pestaña Network, y revisa el cuerpo de la respuesta para ver el error real. -- **Fallo en la carga lateral:** Prueba "Upload an app to your org's app catalog" en lugar de "Upload a custom app"; esto suele evitar restricciones de carga lateral. +- **"Something went wrong" al cargar:** Cárgala mediante [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) en su lugar, abre las herramientas de desarrollo del navegador (F12) → pestaña Network, y revisa el cuerpo de la respuesta para ver el error real. +- **Fallo de carga lateral:** Prueba con "Upload an app to your org's app catalog" en lugar de "Upload a custom app"; esto suele omitir las restricciones de carga lateral. ### Los permisos RSC no funcionan 1. Verifica que `webApplicationInfo.id` coincida exactamente con el App ID de tu bot 2. Vuelve a cargar la aplicación y reinstálala en el equipo/chat 3. Comprueba si el administrador de tu organización ha bloqueado los permisos RSC -4. Confirma que estás usando el ámbito correcto: `ChannelMessage.Read.Group` para equipos, `ChatMessage.Read.Chat` para chats grupales +4. Confirma que estás usando el alcance correcto: `ChannelMessage.Read.Group` para equipos, `ChatMessage.Read.Chat` para chats grupales ## Referencias - [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - guía de configuración de Azure Bot - [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - crear/gestionar aplicaciones de Teams -- [Esquema del manifiesto de la aplicación de Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) -- [Recibir mensajes de canal con RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) -- [Referencia de permisos RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) -- [Manejo de archivos del bot de Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (canal/grupo requiere Graph) -- [Mensajería proactiva](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) +- [Teams app manifest schema](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) +- [Receive channel messages with RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) +- [RSC permissions reference](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) +- [Teams bot file handling](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (canal/grupo requiere Graph) +- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) ## Relacionado -- [Resumen de canales](/channels) — todos los canales compatibles -- [Emparejamiento](/channels/pairing) — autenticación de MD y flujo de emparejamiento -- [Grupos](/channels/groups) — comportamiento del chat grupal y control por mención -- [Enrutamiento de canales](/channels/channel-routing) — enrutamiento de sesiones para mensajes -- [Seguridad](/gateway/security) — modelo de acceso y endurecimiento +- [Resumen de canales](/es/channels) — todos los canales compatibles +- [Pairing](/es/channels/pairing) — autenticación de mensajes directos y flujo de emparejamiento +- [Grupos](/es/channels/groups) — comportamiento del chat grupal y restricción por mención +- [Enrutamiento de canales](/es/channels/channel-routing) — enrutamiento de sesiones para mensajes +- [Seguridad](/es/gateway/security) — modelo de acceso y fortalecimiento diff --git a/docs/es/plugins/sdk-agent-harness.md b/docs/es/plugins/sdk-agent-harness.md index 71971e304..1bd220cb9 100644 --- a/docs/es/plugins/sdk-agent-harness.md +++ b/docs/es/plugins/sdk-agent-harness.md @@ -1,60 +1,53 @@ --- read_when: - - Estás cambiando el runtime del agente integrado o el registro del arnés - - Estás registrando un arnés de agente desde un plugin integrado o de confianza + - Estás cambiando el tiempo de ejecución integrado del agente o el registro del harness + - Estás registrando un harness de agente desde un plugin incluido o de confianza - Necesitas entender cómo se relaciona el plugin Codex con los proveedores de modelos sidebarTitle: Agent Harness -summary: Superficie experimental del SDK para plugins que reemplazan el ejecutor de agente integrado de bajo nivel -title: Plugins de arnés de agente +summary: Superficie experimental del SDK para plugins que reemplazan el ejecutor integrado de agentes de bajo nivel +title: Plugins de Agent Harness x-i18n: - generated_at: "2026-04-11T02:46:17Z" + generated_at: "2026-04-12T00:19:04Z" model: gpt-5.4 provider: openai - source_hash: 43c1f2c087230398b0162ed98449f239c8db1e822e51c7dcd40c54fa6c3374e1 + source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -# Plugins de arnés de agente +# Plugins de Agent Harness -Un **arnés de agente** es el ejecutor de bajo nivel para un turno preparado de un agente de OpenClaw. -No es un proveedor de modelos, ni un canal, ni un registro de herramientas. +Un **agent harness** es el ejecutor de bajo nivel para un turno preparado de un agente de OpenClaw. No es un proveedor de modelos, no es un canal y no es un registro de herramientas. -Usa esta superficie solo para plugins nativos integrados o de confianza. El contrato -sigue siendo experimental porque los tipos de parámetros reflejan intencionalmente el ejecutor -integrado actual. +Usa esta superficie solo para plugins nativos incluidos o de confianza. El contrato sigue siendo experimental porque los tipos de parámetros reflejan intencionalmente el ejecutor integrado actual. -## Cuándo usar un arnés +## Cuándo usar un harness -Registra un arnés de agente cuando una familia de modelos tiene su propio runtime -nativo de sesión y el transporte normal de proveedor de OpenClaw es la abstracción incorrecta. +Registra un agent harness cuando una familia de modelos tiene su propio tiempo de ejecución de sesión nativo y el transporte normal de proveedores de OpenClaw es la abstracción incorrecta. Ejemplos: -- un servidor nativo de agente de coding que gestiona hilos y compactación -- una CLI o daemon local que debe transmitir eventos nativos de plan/razonamiento/herramientas -- un runtime de modelo que necesita su propio ID de reanudación además de la - transcripción de sesión de OpenClaw +- un servidor nativo de agente de programación que administra hilos y compactación +- una CLI o un daemon local que debe transmitir eventos nativos de plan/razonamiento/herramientas +- un tiempo de ejecución de modelos que necesita su propio id de reanudación además del transcrito de sesión de OpenClaw -**No** registres un arnés solo para agregar una nueva API de LLM. Para APIs normales de modelos por HTTP o -WebSocket, crea un [plugin de proveedor](/es/plugins/sdk-provider-plugins). +**No** registres un harness solo para agregar una nueva API de LLM. Para APIs de modelos HTTP o WebSocket normales, crea un [plugin de proveedor](/es/plugins/sdk-provider-plugins). -## Qué sigue gestionando el núcleo +## Lo que el núcleo sigue administrando -Antes de que se seleccione un arnés, OpenClaw ya ha resuelto: +Antes de que se seleccione un harness, OpenClaw ya ha resuelto: - proveedor y modelo -- estado de autenticación de runtime -- nivel de pensamiento y presupuesto de contexto -- la transcripción/archivo de sesión de OpenClaw +- estado de autenticación del tiempo de ejecución +- nivel de razonamiento y presupuesto de contexto +- el archivo de transcripción/sesión de OpenClaw - espacio de trabajo, sandbox y política de herramientas -- callbacks de respuesta del canal y callbacks de streaming -- política de respaldo de modelos y cambio de modelos en vivo +- callbacks de respuesta del canal y callbacks de transmisión +- política de fallback de modelo y cambio de modelo en vivo -Esa división es intencional. Un arnés ejecuta un intento preparado; no elige -proveedores, no reemplaza la entrega por canal ni cambia modelos silenciosamente. +Esta separación es intencional. Un harness ejecuta un intento preparado; no elige proveedores, no reemplaza la entrega del canal ni cambia modelos silenciosamente. -## Registrar un arnés +## Registrar un harness **Importación:** `openclaw/plugin-sdk/agent-harness` @@ -64,7 +57,7 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; const myHarness: AgentHarness = { id: "my-harness", - label: "Mi arnés de agente nativo", + label: "My native agent harness", supports(ctx) { return ctx.provider === "my-provider" @@ -73,17 +66,17 @@ const myHarness: AgentHarness = { }, async runAttempt(params) { - // Inicia o reanuda tu hilo nativo. - // Usa params.prompt, params.tools, params.images, params.onPartialReply, - // params.onAgentEvent y los demás campos del intento preparado. + // Start or resume your native thread. + // Use params.prompt, params.tools, params.images, params.onPartialReply, + // params.onAgentEvent, and the other prepared attempt fields. return await runMyNativeTurn(params); }, }; export default definePluginEntry({ id: "my-native-agent", - name: "Mi agente nativo", - description: "Ejecuta modelos seleccionados mediante un daemon nativo de agente.", + name: "My Native Agent", + description: "Runs selected models through a native agent daemon.", register(api) { api.registerAgentHarness(myHarness); }, @@ -92,66 +85,51 @@ export default definePluginEntry({ ## Política de selección -OpenClaw elige un arnés después de resolver proveedor/modelo: +OpenClaw elige un harness después de la resolución de proveedor/modelo: -1. `OPENCLAW_AGENT_RUNTIME=` fuerza un arnés registrado con ese id. -2. `OPENCLAW_AGENT_RUNTIME=pi` fuerza el arnés PI integrado. -3. `OPENCLAW_AGENT_RUNTIME=auto` pide a los arneses registrados si admiten el - proveedor/modelo resuelto. -4. Si ningún arnés registrado coincide, OpenClaw usa PI a menos que el respaldo a PI - esté desactivado. +1. `OPENCLAW_AGENT_RUNTIME=` fuerza un harness registrado con ese id. +2. `OPENCLAW_AGENT_RUNTIME=pi` fuerza el harness PI integrado. +3. `OPENCLAW_AGENT_RUNTIME=auto` pide a los harnesses registrados si admiten el proveedor/modelo resuelto. +4. Si ningún harness registrado coincide, OpenClaw usa PI a menos que el fallback a PI esté deshabilitado. -Los fallos de arneses de plugin forzados aparecen como fallos de ejecución. En modo `auto`, -OpenClaw puede recurrir a PI cuando el arnés de plugin seleccionado falla antes de que un -turno haya producido efectos secundarios. Configura `OPENCLAW_AGENT_HARNESS_FALLBACK=none` o -`embeddedHarness.fallback: "none"` para convertir ese respaldo en un fallo definitivo. +Los fallos de un harness de plugin forzado se muestran como fallos de ejecución. En modo `auto`, OpenClaw puede volver a PI cuando el harness de plugin seleccionado falla antes de que un turno haya producido efectos secundarios. Configura `OPENCLAW_AGENT_HARNESS_FALLBACK=none` o `embeddedHarness.fallback: "none"` para que ese fallback sea en cambio un fallo definitivo. -El plugin Codex integrado registra `codex` como su ID de arnés. El núcleo trata eso -como un ID ordinario de arnés de plugin; los alias específicos de Codex pertenecen al plugin -o a la configuración del operador, no al selector de runtime compartido. +El plugin Codex incluido registra `codex` como su id de harness. El núcleo trata eso como un id de harness de plugin normal; los alias específicos de Codex pertenecen al plugin o a la configuración del operador, no al selector de tiempo de ejecución compartido. -## Emparejamiento de proveedor y arnés +## Emparejamiento de proveedor y harness -La mayoría de los arneses también deberían registrar un proveedor. El proveedor hace visibles al resto de -OpenClaw las referencias de modelo, el estado de autenticación, los metadatos del modelo y la selección de `/model`. -Luego el arnés reclama ese proveedor en `supports(...)`. +La mayoría de los harnesses también deberían registrar un proveedor. El proveedor hace que las referencias de modelos, el estado de autenticación, los metadatos del modelo y la selección de `/model` sean visibles para el resto de OpenClaw. Luego, el harness reclama ese proveedor en `supports(...)`. -El plugin Codex integrado sigue este patrón: +El plugin Codex incluido sigue este patrón: -- ID de proveedor: `codex` -- referencias de modelo para el usuario: `codex/gpt-5.4`, `codex/gpt-5.2` u otro modelo devuelto - por el servidor de aplicaciones de Codex -- ID de arnés: `codex` -- autenticación: disponibilidad sintética del proveedor, porque el arnés Codex gestiona el - inicio de sesión/sesión nativos de Codex -- solicitud al servidor de aplicaciones: OpenClaw envía el ID de modelo sin prefijo a Codex y deja que el - arnés hable con el protocolo nativo del servidor de aplicaciones +- id del proveedor: `codex` +- referencias de modelos del usuario: `codex/gpt-5.4`, `codex/gpt-5.2` u otro modelo devuelto por el servidor de aplicaciones de Codex +- id del harness: `codex` +- autenticación: disponibilidad sintética del proveedor, porque el harness de Codex administra el inicio de sesión/sesión nativos de Codex +- solicitud al servidor de aplicaciones: OpenClaw envía el id de modelo sin prefijo a Codex y permite que el harness hable con el protocolo nativo del servidor de aplicaciones -El plugin Codex es aditivo. Las referencias simples `openai/gpt-*` siguen siendo referencias del proveedor OpenAI -y continúan usando la ruta normal de proveedor de OpenClaw. Selecciona `codex/gpt-*` -cuando quieras autenticación gestionada por Codex, detección de modelos de Codex, hilos nativos y -ejecución en servidor de aplicaciones de Codex. `/model` puede cambiar entre los modelos de Codex devueltos -por el servidor de aplicaciones de Codex sin requerir credenciales del proveedor OpenAI. +El plugin Codex es aditivo. Las referencias simples `openai/gpt-*` siguen siendo referencias del proveedor OpenAI y continúan usando la ruta normal de proveedores de OpenClaw. Selecciona `codex/gpt-*` cuando quieras autenticación administrada por Codex, descubrimiento de modelos de Codex, hilos nativos y ejecución del servidor de aplicaciones de Codex. `/model` puede cambiar entre los modelos de Codex devueltos por el servidor de aplicaciones de Codex sin requerir credenciales del proveedor OpenAI. -Para la configuración del operador, ejemplos de prefijos de modelo y configuraciones solo de Codex, consulta -[Codex Harness](/es/plugins/codex-harness). +Para la configuración del operador, ejemplos de prefijos de modelo y configuraciones exclusivas de Codex, consulta [Codex Harness](/es/plugins/codex-harness). -OpenClaw requiere Codex app-server `0.118.0` o posterior. El plugin Codex verifica el handshake -de inicialización del servidor de aplicaciones y bloquea servidores más antiguos o sin versión para que -OpenClaw solo se ejecute sobre la superficie de protocolo con la que se ha probado. +OpenClaw requiere Codex app-server `0.118.0` o una versión más reciente. El plugin Codex verifica el handshake de inicialización del servidor de aplicaciones y bloquea servidores más antiguos o sin versión para que OpenClaw solo se ejecute contra la superficie de protocolo con la que se ha probado. -## Desactivar el respaldo a PI +### Modo de harness nativo de Codex -De forma predeterminada, OpenClaw ejecuta agentes integrados con `agents.defaults.embeddedHarness` -configurado como `{ runtime: "auto", fallback: "pi" }`. En modo `auto`, los plugins registrados -de arnés pueden reclamar un par proveedor/modelo. Si ninguno coincide, o si un -arnés de plugin seleccionado automáticamente falla antes de producir salida, OpenClaw recurre a PI. +El harness `codex` incluido es el modo nativo de Codex para los turnos integrados de agentes de OpenClaw. Primero habilita el plugin `codex` incluido e incluye `codex` en `plugins.allow` si tu configuración usa una allowlist restrictiva. Es diferente de `openai-codex/*`: -Configura `fallback: "none"` cuando necesites demostrar que un arnés de plugin es el único -runtime que se está usando. Esto desactiva el respaldo automático a PI; no bloquea -un `runtime: "pi"` explícito ni `OPENCLAW_AGENT_RUNTIME=pi`. +- `openai-codex/*` usa OAuth de ChatGPT/Codex a través de la ruta normal de proveedores de OpenClaw. +- `codex/*` usa el proveedor Codex incluido y enruta el turno a través de Codex app-server. -Para ejecuciones integradas solo con Codex: +Cuando se ejecuta este modo, Codex administra el id del hilo nativo, el comportamiento de reanudación, la compactación y la ejecución del servidor de aplicaciones. OpenClaw sigue administrando el canal de chat, el espejo visible de la transcripción, la política de herramientas, las aprobaciones, la entrega de medios y la selección de sesión. Usa `embeddedHarness.runtime: "codex"` con `embeddedHarness.fallback: "none"` cuando necesites demostrar que se usa la ruta de Codex app-server y que el fallback a PI no está ocultando un harness nativo defectuoso. + +## Deshabilitar el fallback a PI + +De forma predeterminada, OpenClaw ejecuta agentes integrados con `agents.defaults.embeddedHarness` configurado como `{ runtime: "auto", fallback: "pi" }`. En el modo `auto`, los harnesses de plugin registrados pueden reclamar un par proveedor/modelo. Si ninguno coincide, o si un harness de plugin seleccionado automáticamente falla antes de producir salida, OpenClaw vuelve a PI. + +Configura `fallback: "none"` cuando necesites demostrar que un harness de plugin es el único tiempo de ejecución que se está usando. Esto deshabilita el fallback automático a PI; no bloquea un `runtime: "pi"` explícito ni `OPENCLAW_AGENT_RUNTIME=pi`. + +Para ejecuciones integradas exclusivas de Codex: ```json { @@ -167,9 +145,7 @@ Para ejecuciones integradas solo con Codex: } ``` -Si quieres que cualquier arnés de plugin registrado reclame modelos coincidentes pero nunca -quieres que OpenClaw recurra silenciosamente a PI, mantén `runtime: "auto"` y desactiva -el respaldo: +Si quieres que cualquier harness de plugin registrado reclame modelos coincidentes pero nunca quieres que OpenClaw vuelva silenciosamente a PI, mantén `runtime: "auto"` y deshabilita el fallback: ```json { @@ -209,9 +185,7 @@ Las anulaciones por agente usan la misma forma: } ``` -`OPENCLAW_AGENT_RUNTIME` sigue anulando el runtime configurado. Usa -`OPENCLAW_AGENT_HARNESS_FALLBACK=none` para desactivar el respaldo a PI desde el -entorno. +`OPENCLAW_AGENT_RUNTIME` sigue anulando el tiempo de ejecución configurado. Usa `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para deshabilitar el fallback a PI desde el entorno. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -219,53 +193,39 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Con el respaldo desactivado, una sesión falla temprano cuando el arnés solicitado no está -registrado, no admite el proveedor/modelo resuelto o falla antes de -producir efectos secundarios del turno. Eso es intencional para despliegues solo con Codex y -para pruebas en vivo que deben demostrar que realmente se está usando la ruta del servidor de aplicaciones de Codex. +Con el fallback deshabilitado, una sesión falla pronto cuando el harness solicitado no está registrado, no admite el proveedor/modelo resuelto o falla antes de producir efectos secundarios del turno. Eso es intencional para implementaciones exclusivas de Codex y para pruebas en vivo que deben demostrar que la ruta de Codex app-server realmente está en uso. -Esta configuración solo controla el arnés de agente integrado. No desactiva -el enrutamiento específico de modelos para imagen, video, música, TTS, PDF u otros proveedores. +Esta configuración solo controla el harness integrado del agente. No deshabilita el enrutamiento específico del proveedor para modelos de imagen, video, música, TTS, PDF u otros. ## Sesiones nativas y espejo de transcripción -Un arnés puede conservar un ID de sesión nativa, ID de hilo o token de reanudación del lado del daemon. -Mantén esa asociación vinculada explícitamente con la sesión de OpenClaw y sigue -reflejando la salida visible para el usuario del asistente/herramienta en la transcripción de OpenClaw. +Un harness puede conservar un id de sesión nativo, id de hilo o token de reanudación del lado del daemon. Mantén esa vinculación asociada explícitamente con la sesión de OpenClaw y sigue reflejando en la transcripción de OpenClaw la salida visible para el usuario del asistente/herramienta. La transcripción de OpenClaw sigue siendo la capa de compatibilidad para: - historial de sesión visible en el canal - búsqueda e indexación de transcripciones -- volver al arnés PI integrado en un turno posterior -- comportamiento genérico de `/new`, `/reset` y eliminación de sesiones +- volver al harness PI integrado en un turno posterior +- comportamiento genérico de `/new`, `/reset` y eliminación de sesión -Si tu arnés almacena una asociación auxiliar, implementa `reset(...)` para que OpenClaw pueda -borrarla cuando se restablezca la sesión de OpenClaw propietaria. +Si tu harness almacena una vinculación sidecar, implementa `reset(...)` para que OpenClaw pueda borrarla cuando se restablezca la sesión de OpenClaw propietaria. ## Resultados de herramientas y medios -El núcleo construye la lista de herramientas de OpenClaw y la pasa al intento preparado. -Cuando un arnés ejecuta una llamada de herramienta dinámica, devuelve el resultado de la herramienta mediante -la forma de resultado del arnés en lugar de enviar tú mismo el contenido multimedia por el canal. +El núcleo construye la lista de herramientas de OpenClaw y la pasa al intento preparado. Cuando un harness ejecuta una llamada de herramienta dinámica, devuelve el resultado de la herramienta a través de la forma de resultado del harness en lugar de enviar tú mismo los medios del canal. -Esto mantiene las salidas de texto, imagen, video, música, TTS, aprobación y herramientas de mensajería -en la misma ruta de entrega que las ejecuciones respaldadas por PI. +Esto mantiene las salidas de texto, imagen, video, música, TTS, aprobación y herramientas de mensajería en la misma ruta de entrega que las ejecuciones respaldadas por PI. ## Limitaciones actuales -- La ruta pública de importación es genérica, pero algunos alias de tipos de intento/resultado todavía - llevan nombres `Pi` por compatibilidad. -- La instalación de arneses de terceros es experimental. Prefiere plugins de proveedor - hasta que necesites un runtime de sesión nativa. -- Se admite el cambio de arnés entre turnos. No cambies de arnés en medio de un - turno después de que hayan comenzado herramientas nativas, aprobaciones, texto del asistente o - envíos de mensajes. +- La ruta de importación pública es genérica, pero algunos alias de tipos de intento/resultado todavía llevan nombres `Pi` por compatibilidad. +- La instalación de harnesses de terceros es experimental. Prefiere plugins de proveedor hasta que necesites un tiempo de ejecución de sesión nativo. +- Se admite el cambio de harness entre turnos. No cambies de harness en medio de un turno después de que hayan comenzado herramientas nativas, aprobaciones, texto del asistente o envíos de mensajes. ## Relacionado -- [SDK Overview](/es/plugins/sdk-overview) -- [Runtime Helpers](/es/plugins/sdk-runtime) -- [Provider Plugins](/es/plugins/sdk-provider-plugins) +- [Resumen del SDK](/es/plugins/sdk-overview) +- [Helpers de tiempo de ejecución](/es/plugins/sdk-runtime) +- [Plugins de proveedor](/es/plugins/sdk-provider-plugins) - [Codex Harness](/es/plugins/codex-harness) -- [Model Providers](/es/concepts/model-providers) +- [Proveedores de modelos](/es/concepts/model-providers) diff --git a/docs/es/providers/openai.md b/docs/es/providers/openai.md index 0afe40ff8..a3efcb7b1 100644 --- a/docs/es/providers/openai.md +++ b/docs/es/providers/openai.md @@ -1,31 +1,31 @@ --- read_when: - Quieres usar modelos de OpenAI en OpenClaw - - Quieres autenticación con suscripción de Codex en lugar de API keys -summary: Usa OpenAI mediante API keys o suscripción de Codex en OpenClaw + - Quieres la autenticación mediante suscripción a Codex en lugar de claves de API + - Necesitas un comportamiento de ejecución del agente GPT-5 más estricto +summary: Usa OpenAI mediante claves de API o una suscripción a Codex en OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-07T05:06:32Z" + generated_at: "2026-04-12T00:19:04Z" model: gpt-5.4 provider: openai - source_hash: 6a2ce1ce5f085fe55ec50b8d20359180b9002c9730820cd5b0e011c3bf807b64 + source_hash: 7aa06fba9ac901e663685a6b26443a2f6aeb6ec3589d939522dc87cbb43497b4 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAI proporciona APIs para desarrolladores de modelos GPT. Codex admite **inicio de sesión con ChatGPT** para acceso -por suscripción o **inicio de sesión con API key** para acceso basado en uso. La nube de Codex requiere inicio de sesión con ChatGPT. -OpenAI admite explícitamente el uso de OAuth con suscripción en herramientas/flujos de trabajo externos como OpenClaw. +OpenAI proporciona API para desarrolladores para modelos GPT. Codex admite **inicio de sesión con ChatGPT** para acceso por suscripción o **inicio de sesión con clave de API** para acceso basado en uso. Codex cloud requiere inicio de sesión con ChatGPT. +OpenAI admite explícitamente el uso de OAuth de suscripción en herramientas/flujos de trabajo externos como OpenClaw. ## Estilo de interacción predeterminado OpenClaw puede agregar una pequeña superposición de prompt específica de OpenAI tanto para ejecuciones `openai/*` como -`openai-codex/*`. De forma predeterminada, la superposición mantiene al asistente cálido, -colaborativo, conciso, directo y un poco más expresivo emocionalmente -sin reemplazar el prompt base del sistema de OpenClaw. La superposición amistosa también -permite el emoji ocasional cuando encaja de forma natural, al tiempo que mantiene la +`openai-codex/*`. De forma predeterminada, la superposición mantiene al asistente cercano, +colaborativo, conciso, directo y un poco más expresivo emocionalmente, +sin reemplazar el prompt base del sistema de OpenClaw. La superposición amigable también +permite algún emoji ocasional cuando encaja de forma natural, manteniendo a la vez la salida general concisa. Clave de configuración: @@ -36,7 +36,7 @@ Valores permitidos: - `"friendly"`: predeterminado; habilita la superposición específica de OpenAI. - `"on"`: alias de `"friendly"`. -- `"off"`: desactiva la superposición y usa solo el prompt base de OpenClaw. +- `"off"`: deshabilita la superposición y usa solo el prompt base de OpenClaw. Alcance: @@ -44,8 +44,8 @@ Alcance: - Se aplica a los modelos `openai-codex/*`. - No afecta a otros proveedores. -Este comportamiento está activado de forma predeterminada. Mantén `"friendly"` explícitamente si quieres que esto -sobreviva a futuros cambios locales de configuración: +Este comportamiento está activado de forma predeterminada. Mantén `"friendly"` explícitamente si quieres que +esto sobreviva a futuros cambios locales de configuración: ```json5 { @@ -61,9 +61,9 @@ sobreviva a futuros cambios locales de configuración: } ``` -### Desactivar la superposición de prompt de OpenAI +### Deshabilitar la superposición de prompt de OpenAI -Si quieres el prompt base de OpenClaw sin modificar, establece la superposición en `"off"`: +Si quieres el prompt base de OpenClaw sin modificaciones, establece la superposición en `"off"`: ```json5 { @@ -86,24 +86,24 @@ openclaw config set plugins.entries.openai.config.personality off ``` OpenClaw normaliza esta configuración sin distinguir mayúsculas y minúsculas en tiempo de ejecución, por lo que valores como -`"Off"` también desactivan la superposición amistosa. +`"Off"` siguen deshabilitando la superposición amigable. -## Opción A: API key de OpenAI (OpenAI Platform) +## Opción A: clave de API de OpenAI (OpenAI Platform) **Ideal para:** acceso directo a la API y facturación basada en uso. -Obtén tu API key desde el panel de OpenAI. +Obtén tu clave de API desde el panel de OpenAI. Resumen de rutas: - `openai/gpt-5.4` = ruta directa de la API de OpenAI Platform -- Requiere `OPENAI_API_KEY` (o configuración equivalente del proveedor OpenAI) +- Requiere `OPENAI_API_KEY` (o una configuración equivalente del proveedor OpenAI) - En OpenClaw, el inicio de sesión con ChatGPT/Codex se enruta mediante `openai-codex/*`, no `openai/*` -### Configuración en CLI +### Configuración en la CLI ```bash openclaw onboard --auth-choice openai-api-key -# o no interactivo +# o de forma no interactiva openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` @@ -116,25 +116,25 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY" } ``` -La documentación actual de modelos de la API de OpenAI enumera `gpt-5.4` y `gpt-5.4-pro` para uso directo de la -API de OpenAI. OpenClaw reenvía ambos mediante la ruta de Responses `openai/*`. -OpenClaw suprime intencionadamente la fila obsoleta `openai/gpt-5.3-codex-spark`, +La documentación actual de modelos de API de OpenAI enumera `gpt-5.4` y `gpt-5.4-pro` para uso directo de la +API de OpenAI. OpenClaw reenvía ambos a través de la ruta `openai/*` Responses. +OpenClaw suprime intencionalmente la fila obsoleta `openai/gpt-5.3-codex-spark`, porque las llamadas directas a la API de OpenAI la rechazan en tráfico real. -OpenClaw **no** expone `openai/gpt-5.3-codex-spark` en la ruta directa de la API de OpenAI. -`pi-ai` sigue incluyendo una fila integrada para ese modelo, pero las solicitudes reales a la API de OpenAI -la rechazan actualmente. En OpenClaw, Spark se considera solo de Codex. +OpenClaw **no** expone `openai/gpt-5.3-codex-spark` en la ruta directa de la +API de OpenAI. `pi-ai` sigue incluyendo una fila integrada para ese modelo, pero las solicitudes reales a la API de OpenAI +actualmente la rechazan. Spark se trata como exclusivo de Codex en OpenClaw. ## Generación de imágenes -El plugin empaquetado `openai` también registra la generación de imágenes mediante la herramienta compartida +El plugin `openai` incluido también registra la generación de imágenes mediante la herramienta compartida `image_generate`. - Modelo de imagen predeterminado: `openai/gpt-image-1` - Generación: hasta 4 imágenes por solicitud - Modo de edición: habilitado, hasta 5 imágenes de referencia - Admite `size` -- Advertencia específica actual de OpenAI: OpenClaw no reenvía hoy anulaciones de `aspectRatio` ni +- Limitación actual específica de OpenAI: OpenClaw no reenvía hoy las anulaciones de `aspectRatio` ni `resolution` a la API de imágenes de OpenAI Para usar OpenAI como proveedor de imágenes predeterminado: @@ -151,21 +151,21 @@ Para usar OpenAI como proveedor de imágenes predeterminado: } ``` -Consulta [Generación de imágenes](/es/tools/image-generation) para los parámetros -compartidos de herramientas, la selección de proveedor y el comportamiento de failover. +Consulta [Generación de imágenes](/es/tools/image-generation) para ver los parámetros +de la herramienta compartida, la selección de proveedor y el comportamiento de conmutación por error. ## Generación de video -El plugin empaquetado `openai` también registra la generación de video mediante la herramienta compartida +El plugin `openai` incluido también registra la generación de video mediante la herramienta compartida `video_generate`. - Modelo de video predeterminado: `openai/sora-2` - Modos: texto a video, imagen a video y flujos de referencia/edición con un solo video -- Límites actuales: 1 imagen o 1 entrada de referencia de video -- Advertencia específica actual de OpenAI: OpenClaw actualmente solo reenvía anulaciones de `size` - para la generación nativa de video de OpenAI. Las anulaciones opcionales no compatibles +- Límites actuales: 1 imagen o 1 video de referencia como entrada +- Limitación actual específica de OpenAI: OpenClaw actualmente solo reenvía las anulaciones de `size` + para la generación de video nativa de OpenAI. Las anulaciones opcionales no admitidas como `aspectRatio`, `resolution`, `audio` y `watermark` se ignoran - y se devuelven como advertencia de herramienta. + y se devuelven como una advertencia de herramienta. Para usar OpenAI como proveedor de video predeterminado: @@ -181,31 +181,31 @@ Para usar OpenAI como proveedor de video predeterminado: } ``` -Consulta [Generación de video](/es/tools/video-generation) para los parámetros -compartidos de herramientas, la selección de proveedor y el comportamiento de failover. +Consulta [Generación de video](/es/tools/video-generation) para ver los parámetros +de la herramienta compartida, la selección de proveedor y el comportamiento de conmutación por error. ## Opción B: suscripción a OpenAI Code (Codex) -**Ideal para:** usar acceso por suscripción de ChatGPT/Codex en lugar de una API key. -La nube de Codex requiere inicio de sesión con ChatGPT, mientras que la CLI de Codex admite inicio de sesión con ChatGPT o API key. +**Ideal para:** usar acceso por suscripción de ChatGPT/Codex en lugar de una clave de API. +Codex cloud requiere inicio de sesión con ChatGPT, mientras que la CLI de Codex admite inicio de sesión con ChatGPT o con clave de API. Resumen de rutas: - `openai-codex/gpt-5.4` = ruta OAuth de ChatGPT/Codex -- Usa inicio de sesión con ChatGPT/Codex, no una API key directa de OpenAI Platform -- Los límites del proveedor para `openai-codex/*` pueden diferir de la experiencia web/app de ChatGPT +- Usa inicio de sesión con ChatGPT/Codex, no una clave directa de API de OpenAI Platform +- Los límites del lado del proveedor para `openai-codex/*` pueden diferir de la experiencia web/app de ChatGPT -### Configuración en CLI (OAuth de Codex) +### Configuración en la CLI (OAuth de Codex) ```bash -# Ejecutar OAuth de Codex en el asistente +# Ejecuta OAuth de Codex en el asistente openclaw onboard --auth-choice openai-codex -# O ejecutar OAuth directamente +# O ejecuta OAuth directamente openclaw models auth login --provider openai-codex ``` -### Fragmento de configuración (suscripción de Codex) +### Fragmento de configuración (suscripción a Codex) ```json5 { @@ -216,39 +216,40 @@ openclaw models auth login --provider openai-codex La documentación actual de Codex de OpenAI enumera `gpt-5.4` como el modelo actual de Codex. OpenClaw lo asigna a `openai-codex/gpt-5.4` para uso con OAuth de ChatGPT/Codex. -Esta ruta está intencionadamente separada de `openai/gpt-5.4`. Si quieres la -ruta directa de la API de OpenAI Platform, usa `openai/*` con una API key. Si quieres +Esta ruta se mantiene intencionalmente separada de `openai/gpt-5.4`. Si quieres la +ruta directa de la API de OpenAI Platform, usa `openai/*` con una clave de API. Si quieres inicio de sesión con ChatGPT/Codex, usa `openai-codex/*`. -Si la incorporación reutiliza un inicio de sesión existente de Codex CLI, esas credenciales siguen -gestionadas por Codex CLI. Al caducar, OpenClaw vuelve a leer primero la fuente externa de Codex -y, cuando el proveedor puede actualizarla, escribe la credencial actualizada -de vuelta en el almacenamiento de Codex en lugar de asumir la propiedad en una copia separada exclusiva de OpenClaw. +Si el onboarding reutiliza un inicio de sesión existente de la CLI de Codex, esas credenciales seguirán +gestionadas por la CLI de Codex. Cuando caduquen, OpenClaw vuelve a leer primero la fuente externa de Codex +y, cuando el proveedor puede actualizarlas, escribe la credencial actualizada +de vuelta en el almacenamiento de Codex en lugar de asumir la propiedad en una copia separada +solo de OpenClaw. Si tu cuenta de Codex tiene derecho a Codex Spark, OpenClaw también admite: - `openai-codex/gpt-5.3-codex-spark` -OpenClaw trata Codex Spark como exclusivo de Codex. No expone una ruta directa -`openai/gpt-5.3-codex-spark` con API key. +OpenClaw trata Codex Spark como exclusivo de Codex. No expone una ruta directa con clave de API +`openai/gpt-5.3-codex-spark`. OpenClaw también conserva `openai-codex/gpt-5.3-codex-spark` cuando `pi-ai` -lo detecta. Trátalo como dependiente de derechos y experimental: Codex Spark está -separado de GPT-5.4 `/fast`, y la disponibilidad depende de la cuenta de Codex / -ChatGPT con sesión iniciada. +lo detecta. Trátalo como dependiente de derechos y experimental: Codex Spark es +independiente de GPT-5.4 `/fast`, y la disponibilidad depende de la cuenta de Codex / +ChatGPT que haya iniciado sesión. ### Límite de ventana de contexto de Codex -OpenClaw trata los metadatos del modelo de Codex y el límite de contexto en tiempo de ejecución como valores -separados. +OpenClaw trata los metadatos del modelo Codex y el límite de contexto en tiempo de ejecución como +valores separados. Para `openai-codex/gpt-5.4`: - `contextWindow` nativo: `1050000` -- límite predeterminado de `contextTokens` en tiempo de ejecución: `272000` +- límite `contextTokens` predeterminado en tiempo de ejecución: `272000` -Esto mantiene fieles los metadatos del modelo mientras conserva la ventana predeterminada -más pequeña en tiempo de ejecución, que en la práctica tiene mejores características de latencia y calidad. +Esto mantiene fieles los metadatos del modelo y a la vez conserva la ventana predeterminada más pequeña en tiempo de ejecución, +que en la práctica tiene mejores características de latencia y calidad. Si quieres un límite efectivo diferente, establece `models.providers..models[].contextTokens`: @@ -269,50 +270,51 @@ Si quieres un límite efectivo diferente, establece `models.providers. } ``` -Usa `contextWindow` solo cuando estés declarando o anulando metadatos nativos del -modelo. Usa `contextTokens` cuando quieras limitar el presupuesto de contexto en tiempo de ejecución. +Usa `contextWindow` solo cuando estés declarando o anulando metadatos nativos del modelo. +Usa `contextTokens` cuando quieras limitar el presupuesto de contexto en tiempo de ejecución. ### Transporte predeterminado -OpenClaw usa `pi-ai` para el streaming del modelo. Tanto para `openai/*` como para -`openai-codex/*`, el transporte predeterminado es `"auto"` (primero WebSocket, luego -alternativa SSE). +OpenClaw usa `pi-ai` para el streaming de modelos. Tanto para `openai/*` como para +`openai-codex/*`, el transporte predeterminado es `"auto"` (WebSocket primero, luego +respaldo con SSE). -En modo `"auto"`, OpenClaw también reintenta un fallo temprano de WebSocket que se pueda reintentar -antes de pasar a SSE. El modo forzado `"websocket"` sigue mostrando errores de transporte directamente -en lugar de ocultarlos detrás de la alternativa. +En modo `"auto"`, OpenClaw también reintenta un fallo temprano de WebSocket que pueda reintentarse +antes de pasar a SSE. El modo `"websocket"` forzado sigue mostrando los errores de transporte +directamente en lugar de ocultarlos detrás del respaldo. -Después de un fallo de conexión o de un fallo temprano de WebSocket durante el turno en modo `"auto"`, OpenClaw marca -la ruta WebSocket de esa sesión como degradada durante unos 60 segundos y envía los -turnos posteriores por SSE durante el enfriamiento en lugar de alternar continuamente entre -transportes. +Después de un fallo de conexión de WebSocket o de un fallo al inicio del turno en modo `"auto"`, OpenClaw marca +la ruta WebSocket de esa sesión como degradada durante unos 60 segundos y envía +los turnos posteriores por SSE durante el enfriamiento en lugar de alternar +constantemente entre transportes. Para endpoints nativos de la familia OpenAI (`openai/*`, `openai-codex/*` y Azure OpenAI Responses), OpenClaw también adjunta estado estable de identidad de sesión y turno -a las solicitudes para que los reintentos, las reconexiones y la alternativa SSE permanezcan alineados con la misma -identidad de conversación. En las rutas nativas de la familia OpenAI, esto incluye encabezados estables de identidad de solicitud de sesión/turno más metadatos de transporte coincidentes. +a las solicitudes para que los reintentos, las reconexiones y el respaldo con SSE permanezcan alineados con la misma +identidad de conversación. En las rutas nativas de la familia OpenAI esto incluye encabezados estables de identidad de solicitud +de sesión/turno, además de metadatos de transporte coincidentes. -OpenClaw también normaliza los contadores de uso de OpenAI entre variantes de transporte antes de -que lleguen a las superficies de sesión/estado. El tráfico nativo de OpenAI/Codex Responses puede +OpenClaw también normaliza los contadores de uso de OpenAI entre variantes de transporte antes de que +lleguen a las superficies de sesión/estado. El tráfico nativo de OpenAI/Codex Responses puede informar el uso como `input_tokens` / `output_tokens` o `prompt_tokens` / `completion_tokens`; OpenClaw los trata como los mismos contadores de entrada -y salida para `/status`, `/usage` y los registros de sesión. Cuando el tráfico nativo -de WebSocket omite `total_tokens` (o informa `0`), OpenClaw recurre al total normalizado -de entrada + salida para que las pantallas de sesión/estado sigan mostrando datos. +y salida para `/status`, `/usage` y los registros de sesión. Cuando el tráfico nativo por +WebSocket omite `total_tokens` (o informa `0`), OpenClaw recurre al total normalizado de entrada + salida +para que las vistas de sesión/estado sigan mostrando datos. Puedes establecer `agents.defaults.models..params.transport`: - `"sse"`: forzar SSE - `"websocket"`: forzar WebSocket -- `"auto"`: probar WebSocket y luego usar SSE como alternativa +- `"auto"`: intentar WebSocket y luego pasar a SSE -Para `openai/*` (API de Responses), OpenClaw también habilita el calentamiento de WebSocket de forma -predeterminada (`openaiWsWarmup: true`) cuando se usa transporte WebSocket. +Para `openai/*` (API de Responses), OpenClaw también habilita por defecto el calentamiento de WebSocket +(`openaiWsWarmup: true`) cuando se usa transporte WebSocket. Documentación relacionada de OpenAI: -- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) -- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) +- [Realtime API con WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) +- [Respuestas de API en streaming (SSE)](https://platform.openai.com/docs/guides/streaming-responses) ```json5 { @@ -336,7 +338,7 @@ Documentación relacionada de OpenAI: La documentación de OpenAI describe el calentamiento como opcional. OpenClaw lo habilita de forma predeterminada para `openai/*` para reducir la latencia del primer turno cuando se usa transporte WebSocket. -### Desactivar el calentamiento +### Deshabilitar el calentamiento ```json5 { @@ -354,7 +356,7 @@ La documentación de OpenAI describe el calentamiento como opcional. OpenClaw lo } ``` -### Habilitar explícitamente el calentamiento +### Habilitar el calentamiento explícitamente ```json5 { @@ -372,11 +374,11 @@ La documentación de OpenAI describe el calentamiento como opcional. OpenClaw lo } ``` -### Procesamiento prioritario para OpenAI y Codex +### Procesamiento prioritario de OpenAI y Codex La API de OpenAI expone procesamiento prioritario mediante `service_tier=priority`. En OpenClaw, establece `agents.defaults.models["/"].params.serviceTier` -para reenviar ese campo en endpoints nativos de OpenAI/Codex Responses. +para transmitir ese campo en los endpoints nativos de OpenAI/Codex Responses. ```json5 { @@ -401,19 +403,19 @@ para reenviar ese campo en endpoints nativos de OpenAI/Codex Responses. Los valores admitidos son `auto`, `default`, `flex` y `priority`. -OpenClaw reenvía `params.serviceTier` tanto a solicitudes directas de Responses `openai/*` -como a solicitudes de Codex Responses `openai-codex/*` cuando esos modelos apuntan +OpenClaw reenvía `params.serviceTier` tanto a las solicitudes directas de `openai/*` Responses +como a las solicitudes de `openai-codex/*` Codex Responses cuando esos modelos apuntan a los endpoints nativos de OpenAI/Codex. Comportamiento importante: - `openai/*` directo debe apuntar a `api.openai.com` - `openai-codex/*` debe apuntar a `chatgpt.com/backend-api` -- si enrutas cualquiera de los dos proveedores mediante otra URL base o proxy, OpenClaw deja `service_tier` sin cambios +- si enrutas cualquiera de los proveedores a través de otra URL base o proxy, OpenClaw deja `service_tier` intacto ### Modo rápido de OpenAI -OpenClaw expone un interruptor compartido de modo rápido tanto para sesiones `openai/*` como +OpenClaw expone un interruptor compartido de modo rápido para sesiones tanto `openai/*` como `openai-codex/*`: - Chat/UI: `/fast status|on|off` @@ -421,12 +423,12 @@ OpenClaw expone un interruptor compartido de modo rápido tanto para sesiones `o Cuando el modo rápido está habilitado, OpenClaw lo asigna al procesamiento prioritario de OpenAI: -- las llamadas directas de Responses `openai/*` a `api.openai.com` envían `service_tier = "priority"` -- las llamadas de Responses `openai-codex/*` a `chatgpt.com/backend-api` también envían `service_tier = "priority"` +- las llamadas directas de `openai/*` Responses a `api.openai.com` envían `service_tier = "priority"` +- las llamadas de `openai-codex/*` Responses a `chatgpt.com/backend-api` también envían `service_tier = "priority"` - se conservan los valores existentes de `service_tier` en la carga útil - el modo rápido no reescribe `reasoning` ni `text.verbosity` -Para GPT 5.4 concretamente, la configuración más habitual es: +Para GPT 5.4 en concreto, la configuración más común es: - enviar `/fast on` en una sesión que use `openai/gpt-5.4` o `openai-codex/gpt-5.4` - o establecer `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true` @@ -455,49 +457,75 @@ Ejemplo: } ``` -Las anulaciones de sesión prevalecen sobre la configuración. Limpiar la anulación de sesión en la interfaz de Sessions +Las anulaciones de sesión tienen prioridad sobre la configuración. Borrar la anulación de sesión en la UI de Sesiones devuelve la sesión al valor predeterminado configurado. ### Rutas nativas de OpenAI frente a rutas compatibles con OpenAI -OpenClaw trata los endpoints directos de OpenAI, Codex y Azure OpenAI de manera diferente -a los proxies genéricos compatibles con OpenAI `/v1`: +OpenClaw trata los endpoints directos de OpenAI, Codex y Azure OpenAI de forma diferente +a los proxies `/v1` genéricos compatibles con OpenAI: - las rutas nativas `openai/*`, `openai-codex/*` y Azure OpenAI mantienen - `reasoning: { effort: "none" }` intacto cuando desactivas explícitamente el razonamiento -- las rutas nativas de la familia OpenAI usan por defecto esquemas de herramientas en modo estricto + `reasoning: { effort: "none" }` intacto cuando deshabilitas explícitamente el razonamiento +- las rutas nativas de la familia OpenAI usan por defecto el modo estricto para los esquemas de herramientas - los encabezados ocultos de atribución de OpenClaw (`originator`, `version` y `User-Agent`) solo se adjuntan en hosts nativos verificados de OpenAI (`api.openai.com`) y hosts nativos de Codex (`chatgpt.com/backend-api`) -- las rutas nativas de OpenAI/Codex mantienen el moldeado de solicitudes exclusivo de OpenAI, como +- las rutas nativas de OpenAI/Codex mantienen el modelado de solicitudes exclusivo de OpenAI, como `service_tier`, `store` de Responses, cargas útiles de compatibilidad de razonamiento de OpenAI y - pistas de caché de prompt + sugerencias de caché de prompt - las rutas compatibles con OpenAI de estilo proxy mantienen el comportamiento de compatibilidad más flexible y no - fuerzan esquemas estrictos de herramientas, moldeado de solicitudes exclusivo nativo ni encabezados ocultos + fuerzan esquemas de herramientas estrictos, modelado de solicitudes exclusivo nativo ni encabezados ocultos de atribución de OpenAI/Codex -Azure OpenAI permanece dentro del grupo de enrutamiento nativo para el comportamiento de transporte y compatibilidad, +Azure OpenAI permanece en el grupo de rutas nativas para el comportamiento de transporte y compatibilidad, pero no recibe los encabezados ocultos de atribución de OpenAI/Codex. -Esto preserva el comportamiento actual de Responses nativas de OpenAI sin forzar -shims antiguos compatibles con OpenAI sobre backends `/v1` de terceros. +Esto preserva el comportamiento actual de OpenAI Responses nativo sin forzar adaptadores compatibles con OpenAI más antiguos sobre backends `/v1` de terceros. + +### Modo GPT agéntico estricto + +Para ejecuciones de la familia GPT-5 de `openai/*` y `openai-codex/*`, OpenClaw puede usar un +contrato de ejecución de Pi incrustado más estricto: + +```json5 +{ + agents: { + defaults: { + embeddedPi: { + executionContract: "strict-agentic", + }, + }, + }, +} +``` + +Con `strict-agentic`, OpenClaw ya no trata un turno del asistente que solo planifica como +un progreso exitoso cuando hay disponible una acción concreta con herramienta. Reintenta el +turno con una directiva para actuar ahora, habilita automáticamente la herramienta estructurada `update_plan` para +trabajo sustancial y muestra un estado explícito de bloqueo si el modelo sigue +planificando sin actuar. + +Este modo se limita a ejecuciones de la familia GPT-5 de OpenAI y OpenAI Codex. Otros proveedores +y familias de modelos anteriores mantienen el comportamiento predeterminado de Pi incrustado, a menos que los incorpores +a otras configuraciones de tiempo de ejecución. ### Compactación del lado del servidor de OpenAI Responses Para modelos directos de OpenAI Responses (`openai/*` usando `api: "openai-responses"` con -`baseUrl` en `api.openai.com`), OpenClaw ahora habilita automáticamente pistas de carga útil +`baseUrl` en `api.openai.com`), OpenClaw ahora habilita automáticamente las sugerencias de carga útil de compactación del lado del servidor de OpenAI: - Fuerza `store: true` (a menos que la compatibilidad del modelo establezca `supportsStore: false`) - Inyecta `context_management: [{ type: "compaction", compact_threshold: ... }]` -De forma predeterminada, `compact_threshold` es el `70%` de `contextWindow` del modelo (o `80000` +De forma predeterminada, `compact_threshold` es el `70%` del `contextWindow` del modelo (o `80000` cuando no está disponible). ### Habilitar explícitamente la compactación del lado del servidor -Úsalo cuando quieras forzar la inyección de `context_management` en modelos de -Responses compatibles (por ejemplo Azure OpenAI Responses): +Úsalo cuando quieras forzar la inyección de `context_management` en modelos +Responses compatibles (por ejemplo, Azure OpenAI Responses): ```json5 { @@ -534,7 +562,7 @@ Responses compatibles (por ejemplo Azure OpenAI Responses): } ``` -### Desactivar la compactación del lado del servidor +### Deshabilitar la compactación del lado del servidor ```json5 { @@ -558,5 +586,5 @@ Los modelos directos de OpenAI Responses siguen forzando `store: true` a menos q ## Notas -- Las referencias de modelo siempre usan `provider/model` (ver [/concepts/models](/es/concepts/models)). -- Los detalles de autenticación + reglas de reutilización están en [/concepts/oauth](/es/concepts/oauth). +- Las referencias de modelo siempre usan `provider/model` (consulta [/concepts/models](/es/concepts/models)). +- Los detalles de autenticación y las reglas de reutilización están en [/concepts/oauth](/es/concepts/oauth).