chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
13131876af
commit
da963bfe1e
@ -1,31 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Lavoro sulle funzionalità del canale Microsoft Teams
|
||||
summary: Stato del supporto del bot Microsoft Teams, capacità e configurazione
|
||||
- Lavorando sulle funzionalità del canale Microsoft Teams
|
||||
summary: stato del supporto del bot Microsoft Teams, capacità e configurazione
|
||||
title: Microsoft Teams
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:47:21Z"
|
||||
generated_at: "2026-04-12T00:18:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf
|
||||
source_hash: 3e6841a618fb030e4c2029b3652d45dedd516392e2ae17309ff46b93648ffb79
|
||||
source_path: channels/msteams.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Microsoft Teams
|
||||
|
||||
> "Lasciate ogni speranza, voi che entrate qui."
|
||||
> "Lasciate ogni speranza, voi ch'entrate."
|
||||
|
||||
Aggiornato: 2026-01-21
|
||||
Aggiornato: 2026-03-25
|
||||
|
||||
Stato: il testo + gli allegati DM sono supportati; l'invio di file in canali/gruppi richiede `sharePointSiteId` + autorizzazioni Graph (vedi [Invio di file nelle chat di gruppo](#sending-files-in-group-chats)). I sondaggi vengono inviati tramite Adaptive Cards. Le azioni del messaggio espongono `upload-file` esplicito per gli invii con file come primo elemento.
|
||||
Stato: testo + allegati nei DM sono supportati; l'invio di file in canali/gruppi richiede `sharePointSiteId` + autorizzazioni Graph (vedi [Invio di file nelle chat di gruppo](#sending-files-in-group-chats)). I sondaggi vengono inviati tramite Adaptive Cards. Le azioni sui messaggi espongono `upload-file` esplicito per gli invii incentrati sui file.
|
||||
|
||||
## Plugin incluso
|
||||
|
||||
Microsoft Teams viene fornito come plugin incluso nelle attuali versioni di OpenClaw, quindi
|
||||
non è necessaria alcuna installazione separata nella normale build pacchettizzata.
|
||||
Microsoft Teams è distribuito come plugin incluso nelle attuali release di OpenClaw, quindi non è richiesta alcuna installazione separata nella normale build pacchettizzata.
|
||||
|
||||
Se usi una build precedente o un'installazione personalizzata che esclude Teams incluso,
|
||||
Se usi una build meno recente o un'installazione personalizzata che esclude Teams incluso,
|
||||
installalo manualmente:
|
||||
|
||||
```bash
|
||||
@ -38,19 +37,19 @@ Checkout locale (quando esegui da un repository git):
|
||||
openclaw plugins install ./path/to/local/msteams-plugin
|
||||
```
|
||||
|
||||
Dettagli: [Plugins](/tools/plugin)
|
||||
Dettagli: [Plugin](/it/tools/plugin)
|
||||
|
||||
## Configurazione rapida (principianti)
|
||||
|
||||
1. Assicurati che il plugin Microsoft Teams sia disponibile.
|
||||
- Le attuali versioni pacchettizzate di OpenClaw lo includono già.
|
||||
- Le installazioni precedenti/personalizzate possono aggiungerlo manualmente con i comandi sopra.
|
||||
2. Crea un **Azure Bot** (ID app + client secret + ID tenant).
|
||||
- Le attuali release pacchettizzate di OpenClaw lo includono già.
|
||||
- Le installazioni meno recenti/personalizzate possono aggiungerlo manualmente con i comandi sopra.
|
||||
2. Crea un **Azure Bot** (App ID + client secret + tenant ID).
|
||||
3. Configura OpenClaw con queste credenziali.
|
||||
4. Esponi `/api/messages` (porta 3978 per impostazione predefinita) tramite un URL pubblico o un tunnel.
|
||||
5. Installa il pacchetto app Teams e avvia il gateway.
|
||||
5. Installa il pacchetto dell'app Teams e avvia il gateway.
|
||||
|
||||
Configurazione minima:
|
||||
Configurazione minima (client secret):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -66,13 +65,15 @@ Configurazione minima:
|
||||
}
|
||||
```
|
||||
|
||||
Nota: le chat di gruppo sono bloccate per impostazione predefinita (`channels.msteams.groupPolicy: "allowlist"`). Per consentire le risposte nei gruppi, imposta `channels.msteams.groupAllowFrom` (oppure usa `groupPolicy: "open"` per consentire qualsiasi membro, con gate basato su menzione).
|
||||
Per i deployment di produzione, valuta l'uso di [autenticazione federata](#federated-authentication-certificate--managed-identity) (certificato o managed identity) invece dei client secret.
|
||||
|
||||
Nota: le chat di gruppo sono bloccate per impostazione predefinita (`channels.msteams.groupPolicy: "allowlist"`). Per consentire le risposte nei gruppi, imposta `channels.msteams.groupAllowFrom` (oppure usa `groupPolicy: "open"` per consentire qualsiasi membro, con vincolo di menzione).
|
||||
|
||||
## Obiettivi
|
||||
|
||||
- Parlare con OpenClaw tramite DM Teams, chat di gruppo o canali.
|
||||
- Parlare con OpenClaw tramite DM, chat di gruppo o canali di Teams.
|
||||
- Mantenere il routing deterministico: le risposte tornano sempre al canale da cui sono arrivate.
|
||||
- Adottare per impostazione predefinita un comportamento sicuro nei canali (menzioni richieste salvo diversa configurazione).
|
||||
- Adottare per impostazione predefinita un comportamento sicuro nei canali (menzioni obbligatorie salvo configurazione diversa).
|
||||
|
||||
## Scritture di configurazione
|
||||
|
||||
@ -86,7 +87,7 @@ Disabilita con:
|
||||
}
|
||||
```
|
||||
|
||||
## Controllo degli accessi (DM + gruppi)
|
||||
## Controllo accessi (DM + gruppi)
|
||||
|
||||
**Accesso DM**
|
||||
|
||||
@ -95,11 +96,11 @@ Disabilita con:
|
||||
- UPN/nomi visualizzati sono modificabili; la corrispondenza diretta è disabilitata per impostazione predefinita e viene abilitata solo con `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
- La procedura guidata può risolvere i nomi in ID tramite Microsoft Graph quando le credenziali lo consentono.
|
||||
|
||||
**Accesso ai gruppi**
|
||||
**Accesso di gruppo**
|
||||
|
||||
- Predefinito: `channels.msteams.groupPolicy = "allowlist"` (bloccato a meno che non aggiungi `groupAllowFrom`). Usa `channels.defaults.groupPolicy` per sovrascrivere il valore predefinito quando non è impostato.
|
||||
- `channels.msteams.groupAllowFrom` controlla quali mittenti possono attivarsi nelle chat di gruppo/canali (con fallback a `channels.msteams.allowFrom`).
|
||||
- Imposta `groupPolicy: "open"` per consentire qualsiasi membro (comunque con gate basato su menzione per impostazione predefinita).
|
||||
- Predefinito: `channels.msteams.groupPolicy = "allowlist"` (bloccato a meno che tu non aggiunga `groupAllowFrom`). Usa `channels.defaults.groupPolicy` per sovrascrivere il valore predefinito quando non è impostato.
|
||||
- `channels.msteams.groupAllowFrom` controlla quali mittenti possono attivare nelle chat di gruppo/canali (ripiega su `channels.msteams.allowFrom`).
|
||||
- Imposta `groupPolicy: "open"` per consentire qualsiasi membro (comunque con vincolo di menzione per impostazione predefinita).
|
||||
- Per non consentire **alcun canale**, imposta `channels.msteams.groupPolicy: "disabled"`.
|
||||
|
||||
Esempio:
|
||||
@ -115,14 +116,14 @@ Esempio:
|
||||
}
|
||||
```
|
||||
|
||||
**Teams + allowlist canali**
|
||||
**Allowlist Teams + canale**
|
||||
|
||||
- Limita le risposte in gruppi/canali elencando team e canali in `channels.msteams.teams`.
|
||||
- Limita le risposte di gruppo/canale elencando team e canali in `channels.msteams.teams`.
|
||||
- Le chiavi dovrebbero usare ID team stabili e ID conversazione del canale.
|
||||
- Quando `groupPolicy="allowlist"` ed è presente una allowlist di team, vengono accettati solo team/canali elencati (con gate basato su menzione).
|
||||
- La procedura guidata di configurazione accetta voci `Team/Channel` e le memorizza per te.
|
||||
- All'avvio, OpenClaw risolve i nomi nelle allowlist di team/canali e utenti in ID (quando le autorizzazioni Graph lo consentono)
|
||||
e registra la mappatura; i nomi di team/canali non risolti vengono mantenuti così come digitati ma ignorati per il routing per impostazione predefinita, a meno che non sia abilitato `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
- Quando `groupPolicy="allowlist"` ed è presente una allowlist dei team, vengono accettati solo i team/canali elencati (con vincolo di menzione).
|
||||
- La procedura guidata di configurazione accetta voci `Team/Canale` e le memorizza per te.
|
||||
- All'avvio, OpenClaw risolve i nomi di team/canale e degli utenti nelle allowlist in ID (quando le autorizzazioni Graph lo consentono)
|
||||
e registra la mappatura; i nomi di team/canale non risolti vengono mantenuti come digitati ma ignorati per il routing per impostazione predefinita, a meno che non sia abilitato `channels.msteams.dangerouslyAllowNameMatching: true`.
|
||||
|
||||
Esempio:
|
||||
|
||||
@ -146,28 +147,28 @@ Esempio:
|
||||
## Come funziona
|
||||
|
||||
1. Assicurati che il plugin Microsoft Teams sia disponibile.
|
||||
- Le attuali versioni pacchettizzate di OpenClaw lo includono già.
|
||||
- Le installazioni precedenti/personalizzate possono aggiungerlo manualmente con i comandi sopra.
|
||||
2. Crea un **Azure Bot** (ID app + secret + ID tenant).
|
||||
3. Crea un **pacchetto app Teams** che faccia riferimento al bot e includa le autorizzazioni RSC qui sotto.
|
||||
- Le attuali release pacchettizzate di OpenClaw lo includono già.
|
||||
- Le installazioni meno recenti/personalizzate possono aggiungerlo manualmente con i comandi sopra.
|
||||
2. Crea un **Azure Bot** (App ID + secret + tenant ID).
|
||||
3. Crea un **pacchetto app Teams** che faccia riferimento al bot e includa le autorizzazioni RSC riportate sotto.
|
||||
4. Carica/installa l'app Teams in un team (o nell'ambito personale per i DM).
|
||||
5. Configura `msteams` in `~/.openclaw/openclaw.json` (o variabili d'ambiente) e avvia il gateway.
|
||||
6. Per impostazione predefinita, il gateway ascolta il traffico webhook Bot Framework su `/api/messages`.
|
||||
6. Per impostazione predefinita, il gateway resta in ascolto del traffico webhook Bot Framework su `/api/messages`.
|
||||
|
||||
## Configurazione Azure Bot (prerequisiti)
|
||||
## Configurazione di Azure Bot (Prerequisiti)
|
||||
|
||||
Prima di configurare OpenClaw, devi creare una risorsa Azure Bot.
|
||||
|
||||
### Passaggio 1: crea Azure Bot
|
||||
### Passaggio 1: creare Azure Bot
|
||||
|
||||
1. Vai a [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
|
||||
1. Vai a [Crea Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
|
||||
2. Compila la scheda **Basics**:
|
||||
|
||||
| Campo | Valore |
|
||||
| ------------------ | -------------------------------------------------------- |
|
||||
| **Bot handle** | Il nome del tuo bot, ad esempio `openclaw-msteams` (deve essere univoco) |
|
||||
| **Bot handle** | Il nome del tuo bot, ad es. `openclaw-msteams` (deve essere univoco) |
|
||||
| **Subscription** | Seleziona la tua sottoscrizione Azure |
|
||||
| **Resource group** | Creane uno nuovo o usane uno esistente |
|
||||
| **Resource group** | Creane uno nuovo o usa uno esistente |
|
||||
| **Pricing tier** | **Free** per sviluppo/test |
|
||||
| **Type of App** | **Single Tenant** (consigliato - vedi nota sotto) |
|
||||
| **Creation type** | **Create new Microsoft App ID** |
|
||||
@ -176,27 +177,169 @@ Prima di configurare OpenClaw, devi creare una risorsa Azure Bot.
|
||||
|
||||
3. Fai clic su **Review + create** → **Create** (attendi ~1-2 minuti)
|
||||
|
||||
### Passaggio 2: ottieni le credenziali
|
||||
### Passaggio 2: ottenere le credenziali
|
||||
|
||||
1. Vai alla tua risorsa Azure Bot → **Configuration**
|
||||
2. Copia **Microsoft App ID** → questo è il tuo `appId`
|
||||
3. Fai clic su **Manage Password** → vai all'App Registration
|
||||
3. Fai clic su **Manage Password** → vai alla registrazione dell'app
|
||||
4. In **Certificates & secrets** → **New client secret** → copia il **Value** → questo è il tuo `appPassword`
|
||||
5. Vai a **Overview** → copia **Directory (tenant) ID** → questo è il tuo `tenantId`
|
||||
5. Vai su **Overview** → copia **Directory (tenant) ID** → questo è il tuo `tenantId`
|
||||
|
||||
### Passaggio 3: configura l'endpoint di messaggistica
|
||||
### Passaggio 3: configurare l'endpoint di messaggistica
|
||||
|
||||
1. In Azure Bot → **Configuration**
|
||||
2. Imposta **Messaging endpoint** sul tuo URL webhook:
|
||||
- Produzione: `https://your-domain.com/api/messages`
|
||||
- Sviluppo locale: usa un tunnel (vedi [Sviluppo locale](#local-development-tunneling) sotto)
|
||||
|
||||
### Passaggio 4: abilita il canale Teams
|
||||
### Passaggio 4: abilitare il canale Teams
|
||||
|
||||
1. In Azure Bot → **Channels**
|
||||
2. Fai clic su **Microsoft Teams** → Configure → Save
|
||||
3. Accetta i Termini di servizio
|
||||
|
||||
## Autenticazione federata (certificato + Managed Identity)
|
||||
|
||||
> Aggiunto in 2026.3.24
|
||||
|
||||
Per i deployment di produzione, OpenClaw supporta **l'autenticazione federata** come alternativa più sicura ai client secret. Sono disponibili due metodi:
|
||||
|
||||
### Opzione A: autenticazione basata su certificato
|
||||
|
||||
Usa un certificato PEM registrato nella registrazione app Entra ID.
|
||||
|
||||
**Configurazione:**
|
||||
|
||||
1. Genera o ottieni un certificato (formato PEM con chiave privata).
|
||||
2. In Entra ID → Registrazione app → **Certificates & secrets** → **Certificates** → carica il certificato pubblico.
|
||||
|
||||
**Config:**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
certificatePath: "/path/to/cert.pem",
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Variabili d'ambiente:**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem`
|
||||
|
||||
### Opzione B: Azure Managed Identity
|
||||
|
||||
Usa Azure Managed Identity per un'autenticazione senza password. È l'opzione ideale per i deployment su infrastruttura Azure (AKS, App Service, VM Azure) dove è disponibile una managed identity.
|
||||
|
||||
**Come funziona:**
|
||||
|
||||
1. Il pod/VM del bot ha una managed identity (assegnata dal sistema o dall'utente).
|
||||
2. Una **federated identity credential** collega la managed identity alla registrazione app Entra ID.
|
||||
3. In fase di esecuzione, OpenClaw usa `@azure/identity` per acquisire token dall'endpoint Azure IMDS (`169.254.169.254`).
|
||||
4. Il token viene passato all'SDK Teams per l'autenticazione del bot.
|
||||
|
||||
**Prerequisiti:**
|
||||
|
||||
- Infrastruttura Azure con managed identity abilitata (AKS workload identity, App Service, VM)
|
||||
- Federated identity credential creata sulla registrazione app Entra ID
|
||||
- Accesso di rete a IMDS (`169.254.169.254:80`) dal pod/VM
|
||||
|
||||
**Config (managed identity assegnata dal sistema):**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
useManagedIdentity: true,
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Config (managed identity assegnata dall'utente):**
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
msteams: {
|
||||
enabled: true,
|
||||
appId: "<APP_ID>",
|
||||
tenantId: "<TENANT_ID>",
|
||||
authType: "federated",
|
||||
useManagedIdentity: true,
|
||||
managedIdentityClientId: "<MI_CLIENT_ID>",
|
||||
webhook: { port: 3978, path: "/api/messages" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Variabili d'ambiente:**
|
||||
|
||||
- `MSTEAMS_AUTH_TYPE=federated`
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY=true`
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>` (solo per quelle assegnate dall'utente)
|
||||
|
||||
### Configurazione AKS Workload Identity
|
||||
|
||||
Per deployment AKS che usano workload identity:
|
||||
|
||||
1. **Abilita workload identity** sul cluster AKS.
|
||||
2. **Crea una federated identity credential** sulla registrazione app Entra ID:
|
||||
|
||||
```bash
|
||||
az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{
|
||||
"name": "my-bot-workload-identity",
|
||||
"issuer": "<AKS_OIDC_ISSUER_URL>",
|
||||
"subject": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>",
|
||||
"audiences": ["api://AzureADTokenExchange"]
|
||||
}'
|
||||
```
|
||||
|
||||
3. **Annota il service account Kubernetes** con l'ID client dell'app:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ServiceAccount
|
||||
metadata:
|
||||
name: my-bot-sa
|
||||
annotations:
|
||||
azure.workload.identity/client-id: "<APP_CLIENT_ID>"
|
||||
```
|
||||
|
||||
4. **Etichetta il pod** per l'iniezione della workload identity:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
labels:
|
||||
azure.workload.identity/use: "true"
|
||||
```
|
||||
|
||||
5. **Assicurati l'accesso di rete** a IMDS (`169.254.169.254`) — se usi NetworkPolicy, aggiungi una regola di uscita che consenta traffico verso `169.254.169.254/32` sulla porta 80.
|
||||
|
||||
### Confronto dei tipi di autenticazione
|
||||
|
||||
| Metodo | Config | Vantaggi | Svantaggi |
|
||||
| -------------------- | ---------------------------------------------- | ---------------------------------- | ------------------------------------- |
|
||||
| **Client secret** | `appPassword` | Configurazione semplice | Rotazione del secret richiesta, meno sicuro |
|
||||
| **Certificate** | `authType: "federated"` + `certificatePath` | Nessun secret condiviso sulla rete | Sovraccarico nella gestione dei certificati |
|
||||
| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | Senza password, nessun secret da gestire | Richiede infrastruttura Azure |
|
||||
|
||||
**Comportamento predefinito:** quando `authType` non è impostato, OpenClaw usa per impostazione predefinita l'autenticazione con client secret. Le configurazioni esistenti continuano a funzionare senza modifiche.
|
||||
|
||||
## Sviluppo locale (tunneling)
|
||||
|
||||
Teams non può raggiungere `localhost`. Usa un tunnel per lo sviluppo locale:
|
||||
@ -205,7 +348,7 @@ Teams non può raggiungere `localhost`. Usa un tunnel per lo sviluppo locale:
|
||||
|
||||
```bash
|
||||
ngrok http 3978
|
||||
# Copia l'URL https, ad esempio https://abc123.ngrok.io
|
||||
# Copia l'URL https, ad es. https://abc123.ngrok.io
|
||||
# Imposta l'endpoint di messaggistica su: https://abc123.ngrok.io/api/messages
|
||||
```
|
||||
|
||||
@ -221,12 +364,12 @@ tailscale funnel 3978
|
||||
Invece di creare manualmente un file ZIP del manifest, puoi usare il [Teams Developer Portal](https://dev.teams.microsoft.com/apps):
|
||||
|
||||
1. Fai clic su **+ New app**
|
||||
2. Compila le informazioni di base (nome, descrizione, informazioni sullo sviluppatore)
|
||||
2. Compila le informazioni di base (nome, descrizione, informazioni sviluppatore)
|
||||
3. Vai a **App features** → **Bot**
|
||||
4. Seleziona **Enter a bot ID manually** e incolla il tuo Azure Bot App ID
|
||||
4. Seleziona **Enter a bot ID manually** e incolla l'App ID del tuo Azure Bot
|
||||
5. Seleziona gli ambiti: **Personal**, **Team**, **Group Chat**
|
||||
6. Fai clic su **Distribute** → **Download app package**
|
||||
7. In Teams: **Apps** → **Manage your apps** → **Upload a custom app** → seleziona il file ZIP
|
||||
7. In Teams: **Apps** → **Manage your apps** → **Upload a custom app** → seleziona lo ZIP
|
||||
|
||||
Spesso è più semplice che modificare manualmente i manifest JSON.
|
||||
|
||||
@ -236,27 +379,27 @@ Spesso è più semplice che modificare manualmente i manifest JSON.
|
||||
|
||||
1. In Azure Portal → la tua risorsa Azure Bot → **Test in Web Chat**
|
||||
2. Invia un messaggio: dovresti vedere una risposta
|
||||
3. Questo conferma che il tuo endpoint webhook funziona prima della configurazione Teams
|
||||
3. Questo conferma che il tuo endpoint webhook funziona prima della configurazione di Teams
|
||||
|
||||
**Opzione B: Teams (dopo l'installazione dell'app)**
|
||||
|
||||
1. Installa l'app Teams (sideload o catalogo org)
|
||||
1. Installa l'app Teams (sideload o catalogo organizzazione)
|
||||
2. Trova il bot in Teams e invia un DM
|
||||
3. Controlla i log del gateway per l'attività in ingresso
|
||||
|
||||
## Configurazione (solo testo minima)
|
||||
## Configurazione (solo testo, minima)
|
||||
|
||||
1. **Assicurati che il plugin Microsoft Teams sia disponibile**
|
||||
- Le attuali versioni pacchettizzate di OpenClaw lo includono già.
|
||||
- Le installazioni precedenti/personalizzate possono aggiungerlo manualmente:
|
||||
- Le attuali release pacchettizzate di OpenClaw lo includono già.
|
||||
- Le installazioni meno recenti/personalizzate possono aggiungerlo manualmente:
|
||||
- Da npm: `openclaw plugins install @openclaw/msteams`
|
||||
- Da un checkout locale: `openclaw plugins install ./path/to/local/msteams-plugin`
|
||||
|
||||
2. **Registrazione del bot**
|
||||
- Crea un Azure Bot (vedi sopra) e annota:
|
||||
- ID app
|
||||
- Client secret (password app)
|
||||
- ID tenant (single-tenant)
|
||||
- App ID
|
||||
- Client secret (password dell'app)
|
||||
- Tenant ID (single-tenant)
|
||||
|
||||
3. **Manifest dell'app Teams**
|
||||
- Includi una voce `bot` con `botId = <App ID>`.
|
||||
@ -286,35 +429,40 @@ Spesso è più semplice che modificare manualmente i manifest JSON.
|
||||
- `MSTEAMS_APP_ID`
|
||||
- `MSTEAMS_APP_PASSWORD`
|
||||
- `MSTEAMS_TENANT_ID`
|
||||
- `MSTEAMS_AUTH_TYPE` (facoltativo: `"secret"` o `"federated"`)
|
||||
- `MSTEAMS_CERTIFICATE_PATH` (federated + certificato)
|
||||
- `MSTEAMS_CERTIFICATE_THUMBPRINT` (facoltativo, non richiesto per l'autenticazione)
|
||||
- `MSTEAMS_USE_MANAGED_IDENTITY` (federated + managed identity)
|
||||
- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID` (solo MI assegnata dall'utente)
|
||||
|
||||
5. **Endpoint del bot**
|
||||
- Imposta l'Azure Bot Messaging Endpoint su:
|
||||
- `https://<host>:3978/api/messages` (o il tuo percorso/porta scelti).
|
||||
- Imposta il Messaging Endpoint di Azure Bot su:
|
||||
- `https://<host>:3978/api/messages` (oppure il percorso/porta che hai scelto).
|
||||
|
||||
6. **Esegui il gateway**
|
||||
- Il canale Teams si avvia automaticamente quando il plugin incluso o installato manualmente è disponibile e la configurazione `msteams` esiste con le credenziali.
|
||||
|
||||
## Azione informazioni membro
|
||||
|
||||
OpenClaw espone un'azione `member-info` supportata da Graph per Microsoft Teams in modo che agenti e automazioni possano risolvere i dettagli dei membri del canale (nome visualizzato, email, ruolo) direttamente da Microsoft Graph.
|
||||
OpenClaw espone un'azione `member-info` supportata da Graph per Microsoft Teams, così agenti e automazioni possono risolvere direttamente da Microsoft Graph i dettagli dei membri del canale (nome visualizzato, email, ruolo).
|
||||
|
||||
Requisiti:
|
||||
|
||||
- Autorizzazione RSC `Member.Read.Group` (già presente nel manifest consigliato)
|
||||
- Per ricerche tra team diversi: autorizzazione applicazione Graph `User.Read.All` con consenso amministratore
|
||||
- Autorizzazione RSC `Member.Read.Group` (già inclusa nel manifest consigliato)
|
||||
- Per ricerche tra team diversi: autorizzazione applicativa Graph `User.Read.All` con consenso amministratore
|
||||
|
||||
L'azione è controllata da `channels.msteams.actions.memberInfo` (predefinito: abilitata quando sono disponibili credenziali Graph).
|
||||
|
||||
## Contesto cronologia
|
||||
|
||||
- `channels.msteams.historyLimit` controlla quanti messaggi recenti di canale/gruppo vengono inseriti nel prompt.
|
||||
- Usa come fallback `messages.groupChat.historyLimit`. Imposta `0` per disabilitare (predefinito 50).
|
||||
- La cronologia del thread recuperata viene filtrata tramite allowlist dei mittenti (`allowFrom` / `groupAllowFrom`), quindi l'inizializzazione del contesto del thread include solo messaggi di mittenti consentiti.
|
||||
- Il contesto degli allegati citati (`ReplyTo*` derivato dall'HTML di risposta Teams) viene attualmente passato così come ricevuto.
|
||||
- In altre parole, le allowlist controllano chi può attivare l'agente; oggi vengono filtrati solo specifici percorsi di contesto supplementare.
|
||||
- Ripiega su `messages.groupChat.historyLimit`. Imposta `0` per disabilitare (predefinito 50).
|
||||
- La cronologia del thread recuperata viene filtrata dalle allowlist dei mittenti (`allowFrom` / `groupAllowFrom`), quindi il seeding del contesto del thread include solo messaggi provenienti da mittenti consentiti.
|
||||
- Il contesto degli allegati citati (`ReplyTo*` derivato dall'HTML di risposta di Teams) attualmente viene passato così come ricevuto.
|
||||
- In altre parole, le allowlist controllano chi può attivare l'agente; oggi solo alcuni percorsi di contesto supplementare specifici vengono filtrati.
|
||||
- La cronologia DM può essere limitata con `channels.msteams.dmHistoryLimit` (turni utente). Override per utente: `channels.msteams.dms["<user_id>"].historyLimit`.
|
||||
|
||||
## Autorizzazioni RSC Teams attuali (Manifest)
|
||||
## Autorizzazioni RSC Teams attuali (manifest)
|
||||
|
||||
Queste sono le **attuali autorizzazioni resourceSpecific** nel nostro manifest dell'app Teams. Si applicano solo all'interno del team/chat in cui l'app è installata.
|
||||
|
||||
@ -382,72 +530,72 @@ Esempio minimo e valido con i campi richiesti. Sostituisci ID e URL.
|
||||
}
|
||||
```
|
||||
|
||||
### Limitazioni del manifest (campi obbligatori)
|
||||
### Avvertenze sul manifest (campi indispensabili)
|
||||
|
||||
- `bots[].botId` **deve** corrispondere all'Azure Bot App ID.
|
||||
- `webApplicationInfo.id` **deve** corrispondere all'Azure Bot App ID.
|
||||
- `bots[].botId` **deve** corrispondere all'App ID di Azure Bot.
|
||||
- `webApplicationInfo.id` **deve** corrispondere all'App ID di Azure Bot.
|
||||
- `bots[].scopes` deve includere le superfici che intendi usare (`personal`, `team`, `groupChat`).
|
||||
- `bots[].supportsFiles: true` è richiesto per la gestione dei file nell'ambito personale.
|
||||
- `authorization.permissions.resourceSpecific` deve includere lettura/invio canale se vuoi traffico canale.
|
||||
- `authorization.permissions.resourceSpecific` deve includere lettura/invio del canale se vuoi traffico del canale.
|
||||
|
||||
### Aggiornare un'app esistente
|
||||
|
||||
Per aggiornare un'app Teams già installata (ad esempio, per aggiungere autorizzazioni RSC):
|
||||
Per aggiornare un'app Teams già installata (ad esempio per aggiungere autorizzazioni RSC):
|
||||
|
||||
1. Aggiorna il tuo `manifest.json` con le nuove impostazioni
|
||||
2. **Incrementa il campo `version`** (ad esempio `1.0.0` → `1.1.0`)
|
||||
3. **Ricomprimi** il manifest con le icone (`manifest.json`, `outline.png`, `color.png`)
|
||||
2. **Incrementa il campo `version`** (ad es. `1.0.0` → `1.1.0`)
|
||||
3. **Ricrea lo ZIP** del manifest con le icone (`manifest.json`, `outline.png`, `color.png`)
|
||||
4. Carica il nuovo zip:
|
||||
- **Opzione A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → trova la tua app → Upload new version
|
||||
- **Opzione B (Sideload):** In Teams → Apps → Manage your apps → Upload a custom app
|
||||
5. **Per i canali team:** reinstalla l'app in ogni team affinché le nuove autorizzazioni abbiano effetto
|
||||
6. **Chiudi completamente e riavvia Teams** (non solo chiudere la finestra) per cancellare i metadati dell'app memorizzati nella cache
|
||||
5. **Per i canali del team:** reinstalla l'app in ogni team affinché le nuove autorizzazioni abbiano effetto
|
||||
6. **Chiudi completamente e riavvia Teams** (non limitarti a chiudere la finestra) per svuotare i metadati dell'app nella cache
|
||||
|
||||
## Capacità: solo RSC vs Graph
|
||||
|
||||
### Con **solo Teams RSC** (app installata, nessuna autorizzazione API Graph)
|
||||
### Con **solo Teams RSC** (app installata, senza autorizzazioni API Graph)
|
||||
|
||||
Funziona:
|
||||
|
||||
- Lettura del contenuto **testuale** dei messaggi di canale.
|
||||
- Invio del contenuto **testuale** dei messaggi di canale.
|
||||
- Ricezione di allegati file **personali (DM)**.
|
||||
- Leggere il contenuto **testuale** dei messaggi del canale.
|
||||
- Inviare il contenuto **testuale** dei messaggi del canale.
|
||||
- Ricevere allegati di file nei **messaggi personali (DM)**.
|
||||
|
||||
NON funziona:
|
||||
|
||||
- **Contenuto di immagini o file** in canali/gruppi (il payload include solo uno stub HTML).
|
||||
- Contenuti di **immagini o file** in canali/gruppi (il payload include solo uno stub HTML).
|
||||
- Download di allegati archiviati in SharePoint/OneDrive.
|
||||
- Lettura della cronologia messaggi (oltre l'evento webhook in tempo reale).
|
||||
- Lettura della cronologia dei messaggi (oltre l'evento webhook live).
|
||||
|
||||
### Con **Teams RSC + autorizzazioni applicazione Microsoft Graph**
|
||||
### Con **Teams RSC + autorizzazioni applicative Microsoft Graph**
|
||||
|
||||
Aggiunge:
|
||||
|
||||
- Download dei contenuti ospitati (immagini incollate nei messaggi).
|
||||
- Download degli allegati file archiviati in SharePoint/OneDrive.
|
||||
- Download di contenuti ospitati (immagini incollate nei messaggi).
|
||||
- Download di allegati di file archiviati in SharePoint/OneDrive.
|
||||
- Lettura della cronologia dei messaggi di canale/chat tramite Graph.
|
||||
|
||||
### RSC vs API Graph
|
||||
|
||||
| Capacità | Autorizzazioni RSC | API Graph |
|
||||
| ----------------------- | -------------------- | ----------------------------------- |
|
||||
| Capacità | Autorizzazioni RSC | API Graph |
|
||||
| ----------------------- | --------------------- | ----------------------------------- |
|
||||
| **Messaggi in tempo reale** | Sì (tramite webhook) | No (solo polling) |
|
||||
| **Messaggi storici** | No | Sì (può interrogare la cronologia) |
|
||||
| **Complessità di setup** | Solo manifest app | Richiede consenso amministratore + flusso token |
|
||||
| **Messaggi storici** | No | Sì (può interrogare la cronologia) |
|
||||
| **Complessità di configurazione** | Solo manifest dell'app | Richiede consenso amministratore + flusso token |
|
||||
| **Funziona offline** | No (deve essere in esecuzione) | Sì (interrogabile in qualsiasi momento) |
|
||||
|
||||
**In sintesi:** RSC serve per l'ascolto in tempo reale; l'API Graph serve per l'accesso storico. Per recuperare i messaggi persi mentre si è offline, serve l'API Graph con `ChannelMessage.Read.All` (richiede consenso amministratore).
|
||||
**In sintesi:** RSC serve per l'ascolto in tempo reale; l'API Graph serve per l'accesso storico. Per recuperare i messaggi persi mentre eri offline, ti serve l'API Graph con `ChannelMessage.Read.All` (richiede consenso amministratore).
|
||||
|
||||
## Media + cronologia abilitati da Graph (richiesti per i canali)
|
||||
|
||||
Se hai bisogno di immagini/file nei **canali** o vuoi recuperare la **cronologia dei messaggi**, devi abilitare le autorizzazioni Microsoft Graph e concedere il consenso amministratore.
|
||||
Se ti servono immagini/file nei **canali** o vuoi recuperare la **cronologia dei messaggi**, devi abilitare le autorizzazioni Microsoft Graph e concedere il consenso amministratore.
|
||||
|
||||
1. In Entra ID (Azure AD) **App Registration**, aggiungi autorizzazioni Microsoft Graph **Application**:
|
||||
- `ChannelMessage.Read.All` (allegati canale + cronologia)
|
||||
1. In Entra ID (Azure AD) **App Registration**, aggiungi autorizzazioni **Application** Microsoft Graph:
|
||||
- `ChannelMessage.Read.All` (allegati dei canali + cronologia)
|
||||
- `Chat.Read.All` o `ChatMessage.Read.All` (chat di gruppo)
|
||||
2. **Concedi il consenso amministratore** per il tenant.
|
||||
3. Incrementa la **versione del manifest** dell'app Teams, ricaricala e **reinstalla l'app in Teams**.
|
||||
4. **Chiudi completamente e riavvia Teams** per cancellare i metadati dell'app memorizzati nella cache.
|
||||
3. Incrementa la **versione del manifest** dell'app Teams, ricaricalo e **reinstalla l'app in Teams**.
|
||||
4. **Chiudi completamente e riavvia Teams** per svuotare i metadati dell'app nella cache.
|
||||
|
||||
**Autorizzazione aggiuntiva per le menzioni utente:** le @mention utente funzionano subito per gli utenti nella conversazione. Tuttavia, se vuoi cercare dinamicamente e menzionare utenti che **non sono nella conversazione corrente**, aggiungi l'autorizzazione `User.Read.All` (Application) e concedi il consenso amministratore.
|
||||
|
||||
@ -455,73 +603,78 @@ Se hai bisogno di immagini/file nei **canali** o vuoi recuperare la **cronologia
|
||||
|
||||
### Timeout webhook
|
||||
|
||||
Teams consegna i messaggi tramite webhook HTTP. Se l'elaborazione richiede troppo tempo (ad esempio risposte LLM lente), potresti vedere:
|
||||
Teams consegna i messaggi tramite webhook HTTP. Se l'elaborazione richiede troppo tempo (ad es. risposte LLM lente), potresti vedere:
|
||||
|
||||
- Timeout del gateway
|
||||
- Teams che ritenta il messaggio (causando duplicati)
|
||||
- Risposte perse
|
||||
|
||||
OpenClaw gestisce questo problema restituendo rapidamente e inviando le risposte in modo proattivo, ma risposte molto lente possono comunque causare problemi.
|
||||
OpenClaw lo gestisce rispondendo rapidamente e inviando le risposte in modo proattivo, ma risposte molto lente possono comunque causare problemi.
|
||||
|
||||
### Formattazione
|
||||
|
||||
Il markdown di Teams è più limitato di Slack o Discord:
|
||||
Il markdown di Teams è più limitato rispetto a Slack o Discord:
|
||||
|
||||
- La formattazione di base funziona: **grassetto**, _corsivo_, `code`, link
|
||||
- Il markdown complesso (tabelle, elenchi annidati) potrebbe non essere renderizzato correttamente
|
||||
- Le Adaptive Cards sono supportate per sondaggi e invii arbitrari di card (vedi sotto)
|
||||
- Markdown complesso (tabelle, elenchi annidati) potrebbe non essere renderizzato correttamente
|
||||
- Le Adaptive Cards sono supportate per i sondaggi e per l'invio arbitrario di card (vedi sotto)
|
||||
|
||||
## Configurazione
|
||||
|
||||
Impostazioni principali (vedi `/gateway/configuration` per i pattern canale condivisi):
|
||||
Impostazioni chiave (vedi `/gateway/configuration` per i modelli condivisi dei canali):
|
||||
|
||||
- `channels.msteams.enabled`: abilita/disabilita il canale.
|
||||
- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: credenziali del bot.
|
||||
- `channels.msteams.webhook.port` (predefinito `3978`)
|
||||
- `channels.msteams.webhook.path` (predefinito `/api/messages`)
|
||||
- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (predefinito: pairing)
|
||||
- `channels.msteams.allowFrom`: allowlist DM (consigliati ID oggetto AAD). La procedura guidata risolve i nomi in ID durante la configurazione quando l'accesso Graph è disponibile.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching`: interruttore di emergenza per riabilitare la corrispondenza con UPN/nome visualizzato modificabili e il routing diretto per nome team/canale.
|
||||
- `channels.msteams.textChunkLimit`: dimensione chunk testo in uscita.
|
||||
- `channels.msteams.chunkMode`: `length` (predefinito) o `newline` per dividere sulle righe vuote (confini di paragrafo) prima del chunking per lunghezza.
|
||||
- `channels.msteams.mediaAllowHosts`: allowlist per host di allegati in ingresso (predefinito: domini Microsoft/Teams).
|
||||
- `channels.msteams.mediaAuthAllowHosts`: allowlist per allegare header Authorization ai retry dei media (predefinito: host Graph + Bot Framework).
|
||||
- `channels.msteams.allowFrom`: allowlist DM (consigliati gli ID oggetto AAD). La procedura guidata risolve i nomi in ID durante la configurazione quando è disponibile l'accesso a Graph.
|
||||
- `channels.msteams.dangerouslyAllowNameMatching`: interruttore di emergenza per riattivare la corrispondenza con UPN/nomi visualizzati modificabili e il routing diretto per nome di team/canale.
|
||||
- `channels.msteams.textChunkLimit`: dimensione dei blocchi di testo in uscita.
|
||||
- `channels.msteams.chunkMode`: `length` (predefinito) oppure `newline` per suddividere sulle righe vuote (confini di paragrafo) prima della suddivisione per lunghezza.
|
||||
- `channels.msteams.mediaAllowHosts`: allowlist per gli host degli allegati in ingresso (predefinita ai domini Microsoft/Teams).
|
||||
- `channels.msteams.mediaAuthAllowHosts`: allowlist per allegare header Authorization nei tentativi di recupero dei media (predefinita agli host Graph + Bot Framework).
|
||||
- `channels.msteams.requireMention`: richiede @mention in canali/gruppi (predefinito true).
|
||||
- `channels.msteams.replyStyle`: `thread | top-level` (vedi [Stile di risposta](#reply-style-threads-vs-posts)).
|
||||
- `channels.msteams.teams.<teamId>.replyStyle`: override per team.
|
||||
- `channels.msteams.teams.<teamId>.requireMention`: override per team.
|
||||
- `channels.msteams.teams.<teamId>.tools`: override predefiniti dei criteri strumenti per team (`allow`/`deny`/`alsoAllow`) usati quando manca un override di canale.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender`: override predefiniti dei criteri strumenti per team per mittente (`"*"` wildcard supportato).
|
||||
- `channels.msteams.teams.<teamId>.tools`: override predefiniti per team delle policy degli strumenti (`allow`/`deny`/`alsoAllow`) usati quando manca un override di canale.
|
||||
- `channels.msteams.teams.<teamId>.toolsBySender`: override predefiniti per team delle policy degli strumenti per mittente (supportato il wildcard `"*"`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: override per canale.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: override per canale.
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: override dei criteri strumenti per canale (`allow`/`deny`/`alsoAllow`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: override dei criteri strumenti per canale per mittente (`"*"` wildcard supportato).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: override delle policy degli strumenti per canale (`allow`/`deny`/`alsoAllow`).
|
||||
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: override delle policy degli strumenti per mittente a livello di canale (supportato il wildcard `"*"`).
|
||||
- Le chiavi `toolsBySender` dovrebbero usare prefissi espliciti:
|
||||
`id:`, `e164:`, `username:`, `name:` (le chiavi legacy senza prefisso continuano a essere mappate solo a `id:`).
|
||||
- `channels.msteams.actions.memberInfo`: abilita o disabilita l'azione informazioni membro supportata da Graph (predefinito: abilitata quando sono disponibili credenziali Graph).
|
||||
- `channels.msteams.sharePointSiteId`: ID sito SharePoint per caricamenti file in chat di gruppo/canali (vedi [Invio di file nelle chat di gruppo](#sending-files-in-group-chats)).
|
||||
- `channels.msteams.authType`: tipo di autenticazione — `"secret"` (predefinito) oppure `"federated"`.
|
||||
- `channels.msteams.certificatePath`: percorso del file certificato PEM (federated + autenticazione con certificato).
|
||||
- `channels.msteams.certificateThumbprint`: thumbprint del certificato (facoltativo, non richiesto per l'autenticazione).
|
||||
- `channels.msteams.useManagedIdentity`: abilita l'autenticazione con managed identity (modalità federated).
|
||||
- `channels.msteams.managedIdentityClientId`: ID client per managed identity assegnata dall'utente.
|
||||
- `channels.msteams.sharePointSiteId`: ID sito SharePoint per i caricamenti di file nelle chat di gruppo/canali (vedi [Invio di file nelle chat di gruppo](#sending-files-in-group-chats)).
|
||||
|
||||
## Routing e sessioni
|
||||
|
||||
- Le chiavi di sessione seguono il formato agente standard (vedi [/concepts/session](/concepts/session)):
|
||||
- Le chiavi di sessione seguono il formato standard degli agenti (vedi [/concepts/session](/it/concepts/session)):
|
||||
- I messaggi diretti condividono la sessione principale (`agent:<agentId>:<mainKey>`).
|
||||
- I messaggi di canale/gruppo usano l'id conversazione:
|
||||
- I messaggi di canale/gruppo usano l'ID conversazione:
|
||||
- `agent:<agentId>:msteams:channel:<conversationId>`
|
||||
- `agent:<agentId>:msteams:group:<conversationId>`
|
||||
|
||||
## Stile di risposta: thread vs post
|
||||
|
||||
Teams ha recentemente introdotto due stili UI per i canali sullo stesso modello dati sottostante:
|
||||
Teams ha recentemente introdotto due stili UI per i canali sulla stessa struttura dati sottostante:
|
||||
|
||||
| Stile | Descrizione | `replyStyle` consigliato |
|
||||
| ----------------------- | -------------------------------------------------------- | ------------------------ |
|
||||
| **Posts** (classico) | I messaggi appaiono come card con risposte in thread sotto | `thread` (predefinito) |
|
||||
| **Threads** (simile a Slack) | I messaggi scorrono linearmente, più come Slack | `top-level` |
|
||||
| Stile | Descrizione | `replyStyle` consigliato |
|
||||
| ------------------------ | -------------------------------------------------------- | ------------------------ |
|
||||
| **Posts** (classico) | I messaggi appaiono come card con risposte in thread sotto | `thread` (predefinito) |
|
||||
| **Threads** (simile a Slack) | I messaggi scorrono linearmente, più simili a Slack | `top-level` |
|
||||
|
||||
**Il problema:** l'API Teams non espone quale stile UI usa un canale. Se usi il `replyStyle` sbagliato:
|
||||
|
||||
- `thread` in un canale in stile Threads → le risposte appaiono annidate in modo scomodo
|
||||
- `top-level` in un canale in stile Posts → le risposte appaiono come post top-level separati invece che nel thread
|
||||
- `top-level` in un canale in stile Posts → le risposte appaiono come post separati di primo livello invece che nel thread
|
||||
|
||||
**Soluzione:** configura `replyStyle` per canale in base a come è configurato il canale:
|
||||
|
||||
@ -548,27 +701,27 @@ Teams ha recentemente introdotto due stili UI per i canali sullo stesso modello
|
||||
|
||||
**Limitazioni attuali:**
|
||||
|
||||
- **DM:** immagini e allegati file funzionano tramite le API file del bot Teams.
|
||||
- **Canali/gruppi:** gli allegati vivono nello storage M365 (SharePoint/OneDrive). Il payload webhook include solo uno stub HTML, non i byte effettivi del file. **Sono richieste autorizzazioni API Graph** per scaricare gli allegati dei canali.
|
||||
- Per invii espliciti file-first, usa `action=upload-file` con `media` / `filePath` / `path`; `message` opzionale diventa il testo/commento di accompagnamento, e `filename` sovrascrive il nome caricato.
|
||||
- **DM:** immagini e allegati di file funzionano tramite le API file del bot Teams.
|
||||
- **Canali/gruppi:** gli allegati risiedono nello storage M365 (SharePoint/OneDrive). Il payload del webhook include solo uno stub HTML, non i byte reali del file. **Le autorizzazioni API Graph sono richieste** per scaricare gli allegati del canale.
|
||||
- Per invii espliciti incentrati sul file, usa `action=upload-file` con `media` / `filePath` / `path`; `message` facoltativo diventa il testo/commento di accompagnamento e `filename` sostituisce il nome caricato.
|
||||
|
||||
Senza autorizzazioni Graph, i messaggi di canale con immagini verranno ricevuti solo come testo (il contenuto dell'immagine non è accessibile al bot).
|
||||
Per impostazione predefinita, OpenClaw scarica media solo da host Microsoft/Teams. Sovrascrivi con `channels.msteams.mediaAllowHosts` (usa `["*"]` per consentire qualsiasi host).
|
||||
Per impostazione predefinita, OpenClaw scarica media solo da hostname Microsoft/Teams. Puoi sovrascrivere con `channels.msteams.mediaAllowHosts` (usa `["*"]` per consentire qualsiasi host).
|
||||
Gli header Authorization vengono allegati solo per gli host in `channels.msteams.mediaAuthAllowHosts` (predefinito: host Graph + Bot Framework). Mantieni questo elenco rigoroso (evita suffissi multi-tenant).
|
||||
|
||||
## Invio di file nelle chat di gruppo
|
||||
|
||||
I bot possono inviare file nei DM usando il flusso FileConsentCard (integrato). Tuttavia, **l'invio di file nelle chat di gruppo/canali** richiede configurazione aggiuntiva:
|
||||
I bot possono inviare file nei DM usando il flusso FileConsentCard (integrato). Tuttavia, **l'invio di file nelle chat di gruppo/canali** richiede una configurazione aggiuntiva:
|
||||
|
||||
| Contesto | Come vengono inviati i file | Configurazione necessaria |
|
||||
| ------------------------ | ----------------------------------------- | ------------------------------------------------ |
|
||||
| **DM** | FileConsentCard → l'utente accetta → il bot carica | Funziona subito |
|
||||
| **Chat di gruppo/canali** | Caricamento su SharePoint → link di condivisione | Richiede `sharePointSiteId` + autorizzazioni Graph |
|
||||
| **Immagini (qualsiasi contesto)** | Inline con codifica Base64 | Funziona subito |
|
||||
| **Immagini (qualsiasi contesto)** | Inline con codifica Base64 | Funziona subito |
|
||||
|
||||
### Perché i gruppi richiedono SharePoint
|
||||
### Perché le chat di gruppo richiedono SharePoint
|
||||
|
||||
I bot non hanno un drive personale OneDrive (l'endpoint Graph API `/me/drive` non funziona per identità applicative). Per inviare file in chat di gruppo/canali, il bot carica su un **sito SharePoint** e crea un link di condivisione.
|
||||
I bot non hanno un drive OneDrive personale (l'endpoint API Graph `/me/drive` non funziona per le identità applicative). Per inviare file nelle chat di gruppo/canali, il bot carica su un **sito SharePoint** e crea un link di condivisione.
|
||||
|
||||
### Configurazione
|
||||
|
||||
@ -578,7 +731,7 @@ I bot non hanno un drive personale OneDrive (l'endpoint Graph API `/me/drive` no
|
||||
|
||||
2. **Concedi il consenso amministratore** per il tenant.
|
||||
|
||||
3. **Ottieni il tuo ID sito SharePoint:**
|
||||
3. **Ottieni l'ID del tuo sito SharePoint:**
|
||||
|
||||
```bash
|
||||
# Tramite Graph Explorer o curl con un token valido:
|
||||
@ -605,42 +758,42 @@ I bot non hanno un drive personale OneDrive (l'endpoint Graph API `/me/drive` no
|
||||
}
|
||||
```
|
||||
|
||||
### Comportamento di condivisione
|
||||
### Comportamento della condivisione
|
||||
|
||||
| Autorizzazione | Comportamento di condivisione |
|
||||
| ---------------------------------------- | --------------------------------------------------------- |
|
||||
| `Sites.ReadWrite.All` soltanto | Link di condivisione a livello organizzazione (chiunque nell'org può accedere) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Link di condivisione per utente (solo i membri della chat possono accedere) |
|
||||
| Autorizzazione | Comportamento della condivisione |
|
||||
| ----------------------------------------- | -------------------------------------------------------- |
|
||||
| `Sites.ReadWrite.All` soltanto | Link di condivisione a livello organizzazione (chiunque nell'organizzazione può accedere) |
|
||||
| `Sites.ReadWrite.All` + `Chat.Read.All` | Link di condivisione per utente (solo i membri della chat possono accedere) |
|
||||
|
||||
La condivisione per utente è più sicura perché solo i partecipanti alla chat possono accedere al file. Se manca l'autorizzazione `Chat.Read.All`, il bot usa come fallback la condivisione a livello organizzazione.
|
||||
La condivisione per utente è più sicura perché solo i partecipanti alla chat possono accedere al file. Se manca l'autorizzazione `Chat.Read.All`, il bot ripiega sulla condivisione a livello organizzazione.
|
||||
|
||||
### Comportamento di fallback
|
||||
|
||||
| Scenario | Risultato |
|
||||
| ------------------------------------------------- | -------------------------------------------------- |
|
||||
| Chat di gruppo + file + `sharePointSiteId` configurato | Caricamento su SharePoint, invio link di condivisione |
|
||||
| Chat di gruppo + file + nessun `sharePointSiteId` | Tentativo di caricamento su OneDrive (può fallire), invio solo testo |
|
||||
| Chat di gruppo + file + `sharePointSiteId` configurato | Carica su SharePoint, invia il link di condivisione |
|
||||
| Chat di gruppo + file + nessun `sharePointSiteId` | Tenta il caricamento su OneDrive (potrebbe fallire), invia solo testo |
|
||||
| Chat personale + file | Flusso FileConsentCard (funziona senza SharePoint) |
|
||||
| Qualsiasi contesto + immagine | Inline con codifica Base64 (funziona senza SharePoint) |
|
||||
|
||||
### Posizione dei file archiviati
|
||||
### Posizione di archiviazione dei file
|
||||
|
||||
I file caricati vengono archiviati in una cartella `/OpenClawShared/` nella raccolta documenti predefinita del sito SharePoint configurato.
|
||||
|
||||
## Sondaggi (Adaptive Cards)
|
||||
|
||||
OpenClaw invia i sondaggi Teams come Adaptive Cards (non esiste un'API nativa dei sondaggi Teams).
|
||||
OpenClaw invia i sondaggi di Teams come Adaptive Cards (non esiste un'API nativa per i sondaggi in Teams).
|
||||
|
||||
- CLI: `openclaw message poll --channel msteams --target conversation:<id> ...`
|
||||
- I voti vengono registrati dal gateway in `~/.openclaw/msteams-polls.json`.
|
||||
- Il gateway deve restare online per registrare i voti.
|
||||
- I sondaggi non pubblicano ancora automaticamente riepiloghi dei risultati (se necessario, ispeziona il file dello store).
|
||||
- I sondaggi non pubblicano ancora automaticamente i riepiloghi dei risultati (se necessario, ispeziona il file di archiviazione).
|
||||
|
||||
## Adaptive Cards (arbitrarie)
|
||||
|
||||
Invia qualsiasi JSON Adaptive Card a utenti o conversazioni Teams usando lo strumento `message` o la CLI.
|
||||
|
||||
Il parametro `card` accetta un oggetto JSON Adaptive Card. Quando `card` è fornito, il testo del messaggio è facoltativo.
|
||||
Il parametro `card` accetta un oggetto JSON Adaptive Card. Quando viene fornito `card`, il testo del messaggio è facoltativo.
|
||||
|
||||
**Strumento agente:**
|
||||
|
||||
@ -665,18 +818,18 @@ openclaw message send --channel msteams \
|
||||
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
|
||||
```
|
||||
|
||||
Vedi [la documentazione Adaptive Cards](https://adaptivecards.io/) per schema ed esempi delle card. Per i dettagli sul formato target, vedi [Formati target](#target-formats) sotto.
|
||||
Vedi la [documentazione di Adaptive Cards](https://adaptivecards.io/) per lo schema delle card e gli esempi. Per i dettagli sul formato del target, vedi [Formati target](#target-formats) sotto.
|
||||
|
||||
## Formati target
|
||||
|
||||
I target MSTeams usano prefissi per distinguere utenti e conversazioni:
|
||||
I target MSTeams usano prefissi per distinguere tra utenti e conversazioni:
|
||||
|
||||
| Tipo di target | Formato | Esempio |
|
||||
| --------------------- | ------------------------------- | --------------------------------------------------- |
|
||||
| Utente (per ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
|
||||
| Utente (per nome) | `user:<display-name>` | `user:John Smith` (richiede API Graph) |
|
||||
| Gruppo/canale | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Gruppo/canale (raw) | `<conversation-id>` | `19:abc123...@thread.tacv2` (se contiene `@thread`) |
|
||||
| Tipo di target | Formato | Esempio |
|
||||
| ---------------------- | ------------------------------- | --------------------------------------------------- |
|
||||
| Utente (per ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
|
||||
| Utente (per nome) | `user:<display-name>` | `user:John Smith` (richiede API Graph) |
|
||||
| Gruppo/canale | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
|
||||
| Gruppo/canale (raw) | `<conversation-id>` | `19:abc123...@thread.tacv2` (se contiene `@thread`) |
|
||||
|
||||
**Esempi CLI:**
|
||||
|
||||
@ -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"}]}'
|
||||
```
|
||||
|
||||
**Esempi strumento agente:**
|
||||
**Esempi dello strumento agente:**
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -719,23 +872,23 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread.
|
||||
}
|
||||
```
|
||||
|
||||
Nota: senza il prefisso `user:`, i nomi sono interpretati per impostazione predefinita come risoluzione gruppo/team. Usa sempre `user:` quando indirizzi persone per nome visualizzato.
|
||||
Nota: senza il prefisso `user:`, i nomi vengono interpretati per impostazione predefinita come risoluzione di gruppo/team. Usa sempre `user:` quando indirizzi persone per nome visualizzato.
|
||||
|
||||
## Messaggistica proattiva
|
||||
|
||||
- I messaggi proattivi sono possibili **solo dopo** che un utente ha interagito, perché a quel punto memorizziamo i riferimenti alla conversazione.
|
||||
- I messaggi proattivi sono possibili solo **dopo** che un utente ha interagito, perché a quel punto memorizziamo i riferimenti della conversazione.
|
||||
- Vedi `/gateway/configuration` per `dmPolicy` e il controllo tramite allowlist.
|
||||
|
||||
## ID team e canale (problema comune)
|
||||
## ID team e canale (errore comune)
|
||||
|
||||
Il parametro di query `groupId` negli URL Teams **NON** è l'ID team usato per la configurazione. Estrai invece gli ID dal percorso URL:
|
||||
Il parametro di query `groupId` negli URL di Teams **NON** è l'ID team usato per la configurazione. Estrai invece gli ID dal percorso dell'URL:
|
||||
|
||||
**URL team:**
|
||||
|
||||
```
|
||||
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
|
||||
└────────────────────────────┘
|
||||
ID team (decodifica questo URL)
|
||||
ID team (decodifica URL)
|
||||
```
|
||||
|
||||
**URL canale:**
|
||||
@ -743,12 +896,12 @@ https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?gro
|
||||
```
|
||||
https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
|
||||
└─────────────────────────┘
|
||||
ID canale (decodifica questo URL)
|
||||
ID canale (decodifica URL)
|
||||
```
|
||||
|
||||
**Per la configurazione:**
|
||||
|
||||
- ID team = segmento del percorso dopo `/team/` (decodificato URL, ad esempio `19:Bk4j...@thread.tacv2`)
|
||||
- ID team = segmento del percorso dopo `/team/` (decodificato URL, ad es. `19:Bk4j...@thread.tacv2`)
|
||||
- ID canale = segmento del percorso dopo `/channel/` (decodificato URL)
|
||||
- **Ignora** il parametro di query `groupId`
|
||||
|
||||
@ -756,17 +909,17 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr
|
||||
|
||||
I bot hanno supporto limitato nei canali privati:
|
||||
|
||||
| Funzionalità | Canali standard | Canali privati |
|
||||
| ---------------------------- | ------------------ | ---------------------- |
|
||||
| Installazione bot | Sì | Limitata |
|
||||
| Messaggi in tempo reale (webhook) | Sì | Potrebbe non funzionare |
|
||||
| Autorizzazioni RSC | Sì | Potrebbero comportarsi diversamente |
|
||||
| @mentions | Sì | Se il bot è accessibile |
|
||||
| Cronologia API Graph | Sì | Sì (con autorizzazioni) |
|
||||
| Funzionalità | Canali standard | Canali privati |
|
||||
| ---------------------------- | ----------------- | --------------------- |
|
||||
| Installazione del bot | Sì | Limitata |
|
||||
| Messaggi in tempo reale (webhook) | Sì | Potrebbe non funzionare |
|
||||
| Autorizzazioni RSC | Sì | Potrebbero comportarsi in modo diverso |
|
||||
| @mentions | Sì | Se il bot è accessibile |
|
||||
| Cronologia API Graph | Sì | Sì (con autorizzazioni) |
|
||||
|
||||
**Soluzioni alternative se i canali privati non funzionano:**
|
||||
|
||||
1. Usa canali standard per le interazioni col bot
|
||||
1. Usa canali standard per le interazioni con il bot
|
||||
2. Usa i DM - gli utenti possono sempre inviare messaggi direttamente al bot
|
||||
3. Usa l'API Graph per l'accesso storico (richiede `ChannelMessage.Read.All`)
|
||||
|
||||
@ -775,38 +928,38 @@ I bot hanno supporto limitato nei canali privati:
|
||||
### Problemi comuni
|
||||
|
||||
- **Le immagini non vengono mostrate nei canali:** mancano autorizzazioni Graph o consenso amministratore. Reinstalla l'app Teams e chiudi/riapri completamente Teams.
|
||||
- **Nessuna risposta nel canale:** le menzioni sono richieste per impostazione predefinita; imposta `channels.msteams.requireMention=false` oppure configura per team/canale.
|
||||
- **Version mismatch (Teams mostra ancora il vecchio manifest):** rimuovi e aggiungi di nuovo l'app, quindi chiudi completamente Teams per aggiornare.
|
||||
- **401 Unauthorized dal webhook:** previsto quando si testa manualmente senza JWT Azure - significa che l'endpoint è raggiungibile ma l'autenticazione è fallita. Usa Azure Web Chat per testare correttamente.
|
||||
- **Nessuna risposta nel canale:** per impostazione predefinita le menzioni sono richieste; imposta `channels.msteams.requireMention=false` o configura per team/canale.
|
||||
- **Versione non corrispondente (Teams mostra ancora il vecchio manifest):** rimuovi e aggiungi di nuovo l'app e chiudi completamente Teams per aggiornare.
|
||||
- **401 Unauthorized dal webhook:** previsto quando fai test manuali senza JWT Azure - significa che l'endpoint è raggiungibile ma l'autenticazione non è riuscita. Usa Azure Web Chat per testare correttamente.
|
||||
|
||||
### Errori di caricamento del manifest
|
||||
### Errori nel caricamento del manifest
|
||||
|
||||
- **"Icon file cannot be empty":** il manifest fa riferimento a file icona da 0 byte. Crea icone PNG valide (32x32 per `outline.png`, 192x192 per `color.png`).
|
||||
- **"Icon file cannot be empty":** il manifest fa riferimento a file icona di 0 byte. Crea icone PNG valide (32x32 per `outline.png`, 192x192 per `color.png`).
|
||||
- **"webApplicationInfo.Id already in use":** l'app è ancora installata in un altro team/chat. Trovala e disinstallala prima, oppure attendi 5-10 minuti per la propagazione.
|
||||
- **"Something went wrong" durante il caricamento:** carica invece tramite [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), apri DevTools del browser (F12) → scheda Network, e controlla il corpo della risposta per l'errore effettivo.
|
||||
- **Sideload non riuscito:** prova "Upload an app to your org's app catalog" invece di "Upload a custom app" - spesso aggira le restrizioni sul sideload.
|
||||
- **"Something went wrong" durante il caricamento:** carica invece tramite [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), apri i DevTools del browser (F12) → scheda Network, e controlla il corpo della risposta per l'errore effettivo.
|
||||
- **Sideload non riuscito:** prova "Upload an app to your org's app catalog" invece di "Upload a custom app" - spesso questo aggira le restrizioni del sideload.
|
||||
|
||||
### Le autorizzazioni RSC non funzionano
|
||||
|
||||
1. Verifica che `webApplicationInfo.id` corrisponda esattamente all'App ID del tuo bot
|
||||
2. Ricarica l'app e reinstallala nel team/chat
|
||||
3. Controlla se l'amministratore dell'organizzazione ha bloccato le autorizzazioni RSC
|
||||
3. Controlla se l'amministratore della tua organizzazione ha bloccato le autorizzazioni RSC
|
||||
4. Conferma di usare l'ambito corretto: `ChannelMessage.Read.Group` per i team, `ChatMessage.Read.Chat` per le chat di gruppo
|
||||
|
||||
## Riferimenti
|
||||
|
||||
- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - guida alla configurazione Azure Bot
|
||||
- [Crea Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - guida alla configurazione di Azure Bot
|
||||
- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - crea/gestisci app Teams
|
||||
- [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) (canale/gruppo richiede Graph)
|
||||
- [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
|
||||
- [Schema manifest app Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
|
||||
- [Ricevere messaggi di canale con RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
|
||||
- [Riferimento autorizzazioni RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
|
||||
- [Gestione file del bot Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (canale/gruppo richiede Graph)
|
||||
- [Messaggistica proattiva](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Panoramica canali](/it/channels) — tutti i canali supportati
|
||||
- [Pairing](/it/channels/pairing) — autenticazione DM e flusso di pairing
|
||||
- [Gruppi](/it/channels/groups) — comportamento della chat di gruppo e gate basato su menzione
|
||||
- [Routing del canale](/it/channels/channel-routing) — routing della sessione per i messaggi
|
||||
- [Sicurezza](/gateway/security) — modello di accesso e hardening
|
||||
- [Gruppi](/it/channels/groups) — comportamento della chat di gruppo e vincolo di menzione
|
||||
- [Routing canale](/it/channels/channel-routing) — routing della sessione per i messaggi
|
||||
- [Sicurezza](/it/gateway/security) — modello di accesso e hardening
|
||||
|
||||
@ -1,58 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- Stai modificando il runtime incorporato dell'agente o il registro harness
|
||||
- Stai registrando un agent harness da un plugin bundled o trusted
|
||||
- Stai modificando il runtime dell'agente incorporato o il registro dell'harness
|
||||
- Stai registrando un harness dell'agente da un plugin incluso o attendibile
|
||||
- Devi capire come il plugin Codex si relaziona ai provider di modelli
|
||||
sidebarTitle: Agent Harness
|
||||
summary: Superficie SDK sperimentale per plugin che sostituiscono l'esecutore incorporato dell'agente di basso livello
|
||||
title: Plugin Agent Harness
|
||||
summary: Superficie SDK sperimentale per i plugin che sostituiscono l'esecutore dell'agente incorporato di basso livello
|
||||
title: Plugin Harness dell'agente
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:46:05Z"
|
||||
generated_at: "2026-04-12T00:19:02Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 43c1f2c087230398b0162ed98449f239c8db1e822e51c7dcd40c54fa6c3374e1
|
||||
source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Plugin Agent Harness
|
||||
# Plugin Harness dell'agente
|
||||
|
||||
Un **agent harness** è l'esecutore di basso livello per un singolo turno di agente
|
||||
OpenClaw già preparato. Non è un provider di modelli, non è un canale e non è un registro degli strumenti.
|
||||
Un **agent harness** è l'esecutore di basso livello per un turno preparato di un agente OpenClaw. Non è un provider di modelli, non è un canale e non è un registro di strumenti.
|
||||
|
||||
Usa questa superficie solo per plugin nativi bundled o trusted. Il contratto è
|
||||
ancora sperimentale perché i tipi dei parametri rispecchiano intenzionalmente l'attuale
|
||||
runner incorporato.
|
||||
Usa questa superficie solo per plugin nativi inclusi o attendibili. Il contratto è ancora sperimentale perché i tipi dei parametri rispecchiano intenzionalmente l'attuale runner incorporato.
|
||||
|
||||
## Quando usare un harness
|
||||
|
||||
Registra un agent harness quando una famiglia di modelli ha il proprio runtime
|
||||
di sessione nativo e il normale trasporto provider di OpenClaw è l'astrazione sbagliata.
|
||||
Registra un agent harness quando una famiglia di modelli ha un proprio runtime di sessione nativo e il normale trasporto provider di OpenClaw è l'astrazione sbagliata.
|
||||
|
||||
Esempi:
|
||||
|
||||
- un server di agente di coding nativo che gestisce thread e compattazione
|
||||
- una CLI o un daemon locale che deve trasmettere eventi nativi di piano/ragionamento/strumenti
|
||||
- un runtime di modello che necessita del proprio resume id oltre alla
|
||||
trascrizione di sessione OpenClaw
|
||||
- un server nativo per agenti di coding che gestisce thread e compattazione
|
||||
- una CLI o un demone locale che deve trasmettere eventi nativi di piano/ragionamento/strumenti
|
||||
- un runtime di modelli che ha bisogno di un proprio ID di ripresa oltre alla trascrizione di sessione OpenClaw
|
||||
|
||||
**Non** registrare un harness solo per aggiungere una nuova API LLM. Per normali API di modelli HTTP o
|
||||
WebSocket, crea un [plugin provider](/it/plugins/sdk-provider-plugins).
|
||||
**Non** registrare un harness solo per aggiungere una nuova API LLM. Per normali API di modelli HTTP o WebSocket, crea un [plugin provider](/it/plugins/sdk-provider-plugins).
|
||||
|
||||
## Cosa continua a essere gestito dal core
|
||||
## Cosa rimane di competenza del core
|
||||
|
||||
Prima che venga selezionato un harness, OpenClaw ha già risolto:
|
||||
|
||||
- provider e modello
|
||||
- stato auth del runtime
|
||||
- livello di ragionamento e budget di contesto
|
||||
- la trascrizione/sessione OpenClaw
|
||||
- policy di workspace, sandbox e strumenti
|
||||
- stato di autenticazione del runtime
|
||||
- livello di reasoning e budget di contesto
|
||||
- la trascrizione OpenClaw / il file di sessione
|
||||
- workspace, sandbox e policy degli strumenti
|
||||
- callback di risposta del canale e callback di streaming
|
||||
- policy di fallback del modello e di cambio modello live
|
||||
- fallback del modello e policy di cambio del modello live
|
||||
|
||||
Questa separazione è intenzionale. Un harness esegue un tentativo preparato; non sceglie
|
||||
provider, non sostituisce la consegna del canale e non cambia silenziosamente modello.
|
||||
Questa separazione è intenzionale. Un harness esegue un tentativo preparato; non sceglie i provider, non sostituisce la consegna del canale e non cambia silenziosamente modello.
|
||||
|
||||
## Registrare un harness
|
||||
|
||||
@ -90,66 +83,51 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
## Policy di selezione
|
||||
## Criterio di selezione
|
||||
|
||||
OpenClaw sceglie un harness dopo la risoluzione di provider/modello:
|
||||
|
||||
1. `OPENCLAW_AGENT_RUNTIME=<id>` forza un harness registrato con quell'id.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=pi` forza l'harness PI integrato.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` chiede agli harness registrati se supportano il
|
||||
provider/modello risolto.
|
||||
4. Se nessun harness registrato corrisponde, OpenClaw usa PI a meno che il fallback a PI non sia
|
||||
disabilitato.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=auto` chiede agli harness registrati se supportano il provider/modello risolto.
|
||||
4. Se nessun harness registrato corrisponde, OpenClaw usa PI a meno che il fallback a PI non sia disabilitato.
|
||||
|
||||
Gli errori di un harness plugin forzato emergono come errori di esecuzione. In modalità `auto`,
|
||||
OpenClaw può tornare a PI quando l'harness plugin selezionato fallisce prima che un
|
||||
turno abbia prodotto effetti collaterali. Imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` oppure
|
||||
`embeddedHarness.fallback: "none"` per rendere invece quel fallback un errore definitivo.
|
||||
Gli errori forzati dell'harness del plugin emergono come errori di esecuzione. In modalità `auto`, OpenClaw può ricadere su PI quando l'harness del plugin selezionato fallisce prima che un turno produca effetti collaterali. Imposta `OPENCLAW_AGENT_HARNESS_FALLBACK=none` o `embeddedHarness.fallback: "none"` per rendere invece quel fallback un errore irreversibile.
|
||||
|
||||
Il plugin Codex bundled registra `codex` come id del proprio harness. Il core tratta questo
|
||||
come un normale id di harness plugin; gli alias specifici di Codex appartengono al plugin
|
||||
o alla configurazione dell'operatore, non al selettore runtime condiviso.
|
||||
Il plugin Codex incluso registra `codex` come ID del proprio harness. Il core lo tratta come un normale ID di harness del plugin; gli alias specifici di Codex appartengono al plugin o alla configurazione dell'operatore, non al selettore di runtime condiviso.
|
||||
|
||||
## Associazione provider più harness
|
||||
|
||||
La maggior parte degli harness dovrebbe registrare anche un provider. Il provider rende i riferimenti ai modelli,
|
||||
lo stato auth, i metadati del modello e la selezione `/model` visibili al resto di
|
||||
OpenClaw. L'harness poi rivendica quel provider in `supports(...)`.
|
||||
La maggior parte degli harness dovrebbe anche registrare un provider. Il provider rende visibili al resto di OpenClaw i riferimenti ai modelli, lo stato di autenticazione, i metadati del modello e la selezione `/model`. L'harness poi rivendica quel provider in `supports(...)`.
|
||||
|
||||
Il plugin Codex bundled segue questo schema:
|
||||
Il plugin Codex incluso segue questo schema:
|
||||
|
||||
- id provider: `codex`
|
||||
- riferimenti modello utente: `codex/gpt-5.4`, `codex/gpt-5.2` o un altro modello restituito
|
||||
dal server app Codex
|
||||
- riferimenti ai modelli per l'utente: `codex/gpt-5.4`, `codex/gpt-5.2` o un altro modello restituito dal server app Codex
|
||||
- id harness: `codex`
|
||||
- auth: disponibilità sintetica del provider, perché l'harness Codex gestisce il
|
||||
login/sessione Codex nativo
|
||||
- richiesta al server app: OpenClaw invia l'id modello nudo a Codex e lascia che
|
||||
l'harness parli con il protocollo nativo del server app
|
||||
- autenticazione: disponibilità sintetica del provider, perché l'harness Codex gestisce il login/sessione Codex nativo
|
||||
- richiesta al server app: OpenClaw invia l'ID del modello senza prefissi a Codex e lascia che l'harness comunichi con il protocollo nativo del server app
|
||||
|
||||
Il plugin Codex è additivo. I semplici riferimenti `openai/gpt-*` restano riferimenti del provider OpenAI
|
||||
e continuano a usare il normale percorso provider di OpenClaw. Seleziona `codex/gpt-*`
|
||||
quando vuoi auth gestita da Codex, rilevamento modelli Codex, thread nativi e
|
||||
esecuzione del server app Codex. `/model` può passare tra i modelli Codex restituiti
|
||||
dal server app Codex senza richiedere credenziali del provider OpenAI.
|
||||
Il plugin Codex è aggiuntivo. I riferimenti semplici `openai/gpt-*` restano riferimenti del provider OpenAI e continuano a usare il normale percorso provider di OpenClaw. Seleziona `codex/gpt-*` quando vuoi autenticazione gestita da Codex, rilevamento dei modelli Codex, thread nativi ed esecuzione del server app Codex. `/model` può passare tra i modelli Codex restituiti dal server app Codex senza richiedere credenziali del provider OpenAI.
|
||||
|
||||
Per la configurazione dell'operatore, esempi di prefisso modello e configurazioni solo Codex, vedi
|
||||
[Codex Harness](/it/plugins/codex-harness).
|
||||
Per la configurazione dell'operatore, esempi di prefissi di modello e configurazioni solo Codex, vedi [Codex Harness](/it/plugins/codex-harness).
|
||||
|
||||
OpenClaw richiede Codex app-server `0.118.0` o successivo. Il plugin Codex controlla
|
||||
l'handshake di inizializzazione del server app e blocca server più vecchi o senza versione, così
|
||||
OpenClaw viene eseguito solo contro la superficie di protocollo su cui è stato testato.
|
||||
OpenClaw richiede Codex app-server `0.118.0` o successivo. Il plugin Codex controlla l'handshake di inizializzazione dell'app-server e blocca i server più vecchi o senza versione, così OpenClaw viene eseguito solo sulla superficie di protocollo con cui è stato testato.
|
||||
|
||||
### Modalità harness Codex nativa
|
||||
|
||||
L'harness `codex` incluso è la modalità Codex nativa per i turni degli agenti OpenClaw incorporati. Abilita prima il plugin `codex` incluso e includi `codex` in `plugins.allow` se la tua configurazione usa una allowlist restrittiva. È diverso da `openai-codex/*`:
|
||||
|
||||
- `openai-codex/*` usa OAuth ChatGPT/Codex tramite il normale percorso provider di OpenClaw.
|
||||
- `codex/*` usa il provider Codex incluso e instrada il turno tramite il server app Codex.
|
||||
|
||||
Quando questa modalità è in esecuzione, Codex gestisce l'ID del thread nativo, il comportamento di ripresa, la compattazione e l'esecuzione dell'app-server. OpenClaw continua comunque a gestire il canale di chat, il mirror della trascrizione visibile, la policy degli strumenti, le approvazioni, la consegna dei contenuti multimediali e la selezione della sessione. Usa `embeddedHarness.runtime: "codex"` con `embeddedHarness.fallback: "none"` quando devi dimostrare che viene usato il percorso del server app Codex e che il fallback a PI non sta nascondendo un harness nativo non funzionante.
|
||||
|
||||
## Disabilitare il fallback a PI
|
||||
|
||||
Per impostazione predefinita, OpenClaw esegue agenti incorporati con `agents.defaults.embeddedHarness`
|
||||
impostato su `{ runtime: "auto", fallback: "pi" }`. In modalità `auto`, gli harness plugin registrati
|
||||
possono rivendicare una coppia provider/modello. Se nessuno corrisponde, oppure se un harness plugin
|
||||
selezionato automaticamente fallisce prima di produrre output, OpenClaw torna a PI.
|
||||
Per impostazione predefinita, OpenClaw esegue gli agenti incorporati con `agents.defaults.embeddedHarness` impostato su `{ runtime: "auto", fallback: "pi" }`. In modalità `auto`, gli harness dei plugin registrati possono rivendicare una coppia provider/modello. Se nessuno corrisponde, oppure se un harness del plugin selezionato automaticamente fallisce prima di produrre output, OpenClaw ricade su PI.
|
||||
|
||||
Imposta `fallback: "none"` quando devi dimostrare che un harness plugin è l'unico
|
||||
runtime effettivamente usato. Questo disabilita il fallback automatico a PI; non blocca
|
||||
un `runtime: "pi"` esplicito o `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
Imposta `fallback: "none"` quando devi dimostrare che un harness del plugin è l'unico runtime realmente utilizzato. Questo disabilita il fallback automatico a PI; non blocca un `runtime: "pi"` esplicito o `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
Per esecuzioni incorporate solo Codex:
|
||||
|
||||
@ -167,9 +145,7 @@ Per esecuzioni incorporate solo Codex:
|
||||
}
|
||||
```
|
||||
|
||||
Se vuoi che qualsiasi harness plugin registrato rivendichi i modelli corrispondenti ma non
|
||||
vuoi mai che OpenClaw torni silenziosamente a PI, mantieni `runtime: "auto"` e disabilita
|
||||
il fallback:
|
||||
Se vuoi che qualunque harness del plugin registrato possa rivendicare i modelli corrispondenti ma non vuoi mai che OpenClaw ricada silenziosamente su PI, mantieni `runtime: "auto"` e disabilita il fallback:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -184,7 +160,7 @@ il fallback:
|
||||
}
|
||||
```
|
||||
|
||||
Gli override per agente usano la stessa struttura:
|
||||
Le override per agente usano la stessa struttura:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -209,9 +185,7 @@ Gli override per agente usano la stessa struttura:
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` continua a sovrascrivere il runtime configurato. Usa
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none` per disabilitare il fallback a PI
|
||||
dall'ambiente.
|
||||
`OPENCLAW_AGENT_RUNTIME` continua a sovrascrivere il runtime configurato. Usa `OPENCLAW_AGENT_HARNESS_FALLBACK=none` per disabilitare il fallback a PI dall'ambiente.
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -219,47 +193,34 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Con il fallback disabilitato, una sessione fallisce subito quando l'harness richiesto non è
|
||||
registrato, non supporta il provider/modello risolto o fallisce prima di
|
||||
produrre effetti collaterali del turno. Questo è intenzionale per distribuzioni solo Codex e
|
||||
per test live che devono dimostrare che il percorso del server app Codex è realmente in uso.
|
||||
Con il fallback disabilitato, una sessione fallisce subito quando l'harness richiesto non è registrato, non supporta il provider/modello risolto o fallisce prima di produrre effetti collaterali del turno. Questo è intenzionale per i deployment solo Codex e per i test live che devono dimostrare che il percorso del server app Codex è effettivamente in uso.
|
||||
|
||||
Questa impostazione controlla solo l'agent harness incorporato. Non disabilita
|
||||
l'instradamento specifico del provider per immagini, video, musica, TTS, PDF o altri modelli.
|
||||
Questa impostazione controlla solo l'harness dell'agente incorporato. Non disabilita l'instradamento specifico del provider per immagini, video, musica, TTS, PDF o altri modelli.
|
||||
|
||||
## Sessioni native e mirror della trascrizione
|
||||
|
||||
Un harness può mantenere un id di sessione nativo, id thread o token di ripresa lato daemon.
|
||||
Mantieni questa associazione esplicitamente collegata alla sessione OpenClaw e continua a
|
||||
rispecchiare nella trascrizione OpenClaw l'output di assistente/strumenti visibile all'utente.
|
||||
Un harness può mantenere un ID di sessione nativo, un ID di thread o un token di ripresa lato demone. Mantieni tale associazione esplicitamente legata alla sessione OpenClaw e continua a riflettere l'output visibile all'utente di assistente/strumenti nella trascrizione OpenClaw.
|
||||
|
||||
La trascrizione OpenClaw resta il livello di compatibilità per:
|
||||
La trascrizione OpenClaw rimane il livello di compatibilità per:
|
||||
|
||||
- cronologia della sessione visibile nel canale
|
||||
- ricerca e indicizzazione della trascrizione
|
||||
- ritorno all'harness PI integrato in un turno successivo
|
||||
- comportamento generico di `/new`, `/reset` ed eliminazione della sessione
|
||||
|
||||
Se il tuo harness memorizza un'associazione sidecar, implementa `reset(...)` in modo che OpenClaw possa
|
||||
cancellarla quando la sessione OpenClaw proprietaria viene reimpostata.
|
||||
Se il tuo harness memorizza un'associazione sidecar, implementa `reset(...)` così OpenClaw può cancellarla quando la sessione OpenClaw proprietaria viene reimpostata.
|
||||
|
||||
## Risultati di strumenti e media
|
||||
## Risultati di strumenti e contenuti multimediali
|
||||
|
||||
Il core costruisce l'elenco degli strumenti OpenClaw e lo passa al tentativo preparato.
|
||||
Quando un harness esegue una chiamata dinamica a uno strumento, restituisci il risultato dello strumento tramite
|
||||
la forma di risultato dell'harness invece di inviare tu stesso i media al canale.
|
||||
Il core costruisce l'elenco degli strumenti OpenClaw e lo passa nel tentativo preparato. Quando un harness esegue una chiamata a strumento dinamica, restituisci il risultato dello strumento tramite la forma del risultato dell'harness invece di inviare tu stesso i contenuti multimediali al canale.
|
||||
|
||||
Questo mantiene testo, immagine, video, musica, TTS, approvazione e output degli
|
||||
strumenti di messaggistica sullo stesso percorso di consegna delle esecuzioni supportate da PI.
|
||||
Questo mantiene output di testo, immagine, video, musica, TTS, approvazione e strumenti di messaggistica sullo stesso percorso di consegna delle esecuzioni supportate da PI.
|
||||
|
||||
## Limitazioni attuali
|
||||
|
||||
- Il percorso di import pubblico è generico, ma alcuni alias di tipo per tentativo/risultato
|
||||
portano ancora nomi `Pi` per compatibilità.
|
||||
- L'installazione di harness di terze parti è sperimentale. Preferisci i plugin provider
|
||||
finché non ti serve un runtime di sessione nativo.
|
||||
- Il cambio di harness è supportato tra i turni. Non cambiare harness nel
|
||||
mezzo di un turno dopo che strumenti nativi, approvazioni, testo dell'assistente o invii di messaggi sono iniziati.
|
||||
- Il percorso di import pubblico è generico, ma alcuni alias di tipo attempt/result riportano ancora nomi `Pi` per compatibilità.
|
||||
- L'installazione di harness di terze parti è sperimentale. Preferisci i plugin provider finché non ti serve un runtime di sessione nativo.
|
||||
- Il cambio di harness è supportato tra i turni. Non cambiare harness nel mezzo di un turno dopo che sono iniziati strumenti nativi, approvazioni, testo dell'assistente o invii di messaggi.
|
||||
|
||||
## Correlati
|
||||
|
||||
|
||||
@ -1,31 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi usare i modelli OpenAI in OpenClaw
|
||||
- Vuoi usare l'autenticazione con abbonamento Codex invece delle chiavi API
|
||||
- Vuoi l'autenticazione con abbonamento Codex invece delle chiavi API
|
||||
- Hai bisogno di un comportamento di esecuzione degli agenti GPT-5 più rigoroso
|
||||
summary: Usa OpenAI tramite chiavi API o abbonamento Codex in OpenClaw
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T08:17:29Z"
|
||||
generated_at: "2026-04-12T00:18:54Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a2ce1ce5f085fe55ec50b8d20359180b9002c9730820cd5b0e011c3bf807b64
|
||||
source_hash: 7aa06fba9ac901e663685a6b26443a2f6aeb6ec3589d939522dc87cbb43497b4
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenAI
|
||||
|
||||
OpenAI fornisce API per sviluppatori per i modelli GPT. Codex supporta l'**accesso con ChatGPT** per l'accesso in abbonamento
|
||||
OpenAI fornisce API per sviluppatori per i modelli GPT. Codex supporta l'**accesso con ChatGPT** per l'accesso tramite abbonamento
|
||||
oppure l'accesso con **chiave API** per l'accesso basato sul consumo. Codex cloud richiede l'accesso con ChatGPT.
|
||||
OpenAI supporta esplicitamente l'uso di OAuth dell'abbonamento in strumenti/workflow esterni come OpenClaw.
|
||||
OpenAI supporta esplicitamente l'uso dell'OAuth dell'abbonamento in strumenti/workflow esterni come OpenClaw.
|
||||
|
||||
## Stile di interazione predefinito
|
||||
|
||||
OpenClaw può aggiungere una piccola sovrapposizione di prompt specifica per OpenAI sia per le esecuzioni `openai/*` sia per quelle
|
||||
`openai-codex/*`. Per impostazione predefinita, la sovrapposizione mantiene l'assistente disponibile,
|
||||
OpenClaw può aggiungere un piccolo overlay di prompt specifico per OpenAI sia per le esecuzioni `openai/*` sia per
|
||||
quelle `openai-codex/*`. Per impostazione predefinita, l'overlay mantiene l'assistente cordiale,
|
||||
collaborativo, conciso, diretto e un po' più espressivo dal punto di vista emotivo
|
||||
senza sostituire il prompt di sistema base di OpenClaw. La sovrapposizione amichevole
|
||||
consente anche l'uso occasionale di emoji quando si adattano in modo naturale, mantenendo comunque
|
||||
senza sostituire il prompt di sistema base di OpenClaw. L'overlay cordiale
|
||||
consente anche l'emoji occasionale quando si adatta in modo naturale, mantenendo comunque
|
||||
l'output complessivamente conciso.
|
||||
|
||||
Chiave di configurazione:
|
||||
@ -34,15 +35,15 @@ Chiave di configurazione:
|
||||
|
||||
Valori consentiti:
|
||||
|
||||
- `"friendly"`: predefinito; abilita la sovrapposizione specifica per OpenAI.
|
||||
- `"friendly"`: predefinito; abilita l'overlay specifico per OpenAI.
|
||||
- `"on"`: alias di `"friendly"`.
|
||||
- `"off"`: disabilita la sovrapposizione e usa solo il prompt base di OpenClaw.
|
||||
- `"off"`: disabilita l'overlay e usa solo il prompt base di OpenClaw.
|
||||
|
||||
Ambito:
|
||||
|
||||
- Si applica ai modelli `openai/*`.
|
||||
- Si applica ai modelli `openai-codex/*`.
|
||||
- Non influisce sugli altri provider.
|
||||
- Non influisce su altri provider.
|
||||
|
||||
Questo comportamento è attivo per impostazione predefinita. Mantieni `"friendly"` esplicitamente se vuoi che
|
||||
sopravviva a future modifiche locali della configurazione:
|
||||
@ -61,9 +62,9 @@ sopravviva a future modifiche locali della configurazione:
|
||||
}
|
||||
```
|
||||
|
||||
### Disabilitare la sovrapposizione di prompt OpenAI
|
||||
### Disabilitare l'overlay di prompt OpenAI
|
||||
|
||||
Se vuoi il prompt base di OpenClaw non modificato, imposta la sovrapposizione su `"off"`:
|
||||
Se vuoi il prompt base non modificato di OpenClaw, imposta l'overlay su `"off"`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -85,19 +86,19 @@ Puoi anche impostarlo direttamente con la CLI di configurazione:
|
||||
openclaw config set plugins.entries.openai.config.personality off
|
||||
```
|
||||
|
||||
OpenClaw normalizza questa impostazione senza distinzione tra maiuscole e minuscole a runtime, quindi valori come
|
||||
`"Off"` disabilitano comunque la sovrapposizione amichevole.
|
||||
OpenClaw normalizza questa impostazione in modo non sensibile alle maiuscole/minuscole in fase di esecuzione, quindi valori come
|
||||
`"Off"` disabilitano comunque l'overlay cordiale.
|
||||
|
||||
## Opzione A: chiave API OpenAI (OpenAI Platform)
|
||||
|
||||
**Ideale per:** accesso diretto alle API e fatturazione basata sull'utilizzo.
|
||||
Ottieni la tua chiave API dalla dashboard OpenAI.
|
||||
**Ideale per:** accesso API diretto e fatturazione basata sul consumo.
|
||||
Ottieni la tua chiave API dalla dashboard di OpenAI.
|
||||
|
||||
Riepilogo del routing:
|
||||
Riepilogo dei percorsi:
|
||||
|
||||
- `openai/gpt-5.4` = route API diretta di OpenAI Platform
|
||||
- Richiede `OPENAI_API_KEY` (o configurazione equivalente del provider OpenAI)
|
||||
- In OpenClaw, l'accesso ChatGPT/Codex viene instradato tramite `openai-codex/*`, non `openai/*`
|
||||
- `openai/gpt-5.4` = percorso API diretto di OpenAI Platform
|
||||
- Richiede `OPENAI_API_KEY` (o una configurazione equivalente del provider OpenAI)
|
||||
- In OpenClaw, l'accesso ChatGPT/Codex passa tramite `openai-codex/*`, non `openai/*`
|
||||
|
||||
### Configurazione CLI
|
||||
|
||||
@ -107,7 +108,7 @@ openclaw onboard --auth-choice openai-api-key
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
|
||||
### Esempio di configurazione
|
||||
### Frammento di configurazione
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -117,27 +118,27 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
|
||||
La documentazione attuale dei modelli API di OpenAI elenca `gpt-5.4` e `gpt-5.4-pro` per l'uso diretto
|
||||
delle API OpenAI. OpenClaw inoltra entrambi tramite il percorso `openai/*` Responses.
|
||||
tramite API OpenAI. OpenClaw inoltra entrambi attraverso il percorso Responses `openai/*`.
|
||||
OpenClaw sopprime intenzionalmente la riga obsoleta `openai/gpt-5.3-codex-spark`,
|
||||
perché le chiamate API dirette a OpenAI la rifiutano nel traffico live.
|
||||
perché le chiamate API dirette a OpenAI la rifiutano nel traffico reale.
|
||||
|
||||
OpenClaw **non** espone `openai/gpt-5.3-codex-spark` sul percorso API diretto di OpenAI.
|
||||
`pi-ai` include ancora una riga integrata per quel modello, ma le richieste API OpenAI live
|
||||
la rifiutano attualmente. In OpenClaw Spark è trattato come solo Codex.
|
||||
OpenClaw **non** espone `openai/gpt-5.3-codex-spark` nel percorso API diretto di OpenAI.
|
||||
`pi-ai` include ancora una riga integrata per quel modello, ma le richieste API OpenAI reali
|
||||
attualmente la rifiutano. In OpenClaw, Spark è trattato solo come Codex.
|
||||
|
||||
## Generazione di immagini
|
||||
|
||||
Il plugin `openai` incluso registra anche la generazione di immagini tramite lo
|
||||
strumento condiviso `image_generate`.
|
||||
Il plugin `openai` incluso registra anche la generazione di immagini tramite lo strumento condiviso
|
||||
`image_generate`.
|
||||
|
||||
- Modello immagine predefinito: `openai/gpt-image-1`
|
||||
- Modello di immagini predefinito: `openai/gpt-image-1`
|
||||
- Generazione: fino a 4 immagini per richiesta
|
||||
- Modalità modifica: abilitata, fino a 5 immagini di riferimento
|
||||
- Supporta `size`
|
||||
- Limitazione attuale specifica di OpenAI: OpenClaw oggi non inoltra le sostituzioni `aspectRatio` o
|
||||
`resolution` alla OpenAI Images API
|
||||
- Avvertenza specifica attuale di OpenAI: oggi OpenClaw non inoltra gli override `aspectRatio` o
|
||||
`resolution` all'API OpenAI Images
|
||||
|
||||
Per usare OpenAI come provider immagine predefinito:
|
||||
Per usare OpenAI come provider di immagini predefinito:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -151,21 +152,21 @@ Per usare OpenAI come provider immagine predefinito:
|
||||
}
|
||||
```
|
||||
|
||||
Vedi [Generazione di immagini](/it/tools/image-generation) per i parametri condivisi
|
||||
dello strumento, la selezione del provider e il comportamento di failover.
|
||||
Vedi [Generazione di immagini](/it/tools/image-generation) per i parametri dello strumento condiviso,
|
||||
la selezione del provider e il comportamento di failover.
|
||||
|
||||
## Generazione video
|
||||
## Generazione di video
|
||||
|
||||
Il plugin `openai` incluso registra anche la generazione video tramite lo strumento condiviso
|
||||
Il plugin `openai` incluso registra anche la generazione di video tramite lo strumento condiviso
|
||||
`video_generate`.
|
||||
|
||||
- Modello video predefinito: `openai/sora-2`
|
||||
- Modalità: text-to-video, image-to-video e flussi di riferimento/modifica a video singolo
|
||||
- Modalità: text-to-video, image-to-video e flussi di riferimento/modifica con singolo video
|
||||
- Limiti attuali: 1 immagine o 1 input video di riferimento
|
||||
- Limitazione attuale specifica di OpenAI: OpenClaw attualmente inoltra solo le sostituzioni `size`
|
||||
per la generazione video nativa di OpenAI. Le sostituzioni opzionali non supportate
|
||||
come `aspectRatio`, `resolution`, `audio` e `watermark` vengono ignorate
|
||||
e restituite come avviso dello strumento.
|
||||
- Avvertenza specifica attuale di OpenAI: OpenClaw attualmente inoltra solo gli override `size`
|
||||
per la generazione video nativa di OpenAI. Gli override opzionali non supportati
|
||||
come `aspectRatio`, `resolution`, `audio` e `watermark` vengono ignorati
|
||||
e riportati come avviso dello strumento.
|
||||
|
||||
Per usare OpenAI come provider video predefinito:
|
||||
|
||||
@ -181,31 +182,31 @@ Per usare OpenAI come provider video predefinito:
|
||||
}
|
||||
```
|
||||
|
||||
Vedi [Generazione video](/it/tools/video-generation) per i parametri condivisi
|
||||
dello strumento, la selezione del provider e il comportamento di failover.
|
||||
Vedi [Generazione di video](/it/tools/video-generation) per i parametri dello strumento condiviso,
|
||||
la selezione del provider e il comportamento di failover.
|
||||
|
||||
## Opzione B: abbonamento OpenAI Code (Codex)
|
||||
|
||||
**Ideale per:** usare l'accesso in abbonamento ChatGPT/Codex invece di una chiave API.
|
||||
Codex cloud richiede l'accesso con ChatGPT, mentre la CLI Codex supporta l'accesso con ChatGPT o con chiave API.
|
||||
**Ideale per:** usare l'accesso tramite abbonamento ChatGPT/Codex invece di una chiave API.
|
||||
Codex cloud richiede l'accesso con ChatGPT, mentre la CLI di Codex supporta l'accesso con ChatGPT o chiave API.
|
||||
|
||||
Riepilogo del routing:
|
||||
Riepilogo dei percorsi:
|
||||
|
||||
- `openai-codex/gpt-5.4` = route OAuth ChatGPT/Codex
|
||||
- `openai-codex/gpt-5.4` = percorso OAuth ChatGPT/Codex
|
||||
- Usa l'accesso ChatGPT/Codex, non una chiave API diretta di OpenAI Platform
|
||||
- I limiti lato provider per `openai-codex/*` possono differire dall'esperienza web/app di ChatGPT
|
||||
|
||||
### Configurazione CLI (Codex OAuth)
|
||||
### Configurazione CLI (OAuth Codex)
|
||||
|
||||
```bash
|
||||
# Esegui Codex OAuth nella procedura guidata
|
||||
# Esegui l'OAuth Codex nella procedura guidata
|
||||
openclaw onboard --auth-choice openai-codex
|
||||
|
||||
# Oppure esegui OAuth direttamente
|
||||
# Oppure esegui direttamente l'OAuth
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
### Esempio di configurazione (abbonamento Codex)
|
||||
### Frammento di configurazione (abbonamento Codex)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -213,17 +214,17 @@ openclaw models auth login --provider openai-codex
|
||||
}
|
||||
```
|
||||
|
||||
La documentazione attuale di Codex di OpenAI elenca `gpt-5.4` come attuale modello Codex. OpenClaw
|
||||
La documentazione attuale di OpenAI per Codex elenca `gpt-5.4` come modello Codex corrente. OpenClaw
|
||||
lo mappa a `openai-codex/gpt-5.4` per l'uso con OAuth ChatGPT/Codex.
|
||||
|
||||
Questa route è intenzionalmente separata da `openai/gpt-5.4`. Se vuoi il
|
||||
Questo percorso è intenzionalmente separato da `openai/gpt-5.4`. Se vuoi il
|
||||
percorso API diretto di OpenAI Platform, usa `openai/*` con una chiave API. Se vuoi
|
||||
l'accesso ChatGPT/Codex, usa `openai-codex/*`.
|
||||
l'accesso con ChatGPT/Codex, usa `openai-codex/*`.
|
||||
|
||||
Se l'onboarding riutilizza un accesso CLI Codex esistente, quelle credenziali restano
|
||||
gestite dalla CLI Codex. Alla scadenza, OpenClaw rilegge prima l'origine Codex esterna
|
||||
Se l'onboarding riutilizza un accesso esistente della CLI di Codex, tali credenziali restano
|
||||
gestite dalla CLI di Codex. Alla scadenza, OpenClaw rilegge prima la fonte Codex esterna
|
||||
e, quando il provider può aggiornarla, riscrive la credenziale aggiornata
|
||||
nell'archiviazione Codex invece di assumerne il controllo in una copia separata solo OpenClaw.
|
||||
nell'archiviazione di Codex invece di assumerne la gestione in una copia separata solo OpenClaw.
|
||||
|
||||
Se il tuo account Codex ha diritto a Codex Spark, OpenClaw supporta anche:
|
||||
|
||||
@ -232,23 +233,23 @@ Se il tuo account Codex ha diritto a Codex Spark, OpenClaw supporta anche:
|
||||
OpenClaw tratta Codex Spark come solo Codex. Non espone un percorso diretto
|
||||
`openai/gpt-5.3-codex-spark` con chiave API.
|
||||
|
||||
OpenClaw preserva anche `openai-codex/gpt-5.3-codex-spark` quando `pi-ai`
|
||||
OpenClaw conserva anche `openai-codex/gpt-5.3-codex-spark` quando `pi-ai`
|
||||
lo rileva. Trattalo come dipendente dai diritti e sperimentale: Codex Spark è
|
||||
separato da GPT-5.4 `/fast`, e la disponibilità dipende dall'account Codex /
|
||||
ChatGPT connesso.
|
||||
|
||||
### Limite della finestra di contesto di Codex
|
||||
|
||||
OpenClaw tratta i metadati del modello Codex e il limite del contesto runtime come
|
||||
OpenClaw tratta i metadati del modello Codex e il limite di contesto a runtime come
|
||||
valori separati.
|
||||
|
||||
Per `openai-codex/gpt-5.4`:
|
||||
|
||||
- `contextWindow` nativo: `1050000`
|
||||
- limite predefinito runtime `contextTokens`: `272000`
|
||||
- limite `contextTokens` predefinito a runtime: `272000`
|
||||
|
||||
Questo mantiene veritieri i metadati del modello, preservando allo stesso tempo la finestra runtime
|
||||
predefinita più piccola che in pratica ha caratteristiche migliori di latenza e qualità.
|
||||
Questo mantiene fedeli i metadati del modello preservando al tempo stesso la finestra
|
||||
predefinita più piccola a runtime, che in pratica ha caratteristiche migliori di latenza e qualità.
|
||||
|
||||
Se vuoi un limite effettivo diverso, imposta `models.providers.<provider>.models[].contextTokens`:
|
||||
|
||||
@ -269,37 +270,37 @@ Se vuoi un limite effettivo diverso, imposta `models.providers.<provider>.models
|
||||
}
|
||||
```
|
||||
|
||||
Usa `contextWindow` solo quando dichiari o sovrascrivi metadati nativi del modello.
|
||||
Usa `contextTokens` quando vuoi limitare il budget del contesto runtime.
|
||||
Usa `contextWindow` solo quando stai dichiarando o sovrascrivendo i metadati nativi
|
||||
del modello. Usa `contextTokens` quando vuoi limitare il budget di contesto a runtime.
|
||||
|
||||
### Trasporto predefinito
|
||||
|
||||
OpenClaw usa `pi-ai` per lo streaming dei modelli. Sia per `openai/*` sia per
|
||||
OpenClaw usa `pi-ai` per lo streaming del modello. Per `openai/*` e
|
||||
`openai-codex/*`, il trasporto predefinito è `"auto"` (prima WebSocket, poi fallback
|
||||
SSE).
|
||||
|
||||
In modalità `"auto"`, OpenClaw riprova anche un errore WebSocket iniziale e riprovabile
|
||||
prima di passare a SSE. La modalità `"websocket"` forzata espone comunque gli errori di trasporto
|
||||
direttamente invece di nasconderli dietro al fallback.
|
||||
In modalità `"auto"`, OpenClaw ritenta anche un errore WebSocket iniziale e ripetibile
|
||||
prima di passare a SSE. La modalità `"websocket"` forzata continua invece a mostrare
|
||||
direttamente gli errori di trasporto invece di nasconderli dietro il fallback.
|
||||
|
||||
Dopo un errore WebSocket di connessione o nelle prime fasi del turno in modalità `"auto"`, OpenClaw contrassegna
|
||||
il percorso WebSocket di quella sessione come degradato per circa 60 secondi e invia
|
||||
i turni successivi tramite SSE durante il cooldown invece di oscillare continuamente tra
|
||||
i trasporti.
|
||||
i turni successivi tramite SSE durante il periodo di raffreddamento invece di oscillare
|
||||
continuamente tra i trasporti.
|
||||
|
||||
Per gli endpoint nativi della famiglia OpenAI (`openai/*`, `openai-codex/*` e Azure
|
||||
OpenAI Responses), OpenClaw allega anche uno stato stabile di identità di sessione e turno
|
||||
alle richieste, così retry, riconnessioni e fallback SSE restano allineati alla stessa
|
||||
identità di conversazione. Sulle route native della famiglia OpenAI questo include header stabili di identità
|
||||
di richiesta di sessione/turno più metadati di trasporto corrispondenti.
|
||||
alle richieste in modo che retry, riconnessioni e fallback SSE restino allineati alla stessa
|
||||
identità di conversazione. Nei percorsi nativi della famiglia OpenAI questo include intestazioni di identità
|
||||
stabili di richiesta di sessione/turno insieme a metadati di trasporto corrispondenti.
|
||||
|
||||
OpenClaw normalizza anche i contatori di utilizzo OpenAI tra le varianti di trasporto prima
|
||||
che raggiungano le superfici session/status. Il traffico nativo OpenAI/Codex Responses può
|
||||
OpenClaw normalizza anche i contatori di utilizzo di OpenAI tra le varianti di trasporto prima
|
||||
che raggiungano le superfici di sessione/stato. Il traffico nativo OpenAI/Codex Responses può
|
||||
riportare l'utilizzo come `input_tokens` / `output_tokens` oppure
|
||||
`prompt_tokens` / `completion_tokens`; OpenClaw li tratta come gli stessi contatori di input
|
||||
e output per `/status`, `/usage` e i log di sessione. Quando il traffico nativo
|
||||
WebSocket omette `total_tokens` (o riporta `0`), OpenClaw ripiega sul totale normalizzato input + output
|
||||
così le viste session/status restano popolate.
|
||||
WebSocket omette `total_tokens` (o riporta `0`), OpenClaw usa come fallback
|
||||
il totale normalizzato input + output così che le visualizzazioni di sessione/stato restino popolate.
|
||||
|
||||
Puoi impostare `agents.defaults.models.<provider/model>.params.transport`:
|
||||
|
||||
@ -307,13 +308,13 @@ Puoi impostare `agents.defaults.models.<provider/model>.params.transport`:
|
||||
- `"websocket"`: forza WebSocket
|
||||
- `"auto"`: prova WebSocket, poi passa a SSE
|
||||
|
||||
Per `openai/*` (Responses API), OpenClaw abilita anche per impostazione predefinita il warm-up WebSocket
|
||||
Per `openai/*` (API Responses), OpenClaw abilita anche per impostazione predefinita il warm-up WebSocket
|
||||
(`openaiWsWarmup: true`) quando viene usato il trasporto WebSocket.
|
||||
|
||||
Documentazione OpenAI correlata:
|
||||
|
||||
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
- [API Realtime con WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming delle risposte API (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -334,7 +335,7 @@ Documentazione OpenAI correlata:
|
||||
|
||||
### Warm-up WebSocket OpenAI
|
||||
|
||||
La documentazione OpenAI descrive il warm-up come facoltativo. OpenClaw lo abilita per impostazione predefinita per
|
||||
La documentazione di OpenAI descrive il warm-up come facoltativo. OpenClaw lo abilita per impostazione predefinita per
|
||||
`openai/*` per ridurre la latenza del primo turno quando si usa il trasporto WebSocket.
|
||||
|
||||
### Disabilitare il warm-up
|
||||
@ -402,28 +403,28 @@ per inoltrare quel campo sugli endpoint nativi OpenAI/Codex Responses.
|
||||
|
||||
I valori supportati sono `auto`, `default`, `flex` e `priority`.
|
||||
|
||||
OpenClaw inoltra `params.serviceTier` sia alle richieste Responses dirette `openai/*`
|
||||
sia alle richieste Codex Responses `openai-codex/*` quando quei modelli puntano
|
||||
OpenClaw inoltra `params.serviceTier` sia alle richieste dirette `openai/*` Responses
|
||||
sia alle richieste `openai-codex/*` Codex Responses quando tali modelli puntano
|
||||
agli endpoint nativi OpenAI/Codex.
|
||||
|
||||
Comportamento importante:
|
||||
|
||||
- `openai/*` diretto deve puntare a `api.openai.com`
|
||||
- `openai-codex/*` deve puntare a `chatgpt.com/backend-api`
|
||||
- se instradi uno dei due provider tramite un'altra base URL o proxy, OpenClaw lascia `service_tier` invariato
|
||||
- se instradi uno dei due provider tramite un altro URL di base o proxy, OpenClaw lascia `service_tier` invariato
|
||||
|
||||
### Modalità veloce OpenAI
|
||||
|
||||
OpenClaw espone un interruttore condiviso di modalità veloce sia per le sessioni `openai/*` sia per quelle
|
||||
`openai-codex/*`:
|
||||
OpenClaw espone un interruttore condiviso della modalità veloce sia per le sessioni `openai/*` sia per
|
||||
quelle `openai-codex/*`:
|
||||
|
||||
- Chat/UI: `/fast status|on|off`
|
||||
- Config: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Quando la modalità veloce è abilitata, OpenClaw la mappa all'elaborazione prioritaria OpenAI:
|
||||
Quando la modalità veloce è abilitata, OpenClaw la mappa all'elaborazione prioritaria di OpenAI:
|
||||
|
||||
- le chiamate Responses dirette `openai/*` a `api.openai.com` inviano `service_tier = "priority"`
|
||||
- anche le chiamate Responses `openai-codex/*` a `chatgpt.com/backend-api` inviano `service_tier = "priority"`
|
||||
- le chiamate dirette `openai/*` Responses a `api.openai.com` inviano `service_tier = "priority"`
|
||||
- anche le chiamate `openai-codex/*` Responses a `chatgpt.com/backend-api` inviano `service_tier = "priority"`
|
||||
- i valori `service_tier` già presenti nel payload vengono preservati
|
||||
- la modalità veloce non riscrive `reasoning` o `text.verbosity`
|
||||
|
||||
@ -431,7 +432,7 @@ Per GPT 5.4 in particolare, la configurazione più comune è:
|
||||
|
||||
- inviare `/fast on` in una sessione che usa `openai/gpt-5.4` o `openai-codex/gpt-5.4`
|
||||
- oppure impostare `agents.defaults.models["openai/gpt-5.4"].params.fastMode = true`
|
||||
- se usi anche Codex OAuth, imposta anche `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true`
|
||||
- se usi anche l'OAuth Codex, imposta anche `agents.defaults.models["openai-codex/gpt-5.4"].params.fastMode = true`
|
||||
|
||||
Esempio:
|
||||
|
||||
@ -456,48 +457,74 @@ Esempio:
|
||||
}
|
||||
```
|
||||
|
||||
Le sostituzioni di sessione hanno la precedenza sulla configurazione. La cancellazione della sostituzione di sessione nell'interfaccia Sessions UI
|
||||
Le sostituzioni a livello di sessione hanno la precedenza sulla configurazione. La rimozione della sostituzione della sessione nell'interfaccia Sessions UI
|
||||
riporta la sessione al valore predefinito configurato.
|
||||
|
||||
### Route OpenAI native rispetto a route compatibili con OpenAI
|
||||
### Percorsi OpenAI nativi rispetto ai percorsi compatibili con OpenAI
|
||||
|
||||
OpenClaw tratta gli endpoint diretti OpenAI, Codex e Azure OpenAI in modo diverso
|
||||
dai proxy generici compatibili con OpenAI `/v1`:
|
||||
|
||||
- le route native `openai/*`, `openai-codex/*` e Azure OpenAI mantengono
|
||||
intatto `reasoning: { effort: "none" }` quando disabiliti esplicitamente il reasoning
|
||||
- le route native della famiglia OpenAI usano per impostazione predefinita schemi degli strumenti in modalità strict
|
||||
- gli header nascosti di attribuzione OpenClaw (`originator`, `version` e
|
||||
`User-Agent`) vengono allegati solo sugli host nativi OpenAI verificati
|
||||
(`api.openai.com`) e sugli host Codex nativi (`chatgpt.com/backend-api`)
|
||||
- le route native OpenAI/Codex mantengono il request shaping specifico di OpenAI come
|
||||
`service_tier`, `store` di Responses, payload di compatibilità del reasoning OpenAI e
|
||||
suggerimenti per la prompt cache
|
||||
- le route in stile proxy compatibili con OpenAI mantengono il comportamento compatibile più permissivo e non
|
||||
forzano schemi degli strumenti strict, request shaping solo nativo o header nascosti
|
||||
di attribuzione OpenAI/Codex
|
||||
- i percorsi nativi `openai/*`, `openai-codex/*` e Azure OpenAI mantengono
|
||||
`reasoning: { effort: "none" }` intatto quando disabiliti esplicitamente il ragionamento
|
||||
- i percorsi nativi della famiglia OpenAI impostano per default gli schemi degli strumenti in modalità rigorosa
|
||||
- le intestazioni nascoste di attribuzione di OpenClaw (`originator`, `version` e
|
||||
`User-Agent`) vengono allegate solo agli host OpenAI nativi verificati
|
||||
(`api.openai.com`) e agli host Codex nativi (`chatgpt.com/backend-api`)
|
||||
- i percorsi nativi OpenAI/Codex mantengono la formattazione delle richieste specifica di OpenAI, come
|
||||
`service_tier`, `store` di Responses, payload di compatibilità del ragionamento OpenAI e
|
||||
suggerimenti per la cache del prompt
|
||||
- i percorsi compatibili con OpenAI in stile proxy mantengono il comportamento di compatibilità più permissivo e non
|
||||
forzano schemi degli strumenti rigorosi, formattazione delle richieste solo nativa o intestazioni nascoste di attribuzione
|
||||
OpenAI/Codex
|
||||
|
||||
Azure OpenAI resta nel gruppo di routing nativo per il comportamento di trasporto e compatibilità, ma non riceve gli header nascosti di attribuzione OpenAI/Codex.
|
||||
Azure OpenAI resta nel gruppo dei percorsi nativi per il comportamento di trasporto e compatibilità,
|
||||
ma non riceve le intestazioni nascoste di attribuzione OpenAI/Codex.
|
||||
|
||||
Questo preserva l'attuale comportamento nativo di OpenAI Responses senza imporre
|
||||
vecchi shim compatibili con OpenAI ai backend `/v1` di terze parti.
|
||||
Questo preserva l'attuale comportamento nativo di OpenAI Responses senza imporre shim
|
||||
compatibili con OpenAI più vecchi ai backend `/v1` di terze parti.
|
||||
|
||||
### Modalità GPT agentica rigorosa
|
||||
|
||||
Per le esecuzioni GPT-5-family `openai/*` e `openai-codex/*`, OpenClaw può usare un
|
||||
contratto di esecuzione Pi incorporato più rigoroso:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
embeddedPi: {
|
||||
executionContract: "strict-agentic",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Con `strict-agentic`, OpenClaw non tratta più un turno dell'assistente che contiene solo un piano come
|
||||
un progresso riuscito quando è disponibile un'azione concreta tramite strumento. Ritenta il
|
||||
turno con un orientamento ad agire subito, abilita automaticamente lo strumento strutturato `update_plan` per
|
||||
lavori sostanziali e mostra uno stato di blocco esplicito se il modello continua
|
||||
a pianificare senza agire.
|
||||
|
||||
La modalità è limitata alle esecuzioni GPT-5-family di OpenAI e OpenAI Codex. Gli altri provider
|
||||
e le famiglie di modelli meno recenti mantengono il comportamento Pi incorporato predefinito, a meno che tu non li abiliti
|
||||
esplicitamente con altre impostazioni di runtime.
|
||||
|
||||
### Compattazione lato server di OpenAI Responses
|
||||
|
||||
Per i modelli diretti OpenAI Responses (`openai/*` che usano `api: "openai-responses"` con
|
||||
`baseUrl` su `api.openai.com`), OpenClaw ora abilita automaticamente i suggerimenti di payload
|
||||
per la compattazione lato server di OpenAI:
|
||||
Per i modelli OpenAI Responses diretti (`openai/*` che usano `api: "openai-responses"` con
|
||||
`baseUrl` su `api.openai.com`), OpenClaw ora abilita automaticamente i suggerimenti di payload per la compattazione lato server di OpenAI:
|
||||
|
||||
- Forza `store: true` (a meno che la compatibilità del modello imposti `supportsStore: false`)
|
||||
- Inietta `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Inserisce `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
|
||||
Per impostazione predefinita, `compact_threshold` è `70%` di `contextWindow` del modello (oppure `80000`
|
||||
quando non disponibile).
|
||||
Per impostazione predefinita, `compact_threshold` è il `70%` di `contextWindow` del modello (oppure `80000`
|
||||
se non disponibile).
|
||||
|
||||
### Abilitare esplicitamente la compattazione lato server
|
||||
|
||||
Usa questa opzione quando vuoi forzare l'iniezione di `context_management` su modelli
|
||||
Responses compatibili (ad esempio Azure OpenAI Responses):
|
||||
Usalo quando vuoi forzare l'inserimento di `context_management` su modelli Responses compatibili (ad esempio Azure OpenAI Responses):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -552,11 +579,11 @@ Responses compatibili (ad esempio Azure OpenAI Responses):
|
||||
}
|
||||
```
|
||||
|
||||
`responsesServerCompaction` controlla solo l'iniezione di `context_management`.
|
||||
I modelli diretti OpenAI Responses continuano a forzare `store: true` a meno che la compatibilità non imposti
|
||||
`responsesServerCompaction` controlla solo l'inserimento di `context_management`.
|
||||
I modelli OpenAI Responses diretti continuano comunque a forzare `store: true` a meno che la compatibilità non imposti
|
||||
`supportsStore: false`.
|
||||
|
||||
## Note
|
||||
|
||||
- I riferimenti ai modelli usano sempre `provider/model` (vedi [/concepts/models](/it/concepts/models)).
|
||||
- I dettagli di autenticazione + le regole di riutilizzo si trovano in [/concepts/oauth](/it/concepts/oauth).
|
||||
- I dettagli di autenticazione e le regole di riutilizzo sono in [/concepts/oauth](/it/concepts/oauth).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user