From da963bfe1e2ad99a56dbf1ebadf92eac1fe15bb3 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 12 Apr 2026 00:21:10 +0000 Subject: [PATCH] chore(i18n): refresh it translations --- docs/it/channels/msteams.md | 517 +++++++++++++++++---------- docs/it/plugins/sdk-agent-harness.md | 157 +++----- docs/it/providers/openai.md | 267 +++++++------- 3 files changed, 541 insertions(+), 400 deletions(-) diff --git a/docs/it/channels/msteams.md b/docs/it/channels/msteams.md index cd63e0ec8..74b16fc60 100644 --- a/docs/it/channels/msteams.md +++ b/docs/it/channels/msteams.md @@ -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: "", + tenantId: "", + 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: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Config (managed identity assegnata dall'utente):** + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + tenantId: "", + authType: "federated", + useManagedIdentity: true, + managedIdentityClientId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +**Variabili d'ambiente:** + +- `MSTEAMS_AUTH_TYPE=federated` +- `MSTEAMS_USE_MANAGED_IDENTITY=true` +- `MSTEAMS_MANAGED_IDENTITY_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 --parameters '{ + "name": "my-bot-workload-identity", + "issuer": "", + "subject": "system:serviceaccount::", + "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: "" + ``` + +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 = `. @@ -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://:3978/api/messages` (o il tuo percorso/porta scelti). + - Imposta il Messaging Endpoint di Azure Bot su: + - `https://: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[""].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..replyStyle`: override per team. - `channels.msteams.teams..requireMention`: override per team. -- `channels.msteams.teams..tools`: override predefiniti dei criteri strumenti per team (`allow`/`deny`/`alsoAllow`) usati quando manca un override di canale. -- `channels.msteams.teams..toolsBySender`: override predefiniti dei criteri strumenti per team per mittente (`"*"` wildcard supportato). +- `channels.msteams.teams..tools`: override predefiniti per team delle policy degli strumenti (`allow`/`deny`/`alsoAllow`) usati quando manca un override di canale. +- `channels.msteams.teams..toolsBySender`: override predefiniti per team delle policy degli strumenti per mittente (supportato il wildcard `"*"`). - `channels.msteams.teams..channels..replyStyle`: override per canale. - `channels.msteams.teams..channels..requireMention`: override per canale. -- `channels.msteams.teams..channels..tools`: override dei criteri strumenti per canale (`allow`/`deny`/`alsoAllow`). -- `channels.msteams.teams..channels..toolsBySender`: override dei criteri strumenti per canale per mittente (`"*"` wildcard supportato). +- `channels.msteams.teams..channels..tools`: override delle policy degli strumenti per canale (`allow`/`deny`/`alsoAllow`). +- `channels.msteams.teams..channels..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::`). - - I messaggi di canale/gruppo usano l'id conversazione: + - I messaggi di canale/gruppo usano l'ID conversazione: - `agent::msteams:channel:` - `agent::msteams:group:` ## 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: ...` - 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:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | -| Utente (per nome) | `user:` | `user:John Smith` (richiede API Graph) | -| Gruppo/canale | `conversation:` | `conversation:19:abc123...@thread.tacv2` | -| Gruppo/canale (raw) | `` | `19:abc123...@thread.tacv2` (se contiene `@thread`) | +| Tipo di target | Formato | Esempio | +| ---------------------- | ------------------------------- | --------------------------------------------------- | +| Utente (per ID) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | +| Utente (per nome) | `user:` | `user:John Smith` (richiede API Graph) | +| Gruppo/canale | `conversation:` | `conversation:19:abc123...@thread.tacv2` | +| Gruppo/canale (raw) | `` | `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 diff --git a/docs/it/plugins/sdk-agent-harness.md b/docs/it/plugins/sdk-agent-harness.md index f1976e511..bb771ad6a 100644 --- a/docs/it/plugins/sdk-agent-harness.md +++ b/docs/it/plugins/sdk-agent-harness.md @@ -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=` 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 diff --git a/docs/it/providers/openai.md b/docs/it/providers/openai.md index aa2dee146..357a1dfe8 100644 --- a/docs/it/providers/openai.md +++ b/docs/it/providers/openai.md @@ -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..models[].contextTokens`: @@ -269,37 +270,37 @@ Se vuoi un limite effettivo diverso, imposta `models.providers..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..params.transport`: @@ -307,13 +308,13 @@ Puoi impostare `agents.defaults.models..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["/"].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).